@nanobpm/nano-workforce 0.182.2 → 0.183.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* cockpit historical transcript replay 404s through console gateway (encoded slash in stream-id path) ([#750](https://github.com/nanobpm/nano-workforce/issues/750)) ([8dd5e61](https://github.com/nanobpm/nano-workforce/commit/8dd5e619d664a50f513347f3b6f090d190495070)), closes [#744](https://github.com/nanobpm/nano-workforce/issues/744) [#744](https://github.com/nanobpm/nano-workforce/issues/744)
+
 ## [0.182.2](https://github.com/nanobpm/nano-workforce/compare/v0.182.1...v0.182.2) (2026-09-04)
 
 ### Bug Fixes

package/app/agentic/cockpit/mount.test.ts

@@ -70,12 +70,14 @@ function installEnv(fetchImpl: (url: string) => Promise<unknown>): () => void {
 
 const SUPPLY = { leaves: [], correlations: [] };
 
-/** A fetch stub answering the supply poll, the past-sessions list, and a single-stream replay. */
+/** A fetch stub answering the supply poll, the past-sessions list, and a single-stream replay. The
+ * replay READ is matched by its `stream` query param — the proxy-safe form (#744) the deployed
+ * client builds; a slash-bearing id must never appear as a path segment. */
 function fetchStub(replay?: unknown) {
   return (url: string): Promise<unknown> => {
     const ok = (body: unknown) => Promise.resolve({ ok: true, status: 200, json: async () => body });
     if (url.includes("/supply")) return ok(SUPPLY);
-    if (replay !== undefined && /\/transcripts\/[^/]+$/.test(url)) return ok(replay);
+    if (replay !== undefined && /[?&]stream=/.test(url)) return ok(replay);
     if (url.includes("/transcripts")) return ok({ sessions: [] });
     return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
   };
@@ -160,3 +162,54 @@ test("replay renders a past session's transcript — never a raw nwfTranscriptEv
     restore();
   }
 });
+
+// #744 — the deployed cockpit's replay READ must be proxy-safe: the stream id rides the QUERY
+// (`?stream=`), never a path segment. A worker-instance stream id contains a real `/`
+// (`34:<instance>/<jobKey>`); the console gateway decodes an encoded %2F in a PATH segment back
+// to `/` before the app routes, splitting the id into an extra segment → 404 {"error":"no such
+// operation"} → replayInto's fetch throws → the terminal region renders empty ("nothing").
+test("#744: replay fetches the proxy-safe ?stream= query form — a slash-bearing id never lands in a path segment", async () => {
+  const stream = "34:joshs-macbook-pro-copilot-3d6ee882/13859";
+  const replay = {
+    stream,
+    from: 0,
+    gap: false,
+    nextOffset: 1,
+    entries: [{ offset: 0, chunk: envChunk("message", { role: "user", text: "past session bytes" }) }],
+  };
+  const urls: string[] = [];
+  const stub = fetchStub(replay);
+  const restore = installEnv((url) => {
+    urls.push(url);
+    return stub(url);
+  });
+  try {
+    const { mountCockpit } = await import("../../../pages/cockpit/mount.js");
+    const handle = mountCockpit(document.getElementById("root"), OPTS);
+    // Dispose in a finally: mountCockpit auto-starts a poll whose next-tick timer (refreshMs) is a
+    // live handle — a mid-test assertion failure that skipped dispose would hold the event loop
+    // open and hang the whole test runner.
+    try {
+      await handle.replay(stream);
+
+      // The auto-started supply poll and the past-sessions list also hit the wire; the READ fetch is
+      // the only one carrying the stream id (in either URL form — that's what's under test).
+      const readUrl = urls.find((u) => u.includes(encodeURIComponent(stream)) || u.includes(stream));
+      assert(readUrl !== undefined, `the replay fetched a transcript read URL for the stream (saw: ${urls.join(", ")})`);
+      const parsed = new URL(readUrl);
+      // The pathname STAYS the collection route: no %-encoded (or raw) slash-bearing id segment the
+      // gateway peel could split — this is the structural fix for the whole failure class, not just
+      // this one stream shape.
+      assertEquals(parsed.pathname, "/app/api/agentic/transcripts");
+      assertEquals(parsed.searchParams.get("stream"), stream, "the slash-bearing id round-trips intact as a query value");
+      // And the fetched bytes still render through the derive path.
+      const host = document.querySelector('[data-terminal="host"]');
+      assert((host?.textContent ?? "").includes("past session bytes"), "the past session rendered");
+      assertEquals(document.querySelector(".cockpit-terminal")?.getAttribute("data-terminal-mode"), "replay");
+    } finally {
+      handle.dispose();
+    }
+  } finally {
+    restore();
+  }
+});

package/app/agentic/cockpit/supply-boot.ts

@@ -61,7 +61,11 @@ export interface SupplyCockpitEnv {
    */
   readonly fetchTranscripts?: (instance?: string) => Promise<TranscriptListReport>;
   /**
-   * Fetches a stored transcript's bytes (`GET /agentic/transcripts/{stream}`) for static replay.
+   * Fetches a stored transcript's bytes for static replay. Production wiring hits the proxy-safe
+   * query form `GET /agentic/transcripts?stream=<id>&from=<n>` (#744 — see `transcriptReadUrlFor`
+   * in app/agentic/transcript-url.ts and its browser twin in pages/cockpit/mount.js): a
+   * slash-bearing stream id in a PATH segment (`GET /agentic/transcripts/{stream}`) is split by
+   * gateway proxies that decode %2F before routing, 404ing the read.
    * Required for the "past sessions" replay to work; must be provided together with {@link fetchTranscripts}.
    */
   readonly fetchTranscript?: (stream: string, from?: number) => Promise<TranscriptDataReport>;

package/app/agentic/transcript-read.ts

@@ -15,9 +15,10 @@
 // unit-testable on the injected env (Node, no browser), and never touches the engine or a BPMN flow.
 
 import type { TranscriptChunk, TranscriptRing, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
-import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
+import type { AgenticTranscript, AgenticTranscriptData, ErrorBody } from "../../nano-generated/api-io.d.ts";
 import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
 import type { AgenticCorrelationStore } from "./correlation-store.ts";
+import type { RelayTranscriptService } from "./families/relay.family.ts";
 import { utf8ByteLength } from "./transcript-events.ts";
 
 /** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
@@ -242,3 +243,47 @@ export function readTranscriptFrom(
   if (fields.host !== undefined) out.host = fields.host;
   return out;
 }
+
+/** The single-stream read result both transcript READ routes share (#744): the bytes on 200, the
+ * same 400 (malformed `from`) / 404 (no such stream, or no service mounted) outcomes on failure. */
+export type SingleTranscriptResult =
+  | { status: 200; body: AgenticTranscriptData }
+  | { status: 400; body: ErrorBody }
+  | { status: 404; body: ErrorBody };
+
+/**
+ * The ONE canonical single-stream transcript read, shared by BOTH routes that serve it (#744):
+ * `GET /agentic/transcripts?stream=<id>&from=<n>` (the proxy-safe QUERY form the cockpit clients
+ * build — a gateway that peels one percent-encoding layer before routing splits an encoded slash
+ * in a PATH segment into an extra segment and 404s, while a query value survives intact) and
+ * `GET /agentic/transcripts/{stream}` (the legacy path form the worker-emitted `transcriptUrl`
+ * resolves — safe there because `job:<jobKey>` ids structurally never contain a slash). One
+ * implementation so the two addressings can never answer differently for the same stream/from.
+ */
+export function readSingleTranscript(
+  stream: string,
+  from: number | undefined,
+  service: RelayTranscriptService | undefined,
+  correlation: CorrelationRegistry | undefined,
+): SingleTranscriptResult {
+  const offset = from ?? 0;
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    return { status: 400, body: { error: "invalid from: expected a non-negative integer offset" } };
+  }
+  if (!service) {
+    // No relay/transcript service mounted at all - nothing to replay.
+    return { status: 404, body: { error: "no transcript for stream" } };
+  }
+  const data = readTranscriptFrom(
+    stream,
+    offset,
+    service.store,
+    correlation,
+    service.correlationStore,
+    service.liveFallback(stream),
+  );
+  if (data === undefined) {
+    return { status: 404, body: { error: "no transcript for stream" } };
+  }
+  return { status: 200, body: data };
+}

package/app/agentic/transcript-url.test.ts

@@ -7,6 +7,7 @@ import { jobStream } from "./correlation.ts";
 import {
   TRANSCRIPT_URL_BASE_VAR,
   TRANSCRIPT_URL_VAR,
+  transcriptReadUrlFor,
   transcriptUrlBaseFor,
   transcriptUrlForJob,
 } from "./transcript-url.ts";
@@ -33,3 +34,48 @@ test("derivation: transcriptUrlForJob is exactly transcriptUrlBaseFor + jobStrea
   const jobKey = "job-abc";
   assertEquals(transcriptUrlForJob(jobKey, BASE), `${transcriptUrlBaseFor(BASE)}${jobStream(jobKey)}`);
 });
+
+// #744 — the proxy-safe single-stream READ form. A worker-instance stream id CONTAINS a slash
+// (`34:<instance>/<jobKey>`); the Nano Console gateway proxy peels exactly one percent-encoding
+// layer off the request before the app routes it, so an encoded slash (%2F) in a PATH segment
+// arrives as a real / and splits the id into an extra segment — the app matches no route and
+// answers 404 {"error":"no such operation"}. Carrying the id as a QUERY value makes the read
+// structurally immune: a / is legal inside a query value, encoded or not.
+const SLASH_STREAM = "34:joshs-macbook-pro-copilot-3d6ee882/13859";
+const ENDPOINT = `${BASE}/app/api/agentic/transcripts`;
+
+/** Non-empty path-segment count of a URL — what a route matcher counts. */
+function pathSegments(u: string): number {
+  return new URL(u).pathname.split("/").filter((s) => s !== "").length;
+}
+
+test("transcriptReadUrlFor: the stream id rides the query, never a path segment (#744)", () => {
+  const url = new URL(transcriptReadUrlFor(ENDPOINT, SLASH_STREAM));
+  assertEquals(url.pathname, "/app/api/agentic/transcripts");
+  assertEquals(url.searchParams.get("stream"), SLASH_STREAM);
+});
+
+test("transcriptReadUrlFor: an explicit from offset appends as a query param", () => {
+  const url = new URL(transcriptReadUrlFor(ENDPOINT, "job:6494", 42));
+  assertEquals(url.searchParams.get("stream"), "job:6494");
+  assertEquals(url.searchParams.get("from"), "42");
+});
+
+test("#744 failure class: a gateway peel of one encoding layer breaks an encoded slash in a PATH segment but not a query value", () => {
+  // The legacy path form matches the `/app/api/agentic/transcripts/{stream}` route (5 segments)
+  // ONLY while the %2F stays encoded.
+  const pathForm = `${ENDPOINT}/${encodeURIComponent(SLASH_STREAM)}`;
+  assertEquals(pathSegments(pathForm), 5);
+  // The gateway peels exactly one percent-encoding layer before the app routes (#744 evidence):
+  // %2F becomes a real /, the app sees 6 segments, no route matches → 404 → the cockpit's replay
+  // fetch throws and the terminal region renders empty.
+  assertEquals(pathSegments(decodeURIComponent(pathForm)), 6);
+
+  // The query form is immune to the SAME peel: the pathname stays the collection route (4
+  // segments) before and after decoding, and the slash-bearing id round-trips intact.
+  const queryForm = transcriptReadUrlFor(ENDPOINT, SLASH_STREAM);
+  assertEquals(pathSegments(queryForm), 4);
+  const peeled = new URL(decodeURIComponent(queryForm));
+  assertEquals(pathSegments(peeled.href), 4);
+  assertEquals(peeled.searchParams.get("stream"), SLASH_STREAM);
+});

package/app/agentic/transcript-url.ts

@@ -48,7 +48,36 @@ export function transcriptUrlBaseFor(base: string = publicBaseUrl()): string {
  * The full durable transcript URL for a completed job's `jobKey` — the value a worker emits on
  * {@link TRANSCRIPT_URL_VAR}. Derived from {@link transcriptUrlBaseFor} + {@link jobStream} so it can
  * never disagree with the base the dispatcher seeds or the endpoint route it resolves to.
+ *
+ * The path-segment form is proxy-safe HERE because a `job:<jobKey>` id structurally never contains a
+ * slash (the jobKey is an engine key) — the #744 gateway-peel failure only bites slash-bearing ids.
+ * Any client that reads an ARBITRARY stream (e.g. the cockpit's past-session replay, whose
+ * worker-instance ids look like `34:<instance>/<jobKey>`) MUST use {@link transcriptReadUrlFor}
+ * instead.
  */
 export function transcriptUrlForJob(jobKey: string, base: string = publicBaseUrl()): string {
   return `${transcriptUrlBaseFor(base)}${jobStream(jobKey)}`;
 }
+
+/**
+ * The proxy-safe single-stream READ URL (#744): `<transcriptsEndpoint>?stream=<id>[&from=<n>]` —
+ * the query form of `GET /agentic/transcripts` (operation `listAgenticTranscripts`), answering with
+ * the same bytes the legacy `GET /agentic/transcripts/{stream}` path form serves.
+ *
+ * The stream id rides a QUERY value, never a path segment: the Nano Console gateway proxy peels
+ * exactly one percent-encoding layer before the app routes, so an encoded slash (%2F) in a PATH
+ * segment arrives as a real / and splits a slash-bearing id (`34:<instance>/<jobKey>`) into an extra
+ * segment — no route matches and the read 404s. A / inside a query value is never a separator, so
+ * this form survives the peel intact (the whole failure class, not just one stream shape).
+ *
+ * `transcriptsEndpoint` is the collection-route URL (`<base>/app/api/agentic/transcripts` — the same
+ * string the cockpit carries as its `transcriptsUrl`). This is the SINGLE SOURCE OF TRUTH for the
+ * query form: the cockpit's browser adapter (`pages/cockpit/mount.js`, which cannot import server
+ * modules) carries a hand-maintained twin of this builder — keep the two in lockstep.
+ */
+export function transcriptReadUrlFor(transcriptsEndpoint: string, stream: string, from?: number): string {
+  const url = new URL(transcriptsEndpoint);
+  url.searchParams.set("stream", stream);
+  if (from !== undefined) url.searchParams.set("from", String(from));
+  return url.href;
+}

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

@@ -471,6 +471,22 @@ export const WIRE_CONTRACTS = {
       "The harness's job-end `phase:\"close\"` transcript `lifecycle` event (issue #710, harness half jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:\"open\"` RELAY_OPEN_CHUNK the harness emits at relay-session open. The harness emits it on the `job:<jobKey>` relay stream through agentic's own `encodeTranscriptEvent` (never hand-rolled), right before `job.complete`/`job.fail` and AFTER draining its outbound relay buffer, so it is the deterministic \"all this job's bytes are here, it is done\" signal. The app recognizes it in `isTerminalLifecycleChunk` (relay.family.ts) to `completeStream()` — flush the durable past-session transcript and release job⇄instance correlation — at job-completion time, fixing the truncated-tail defect where the flush waited for a supersede/disconnect. `close` is NOT a core agentic `LifecycleEvent` phase (the contract's phases are open|completed|exited); the app decodes it via an ADDITIVE `mergeTranscriptVocab` extension (`RELAY_TERMINAL_VOCAB`) that maps it onto the terminal `completed` phase — never a forked wire shape, and scoped to the relay job-end detector so the cockpit derive (CORE vocab) keeps the close chunk byte-faithful. The `close` trigger is ADDITIVE: supersede + disconnect remain as fallbacks and the `state.completed` guard keeps a close-then-disconnect (or duplicate close) idempotent. Consume this ONE marker — do not re-declare a synonym or a second job-end signal.",
     shape: '{ nwfTranscriptEvent: 1, kind: "lifecycle", phase: "close" }',
   },
+  "transcript.readUrl": {
+    category: "wire",
+    name: "transcript.readUrl",
+    owner: "app/agentic/transcript-url.ts",
+    semantics:
+      "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/app/mcpToolSurface.ts

@@ -92,8 +92,14 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * client must parse). The deployed surface measures ~78,962 bytes (issue #715); this ceiling forbids
  * meaningful growth so a fat new schema cannot silently re-inflate the surface past the harness
  * deferral point.
+ *
+ * RAISE PROVENANCE — 84_000 → 84_500 (#744): the proxy-safe single-stream transcript read adds two
+ * input-schema properties (`stream`/`from`) to `listAgenticTranscripts` plus one summary line on
+ * each of the two transcript tools, keeping the `?stream=` form discoverable from the tool surface
+ * alone (measured +219 bytes serialized, 83,824 → 84,043 — over the old ceiling's 176-byte
+ * headroom). Deliberate, documented growth — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 84_000;
+export const MCP_SURFACE_BYTES_BUDGET = 84_500;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/openapi.yaml

@@ -3795,11 +3795,33 @@ paths:
       operationId: listAgenticTranscripts
       summary: List captured agent sessions (H3/#146) — the durable transcripts an ephemeral agent flushed
         on job completion, readable AFTER it exited. Optional filters by jobKey / process instance / plan /
-        time. Advisory read-only; never gates control flow. Feeds the cockpit "past sessions" view.
+        time. Also serves the proxy-safe single-stream READ form `?stream=` (#744). Advisory read-only;
+        never gates control flow. Feeds the cockpit "past sessions" view.
       security:
         - hookSecret: []
         - {}
       parameters:
+        - name: stream
+          in: query
+          required: false
+          schema:
+            type: string
+          description: >-
+            Single-stream READ form (#744, proxy-safe): when present, the response is that ONE
+            stream's transcript bytes (`AgenticTranscriptData` — the payload
+            `GET /agentic/transcripts/{stream}` serves), NOT the list, and the filters below are
+            ignored. The id rides a query value, so slash-bearing worker-instance ids
+            (`34:<instance>/<jobKey>`) survive gateways that decode %2F in path segments before
+            routing. Prefer this form over the path form behind any proxy.
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Only with `stream` — resume from this offset (inclusive). Default 0. Rejected with 400
+            when supplied without `stream`.
         - name: jobKey
           in: query
           required: false
@@ -3846,13 +3868,17 @@ paths:
           description: Return only sessions created at or before this ISO-8601 instant.
       responses:
         "200":
-          description: The captured session list.
+          description: The captured session list — or, in the single-stream form (`?stream=`), that
+            stream's stored transcript bytes (#744).
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AgenticTranscriptList"
+                oneOf:
+                  - $ref: "#/components/schemas/AgenticTranscriptList"
+                  - $ref: "#/components/schemas/AgenticTranscriptData"
         "400":
-          description: A malformed filter (e.g. an unparseable since/until).
+          description: A malformed filter (e.g. an unparseable since/until), or — in the single-stream
+            form — a malformed `from` offset.
           content:
             application/json:
               schema:
@@ -3863,12 +3889,19 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: Single-stream form only — no transcript exists for the given `stream`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /agentic/transcripts/{stream}:
     get:
       operationId: getAgenticTranscript
       summary: Fetch a stored transcript's bytes (H3/#146), range/offset-based so the cockpit terminal
-        replays it through the same resume-from-offset renderer it uses for a live stream. Advisory
-        read-only; never gates control flow.
+        replays it through the same resume-from-offset renderer it uses for a live stream. PATH form
+        of the single-stream read (back-compat; a slash-bearing id 404s behind a decoding proxy —
+        prefer the `?stream=` query form there, #744). Advisory read-only; never gates control flow.
       security:
         - hookSecret: []
         - {}
@@ -3878,7 +3911,9 @@ paths:
           required: true
           schema:
             type: string
-          description: The relay stream id to fetch (`job:<jobKey>` for a job stream).
+          description: The relay stream id to fetch (`job:<jobKey>` for a job stream). CAVEAT (#744) —
+            a gateway that decodes %2F in a path segment splits a slash-bearing id and this route
+            404s; such ids must use the `?stream=` query form. Slash-free ids are safe in either.
         - name: from
           in: query
           required: false

package/operations/getAgenticTranscript.ts

@@ -2,8 +2,12 @@
 //
 // Fetch a stored transcript's bytes, range/offset-based (?from=<offset>, default 0) so the cockpit
 // terminal replays a closed stream through the SAME resume-from-offset renderer it uses for a live one
-// (static playback of an exited agent). Sourced from the mounted relay/transcript service's
-// TranscriptStore over `app.data`, correlated best-effort via `app/agentic/correlation.ts`.
+// (static playback of an exited agent). The PATH form of the single-stream read, kept for back-compat
+// (the worker-emitted `transcriptUrl` and Explorer links resolve here — safe because `job:<jobKey>`
+// ids never contain a slash); proxy-exposed clients use the `?stream=` QUERY form on the collection
+// route instead (#744 — a gateway that decodes %2F in a path segment 404s this route). Both forms run
+// the ONE canonical read (`readSingleTranscript` in app/agentic/transcript-read.ts), so they can never
+// answer differently for the same stream/from.
 //
 // Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Unknown stream -> 404; a
 // malformed `from` -> 400. Shared-secret guard mirrors getAgenticSupply (x-hook-secret when
@@ -11,7 +15,7 @@
 
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
-import { readTranscriptFrom } from "../app/agentic/transcript-read.ts";
+import { readSingleTranscript } from "../app/agentic/transcript-read.ts";
 import { envVar } from "../app/version.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
@@ -23,29 +27,5 @@ export default defineOperation("getAgenticTranscript", async ({ params, query, r
     return { status: 401, body: { error: "unauthorized" } };
   }
 
-  const from = query.from ?? 0;
-  if (!Number.isSafeInteger(from) || from < 0) {
-    return { status: 400, body: { error: "invalid from: expected a non-negative integer offset" } };
-  }
-
-  const service = currentRelayTranscriptService();
-  if (!service) {
-    // No relay/transcript service mounted at all - nothing to replay.
-    return { status: 404, body: { error: "no transcript for stream" } };
-  }
-
-  // Read the durable store first, falling back to the still-live relay ring (#486) so a `transcriptUrl`
-  // emitted by a job on a still-live multiplexing worker is readable before its ring is flushed.
-  const data = readTranscriptFrom(
-    params.stream,
-    from,
-    service.store,
-    currentCorrelation(),
-    service.correlationStore,
-    service.liveFallback(params.stream),
-  );
-  if (data === undefined) {
-    return { status: 404, body: { error: "no transcript for stream" } };
-  }
-  return { status: 200, body: data };
+  return readSingleTranscript(params.stream, query.from, currentRelayTranscriptService(), currentCorrelation());
 });

package/operations/listAgenticTranscripts.test.ts

@@ -167,3 +167,89 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
     else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
   }
 });
+
+// #744 — the proxy-safe single-stream read form: `?stream=` on the collection route returns that
+// transcript's BYTES (the AgenticTranscriptData payload GET /{stream} serves), NOT the session
+// list. Worker-instance stream ids contain a slash (`34:<instance>/<jobKey>`); behind the console
+// gateway — which decodes %2F in a path segment back to a real / before the app routes — the
+// legacy path form 404s, so the cockpit reads a single stream through this query form.
+test("#744: ?stream= returns the single transcript's bytes for a slash-bearing id (not the list)", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  const stream = "34:joshs-macbook-pro-copilot-3d6ee882/13859";
+  store.flush(
+    stream,
+    { since: () => ({ entries: [{ offset: 0, chunk: "aa" }, { offset: 1, chunk: "bb" }] }), nextOffset: 2 },
+    "ephemeral",
+  );
+  try {
+    const res = (await handler(input({ stream }), app)) as {
+      status: number;
+      body: {
+        stream: string;
+        from: number;
+        gap: boolean;
+        nextOffset: number;
+        chunkCount: number;
+        byteLength: number;
+        entries: Array<{ offset: number; chunk: string }>;
+      };
+    };
+    assertEquals(res.status, 200);
+    assertEquals(res.body.stream, stream);
+    assertEquals(res.body.from, 0);
+    assertEquals(res.body.gap, false);
+    assertEquals(res.body.nextOffset, 2);
+    assertEquals(res.body.chunkCount, 2);
+    assertEquals(res.body.byteLength, 4);
+    assertEquals(res.body.entries.map((e) => e.chunk), ["aa", "bb"]);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("#744: ?stream= honors from, 404s an unknown stream, and 400s a malformed from", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  const store = currentRelayTranscriptService()?.store;
+  assert(store !== undefined);
+  store.flush(
+    "job:6494",
+    { since: () => ({ entries: [{ offset: 0, chunk: "aa" }, { offset: 1, chunk: "bb" }] }), nextOffset: 2 },
+    "ephemeral",
+  );
+  try {
+    const resume = (await handler(input({ stream: "job:6494", from: 1 }), app)) as {
+      status: number;
+      body: { from: number; chunkCount: number; entries: Array<{ chunk: string }> };
+    };
+    assertEquals(resume.status, 200);
+    assertEquals(resume.body.from, 1);
+    assertEquals(resume.body.entries.map((e) => e.chunk), ["bb"]);
+
+    const unknown = (await handler(input({ stream: "job:nope" }), app)) as { status: number };
+    assertEquals(unknown.status, 404);
+
+    const bad = (await handler(input({ stream: "job:6494", from: -1 }), app)) as { status: number };
+    assertEquals(bad.status, 400);
+  } finally {
+    relayFamily.teardown?.();
+  }
+});
+
+test("#744: ?stream= 404s (not an empty list) when no relay/transcript family is mounted", async () => {
+  relayFamily.teardown?.();
+  const res = (await handler(input({ stream: "job:1" }), app)) as { status: number };
+  assertEquals(res.status, 404);
+});
+
+test("#744: `from` without `stream` is a 400 (not a silently-ignored list read)", async () => {
+  relayFamily.mount(mountCtx(memSqlite()));
+  try {
+    const res = (await handler(input({ from: 0 }), app)) as { status: number; body: { error: string } };
+    assertEquals(res.status, 400);
+    assert(res.body.error.includes("stream"));
+  } finally {
+    relayFamily.teardown?.();
+  }
+});

package/operations/listAgenticTranscripts.ts

@@ -6,13 +6,19 @@
 // correlated via `app/agentic/correlation.ts` (best-effort — jobKey is always recovered from the stream
 // id, engine context only while the job is still live). Feeds the cockpit "past sessions" view.
 //
+// Also serves the proxy-safe single-stream READ form (#744): `?stream=<id>&from=<n>` switches this route
+// from the session list to that ONE stream's bytes — the same payload GET /{stream} serves, through the
+// same canonical read (`readSingleTranscript`). The id rides a QUERY value so a slash-bearing stream id
+// (`34:<instance>/<jobKey>`) survives gateway proxies that decode %2F in a PATH segment back to a real /
+// before routing (the cockpit replay 404'd silently behind the Nano Console).
+//
 // Advisory read-only (ADR 0056): it NEVER gates a BPMN sequence flow. Optional filters (jobKey / process
 // instance / plan / time) narrow the feed. The optional shared-secret guard mirrors getAgenticSupply:
 // when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header; unset -> open.
 
 import { currentCorrelation } from "../app/agentic/correlation.ts";
 import { currentRelayTranscriptService } from "../app/agentic/families/relay.family.ts";
-import { listTranscripts, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
+import { listTranscripts, readSingleTranscript, type TranscriptFilter } from "../app/agentic/transcript-read.ts";
 import { envVar } from "../app/version.ts";
 import type { AgenticTranscriptList } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -30,6 +36,18 @@ export default defineOperation("listAgenticTranscripts", async ({ query, req },
     return { status: 401, body: { error: "unauthorized" } };
   }
 
+  // #744: the single-stream READ form takes precedence — `?stream=` addresses ONE transcript's bytes,
+  // not the list, so the list filters below do not apply.
+  if (query.stream !== undefined) {
+    return readSingleTranscript(query.stream, query.from, currentRelayTranscriptService(), currentCorrelation());
+  }
+
+  // `from` addresses an offset WITHIN one stream, so it is only meaningful with `?stream=`. Reject it
+  // rather than silently returning the list, so the API can never quietly ignore a caller's intent.
+  if (query.from !== undefined) {
+    return { status: 400, body: { error: "invalid from: only valid together with stream" } };
+  }
+
   if (badInstant(query.since) || badInstant(query.until)) {
     return { status: 400, body: { error: "invalid since/until: expected an ISO-8601 instant" } };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.182.2",
+  "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/pages/cockpit/mount.js

@@ -468,7 +468,9 @@ function relaySocketFactory(url) {
  * @param {string} [opts.transcriptsUrl] — the captured-session list endpoint backing the always-on
  *   "past sessions" history + replay (default
  *   `new URL("../app/api/agentic/transcripts", import.meta.url).href`, module-anchored so it
- *   resolves to the app root `<appMount>/app/api/agentic/transcripts`, not the `/cockpit/` shell base).
+ *   resolves to the app root `<appMount>/app/api/agentic/transcripts`, not the `/cockpit/` shell
+ *   base). The per-session replay read uses the proxy-safe `?stream=` query form on this same URL
+ *   (#744 — never a `/…/<id>` path segment, which a decoding gateway splits on encoded slashes).
  * @returns a handle with `.dispose()`.
  */
 export function mountCockpit(host, opts = {}) {
@@ -718,7 +720,8 @@ export function mountCockpit(host, opts = {}) {
       abortTimer.unref?.();
       let res;
       try {
-        res = await fetch(`${transcriptsUrl}/${encodeURIComponent(stream)}`, { headers: jsonHeaders(), signal: controller.signal });
+        // Proxy-safe read URL (#744): the stream id rides the QUERY (?stream=), never a path segment.
+        res = await fetch(transcriptReadUrl(stream), { headers: jsonHeaders(), signal: controller.signal });
       } finally {
         clearTimeout(abortTimer);
       }
@@ -753,6 +756,25 @@ export function mountCockpit(host, opts = {}) {
     return url.href;
   }
 
+  // The proxy-safe single-stream READ URL (#744) — the browser twin of `transcriptReadUrlFor` in
+  // app/agentic/transcript-url.ts (mount.js cannot import the server module; keep the two in
+  // lockstep). The stream id rides a QUERY value, never a path segment: the console gateway peels
+  // one percent-encoding layer before the app routes, so 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 — the app matches no route and answers 404, which left the past-session
+  // replay silently empty behind the proxy. A / inside a query value is never a separator.
+  //
+  // Mirrors the server SSOT's optional `from` offset (`transcriptReadUrlFor(endpoint, stream, from?)`):
+  // omitted -> no `from` param (read from the start); a numeric offset appends `&from=<n>` so a
+  // resume-from-offset replay can fetch from a non-zero position and the two twins stay structurally
+  // in lockstep.
+  function transcriptReadUrl(stream, from) {
+    const url = new URL(transcriptsUrl, location.href);
+    url.searchParams.set("stream", stream);
+    if (from !== undefined) url.searchParams.set("from", String(from));
+    return url.href;
+  }
+
   async function refreshPast(instance = routeInstance()) {
     // Single-flight: while one past-fetch is outstanding (including a hung one), skip starting another
     // so the supply poll can't stack pending fetches against a slow/unresponsive transcripts endpoint.

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)`,