@nanobpm/nano-workforce 0.97.1 → 0.98.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.98.0](https://github.com/nanobpm/nano-workforce/compare/v0.97.1...v0.98.0) (2026-08-19)
+
+
+### Features
+
+* host-orchestrated per-task capability barrier for epic dispatch ([#289](https://github.com/nanobpm/nano-workforce/issues/289)) ([#290](https://github.com/nanobpm/nano-workforce/issues/290)) ([bb2f4bf](https://github.com/nanobpm/nano-workforce/commit/bb2f4bffb04b63d3b43bdec762d37770d03b1efb)), closes [263/#274](https://github.com/nanobpm/nano-workforce/issues/274)
+
 ## [0.97.1](https://github.com/nanobpm/nano-workforce/compare/v0.97.0...v0.97.1) (2026-08-19)
 
 

package/app/capabilityNeed.test.ts

@@ -0,0 +1,156 @@
+// Unit coverage for the cross-repo capability-edge helpers (app/capabilityNeed.ts, issue #289).
+//
+// The gate wiring is proven through the process; these tests pin the pure surface: tolerant need
+// parsing + de-dupe, the handle → releases-repo derivation, the need → readiness-gate input mapping
+// (reusing the #274 `capability` probe verbatim), the gate-key shape, and the late-bind prompt brief.
+import { test } from "node:test";
+import { assert, assertEquals, assertStringIncludes, assertThrows } from "#test-assert";
+import {
+  type CapabilityNeed,
+  capabilityGateKey,
+  capabilityNeedToProbeInput,
+  capabilityRefNumber,
+  capabilityReleasesRepo,
+  parseCapabilityNeed,
+  parseCapabilityNeeds,
+  renderResolvedDepsBrief,
+  UnresolvableCapabilityRefError,
+} from "./capabilityNeed.ts";
+
+// ── parseCapabilityNeed / parseCapabilityNeeds ───────────────────────────────────────────────────
+
+test("parseCapabilityNeed: a well-formed need round-trips its fields", () => {
+  const need = parseCapabilityNeed({
+    capabilityRef: "nanobpm/nano-ide#274",
+    package: "@nanobpm/urban",
+    verifyCommand: "node -e 0",
+  });
+  assertEquals(need, {
+    capabilityRef: "nanobpm/nano-ide#274",
+    package: "@nanobpm/urban",
+    verifyCommand: "node -e 0",
+  });
+});
+
+test("parseCapabilityNeed: verifyCommand is dropped when blank (deterministic-only edge)", () => {
+  const need = parseCapabilityNeed({ capabilityRef: "#274", package: "@nanobpm/urban", verifyCommand: "  " });
+  assertEquals(need, { capabilityRef: "#274", package: "@nanobpm/urban" });
+});
+
+test("parseCapabilityNeed: a blank capabilityRef or package is dropped (unusable, never throws)", () => {
+  assertEquals(parseCapabilityNeed({ capabilityRef: "  ", package: "@nanobpm/urban" }), null);
+  assertEquals(parseCapabilityNeed({ capabilityRef: "#274", package: "" }), null);
+  assertEquals(parseCapabilityNeed(null), null);
+  assertEquals(parseCapabilityNeed("nope"), null);
+});
+
+test("parseCapabilityNeeds: drops malformed entries and de-dupes on capabilityRef@package", () => {
+  const needs = parseCapabilityNeeds([
+    { capabilityRef: "owner/repo#1", package: "@nanobpm/urban" },
+    { capabilityRef: "owner/repo#1", package: "@nanobpm/urban" }, // dup
+    { capabilityRef: "owner/repo#1", package: "@nanobpm/agentic" }, // different package, kept
+    { capabilityRef: "  ", package: "@x" }, // malformed
+    "garbage",
+  ]);
+  assertEquals(needs.length, 2);
+  assertEquals(needs[0], { capabilityRef: "owner/repo#1", package: "@nanobpm/urban" });
+  assertEquals(needs[1], { capabilityRef: "owner/repo#1", package: "@nanobpm/agentic" });
+});
+
+test("parseCapabilityNeeds: a non-array is []", () => {
+  assertEquals(parseCapabilityNeeds(undefined), []);
+  assertEquals(parseCapabilityNeeds({}), []);
+});
+
+// ── capabilityRefNumber / capabilityReleasesRepo ─────────────────────────────────────────────────
+
+test("capabilityRefNumber: extracts the trailing number from any handle form", () => {
+  assertEquals(capabilityRefNumber("nanobpm/nano-ide#274"), "274");
+  assertEquals(capabilityRefNumber("nano-ide#274"), "274");
+  assertEquals(capabilityRefNumber("#274"), "274");
+  assertEquals(capabilityRefNumber("274"), "274");
+  assertEquals(capabilityRefNumber("no-number-here"), undefined);
+});
+
+test("capabilityReleasesRepo: owner/repo prefix yields the releases source, bare/short forms yield undefined", () => {
+  assertEquals(capabilityReleasesRepo("nanobpm/nano-ide#274"), "nanobpm/nano-ide");
+  assertEquals(capabilityReleasesRepo("nano-ide#274"), undefined);
+  assertEquals(capabilityReleasesRepo("#274"), undefined);
+  assertEquals(capabilityReleasesRepo("a/b/c#1"), undefined);
+});
+
+// ── capabilityGateKey ────────────────────────────────────────────────────────────────────────────
+
+test("capabilityGateKey: <planKey>:<taskId>:<capabilityRef>:<package> (stable across a resume)", () => {
+  assertEquals(
+    capabilityGateKey("owner/repo#289", "issue-289", "nanobpm/nano-ide#274", "@nanobpm/urban"),
+    "owner/repo#289:issue-289:nanobpm/nano-ide#274:@nanobpm/urban",
+  );
+});
+
+test("capabilityGateKey: same capabilityRef, different package → distinct keys (no gate collision)", () => {
+  const a = capabilityGateKey("owner/repo#289", "issue-289", "nanobpm/nano-ide#274", "@nanobpm/urban");
+  const b = capabilityGateKey("owner/repo#289", "issue-289", "nanobpm/nano-ide#274", "@nanobpm/urban-testkit");
+  assertEquals(a === b, false);
+});
+
+// ── capabilityNeedToProbeInput ───────────────────────────────────────────────────────────────────
+
+test("capabilityNeedToProbeInput: maps a need to the readiness-gate capability probe input", () => {
+  const need: CapabilityNeed = {
+    capabilityRef: "nanobpm/nano-ide#274",
+    package: "@nanobpm/urban",
+    verifyCommand: "verify.sh",
+  };
+  const input = capabilityNeedToProbeInput(need, {
+    planKey: "owner/repo#289",
+    taskId: "issue-289",
+    probeTimeout: "PT12H",
+  });
+  assertEquals(input.gateKey, "owner/repo#289:issue-289:nanobpm/nano-ide#274:@nanobpm/urban");
+  assertEquals(input.probeTimeout, "PT12H");
+  assertEquals(input.onTimeout, "escalate");
+  assertEquals(input.probe.kind, "capability");
+  assertEquals(input.probe.target, "github-releases:nanobpm/nano-ide");
+  assertEquals(input.probe.onTimeout, "escalate");
+  assertEquals(input.probe.match?.capabilityRef, "nanobpm/nano-ide#274");
+  assertEquals(input.probe.match?.package, "@nanobpm/urban");
+  assertEquals(input.probe.match?.verifyCommand, "verify.sh");
+});
+
+test("capabilityNeedToProbeInput: omits verifyCommand when the need has none", () => {
+  const input = capabilityNeedToProbeInput(
+    { capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban" },
+    { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H" },
+  );
+  assertEquals(input.probe.match?.verifyCommand, undefined);
+});
+
+test("capabilityNeedToProbeInput: throws when the handle names no releases source (fail loudly)", () => {
+  assertThrows(
+    () =>
+      capabilityNeedToProbeInput(
+        { capabilityRef: "#274", package: "@nanobpm/urban" },
+        { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H" },
+      ),
+    UnresolvableCapabilityRefError,
+    "names no owner/repo releases source",
+  );
+});
+
+// ── renderResolvedDepsBrief ──────────────────────────────────────────────────────────────────────
+
+test("renderResolvedDepsBrief: empty list renders nothing (unconditional concatenation is safe)", () => {
+  assertEquals(renderResolvedDepsBrief([]), "");
+});
+
+test("renderResolvedDepsBrief: pins each capabilityRef → resolvedArtifact", () => {
+  const brief = renderResolvedDepsBrief([
+    { capabilityRef: "nanobpm/nano-ide#274", resolvedArtifact: "@nanobpm/urban@0.54.0" },
+    { capabilityRef: "nanobpm/nano-ide#280", resolvedArtifact: "@nanobpm/agentic@0.9.0" },
+  ]);
+  assert(brief.startsWith("\n\n---\n"));
+  assertStringIncludes(brief, "`nanobpm/nano-ide#274` → `@nanobpm/urban@0.54.0`");
+  assertStringIncludes(brief, "`nanobpm/nano-ide#280` → `@nanobpm/agentic@0.9.0`");
+  assertStringIncludes(brief, "pin these EXACT versions");
+});

package/app/capabilityNeed.ts

@@ -0,0 +1,200 @@
+// nano-workforce — the cross-repo CAPABILITY EDGE authoring/plumbing helpers (issue #289).
+//
+// This is the pure, I/O-free half of the "consumer readiness edge" (ADR 0001 §4, #263): a plan task
+// declares that it consumes an upstream capability C that ships as some `pkg@version` from ANOTHER
+// repo, and must not start until C first ships. The planner emits this as `RecordPlanTask.needs[]`
+// (plan-fanout.bpmn); `pr.record-plan` levelizes it to `plan_task_needs` and `pr.select-wave` reads
+// it back to gate the task before dispatch.
+//
+// The gate itself is the EXISTING durable `readiness-gate` process (#258) driven with a `capability`
+// {@link ReadinessProbe} (#274) — this module never re-implements the wait or the matcher; it only
+// (a) normalises a raw planner need, (b) maps a need to the gate's `ReadinessProbeIn`, and (c) renders
+// the late-bound "resolved-dependencies" prompt brief that pins each `pkg@version` into the agent's
+// context (mirroring `renderBaseBranchBrief` in app/plan.ts). Pure + unit-testable — no network, no DB.
+import type { OnTimeout, ProbeMatch, ReadinessProbe } from "./readiness.ts";
+
+/** A single cross-repo capability dependency declared on a plan task — the stable authoring contract
+ * (#263: declare the HANDLE, never a version). Mirrors the `CapabilityNeed` `nano:shape` in
+ * plan-fanout.bpmn so it is typed end to end. */
+export interface CapabilityNeed {
+  /** The upstream capability handle — `owner/repo#NNN`, `repo#NNN`, or the bare `#NNN`. It carries
+   * the provenance issue/PR ref the resolved version must reference; the leading `owner/repo` (when
+   * present) also names the releases source repo the gate polls (see {@link capabilityReleasesRepo}). */
+  readonly capabilityRef: string;
+  /** The artifact whose GitHub Releases carry the publish provenance (e.g. `@nanobpm/urban`).
+   * Per-package scoped — a sibling package's provenance can never resolve this edge. */
+  readonly package: string;
+  /** OPTIONAL gated empirical verifier (#274 decision 5): run ONCE at the gate boundary against the
+   * newest published `package` version when deterministic provenance resolved nothing. Left unset,
+   * the edge is deterministic-provenance-only. */
+  readonly verifyCommand?: string;
+}
+
+/** The gate's input envelope — mirrors the `ReadinessProbeIn` `nano:shape` in readiness-gate.bpmn
+ * (`gateKey`, `probeTimeout`, optional `onTimeout`, nested `probe`). Kept local (not imported) so this
+ * pure module never depends on the generated worker-io types. */
+export interface ReadinessProbeInput {
+  readonly gateKey: string;
+  readonly probeTimeout: string;
+  readonly onTimeout?: OnTimeout;
+  readonly probe: ReadinessProbe;
+}
+
+/** One resolved capability edge — the late-bound fact the gate hands back (`capabilityRef →
+ * resolvedArtifact`, e.g. `nanobpm/nano-ide#274 → @nanobpm/urban@0.54.0`). Fanned in over a task's
+ * needs and rendered into the implementation prompt by {@link renderResolvedDepsBrief}. */
+export interface ResolvedCapability {
+  readonly capabilityRef: string;
+  readonly resolvedArtifact: string;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v));
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Normalise ONE raw planner-emitted need into a {@link CapabilityNeed}, or `null` when it is unusable
+ * (blank `capabilityRef` or `package`). A malformed need is DROPPED rather than throwing so one bad
+ * entry can never fail the whole plan record — mirroring `record-plan`'s tolerant task normalisation. */
+export function parseCapabilityNeed(raw: unknown): CapabilityNeed | null {
+  if (!isRecord(raw)) return null;
+  const capabilityRef = str(raw.capabilityRef).trim();
+  const pkg = str(raw.package).trim();
+  if (capabilityRef === "" || pkg === "") return null;
+  const verifyCommand = str(raw.verifyCommand).trim();
+  return { capabilityRef, package: pkg, ...(verifyCommand === "" ? {} : { verifyCommand }) };
+}
+
+/** Normalise a whole `needs[]` array, dropping malformed entries and de-duplicating on
+ * `capabilityRef@package` (a task that lists the same edge twice must gate on it once). */
+export function parseCapabilityNeeds(raw: unknown): CapabilityNeed[] {
+  if (!Array.isArray(raw)) return [];
+  const out: CapabilityNeed[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    const need = parseCapabilityNeed(entry);
+    if (!need) continue;
+    const key = `${need.capabilityRef}\u0000${need.package}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(need);
+  }
+  return out;
+}
+
+/** The bare numeric id of a capability handle — `nanobpm/nano-ide#274`, `nano-ide#274`, `#274`, and a
+ * naked `274` all normalise to `274`. Returns `undefined` for a handle with no number (never
+ * resolvable). Kept in lockstep with `capabilityNumber` in app/readiness.ts (the matcher's predicate). */
+export function capabilityRefNumber(capabilityRef: string): string | undefined {
+  const m = capabilityRef.match(/(\d+)\s*$/);
+  return m ? m[1] : undefined;
+}
+
+/** The releases-source repo a capability handle names, as `owner/repo`, or `undefined` when the handle
+ * carries no `owner/repo` prefix (a bare `#274` / `repo#274`). The gate polls THIS repo's GitHub
+ * Releases for the package's publish provenance, so a handle without it cannot be gated deterministically
+ * — the planner is taught to always write the full `owner/repo#NNN` (resources/prompts/plan.md). */
+export function capabilityReleasesRepo(capabilityRef: string): string | undefined {
+  const beforeHash = capabilityRef.split("#")[0]?.trim() ?? "";
+  const m = beforeHash.match(/^([^/\s]+\/[^/\s]+)$/);
+  return m ? m[1] : undefined;
+}
+
+/** Raised when a capability need cannot be turned into a gateable probe because its handle names no
+ * `owner/repo` releases source (e.g. a bare `#274`). Fail LOUDLY at wiring time — a silently
+ * un-pollable edge would only surface as a spurious gate timeout much later. */
+export class UnresolvableCapabilityRefError extends Error {
+  readonly capabilityRef: string;
+  constructor(capabilityRef: string) {
+    super(
+      `capability need '${capabilityRef}': the handle names no owner/repo releases source. ` +
+        `Declare the full 'owner/repo#NNN' handle so the gate knows which repo's Releases to poll.`,
+    );
+    this.name = "UnresolvableCapabilityRefError";
+    this.capabilityRef = capabilityRef;
+  }
+}
+
+/** The gate's correlation/idempotency key for a task's capability edge:
+ * `<planKey>:<taskId>:<capabilityRef>:<package>` (issue #289 design §2). Stable across a resume so a
+ * re-dispatched agent re-attaches to the same gate. `package` is part of the identity because a task
+ * can legitimately declare the SAME `capabilityRef` for different packages (`parseCapabilityNeeds`
+ * de-dupes on `capabilityRef+package`; `plan_task_needs`' PK includes `package`) — each
+ * `(capabilityRef, package)` edge is a distinct need with its own gate row, so the key must be 1:1
+ * with the need or two edges would collide on one gate row and only one could ever resolve. */
+export function capabilityGateKey(
+  planKey: string,
+  taskId: string,
+  capabilityRef: string,
+  pkg: string,
+): string {
+  return `${planKey}:${taskId}:${capabilityRef}:${pkg}`;
+}
+
+/** The message name plan-fanout's per-task capability barrier (`wait-caps-resolved`) subscribes to and
+ * the host publishes to release the gated task once every one of its capability needs has resolved
+ * (issue #289 §2/§3). The single source of truth for the string shared by the BPMN subscription and
+ * the host publisher, mirroring `WAVE_MERGED_MESSAGE`. */
+export const CAPS_RESOLVED_MESSAGE = "caps-resolved";
+
+/** The per-TASK barrier correlation key `<planKey>:<taskId>` the `wait-caps-resolved` catch binds
+ * and the host publishes `caps-resolved` on (issue #289 §2). Distinct from {@link capabilityGateKey}
+ * (which is per-NEED): a task fans in ALL its needs, so its barrier releases ONCE, keyed on the task —
+ * not once per need. Stable across a resume so a re-dispatched fan-out re-attaches to the same barrier. */
+export function capabilityTaskBarrierKey(planKey: string, taskId: string): string {
+  return `${planKey}:${taskId}`;
+}
+
+/** Map a normalised {@link CapabilityNeed} to the EXISTING `readiness-gate` process input (#289 §2):
+ * a `capability` probe scanning the handle's releases source for the package's provenance, bounded by
+ * `probeTimeout` and escalating on timeout. Reuses the gate + matcher verbatim (derivation over
+ * duplication) — this only shapes the descriptor. Throws {@link UnresolvableCapabilityRefError} when
+ * the handle names no releases source. */
+export function capabilityNeedToProbeInput(
+  need: CapabilityNeed,
+  opts: { planKey: string; taskId: string; probeTimeout: string },
+): ReadinessProbeInput {
+  const repo = capabilityReleasesRepo(need.capabilityRef);
+  if (!repo) throw new UnresolvableCapabilityRefError(need.capabilityRef);
+  const match: ProbeMatch = {
+    capabilityRef: need.capabilityRef,
+    package: need.package,
+    ...(need.verifyCommand ? { verifyCommand: need.verifyCommand } : {}),
+  };
+  const probe: ReadinessProbe = {
+    kind: "capability",
+    target: `github-releases:${repo}`,
+    match,
+    onTimeout: "escalate",
+  };
+  return {
+    gateKey: capabilityGateKey(opts.planKey, opts.taskId, need.capabilityRef, need.package),
+    probeTimeout: opts.probeTimeout,
+    onTimeout: "escalate",
+    probe,
+  };
+}
+
+/** Render the per-task "resolved-dependencies" brief appended to an implementer agent's prompt once
+ * every capability gate on the task has resolved (#289 §3), mirroring `renderBaseBranchBrief`. It pins
+ * each `capabilityRef → pkg@version` the gate discovered so the agent installs EXACTLY that version —
+ * no pre-named version, no human. Returns "" for an empty list so callers can concatenate unconditionally. */
+export function renderResolvedDepsBrief(resolved: readonly ResolvedCapability[]): string {
+  if (resolved.length === 0) return "";
+  const lines = [
+    "",
+    "",
+    "---",
+    "",
+    "**Resolved cross-repo dependencies (authoritative — pin these EXACT versions):**",
+    "",
+    "An upstream capability this task depends on has shipped. Install/pin exactly the resolved",
+    "`package@version` below — do NOT bump, float, or re-resolve it:",
+    "",
+  ];
+  for (const r of resolved) lines.push(`- \`${r.capabilityRef}\` → \`${r.resolvedArtifact}\``);
+  lines.push("");
+  lines.push("These versions first carry the capability your slice consumes; a newer or older version");
+  lines.push("may not. Treat them as the contract you build against.");
+  return lines.join("\n");
+}

package/app/capsWait.test.ts

@@ -0,0 +1,39 @@
+// Unit coverage for the capability-barrier bounded-wait duration policy (#289). The value is baked
+// into every plan-fanout instance's `capsWaitTimeout` process variable and evaluated by the
+// `wait-caps-timeout` timer arm on the `wait-caps-resolved` event-based gateway, so a malformed
+// operator env must never deploy an uninterpretable `<bpmn:timeDuration>` — it falls back to the
+// default instead. Run with `node --test`.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { capsWaitTimeout, DEFAULT_CAPS_WAIT_TIMEOUT } from "./capsWait.ts";
+
+test("capsWaitTimeout: blank / absent / malformed → default", () => {
+  assert.equal(capsWaitTimeout(undefined), DEFAULT_CAPS_WAIT_TIMEOUT);
+  assert.equal(capsWaitTimeout(""), DEFAULT_CAPS_WAIT_TIMEOUT);
+  assert.equal(capsWaitTimeout("   "), DEFAULT_CAPS_WAIT_TIMEOUT);
+  assert.equal(capsWaitTimeout("2h"), DEFAULT_CAPS_WAIT_TIMEOUT); // missing leading P/T
+  assert.equal(capsWaitTimeout("P"), DEFAULT_CAPS_WAIT_TIMEOUT); // no component
+  assert.equal(capsWaitTimeout("PT"), DEFAULT_CAPS_WAIT_TIMEOUT); // T with no time part
+  assert.equal(capsWaitTimeout("garbage"), DEFAULT_CAPS_WAIT_TIMEOUT);
+});
+
+test("capsWaitTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(capsWaitTimeout("PT30M"), "PT30M");
+  assert.equal(capsWaitTimeout("pt2h"), "PT2H");
+  assert.equal(capsWaitTimeout("P2D"), "P2D");
+  assert.equal(capsWaitTimeout("  pt15m  "), "PT15M");
+});
+
+test("capsWaitTimeout: an explicit fallback is honoured for a bad value", () => {
+  assert.equal(capsWaitTimeout("nope", "PT10M"), "PT10M");
+  assert.equal(capsWaitTimeout("PT45M", "PT10M"), "PT45M");
+});
+
+test("the default is itself a well-formed ISO-8601 duration (never an uninterpretable timer)", () => {
+  // Validate the default against the grammar with a *distinct* fallback: if the default were
+  // malformed it would fall through to the sentinel, so equality to itself proves it parses.
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_CAPS_WAIT_TIMEOUT, sentinel);
+  assert.equal(capsWaitTimeout(DEFAULT_CAPS_WAIT_TIMEOUT, sentinel), DEFAULT_CAPS_WAIT_TIMEOUT);
+});

package/app/capsWait.ts

@@ -0,0 +1,33 @@
+// Capability-barrier bounded-wait policy (issue #289), kept as a pure module (no env, no I/O) so it
+// is trivially testable — mirrors app/escalationSla.ts and app/reviewWait.ts. `app/plan.ts` seeds the
+// validated `capsWaitTimeout` process variable at submit; the `wait-caps-timeout` timer catch on the
+// `wait-caps-resolved` event-based gateway in plan-fanout.bpmn evaluates it at timer creation
+// (FEEL-expression timer durations, engine-native).
+//
+// This models liveness IN the process: a task parked at the `wait-caps-resolved` capability barrier
+// can no longer hang forever when a declared cross-repo capability never resolves — most acutely when
+// the handle names no `owner/repo` releases source (an `UnresolvableCapabilityRefError`), so the host
+// reconciler can never start a readiness-gate and never publishes `caps-resolved`. When this bound
+// elapses the event-based gateway's timer arm fires and the token routes to the existing
+// `feature-escalation` operator user task — a bounded wait + operator escalation, not a poller-side
+// watchdog and not a silent wedge.
+
+import { isoDuration } from "./reviewWait.ts";
+
+/** Default capability-barrier bound (ISO-8601 duration): how long a task may park at
+ * `wait-caps-resolved` waiting for every declared cross-repo capability to ship before the timer arm
+ * fires and the token escalates to an operator. A day is generous for a genuine cross-team dependency
+ * to publish while still bounding the wait — and it decisively unwedges a permanently-unresolvable
+ * capability handle, which would otherwise never resolve at all. */
+export const DEFAULT_CAPS_WAIT_TIMEOUT = "P1D";
+
+/** Validate the operator-supplied capability-barrier bound (env `NANO_CAPS_WAIT_TIMEOUT`, ISO-8601
+ * duration), falling back to {@link DEFAULT_CAPS_WAIT_TIMEOUT} when absent, blank, or malformed — a
+ * bad env value must never deploy an uninterpretable timer expression. Derives its validation from
+ * the single canonical {@link isoDuration}. */
+export function capsWaitTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_CAPS_WAIT_TIMEOUT,
+): string {
+  return isoDuration(raw, def);
+}

package/app/contracts.ts

@@ -208,6 +208,14 @@ export const ENV_CONTRACTS = {
       "SLA timeout for an agent (service) task before its boundary timer fires and the PR escalates for human attention (ISO-8601 duration). A malformed value falls back to the default.",
     default: "PT2H",
   },
+  NANO_CAPS_WAIT_TIMEOUT: {
+    category: "env",
+    name: "NANO_CAPS_WAIT_TIMEOUT",
+    owner: "app/plan.ts",
+    semantics:
+      "Bounded wait (FEEL/ISO-8601 duration) a plan-fanout task may park at the wait-caps-resolved capability barrier before the event-based gateway's timer arm fires and it escalates to an operator. Bounds a permanently-unresolvable capability handle (UnresolvableCapabilityRefError) so it can never silently wedge the epic. A malformed value falls back to the default.",
+    default: "P1D",
+  },
   NANO_READINESS_POLL_TIMEOUT: {
     category: "env",
     name: "NANO_READINESS_POLL_TIMEOUT",

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