@nanobpm/nano-workforce 0.102.0 → 0.103.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **merge-loop:** re-attempt merge for stale/transient CI instead of paging a human ([#348](https://github.com/nanobpm/nano-workforce/issues/348)) ([#350](https://github.com/nanobpm/nano-workforce/issues/350)) ([87ce2d6](https://github.com/nanobpm/nano-workforce/commit/87ce2d69e893b4b0f965f481d6c247fb8fcb84e8))
+
 # [0.102.0](https://github.com/nanobpm/nano-workforce/compare/v0.101.1...v0.102.0) (2026-08-19)
 
 

package/SPEC.md

@@ -424,8 +424,30 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   check names ride `appendPrompt`) to green the checks on the branch, then re-arms the
   poller. It repeats while `ciFixRound < ciFixMax`
   (`NANO_PR_MAX_CI_FIX_ROUNDS`, default 3; `0` disables). Only when the budget is
-  exhausted, the agent reports `blocked`, or the branch is in `conflict` does it fall
-  through to the human escalation path.
+  exhausted, the agent reports `blocked` *and the PR is still blocked after a
+  ground-truth reconcile*, or the branch is in `conflict` does it fall through to the
+  human escalation path.
+
+- **Stale / transient checks — re-attempt, don't escalate** (issue #348) — GitHub's CI
+  concurrency **cancels** a superseded workflow run while a newer run on the *identical
+  head SHA* takes over. Both land in the head's `statusCheckRollup` under the same check
+  name — the stale one stamped `CANCELLED`, the live one green. This is a
+  **CI-concurrency-cancellation drift class**, not a code defect, defended at three
+  layers so it never pages a human:
+  - **Derivation (root cause)** — the merge poller's check derivation collapses the
+    rollup to the **newest run per `(headSha, checkName)`** (`latestRunPerCheck`) before
+    classifying, so a `CANCELLED` run superseded by a newer green run is **not** counted
+    as a failing gate. The phantom `blocked` never arises, so `fix-ci` is not even armed.
+  - **Agent verdict** — when `fix-ci` pushes nothing because the failing checks are
+    stale/transient (head already green), it returns `status: "reattempt"` (with
+    `pushed: false`). That routes to `arm-merge` — the merge is simply re-queued from
+    ground truth. The prompt reserves `blocked` for a genuine human decision (a missing
+    secret, an un-fixable failure), never a self-healing PR.
+  - **Reconcile-before-escalate guard** — even a *mislabelled* `blocked` self-heals: a
+    `blocked` verdict with no push (`pushed != true`) reconciles **once** via ground
+    truth (`gw-ci-blocked` → `ci-reconcile`, which re-arms the canonical merge poller and
+    sets `ciBlockedReconciled`), and escalates only if the PR is **still** blocked on the
+    re-derived state.
 
 - **Discovered dependency** — a `senior:fix-ci` or `senior:rebase` agent may find that
   the PR cannot land because **another PR must merge first** (a required linked-issue

package/app/failingChecksSupersede.test.ts

@@ -0,0 +1,93 @@
+// Derivation-layer guard for the CI-concurrency-cancellation drift class (issue #348).
+//
+// GitHub's CI concurrency cancels a superseded workflow run while a newer run on the *identical
+// head SHA* takes over. Both land in the head's `statusCheckRollup` under the same check name — the
+// stale one stamped `CANCELLED`, the live one green. The merge poller's check derivation used to
+// count that stale `CANCELLED` as a failing required check, so a PR whose head is actually green
+// read as `blocked`, armed `senior:fix-ci`, which honestly pushed nothing and (pre-#348) returned
+// `blocked` → a human merge-escalation for a self-healing PR.
+//
+// The fix collapses the rollup to the NEWEST run per check before classifying, so a superseded
+// `CANCELLED` never counts. These are pure unit tests over the exported derivation helpers.
+
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { allCheckNames, failingCheckNames, latestRunPerCheck } from "./github.ts";
+
+test("a CANCELLED run superseded by a newer green run on the same head does not count as failing", () => {
+  const rollup = [
+    // The superseded run: GitHub CI concurrency cancelled it when a newer run started.
+    { name: "engine-core", conclusion: "CANCELLED", startedAt: "2024-01-01T00:00:00Z", completedAt: "2024-01-01T00:01:00Z" },
+    // The live run on the identical head SHA: green.
+    { name: "engine-core", conclusion: "SUCCESS", startedAt: "2024-01-01T00:02:00Z", completedAt: "2024-01-01T00:05:00Z" },
+  ];
+  assertEquals(failingCheckNames(rollup), [], "the stale CANCELLED must not read as a failing gate");
+});
+
+test("every CANCELLED-superseded required check on one head SHA is dropped (the #348 instance)", () => {
+  // The exact PR #887 evidence: four required checks each with a superseded CANCELLED + a newer
+  // green run on the same head. None must count as failing.
+  const names = ["engine-core", "engine-wasm read-model wasm32 type-check", "processos", "server"];
+  const rollup = names.flatMap((name) => [
+    { name, conclusion: "CANCELLED", startedAt: "2024-01-01T00:00:00Z" },
+    { name, conclusion: "SUCCESS", startedAt: "2024-01-01T00:02:00Z" },
+  ]);
+  assertEquals(failingCheckNames(rollup), [], "no superseded CANCELLED may count as a failing check");
+});
+
+test("a genuine failure on the newest run still counts (no false-negative)", () => {
+  const rollup = [
+    { name: "engine-core", conclusion: "SUCCESS", startedAt: "2024-01-01T00:00:00Z" },
+    // Newest run genuinely failed — this must still be reported.
+    { name: "engine-core", conclusion: "FAILURE", startedAt: "2024-01-01T00:02:00Z" },
+  ];
+  assertEquals(failingCheckNames(rollup), ["engine-core"], "a real failure on the newest run must count");
+});
+
+test("a lone CANCELLED with no superseding run still counts (nothing green replaced it)", () => {
+  const rollup = [{ name: "engine-core", conclusion: "CANCELLED", startedAt: "2024-01-01T00:00:00Z" }];
+  assertEquals(failingCheckNames(rollup), ["engine-core"], "an unsuperseded CANCELLED remains a failing gate");
+});
+
+test("ties (missing timestamps) prefer the non-CANCELLED run so the real result wins", () => {
+  // GitHub sometimes omits run times; a superseded CANCELLED alongside a completed run must not
+  // shadow the real conclusion even when neither carries a timestamp.
+  const cancelledFirst = [
+    { name: "server", conclusion: "CANCELLED" },
+    { name: "server", conclusion: "SUCCESS" },
+  ];
+  const successFirst = [
+    { name: "server", conclusion: "SUCCESS" },
+    { name: "server", conclusion: "CANCELLED" },
+  ];
+  assertEquals(failingCheckNames(cancelledFirst), [], "CANCELLED-first tie resolves to the real (green) result");
+  assertEquals(failingCheckNames(successFirst), [], "success-first tie keeps the real (green) result");
+});
+
+test("latestRunPerCheck keeps exactly one run per check name (newest)", () => {
+  const rollup = [
+    { name: "a", conclusion: "CANCELLED", startedAt: "2024-01-01T00:00:00Z" },
+    { name: "a", conclusion: "SUCCESS", startedAt: "2024-01-01T00:02:00Z" },
+    { name: "b", conclusion: "FAILURE", startedAt: "2024-01-01T00:00:00Z" },
+  ];
+  const latest = latestRunPerCheck(rollup);
+  assertEquals(latest.length, 2, "one run per distinct check name");
+  const a = latest.find((c) => c.name === "a");
+  assert(a && a.conclusion === "SUCCESS", "check `a` resolves to its newest (green) run");
+});
+
+test("allCheckNames dedupes superseded reruns to a single name", () => {
+  const rollup = [
+    { name: "engine-core", conclusion: "CANCELLED", startedAt: "2024-01-01T00:00:00Z" },
+    { name: "engine-core", conclusion: "SUCCESS", startedAt: "2024-01-01T00:02:00Z" },
+  ];
+  assertEquals(allCheckNames(rollup), ["engine-core"], "a superseded rerun must not double-list the check name");
+});
+
+test("legacy StatusContext (state + context) supersession is handled by createdAt", () => {
+  const rollup = [
+    { context: "ci/legacy", state: "ERROR", createdAt: "2024-01-01T00:00:00Z" },
+    { context: "ci/legacy", state: "SUCCESS", createdAt: "2024-01-01T00:02:00Z" },
+  ];
+  assertEquals(failingCheckNames(rollup), [], "a superseded legacy status context is not a failing gate");
+});

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);
+});

package/app/featureReadiness.ts

@@ -0,0 +1,151 @@
+// nano-workforce — feature-intake readiness gate desugaring (issue #295).
+//
+// The intake-time half of the durable readiness gate for a SINGLE-issue feature run. A submitted
+// feature may carry an optional `readiness` (one or more full {@link ReadinessProbe} descriptors) or
+// the ergonomic shorthand `blockedOn` — a list of upstream issue/PR handles the feature must wait to
+// land before its implementation agent is dispatched. This module turns either form into the SAME
+// `readinessProbes` + `probeTimeout` process variables the (existing) readiness-gate preflight in
+// `resources/processes/feature.bpmn` runs — reusing the production probe kinds, the escalation form,
+// and the `capability` late-bind primitive verbatim (derivation over duplication). No new subsystem:
+// this is intake plumbing on top of `app/readiness.ts` (#258) and the `capability` kind (#274).
+//
+// `blockedOn` desugars per handle:
+//   • With a declared `consumerPackage` (the cross-repo case — e.g. a wfd feature gated on
+//     `@nanobpm/engine-wasm` carrying `nanobpm/nano-bpm#631`) → a `capability` probe that resolves
+//     "which published `pkg@version` FIRST carries this handle?" from publish provenance and
+//     late-binds the resolved `pkg@version` back into the run (`resolvedArtifacts`), so the agent can
+//     bump the consumer dependency to exactly that version.
+//   • Without a `consumerPackage` (no published-artifact edge applies) → a `command` probe that goes
+//     green once the referenced issue/PR is closed/merged (`gh api …/issues/<n> --jq .state`), the
+//     "merged is enough" fallback.
+//
+// The derivation is pure (no I/O, no engine) so it is trivially unit-testable — the seam
+// `startFeature` calls at submit to seed the gate.
+import { parseIssue } from "./plan.ts";
+import {
+  DEFAULT_READINESS_TIMEOUT,
+  parseProbe,
+  type ReadinessProbe,
+  readinessTimeout,
+} from "./readiness.ts";
+import { isoDurationToMs } from "./reviewWait.ts";
+
+/** The raw intake shape a submitted feature may carry (all optional). `readiness` is one or more
+ * full {@link ReadinessProbe} descriptors; `blockedOn` is the ergonomic shorthand — a list of
+ * upstream `owner/repo#N` handles; `consumerPackage` is the npm package whose publish provenance the
+ * `blockedOn` shorthand resolves the handles against (e.g. `@nanobpm/engine-wasm`). */
+export interface FeatureReadinessInput {
+  readonly readiness?: unknown;
+  readonly blockedOn?: unknown;
+  readonly consumerPackage?: unknown;
+}
+
+/** The desugared gate: the probes the feature must satisfy before it implements, and the single
+ * ISO-8601 bound the preflight's escalation timers fire off (the LONGEST of the probes' derived
+ * timeouts, so no probe is cut short). `probes` is empty when the feature declared no readiness —
+ * the gate is then skipped and the run proceeds straight to implementation (behaviour unchanged). */
+export interface FeatureReadiness {
+  readonly probes: ReadinessProbe[];
+  readonly probeTimeout: string | null;
+}
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim() !== "";
+}
+
+/** A valid GitHub `owner/repo` slug: both segments are restricted to the characters GitHub itself
+ * allows (alphanumerics, `-`, `_`, `.`). `parseIssue`'s shorthand branch matches `[^#]+` for the
+ * slug, so it would otherwise admit shell metacharacters (`;`, `$( )`, backticks, spaces) that get
+ * interpolated verbatim into the `command` probe's `exec` string (and the `capability` target).
+ * Constraining the slug here shuts that injection surface for the whole `blockedOn` desugaring. */
+const GITHUB_SLUG = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+/** Normalise a single `blockedOn` handle into a `capability` (with `consumerPackage`) or `command`
+ * (fallback) probe. The handle MUST parse as a full `owner/repo#N` reference — a bare `repo#N`
+ * cannot name a provenance source repo unambiguously, so it fails loudly here rather than desugaring
+ * to a probe that can never resolve. */
+function desugarHandle(handle: string, consumerPackage: string | null): ReadinessProbe {
+  const parsed = parseIssue(handle.trim());
+  if (!parsed) {
+    throw new Error(
+      `feature readiness: blockedOn handle '${handle}' must be a full 'owner/repo#123' reference ` +
+        "(a bare 'repo#123' cannot name the upstream provenance repo)",
+    );
+  }
+  // `parsed.number` is numeric (via `Number`), but `parsed.repo` is an unconstrained slug that lands in
+  // a shell `command` target — reject anything that isn't a plain GitHub `owner/repo` before we build it.
+  if (!GITHUB_SLUG.test(parsed.repo)) {
+    throw new Error(
+      `feature readiness: blockedOn handle '${handle}' has an invalid 'owner/repo' slug — only ` +
+        "alphanumerics, '-', '_' and '.' are allowed in each segment",
+    );
+  }
+  if (consumerPackage) {
+    // The `capability` edge (#274): resolve which published `<consumerPackage>@version` first carries
+    // this upstream handle and late-bind that `pkg@version` back into the run. The provenance source
+    // repo is the handle's own repo (where the upstream lands and publishes).
+    return {
+      kind: "capability",
+      target: `github-releases:${parsed.repo}`,
+      match: { package: consumerPackage, capabilityRef: parsed.planKey },
+      // A stuck/never-publishing upstream must ESCALATE (bounded) — never fail or proceed unbound.
+      onTimeout: "escalate",
+    };
+  }
+  // Fallback (no published-artifact edge): "merged is enough". `gh` reads its token from the ambient
+  // env (like the `github-check`/`capability` kinds), and PRs are issues in the REST API, so a single
+  // `/issues/<n>` state check covers both an issue being closed and a PR being merged (→ closed).
+  return {
+    kind: "command",
+    target: `gh api repos/${parsed.repo}/issues/${parsed.number} --jq .state`,
+    match: { stdoutIncludes: "closed" },
+    onTimeout: "escalate",
+  };
+}
+
+/** Parse + desugar a feature's optional intake readiness into the gate's `readinessProbes` +
+ * `probeTimeout`. Accepts EITHER the full `readiness` descriptor list OR the `blockedOn` shorthand
+ * (or both — they concatenate). Returns an empty probe set (gate skipped) when neither is present.
+ *
+ * Throws a descriptive error on a malformed descriptor (via {@link parseProbe}), a `blockedOn` entry
+ * that is not a string, an unparseable handle, or a `consumerPackage` that is present but blank — a
+ * mis-declared gate must fail loudly at submit, never wait forever at runtime. */
+export function parseFeatureReadiness(
+  input: FeatureReadinessInput | null | undefined,
+  env: Record<string, string | undefined> = process.env,
+): FeatureReadiness {
+  const probes: ReadinessProbe[] = [];
+  if (input && input.consumerPackage !== undefined && !isNonEmptyString(input.consumerPackage)) {
+    throw new Error("feature readiness: 'consumerPackage' must be a non-blank package name when supplied");
+  }
+  const consumerPackage = input && isNonEmptyString(input.consumerPackage) ? input.consumerPackage.trim() : null;
+
+  if (input?.readiness !== undefined && input.readiness !== null) {
+    if (!Array.isArray(input.readiness)) {
+      throw new Error("feature readiness: 'readiness' must be an array of probe descriptors");
+    }
+    for (const raw of input.readiness) probes.push(parseProbe(raw));
+  }
+
+  if (input?.blockedOn !== undefined && input.blockedOn !== null) {
+    if (!Array.isArray(input.blockedOn)) {
+      throw new Error("feature readiness: 'blockedOn' must be an array of 'owner/repo#123' handles");
+    }
+    for (const raw of input.blockedOn) {
+      if (!isNonEmptyString(raw)) {
+        throw new Error("feature readiness: each 'blockedOn' entry must be a non-blank 'owner/repo#123' handle");
+      }
+      probes.push(desugarHandle(raw, consumerPackage));
+    }
+  }
+
+  if (probes.length === 0) return { probes: [], probeTimeout: null };
+
+  // One bound governs the whole preflight's escalation timers — the LONGEST of the probes' derived
+  // timeouts (via the canonical `readinessTimeout`), so no probe is cut short. Mirrors the epic
+  // lowering (app/planLowering.ts) so the feature and epic gates derive the bound identically.
+  const probeTimeout = probes
+    .map((p) => readinessTimeout(p, env))
+    .reduce((a, b) => (isoDurationToMs(b, DEFAULT_READINESS_TIMEOUT) > isoDurationToMs(a, DEFAULT_READINESS_TIMEOUT) ? b : a));
+  return { probes, probeTimeout };
+}