@nanobpm/nano-workforce 0.182.3 → 0.183.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.183.1](https://github.com/nanobpm/nano-workforce/compare/v0.183.0...v0.183.1) (2026-09-07)
+
+### Bug Fixes
+
+* **reconcile:** cross-check engine truth before orphaning a vanished instance ([#753](https://github.com/nanobpm/nano-workforce/issues/753)) ([a363fdb](https://github.com/nanobpm/nano-workforce/commit/a363fdbec1fd14641f2c4a2ef2718034a11a1e92)), closes [#630](https://github.com/nanobpm/nano-workforce/issues/630) [#736](https://github.com/nanobpm/nano-workforce/issues/736) [#736](https://github.com/nanobpm/nano-workforce/issues/736) [#736](https://github.com/nanobpm/nano-workforce/issues/736)
+
+## [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/app/reconcile.test.ts

@@ -10,10 +10,12 @@
 // `makeGateway`), so the tables/columns/indexes reconcile reads and writes are the shipping schema.
 import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import type { DataLayer, GatewayDataSource as DataSource } from "@nanobpm/urban";
+import { assertEquals, assertNotEquals } from "#test-assert";
 import { freshData } from "../test/reconcileDb.ts";
 import {
   DEFAULT_VANISHED_GRACE_MS,
+  makeEngineActiveProbe,
   ORPHANED_STATUS,
   parseEngineEpoch,
   RECONCILE_ORPHAN_REASON,
@@ -393,28 +395,115 @@ test("idempotent: a second vanished pass is a no-op (the orphaned row left activ
   assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 1);
 });
 
+// --- Engine-truth cross-check before orphaning a "vanished" row (issue #736) -------------------
+// The `_urban_instance_state` projection is an app-side read model that can lag / be pruned / be
+// rebuilt while the instance is still ACTIVE on the engine. "No projection row" is therefore NOT
+// "instance vanished": on merlin (whose engine exposes no incarnation epoch, so the robust epoch
+// detector is disabled) this false-orphaned 3 concurrently-LIVE instances in one pass. The vanished
+// pass now cross-checks ENGINE TRUTH via `engineActive` before folding — an ACTIVE instance is spared.
+
+test("RED→GREEN #736: an engine-ACTIVE instance with no _urban_instance_state row (past grace) is NOT orphaned", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  // The merlin repro: an inflight run past grace whose projection row is absent (lagging/pruned) but
+  // whose instance the engine still reports ACTIVE. RED (pre-fix): folded to `orphaned`. GREEN: spared.
+  seedFeatureRun(raw, "nanobpm/nano-workforce#336", "running", "11625");
+  // Engine truth says ACTIVE for this key.
+  const engineActive = async (key: string) => (key === "11625" ? true : false);
+
+  const res = await reconcileVanishedInstances(data, { now: AT, runId: "van-1", engineActive });
+
+  assertEquals(res.reason, "no-op");
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='nanobpm/nano-workforce#336'").get() as {
+    status: string;
+  };
+  assertEquals(row.status, "running");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+test("#736: an engine-CONFIRMED-gone instance (engineActive=false) IS still orphaned", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  seedFeatureRun(raw, "Magikcraft/nano-bpm#1051", "escalated", "71506");
+  // Engine answered and the instance is absent/terminated — genuinely gone in engine truth.
+  const engineActive = async () => false;
+
+  const res = await reconcileVanishedInstances(data, { now: AT, runId: "van-1", engineActive });
+
+  assertEquals(res.reason, "instance-vanished");
+  assertEquals(res.orphanedCount, 1);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='Magikcraft/nano-bpm#1051'").get() as {
+    status: string;
+  };
+  assertEquals(row.status, ORPHANED_STATUS);
+});
+
+test("#736: an instance whose engine truth is UNKNOWN (engineActive=null) is spared — never orphan unconfirmed", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  seedFeatureRun(raw, "o/r#unknown", "escalated", "71506");
+  // The engine truth could not be established (unreachable / non-2xx / malformed) — we must NOT orphan.
+  const engineActive = async () => null;
+
+  const res = await reconcileVanishedInstances(data, { now: AT, runId: "van-1", engineActive });
+
+  assertEquals(res.reason, "no-op");
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#unknown'").get() as {
+    status: string;
+  };
+  assertEquals(row.status, "escalated");
+});
+
 // --- Merged seam: runEngineReconcile (both passes, one result) --------------------------------
 // The operator/startup seam merges the epoch-regression and vanished-instance passes into ONE
 // result. This guards the merged behavior the two per-pass suites above don't reach: run-id
-// correlation (the vanished pass's provenance must be locatable from the returned `runId`) and
-// `reason` selection when the epoch pass is `engine-unreachable` yet vanished instances are orphaned.
+// correlation (the vanished pass's provenance must be locatable from the returned `runId`), the
+// engine-truth cross-check the seam wires from the live engine (#736), and `reason` selection.
+
+/** A `/v2` fetch stub: `/topology` answers `topologyBody` (200), and `/process-instances/search`
+ *  answers with `searchItems` (200) — the engine-truth cross-check the vanished pass runs (#736). */
+function engineFetch(
+  topologyBody: unknown,
+  searchItems: { processInstanceKey?: string | number; state?: string }[],
+): typeof fetch {
+  return (async (url: string, init?: { method?: string }) => {
+    const u = String(url);
+    if (u.endsWith("/topology")) return new Response(JSON.stringify(topologyBody), { status: 200 });
+    if (u.endsWith("/process-instances/search") && init?.method === "POST") {
+      return new Response(JSON.stringify({ items: searchItems }), { status: 200 });
+    }
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+}
+
+test("runEngineReconcile #736: a reachable engine reporting the instance ACTIVE spares it (no false-orphan)", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  // No projection row, past grace — but the engine (reachable, no epoch, like merlin) reports ACTIVE.
+  seedFeatureRun(raw, "nanobpm/nano-workforce#731", "escalated", "11644");
+  const fetchImpl = engineFetch({ nano: { engine: "merlin" } }, [{ processInstanceKey: "11644", state: "ACTIVE" }]);
+
+  const res = await runEngineReconcile(data, { restAddress: "http://engine.local/v2" }, { now: AT, fetchImpl });
+
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='nanobpm/nano-workforce#731'").get() as {
+    status: string;
+  };
+  assertEquals(row.status, "escalated");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
 
-test("runEngineReconcile: engine-unreachable epoch pass still folds vanished instances, with a correlatable run id", async () => {
+test("runEngineReconcile #736: a reachable engine that no longer knows the instance folds it, with a correlatable run id", async () => {
   const { data, raw } = freshData();
   ensureInstanceState(raw);
-  // A vanished orphan (escalated, past grace, instance absent from the read model).
+  // A genuinely-vanished orphan (escalated, past grace); the engine answers but the instance is absent.
   seedFeatureRun(raw, "Magikcraft/nano-bpm#1051", "escalated", "71506");
+  const fetchImpl = engineFetch({ nano: { engine: "merlin" } }, []);
 
-  // The engine is unreachable — the epoch probe fails, so the epoch pass reports `engine-unreachable`
-  // and orphans nothing; the vanished pass must still act.
-  const fetchImpl = (() => Promise.reject(new Error("ECONNREFUSED"))) as unknown as typeof fetch;
-  const res = await runEngineReconcile(
-    data,
-    { restAddress: "http://engine.invalid" },
-    { now: AT, fetchImpl },
-  );
+  const res = await runEngineReconcile(data, { restAddress: "http://engine.local/v2" }, { now: AT, fetchImpl });
 
-  // The vanished pass acted even though the epoch pass could not reach the engine.
   assertEquals(res.reason, "instance-vanished");
   assertEquals(res.orphanedCount, 1);
   const orphan = raw
@@ -429,14 +518,189 @@ test("runEngineReconcile: engine-unreachable epoch pass still folds vanished ins
     .get() as { run_id: string };
   assertEquals(prov.run_id, `${res.runId}-vanished`);
 
-  // Both passes recorded their own reconcile_runs row under correlatable ids.
-  const epochRun = raw.prepare("SELECT reason FROM reconcile_runs WHERE run_id=?").get(res.runId) as
-    | { reason: string }
-    | undefined;
-  assertEquals(epochRun?.reason, "engine-unreachable");
   const vanishedRun = raw
     .prepare("SELECT reason, orphaned_count FROM reconcile_runs WHERE run_id=?")
     .get(`${res.runId}-vanished`) as { reason: string; orphaned_count: number } | undefined;
   assertEquals(vanishedRun?.reason, "instance-vanished");
   assertEquals(vanishedRun?.orphaned_count, 1);
 });
+
+test("runEngineReconcile #736: an UNREACHABLE engine spares vanished candidates (truth unconfirmed → never orphan)", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  // A candidate that looks vanished (escalated, past grace, no projection row) — but with the engine
+  // unreachable we cannot confirm it is gone, so it MUST be spared (issue #736): the old projection-only
+  // behavior would have orphaned it, potentially false-orphaning a live instance mid-outage.
+  seedFeatureRun(raw, "Magikcraft/nano-bpm#1051", "escalated", "71506");
+
+  const fetchImpl = (() => Promise.reject(new Error("ECONNREFUSED"))) as unknown as typeof fetch;
+  const res = await runEngineReconcile(data, { restAddress: "http://engine.invalid" }, { now: AT, fetchImpl });
+
+  // The epoch pass could not reach the engine, and the vanished pass could not confirm death → no-op.
+  assertEquals(res.reason, "engine-unreachable");
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='Magikcraft/nano-bpm#1051'").get() as {
+    status: string;
+  };
+  assertEquals(row.status, "escalated");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+// --- Hardening the cross-check itself (#736 review) ---------------------------------------------
+// Two defects of the SAME class the first cut still carried — "never orphan a row we could not
+// positively confirm is gone" — plus the lock-hold the cross-check introduced:
+//   1. a MATCHING search item whose `state` was missing or outside the engine's lifecycle enum read as
+//      `false` ("gone"), so a malformed/partial engine answer folded live work;
+//   2. the probe (network I/O) was awaited INSIDE `src.tx(...)`, so a slow or unreachable engine held
+//      the SQLite write transaction open for the probe's full timeout PER CANDIDATE ROW — stalling
+//      every other writer, including boot — and an injected probe that threw aborted the whole pass.
+
+/** Answer `/v2/process-instances/search` with exactly `items` (200), so a probe's classification can
+ *  be read off one wire shape varying only in the item's `state`. */
+function searchItemsFetch(items: { processInstanceKey?: string | number; state?: string }[]): typeof fetch {
+  return (async () => new Response(JSON.stringify({ items }), { status: 200 })) as unknown as typeof fetch;
+}
+
+/** Probe the key `11644` against a stubbed engine search answer of `items`. */
+function probeAgainst(items: { processInstanceKey?: string | number; state?: string }[]): Promise<boolean | null> {
+  const probe = makeEngineActiveProbe({ restAddress: "http://engine.local/v2" }, { fetchImpl: searchItemsFetch(items) });
+  return probe("11644");
+}
+
+test("#736: the probe answers `true` for ACTIVE and `false` ONLY for a known-terminal engine state", async () => {
+  assertEquals(await probeAgainst([{ processInstanceKey: "11644", state: "ACTIVE" }]), true);
+  // The wire may carry the key as a JSON number and the state in any casing.
+  assertEquals(await probeAgainst([{ processInstanceKey: 11644, state: "active" }]), true);
+  for (const state of ["COMPLETED", "TERMINATED", "CANCELED", "FAILED"]) {
+    assertEquals(await probeAgainst([{ processInstanceKey: "11644", state }]), false, `${state} is a positive "gone"`);
+  }
+  // Absent from the read model is STILL a positive "gone": the engine answered and does not know it.
+  assertEquals(await probeAgainst([]), false);
+});
+
+test("RED→GREEN #736: a MISSING or UNRECOGNIZED engine state is UNKNOWN truth (`null` → spare), never `false`", async () => {
+  // RED (pre-fix): the probe answered `String(match.state ?? "").toUpperCase() === "ACTIVE"`, so a
+  // partial item (no `state`) or a state outside the enum this app knows read as "gone" and folded the
+  // row — contradicting the probe's own contract that malformed engine truth degrades to `null`.
+  assertEquals(await probeAgainst([{ processInstanceKey: "11644" }]), null, "a missing state is not a confirmed death");
+  assertEquals(await probeAgainst([{ processInstanceKey: "11644", state: "" }]), null);
+  assertEquals(await probeAgainst([{ processInstanceKey: "11644", state: "SUSPENDED" }]), null);
+  // An item for a DIFFERENT key is no match for this one, so that stays "absent" (gone), not unknown.
+  assertEquals(await probeAgainst([{ processInstanceKey: "99999" }]), false);
+});
+
+test("RED→GREEN #736: a malformed search item (no `state`) spares the candidate end-to-end", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  // Past grace, no projection row, and the engine ANSWERS — but its item carries no lifecycle state, so
+  // engine truth is unestablished and the row must survive (RED pre-fix: folded to `orphaned`).
+  seedFeatureRun(raw, "nanobpm/nano-workforce#731", "escalated", "11644");
+  const fetchImpl = engineFetch({ nano: { engine: "merlin" } }, [{ processInstanceKey: "11644" }]);
+
+  const res = await runEngineReconcile(data, { restAddress: "http://engine.local/v2" }, { now: AT, fetchImpl });
+
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='nanobpm/nano-workforce#731'").get() as {
+    status: string;
+  };
+  assertEquals(row.status, "escalated");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+test("RED→GREEN #736: a probe that THROWS is unknown truth — it spares the row instead of aborting the pass", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  seedFeatureRun(raw, "o/r#boom", "escalated", "71506");
+  // `engineActive` is injectable: an implementation that rejects means truth could NOT be established
+  // (spare), and must not bubble out of the pass.
+  const engineActive = async (): Promise<boolean | null> => {
+    throw new Error("engine exploded");
+  };
+
+  const res = await reconcileVanishedInstances(data, { now: AT, runId: "van-1", engineActive });
+
+  assertEquals(res.reason, "no-op");
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#boom'").get() as { status: string };
+  assertEquals(row.status, "escalated");
+  // The pass COMPLETED and recorded its run — pre-fix the throw escaped the transaction and rejected the
+  // whole reconcile, so no `reconcile_runs` row was written at all.
+  const run = raw.prepare("SELECT reason, orphaned_count FROM reconcile_runs WHERE run_id='van-1'").get() as
+    | { reason: string; orphaned_count: number }
+    | undefined;
+  assertEquals(run?.reason, "no-op");
+  assertEquals(run?.orphaned_count, 0);
+});
+
+test("RED→GREEN #736: the probe (network I/O) is never awaited INSIDE the write transaction", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  seedFeatureRun(raw, "o/r#tx", "escalated", "71506");
+
+  // Wrap the gateway so the probe can report how deep in `src.tx(...)` it was awaited. RED (pre-fix):
+  // depth 1 — every candidate row held the SQLite write transaction open across a network round trip
+  // (up to the probe's full timeout on a slow/unreachable engine), delaying every other writer and
+  // slowing/locking boot. GREEN: depth 0 — the probes finish first, and only the guarded UPDATE +
+  // provenance writes run in a short transaction.
+  let depth = 0;
+  const observed: number[] = [];
+  const inner = data.open();
+  const tracked = {
+    open: () => ({
+      query: (sql: string, params?: unknown[]) => inner.query(sql, params),
+      exec: (sql: string, params?: unknown[]) => inner.exec(sql, params),
+      schema: () => inner.schema(),
+      table: (name: string, pk?: string) => inner.table(name, pk),
+      tx: async <T>(fn: (t: DataSource) => Promise<T>): Promise<T> => {
+        depth += 1;
+        try {
+          return await inner.tx(fn);
+        } finally {
+          depth -= 1;
+        }
+      },
+    }),
+  } as unknown as DataLayer;
+
+  const engineActive = async (): Promise<boolean | null> => {
+    observed.push(depth);
+    return false;
+  };
+
+  const res = await reconcileVanishedInstances(tracked, { now: AT, runId: "van-tx", engineActive });
+
+  // Exactly one entry: the seeded row also mirrors into `delivery_units` (same `process_key`), and one
+  // instance is probed once (see the next test) — at depth 0, outside any open write transaction.
+  assertEquals(observed, [0], "the engine-truth probe must be awaited outside any open write transaction");
+  // Hoisting the probe out of the transaction must not weaken the pass: a confirmed-gone row still folds.
+  assertEquals(res.orphanedCount, 1);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#tx'").get() as { status: string };
+  assertEquals(row.status, ORPHANED_STATUS);
+});
+
+test("#736: one instance backing several tracked rows is probed ONCE (engine truth is per instance)", async () => {
+  const { data, raw } = freshData();
+  ensureInstanceState(raw);
+  // A `feature_runs` row is ALSO mirrored into the `delivery_units` aggregate by DB trigger
+  // (db/migrations/089), carrying the same `process_key` — so one vanished instance yields TWO
+  // candidates. Engine truth is per instance, so it must be asked once, not once per row (each probe
+  // can block for its full timeout on a slow engine).
+  seedFeatureRun(raw, "o/r#mirror", "escalated", "71506");
+  const probed: string[] = [];
+  const engineActive = async (key: string): Promise<boolean | null> => {
+    probed.push(key);
+    return false;
+  };
+
+  const res = await reconcileVanishedInstances(data, { now: AT, runId: "van-mirror", engineActive });
+
+  assertEquals(probed, ["71506"], "one probe per distinct instance key");
+  // Folding the base row re-projects its mirror (the sync trigger clears `dispatch_status`), so the
+  // mirror is not folded a second time for the same instance — no duplicate provenance.
+  assertEquals(res.orphaned.map((o) => o.table), ["feature_runs"]);
+  assertEquals(res.orphanedCount, 1);
+  const mirror = raw.prepare("SELECT dispatch_status FROM delivery_units WHERE legacy_key='o/r#mirror'").get() as {
+    dispatch_status: string | null;
+  };
+  assertNotEquals(mirror.dispatch_status, "dispatched");
+});

package/app/reconcile.ts

@@ -38,8 +38,13 @@
 // `reconcileVanishedInstances` drives every such row — active, dispatched, its key absent from
 // `_urban_instance_state`, and PAST A GRACE WINDOW (so a still-starting run not yet projected is
 // spared) — to the same `orphaned` terminal, with a DISTINCT provenance reason so an operator can
-// tell a vanished-instance orphan apart from an epoch-regression one. `runEngineReconcile` runs BOTH
-// passes, so startup and the operator command converge both failure modes in one call.
+// tell a vanished-instance orphan apart from an epoch-regression one. Because `_urban_instance_state`
+// is an app-side projection that can lag / be pruned / be rebuilt while the instance is still ACTIVE
+// on the engine, "no projection row" is NOT proof the instance vanished — so before folding, the pass
+// CROSS-CHECKS ENGINE TRUTH (`/v2/process-instances/search`, issue #736): an instance the engine still
+// reports ACTIVE (or whose truth cannot be established) is SPARED, closing the false-orphan class on
+// deployments whose engine omits the incarnation epoch. `runEngineReconcile` runs BOTH passes, so
+// startup and the operator command converge both failure modes in one call.
 //
 // The provenance is app-owned (not urban's `_urban_write_provenance`, which is a domain-free
 // insert-join sidecar written only inside a job): reconcile runs at boot / over HTTP, outside any
@@ -152,6 +157,15 @@ export interface VanishedReconcileOptions extends ReconcileOptions {
    *  still-starting run (not yet projected into `_urban_instance_state`) is not orphaned prematurely.
    *  Defaults to {@link DEFAULT_VANISHED_GRACE_MS}. */
   graceMs?: number;
+  /** Cross-check against ENGINE TRUTH before orphaning a candidate row (issue #736). Given the row's
+   *  `keyField` (process instance key), it reports whether the engine still considers the instance
+   *  ACTIVE. An ACTIVE instance is NEVER orphaned — the app-side `_urban_instance_state` projection is
+   *  merely lagging — and an instance whose truth could not be established (`null`) is spared too (we
+   *  never orphan what we could not confirm dead). Only a row the engine positively confirms is gone
+   *  (`false`) is folded. When omitted the pass falls back to projection-only behaviour (no live
+   *  cross-check); production always wires one via {@link runEngineReconcile}. See
+   *  {@link makeEngineActiveProbe}. */
+  engineActive?: EngineActiveProbe;
 }
 
 /** Read the incarnation epoch out of a `/v2/topology` body — `nano.incarnation` (or its `epoch`
@@ -189,6 +203,80 @@ export async function probeEngineEpoch(
   }
 }
 
+/** A cross-check against ENGINE TRUTH for one process instance key, used to spare a live instance from
+ *  the vanished-instance pass. Returns:
+ *   • `true`  — the engine reports the instance ACTIVE. It is live; the app-side `_urban_instance_state`
+ *               projection is merely lagging/pruned/rebuilding, so the row MUST NOT be orphaned.
+ *   • `false` — the engine answered and the instance is NOT active: absent from the read model, or in a
+ *               known terminal state ({@link ENGINE_TERMINAL_STATES}). It is genuinely gone in engine
+ *               truth → orphan-eligible.
+ *   • `null`  — engine truth could NOT be established (unreachable, non-2xx, malformed — including an
+ *               item whose `state` is missing or outside {@link ENGINE_TERMINAL_STATES}). We never
+ *               orphan a row we could not confirm dead, so the caller spares it (a transient outage
+ *               must never fold live work). */
+export type EngineActiveProbe = (processKey: string) => Promise<boolean | null>;
+
+/** One item of a `/v2/process-instances/search` result, narrowed to what the engine-truth cross-check
+ *  reads: the instance key (to match the row we probed for) and its lifecycle `state`. Keys are
+ *  stringified defensively (the wire may send a JSON number or string); `state` is the engine's
+ *  lifecycle enum (`ACTIVE`/`COMPLETED`/`CANCELED`/…). */
+interface InstanceSearchStateItem {
+  processInstanceKey?: string | number;
+  state?: string;
+}
+
+/** The lifecycle states that POSITIVELY mean "this instance is no longer running" — urban's
+ *  `ProcessInstanceState` terminals (`COMPLETED`/`TERMINATED`) plus the Camunda-8-parity v2 REST
+ *  terminals (`CANCELED`/`FAILED`), since the probe reads that raw surface rather than the typed
+ *  client. ONLY these may answer `false` (orphan-eligible): a `state` that is missing, empty, or
+ *  outside this set is a partial/malformed read this app cannot interpret, so it degrades to `null`
+ *  ("unknown" → the caller spares the row). Classifying an unrecognized state as "gone" would fold
+ *  live work off a wire shape we misread — the exact failure mode the #736 cross-check exists to stop. */
+const ENGINE_TERMINAL_STATES: ReadonlySet<string> = new Set(["COMPLETED", "TERMINATED", "CANCELED", "FAILED"]);
+
+/** Build an {@link EngineActiveProbe} that queries the engine's own `/v2/process-instances/search` for
+ *  a single process instance key and reports whether the engine still considers it ACTIVE. This is the
+ *  authoritative engine-truth check the vanished-instance pass consults before orphaning: an ACTIVE
+ *  engine instance must NEVER be orphaned regardless of the app-side projection (issue #736), so a
+ *  merlin-style deployment whose `_urban_instance_state` lags no longer false-orphans live work.
+ *  Never throws — every transport/parse failure, and every `state` this app cannot interpret (missing,
+ *  or outside {@link ENGINE_TERMINAL_STATES}), degrades to `null` ("unknown"), which the caller treats
+ *  as "spare" (we never orphan what we could not confirm dead). */
+export function makeEngineActiveProbe(
+  engineRest: { restAddress: string; token?: string },
+  opts: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): EngineActiveProbe {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = engineRest.restAddress.replace(/\/+$/, "");
+  const headers: Record<string, string> = { accept: "application/json", "content-type": "application/json" };
+  if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
+  return async (processKey: string): Promise<boolean | null> => {
+    try {
+      const res = await fetchImpl(`${base}/process-instances/search`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ filter: { processInstanceKey: processKey }, page: { from: 0, limit: 10 } }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 3000),
+      });
+      if (!res.ok) return null;
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = (await res.json()) as { items?: InstanceSearchStateItem[] };
+      const items = body.items ?? [];
+      const match = items.find((it) => it.processInstanceKey != null && String(it.processInstanceKey) === processKey);
+      // Engine answered but the instance is absent from the read model → genuinely gone (not active).
+      if (!match) return false;
+      const state = String(match.state ?? "").trim().toUpperCase();
+      if (state === "ACTIVE") return true;
+      // A KNOWN terminal state is a positive "gone". Anything else — a missing/empty `state`, or one
+      // outside the enum this app can interpret — is a partial or malformed answer, NOT a confirmed
+      // death, so it degrades to `null` and the caller spares the row.
+      return ENGINE_TERMINAL_STATES.has(state) ? false : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
 /** Double-quote a SQL identifier (table/column) so a manifest-declared name is safe to interpolate. */
 function q(id: string): string {
   return `"${id.replace(/"/g, '""')}"`;
@@ -334,19 +422,24 @@ function withinGrace(updated: unknown, nowMs: number, graceMs: number): boolean
   return nowMs - t < graceMs;
 }
 
-/** Orphan every NON-terminal, engine-backed row whose `keyField` (process instance key) has NO
- *  `_urban_instance_state` row — the instance is absent/unknown in engine truth (vanished, issue
- *  #630) — and whose last transition is older than the grace window. Records one
- *  `reconcile_provenance` row per transition (reason {@link RECONCILE_VANISHED_REASON}). Runs inside
- *  the caller's transaction. */
-async function orphanVanishedRows(
+/** A vanished-instance candidate: the row selected for possible orphaning plus the binding shape that
+ *  resolves its physical schema. Selected OUTSIDE any transaction, because the engine-truth
+ *  cross-check that narrows these is network I/O (see {@link confirmVanishedGone}). */
+interface VanishedCandidate {
+  shape: BindingShape;
+  row: OrphanCandidate;
+}
+
+/** SELECT every NON-terminal, engine-backed row whose `keyField` (process instance key) has NO
+ *  `_urban_instance_state` row — the instance is absent/unknown in the app-side read model (vanished,
+ *  issue #630) — and whose last transition is older than the grace window. READ-ONLY and network-free,
+ *  so it is safe to run outside the orphaning transaction. */
+async function selectVanishedCandidates(
   src: DataSource,
-  runId: string,
-  at: string,
   nowMs: number,
   graceMs: number,
-): Promise<OrphanedRow[]> {
-  const orphaned: OrphanedRow[] = [];
+): Promise<VanishedCandidate[]> {
+  const candidates: VanishedCandidate[] = [];
   for (const binding of engineBackedBindings()) {
     const shape = await resolveShape(src, binding);
     if (!shape) continue;
@@ -360,17 +453,79 @@ async function orphanVanishedRows(
         `AND NOT EXISTS (SELECT 1 FROM ${q(INSTANCE_STATE_TABLE)} s WHERE s.process_instance_key = b.${q(shape.keyField)})`,
       [...shape.active],
     );
-    // Re-assert "still no instance-state row" in the guarded UPDATE too, so an instance that reappears
-    // (the poller records it) between the SELECT above and the UPDATE wins the race.
-    const stillVanishedGuard =
-      ` AND NOT EXISTS (SELECT 1 FROM ${q(INSTANCE_STATE_TABLE)} s ` +
-      `WHERE s.process_instance_key = ${q(shape.table)}.${q(shape.keyField)})`;
     for (const row of rows) {
       if (shape.hasUpdatedAt && withinGrace(row.__updated, nowMs, graceMs)) continue;
-      const o = await orphanRow(src, shape, row, RECONCILE_VANISHED_REASON, null, runId, at, stillVanishedGuard);
-      if (o) orphaned.push(o);
+      candidates.push({ shape, row });
     }
   }
+  return candidates;
+}
+
+/** Narrow candidates to the ones ENGINE TRUTH positively confirms are gone (issue #736): the
+ *  `_urban_instance_state` projection is an app-side read model that can lag / be pruned / be rebuilt
+ *  while the instance is still ACTIVE on the engine, so "no projection row" is NOT "instance vanished".
+ *  An ACTIVE instance (`true`) is spared, and one whose truth could not be established (`null` — engine
+ *  unreachable, malformed answer, or a probe that THREW) is spared too: we never orphan a row we could
+ *  not positively confirm is gone, and an injected probe's failure must never abort the pass. Only a
+ *  `false` (engine confirms absent/terminated) survives. Runs OUTSIDE the DB transaction — this is
+ *  network I/O, and awaiting it under an open write transaction would hold the SQLite lock for up to
+ *  the probe's timeout PER ROW, stalling every other writer (including boot). Without a probe (omitted)
+ *  the pass falls back to projection-only behaviour, so every candidate survives. */
+async function confirmVanishedGone(
+  candidates: VanishedCandidate[],
+  engineActive?: EngineActiveProbe,
+): Promise<VanishedCandidate[]> {
+  if (!engineActive) return candidates;
+  // Engine truth is PER INSTANCE, not per row, and one instance can back several tracked rows: the
+  // `delivery_units` aggregate is a DB-trigger mirror of its legacy base row (db/migrations/089) and
+  // carries the same `process_key`, so both are candidates for one vanished instance. Probe each
+  // DISTINCT key once and apply that verdict to every row carrying it — the same answer, without
+  // doubling engine calls that can each block for the probe's full timeout.
+  const verdicts = new Map<string, boolean | null>();
+  const gone: VanishedCandidate[] = [];
+  for (const candidate of candidates) {
+    const key = candidate.row.__key == null ? null : String(candidate.row.__key);
+    // Defensive: the SELECT requires a populated key, so with no key there is nothing to cross-check
+    // and the projection-only verdict stands.
+    if (key == null) {
+      gone.push(candidate);
+      continue;
+    }
+    let verdict = verdicts.get(key);
+    if (verdict === undefined) {
+      try {
+        verdict = await engineActive(key);
+      } catch {
+        // A probe that throws established nothing — treat it exactly like an unreachable engine.
+        verdict = null;
+      }
+      verdicts.set(key, verdict);
+    }
+    if (verdict === false) gone.push(candidate);
+  }
+  return gone;
+}
+
+/** Fold each confirmed-gone candidate to the `orphaned` terminal, recording one
+ *  `reconcile_provenance` row per transition (reason {@link RECONCILE_VANISHED_REASON}). WRITE-ONLY and
+ *  network-free, so the caller's transaction stays short. Runs inside the caller's transaction. */
+async function orphanVanishedCandidates(
+  t: DataSource,
+  candidates: VanishedCandidate[],
+  runId: string,
+  at: string,
+): Promise<OrphanedRow[]> {
+  const orphaned: OrphanedRow[] = [];
+  for (const { shape, row } of candidates) {
+    // Re-assert "still no instance-state row" in the guarded UPDATE (which also re-asserts the exact
+    // status read), so a row that went terminal — or an instance that reappeared, the poller recording
+    // it — between the out-of-transaction SELECT/probe and this UPDATE wins the race.
+    const stillVanishedGuard =
+      ` AND NOT EXISTS (SELECT 1 FROM ${q(INSTANCE_STATE_TABLE)} s ` +
+      `WHERE s.process_instance_key = ${q(shape.table)}.${q(shape.keyField)})`;
+    const o = await orphanRow(t, shape, row, RECONCILE_VANISHED_REASON, null, runId, at, stillVanishedGuard);
+    if (o) orphaned.push(o);
+  }
   return orphaned;
 }
 
@@ -475,9 +630,20 @@ export async function reconcileEngineBackedWork(
  *     it), every dispatched row would look vanished, so the pass is a hard no-op.
  *   • GUARDED — the same status-re-assert as the epoch pass, plus a still-vanished re-check, so a
  *     concurrent terminal write or a reappearing instance wins the race.
- *   • This pass reads the app's OWN last-known projection, not a live probe, so it acts correctly on a
- *     genuinely-vanished instance regardless of transient engine reachability (a live instance keeps
- *     its persisted ACTIVE row across a restart, so it is never mistaken for vanished).
+ *   • ENGINE-TRUTH CROSS-CHECK (issue #736) — the `_urban_instance_state` projection is an app-side
+ *     read model that can lag / be pruned / be rebuilt for an instance that is still ACTIVE on the
+ *     engine, so "no projection row" is NOT "instance vanished". Before folding, the pass consults
+ *     `opts.engineActive` (production wires one from the live engine via {@link makeEngineActiveProbe};
+ *     {@link runEngineReconcile}): an instance the engine reports ACTIVE — or whose truth could not be
+ *     established (engine unreachable, malformed answer, a probe that threw) — is SPARED. Only an
+ *     instance the engine positively confirms is gone is orphaned. Without a cross-check (omitted) the
+ *     pass falls back to projection-only.
+ *   • SHORT TRANSACTION — the cross-check is network I/O, so the candidate SELECT and every probe run
+ *     OUTSIDE `src.tx(...)`; the transaction covers only the guarded UPDATE + provenance writes. A
+ *     slow or unreachable engine therefore cannot hold the SQLite write lock open (for up to the
+ *     probe's timeout per candidate row), stalling other writers or boot. The guards make the split
+ *     safe: a row that went terminal, or an instance that reappeared in the projection, between the
+ *     out-of-transaction read and the in-transaction UPDATE wins the race and is not folded.
  */
 export async function reconcileVanishedInstances(
   data: DataLayer,
@@ -498,8 +664,13 @@ export async function reconcileVanishedInstances(
     return { runId, reason: "no-op", observedEpoch: null, recordedEpoch: null, orphanedCount: 0, orphaned: [] };
   }
 
+  // READ + PROBE first, transaction second: the engine-truth cross-check is network I/O and must never
+  // be awaited under an open write transaction (see SHORT TRANSACTION above).
+  const candidates = await selectVanishedCandidates(src, nowMs, graceMs);
+  const confirmedGone = await confirmVanishedGone(candidates, opts.engineActive);
+
   const orphaned = await src.tx(async (t) => {
-    const rows = await orphanVanishedRows(t, runId, at, nowMs, graceMs);
+    const rows = await orphanVanishedCandidates(t, confirmedGone, runId, at);
     const reason: ReconcileReason = rows.length > 0 ? "instance-vanished" : "no-op";
     await recordRun(t, { runId, at, observedEpoch: null, recordedEpoch: null, reason, orphanedCount: rows.length });
     return rows;
@@ -561,6 +732,12 @@ export async function runEngineReconcile(
   const vanished = await reconcileVanishedInstances(data, {
     ...opts,
     runId: `${epoch.runId}-vanished`,
+    // Cross-check ENGINE TRUTH before orphaning any vanished-instance candidate (issue #736): an
+    // instance the engine still reports ACTIVE is spared even when its `_urban_instance_state`
+    // projection is absent (the merlin false-orphan: the projection lags, the instance is live). A
+    // caller-supplied `engineActive` wins (tests inject a deterministic one); otherwise build one from
+    // the same engine address/token the epoch probe used.
+    engineActive: opts.engineActive ?? makeEngineActiveProbe(engineRest, { fetchImpl: opts.fetchImpl }),
   });
 
   const orphaned = [...epoch.orphaned, ...vanished.orphaned];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.182.3",
+  "version": "0.183.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -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)`,