@nanobpm/nano-workforce 0.199.0 → 0.200.1

package/app/layoutOffThread.ts

@@ -0,0 +1,182 @@
+// app/layoutOffThread.ts — the ONE canonical off-main-thread bridge to the CPU-bound BPMN autolayout
+// (`layoutBpmn` → `bpmn-auto-layout`), issue #854.
+//
+// WHY: `layoutBpmn` is superlinear in node/edge count and, run inline on the event loop, blocked the
+// whole app (no HTTP, no poll passes) for the entire layout — ~52s on merlin, >4min under load on a
+// 54-node delivery graph, a hard lock-up the operator had to kill mid-launch (#852). This module runs
+// the layout in a `node:worker_threads` worker so the main loop keeps ticking, and BOUNDS it with a
+// timeout that TERMINATES the worker on expiry so a pathological graph fails the launch CLEANLY
+// instead of hanging forever.
+//
+// `layoutDeliveryDiagram` (app/deliveryGraphCompiler.ts) — the single layout entry point BOTH the
+// dispatch path (`dispatchDeliveryGraphRun` → `compileDeliveryGraph`) and the preview path
+// (`previewProposalBpmn` → `compileDeliveryGraph`) funnel through — calls `layoutBpmnOffThread` here,
+// so there is exactly ONE place the autolayout runs and exactly ONE timeout/termination policy.
+
+import { Worker } from "node:worker_threads";
+import { readEnvOr } from "./contracts.ts";
+
+/** Node's `setTimeout` delay ceiling (a signed 32-bit ms value). A delay above this silently wraps to
+ * 1ms (emitting `TimeoutOverflowWarning`), so an over-large override would abort layouts IMMEDIATELY
+ * instead of extending the bound — a value that large is treated as garbage and degrades to the
+ * registered default. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** The registered default, resolved once from the schema (empty env ⇒ registry `default`) so the
+ * invalid-override fallback and the timeout message stay single-sourced — not a literal `300000`
+ * duplicated here that would drift from `ENV_CONTRACTS`. Mirrors `cloneTimeoutMs` in
+ * `app/repoEnvelope.ts`. */
+const envDefaultLayoutTimeoutMs = Number(readEnvOr("NANO_DELIVERY_LAYOUT_TIMEOUT_MS", "300000", {}));
+
+/** Resolve the layout timeout (ms) from `NANO_DELIVERY_LAYOUT_TIMEOUT_MS` (registered default 300000
+ * = 5 min), degrading to the registered default for any value that is non-positive, garbage, or above
+ * Node's timer ceiling ({@link MAX_TIMER_MS} — an overflow would wrap to 1ms and abort every layout).
+ * Read per call so an operator can retune it without a restart; the layout is rare (dispatch/preview),
+ * so the lookup cost is irrelevant. */
+export function layoutTimeoutMs(env: Record<string, string | undefined> = process.env): number {
+  const raw = Number(readEnvOr("NANO_DELIVERY_LAYOUT_TIMEOUT_MS", "300000", env));
+  return Number.isFinite(raw) && raw > 0 && raw <= MAX_TIMER_MS ? raw : envDefaultLayoutTimeoutMs;
+}
+
+/** A sanity ceiling on the concurrency bound: a value this large is effectively unbounded and is
+ * treated as garbage (degrading to the registered default) rather than honoured — the whole point of
+ * the bound is to keep concurrent CPU-bound layouts SMALL. */
+const MAX_LAYOUT_CONCURRENCY = 1024;
+
+/** The registered default concurrency, resolved once from the schema (empty env ⇒ registry `default`)
+ * so the invalid-override fallback stays single-sourced — not a literal duplicated here that would
+ * drift from `ENV_CONTRACTS`. Mirrors {@link envDefaultLayoutTimeoutMs}. */
+const envDefaultLayoutMaxConcurrency = Number(readEnvOr("NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY", "2", {}));
+
+/** Resolve the max number of concurrent layout workers from `NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY`
+ * (registered default 2), degrading to the registered default for any value that is non-integer,
+ * non-positive, garbage, or above {@link MAX_LAYOUT_CONCURRENCY}. Mirrors {@link layoutTimeoutMs}'s
+ * fail-safe parsing so a bad override can never make the bound 0/∞ (either of which defeats it). */
+export function layoutMaxConcurrency(env: Record<string, string | undefined> = process.env): number {
+  const raw = Number(readEnvOr("NANO_DELIVERY_LAYOUT_MAX_CONCURRENCY", "2", env));
+  return Number.isInteger(raw) && raw > 0 && raw <= MAX_LAYOUT_CONCURRENCY ? raw : envDefaultLayoutMaxConcurrency;
+}
+
+/** A minimal FIFO counting semaphore: at most `max` holders run concurrently, the rest queue in
+ * arrival order. Bounds how many CPU-bound layout workers exist at once so a burst of overlapping
+ * preview/dispatch layouts cannot spawn an UNBOUNDED number of superlinear workers and saturate
+ * CPU/memory — the very starvation this off-thread move exists to prevent (issue #854). Each
+ * `acquire()` resolves with an idempotent `release` that hands the freed slot to the next waiter. */
+export class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+  private readonly max: number;
+
+  constructor(max: number) {
+    if (!Number.isInteger(max) || max < 1) {
+      throw new Error(`Semaphore: max must be a positive integer, got ${String(max)}`);
+    }
+    this.max = max;
+  }
+
+  /** Wait (FIFO) for a slot, then return a one-shot `release`. Always `release()` in a `finally` so a
+   * rejecting holder cannot leak its slot and wedge every queued layout behind it. */
+  async acquire(): Promise<() => void> {
+    await new Promise<void>((resolve) => {
+      if (this.active < this.max) {
+        this.active++;
+        resolve();
+      } else {
+        this.waiters.push(() => {
+          this.active++;
+          resolve();
+        });
+      }
+    });
+    let released = false;
+    return () => {
+      if (released) return; // idempotent: a double release must not free a slot it never held
+      released = true;
+      this.active--;
+      this.waiters.shift()?.();
+    };
+  }
+}
+
+/** The ONE shared gate bounding concurrent layout workers, sized lazily on first use from
+ * {@link layoutMaxConcurrency}. A singleton so EVERY `layoutBpmnOffThread` call — across both the
+ * dispatch and preview paths — contends for the same small pool of slots. */
+let layoutGate: Semaphore | undefined;
+function layoutConcurrencyGate(): Semaphore {
+  if (!layoutGate) layoutGate = new Semaphore(layoutMaxConcurrency());
+  return layoutGate;
+}
+
+/** The worker message shape: a laid-out XML payload on success, or a server-side error string. */
+type LayoutWorkerMessage = { ok: true; laidOut: string } | { ok: false; error: string };
+
+/** Run `layoutBpmn(semanticBpmn)` in a dedicated `worker_threads` worker, OFF the main event loop,
+ * bounded by `timeoutMs`. Resolves with the laid-out XML; rejects (and TERMINATES the worker — the
+ * bound that stops a runaway layout) on timeout, a worker error, an early exit, or a layout failure
+ * reported by the worker. The worker is always torn down before this resolves/rejects, so no isolate
+ * leaks across calls. At most {@link layoutMaxConcurrency} workers run at once (the shared
+ * {@link Semaphore} gate) — a burst of overlapping preview/dispatch layouts queues for a slot rather
+ * than spawning an unbounded number of superlinear CPU-bound workers that would saturate the host.
+ * The timeout covers only the ACTUAL layout (it starts after a slot is acquired), so queueing behind
+ * other layouts is never charged against a graph's bound.
+ *
+ * `spawnWorker` is an injectable seam (default: the real `layoutWorker.ts` worker) so a test can force
+ * a SYNCHRONOUS construction failure — `new Worker(...)` can throw (e.g. `ERR_WORKER_INIT_FAILED`
+ * under resource pressure) — and prove the slot is still released (see below). */
+export async function layoutBpmnOffThread(
+  semanticBpmn: string,
+  timeoutMs: number = layoutTimeoutMs(),
+  spawnWorker: () => Worker = () =>
+    new Worker(new URL("./layoutWorker.ts", import.meta.url), { workerData: { semanticBpmn } }),
+): Promise<string> {
+  // Acquire the slot, then wrap EVERYTHING — including worker construction — in the release `finally`.
+  // `new Worker(...)` can throw synchronously (e.g. `ERR_WORKER_INIT_FAILED` under resource pressure);
+  // if construction sat outside this guard, each such failure would permanently consume a slot and,
+  // after `max` failures, wedge every later layout waiting on the gate forever (issue #854 review).
+  const release = await layoutConcurrencyGate().acquire();
+  try {
+    const worker = spawnWorker();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await new Promise<string>((resolve, reject) => {
+        let settled = false;
+        const settle = (fn: () => void) => {
+          if (settled) return;
+          settled = true;
+          if (timer) clearTimeout(timer);
+          fn();
+        };
+        timer = setTimeout(() => {
+          settle(() =>
+            reject(
+              new Error(
+                `layoutDeliveryDiagram: BPMN autolayout exceeded its ${timeoutMs}ms bound and was aborted — the ` +
+                  "delivery graph is too large/dense to lay out within the timeout (bpmn-auto-layout is superlinear in " +
+                  "node/edge count, issue #854). The launch was failed cleanly rather than hung; retune " +
+                  `\`NANO_DELIVERY_LAYOUT_TIMEOUT_MS\` (default ${envDefaultLayoutTimeoutMs}) or shrink the graph.`,
+              ),
+            ),
+          );
+        }, timeoutMs);
+        // A setTimeout in a hot dispatch path should not itself keep a draining process alive.
+        timer.unref?.();
+        worker.once("message", (msg: LayoutWorkerMessage) => {
+          settle(() => {
+            if (msg.ok) resolve(msg.laidOut);
+            else reject(new Error(msg.error));
+          });
+        });
+        worker.once("error", (err) => settle(() => reject(err)));
+        worker.once("exit", (code) => {
+          if (code === 0) return; // a clean exit after a delivered message is expected on teardown
+          settle(() => reject(new Error(`layoutDeliveryDiagram: layout worker exited early with code ${code}`)));
+        });
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+      await worker.terminate();
+    }
+  } finally {
+    release(); // hand our slot to the next queued layout — ALWAYS, even on a construction throw/reject/terminate
+  }
+}

package/app/layoutWorker.ts

@@ -0,0 +1,34 @@
+// app/layoutWorker.ts — the `node:worker_threads` entry that runs the CPU-bound BPMN autolayout
+// (`layoutBpmn` → `bpmn-auto-layout`) OFF the app's main event loop (issue #854).
+//
+// `bpmn-auto-layout` is superlinear in node/edge count: on the 54-node merlin delivery graph it ran
+// ~52s on merlin and >4min under real load, and because it ran SYNCHRONOUSLY on the event loop in
+// `layoutDeliveryDiagram`, the whole app served no HTTP and ran no poll passes for that entire window
+// — the operator saw a hard lock-up (#852). Hoisting the layout into this worker keeps the main loop
+// free to serve pages/API/MCP and tick its poll loop while a large graph lays out; the parent bounds
+// the work with a timeout and TERMINATES this worker on expiry (see `app/layoutOffThread.ts`), so a
+// pathological graph fails the launch cleanly instead of hanging forever.
+//
+// Protocol: `workerData.semanticBpmn` carries the pre-layout semantic BPMN; we post back either the
+// laid-out XML (a string) on success or `{ error }` on failure. We never `process.exit` — resolving
+// the message lets the parent `terminate()` us.
+
+import { parentPort, workerData } from "node:worker_threads";
+import { layoutBpmn } from "@nanobpm/urban";
+
+async function run(): Promise<void> {
+  const port = parentPort;
+  if (!port) throw new Error("layoutWorker: must be spawned as a worker_threads worker (no parentPort)");
+  const { semanticBpmn } = workerData ?? {};
+  if (typeof semanticBpmn !== "string") {
+    throw new Error("layoutWorker: workerData.semanticBpmn must be a string");
+  }
+  try {
+    const laidOut = await layoutBpmn(semanticBpmn);
+    port.postMessage({ ok: true, laidOut });
+  } catch (err) {
+    port.postMessage({ ok: false, error: err instanceof Error ? err.message : String(err) });
+  }
+}
+
+void run();

package/app/roundProgress.test.ts

@@ -945,8 +945,14 @@ test("the round-cap guard is downstream of progress classification, so a husk au
   const retry = flowElement("f_huskRetry");
   assert(retry, "f_huskRetry flow missing");
   assertStringIncludes(retry, 'targetRef="capture-head"');
-  // The addressed/waiting status arms feed persist-round directly (not the guard).
+  // (#844: the addressed AND waiting arms detour through the bounded adversarial gate, whose arms all
+  // land on persist-round or loop to review-round — never gw-guard.)
   for (const id of ["f_addressed", "f_waiting"]) {
+    const f = flowElement(id);
+    assert(f, `${id} flow missing`);
+    assertStringIncludes(f, 'targetRef="gw-adv-due"');
+  }
+  for (const id of ["f_advSkip", "f_advClean"]) {
     const f = flowElement(id);
     assert(f, `${id} flow missing`);
     assertStringIncludes(f, 'targetRef="persist-round"');

package/app/roundResultDefault.test.ts

@@ -77,14 +77,35 @@ test("escalation is an explicit needs_input/blocked arm gated on a non-blank que
 test("the default (addressed) arm carries no condition and re-enters round processing", () => {
   const addressed = flowElement("f_addressed");
   assert(addressed, "f_addressed flow missing");
-  assertStringIncludes(addressed, 'targetRef="persist-round"');
+  // #844: the addressed arm first passes the (bounded) local adversarial-review gate, whose
+  // unconditional defaults — budget spent / findings clean — both land on round processing.
+  assertStringIncludes(addressed, 'targetRef="gw-adv-due"');
   // A default flow must have NO conditionExpression.
   assert(
     !/conditionExpression/.test(addressed),
     "f_addressed is the default flow and must not carry a conditionExpression",
   );
+  assertAdversarialDefaultsReenterRound();
 });
 
+/** The adversarial-review detour (#844) on the addressed arm must always drain to round
+ * processing: both gateways' DEFAULT arms are unconditional and target persist-round, and the only
+ * conditional arm loops back into review-round (bounded by advPass/advMax) — never escalation. */
+function assertAdversarialDefaultsReenterRound() {
+  for (const [gw, dflt] of [["gw-adv-due", "f_advSkip"], ["gw-adv-result", "f_advClean"]]) {
+    const g = flat.match(new RegExp(`<bpmn:exclusiveGateway\\b[^>]*\\bid="${gw}"[^>]*>`));
+    assert(g, `${gw} gateway missing`);
+    assertStringIncludes(g[0], `default="${dflt}"`);
+    const f = flowElement(dflt);
+    assert(f, `${dflt} flow missing`);
+    assertStringIncludes(f, 'targetRef="persist-round"');
+    assert(!/conditionExpression/.test(f), `${dflt} is a default arm and must not carry a condition`);
+  }
+  const loop = flowElement("f_advFindings");
+  assert(loop, "f_advFindings flow missing");
+  assertStringIncludes(loop, 'targetRef="review-round"');
+}
+
 test("regression: an empty/unknown status no longer routes to persist-escalation", () => {
   // Escalation is reachable ONLY via an explicit condition (the needs_input/blocked arm),
   // never as a catch-all default. Enumerate EVERY sequenceFlow into `persist-escalation`
@@ -98,7 +119,8 @@ test("regression: an empty/unknown status no longer routes to persist-escalation
   // The addressed default must land on round processing (persist-round → check-progress, which
   // re-solicits the review after the round-cap gate downstream), not escalation.
   const addressed = flowElement("f_addressed");
-  assert(addressed && /targetRef="persist-round"/.test(addressed), "default arm must re-enter round processing");
+  assert(addressed && /targetRef="gw-adv-due"/.test(addressed), "default arm must re-enter round processing");
+  assertAdversarialDefaultsReenterRound();
 });
 
 // The canonical router (app/roundResultDefault.ts) mirrors the gw-status routing above, with the

package/app/service.test.ts

@@ -11,7 +11,7 @@ import { memDataFor } from "../test/worldDb.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
 import { WorldStore } from "./world/index.ts";
-import { abandonClosedPr, isPrSettled, MAX_ACK_RETRIES, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollReviews, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { abandonClosedPr, isPrSettled, MAX_ACK_RETRIES, MAX_ADVERSARIAL_PASSES, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollJobActivationImpl, pollReviews, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
 import { trackingTargetFor } from "./instanceTracking.ts";
 import type { DataLayer } from "@nanobpm/urban";
 import { READINESS_READY_MESSAGE } from "./readiness.ts";
@@ -669,6 +669,168 @@ test("pollIncidents picks the oldest incident by creationTime, sorting a missing
 });
 
 
+// Red/green regression (nano-workforce#845 Copilot review): the convergence loop runs TWO external
+// agent task types while the PR reads `converging` — `review-round` (`senior:pr-review`) and, since
+// issue #844, `adversarial-review` (`senior:adversarial-review`). `pollJobActivation` originally
+// searched only for `senior:pr-review`, so during an adversarial pass it found no matching job and
+// cleared `active_worker`/`lease_until` — the Home/Overview grids reported "queued" while an agent
+// was actively working. This drives the pass's reconciliation core against a stubbed
+// `/v2/jobs/search`:
+//   1. an activated `senior:adversarial-review` job surfaces its leasing worker (the defect),
+//   2. the review-round → adversarial-review handoff keeps a live worker visible across the switch,
+//   3. a non-agent job (an internal `pr.*` worker) is defensively excluded even if the wire `$in`
+//      filter is ignored,
+//   4. a merely-created (unactivated) agent job — no `worker` yet — reads as "queued" (lease null).
+function jobActivationFetch(byInstance: Record<string, unknown[]>, opts: { ignoreTypeFilter?: boolean } = {}) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/jobs/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    const body = JSON.parse(String(init?.body ?? "{}")) as {
+      filter?: { processInstanceKey?: string; type?: string | { $in?: string[] } };
+    };
+    const all = (byInstance[body.filter?.processInstanceKey ?? ""] ?? []) as { type?: string }[];
+    // Honor the wire `type` filter (scalar `$eq` or `{ $in: [...] }`) the way the engine does, so the
+    // test reproduces the real defect: a single-type `senior:pr-review` filter returns ZERO items for
+    // an adversarial-pass job (the engine filters server-side), which is exactly what cleared the
+    // lease pre-fix. A stub that ignores `type` would pass against the old code and prove nothing.
+    // `ignoreTypeFilter` simulates an engine that IGNORES the `$in` filter, so the non-agent item
+    // reaches `pollJobActivationImpl` and the test exercises the defensive client-side `.includes`
+    // re-filter (service.ts) rather than the wire filter doing the work.
+    const t = body.filter?.type;
+    const wanted: string[] | null = typeof t === "string" ? [t] : Array.isArray(t?.$in) ? t.$in : null;
+    const items = opts.ignoreTypeFilter || wanted == null ? all : all.filter((j) => wanted.includes(j.type ?? ""));
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+function jobActivationData(rows: unknown[]) {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows, key: "pr_key" },
+  };
+  return {
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+    open: () => memOpen(stores),
+  } as any;
+}
+
+test("pollJobActivation surfaces an activated adversarial-review agent (not just senior:pr-review)", async () => {
+  const row = {
+    pr_key: "owner/repo#20",
+    status: "converging",
+    process_key: "PI-20",
+    active_worker: null as string | null,
+    lease_until: null as string | null,
+    updated_at: "t0",
+  };
+  const data = jobActivationData([row]);
+  const headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  // The PR is mid adversarial pass: the only open job is `senior:adversarial-review`, leased by a
+  // worker. Before the fix the pass filtered on `senior:pr-review` alone, found nothing, and left
+  // `active_worker` null — the grid showed "queued" while this agent was actively working.
+  globalThis.fetch = jobActivationFetch({
+    "PI-20": [
+      { type: "senior:adversarial-review", worker: "agent-adv", deadline: "2024-01-01T00:15:00Z", state: "CREATED" },
+    ],
+  }) as typeof fetch;
+  try {
+    await pollJobActivationImpl(data, "http://engine/v2", headers);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(row.active_worker, "agent-adv");
+  assertEquals(row.lease_until, "2024-01-01T00:15:00Z");
+});
+
+test("pollJobActivation keeps a live worker visible across the review-round ↔ adversarial handoff", async () => {
+  const row = {
+    pr_key: "owner/repo#21",
+    status: "converging",
+    process_key: "PI-21",
+    active_worker: null as string | null,
+    lease_until: null as string | null,
+    updated_at: "t0",
+  };
+  const data = jobActivationData([row]);
+  const headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  try {
+    // Leg 1: the review-round agent (`senior:pr-review`) is working.
+    globalThis.fetch = jobActivationFetch({
+      "PI-21": [
+        { type: "senior:pr-review", worker: "agent-review", deadline: "2024-01-01T00:10:00Z", state: "CREATED" },
+      ],
+    }) as typeof fetch;
+    await pollJobActivationImpl(data, "http://engine/v2", headers);
+    assertEquals(row.active_worker, "agent-review");
+
+    // Leg 2: the loop handed off to the adversarial pass (`senior:adversarial-review`) — same
+    // `converging` status, different job type. The grid must keep showing "agent working", not
+    // flash "queued".
+    globalThis.fetch = jobActivationFetch({
+      "PI-21": [
+        { type: "senior:adversarial-review", worker: "agent-adv", deadline: "2024-01-01T00:20:00Z", state: "CREATED" },
+      ],
+    }) as typeof fetch;
+    await pollJobActivationImpl(data, "http://engine/v2", headers);
+    assertEquals(row.active_worker, "agent-adv");
+    assertEquals(row.lease_until, "2024-01-01T00:20:00Z");
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+});
+
+test("pollJobActivation excludes a non-agent job and reports an unactivated agent job as queued", async () => {
+  const row = {
+    pr_key: "owner/repo#22",
+    status: "converging",
+    process_key: "PI-22",
+    active_worker: "stale-worker" as string | null,
+    lease_until: "2024-01-01T00:05:00Z" as string | null,
+    updated_at: "t0",
+  };
+  const data = jobActivationData([row]);
+  const headers = { "content-type": "application/json" };
+
+  const prevFetch = globalThis.fetch;
+  try {
+    // An internal `pr.*` worker job is open and "leased" — but it is not a convergence agent, so it
+    // must NOT keep `active_worker` lit even if the engine ignores the wire `$in` type filter. Pass
+    // `ignoreTypeFilter` so the mock returns the non-agent item UNFILTERED (an engine that ignores
+    // `$in`): the defensive client-side `.includes(j.type)` re-filter in `pollJobActivationImpl` is
+    // then what excludes it — so the assertion genuinely guards that branch (a wire-filtered stub
+    // would pass even if the defensive check were deleted).
+    globalThis.fetch = jobActivationFetch(
+      {
+        "PI-22": [
+          { type: "pr.capture-head", worker: "host-internal", deadline: "2024-01-01T00:30:00Z", state: "CREATED" },
+        ],
+      },
+      { ignoreTypeFilter: true },
+    ) as typeof fetch;
+    await pollJobActivationImpl(data, "http://engine/v2", headers);
+    assertEquals(row.active_worker, null);
+    assertEquals(row.lease_until, null);
+
+    // A merely-created (queued) agent job carries no worker yet → still "queued" (lease null).
+    globalThis.fetch = jobActivationFetch({
+      "PI-22": [{ type: "senior:adversarial-review", state: "CREATED" }],
+    }) as typeof fetch;
+    await pollJobActivationImpl(data, "http://engine/v2", headers);
+    assertEquals(row.active_worker, null);
+    assertEquals(row.lease_until, null);
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+});
+
+
 // Red/green regression (nano-workforce#102 review): the engine can hand back a numeric
 // `processInstanceKey`, but the OpenAPI `SubmitResult.processKey` contract is `string | null`, so
 // under api `validateResponses:"dev"` a raw number fails response validation. Stringifying at the
@@ -876,6 +1038,21 @@ test("submitPr seeds the #796 auto-ack budget onto the instance (ackRetryRound=0
   });
 });
 
+test("submitPr seeds the #844 adversarial-review budget (advPass=0, advMax=MAX_ADVERSARIAL_PASSES)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, get } = captureVars();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 14,
+      url: "https://github.com/owner/repo/pull/14",
+      prKey: "owner/repo#14",
+    });
+    const vars = get();
+    assertEquals(vars?.advPass, 0);
+    assertEquals(vars?.advMax, MAX_ADVERSARIAL_PASSES);
+  });
+});
+
 test("submitPr seeds humanApproval (issue #826), pinned off for a converge-only run that never merges", async () => {
   await withGithubOff(async () => {
     const pr = (n: number) => ({ repo: "owner/repo", number: n, url: `https://github.com/owner/repo/pull/${n}`, prKey: `owner/repo#${n}` });

package/app/service.ts

@@ -27,6 +27,7 @@ import {
   CONFORMANCE_ESCALATION_ELEMENT,
   conformanceEscalationQuestion,
 } from "./conformance.ts";
+import { envContract, readEnvOr } from "./contracts.ts";
 import { makeDefaultReadHead } from "./currentHead.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
@@ -136,6 +137,18 @@ export const MERGE_PROCESS_ID = "merge-loop";
  * in convergence-loop.bpmn). Deliberately NOT hosted here — an external harness services it; the
  * activation poll keys off it to tell "agent working" from "queued". */
 const REVIEW_JOB_TYPE = "senior:pr-review";
+/** Job type of the local adversarial-review agent (the `adversarial-review` service task's
+ * `zeebe:taskDefinition` in convergence-loop.bpmn, issue #844). Like {@link REVIEW_JOB_TYPE} it is
+ * serviced by an external harness while the PR stays `converging`, so the activation poll must
+ * treat it as another live convergence agent — otherwise the grid reports "queued" for the whole
+ * adversarial pass even though an agent has leased the job. */
+const ADVERSARIAL_JOB_TYPE = "senior:adversarial-review";
+/** Every external-agent job type the convergence loop parks on while the PR reads `converging`.
+ * `pollJobActivation` reconciles `active_worker`/`lease_until` against ANY of these so the
+ * review-round ↔ adversarial-review handoff (same `converging` status, different job type) never
+ * flashes a phantom "queued". Typed `readonly string[]` (not `as const`) so `.includes(aString)`
+ * needs no `as` cast at the read site. */
+const CONVERGENCE_AGENT_JOB_TYPES: readonly string[] = [REVIEW_JOB_TYPE, ADVERSARIAL_JOB_TYPE];
 
 /** Default round cap before the loop escalates to a human. A per-submit override (submit form /
  * webhook / start action) takes precedence; this env var sets the fleet-wide default. The cap
@@ -179,6 +192,18 @@ export const MAX_MERGE_RETRIES = clampCiFixBudget(process.env.NANO_PR_MAX_MERGE_
  * (allows 0 = disable, ceiling-capped). */
 export const MAX_ACK_RETRIES = clampCiFixBudget(process.env.NANO_PR_MAX_ACK_RETRIES, 2);
 
+/** Local adversarial-review passes per convergence round (issue #844). An `addressed` round runs the
+ * `senior:adversarial-review` agent over its diff BEFORE the round parks on `waiting_review` (the only
+ * status the poller solicits a Copilot review for); non-blank findings re-dispatch `review-round`, up
+ * to this many passes per round. Default 1; `NANO_PR_MAX_ADVERSARIAL_PASSES=0` disables the stage.
+ * Reuses the CI-fix budget clamp (allows 0 = disable, ceiling-capped). The clamp fallback is
+ * derived from the registered `default` so the schema stays the single source of truth (a
+ * registry edit can't drift from a second literal here). */
+export const MAX_ADVERSARIAL_PASSES = clampCiFixBudget(
+  readEnvOr("NANO_PR_MAX_ADVERSARIAL_PASSES"),
+  Number(envContract("NANO_PR_MAX_ADVERSARIAL_PASSES").default),
+);
+
 /** How many times the mergeable-wait timeout backstop (`merge-stall-probe`) will re-derive
  * mergeability from ground truth and re-arm the merge stage before giving up and escalating to a
  * human. Bounds the timer arm of the `gw-merge-wait` event-based gateway so a dead in-process poller
@@ -740,6 +765,10 @@ async function submitPrCritical(
       // solely on unacked ones, before escalating to a human. `ackRetryRound` counts those passes.
       ackRetryRound: 0,
       ackRetryMax: MAX_ACK_RETRIES,
+      // Local adversarial review (issue #844): `advPass` counts this round's adversarial passes (reset
+      // by `capture-head` each round); `advMax` bounds them. 0 skips the stage.
+      advPass: 0,
+      advMax: MAX_ADVERSARIAL_PASSES,
       // Lineage (issue #245): carry the origin identity onto the convergence instance so every
       // descendant (and any message it correlates) is stitched back to the originating request.
       // A human/webhook PR that is its own root carries its own `pr_key` (never NULL — see above).
@@ -1669,15 +1698,19 @@ interface JobSearchItem {
   worker?: string;
   deadline?: string | null;
   state?: string;
+  /** The job's `zeebe:taskDefinition` type — read to defensively re-filter the wire `$in` type
+   * filter so a non-agent job can never masquerade as a leasing convergence agent. */
+  type?: string;
 }
 
-/** One job-activation poll pass. The `converging` status means the process is parked at the
- * `review-round` service task with a `senior:pr-review` job outstanding — but it does not say
- * whether an external agent has *activated* (leased) that job yet. This pass reads that off the
- * engine's Camunda-8 `/v2/jobs/search`: an activated job carries a leasing `worker` + a lock
- * `deadline`; a merely-created (queued) one carries neither. (The wire `state` can't tell them
- * apart — Camunda's JobStateEnum has no ACTIVATED value, so the engine projects Activated ->
- * CREATED; the `worker`/`deadline` fields are the compatible activation signal.)
+/** One job-activation poll pass. The `converging` status means the process is parked at a
+ * convergence-agent service task (`review-round`'s `senior:pr-review`, or `adversarial-review`'s
+ * `senior:adversarial-review` — issue #844) with a job outstanding — but it does not say whether an
+ * external agent has *activated* (leased) that job yet. This pass reads that off the engine's
+ * Camunda-8 `/v2/jobs/search`: an activated job carries a leasing `worker` + a lock `deadline`; a
+ * merely-created (queued) one carries neither. (The wire `state` can't tell them apart — Camunda's
+ * JobStateEnum has no ACTIVATED value, so the engine projects Activated -> CREATED; the
+ * `worker`/`deadline` fields are the compatible activation signal.)
  *
  * It writes `active_worker` + `lease_until` onto the PR row so the pages surface can show
  * "agent working" vs "queued (awaiting an agent)", updating (and bumping `updated_at`) only on
@@ -1691,10 +1724,21 @@ async function pollJobActivation(
   const base = restAddress.replace(/\/+$/, "");
   const headers: Record<string, string> = { "content-type": "application/json" };
   if (engineToken) headers.authorization = `Bearer ${engineToken}`;
+  await pollJobActivationImpl(data, base, headers);
+}
 
+/** Testable core of {@link pollJobActivation}: given the normalised `base` URL and prepared auth
+ * `headers`, reconcile every `converging` PR row against the engine's open convergence-agent jobs.
+ * Split out so tests can exercise the reconciliation with a stubbed `fetch` without re-deriving
+ * transport wiring. */
+export async function pollJobActivationImpl(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
+) {
   const all = await prsTracking(data).all();
   for (const pr of all) {
-    // Only a `converging` PR has a live review-round job. Any other status with a stale worker
+    // Only a `converging` PR has a live convergence-agent job. Any other status with a stale worker
     // set (e.g. it just moved to `waiting_review`) gets cleared so the grid can't show a
     // phantom "agent working". ADR-0065: classify on the DERIVED status, not the base transient —
     // a PR whose instance was terminated out-of-band keeps its base `status` frozen at `converging`
@@ -1731,7 +1775,15 @@ async function pollJobActivation(
         method: "POST",
         headers,
         body: JSON.stringify({
-          filter: { type: REVIEW_JOB_TYPE, processInstanceKey: pr.process_key, state: "CREATED" },
+          filter: {
+            // ANY convergence-agent job type: the loop moves between `review-round`
+            // (`senior:pr-review`) and `adversarial-review` (`senior:adversarial-review`) without
+            // leaving `converging`, so filtering on only one would clear the lease mid-handoff and
+            // report "queued" while the other agent is actively working (issue #845 review).
+            type: { $in: [...CONVERGENCE_AGENT_JOB_TYPES] },
+            processInstanceKey: pr.process_key,
+            state: "CREATED",
+          },
           page: { limit: 20 },
         }),
       });
@@ -1739,9 +1791,16 @@ async function pollJobActivation(
       // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
       const body = (await res.json()) as { items?: JobSearchItem[] };
       // An open job with a leasing worker means an agent has activated it. Prefer the one with
-      // the latest deadline if several are open (there is normally at most one).
+      // the latest deadline if several are open (there is normally at most one). Re-filter on the
+      // job type defensively in case the wire `$in` filter is ignored, so a non-agent job (e.g. an
+      // internal `pr.*` worker) can never masquerade as a leasing convergence agent.
       const activated = (body.items ?? [])
-        .filter((j) => typeof j.worker === "string" && j.worker.length > 0)
+        .filter(
+          (j) =>
+            typeof j.worker === "string" &&
+            j.worker.length > 0 &&
+            CONVERGENCE_AGENT_JOB_TYPES.includes(j.type ?? ""),
+        )
         .sort((a, b) => (a.deadline ?? "").localeCompare(b.deadline ?? ""))
         .pop();
       if (activated) {

package/nano.app.json

@@ -255,7 +255,8 @@
     "senior:trial-merge",
     "senior:retro",
     "senior:conformance",
-    "senior:scope-classify"
+    "senior:scope-classify",
+    "senior:adversarial-review"
   ],
   "surfaces": {
     "taskInbox": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.199.0",
+  "version": "0.200.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",