@nanobpm/nano-workforce 0.182.3 → 0.183.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.183.0](https://github.com/nanobpm/nano-workforce/compare/v0.182.3...v0.183.0) (2026-09-07)
+
+### Features
+
+* **agent:** mark senior:* tasks as engine-native external AgentTasks ([#748](https://github.com/nanobpm/nano-workforce/issues/748)) ([806eea5](https://github.com/nanobpm/nano-workforce/commit/806eea522490a999747ad4814fc92847dab3a6e4)), closes [#464](https://github.com/nanobpm/nano-workforce/issues/464) [#745](https://github.com/nanobpm/nano-workforce/issues/745) [#746](https://github.com/nanobpm/nano-workforce/issues/746) [#747](https://github.com/nanobpm/nano-workforce/issues/747) [Magikcraft/nano-bpm#1137](https://github.com/Magikcraft/nano-bpm/issues/1137)
+
 ## [0.182.3](https://github.com/nanobpm/nano-workforce/compare/v0.182.2...v0.182.3) (2026-09-06)
 
 ### Bug Fixes

package/app/agentic/vocab/agent-marker.test.ts

@@ -0,0 +1,74 @@
+// Tests for the engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity),
+// including the defect-class regression guard: every deployed prompt-bearing `senior:*` agent task
+// must carry `<zeebe:agentDefinition agentType="external" />` alongside its `<zeebe:taskDefinition>`,
+// so the worker harness mints an engine-native AgentInstance for it. A newly-added agent task that
+// forgets the marker never persists durable AgentHistory — so it fails CI here instead of silently
+// drifting.
+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, promptBearingTaskTypes } from "./job-types.ts";
+
+const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
+
+// urban deploys `resources/` recursively (every file at any depth), so a process
+// model added under a subdirectory would still deploy — walk recursively here too,
+// or the guard would miss it and let an unmarked agent task slip through.
+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(PROCESSES_DIR, full)] : [];
+    });
+  return walk(PROCESSES_DIR).sort();
+}
+
+test("agentTaskTypesMissingExternalMarker flags a prompt-bearing agent task with no external marker", () => {
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="feature.md" resourceType="GenericScript" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesMissingExternalMarker(xml), ["senior:feature"]);
+});
+
+test("agentTaskTypesMissingExternalMarker passes a marked agent task and ignores a plain host task", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="feature.md" resourceType="GenericScript" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesMissingExternalMarker(xml), []);
+});
+
+test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent task carries the external AgentTask marker", () => {
+  let anyAgentTasks = false;
+  for (const file of bpmnFiles()) {
+    const xml = readFileSync(join(PROCESSES_DIR, file), "utf8");
+    if (promptBearingTaskTypes(xml).length > 0) anyAgentTasks = true;
+    const missing = agentTaskTypesMissingExternalMarker(xml);
+    assert(
+      missing.length === 0,
+      `${file}: agent task(s) missing <zeebe:agentDefinition agentType="external" /> — ${missing.join(", ")}`,
+    );
+  }
+  // Sanity: the models really do declare agent tasks (guard is not vacuously green).
+  assert(anyAgentTasks, "the deployed models declare prompt-bearing agent tasks");
+});

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

@@ -49,6 +49,10 @@ 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 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"/;
 
 /**
  * Scan one BPMN document for the job types of its PROMPT-BEARING service tasks — the deployed fleet
@@ -68,3 +72,25 @@ export function promptBearingTaskTypes(xml: string): string[] {
   }
   return types;
 }
+
+/**
+ * Scan one BPMN document for the job types of PROMPT-BEARING agent service tasks that are MISSING the
+ * 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).
+ */
+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;
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    if (type === undefined || type.length === 0 || seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}

package/app/contracts.ts

@@ -479,6 +479,14 @@ export const WIRE_CONTRACTS = {
       "The proxy-safe single-stream transcript READ URL (issue #744): `GET <base>/app/api/agentic/transcripts?stream=<id>&from=<n>` — the stream id rides a QUERY value, NEVER a path segment, because the Nano Console gateway proxy peels one percent-encoding layer before the app routes: an encoded slash (%2F) in a PATH segment arrives as a real / and splits a slash-bearing worker-instance id (`34:<instance>/<jobKey>`) into an extra segment, so the legacy `GET /app/api/agentic/transcripts/{stream}` route 404s behind the proxy (the cockpit past-session replay rendered empty). The path form stays served for back-compat and is proxy-safe ONLY for the slash-free `job:<jobKey>` ids it is seeded with (the worker-emitted `transcriptUrl` = `transcriptUrlBaseFor()` + `jobStream()`, a bare concatenation, must remain resolvable both directly and behind the proxy). ONE builder: `transcriptReadUrlFor()` in app/agentic/transcript-url.ts, served by ONE canonical read (`readSingleTranscript` in app/agentic/transcript-read.ts) shared by both routes; the browser adapter pages/cockpit/mount.js carries a hand-maintained twin (it cannot import server modules). Never put a stream id in a path segment again — do not re-declare a synonym scheme.",
     shape: "GET <transcriptsEndpoint>?stream=<percent-encoded stream id>[&from=<non-negative integer offset>] → AgenticTranscriptData | ErrorBody",
   },
+  "agentTask.agentDefinition": {
+    category: "wire",
+    name: "agentTask.agentDefinition",
+    owner: "resources/processes/*.bpmn",
+    semantics:
+      "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, deferred until the broker read API is reachable from the app's EngineClient). 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)',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.182.3",
+  "version": "0.183.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",
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^1.2.0",
+    "@nanobpm/urban-testkit": "^1.3.0",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.0",
@@ -83,6 +83,7 @@
     "yaml": "^2.9.0"
   },
   "overrides": {
+    "@nanobpm/engine-wasm": "^0.9.0",
     "@semantic-release/npm": "^13.1.5"
   }
 }

package/resources/processes/convergence-loop.bpmn

@@ -100,6 +100,7 @@
     <bpmn:serviceTask id="review-round" name="Review round (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:pr-review" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
@@ -320,6 +321,7 @@
     <bpmn:serviceTask id="classify-scope" name="Scope classifier (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:scope-classify" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/scope-classify.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>

package/resources/processes/implement-cell.bpmn

@@ -16,6 +16,7 @@
     <bpmn:serviceTask id="implement-task" name="Implement (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>

package/resources/processes/merge-cell.bpmn

@@ -7,6 +7,7 @@
     <bpmn:serviceTask id="trial-merge" name="Trial merge (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:trial-merge" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/trial-merge.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>

package/resources/processes/merge-loop.bpmn

@@ -339,6 +339,7 @@
       <bpmn:serviceTask id="fix-ci" name="Fix CI (agent)">
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:fix-ci" />
+          <zeebe:agentDefinition agentType="external" />
           <zeebe:linkedResources>
             <zeebe:linkedResource resourceId="prompts/fix-ci.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
           </zeebe:linkedResources>
@@ -496,6 +497,7 @@
       <bpmn:serviceTask id="rebase" name="Rebase (agent)">
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:rebase" />
+          <zeebe:agentDefinition agentType="external" />
           <zeebe:linkedResources>
             <zeebe:linkedResource resourceId="prompts/rebase.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
           </zeebe:linkedResources>

package/resources/processes/plan-fanout.bpmn

@@ -260,6 +260,7 @@
     <bpmn:serviceTask id="plan" name="Plan (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:plan" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/plan.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
@@ -311,6 +312,7 @@
     <bpmn:serviceTask id="review-plan" name="Review plan (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:plan-review" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/plan-review.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
@@ -520,6 +522,7 @@
     <bpmn:serviceTask id="trial-merge" name="Trial merge (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:trial-merge" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/trial-merge.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>

package/resources/processes/retro.bpmn

@@ -43,6 +43,7 @@
     <bpmn:serviceTask id="conformance" name="Verify implementation vs spec (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:conformance" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/conformance.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
@@ -91,6 +92,7 @@
     <bpmn:serviceTask id="synthesize" name="Synthesize &#38; promote (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:retro" />
+        <zeebe:agentDefinition agentType="external" />
         <zeebe:linkedResources>
           <zeebe:linkedResource resourceId="prompts/retro.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>

package/test/derivation-parity/derivation-parity.test.ts

@@ -9,18 +9,19 @@
 // and linked resources — with a legible red/green diff on mismatch.
 //
 // Ported models run a real `assertDerivationParity`; parked models (see
-// `./flows.ts`) are reported as skipped WITH their precise reason, in two
+// `./flows.ts`) are reported as skipped WITH their precise reason, in three
 // blocker classes — class 1: multiple top-level start/end events; class 2:
-// arbitrary control-flow graph (`convergence-loop`). Companion diagnostics prove
-// each blocker is real against the goldens themselves. No golden is modified to
+// arbitrary control-flow graph (`convergence-loop`); class 3: the engine-native
+// agent-task marker (`retro`, issue #745). Companion diagnostics prove each
+// blocker is real against the goldens themselves. No golden is modified to
 // force a match — the derivation must reproduce the checked-in file.
 
 import { test } from "node:test";
 import { readFileSync } from "node:fs";
 import { assert, assertEquals } from "#test-assert";
-import { assertDerivationParity, normalize } from "@nanobpm/workflow/test-support";
+import { assertDerivationParity, diffModels, modelsEqual, normalize } from "@nanobpm/workflow/test-support";
 import { declarativeToBpmn, defineFlow } from "@nanobpm/workflow";
-import { PORTS } from "./flows.ts";
+import { PORTS, retroFlow } from "./flows.ts";
 
 const ROOT = decodeURIComponent(new URL("../../", import.meta.url).pathname);
 const goldenPath = (model: string): string => `${ROOT}resources/processes/${model}.bpmn`;
@@ -98,8 +99,9 @@ test("class-1 blocked goldens genuinely have multiple top-level start/end events
   }
 
   // The two single-start/single-end goldens (retro, convergence-loop) clear
-  // class 1; retro is a GREEN whole-model parity port (it runs through
-  // `assertDerivationParity` above), convergence-loop is class-2 blocked (below).
+  // class 1; each is blocked on a LATER class instead — retro on the class-3
+  // agent-task marker (proven below), convergence-loop on its class-2 arbitrary
+  // graph.
   for (const model of ["retro", "convergence-loop"]) {
     const xml = readFileSync(goldenPath(model), "utf8");
     assertEquals(countTag(xml, "startEvent"), 1, `${model} should have one start event`);
@@ -157,3 +159,38 @@ test("loop() inserts a gateway head, so back-edges cannot merge into a task", ()
     "the loop-body task cannot itself be the back-edge merge (it stays in<=1)",
   );
 });
+
+// CLASS 3 — retro has a single top-level start/end (clears class 1) and a fully
+// structured topology (clears class 2), but issue #745 added the engine-native
+// AgentTask marker `<zeebe:agentDefinition agentType="external" />` to its two
+// prompt-bearing `senior:*` tasks and the published compiler cannot emit it.
+// Prove the blocker is real AND that it is the ONLY divergence, so the parked
+// entry is a complete, verified port held ready — not an abandoned one.
+test("retro's complete port differs from its golden by ONLY the agent-task marker", () => {
+  const golden = readFileSync(goldenPath("retro"), "utf8");
+  const derived = declarativeToBpmn(retroFlow);
+  const markers = (xml: string): number =>
+    (xml.match(/<(?:\w+:)?agentDefinition\b[^>]*\bagentType="external"/g) ?? []).length;
+
+  // (a) the golden really carries the marker, on BOTH of its agent tasks — and it
+  //     cannot simply be dropped: app/agentic/vocab/agent-marker.test.ts is a
+  //     defect-class guard requiring it on every deployed prompt-bearing agent task.
+  assertEquals(markers(golden), 2, "retro's golden should mark senior:conformance and senior:retro");
+
+  // (b) the published compiler emits none of it — the blocker is real, not a guess.
+  //     When this starts failing, upstream task() grew marker support: un-park retro
+  //     by threading `retroFlow` back into its PORTS entry in ./flows.ts.
+  assertEquals(markers(derived), 0, "@nanobpm/workflow can now emit <zeebe:agentDefinition/> — un-park retro");
+
+  // (c) strip exactly the marker lines from the golden and the port derives the
+  //     WHOLE model green, through the shared harness's own normalize/equality —
+  //     so nothing but the marker diverges.
+  const unmarked = golden.replace(/^[ \t]*<(?:\w+:)?agentDefinition\b[^>]*\/>[ \t]*\r?\n/gm, "");
+  assertEquals(markers(unmarked), 0, "the strip must remove every marker line");
+  const expected = normalize(unmarked);
+  const actual = normalize(derived);
+  assert(
+    modelsEqual(expected, actual),
+    `retro's port must derive its golden once the agent-task marker is stripped — residual drift:\n${diffModels(expected, actual)}`,
+  );
+});

package/test/derivation-parity/flows.ts

@@ -9,10 +9,9 @@
 // the structurally-derivable goldens at full whole-model parity, park the rest
 // pending an upstream construct, and do NOT relax to node-surface parity):
 //
-//   • `retro` is a GREEN whole-model parity port (see below). The remaining seven
-//     goldens are `blockedReason`-parked, in TWO distinct classes, each awaiting
-//     an upstream `@nanobpm/workflow` (nano-ide) construct + re-release — never a
-//     golden edit and never relaxed acceptance:
+//   • EVERY golden is currently `blockedReason`-parked, in THREE distinct
+//     classes, each awaiting an upstream `@nanobpm/workflow` (nano-ide) construct
+//     + re-release — never a golden edit and never relaxed acceptance:
 //
 //     (1) MULTI top-level start/end (spine-demo, readiness-gate, feature,
 //         merge-loop, plan-fanout, delivery-human). `@nanobpm/workflow` derives EXACTLY
@@ -35,6 +34,19 @@
 //         arbitrary-graph / explicit-join (named-target) builder — a SUPERSET of
 //         the class-(1) gap.
 //
+//     (3) ENGINE-NATIVE AGENT-TASK MARKER (retro). `retro` clears BOTH classes
+//         above and WAS a green whole-model parity port: its single start/end,
+//         linear pipeline, `deviations?` branch, userTask, data envelopes, prompt
+//         bindings and general `io` mappings all derive faithfully — the complete
+//         port is still authored below, and `derivation-parity.test.ts` proves it
+//         differs from its golden by NOTHING but the marker. Issue #745 then added
+//         `<zeebe:agentDefinition agentType="external" />` to every prompt-bearing
+//         `senior:*` task (a marker `app/agentic/vocab/agent-marker.test.ts`
+//         requires, so the golden cannot drop it), and the published compiler
+//         cannot emit it: `task()` accepts only `{ jobType, prompt, io }`, and no
+//         `agentDefinition`/`agentType` appears anywhere in
+//         `@nanobpm/workflow@0.14.0`. Needs an agent-marker option on `task()`.
+//
 // A resumed run flips any parked model to a real `flow` once the corresponding
 // upstream construct lands and `@nanobpm/workflow` is bumped to carry it.
 
@@ -60,7 +72,7 @@ export type PortEntry =
       readonly blockedReason: string;
     };
 
-// ── retro (GREEN — whole-model parity) ───────────────────────────────────────
+// ── retro (PARKED — class 3: agent-task marker; the port is otherwise COMPLETE) ─
 // retro is a single-start/single-end model: a linear gather → conformance →
 // record-conformance agent pipeline, a `deviations?` exclusive gateway guarding a
 // conformance-escalation subgraph (nano-workforce #355/#356), then a shared
@@ -72,6 +84,15 @@ export type PortEntry =
 // (nano-ide#405) — `w.task`+`io` for `record-conformance-ack`'s general
 // <zeebe:ioMapping> (inputs `=planKey`→planKey and
 // `=if (is defined(note)) then note else null`→note).
+//
+// The port below is therefore kept WHOLE and exported, not deleted: it is a
+// faithful whole-model derivation whose ONLY divergence from the golden is the
+// `<zeebe:agentDefinition agentType="external" />` marker issue #745 added to the
+// two `senior:*` tasks (class 3 above). `derivation-parity.test.ts` asserts that
+// divergence is exactly the marker, so the moment upstream `task()` grows an
+// agent-marker option this diagnostic fires and the model is un-parked by
+// threading `retroFlow` back into its PORTS entry — a one-line change, with the
+// port already proven correct rather than re-authored from scratch.
 
 /** The typed data envelopes retro's non-agent service tasks lift into the model
  *  (`nano:shape` + `io.nanobpm.dataEnvelope.in`), matching the golden's shapes. */
@@ -96,8 +117,10 @@ const ConformanceRecordIn = envelope("ConformanceRecordIn", {
   summary: { type: "string", optional: true },
 });
 
-/** The code-first port of `resources/processes/retro.bpmn`. */
-const retroFlow: DeclarativeFlow = defineFlow(
+/** The code-first port of `resources/processes/retro.bpmn` — complete but for the
+ *  class-3 agent-task marker, so it is exported for the parity diagnostic that
+ *  pins the divergence to exactly that marker (and parked in PORTS below). */
+export const retroFlow: DeclarativeFlow = defineFlow(
   "retro",
   {
     gather: { in: RetroGatherIn },
@@ -146,9 +169,26 @@ const MULTI_START_END_BLOCK =
   "cannot reproduce. Awaits an upstream terminal/explicit-end (+ multi-start) " +
   "construct in @nanobpm/workflow (nano-ide).";
 
+/** The engine-native AgentTask marker limitation (issue #745), the `blockedReason`
+ *  for a golden whose ONLY underivable feature is `<zeebe:agentDefinition
+ *  agentType="external" />` on its agent service tasks. */
+const AGENT_MARKER_BLOCK =
+  "blocked (agent-task marker): single top-level start/end and a fully " +
+  "structured topology, so this golden derives EXCEPT for the " +
+  "<zeebe:agentDefinition agentType=\"external\" /> marker issue #745 added to " +
+  "its prompt-bearing senior:* tasks — a marker the published compiler cannot " +
+  "emit (task() accepts only { jobType, prompt, io }, and no agentDefinition " +
+  "appears anywhere in @nanobpm/workflow@0.14.0). The golden cannot drop the " +
+  "marker: app/agentic/vocab/agent-marker.test.ts is a defect-class guard " +
+  "requiring it on every deployed prompt-bearing agent task. Proven in the test " +
+  "suite — the complete port (retroFlow, still authored here) differs from the " +
+  "golden by nothing else. Awaits an agent-marker option on task() upstream in " +
+  "@nanobpm/workflow (nano-ide); flip this entry back to `flow: retroFlow` when " +
+  "it lands.";
+
 /** All ports, keyed by model, in the epic's stated authoring order. */
 export const PORTS: readonly PortEntry[] = [
-  { model: "retro", flow: retroFlow },
+  { model: "retro", blockedReason: AGENT_MARKER_BLOCK },
   {
     model: "spine-demo",
     blockedReason: `${MULTI_START_END_BLOCK} (spine-demo: 1 start, 2 ends)`,