@nanobpm/nano-workforce 0.102.0 → 0.103.0

package/app/github.ts

@@ -521,17 +521,78 @@ interface RollupEntry {
   name?: string;
   context?: string;
   workflowName?: string;
+  /** CheckRun timestamps (GraphQL `statusCheckRollup`). A superseded run and the newer run that
+   * replaced it carry the same check name but different times, so they order the runs of one check.
+   * StatusContext carries `createdAt` instead. All are ISO-8601 or absent. */
+  startedAt?: string;
+  completedAt?: string;
+  createdAt?: string;
 }
+
+/** The canonical identity of a check across its reruns: its name (CheckRun) or context
+ * (StatusContext), falling back to its `workflowName` and finally the sentinel `"check"` when
+ * neither is present. GitHub CI concurrency can leave several runs of the SAME check on one head
+ * commit — a superseded run plus the newer run that replaced it — so this is what we group by. */
+function checkKey(c: RollupEntry): string {
+  return c.name || c.context || c.workflowName || "check";
+}
+
+/** A run's ordering timestamp (newest wins): its completion, else its start, else its creation.
+ * `0` when none is present (the shape carries no time) so a timed run always outranks an untimed
+ * one. */
+function runOrder(c: RollupEntry): number {
+  const t = c.completedAt || c.startedAt || c.createdAt;
+  if (!t) return 0;
+  const ms = Date.parse(t);
+  return Number.isNaN(ms) ? 0 : ms;
+}
+
+/** True when a run's conclusion is `CANCELLED` — the state GitHub CI concurrency stamps on a run it
+ * supersedes with a newer run on the identical head SHA (a stale/transient cancellation, not a code
+ * defect). */
+function isCancelled(c: RollupEntry): boolean {
+  return (c.conclusion || c.state || "").toUpperCase() === "CANCELLED";
+}
+
+/** Collapse a head's rollup to the **newest run per check**. GitHub's CI-concurrency cancellation
+ * (issue #348) leaves BOTH a superseded run (stamped `CANCELLED`) and the newer run that replaced
+ * it on the *same head SHA*, under the same check name. Counting the stale `CANCELLED` as a failure
+ * escalates a self-healing PR whose head is actually green. The rollup is already scoped to the head
+ * commit, so grouping by check name and keeping the newest run per name yields one ground-truth
+ * conclusion per `(headSha, checkName)`. Ties (equal/absent timestamps) prefer a non-`CANCELLED`
+ * run, so a superseded cancellation never shadows the real result even when GitHub omits times. */
+export function latestRunPerCheck(rollup: RollupEntry[]): RollupEntry[] {
+  const newest = new Map<string, RollupEntry>();
+  for (const c of rollup) {
+    const key = checkKey(c);
+    const prev = newest.get(key);
+    if (prev === undefined) {
+      newest.set(key, c);
+      continue;
+    }
+    const dt = runOrder(c) - runOrder(prev);
+    if (dt > 0) {
+      newest.set(key, c);
+    } else if (dt === 0 && isCancelled(prev) && !isCancelled(c)) {
+      // Same/unknown time: a CANCELLED run is the superseded one — the real result wins.
+      newest.set(key, c);
+    }
+  }
+  return [...newest.values()];
+}
+
 /** Names of the checks whose result is a hard failure (as opposed to pending/success). Covers
  * both the CheckRun shape (`conclusion` + `name`/`workflowName`) and the legacy StatusContext
  * shape (`state` + `context`). The names are what the CI-fix agent is handed so it knows which
- * gates to make green; `failingChecks` (the count) is derived from this list. */
-function failingCheckNames(rollup: RollupEntry[]): string[] {
+ * gates to make green; `failingChecks` (the count) is derived from this list. Derivation is over the
+ * **newest run per check** (`latestRunPerCheck`) so a `CANCELLED` run superseded by a newer green
+ * run on the identical head SHA is not counted as a failing gate (issue #348). */
+export function failingCheckNames(rollup: RollupEntry[]): string[] {
   const bad = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "ERROR"]);
   const names: string[] = [];
-  for (const c of rollup) {
+  for (const c of latestRunPerCheck(rollup)) {
     const v = (c.conclusion || c.state || "").toUpperCase();
-    if (bad.has(v)) names.push(c.name || c.context || c.workflowName || "check");
+    if (bad.has(v)) names.push(checkKey(c));
   }
   return names;
 }
@@ -539,10 +600,11 @@ function failingCheckNames(rollup: RollupEntry[]): string[] {
 /** Names of every head check present, regardless of state. Covers both the CheckRun shape
  * (`name`/`workflowName`) and the legacy StatusContext shape (`context`). Used to test whether a
  * repo's *required* checks are present on the head — so an unrelated always-on check (e.g.
- * Mergify's "Merge Queue") doesn't masquerade as the required CI run having already happened. */
-function allCheckNames(rollup: RollupEntry[]): string[] {
+ * Mergify's "Merge Queue") doesn't masquerade as the required CI run having already happened.
+ * Deduped to the newest run per check so a superseded rerun doesn't list a check name twice. */
+export function allCheckNames(rollup: RollupEntry[]): string[] {
   const names: string[] = [];
-  for (const c of rollup) {
+  for (const c of latestRunPerCheck(rollup)) {
     const name = c.name || c.context || c.workflowName;
     if (name) names.push(name);
   }

package/app/mergeCiReattempt.test.ts

@@ -0,0 +1,138 @@
+// Structural regression guard for the CI-concurrency-cancellation drift class (issue #348).
+//
+// The merge loop escalated a human whenever `senior:fix-ci` returned `blocked` — even when the
+// failing required checks were STALE/TRANSIENT (CANCELLED runs superseded by a newer green run on
+// the identical head SHA) and the agent honestly pushed nothing. The `fix-ci` prompt actively
+// funnelled that self-healing case into `blocked`, and `blocked` routed straight to the merge
+// escalation user task. A phantom-blocked, self-healing merge paged a human.
+//
+// The fix adds a first-class re-attempt path and a reconcile-before-escalate guard:
+//
+//   1. `status = "reattempt"` (a first-class fix-ci verdict for stale/transient checks) routes to
+//      `arm-merge`, re-queuing the merge from ground truth — no human, and declared explicitly
+//      beside the `f_ci_reconcile` empty-status default rather than relying on the fall-through.
+//   2. A `blocked` verdict with no push (`pushed != true`) reconciles ONCE via ground truth
+//      (`gw-ci-blocked` → `ci-reconcile` → re-arm the poller) and escalates only if it is STILL
+//      blocked — so even a mislabelled `blocked` self-heals.
+//
+// Pure text assertions over the committed BPMN (no engine), matching the repo's lightweight
+// model-guard style (see mergeEscalationQuestion.test.ts, mergeRebaseArm.test.ts).
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const bpmn = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+// Collapse whitespace so attribute-order / line-wrapping churn doesn't make the assertions brittle.
+const flat = bpmn.replace(/\s+/g, " ");
+
+function flowElement(id: string): string | null {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*?\\bid="${id}"[^>]*?(?:/>|>(?:(?!<bpmn:sequenceFlow\\b).)*?</bpmn:sequenceFlow>)`,
+  );
+  const m = flat.match(re);
+  return m ? m[0] : null;
+}
+
+function flowHasId(id: string, source: string, target: string): boolean {
+  const el = flowElement(id);
+  if (!el) return false;
+  return el.includes(`sourceRef="${source}"`) && el.includes(`targetRef="${target}"`);
+}
+
+function serviceTask(id: string): string | null {
+  const m = flat.match(new RegExp(`<bpmn:serviceTask\\b[^>]*\\bid="${id}"[\\s\\S]*?</bpmn:serviceTask>`));
+  return m ? m[0].replace(/&#34;/g, '"').replace(/&amp;/g, "&").replace(/&#10;/g, "\n") : null;
+}
+
+test("a first-class `reattempt` verdict re-attempts the merge (arm-merge), not escalation", () => {
+  // gw-ci-result must carry an explicit `status = "reattempt"` arm to arm-merge, declared beside
+  // (not folded into) the empty-status `f_ci_reconcile` default.
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-ci-result"[\s\S]*?<\/bpmn:exclusiveGateway>/);
+  assert(gw, "gw-ci-result gateway must exist");
+  assertStringIncludes(gw![0], "f_ci_reattempt", "gw-ci-result must declare the reattempt outgoing arm");
+
+  const reattempt = flowElement("f_ci_reattempt");
+  assert(reattempt, "f_ci_reattempt flow missing");
+  assert(
+    flowHasId("f_ci_reattempt", "gw-ci-result", "arm-merge"),
+    "a reattempt verdict must re-arm the merge poller (arm-merge), never escalate",
+  );
+  assertStringIncludes(reattempt!, 'status = "reattempt"', "the reattempt arm must be gated on status = reattempt");
+  // It must be an EXPLICIT labelled flow, not the empty-status default.
+  assert(!/default="f_ci_reattempt"/.test(flat), "reattempt must be an explicit arm, not the gateway default");
+});
+
+test("a fix-ci `reattempt` result does NOT create a merge escalation", () => {
+  // No flow originating from the reattempt classification may reach the merge-escalation task.
+  assert(
+    !flowHasId("f_ci_reattempt", "gw-ci-result", "merge-esc-attempt"),
+    "reattempt must never route to merge-esc-attempt",
+  );
+});
+
+test("a blocked-with-no-push verdict reconciles once from ground truth before escalating", () => {
+  // The `blocked` arm no longer flows straight into the escalation: it passes through gw-ci-blocked.
+  assert(
+    flowHasId("f_ci_blocked", "gw-ci-result", "gw-ci-blocked"),
+    "a blocked verdict must route through gw-ci-blocked, not straight to merge-esc-attempt",
+  );
+
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-ci-blocked"[^>]*>/);
+  assert(gw, "gw-ci-blocked gateway must exist");
+  // Default is escalate (still blocked), so a missing/true reconcile flag never wedges.
+  assertStringIncludes(gw![0], 'default="f_cib_esc"', "gw-ci-blocked must default to escalation");
+
+  // The reconcile-once arm: pushed nothing AND not yet reconciled → re-derive via ci-reconcile.
+  const recon = flowElement("f_cib_recon");
+  assert(recon, "f_cib_recon flow missing");
+  assert(flowHasId("f_cib_recon", "gw-ci-blocked", "ci-reconcile"), "reconcile arm must target ci-reconcile");
+  assertStringIncludes(recon!, "pushed != true", "reconcile only when the agent pushed nothing");
+  assertStringIncludes(recon!, "ciBlockedReconciled != true", "reconcile at most once");
+
+  // The escalate arm (default): still blocked → the human merge escalation.
+  assert(flowHasId("f_cib_esc", "gw-ci-blocked", "merge-esc-attempt"), "the still-blocked arm must escalate");
+  assert(
+    !/conditionExpression/.test(flowElement("f_cib_esc") ?? ""),
+    "f_cib_esc is the default arm and must not carry a conditionExpression",
+  );
+});
+
+test("ci-reconcile re-arms the canonical merge poller and marks the reconcile as spent", () => {
+  const el = serviceTask("ci-reconcile");
+  assert(el, "ci-reconcile service task must exist");
+  // Reuses the canonical arm-merge worker — one poller implementation, no second poller pass.
+  assertStringIncludes(el!, 'type="pr.arm-merge"', "ci-reconcile must reuse the canonical pr.arm-merge worker");
+  // Marks the reconcile spent so the SECOND blocked (still blocked after re-derivation) escalates.
+  const outs = el!.match(/<zeebe:output\b[^>]*\/>/g) ?? [];
+  assert(
+    outs.some((t) => t.includes('target="ciBlockedReconciled"') && t.includes('source="=true"')),
+    "ci-reconcile must set ciBlockedReconciled = true so a still-blocked PR escalates on the next pass",
+  );
+  // Re-derivation flows back through the mergeable wait (re-runs the ground-truth mergeable gate).
+  assert(flowHasId("f_cib_armed", "ci-reconcile", "wait-mergeable"), "ci-reconcile must re-enter wait-mergeable");
+});
+
+test("arm-merge clears the reconcile flag each loop so a fresh block episode gets its own reconcile", () => {
+  const el = serviceTask("arm-merge");
+  assert(el, "arm-merge service task must exist");
+  const outs = el!.match(/<zeebe:output\b[^>]*\/>/g) ?? [];
+  assert(
+    outs.some((t) => t.includes('target="ciBlockedReconciled"') && t.includes('source="=null"')),
+    "arm-merge must reset ciBlockedReconciled each loop so a later, unrelated block still reconciles once",
+  );
+});
+
+test("regression: a stale/transient fix-ci result can no longer page a human", () => {
+  // The old wedge: `status = "blocked"` flowing directly into merge-esc-attempt. The blocked
+  // verdict now routes through gw-ci-blocked (reconcile-before-escalate), never straight to the
+  // escalation.
+  assert(
+    !flowHasId("f_ci_blocked", "gw-ci-result", "merge-esc-attempt"),
+    "the blocked verdict must not route directly into merge-esc-attempt (the #348 phantom escalation)",
+  );
+  // The blocked arm targets the reconcile gateway; the reattempt arm re-arms the poller. Neither
+  // gw-ci-result arm may target the escalation directly.
+  assertStringIncludes(flowElement("f_ci_blocked") ?? "", 'targetRef="gw-ci-blocked"');
+  assertStringIncludes(flowElement("f_ci_reattempt") ?? "", 'targetRef="arm-merge"');
+});

package/app/mergeRebaseArm.test.ts

@@ -118,11 +118,14 @@ test("ci-fix result: a missing/ambiguous status reconciles from ground truth, no
     flowHasId("f_ci_reconcile", "gw-ci-result", "arm-merge"),
     "f_ci_reconcile must default gw-ci-result → arm-merge (reconcile)",
   );
-  // Escalation reserved for the agent's explicit `blocked` verdict.
+  // Escalation reserved for the agent's explicit `blocked` verdict — but now via a
+  // reconcile-before-escalate guard (issue #348): a `blocked` with no push reconciles once from
+  // ground truth, and only a still-blocked PR reaches the human escalation.
   const ciBlocked = flat.match(/<bpmn:sequenceFlow[^>]*id="f_ci_blocked"[\s\S]*?<\/bpmn:sequenceFlow>/);
   assert(ciBlocked, "f_ci_blocked flow missing");
   assertStringIncludes(ciBlocked![0], 'status = "blocked"');
-  assert(hasFlow("gw-ci-result", "merge-esc-attempt"), "gw-ci-result → merge-esc-attempt (blocked) missing");
+  assert(hasFlow("gw-ci-result", "gw-ci-blocked"), "blocked verdict must pass through gw-ci-blocked (reconcile-before-escalate)");
+  assert(hasFlow("gw-ci-blocked", "merge-esc-attempt"), "gw-ci-blocked → merge-esc-attempt (still blocked) missing");
 });
 
 test("regression: the conflict verdict passes through the rebase actor, not straight to escalation", () => {

package/e2e/feature-preflight.e2e.ts

@@ -0,0 +1,191 @@
+// End-to-end proof for the intake-time readiness gate seeded into a single-issue feature run
+// (issue #295). Boots the whole app against the WASM engine + virtual clock and drives the REAL
+// `feature.bpmn` with `readinessProbes` seeded — the exact shape `startFeature` seeds for a gated
+// submission — proving the leading readiness-preflight executes on the engine BEFORE the fan-out
+// head (`ensure-base-branch`) and the implement agent:
+//   • GATED — a feature seeded with a probe that is ready runs the reused `pr.readiness-probe`
+//     worker inside the multi-instance preflight, releases through `pf_gw → pf_end`, and only THEN
+//     reaches `ensure-base-branch` and `implement-task` — it never implements before the gate is
+//     green, and never escalates.
+//   • UNGATED — a feature seeded with `readinessProbes = null` skips the gate entirely
+//     (`gw-readiness → ensure-base-branch`), implementing immediately as today's ungated features do.
+//
+// The probe is a deterministic shell builtin (`true`) with a bound artifact, so the gate itself is
+// hermetic (no network, no GitHub). The fan-out head (`pr.ensure-base-branch`) that follows a green
+// gate is handled by the shared hermetic admit-github stub (installAdmitGithub) like the sibling
+// preflight e2e, so the whole flow runs offline. The implement agent (`senior:feature`) has no
+// worker registered here, so the instance simply parks on `implement-task` after the gate — we
+// assert on the cumulative taken sequence flows (the WASM engine folds completed variables away).
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+const savedEnv = new Map<string, string | undefined>();
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+// The full variable set `startFeature` seeds onto a feature instance (app/feature.ts). We seed it
+// directly so we can inject `readinessProbes` (and the derived `probeTimeout`/`gateKey`) without
+// standing up a whole upstream-dependency set. `baseBranch` is the admit-github default branch, so
+// the fan-out head reads it without creating a ref.
+function featureVars(overrides: Record<string, unknown>): Record<string, unknown> {
+  return {
+    featureKey: "owner/repo#7",
+    repo: "owner/repo",
+    issue: "owner/repo#7",
+    issueNumber: 7,
+    issueUrl: "https://github.com/owner/repo/issues/7",
+    task: {
+      id: "issue-7",
+      title: "owner/repo#7",
+      prompt: "Implement the GitHub issue owner/repo#7 end to end.",
+    },
+    converge: true,
+    autoMerge: false,
+    claimIssue: true,
+    answer: null,
+    status: null,
+    question: null,
+    summary: null,
+    pr: null,
+    escalationSlaTimeout: "PT24H",
+    escalationAssignee: null,
+    baseBranch: "main",
+    baseBranchBrief: "",
+    customInstructions: null,
+    readinessProbes: null,
+    probeTimeout: null,
+    gateKey: null,
+    resolvedArtifacts: null,
+    ...overrides,
+  };
+}
+
+async function boot(): Promise<{ app: TestApp; dbDir: string }> {
+  const dbDir = mkdtempSync(join(tmpdir(), "nwf-feature-preflight-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dbDir, "app.db")}` } });
+  return { app, dbDir };
+}
+
+describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)", () => {
+  let restoreGithub: (() => void) | undefined;
+
+  before(() => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    // `pr.ensure-base-branch` reads the base ref via the token transport, which would throw
+    // `no GitHub transport available` under an empty token. Pin the shared hermetic admit-github
+    // stub (dummy token + fetch intercept) like the sibling preflight e2e so base-branch admission
+    // is deterministic and offline.
+    restoreGithub = installAdmitGithub(admitGithubState("owner/repo", "main"));
+  });
+  after(() => {
+    restoreGithub?.();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  test("GATED: a feature with a green probe parks on the preflight, releases green, and only THEN implements", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      const { processInstanceKey } = await app.engine.createInstance({
+        processDefinitionId: "feature",
+        variables: featureVars({
+          // The shape `startFeature` seeds for a gated submission — here a hermetic green probe that
+          // binds a version, standing in for the `capability` probe (whose green/bind path is
+          // unit-tested in featureReadiness.test).
+          readinessProbes: [
+            {
+              kind: "command",
+              target: "true",
+              resolvedArtifact: "@scope/pkg@1.4.0",
+              poll: { everyMs: 5, timeoutMs: 5000, backoff: "fixed" },
+            },
+          ],
+          probeTimeout: "PT30M",
+          gateKey: "feature-readiness:owner/repo#7",
+        }),
+      });
+      await app.settle();
+
+      const flows = takenFlows(app);
+      // The feature was gated: it entered the preflight (not the ungated skip) and released green.
+      assert.ok(
+        flows.includes("gw-readiness->readiness-preflight"),
+        `a gated feature enters the preflight (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(flows.includes("pf_gw->pf_end"), "the probe went green and settled the preflight");
+      // Only AFTER the gate does it reach ensure-base-branch and then implement-task — the gate is a
+      // true PREFLIGHT, not a parallel afterthought.
+      assert.ok(
+        flows.includes("readiness-preflight->ensure-base-branch"),
+        "the green gate leads into the fan-out head",
+      );
+      assert.ok(
+        flows.includes("ensure-base-branch->implement-task"),
+        `the run reaches the implement agent only after the gate (flows: ${flows.join(", ")})`,
+      );
+      // A green probe never escalates.
+      const tasks = await app.engine.searchUserTasks({ processInstanceKey });
+      assert.equal(
+        tasks.filter((t) => t.elementId === "readiness-escalation-pf").length,
+        0,
+        "a green preflight never opens an escalation task",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("UNGATED: readinessProbes = null skips the gate and implements immediately", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      await app.engine.createInstance({
+        processDefinitionId: "feature",
+        variables: featureVars({ featureKey: "owner/repo#8", issue: "owner/repo#8", readinessProbes: null }),
+      });
+      await app.settle();
+
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("gw-readiness->ensure-base-branch"),
+        `an ungated feature skips straight to the fan-out head (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(!flows.includes("gw-readiness->readiness-preflight"), "an ungated feature never enters the preflight");
+      assert.ok(
+        flows.includes("ensure-base-branch->implement-task"),
+        "an ungated feature reaches the implement agent",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+});

package/openapi.yaml

@@ -1153,12 +1153,65 @@ components:
             Accepted by the schema today but currently has no runtime effect. When implemented it
             will be the required acknowledgement when `baseBranch` names the repository default
             branch. See `PlanStartByIssue.confirmDefaultBase`.
+    ReadinessProbe:
+      description: >-
+        A single durable readiness probe (issue #258, #295) the feature run must satisfy before its
+        implementation agent is dispatched. `kind` selects the source; `target` + `match` are the
+        per-kind predicate. The `capability` kind resolves "which published `pkg@version` first
+        carries capability C?" from publish provenance and late-binds it into the run. See
+        `app/readiness.ts` for the full per-kind semantics.
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - target
+      properties:
+        kind:
+          type: string
+          enum: [http, command, npm, github-check, capability]
+          description: The readiness source. `command` is the escape hatch; `capability` resolves a cross-repo published-artifact edge.
+        target:
+          type: string
+          minLength: 1
+          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, or `github-releases:owner/repo`).
+        onTimeout:
+          type: string
+          enum: [escalate, fail, continue]
+          description: What the gate does when the bounded wait elapses (default `escalate`).
+        credentialEnv:
+          type: string
+          description: A declared env-contract key supplying a credential (http kind only). Names a key, never a secret value.
+        match:
+          type: object
+          additionalProperties: false
+          description: The per-kind readiness predicate; every field is optional and read only by the kinds that understand it.
+          properties:
+            status: { type: integer, description: "http: the exact status that means ready (default any 2xx)." }
+            bodyIncludes: { type: string, description: "http: a substring the response body must contain." }
+            exitCode: { type: integer, description: "command: the exit code that means ready (default 0)." }
+            stdoutIncludes: { type: string, description: "command/npm: a substring stdout must contain." }
+            version: { type: string, description: "npm: the version that must be published." }
+            conclusion: { type: string, description: "github-check: the conclusion that means ready (default success)." }
+            checkName: { type: string, description: "github-check: restrict to the named check run." }
+            capabilityRef: { type: string, description: "capability: the upstream issue/PR handle the resolved version must carry." }
+            package: { type: string, description: "capability: the package whose releases are scanned for provenance." }
+            verifyCommand: { type: string, description: "capability: optional empirical verifier run once at the gate boundary." }
+        poll:
+          type: object
+          additionalProperties: false
+          description: The poll cadence (how often to re-probe, how long to keep trying, and the backoff shape).
+          properties:
+            everyMs: { type: integer, description: Interval between poll attempts (ms). }
+            timeoutMs: { type: integer, description: Bounded budget (ms) before the gate escalates. }
+            backoff: { type: string, enum: [fixed, exponential], description: Backoff shape between attempts. }
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a
         REQUIRED `baseBranch` (ADR 0003, same admission as the epic path), and the two optional
-        follow-on knobs `converge` / `autoMerge`. Modeled as `oneOf` named variants (Camunda REST v2
-        pattern) so an ambiguous or empty target is a 400 at the edge.
+        follow-on knobs `converge` / `autoMerge`. May also carry an intake-time readiness gate
+        (`readiness` and/or `blockedOn` + `consumerPackage`, per issue 295) that parks the run until
+        the declared upstreams land. Modeled as `oneOf` named variants (Camunda REST v2 pattern) so an
+        ambiguous or empty target is a 400 at the edge.
       oneOf:
         - $ref: "#/components/schemas/FeatureStartByIssue"
         - $ref: "#/components/schemas/FeatureStartByUrl"
@@ -1210,6 +1263,36 @@ components:
             OPTIONAL free-text steering appended to the implementation agent's prompt for this run
             (via the implement task's `appendPrompt`). Blank/whitespace is treated as absent. Persists
             on the instance, so it also applies to the agent's answer-loop redispatch.
+        readiness:
+          type: array
+          maxItems: 32
+          items:
+            $ref: "#/components/schemas/ReadinessProbe"
+          description: >-
+            OPTIONAL intake-time readiness gate (issue #295): one or more durable probes the run must
+            ALL satisfy before its implementation agent is dispatched. The run parks (durably, bounded
+            by the gate's escalating timer) at the leading readiness preflight until every probe goes
+            green. Absent/empty ⇒ the run implements immediately, unchanged.
+        blockedOn:
+          type: array
+          maxItems: 32
+          items:
+            type: string
+            minLength: 1
+          description: >-
+            OPTIONAL ergonomic shorthand for `readiness` (issue #295): a list of upstream
+            `owner/repo#123` issue/PR handles the run waits to land. With `consumerPackage` each
+            desugars to a `capability` probe (resolve which published `pkg@version` first carries the
+            handle, and late-bind it into the run); without it, to a `command` probe that goes green
+            once the referenced issue/PR is closed/merged.
+        consumerPackage:
+          type: string
+          minLength: 1
+          description: >-
+            OPTIONAL npm package name (e.g. `@nanobpm/engine-wasm`) the `blockedOn` shorthand resolves
+            its handles against — the consumer dependency whose published provenance must carry each
+            awaited upstream. When present, `blockedOn` desugars to `capability` probes and the
+            resolved `pkg@version` is late-bound into the implementation agent's brief.
     FeatureStartByUrl:
       type: object
       additionalProperties: false
@@ -1246,6 +1329,23 @@ components:
           description: >-
             OPTIONAL free-text steering appended to the implementation agent's prompt for this run.
             See `FeatureStartByIssue.customInstructions`.
+        readiness:
+          type: array
+          maxItems: 32
+          items:
+            $ref: "#/components/schemas/ReadinessProbe"
+          description: OPTIONAL intake-time readiness gate. See `FeatureStartByIssue.readiness`.
+        blockedOn:
+          type: array
+          maxItems: 32
+          items:
+            type: string
+            minLength: 1
+          description: OPTIONAL readiness shorthand — upstream `owner/repo#123` handles to wait on. See `FeatureStartByIssue.blockedOn`.
+        consumerPackage:
+          type: string
+          minLength: 1
+          description: OPTIONAL package the `blockedOn` handles resolve against. See `FeatureStartByIssue.consumerPackage`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startFeature.ts

@@ -13,6 +13,7 @@
 // confirm-default / shared-base rules, with the same typed-error → HTTP mapping.
 
 import { startFeature } from "../app/feature.ts";
+import { parseFeatureReadiness } from "../app/featureReadiness.ts";
 import { BaseBranchMustExistError } from "../app/github.ts";
 import {
   admitPlan,
@@ -22,6 +23,7 @@ import {
   parseIssue,
   SharedBaseError,
 } from "../app/plan.ts";
+import type { ReadinessProbe } from "../app/readiness.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startFeature", async ({ body }, app) => {
@@ -120,13 +122,39 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
     ? body.customInstructions
     : null;
-  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge, customInstructions);
+  // Intake-time readiness gate (issue #295): desugar the optional `readiness` descriptors and/or the
+  // `blockedOn` shorthand (resolved against `consumerPackage`) into the probes + bound the run parks
+  // on before implementing. A malformed gate (bad descriptor, unparseable handle, blank package) is a
+  // 400 at the edge — it must never wait forever at runtime.
+  let readiness: { probes: ReadinessProbe[]; probeTimeout: string | null };
+  try {
+    readiness = parseFeatureReadiness({
+      readiness: "readiness" in body ? body.readiness : undefined,
+      blockedOn: "blockedOn" in body ? body.blockedOn : undefined,
+      consumerPackage: "consumerPackage" in body ? body.consumerPackage : undefined,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "invalid readiness gate";
+    app.log.warn("start-feature rejected: invalid readiness gate", { message });
+    return { status: 400, body: { error: message } };
+  }
+  const result = await startFeature(
+    app.data,
+    app.engine,
+    parsed,
+    normalizedBase,
+    converge,
+    autoMerge,
+    customInstructions,
+    { probes: readiness.probes, probeTimeout: readiness.probeTimeout },
+  );
   app.log.info("feature run started", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
     hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
+    readinessProbes: readiness.probes.length,
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
   });
   return { status: 202, body: result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.102.0",
+  "version": "0.103.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",