@nanobpm/nano-workforce 0.208.3 → 0.208.5

package/app/mergeStatus.test.ts

@@ -55,7 +55,9 @@ function memData(stores: Stores) {
 
 /** A fake engine whose `searchVariables` serves the given per-instance variables. A name-less,
  *  key-less query (`{}` — the batched /status read, issue #936) returns EVERY variable across all
- *  instances, each row carrying its owning `processInstanceKey`, exactly as the real engine does. */
+ *  instances, each row carrying its owning `processInstanceKey`, exactly as the real engine does.
+ *  These tests exercise the LEGACY fallback path (issue #947): the row carries no
+ *  `merge_requested` projection, so the policy is read back off the engine. */
 function fakeEngine(varsByInstance: Record<string, Record<string, unknown>>) {
   return {
     searchVariables: (q: { processInstanceKey?: string; scopeKey?: string; name?: string }) => {
@@ -112,20 +114,20 @@ async function mergeOfWith(
 
 test("merge policy: a loop seeded autoMerge=true reads requested+effective (the #916 phantom)", async () => {
   const merge = await mergeOf({ autoMerge: true, convergeOnly: false, humanApproval: false });
-  assertEquals(merge, { requested: true, enabled: true, effective: true, blockedBy: null });
+  assertEquals(merge, { requested: true, enabled: true, effective: true, blockedBy: null, stale: false });
 });
 
 test("merge policy: a legacy in-flight loop (convergeOnly only) derives requested from its inverse", async () => {
   // Seeded BEFORE `autoMerge` existed: only the legacy inverted variable is present.
   const review = await mergeOf({ convergeOnly: true });
-  assertEquals(review, { requested: false, enabled: true, effective: false, blockedBy: null });
+  assertEquals(review, { requested: false, enabled: true, effective: false, blockedBy: null, stale: false });
   const merging = await mergeOf({ convergeOnly: false });
-  assertEquals(merging, { requested: true, enabled: true, effective: true, blockedBy: null });
+  assertEquals(merging, { requested: true, enabled: true, effective: true, blockedBy: null, stale: false });
 });
 
 test("merge policy: humanApproval gates the effective merge and is named as the blocker", async () => {
   const merge = await mergeOf({ autoMerge: true, humanApproval: true });
-  assertEquals(merge, { requested: true, enabled: true, effective: false, blockedBy: "human-approval" });
+  assertEquals(merge, { requested: true, enabled: true, effective: false, blockedBy: "human-approval", stale: false });
 });
 
 test("merge policy: an approved PR with finalization still pending reports no blocker (PR #917 review)", async () => {
@@ -135,12 +137,12 @@ test("merge policy: an approved PR with finalization still pending reports no bl
   // an approval that is already complete. (`status` stays non-terminal: `converged_at` is only
   // stamped once `pr.finalize` actually runs.)
   const merge = await mergeOf({ autoMerge: true, humanApproval: false }, { status: "converging" });
-  assertEquals(merge, { requested: true, enabled: true, effective: true, blockedBy: null });
+  assertEquals(merge, { requested: true, enabled: true, effective: true, blockedBy: null, stale: false });
 });
 
 test("merge policy: a review-only request reads requested=false (distinct from env/human blocking)", async () => {
   const merge = await mergeOf({ autoMerge: false, convergeOnly: true });
-  assertEquals(merge, { requested: false, enabled: true, effective: false, blockedBy: null });
+  assertEquals(merge, { requested: false, enabled: true, effective: false, blockedBy: null, stale: false });
 });
 
 test("merge policy: no readable instance key (or neither variable) defaults to the historical merge default", async () => {
@@ -151,9 +153,9 @@ test("merge policy: no readable instance key (or neither variable) defaults to t
     user_tasks: { rows: [], key: "id" },
   };
   const [noKey] = await activePrs(memData(stores), fakeEngine({}));
-  assertEquals(noKey.merge, { requested: true, enabled: true, effective: true, blockedBy: null });
+  assertEquals(noKey.merge, { requested: true, enabled: true, effective: true, blockedBy: null, stale: true });
   const bare = await mergeOf({});
-  assertEquals(bare, { requested: true, enabled: true, effective: true, blockedBy: null });
+  assertEquals(bare, { requested: true, enabled: true, effective: true, blockedBy: null, stale: true });
 });
 
 test("merge policy: NANO_PR_AUTO_MERGE=0 blocks a requested merge as env, never a review-only one", async () => {
@@ -165,9 +167,9 @@ test("merge policy: NANO_PR_AUTO_MERGE=0 blocks a requested merge as env, never
   try {
     const mod: typeof import("./service.ts") = await import(`./service.ts?mergeStatusAutoMergeOff=${Date.now()}`);
     const requested = await mergeOfWith(mod, { autoMerge: true, humanApproval: true });
-    assertEquals(requested, { requested: true, enabled: false, effective: false, blockedBy: "env" });
+    assertEquals(requested, { requested: true, enabled: false, effective: false, blockedBy: "env", stale: false });
     const reviewOnly = await mergeOfWith(mod, { autoMerge: false });
-    assertEquals(reviewOnly, { requested: false, enabled: false, effective: false, blockedBy: null });
+    assertEquals(reviewOnly, { requested: false, enabled: false, effective: false, blockedBy: null, stale: false });
   } finally {
     if (prev === undefined) delete process.env["NANO_PR_AUTO_MERGE"];
     else process.env["NANO_PR_AUTO_MERGE"] = prev;
@@ -220,5 +222,5 @@ test("merge policy: a delayed successful probe cannot resurrect a policy after a
   } as any;
   const prs = await activePrs(memData(stores), engine);
   const pr = prs.find((p: { prKey?: string; pr_key?: string; number?: number }) => p.number === 1);
-  assertEquals(pr?.merge, { requested: true, enabled: true, effective: true, blockedBy: null }, "failed probe → default, not a half-read policy");
+  assertEquals(pr?.merge, { requested: true, enabled: true, effective: true, blockedBy: null, stale: true }, "failed probe → default, not a half-read policy");
 });

package/app/migration132.test.ts

@@ -0,0 +1,72 @@
+// Migration guard for 132_pull_requests_merge_policy.sql (issue #947): the durable merge-policy
+// projection `/status` serves. Applies the migration to a real in-memory SQLite DB over a
+// pre-existing `pull_requests` table and asserts the expand-and-contract contract:
+//   * both columns are added NULLABLE with no default — a pre-existing row reads
+//     `merge_requested IS NULL` (the legacy marker `activePrs` falls back to the #937 batched
+//     engine read for), never a fabricated 0/1;
+//   * the writers' stamped values round-trip (0/1 for `merge_requested`, NULL/0/1 for
+//     `merge_human_approval`).
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION_132 = fileURLToPath(
+  new URL("../db/migrations/132_pull_requests_merge_policy.sql", import.meta.url),
+);
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (
+       pr_key TEXT PRIMARY KEY,
+       repo TEXT NOT NULL,
+       number INTEGER NOT NULL,
+       status TEXT NOT NULL,
+       process_key TEXT
+     );
+     INSERT INTO pull_requests (pr_key, repo, number, status, process_key)
+       VALUES ('owner/repo#1', 'owner/repo', 1, 'converging', 'PI-1');`,
+  );
+  db.exec(readFileSync(MIGRATION_132, "utf8"));
+  return db;
+}
+
+test("migration 132 adds both merge-policy columns NULLABLE — a pre-existing row reads legacy (NULL)", () => {
+  const db = migratedDb();
+  // node:sqlite rows are null-prototype objects; spread to a plain object for the deep-equal.
+  const row = {
+    ...(db
+      .prepare(`SELECT merge_requested, merge_human_approval FROM pull_requests WHERE pr_key = 'owner/repo#1'`)
+      .get() as { merge_requested: number | null; merge_human_approval: number | null }),
+  };
+  assertEquals(
+    row,
+    { merge_requested: null, merge_human_approval: null },
+    "a row written before the projection existed must NOT be back-filled — NULL is the legacy marker the /status fallback keys on",
+  );
+});
+
+test("migration 132 columns round-trip the writers' stamped values", () => {
+  const db = migratedDb();
+  db.prepare(
+    `UPDATE pull_requests SET merge_requested = 1, merge_human_approval = 0 WHERE pr_key = 'owner/repo#1'`,
+  ).run();
+  const row = {
+    ...(db
+      .prepare(`SELECT merge_requested, merge_human_approval FROM pull_requests WHERE pr_key = 'owner/repo#1'`)
+      .get() as { merge_requested: number | null; merge_human_approval: number | null }),
+  };
+  assertEquals(row, { merge_requested: 1, merge_human_approval: 0 });
+  // A review-only run stamps 0; the approval gate stamps 1 while outstanding.
+  db.prepare(
+    `UPDATE pull_requests SET merge_requested = 0, merge_human_approval = 1 WHERE pr_key = 'owner/repo#1'`,
+  ).run();
+  const gated = {
+    ...(db
+      .prepare(`SELECT merge_requested, merge_human_approval FROM pull_requests WHERE pr_key = 'owner/repo#1'`)
+      .get() as { merge_requested: number | null; merge_human_approval: number | null }),
+  };
+  assertEquals(gated, { merge_requested: 0, merge_human_approval: 1 });
+});

package/app/pullRequestReadModel.test.ts

@@ -33,7 +33,7 @@ import {
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-const READ_MODEL_MIGRATION = "131_pull_requests_read_model_termination_reason.sql";
+const READ_MODEL_MIGRATION = "133_pull_requests_read_model_merge_policy.sql";
 
 // The real base `pull_requests` columns, in schema order — DERIVED from the migration chain (not a
 // hand-kept list that could silently omit one), used by both the drift guard and the e2e stand-in.

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

@@ -62,6 +62,16 @@ function memOpen(stores: Record<string, { rows: any[]; key: string }>, ops?: str
         }
         return { changed };
       }
+      if (/^UPDATE "pull_requests" SET "merge_human_approval" = 1 WHERE "pr_key" = \? AND "process_key" = \? AND "converged_at" IS NULL$/.test(sql)) {
+        let changed = 0;
+        for (const r of stores.pull_requests?.rows ?? []) {
+          if (r.pr_key === params[0] && r.process_key === params[1] && r.converged_at == null) {
+            r.merge_human_approval = 1;
+            changed++;
+          }
+        }
+        return { changed };
+      }
       throw new Error(`unexpected exec sql: ${sql}`);
     },
   };
@@ -1259,6 +1269,25 @@ function adoptLoop(status: string, loopState: string, convergedAt: string | null
   return { data, engine, narrowed };
 }
 
+test("a gated submitPr stamps an OUTSTANDING approval matching the engine seed (PR #950 review)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, vars } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 25, url: "https://github.com/owner/repo/pull/25", prKey: "owner/repo#25" },
+      [],
+      20,
+      false,
+      null,
+      true, // humanApproval
+    );
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.merge_human_approval, vars()?.humanApproval === true ? 1 : 0, "projection agrees with the engine seed");
+    assertEquals(pr.merge_human_approval, 1, "a gated run projects the outstanding gate");
+  });
+});
+
 test("a gated submitPr adopting a live loop narrows it to humanApproval (issue #826)", async () => {
   await withGithubOff(async () => {
     const pr = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
@@ -1464,6 +1493,140 @@ test("startMerge seeds the merge-policy triple so /status needs no per-instance
   });
 });
 
+// ── Issue #947: the durable merge-policy projection the writers stamp ────────────────────────────
+// `/status` serves the merge policy off the `pull_requests` row (zero engine reads) — these pin the
+// writer side of that contract: every path that KNOWS the policy must stamp it.
+
+test("submitPr stamps the merge-policy projection on the row (insert path)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores } = captureRoot();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 21,
+      url: "https://github.com/owner/repo/pull/21",
+      prKey: "owner/repo#21",
+    });
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.merge_requested, 1, "the default submit requests the merge");
+    assertEquals(pr.merge_human_approval, 0, "an ungated run mirrors the engine seed humanApproval:false (PR #950 review)");
+  });
+});
+
+test("submitPr stamps a review-only intent as merge_requested 0 (convergeOnly)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 22, url: "https://github.com/owner/repo/pull/22", prKey: "owner/repo#22" },
+      [],
+      20,
+      true, // convergeOnly
+    );
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.merge_requested, 0, "a review-only run projects requested=false with no engine read");
+    assertEquals(pr.merge_human_approval, 0, "no gate on a review-only run");
+  });
+});
+
+test("submitPr reopen restamps the projection to the FRESH run's intent (run-scoped reset)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores } = captureRoot();
+    (stores.pull_requests.rows as unknown[]).push({
+      pr_key: "owner/repo#23",
+      repo: "owner/repo",
+      number: 23,
+      url: "https://github.com/owner/repo/pull/23",
+      status: "converged", // terminal -> reopen path
+      current_round: 2,
+      process_key: "PI-OLD",
+      // The PRIOR run's projection: review-only, approval decided. A fresh default submit must
+      // overwrite both — a carried-over stamp would misreport the new run's policy.
+      merge_requested: 0,
+      merge_human_approval: 0,
+    });
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 23,
+      url: "https://github.com/owner/repo/pull/23",
+      prKey: "owner/repo#23",
+    });
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.merge_requested, 1, "the fresh run's intent wins");
+    assertEquals(pr.merge_human_approval, 0, "the approval state mirrors the fresh ungated seed");
+  });
+});
+
+test("a gated submitPr adopting a live loop stamps merge_human_approval on the row (issue #947)", async () => {
+  await withGithubOff(async () => {
+    const pr = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
+    const live = adoptLoop("converging", "ACTIVE");
+    await submitPr(live.data, live.engine, pr, [], 20, false, null, true);
+    const row = (await live.data.table("pull_requests", "pr_key").get(pr.prKey)) as {
+      merge_human_approval?: number | null;
+    } | null;
+    assertEquals(row?.merge_human_approval, 1, "the gate is mirrored onto the /status projection");
+
+    const ungated = adoptLoop("converging", "ACTIVE");
+    await submitPr(ungated.data, ungated.engine, pr);
+    const ungatedRow = (await ungated.data.table("pull_requests", "pr_key").get(pr.prKey)) as {
+      merge_human_approval?: number | null;
+    } | null;
+    assertEquals(ungatedRow?.merge_human_approval ?? null, null, "an ungated adopter leaves the projection undecided");
+  });
+});
+
+test("a gated adopter never gates a merge-loop or a row re-pointed mid-handoff (PR #950 review)", async () => {
+  await withGithubOff(async () => {
+    const pr = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
+    // Variant 1: the key already resolves to the merge-loop (startMerge re-pointed it, converged_at unset).
+    const merge = adoptLoop("converging", "ACTIVE");
+    merge.engine.searchProcessInstances = () =>
+      Promise.resolve([{ processInstanceKey: "PI-LOOP", state: "ACTIVE", processDefinitionId: "merge-loop" }]);
+    await submitPr(merge.data, merge.engine, pr, [], 20, false, null, true);
+    const mergeRow = (await merge.data.table("pull_requests", "pr_key").get(pr.prKey)) as any;
+    assertEquals(mergeRow?.merge_human_approval ?? null, null, "merge-loop policy untouched");
+    assertEquals(merge.narrowed.length, 0, "no humanApproval set on the merge-loop");
+    // Variant 2: the handoff re-points the row between the engine read and the stamp.
+    const race = adoptLoop("converging", "ACTIVE");
+    race.engine.setVariables = async () => {
+      const row = (await race.data.table("pull_requests", "pr_key").get(pr.prKey)) as any;
+      row.process_key = "PI-MERGE";
+      row.merge_human_approval = 0;
+    };
+    await submitPr(race.data, race.engine, pr, [], 20, false, null, true);
+    const raceRow = (await race.data.table("pull_requests", "pr_key").get(pr.prKey)) as any;
+    assertEquals(raceRow?.merge_human_approval, 0, "the handoff's merge-stage policy survives");
+  });
+});
+
+test("startMerge stamps the merge-stage policy on the row (issue #947)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores } = captureRoot();
+    (stores.pull_requests.rows as unknown[]).push({
+      pr_key: "owner/repo#24",
+      repo: "owner/repo",
+      number: 24,
+      url: "https://github.com/owner/repo/pull/24",
+      status: "converged",
+      current_round: 1,
+      process_key: "PI-CONV",
+      merge_requested: 1,
+      merge_human_approval: 1, // the convergence-stage gate — decided by the merge hand-off
+    });
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 24,
+      url: "https://github.com/owner/repo/pull/24",
+      prKey: "owner/repo#24",
+      round: 1,
+    });
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.merge_requested, 1, "a merge loop only starts for a requested merge");
+    assertEquals(pr.merge_human_approval, 0, "…and an approved one — the gate is behind it");
+  });
+});
+
 // The repository envelope drives the c8ctl harness's isolated workspace provisioning: it is
 // emitted under the reserved `io.nanobpm.agentTask` namespace with the PR head branch as the
 // checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness
@@ -2681,7 +2844,7 @@ test("submitPr handoffFrom: a failed reset restores the prior owner so the hand-
     const PR_KEY = "owner/repo#79";
     const stores: Record<string, { rows: any[]; key: string }> = {
       pull_requests: {
-        rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 79, url: "https://github.com/owner/repo/pull/79", title: "t", status: "waiting_merge", current_round: 4, process_key: "PI-MERGE" }],
+        rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 79, url: "https://github.com/owner/repo/pull/79", title: "t", status: "waiting_merge", current_round: 4, process_key: "PI-MERGE", merge_requested: 0, merge_human_approval: 1 }],
         key: "pr_key",
       },
       escalations: { rows: [], key: "id" },
@@ -2722,6 +2885,10 @@ test("submitPr handoffFrom: a failed reset restores the prior owner so the hand-
     assertEquals(row.process_key, "PI-MERGE", "rollback restores the prior owner, never leaves the cancelled key");
     assertEquals(row.status, "waiting_merge", "rollback restores the prior status");
     assertEquals(row.current_round, 4);
+    // PR #950 review: the merge-policy projection is restored WITH ownership, never left as the
+    // failed run's policy under the old owner (which /status would serve as authoritative).
+    assertEquals(row.merge_requested, 0, "rollback restores the prior merge intent");
+    assertEquals(row.merge_human_approval, 1, "rollback restores the prior approval state");
 
     failReset = false;
     const retry = await submitPr(data, engine, parsed, [], undefined, false, null, false, false, true, "PI-MERGE");