@nanobpm/nano-workforce 0.187.0 → 0.187.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.187.2](https://github.com/nanobpm/nano-workforce/compare/v0.187.1...v0.187.2) (2026-09-13)
+
+### Bug Fixes
+
+* **convergence:** key suppressed-advisory acks on line-stable identity ([#788](https://github.com/nanobpm/nano-workforce/issues/788)) ([9b9d124](https://github.com/nanobpm/nano-workforce/commit/9b9d1241dbd725cfe9b8ac88f5a9f5b949dc4fc4)), closes [#787](https://github.com/nanobpm/nano-workforce/issues/787) [#787](https://github.com/nanobpm/nano-workforce/issues/787) [pre-#787](https://github.com/nanobpm/pre-/issues/787) [#787](https://github.com/nanobpm/nano-workforce/issues/787)
+
+## [0.187.1](https://github.com/nanobpm/nano-workforce/compare/v0.187.0...v0.187.1) (2026-09-12)
+
+### Bug Fixes
+
+* **delivery-graph:** emit a deterministic branch.create so agent cells never commit on the base branch ([#781](https://github.com/nanobpm/nano-workforce/issues/781)) ([56f6488](https://github.com/nanobpm/nano-workforce/commit/56f6488344b439a5ac12f5069567facd9519bf66)), closes [#776](https://github.com/nanobpm/nano-workforce/issues/776) [pre-#776](https://github.com/nanobpm/pre-/issues/776) [#776](https://github.com/nanobpm/nano-workforce/issues/776)
+
 ## [0.187.0](https://github.com/nanobpm/nano-workforce/compare/v0.186.4...v0.187.0) (2026-09-12)
 
 ### Features

package/app/contracts.ts

@@ -399,7 +399,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` (the deterministic `feat/<task.id>`, emitted only for a single-task feature run; the epic seed AND the delivery-graph run-root seed omit it so each fan-out slice's agent branches per node/MI child). 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).",
+      "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` (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). 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).",
     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 } }',
   },

package/app/convergeGate.test.ts

@@ -11,9 +11,10 @@
 // thread, escalating to the human `wait-answer` task instead of finalizing.
 import { readFileSync } from "node:fs";
 import { test } from "node:test";
-import { assert, assertEquals, assertStringIncludes } from "#test-assert";
+import { assert, assertEquals, assertNotEquals, assertStringIncludes } from "#test-assert";
 import { evaluateConvergeGate } from "./convergeGate.ts";
 import {
+  advisoryStableKey,
   parseAckedAdvisories,
   parseReviewThreadsPage,
   parseSuppressedAdvisories,
@@ -24,13 +25,13 @@ import {
 // ── The canonical router ────────────────────────────────────────────────────
 
 test("evaluateConvergeGate: a clean PR (no unresolved threads, no advisories) converges", () => {
-  const r = evaluateConvergeGate({ unresolvedThreadCount: 0, suppressedKeys: [], acknowledgedKeys: [] });
+  const r = evaluateConvergeGate({ unresolvedThreadCount: 0, suppressedAdvisories: [], acknowledgedKeys: [] });
   assertEquals(r.convergeBlocked, false);
   assertEquals(r.convergeBlockReason, "");
 });
 
 test("evaluateConvergeGate: an unresolved review thread blocks convergence", () => {
-  const r = evaluateConvergeGate({ unresolvedThreadCount: 2, suppressedKeys: [], acknowledgedKeys: [] });
+  const r = evaluateConvergeGate({ unresolvedThreadCount: 2, suppressedAdvisories: [], acknowledgedKeys: [] });
   assertEquals(r.convergeBlocked, true);
   assertStringIncludes(r.convergeBlockReason, "2 unresolved review threads");
 });
@@ -38,7 +39,7 @@ test("evaluateConvergeGate: an unresolved review thread blocks convergence", ()
 test("evaluateConvergeGate: an unacknowledged suppressed advisory blocks convergence", () => {
   const r = evaluateConvergeGate({
     unresolvedThreadCount: 0,
-    suppressedKeys: ["spec/a.json:613"],
+    suppressedAdvisories: [{ key: "spec/a.json#deadbeef", label: "spec/a.json:613" }],
     acknowledgedKeys: [],
   });
   assertEquals(r.convergeBlocked, true);
@@ -50,16 +51,34 @@ test("evaluateConvergeGate: an unacknowledged suppressed advisory blocks converg
 test("evaluateConvergeGate: an ACKNOWLEDGED suppressed advisory no longer blocks convergence", () => {
   const r = evaluateConvergeGate({
     unresolvedThreadCount: 0,
-    suppressedKeys: ["spec/a.json:613"],
-    acknowledgedKeys: ["spec/a.json:613"],
+    suppressedAdvisories: [{ key: "spec/a.json#deadbeef", label: "spec/a.json:613" }],
+    acknowledgedKeys: ["spec/a.json#deadbeef"],
   });
   assertEquals(r.convergeBlocked, false);
 });
 
+test("evaluateConvergeGate: a prose-blind legacy `path:line` ack does NOT acknowledge an advisory (no false-OPEN)", () => {
+  // A resolved `nano-ack: spec/a.json:613` for a PRIOR advisory would yield only the `path:line`
+  // string — never a stable `<path>#<fp>` key. A genuinely new advisory at that same line carries a
+  // different stable key, so a bare-line ack can never satisfy it: the gate stays blocked. This is
+  // the guard for issue #787's re-review finding — honouring `path:line` let a resolved ack for
+  // advisory A silently converge a NEW advisory B re-emitted at the same line.
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedAdvisories: [{ key: "spec/a.json#deadbeef", label: "spec/a.json:613" }],
+    acknowledgedKeys: ["spec/a.json:613"],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertStringIncludes(r.convergeBlockReason, "spec/a.json:613");
+});
+
 test("evaluateConvergeGate: multiple unacknowledged advisories use the plural noun", () => {
   const r = evaluateConvergeGate({
     unresolvedThreadCount: 0,
-    suppressedKeys: ["x.ts:10", "y.ts:20"],
+    suppressedAdvisories: [
+      { key: "x.ts#a", label: "x.ts:10" },
+      { key: "y.ts#b", label: "y.ts:20" },
+    ],
     acknowledgedKeys: [],
   });
   assertEquals(r.convergeBlocked, true);
@@ -69,8 +88,11 @@ test("evaluateConvergeGate: multiple unacknowledged advisories use the plural no
 test("evaluateConvergeGate: reports both a thread and an advisory when both are outstanding", () => {
   const r = evaluateConvergeGate({
     unresolvedThreadCount: 1,
-    suppressedKeys: ["x.ts:10", "y.ts:20"],
-    acknowledgedKeys: ["x.ts:10"],
+    suppressedAdvisories: [
+      { key: "x.ts#a", label: "x.ts:10" },
+      { key: "y.ts#b", label: "y.ts:20" },
+    ],
+    acknowledgedKeys: ["x.ts#a"],
   });
   assertEquals(r.convergeBlocked, true);
   assertStringIncludes(r.convergeBlockReason, "1 unresolved review thread");
@@ -95,9 +117,19 @@ const SAMPLE_REVIEW_BODY = [
   "</details>",
 ].join("\n");
 
-test("parseSuppressedAdvisories: extracts only the keys inside the Suppressed comments block", () => {
-  const keys = parseSuppressedAdvisories(SAMPLE_REVIEW_BODY);
-  assertEquals(keys, ["spec-app/nano-app.schema.json:613", "server/src/main.rs:42"]);
+test("parseSuppressedAdvisories: extracts advisories inside the Suppressed comments block", () => {
+  const advisories = parseSuppressedAdvisories(SAMPLE_REVIEW_BODY);
+  assertEquals(
+    advisories.map((a) => a.label),
+    ["spec-app/nano-app.schema.json:613", "server/src/main.rs:42"],
+  );
+  // The line-stable key is `<path>#<fingerprint>` of the prose; `label` remains the human `path:line`.
+  assertEquals(advisories[0].label, "spec-app/nano-app.schema.json:613");
+  assertEquals(
+    advisories[0].key,
+    advisoryStableKey("spec-app/nano-app.schema.json", "The description could be clearer about the loopback default."),
+  );
+  assert(advisories[0].key.startsWith("spec-app/nano-app.schema.json#"), "stable key is path#fingerprint");
 });
 
 test("parseSuppressedAdvisories: returns [] when there is no suppressed block", () => {
@@ -108,12 +140,198 @@ test("parseSuppressedAdvisories: returns [] when there is no suppressed block",
 
 test("parseAckedAdvisories: only RESOLVED threads carrying a nano-ack marker count", () => {
   const threads: ReviewThread[] = [
-    { isResolved: true, path: "a.ts", bodies: ["Fixed. nano-ack: spec-app/nano-app.schema.json:613"] },
-    { isResolved: false, path: "b.ts", bodies: ["nano-ack: server/src/main.rs:42"] }, // open -> ignored
+    {
+      isResolved: true,
+      path: "a.ts",
+      bodies: ["Fixed. nano-ack: spec-app/nano-app.schema.json :: Clarify the loopback default."],
+    },
+    { isResolved: false, path: "b.ts", bodies: ["nano-ack: server/src/main.rs :: Narrow this type."] }, // open -> ignored
     { isResolved: true, path: "c.ts", bodies: ["unrelated resolved comment"] },
   ];
   const acked = parseAckedAdvisories(threads);
-  assertEquals(acked, ["spec-app/nano-app.schema.json:613"]);
+  assertEquals(acked, [advisoryStableKey("spec-app/nano-app.schema.json", "Clarify the loopback default.")]);
+});
+
+// A resolved bare `<path>:<line>` ack (the retired legacy form) must NOT count: it carries no
+// advisory prose, so it cannot identify WHICH advisory it acknowledged. Honouring it would false-OPEN
+// a genuinely new advisory re-emitted at that same line (issue #787's re-review finding).
+test("parseAckedAdvisories: a bare legacy `<path>:<line>` marker is NOT honoured (no prose-blind ack)", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: true, path: "a.ts", bodies: ["Fixed. nano-ack: spec-app/nano-app.schema.json:613"] },
+  ];
+  assertEquals(parseAckedAdvisories(threads), []);
+});
+
+test("parseAckedAdvisories: the new `<path> :: <text>` form yields the line-stable key", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: true, path: "a.ts", bodies: ["Declined. nano-ack: server/src/main.rs :: Consider narrowing this type."] },
+  ];
+  const acked = parseAckedAdvisories(threads);
+  assertEquals(acked, [advisoryStableKey("server/src/main.rs", "Consider narrowing this type.")]);
+});
+
+// A valid GitHub path can contain spaces; the ack form must not reject it (regression for the
+// critical review finding — `\S+`/`[^\s]` path groups silently dropped a spaced-path ack, so the
+// gate could never observe the acknowledgement and escalated forever).
+test("parseAckedAdvisories: a path containing spaces is honoured in the new `<path> :: <text>` form", () => {
+  const newForm: ReviewThread[] = [
+    { isResolved: true, path: "d.md", bodies: ["Applied. nano-ack: docs/my file.md :: Clarify the loopback default."] },
+  ];
+  assertEquals(parseAckedAdvisories(newForm), [advisoryStableKey("docs/my file.md", "Clarify the loopback default.")]);
+});
+
+// A valid GitHub path can itself contain `::` (e.g. `src/a::b.ts`); the ` :: ` separator must be
+// whitespace-delimited so a bare `::` inside the path is not mistaken for the delimiter (regression
+// for the suppressed finding: `\s*::\s*` split `src/a::b.ts :: text` at the wrong `::`, mangling the
+// path and producing a key that could never match the advisory).
+// The `<path> :: <text>` separator is whitespace-delimited, so a path containing a bare `::` is not
+// split at the interior `::` (a legacy `<path>:<line>` interior-colon test was retired with the
+// prose-blind legacy form).
+test("parseAckedAdvisories: a path containing `::` is not split at the interior `::`", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: true, path: "a.ts", bodies: ["Applied. nano-ack: src/a::b.ts :: Narrow the return type here."] },
+  ];
+  assertEquals(parseAckedAdvisories(threads), [advisoryStableKey("src/a::b.ts", "Narrow the return type here.")]);
+});
+
+// Normalization must preserve word boundaries, punctuation, and Unicode so distinct advisories on
+// one path do not alias to the same key (regression for the suppressed findings: deleting every
+// separator made `foo-bar`/`foobar` collide and non-ASCII-only prose normalized to an empty key;
+// collapsing punctuation-into-space aliased `Use foo() here` with `Use foo here` — a false-OPEN).
+test("advisoryStableKey: word boundaries, punctuation and Unicode are preserved (distinct prose -> distinct keys)", () => {
+  const p = "app/x.ts";
+  assertNotEquals(advisoryStableKey(p, "foo-bar"), advisoryStableKey(p, "foobar"));
+  // Two different non-ASCII-only advisories must not both collapse to the empty-string key.
+  assertNotEquals(advisoryStableKey(p, "café"), advisoryStableKey(p, "naïve"));
+  // Punctuation must NOT collapse into whitespace: prose differing only by punctuation-vs-space
+  // stays distinct, so a resolved ack for one cannot silently acknowledge the other (false-OPEN).
+  assertNotEquals(advisoryStableKey(p, "Use foo() here"), advisoryStableKey(p, "Use foo here"));
+  assertNotEquals(advisoryStableKey(p, "foo/bar"), advisoryStableKey(p, "foo bar"));
+  // Only case and whitespace runs are normalized (verbatim copy modulo reflow -> same key).
+  assertEquals(advisoryStableKey(p, "Foo  bar,   baz."), advisoryStableKey(p, "foo bar, baz."));
+  // NFC (not NFKC): compatibility variants must stay DISTINCT, or acking one false-OPENs the other.
+  // Full-width `！` vs ASCII `!` (NFKC would fold them together); ligature `fi` vs `fi`.
+  assertNotEquals(advisoryStableKey(p, "Use foo\uFF01"), advisoryStableKey(p, "Use foo!"));
+  assertNotEquals(advisoryStableKey(p, "The \uFB01le"), advisoryStableKey(p, "The file"));
+  // A precomposed vs decomposed accent IS canonically equivalent (NFC unifies) -> same key.
+  assertEquals(advisoryStableKey(p, "caf\u00E9"), advisoryStableKey(p, "cafe\u0301"));
+});
+
+// The advisory side strips a leading markdown bullet (Copilot renders suppressed prose as `* …`),
+// and the prompt tells the agent to copy that first line VERBATIM — so an ack marker legitimately
+// carries the `* ` bullet. Keying must therefore be bullet-insensitive on BOTH sides, else the ack
+// key never matches the advisory key and the gate livelocks (fail-CLOSED). Regression for the
+// suppressed finding that `parseSuppressedAdvisories` stripped the bullet but the ack path did not.
+test("advisoryStableKey: a leading markdown bullet is stripped so bulleted ack text matches", () => {
+  const p = "app/x.ts";
+  assertEquals(advisoryStableKey(p, "* Consider narrowing this type."), advisoryStableKey(p, "Consider narrowing this type."));
+  assertEquals(advisoryStableKey(p, "- Consider narrowing this type."), advisoryStableKey(p, "Consider narrowing this type."));
+  // But a leading `-`/`*` with NO trailing whitespace is NOT a bullet: it is preserved, so distinct
+  // first-line prose keeps a distinct key (else `-foo` false-acks `foo`). Regression for the finding
+  // that the greedy `[-*]\s*` stripped a non-bullet leading punctuation char.
+  assertNotEquals(advisoryStableKey(p, "-foo"), advisoryStableKey(p, "foo"));
+  assertNotEquals(advisoryStableKey(p, "*foo"), advisoryStableKey(p, "foo"));
+});
+
+// End-to-end: an ack whose marker copies Copilot's bulleted first line verbatim acknowledges the
+// advisory parsed from that same rendered bullet (the ack key == the parsed advisory key).
+test("parseAckedAdvisories: an ack copying the rendered `* ` bullet verbatim matches the advisory key", () => {
+  const advisories = parseSuppressedAdvisories(SAMPLE_REVIEW_BODY);
+  const bulleted = advisories.map((a) => a.label); // ["…schema.json:613", "…main.rs:42"]
+  assert(bulleted.length === 2);
+  const threads: ReviewThread[] = [
+    {
+      isResolved: true,
+      path: "a.ts",
+      // Verbatim copy of Copilot's rendered first line, bullet included.
+      bodies: ["Declined. nano-ack: server/src/main.rs :: - Consider narrowing this type."],
+    },
+  ];
+  const acked = parseAckedAdvisories(threads);
+  const mainRs = advisories.find((a) => a.path === "server/src/main.rs");
+  assert(mainRs !== undefined);
+  assert(acked.includes(mainRs.key), "bulleted verbatim ack resolves to the advisory's stable key");
+});
+
+// A collision in the advisory fingerprint would let a NEWER, unacknowledged advisory on the same
+// path pass the gate on a resolved ack for a DIFFERENT advisory — a false-OPEN. The former 32-bit
+// FNV-1a digest was cheaply collidable; the key now carries a 128-bit (32-hex) SHA-256 slice.
+test("advisoryStableKey: digest is a collision-resistant 128-bit (32-hex) SHA-256 slice", () => {
+  const p = "app/x.ts";
+  const hash = advisoryStableKey(p, "Some advisory prose.").split("#")[1];
+  assertEquals(hash.length, 32, "digest is 32 hex chars (128 bits)");
+  assert(/^[0-9a-f]{32}$/.test(hash), "digest is lowercase hex");
+  // Distinct prose on the same path yields distinct keys (no cheap collision surface).
+  assertNotEquals(
+    advisoryStableKey(p, "Narrow this return type."),
+    advisoryStableKey(p, "Guard against a null argument here."),
+  );
+});
+
+// ── Issue #787: a DECLINED advisory must not livelock the gate when its line drifts ──────────
+//
+// A declined advisory is re-emitted by Copilot every round; any unrelated edit shifts its line, so
+// Copilot re-anchors it to a new line. Keying the ack on the line-stable prose fingerprint (not
+// path:line) keeps a prior-round ack matching the re-emitted advisory across the drift.
+test("converge gate #787: a stable-key ack survives a line drift and keeps the advisory acknowledged", () => {
+  const proseText = "Consider narrowing this type.";
+  // Round 1: Copilot suppressed the advisory at line 360; the agent acked it with the new form.
+  const round1Body = [
+    "<details>",
+    "<summary>Suppressed comments (1)</summary>",
+    "",
+    "**app/deliveryRunner.ts:360**",
+    `- ${proseText}`,
+    "</details>",
+  ].join("\n");
+  // Round 2: an unrelated edit shifted the SAME advisory to line 369; Copilot re-emitted it there.
+  const round2Body = round1Body.replace("app/deliveryRunner.ts:360", "app/deliveryRunner.ts:369");
+  // The resolved ack thread from round 1 persists (its marker text is line-independent).
+  const ackThreads: ReviewThread[] = [
+    { isResolved: true, path: "app/deliveryRunner.ts", bodies: [`Declined, false positive. nano-ack: app/deliveryRunner.ts :: ${proseText}`] },
+  ];
+  const acknowledgedKeys = parseAckedAdvisories(ackThreads);
+
+  const round1 = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedAdvisories: parseSuppressedAdvisories(round1Body),
+    acknowledgedKeys,
+  });
+  assertEquals(round1.convergeBlocked, false);
+
+  // The drift MUST NOT re-block: the round-1 ack still acknowledges the round-2 re-emission.
+  const round2 = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedAdvisories: parseSuppressedAdvisories(round2Body),
+    acknowledgedKeys,
+  });
+  assertEquals(round2.convergeBlocked, false);
+});
+
+test("converge gate #787: a genuinely new, never-acked advisory still blocks (no false-open)", () => {
+  const body = [
+    "<details>",
+    "<summary>Suppressed comments (2)</summary>",
+    "",
+    "**app/x.ts:10**",
+    "- The declined advisory that was acknowledged.",
+    "",
+    "**app/x.ts:20**", // SAME path, DIFFERENT advisory — never acknowledged.
+    "- A brand-new concern that was never triaged.",
+    "</details>",
+  ].join("\n");
+  const ackThreads: ReviewThread[] = [
+    { isResolved: true, path: "app/x.ts", bodies: ["Declined. nano-ack: app/x.ts :: The declined advisory that was acknowledged."] },
+  ];
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedAdvisories: parseSuppressedAdvisories(body),
+    acknowledgedKeys: parseAckedAdvisories(ackThreads),
+  });
+  assertEquals(r.convergeBlocked, true);
+  // Only the un-acked advisory on the same path is reported; the acked one is not.
+  assertStringIncludes(r.convergeBlockReason, "app/x.ts:20");
+  assert(!r.convergeBlockReason.includes("app/x.ts:10"), "the acknowledged advisory must not be listed");
 });
 
 test("parseReviewThreadsPage: maps nodes and reports a complete (final) page", () => {
@@ -254,8 +472,18 @@ test("converge-gate: an unacknowledged suppressed advisory blocks convergence",
 test("converge-gate: an acknowledged advisory (resolved ack thread) is allowed", async () => {
   const handler = await makeUnderTest({
     readThreads: async () => [
-      { isResolved: true, path: "spec-app/nano-app.schema.json", bodies: ["Applied. nano-ack: spec-app/nano-app.schema.json:613"] },
-      { isResolved: true, path: "server/src/main.rs", bodies: ["Declined, false positive. nano-ack: server/src/main.rs:42"] },
+      {
+        isResolved: true,
+        path: "spec-app/nano-app.schema.json",
+        bodies: [
+          "Applied. nano-ack: spec-app/nano-app.schema.json :: The description could be clearer about the loopback default.",
+        ],
+      },
+      {
+        isResolved: true,
+        path: "server/src/main.rs",
+        bodies: ["Declined, false positive. nano-ack: server/src/main.rs :: Consider narrowing this type."],
+      },
     ],
     readReviewBody: async () => SAMPLE_REVIEW_BODY,
   });

package/app/convergeGate.ts

@@ -6,16 +6,19 @@
 // the comment unaddressed). This deterministic gate runs on the converged path and blocks handoff
 // while either:
 //   • any review THREAD is still unresolved, or
-//   • any SUPPRESSED advisory (`path:line` in the latest Copilot review body) lacks a matching
-//     RESOLVED ack thread (a thread carrying a `nano-ack: <path>:<line>` marker).
+//   • any SUPPRESSED advisory (in the latest Copilot review body) lacks a matching
+//     RESOLVED ack thread (a thread carrying a line-stable `nano-ack: <path> :: <text>` marker; the
+//     bare `nano-ack: <path>:<line>` form is NOT honoured — its `path:line` key is prose-blind and
+//     would false-OPEN a new advisory re-emitted at a previously-acked line).
 // A blocked gate escalates to the human wait-answer task (recoverable), never a hard wedge.
 
 export interface ConvergeGateInput {
   /** Count of review threads with `isResolved === false`. */
   unresolvedThreadCount: number;
-  /** `path:line` keys of Copilot's suppressed advisories (latest review body). */
-  suppressedKeys: string[];
-  /** `path:line` keys acknowledged by RESOLVED `nano-ack:` threads. */
+  /** Copilot's suppressed advisories (latest review body), each with its line-stable key + label. */
+  suppressedAdvisories: { key: string; label: string }[];
+  /** Acknowledged line-stable keys (`<path>#<fp>`) from RESOLVED `nano-ack:` threads. An advisory is
+   * acked iff its stable key appears here. */
   acknowledgedKeys: string[];
 }
 
@@ -28,7 +31,11 @@ export interface ConvergeGateResult {
  * feeds it live GitHub state and fails CLOSED (blocks) when that state cannot be read. */
 export function evaluateConvergeGate(input: ConvergeGateInput): ConvergeGateResult {
   const acked = new Set(input.acknowledgedKeys);
-  const unacked = input.suppressedKeys.filter((k) => !acked.has(k));
+  // An advisory is acknowledged iff its line-stable prose key was acked — the stable key survives a
+  // line drift across rounds (issue #787). The prose-blind legacy `path:line` key is intentionally
+  // NOT consulted: it would let a resolved ack for one advisory silently acknowledge a genuinely new
+  // advisory re-emitted at the same line (a false-OPEN this gate exists to prevent).
+  const unacked = input.suppressedAdvisories.filter((a) => !acked.has(a.key));
   const reasons: string[] = [];
   if (input.unresolvedThreadCount > 0) {
     const n = input.unresolvedThreadCount;
@@ -36,13 +43,13 @@ export function evaluateConvergeGate(input: ConvergeGateInput): ConvergeGateResu
   }
   if (unacked.length > 0) {
     const noun = unacked.length === 1 ? "advisory" : "advisories";
-    reasons.push(`${unacked.length} unacknowledged suppressed ${noun} (${unacked.join(", ")})`);
+    reasons.push(`${unacked.length} unacknowledged suppressed ${noun} (${unacked.map((a) => a.label).join(", ")})`);
   }
   if (reasons.length === 0) {
     return { convergeBlocked: false, convergeBlockReason: "" };
   }
   return {
     convergeBlocked: true,
-    convergeBlockReason: `Convergence blocked: ${reasons.join("; ")}. Resolve every review thread and reply-and-resolve an ack thread (nano-ack: <path>:<line>) for each suppressed advisory before converging.`,
+    convergeBlockReason: `Convergence blocked: ${reasons.join("; ")}. Resolve every review thread and reply-and-resolve an ack thread (nano-ack: <path> :: <verbatim advisory text>) for each suppressed advisory before converging.`,
   };
 }

package/app/deliveryGraphCompiler.ts

@@ -1057,15 +1057,19 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>): stri
 
 /** Render the DECLARED per-node repository-spec marker task header (#739) for an `agent` node — a single
  * `<zeebe:taskHeaders>` block carrying {@link AGENT_REPO_SPEC_HEADER} with a compact JSON of the node's
- * DECLARED `{ repository, baseBranch }` (each `null` when absent). It is emitted on EVERY agent service
- * task (even one with no declared repo → `{"repository":null,"baseBranch":null}`) so the runner has a
- * single, uniform anchor to replace with the effective envelope on every cell. Digest-stable and
- * env-free — only the declared values (pure graph content) appear here; the run-level fallback and the
- * env-dependent `cloneTimeoutMs` are injected by the runner POST-digest. Declared values pass the
- * `owner/repo` + branch-name allowlists (validator/OpenAPI), so the JSON carries no XML-hostile chars. */
+ * `id` and its DECLARED `{ repository, baseBranch }` (each `null` when absent). It is emitted on EVERY
+ * agent service task (even one with no declared repo → `{"repository":null,"baseBranch":null}`) so the
+ * runner has a single, uniform anchor to replace with the effective envelope on every cell. The node
+ * `id` is carried here (issue #776) so the runner can emit the deterministic per-node `feat/<node.id>`
+ * `branch.create` on the injected envelope — the identity is not otherwise recoverable from the isolated
+ * `<zeebe:taskHeaders>` block the runner rewrites. Digest-stable and env-free — only the node id and
+ * declared values (pure graph content) appear here; the run-level fallback and the env-dependent
+ * `cloneTimeoutMs` are injected by the runner POST-digest. The id + declared values pass the
+ * `owner/repo` + node-id/branch-name allowlists (validator/OpenAPI), so the JSON carries no XML-hostile
+ * chars. */
 function agentRepoSpecHeaderLines(node: Extract<DeliveryNode, { kind: "agent" }>): string[] {
   const trimOrNull = (v: unknown): string | null => (typeof v === "string" && v.trim() !== "" ? v.trim() : null);
-  const spec = JSON.stringify({ repository: trimOrNull(node.agent.repository), baseBranch: trimOrNull(node.agent.baseBranch) });
+  const spec = JSON.stringify({ nodeId: node.id, repository: trimOrNull(node.agent.repository), baseBranch: trimOrNull(node.agent.baseBranch) });
   return [
     "          <zeebe:taskHeaders>",
     `            <zeebe:header key="${AGENT_REPO_SPEC_HEADER}" ${attr("value", spec)} />`,

package/app/deliveryRunner.test.ts

@@ -13,7 +13,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects } from "#test-assert";
 import { AGENT_TERMINAL_SUCCESS_STATUSES } from "./deliveryGraphCompiler.ts";
 import { prepareDeliveryGraph, renderEmitContract, renderIdempotencyPreamble, renderProducerContract, runDeliveryGraph } from "./deliveryRunner.ts";
-import { RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
+import { RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError, agentNodeRepoEnvelope } from "./repoEnvelope.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 const GRAPH: DeliveryGraph = {
@@ -488,6 +488,9 @@ test("prepareDeliveryGraph injects the repository envelope PER agent cell from t
   // Repo-provisioning auth gate (issue #770): the per-cell envelope carries `task.allowPr:true` so the
   // c8ctl harness resolves the git credential for the clone instead of failing on password prompt.
   assert(headers.some((h) => h.includes('task.allowPr" value="true"')), `expected a task.allowPr header, got ${JSON.stringify(headers)}`);
+  // The deterministic per-node isolation branch (issue #776): the harness cuts `feat/<node.id>` itself,
+  // so the agent can never be left committing on the base branch (a non-ff push that strands the run).
+  assert(headers.some((h) => h.includes('repository.branch.create" value="feat/open-b"')), `expected a per-node branch.create header, got ${JSON.stringify(headers)}`);
   // No `__repoSpec` marker survives injection — it is the compiler's digest-stable anchor only.
   assert(!p.bpmn.includes("__repoSpec"), "the __repoSpec marker is fully replaced");
   // No run-root `io.nanobpm.agentTask` variable — the envelope rides headers now, not a run variable.
@@ -542,6 +545,68 @@ test("a declared repository WITHOUT a base branch omits ref/baseRef — the harn
   assert(headers.some((h) => h.includes('repository.url" value="https://github.com/acme/one.git"')), "url present");
   assert(!headers.some((h) => h.includes("repository.ref")), "no ref → clone the repo default branch");
   assert(!headers.some((h) => h.includes("repository.baseRef")), "no baseRef either");
+  // Even without a known base, the deterministic isolation branch is still emitted (issue #776): the
+  // harness cuts `feat/<node.id>` off the cloned default tip, so the agent never commits on the default.
+  assert(headers.some((h) => h.includes('repository.branch.create" value="feat/a"')), `expected branch.create even without a base, got ${JSON.stringify(headers)}`);
+});
+
+test("each agent cell gets its OWN deterministic feat/<node.id> branch.create — never a shared branch (#776)", async () => {
+  const graph: DeliveryGraph = {
+    name: "deterministic isolation branches",
+    nodes: [
+      { id: "impl-a", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one" } },
+      { id: "impl-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "b", repository: "acme/two" } },
+    ],
+    edges: [{ from: "impl-a", to: "impl-b" }],
+  };
+  const p = await prepareOk(graph, {});
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  // Two distinct cells → two distinct per-node branches, so no two agents can collide on one branch.
+  assert(branches.some((h) => h.includes('value="feat/impl-a"')), `expected feat/impl-a, got ${JSON.stringify(branches)}`);
+  assert(branches.some((h) => h.includes('value="feat/impl-b"')), `expected feat/impl-b, got ${JSON.stringify(branches)}`);
+  assertEquals(branches.length, 2, "exactly one branch.create per agent cell");
+});
+
+test("an explicit repoless run emits NO branch.create — no envelope at all (#776/#729)", async () => {
+  const p = await prepareOk(GRAPH, { repoless: true });
+  assert(!p.bpmn.includes("repository.branch.create"), "a repoless run carries no isolation branch either");
+});
+
+test("a node id that derives an invalid git ref degrades to NO branch.create — never emits an unusable feat/... (#776)", async () => {
+  // Node ids are only constrained by `^[A-Za-z_][A-Za-z0-9_.-]*$`, laxer than git's ref rules: `a..b` and
+  // `a.lock` pass id validation but produce ill-formed `feat/...` refs the harness cannot create. The
+  // runner must degrade to the pre-#776 agent-cuts-its-own-branch behaviour (no branch.create) for those,
+  // not emit a branch the harness will choke on — while a sibling with a valid id still gets its branch.
+  const graph: DeliveryGraph = {
+    name: "invalid-ref node ids degrade",
+    nodes: [
+      { id: "a..b", kind: "agent", agent: { jobType: "senior:feature", prompt: "a", repository: "acme/one" } },
+      { id: "a.lock", kind: "agent", agent: { jobType: "senior:feature", prompt: "b", repository: "acme/two" } },
+      { id: "ok", kind: "agent", agent: { jobType: "senior:feature", prompt: "c", repository: "acme/three" } },
+    ],
+    edges: [{ from: "a..b", to: "a.lock" }, { from: "a.lock", to: "ok" }],
+  };
+  const p = await prepareOk(graph, {});
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  // Only the valid-id cell keeps a branch.create; the two invalid-ref ids emit none (their agents still
+  // provision an isolated clone, they just cut their own branch inside it — the pre-#776 fallback).
+  assertEquals(branches.length, 1, `only the valid id keeps a branch.create, got ${JSON.stringify(branches)}`);
+  assert(branches[0].includes('value="feat/ok"'), `expected feat/ok, got ${JSON.stringify(branches)}`);
+});
+
+test("agentNodeRepoEnvelope emits branch.create off the base when known, off the default when not, and omits it when blank (#776)", () => {
+  const withBase = (agentNodeRepoEnvelope("acme/one", "main", "feat/n1") as any)["io.nanobpm.agentTask"].repository;
+  assertEquals(withBase.ref, "main", "known base → checked-out ref");
+  assertEquals(withBase.branch.create, "feat/n1", "the harness cuts feat/<node.id> off the base");
+  const noBase = (agentNodeRepoEnvelope("acme/one", null, "feat/n2") as any)["io.nanobpm.agentTask"].repository;
+  assertEquals("ref" in noBase, false, "no base → clone the default branch");
+  assertEquals(noBase.branch.create, "feat/n2", "branch.create is still emitted off the default tip");
+  // A whitespace-tainted branch is trimmed; a blank/absent one omits the `branch` key (pre-#776 behaviour).
+  assertEquals((agentNodeRepoEnvelope("acme/one", "main", "  feat/n3  ") as any)["io.nanobpm.agentTask"].repository.branch.create, "feat/n3");
+  for (const blank of [null, undefined, "", "   "]) {
+    const r = (agentNodeRepoEnvelope("acme/one", "main", blank as any) as any)["io.nanobpm.agentTask"].repository;
+    assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
+  }
 });
 
 test("prepareDeliveryGraph seeds NO envelope ONLY on an EXPLICIT repoless run — the conscious opt-out (#729)", async () => {

package/app/deliveryRunner.ts

@@ -18,6 +18,7 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
+import { isPlausibleBranchName } from "./baseBranch.ts";
 import { AGENT_REPO_SPEC_HEADER, AGENT_TERMINAL_SUCCESS_STATUSES, assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, isResolvableRepo, RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
@@ -80,9 +81,10 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
   repository?: string | null;
   /** OPTIONAL run-level base-branch DEFAULT for `agent` nodes that declare a `repository` but no
    * `baseBranch` — the `ref` the harness checks out in the isolated clone (the PRE-PR shape: no PR head
-   * exists yet, so the agent cuts its own `feat/<node.id>` branch off this base inside the clone). A
-   * node with a resolvable repository but no base clones the repo's default branch, so this is a
-   * convenience default, not a hard requirement. */
+   * exists yet). Per issue #776 the harness itself cuts the deterministic `feat/<node.id>` branch off
+   * this base (emitted as `branch.create`) so a forgetful agent can never be left committing on the base
+   * branch; a node with a resolvable repository but no base clones the repo's default branch, so this is
+   * a convenience default, not a hard requirement. */
   baseBranch?: string | null;
   /** EXPLICIT opt-out of repository provisioning (issue #729). `true` → the run is dispatched with NO
    * isolation envelope on ANY node (the per-node headers are stripped, the legacy launch-dir behaviour),
@@ -345,13 +347,28 @@ function injectAgentRepoEnvelopes(bpmn: string, graph: DeliveryGraph, options: D
   );
   return bpmn.replace(blockRe, (_full, indent: string, sq: string | undefined, dq: string | undefined, tail: string) => {
     const raw = sq ?? (dq ?? "").replace(/&apos;/g, "'").replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
-    const declared: { repository: string | null; baseBranch: string | null } = JSON.parse(raw);
+    const declared: { nodeId?: string; repository: string | null; baseBranch: string | null } = JSON.parse(raw);
     // `repoless` → strip the block entirely (no isolation envelope, the launch-dir fallback).
     if (repoless) return "";
     const effRepo = trimOrNull(declared.repository) ?? runRepo;
     const effBase = trimOrNull(declared.baseBranch) ?? runBase;
+    // The deterministic per-node isolation branch (issue #776): the harness cuts `feat/<node.id>` itself
+    // so a cell can never leave its agent committing on the checked-out base branch (a non-ff push that
+    // strands the run — merlin job 20974). The node id rides the marker so it survives into this
+    // per-block rewrite; delivery-graph agent cells are single-instance, so the static per-node branch
+    // never collides across siblings. Omitted when the marker predates the id (a blank id degrades to the
+    // pre-#776 agent-cuts-its-own-branch behaviour rather than an ill-formed `feat/`).
+    // A graph node id is only constrained by `^[A-Za-z_][A-Za-z0-9_.-]*$` (deliveryGraph.ts), which is
+    // laxer than git's ref rules: ids like `a..b`, `a.`, or `a.lock` pass id validation yet produce an
+    // ill-formed `feat/...` ref the harness cannot create — turning the isolation guarantee into a
+    // launch/checkout failure. Validate the DERIVED branch with the same `isPlausibleBranchName` gate the
+    // dispatch doors use and degrade to null (the pre-#776 agent-cuts-its-own-branch behaviour) rather
+    // than emit an unusable branch.create.
+    const nodeId = trimOrNull(declared.nodeId);
+    const derivedBranch = nodeId ? `feat/${nodeId}` : null;
+    const branchCreate = derivedBranch !== null && isPlausibleBranchName(derivedBranch) ? derivedBranch : null;
     // The unresolved invariant above guarantees a resolvable repo here on a non-repoless run.
-    const envelope = agentNodeRepoEnvelope(effRepo ?? "", effBase);
+    const envelope = agentNodeRepoEnvelope(effRepo ?? "", effBase, branchCreate);
     const flat = flattenAgentTaskEnvelope(envelope);
     const headerLines = Object.entries(flat).map(([k, v]) => `${indent}  <zeebe:header key="${xmlAttr(k)}" value="${xmlAttr(v)}" />`);
     if (headerLines.length === 0) return "";

package/app/github.ts

@@ -11,6 +11,8 @@
 // The poller is app-side host glue (main.ts), so host-specific subprocess I/O is allowed here.
 // Cross-runtime: runs under Node (`node:child_process`).
 
+import { createHash } from "node:crypto";
+
 // Type-only import (erased at runtime, so no runtime cycle with mergeProtocol.ts, which imports
 // `fetchRepoFile` from here): `classifyMergeability` reads a repo's declared required checks to gate
 // a merge independently of GitHub branch protection.
@@ -90,9 +92,23 @@ export async function fetchPrReviews(
 //   • SUPPRESSED / low-confidence advisories — Copilot folds these into the review BODY under a
 //     "Suppressed comments (N)" block; they are NOT threads, cannot be resolved, and are re-listed
 //     every round. To make "acknowledged" trackable, the review-round agent must post a RESOLVED
-//     review thread carrying a `nano-ack: <path>:<line>` marker (the exact key from Copilot's
-//     `**path:line**` header) for each advisory it applies or declines. The gate then treats an
-//     advisory as addressed iff a resolved thread carries its ack marker.
+//     review thread carrying a `nano-ack:` marker for each advisory it applies or declines. The gate
+//     then treats an advisory as addressed iff a resolved thread carries a matching ack marker.
+//
+// The ack key must be LINE-STABLE. Keying it on `path:line` (issue #787) livelocks a DECLINED
+// advisory: Copilot re-emits a declined advisory every round, but any unrelated edit in the PR
+// shifts its line, so Copilot re-anchors it to a new line. A prior-round `nano-ack: path:OLD` no
+// longer matches the re-emitted `path:NEW`, the gate sees a freshly "unacknowledged" advisory, and
+// escalates to a human every round. The fix keys acknowledgement on a line-independent identity —
+// `<path>#<fingerprint>` of the advisory's PROSE — so a drifted line still matches. The resolved
+// ack thread is itself the durable store: its marker text survives across rounds regardless of the
+// line, so a decline stays acknowledged without the agent re-acking each round. The new marker is
+// `nano-ack: <path> :: <verbatim advisory text>`. This line-stable prose key is the SOLE ack
+// identity. A bare `nano-ack: <path>:<line>` form is NOT honoured: keyed only on `path:line`, it is
+// blind to the advisory's prose, so a resolved legacy ack for advisory A at a line would silently
+// acknowledge a genuinely NEW advisory B re-emitted at that same line — a false-OPEN this gate exists
+// to prevent. (Issue #787 introduces the ack mechanism itself in this change, so there is no pre-#787
+// legacy-ack corpus to protect by honouring the prose-blind form.)
 
 /** One PR review thread, narrowed to what the convergence gate needs. */
 export interface ReviewThread {
@@ -101,30 +117,141 @@ export interface ReviewThread {
   bodies: string[];
 }
 
-/** The `nano-ack:` acknowledgement marker the review-round agent stamps into the resolved thread
- * it opens per suppressed advisory. The captured group is the advisory key (`path:line`). */
-const ACK_MARKER = /nano-ack:\s*([^\s)>*]+:\d+)/gi;
-
-/** Parse the `path:line` keys of Copilot's suppressed / low-confidence advisories out of a review
- * body. Copilot renders them under a `<summary>Suppressed comments (N)</summary>` block, each as a
- * bold `**path:line**` header. Returns the de-duplicated keys (empty when there is no such block). */
-export function parseSuppressedAdvisories(reviewBody: string | null | undefined): string[] {
+/** A suppressed / low-confidence Copilot advisory parsed out of a review body. Its `key` is the
+ * line-stable identity (survives a line drift); `label` is the human-facing `path:line` shown in
+ * block reasons. */
+export interface SuppressedAdvisory {
+  path: string;
+  line: number;
+  /** The advisory prose (first non-empty line after the header), used for the stable fingerprint. */
+  text: string;
+  /** Line-stable identity: `<path>#<fingerprint>` of the normalized prose. Survives line drift. */
+  key: string;
+  /** Human-facing `path:line` label for block-reason messages. */
+  label: string;
+}
+
+/** Any `nano-ack:` marker — captures the rest of the marker's line (path + optional `:: text`). */
+const ACK_MARKER = /nano-ack:\s*([^\n\r]+)/gi;
+/** The ONLY honoured ack form: line-stable `<path> :: <advisory text>`. The delimiter is ` :: ` with
+ * REQUIRED surrounding whitespace (matching the canonical marker the agent authors), so a bare `::`
+ * inside a valid GitHub path (e.g. `src/a::b.ts`) is NOT mistaken for the separator — the path group
+ * parses non-greedily up to the first *whitespace-delimited* ` :: `, so a path containing spaces
+ * (e.g. `docs/my file.md`) is still honoured. A bare `<path>:<line>` marker is intentionally not
+ * parsed: keyed only on `path:line`, it is blind to the advisory prose and would false-OPEN a new
+ * advisory re-emitted at a previously-acked line. */
+const NEW_ACK = /^(.+?)\s+::\s+(.+)$/s;
+
+/** Normalize advisory prose to a line-/format-independent form before fingerprinting: strip a
+ * leading markdown bullet, NFC-normalize, lowercase, and collapse runs of WHITESPACE to a single
+ * space. Punctuation is PRESERVED, NOT collapsed: the prompt requires the agent to copy the
+ * advisory's first line VERBATIM, so whitespace/case tolerance is all that is needed to absorb
+ * trivial markdown/whitespace reflow. Collapsing every non-word run into a space (as an earlier
+ * revision did) instead ALIASES genuinely-distinct advisories whose prose differs only by
+ * punctuation-vs-space — e.g. `Use foo() here` vs `Use foo here`, or `foo/bar` vs `foo bar` — so a
+ * resolved ack for advisory A would silently acknowledge a DIFFERENT advisory B that normalizes to
+ * the same key: a false-OPEN this gate exists to prevent. Preserving punctuation errs toward a
+ * stricter match, which is fail-CLOSED: a benign punctuation mismatch merely re-escalates to a
+ * human, and never converges an unacknowledged advisory.
+ *
+ * NFC — canonical composition — is used deliberately in preference to NFKC. NFKC additionally folds
+ * COMPATIBILITY variants (full-width `！` → ASCII `!`, ligatures, super/subscripts, …), which would
+ * ALIAS genuinely-distinct advisories such as `Use foo！` and `Use foo!` to one key — the very
+ * false-OPEN this fingerprint exists to prevent, and a contradiction with "punctuation is
+ * preserved". NFC only unifies sequences that are canonically equivalent (visually and semantically
+ * identical, e.g. a precomposed `é` vs `e`+combining-acute), so verbatim copies still match while
+ * distinct compatibility forms stay distinct (fail-CLOSED). Unicode letters/digits are preserved
+ * rather than stripped, so non-ASCII-only prose still yields a non-empty, distinct key.
+ *
+ * The leading-bullet strip keeps the ADVISORY side (Copilot renders suppressed prose as `* …`, which
+ * `parseSuppressedAdvisories` also strips for display) and the ACK side SYMMETRIC: the prompt tells
+ * the agent to copy the advisory's first line verbatim, so an ack marker legitimately carries the
+ * `* ` bullet — without stripping it here the ack key would differ from the advisory key and the
+ * gate would never converge (fail-CLOSED livelock). Applying it in this shared canonicaliser is the
+ * SINGLE source of truth for both sides.
+ *
+ * The bullet marker REQUIRES trailing whitespace (`[-*]\s+`): a genuine markdown bullet is always
+ * `- ` / `* ` followed by a space, so `-foo` / `*foo` (leading punctuation, no separator) is NOT a
+ * bullet and its leading char is PRESERVED. A greedy `\s*` there would strip the `-`/`*` off such
+ * prose too, collapsing distinct first lines like `-foo` and `foo` to one key — a false-ACK
+ * (false-OPEN) where acking one silently satisfies the other. */
+function normalizeAdvisoryText(text: string): string {
+  return text
+    .normalize("NFC")
+    .replace(/^\s*[-*]\s+/u, "")
+    .toLowerCase()
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
+/** COLLISION-RESISTANT fingerprint of a string → 32-hex-char (128-bit) digest, the leading half of
+ * a SHA-256 hash. Deterministic and dependency-free (Node's built-in `node:crypto`, no npm dep).
+ *
+ * The gate treats an advisory whose key `<path>#<fingerprint>` matches a resolved ack as addressed,
+ * so a *collision* would let a NEWER, unacknowledged advisory on the same path pass without its own
+ * ack — a false-OPEN that violates the gate's no-false-open guarantee. The former 32-bit FNV-1a
+ * digest was cheap to collide (birthday bound ~2^16); a 128-bit SHA-256 slice makes an accidental
+ * collision (~2^-64 for realistic advisory counts) infeasible. The digest is INTERNAL to the key —
+ * it never appears in a human-authored `nano-ack:` marker (those carry the verbatim prose, which is
+ * re-fingerprinted at read time), so widening it neither lengthens any marker nor breaks a
+ * previously-issued one: both the advisory side and the ack side recompute with this same function. */
+function fingerprint(s: string): string {
+  return createHash("sha256").update(s, "utf8").digest("hex").slice(0, 32);
+}
+
+/** The line-stable acknowledgement key for an advisory: `<path>#<fingerprint(normalized prose)>`.
+ * Exported so the review-round agent's contract and tests share one canonical implementation. */
+export function advisoryStableKey(path: string, text: string): string {
+  return `${path.trim()}#${fingerprint(normalizeAdvisoryText(text))}`;
+}
+
+/** Parse Copilot's suppressed / low-confidence advisories out of a review body. Copilot renders them
+ * under a `<summary>Suppressed comments (N)</summary>` block, each as a bold `**path:line**` header
+ * followed by the advisory prose. Returns de-duplicated advisories (empty when there is no block). */
+export function parseSuppressedAdvisories(reviewBody: string | null | undefined): SuppressedAdvisory[] {
   const body = reviewBody ?? "";
   const idx = body.search(/Suppressed comments\s*\(/i);
   if (idx < 0) return [];
   // Scan only from the "Suppressed comments" marker onward so a `**path:line**` elsewhere in the
   // overview prose can never be mistaken for an advisory.
   const region = body.slice(idx);
-  const keys = new Set<string>();
-  const re = /\*\*([^*]+?:\d+)\*\*/g;
-  let m: RegExpExecArray | null;
-  // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec accumulation loop
-  while ((m = re.exec(region)) !== null) keys.add(m[1].trim());
-  return [...keys];
+  const lines = region.split(/\r?\n/);
+  const headerRe = /\*\*([^*]+?):(\d+)\*\*/;
+  const out: SuppressedAdvisory[] = [];
+  const seen = new Set<string>();
+  for (let i = 0; i < lines.length; i++) {
+    const h = headerRe.exec(lines[i]);
+    if (!h) continue;
+    const path = h[1].trim();
+    const line = Number(h[2]);
+    const label = `${path}:${line}`;
+    // The advisory prose is the first non-empty line after the header (up to the next header). A
+    // single bullet is the common shape; strip a leading markdown bullet marker for the display
+    // `text`. (Keying is bullet-insensitive regardless: `normalizeAdvisoryText` strips a leading
+    // bullet too, so the ack side — which copies the bulleted first line verbatim — keys the same.)
+    let text = "";
+    for (let j = i + 1; j < lines.length; j++) {
+      if (headerRe.test(lines[j])) break;
+      const t = lines[j].replace(/^\s*[-*]\s+/, "").trim();
+      if (t) {
+        text = t;
+        break;
+      }
+    }
+    const key = advisoryStableKey(path, text);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ path, line, text, key, label });
+  }
+  return out;
 }
 
 /** Extract the acknowledged advisory keys from a set of review threads (only RESOLVED threads
- * count — an open ack thread is not yet an acknowledgement). */
+ * count — an open ack thread is not yet an acknowledgement). Returns line-stable keys (`<path>#<fp>`)
+ * parsed from the `nano-ack: <path> :: <text>` form ONLY. A bare `nano-ack: <path>:<line>` marker is
+ * intentionally NOT honoured: its `path:line` key is blind to the advisory prose and would false-OPEN
+ * a genuinely new advisory re-emitted at a previously-acked line. The gate treats an advisory as
+ * acked iff its stable key appears here. */
 export function parseAckedAdvisories(threads: ReviewThread[]): string[] {
   const acked = new Set<string>();
   for (const t of threads) {
@@ -133,7 +260,10 @@ export function parseAckedAdvisories(threads: ReviewThread[]): string[] {
       ACK_MARKER.lastIndex = 0;
       let m: RegExpExecArray | null;
       // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec accumulation loop
-      while ((m = ACK_MARKER.exec(body)) !== null) acked.add(m[1].trim());
+      while ((m = ACK_MARKER.exec(body)) !== null) {
+        const nw = NEW_ACK.exec(m[1].trim());
+        if (nw) acked.add(advisoryStableKey(nw[1], nw[2]));
+      }
     }
   }
   return [...acked];

package/app/repoEnvelope.ts

@@ -211,13 +211,26 @@ export function repoEnvelopeVars(
  * `ref`): a cross-repo graph node carries only its `owner/repo` (an issue ref names no branch), so when
  * neither the node nor the run declares a base the cell must still provision an isolated clone — of the
  * repository's DEFAULT branch. The harness `provisionRepo` omits `--branch` when `ref` is blank, so a
- * `ref`-less envelope clones the default branch (each agent then cuts its own `feat/<node.id>` branch
- * inside the isolated clone, unchanged). Returns `{}` for a `repo` that is not a plain `owner/repo` (an
- * unresolved cell — the runner's invariant rejects the run before this degrades to a launch-dir share).
- * Blobless single-branch shaping + `cloneTimeoutMs` (issues #287/#694) are emitted on every cell. */
-export function agentNodeRepoEnvelope(repo: string, base: string | null): Record<string, unknown> {
+ * `ref`-less envelope clones the default branch. Returns `{}` for a `repo` that is not a plain
+ * `owner/repo` (an unresolved cell — the runner's invariant rejects the run before this degrades to a
+ * launch-dir share). Blobless single-branch shaping + `cloneTimeoutMs` (issues #287/#694) are emitted on
+ * every cell.
+ *
+ * Deterministic isolation branch (issue #776): `branchCreate` (the per-node `feat/<node.id>`) is emitted
+ * as `branch.create` so the harness cuts the isolation branch ITSELF — mirroring the single-feature path
+ * (`repoEnvelopeVars`/`feature.ts`) — instead of delegating branch-cutting to agent prompt discipline. A
+ * forgetful agent that never branched used to commit on the checked-out BASE branch; its `git push
+ * origin <base>` was then rejected non-fast-forward and the whole run's work was stranded (merlin job
+ * 20974; harness counterpart jwulf/c8ctl-plugin-nano#231). Emitting `branch.create` makes it impossible
+ * for a cell to leave its agent committing on the base. Emitted independently of `ref`: when the base is
+ * unknown the harness cuts the branch off the cloned default tip; when known, off `ref`. Omitted for a
+ * blank `branchCreate` (falls back to the pre-#776 agent-cuts-its-own-branch behaviour). Delivery-graph
+ * agent cells are single-instance, so a static per-node `feat/<node.id>` never collides across siblings
+ * (the MI-child collision the issue flags does not arise in the current single-instance cells). */
+export function agentNodeRepoEnvelope(repo: string, base: string | null, branchCreate: string | null = null): Record<string, unknown> {
   if (!isPlainOwnerRepo(repo)) return {};
   const ref = typeof base === "string" && base.trim() !== "" ? base.trim() : null;
+  const create = typeof branchCreate === "string" && branchCreate.trim() !== "" ? branchCreate.trim() : null;
   return {
     [AGENT_TASK_NS]: {
       repository: {
@@ -226,9 +239,12 @@ export function agentNodeRepoEnvelope(repo: string, base: string | null): Record
         singleBranch: true,
         filter: "blob:none",
         cloneTimeoutMs: cloneTimeoutMs(),
-        // A per-node base (declared, or defaulted from the run level) — the branch the agent cuts its
+        // A per-node base (declared, or defaulted from the run level) — the branch the harness cuts its
         // `feat/<node.id>` off. Omitted when unknown so the harness clones the repo's default branch.
         ...(ref ? { ref, baseRef: ref } : {}),
+        // The deterministic isolation branch the harness cuts (issue #776), so the agent can never be
+        // left committing on the checked-out base branch. Off `ref` when known, else off the default tip.
+        ...(create ? { branch: { create } } : {}),
       },
       // Repo-provisioning auth gate (issue #770): as in `repoEnvelopeVars`, a repo-backed cell must
       // opt the harness into git-credential resolution (`task.allowPr`) or the clone fails with

package/openapi.yaml

@@ -2112,8 +2112,9 @@ components:
                   pattern: '^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$'
                   description: >-
                     OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the
-                    harness checks out in the isolated clone (the pre-PR shape: the agent cuts its own
-                    `feat/<node.id>` branch off this base). Absent → the run-level dispatch `baseBranch`
+                    harness checks out in the isolated clone (the pre-PR shape: the harness cuts the
+                    deterministic `feat/<node.id>` branch off this base itself, per #776, so a forgetful
+                    agent can never be left committing on the base branch). Absent → the run-level dispatch `baseBranch`
                     (else the node's repository default branch). A value that is not a plausible git
                     branch name is rejected at submit; the pattern mirrors the authoritative server-side
                     gate (`isPlausibleBranchName`, app/baseBranch.ts).
@@ -5005,7 +5006,7 @@ paths:
                                 type: string
                                 maxLength: 255
                                 pattern: ^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$
-                                description: "OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the harness checks out in the isolated clone (the pre-PR shape: the agent cuts its own `feat/<node.id>` branch off this base). Absent → the run-level dispatch `baseBranch` (else the node's repository default branch). A value that is not a plausible git branch name is rejected at submit; the pattern mirrors the authoritative server-side gate (`isPlausibleBranchName`, app/baseBranch.ts)."
+                                description: "OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the harness checks out in the isolated clone (the pre-PR shape: the harness cuts the deterministic `feat/<node.id>` branch off this base itself, per #776, so a forgetful agent can never be left committing on the base branch). Absent → the run-level dispatch `baseBranch` (else the node's repository default branch). A value that is not a plausible git branch name is rejected at submit; the pattern mirrors the authoritative server-side gate (`isPlausibleBranchName`, app/baseBranch.ts)."
                               converge:
                                 type: boolean
                                 description: 'OPTIONAL first-class CONVERGE policy (ADR 0006 §3 / S5) — a DECLARED, compiler- validated completion-policy flag on this cell node. It declares that the node''s opened PR is to be driven through the review-convergence loop to green as an edge-gated completion policy; this slice adds and validates the flag, with the delivery-graph execution wiring that consumes it landing in a follow-up slice. It supersedes (in intent) the emergent `feature.bpmn` `gw-converge` gateway and the "un-draft + merge #B" prompt prose a delivery-graph `agent` node used to smuggle. Converge and merge are SEPARABLE phases; a node may converge without merging (stop at green and gate the landing behind a downstream node).'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.187.0",
+  "version": "0.187.2",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/prompts/review-round.md

@@ -119,19 +119,43 @@ Because several agents may run on the same host at once:
    carries a **resolved** acknowledgement, so a decision you only wrote into your
    `summary` is invisible to the gate. For each suppressed advisory you applied or
    declined (step 2), post a **new review comment thread** whose body contains the
-   verbatim marker **`nano-ack: <path>:<line>`** — copied exactly from Copilot's
-   bold `**<path>:<line>**` header for that advisory — then **resolve** that thread.
-   The gate matches on the marker **text**, so the thread may sit on any valid diff
-   line; only the exact `path:line` string must match. Example:
+   verbatim marker **`nano-ack: <path> :: <advisory text>`** — the `<path>` from
+   Copilot's bold `**<path>:<line>**` header and `<advisory text>` copied
+   **verbatim** from the first line of that advisory's prose — then **resolve** that
+   thread. The gate keys the acknowledgement on the advisory **text** (a
+   line-independent fingerprint of `<path> + <advisory text>`), *not* on the line
+   number: this is deliberate. A **declined** advisory is re-emitted every round,
+   and any unrelated edit you make shifts its line, so Copilot re-anchors it to a
+   new line — a line-based ack would go stale and the gate would escalate to a human
+   every round (issue #787). Because the ack is keyed on the prose, a decline you
+   made in an earlier round stays acknowledged across the drift and you need **not**
+   re-ack it. The ack thread may sit on any valid diff line. Example:
 
    ```sh
    # Post the ack thread (pick any changed line in the diff for path/line). Use the PR's real HEAD
    # SHA as commit_id — `git rev-parse HEAD` can drift from the PR head; ask GitHub:
    CID=$(gh api repos/OWNER/REPO/pulls/PR --jq .head.sha)
-   gh api repos/OWNER/REPO/pulls/PR/comments -f commit_id="$CID" -f path=PATH -F line=LINE -f side=RIGHT \
-     -f body='Applied. nano-ack: <path>:<line>'   # or: 'Declined, false positive — <reason>. nano-ack: <path>:<line>'
+   # Build the body via a QUOTED heredoc so the verbatim advisory prose is never re-interpreted by
+   # the shell — a single-quoted `-f body='...'` breaks the moment the prose contains a `'` (e.g.
+   # "doesn't handle ..."), and a double-quoted one breaks on `$`/backticks. `<<'EOF'` (quoted
+   # delimiter) disables ALL expansion, so any advisory text is safe:
+   BODY=$(cat <<'EOF'
+   Applied. nano-ack: <path> :: <verbatim advisory text>
+   EOF
+   )   # to DECLINE instead, build the body the same quoted-heredoc way (never a single-quoted
+       # `-f body='...'`, which breaks the moment the reason or advisory prose contains a `'`):
+       #   BODY=$(cat <<'EOF'
+       #   Declined, false positive — <reason>. nano-ack: <path> :: <verbatim advisory text>
+       #   EOF
+       #   )
+   gh api repos/OWNER/REPO/pulls/PR/comments -f commit_id="$CID" -f path="PATH" -F line=LINE -f side=RIGHT -f body="$BODY"
    # Then resolve it exactly like any other thread (map its databaseId -> thread node id -> resolveReviewThread).
    ```
+   Only the `nano-ack: <path> :: <text>` (prose-keyed) form is honoured. A bare
+   `nano-ack: <path>:<line>` marker is **not** an acknowledgement: keyed only on
+   `path:line`, it is blind to the advisory's prose, so it would let a resolved ack
+   for one advisory silently acknowledge a genuinely new advisory re-emitted at that
+   same line. Always use the `<path> :: <text>` form.
 6. **Do NOT request, re-request, or remove the reviewer yourself.** Keeping
    Copilot attached is the **process's** job: a deterministic poller ensures a
    Copilot review is requested (idempotently) whenever this PR is waiting, and it

package/workers/converge-gate/worker.ts

@@ -8,7 +8,11 @@
 // comments:
 //   • any review THREAD is still unresolved (GraphQL `isResolved = false`), or
 //   • any SUPPRESSED advisory in the latest Copilot review body lacks a matching RESOLVED ack
-//     thread (a `nano-ack: <path>:<line>` marker copied from Copilot's `**path:line**` header).
+//     thread (a `nano-ack: <path> :: <verbatim advisory text>` marker whose line-stable prose
+//     fingerprint matches Copilot's advisory). The bare legacy `nano-ack: <path>:<line>` form is
+//     NOT honoured: keyed only on `path:line`, it is blind to the advisory prose and would let a
+//     resolved ack for one advisory silently acknowledge a genuinely new advisory re-emitted at
+//     that same line (a false-OPEN). Only the prose-keyed `<path> :: <text>` form acknowledges.
 // A blocked gate returns `convergeBlocked = true`; the model's `gw-converge-gate` gateway routes to
 // the human `wait-answer` escalation (recoverable), never a hard wedge.
 //
@@ -87,9 +91,10 @@ export function makeHandler(deps: {
         return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
       }
       const unresolvedThreadCount = threads.filter((t) => !t.isResolved).length;
+      const advisories = parseSuppressedAdvisories(reviewBody);
       result = evaluateConvergeGate({
         unresolvedThreadCount,
-        suppressedKeys: parseSuppressedAdvisories(reviewBody),
+        suppressedAdvisories: advisories.map((a) => ({ key: a.key, label: a.label })),
         acknowledgedKeys: parseAckedAdvisories(threads),
       });
     } catch {