@nanobpm/nano-workforce 0.186.4 → 0.187.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **agentic:** autoSubscribe opt-out marker + single agentDefinition-external convention ([#782](https://github.com/nanobpm/nano-workforce/issues/782)) ([6a0c616](https://github.com/nanobpm/nano-workforce/commit/6a0c616158db7e83ab2479d66677dd652c12f886)), closes [jwulf/c8ctl-plugin-nano#235](https://github.com/jwulf/c8ctl-plugin-nano/issues/235) [#779](https://github.com/nanobpm/nano-workforce/issues/779) [#745](https://github.com/nanobpm/nano-workforce/issues/745)
+
 ## [0.186.4](https://github.com/nanobpm/nano-workforce/compare/v0.186.3...v0.186.4) (2026-09-12)
 
 ### Bug Fixes

package/SPEC.md

@@ -357,6 +357,41 @@ the app, which deploys on boot), and the next agent job of that type picks it up
 > (`$AGENT_RESULT_FILE` / `::nano:result::`), and no task may still carry the retired
 > baked `io.nanobpm.agentTask.task.prompt` header.
 
+> **`<zeebe:agentDefinition agentType="external" />` is the ONE agentic-task signal.**
+> Every hand-authored `senior:*` agent service task in `resources/processes` carries this
+> engine-native AgentTask marker
+> (issue #745) alongside its `<zeebe:taskDefinition>`, and it is the **single
+> convention** the worker harness `--auto` reconciliation scans to discover agentic
+> tasks — replacing the legacy `linkName="prompt"` / header dual signal so the app and
+> harness converge on one signal (issue #779, harness jwulf/c8ctl-plugin-nano#235). The
+> marker is CI-enforced over the deployed `resources/` process models
+> (`agentTaskTypesMissingExternalMarker`,
+> `agent-marker.test.ts`), so no prompt-bearing agent task in those models relies on
+> prompt-link-only discovery. (The delivery-graph compiler's GENERATED agent BPMN —
+> deployed at run time by `runDeliveryGraph`, not authored under `resources/` — is a
+> separate deployed path NOT covered by this static guard; whether its generated cells
+> should also carry the marker/opt-out convention is tracked separately under issue #745,
+> not #779.) To **exclude** a task from `--auto` — one that must be served only by a
+> worker that explicitly subscribes (`--job-type <type>` / a profile capability) — add
+> the inert opt-out property inside its `extensionElements`, nested in the
+> `<zeebe:properties>` wrapper the models and engine expect (as
+> `resources/processes/feature.bpmn:57-63` does — a bare `<zeebe:property>` placed
+> directly under `<bpmn:extensionElements>` is NOT the accepted shape):
+>
+> ```xml
+> <bpmn:extensionElements>
+>   <zeebe:properties>
+>     <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+>   </zeebe:properties>
+> </bpmn:extensionElements>
+> ```
+>
+> Absence (or any value other than `"false"`) auto-subscribes as normal — opt-out is
+> explicit and fail-safe. The property is inert to the engine (no migration, no
+> behaviour change). It is a registered contract (`agentTask.autoSubscribe` in
+> `app/contracts.ts`), read by the ONE helper `agentTaskTypesOptedOutOfAuto`
+> (`app/agentic/vocab/job-types.ts`) and guarded by `auto-subscribe.test.ts`.
+
 Per-instance dynamic context still rides **`appendPrompt`** (unchanged): an ioMapping
 sets a job-local `appendPrompt` string (a plan's rejection findings, a feature task's
 brief, the failing-check list) which the agent harness concatenates **verbatim** onto

package/app/agentic/vocab/auto-subscribe.test.ts

@@ -0,0 +1,261 @@
+// Tests for the `--auto` opt-OUT marker (issue #779, harness jwulf/c8ctl-plugin-nano#235). The single
+// agentic-task signal the harness `--auto` reconciliation scans is `<zeebe:agentDefinition
+// agentType="external" />`; this marker — `<zeebe:property name="io.nanobpm.agentTask.autoSubscribe"
+// value="false" />` inside an agent task's extensionElements — is the explicit escape hatch that
+// EXCLUDES a task from `--auto` so it is served only by a worker that explicitly subscribes. Mirrors
+// agent-marker.test.ts: assert the marker's shape/placement, and guard that any opted-out task in the
+// deployed models is itself a real (externally-marked) agent task, so the opt-out can't drift onto a
+// non-agent element.
+import { readFileSync, readdirSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import {
+  agentTaskTypesMissingExternalMarker,
+  agentTaskTypesOptedOutMissingExternalMarker,
+  agentTaskTypesOptedOutOfAuto,
+  MALFORMED_OPTOUT_LABEL,
+} from "./job-types.ts";
+
+const RESOURCES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources");
+
+// urban deploys `resources/` recursively (every file at ANY depth), so an opted-out task in a `.bpmn`
+// added under any resources subdirectory — not just `resources/processes` — would still deploy. Root
+// the walk at the `resources/` convention root (mirroring the deploy contract) so a deployed BPMN
+// placed elsewhere under `resources/` cannot bypass this guard.
+function bpmnFiles(): string[] {
+  const walk = (dir: string): string[] =>
+    readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) return walk(full);
+      return entry.name.endsWith(".bpmn") ? [relative(RESOURCES_DIR, full)] : [];
+    });
+  return walk(RESOURCES_DIR).sort();
+}
+
+test("agentTaskTypesOptedOutOfAuto flags a task carrying the value=\"false\" opt-out property", () => {
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutOfAuto(xml), ["senior:special"]);
+});
+
+test("agentTaskTypesOptedOutOfAuto tolerates reversed attribute order (name/value swapped)", () => {
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:properties>
+          <zeebe:property value="false" name="io.nanobpm.agentTask.autoSubscribe" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutOfAuto(xml), ["senior:special"]);
+});
+
+test("agentTaskTypesOptedOutOfAuto ignores a task without the marker and one with a non-false value", () => {
+  const xml = `
+    <bpmn:serviceTask id="plain">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="explicitTrue">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:retro" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="true" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutOfAuto(xml), []);
+});
+
+test("agentTaskTypesOptedOutOfAuto ignores an unrelated property named the same-ish", () => {
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribeMode" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutOfAuto(xml), []);
+});
+
+test("agentTaskTypesOptedOutOfAuto ignores a bare opt-out property OUTSIDE the <zeebe:properties> wrapper (placement contract)", () => {
+  // The property carries the exact name/value, but it sits directly under <bpmn:extensionElements>
+  // rather than inside the <zeebe:properties> wrapper the engine honours — so the engine ignores it
+  // and it is NOT an active opt-out. Both the reader and the drift guard must treat it as absent.
+  const xml = `
+    <bpmn:serviceTask id="bare">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutOfAuto(xml), []);
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), []);
+});
+
+test("agentTaskTypesMissingExternalMarker flags a prompt-bearing task whose external marker sits OUTSIDE extensionElements (placement contract)", () => {
+  // The task is a real prompt-bearing agent task, but its <zeebe:agentDefinition> marker is a sibling
+  // of <serviceTask> rather than inside extensionElements, so the engine/harness ignores it — the
+  // task is effectively unmarked. A whole-block scan would see the marker "somewhere" and wrongly
+  // pass; the placement-scoped scan flags the drift.
+  const xml = `
+    <bpmn:serviceTask id="misplaced">
+      <zeebe:agentDefinition agentType="external" />
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:linkedResource resourceId="prompts/x.md" linkName="prompt" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesMissingExternalMarker(xml), ["senior:special"]);
+});
+
+test("agentTaskTypesOptedOutMissingExternalMarker flags an opt-out on a block lacking the external marker", () => {
+  // A host task (no external marker, no prompt link) that carries the opt-out is authoring drift:
+  // the block-level check catches it even though `agentTaskTypesMissingExternalMarker` (prompt-only)
+  // never reports it.
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesMissingExternalMarker(xml), []);
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), ["pr.finalize"]);
+});
+
+test("agentTaskTypesOptedOutMissingExternalMarker passes an opt-out on an externally-marked agent task", () => {
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), []);
+});
+
+test("agentTaskTypesOptedOutMissingExternalMarker checks each block independently (a marked sibling does not cover a drifted opt-out)", () => {
+  // Two tasks share the `senior:special` type: one is a proper externally-marked agent task, the
+  // other opts out but lacks the marker. A deduplicated cross-task comparison would miss this; the
+  // per-block check flags the unmarked one.
+  const xml = `
+    <bpmn:serviceTask id="marked">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="drifted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), ["senior:special"]);
+});
+
+test("agentTaskTypesOptedOutMissingExternalMarker flags an opt-out whose external marker sits OUTSIDE extensionElements (placement contract)", () => {
+  // The opt-out is correctly placed inside extensionElements, but the external marker is out of place
+  // (a sibling of <serviceTask>, not inside extensionElements) so the engine ignores it — the block
+  // is therefore NOT a real marked agent task. A whole-block scan would see the marker "somewhere" and
+  // wrongly pass; the placement-scoped scan flags the drift.
+  const xml = `
+    <bpmn:serviceTask id="misplaced">
+      <zeebe:agentDefinition agentType="external" />
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:special" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), ["senior:special"]);
+});
+
+test("agentTaskTypesOptedOutMissingExternalMarker surfaces an opt-out on a block with a missing/empty taskDefinition type", () => {
+  // An opt-out on an unmarked block whose <zeebe:taskDefinition> type is empty cannot be a real agent
+  // task, so it is still drift — surfaced under the sentinel rather than silently skipped.
+  const xml = `
+    <bpmn:serviceTask id="typeless">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), [MALFORMED_OPTOUT_LABEL]);
+});
+
+test("agentTaskTypesOptedOutMissingExternalMarker surfaces a MARKED opt-out block with a missing/empty taskDefinition type", () => {
+  // The block carries BOTH the external marker AND the opt-out, but its <zeebe:taskDefinition> type
+  // is empty — so it still cannot be a real agent task. The malformed check must run BEFORE the
+  // external-marker short-circuit, or the marker would wrongly let this typeless opt-out pass.
+  const xml = `
+    <bpmn:serviceTask id="markedTypeless">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesOptedOutMissingExternalMarker(xml), [MALFORMED_OPTOUT_LABEL]);
+});
+
+test("GUARD: the deploy-scan walks from the resources/ convention root (not just resources/processes)", () => {
+  // Regression for the deploy-by-convention coverage gap: urban deploys `resources/` recursively, so
+  // the guard must root its BPMN walk at `resources/` — a `.bpmn` added under any other resources
+  // subdirectory must still be scanned. Assert the walk actually reaches the process models AND that
+  // every returned path is relative to the resources root (carries its subdirectory segment), so a
+  // future refactor that narrows the root back to `resources/processes` is caught here.
+  const files = bpmnFiles();
+  assert(files.length > 0, "expected the resources/ walk to discover deployed BPMN models");
+  assert(
+    files.some((f) => f.startsWith("processes/")),
+    `expected resources-root-relative paths (e.g. "processes/…"); got ${JSON.stringify(files.slice(0, 3))}`,
+  );
+});
+
+test("GUARD: every deployed opted-out task is itself an externally-marked agent task", () => {
+  for (const file of bpmnFiles()) {
+    const xml = readFileSync(join(RESOURCES_DIR, file), "utf8");
+    // Drive the guard DIRECTLY from the block-level, placement-scoped helper rather than gating on
+    // `agentTaskTypesOptedOutOfAuto` (which skips missing/empty task-definition types, so a typeless
+    // opt-out would never reach the check). The helper scans every service task itself, surfaces a
+    // malformed typeless opt-out under the sentinel, and checks the external marker on the SAME
+    // block's extensionElements — so a typeless opt-out, an out-of-place property, or a marker that
+    // drifted onto a non-agent element all fail CI here.
+    const drifted = agentTaskTypesOptedOutMissingExternalMarker(xml);
+    assertEquals(
+      drifted,
+      [],
+      `${file}: task(s) ${JSON.stringify(drifted)} opt out of --auto but lack <zeebe:agentDefinition agentType="external" /> on the same block — an opt-out belongs only on a real agent task`,
+    );
+  }
+});

package/app/agentic/vocab/job-types.ts

@@ -48,11 +48,53 @@ export function jobTypeToRoutingToken(jobType: string): string | undefined {
 
 const SERVICE_TASK = /<(?:\w+:)?serviceTask\b[\s\S]*?<\/(?:\w+:)?serviceTask>/g;
 const TASK_DEFINITION_TYPE = /<(?:\w+:)?taskDefinition\b[^>]*\btype="([^"]*)"/;
+const EXTENSION_ELEMENTS = /<(?:\w+:)?extensionElements\b[\s\S]*?<\/(?:\w+:)?extensionElements>/;
+// The engine only honours a `<zeebe:property>` nested inside a `<zeebe:properties>` wrapper (itself
+// inside `<bpmn:extensionElements>`). A bare `<zeebe:property>` placed directly under
+// `extensionElements` (or `serviceTask`) is ignored, so property-contract scans (the `--auto`
+// opt-out) run against THIS wrapper — a misplaced bare property is treated as absent, exactly as the
+// engine treats it.
+const ZEEBE_PROPERTIES = /<(?:\w+:)?properties\b[\s\S]*?<\/(?:\w+:)?properties>/;
 const PROMPT_LINK = /<(?:\w+:)?linkedResource\b[^>]*\blinkName="prompt"/;
 // The engine-native AgentTask marker (issue #745): a `<zeebe:agentDefinition agentType="external" />`
 // sibling of the `<zeebe:taskDefinition>` inside a `senior:*` agent task's extensionElements. It is
 // what makes the element eligible for engine-native AgentInstance minting by the worker harness.
 const EXTERNAL_AGENT_MARKER = /<(?:\w+:)?agentDefinition\b[^>]*\bagentType="external"/;
+// The `--auto` opt-OUT marker (issue #779): a `<zeebe:property name="io.nanobpm.agentTask.
+// autoSubscribe" value="false" />` sibling inside an agent task's extensionElements. It declares the
+// task is EXCLUDED from the harness `--auto` reconciliation (which keys on EXTERNAL_AGENT_MARKER) and
+// is served only by a worker that explicitly subscribes. The property is inert to the engine. Only
+// the exact `value="false"` opts out — any other value auto-subscribes as normal (fail-safe).
+const AUTO_SUBSCRIBE_OPTOUT =
+  /<(?:\w+:)?property\b[^>]*\bname="io\.nanobpm\.agentTask\.autoSubscribe"[^>]*\bvalue="false"|<(?:\w+:)?property\b[^>]*\bvalue="false"[^>]*\bname="io\.nanobpm\.agentTask\.autoSubscribe"/;
+
+// The label surfaced for an opted-out, unmarked service task whose `<zeebe:taskDefinition>` is
+// missing or has an empty `type` (issue #779 drift guard). Such a block cannot be a real
+// externally-marked agent task, so the opt-out is drift regardless of the absent type — we surface it
+// under a descriptive sentinel rather than letting the dedupe skip swallow it.
+export const MALFORMED_OPTOUT_LABEL = "(opted-out task with missing/empty taskDefinition type)";
+
+/**
+ * The `<bpmn:extensionElements>…</bpmn:extensionElements>` content of a service-task block, or the
+ * empty string when the block has none. Placement-contract scans (issue #745/#779: a marker is only
+ * honoured by the engine INSIDE `extensionElements`) run against THIS scope, so a property/marker
+ * sitting outside `extensionElements` is treated as absent — the engine ignores it, and so must the
+ * guard (an out-of-place external marker cannot "cover" an opt-out).
+ */
+function extensionElementsOf(block: string): string {
+  return block.match(EXTENSION_ELEMENTS)?.[0] ?? "";
+}
+
+/**
+ * The `<zeebe:properties>…</zeebe:properties>` content nested inside a block's `extensionElements`,
+ * or the empty string when absent. The engine only honours `<zeebe:property>` entries INSIDE this
+ * wrapper, so the `--auto` opt-out property scan runs against THIS scope — a bare `<zeebe:property>`
+ * sitting directly under `extensionElements` (or `serviceTask`) is treated as absent, exactly as the
+ * engine treats it, matching the registered/documented shape (`<zeebe:properties>`-nested).
+ */
+function optOutPropertiesOf(block: string): string {
+  return extensionElementsOf(block).match(ZEEBE_PROPERTIES)?.[0] ?? "";
+}
 
 /**
  * Scan one BPMN document for the job types of its PROMPT-BEARING service tasks — the deployed fleet
@@ -78,15 +120,18 @@ export function promptBearingTaskTypes(xml: string): string[] {
  * engine-native AgentTask marker `<zeebe:agentDefinition agentType="external" />` (issue #745). Every
  * deployed `senior:*` agent task must carry the marker so the worker harness mints an AgentInstance
  * for it; a newly-added agent task that forgets it is a silent drift surface (its run never persists
- * durable AgentHistory), so the regression guard fails CI. Returns the offending task types in
- * first-occurrence order (empty when every agent task is marked).
+ * durable AgentHistory), so the regression guard fails CI. The marker check is scoped to the block's
+ * `<bpmn:extensionElements>` (the engine-honoured PLACEMENT scope, via `extensionElementsOf`) — a
+ * marker sitting outside `extensionElements` is ignored by the engine, so it must not "cover" a task
+ * here either. Returns the offending task types in first-occurrence order (empty when every agent
+ * task is marked).
  */
 export function agentTaskTypesMissingExternalMarker(xml: string): string[] {
   const seen = new Set<string>();
   const missing: string[] = [];
   for (const [block] of xml.matchAll(SERVICE_TASK)) {
     if (!PROMPT_LINK.test(block)) continue;
-    if (EXTERNAL_AGENT_MARKER.test(block)) continue;
+    if (EXTERNAL_AGENT_MARKER.test(extensionElementsOf(block))) continue;
     const type = block.match(TASK_DEFINITION_TYPE)?.[1];
     if (type === undefined || type.length === 0 || seen.has(type)) continue;
     seen.add(type);
@@ -94,3 +139,78 @@ export function agentTaskTypesMissingExternalMarker(xml: string): string[] {
   }
   return missing;
 }
+
+/**
+ * Scan one BPMN document for the job types of agent service tasks that OPT OUT of the harness
+ * `--auto` reconciliation (issue #779) — those carrying `<zeebe:property
+ * name="io.nanobpm.agentTask.autoSubscribe" value="false" />` inside their extensionElements. An
+ * opted-out task is served ONLY by a worker that explicitly subscribes (`--job-type <type>` / a
+ * profile capability), never by `--auto` auto-discovery (which keys on the
+ * `<zeebe:agentDefinition agentType="external" />` marker). The property is inert to the engine;
+ * only the exact `value="false"` opts out (any other value auto-subscribes, fail-safe). The opt-out
+ * scan is scoped to the block's `<zeebe:properties>` wrapper inside `<bpmn:extensionElements>` (the
+ * engine-honoured PLACEMENT scope, via `optOutPropertiesOf`) — a bare `<zeebe:property>` sitting
+ * directly under `<bpmn:extensionElements>` or `<bpmn:serviceTask>` is ignored by the engine, so it
+ * must not be reported as an active opt-out here (this keeps the reader consistent with the
+ * placement-scoped drift guard `agentTaskTypesOptedOutMissingExternalMarker`). Returns the
+ * distinct opted-out task types in first-occurrence order (empty when no task opts out).
+ */
+export function agentTaskTypesOptedOutOfAuto(xml: string): string[] {
+  const seen = new Set<string>();
+  const optedOut: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    if (!AUTO_SUBSCRIBE_OPTOUT.test(optOutPropertiesOf(block))) continue;
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    if (type === undefined || type.length === 0 || seen.has(type)) continue;
+    seen.add(type);
+    optedOut.push(type);
+  }
+  return optedOut;
+}
+
+/**
+ * Scan one BPMN document for the job types of service tasks that OPT OUT of `--auto` (issue #779) yet
+ * are NOT themselves externally-marked agent tasks — i.e. an opt-out property on a block WITHOUT a
+ * sibling `<zeebe:agentDefinition agentType="external" />`. An opt-out only makes sense on a real
+ * agent task (one that WOULD otherwise be auto-discovered via its external marker); a marker that has
+ * drifted onto a host task (e.g. `pr.finalize`, which carries no external marker) or onto one task
+ * that merely shares a `taskDefinition` type with a properly-marked sibling is authoring drift. This
+ * checks both markers on the SAME service-task block — the opt-out property inside the block's
+ * `<zeebe:properties>` wrapper (via `optOutPropertiesOf`, so a bare misplaced `<zeebe:property>` is
+ * ignored just as the engine ignores it) and the external marker inside that block's
+ * `<bpmn:extensionElements>` (the engine-honoured PLACEMENT scope), so an out-of-place external
+ * marker sitting outside `extensionElements` cannot spuriously "cover" the opt-out — so, unlike
+ * comparing the deduplicated `agentTaskTypesOptedOutOfAuto` / `agentTaskTypesMissingExternalMarker`
+ * lists (the latter only reports PROMPT-BEARING tasks, so a non-prompt host task's opt-out is
+ * invisible to it), the drift cannot hide. An opt-out on a block with a missing/empty
+ * `<zeebe:taskDefinition>` type (which likewise cannot be a real agent task) is surfaced under a
+ * descriptive sentinel BEFORE the external-marker short-circuit — so even a typeless block that
+ * carries the external marker is still flagged as malformed drift. Returns the offending task types
+ * in first-occurrence order (empty when every opted-out task is a properly-typed, externally-marked
+ * agent task).
+ */
+export function agentTaskTypesOptedOutMissingExternalMarker(xml: string): string[] {
+  const seen = new Set<string>();
+  const offending: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    const ext = extensionElementsOf(block);
+    if (!AUTO_SUBSCRIBE_OPTOUT.test(optOutPropertiesOf(block))) continue;
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    // A missing/empty type cannot be a real agent task, so an opt-out here is malformed drift
+    // REGARDLESS of any external marker — surface it under the sentinel BEFORE the marker
+    // short-circuit, so a marked-yet-typeless opt-out is caught rather than passed by the marker.
+    if (type === undefined || type.length === 0) {
+      if (seen.has(MALFORMED_OPTOUT_LABEL)) continue;
+      seen.add(MALFORMED_OPTOUT_LABEL);
+      offending.push(MALFORMED_OPTOUT_LABEL);
+      continue;
+    }
+    // A properly-typed opt-out is fine only when the SAME block is externally marked inside its
+    // extensionElements (the engine-honoured placement scope).
+    if (EXTERNAL_AGENT_MARKER.test(ext)) continue;
+    if (seen.has(type)) continue;
+    seen.add(type);
+    offending.push(type);
+  }
+  return offending;
+}

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 } }',
   },
@@ -494,6 +494,14 @@ export const WIRE_CONTRACTS = {
       "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
     shape: '<zeebe:agentDefinition agentType="external" /> (sibling of <zeebe:taskDefinition> in a senior:* service task\'s extensionElements)',
   },
+  "agentTask.autoSubscribe": {
+    category: "wire",
+    name: "agentTask.autoSubscribe",
+    owner: "resources/processes/*.bpmn",
+    semantics:
+      "The `--auto` opt-OUT marker (issue #779, harness jwulf/c8ctl-plugin-nano#235). The ONE agentic-task signal the harness `--auto` reconciliation scans is `<zeebe:agentDefinition agentType=\"external\" />` (the `agentTask.agentDefinition` marker) — it replaces the legacy `linkName=\"prompt\"` / header dual signal so both sides converge on a single convention. This marker is the escape hatch: a `<zeebe:property name=\"io.nanobpm.agentTask.autoSubscribe\" value=\"false\" />` INSIDE an agent task's `<bpmn:extensionElements>` declares the task is EXCLUDED from `--auto` auto-discovery and is served ONLY by a worker that explicitly subscribes (`--job-type <type>` / a profile capability). Absence of the marker (or any value other than the literal string `\"false\"`) means the task auto-subscribes as normal — opt-out is explicit and fail-safe. The `zeebe:property` is INERT to the engine (no runtime/behaviour change, no migration). Authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. The scan helper `agentTaskTypesOptedOutOfAuto(xml)` in app/agentic/vocab/job-types.ts is the ONE reader of this marker (mirrors `agentTaskTypesMissingExternalMarker`); a CI guard asserts its shape/placement. Use THIS one marker to opt a task out — never a second/synonym opt-out property.",
+    shape: '<zeebe:properties><zeebe:property name="io.nanobpm.agentTask.autoSubscribe" value="false" /></zeebe:properties> (the <zeebe:property> nested in a <zeebe:properties> wrapper inside a senior:* agent service task\'s <bpmn:extensionElements> — a bare <zeebe:property> directly under extensionElements is NOT the accepted shape; see SPEC.md)',
+  },
   "agentTask.historyRead": {
     category: "wire",
     name: "agentTask.historyRead",

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/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.186.4",
+  "version": "0.187.1",
   "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",