@nanobpm/nano-workforce 0.201.3 → 0.201.5

package/app/agentOutputEnvelope.test.ts

@@ -0,0 +1,464 @@
+// Regression guard for issue #887 — an external-agent job's completion variables must not clobber
+// engine-owned process state.
+//
+// The defect (merlin PI 351101, incident 363350 at `gw-guard`): a `senior:pr-review` job returned
+// `round: "4"` (a STRING) alongside its result. The engine merges EVERY variable an external agent
+// returns into process scope UNFILTERED (the `io.nanobpm.dataEnvelope.out` shape is typing-only — no
+// runtime filtering/coercion), so the agent's string overwrote the engine-owned integer counter
+// `round`. The next `gw-guard` evaluation (`round >= maxRounds`) then raised
+//   "comparison not defined for string and number"
+// and wedged the loop on an unrecoverable incident.
+//
+// Failure CLASS: any external-agent task can corrupt engine-owned state (round, maxRounds, the
+// adversarial/ack/husk counters, prKey…) by name collision or type drift. The categorical fix snapshots
+// each engine-owned control variable into a task-LOCAL input before the agent runs and RESTORES it from
+// that snapshot on the task's output mapping, so an agent completion can never alter it (the snapshot is
+// the pre-merge value; an output `source="=round"` would read the already-clobbered merge — proven by the
+// `app/agentCompletion*`/testkit notes). The agent's real outputs (status/summary/question for a review
+// round, findings for the adversarial pass, the scope verdict) still flow through untouched.
+//
+// These deploy the committed convergence-loop into the real WASM engine and drive a token to `gw-guard`
+// with an agent that echoes `round: "4"`; the fix means NO incident is raised and `round` stays the
+// engine-managed integer.
+import { after, test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { createWasmEngineClient, type WasmEngineClient } from "@nanobpm/urban-testkit";
+
+const MODEL = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+
+type Output = Record<string, unknown>;
+type Responder = Output | ((job: { variables: Record<string, unknown> }) => Output);
+
+const ALL_JOB_TYPES = [
+  "senior:pr-review",
+  "senior:adversarial-review",
+  "pr.capture-head",
+  "pr.persist-round",
+  "pr.progress-check",
+  "pr.converge-gate",
+  "senior:scope-classify",
+  "pr.finalize",
+  "pr.persist-escalation",
+  "pr.answer-escalation",
+] as const;
+
+const DEFAULT_RESPONSES: Record<string, Responder> = {
+  "senior:pr-review": { status: "addressed", summary: "fixed" },
+  "senior:adversarial-review": { adversarialFindings: "", adversarialSummary: "clean" },
+  "pr.capture-head": { roundEntryHead: "sha-entry" },
+  "pr.persist-round": {},
+  "pr.progress-check": { progressed: true },
+  "pr.converge-gate": { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false },
+  "senior:scope-classify": { scopeBlocked: false, scopeBlockReason: "" },
+  "pr.finalize": {},
+  "pr.persist-escalation": { escalated: true },
+  "pr.answer-escalation": {},
+};
+
+const DEFAULT_VARS: Record<string, unknown> = {
+  prKey: "o/r#1",
+  repo: "o/r",
+  prNumber: 1,
+  prUrl: "https://example.test/pr/1",
+  round: 1,
+  maxRounds: 20,
+  reviewWaitTimeout: "PT30M",
+  ackRetryRound: 0,
+  ackRetryMax: 2,
+  abandonUrl: "https://hooks.test/abandon?token=seed",
+  abandonBrief: "\n\n---\nAbort if cancelled: curl …",
+  status: null,
+  question: null,
+  summary: null,
+  answer: null,
+  scopePending: false,
+  scopeAnswer: null,
+  convergeBlocked: null,
+  convergeBlockReason: null,
+  convergeAckOnly: null,
+  reviewStale: null,
+  roundEntryHead: null,
+  huskRetries: 0,
+  progressed: true,
+  escalated: null,
+  humanApproval: false,
+  convergeOnly: false,
+};
+
+const engines: WasmEngineClient[] = [];
+after(async () => {
+  await Promise.all(engines.map((e) => e.close()));
+});
+
+async function boot(opts: { responses?: Record<string, Responder>; vars?: Record<string, unknown> } = {}) {
+  const engine = await createWasmEngineClient();
+  engines.push(engine);
+  await engine.deployResources([{ name: "convergence-loop.bpmn", content: MODEL, contentType: "text/xml" }]);
+  const responses = { ...DEFAULT_RESPONSES, ...(opts.responses ?? {}) };
+  for (const jobType of ALL_JOB_TYPES) {
+    const responder = responses[jobType];
+    await engine.registerWorker(jobType, (job) =>
+      typeof responder === "function" ? responder(job as { variables: Record<string, unknown> }) : (responder ?? {}),
+    );
+  }
+  const created = await engine.createInstance({
+    processDefinitionId: "convergence-loop",
+    awaitCompletion: false,
+    variables: { ...DEFAULT_VARS, ...(opts.vars ?? {}) },
+  });
+  return { engine, processInstanceKey: created.processInstanceKey };
+}
+
+function instanceVars(engine: WasmEngineClient): Record<string, unknown> {
+  const snap = engine.snapshot() as { instances?: { variables?: Record<string, unknown> }[] };
+  return snap.instances?.[0]?.variables ?? {};
+}
+
+/** Read one variable's deserialized value via the engine read channel — works on a COMPLETED instance. */
+async function variableValue(engine: WasmEngineClient, processInstanceKey: string, name: string): Promise<unknown> {
+  const rows = await engine.searchVariables({ processInstanceKey, name });
+  const row = rows.find((v) => v.name === name);
+  assert(row, `expected variable ${name} to be present`);
+  return JSON.parse(row.value);
+}
+
+test("a review-round agent echoing round:\"4\" does not clobber the engine-owned counter or wedge gw-guard", async () => {
+  const { engine } = await boot({
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", round: "4" } },
+  });
+  // gw-guard evaluates `round >= maxRounds`. If the agent's string "4" clobbered `round`, the engine
+  // raises "comparison not defined for string and number" and parks the token on an open incident.
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident must be raised; got: ${JSON.stringify(incidents)}`);
+  // The engine-owned counter must remain the integer it was — untouched by the agent's echo.
+  assertEquals(instanceVars(engine).round, 1, "engine-owned `round` must stay the integer 1, unclobbered");
+});
+
+test("a review-round agent echoing numeric engine counters cannot alter them", async () => {
+  // A well-formed numeric echo must still be ignored — the agent owns NONE of these control variables.
+  const { engine } = await boot({
+    responses: {
+      "senior:pr-review": { status: "addressed", summary: "fixed", round: 99, maxRounds: 1, prKey: "evil/repo#999" },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.round, 1, "round must be unchanged");
+  assertEquals(vars.maxRounds, 20, "maxRounds must be unchanged");
+  assertEquals(vars.prKey, "o/r#1", "prKey correlation key must be unchanged");
+});
+
+test("a review-round agent echoing PR identity inputs cannot alter them", async () => {
+  // `repo`/`prNumber`/`prUrl` are the agent's declared *inputs* (PrReviewRoundIn), not its outputs —
+  // but the engine merges a completion UNFILTERED, so an input-echo would replace the valid process
+  // identity that `progress-check`, `converge-gate`, and `finalize` go on to read. The snapshot/restore
+  // guard must pin them.
+  const { engine } = await boot({
+    responses: {
+      "senior:pr-review": {
+        status: "addressed",
+        summary: "fixed",
+        repo: "evil/repo",
+        prNumber: 999,
+        prUrl: "https://evil.test/pr/999",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.repo, "o/r", "repo must be unchanged");
+  assertEquals(vars.prNumber, 1, "prNumber must be unchanged");
+  assertEquals(vars.prUrl, "https://example.test/pr/1", "prUrl must be unchanged");
+});
+
+// The adversarial reviewer (`senior:adversarial-review`) and scope classifier
+// (`senior:scope-classify`) are hardened by the SAME snapshot/restore mappings as `review-round`;
+// these drive each of those tasks with an engine-owned-field echo so removing either task's guard
+// turns this suite red (the `review-round` regressions above would stay green).
+
+test("an adversarial-review agent echoing engine counters cannot alter them", async () => {
+  // advMax: 1 makes the adversarial pass due on round 1. The agent echoes `advPass`/`advMax` (and a
+  // counter) as the WRONG type; the guard must keep the engine's own increment (0 → 1) and budget.
+  const { engine } = await boot({
+    vars: { advMax: 1 },
+    responses: {
+      "senior:adversarial-review": { adversarialFindings: "", adversarialSummary: "clean", advPass: "7", advMax: "0", round: "9" },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.advPass, 1, "advPass must be the engine increment (0 → 1), not the agent's \"7\"");
+  assertEquals(vars.advMax, 1, "advMax budget ceiling must be unchanged");
+  assertEquals(vars.round, 1, "round must be unchanged");
+});
+
+test("an adversarial-review agent echoing PR identity inputs cannot alter them", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1 },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        repo: "evil/repo",
+        prNumber: 999,
+        prUrl: "https://evil.test/pr/999",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.repo, "o/r", "repo must be unchanged");
+  assertEquals(vars.prNumber, 1, "prNumber must be unchanged");
+  assertEquals(vars.prUrl, "https://example.test/pr/1", "prUrl must be unchanged");
+});
+
+test("a scope-classify agent echoing engine-owned fields cannot alter them", async () => {
+  // Drive to the scope classifier via a `converged` review. The classifier echoes prKey + the PR
+  // identity inputs; the guard must keep them. The instance runs to completion, so read the
+  // variables back through the read channel (a completed instance's `snapshot().variables` is folded).
+  const { engine, processInstanceKey } = await boot({
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        prKey: "evil/repo#999",
+        repo: "evil/repo",
+        prNumber: 999,
+        prUrl: "https://evil.test/pr/999",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "prKey"), "o/r#1", "prKey correlation key must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "repo"), "o/r", "repo must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "prNumber"), 1, "prNumber must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "prUrl"), "https://example.test/pr/1", "prUrl must be unchanged");
+});
+
+// ---------------------------------------------------------------------------
+// Issue #887 (round 3): the seeded merge-control gates `humanApproval` and
+// `convergeOnly` are ALSO engine-owned and must survive an agent completion.
+// A converged review that echoes `humanApproval:false` would bypass `gw-approval`
+// (skip the required human merge approval), and `convergeOnly:false` would hand a
+// review-only PR to the merge loop. The snapshot/restore guard pins both.
+//
+// `humanApproval` is MONOTONIC (false→true only — the host flips it true via
+// `engine.setVariables` when a gated caller adopts a live loop, app/service.ts).
+// So its restore is `(guardHumanApproval = true) or (humanApproval = true)`: it
+// recovers a snapshot-true against an agent's false AND preserves a concurrent
+// host-set true, but never lets an agent force it back to false.
+// ---------------------------------------------------------------------------
+
+test("a review-round agent echoing humanApproval:false cannot bypass the approval gate", async () => {
+  // Seeded gated (humanApproval:true). The agent echoes false; the monotonic restore must keep it true.
+  const { engine } = await boot({
+    vars: { humanApproval: true },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", humanApproval: false } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).humanApproval, true, "seeded humanApproval:true must survive the agent's false echo");
+});
+
+test("a review-round agent echoing convergeOnly:false cannot re-target a review-only run at the merge loop", async () => {
+  // Seeded review-only (convergeOnly:true). The agent echoes false; the restore must keep it true.
+  const { engine } = await boot({
+    vars: { convergeOnly: true },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", convergeOnly: false } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).convergeOnly, true, "seeded convergeOnly:true must survive the agent's false echo");
+});
+
+test("an adversarial-review agent echoing humanApproval/convergeOnly cannot alter the seeded gates", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1, humanApproval: true, convergeOnly: true },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        humanApproval: false,
+        convergeOnly: false,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.humanApproval, true, "humanApproval gate must be unchanged");
+  assertEquals(vars.convergeOnly, true, "convergeOnly flag must be unchanged");
+});
+
+test("a scope-classify agent echoing humanApproval/convergeOnly cannot alter the seeded gates", async () => {
+  // Drive to the scope classifier via a `converged` review with the gates seeded true; the classifier
+  // echoes them false. With humanApproval:true the instance then parks at the merge-approval user task
+  // (still ACTIVE), so read the gates back through the variables channel after classify-scope ran.
+  const { engine, processInstanceKey } = await boot({
+    vars: { humanApproval: true, convergeOnly: true },
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        humanApproval: false,
+        convergeOnly: false,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "humanApproval"), true, "humanApproval gate must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "convergeOnly"), true, "convergeOnly flag must be unchanged");
+});
+
+// ---------------------------------------------------------------------------
+// Issue #887 (round 4 — Copilot "previously missed"): `reviewStale` and
+// `roundEntryHead` are ALSO process-owned and readable by downstream decisions,
+// so an agent completion must not overwrite them:
+//   * `f_guardMax` escalates only when `round >= maxRounds and reviewStale != true`
+//     — a forged `reviewStale:true` suppresses the max-round escalation.
+//   * `check-progress` (pr.progress-check) consumes `roundEntryHead` as the
+//     within-round baseline — a forged head falsifies the progress decision.
+// The snapshot/restore guard pins both on all three agent tasks.
+// ---------------------------------------------------------------------------
+
+test("a review-round agent echoing reviewStale:true cannot suppress the max-round escalation", async () => {
+  // Seeded at the max-round boundary with reviewStale false. The agent echoes reviewStale:true;
+  // without the guard, gw-guard's `reviewStale != true` arm would go false and suppress escalation.
+  const { engine } = await boot({
+    vars: { round: 20, maxRounds: 20, reviewStale: false },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", reviewStale: true } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).reviewStale, false, "seeded reviewStale:false must survive the agent's true echo");
+});
+
+test("a review-round agent echoing a forged roundEntryHead cannot falsify the progress baseline", async () => {
+  // capture-head seeds roundEntryHead="sha-entry"; the agent echoes a forged head. The restore must keep it.
+  const { engine } = await boot({
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", roundEntryHead: "sha-forged" } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(instanceVars(engine).roundEntryHead, "sha-entry", "captured roundEntryHead must survive the agent's forged echo");
+});
+
+test("an adversarial-review agent echoing reviewStale/roundEntryHead cannot alter them", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1, reviewStale: false },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        reviewStale: true,
+        roundEntryHead: "sha-forged",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.reviewStale, false, "reviewStale must be unchanged");
+  assertEquals(vars.roundEntryHead, "sha-entry", "roundEntryHead must be unchanged");
+});
+
+test("a scope-classify agent echoing reviewStale/roundEntryHead cannot alter them", async () => {
+  // Drive to the scope classifier via a `converged` review; the classifier echoes both. With
+  // humanApproval:false the instance runs to completion, so read the vars back via the channel.
+  const { engine, processInstanceKey } = await boot({
+    vars: { reviewStale: false },
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        reviewStale: true,
+        roundEntryHead: "sha-forged",
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "reviewStale"), false, "reviewStale must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "roundEntryHead"), "sha-entry", "roundEntryHead must be unchanged");
+});
+
+// ---------------------------------------------------------------------------
+// Issue #887 (round 5 — Copilot "previously missed"): `abandonUrl` and
+// `abandonBrief` are ALSO seeded engine-owned state readable by downstream
+// persistence and prompt mappings:
+//   * `abandonUrl` is the cooperative-abandon capability recorded by
+//     `pr.persist-round`/`pr.persist-escalation`/`pr.finalize` (EscalationIn.abandonUrl,
+//     PrPersistRoundIn.abandonUrl, PrFinalizeIn.abandonUrl) — a forged echo
+//     redirects the abandon token persisted for a human.
+//   * `abandonBrief` feeds the `appendPrompt` input of the NEXT agent task
+//     (`=(if (abandonBrief = null) then "" else abandonBrief)`) — a non-string
+//     echo makes that later prompt mapping carry a non-string / wrong brief.
+// The snapshot/restore guard pins both on all three agent tasks. (The reserved
+// dotted `io.nanobpm.agentTask` envelope was DECLINED — it has no FEEL-path
+// access and a backtick-escaped restore, untested on this engine, would null the
+// fleet-critical repository envelope; see the PR discussion.)
+
+test("a review-round agent echoing abandonUrl/abandonBrief cannot clobber the seeded capability or brief", async () => {
+  const { engine } = await boot({
+    responses: {
+      "senior:pr-review": {
+        status: "addressed",
+        summary: "fixed",
+        abandonUrl: "https://evil.test/abandon?token=forged",
+        abandonBrief: 42,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.abandonUrl, "https://hooks.test/abandon?token=seed", "seeded abandonUrl must survive the agent's forged echo");
+  assertEquals(vars.abandonBrief, "\n\n---\nAbort if cancelled: curl …", "seeded abandonBrief must survive the agent's non-string echo");
+});
+
+test("an adversarial-review agent echoing abandonUrl/abandonBrief cannot alter them", async () => {
+  const { engine } = await boot({
+    vars: { advMax: 1 },
+    responses: {
+      "senior:adversarial-review": {
+        adversarialFindings: "",
+        adversarialSummary: "clean",
+        abandonUrl: "https://evil.test/abandon?token=forged",
+        abandonBrief: 42,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const vars = instanceVars(engine);
+  assertEquals(vars.abandonUrl, "https://hooks.test/abandon?token=seed", "abandonUrl must be unchanged");
+  assertEquals(vars.abandonBrief, "\n\n---\nAbort if cancelled: curl …", "abandonBrief must be unchanged");
+});
+
+test("a scope-classify agent echoing abandonUrl/abandonBrief cannot alter them", async () => {
+  const { engine, processInstanceKey } = await boot({
+    responses: {
+      "senior:pr-review": { status: "converged", summary: "done" },
+      "senior:scope-classify": {
+        scopeBlocked: false,
+        scopeBlockReason: "",
+        abandonUrl: "https://evil.test/abandon?token=forged",
+        abandonBrief: 42,
+      },
+    },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  assertEquals(await variableValue(engine, processInstanceKey, "abandonUrl"), "https://hooks.test/abandon?token=seed", "abandonUrl must be unchanged");
+  assertEquals(await variableValue(engine, processInstanceKey, "abandonBrief"), "\n\n---\nAbort if cancelled: curl …", "abandonBrief must be unchanged");
+});

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

@@ -9,7 +9,8 @@ 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";
+import { compileDeliveryGraph } from "../../deliveryGraphCompiler.ts";
+import { agentTaskTypesMissingExternalMarker, missingExternalMarkerAgentTaskTypes, promptBearingTaskTypes } from "./job-types.ts";
 
 const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
 
@@ -72,3 +73,31 @@ test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent task carries the e
   // Sanity: the models really do declare agent tasks (guard is not vacuously green).
   assert(anyAgentTasks, "the deployed models declare prompt-bearing agent tasks");
 });
+
+test("DEFECT-CLASS GUARD (compiler output, issue #884): every COMPILED delivery-graph agent cell carries the marker", async () => {
+  // The hand-authored corpus above is only HALF the class — the delivery-graph COMPILER
+  // (`app/deliveryGraphCompiler.ts`) is the other producer of agent service tasks, and it emitted
+  // cells with NO `agentDefinition` until #884: every delivery-graph agent run failed AgentInstance
+  // creation (`… has no agentDefinition`) and persisted no durable transcript (269 failed creates on
+  // omarchy). Per the resolved "Decide" half of #884 (Option (a), PR #886 review) a compiled cell is
+  // prompt-LESS (no base-prompt link), so the prompt-keyed scanner cannot see it — it is the
+  // type-keyed half of the union scanner (`missingExternalMarkerAgentTaskTypes`, keyed by the
+  // `<rank>:<task>` colon-form type) that sees these cells. Apply the SAME union to the compiler's
+  // OUTPUT so a compiler regression that drops the marker fails here — not silently at runtime.
+  const r = await compileDeliveryGraph({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+    ],
+    edges: [{ from: "impl", to: "review" }],
+  });
+  assert(r.ok, `expected the graph to compile, got ${JSON.stringify(r)}`);
+  // The compiled agent cells are prompt-LESS (Option (a)), so the prompt-keyed scan sees none — the
+  // union's type-keyed half is what covers them.
+  assertEquals(promptBearingTaskTypes(r.bpmn), []);
+  const missing = missingExternalMarkerAgentTaskTypes(r.bpmn);
+  assert(
+    missing.length === 0,
+    `compiled delivery-graph agent cell(s) missing <zeebe:agentDefinition agentType="external" /> — ${missing.join(", ")}`,
+  );
+});

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

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 import { assert, assertEquals } from "#test-assert";
 import type { Capability } from "@nanobpm/agentic/protocol";
 import { crewResolver } from "./crew-vocab.ts";
-import { jobTypeToRoutingToken, promptBearingTaskTypes } from "./job-types.ts";
+import { externalAgentTaskTypesMissingMarker, jobTypeToRoutingToken, missingExternalMarkerAgentTaskTypes, promptBearingTaskTypes } from "./job-types.ts";
 
 const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
 
@@ -105,3 +105,135 @@ test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent job type resolves
     );
   }
 });
+
+test("externalAgentTaskTypesMissingMarker flags an UNMAPPED (prompt-less) agent task with no marker", () => {
+  // The prompt-keyed scanner (`agentTaskTypesMissingExternalMarker`) cannot see this block — it has no
+  // prompt link. The marker scan must key on the colon-form job type ALONE (issue #886 review): a
+  // compiled delivery-graph cell for a bespoke `senior:<task>` (no deployed base prompt, deliberately
+  // prompt-less) must still carry the marker or it runs transcript-less.
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke"]);
+});
+
+test("externalAgentTaskTypesMissingMarker passes a marked prompt-less 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:bespoke" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), []);
+});
+
+test("externalAgentTaskTypesMissingMarker flags a marked-outside-extensionElements task (placement contract)", () => {
+  // A marker sitting OUTSIDE `<bpmn:extensionElements>` is ignored by the engine, so it must not
+  // "cover" the task here either (the same placement scope the prompt-keyed scanner enforces).
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <zeebe:agentDefinition agentType="external" />
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke"]);
+});
+
+test("externalAgentTaskTypesMissingMarker ignores malformed/non-agent types (no false positives)", () => {
+  // Only a `<rank>:<task>` colon-form type (the `jobTypeToRoutingToken` grammar) keys a block as an
+  // agent task: a dot-form host job, a typeless block, and a malformed colon form are all out of
+  // scope — the scanner must not flag them as unmarked agents.
+  const xml = `
+    <bpmn:serviceTask id="host1">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host2">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature:extra" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host3">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host4">
+      <bpmn:extensionElements>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), []);
+});
+
+test("missingExternalMarkerAgentTaskTypes unions BOTH scanners — catches a prompt-bearing AND a prompt-less unmarked agent task", () => {
+  // The single "every agent task carries the external marker" invariant (PR #886 review): a
+  // prompt-BEARING senior:* task that loses its marker is caught only by the prompt-keyed scanner,
+  // while a prompt-LESS senior:* task that loses its marker is caught only by the type-keyed scanner.
+  // Scanning by just one leaves the other's blind spot open, so the union must flag BOTH in one pass.
+  const xml = `
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="bespoke">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), ["senior:feature", "senior:bespoke"]);
+});
+
+test("missingExternalMarkerAgentTaskTypes passes when every agent task is marked and ignores host tasks", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="bespoke">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), []);
+});
+
+test("missingExternalMarkerAgentTaskTypes de-duplicates a type caught by both scanners", () => {
+  // A prompt-bearing task missing its marker is seen by BOTH the prompt-keyed and the type-keyed
+  // scanner; the union must report it ONCE, not twice.
+  const xml = `
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), ["senior:feature"]);
+});