@nanobpm/nano-workforce 0.84.0 → 0.85.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.85.0](https://github.com/nanobpm/nano-workforce/compare/v0.84.0...v0.85.0) (2026-08-17)
+
+
+### Features
+
+* **readiness:** capability probe kind — resolve capability→version from publish provenance, late-bind + pin ([#274](https://github.com/nanobpm/nano-workforce/issues/274)) ([#275](https://github.com/nanobpm/nano-workforce/issues/275)) ([33171b7](https://github.com/nanobpm/nano-workforce/commit/33171b73a69d5b130f205be12e7f0988b3f268a6)), closes [#258](https://github.com/nanobpm/nano-workforce/issues/258)
+
 # [0.84.0](https://github.com/nanobpm/nano-workforce/compare/v0.83.0...v0.84.0) (2026-08-17)
 
 

package/app/feature.ts

@@ -17,7 +17,7 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
-import { deriveListBucket, deriveStage } from "./stage.ts";
+import { deriveEscalationOpen, deriveListBucket, deriveStage } from "./stage.ts";
 
 /** The BPMN process this module drives (resources/processes/feature.bpmn). */
 export const FEATURE_PROCESS_ID = "feature";
@@ -63,6 +63,16 @@ export interface FeatureRun {
    * (`completeUserTaskAttributed`) and the pages gate the answer controls on (`showWhenField`). Set by
    * `pollFeatureEscalations` while parked; NULL otherwise. */
   escalation_user_task_key: string | null;
+  /** Gateway projection (issue #272): the single fail-closed "open escalation" display signal, `1` iff
+   * ALL THREE escalation columns agree the run is parked at an answerable escalation
+   * (`status='escalated'` AND `escalation_user_task_key` non-NULL AND `escalation_question` non-NULL),
+   * else `0`. Derived by `deriveEscalationOpen` at write time. The escalation tuple is spread across
+   * three independently-written columns, so an interim read can see a TORN state (a live pointer with a
+   * blank question, or a status lagging behind a cleared question); the pages gate the Abandon action
+   * and the answer form on THIS conjunction instead of on `escalation_user_task_key` alone, so a torn
+   * tuple renders as not-escalated rather than escalated-but-blank. NULL only on legacy rows before the
+   * projection reached them (backfilled once at boot). */
+  escalation_open: number | null;
   /** The completable native `feature-blocked` user-task key the "Acknowledge blocked" affordance posts
    * to (`completeUserTaskAttributed`) and the pages gate the acknowledge control on (`showWhenField`).
    * Kept DISTINCT from `escalation_user_task_key` so the two human tasks (an escalation answer vs a
@@ -296,6 +306,7 @@ const PROJECTION_OUTPUT_KEYS: readonly (keyof FeatureRun)[] = [
   "stage_skipped",
   "attention",
   "list_bucket",
+  "escalation_open",
 ];
 
 /** True when a patch changes at least one field the projection derives from OR one it writes — i.e. the
@@ -326,6 +337,13 @@ function projectFeatureRun(row: Partial<FeatureRun>): Partial<FeatureRun> {
     stage_skipped: skipped,
     attention,
     list_bucket: deriveListBucket(row.status, row.acknowledged_at ?? null),
+    escalation_open: deriveEscalationOpen({
+      status: row.status,
+      escalation_question: row.escalation_question ?? null,
+      escalation_user_task_key: row.escalation_user_task_key ?? null,
+    })
+      ? 1
+      : 0,
   };
 }
 
@@ -370,21 +388,25 @@ export const featureRuns = (data: DataLayer) => {
   });
 };
 
-/** Re-project every feature_runs row through the gateway so rows written before migration 039 (whose
- * projection columns are NULL) get correct `stage`/`stage_state`/`stage_skipped`/`attention`/
- * `list_bucket` values. Idempotent and safe to re-run: it re-derives from each row's own stored fields,
- * so a second pass is a no-op. Runs once at boot (pollOnce) — the gateway keeps every future write
- * fresh, so this only needs to catch legacy rows once. */
+/** Re-project every feature_runs row through the gateway so rows missing any projection column get
+ * correct `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`/`escalation_open` values.
+ * Catches rows written before migration 039 (the pipeline columns) AND rows written before migration
+ * 040 (whose `escalation_open` column is NULL, issue #272). Idempotent and safe to re-run: it
+ * re-derives from each row's own stored fields, so a second pass is a no-op. Runs once at boot
+ * (pollOnce) — the gateway keeps every future write fresh, so this only needs to catch legacy rows.
+ * Reprojecting on a missing `escalation_open` matters for a run parked at a LIVE escalation when
+ * migration 040 lands: `pollFeatureEscalations` writes nothing while it stays parked (no change), so
+ * without this the fail-closed signal would stay NULL and hide a genuinely-open escalation. */
 export async function backfillFeatureStages(data: DataLayer): Promise<number> {
   const table = featureRuns(data);
   const rows = await table.all();
   let stamped = 0;
   for (const row of rows) {
-    // Only touch rows the projection has never reached — a legacy pre-039 row whose `stage` column is
-    // still NULL. The gateway keeps every write fresh, so an already-projected row needs no re-write;
-    // skipping them avoids a full-table rewrite on every boot and keeps `stamped` an honest count of
-    // rows actually backfilled (not the total row count).
-    if (row.stage != null) continue;
+    // Only touch rows the projection has never fully reached — a legacy row whose `stage` (pre-039) or
+    // `escalation_open` (pre-040) column is still NULL. The gateway keeps every write fresh, so a
+    // fully-projected row needs no re-write; skipping them avoids a full-table rewrite on every boot and
+    // keeps `stamped` an honest count of rows actually backfilled (not the total row count).
+    if (row.stage != null && row.escalation_open != null) continue;
     // Re-derive the projection from the legacy row's own stored fields and write it. (An empty patch
     // would now short-circuit the projecting proxy — it only reprojects on a projection-input change —
     // so backfill projects explicitly rather than relying on an empty-patch reproject.)

package/app/featureGateway.test.ts

@@ -72,6 +72,56 @@ test("update {status:'escalated'} on a row with no pr_key projects Implementing
   assertEquals(rows[0].stage_state, null);
 });
 
+// issue #272: the fail-closed open-escalation projection. The escalation tuple is spread across three
+// independently-written columns; the gateway projects `escalation_open=1` ONLY when all three agree.
+test("escalation_open is 1 only when status=escalated AND pointer AND question all present", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#esc", status: "running", pr_key: null, converge: 1, auto_merge: 1 });
+  // A complete, answerable escalation → 1.
+  await featureRuns(data).update("o/r#esc", {
+    status: "escalated",
+    escalation_user_task_key: "ut-9",
+    escalation_question: "which base branch?",
+  });
+  assertEquals(rows[0].escalation_open, 1);
+});
+
+test("a torn escalation tuple projects escalation_open=0 (renders not-escalated, fail closed)", async () => {
+  const { data, rows } = memData();
+  // Simulate the exit-path/poller race: the question was cleared while status + pointer still lag in the
+  // escalated projection (the mirror tear observed on nwf#270). The page must NOT show an escalation.
+  rows.push({
+    feature_key: "o/r#torn",
+    status: "escalated",
+    pr_key: null,
+    converge: 1,
+    auto_merge: 1,
+    escalation_user_task_key: "ut-9",
+    escalation_question: "which base?",
+    escalation_open: 1,
+  });
+  await featureRuns(data).update("o/r#torn", { escalation_question: null });
+  assertEquals(rows[0].escalation_open, 0);
+});
+
+test("clearing the escalation tuple flips escalation_open to 0 without waiting a poll pass", async () => {
+  const { data, rows } = memData();
+  // The answer operation eagerly clears pointer + question; the gateway reprojects on that same write,
+  // so the affordance disappears immediately (issue #272 acceptance: no poll-pass lag).
+  rows.push({
+    feature_key: "o/r#ans",
+    status: "escalated",
+    pr_key: null,
+    converge: 1,
+    auto_merge: 1,
+    escalation_user_task_key: "ut-9",
+    escalation_question: "which base?",
+    escalation_open: 1,
+  });
+  await featureRuns(data).update("o/r#ans", { escalation_user_task_key: null, escalation_question: null });
+  assertEquals(rows[0].escalation_open, 0);
+});
+
 test("a run with converge=false projects stage_skipped containing Converging and Merging", async () => {
   const { data, rows } = memData();
   rows.push({ feature_key: "o/r#5", status: "running", converge: 0, auto_merge: 0 });
@@ -162,9 +212,12 @@ test("backfillFeatureStages stamps legacy terminal and live rows with helper-der
   // Legacy rows written before migration 039 → projection columns absent/NULL.
   rows.push({ feature_key: "o/r#8", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: "2024-01-01T00:00:00Z" });
   rows.push({ feature_key: "o/r#9", status: "running", pr_key: null, converge: 0, auto_merge: 0 });
+  // A legacy row parked at a LIVE escalation when migration 040 lands: escalation_open is NULL and the
+  // poller won't re-write it while it stays parked, so backfill MUST reproject it to 1 (issue #272).
+  rows.push({ feature_key: "o/r#esc", status: "escalated", pr_key: null, converge: 1, auto_merge: 1, escalation_user_task_key: "ut-9", escalation_question: "which base?" });
 
   const stamped = await backfillFeatureStages(data);
-  assertEquals(stamped, 2);
+  assertEquals(stamped, 3);
 
   const terminal = rows.find((r) => r.feature_key === "o/r#8");
   assertEquals(terminal.stage, "Done");
@@ -176,19 +229,24 @@ test("backfillFeatureStages stamps legacy terminal and live rows with helper-der
   assertEquals(live.stage_state, null);
   assertEquals(live.stage_skipped, "Converging Merging");
   assertEquals(live.list_bucket, "active");
+  assertEquals(live.escalation_open, 0);
+
+  const escalated = rows.find((r) => r.feature_key === "o/r#esc");
+  assertEquals(escalated.escalation_open, 1);
 });
 
 test("backfillFeatureStages skips already-projected rows and counts only rows it stamps", async () => {
   const { data, rows } = memData();
   // One legacy row (no projection) + one already-projected row (gateway kept it fresh).
   rows.push({ feature_key: "o/r#legacy", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null });
-  rows.push({ feature_key: "o/r#fresh", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null, stage: "Done", stage_state: "ok", stage_skipped: "", attention: null, list_bucket: "active", updated_at: "0" });
+  rows.push({ feature_key: "o/r#fresh", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null, stage: "Done", stage_state: "ok", stage_skipped: "", attention: null, list_bucket: "active", escalation_open: 0, updated_at: "0" });
 
   const stamped = await backfillFeatureStages(data);
   // Only the legacy row is stamped; the already-projected row is skipped.
   assertEquals(stamped, 1);
   const legacy = rows.find((r) => r.feature_key === "o/r#legacy");
   assertEquals(legacy.stage, "Done");
+  assertEquals(legacy.escalation_open, 0);
   // The already-projected row was not re-written (its sentinel updated_at is untouched).
   const fresh = rows.find((r) => r.feature_key === "o/r#fresh");
   assertEquals(fresh.updated_at, "0");

package/app/readiness.test.ts

@@ -7,20 +7,27 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects, assertStringIncludes, assertThrows } from "#test-assert";
 import {
   type CommandResult,
+  cmpVersion,
   DEFAULT_ATTEMPT_TIMEOUT_MS,
   DEFAULT_EVERY_MS,
   DEFAULT_TIMEOUT_MS,
   defaultProbeExec,
+  type GithubRelease,
   type HttpResponse,
+  makeCapabilityFallback,
   MAX_EVERY_MS,
+  matchCapability,
   matchCommand,
   matchGithubCheck,
   matchHttp,
   matchNpm,
   msToIsoDuration,
+  newestPublishedVersion,
   nextDelay,
   normalizePoll,
   parseProbe,
+  parseReleases,
+  parseReleasesTarget,
   parseRepoRef,
   probeBudgetMs,
   probeOnce,
@@ -102,6 +109,186 @@ test("parseProbe: accepts a declared credentialEnv (http) and parses nested matc
   assertEquals(p.poll?.backoff, "fixed");
 });
 
+// ── parseProbe: capability kind (#274 — required capabilityRef + package, fail loudly on blank) ──
+test("parseProbe: a capability probe with a blank capabilityRef throws (a never-resolvable edge must fail loudly)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "capability", target: "github-releases:nanobpm/nano-ide", match: { package: "@nanobpm/urban" } }),
+    Error,
+    "capabilityRef' is required",
+  );
+});
+
+test("parseProbe: a capability probe with a blank package throws (provenance is per-package scoped)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "capability", target: "github-releases:nanobpm/nano-ide", match: { capabilityRef: "#274" } }),
+    Error,
+    "package' is required",
+  );
+});
+
+test("parseProbe: a capability probe whose capabilityRef carries no numeric id throws (never resolvable)", () => {
+  assertThrows(
+    () =>
+      parseProbe({
+        kind: "capability",
+        target: "github-releases:nanobpm/nano-ide",
+        match: { capabilityRef: "nano-ide#", package: "@nanobpm/urban" },
+      }),
+    Error,
+    "must carry a",
+  );
+});
+
+test("parseProbe: a valid capability probe round-trips its required match fields", () => {
+  const p = parseProbe({
+    kind: "capability",
+    target: "github-releases:nanobpm/nano-ide",
+    match: { capabilityRef: "nano-ide#274", package: "@nanobpm/urban", verifyCommand: "node -e 0" },
+  });
+  assertEquals(p.kind, "capability");
+  assertEquals(p.match?.capabilityRef, "nano-ide#274");
+  assertEquals(p.match?.package, "@nanobpm/urban");
+  assertEquals(p.match?.verifyCommand, "node -e 0");
+  assertEquals(p.onTimeout, "escalate");
+});
+
+// ── matchCapability: the deterministic lowest-version-per-package resolver (#274 Gap A) ──────────
+const rel = (tag: string, refs: number[]): GithubRelease => ({
+  tag,
+  body: `Automated release of \`${tag}\`.\n\n## Provenance\n${refs.map((n) => `- #${n}`).join("\n")}\n`,
+});
+const capMatch = { capabilityRef: "nano-ide#274", package: "@nanobpm/urban" };
+
+test("matchCapability: a capability in exactly one release resolves that version and binds resolvedArtifact", () => {
+  const res = matchCapability(capMatch, [rel("@nanobpm/urban@0.54.0", [273, 274, 275])]);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@0.54.0");
+});
+
+test("matchCapability: present in multiple releases resolves the LOWEST version (first-carries)", () => {
+  const releases = [
+    rel("@nanobpm/urban@0.60.0", [274]),
+    rel("@nanobpm/urban@0.54.0", [274]),
+    rel("@nanobpm/urban@0.9.0", [274]), // 0.9 < 0.54 numerically — cmpVersion, not lexicographic
+  ];
+  const res = matchCapability(capMatch, releases);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@0.9.0");
+});
+
+test("matchCapability: an absent capability is not-ready (still waiting), never throws", () => {
+  const res = matchCapability(capMatch, [rel("@nanobpm/urban@0.54.0", [200, 201])]);
+  assert(!res.ready);
+  assertEquals(res.bind, undefined);
+});
+
+test("matchCapability: the same #C in another package resolves ONLY within the named package", () => {
+  const releases = [
+    rel("@nanobpm/other@1.0.0", [274]), // same #274, wrong package — must be ignored
+    rel("@nanobpm/urban@0.55.0", [274]),
+  ];
+  const res = matchCapability(capMatch, releases);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@0.55.0");
+});
+
+test("matchCapability: a prefix ref (#27) never spuriously satisfies #274", () => {
+  assert(!matchCapability(capMatch, [rel("@nanobpm/urban@0.54.0", [27])]).ready);
+});
+
+test("matchCapability: a malformed/empty releases list is not-ready and never throws", () => {
+  assert(!matchCapability(capMatch, []).ready);
+  // biome-ignore lint/suspicious/noExplicitAny: deliberately malformed rows exercise the tolerant guard.
+  assert(!matchCapability(capMatch, [{ tag: 123, body: null } as any, null as any]).ready);
+});
+
+test("matchCapability: the bare '#274' ref form resolves identically to 'nano-ide#274'", () => {
+  const res = matchCapability({ capabilityRef: "#274", package: "@nanobpm/urban" }, [rel("@nanobpm/urban@1.2.3", [274])]);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@1.2.3");
+});
+
+test("cmpVersion: numeric dotted compare (0.9 < 0.54 < 0.60), matching nano-ide publish.mjs", () => {
+  assert(cmpVersion("0.9.0", "0.54.0") < 0);
+  assert(cmpVersion("0.54.0", "0.60.0") < 0);
+  assertEquals(cmpVersion("1.2", "1.2.0"), 0);
+});
+
+test("newestPublishedVersion: picks the highest version of the named package only", () => {
+  const releases = [rel("@nanobpm/urban@0.9.0", []), rel("@nanobpm/urban@0.54.0", []), rel("@nanobpm/other@9.9.9", [])];
+  assertEquals(newestPublishedVersion("@nanobpm/urban", releases), "0.54.0");
+  assertEquals(newestPublishedVersion("@nanobpm/missing", releases), undefined);
+});
+
+test("parseReleases: reduces a gh api payload to {tag, body}; non-array input yields []", () => {
+  const parsed = parseReleases([{ tag_name: "@nanobpm/urban@0.54.0", body: "## Provenance\n- #274" }, { nope: 1 }]);
+  assertEquals(parsed[0]?.tag, "@nanobpm/urban@0.54.0");
+  assertEquals(parseReleases("not-an-array").length, 0);
+  assertEquals(parseReleases(null).length, 0);
+});
+
+test("parseReleases: flattens the --paginate --slurp array-of-pages shape (>100 releases are seen)", () => {
+  const slurped = [
+    [{ tag_name: "@nanobpm/urban@0.54.0", body: "- #274" }],
+    [{ tag_name: "@nanobpm/urban@0.9.0", body: "- #274" }],
+  ];
+  const tags = parseReleases(slurped).map((r) => r.tag);
+  assertEquals(tags.includes("@nanobpm/urban@0.54.0"), true, "first page's release is seen");
+  assertEquals(tags.includes("@nanobpm/urban@0.9.0"), true, "a later page's release is seen too");
+});
+
+test("parseReleasesTarget: strips the optional github-releases: scheme, else passes owner/repo through", () => {
+  assertEquals(parseReleasesTarget("github-releases:nanobpm/nano-ide"), "nanobpm/nano-ide");
+  assertEquals(parseReleasesTarget("nanobpm/nano-ide"), "nanobpm/nano-ide");
+});
+
+// ── probeOnce capability dispatch + gated fallback (#274 decision 5) ─────────────────────────────
+test("probeOnce capability: queries the repo's releases and binds the resolved artifact", async () => {
+  const cap: { cmd?: string } = {};
+  const payload = JSON.stringify([{ tag_name: "@nanobpm/urban@0.54.0", body: "## Provenance\n- #274\n" }]);
+  const exec = stubExec({ command: { code: 0, stdout: payload, stderr: "" }, capture: cap });
+  const res = await probeOnce(parseProbe({ kind: "capability", target: "github-releases:nanobpm/nano-ide", match: capMatch }), exec, {});
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@0.54.0");
+  assertStringIncludes(cap.cmd ?? "", "repos/nanobpm/nano-ide/releases");
+});
+
+test("probeOnce capability: a failed gh api call is not-ready (never throws)", async () => {
+  const exec = stubExec({ command: { code: 1, stdout: "", stderr: "boom" } });
+  const res = await probeOnce(parseProbe({ kind: "capability", target: "nanobpm/nano-ide", match: capMatch }), exec, {});
+  assert(!res.ready);
+});
+
+test("makeCapabilityFallback: null for a capability probe with no verifyCommand (deterministic-only)", async () => {
+  const probe = parseProbe({ kind: "capability", target: "nanobpm/nano-ide", match: capMatch });
+  const fb = makeCapabilityFallback(probe, stubExec({}), {});
+  assertEquals(await fb(), null);
+});
+
+test("makeCapabilityFallback: verifies the NEWEST version empirically and binds it when the verifier passes", async () => {
+  const payload = JSON.stringify([
+    { tag_name: "@nanobpm/urban@0.54.0", body: "no ref" },
+    { tag_name: "@nanobpm/urban@0.60.0", body: "no ref" },
+  ]);
+  const seen: string[] = [];
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(command, env) {
+      seen.push(command);
+      if (command.includes("gh api")) return { code: 0, stdout: payload, stderr: "" };
+      // the verifier: assert the newest version was handed to it via the env
+      return { code: env.RESOLVED_VERSION === "0.60.0" ? 0 : 1, stdout: "", stderr: "" };
+    },
+  };
+  const probe = parseProbe({ kind: "capability", target: "nanobpm/nano-ide", match: { ...capMatch, verifyCommand: "verify.sh" } });
+  const res = await makeCapabilityFallback(probe, exec, {})();
+  assert(res?.ready);
+  assertEquals(res?.bind?.resolvedArtifact, "@nanobpm/urban@0.60.0");
+  assert(seen.some((c) => c === "verify.sh"), "the verifier command was run at the boundary");
+});
+
 // ── matchers ────────────────────────────────────────────────────────────────────────────────
 test("matchHttp: any 2xx is ready by default; a 503 is not", () => {
   assert(matchHttp(undefined, { status: 204, body: "" }).ready);

package/app/readiness.ts

@@ -9,18 +9,23 @@
 //
 // The probe is DATA, not code — a {@link ReadinessProbe} descriptor with a `kind` and a per-kind
 // `match` predicate. Authors add a readiness source by adding a `kind`'s matcher, never by editing
-// the BPMN or the worker's control flow. Four built-in kinds ship (`http`, `command`, `npm`,
-// `github-check`); everything else is reached through the `command` escape hatch (ADR 0001 §2
-// pinned decision 1). A probe carries NO secret material — any credential is read at execution
-// time from the typed env-contract (`credentialEnv` names a declared {@link EnvKey}; ADR 0004
-// pinned decision 2) and is redacted from every log line.
+// the BPMN or the worker's control flow. Five built-in kinds ship (`http`, `command`, `npm`,
+// `github-check`, `capability`); everything else is reached through the `command` escape hatch
+// (ADR 0001 §2 pinned decision 1). The `capability` kind (ADR 0001 §4, issue #274) resolves a
+// cross-repo capability edge — "which published version first carries capability C?" — from the
+// publish-provenance substrate and late-binds the discovered `pkg@version` back through the gate
+// via {@link ProbeResult.bind}, the reusable emit primitive. A probe carries NO secret material —
+// any credential is read at execution time from the typed env-contract (`credentialEnv` names a
+// declared {@link EnvKey}; ADR 0004 pinned decision 2) and is redacted from every log line.
 import { isEnvKey, readEnv, readEnvOr } from "./contracts.ts";
 import { isoDuration, isoDurationToMs } from "./reviewWait.ts";
 
 /** The built-in readiness sources. `command` is the escape hatch that subsumes the long tail
  * (`gh`, `curl`, `docker manifest inspect`, a custom probe) — adding a first-class kind later is
- * an additive matcher, not a schema change. */
-export type ProbeKind = "http" | "command" | "npm" | "github-check";
+ * an additive matcher, not a schema change. `capability` is the first such additive kind (#274):
+ * it resolves "which published version first carries capability C?" from the publish-provenance
+ * substrate and binds the discovered `pkg@version` back through the gate (see {@link matchCapability}). */
+export type ProbeKind = "http" | "command" | "npm" | "github-check" | "capability";
 
 /** What the gate does when the bounded wait times out (the engine timer arm fires). */
 export type OnTimeout = "escalate" | "fail" | "continue";
@@ -28,7 +33,7 @@ export type OnTimeout = "escalate" | "fail" | "continue";
 /** Backoff policy between poll attempts. */
 export type Backoff = "fixed" | "exponential";
 
-const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check"];
+const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability"];
 const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
 const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
 
@@ -49,6 +54,18 @@ export interface ProbeMatch {
   readonly conclusion?: string;
   /** github-check: restrict the predicate to the named check run (default: every check run). */
   readonly checkName?: string;
+  /** capability: the upstream issue/PR handle the resolved version must carry in its publish
+   * provenance — `nano-ide#274` or the bare `#274`. Required for the `capability` kind. */
+  readonly capabilityRef?: string;
+  /** capability: the package whose releases are scanned (e.g. `@nanobpm/urban`). Provenance is
+   * per-package scoped — the same `#C` may appear in two packages — so this is required. */
+  readonly package?: string;
+  /** capability: an OPTIONAL empirical verifier command for the gated fallback (decision 5). Run
+   * ONCE at the gate boundary (poll budget exhausted) against the newest published `package`
+   * version when deterministic provenance resolved nothing; exit 0 binds that newest version. Left
+   * unset, the capability edge is deterministic-only. The resolved `pkg@version` and bare version
+   * are exposed to the command as `RESOLVED_ARTIFACT` / `RESOLVED_VERSION`. */
+  readonly verifyCommand?: string;
 }
 
 /** The poll cadence: how often to re-probe, how long to keep trying, and the backoff shape. */
@@ -75,10 +92,24 @@ export interface ReadinessProbe {
   readonly credentialEnv?: string;
 }
 
-/** The result of a single probe attempt. `detail` is a short, already-redacted human note. */
+/** The result of a single probe attempt. `detail` is a short, already-redacted human note.
+ * `bind` is the OPTIONAL late-bound value a matcher discovered (the reusable "emit" primitive,
+ * #274 Gap B): a kind-agnostic `key → value` map the worker forwards into the `readiness-ready`
+ * message so the gate can surface it as an output process variable (e.g. the `capability` kind
+ * binds `{ resolvedArtifact: "@nanobpm/urban@0.54.0" }`). Provenance is public, so nothing in
+ * `bind` is redacted; keep values free of any secret material by construction. */
 export interface ProbeResult {
   readonly ready: boolean;
   readonly detail: string;
+  readonly bind?: Record<string, string>;
+}
+
+/** A single published GitHub Release, reduced to the two fields the capability resolver reads: the
+ * `<package>@<version>` tag and the release body carrying the `## Provenance` `#NNN` refs. Kept
+ * separate from I/O so {@link matchCapability} is pure/unit-testable. */
+export interface GithubRelease {
+  readonly tag: string;
+  readonly body: string;
 }
 
 /** A raw HTTP response the http matcher inspects (kept separate from I/O so it is pure-testable). */
@@ -148,6 +179,26 @@ export function parseProbe(raw: unknown): ReadinessProbe {
   const onTimeout: OnTimeout = onTimeoutRaw === "" ? "escalate" : onTimeoutRaw;
 
   const match = isRecord(raw.match) ? parseMatch(raw.match) : undefined;
+  // A capability edge whose ref or package is blank can never resolve — fail loudly here rather than
+  // wait forever (mirroring the blank-`target` guard above). Both are required for this kind.
+  if (kind === "capability") {
+    if (!match?.capabilityRef) {
+      throw new Error("readiness probe (capability): 'match.capabilityRef' is required (e.g. 'nano-ide#274' or '#274')");
+    }
+    // A ref that carries no numeric issue/PR id (e.g. 'cap274' has a number, but 'nano-ide#' or a
+    // bare word does not) can never resolve — `matchCapability` would only surface it as a timeout
+    // much later. Reject it now, via the SAME canonical parser the resolver uses, so a malformed
+    // edge fails loudly at parse (mirroring the intent of the blank-ref guard above).
+    if (!capabilityNumber(match.capabilityRef)) {
+      throw new Error(
+        `readiness probe (capability): 'match.capabilityRef' ('${match.capabilityRef}') must carry a ` +
+          "numeric issue/PR id (e.g. 'nano-ide#274' or '#274')",
+      );
+    }
+    if (!match?.package) {
+      throw new Error("readiness probe (capability): 'match.package' is required (provenance is per-package scoped)");
+    }
+  }
   const poll = isRecord(raw.poll) ? parsePoll(raw.poll) : undefined;
   const credentialEnv = str(raw.credentialEnv).trim() || undefined;
   if (credentialEnv !== undefined && !isEnvKey(credentialEnv)) {
@@ -197,6 +248,9 @@ function parseMatch(raw: Record<string, unknown>): ProbeMatch {
     version: str(raw.version).trim() || undefined,
     conclusion: str(raw.conclusion).trim() || undefined,
     checkName: str(raw.checkName).trim() || undefined,
+    capabilityRef: str(raw.capabilityRef).trim() || undefined,
+    package: str(raw.package).trim() || undefined,
+    verifyCommand: str(raw.verifyCommand).trim() || undefined,
   };
 }
 
@@ -304,6 +358,126 @@ function versionOf(target: string): string | undefined {
   return v === "" ? undefined : v;
 }
 
+// ── Capability resolver (#274 Gap A — a stable, pure "which version first carries C?" matcher) ───
+
+/** Compare two dotted numeric version strings (`major.minor.patch…`), reusing the exact semantics of
+ * nano-ide `scripts/publish.mjs` `cmpVersion` so the resolver and the publisher agree on ordering.
+ * Missing trailing segments count as 0; returns <0, 0, or >0. */
+export function cmpVersion(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+/** The bare, purely numeric `#NNN` number from a capability handle — `nano-ide#274`, `#274`, or a
+ * naked `274` all normalise to `274`. Returns undefined for anything without a number, so a blank/
+ * malformed ref never accidentally matches. */
+function capabilityNumber(ref: string): string | undefined {
+  const m = ref.match(/(\d+)\s*$/);
+  return m ? m[1] : undefined;
+}
+
+/** Does a release body's `## Provenance` reference `#NNN`? Matched on a `#`-prefixed word boundary so
+ * `#27` never spuriously satisfies `#274`. */
+function bodyReferences(body: string, num: string): boolean {
+  return new RegExp(`#${num}(?!\\d)`).test(body);
+}
+
+/** The `<version>` of a release tagged exactly `<package>@<version>` (numeric-dotted), or undefined
+ * when the tag belongs to another package or is not a version tag. Per-package scoping is enforced
+ * here: a sibling package's provenance can never leak into this package's resolution. */
+function versionForPackage(tag: string, pkg: string): string | undefined {
+  const prefix = `${pkg}@`;
+  if (!tag.startsWith(prefix)) return undefined;
+  const v = tag.slice(prefix.length).trim();
+  return /^\d+(\.\d+)*$/.test(v) ? v : undefined;
+}
+
+/** capability readiness (#274 Gap A): among GitHub Releases tagged `<match.package>@*` whose body
+ * references `match.capabilityRef`, resolve the **lowest** SemVer version — that is the version that
+ * *first* carries the capability (`firstVersion`). Late-binds it as `{ resolvedArtifact }` so the
+ * gate can hand the exact `pkg@version` to the consumer (#274 Gap B). PURE: it operates on an
+ * already-fetched, parsed releases list and NEVER throws — a malformed/empty list is simply
+ * "not ready yet" (keep waiting), so a transient provenance read cannot crash the poll loop. */
+export function matchCapability(match: ProbeMatch | undefined, releases: readonly GithubRelease[]): ProbeResult {
+  const pkg = match?.package;
+  const ref = match?.capabilityRef;
+  if (!pkg || !ref) return { ready: false, detail: "capability: missing package/capabilityRef" };
+  const num = capabilityNumber(ref);
+  if (!num) return { ready: false, detail: "capability: unparseable capabilityRef (no #NNN)" };
+
+  let firstVersion: string | undefined;
+  for (const rel of releases) {
+    if (!rel || typeof rel.tag !== "string" || typeof rel.body !== "string") continue;
+    const version = versionForPackage(rel.tag, pkg);
+    if (!version) continue;
+    if (!bodyReferences(rel.body, num)) continue;
+    if (firstVersion === undefined || cmpVersion(version, firstVersion) < 0) firstVersion = version;
+  }
+  if (firstVersion === undefined) return { ready: false, detail: `capability #${num} not published in ${pkg} yet` };
+  const resolvedArtifact = `${pkg}@${firstVersion}`;
+  return { ready: true, detail: `capability #${num} carried by ${resolvedArtifact}`, bind: { resolvedArtifact } };
+}
+
+/** The **newest** published SemVer version of `pkg` across `releases` — the target of the gated
+ * empirical fallback (decision 5), which installs the latest release and verifies the capability
+ * behaviourally when deterministic provenance resolved nothing. PURE / never throws. */
+export function newestPublishedVersion(pkg: string | undefined, releases: readonly GithubRelease[]): string | undefined {
+  if (!pkg) return undefined;
+  let newest: string | undefined;
+  for (const rel of releases) {
+    if (!rel || typeof rel.tag !== "string") continue;
+    const version = versionForPackage(rel.tag, pkg);
+    if (!version) continue;
+    if (newest === undefined || cmpVersion(version, newest) > 0) newest = version;
+  }
+  return newest;
+}
+
+/** Parse a raw `gh api .../releases` payload (already JSON-decoded) into the minimal
+ * {@link GithubRelease} list the resolver reads. Tolerant: non-array/malformed input yields `[]`,
+ * so a bad provenance read degrades to "not ready", never a throw. Also accepts the `--paginate
+ * --slurp` shape — an array whose elements are themselves per-page arrays — flattening one level so
+ * releases beyond the first 100 (the true lowest version that first carried a capability) are seen. */
+export function parseReleases(payload: unknown): GithubRelease[] {
+  if (!Array.isArray(payload)) return [];
+  const out: GithubRelease[] = [];
+  const push = (r: unknown): void => {
+    if (!isRecord(r)) return;
+    out.push({ tag: str(r.tag_name), body: str(r.body) });
+  };
+  for (const el of payload) {
+    if (Array.isArray(el)) {
+      for (const r of el) push(r);
+    } else {
+      push(el);
+    }
+  }
+  return out;
+}
+
+/** Split a `capability` target (`github-releases:owner/repo`) into the provenance source repo. The
+ * `github-releases:` scheme prefix is optional — a bare `owner/repo` is accepted too. */
+export function parseReleasesTarget(target: string): string {
+  const t = target.trim();
+  const scheme = "github-releases:";
+  return t.startsWith(scheme) ? t.slice(scheme.length).trim() : t;
+}
+
+/** Build the `gh api` command that lists a repo's releases (the provenance substrate). `gh` reads
+ * its token from the ambient env, exactly like the `github-check` kind — no `credentialEnv`.
+ * `--paginate --slurp` walks the FULL release history (not just the first `per_page=100` page), so a
+ * repo with >100 releases can still surface the lowest version that first carried a capability;
+ * `--slurp` wraps the pages in an outer array that {@link parseReleases} flattens. */
+export function githubReleasesCommand(repo: string): string {
+  return `gh api --paginate --slurp ${shellQuote(`repos/${repo}/releases?per_page=100`)} -H ${shellQuote("Accept: application/vnd.github+json")}`;
+}
+
+
 // ── Single probe attempt (does I/O via the injected {@link ProbeExec}) ──────────────────────────
 
 /** Run ONE probe attempt for `probe`, resolving any credential from the typed env-contract and
@@ -332,9 +506,46 @@ export async function probeOnce(
       if (out.code !== 0) return { ready: false, detail: "github-check: gh api failed (not ready)" };
       return matchGithubCheck(probe.match, parseJson(out.stdout));
     }
+    case "capability": {
+      const repo = parseReleasesTarget(probe.target);
+      const out = await exec.run(githubReleasesCommand(repo), env);
+      if (out.code !== 0) return { ready: false, detail: "capability: gh api failed (not ready)" };
+      return matchCapability(probe.match, parseReleases(parseJson(out.stdout)));
+    }
   }
 }
 
+/** Build the gated empirical fallback for a `capability` probe (decision 5) — a thunk the poll loop
+ * runs ONCE at the gate boundary (local budget exhausted) when deterministic provenance resolved
+ * nothing. It installs nothing itself: it fetches releases, picks the NEWEST published version, and
+ * runs the descriptor's `match.verifyCommand` against it (with `RESOLVED_ARTIFACT`/`RESOLVED_VERSION`
+ * in the env) — exit 0 binds that newest version, letting a capability that provenance under-reported
+ * still resolve empirically. Returns `null` (no fallback) for a non-capability probe, a capability
+ * probe with no `verifyCommand` (deterministic-only), or when no version/releases are available — so
+ * the default path stays a pure deterministic lookup and the agent judgment is the gated exception. */
+export function makeCapabilityFallback(
+  probe: ReadinessProbe,
+  exec: ProbeExec,
+  env: Record<string, string | undefined>,
+): () => Promise<ProbeResult | null> {
+  return async () => {
+    if (probe.kind !== "capability") return null;
+    const verify = probe.match?.verifyCommand;
+    const pkg = probe.match?.package;
+    if (!verify || !pkg) return null;
+    const listed = await exec.run(githubReleasesCommand(parseReleasesTarget(probe.target)), env);
+    if (listed.code !== 0) return null;
+    const newest = newestPublishedVersion(pkg, parseReleases(parseJson(listed.stdout)));
+    if (!newest) return null;
+    const artifact = `${pkg}@${newest}`;
+    const res = await exec.run(verify, { ...env, RESOLVED_ARTIFACT: artifact, RESOLVED_VERSION: newest });
+    if (res.code === 0) {
+      return { ready: true, detail: `capability verified empirically at ${artifact}`, bind: { resolvedArtifact: artifact } };
+    }
+    return { ready: false, detail: "capability: empirical verification failed at gate boundary" };
+  };
+}
+
 /** Resolve the credential a probe declares, from the typed env-contract only. Returns undefined
  * when no `credentialEnv` is declared or the key is unset — never a value from the descriptor. */
 function credentialFor(probe: ReadinessProbe, env: Record<string, string | undefined>): string | undefined {

package/app/stage.test.ts

@@ -5,7 +5,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import { FEATURE_RUN_STATUSES } from "./feature.ts";
-import { deriveListBucket, deriveStage, type StageInput } from "./stage.ts";
+import { deriveEscalationOpen, deriveListBucket, deriveStage, type StageInput } from "./stage.ts";
 
 const base = (over: Partial<StageInput> & { status: string }): StageInput => ({
   pr_key: null,
@@ -105,3 +105,47 @@ test("deriveListBucket: history iff terminal AND acknowledged, else active", ()
   assertEquals(deriveListBucket("running", "2024-01-01T00:00:00Z"), "active");
   assertEquals(deriveListBucket("blocked", "2024-01-01T00:00:00Z"), "history");
 });
+
+// deriveEscalationOpen (issue #272): the single fail-closed "open escalation" display signal. TRUE iff
+// all three independently-written escalation columns AGREE the run is parked at an answerable
+// escalation; any single missing/torn field yields FALSE so the pages render not-escalated.
+test("deriveEscalationOpen: true only when status, pointer AND question all present", () => {
+  assertEquals(
+    deriveEscalationOpen({ status: "escalated", escalation_user_task_key: "ut-7", escalation_question: "which base?" }),
+    true,
+  );
+});
+
+test("deriveEscalationOpen: torn tuple (pointer set, question blank) renders as NOT escalated", () => {
+  // The mirror tear observed on nwf#270: status=escalated + live pointer + blank question.
+  assertEquals(
+    deriveEscalationOpen({ status: "escalated", escalation_user_task_key: "ut-7", escalation_question: null }),
+    false,
+  );
+  assertEquals(
+    deriveEscalationOpen({ status: "escalated", escalation_user_task_key: "ut-7", escalation_question: "" }),
+    false,
+  );
+});
+
+test("deriveEscalationOpen: torn tuple (question set, pointer null) renders as NOT escalated", () => {
+  // The entry-window tear: record-feature-escalation persisted the question but the poller has not yet
+  // denormalised the pointer.
+  assertEquals(
+    deriveEscalationOpen({ status: "escalated", escalation_user_task_key: null, escalation_question: "which base?" }),
+    false,
+  );
+});
+
+test("deriveEscalationOpen: a resumed run whose status lags behind a cleared tuple is NOT escalated", () => {
+  // status still 'escalated' but the answer op already cleared pointer + question → fail closed.
+  assertEquals(
+    deriveEscalationOpen({ status: "escalated", escalation_user_task_key: null, escalation_question: null }),
+    false,
+  );
+  // A non-escalated status can never be open regardless of stray column values.
+  assertEquals(
+    deriveEscalationOpen({ status: "running", escalation_user_task_key: "ut-7", escalation_question: "which base?" }),
+    false,
+  );
+});

package/app/stage.ts

@@ -103,6 +103,35 @@ export function deriveStage(run: StageInput): DerivedStage {
   return { stage, state, skipped: skippedKeys.join(" "), attention };
 }
 
+/** Derive the single fail-closed "open escalation" display signal for one feature run (issue #272).
+ *
+ * The open-escalation condition is jointly encoded by THREE independently-written columns —
+ * `status='escalated'`, `escalation_user_task_key` (the completable pointer), and `escalation_question`
+ * — owned by different writers on different schedules (the `record-feature-escalation` service task
+ * sets the question; `pollFeatureEscalations`/`deriveFeatureEscalationPatch` sets status + pointer; the
+ * answer operation clears the tuple). Because they are not written as one atomic tuple, a reader can
+ * observe a TORN interim state (e.g. `status=escalated` + pointer set + `question=null`) and render a
+ * self-contradictory escalation — an "answer me" affordance with nothing to answer.
+ *
+ * Collapse that class at the consumer: the pages gate the escalation affordances (Abandon / answer
+ * form) on this ONE derived conjunction rather than on any single column, so a torn tuple renders as
+ * NOT escalated (fail closed) instead of escalated-but-blank. `true` iff ALL THREE fields agree the run
+ * is parked at an answerable escalation; any missing field yields `false`. Maintained as a write-time
+ * projection by the feature_runs gateway (like `stage`/`list_bucket`), so it stays fresh on every write
+ * — including the answer operation's eager tuple-clear, which makes the affordance disappear WITHOUT
+ * waiting a poll pass. Pure and read-only. */
+export function deriveEscalationOpen(run: {
+  status: string;
+  escalation_question?: string | null;
+  escalation_user_task_key?: string | null;
+}): boolean {
+  return (
+    run.status === "escalated" &&
+    (run.escalation_user_task_key ?? "") !== "" &&
+    (run.escalation_question ?? "") !== ""
+  );
+}
+
 /** The Active/History partition label (§5), maintained at write time so the flat-DSL page tabs filter
  * on a stored `list_bucket` column with only `in` clauses. `history` iff the row is in a truly-terminal
  * status AND acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). */

package/db/migrations/040_feature_escalation_open.sql

@@ -0,0 +1,33 @@
+-- 040_feature_escalation_open.sql — issue #272: collapse the torn open-escalation projection.
+--
+-- A feature run's "open escalation" condition is jointly encoded by THREE independently-written
+-- columns — `status='escalated'`, `escalation_user_task_key` (the completable pointer), and
+-- `escalation_question` — owned by DIFFERENT writers on DIFFERENT schedules:
+--   • `record-feature-escalation` (service task) persists `escalation_question` (pointer still NULL).
+--   • `pollFeatureEscalations` / `deriveFeatureEscalationPatch` (async poller) sets `status='escalated'`
+--     + denormalises `escalation_user_task_key` on the next pass, and clears the tuple when the task
+--     is gone — but only on the next pass.
+--   • the answer/complete operation (`answerFeatureEscalation`) clears the pointer + question eagerly.
+-- Because they are never written as one atomic tuple, a reader can observe a TORN interim state (e.g.
+-- `status=escalated` + pointer set + `question=null`) and the page renders a self-contradictory
+-- escalation — an "answer me" affordance (Abandon action, answer form) for a run with nothing to
+-- answer (observed on nwf#270).
+--
+-- Fix: derive the display-state, don't denormalise it, and FAIL CLOSED. `escalation_open` is a single
+-- write-time-projected signal — `1` iff ALL THREE columns agree the run is parked at an answerable
+-- escalation (`status='escalated'` AND `escalation_user_task_key` non-NULL AND `escalation_question`
+-- non-NULL), else `0`. The pages gate the escalation affordances on THIS conjunction instead of on
+-- `escalation_user_task_key` alone, so a torn tuple renders as NOT escalated rather than
+-- escalated-but-blank. It mirrors the existing `stage` / `list_bucket` display projections: maintained
+-- by the feature_runs gateway (app/feature.ts) from the pure `deriveEscalationOpen` helper (app/stage.ts)
+-- on every write — never hand-derived in SQL, the page, or a poller. Because the gateway reprojects on
+-- the answer operation's eager tuple-clear (which touches projection inputs), the affordance disappears
+-- WITHOUT waiting a poll pass.
+--
+-- Forward-only, additive (expand): nullable with no default, so pre-#272 rows grandfather in as NULL
+-- and never gate control flow. `backfillFeatureStages` (app/feature.ts) stamps rows whose
+-- `escalation_open` is still NULL once at boot — including a run parked at a LIVE escalation when this
+-- lands, which the poller would otherwise never re-write while it stays parked — and the gateway keeps
+-- every future write fresh. Numbered after the current highest prefix on origin/main (039); the runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE feature_runs ADD COLUMN escalation_open INTEGER;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.84.0",
+  "version": "0.85.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",

package/pages/feature.page.json

@@ -96,7 +96,7 @@
           {
             "label": "Abandon",
             "confirm": "Abandon this escalated task? The run gives up on it (no PR).",
-            "showWhenField": "escalation_user_task_key",
+            "showWhenField": "escalation_open",
             "action": {
               "path": "/app/api/actions/answer-escalation",
               "body": { "userTaskKey": "{{row.escalation_user_task_key}}", "resolution": "abandon" }
@@ -129,7 +129,7 @@
             { "field": "delivery_label", "label": "Delivery" }
           ],
           "form": {
-            "showWhenField": "escalation_user_task_key",
+            "showWhenField": "escalation_open",
             "title": "Answer escalation",
             "promptField": "escalation_question",
             "inputKey": "answer",

package/pages/overview.page.json

@@ -123,7 +123,7 @@
           {
             "label": "Abandon",
             "confirm": "Abandon this escalated task? The run gives up on it (no PR).",
-            "showWhenField": "escalation_user_task_key",
+            "showWhenField": "escalation_open",
             "action": {
               "path": "/app/api/actions/answer-escalation",
               "body": { "userTaskKey": "{{row.escalation_user_task_key}}", "resolution": "abandon" }
@@ -145,7 +145,7 @@
             { "field": "outcome", "label": "Outcome" }
           ],
           "form": {
-            "showWhenField": "escalation_user_task_key",
+            "showWhenField": "escalation_open",
             "title": "Answer escalation",
             "promptField": "escalation_question",
             "inputKey": "answer",

package/resources/processes/readiness-gate.bpmn

@@ -19,6 +19,9 @@
           <nano:extend name="version" type="string" optional="true" />
           <nano:extend name="conclusion" type="string" optional="true" />
           <nano:extend name="checkName" type="string" optional="true" />
+          <nano:extend name="capabilityRef" type="string" optional="true" />
+          <nano:extend name="package" type="string" optional="true" />
+          <nano:extend name="verifyCommand" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="ReadinessProbePoll" name="Readiness probe — poll policy">
           <nano:extend name="everyMs" type="integer" optional="true" />
@@ -42,10 +45,12 @@
         <nano:shape id="ReadinessProbeOut" name="Readiness probe — result">
           <nano:extend name="ready" type="boolean" />
           <nano:extend name="detail" type="string" optional="true" />
+          <nano:extend name="resolvedArtifact" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="ReadinessReady" name="readiness-ready message payload">
           <nano:extend name="ready" type="boolean" />
           <nano:extend name="detail" type="string" optional="true" />
+          <nano:extend name="resolvedArtifact" type="string" optional="true" />
         </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>

package/workers/readiness-probe/worker.test.ts

@@ -9,7 +9,7 @@ import { test } from "node:test";
 import { assert, assertEquals, assertRejects } from "#test-assert";
 import type { CommandResult, HttpResponse, ProbeExec, ReadinessProbe } from "../../app/readiness.ts";
 import { parseProbe } from "../../app/readiness.ts";
-import handler, { pollUntilReady, READINESS_READY_MESSAGE, readGateVars } from "./worker.ts";
+import handler, { pollUntilReady, READINESS_READY_MESSAGE, readGateVars, safeBind } from "./worker.ts";
 
 // A virtual clock: `now()` advances only when the loop's `wait(ms)` is called, so a never-ready
 // probe races to its deadline in zero real time (no setTimeout) and the test can never hang.
@@ -40,6 +40,40 @@ function execReturning(seq: Array<HttpResponse>): ProbeExec {
 const httpProbe = (poll: ReadinessProbe["poll"]): ReadinessProbe =>
   parseProbe({ kind: "http", target: "https://x/health", poll });
 
+test("safeBind: strips reserved keys (ready/detail) so a bind can only ADD outputs, never shadow the payload", () => {
+  const cleaned = safeBind({ resolvedArtifact: "@nanobpm/urban@0.54.0", ready: "false", detail: "spoofed" });
+  assertEquals(cleaned.resolvedArtifact, "@nanobpm/urban@0.54.0");
+  assertEquals("ready" in cleaned, false, "a bound 'ready' can never override the canonical payload");
+  assertEquals("detail" in cleaned, false, "a bound 'detail' can never override the canonical payload");
+  assertEquals(Object.keys(safeBind(undefined)).length, 0, "an absent bind yields an empty object");
+});
+
+test("pollUntilReady: a fallback that throws is caught, logged by class name (no leak), and stays not-ready", async () => {
+  const clock = fakeClock();
+  const seen: string[] = [];
+  let publishes = 0;
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 5, timeoutMs: 30, backoff: "fixed" }),
+    gateKey: "gate-fallback-throws",
+    exec: execReturning([{ status: 503, body: "" }]),
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async () => {
+      publishes += 1;
+    },
+    fallback: async () => {
+      throw new Error("boom at https://h/p?token=s3cr3t");
+    },
+    log: (msg) => seen.push(msg),
+  });
+  assert(!res.ready, "a throwing fallback keeps the not-ready outcome for the engine timer");
+  assertEquals(publishes, 0, "nothing is published when the fallback throws");
+  const all = seen.join("\n");
+  assert(all.includes("fallback error: Error"), "the fallback error is logged by class name");
+  assert(!all.includes("s3cr3t"), "the raw error message (with its secret) must not leak");
+});
+
 test("pollUntilReady: publishes readiness-ready once and returns ready when a probe goes green", async () => {
   const clock = fakeClock();
   const published: Array<{ detail: string }> = [];
@@ -59,6 +93,90 @@ test("pollUntilReady: publishes readiness-ready once and returns ready when a pr
   assertEquals(published.length, 1, "exactly one readiness message was published");
 });
 
+test("pollUntilReady: forwards a matcher's bind through publish into the message variables (#274 Gap B)", async () => {
+  // A capability probe resolves a version; its bind must flow through publish so the gate can surface
+  // resolvedArtifact as an output. The gh-api stub returns a release whose provenance carries #274.
+  const clock = fakeClock();
+  const published: Array<{ detail: string; bind?: Record<string, string> }> = [];
+  const payload = JSON.stringify([{ tag_name: "@nanobpm/urban@0.54.0", body: "## Provenance\n- #274\n" }]);
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(): Promise<CommandResult> {
+      return { code: 0, stdout: payload, stderr: "" };
+    },
+  };
+  const res = await pollUntilReady({
+    probe: parseProbe({
+      kind: "capability",
+      target: "github-releases:nanobpm/nano-ide",
+      match: { capabilityRef: "nano-ide#274", package: "@nanobpm/urban" },
+      poll: { everyMs: 5, timeoutMs: 5000, backoff: "fixed" },
+    }),
+    gateKey: "gate-cap",
+    exec,
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async (detail, bind) => {
+      published.push({ detail, bind });
+    },
+  });
+  assert(res.ready, "the capability edge resolved");
+  assertEquals(published.length, 1, "exactly one readiness message was published");
+  assertEquals(published[0]?.bind?.resolvedArtifact, "@nanobpm/urban@0.54.0", "the resolved artifact flowed through the bind");
+});
+
+test("pollUntilReady: the gated fallback fires ONCE at budget exhaustion and can still resolve+publish", async () => {
+  // Deterministic provenance never resolves (no matching release), so the loop exhausts its budget —
+  // the gate boundary. The fallback thunk then verifies empirically and publishes a bound version.
+  const clock = fakeClock();
+  const published: Array<{ bind?: Record<string, string> }> = [];
+  let fallbackCalls = 0;
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 5, timeoutMs: 30, backoff: "fixed" }),
+    gateKey: "gate-fallback",
+    exec: execReturning([{ status: 503, body: "" }]),
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async (_detail, bind) => {
+      published.push({ bind });
+    },
+    fallback: async () => {
+      fallbackCalls += 1;
+      return { ready: true, detail: "verified empirically", bind: { resolvedArtifact: "@nanobpm/urban@0.60.0" } };
+    },
+  });
+  assert(res.ready, "the boundary fallback resolved the edge");
+  assertEquals(fallbackCalls, 1, "the fallback fires exactly once, at the boundary — never per attempt");
+  assertEquals(published[0]?.bind?.resolvedArtifact, "@nanobpm/urban@0.60.0");
+});
+
+test("pollUntilReady: a fallback that does not resolve leaves the not-ready outcome for the engine timer", async () => {
+  const clock = fakeClock();
+  let publishes = 0;
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 5, timeoutMs: 30, backoff: "fixed" }),
+    gateKey: "gate-fallback-noop",
+    exec: execReturning([{ status: 503, body: "" }]),
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async () => {
+      publishes += 1;
+    },
+    fallback: async () => ({ ready: false, detail: "still nothing" }),
+  });
+  assert(!res.ready, "an inconclusive fallback keeps the wait bounded by the engine timer");
+  assertEquals(publishes, 0, "no readiness signal is published when the fallback does not resolve");
+  assert(
+    res.detail.includes("still nothing"),
+    "the inconclusive fallback's (redacted) diagnostic is surfaced in the returned detail, not discarded",
+  );
+});
+
 test("pollUntilReady: a never-green probe exhausts its budget and returns not-ready WITHOUT publishing", async () => {
   const clock = fakeClock();
   let publishes = 0;
@@ -79,6 +197,34 @@ test("pollUntilReady: a never-green probe exhausts its budget and returns not-re
   assert(clock.now() <= 100, "the loop stopped at (or before) its declared budget");
 });
 
+test("pollUntilReady: keeps probing up to the deadline — a flip-to-ready in the final backoff window is caught, not missed", async () => {
+  // everyMs 10, budget 25: three deterministic probes land at t=0,10,20. A full-backoff sleep from
+  // t=20 would jump to t=30 (past the 25ms bound) and stop probing early, missing a green at t=25 and
+  // forcing a spurious timeout escalation. The clamp keeps probing to the same bound the engine holds.
+  const clock = fakeClock();
+  let publishes = 0;
+  const exec = execReturning([
+    { status: 503, body: "" },
+    { status: 503, body: "" },
+    { status: 503, body: "" },
+    { status: 200, body: "ok" },
+  ]);
+  const res = await pollUntilReady({
+    probe: httpProbe({ everyMs: 10, timeoutMs: 25, backoff: "fixed" }),
+    gateKey: "gate-final-window",
+    exec,
+    env: {},
+    now: clock.now,
+    wait: clock.wait,
+    publish: async () => {
+      publishes += 1;
+    },
+  });
+  assert(res.ready, "the flip-to-ready inside the final backoff window was probed and caught");
+  assertEquals(publishes, 1, "the readiness signal was published exactly once");
+  assert(clock.now() <= 25, "the worker never probed past the engine-enforced deadline");
+});
+
 test("pollUntilReady: an I/O throw is caught and treated as not-ready (never rejects), and its raw message is not leaked", async () => {
   const clock = fakeClock();
   const seen: string[] = [];

package/workers/readiness-probe/worker.ts

@@ -16,6 +16,7 @@ import { readEnvOr } from "../../app/contracts.ts";
 import {
   DEFAULT_EVERY_MS,
   defaultProbeExec,
+  makeCapabilityFallback,
   nextDelay,
   normalizePoll,
   type ProbeExec,
@@ -40,6 +41,22 @@ export const READINESS_READY_MESSAGE = "readiness-ready";
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
+/** The canonical gate-payload keys the matcher's `bind` must never override. `bind` is the
+ * kind-agnostic emit primitive (#274 Gap B), but it flows from matcher output into both the
+ * `readiness-ready` message variables and the worker output — so a matcher that (accidentally or
+ * maliciously) binds `ready`/`detail` could shadow the canonical payload and break the gate
+ * contract. Strip them before spreading so a matcher can only ADD outputs, never overwrite the
+ * shape the gate correlates on. */
+const RESERVED_BIND_KEYS: ReadonlySet<string> = new Set(["ready", "detail"]);
+export function safeBind(bind?: Record<string, string>): Record<string, string> {
+  if (!bind) return {};
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(bind)) {
+    if (!RESERVED_BIND_KEYS.has(k)) out[k] = v;
+  }
+  return out;
+}
+
 /** The effective poll cadence: the descriptor's values, with `everyMs` defaulting through the env
  * contract (`NANO_READINESS_POLL_EVERY_MS`) when the descriptor omits it, then the built-in
  * defaults/clamps in {@link normalizePoll}. Reads the env value from the injected `env` (not the
@@ -64,7 +81,12 @@ export async function pollUntilReady(deps: {
   env: Record<string, string | undefined>;
   now: () => number;
   wait: (ms: number) => Promise<void>;
-  publish: (detail: string) => Promise<void>;
+  publish: (detail: string, bind?: Record<string, string>) => Promise<void>;
+  /** An OPTIONAL last-attempt thunk run ONCE at the gate boundary (local budget exhausted) before
+   * giving up — the seam for the gated empirical fallback (decision 5). A ready result is published
+   * (with its bind) and returned; anything else keeps the not-ready outcome so the engine timer
+   * bounds the wait as usual. Kept generic so the loop stays kind-agnostic. */
+  fallback?: () => Promise<ProbeResult | null>;
   log?: (msg: string) => void;
 }): Promise<ProbeResult> {
   const poll = effectivePoll(deps.probe.poll, deps.env);
@@ -84,15 +106,46 @@ export async function pollUntilReady(deps: {
     }));
     deps.log?.(`readiness probe ${label} attempt ${attempt + 1}: ${res.detail}`);
     if (res.ready) {
-      await deps.publish(res.detail);
+      await deps.publish(res.detail, res.bind);
       return res;
     }
     attempt += 1;
-    const wait = nextDelay(attempt, poll);
-    if (deps.now() + wait >= deadline) {
-      return { ready: false, detail: "probe budget exhausted; engine timer bounds the wait" };
+    const remaining = deadline - deps.now();
+    if (remaining <= 0) {
+      // The gate boundary: the deterministic poll is exhausted. Give the gated fallback (if any) ONE
+      // empirical attempt before conceding to the engine timer — a capability provenance under-reports
+      // can still resolve here, exactly once, never per unrelated release.
+      const settled = deps.fallback
+        ? await deps.fallback().catch((err) => {
+            // Never swallow a fallback failure silently — it degrades to "not ready" and is hard
+            // to diagnose. Log only the error class name (no message), consistent with the main
+            // probeOnce error handling, so a target URL/token in the message never leaks.
+            deps.log?.(
+              `readiness probe ${label} fallback error: ${err instanceof Error ? err.name : "Error"}`,
+            );
+            return null;
+          })
+        : null;
+      if (settled?.ready) {
+        deps.log?.(`readiness probe ${label} fallback: ${settled.detail}`);
+        await deps.publish(settled.detail, settled.bind);
+        return settled;
+      }
+      // Surface the fallback's (already-redacted) diagnostic when one ran and reported not-ready, so a
+      // timeout escalation is actionable instead of a generic "budget exhausted". `settled` is null when
+      // there is no fallback or it threw (logged above), in which case only the generic detail applies.
+      return {
+        ready: false,
+        detail: settled
+          ? `probe budget exhausted; engine timer bounds the wait (fallback: ${settled.detail})`
+          : "probe budget exhausted; engine timer bounds the wait",
+      };
     }
-    await deps.wait(wait);
+    // Clamp the sleep to the time left until `deadline` so the worker keeps probing right up to the
+    // SAME bound the engine timer enforces. Sleeping a full `nextDelay` unconditionally would stop
+    // probing up to one backoff early — a window where readiness could flip to ready but no
+    // `readiness-ready` message is published, forcing a spurious timeout escalation.
+    await deps.wait(Math.min(nextDelay(attempt, poll), remaining));
   }
 }
 
@@ -123,24 +176,31 @@ export function readGateVars(vars: { gateKey?: unknown; probeTimeout?: unknown }
 const handler: AppJobHandler<In, Out> = async (job, app) => {
   const probe = parseProbe(job.variables.probe);
   const { gateKey, probeTimeout } = readGateVars(job.variables);
+  const exec = defaultProbeExec();
   const result = await pollUntilReady({
     probe,
     gateKey,
     probeTimeout,
-    exec: defaultProbeExec(),
+    exec,
     env: process.env,
     now: () => Date.now(),
     wait: sleep,
-    publish: async (detail) => {
+    // The gated empirical fallback (decision 5) — a no-op for every kind but a `capability` probe
+    // that declares a `verifyCommand`, so the deterministic provenance lookup stays the default.
+    fallback: makeCapabilityFallback(probe, exec, process.env),
+    publish: async (detail, bind) => {
       await app.engine.publishMessage({
         name: READINESS_READY_MESSAGE,
         correlationKey: gateKey,
-        variables: { ready: true, detail },
+        // `bind` is the kind-agnostic emit primitive (#274 Gap B): forward whatever the matcher
+        // discovered (e.g. `resolvedArtifact`) into the message so the gate surfaces it as output.
+        // Reserved keys are stripped so a bind can only ADD outputs, never shadow `ready`/`detail`.
+        variables: { ready: true, detail, ...safeBind(bind) },
       });
     },
     log: (msg) => app.log.info(msg),
   });
-  return { ready: result.ready, detail: result.detail };
+  return { ready: result.ready, detail: result.detail, ...safeBind(result.bind) };
 };
 
 export default handler;