@nanobpm/nano-workforce 0.97.0 → 0.98.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **merge-loop:** give merge-blocked escalation a question + gw-escalated guard ([#329](https://github.com/nanobpm/nano-workforce/issues/329)) ([#331](https://github.com/nanobpm/nano-workforce/issues/331)) ([abb2952](https://github.com/nanobpm/nano-workforce/commit/abb2952b5ff5874ff928085167f4a0fd5f0580e5))
+
 # [0.97.0](https://github.com/nanobpm/nano-workforce/compare/v0.96.1...v0.97.0) (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/mergeEscalationQuestion.test.ts

@@ -0,0 +1,140 @@
+// Regression guard for the question-less merge escalation defect (issue #329).
+//
+// The merge loop (`resources/processes/merge-loop.bpmn`) raised escalations with NO question
+// whenever a PR was blocked by anything other than a merge conflict: `merge-esc-attempt` called
+// `pr.persist-escalation` with no `question`/`status` ioMapping, and its output flowed
+// UNCONDITIONALLY into `wait-merge-answer`. Two coupled defects fell out of that:
+//
+//   1. A blank question surfaced on the merge-driving inbox — the human was asked to answer but
+//      told nothing (observed live on nano-ide PR #354).
+//   2. Per ADR 0002 §1 a blank question is a NON-escalation: `pr.persist-escalation` opens no row
+//      and returns `escalated:false`. The convergence loop honours this via a `gw-escalated`
+//      branch; the merge loop had none, so a question-less job still parked a dead
+//      `wait-merge-answer` with nothing for a human to answer.
+//
+// The fix (mirroring the convergence loop): give `merge-esc-attempt` a human-actionable
+// `status`/`question` that distinguishes its four trigger conditions, and add a `gw-merge-escalated`
+// guard so a `persist-escalation` returning `escalated:false` re-enters the loop (re-arms the
+// poller) instead of parking a dead wait.
+//
+// These are pure text assertions over the committed BPMN (no engine), matching the repo's
+// lightweight model-guard style (see mergeRebaseArm.test.ts, mergeEscalationUserTask.test.ts).
+
+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");
+// Collapse whitespace so attribute-order / line-wrapping churn doesn't make the assertions brittle.
+const flat = bpmn.replace(/\s+/g, " ");
+
+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}"`);
+}
+
+// The <serviceTask> element for merge-esc-attempt, including its ioMapping. Unescape XML entities so
+// FEEL string literals (authored as `&#34;ready&#34;` inside the attribute) read naturally here.
+const escAttemptRaw = flat.match(/<bpmn:serviceTask\b[^>]*\bid="merge-esc-attempt"[\s\S]*?<\/bpmn:serviceTask>/);
+const escAttempt = escAttemptRaw
+  ? [escAttemptRaw[0].replace(/&#34;/g, '"').replace(/&amp;/g, "&").replace(/&#10;/g, "\n")]
+  : null;
+
+test("merge-esc-attempt carries a non-blank, human-actionable status + question", () => {
+  assert(escAttempt, "merge-esc-attempt service task must exist");
+  const el = escAttempt![0];
+  // Mirror the merge-esc-conflict mapping style: an explicit `blocked` status…
+  assertStringIncludes(el, "<zeebe:ioMapping", "merge-esc-attempt must set an ioMapping (was absent — the #329 defect)");
+  assertStringIncludes(el, 'target="status"', "merge-esc-attempt must set a `status`");
+  assertStringIncludes(el, 'target="question"', "merge-esc-attempt must set a non-blank `question`");
+  // Tighten: assert the explicit `status` INPUT MAPPING sets blocked, not merely the substring
+  // `="blocked"` (which the FEEL question's `agentVerdict = "blocked"` comparison would also satisfy
+  // even if the status mapping were removed/changed). Match tolerant of attribute order/spacing: the
+  // file is XML and a formatter could reorder `source`/`target` within the tag.
+  const escInputs = el.match(/<zeebe:input\b[^>]*\/>/g) ?? [];
+  const setsBlockedStatus = escInputs.some(
+    (t) => t.includes('target="status"') && t.includes('source="="blocked""'),
+  );
+  assert(setsBlockedStatus, "the explicit `status` input mapping must set `blocked`");
+});
+
+test("arm-merge clears the prior verdict `status` so a stale `blocked` cannot misclassify the CI-fix SLA escalation", () => {
+  // merge-esc-attempt captures `agentVerdict = status` to split its CI could-not-fix vs SLA question
+  // arms. On the SLA boundary path (`f_ci_sla`) no worker sets a fresh `status`, and every escalation
+  // task overwrites `status = "blocked"` (merge-esc-attempt line 194, merge-esc-conflict line 174).
+  // Without a reset, a retry after any prior escalation re-enters fix-ci with `status` still
+  // "blocked", so an SLA timeout would render the wrong ("could not fix") question. arm-merge is the
+  // single loop hub every fix-ci entry passes through, so clearing `status` there (to null) each
+  // iteration guarantees a genuine SLA reads no stale verdict. Nothing between arm-merge and the next
+  // verdict-setter (fix-ci/rebase) reads `status`, so the reset is safe.
+  const armRaw = flat.match(/<bpmn:serviceTask\b[^>]*\bid="arm-merge"[\s\S]*?<\/bpmn:serviceTask>/);
+  assert(armRaw, "arm-merge service task must exist");
+  const armOutputs = armRaw![0].match(/<zeebe:output\b[^>]*\/>/g) ?? [];
+  const clearsStatus = armOutputs.some(
+    (t) => t.includes('target="status"') && t.includes('source="=null"'),
+  );
+  assert(clearsStatus, "arm-merge must reset `status` to null each loop iteration so a stale `blocked` cannot misclassify the SLA escalation");
+});
+
+test("the question distinguishes all four blocked/SLA triggers rather than a single generic string", () => {
+  // Four flows route into merge-esc-attempt — the gate `blocked` default, CI could-not-fix,
+  // rebase could-not-resolve, and the CI-fix SLA. Each is a legitimately different escalation and
+  // the question must explain which one fired.
+  assert(escAttempt, "merge-esc-attempt service task must exist");
+  const el = escAttempt![0];
+  // gate blocked (gw-merge default): distinguishes on the `ready` mergeState + surfaces mergeStatus.
+  assertStringIncludes(el, 'mergeState = "ready"', "must branch on the gate-blocked (ready) trigger");
+  assertStringIncludes(el, "mergeStatus", "the gate-blocked question must surface the merge result");
+  // rebase could-not-resolve (conflict arm).
+  assertStringIncludes(el, 'mergeState = "conflict"', "must branch on the rebase (conflict) trigger");
+  // CI could-not-fix vs CI SLA both arrive with mergeState = blocked — split on the agent verdict,
+  // captured into a dedicated `agentVerdict` binding so the escalation-classification `status =
+  // "blocked"` override in the SAME ioMapping cannot make the SLA branch unreachable (issue #329
+  // review). Assert the question branches on that binding, not on the overwritten `status`.
+  assertStringIncludes(el, "agentVerdict", "must capture the agent verdict into a dedicated binding");
+  assertStringIncludes(el, 'agentVerdict = "blocked"', "must branch CI could-not-fix vs SLA on the agent verdict binding, not the overwritten status");
+});
+
+test("a gw-merge-escalated guard honours persist-escalation's escalated:false (mirrors the convergence loop)", () => {
+  // The escalation output no longer flows UNCONDITIONALLY into the durable answer wait: it passes
+  // through a gateway that reads the worker's `escalated` output.
+  assert(
+    flowHasId("f_m_escA", "merge-esc-attempt", "gw-merge-escalated"),
+    "merge-esc-attempt must route through gw-merge-escalated, not straight to wait-merge-answer",
+  );
+  // escalated:true → park the native user task for a human to answer.
+  assert(
+    flowHasId("f_m_escWait", "gw-merge-escalated", "wait-merge-answer"),
+    "gw-merge-escalated → wait-merge-answer (escalated) missing",
+  );
+  const escWait = flat.match(/<bpmn:sequenceFlow[^>]*id="f_m_escWait"[\s\S]*?<\/bpmn:sequenceFlow>/);
+  assert(escWait, "f_m_escWait flow missing");
+  assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
+  // escalated:false (a non-escalation, e.g. a blank question) → re-enter the loop, NOT a dead wait.
+  assert(
+    gatewayDefault("gw-merge-escalated", "f_m_escReenter"),
+    "gw-merge-escalated must default to f_m_escReenter (re-enter, not park)",
+  );
+  assert(
+    flowHasId("f_m_escReenter", "gw-merge-escalated", "arm-merge"),
+    "f_m_escReenter must re-arm the merge poller instead of parking a dead wait-merge-answer",
+  );
+});
+
+test("regression: a question-less escalation can no longer park a dead wait-merge-answer", () => {
+  // The exact #329 wedge: `merge-esc-attempt → wait-merge-answer` as a direct, unconditional edge.
+  // It must be gone — the only path into the answer wait from the attempt arm is now guarded by
+  // `escalated = true`.
+  assert(
+    !flowHasId("f_m_escA", "merge-esc-attempt", "wait-merge-answer"),
+    "merge-esc-attempt must NOT flow directly into wait-merge-answer (the #329 dead-wait defect)",
+  );
+});