@nanobpm/nano-workforce 0.97.1 → 0.98.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.98.1](https://github.com/nanobpm/nano-workforce/compare/v0.98.0...v0.98.1) (2026-08-19)
+
+
+### Bug Fixes
+
+* **merge-loop:** transient 'Base branch was modified' merge race → bounded retry, not escalate ([#335](https://github.com/nanobpm/nano-workforce/issues/335)) ([4093d50](https://github.com/nanobpm/nano-workforce/commit/4093d50b0ecd1a226bcfe7a5ecca10ba1db0937a)), closes [#330](https://github.com/nanobpm/nano-workforce/issues/330) [#334](https://github.com/nanobpm/nano-workforce/issues/334)
+
+# [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

@@ -117,6 +117,13 @@ export const ENV_CONTRACTS = {
     semantics: "Maximum rebase attempts per PR.",
     default: "3",
   },
+  NANO_PR_MAX_MERGE_RETRIES: {
+    category: "env",
+    name: "NANO_PR_MAX_MERGE_RETRIES",
+    owner: "app/service.ts",
+    semantics: "Maximum transient base/head-moved merge-race retries per PR before escalating.",
+    default: "5",
+  },
   NANO_PR_REVIEW_WAIT_TIMEOUT: {
     category: "env",
     name: "NANO_PR_REVIEW_WAIT_TIMEOUT",
@@ -208,6 +215,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/github.ts

@@ -822,14 +822,26 @@ export interface MergeOptions {
   admin: boolean;
 }
 export interface MergeResult {
-  outcome: "merged" | "queued" | "blocked";
+  outcome: "merged" | "queued" | "blocked" | "retry";
   detail: string;
 }
 
+/** GitHub-flagged *retryable* merge races: the base (or head) branch advanced between the
+ * mergeability read and the merge mutation, so GitHub aborted the merge with a "… try the merge
+ * again" message. These are transient — GitHub itself tells us to just retry — so the merge loop
+ * must re-attempt on the settled base, NOT page a human. Matches GitHub's stable message across
+ * both the GraphQL `mergePullRequest` error and its HTTP 405 REST variant. Kept narrow — the exact
+ * "<Base|Head> branch was modified" phrase — so a genuine block (conflict, failing required check,
+ * 403 perms, 422 not-mergeable) is never swallowed as transient. */
+export function isTransientMergeRace(detail: string): boolean {
+  return /\b(?:base|head) branch was modified\b/i.test(detail);
+}
+
 /** Attempt to land the PR. Returns `merged` (landed now), `queued` (added to the repo's merge
- * queue — the poller then watches for it to land), or `blocked` (GitHub refused — a human must
- * resolve it, then reply to retry). `null` when no transport is usable. Never throws for a
- * refused merge; only a genuine transport failure propagates. */
+ * queue — the poller then watches for it to land), `retry` (a transient base/head-moved race —
+ * GitHub says to re-attempt on the settled base, no human needed), or `blocked` (GitHub refused —
+ * a human must resolve it, then reply to retry). `null` when no transport is usable. Never throws
+ * for a refused merge; only a genuine transport failure propagates. */
 export async function mergePr(
   repo: string,
   number: number | string,
@@ -850,6 +862,9 @@ export async function mergePr(
       // A merge-queue-required branch surfaces as an error on older gh; treat as queued when the
       // message says so, otherwise it is a genuine block (conflict, failing gate, perms).
       if (/added to the merge queue|enqueued/i.test(msg)) return { outcome: "queued", detail: msg };
+      // A base/head-moved race is transient (GitHub says to retry) — re-enter the merge loop
+      // rather than escalate. Checked before the catch-all block so it is never swallowed as blocked.
+      if (isTransientMergeRace(msg)) return { outcome: "retry", detail: msg };
       return { outcome: "blocked", detail: msg };
     }
   }
@@ -877,6 +892,9 @@ export async function mergePr(
     return { outcome: "queued", detail: "merge accepted; PR not yet landed (awaiting merge queue)" };
   }
   const detail = `github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim();
+  // The REST merge endpoint returns 405 "Base branch was modified. Review and try the merge again."
+  // for the same transient race — classify it as retry, not a human-actionable block.
+  if (isTransientMergeRace(detail)) return { outcome: "retry", detail };
   return { outcome: "blocked", detail };
 }
 

package/app/mergeEscalationQuestion.test.ts

@@ -103,6 +103,23 @@ test("the question distinguishes all four blocked/SLA triggers rather than a sin
   assertStringIncludes(el, 'agentVerdict = "blocked"', "must branch CI could-not-fix vs SLA on the agent verdict binding, not the overwritten status");
 });
 
+test("retry-budget-exhausted escalation reads as a repeated race, not a generic merge refusal", () => {
+  // `f_mr_giveup` (transient merge-retry budget exhausted) routes into merge-esc-attempt with
+  // mergeState = "ready" AND mergeStatus = "retry". Without a dedicated branch this reused the
+  // generic gate-blocked ("Investigate why GitHub refused the merge") text, which is misleading for
+  // a repeated base/head-moved race whose retry budget simply ran out. The question must branch on
+  // mergeStatus = "retry" — ahead of the generic `mergeState = "ready"` arm — and name the budget.
+  assert(escAttempt, "merge-esc-attempt service task must exist");
+  const el = escAttempt![0];
+  assertStringIncludes(el, 'mergeStatus = "retry"', "must branch the retry-budget-exhausted escalation on mergeStatus = retry");
+  assertStringIncludes(el, "mergeRetryMax", "the retry-exhausted question must surface the retry budget");
+  // The retry branch must precede the generic `mergeState = "ready"` branch, or the generic arm
+  // (also true here) would shadow it and re-emit the misleading refusal text.
+  const retryIdx = el.indexOf('mergeStatus = "retry"');
+  const readyIdx = el.indexOf('mergeState = "ready"');
+  assert(retryIdx !== -1 && readyIdx !== -1 && retryIdx < readyIdx, "the retry branch must be evaluated before the generic ready branch");
+});
+
 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.

package/app/mergeRetry.test.ts

@@ -0,0 +1,90 @@
+// Unit tests for the transient merge-race classification (issue #334).
+//
+// #334: a GitHub-flagged *retryable* merge race — the base (or head) branch advanced between the
+// mergeability read and the merge mutation, so GitHub aborted with "… try the merge again" — was
+// misclassified by `mergePr`'s catch-all as `blocked`, producing a misleading human escalation on
+// a PR that was actually mergeable once the base settled. The fix classifies the stable
+// base/head-moved messages as a new `retry` outcome (the merge loop re-attempts on the settled
+// base), while every genuine block (conflict / failing check / 403 perms / 422 not-mergeable)
+// stays `blocked`. These tests pin that split so a real block is never swallowed as transient.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { isTransientMergeRace, mergePr } from "./github.ts";
+
+test("isTransientMergeRace: the base/head-moved races are transient", () => {
+  // GraphQL mergePullRequest error (observed live on nano-workforce #330).
+  assertEquals(
+    isTransientMergeRace(
+      "GraphQL: Base branch was modified. Review and try the merge again. (mergePullRequest)",
+    ),
+    true,
+  );
+  // The head-branch-moved sibling.
+  assertEquals(
+    isTransientMergeRace("Head branch was modified. Review and try the merge again."),
+    true,
+  );
+  // The HTTP 405 REST variant.
+  assertEquals(
+    isTransientMergeRace(
+      "github 405 Method Not Allowed: Base branch was modified. Review and try the merge again.",
+    ),
+    true,
+  );
+});
+
+test("isTransientMergeRace: genuine blocks are NOT transient (never swallowed)", () => {
+  assertEquals(isTransientMergeRace("Pull Request is not mergeable"), false); // conflict / failing check
+  assertEquals(isTransientMergeRace("github 403 Forbidden: Resource not accessible"), false); // perms
+  assertEquals(
+    isTransientMergeRace("github 422 Unprocessable Entity: Required status check is expected"),
+    false,
+  ); // not-mergeable gate
+  assertEquals(isTransientMergeRace("Merge conflict; base branch has conflicts"), false); // a base conflict is a real block
+});
+
+// Drive `mergePr`'s REST (token) transport: the 405 base-moved race must surface as `retry`, while
+// a genuine 405 refusal stays `blocked`.
+async function withMergePut(
+  status: number,
+  statusText: string,
+  body: string,
+  run: () => Promise<void>,
+): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    if (/\/pulls\/\d+\/merge$/.test(url) && (init?.method ?? "").toUpperCase() === "PUT") {
+      return Promise.resolve(new Response(body, { status, statusText }));
+    }
+    return Promise.resolve(new Response("not found", { status: 404 }));
+  }) as typeof fetch;
+  try {
+    await run();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("mergePr: a 405 base-moved race → outcome 'retry'", async () => {
+  await withMergePut(
+    405,
+    "Method Not Allowed",
+    "Base branch was modified. Review and try the merge again.",
+    async () => {
+      const res = await mergePr("acme/widgets", 42, "test-token", { method: "squash", admin: false });
+      assertEquals(res?.outcome, "retry");
+    },
+  );
+});
+
+test("mergePr: a genuine 405 refusal → outcome 'blocked' (not swallowed as transient)", async () => {
+  await withMergePut(405, "Method Not Allowed", "Pull Request is not mergeable", async () => {
+    const res = await mergePr("acme/widgets", 42, "test-token", { method: "squash", admin: false });
+    assertEquals(res?.outcome, "blocked");
+  });
+});