@nanobpm/nano-workforce 0.186.4 → 0.187.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.186.4",
+  "version": "0.187.0",
   "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",