@nanobpm/nano-workforce 0.102.1 → 0.104.0

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

package/app/migration052.test.ts

@@ -0,0 +1,66 @@
+// Regression guard for migration 052 (issue #325, ADR 0062 Slice 5/5): the durable `durable-resume`
+// enrolment registry. The table is FK-free (enrolment is per-worker and connection-agnostic, with no
+// `pull_requests`/`plans` parent), the `instance` PRIMARY KEY makes `recordEnrolment` an idempotent
+// upsert, and `CHECK(durable_resume IN (0,1))` pins the gate's boolean domain.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals, assertThrows } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  // Deliberately NO parent tables — the enrolment table must apply and accept rows on a bare db.
+  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/052_worker_durable_resume.sql", import.meta.url)), "utf8");
+  db.exec(sql);
+  return db;
+}
+
+const upsert = (db: DatabaseSync, instance: string, flag: number) =>
+  db
+    .prepare(
+      `INSERT INTO worker_durable_resume (instance, durable_resume, updated_at) VALUES (?, ?, 't')
+       ON CONFLICT(instance) DO UPDATE SET durable_resume = excluded.durable_resume`,
+    )
+    .run(instance, flag);
+
+test("migration 052 applies cleanly with NO parent tables (FK-free) and records an enrolment", () => {
+  const db = migratedDb();
+  upsert(db, "w1", 1);
+  const row = db.prepare("SELECT instance, durable_resume FROM worker_durable_resume WHERE instance = ?").get("w1") as {
+    instance: string;
+    durable_resume: number;
+  };
+  assertEquals(row.instance, "w1");
+  assertEquals(row.durable_resume, 1);
+});
+
+test("instance PRIMARY KEY makes a re-enrol an upsert (one row per worker, latest flag wins)", () => {
+  const db = migratedDb();
+  upsert(db, "w1", 1);
+  upsert(db, "w1", 0);
+  const count = Number((db.prepare("SELECT COUNT(*) c FROM worker_durable_resume").get() as { c: number }).c);
+  assertEquals(count, 1, "no duplicate row for one instance");
+  const row = db.prepare("SELECT durable_resume FROM worker_durable_resume WHERE instance = 'w1'").get() as { durable_resume: number };
+  assertEquals(row.durable_resume, 0, "the latest enrolment flag wins");
+});
+
+test("durable_resume defaults to 0 (a non-participant) when unset", () => {
+  const db = migratedDb();
+  db.prepare("INSERT INTO worker_durable_resume (instance, updated_at) VALUES ('w1', 't')").run();
+  const row = db.prepare("SELECT durable_resume FROM worker_durable_resume WHERE instance = 'w1'").get() as { durable_resume: number };
+  assertEquals(row.durable_resume, 0);
+});
+
+test("CHECK(durable_resume IN (0,1)): the gate's boolean domain is pinned at the schema", () => {
+  const db = migratedDb();
+  assertThrows(
+    () => db.prepare("INSERT INTO worker_durable_resume (instance, durable_resume, updated_at) VALUES ('w1', 2, 't')").run(),
+    undefined,
+    "CHECK constraint failed",
+  );
+  upsert(db, "yes", 1);
+  upsert(db, "no", 0);
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM worker_durable_resume").get() as { c: number }).c), 2);
+});

package/app/service.test.ts

@@ -7,7 +7,10 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry } from "./durableResume.ts";
+import { WorldStore } from "./world/index.ts";
+import { parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -519,6 +522,35 @@ test("repoEnvelopeVars emits commitSha only for a well-formed 40-hex SHA (world-
   assertEquals("commitSha" in none, false);
 });
 
+// Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): `worldRestoreSha` — the seam
+// `submitPr`/`startMerge` thread into `repoEnvelopeVars` — hands the harness the last push-checkpoint
+// ONLY when the enrolled fleet advertises `durable-resume`. With no participant it degrades to null,
+// so the round redrives from scratch (exactly as today). Proven against a REAL in-memory SQLite db
+// with the world (049) + enrolment (052) schemas applied.
+test("worldRestoreSha is gated on the durable-resume enrolment: participant → SHA, none → null", async () => {
+  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql"]);
+  const PR = "owner/repo#7";
+  const sha = "77ee0993cc6ad4493da0f7551212ef16722135db";
+  await new WorldStore(data).recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: sha });
+
+  // No participant enrolled yet — graceful degradation: no resume marker even though a checkpoint exists.
+  assertEquals(await worldRestoreSha(data, PR), null, "no participant → redrive from scratch");
+
+  // A non-participant enrolment still does not open the gate (a fleet of only non-participants).
+  await new DurableResumeRegistry(data).recordEnrolment("legacy-1", false);
+  assertEquals(await worldRestoreSha(data, PR), null, "only non-participants → still scratch");
+
+  // One participant makes the mixed fleet resume-capable: the checkpoint SHA is now emitted.
+  await new DurableResumeRegistry(data).recordEnrolment("modern-1", true);
+  assertEquals(await worldRestoreSha(data, PR), sha, "a participant → resume at the checkpoint SHA");
+});
+
+test("worldRestoreSha is null when a participant is enrolled but the PR has no checkpoint yet", async () => {
+  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql"]);
+  await new DurableResumeRegistry(data).recordEnrolment("modern-1", true);
+  assertEquals(await worldRestoreSha(data, "owner/repo#8"), null, "nothing to reconstruct on a first activation");
+});
+
 // `parsePr` is total on any input: it is called unguarded from several workers (progress-check,
 // persist-round, persist-escalation, record-dependency) with a process variable that a regression
 // — or an older in-flight instance — could carry as a non-string. `.trim()` on a non-string throws,

package/app/service.ts

@@ -22,6 +22,7 @@ import {
   UnresolvableCapabilityRefError,
 } from "./capabilityNeed.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { backfillFeatureStages, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -441,6 +442,19 @@ async function lastPushedSha(data: DataLayer, prKey: string): Promise<string | n
   }
 }
 
+/** The world-restore SHA to emit into the repo-provisioning envelope for a PR, GATED on the
+ * `durable-resume` enrolment (issue #325, ADR 0062 Slice 5/5). Only when the enrolled fleet includes a
+ * durable-resume participant (`fleetSupportsDurableResume`) do we hand the harness the last
+ * push-checkpoint so a replacement activation RESUMES by reconstructing the exact pushed tree
+ * (inverting `git push` → `git fetch && git checkout <sha>`). With no participant the marker is
+ * omitted (`null`), so the round redrives from scratch — graceful degradation, exactly as today.
+ * Resume is purely additive: gating on the enrolment attribute, not a sequence flow, keeps the
+ * engine/C8 job protocol untouched (ADR 0056 boundary). */
+export async function worldRestoreSha(data: DataLayer, prKey: string): Promise<string | null> {
+  if (!(await fleetSupportsDurableResume(data))) return null;
+  return lastPushedSha(data, prKey);
+}
+
 /** Register a PR row (if new) and start the convergence process. Idempotent on prKey. Optional
  * `dependsOn` (explicit refs) is unioned with any `Depends-on:` line parsed from the PR body and
  * recorded as the PR's merge-stage dependency set. */
@@ -547,9 +561,11 @@ export async function submitPr(
   const abUrl = abandonUrl(abandonToken);
   // World-restore (issue #324, ADR 0062 Slice 4/5): a re-run of convergence for a PR that already
   // pushed is a resume — carry its last durable push-checkpoint so a replacement activation on a
-  // fresh worktree reconstructs the tree to the EXACT pushed SHA. Absent (null) on a first submit,
-  // which leaves the envelope unchanged.
-  const worldSha = await lastPushedSha(data, parsed.prKey);
+  // fresh worktree reconstructs the tree to the EXACT pushed SHA. GATED (issue #325, Slice 5/5) on the
+  // fleet advertising `durable-resume`: with no participant it stays null, so the round redrives from
+  // scratch (graceful degradation). Absent (null) on a first submit, which leaves the envelope
+  // unchanged.
+  const worldSha = await worldRestoreSha(data, parsed.prKey);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: PROCESS_ID,
     variables: {
@@ -623,8 +639,10 @@ export async function startMerge(
     console.warn(`[startMerge] ${pr.prKey} head branch unresolved — merge-agent workspace won't be provisioned`);
   }
   // World-restore (issue #324): the merge stage runs on the same durable working tree; carry the
-  // last push-checkpoint so a replacement fix-ci/rebase activation reconstructs the exact SHA.
-  const worldSha = await lastPushedSha(data, pr.prKey);
+  // last push-checkpoint so a replacement fix-ci/rebase activation reconstructs the exact SHA. GATED
+  // (issue #325, Slice 5/5) on the fleet advertising `durable-resume` — otherwise null, so the merge
+  // agents redrive from scratch (graceful degradation).
+  const worldSha = await worldRestoreSha(data, pr.prKey);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: MERGE_PROCESS_ID,
     variables: {

package/db/migrations/052_worker_durable_resume.sql

@@ -0,0 +1,35 @@
+-- 052_worker_durable_resume.sql — issue #325 (ADR 0062, Slice 5/5): the ENROLMENT GATE for durable
+-- agent-session resume. Slices 1–4 built the mind (harness conversation) and world (git tree + effect
+-- ledger) halves; this slice wires them into the running orchestration behind a `durable-resume`
+-- enrolment gate so a re-leased `senior:pr-review` round RESUMES at the last push-checkpoint on a
+-- participating harness, and gracefully DEGRADES (redriven from scratch, exactly as today) on one
+-- that does not advertise it.
+--
+-- `durable-resume` is a WORKER ATTRIBUTE declared at enrolment (ADR 0056 §7 — capability gates
+-- enrolment, it is NEVER in the routing token `network.role#seat`). The registry records, per worker
+-- instance, whether that worker's harness advertises durable-resume (the probe result from Slice
+-- 2/3). The world-restore `commitSha` is emitted into the repo-provisioning envelope ONLY when the
+-- fleet includes a participant; a fleet with no participant emits no resume marker and clones the
+-- head branch tip — the pre-#324 behaviour. Resume is purely additive, never a new sequence-flow
+-- gate (ADR 0056 boundary): the engine/C8 job protocol is untouched.
+--
+-- One FK-free table keyed by the worker instance (`register.instance` / the enrol `instance`). It is
+-- FK-free by design — enrolment is per-worker and connection-agnostic, with no `pull_requests`/`plans`
+-- parent to reference. EXPAND (additive) phase: one new table + its index; nothing is dropped or
+-- renamed. Numbered after the current highest prefix on origin/main (051). The runner wraps each file
+-- in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE TABLE IF NOT EXISTS worker_durable_resume (
+  instance       TEXT PRIMARY KEY,            -- the worker instance id (enrol `instance` / register.instance)
+  durable_resume INTEGER NOT NULL DEFAULT 0,  -- 1 when the worker's harness advertises durable-resume, else 0
+  updated_at     TEXT NOT NULL,
+  -- `durable_resume` is a strict boolean domain — the gate reads it as "does this worker participate?",
+  -- so a stray value (a future writer bug, a corrupt row on this externalised enrolment boundary) would
+  -- make the gate mis-decide whether to emit the resume marker. Pin it to {0,1} at the schema.
+  CHECK (durable_resume IN (0, 1))
+);
+
+-- The gate asks "does the fleet include a durable-resume participant?" — an existence probe over the
+-- participants. Index the flag so that lookup is a covered scan, not a table walk.
+CREATE INDEX IF NOT EXISTS idx_worker_durable_resume_flag
+  ON worker_durable_resume(durable_resume);

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