@nanobpm/nano-workforce 0.97.1 → 0.98.1

package/app/mergeRetryArm.test.ts

@@ -0,0 +1,100 @@
+// Structural regression guard for the merge-loop transient-retry arm (issue #334).
+//
+// #334: a transient, GitHub-flagged-retryable merge race ("Base branch was modified. Review and
+// try the merge again.") was mapped to `blocked` → a decision-required human escalation on a PR
+// that was actually mergeable once the base settled. The fix adds a `retry` merge outcome that
+// re-enters the merge loop on the settled base through a *bounded* budget gate — mirroring the
+// `gw-ci-fix` within-budget / budget-exhausted pattern — WITHOUT any remediation agent, and
+// escalates via the existing `merge-esc-attempt` only when the retry budget is exhausted (so a
+// continuously-moving base still escalates promptly rather than spinning forever).
+//
+// This test asserts the arm's topology on the committed model so it cannot regress silently. It is
+// a pure text assertion over the BPMN (no engine), matching the repo's lightweight model-guard style.
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const bpmn = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+function hasFlow(source: string, target: string): boolean {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*\\bsourceRef="${source}"[^>]*\\btargetRef="${target}"|` +
+      `<bpmn:sequenceFlow\\b[^>]*\\btargetRef="${target}"[^>]*\\bsourceRef="${source}"`,
+  );
+  return re.test(flat);
+}
+
+function flowHasId(id: string, source: string, target: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:sequenceFlow\\b[^>]*\\bid="${id}"[^>]*/?>`));
+  if (!m) return false;
+  const tag = m[0];
+  return tag.includes(`sourceRef="${source}"`) && tag.includes(`targetRef="${target}"`);
+}
+
+function gatewayDefault(id: string, def: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:exclusiveGateway\\b[^>]*\\bid="${id}"[^>]*>`));
+  if (!m) return false;
+  return m[0].includes(`default="${def}"`);
+}
+
+// Assert the conditionExpression *of a specific sequenceFlow* contains `needle`, so the guard
+// cannot be satisfied by the same substring appearing on an unrelated flow (e.g. the
+// merge-esc-attempt question FEEL also mentions `mergeStatus = "retry"`).
+function flowHasCondition(id: string, needle: string): boolean {
+  const m = flat.match(
+    new RegExp(`<bpmn:sequenceFlow\\b[^>]*\\bid="${id}"[^>]*>(.*?)</bpmn:sequenceFlow>`),
+  );
+  if (!m) return false;
+  const cond = m[1].match(/<bpmn:conditionExpression\b[^>]*>(.*?)<\/bpmn:conditionExpression>/);
+  return cond ? cond[1].includes(needle) : false;
+}
+
+test("gw-merge routes the retry outcome to a dedicated budget gate, not to a human", () => {
+  // A `retry` merge result must reach the retry-budget gate…
+  assert(hasFlow("gw-merge", "gw-merge-retry"), "gw-merge → gw-merge-retry (retry) missing");
+  // …guarded by the exact retry condition (mergeStatus = "retry").
+  assert(flowHasId("f_m_gRetry", "gw-merge", "gw-merge-retry"), "f_m_gRetry must be gw-merge → gw-merge-retry");
+  // Assert the retry condition on f_m_gRetry ITSELF — not merely anywhere in the model — so the
+  // guard cannot be satisfied by the identical substring in the merge-esc-attempt question FEEL.
+  assert(
+    flowHasCondition("f_m_gRetry", 'mergeStatus = "retry"'),
+    'f_m_gRetry conditionExpression must be mergeStatus = "retry"',
+  );
+});
+
+test("retry arm mirrors the fix-ci arm: budget gate → re-arm, exhausted → escalate", () => {
+  // Within budget → re-arm the merge poller (re-attempt on the settled base). No remediation agent.
+  assert(hasFlow("gw-merge-retry", "arm-merge"), "gw-merge-retry → arm-merge (within budget) missing");
+  assert(flowHasId("f_mr_go", "gw-merge-retry", "arm-merge"), "f_mr_go must be gw-merge-retry → arm-merge");
+  assertStringIncludes(flat, "mergeRetryRound &lt;= mergeRetryMax");
+
+  // Budget exhausted → the EXISTING human escalation (merge-esc-attempt), and it is the gateway default
+  // so a continuously-moving base can never spin past the cap.
+  assert(
+    hasFlow("gw-merge-retry", "merge-esc-attempt"),
+    "gw-merge-retry → merge-esc-attempt (budget exhausted) missing",
+  );
+  assert(gatewayDefault("gw-merge-retry", "f_mr_giveup"), "gw-merge-retry must default to f_mr_giveup");
+  assert(
+    flowHasId("f_mr_giveup", "gw-merge-retry", "merge-esc-attempt"),
+    "f_mr_giveup must default gw-merge-retry → merge-esc-attempt",
+  );
+});
+
+test("the retry arm advances the attempt counter only on a transient retry outcome", () => {
+  // The counter advances ONLY when the merge attempt returned `retry` — mirroring how fix-ci/rebase
+  // advance their own rounds only on their own remediation — so unrelated merge attempts (initial,
+  // post-rebase, post-fix-ci, post-evict) can't consume the transient-retry budget. N consecutive
+  // transient races then trip the `mergeRetryRound <= mergeRetryMax` gate at exactly the cap.
+  assertStringIncludes(flat, "=if mergeStatus = &#34;retry&#34; then mergeRetryRound + 1 else mergeRetryRound");
+});
+
+test("the retry arm has NO remediation agent (contrast the conflict/rebase arm)", () => {
+  // The base-moved race needs only a re-attempt on the settled base — no rebase/CI-fix agent. The
+  // within-budget flow goes straight back to arm-merge, never through a `senior:*` task.
+  assert(flowHasId("f_mr_go", "gw-merge-retry", "arm-merge"), "retry within-budget must go directly to arm-merge");
+  // Sanity: the untouched blocked path still escalates directly (a genuine refusal is unchanged).
+  assert(flowHasId("f_m_gBlocked", "gw-merge", "merge-esc-attempt"), "blocked → merge-esc-attempt must remain");
+});

package/app/plan.ts

@@ -11,6 +11,7 @@
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { capsWaitTimeout, DEFAULT_CAPS_WAIT_TIMEOUT } from "./capsWait.ts";
 import { deriveEpicBucket, epicIsAcknowledgeable } from "./delivery.ts";
 import { EPIC_PHASE } from "./epicPhase.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
@@ -37,6 +38,17 @@ export const ESCALATION_SLA_TIMEOUT = escalationSlaTimeout(
   DEFAULT_ESCALATION_SLA_TIMEOUT,
 );
 
+/** The fleet-wide capability-barrier bound (ISO-8601 duration) seeded onto every plan-fanout instance
+ * as the `capsWaitTimeout` process variable and evaluated by the `wait-caps-timeout` timer arm of the
+ * `wait-caps-resolved` event-based gateway. An operator sets `NANO_CAPS_WAIT_TIMEOUT`; a malformed
+ * value falls back to {@link DEFAULT_CAPS_WAIT_TIMEOUT} so a bad env can never deploy an
+ * uninterpretable timer. Bounds a task's wait on an unresolvable cross-repo capability so it escalates
+ * to an operator instead of parking forever. */
+export const CAPS_WAIT_TIMEOUT = capsWaitTimeout(
+  process.env.NANO_CAPS_WAIT_TIMEOUT,
+  DEFAULT_CAPS_WAIT_TIMEOUT,
+);
+
 const now = () => new Date().toISOString();
 
 // Agent prompts are no longer read by the host. The `senior:plan`, `senior:plan-review`, and
@@ -263,6 +275,51 @@ export interface PlanTaskDep {
 export const planTaskDeps = (data: DataLayer) =>
   data.table<PlanTaskDep>("plan_task_deps", "plan_key");
 
+/** One cross-repo CAPABILITY EDGE on a plan task (049_plan_task_needs.sql, issue #289): the
+ * consuming `task_id` must not start until the upstream capability `capability_ref` first ships as
+ * a published `package` version. Levelized from the planner's `RecordPlanTask.needs[]` by
+ * `pr.record-plan`, read back by `pr.select-wave` to gate the task before dispatch. Keyed on
+ * `plan_key` (like {@link PlanTaskDep}) so one delete clears a plan's whole need set on re-plan.
+ *
+ * `capability_ref` is the STABLE handle (`owner/repo#NNN` | `repo#NNN` | `#NNN`) — NEVER a version
+ * (the #263 core decision). `package` is the per-package-scoped provenance artifact. `verify_command`
+ * is the optional gated empirical fallback (#274 decision 5); NULL means deterministic-provenance-only. */
+export interface PlanTaskNeed {
+  plan_key: string;
+  task_id: string;
+  capability_ref: string;
+  package: string;
+  verify_command: string | null;
+}
+export const planTaskNeeds = (data: DataLayer) =>
+  data.table<PlanTaskNeed>("plan_task_needs", "plan_key");
+
+/** One host-orchestrated CAPABILITY GATE (050_capability_gates.sql, issue #289): the durable,
+ * idempotent state the `pollCapabilityGatesImpl` reconciler keeps for ONE (plan, task, capability
+ * need) while its plan-fanout fan-out is parked at the `wait-caps-resolved` barrier. The host starts
+ * the EXISTING `readiness-gate` process (#258) per need — recording its instance key on `process_key`
+ * so it starts exactly once — and, each pass, reconciles whether the capability has shipped as a
+ * published `pkg@version`; on match it stamps `resolved_artifact` and flips `status` to `resolved`.
+ * When every one of a task's needs is `resolved` the reconciler publishes `caps-resolved` (releasing
+ * the barrier with the late-bound brief). Keyed on the readiness-gate correlation key
+ * `<plan_key>:<task_id>:<capability_ref>:<package>` ({@link capabilityGateKey}) so a host restart
+ * re-derives the whole picture from the DB — never re-starting a gate nor re-publishing a settled
+ * barrier. `package` is part of the key so two needs sharing a `capability_ref` across different
+ * packages never collide on one gate row. */
+export interface CapabilityGate {
+  gate_key: string;
+  plan_key: string;
+  task_id: string;
+  capability_ref: string;
+  package: string;
+  status: string;
+  resolved_artifact: string | null;
+  process_key: string | null;
+  created_at: string;
+  updated_at: string;
+}
+export const capabilityGates = (data: DataLayer) =>
+  data.table<CapabilityGate>("capability_gates", "gate_key");
 /** One INTER-epic dependency edge in the plan-set DAG (issue #292, slice S1): the epic `plan_key`
  * waits for the producer epic `depends_on_plan_key` to publish a capability before it may fan out.
  *
@@ -1014,6 +1071,12 @@ export async function startPlan(
       // `operators` candidate group); an operator/agent can claim/reassign via the task inbox.
       escalationSlaTimeout: ESCALATION_SLA_TIMEOUT,
       escalationAssignee: null,
+      // Capability-barrier bound (#289): the validated ISO-8601 duration read by the
+      // `wait-caps-timeout` timer arm of the `wait-caps-resolved` event-based gateway. A task whose
+      // declared cross-repo capabilities never resolve (most acutely an unresolvable capabilityRef the
+      // host reconciler can never gate) escalates to the `feature-escalation` operator user task when
+      // this elapses, instead of parking at the barrier forever — durable in-process liveness.
+      capsWaitTimeout: CAPS_WAIT_TIMEOUT,
       // Coordination blackboard (#51): the capability URL + the protocol brief that each
       // implementer agent gets appended to its prompt (composed into `appendPrompt` in
       // plan-fanout.bpmn's implement-task). Advisory shared state, delivered in-band, used

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
+import { parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -15,6 +15,8 @@ function memTable(rows: any[], key: string) {
     all: () => Promise.resolve([...rows]),
     find: (q: any) =>
       Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
     insert: (r: any) => {
       rows.push(r);
       return Promise.resolve(r);
@@ -704,3 +706,375 @@ test("pollWaveGatesImpl never releases the barrier on an unverifiable subscripti
     assertEquals(plan.gate_wave, 1, "gate_wave must stay armed while no OPEN subscription is confirmed");
   });
 });
+
+// ── pollCapabilityGatesImpl — the host half of the cross-repo capability edge (issue #289) ──────────
+//
+// plan-fanout parks a task with capability `needs` at the `wait-caps-resolved` message barrier. This
+// reconciler, on every pass, (a) starts the durable `readiness-gate` once per need, (b) does a single
+// DETERMINISTIC provenance lookup (`probeOnce`, reused verbatim), and (c) publishes `caps-resolved`
+// (correlated on the per-task barrier key `<planKey>:<taskId>`) with the late-bound resolved-deps brief
+// ONLY when EVERY need has shipped as a published `pkg@version` AND the barrier subscription is open.
+//
+// Stubs: `/message-subscriptions/search` (toggle the barrier open per barrier key), a capture engine
+// (`createInstance`/`publishMessage`), and a `ProbeExec` returning a canned `gh api .../releases`
+// payload so `matchCapability` resolves the lowest capability-bearing version — all hermetic.
+
+function capsSubscriptionFetch(openKeys: Set<string>) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/message-subscriptions/search")) throw new Error(`unexpected fetch: ${u}`);
+    const body = JSON.parse(String(init?.body ?? "{}")) as {
+      filter?: { messageName?: string; processInstanceKey?: string };
+    };
+    const key = body.filter?.processInstanceKey ?? "";
+    // The reconciler filters by processInstanceKey + messageName; we toggle by barrier correlationKey,
+    // which the search response carries back on each item. Return an open item for every requested key
+    // registered in `openKeys` (keyed by the barrier correlationKey the caller expects).
+    const items = [...openKeys]
+      .filter((k) => k.startsWith(`${key}|`))
+      .map((k) => ({
+        messageName: "caps-resolved",
+        correlationKey: k.slice(k.indexOf("|") + 1),
+        messageSubscriptionState: "CREATED",
+      }));
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+// A `ProbeExec` whose `gh api .../releases` output resolves `capabilityRef` #274 to `@nanobpm/urban@0.54.0`
+// (the LOWEST version whose body references #274) — or resolves nothing when `ready` is false.
+function capsProbeExec(ready: boolean) {
+  const releases = ready
+    ? [
+        { tag_name: "@nanobpm/urban@0.55.0", body: "## Provenance\n- nanobpm/nano-ide#274" },
+        { tag_name: "@nanobpm/urban@0.54.0", body: "## Provenance\n- nanobpm/nano-ide#274" },
+        { tag_name: "@nanobpm/urban@0.53.0", body: "unrelated" },
+      ]
+    : [{ tag_name: "@nanobpm/urban@0.53.0", body: "unrelated" }];
+  const calls: string[] = [];
+  return {
+    calls,
+    exec: {
+      httpGet: () => Promise.reject(new Error("no http probe expected")),
+      run: (command: string) => {
+        calls.push(command);
+        return Promise.resolve({ code: 0, stdout: JSON.stringify(releases), stderr: "" });
+      },
+    },
+  };
+}
+
+function capsDataLayer(stores: Record<string, { rows: any[]; key: string }>) {
+  return {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+}
+
+function capsEngine() {
+  const created: { processDefinitionId?: string; variables?: Record<string, unknown> }[] = [];
+  const published: { name: string; correlationKey?: string; variables?: Record<string, unknown> }[] = [];
+  let seq = 0;
+  return {
+    created,
+    published,
+    engine: {
+      createInstance: (req: { processDefinitionId?: string; variables?: Record<string, unknown> }) => {
+        created.push(req);
+        return Promise.resolve({ processInstanceKey: `RG-${++seq}` });
+      },
+      publishMessage: (input: { name: string; correlationKey?: string; variables?: Record<string, unknown> }) => {
+        published.push(input);
+        return Promise.resolve();
+      },
+    } as any,
+  };
+}
+
+test("pollCapabilityGatesImpl: releases a task once every need ships, starting the gate + publishing the resolved brief (#289)", async () => {
+  const PLAN_KEY = "owner/repo#7";
+  const PI = "PI-289";
+  const TASK = "gap-a";
+  const barrierKey = `${PLAN_KEY}:${TASK}`;
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, process_key: PI }], key: "plan_key" },
+    plan_task_needs: {
+      rows: [
+        {
+          plan_key: PLAN_KEY,
+          task_id: TASK,
+          capability_ref: "nanobpm/nano-ide#274",
+          package: "@nanobpm/urban",
+          verify_command: null,
+        },
+      ],
+      key: "plan_key",
+    },
+    capability_gates: { rows: [], key: "gate_key" },
+  };
+  const data = capsDataLayer(stores);
+  const { engine, created, published } = capsEngine();
+  const { exec, calls } = capsProbeExec(true);
+  const headers = { "content-type": "application/json" };
+  const open = new Set<string>([`${PI}|${barrierKey}`]);
+  const prevFetch = globalThis.fetch;
+  globalThis.fetch = capsSubscriptionFetch(open) as typeof fetch;
+  try {
+    await pollCapabilityGatesImpl(data, engine, "http://engine/v2", headers, exec, {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+
+  // The durable readiness-gate was started exactly once, its instance key persisted.
+  assertEquals(created.length, 1, "readiness-gate started exactly once");
+  assertEquals(created[0]?.processDefinitionId, "readiness-gate");
+  assertEquals(stores.capability_gates.rows.length, 1);
+  assertEquals(stores.capability_gates.rows[0]?.process_key, "RG-1");
+  assertEquals(stores.capability_gates.rows[0]?.status, "resolved");
+  assertEquals(stores.capability_gates.rows[0]?.resolved_artifact, "@nanobpm/urban@0.54.0");
+
+  // The barrier was released once with the late-bound brief pinning the LOWEST capability-bearing version.
+  assertEquals(published.length, 1, "caps-resolved published once");
+  assertEquals(published[0]?.name, "caps-resolved");
+  assertEquals(published[0]?.correlationKey, barrierKey);
+  const brief = String(published[0]?.variables?.["resolvedDepsBrief"] ?? "");
+  assertEquals(brief.includes("@nanobpm/urban@0.54.0"), true, "brief pins the resolved artifact");
+  assertEquals(brief.includes("nanobpm/nano-ide#274"), true, "brief names the capability ref");
+  assertEquals(calls.length, 1, "one deterministic provenance lookup");
+});
+
+test("pollCapabilityGatesImpl: an unresolved need starts the gate but never releases the barrier (#289)", async () => {
+  const PLAN_KEY = "owner/repo#8";
+  const PI = "PI-290";
+  const TASK = "gap-b";
+  const barrierKey = `${PLAN_KEY}:${TASK}`;
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, process_key: PI }], key: "plan_key" },
+    plan_task_needs: {
+      rows: [
+        {
+          plan_key: PLAN_KEY,
+          task_id: TASK,
+          capability_ref: "nanobpm/nano-ide#274",
+          package: "@nanobpm/urban",
+          verify_command: null,
+        },
+      ],
+      key: "plan_key",
+    },
+    capability_gates: { rows: [], key: "gate_key" },
+  };
+  const data = capsDataLayer(stores);
+  const { engine, created, published } = capsEngine();
+  const { exec } = capsProbeExec(false); // capability not published yet
+  const headers = { "content-type": "application/json" };
+  const open = new Set<string>([`${PI}|${barrierKey}`]);
+  const prevFetch = globalThis.fetch;
+  globalThis.fetch = capsSubscriptionFetch(open) as typeof fetch;
+  try {
+    await pollCapabilityGatesImpl(data, engine, "http://engine/v2", headers, exec, {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+
+  // The gate is still started (bounded/durable wait + operator escalation) but no release.
+  assertEquals(created.length, 1, "gate started even while unresolved");
+  assertEquals(stores.capability_gates.rows[0]?.status, "pending");
+  assertEquals(stores.capability_gates.rows[0]?.resolved_artifact, null);
+  assertEquals(published.length, 0, "barrier NOT released until the capability ships");
+});
+
+test("pollCapabilityGatesImpl: level-triggered — no publish and no re-probe when the barrier subscription is not open (#289)", async () => {
+  const PLAN_KEY = "owner/repo#9";
+  const PI = "PI-291";
+  const TASK = "gap-c";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, process_key: PI }], key: "plan_key" },
+    plan_task_needs: {
+      rows: [
+        {
+          plan_key: PLAN_KEY,
+          task_id: TASK,
+          capability_ref: "nanobpm/nano-ide#274",
+          package: "@nanobpm/urban",
+          verify_command: null,
+        },
+      ],
+      key: "plan_key",
+    },
+    capability_gates: { rows: [], key: "gate_key" },
+  };
+  const data = capsDataLayer(stores);
+  const { engine, created, published } = capsEngine();
+  const { exec, calls } = capsProbeExec(true);
+  const headers = { "content-type": "application/json" };
+  const prevFetch = globalThis.fetch;
+  globalThis.fetch = capsSubscriptionFetch(new Set<string>()) as typeof fetch; // barrier not parked
+  try {
+    await pollCapabilityGatesImpl(data, engine, "http://engine/v2", headers, exec, {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(published.length, 0, "no publish into a subscription that is not open");
+  assertEquals(created.length, 0, "no gate work until the task is parked at the barrier");
+  assertEquals(calls.length, 0, "no provenance probe until the task is parked at the barrier");
+});
+
+test("pollCapabilityGatesImpl: idempotent — a resolved gate is reused without a re-probe or a second publish (#289)", async () => {
+  const PLAN_KEY = "owner/repo#10";
+  const PI = "PI-292";
+  const TASK = "gap-d";
+  const barrierKey = `${PLAN_KEY}:${TASK}`;
+  const gateKey = `${PLAN_KEY}:${TASK}:nanobpm/nano-ide#274:@nanobpm/urban`;
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, process_key: PI }], key: "plan_key" },
+    plan_task_needs: {
+      rows: [
+        {
+          plan_key: PLAN_KEY,
+          task_id: TASK,
+          capability_ref: "nanobpm/nano-ide#274",
+          package: "@nanobpm/urban",
+          verify_command: null,
+        },
+      ],
+      key: "plan_key",
+    },
+    capability_gates: {
+      rows: [
+        {
+          gate_key: gateKey,
+          plan_key: PLAN_KEY,
+          task_id: TASK,
+          capability_ref: "nanobpm/nano-ide#274",
+          package: "@nanobpm/urban",
+          status: "resolved",
+          resolved_artifact: "@nanobpm/urban@0.54.0",
+          process_key: "RG-EXISTING",
+          created_at: "t0",
+          updated_at: "t0",
+        },
+      ],
+      key: "gate_key",
+    },
+  };
+  const data = capsDataLayer(stores);
+  const { engine, created, published } = capsEngine();
+  const { exec, calls } = capsProbeExec(true);
+  const headers = { "content-type": "application/json" };
+  const open = new Set<string>([`${PI}|${barrierKey}`]);
+  const prevFetch = globalThis.fetch;
+  globalThis.fetch = capsSubscriptionFetch(open) as typeof fetch;
+  try {
+    await pollCapabilityGatesImpl(data, engine, "http://engine/v2", headers, exec, {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(created.length, 0, "already-started gate is never re-started");
+  assertEquals(calls.length, 0, "already-resolved need is never re-probed");
+  assertEquals(published.length, 1, "the still-parked barrier is released from the pinned artifact");
+  assertEquals(published[0]?.correlationKey, barrierKey);
+});
+
+test("pollCapabilityGatesImpl: two needs sharing a capabilityRef across packages get distinct gate rows (#290)", async () => {
+  // Regression for the gate_key collision: `capabilityGateKey` folds `package` into the key, so a task
+  // that declares the SAME `capabilityRef` for two different packages tracks each `(capabilityRef,
+  // package)` edge on its OWN gate row and starts its OWN readiness-gate. With the old package-blind key
+  // the second need would alias the first row, only one gate would ever start, and the second package
+  // could never resolve — wedging the barrier forever.
+  const PLAN_KEY = "owner/repo#12";
+  const PI = "PI-294";
+  const TASK = "gap-f";
+  const barrierKey = `${PLAN_KEY}:${TASK}`;
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, process_key: PI }], key: "plan_key" },
+    plan_task_needs: {
+      rows: [
+        { plan_key: PLAN_KEY, task_id: TASK, capability_ref: "nanobpm/nano-ide#274", package: "@nanobpm/urban", verify_command: null },
+        { plan_key: PLAN_KEY, task_id: TASK, capability_ref: "nanobpm/nano-ide#274", package: "@nanobpm/urban-testkit", verify_command: null },
+      ],
+      key: "plan_key",
+    },
+    capability_gates: { rows: [], key: "gate_key" },
+  };
+  const data = capsDataLayer(stores);
+  const { engine, created, published } = capsEngine();
+  const { exec } = capsProbeExec(false); // neither capability published yet — both stay pending
+  const headers = { "content-type": "application/json" };
+  const open = new Set<string>([`${PI}|${barrierKey}`]);
+  const prevFetch = globalThis.fetch;
+  globalThis.fetch = capsSubscriptionFetch(open) as typeof fetch;
+  try {
+    await pollCapabilityGatesImpl(data, engine, "http://engine/v2", headers, exec, {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+
+  // Two distinct gate rows (one per package) — no collision, no aliasing.
+  assertEquals(stores.capability_gates.rows.length, 2, "one gate row per (capabilityRef, package) need");
+  const gateKeys = stores.capability_gates.rows.map((r) => r.gate_key).sort();
+  assertEquals(gateKeys, [
+    `${PLAN_KEY}:${TASK}:nanobpm/nano-ide#274:@nanobpm/urban`,
+    `${PLAN_KEY}:${TASK}:nanobpm/nano-ide#274:@nanobpm/urban-testkit`,
+  ]);
+  assertEquals(created.length, 2, "each need starts its own readiness-gate");
+  assertEquals(published.length, 0, "barrier NOT released while either need is unresolved");
+});
+
+test("pollCapabilityGatesImpl: scopes the barrier subscription search server-side by correlationKey (#290)", async () => {
+  // Regression for the page-limit false negative: the capability barrier opens ONE subscription per
+  // task, so a plan with many parked siblings can overflow a process+message-only search page and omit
+  // THIS task's subscription — wedging its gate forever. The reconciler must therefore scope the search
+  // by `correlationKey`. This stub emulates an engine that HONOURS the server-side `correlationKey`
+  // filter: it returns the open item only when the request carries the matching key (as the real engine
+  // does), so the old process+message-only filter would come back empty and never release the barrier.
+  const PLAN_KEY = "owner/repo#11";
+  const PI = "PI-293";
+  const TASK = "gap-e";
+  const barrierKey = `${PLAN_KEY}:${TASK}`;
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: PLAN_KEY, process_key: PI }], key: "plan_key" },
+    plan_task_needs: {
+      rows: [
+        {
+          plan_key: PLAN_KEY,
+          task_id: TASK,
+          capability_ref: "nanobpm/nano-ide#274",
+          package: "@nanobpm/urban",
+          verify_command: null,
+        },
+      ],
+      key: "plan_key",
+    },
+    capability_gates: { rows: [], key: "gate_key" },
+  };
+  const data = capsDataLayer(stores);
+  const { engine, published } = capsEngine();
+  const { exec } = capsProbeExec(true);
+  const headers = { "content-type": "application/json" };
+  const seenFilters: Array<Record<string, unknown>> = [];
+  const prevFetch = globalThis.fetch;
+  globalThis.fetch = ((url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/message-subscriptions/search")) throw new Error(`unexpected fetch: ${u}`);
+    const filter = (JSON.parse(String(init?.body ?? "{}")) as { filter?: Record<string, unknown> }).filter ?? {};
+    seenFilters.push(filter);
+    // Engine honours the server-side correlationKey filter: only the exactly-scoped query sees the item.
+    const items =
+      filter.correlationKey === barrierKey
+        ? [{ messageName: "caps-resolved", correlationKey: barrierKey, messageSubscriptionState: "CREATED" }]
+        : [];
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  }) as typeof fetch;
+  try {
+    await pollCapabilityGatesImpl(data, engine, "http://engine/v2", headers, exec, {});
+  } finally {
+    globalThis.fetch = prevFetch;
+  }
+  assertEquals(seenFilters[0]?.correlationKey, barrierKey, "search is scoped server-side by the barrier key");
+  assertEquals(published.length, 1, "the scoped search still finds THIS task's subscription and releases it");
+  assertEquals(published[0]?.correlationKey, barrierKey);
+});