@nanobpm/nano-workforce 0.208.3 → 0.208.5

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.5](https://github.com/nanobpm/nano-workforce/compare/v0.208.4...v0.208.5) (2026-11-11)
+
+### Bug Fixes
+
+* **status:** serve the /status merge policy from a durable pull_requests projection ([#950](https://github.com/nanobpm/nano-workforce/issues/950)) ([c3f19d5](https://github.com/nanobpm/nano-workforce/commit/c3f19d50ef6cf4f731f50ab778b5cd7ebdb3454e)), closes [#937](https://github.com/nanobpm/nano-workforce/issues/937) [#937](https://github.com/nanobpm/nano-workforce/issues/937) [#947](https://github.com/nanobpm/nano-workforce/issues/947)
+
+## [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/agentCompletion.test.ts

@@ -85,6 +85,21 @@ function memData(
       }
       return { changed: 0 };
     }
+    // The guarded merge-approval projection stamp (issue #947, PR #950 review): ownership is checked
+    // IN the UPDATE predicate, so only a row still owned by the approving instance is stamped.
+    const mp = /^UPDATE "pull_requests" SET "merge_human_approval" = 0 WHERE "process_key" = \?$/.exec(sql);
+    if (mp) {
+      const store = stores.pull_requests;
+      if (!store) throw new Error("no such table: pull_requests");
+      let changed = 0;
+      for (const r of store.rows) {
+        if (r.process_key === params[0]) {
+          r.merge_human_approval = 0;
+          changed++;
+        }
+      }
+      return { changed };
+    }
     // The FIRST-HAND agent-revert tombstone keyed on `source_completion_id` (Copilot review of #806) —
     // `invalidateAdjudicationByCompletion`. Tombstones EVERY live row this completion produced (a
     // completion settles one question, so at most one) so reverting a first-hand agent answer (which has
@@ -991,3 +1006,143 @@ test("snapshotUserTaskFormOptions: an unresolvable form_key never throws (safe r
     "an unresolvable form_key falls back to the element's static form",
   );
 });
+
+// ── Issue #947: a merge-approval APPROVE mirrors onto the durable /status merge-policy projection ──
+// `submitPr` stamps `merge_human_approval = 1` when it gates a loop; the human's approve at the
+// `merge-approval` task clears the loop's `humanApproval` variable via the task's output mapping.
+// The canonical completer must stamp the SAME decision onto the row column `/status` reads, or the
+// projection reports `blockedBy: "human-approval"` long after approval landed.
+
+test("a merge-approval APPROVE stamps merge_human_approval=0 on the owning PR row (issue #947)", async () => {
+  const stores = {
+    task_completions: { rows: [] as any[], key: "id" },
+    pull_requests: {
+      rows: [
+        { pr_key: "owner/repo#7", process_key: "PI-7", merge_requested: 1, merge_human_approval: 1 },
+      ],
+      key: "pr_key",
+    },
+  };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-ma", elementId: "merge-approval", processInstanceKey: "PI-7" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-ma",
+    operatorId: "alice",
+    variables: { mergeDecision: "approve" },
+  });
+
+  assertEquals(r.ok, true);
+  const row = stores.pull_requests.rows[0];
+  assertEquals(row.merge_human_approval, 0, "the approval is mirrored onto the /status projection");
+  assertEquals(row.merge_requested, 1, "the merge intent is untouched");
+});
+
+test("a merge-approval REVISE leaves the projection gated (issue #947)", async () => {
+  const stores = {
+    task_completions: { rows: [] as any[], key: "id" },
+    pull_requests: {
+      rows: [{ pr_key: "owner/repo#8", process_key: "PI-8", merge_requested: 1, merge_human_approval: 1 }],
+      key: "pr_key",
+    },
+  };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-mr", elementId: "merge-approval", processInstanceKey: "PI-8" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-mr",
+    operatorId: "alice",
+    variables: { mergeDecision: "revise", answer: "split the migration" },
+  });
+
+  assertEquals(r.ok, true);
+  assertEquals(stores.pull_requests.rows[0].merge_human_approval, 1, "a revise keeps the gate outstanding");
+});
+
+test("a merge-approval approve against a SUPERSEDED instance never clears the fresh run's gate (issue #947)", async () => {
+  // The stamp is ownership-guarded on the instance the task parked on: after a reopen re-pointed
+  // `process_key` at the fresh run, a straggler completion resolved against the OLD instance must
+  // not clear the new run's projection.
+  const stores = {
+    task_completions: { rows: [] as any[], key: "id" },
+    pull_requests: {
+      rows: [{ pr_key: "owner/repo#9", process_key: "PI-NEW", merge_requested: 1, merge_human_approval: 1 }],
+      key: "pr_key",
+    },
+  };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-stale", elementId: "merge-approval", processInstanceKey: "PI-OLD" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-stale",
+    operatorId: "alice",
+    variables: { mergeDecision: "approve" },
+  });
+
+  assertEquals(r.ok, true, "the engine completion itself still lands");
+  assertEquals(stores.pull_requests.rows[0].merge_human_approval, 1, "the fresh run's gate is not cleared by a stale instance");
+});
+
+test("a reopen racing the approval stamp can never let the PREVIOUS run clear the successor's gate (PR #950 review)", async () => {
+  // A reopen re-points `process_key` the moment the stamp looks the row up (simulated in the
+  // table's `findOne`). A read-then-write stamp would then clear the FRESH run's gate; the guarded
+  // single-statement UPDATE checks ownership atomically, so the successor's gate survives.
+  const stores = {
+    task_completions: { rows: [] as any[], key: "id" },
+    pull_requests: {
+      rows: [{ pr_key: "owner/repo#10", process_key: "PI-OLD", merge_requested: 1, merge_human_approval: 1 }],
+      key: "pr_key",
+    },
+  };
+  const base = memData(stores);
+  const reopen = () => {
+    const live = stores.pull_requests.rows[0];
+    live.process_key = "PI-NEW";
+    live.merge_human_approval = 1; // the fresh gated run restarts outstanding
+  };
+  const data: any = Object.create(base);
+  data.table = (name: string, key: string) => {
+    const t: any = base.table(name, key);
+    if (name !== "pull_requests") return t;
+    return {
+      ...t,
+      findOne: async (q: any) => {
+        const row = await t.findOne(q);
+        reopen(); // the reopen lands between a lookup and its write
+        return row;
+      },
+    };
+  };
+  // An atomic statement leaves no window: the reopen can only land after it (and resets the gate).
+  data.open = () => {
+    const db: any = base.open();
+    return { ...db, exec: async (sql: string, params?: unknown[]) => {
+      const res = await db.exec(sql, params);
+      reopen();
+      return res;
+    } };
+  };
+  const { engine } = fakeEngine([{ userTaskKey: "ut-race", elementId: "merge-approval", processInstanceKey: "PI-OLD" }]);
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-race",
+    operatorId: "alice",
+    variables: { mergeDecision: "approve" },
+  });
+  assertEquals(r.ok, true);
+  assertEquals(stores.pull_requests.rows[0].merge_human_approval, 1, "the successor's gate stays outstanding");
+});
+
+test("a merge-approval projection-stamp failure never masks the engine completion (issue #947)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores); // no pull_requests store — the stamp's table read throws
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-mx", elementId: "merge-approval", processInstanceKey: "PI-X" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-mx",
+    operatorId: "alice",
+    variables: { mergeDecision: "approve" },
+  });
+
+  assertEquals(r.ok, true, "best-effort: the projection miss is swallowed");
+  assertEquals(completed.length, 1, "the engine resume already happened");
+});

package/app/agentCompletion.ts

@@ -25,6 +25,7 @@ import type { DataLayer, EngineClient, GatewayDataSource } from "@nanobpm/urban"
 import { invalidateAdjudication, invalidateAdjudicationByCompletion } from "./adjudications.ts";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, ESCALATION_FORM, GENERIC_HUMAN_FORM, isDeliveryEscalationTwin, isDeliveryHumanElement, isDeliveryWaitEscalationTwin } from "./deliveryHuman.ts";
+import { withMergePolicyLock } from "./mergePolicyLock.ts";
 import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, PR_MERGE_APPROVAL_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
@@ -432,6 +433,11 @@ export async function completeUserTaskAttributed(
     created_at: now(),
   });
   const completionId = Number(id);
+  // Merge-approval approve: serialize the engine completion + projection stamp against gated adoption
+  // on the same loop (PR #950 review) so a concurrent adopter's stale `1` can never land after our `0`.
+  const approvingMerge = target.elementId === PR_MERGE_APPROVAL_ELEMENT && target.variables.mergeDecision === "approve";
+  const lockKey = approvingMerge ? target.processInstanceKey?.trim() : undefined;
+  const resume = async (): Promise<void> => {
   try {
     // Carry the completed user-task's identity forward on the resumed token (Copilot review of #806).
     // `pr.answer-escalation` (record-answer) reconciles the durable adjudication AFTER this completion
@@ -461,9 +467,42 @@ export async function completeUserTaskAttributed(
     }
     throw err;
   }
+  // Merge-policy projection (issue #947): a human APPROVE at the convergence loop's `merge-approval`
+  // task clears the loop's `humanApproval` variable via the task's output mapping — mirror that
+  // decision onto the durable row column `/status` reads, so the projection lifts the
+  // `human-approval` blocker the moment approval lands instead of reporting a stale block until
+  // `startMerge` re-stamps. Best-effort (the engine resume above already succeeded — a projection
+  // miss only leaves the row reading blocked until the merge hand-off, never blocks the merge) and
+  // ownership-guarded on the instance the task parked on, so a completion replayed against a stale
+  // instance can never clear a SUCCESSOR run's gate after a reopen re-pointed `process_key`.
+  if (approvingMerge) {
+    await stampMergeApprovalProjection(data, target.processInstanceKey);
+  }
+  };
+  if (lockKey) await withMergePolicyLock(lockKey, resume);
+  else await resume();
   return { completionId };
 }
 
+/** Mirror a `merge-approval` approve onto the durable `/status` merge-policy projection
+ *  (`merge_human_approval = 0` — decided-and-approved; 132_pull_requests_merge_policy.sql). The
+ *  stamp is keyed by the OWNING instance: the row is only updated while its `process_key` still
+ *  names the instance the completed task parked on, so a late/stray completion against an
+ *  already-replaced run is a no-op. Best-effort and never throws — the engine-side completion is
+ *  the authority; this column only feeds the read projection. */
+async function stampMergeApprovalProjection(data: DataLayer, processInstanceKey: string | null | undefined): Promise<void> {
+  const key = processInstanceKey?.trim();
+  if (!key) return;
+  try {
+    // ONE guarded UPDATE (PR #950 review): the ownership check and the stamp are a single atomic
+    // statement, so a reopen that re-points `process_key` between a lookup and a write can never let
+    // the PREVIOUS run's approval clear its successor's gate (no read-then-write window).
+    await data.open().exec(`UPDATE "pull_requests" SET "merge_human_approval" = 0 WHERE "process_key" = ?`, [key]);
+  } catch {
+    // swallow — a projection miss never masks a completion the engine has already resumed
+  }
+}
+
 /** The newest recorded completion for a user-task key, or undefined. */
 export async function latestCompletion(
   data: DataLayer,

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/mergePolicyLock.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { withMergePolicyLock } from "./mergePolicyLock.ts";
+
+// PR #950 review: gated adoption (engine humanApproval=true, stamp 1) and merge approval (engine
+// complete, stamp 0) must never interleave on one loop, or the projection ends at a stale 1.
+test("engine-write/projection-stamp pairs on the same loop never interleave", async () => {
+  const log: string[] = [];
+  let projection: number | null = null;
+  let releaseAdopt!: () => void;
+  const adoptEngineWritten = new Promise<void>((r) => {
+    releaseAdopt = r;
+  });
+  const adopt = withMergePolicyLock("loop-1", async () => {
+    log.push("adopt:engine");
+    await adoptEngineWritten; // the approval tries to run while adoption is mid-pair
+    projection = 1;
+    log.push("adopt:stamp");
+  });
+  const approve = withMergePolicyLock("loop-1", async () => {
+    log.push("approve:engine");
+    projection = 0;
+    log.push("approve:stamp");
+  });
+  await Promise.resolve();
+  releaseAdopt();
+  await Promise.all([adopt, approve]);
+  assert.deepEqual(log, ["adopt:engine", "adopt:stamp", "approve:engine", "approve:stamp"]);
+  assert.equal(projection, 0);
+});
+
+test("a failing holder releases the lock; other keys run independently", async () => {
+  await assert.rejects(
+    withMergePolicyLock("loop-2", async () => {
+      throw new Error("boom");
+    }),
+  );
+  assert.equal(await withMergePolicyLock("loop-2", async () => "next"), "next");
+  let release!: () => void;
+  const held = withMergePolicyLock("loop-3", () => new Promise<void>((r) => (release = r)));
+  assert.equal(await withMergePolicyLock("loop-4", async () => "free"), "free");
+  release();
+  await held;
+});

package/app/mergePolicyLock.ts

@@ -0,0 +1,25 @@
+/** In-process keyed serializer for the merge-policy projection (issue #947, PR #950 review).
+ *
+ *  Two writers touch one convergence loop's `humanApproval` policy as an engine-write +
+ *  projection-stamp PAIR: gated adoption (`submitPr`: `setVariables(humanApproval: true)` then stamp
+ *  `merge_human_approval = 1`) and a `merge-approval` approve (`completeUserTask` then stamp `0`).
+ *  Interleaved, the adopter's stale `1` can land after the approval's `0`, so `/status` reports a
+ *  phantom `human-approval` block. Every such pair runs under this lock keyed by the loop's process
+ *  instance key, so the pairs are applied in a single total order and the projection always matches
+ *  the last engine write. The app is a single node process, so an in-memory promise chain suffices. */
+const tails = new Map<string, Promise<unknown>>();
+
+export async function withMergePolicyLock<T>(processKey: string, fn: () => Promise<T>): Promise<T> {
+  const prev = tails.get(processKey) ?? Promise.resolve();
+  const run = prev.then(fn, fn);
+  const tail = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  tails.set(processKey, tail);
+  try {
+    return await run;
+  } finally {
+    if (tails.get(processKey) === tail) tails.delete(processKey);
+  }
+}