@nanobpm/nano-workforce 0.201.3 → 0.201.5

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

@@ -140,6 +140,63 @@ export function agentTaskTypesMissingExternalMarker(xml: string): string[] {
   return missing;
 }
 
+/**
+ * Scan one BPMN document for the job types of agent service tasks — keyed by their `<rank>:<task>`
+ * colon-form `<zeebe:taskDefinition type>` ALONE, NOT by a prompt link — that are MISSING the
+ * engine-native AgentTask marker `<zeebe:agentDefinition agentType="external" />` (issue #884,
+ * PR #886 review). The prompt-keyed scanner (`agentTaskTypesMissingExternalMarker`) is blind to a
+ * DELIBERATELY prompt-less agent task — and EVERY compiled delivery-graph cell is prompt-less (the
+ * resolved #884 "Decide", Option (a): the cell carries the marker alone and is steered by its
+ * per-node `appendPrompt`, never a linked base prompt) — so a marker regression on exactly those
+ * cells would pass that scan vacuously. This scan keys a service task as an AGENT by the same grammar
+ * the crew bridge uses (`jobTypeToRoutingToken`: a single-colon `<rank>:<task>` whose rank is a bare
+ * routing segment), which needs no prompt link, so EVERY agent task — prompt-bearing or not — is
+ * inspected for the marker independently of its prompt status. A dot-form host job (`pr.finalize`),
+ * a typeless block, and a malformed colon form (`senior:feature:extra`) are not agent job types and
+ * are ignored (no false positives). The marker check is scoped to the block's
+ * `<bpmn:extensionElements>` (the engine-honoured PLACEMENT scope, via `extensionElementsOf`) — a
+ * marker sitting outside `extensionElements` is ignored by the engine, so it must not "cover" a
+ * task here either. Returns the offending task types in first-occurrence order (empty when every
+ * agent task is marked).
+ */
+export function externalAgentTaskTypesMissingMarker(xml: string): string[] {
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    if (type === undefined || jobTypeToRoutingToken(type) === undefined) continue;
+    if (EXTERNAL_AGENT_MARKER.test(extensionElementsOf(block))) continue;
+    if (seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}
+
+/**
+ * The SINGLE "every agent service task carries the engine-native `<zeebe:agentDefinition
+ * agentType="external" />` marker" invariant (issue #745/#884, PR #886 review), as the UNION of both
+ * marker scanners. The two scanners each have a blind spot: `agentTaskTypesMissingExternalMarker` keys
+ * a task as an agent by its PROMPT link, so it cannot see a deliberately prompt-less agent cell;
+ * `externalAgentTaskTypesMissingMarker` keys it by its `<rank>:<task>` colon-form type, so it covers
+ * the prompt-less case but is the newer path. Scanning a corpus with only one leaves the other's blind
+ * spot open — a hand-authored (or compiled) `senior:*` task that loses BOTH its prompt link and its
+ * marker would pass a prompt-keyed-only gate. Every producer of agent tasks (the hand-authored corpus
+ * AND the delivery-graph compiler) is checked against THIS union, so neither half can regress through
+ * the other's blind spot. Returns the distinct offending task types in first-occurrence order (the
+ * prompt-keyed matches first, then any type-keyed-only ones), empty when every agent task is marked.
+ */
+export function missingExternalMarkerAgentTaskTypes(xml: string): string[] {
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  for (const type of [...agentTaskTypesMissingExternalMarker(xml), ...externalAgentTaskTypesMissingMarker(xml)]) {
+    if (seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}
+
 /**
  * Scan one BPMN document for the job types of agent service tasks that OPT OUT of the harness
  * `--auto` reconciliation (issue #779) — those carrying `<zeebe:property

package/app/contracts.ts

@@ -538,9 +538,9 @@ export const WIRE_CONTRACTS = {
   "agentTask.agentDefinition": {
     category: "wire",
     name: "agentTask.agentDefinition",
-    owner: "resources/processes/*.bpmn",
+    owner: "resources/processes/*.bpmn + app/deliveryGraphCompiler.ts",
     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 — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
+      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. The class is EVERY agent service task the app generates (issue #884): the hand-authored corpus AND every delivery-graph-compiler `agent` cell. The compiler emits the marker on EVERY cell and — per the resolved \"Decide\" half of #884 (Option (a), PR #886 review) — NO base-prompt link: the hand-authored process prompts are process-specific contracts (they require process variables and a `feat/<task.id>` branch the generic compiled cell never supplies), so a compiled cell is deliberately prompt-LESS and steered by its per-node `appendPrompt` alone. `npm run check:agent-definitions` (scripts/check-agent-definitions.ts, in CI) gates BOTH producers: it scans the compiled output with the prompt-keyed `agentTaskTypesMissingExternalMarker` AND the prompt-link-independent `externalAgentTaskTypesMissingMarker` (an agent task is keyed by its `<rank>:<task>` colon-form type alone, so a marker regression on a prompt-less cell cannot hide). Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
     shape: '<zeebe:agentDefinition agentType="external" /> (sibling of <zeebe:taskDefinition> in a senior:* service task\'s extensionElements)',
   },
   "agentTask.autoSubscribe": {

package/app/deliveryGraphCompiler.test.ts

@@ -14,6 +14,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { missingExternalMarkerAgentTaskTypes } from "./agentic/vocab/job-types.ts";
 import { compileDeliveryGraph, digestInvisibleRawValues, graphCarriesRedactedSecrets, nodeDisplay, redactFreeText, resumeValidVar } from "./deliveryGraphCompiler.ts";
 import { isDeliveryEscalationTwin } from "./deliveryHuman.ts";
 
@@ -158,6 +159,86 @@ test("trust bound: every node inlines an embedded subProcess delegating to an al
   assert(/<bpmn:userTask id="delivery-human-task__n\d+__esc"/.test(r.bpmn), "a bounded node inlines an escalation user task");
 });
 
+test("#884 agentDefinition: every compiled agent cell carries the engine-native AgentTask marker (durable transcript)", async () => {
+  // Issue #884: a compiled `agent` cell's service task carried NO
+  // `<zeebe:agentDefinition agentType="external"/>`, so the engine refused to attach an AgentInstance
+  // to it (`createAgentInstance failed — … has no agentDefinition`) and every delivery-graph agent run
+  // persisted NO durable agentic transcript. The hand-authored processes declare the marker on every
+  // `senior:*` task (issue #745); the compiler must emit it on every agent cell it generates — the
+  // defect CLASS is "every agent service task the app generates", so this guards the compiler output
+  // through the SAME canonical union scanner (`missingExternalMarkerAgentTaskTypes`, the one the
+  // repo-wide gate in `check-agent-definitions.ts` uses) rather than a second, driftable regex.
+  const r = await compileOk(RELEASE_RUNBOOK);
+  // RELEASE_RUNBOOK has exactly one agent node (`open-b` → `senior:feature`); its compiled service
+  // task is `<el>_task`. A compiled agent cell is prompt-LESS (the resolved #884 "Decide", Option (a)),
+  // so it is the type-keyed half of the union scanner (keyed by the `<rank>:<task>` colon-form type)
+  // that sees it — and the marker must be present on THAT cell, not merely somewhere in the document
+  // (a stray marker on a DIFFERENT element would not make THIS cell eligible for AgentInstance minting).
+  const taskBlock = [...r.bpmn.matchAll(/<bpmn:serviceTask id="n\d+_task"[\s\S]*?<\/bpmn:serviceTask>/g)]
+    .map((m) => m[0])
+    .find((b) => b.includes('<zeebe:taskDefinition type="senior:feature" />')) ?? "";
+  assert(taskBlock !== "", "the agent node compiles to an inner senior:feature service task");
+  const ext = /<bpmn:extensionElements>[\s\S]*?<\/bpmn:extensionElements>/.exec(taskBlock)?.[0] ?? "";
+  assert(
+    /<zeebe:agentDefinition agentType="external" \/>/.test(ext),
+    `the compiled agent cell carries <zeebe:agentDefinition agentType="external" /> inside its extensionElements, got:\n${taskBlock}`,
+  );
+  // The marker is a SIBLING of the dispatch verb, which stays (per #464): both must be present.
+  assert(/<zeebe:taskDefinition type="senior:feature" \/>/.test(ext), "the dispatch verb stays alongside the marker");
+  // And the CANONICAL union scanner — the one the repo-wide guard applies — finds NO unmarked agent
+  // task in the whole compiled document (it keys an agent by its colon-form type, which every compiled
+  // agent cell carries; a connector/wait/host task is not colon-form and is correctly ignored).
+  assertEquals(missingExternalMarkerAgentTaskTypes(r.bpmn), []);
+});
+
+test("#884 agentDefinition: EVERY agent cell in a multi-agent graph is marked (not just the first)", async () => {
+  // A marker emitted once (or only on a specific shape) would leave sibling agent cells transcript-less
+  // — the 269 failed creates on omarchy came from several processes. Compile a graph whose agent nodes
+  // differ (distinct job types, one with a repo spec + emits, one bare) and assert EVERY compiled
+  // `<el>_task` service task carries the marker inside its own extensionElements.
+  const r = await compileOk({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", repository: "nanobpm/nano-workforce", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+      { id: "ship", kind: "agent", agent: { jobType: "senior:trial-merge", prompt: "merge it" } },
+    ],
+    edges: [
+      { from: "impl", to: "review" },
+      { from: "review", to: "ship" },
+    ],
+  });
+  const taskBlocks = [...r.bpmn.matchAll(/<bpmn:serviceTask id="(n\d+_task)"[\s\S]*?<\/bpmn:serviceTask>/g)];
+  assertEquals(taskBlocks.length, 3, "all three agent nodes compile to an inner service task");
+  for (const [block, id] of taskBlocks) {
+    const ext = /<bpmn:extensionElements>[\s\S]*?<\/bpmn:extensionElements>/.exec(block)?.[0] ?? "";
+    assert(
+      /<zeebe:agentDefinition agentType="external" \/>/.test(ext),
+      `agent cell ${id} is missing <zeebe:agentDefinition agentType="external" /> in its extensionElements`,
+    );
+  }
+});
+
+test("#884 prompt-less: a compiled agent cell carries NO base-prompt link (Option (a))", async () => {
+  // The resolved "Decide" half of #884 (Option (a), PR #886 review): a compiled agent cell is
+  // deliberately prompt-LESS. The hand-authored process prompts (`prompts/feature.md`, …) are
+  // process-specific contracts — they require process variables (`variables.task`/`variables.issue`)
+  // and a `feat/<task.id>` branch the generic compiled cell never supplies (it seeds only
+  // `{jobType, appendPrompt, timeout}` and the harness provisions `feat/<node.id>`, #776) — so linking
+  // one hands the cell instructions referencing missing inputs and a conflicting branch. The cell is
+  // steered by its per-node `appendPrompt` alone; the marker alone fixes the createAgentInstance
+  // failure. Pin that NO compiled agent cell emits a prompt `linkedResource` — for a mapped-looking
+  // type, a bespoke type, AND a prototype-chain jobType (which must never resolve to a bogus link).
+  for (const jobType of ["senior:feature", "senior:pr-review", "senior:no-such-prompt", "constructor", "__proto__", "toString"]) {
+    const r = await compileOk({ nodes: [{ id: "p", kind: "agent", agent: { jobType } }], edges: [] });
+    assert(
+      !r.bpmn.includes('linkName="prompt"'),
+      `compiled agent cell ${JSON.stringify(jobType)} must link NO base prompt (prompt-less, Option (a)), got:\n${
+        r.bpmn.split("\n").filter((l) => l.includes("linkedResource")).join("\n")
+      }`,
+    );
+  }
+});
+
 test("late-binding: a fact-qualified edge threads a boundFacts input into the consumer subProcess", async () => {
   const r = await compileOk(RELEASE_RUNBOOK);
   // `publish.resolvedArtifact -> consume`: the connector subProcess receives the human's emitted fact as

package/app/deliveryGraphCompiler.ts

@@ -1931,7 +1931,7 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>, displ
       // be a leak here), but the `descriptor` is embedded by `serviceBodyLines` into the operator-visible
       // timeout / producer-contract escalation FEEL `prompt` — so it takes the SAME display redaction
       // `nodeDisplay` applies, never the raw value (issue #778 review — thread deliveryGraphCompiler.ts:1606).
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], redactConnectorValue(node.agent.jobType), contractGate, agentRepoSpecHeaderLines(node), displayName, "agent", nodeEmits);
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], redactConnectorValue(node.agent.jobType), contractGate, agentRepoSpecHeaderLines(node), displayName, "agent", nodeEmits, undefined);
     }
     case "connector": {
       // TRIM the target before building the escalation descriptor — `nodeDisplay` and the connector
@@ -2113,6 +2113,27 @@ function serviceBodyLines(
   const taskExt = [
     "        <bpmn:extensionElements>",
     `          <zeebe:taskDefinition ${taskDefAttr} />`,
+    // Issue #884: an `agent` cell MUST carry the engine-native AgentTask marker
+    // (`<zeebe:agentDefinition agentType="external"/>`, the `agentTask.agentDefinition` contract —
+    // issue #745) INSIDE its extensionElements, as a sibling of the dispatch verb. Without it the
+    // engine refuses to attach an AgentInstance to the element (`createAgentInstance failed — … has
+    // no agentDefinition`), so every delivery-graph agent run persisted NO durable agentic
+    // transcript (269 failed creates on omarchy). The hand-authored `senior:*` tasks all declare it
+    // (guarded by `agent-marker.test.ts`); the compiler emits it on EVERY agent cell it generates —
+    // the defect class is "every agent service task the app generates". A `connector` delegates to a
+    // HOST worker (`pr.delivery-connector`), not an external agent, so it is NOT marked.
+    ...(kind === "agent" ? ['          <zeebe:agentDefinition agentType="external" />'] : []),
+    // Issue #884 (the "Decide" half — resolved Option (a), PR #886 review): an agent cell carries ONLY
+    // the marker above and NO base-prompt `linkedResource`. The hand-authored process prompts
+    // (`prompts/feature.md`, `prompts/review-round.md`, …) are PROCESS-specific contracts, not generic
+    // cell contracts — they require process variables (`variables.task`/`variables.issue`) and a branch
+    // (`feat/<task.id>`) the generic compiled cell never supplies (it seeds only
+    // `{jobType, appendPrompt, timeout}` and the harness provisions `feat/<node.id>`, #776). Linking one
+    // would hand every compiled cell instructions referencing missing inputs and a conflicting branch.
+    // The cell is therefore deliberately prompt-LESS: the per-node `appendPrompt` FEEL (runner-seeded
+    // from `node.agent.prompt` + the emit/producer contracts) is its sole steering channel, matching the
+    // historically-intentional design (`deliveryRunner.ts` — "the delivery agent node carries no
+    // base-prompt resource"). The marker alone is what fixes the #884 `createAgentInstance` failure.
     ...(taskProps.length > 0 ? ["          <zeebe:properties>", ...taskProps, "          </zeebe:properties>"] : []),
     ...taskHeaders,
     "          <zeebe:ioMapping>",

package/app/mergeLoopBehaviour.test.ts

@@ -89,13 +89,15 @@ const DEFAULT_VARS: Record<string, unknown> = {
   mergeableRepollInterval: "PT2M",
   mergeStallRounds: 0,
   mergeStallMax: 3,
-  abandonBrief: null,
+  abandonBrief: "\n\n---\nAbort if cancelled: curl …",
   failingChecksList: null,
   status: null,
   mergeState: null,
   mergeStatus: null,
   ciBlockedReconciled: null,
   failingChecks: 0,
+  round: 2,
+  abandonUrl: "http://host/app/api/hooks/abandon?token=tok-seeded",
 };
 
 /**
@@ -303,6 +305,86 @@ test("a CONFLICTING PR whose poller never signalled reaches the rebase arm via t
     .hasVariable("rebaseRound", 1);
 });
 
+test("a rebase agent echoing engine-owned timeout state cannot clobber it (#887)", async () => {
+  // Same guard class as fix-ci: the rebase agent must not reshape the seeded timers that later loop
+  // passes re-arm, nor forge `ciBlockedReconciled`. Drive to the rebase arm via the timeout path with
+  // the agent echoing a forged marker and tiny timeouts; the restore must pin the timers.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": {
+        status: "rebased",
+        ciBlockedReconciled: true,
+        agentSlaTimeout: "PT1S",
+        landedWaitTimeout: "PT1S",
+        mergeableWaitTimeout: "PT1S",
+        mergeableRepollInterval: "PT1S",
+      },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("agentSlaTimeout", "PT30M")
+    .hasVariable("landedWaitTimeout", "PT30M")
+    .hasVariable("mergeableWaitTimeout", "PT30M")
+    .hasVariable("mergeableRepollInterval", "PT2M");
+  // The forged lifecycle marker was pinned out too (the rebase path never reconciles).
+  assert(instanceVars(engine).ciBlockedReconciled !== true, "a rebase agent must not forge ciBlockedReconciled:true");
+});
+
+test("a rebase agent echoing round/abandonUrl cannot corrupt the converged round or the abandon token (#887)", async () => {
+  // Same guard class as fix-ci: `round`/`abandonUrl` are seeded once and consumed by `pr.merge`
+  // after a successful rebase re-arms the poller. The restore must pin both against an agent echo.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": { status: "rebased", round: 99, abandonUrl: "http://evil.test/abandon?token=forged" },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("round", 2)
+    .hasVariable("abandonUrl", "http://host/app/api/hooks/abandon?token=tok-seeded");
+});
+
+test("a rebase agent echoing abandonBrief cannot corrupt the seeded abort brief (#887 round 5)", async () => {
+  // `abandonBrief` feeds the fix-ci/rebase `appendPrompt` input on the NEXT re-arm; a non-string
+  // echo would make that later prompt mapping carry a non-string brief. The restore must pin it.
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "conflict", failingChecks: 0, failingChecksList: "" },
+      "senior:rebase": { status: "rebased", abandonBrief: 42 },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("abandonBrief", "\n\n---\nAbort if cancelled: curl …");
+});
+
+test("a fix-ci agent echoing abandonBrief cannot corrupt the seeded abort brief (#887 round 5)", async () => {
+  const engine = await boot({
+    responses: {
+      "pr.merge-stall-probe": { mergeState: "blocked", failingChecks: 1, failingChecksList: "build" },
+      "senior:fix-ci": { status: "fixed", abandonBrief: 42 },
+    },
+  });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.advanceTime(MERGEABLE_WAIT_MS + 1);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("merge-stall-probe", "fix-ci")
+    .hasVariable("abandonBrief", "\n\n---\nAbort if cancelled: curl …");
+});
+
 test("a blocked PR probed on timeout reaches the CI-fix arm via the timeout path (#636)", async () => {
   const engine = await boot({
     responses: {
@@ -529,6 +611,67 @@ test("a blocked CI verdict with nothing pushed reconciles once before escalating
   assert(!completedElementIds(engine).has("merge-esc-attempt"), "the first block episode must reconcile, not page a human");
 });
 
+test("a fix-ci agent echoing ciBlockedReconciled:true cannot skip the one-shot ground-truth reconcile (#887)", async () => {
+  // `ciBlockedReconciled` is an engine-owned lifecycle marker (arm-merge seeds it null; ci-reconcile
+  // sets it true). gw-ci-blocked reconciles exactly once per episode while it is != true. If the agent's
+  // completion could echo `ciBlockedReconciled:true`, a `{status:"blocked", pushed:false}` verdict would
+  // skip the mandatory first reconcile and page a human immediately. The snapshot/restore guard pins it,
+  // so the engine still reconciles once.
+  const engine = await boot({
+    responses: { "senior:fix-ci": { status: "blocked", pushed: false, ciBlockedReconciled: true } },
+  });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("ci-reconcile") // the reconcile STILL runs — the agent's echo was pinned out
+    .hasVariable("ciBlockedReconciled", true);
+  assert(!completedElementIds(engine).has("merge-esc-attempt"), "an agent-forged reconciled flag must not skip the first reconcile");
+});
+
+test("a fix-ci agent echoing seeded timeouts cannot clobber the re-armed merge/SLA timers (#887)", async () => {
+  // The seeded timeout/interval config (agentSlaTimeout, landedWaitTimeout, mergeableWaitTimeout,
+  // mergeableRepollInterval) drives timers re-armed on every loop pass. A `reattempt` re-arms the
+  // merge wait, so a clobbered timeout would silently reshape the next wait. The guard restores them.
+  const engine = await boot({
+    responses: {
+      "senior:fix-ci": {
+        status: "reattempt",
+        agentSlaTimeout: "PT1S",
+        landedWaitTimeout: "PT1S",
+        mergeableWaitTimeout: "PT1S",
+        mergeableRepollInterval: "PT1S",
+      },
+    },
+  });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasVariable("agentSlaTimeout", "PT30M")
+    .hasVariable("landedWaitTimeout", "PT30M")
+    .hasVariable("mergeableWaitTimeout", "PT30M")
+    .hasVariable("mergeableRepollInterval", "PT2M");
+});
+
+test("a fix-ci agent echoing round/abandonUrl cannot corrupt the converged round or the abandon token (#887)", async () => {
+  // `round` (the converged round recorded by ensurePr) and `abandonUrl` (the cooperative-abandon
+  // capability URL) are seeded once and consumed directly by `pr.merge` (attempt-merge). A fix-ci
+  // completion echoing either would corrupt the recorded round or replace the abandon token. The
+  // snapshot/restore guard pins both.
+  const engine = await boot({
+    responses: {
+      "senior:fix-ci": { status: "reattempt", round: 99, abandonUrl: "http://evil.test/abandon?token=forged" },
+    },
+  });
+  await driveToCiFix(engine);
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasVariable("round", 2)
+    .hasVariable("abandonUrl", "http://host/app/api/hooks/abandon?token=tok-seeded");
+});
+
 test("a blocked CI verdict that already pushed escalates with a could-not-fix question", async () => {
   const engine = await boot({ responses: { "senior:fix-ci": { status: "blocked", pushed: true } } });
   await driveToCiFix(engine);
@@ -602,6 +745,70 @@ test("a no-verdict rebase result reconciles from ground truth, not escalation (#
   assert(!completedElementIds(engine).has("merge-esc-attempt"), "a missing rebase status must not escalate");
 });
 
+// ---------------------------------------------------------------------------
+// #887 — an external-agent completion must not clobber engine-owned counters
+// ---------------------------------------------------------------------------
+// The engine merges EVERY variable an external agent returns into process scope unfiltered, so a
+// `senior:fix-ci`/`senior:rebase` agent echoing a loop counter (`ciFixRound`, `rebaseRound`, …) with
+// the wrong type/value would corrupt it — and because the counter feeds the task's own `+ 1`
+// increment and the `ciFixRound < ciFixMax` / `rebaseRound < rebaseMax` guards, a string echo wedges
+// the sub-process on a "comparison/arithmetic not defined for string and number" incident. The fix
+// snapshots each engine-owned counter into a task-local input before the agent runs and restores it
+// on the task output (driving the increment from the snapshot), so the agent can never alter it.
+
+test("a fix-ci agent echoing ciFixRound:\"9\" cannot clobber the counter or wedge the increment (#887)", async () => {
+  const engine = await boot({ responses: { "senior:fix-ci": { status: "fixed", ciFixRound: "9", ciFixMax: "1" } } });
+  await driveToCiFix(engine);
+  assertEquals((await engine.searchIncidents()).length, 0, "the agent echo must not raise an incident");
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("fix-ci")
+    .hasVariable("ciFixRound", 1) // the engine increment (0 → 1), NOT the agent's "9"
+    .hasVariable("ciFixMax", 3); // the budget ceiling is engine-owned, unclobbered
+});
+
+test("a rebase agent echoing rebaseRound:\"9\" cannot clobber the counter or wedge the increment (#887)", async () => {
+  const engine = await boot({ responses: { "senior:rebase": { status: "rebased", rebaseRound: "9", rebaseMax: "1" } } });
+  await driveToRebase(engine);
+  assertEquals((await engine.searchIncidents()).length, 0, "the agent echo must not raise an incident");
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("rebaseRound", 1) // the engine increment (0 → 1), NOT the agent's "9"
+    .hasVariable("rebaseMax", 3); // the budget ceiling is engine-owned, unclobbered
+});
+
+test("a fix-ci agent echoing PR identity inputs cannot clobber them (#887)", async () => {
+  // `repo`/`prNumber`/`prUrl` are the agent's declared *inputs* (FixCiIn), not its outputs — but the
+  // engine merges a completion UNFILTERED, so an input-echo would replace the process identity that
+  // `pr.merge` reads for GitHub operations after re-arming. The snapshot/restore guard must pin them.
+  const engine = await boot({
+    responses: { "senior:fix-ci": { status: "fixed", repo: "evil/repo", prNumber: 999, prUrl: "https://evil.test/pr/999" } },
+  });
+  await driveToCiFix(engine);
+  assertEquals((await engine.searchIncidents()).length, 0, "the agent echo must not raise an incident");
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("fix-ci")
+    .hasVariable("repo", "acme/app")
+    .hasVariable("prNumber", 1)
+    .hasVariable("prUrl", "https://example.test/pr/1");
+});
+
+test("a rebase agent echoing PR identity inputs cannot clobber them (#887)", async () => {
+  const engine = await boot({
+    responses: { "senior:rebase": { status: "rebased", repo: "evil/repo", prNumber: 999, prUrl: "https://evil.test/pr/999" } },
+  });
+  await driveToRebase(engine);
+  assertEquals((await engine.searchIncidents()).length, 0, "the agent echo must not raise an incident");
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasCompletedElements("rebase")
+    .hasVariable("repo", "acme/app")
+    .hasVariable("prNumber", 1)
+    .hasVariable("prUrl", "https://example.test/pr/1");
+});
+
 test("rebase budget exhaustion escalates as not-mergeable without running the agent", async () => {
   const engine = await boot({ responses: { "senior:rebase": { status: "rebased" } }, vars: { rebaseMax: 0 } });
   await driveToRebase(engine);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.201.3",
+  "version": "0.201.5",
   "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",
@@ -37,6 +37,7 @@
     "typecheck": "tsc --noEmit",
     "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
+    "check:agent-definitions": "node --experimental-strip-types scripts/check-agent-definitions.ts",
     "check:migrations": "node --experimental-strip-types scripts/check-migrations.ts",
     "heal:migrations": "node --experimental-strip-types scripts/heal-migration-ledger.ts",
     "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",

package/resources/processes/convergence-loop.bpmn

@@ -147,9 +147,45 @@
         </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
+          <zeebe:input source="=round" target="guardRound" />
+          <zeebe:input source="=maxRounds" target="guardMaxRounds" />
+          <zeebe:input source="=advPass" target="guardAdvPass" />
+          <zeebe:input source="=advMax" target="guardAdvMax" />
+          <zeebe:input source="=ackRetryRound" target="guardAckRetryRound" />
+          <zeebe:input source="=ackRetryMax" target="guardAckRetryMax" />
+          <zeebe:input source="=huskRetries" target="guardHuskRetries" />
+          <zeebe:input source="=prKey" target="guardPrKey" />
+          <zeebe:input source="=repo" target="guardRepo" />
+          <zeebe:input source="=prNumber" target="guardPrNumber" />
+          <zeebe:input source="=prUrl" target="guardPrUrl" />
+          <zeebe:input source="=reviewWaitTimeout" target="guardReviewWaitTimeout" />
+          <zeebe:input source="=humanApproval" target="guardHumanApproval" />
+          <zeebe:input source="=convergeOnly" target="guardConvergeOnly" />
+          <zeebe:input source="=reviewStale" target="guardReviewStale" />
+          <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
+          <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
+          <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
           <zeebe:output source="=null" target="answer" />
           <zeebe:output source="=false" target="scopePending" />
           <zeebe:output source="=null" target="adversarialFindings" />
+          <zeebe:output source="=guardRound" target="round" />
+          <zeebe:output source="=guardMaxRounds" target="maxRounds" />
+          <zeebe:output source="=guardAdvPass" target="advPass" />
+          <zeebe:output source="=guardAdvMax" target="advMax" />
+          <zeebe:output source="=guardAckRetryRound" target="ackRetryRound" />
+          <zeebe:output source="=guardAckRetryMax" target="ackRetryMax" />
+          <zeebe:output source="=guardHuskRetries" target="huskRetries" />
+          <zeebe:output source="=guardPrKey" target="prKey" />
+          <zeebe:output source="=guardRepo" target="repo" />
+          <zeebe:output source="=guardPrNumber" target="prNumber" />
+          <zeebe:output source="=guardPrUrl" target="prUrl" />
+          <zeebe:output source="=guardReviewWaitTimeout" target="reviewWaitTimeout" />
+          <zeebe:output source="=(guardHumanApproval = true) or (humanApproval = true)" target="humanApproval" />
+          <zeebe:output source="=guardConvergeOnly" target="convergeOnly" />
+          <zeebe:output source="=guardReviewStale" target="reviewStale" />
+          <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
+          <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
+          <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_capture</bpmn:incoming>
@@ -205,11 +241,46 @@
         </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
+          <zeebe:input source="=round" target="guardRound" />
+          <zeebe:input source="=maxRounds" target="guardMaxRounds" />
+          <zeebe:input source="=advPass" target="guardAdvPass" />
+          <zeebe:input source="=advMax" target="guardAdvMax" />
+          <zeebe:input source="=ackRetryRound" target="guardAckRetryRound" />
+          <zeebe:input source="=ackRetryMax" target="guardAckRetryMax" />
+          <zeebe:input source="=huskRetries" target="guardHuskRetries" />
+          <zeebe:input source="=prKey" target="guardPrKey" />
+          <zeebe:input source="=repo" target="guardRepo" />
+          <zeebe:input source="=prNumber" target="guardPrNumber" />
+          <zeebe:input source="=prUrl" target="guardPrUrl" />
+          <zeebe:input source="=reviewWaitTimeout" target="guardReviewWaitTimeout" />
+          <zeebe:input source="=humanApproval" target="guardHumanApproval" />
+          <zeebe:input source="=convergeOnly" target="guardConvergeOnly" />
+          <zeebe:input source="=reviewStale" target="guardReviewStale" />
+          <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
+          <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
+          <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
           <zeebe:output source="=adversarialFindings" target="adversarialFindings" />
-          <zeebe:output source="=(if advPass = null then 0 else advPass) + 1" target="advPass" />
+          <zeebe:output source="=(if guardAdvPass = null then 0 else guardAdvPass) + 1" target="advPass" />
           <zeebe:output source="=(if adversarialFindings != null and trim(adversarialFindings) != &#34;&#34; then null else status)" target="status" />
           <zeebe:output source="=(if adversarialFindings != null and trim(adversarialFindings) != &#34;&#34; then null else summary)" target="summary" />
           <zeebe:output source="=(if adversarialFindings != null and trim(adversarialFindings) != &#34;&#34; then null else question)" target="question" />
+          <zeebe:output source="=guardRound" target="round" />
+          <zeebe:output source="=guardMaxRounds" target="maxRounds" />
+          <zeebe:output source="=guardAdvMax" target="advMax" />
+          <zeebe:output source="=guardAckRetryRound" target="ackRetryRound" />
+          <zeebe:output source="=guardAckRetryMax" target="ackRetryMax" />
+          <zeebe:output source="=guardHuskRetries" target="huskRetries" />
+          <zeebe:output source="=guardPrKey" target="prKey" />
+          <zeebe:output source="=guardRepo" target="repo" />
+          <zeebe:output source="=guardPrNumber" target="prNumber" />
+          <zeebe:output source="=guardPrUrl" target="prUrl" />
+          <zeebe:output source="=guardReviewWaitTimeout" target="reviewWaitTimeout" />
+          <zeebe:output source="=(guardHumanApproval = true) or (humanApproval = true)" target="humanApproval" />
+          <zeebe:output source="=guardConvergeOnly" target="convergeOnly" />
+          <zeebe:output source="=guardReviewStale" target="reviewStale" />
+          <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
+          <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
+          <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_advDue</bpmn:incoming>
@@ -478,7 +549,43 @@
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="PrScopeClassifyOut" />
         </zeebe:properties>
         <zeebe:ioMapping>
+          <zeebe:input source="=round" target="guardRound" />
+          <zeebe:input source="=maxRounds" target="guardMaxRounds" />
+          <zeebe:input source="=advPass" target="guardAdvPass" />
+          <zeebe:input source="=advMax" target="guardAdvMax" />
+          <zeebe:input source="=ackRetryRound" target="guardAckRetryRound" />
+          <zeebe:input source="=ackRetryMax" target="guardAckRetryMax" />
+          <zeebe:input source="=huskRetries" target="guardHuskRetries" />
+          <zeebe:input source="=prKey" target="guardPrKey" />
+          <zeebe:input source="=repo" target="guardRepo" />
+          <zeebe:input source="=prNumber" target="guardPrNumber" />
+          <zeebe:input source="=prUrl" target="guardPrUrl" />
+          <zeebe:input source="=reviewWaitTimeout" target="guardReviewWaitTimeout" />
+          <zeebe:input source="=humanApproval" target="guardHumanApproval" />
+          <zeebe:input source="=convergeOnly" target="guardConvergeOnly" />
+          <zeebe:input source="=reviewStale" target="guardReviewStale" />
+          <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
+          <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
+          <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
           <zeebe:output source="=null" target="scopeAnswer" />
+          <zeebe:output source="=guardRound" target="round" />
+          <zeebe:output source="=guardMaxRounds" target="maxRounds" />
+          <zeebe:output source="=guardAdvPass" target="advPass" />
+          <zeebe:output source="=guardAdvMax" target="advMax" />
+          <zeebe:output source="=guardAckRetryRound" target="ackRetryRound" />
+          <zeebe:output source="=guardAckRetryMax" target="ackRetryMax" />
+          <zeebe:output source="=guardHuskRetries" target="huskRetries" />
+          <zeebe:output source="=guardPrKey" target="prKey" />
+          <zeebe:output source="=guardRepo" target="repo" />
+          <zeebe:output source="=guardPrNumber" target="prNumber" />
+          <zeebe:output source="=guardPrUrl" target="prUrl" />
+          <zeebe:output source="=guardReviewWaitTimeout" target="reviewWaitTimeout" />
+          <zeebe:output source="=(guardHumanApproval = true) or (humanApproval = true)" target="humanApproval" />
+          <zeebe:output source="=guardConvergeOnly" target="convergeOnly" />
+          <zeebe:output source="=guardReviewStale" target="reviewStale" />
+          <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
+          <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
+          <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_convergeOk</bpmn:incoming>