@nanobpm/nano-workforce 0.97.1 → 0.98.0

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);
+});

package/app/service.ts

@@ -11,6 +11,16 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
+import {
+  CAPS_RESOLVED_MESSAGE,
+  type CapabilityNeed,
+  capabilityGateKey,
+  capabilityNeedToProbeInput,
+  capabilityTaskBarrierKey,
+  type ResolvedCapability,
+  renderResolvedDepsBrief,
+  UnresolvableCapabilityRefError,
+} from "./capabilityNeed.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
 import { backfillFeatureStages, deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
@@ -35,13 +45,16 @@ import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./m
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
 import {
   backfillPlanBuckets,
+  capabilityGates,
   inboundPlanDeps,
   planReviews,
   plans,
   planTaskDeps,
+  planTaskNeeds,
   planTasks,
 } from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
+import { defaultProbeExec, type ProbeExec, probeOnce, type ReadinessProbe, readinessTimeout } from "./readiness.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -1307,6 +1320,231 @@ export async function pollWaveGatesImpl(
   }
 }
 
+/** The readiness-gate process id (`resources/processes/readiness-gate.bpmn`) the capability reconciler
+ * starts one instance of per unresolved need — the durable, bounded, resumable wait that escalates to
+ * an operator if the capability never ships (#258). Single source of truth for the string. */
+const READINESS_GATE_PROCESS_ID = "readiness-gate";
+
+/** Generic sibling of {@link waveMergedSubscriptionOpen}: is `processKey` right now parked at a catch
+ * event with an OPEN (`CREATED`) subscription for `messageName` correlated on `correlationKey`? The
+ * capability barrier (`wait-caps-resolved`) uses this to stay level-triggered exactly like the
+ * wave-merge barrier — we publish `caps-resolved` ONLY into a subscription we've observed open, so a
+ * signal is never dropped into the void nor buffered to trip a later task's barrier. Returns `true`
+ * (open — safe to release), `false` (no open subscription), or `null` (transport unhappy / unparseable
+ * — "unknown", retry next pass). Every field must be present and match explicitly (an item omitting a
+ * field is "unknown", not a match) — a false negative only costs a retry, a false positive is a wedge.
+ *
+ * Unlike the wave-merge barrier (one subscription per plan, correlated on `planKey`), the capability
+ * barrier opens ONE subscription PER TASK (each on its own `<planKey>:<taskId>` key), so a single
+ * plan-fanout instance can have MANY `caps-resolved` subscriptions open at once. We therefore scope the
+ * search server-side by `correlationKey` too — filtering only on process + message could return a page
+ * of sibling tasks' subscriptions that overflows the page limit and omits THIS task's, a false negative
+ * that wedges the gate forever. The client-side re-filter below is retained defensively. */
+async function messageSubscriptionOpen(
+  base: string,
+  headers: Record<string, string>,
+  processKey: string,
+  messageName: string,
+  correlationKey: string,
+): Promise<boolean | null> {
+  try {
+    const res = await fetch(`${base}/message-subscriptions/search`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        filter: { processInstanceKey: processKey, messageName, correlationKey, messageSubscriptionState: "CREATED" },
+        page: { limit: 50 },
+      }),
+    });
+    if (!res.ok) return null;
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const body = (await res.json()) as { items?: MessageSubscriptionSearchItem[] };
+    return (body.items ?? []).some(
+      (it) =>
+        it.messageName === messageName &&
+        it.correlationKey === correlationKey &&
+        typeof it.messageSubscriptionState === "string" &&
+        it.messageSubscriptionState.toUpperCase() === "CREATED",
+    );
+  } catch (err) {
+    console.error(`[poller] caps-resolved subscription ${correlationKey}: ${err}`);
+    return null;
+  }
+}
+
+/** The gate timeout (ISO-8601) seeded onto every capability readiness-gate. A capability need carries
+ * no per-probe poll policy, so the bound is always the env/default (`NANO_READINESS_POLL_TIMEOUT`,
+ * else 30m) — derived from readiness.ts's ONE place so it can't drift from the worker's local budget. */
+function capabilityGateTimeout(env: Record<string, string | undefined>): string {
+  return readinessTimeout({ kind: "capability", target: "" } satisfies ReadinessProbe, env);
+}
+
+/** Capability-edge reconcile pass (issue #289). The host half of the "consumer readiness edge":
+ * plan-fanout's per-task fan-out parks at the `wait-caps-resolved` message barrier for any task that
+ * declared cross-repo capability `needs` (049_plan_task_needs.sql). Here we reconcile, on EVERY pass
+ * and idempotently, each such parked task against the external fact "has every one of its needed
+ * capabilities shipped as a published `pkg@version`?", publishing `caps-resolved` (correlated on the
+ * per-task barrier key) with the late-bound resolved-dependencies brief to release the agent whenever
+ * ALL its needs resolve.
+ *
+ * The bounded/durable/resumable WAIT is NOT re-implemented here — it lives in the EXISTING
+ * `readiness-gate` process (#258), which we start exactly once per need (recording its instance key on
+ * `capability_gates.process_key`) so a capability that never ships escalates to an operator instead of
+ * wedging the epic. This pass only (a) starts those gates and (b) performs a single DETERMINISTIC
+ * provenance lookup per unresolved need (`probeOnce`, the gate's OWN matcher, reused verbatim — never a
+ * second poll loop) to capture the resolved `pkg@version` for the late-bind. All state is durable in
+ * `capability_gates`, so a host restart re-derives the picture from the DB: it never re-starts a gate,
+ * never re-probes a resolved need, and — being level-triggered on the open subscription — never
+ * re-publishes into a released barrier.
+ *
+ * Concurrency correctness (issue #289 §4, inherited from #274): an unrelated upstream release during
+ * the wait does NOT resolve the edge (the provenance predicate matches only the capability-bearing
+ * version) and does NOT spin an agent (this pass uses the deterministic lookup only — the gated
+ * empirical `verifyCommand` fallback lives solely in the gate's worker, never here, so it can never
+ * fire per unrelated release). */
+export async function pollCapabilityGatesImpl(
+  data: DataLayer,
+  engine: EngineClient,
+  base: string,
+  headers: Record<string, string>,
+  exec: ProbeExec = defaultProbeExec(),
+  env: Record<string, string | undefined> = process.env,
+) {
+  const gateTable = capabilityGates(data);
+  const probeTimeout = capabilityGateTimeout(env);
+  for (const plan of await plans(data).all()) {
+    const planKey = plan.plan_key;
+    const processKey = plan.process_key;
+    if (!processKey) continue; // no instance key to correlate the barrier against yet
+    const needRows = await planTaskNeeds(data).find({ plan_key: planKey });
+    if (needRows.length === 0) continue;
+    // Group needs by consuming task — a task's barrier releases ONCE, fanning in ALL its needs.
+    const needsByTask = new Map<string, CapabilityNeed[]>();
+    for (const n of needRows) {
+      const list = needsByTask.get(n.task_id) ?? [];
+      list.push({
+        capabilityRef: n.capability_ref,
+        package: n.package,
+        ...(n.verify_command ? { verifyCommand: n.verify_command } : {}),
+      });
+      needsByTask.set(n.task_id, list);
+    }
+    for (const [taskId, needs] of needsByTask) {
+      const barrierKey = capabilityTaskBarrierKey(planKey, taskId);
+      try {
+        // Only reconcile a task whose fan-out is actually parked at `wait-caps-resolved` (an OPEN
+        // subscription): otherwise publishing would be a signal into the void (the #262 wedge class).
+        const open = await messageSubscriptionOpen(base, headers, processKey, CAPS_RESOLVED_MESSAGE, barrierKey);
+        if (open !== true) continue; // not parked here yet / already released / unknown → retry next pass
+
+        const resolved: ResolvedCapability[] = [];
+        let allResolved = true;
+        for (const need of needs) {
+          const gateKey = capabilityGateKey(planKey, taskId, need.capabilityRef, need.package);
+          let row = await gateTable.findOne({ gate_key: gateKey });
+
+          // Shape the need into the readiness-gate's probe input. A handle that names no owner/repo
+          // releases source is un-pollable — record it so the operator sees the wedge, and treat the
+          // need as unresolved (it can only clear once the handle is corrected on a re-plan).
+          let probeInput: ReturnType<typeof capabilityNeedToProbeInput>;
+          try {
+            probeInput = capabilityNeedToProbeInput(need, { planKey, taskId, probeTimeout });
+          } catch (err) {
+            if (err instanceof UnresolvableCapabilityRefError) {
+              if (!row) {
+                await gateTable.insert({
+                  gate_key: gateKey,
+                  plan_key: planKey,
+                  task_id: taskId,
+                  capability_ref: need.capabilityRef,
+                  package: need.package,
+                  status: "pending",
+                  resolved_artifact: null,
+                  process_key: null,
+                  created_at: now(),
+                  updated_at: now(),
+                });
+              }
+              console.error(`[poller] capability-gate ${gateKey}: ${err.message}`);
+              allResolved = false;
+              continue;
+            }
+            throw err;
+          }
+
+          // First sighting: record the gate row so we start it exactly once and survive a restart.
+          if (!row) {
+            await gateTable.insert({
+              gate_key: gateKey,
+              plan_key: planKey,
+              task_id: taskId,
+              capability_ref: need.capabilityRef,
+              package: need.package,
+              status: "pending",
+              resolved_artifact: null,
+              process_key: null,
+              created_at: now(),
+              updated_at: now(),
+            });
+            row = await gateTable.findOne({ gate_key: gateKey });
+          }
+
+          // Start the EXISTING durable readiness-gate exactly once (bounded wait + operator escalation
+          // if the capability never ships). Idempotent: guarded on `process_key`, so a restart never
+          // double-starts. A start failure is non-fatal — we retry the start next pass.
+          if (row && !row.process_key) {
+            try {
+              const { processInstanceKey } = await engine.createInstance({
+                processDefinitionId: READINESS_GATE_PROCESS_ID,
+                variables: {
+                  gateKey: probeInput.gateKey,
+                  probeTimeout: probeInput.probeTimeout,
+                  onTimeout: probeInput.onTimeout,
+                  probe: probeInput.probe,
+                },
+              });
+              await gateTable.update(gateKey, { process_key: processInstanceKey, updated_at: now() });
+              row.process_key = processInstanceKey;
+            } catch (err) {
+              console.error(`[poller] capability-gate ${gateKey} start: ${err}`);
+            }
+          }
+
+          // Already resolved on an earlier pass → reuse the pinned artifact (never re-probe).
+          if (row && row.status === "resolved" && row.resolved_artifact) {
+            resolved.push({ capabilityRef: need.capabilityRef, resolvedArtifact: row.resolved_artifact });
+            continue;
+          }
+
+          // One deterministic provenance lookup (NOT a wait loop): has the capability shipped?
+          const result = await probeOnce(probeInput.probe, exec, env);
+          const artifact = result.bind?.resolvedArtifact;
+          if (result.ready && artifact) {
+            await gateTable.update(gateKey, { status: "resolved", resolved_artifact: artifact, updated_at: now() });
+            resolved.push({ capabilityRef: need.capabilityRef, resolvedArtifact: artifact });
+          } else {
+            allResolved = false;
+          }
+        }
+
+        // Fan-in: release the task ONLY when every need resolved. The brief pins each
+        // `capabilityRef → pkg@version` into the agent's prompt (late-bind, issue #289 §3).
+        if (allResolved && resolved.length === needs.length) {
+          const resolvedDepsBrief = renderResolvedDepsBrief(resolved);
+          await engine.publishMessage({
+            name: CAPS_RESOLVED_MESSAGE,
+            correlationKey: barrierKey,
+            variables: { resolvedDepsBrief },
+          });
+          console.log(`[poller] capabilities resolved -> ${barrierKey} (${resolved.length})`);
+        }
+      } catch (err) {
+        console.error(`[poller] capability-gate ${barrierKey}: ${err}`);
+      }
+    }
+  }
+}
+
 /** Idempotent read-model pass: recompute each plan's derived `delivery` signal (issue #171) by
  * joining its slice tasks' `pr_key` → `pull_requests.status`, and denormalise it onto the `plans`
  * row so the epics overview / detail views can read it as a flat column (Urban's datasource can't
@@ -1866,6 +2104,7 @@ export async function pollOnce(
     const headers: Record<string, string> = { "content-type": "application/json" };
     if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
     await pollWaveGatesImpl(data, engine, token, base, headers);
+    await pollCapabilityGatesImpl(data, engine, base, headers);
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);
   }