@nanobpm/nano-workforce 0.102.1 → 0.104.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.104.0](https://github.com/nanobpm/nano-workforce/compare/v0.103.0...v0.104.0) (2026-08-19)
+
+
+### Features
+
+* **durable-resume:** enrolment gate + re-lease world-restore wiring ([#325](https://github.com/nanobpm/nano-workforce/issues/325)) ([#351](https://github.com/nanobpm/nano-workforce/issues/351)) ([b495dfa](https://github.com/nanobpm/nano-workforce/commit/b495dfabfda3e9e0953c6637342b79ca0c8148cc))
+
+# [0.103.0](https://github.com/nanobpm/nano-workforce/compare/v0.102.1...v0.103.0) (2026-08-19)
+
+
+### Features
+
+* **feature:** intake-time readiness gate for single-issue runs ([#295](https://github.com/nanobpm/nano-workforce/issues/295)) ([#349](https://github.com/nanobpm/nano-workforce/issues/349)) ([09b519b](https://github.com/nanobpm/nano-workforce/commit/09b519be9ff21c8821b3ec3e0687541710be718b)), closes [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 ## [0.102.1](https://github.com/nanobpm/nano-workforce/compare/v0.102.0...v0.102.1) (2026-08-19)
 
 

package/app/contracts.ts

@@ -402,6 +402,14 @@ export const TYPE_CONTRACTS = {
       "The mind/world checkpoint contract shape (issue #324, ADR 0062 Slice 4/5). `{ commitSha, effectLedger }` — the ONE type both the world marker (recorded in `world_checkpoints`/`world_effects`) and the mind checkpoint (Slice 1's `session.checkpoint`) derive from, so a single derivation feeds both halves and they cannot diverge. Its `effectLedger` is `Effect[]` (the fence-keyed irreversible-action ledger). The world half imports it from app/world; when Slice 1's harness-side `@nanobpm/agentic/session` lands it MUST reuse this shape, not re-declare a synonym.",
     module: "app/world/checkpoint.ts",
   },
+  DurableResumeRegistry: {
+    category: "type",
+    name: "DurableResumeRegistry",
+    owner: "app/durableResume.ts",
+    semantics:
+      "The `durable-resume` ENROLMENT GATE (issue #325, ADR 0062 Slice 5/5, the INTEGRATION slice). `durable-resume` is a worker attribute declared at enrolment (ADR 0056 §7 — capability gates enrolment, NEVER the routing token `network.role#seat`), recorded per worker instance in `worker_durable_resume` (migration 052). The enrol door (`operations/enrolAgenticWorker.ts`) records it via `recordEnrolment`; `app/service.ts` consults `fleetSupportsDurableResume` before emitting the world-restore `commitSha` (the `io.nanobpm.agentTask.repository` envelope) so a re-leased `senior:pr-review` round RESUMES only on a participating fleet and gracefully DEGRADES (redriven from scratch) otherwise. Consume this ONE module for the durable-resume gate — do not re-declare a synonym or read the flag off a second store.",
+    module: "app/durableResume.ts",
+  },
 } as const satisfies Record<string, TypeContract>;
 
 export const CAPABILITY_URL_CONTRACTS = {

package/app/durableResume.test.ts

@@ -0,0 +1,89 @@
+// Tests for the `durable-resume` enrolment registry (issue #325, ADR 0062 Slice 5/5) against a REAL
+// in-memory SQLite engine with migration 052 applied — so the upsert, the {0,1} flag domain, and the
+// fleet-level participation probe are proven, not mocked.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry, DURABLE_RESUME_ATTR, fleetSupportsDurableResume } from "./durableResume.ts";
+
+const mem = () => memDataFor(["052_worker_durable_resume.sql"]);
+
+test("DURABLE_RESUME_ATTR is the canonical enrolment-attribute name", () => {
+  assertEquals(DURABLE_RESUME_ATTR, "durable-resume");
+});
+
+test("recordEnrolment persists a participant and isParticipant reads it back", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  assertEquals(await reg.isParticipant("w1"), false, "unknown instance is a non-participant (safe default)");
+  await reg.recordEnrolment("w1", true);
+  assertEquals(await reg.isParticipant("w1"), true);
+});
+
+test("recordEnrolment records an explicit non-participant as false", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  await reg.recordEnrolment("w1", false);
+  assertEquals(await reg.isParticipant("w1"), false);
+  assertEquals(await reg.anyParticipant(), false, "a recorded non-participant is not a participant");
+});
+
+test("recordEnrolment is an idempotent upsert — a re-enrol overwrites the flag", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  await reg.recordEnrolment("w1", true);
+  assertEquals(await reg.isParticipant("w1"), true);
+  // A redeploy that drops durable-resume support flips the flag back — no duplicate row, no stale yes.
+  await reg.recordEnrolment("w1", false);
+  assertEquals(await reg.isParticipant("w1"), false);
+  await reg.recordEnrolment("w1", true);
+  assertEquals(await reg.isParticipant("w1"), true);
+});
+
+test("the registry normalises keys and ignores a blank/whitespace instance", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  // A blank or whitespace-only key cannot key a reachable row and must never open the fleet gate.
+  await reg.recordEnrolment("", true);
+  await reg.recordEnrolment("   ", true);
+  assertEquals(await reg.anyParticipant(), false, "a blank/whitespace enrolment is ignored, gate stays closed");
+  assertEquals(await reg.isParticipant("   "), false, "a blank key is never a participant");
+  // A padded key is canonicalised (trimmed) so reads and writes agree on one row — no unreachable dup.
+  await reg.recordEnrolment("  w1  ", true);
+  assertEquals(await reg.isParticipant("w1"), true, "a padded write is readable by the trimmed key");
+  assertEquals(await reg.isParticipant("  w1  "), true, "a padded read normalises to the same row");
+});
+
+test("anyParticipant is the fleet-level existence probe over participants", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  assertEquals(await reg.anyParticipant(), false, "no enrolment yet");
+  await reg.recordEnrolment("legacy-1", false);
+  await reg.recordEnrolment("legacy-2", false);
+  assertEquals(await reg.anyParticipant(), false, "a fleet of only non-participants does not support resume");
+  await reg.recordEnrolment("modern-1", true);
+  assertEquals(await reg.anyParticipant(), true, "one participant makes the mixed fleet resume-capable");
+});
+
+test("fleetSupportsDurableResume mirrors anyParticipant, and degrades to false without a data layer", async () => {
+  const { data } = mem();
+  assertEquals(await fleetSupportsDurableResume(undefined), false, "no data layer → additive-safe false");
+  assertEquals(await fleetSupportsDurableResume(data), false, "no participant enrolled");
+  await new DurableResumeRegistry(data).recordEnrolment("w1", true);
+  assertEquals(await fleetSupportsDurableResume(data), true);
+});
+
+test("fleetSupportsDurableResume degrades to false on a store read failure (legacy DB predating 052)", async () => {
+  // A DataLayer whose table has no `worker_durable_resume` — the read throws; the gate must degrade to
+  // false (redrive from scratch) rather than blocking a submit/merge on the enrolment registry.
+  const { data } = memDataFor([]);
+  assertEquals(await fleetSupportsDurableResume(data), false);
+});
+
+test("the flag domain is pinned to {0,1} — a participant reads as exactly true", async () => {
+  const { data, db } = mem();
+  await new DurableResumeRegistry(data).recordEnrolment("w1", true);
+  const rows = db.prepare("SELECT durable_resume FROM worker_durable_resume WHERE instance = ?").all("w1");
+  assertEquals(rows.length, 1);
+  assert(rows[0].durable_resume === 1, "true is stored as the integer 1");
+});

package/app/durableResume.ts

@@ -0,0 +1,141 @@
+// nano-workforce — the `durable-resume` ENROLMENT GATE (issue #325, ADR 0062 Slice 5/5).
+//
+// Durable agent-session resume splits into two halves already landed by the earlier slices: the MIND
+// (the harness conversation — Slices 1–3, restored harness-side via `session/load` / native
+// `--resume`) and the WORLD (the git working tree + irreversible effect ledger — Slice 4,
+// `app/world`, restored by inverting the round's `git push` into `git fetch && git checkout <sha>`).
+// This slice is the INTEGRATION that wires both halves into the running orchestration, behind an
+// enrolment gate, so a re-leased `senior:pr-review` round (ADR 0002 lease-expiry redrive) RESUMES at
+// the last push-checkpoint on a participating harness and gracefully DEGRADES — redriven from scratch,
+// exactly as today — on a harness that does not advertise durable-resume.
+//
+// THE GATE (ADR 0056 §7). `durable-resume` is a WORKER ATTRIBUTE declared at ENROLMENT — never a
+// routing token. The routing token `network.role#seat` is unchanged; there is no BPMN change and no
+// job-type change. A worker's harness advertises durable-resume at enrol (the probe result from Slice
+// 2/3); this registry records that per instance so the app can ask, before it emits the world-restore
+// marker, "does the fleet serving this role include a participant?".
+//
+// WHY FLEET-LEVEL. At the moment the app emits the repo-provisioning envelope it does not yet know
+// WHICH worker will lease the `senior:pr-review` job — any worker enrolled for that role may. So the
+// gate is a fleet-level existence probe ({@link DurableResumeRegistry.anyParticipant}). This is
+// well-defined for a MIXED fleet: emitting the world-restore `commitSha` when at least one participant
+// is enrolled lets a participant RESUME, while a non-participant harness simply ignores the marker
+// (the envelope validators are structurally forward-compatible) and clones the head branch tip —
+// redriving from scratch. When NO participant is enrolled the marker is omitted entirely, so nothing
+// regresses: resume is purely additive.
+//
+// Advisory, app-tier only (ADR 0056): this registry NEVER hard-locks or gates a BPMN sequence flow —
+// it only decides whether an OPTIMISATION (world-restore) is offered inside an activation.
+import type { DataLayer } from "@nanobpm/urban";
+
+/**
+ * The canonical name of the durable-resume enrolment attribute. A worker advertises it at enrol; the
+ * registry records it here. It is an ENROLMENT gate (ADR 0056 §7), never a routing token — do not put
+ * it in `network.role#seat`.
+ */
+export const DURABLE_RESUME_ATTR = "durable-resume";
+
+/** A persisted enrolment row (`worker_durable_resume`): one worker instance's durable-resume flag. */
+interface WorkerDurableResumeRow {
+  instance: string;
+  durable_resume: number;
+  updated_at: string;
+}
+
+/** True when `err` is the durable PRIMARY KEY fence firing — a SQLite `UNIQUE constraint failed`
+ * raised because a concurrent/duplicate enrol inserted the SAME instance BETWEEN our `findOne` and our
+ * `insert`. `recordEnrolment` is an upsert, so a collision means "the row now exists" — the same
+ * intended outcome as the update branch, not a surfaced error. Matched on the message substring the
+ * RAD `Table` surface propagates verbatim (mirrors `WorldStore`), because that surface hides the
+ * concrete driver error type. */
+function isFenceCollision(err: unknown): boolean {
+  return err instanceof Error && /UNIQUE constraint failed/i.test(err.message);
+}
+
+/**
+ * The durable registry of per-worker durable-resume participation, over the `worker_durable_resume`
+ * table (`db/migrations/052_worker_durable_resume.sql`). Backed by the app's SQLite DataLayer through
+ * the RAD `Table<T>` surface (`data.table(...)`) — NOT hand-written SQL — mirroring `WorldStore`.
+ */
+export class DurableResumeRegistry {
+  readonly #data: DataLayer;
+
+  constructor(data: DataLayer) {
+    this.#data = data;
+  }
+
+  #table() {
+    return this.#data.table<WorkerDurableResumeRow>("worker_durable_resume", "instance");
+  }
+
+  /** Canonicalise an instance key: trim surrounding whitespace and reject a blank one. The instance is
+   * the table PRIMARY KEY and drives the fleet-wide gate via {@link anyParticipant}, so a whitespace or
+   * differently-trimmed key would create an unreachable row — or, worse, open the gate on a blank key.
+   * Normalising here makes every registry entry point safe by default rather than relying on each call
+   * site to pre-trim. Returns the trimmed key, or `undefined` when it is empty/whitespace. */
+  static #normaliseInstance(instance: string): string | undefined {
+    const trimmed = instance.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  /**
+   * Record a worker's durable-resume participation at enrolment (an idempotent UPSERT keyed by
+   * `instance`). A re-enrol overwrites the flag so a harness that gains — or loses — durable-resume
+   * support across a redeploy is reflected. The `findOne`-then-insert is racy under a concurrent
+   * duplicate enrol, so a PRIMARY KEY fence collision folds into the update path rather than surfacing
+   * as an error (the same end-state either way). A blank/whitespace `instance` is ignored (no-op) — it
+   * cannot key a reachable row and a blank key would let unrelated workers collide on one registry row.
+   */
+  async recordEnrolment(instance: string, durableResume: boolean): Promise<void> {
+    const key = DurableResumeRegistry.#normaliseInstance(instance);
+    if (key === undefined) return;
+    const table = this.#table();
+    const now = new Date().toISOString();
+    const flag = durableResume ? 1 : 0;
+    const existing = await table.findOne({ instance: key });
+    if (existing) {
+      await table.update(key, { durable_resume: flag, updated_at: now });
+      return;
+    }
+    try {
+      await table.insert({ instance: key, durable_resume: flag, updated_at: now });
+    } catch (err) {
+      if (!isFenceCollision(err)) throw err;
+      await table.update(key, { durable_resume: flag, updated_at: now });
+    }
+  }
+
+  /** Whether a specific worker instance is a durable-resume participant. `false` for an unknown
+   * instance (never enrolled) or a blank/whitespace key — the safe default (graceful degradation). */
+  async isParticipant(instance: string): Promise<boolean> {
+    const key = DurableResumeRegistry.#normaliseInstance(instance);
+    if (key === undefined) return false;
+    const row = await this.#table().findOne({ instance: key });
+    return row?.durable_resume === 1;
+  }
+
+  /** Whether the enrolled fleet includes AT LEAST ONE durable-resume participant — the fleet-level
+   * gate the world-restore emission consults. `false` when none is enrolled (nobody advertises
+   * durable-resume), so the resume marker is omitted and the round redrives from scratch. */
+  async anyParticipant(): Promise<boolean> {
+    const row = await this.#table().findOne({ durable_resume: 1 });
+    return row != null;
+  }
+}
+
+/**
+ * Whether the fleet supports durable resume — the app-tier gate for emitting the world-restore
+ * `commitSha` (see `app/service.ts`). Best-effort: any read failure (a legacy DB predating migration
+ * 052, an in-flight desync) degrades to `false`, so the round redrives from scratch rather than
+ * blocking a submit/merge on the enrolment registry. When no data layer is mounted it is likewise
+ * `false` — resume is purely additive, so its absence is always the safe direction.
+ */
+export async function fleetSupportsDurableResume(data: DataLayer | undefined): Promise<boolean> {
+  if (!data) return false;
+  try {
+    return await new DurableResumeRegistry(data).anyParticipant();
+  } catch (err) {
+    console.warn(`[durable-resume] fleet participation read: ${err}`);
+    return false;
+  }
+}

package/app/feature.test.ts

@@ -307,3 +307,74 @@ test("startFeature: persists the real issue title when the fetch succeeds", asyn
     else process.env["GITHUB_TOKEN"] = prevTok;
   }
 });
+
+test("startFeature: no readiness ⇒ readinessProbes/probeTimeout/gateKey seeded null (gate skipped)", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-R0" });
+    },
+  } as any;
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false);
+  const v = captured.variables;
+  assertEquals(v.readinessProbes, null);
+  assertEquals(v.probeTimeout, null);
+  assertEquals(v.gateKey, null);
+  assertEquals(v.resolvedArtifacts, null);
+});
+
+test("startFeature: readiness probes seed the gate variables + a non-blank correlation key", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-R1" });
+    },
+  } as any;
+  const probes = [
+    {
+      kind: "capability",
+      target: "github-releases:nanobpm/nano-bpm",
+      match: { package: "@nanobpm/engine-wasm", capabilityRef: "nanobpm/nano-bpm#631" },
+      onTimeout: "escalate",
+    },
+  ] as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "main",
+    false,
+    false,
+    null,
+    { probes, probeTimeout: "PT30M" },
+  );
+  const v = captured.variables;
+  assertEquals(v.readinessProbes, probes);
+  assertEquals(v.probeTimeout, "PT30M");
+  // The preflight probe worker requires a non-blank gateKey to publish readiness-ready on.
+  assertEquals(v.gateKey, "feature-readiness:owner/repo#42");
+  assertEquals(v.resolvedArtifacts, null);
+});
+
+test("startFeature: probes without a probeTimeout fail fast (both are load-bearing together)", async () => {
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-R2" }) } as any;
+  let threw = false;
+  try {
+    await startFeature(
+      memData({ feature_runs: { rows: [], key: "feature_key" } }),
+      engine,
+      PARSED,
+      "main",
+      false,
+      false,
+      null,
+      { probes: [{ kind: "command", target: "x" }] as any, probeTimeout: null },
+    );
+  } catch (err) {
+    threw = true;
+    assertEquals((err as Error).message.includes("probeTimeout"), true);
+  }
+  assertEquals(threw, true);
+});

package/app/feature.ts

@@ -17,8 +17,20 @@
 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 type { ReadinessProbe } from "./readiness.ts";
 import { deriveListBucket, deriveStage } from "./stage.ts";
 
+/** Optional intake-time readiness gate for a feature run (issue #295): the `capability`/`command`/…
+ * probes the run must ALL satisfy before its implementation agent is dispatched (parked, durably, at
+ * the leading readiness preflight in feature.bpmn), plus the single ISO-8601 bound the preflight's
+ * escalation timers fire off. Both are DERIVED once from the submitted `readiness`/`blockedOn` intake
+ * by {@link parseFeatureReadiness} (app/featureReadiness.ts). Empty/absent ⇒ the gate is skipped and
+ * the run proceeds straight to implementation, exactly as today's submissions do. */
+export interface FeatureReadinessOptions {
+  readonly probes?: ReadinessProbe[];
+  readonly probeTimeout?: string | null;
+}
+
 /** The BPMN process this module drives (resources/processes/feature.bpmn). */
 export const FEATURE_PROCESS_ID = "feature";
 
@@ -339,7 +351,22 @@ export async function startFeature(
   converge: boolean,
   autoMerge: boolean,
   customInstructions: string | null = null,
+  readiness: FeatureReadinessOptions = {},
 ) {
+  // Intake-time readiness gate (issue #295): the probes the run must satisfy before it implements,
+  // and the bound its preflight escalation timers fire off. Both are load-bearing together —
+  // `pr.readiness-probe` rejects a blank `probeTimeout` and the preflight timers read `=probeTimeout`
+  // — so a non-empty probe set seeded without a bound would incident at runtime. Fail fast at the
+  // start door instead (mirroring `startPlan`); `parseFeatureReadiness` always derives the two
+  // together, so this only fires for a mis-seeded direct caller.
+  const readinessProbes = readiness.probes && readiness.probes.length > 0 ? readiness.probes : null;
+  if (readinessProbes && (readiness.probeTimeout ?? "").trim() === "") {
+    throw new Error(
+      `startFeature(${parsed.planKey}): ${readinessProbes.length} readiness probe(s) seeded without a ` +
+        "probeTimeout — the preflight escalation timers (=probeTimeout) and pr.readiness-probe both require " +
+        "a non-blank bound. Derive it via parseFeatureReadiness before starting a gated feature.",
+    );
+  }
   // Operator free-text steering for the implementation agent (issue #172 follow-on): blank/absent →
   // null so the implement task's `appendPrompt` FEEL (`customInstructions = null`) skips the block
   // rather than appending an empty "Operator custom instructions" heading.
@@ -447,6 +474,21 @@ export async function startFeature(
       // task's `appendPrompt` FEEL (feature.bpmn). Null when none was supplied; persists on the
       // instance so it also rides the answer-loop redispatch back into the same implement task.
       customInstructions: instructions,
+      // Intake-time readiness gate (issue #295): the leading preflight the feature run parks on until
+      // every declared probe goes green (feature.bpmn `gw-readiness` → `readiness-preflight`). A
+      // submission with NO readiness carries `null` here, so the gateway routes straight to
+      // `ensure-base-branch` and the run implements immediately — behaviour unchanged for today's
+      // features. `probeTimeout` bounds the preflight's escalation timers (derived once from the same
+      // probes); `gateKey` is the non-blank correlation key the probe worker publishes
+      // `readiness-ready` on (required even in the preflight, which reads the probe's synchronous
+      // result); `resolvedArtifacts` is filled by the preflight on green — the exact `pkg@version`s
+      // first carrying each awaited capability — and rides the implement task's `appendPrompt` so the
+      // agent bumps the consumer dependency to exactly the bound version. Seeded `null` so a
+      // gate-less run still resolves the variable in that FEEL instead of raising an incident.
+      readinessProbes,
+      probeTimeout: readinessProbes ? (readiness.probeTimeout ?? null) : null,
+      gateKey: readinessProbes ? `feature-readiness:${parsed.planKey}` : null,
+      resolvedArtifacts: null,
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/featureReadiness.test.ts

@@ -0,0 +1,165 @@
+// Unit coverage for the feature-intake readiness gate desugaring (issue #295).
+//
+// `parseFeatureReadiness` turns a submitted feature's optional `readiness`/`blockedOn` intake into the
+// `readinessProbes` + `probeTimeout` process variables the feature.bpmn preflight runs. These tests
+// pin the desugaring: full descriptors round-trip through `parseProbe`, `blockedOn` desugars to
+// `capability` probes (with `consumerPackage`) or `command` state probes (fallback), the bound is
+// derived, and malformed intake fails loudly at submit.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { parseFeatureReadiness } from "./featureReadiness.ts";
+
+const ENV = { NANO_READINESS_POLL_TIMEOUT: "PT30M" } as Record<string, string | undefined>;
+
+test("parseFeatureReadiness: no intake ⇒ empty probes, null bound (gate skipped)", () => {
+  assertEquals(parseFeatureReadiness(undefined, ENV), { probes: [], probeTimeout: null });
+  assertEquals(parseFeatureReadiness({}, ENV), { probes: [], probeTimeout: null });
+  assertEquals(parseFeatureReadiness({ readiness: [], blockedOn: [] }, ENV), { probes: [], probeTimeout: null });
+});
+
+test("parseFeatureReadiness: blockedOn + consumerPackage ⇒ capability probes with derived bound", () => {
+  const out = parseFeatureReadiness(
+    { blockedOn: ["nanobpm/nano-bpm#631", "nanobpm/nano-bpm#808"], consumerPackage: "@nanobpm/engine-wasm" },
+    ENV,
+  );
+  assertEquals(out.probes.length, 2);
+  assertEquals(out.probes[0], {
+    kind: "capability",
+    target: "github-releases:nanobpm/nano-bpm",
+    match: { package: "@nanobpm/engine-wasm", capabilityRef: "nanobpm/nano-bpm#631" },
+    onTimeout: "escalate",
+  });
+  assertEquals(out.probes[1].match?.capabilityRef, "nanobpm/nano-bpm#808");
+  // Every derived probe shares the env default, so the bound is that default.
+  assertEquals(out.probeTimeout, "PT30M");
+});
+
+test("parseFeatureReadiness: blockedOn without consumerPackage ⇒ command state probes (merged-is-enough)", () => {
+  const out = parseFeatureReadiness({ blockedOn: ["octo/cat#7"] }, ENV);
+  assertEquals(out.probes[0], {
+    kind: "command",
+    target: "gh api repos/octo/cat/issues/7 --jq .state",
+    match: { stdoutIncludes: "closed" },
+    onTimeout: "escalate",
+  });
+  assertEquals(out.probeTimeout, "PT30M");
+});
+
+test("parseFeatureReadiness: full readiness descriptors round-trip through parseProbe", () => {
+  const out = parseFeatureReadiness(
+    {
+      readiness: [
+        { kind: "http", target: "https://example.test/health", match: { status: 200 } },
+        { kind: "command", target: "make ready" },
+      ],
+    },
+    ENV,
+  );
+  assertEquals(out.probes.length, 2);
+  assertEquals(out.probes[0].kind, "http");
+  assertEquals(out.probes[0].match?.status, 200);
+  assertEquals(out.probes[1].kind, "command");
+});
+
+test("parseFeatureReadiness: readiness + blockedOn concatenate", () => {
+  const out = parseFeatureReadiness(
+    { readiness: [{ kind: "command", target: "make ready" }], blockedOn: ["octo/cat#7"] },
+    ENV,
+  );
+  assertEquals(out.probes.length, 2);
+  assertEquals(out.probes[0].kind, "command");
+  assertEquals(out.probes[1].target, "gh api repos/octo/cat/issues/7 --jq .state");
+});
+
+test("parseFeatureReadiness: a longer per-probe budget wins the derived bound", () => {
+  const out = parseFeatureReadiness(
+    {
+      readiness: [
+        { kind: "command", target: "a", poll: { timeoutMs: 60_000 } },
+        { kind: "command", target: "b", poll: { timeoutMs: 3_600_000 } },
+      ],
+    },
+    ENV,
+  );
+  assertEquals(out.probeTimeout, "PT3600S");
+});
+
+test("parseFeatureReadiness: a bare repo#N handle is rejected (cannot name a provenance repo)", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ blockedOn: ["nano-bpm#631"], consumerPackage: "@nanobpm/engine-wasm" }, ENV);
+  } catch (err) {
+    threw = true;
+    assertEquals((err as Error).message.includes("owner/repo#123"), true);
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a handle whose repo carries shell metacharacters is rejected (no injection into the command probe)", () => {
+  // The `command` fallback interpolates `parsed.repo` into a shell string run via `exec`. `parseIssue`'s
+  // `owner/repo#N` branch matches `[^#]+` for the slug, so a crafted handle could smuggle `;`/`$()`/backticks
+  // into the readiness worker's shell. Desugaring MUST reject any repo that isn't a valid GitHub slug.
+  for (const evil of [
+    "octo/cat; rm -rf /#7",
+    "octo/cat$(touch pwned)#7",
+    "octo/`whoami`#7",
+    "octo/cat rm#7",
+  ]) {
+    let threw = false;
+    try {
+      parseFeatureReadiness({ blockedOn: [evil] }, ENV);
+    } catch (err) {
+      threw = true;
+      assertEquals((err as Error).message.includes("owner/repo"), true);
+    }
+    assertEquals(threw, true);
+  }
+});
+
+test("parseFeatureReadiness: a non-string blockedOn entry is rejected", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ blockedOn: [42] }, ENV);
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a blank consumerPackage is rejected", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ blockedOn: ["octo/cat#7"], consumerPackage: "   " }, ENV);
+  } catch (err) {
+    threw = true;
+    assertEquals((err as Error).message.includes("consumerPackage"), true);
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a malformed readiness descriptor fails loudly (unknown kind)", () => {
+  let threw = false;
+  try {
+    parseFeatureReadiness({ readiness: [{ kind: "bogus", target: "x" }] }, ENV);
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("parseFeatureReadiness: a non-array readiness/blockedOn is rejected", () => {
+  let a = false;
+  let b = false;
+  try {
+    parseFeatureReadiness({ readiness: { kind: "command", target: "x" } }, ENV);
+  } catch {
+    a = true;
+  }
+  try {
+    parseFeatureReadiness({ blockedOn: "octo/cat#7" }, ENV);
+  } catch {
+    b = true;
+  }
+  assertEquals(a, true);
+  assertEquals(b, true);
+});