@nanobpm/nano-workforce 0.83.0 → 0.85.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Features
+
+* **ui:** render narrative epic-detail sections with urban prose renderer ([#270](https://github.com/nanobpm/nano-workforce/issues/270)) ([#271](https://github.com/nanobpm/nano-workforce/issues/271)) ([38c67a4](https://github.com/nanobpm/nano-workforce/commit/38c67a479693730b9a79f3a7b0f88ef574d3a456)), closes [nano-ide#274](https://github.com/nano-ide/issues/274) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [274/#275](https://github.com/nanobpm/nano-workforce/issues/275)
+
 # [0.83.0](https://github.com/nanobpm/nano-workforce/compare/v0.82.1...v0.83.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);