@nanobpm/nano-workforce 0.80.0 → 0.82.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.82.0](https://github.com/nanobpm/nano-workforce/compare/v0.81.0...v0.82.0) (2026-08-17)
+
+
+### Features
+
+* reify epic domain lifecycle as derived plans.epic_phase ([#261](https://github.com/nanobpm/nano-workforce/issues/261)) ([#265](https://github.com/nanobpm/nano-workforce/issues/265)) ([4cc9dee](https://github.com/nanobpm/nano-workforce/commit/4cc9deee86b800206d264d96269e6a98e8753883)), closes [#266](https://github.com/nanobpm/nano-workforce/issues/266) [nwf#245](https://github.com/nwf/issues/245) [nano-ide#254](https://github.com/nano-ide/issues/254)
+
+# [0.81.0](https://github.com/nanobpm/nano-workforce/compare/v0.80.0...v0.81.0) (2026-08-17)
+
+
+### Features
+
+* durable artifact-readiness wait-gate primitive (ADR 0001 §2) ([#260](https://github.com/nanobpm/nano-workforce/issues/260)) ([e787488](https://github.com/nanobpm/nano-workforce/commit/e787488c074b9e4e44946a4144b814b34caffe57)), closes [#258](https://github.com/nanobpm/nano-workforce/issues/258) [#259](https://github.com/nanobpm/nano-workforce/issues/259) [#258](https://github.com/nanobpm/nano-workforce/issues/258)
+
 # [0.80.0](https://github.com/nanobpm/nano-workforce/compare/v0.79.0...v0.80.0) (2026-08-17)
 
 

package/SPEC.md

@@ -530,6 +530,17 @@ History: done/failed/abandoned) with a `plan_tasks` child grid showing each task
 status and the PR it produced (`pr_key` cross-references the Pull requests grid for
 convergence status).
 
+**Epic domain phase** (issue #261): `plans.status` only distinguishes the process-instance
+terminal (`dispatched` = "fan-out job done"), not the epic's *domain* lifecycle. The read model
+therefore also carries a derived, display-only `plans.epic_phase` — **Planning → Reviewing →
+Implementing (wave n/t) → Trial merging → Finalizing → Dispatched** — projected at write time from
+`plan-fanout.bpmn`'s named activities via each spine worker's BPMN element id (`app/epicPhase.ts`,
+the single binding; nwf is the first consumer of the urban phase-projection primitive, nano-ide#266).
+The `Implementing` band is wave-labelled from the levelize records (`plan_tasks` waves). The epic /
+epic-detail pages surface it as a **Phase** column. It never gates control flow (that stays driven by
+the process `currentWave`/`waveCount`/`gate_wave`); a post-dispatch cross-instance rollup into
+Converging/Merging is a later seam (nwf#245 / nano-ide#254).
+
 ### 13.1 Dependency waves + merge barrier (issues #20, #26, release-notes-concierge)
 
 The flat `implement → record-results` shape above evolved into a **wave loop**. The

package/app/contracts.ts

@@ -208,6 +208,22 @@ export const ENV_CONTRACTS = {
       "SLA timeout for an agent (service) task before its boundary timer fires and the PR escalates for human attention (ISO-8601 duration). A malformed value falls back to the default.",
     default: "PT2H",
   },
+  NANO_READINESS_POLL_TIMEOUT: {
+    category: "env",
+    name: "NANO_READINESS_POLL_TIMEOUT",
+    owner: "app/readiness.ts",
+    semantics:
+      "Default bounded timeout (FEEL/ISO-8601 duration) for a ReadinessProbe wait-gate when the probe descriptor declares no poll.timeoutMs. The gate's event-based-gateway timer arm fires after it and escalates, so a probe that never goes green can never wedge a plan. A malformed value falls back to the default.",
+    default: "PT30M",
+  },
+  NANO_READINESS_POLL_EVERY_MS: {
+    category: "env",
+    name: "NANO_READINESS_POLL_EVERY_MS",
+    owner: "workers/readiness-probe/worker.ts",
+    semantics:
+      "Default interval in milliseconds between ReadinessProbe attempts when the probe descriptor declares no poll.everyMs.",
+    default: "15000",
+  },
   NANO_APP_DB_URL: {
     category: "env",
     name: "NANO_APP_DB_URL",
@@ -259,6 +275,13 @@ export const ENV_CONTRACTS = {
 /** The set of declared config-key names — the single typed vocabulary of env keys. */
 export type EnvKey = keyof typeof ENV_CONTRACTS;
 
+/** Whether `name` is a declared {@link EnvKey}. A runtime-narrowing guard so a value carried in as
+ * a plain string (e.g. a probe descriptor's `credentialEnv`) can be validated against the ONE
+ * schema before it is read through {@link readEnv} — an undeclared key is rejected, never read. */
+export function isEnvKey(name: string): name is EnvKey {
+  return Object.hasOwn(ENV_CONTRACTS, name);
+}
+
 /** Every declared env contract, widened to {@link EnvContract} (assignment-widening — no `as`), so
  * callers can read the optional `default`/`rejectedSynonyms`/`secret` fields on any entry. */
 export function envContracts(): EnvContract[] {

package/app/epicPhase.test.ts

@@ -0,0 +1,62 @@
+// Read-model derivation test for the epic domain phase (issue #261). `deriveEpicPhase` /
+// `implementingPhase` are the single source of truth for the write-time projection each spine
+// worker stamps onto `plans.epic_phase`. The projection binds structurally to plan-fanout.bpmn's
+// named activities via the job's BPMN element id (mirroring the urban #266 phase primitive), so the
+// epic view can show WHICH phase an epic is in — not only the process-instance terminal status.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { deriveEpicPhase, EPIC_PHASE, implementingPhase } from "./epicPhase.ts";
+
+test("deriveEpicPhase maps each spine element to its domain phase", () => {
+  // Planning genesis + hand-off into Reviewing when the plan is recorded.
+  assertEquals(deriveEpicPhase("plan"), EPIC_PHASE.PLANNING);
+  assertEquals(deriveEpicPhase("ensure-base-branch"), EPIC_PHASE.PLANNING);
+  assertEquals(deriveEpicPhase("record-plan"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("review-plan"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("record-plan-review"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("plan-review-decision"), EPIC_PHASE.REVIEWING);
+  // Trial-merge band.
+  assertEquals(deriveEpicPhase("trial-merge"), EPIC_PHASE.TRIAL_MERGING);
+  assertEquals(deriveEpicPhase("record-trial-merge"), EPIC_PHASE.TRIAL_MERGING);
+  assertEquals(deriveEpicPhase("trial-merge-decision"), EPIC_PHASE.TRIAL_MERGING);
+  assertEquals(deriveEpicPhase("resolve-trial-attention"), EPIC_PHASE.TRIAL_MERGING);
+  // Finalize step's lasting result is the "Fleet dispatched" terminal.
+  assertEquals(deriveEpicPhase("record-results"), EPIC_PHASE.DISPATCHED);
+});
+
+test("deriveEpicPhase wave-labels the Implementing band from the levelize records", () => {
+  // select-wave / record-wave / the implement MI + wait-wave-merged all read as Implementing,
+  // labelled with the 1-based wave from the wave/levelize records (0-based `current`).
+  assertEquals(
+    deriveEpicPhase("select-wave", { current: 0, total: 3 }),
+    "Implementing (wave 1/3)",
+  );
+  assertEquals(
+    deriveEpicPhase("record-wave", { current: 2, total: 3 }),
+    "Implementing (wave 3/3)",
+  );
+  assertEquals(
+    deriveEpicPhase("wait-wave-merged", { current: 1, total: 3 }),
+    "Implementing (wave 2/3)",
+  );
+  assertEquals(deriveEpicPhase("implement-task", { current: 0, total: 1 }), "Implementing (wave 1/1)");
+});
+
+test("deriveEpicPhase returns null for a non-spine element so a stray write never clobbers", () => {
+  assertEquals(deriveEpicPhase(undefined), null);
+  assertEquals(deriveEpicPhase(null), null);
+  assertEquals(deriveEpicPhase(""), null);
+  assertEquals(deriveEpicPhase("some-unrelated-element"), null);
+});
+
+test("implementingPhase clamps the 1-based label to the total and degrades gracefully", () => {
+  assertEquals(implementingPhase(0, 2), "Implementing (wave 1/2)");
+  // A `current` at/over the last index (record-wave pins current_wave to waveCount-1 on the final
+  // wave) never reads past n/n.
+  assertEquals(implementingPhase(5, 3), "Implementing (wave 3/3)");
+  // Unusable wave numbers (taskless plan / NaN counter) degrade to a bare Implementing — never
+  // "wave NaN/…".
+  assertEquals(implementingPhase(0, 0), "Implementing");
+  assertEquals(implementingPhase(undefined, undefined), "Implementing");
+  assertEquals(implementingPhase("x", "y"), "Implementing");
+});

package/app/epicPhase.ts

@@ -0,0 +1,125 @@
+// app/epicPhase.ts — reify the epic's own domain lifecycle as a derived `epic_phase` (issue #261).
+//
+// `plans.status` only distinguishes `planning` / `dispatched` / `done` / `failed` / `abandoned` —
+// and `dispatched` is the `plan-fanout.bpmn` PROCESS-INSTANCE terminal ("fan-out job done"), not the
+// epic's domain phase. `plan-fanout.bpmn` already models the rich lifecycle as named activities
+// (Ensure base branch → Plan → Review plan → Select wave → Implement task → Trial merge → Finalize
+// → "Fleet dispatched"); this module reifies that lifecycle as a stored, display-only projection so
+// the epic view can show which phase the epic is in.
+//
+// Convention over declaration: the phases ARE the activities plan-fanout.bpmn already names. Each
+// spine worker derives its projection from its OWN BPMN element id (`job.elementId`) — no annotation
+// map on the model, no second reconciliation pass — mirroring the urban structural phase-projection
+// primitive (nano-ide#266), which derives the phase from the furthest element reached in
+// write-provenance. This module is the single binding (nwf is #266's first consumer).
+//
+// Write-time projection: because the phase only advances when a worker writes, each spine worker
+// stamps the phase the epic is ENTERING as a result of its write — the write points ARE the phase
+// boundaries. Two structural defaults are coarsened where the raw activity label would mislead
+// (documented on `ELEMENT_PHASE` below): `select-wave` reads as `Implementing (wave n/t)` because it
+// dispatches and durably marks the (write-silent) `implement` multi-instance subProcess, and
+// `record-results` reads as the `Dispatched` terminal ("Fleet dispatched").
+//
+// Cross-instance rollup (later): post-dispatch, the epic's effective phase extends into the
+// convergence/merge loops carried on separate top-level instances correlated by lineage
+// (`rootRequestKey`, nwf#245 / nano-ide#254). Once #266's Tier-2 rollup lands, `epic_phase` can
+// advance past `Dispatched` into Converging/Merging with no new wiring here — the seam is this
+// module's derivation staying the single source.
+
+/** The epic's domain phases — the vocabulary the derivation projects onto `plans.epic_phase`.
+ *  Shared with the feature-view stage vocabulary (nwf#254), which uses the same stored-projection
+ *  pattern. `Implementing` is wave-labelled at derivation time (see {@link implementingPhase}). */
+export const EPIC_PHASE = {
+  PLANNING: "Planning",
+  REVIEWING: "Reviewing",
+  IMPLEMENTING: "Implementing",
+  TRIAL_MERGING: "Trial merging",
+  FINALIZING: "Finalizing",
+  DISPATCHED: "Dispatched",
+} as const;
+
+/** Coerce a wave index/count to a non-negative integer, or null when it isn't one. Mirrors the
+ *  `toWave` coercion the wave workers already apply, so a NaN/absent counter degrades to an
+ *  unlabelled `Implementing` rather than emitting `wave NaN/…`. */
+const toWave = (v: unknown): number | null => {
+  const n = Math.trunc(Number(v));
+  return Number.isFinite(n) && n >= 0 ? n : null;
+};
+
+/**
+ * `Implementing (wave n/t)` — special-cased from the wave/levelize records (`plan_tasks` waves),
+ * NOT the raw multi-instance counter. `current` is the 0-based wave index carried on the process
+ * (`currentWave` / the projected `current_wave`); the label is 1-based and clamped to `total` so a
+ * final wave reads `n/n`. Falls back to a bare `Implementing` when the wave numbers aren't usable
+ * (e.g. a taskless plan with `total` 0), so the phase never renders `wave NaN`.
+ */
+export function implementingPhase(current: unknown, total: unknown): string {
+  const t = toWave(total);
+  const c = toWave(current);
+  if (t !== null && t > 0 && c !== null) {
+    const n = Math.min(c + 1, t);
+    return `${EPIC_PHASE.IMPLEMENTING} (wave ${n}/${t})`;
+  }
+  return EPIC_PHASE.IMPLEMENTING;
+}
+
+/**
+ * Structural binding: `plan-fanout.bpmn` element id → the domain phase the epic is IN while that
+ * element (or the write-silent agent step it hands off to) runs. Complete over the epic's spine, so
+ * the projection is derivable from provenance alone (the urban #266 semantics). Two entries are
+ * deliberately COARSENED from their raw activity label because the structural default misleads:
+ *   • `record-plan` ("Record plan & levelize") → Reviewing: recording the plan hands the epic to the
+ *     `review-plan` agent, so the review phase should already read while that (write-silent) agent
+ *     runs. `record-plan-review` re-affirms Reviewing on each round/escalation.
+ *   • `select-wave` ("Select wave") → Implementing: it dispatches the wave and is the last host write
+ *     before the write-silent `implement` MI, so it durably marks the implementation phase for the
+ *     wave it launches (wave-labelled via {@link implementingPhase} at the call site).
+ *   • `record-results` ("Finalize plan") → Dispatched: the finalize step's lasting result is the
+ *     "Fleet dispatched" terminal end event.
+ * `record-wave`'s next phase is data-dependent (trial-merge vs. next wave vs. finalize), so it is
+ * resolved at its call site rather than from the element id alone; its structural fallback here is
+ * the wave it just landed.
+ */
+const ELEMENT_PHASE: Readonly<Record<string, string>> = {
+  "ensure-base-branch": EPIC_PHASE.PLANNING,
+  "plan": EPIC_PHASE.PLANNING,
+  "record-plan": EPIC_PHASE.REVIEWING,
+  "review-plan": EPIC_PHASE.REVIEWING,
+  "record-plan-review": EPIC_PHASE.REVIEWING,
+  "plan-review-decision": EPIC_PHASE.REVIEWING,
+  "select-wave": EPIC_PHASE.IMPLEMENTING,
+  "implement": EPIC_PHASE.IMPLEMENTING,
+  "implement-task": EPIC_PHASE.IMPLEMENTING,
+  "feature-escalation": EPIC_PHASE.IMPLEMENTING,
+  "record-wave": EPIC_PHASE.IMPLEMENTING,
+  "wait-wave-merged": EPIC_PHASE.IMPLEMENTING,
+  "trial-merge": EPIC_PHASE.TRIAL_MERGING,
+  "record-trial-merge": EPIC_PHASE.TRIAL_MERGING,
+  "trial-merge-decision": EPIC_PHASE.TRIAL_MERGING,
+  "resolve-trial-attention": EPIC_PHASE.TRIAL_MERGING,
+  "record-results": EPIC_PHASE.DISPATCHED,
+};
+
+/** Optional wave context for a wave-bearing phase, sourced from the wave/levelize records. */
+export interface WaveContext {
+  current?: unknown;
+  total?: unknown;
+}
+
+/**
+ * Derive the epic phase for a spine element from its BPMN element id, or `null` when the element
+ * doesn't mark a phase — so a non-spine write (e.g. a poller reconcile pass) never clobbers
+ * `epic_phase`. A wave-bearing phase (`Implementing`) is wave-labelled from {@link WaveContext} when
+ * supplied. This is the single structural deriver; workers pass `job.elementId` so the phase name is
+ * never hardcoded at the call site.
+ */
+export function deriveEpicPhase(
+  elementId: string | undefined | null,
+  wave?: WaveContext,
+): string | null {
+  if (!elementId) return null;
+  const base = ELEMENT_PHASE[elementId];
+  if (base === undefined) return null;
+  if (base === EPIC_PHASE.IMPLEMENTING) return implementingPhase(wave?.current, wave?.total);
+  return base;
+}

package/app/plan.ts

@@ -11,6 +11,7 @@
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { EPIC_PHASE } from "./epicPhase.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
 import { coalesceTitle, ensureBaseBranch, fetchDefaultBranch, fetchIssueTitle } from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
@@ -82,6 +83,12 @@ export interface Plan {
   // in app/service.ts); `delivery_label` is the human rollup for the epic detail view. Display-only.
   delivery: string | null;
   delivery_label: string | null;
+  // Derived epic domain phase (038_plan_epic_phase.sql, #261): the epic's own lifecycle phase —
+  // Planning / Reviewing / Implementing (wave n/t) / Trial merging / Finalizing / Dispatched —
+  // projected at write time from plan-fanout.bpmn's named activities (app/epicPhase.ts), so the epic
+  // view can show which phase the epic is IN rather than only the process-instance terminal status.
+  // Display-only; NULL until the lifecycle first stamps it (grandfathers pre-#261 rows).
+  epic_phase: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -436,6 +443,9 @@ export async function startPlan(
       issue_url: parsed.url,
       title,
       outcome: null,
+      // Genesis of the domain lifecycle (#261): the epic re-enters Planning. Cleared of any stale
+      // terminal phase from the prior run so the re-plan reads correctly from the first pass.
+      epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
       updated_at: ts,
@@ -449,6 +459,8 @@ export async function startPlan(
       title,
       status: "planning",
       task_count: 0,
+      // Genesis of the domain lifecycle (#261): a fresh epic starts in Planning.
+      epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
       created_at: ts,

package/app/readiness.test.ts

@@ -0,0 +1,300 @@
+// Unit coverage for the ReadinessProbe core (app/readiness.ts, issue #258 / ADR 0001 §2).
+//
+// The gate's engine model is proven end-to-end in e2e/readiness-gate.e2e.ts; these tests pin the
+// pure surface: descriptor parse/validation, each kind's matcher, the injectable `probeOnce`
+// dispatch (no network / subprocess), backoff, the ms→ISO timeout derivation, and log redaction.
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects, assertStringIncludes, assertThrows } from "#test-assert";
+import {
+  type CommandResult,
+  DEFAULT_ATTEMPT_TIMEOUT_MS,
+  DEFAULT_EVERY_MS,
+  DEFAULT_TIMEOUT_MS,
+  defaultProbeExec,
+  type HttpResponse,
+  MAX_EVERY_MS,
+  matchCommand,
+  matchGithubCheck,
+  matchHttp,
+  matchNpm,
+  msToIsoDuration,
+  nextDelay,
+  normalizePoll,
+  parseProbe,
+  parseRepoRef,
+  probeBudgetMs,
+  probeOnce,
+  type ProbeExec,
+  readinessTimeout,
+  readinessTimeoutMs,
+  redactString,
+  redactTarget,
+} from "./readiness.ts";
+
+// A ProbeExec stub: canned http/command responses, capturing the last command it was asked to run.
+function stubExec(opts: { http?: HttpResponse; command?: CommandResult; capture?: { cmd?: string; headers?: Record<string, string> } }): ProbeExec {
+  return {
+    async httpGet(_url, headers) {
+      if (opts.capture) opts.capture.headers = headers;
+      return opts.http ?? { status: 0, body: "" };
+    },
+    async run(command) {
+      if (opts.capture) opts.capture.cmd = command;
+      return opts.command ?? { code: 0, stdout: "", stderr: "" };
+    },
+  };
+}
+
+// ── parseProbe ──────────────────────────────────────────────────────────────────────────────
+test("parseProbe: accepts a minimal http probe and defaults onTimeout to escalate", () => {
+  const p = parseProbe({ kind: "http", target: "https://x/health" });
+  assertEquals(p.kind, "http");
+  assertEquals(p.target, "https://x/health");
+  assertEquals(p.onTimeout, "escalate");
+});
+
+test("parseProbe: rejects an unknown kind", () => {
+  assertThrows(() => parseProbe({ kind: "oci", target: "img:tag" }), Error, "unknown kind");
+});
+
+test("parseProbe: rejects a blank target", () => {
+  assertThrows(() => parseProbe({ kind: "command", target: "  " }), Error, "'target' is required");
+});
+
+test("parseProbe: rejects an invalid onTimeout", () => {
+  assertThrows(() => parseProbe({ kind: "http", target: "x", onTimeout: "retry" }), Error, "invalid onTimeout");
+});
+
+test("parseProbe: rejects an invalid poll.backoff (a malformed probe must fail loudly, never silently default)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "http", target: "x", poll: { backoff: "linear" } }),
+    Error,
+    "invalid backoff",
+  );
+});
+
+test("parseProbe: rejects an undeclared credentialEnv (a probe must never inline a secret)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "http", target: "x", credentialEnv: "MY_SECRET" }),
+    Error,
+    "not a declared env-contract key",
+  );
+});
+
+test("parseProbe: rejects a credentialEnv on a non-http kind (a subprocess probe never consumes it)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "github-check", target: "o/r@abc", credentialEnv: "GITHUB_TOKEN" }),
+    Error,
+    "only supported for the 'http' kind",
+  );
+});
+
+test("parseProbe: accepts a declared credentialEnv (http) and parses nested match/poll", () => {
+  const p = parseProbe({
+    kind: "http",
+    target: "https://x/health",
+    credentialEnv: "GITHUB_TOKEN",
+    match: { status: 200, checkName: "build" },
+    poll: { everyMs: 1000, timeoutMs: 60000, backoff: "fixed" },
+  });
+  assertEquals(p.credentialEnv, "GITHUB_TOKEN");
+  assertEquals(p.match?.checkName, "build");
+  assertEquals(p.poll?.backoff, "fixed");
+});
+
+// ── matchers ────────────────────────────────────────────────────────────────────────────────
+test("matchHttp: any 2xx is ready by default; a 503 is not", () => {
+  assert(matchHttp(undefined, { status: 204, body: "" }).ready);
+  assert(!matchHttp(undefined, { status: 503, body: "" }).ready);
+});
+
+test("matchHttp: an explicit status + bodyIncludes are both required", () => {
+  const m = { status: 200, bodyIncludes: "OK" };
+  assert(matchHttp(m, { status: 200, body: "all OK here" }).ready);
+  assert(!matchHttp(m, { status: 200, body: "degraded" }).ready);
+  assert(!matchHttp(m, { status: 201, body: "OK" }).ready);
+});
+
+test("matchCommand: exit 0 is ready by default; stdoutIncludes narrows it", () => {
+  assert(matchCommand(undefined, { code: 0, stdout: "", stderr: "" }).ready);
+  assert(!matchCommand(undefined, { code: 1, stdout: "", stderr: "" }).ready);
+  assert(matchCommand({ stdoutIncludes: "ready" }, { code: 0, stdout: "svc ready", stderr: "" }).ready);
+  assert(!matchCommand({ stdoutIncludes: "ready" }, { code: 0, stdout: "starting", stderr: "" }).ready);
+});
+
+test("matchNpm: a printed version means published; a failed view is not-ready", () => {
+  assert(matchNpm(undefined, "pkg@1.2.3", { code: 0, stdout: "1.2.3\n", stderr: "" }).ready);
+  assert(!matchNpm(undefined, "pkg@1.2.3", { code: 1, stdout: "", stderr: "E404" }).ready);
+  assert(!matchNpm(undefined, "pkg@1.2.3", { code: 0, stdout: "", stderr: "" }).ready);
+});
+
+test("matchNpm: the version in pkg@version must match the printed version", () => {
+  assert(!matchNpm(undefined, "pkg@2.0.0", { code: 0, stdout: "1.9.9", stderr: "" }).ready);
+  assert(matchNpm(undefined, "pkg@2.0.0", { code: 0, stdout: "2.0.0", stderr: "" }).ready);
+});
+
+test("matchGithubCheck: all runs must be completed+success; a pending run is not-ready", () => {
+  const green = { check_runs: [{ name: "build", status: "completed", conclusion: "success" }] };
+  const pending = { check_runs: [{ name: "build", status: "in_progress", conclusion: "" }] };
+  assert(matchGithubCheck(undefined, green).ready);
+  assert(!matchGithubCheck(undefined, pending).ready);
+  assert(!matchGithubCheck(undefined, { check_runs: [] }).ready);
+});
+
+test("matchGithubCheck: checkName restricts the predicate to that run", () => {
+  const payload = {
+    check_runs: [
+      { name: "build", status: "completed", conclusion: "success" },
+      { name: "flaky", status: "completed", conclusion: "failure" },
+    ],
+  };
+  assert(matchGithubCheck({ checkName: "build" }, payload).ready);
+  assert(!matchGithubCheck({ checkName: "flaky" }, payload).ready);
+  assert(!matchGithubCheck({ checkName: "missing" }, payload).ready);
+});
+
+// ── probeOnce dispatch (injected exec — no I/O) ───────────────────────────────────────────────
+test("probeOnce http: injects a Bearer credential from the declared env-contract, redacting nothing into the target", async () => {
+  const cap: { headers?: Record<string, string> } = {};
+  const exec = stubExec({ http: { status: 200, body: "ok" }, capture: cap });
+  const p = parseProbe({ kind: "http", target: "https://x/health", credentialEnv: "GITHUB_TOKEN" });
+  const res = await probeOnce(p, exec, { GITHUB_TOKEN: "tkn" });
+  assert(res.ready);
+  assertEquals(cap.headers?.authorization, "Bearer tkn");
+});
+
+test("probeOnce npm: builds a quoted `npm view … version` command", async () => {
+  const cap: { cmd?: string } = {};
+  const exec = stubExec({ command: { code: 0, stdout: "1.0.0", stderr: "" }, capture: cap });
+  const res = await probeOnce(parseProbe({ kind: "npm", target: "@scope/pkg@1.0.0" }), exec, {});
+  assert(res.ready);
+  assertStringIncludes(cap.cmd ?? "", "npm view '@scope/pkg@1.0.0' version");
+});
+
+test("probeOnce github-check: parses gh api JSON and requires success", async () => {
+  const cap: { cmd?: string } = {};
+  const exec = stubExec({
+    command: { code: 0, stdout: JSON.stringify({ check_runs: [{ name: "ci", status: "completed", conclusion: "success" }] }), stderr: "" },
+    capture: cap,
+  });
+  const res = await probeOnce(parseProbe({ kind: "github-check", target: "o/r@main" }), exec, {});
+  assert(res.ready);
+  assertStringIncludes(cap.cmd ?? "", "repos/o/r/commits/main/check-runs");
+});
+
+test("probeOnce github-check: a failed gh api call is not-ready (never throws)", async () => {
+  const exec = stubExec({ command: { code: 1, stdout: "", stderr: "not found" } });
+  const res = await probeOnce(parseProbe({ kind: "github-check", target: "o/r@main" }), exec, {});
+  assert(!res.ready);
+});
+
+// ── backoff + poll normalisation ──────────────────────────────────────────────────────────────
+test("normalizePoll: fills defaults and clamps everyMs to the ceiling", () => {
+  const d = normalizePoll(undefined);
+  assertEquals(d.everyMs, DEFAULT_EVERY_MS);
+  assertEquals(d.timeoutMs, DEFAULT_TIMEOUT_MS);
+  assertEquals(d.backoff, "exponential");
+  assertEquals(normalizePoll({ everyMs: 10 * 60_000 }).everyMs, MAX_EVERY_MS);
+});
+
+test("nextDelay: fixed returns everyMs; exponential doubles and clamps", () => {
+  const fixed = normalizePoll({ everyMs: 1000, backoff: "fixed" });
+  assertEquals(nextDelay(1, fixed), 1000);
+  assertEquals(nextDelay(5, fixed), 1000);
+  const exp = normalizePoll({ everyMs: 1000, backoff: "exponential" });
+  assertEquals(nextDelay(1, exp), 1000);
+  assertEquals(nextDelay(3, exp), 4000);
+  assertEquals(nextDelay(30, exp), MAX_EVERY_MS);
+});
+
+// ── timeout derivation ────────────────────────────────────────────────────────────────────────
+test("msToIsoDuration: rounds up to whole seconds, never zero", () => {
+  assertEquals(msToIsoDuration(1000), "PT1S");
+  assertEquals(msToIsoDuration(1500), "PT2S");
+  assertEquals(msToIsoDuration(1), "PT1S");
+});
+
+test("readinessTimeout: derives from poll.timeoutMs, else the env default, else PT30M", () => {
+  assertEquals(readinessTimeout(parseProbe({ kind: "http", target: "x", poll: { timeoutMs: 60000 } }), {}), "PT60S");
+  assertEquals(readinessTimeout(parseProbe({ kind: "http", target: "x" }), {}), "PT30M");
+  assertEquals(
+    readinessTimeout(parseProbe({ kind: "http", target: "x" }), { NANO_READINESS_POLL_TIMEOUT: "PT5M" }),
+    "PT5M",
+  );
+});
+
+test("readinessTimeoutMs: the ms twin of readinessTimeout — same precedence, no drift with the gate timer", () => {
+  // Declared budget is taken verbatim in ms (the gate rounds it up to whole seconds for its ISO timer).
+  assertEquals(readinessTimeoutMs(parseProbe({ kind: "http", target: "x", poll: { timeoutMs: 60000 } }), {}), 60000);
+  // Omitted + no env → the built-in default (30m), matching readinessTimeout's PT30M.
+  assertEquals(readinessTimeoutMs(parseProbe({ kind: "http", target: "x" }), {}), 1_800_000);
+  // Omitted + env → the env budget in ms. Regression: this used to fall back to the hard-coded 30m,
+  // stranding the worker while the gate timer waited the full env budget.
+  assertEquals(
+    readinessTimeoutMs(parseProbe({ kind: "http", target: "x" }), { NANO_READINESS_POLL_TIMEOUT: "PT2H" }),
+    7_200_000,
+  );
+});
+
+test("probeBudgetMs: prefers the seeded probeTimeout (the gate timer's bound), falling back to the env twin", () => {
+  const probe = parseProbe({ kind: "http", target: "x" });
+  // The seeded probeTimeout wins over the ambient env — binding worker and engine to ONE per-instance
+  // value: a stale env can't shorten the worker while the engine timer waits the seeded budget.
+  assertEquals(probeBudgetMs("PT45M", probe, { NANO_READINESS_POLL_TIMEOUT: "PT1M" }), 2_700_000);
+  // Absent/blank probeTimeout → fall back to the env-derived twin (readinessTimeoutMs).
+  assertEquals(probeBudgetMs(undefined, probe, { NANO_READINESS_POLL_TIMEOUT: "PT2H" }), 7_200_000);
+  assertEquals(probeBudgetMs("   ", probe, {}), 1_800_000);
+  // A malformed seeded value degrades to the built-in default (30m), matching isoDurationToMs.
+  assertEquals(probeBudgetMs("nonsense", probe, { NANO_READINESS_POLL_TIMEOUT: "PT1M" }), 1_800_000);
+});
+
+// ── repo/ref parse + redaction ──────────────────────────────────────────────────────────────
+test("parseRepoRef: splits owner/repo@ref and defaults the ref to HEAD", () => {
+  assertEquals(parseRepoRef("o/r@abc123"), { repo: "o/r", ref: "abc123" });
+  assertEquals(parseRepoRef("o/r"), { repo: "o/r", ref: "HEAD" });
+});
+
+test("redactString/redactTarget: strip userinfo and query (a token often rides either)", () => {
+  assertEquals(redactString("https://user:pass@host/path?token=abc"), "https://***@host/path?***");
+  assertStringIncludes(redactTarget(parseProbe({ kind: "http", target: "https://h/p?tok=s3cr3t" })), "?***");
+  const t = redactTarget(parseProbe({ kind: "http", target: "https://h/p?tok=s3cr3t" }));
+  assert(!t.includes("s3cr3t"), "the secret must not survive redaction");
+});
+
+test("redactTarget: a command target is never logged — only the kind + a fixed placeholder", () => {
+  const ct = redactTarget(parseProbe({ kind: "command", target: "curl -H 'Authorization: Bearer s3cr3t' https://h/p" }));
+  assertEquals(ct, "command:<redacted>");
+  assert(!ct.includes("s3cr3t"), "an arbitrary shell snippet's secrets must never survive to a log line");
+});
+
+// ── default ProbeExec: every attempt is bounded (a stuck probe can never hang the worker) ─────
+test("defaultProbeExec.run: a command that outlives the attempt timeout resolves bounded, non-zero", async () => {
+  const exec = defaultProbeExec(50);
+  const start = Date.now();
+  const out = await exec.run("sleep 5", process.env);
+  const elapsed = Date.now() - start;
+  assert(out.code !== 0, "a killed (timed-out) command must report a non-zero exit code, i.e. not ready");
+  assert(elapsed < 4000, `the attempt must resolve in bounded time, not run to completion (took ${elapsed}ms)`);
+});
+
+test("defaultProbeExec.httpGet: a hung endpoint aborts at the attempt timeout instead of hanging forever", async () => {
+  const { createServer } = await import("node:http");
+  const server = createServer(() => {
+    /* never responds — the request hangs until the client aborts */
+  });
+  await new Promise<void>((r) => server.listen(0, "127.0.0.1", () => r()));
+  const addr = server.address();
+  const port = typeof addr === "object" && addr ? addr.port : 0;
+  try {
+    const exec = defaultProbeExec(50);
+    const start = Date.now();
+    await assertRejects(() => exec.httpGet(`http://127.0.0.1:${port}/`, {}));
+    assert(Date.now() - start < 4000, "the fetch must abort at the attempt deadline, not hang");
+  } finally {
+    server.close();
+  }
+});
+
+test("DEFAULT_ATTEMPT_TIMEOUT_MS is a sane bounded default", () => {
+  assert(DEFAULT_ATTEMPT_TIMEOUT_MS > 0 && DEFAULT_ATTEMPT_TIMEOUT_MS <= 5 * 60_000);
+});