@nanobpm/nano-workforce 0.97.0 → 0.98.0

package/app/service.ts

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

package/app/waitGateVisibility.test.ts

@@ -23,12 +23,15 @@ test("select-wave's input envelope carries resolvedArtifacts so the worker can c
   assertStringIncludes(shape![0], 'name="resolvedArtifacts" type="string" list="true" optional="true"');
 });
 
-test("the epics index projects the wait-gate column", () => {
+test("the epics index is the lean list; the wait-gate lives on the detail panel", () => {
+  // The Epics index was redesigned to a lean list (issue #327): the Wait gate (like Base branch and
+  // Promotion) moved OFF the index onto the epic-detail panel, where it is asserted below. So the
+  // index no longer carries the wait-gate column — it only needs the lean grid to exist.
   const page = JSON.parse(readFileSync("pages/epic.page.json", "utf8"));
   const grid = page.nodes.find((n: any) => n.id === "epic-plans");
   assert(grid, "epics index must have the epic-plans grid");
   const cols: string[] = grid.props.columns.map((c: any) => c.field);
-  assert(cols.includes("wait_gate_label"), "the index shows the wait-gate at a glance");
+  assert(!cols.includes("wait_gate_label"), "the wait-gate moved to the epic-detail panel");
 });
 
 test("the epic detail projects both the DAG (plan_deps) and the wait-gate state", () => {

package/db/migrations/049_plan_task_needs.sql

@@ -0,0 +1,30 @@
+-- 049_plan_task_needs.sql — issue #289: the cross-repo CAPABILITY EDGE on a plan task.
+--
+-- A plan task may declare a cross-repo capability dependency (the "consumer readiness edge",
+-- ADR 0001 §4, #263): it consumes an upstream capability C that is published as some
+-- `pkg@version` from ANOTHER repo, and must not start until that capability first ships. The
+-- planner emits this as an optional `needs: CapabilityNeed[]` on each `RecordPlanTask`
+-- (plan-fanout.bpmn); this table is where `pr.record-plan` levelizes it to, mirroring
+-- `plan_task_deps` (the intra-epic edge table). One row per (task, capability need).
+--
+-- `capability_ref` is the STABLE upstream handle (`owner/repo#NNN`, `repo#NNN`, or `#NNN`) —
+-- NEVER a version (the #263 core decision: declare the handle, resolve the version at the gate).
+-- `package` is the artifact whose GitHub Releases carry the publish provenance (`@nanobpm/urban`),
+-- per-package scoped so a sibling package's provenance can't leak in. `verify_command` is the
+-- OPTIONAL gated empirical fallback (#274 decision 5) — deterministic provenance stays the default.
+--
+-- Keyed on `plan_key` (like plan_task_deps) so a single delete clears a plan's whole need set on a
+-- re-plan / idempotent re-run. Forward-only, additive (expand): a brand-new table, so pre-#289 rows
+-- and plans carry no needs and behave exactly as before. Numbered after the current highest prefix
+-- on origin/main (048); the runner wraps each file in its own transaction, so no BEGIN/COMMIT here.
+
+CREATE TABLE plan_task_needs (
+  plan_key        TEXT NOT NULL REFERENCES plans(plan_key),
+  task_id         TEXT NOT NULL,   -- the consuming task's slug
+  capability_ref  TEXT NOT NULL,   -- upstream handle: owner/repo#NNN | repo#NNN | #NNN (never a version)
+  package         TEXT NOT NULL,   -- artifact whose releases carry provenance, e.g. @nanobpm/urban
+  verify_command  TEXT,            -- optional gated empirical fallback (NULL = deterministic-only)
+  PRIMARY KEY (plan_key, task_id, capability_ref, package)
+);
+
+CREATE INDEX idx_plan_task_needs_plan ON plan_task_needs(plan_key);

package/db/migrations/050_capability_gates.sql

@@ -0,0 +1,40 @@
+-- 050_capability_gates.sql — issue #289: the host-orchestrated CAPABILITY GATE tracker.
+--
+-- When plan-fanout dispatches a wave task that declared a cross-repo capability edge (`needs`, see
+-- 049_plan_task_needs.sql), its per-task fan-out parks at the `wait-caps-resolved` message barrier
+-- (plan-fanout.bpmn) instead of starting the agent. The host reconciler (`pollCapabilityGatesImpl`
+-- in app/service.ts) then, for each such parked task, starts the EXISTING durable `readiness-gate`
+-- process (readiness-gate.bpmn, #258) once per need — the bounded/idempotent/resumable wait that
+-- escalates to an operator if the capability never ships — and reconciles, each pass, whether the
+-- capability has shipped as a published `pkg@version`. When ALL of a task's needs have resolved it
+-- publishes `caps-resolved` with the late-bound resolved-dependencies brief, releasing the barrier.
+--
+-- This table is that reconciler's durable, idempotent state: ONE row per (plan, task, need),
+-- identified by the readiness-gate correlation key `<plan_key>:<task_id>:<capability_ref>:<package>`
+-- (capabilityGateKey). `package` is part of the key because a task can declare the same
+-- `capability_ref` for different packages (plan_task_needs' PK includes `package`), so each
+-- `(capability_ref, package)` edge must map 1:1 to its own gate row. It records the started gate's
+-- instance key (so we start it exactly once) and
+-- the resolved `pkg@version` once the deterministic provenance lookup goes green, so a host restart
+-- re-derives the whole picture from the DB (never re-starts a gate, never re-publishes a settled
+-- barrier). `status` is 'pending' until the need resolves, then 'resolved'.
+--
+-- Numbered after the current highest prefix on origin/main (048); forward-only, additive (expand):
+-- a brand-new table, so pre-#289 plans carry no gate rows and behave exactly as before. The runner
+-- wraps each file in its own transaction, so no BEGIN/COMMIT here.
+
+CREATE TABLE capability_gates (
+  gate_key          TEXT PRIMARY KEY,   -- readiness-gate correlation key: <plan_key>:<task_id>:<capability_ref>:<package>
+  plan_key          TEXT NOT NULL REFERENCES plans(plan_key),
+  task_id           TEXT NOT NULL,      -- the consuming task's slug
+  capability_ref    TEXT NOT NULL,      -- upstream handle: owner/repo#NNN | repo#NNN | #NNN (never a version)
+  package           TEXT NOT NULL,      -- artifact whose releases carry provenance, e.g. @nanobpm/urban
+  status            TEXT NOT NULL DEFAULT 'pending',  -- 'pending' | 'resolved'
+  resolved_artifact TEXT,               -- the late-bound pkg@version once resolved (NULL while pending)
+  process_key       TEXT,               -- the started readiness-gate instance key (NULL until started)
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL
+);
+
+CREATE INDEX idx_capability_gates_plan ON capability_gates(plan_key);
+CREATE INDEX idx_capability_gates_task ON capability_gates(plan_key, task_id);

package/e2e/plan-fanout.e2e.ts

@@ -300,4 +300,149 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
       `abandon routed to record-results (flows: ${flows.join(", ")})`,
     );
   });
+
+  // Capability edge (issue #289): a task that declares cross-repo `needs` must PARK at the
+  // `wait-caps-resolved` barrier (never take the no-needs shortcut), and publishing `caps-resolved`
+  // correlated on the per-task barrier key `<planKey>:<taskId>` must release it into `implement-task`
+  // with the late-bound resolved-deps brief appended to the agent prompt. This ALSO proves the
+  // subprocess-level `capsGateKey = planKey + ":" + task.id` ioMapping resolves (the correlation would
+  // never match otherwise).
+  test("capability edge: a task with needs parks at wait-caps-resolved and caps-resolved releases it (#289)", async () => {
+    const capTaskPlan: Stub = () => ({
+      tasks: [
+        {
+          id: "t1",
+          title: "T1",
+          prompt: "do t1",
+          needs: [{ capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban" }],
+        },
+      ],
+    });
+    let featureBrief: unknown;
+    await withApp(
+      {
+        "senior:plan": capTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": (job) => {
+          featureBrief = (job.variables as Record<string, unknown>)?.["resolvedDepsBrief"];
+          return { status: "opened", summary: "built t1", pr: "owner/repo#2" };
+        },
+      },
+      async ({ app, planKey, processKey }) => {
+        const needRows = await app.db
+          .table<{ plan_key: string; task_id: string; capability_ref: string }>("plan_task_needs", "plan_key")
+          .find({ plan_key: planKey });
+        assert.ok(needRows.length > 0, "the task's capability need was persisted");
+        // The fan-out must have reached the barrier gateway's needs branch, NOT the no-needs shortcut,
+        // and must be parked at `wait-caps-resolved` (the feature agent has NOT run yet).
+        const parked = takenFlows(app);
+        assert.ok(
+          parked.includes("w_gw_needs->w_gw_caps") && parked.includes("w_gw_caps->wait-caps-resolved"),
+          `task with needs routed through the barrier gateway to wait-caps-resolved (flows: ${parked.join(", ")})`,
+        );
+        assert.ok(
+          !parked.includes("w_gw_needs->implement-task"),
+          "the no-needs shortcut was NOT taken for a task that declares needs",
+        );
+        assert.equal(featureBrief, undefined, "the agent has not been dispatched while parked at the barrier");
+
+        // Release the barrier exactly as the host reconciler would: publish `caps-resolved` correlated
+        // on the per-task barrier key with the late-bound resolved-deps brief.
+        const barrierKey = `${planKey}:t1`;
+        await app.engine.publishMessage({
+          name: "caps-resolved",
+          correlationKey: barrierKey,
+          variables: { resolvedDepsBrief: "\n\nRESOLVED: @nanobpm/urban@0.54.0" },
+        });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("wait-caps-resolved->implement-task"),
+          `caps-resolved released the barrier into implement-task (flows: ${flows.join(", ")})`,
+        );
+        assert.equal(
+          featureBrief,
+          "\n\nRESOLVED: @nanobpm/urban@0.54.0",
+          `the late-bound resolved-deps brief reached the agent (got: ${JSON.stringify(featureBrief)})`,
+        );
+        assert.ok(processKey, "processKey resolved");
+      },
+    );
+  });
+
+  // Capability barrier liveness (issue #289): a task whose declared cross-repo capability NEVER
+  // resolves (the reviewer's `UnresolvableCapabilityRefError` wedge: a `caps-resolved` message the
+  // host reconciler can never publish) must NOT park at `wait-caps-resolved` forever. The barrier is
+  // an event-based gateway racing the resolve message against a bounded `capsWaitTimeout` timer; when
+  // the bound elapses the timer arm fires and the token escalates to the `feature-escalation` operator
+  // user task (with a seeded operator `question`). We never publish `caps-resolved` — advancing the
+  // virtual clock past the seeded bound is the only way the token can move, so a green here proves the
+  // durable in-process bound (a barrier with no timer would simply hang, taking no flow).
+  test("capability edge: an unresolvable barrier escalates to the operator when the bound elapses (#289)", async () => {
+    const capTaskPlan: Stub = () => ({
+      tasks: [
+        {
+          id: "t1",
+          title: "T1",
+          prompt: "do t1",
+          // A bare handle names no owner/repo releases source — unresolvable, so caps-resolved never comes.
+          needs: [{ capabilityRef: "#274", package: "@nanobpm/urban" }],
+        },
+      ],
+    });
+    let featureRan = false;
+    await withApp(
+      {
+        "senior:plan": capTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": () => {
+          featureRan = true;
+          return { status: "opened", summary: "built t1", pr: "owner/repo#2" };
+        },
+      },
+      async ({ app, processKey }) => {
+        // Parked at the barrier: the agent has not run and no timeout flow has been taken yet.
+        assert.equal(featureRan, false, "the agent is not dispatched while parked at the barrier");
+        const parked = takenFlows(app);
+        assert.ok(
+          parked.includes("w_gw_caps->wait-caps-resolved") && parked.includes("w_gw_caps->wait-caps-timeout"),
+          `both barrier arms are armed by the event-based gateway (flows: ${parked.join(", ")})`,
+        );
+        assert.ok(!parked.includes("wait-caps-timeout->feature-escalation"), "the timeout has not fired yet");
+
+        // Never publish caps-resolved — let the bound (default P1D) elapse. Advancing past it is the
+        // ONLY way the token can move, so this proves the wait is genuinely bounded.
+        await app.advanceTime(25 * 60 * 60 * 1000);
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("wait-caps-timeout->feature-escalation"),
+          `the caps bound escalated the parked task to the operator (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("wait-caps-resolved->implement-task"),
+          "the resolve arm was withdrawn — the token did not also proceed as if resolved",
+        );
+        assert.equal(featureRan, false, "the agent was NOT dispatched — the unresolved task escalated instead");
+
+        // The escalation is a genuine, operable operator decision point: answering it loops the
+        // child back to re-dispatch the task (the operator having unblocked/decided), exactly like an
+        // agent-raised escalation — proving this is a real bounded wait + operator escalation, not a
+        // dead end.
+        const task = await openTask(app, processKey, "feature-escalation");
+        assert.ok(task.userTaskKey, "the caps-timeout escalation carries a completable userTaskKey");
+        await app.engine.completeUserTask(task.userTaskKey, { resolution: "answer", answer: "shipped it manually" });
+        await app.settle();
+
+        const answered = takenFlows(app);
+        assert.ok(
+          answered.includes("w_gw_answer->implement-task"),
+          `answering the caps escalation routed back to implement-task (flows: ${answered.join(", ")})`,
+        );
+        assert.equal(featureRan, true, "the agent was dispatched once the operator answered the caps escalation");
+      },
+    );
+  });
 });

package/nano.app.json

@@ -118,6 +118,10 @@
       "taskType": "pr.select-wave",
       "handler": "workers/select-wave/worker.ts"
     },
+    {
+      "taskType": "pr.caps-prepare",
+      "handler": "workers/caps-prepare/worker.ts"
+    },
     {
       "taskType": "pr.record-wave",
       "handler": "workers/record-wave/worker.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",