@nanobpm/nano-workforce 0.125.0 → 0.127.0

package/docs/adr/0006-delivery-units-one-representation.md

@@ -20,7 +20,7 @@ to collapse three bespoke status unions into one),
 nano-ide **#424** (datasource can read a SQL VIEW — the *data-level* unlock),
 nano-workforce **#416** (the PR bumping the testkit to engine-wasm 0.7.2, which executes `callActivity`
 — the *process-level* unlock),
-nano-workforce **#464** (the tracking issue with slices S1–S5),
+nano-workforce **#464** (the tracking issue with slices S1–S6),
 nano-workforce **#305** (consolidate escalations on native `user_tasks` — a natural sub-step of S1/S3).
 
 ## Context
@@ -89,7 +89,7 @@ because it did nothing. **Unlocked by #416** (engine-wasm 0.4.0 → **0.7.2**).
 **Verified live:** a `callActivity` parent+child model deployed through engine-wasm 0.7.2 runs to
 `COMPLETED`. Caveat: #416 bumps only the **dev-only** `@nanobpm/urban-testkit`; the production
 `@nanobpm/urban` broker does not itself pin `engine-wasm`, so this verification proves the in-process
-testkit, not the broker/runtime that will execute future `callActivity` models. S4/S5 therefore also
+testkit, not the broker/runtime that will execute future `callActivity` models. S4–S6 therefore also
 carry a **deployment-runtime prerequisite** — the deployed broker's `engine-core` must carry the same
 `callActivity` support — which green testkit CI does not by itself guarantee.
 
@@ -129,18 +129,52 @@ a copy — expressed here as the **target** state:
   content digest (`app/deliveryGraphRun.ts` `computeRunKey`) — so S2's compatibility VIEWs map each
   legacy key onto the new identity, ensuring unrelated runs are never merged onto one row.
 
-### 2. Process encoding — shared cells composed by `callActivity`
-
-- Extract the atomic *implement-cell* (and its sibling wait-gate and human-escalation cells) into
-  standalone processes (`resources/processes/implement-cell.bpmn`, …).
-- Compose them by reference — replacing only the inlined *implement/escalation segment*, not the
-  surrounding orchestration: in **feature** (`feature.bpmn`) the readiness preflight, base-branch setup,
-  `record-feature`, and convergence handoff are retained; only the implement-cell segment becomes one
-  `callActivity`. **Epic** = the multi-instance `implement` body is a `callActivity`; **delivery graph**
-  = the compiler *emits* `callActivity` references, not inlined subprocess copies.
+### 2. Process encoding — **fine-grained** cells composed by `callActivity`
+
+The primitive is a set of **small, single-purpose cells** — `implement-cell`, `converge-cell`,
+`merge-cell`, plus the sibling wait-gate and human-escalation cells — each a standalone process
+(`resources/processes/implement-cell.bpmn`, …), composed by reference and gated by edges. This is a
+deliberate choice of granularity **over** a single coarse whole-feature subprocess with opaque
+completion flags.
+
+- Compose by reference, replacing the inlined segments, not the surrounding orchestration: in
+  **feature** (`feature.bpmn`) the readiness preflight, base-branch setup, and `record-feature` remain;
+  the implement/escalation segment and the convergence/merge tail each become `callActivity`s. **Epic**
+  = the multi-instance `implement` body is a `callActivity`; **delivery graph** = the compiler *emits*
+  `callActivity` references, not inlined subprocess copies.
+- `feature` / `epic` are **derived macros** over the cells, not hand-written processes: a `feature`
+  expands to `implement → converge? → merge?`, so the cells stay the single source of truth and the
+  common case is still one node. (Same derivation discipline as the data encoding: compose by
+  reference, never inline a copy.)
+- **Why fine-grained, not coarse.** A coarse whole-feature `callActivity` with `converge?`/`merge?`
+  flags buries those steps *inside* the black box, so a graph can never insert a gate *between*
+  "converged" and "merged". Fine-grained cells let a graph converge features A **and** B, then hold and
+  land both behind a single `human`/`wait` fan-in — the integration-branch / gated-landing pattern.
+  `feature.bpmn` already separates `converge` (its `gw-converge` gateway) from `autoMerge`, so the seam
+  exists today; this promotes it to a **node boundary** the graph can wire (see §3).
 - This is gated on the engine-wasm 0.7.2 unlock, which is now live on `main`.
 
-### 3. Status lifecycle — one derived union
+### 3. Node completion policy — `converge` / `merge` are first-class cells, not smuggled state
+
+Today the "get to green, then land" tail lives in two places the delivery graph cannot reach: a gateway
+*inside* `feature.bpmn` (`gw-converge` + the `autoMerge` boolean on `ConvergeFeatureIn`), and — for a
+delivery-graph `agent` node — **free text in a prompt** (`{ jobType: "senior:feature", prompt: "un-draft
++ merge #B" }`), with the graph only *observing* the result via a downstream `wait` node that emits
+`mergedSha`. A graph therefore drives merge by asking an agent nicely, not structurally. Promote them to
+first-class, edge-gated cells:
+
+- **`converge`** = drive the PR through its review-convergence loop to green. **`merge`** = land it.
+  These are deliberately **separable phases** (`feature.bpmn` already splits `gw-converge` from
+  `autoMerge`), so a graph can stop at "green" and gate the landing behind any upstream node.
+- A `feature`/`epic` node's `converge?` / `merge?` selectors choose whether the derived macro (§2)
+  includes those cells; omitting `merge` and wiring an explicit `merge` cell downstream of a gate is the
+  advanced case.
+- **`merge` is two-level (ADR 0003 base-branch admission).** A unit's `merge` cell lands onto the
+  epic/graph **base branch**, never `main` directly; the graph's final merge-to-`main` is a *separate*
+  top-level step. `feature.bpmn`'s `autoMerge` is exactly this per-unit knob — do not collapse the two
+  levels.
+
+### 4. Status lifecycle — one derived union
 
 The three bespoke status unions collapse into **one derived union** via ADR 0065's `defineReadModel`,
 so a change to lifecycle semantics is made once and derived everywhere, not re-declared per
@@ -153,7 +187,7 @@ representation. These unions are **not** identical today — features use
 separate node contract — plus the per-shape mapping and precedence and the write/`instanceTracking`
 behavior — not merely projecting an existing value.
 
-### 4. Preserve — the static-vs-adaptive execution axis (do NOT bundle it)
+### 5. Preserve — the static-vs-adaptive execution axis (do NOT bundle it)
 
 This ADR consolidates the *representation*, not the *execution strategy*. ADR 0005's deliberate
 distinction stays intact: **plan-fanout remains adaptive** (agent-discovered slices, waves that adapt),
@@ -183,8 +217,8 @@ their topology is produced. Unifying that axis is explicitly out of scope here.
 
 ## Rollout (see #464 for the live checklist)
 
-Each slice is independently shippable; the process slices (S4/S5) are sequenced behind the engine-wasm
-0.7.2 unlock. The **dev-testkit** side of that unlock has landed (#416, verified in-process above); S4/S5
+Each slice is independently shippable; the process slices (S4–S6) are sequenced behind the engine-wasm
+0.7.2 unlock. The **dev-testkit** side of that unlock has landed (#416, verified in-process above); S4–S6
 additionally gate on the **deployed broker/runtime** carrying verified `callActivity` support (the
 deployment-runtime prerequisite noted above), not on #416 alone.
 
@@ -207,15 +241,20 @@ deployment-runtime prerequisite noted above), not on #416 alone.
   bindings and every other writer off the legacy tables does the table-to-VIEW contract phase retire the
   legacy write paths.
 - **S3 · collapse doors** — unify the three `instanceTracking` bindings + `senior:*` dispatch doors.
-- **S4 · shared cells** — extract the atomic `implement-cell.bpmn` **and its sibling wait-gate and
-  human-escalation cells** (Decision §2) into standalone processes; `feature.bpmn` + the `plan-fanout`
-  MI body compose them via `callActivity`.
-- **S5 · compiler emits calls** — `deliveryGraphCompiler` references shared cells instead of inlining
+- **S4 · fine-grained cells** — extract `implement-cell.bpmn`, `converge-cell.bpmn`, `merge-cell.bpmn`
+  **and the sibling wait-gate and human-escalation cells** (Decision §2) into standalone processes;
+  `feature.bpmn` + the `plan-fanout` MI body compose them via `callActivity`, with `feature`/`epic` as
+  derived macros over the cells.
+- **S5 · `converge?` / `merge?` as first-class node policy** — promote convergence + landing from the
+  `feature.bpmn` `gw-converge`/`autoMerge` gateway and the delivery-graph *prompt prose* into edge-gated
+  `converge`/`merge` cell nodes on the delivery vocabulary (Decision §3); honour ADR 0003 two-level
+  merge (unit → base branch; graph → `main`).
+- **S6 · compiler emits calls** — `deliveryGraphCompiler` references shared cells instead of inlining
   per-node copies.
 
 ## Non-goals / deferred
 
-- **Unifying the static-vs-adaptive execution axis** (see Decision §4) — preserved deliberately.
+- **Unifying the static-vs-adaptive execution axis** (see Decision §5) — preserved deliberately.
 - **Changing the downstream PR/convergence loop** — already single-sourced (`pull_requests`); untouched.
 - **Cross-repo/platform representation** — this ADR is nano-workforce-local; any platform-wide delivery
   aggregate would be a separate nano-bpm ADR.

package/e2e/delivery-graph.e2e.ts

@@ -24,6 +24,7 @@ import { connectorDedupeKey, deliveryConnectorDispatches, dispatchConnector } fr
 import { readConnectorInput } from "../workers/delivery-connector/worker.ts";
 import { runDeliveryGraph } from "../app/deliveryRunner.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { deterministicProbeSeam } from "./support/probe-exec.ts";
 
 const APP_ROOT = resolve(import.meta.dirname, "..");
 const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
@@ -57,9 +58,15 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
     apps.push(app);
     return app;
   };
+  // The `wait` nodes drive `command: true`/`false` probes through the shared readiness-probe worker.
+  // Inject the deterministic exec so they resolve within the virtual clock's drain fixpoint instead
+  // of racing a real subprocess `settle()` cannot await (issue #450).
+  const probeSeam = deterministicProbeSeam("delivery-graph e2e");
+  before(() => probeSeam.install());
   after(async () => {
     for (const app of apps) await app.stop?.();
     for (const d of dirs) rmSync(d, { recursive: true, force: true });
+    probeSeam.restoreAndAssertHermetic();
   });
 
   test("runs end-to-end: agent, wait, human execute; edges gate; fan-in works; human fact late-binds into the connector", async () => {

package/e2e/feature-preflight.e2e.ts

@@ -24,6 +24,7 @@ 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";
+import { deterministicProbeSeam } from "./support/probe-exec.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -92,12 +93,17 @@ async function boot(): Promise<{ app: TestApp; dbDir: string }> {
 
 describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)", () => {
   let restoreGithub: (() => void) | undefined;
+  const probeSeam = deterministicProbeSeam("feature-preflight e2e");
 
   before(() => {
     for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
       savedEnv.set(k, process.env[k]);
       process.env[k] = v;
     }
+    // Inject the deterministic probe exec so the `command: true` probe resolves WITHIN the virtual
+    // clock's drain fixpoint instead of spawning a real subprocess whose wall-clock completion
+    // `settle()` cannot await — the flake behind this suite (issue #450).
+    probeSeam.install();
     // `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
@@ -106,6 +112,7 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
   });
   after(() => {
     restoreGithub?.();
+    probeSeam.restoreAndAssertHermetic();
     for (const [k, v] of savedEnv) {
       if (v === undefined) delete process.env[k];
       else process.env[k] = v;

package/e2e/inter-epic-dependency.e2e.ts

@@ -23,6 +23,7 @@ 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";
+import { deterministicProbeSeam } from "./support/probe-exec.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -89,8 +90,14 @@ async function boot(): Promise<{ app: TestApp; dbDir: string }> {
 
 describe("inter-epic capability gate — adversarial (plan-fanout.bpmn, issue #292 S5)", () => {
   let restoreGithub: (() => void) | undefined;
+  // The adversarial gates poll `command: false` (never-green) probes through the readiness-probe
+  // worker; inject the deterministic exec so each poll resolves inside the virtual clock's drain
+  // fixpoint (the escalation/timeout path is driven by engine-clock advancement, not a real
+  // subprocess) — issue #450.
+  const probeSeam = deterministicProbeSeam("inter-epic adversarial e2e");
 
   before(() => {
+    probeSeam.install();
     for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
       savedEnv.set(k, process.env[k]);
       process.env[k] = v;
@@ -105,6 +112,7 @@ describe("inter-epic capability gate — adversarial (plan-fanout.bpmn, issue #2
       if (v === undefined) delete process.env[k];
       else process.env[k] = v;
     }
+    probeSeam.restoreAndAssertHermetic();
   });
 
   // ── S5 P1 — the gate HOLDS wave 0 ───────────────────────────────────────────────────────────────

package/e2e/plan-fanout-preflight.e2e.ts

@@ -22,6 +22,7 @@ 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";
+import { deterministicProbeSeam } from "./support/probe-exec.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -80,12 +81,17 @@ async function boot(): Promise<{ app: TestApp; dbDir: string }> {
 
 describe("plan-fanout inter-epic capability preflight (plan-fanout.bpmn, issue #292 S3)", () => {
   let restoreGithub: (() => void) | undefined;
+  const probeSeam = deterministicProbeSeam("plan-fanout-preflight e2e");
 
   before(() => {
     for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
       savedEnv.set(k, process.env[k]);
       process.env[k] = v;
     }
+    // Inject the deterministic probe exec so the `command: true` probe resolves WITHIN the virtual
+    // clock's drain fixpoint instead of spawning a real subprocess whose wall-clock completion
+    // `settle()` cannot await — the flake behind this suite (issue #450).
+    probeSeam.install();
     // The fan-out head (`pr.ensure-base-branch`, ADR 0003) reads/creates 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 plan-fanout
@@ -94,6 +100,7 @@ describe("plan-fanout inter-epic capability preflight (plan-fanout.bpmn, issue #
   });
   after(() => {
     restoreGithub?.();
+    probeSeam.restoreAndAssertHermetic();
     for (const [k, v] of savedEnv) {
       if (v === undefined) delete process.env[k];
       else process.env[k] = v;

package/e2e/plan-fanout-sla.e2e.ts

@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+import { advancePastTimer } from "./support/time.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -154,7 +155,7 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
 
         // Never answer — let the SLA elapse. The interrupting boundary cancels the parked task and
         // routes to the task-done end (the safe auto-abandon default).
-        await app.advanceTime(PAST_SLA_MS);
+        await advancePastTimer(app, PAST_SLA_MS);
 
         const flows = takenFlows(app);
         assert.ok(
@@ -180,7 +181,7 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
         await openTask(app, processKey, "plan-review-decision");
         await assertAssignmentFilterable(app, processKey, "plan-review-decision");
 
-        await app.advanceTime(PAST_SLA_MS);
+        await advancePastTimer(app, PAST_SLA_MS);
 
         const flows = takenFlows(app);
         assert.ok(
@@ -221,7 +222,7 @@ describe("plan-fanout escalation SLA + assignment (U5)", () => {
         await openTask(app, processKey, "trial-merge-decision");
         await assertAssignmentFilterable(app, processKey, "trial-merge-decision");
 
-        await app.advanceTime(PAST_SLA_MS);
+        await advancePastTimer(app, PAST_SLA_MS);
 
         const flows = takenFlows(app);
         assert.ok(

package/e2e/plan-fanout.e2e.ts

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+import { advancePastTimer } from "./support/time.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -413,8 +414,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
 
         // Never publish caps-resolved — let the bound (default P1D) elapse. Advancing past it is the
         // ONLY way the token can move, so this proves the wait is genuinely bounded.
-        await app.advanceTime(25 * 60 * 60 * 1000);
-        await app.settle();
+        await advancePastTimer(app, 25 * 60 * 60 * 1000);
 
         const flows = takenFlows(app);
         assert.ok(

package/e2e/readiness-gate.e2e.ts

@@ -23,34 +23,7 @@ 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 type { CommandResult, ProbeExec } from "../app/readiness.ts";
-import { __setProbeExecForTest } from "../workers/readiness-probe/worker.ts";
-
-// A synchronous, in-memory ProbeExec so the probe resolves WITHIN the testkit's virtual-clock drain
-// fixpoint instead of spawning a REAL subprocess (real-time work `settle()` cannot deterministically
-// await — issue #450). It maps the hermetic shell builtins these scenarios use to a deterministic
-// `CommandResult` — `true` → exit 0 (green), `false` → exit 1 (never green) — mirroring the real
-// commands' semantics exactly, but with zero real time. Any OTHER command, or any HTTP call, is an
-// unintended probe escape: because `probeSingleShot` catches a thrown/rejected probe error and folds
-// it into a silent "not ready", an escape would otherwise be INVISIBLE and could let a bounded
-// not-ready scenario still pass, masking a regression (reviewer note). So we record every escape and
-// assert none occurred in teardown, failing the suite loudly instead of swallowing it.
-const unexpectedProbeIO: string[] = [];
-const deterministicExec: ProbeExec = {
-  run(command: string): Promise<CommandResult> {
-    const cmd = command.trim();
-    if (cmd !== "true" && cmd !== "false") {
-      unexpectedProbeIO.push(`command: ${cmd}`);
-      return Promise.resolve({ code: 127, stdout: "", stderr: "" });
-    }
-    const code = cmd === "true" ? 0 : 1;
-    return Promise.resolve({ code, stdout: "", stderr: "" });
-  },
-  httpGet(url: string): Promise<never> {
-    unexpectedProbeIO.push(`http: ${url}`);
-    return Promise.reject(new Error(`readiness-gate e2e: unexpected real HTTP probe (command probes only)`));
-  },
-};
+import { deterministicProbeSeam } from "./support/probe-exec.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 let dbSeq = 0;
@@ -60,7 +33,7 @@ const GITHUB_ENV_OVERRIDES: Record<string, string> = {
   GITHUB_TOKEN: "",
 };
 const savedEnv = new Map<string, string | undefined>();
-let savedProbeExec: ProbeExec | undefined;
+const probeSeam = deterministicProbeSeam("readiness-gate e2e");
 
 interface TakenFlow {
   from: string;
@@ -94,7 +67,7 @@ describe("nano-workforce artifact-readiness wait-gate (readiness-gate.bpmn)", ()
     // clock (issue #450). Scenario-agnostic: it maps each scenario's command by string. Capture the
     // prior override and restore exactly that in teardown, so the seam is restored to its real prior
     // state rather than assuming production.
-    savedProbeExec = __setProbeExecForTest(deterministicExec);
+    probeSeam.install();
   });
 
   after(() => {
@@ -102,13 +75,11 @@ describe("nano-workforce artifact-readiness wait-gate (readiness-gate.bpmn)", ()
       if (v === undefined) delete process.env[k];
       else process.env[k] = v;
     }
-    // Restore the prior exec — the seam must never outlive this suite.
-    __setProbeExecForTest(savedProbeExec);
-    // Fail loudly if the probe ever escaped the hermetic `true`/`false` builtins (an unexpected
-    // command or any HTTP call). `probeSingleShot` folds a probe error into a silent "not ready", so
-    // without this assertion an escape would be invisible and could let a bounded not-ready scenario
-    // still pass, masking a regression.
-    assert.deepEqual(unexpectedProbeIO, [], `readiness-gate e2e saw unexpected probe I/O: ${unexpectedProbeIO.join(", ")}`);
+    // Restore the prior exec (the seam must never outlive this suite) and fail loudly if the probe
+    // ever escaped the hermetic `true`/`false` builtins — `probeSingleShot` folds a probe error into
+    // a silent "not ready", so without this an escape would be invisible and could let a bounded
+    // not-ready scenario still pass, masking a regression.
+    probeSeam.restoreAndAssertHermetic();
   });
 
   test("READY: a green probe publishes readiness-ready and the gate releases through wait-ready → gate-ready", async () => {

package/e2e/support/probe-exec.test.ts

@@ -0,0 +1,78 @@
+// Negative-path coverage for the deterministic probe seam (e2e/support/probe-exec.ts).
+//
+// The wired readiness-gate suites only ever route the hermetic `true`/`false` builtins through the
+// seam, so a regression in RECORDING or REJECTING an unexpected command/HTTP call — the seam's whole
+// reason to exist — would leave every one of them green while silently swallowing an escape. This
+// exercises the escape contract directly: a non-hermetic command or a real HTTP probe must be
+// recorded and make `restoreAndAssertHermetic()` fail, and the recorded escape must never leak the
+// raw command or a URL's credential material into the teardown assertion (ADR 0004 pinned
+// decision 2 — mirrors production `redactTarget`).
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { __setProbeExecForTest } from "../../workers/readiness-probe/worker.ts";
+import { deterministicProbeSeam } from "./probe-exec.ts";
+
+/** Install the seam, then hand back the exact `ProbeExec` it wired into the worker so a test can
+ *  route probes through the real installed seam (not a private copy). Uses the documented
+ *  set-returns-previous contract of `__setProbeExecForTest` to read the current override, then puts
+ *  it straight back so the seam's own restore still returns the DB to the prior exec. */
+function installAndCaptureExec(seam: ReturnType<typeof deterministicProbeSeam>) {
+  seam.install();
+  const installed = __setProbeExecForTest(undefined);
+  assert.ok(installed, "install() must have wired a ProbeExec into the worker");
+  __setProbeExecForTest(installed);
+  return installed;
+}
+
+test("hermetic true/false probes leave the seam clean", async () => {
+  const seam = deterministicProbeSeam("hermetic");
+  const exec = installAndCaptureExec(seam);
+
+  assert.deepEqual(await exec.run("true", {}), { code: 0, stdout: "", stderr: "" });
+  assert.deepEqual(await exec.run("false", {}), { code: 1, stdout: "", stderr: "" });
+
+  // No escape recorded — teardown passes.
+  seam.restoreAndAssertHermetic();
+});
+
+test("a non-hermetic command escapes, fails teardown, and never leaks the raw command", async () => {
+  const seam = deterministicProbeSeam("cmd-escape");
+  const exec = installAndCaptureExec(seam);
+
+  const secret = "curl https://user:supersecret@host/health?token=abc123";
+  const result = await exec.run(secret, {});
+  // The escaping command still resolves to a non-green result so a bounded not-ready scenario holds.
+  assert.equal(result.code, 127);
+
+  assert.throws(
+    () => seam.restoreAndAssertHermetic(),
+    (err: unknown) => {
+      const msg = String(err);
+      assert.match(msg, /cmd-escape saw unexpected probe I\/O/);
+      assert.doesNotMatch(msg, /supersecret/, "the credential must never reach teardown output");
+      assert.doesNotMatch(msg, /abc123/, "the token must never reach teardown output");
+      return true;
+    },
+  );
+});
+
+test("a real HTTP probe escapes, fails teardown, and redacts the URL's credential material", async () => {
+  const seam = deterministicProbeSeam("http-escape");
+  const exec = installAndCaptureExec(seam);
+
+  await assert.rejects(
+    exec.httpGet("https://user:tok@host/ready?apikey=zzz999", {}),
+    /http-escape: unexpected real HTTP probe/,
+  );
+
+  assert.throws(
+    () => seam.restoreAndAssertHermetic(),
+    (err: unknown) => {
+      const msg = String(err);
+      assert.match(msg, /http-escape saw unexpected probe I\/O/);
+      assert.doesNotMatch(msg, /zzz999/, "the query token must never reach teardown output");
+      assert.doesNotMatch(msg, /user:tok/, "the userinfo credential must never reach teardown output");
+      return true;
+    },
+  );
+});

package/e2e/support/probe-exec.ts

@@ -0,0 +1,69 @@
+// Deterministic readiness-probe exec for e2es driven by the testkit's VIRTUAL clock (issue #450).
+//
+// Production `defaultProbeExec` (app/readiness.ts) runs a `command` probe as a REAL
+// `node:child_process` subprocess. That subprocess resolves on the wall clock, spanning macrotasks
+// the urban-testkit's virtual-clock `settle()`/`drain()` fixpoint cannot deterministically await —
+// so `settle()` can return BEFORE the probe publishes `readiness-ready`, and a gate-flow assertion
+// (e.g. `pf_gw->pf_end`) races the subprocess. That race is the flake behind feature-preflight /
+// plan-fanout-preflight failing intermittently (green probe logged, gate flow not yet taken).
+//
+// This seam injects a synchronous, in-memory `ProbeExec` (via the worker's `__setProbeExecForTest`)
+// so the probe resolves WITHIN the drain fixpoint — no real spawn, no wall-clock race. It maps the
+// hermetic shell builtins the gate e2es use to a deterministic `CommandResult` — `true` → exit 0
+// (green), `false` → exit 1 (never green) — mirroring the real commands exactly, with zero real time.
+//
+// Any OTHER command, or any HTTP call, is an unintended probe escape: `probeSingleShot` folds a
+// thrown/rejected probe error into a silent "not ready", so an escape would be INVISIBLE and could
+// let a bounded not-ready scenario still pass, masking a regression. Every escape is recorded and
+// asserted-none in teardown, failing the suite loudly instead of swallowing it.
+//
+// Single source of truth shared by every readiness-gate e2e (readiness-gate, feature-preflight,
+// plan-fanout-preflight, delivery-graph, inter-epic-dependency) so the deterministic-exec contract
+// can never drift between them.
+import assert from "node:assert/strict";
+import { type CommandResult, type ProbeExec, redactString } from "../../app/readiness.ts";
+import { __setProbeExecForTest } from "../../workers/readiness-probe/worker.ts";
+
+export interface DeterministicProbeSeam {
+  /** Install the deterministic exec — call once in the suite's `before`. */
+  install(): void;
+  /** Restore the prior exec and assert no probe escaped the hermetic `true`/`false` builtins — call
+   *  once in the suite's `after`. */
+  restoreAndAssertHermetic(): void;
+}
+
+/** Build a deterministic probe seam scoped to one suite. `label` is used in the escape assertion
+ *  message and the unexpected-HTTP error, so a failure names the offending suite. */
+export function deterministicProbeSeam(label: string): DeterministicProbeSeam {
+  const escapes: string[] = [];
+  const exec: ProbeExec = {
+    run(command: string): Promise<CommandResult> {
+      const cmd = command.trim();
+      if (cmd !== "true" && cmd !== "false") {
+        // A `command` target is an arbitrary shell snippet that can embed a secret, so — exactly as
+        // production `redactTarget` does (app/readiness.ts, ADR 0004 pinned decision 2) — record only
+        // a fixed placeholder, never the raw command, so an escape can't leak credentials into the
+        // teardown assertion at `restoreAndAssertHermetic()`.
+        escapes.push("command: <redacted>");
+        return Promise.resolve({ code: 127, stdout: "", stderr: "" });
+      }
+      return Promise.resolve({ code: cmd === "true" ? 0 : 1, stdout: "", stderr: "" });
+    },
+    httpGet(url: string): Promise<never> {
+      // A probe URL can carry a token in its userinfo or query string; strip those before recording.
+      escapes.push(`http: ${redactString(url)}`);
+      return Promise.reject(new Error(`${label}: unexpected real HTTP probe (command probes only)`));
+    },
+  };
+  let saved: ProbeExec | undefined;
+  return {
+    install() {
+      saved = __setProbeExecForTest(exec);
+    },
+    restoreAndAssertHermetic() {
+      // Restore the prior exec first — the seam must never outlive this suite.
+      __setProbeExecForTest(saved);
+      assert.deepEqual(escapes, [], `${label} saw unexpected probe I/O: ${escapes.join(", ")}`);
+    },
+  };
+}

package/e2e/support/time.test.ts

@@ -0,0 +1,42 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { advancePastTimer } from "./time.ts";
+
+// Guards the defect class behind issue #474: a long BPMN business-wait must be crossed by advancing
+// the ENGINE clock (fire the boundary timer) + one reconcile settle — NOT by `app.advanceTime`,
+// which steps the scheduler in lockstep and replays every 5s runtime-cadence poll across the window
+// (~18,000× for a 25h jump; ~123s of no-op churn). This pins the mechanism so a regression back to
+// the lockstep path — or an added `scheduler.advance` — fails here instead of silently re-slowing CI.
+test("advancePastTimer advances the engine clock then settles once, never replaying scheduler cadence", async () => {
+  const PAST_SLA_MS = 25 * 60 * 60 * 1000;
+  const calls: string[] = [];
+  let engineMs: number | undefined;
+
+  const app = {
+    engine: {
+      advanceTime: async (ms: number) => {
+        engineMs = ms;
+        calls.push("engine.advanceTime");
+      },
+    },
+    settle: async () => {
+      calls.push("settle");
+    },
+    // Present only to catch a regression: touching the scheduler's own `advance` is the slow
+    // lockstep replay path the helper exists to avoid, so it must never be called.
+    scheduler: {
+      advance: async () => {
+        calls.push("scheduler.advance");
+      },
+    },
+  } as unknown as Parameters<typeof advancePastTimer>[0];
+
+  await advancePastTimer(app, PAST_SLA_MS);
+
+  assert.deepEqual(
+    calls,
+    ["engine.advanceTime", "settle"],
+    "the engine boundary fires, then exactly one reconcile settle — the scheduler cadence is never replayed",
+  );
+  assert.equal(engineMs, PAST_SLA_MS, "the full business-wait window is applied to the engine clock");
+});

package/e2e/support/time.ts

@@ -0,0 +1,33 @@
+import type { TestApp } from "@nanobpm/urban-testkit";
+
+/**
+ * Advance a long BPMN **business-wait** boundary timer and reconcile once.
+ *
+ * A business wait — "park at this task until the 24h SLA elapses, then auto-escalate" — is
+ * modelled as a BPMN interrupting boundary timer on the ENGINE clock: durable, engine-owned, and
+ * already virtual under the engine clock. This is the line camunda/orchestration-cluster-api-js#450
+ * draws: *"Long/business waits are BPMN timer events … not [runtime-cadence] `sleep`/poll."* To
+ * cross such a wait we advance the ENGINE clock so the boundary fires, then {@link TestApp.settle}
+ * once to drain the follow-on token flow.
+ *
+ * This deliberately does **not** call {@link TestApp.advanceTime}, which steps the virtual-clock
+ * scheduler in lockstep with the engine and therefore REPLAYS every short runtime-cadence poll —
+ * the 5s `instanceTracking` reconcilers — once per interval across the whole window. A 25h jump
+ * replays each poller ~18,000× (measured: ~123s of pure no-op reconcile churn *per call*, which is
+ * essentially the entire e2e wall-clock). Those replays are runtime cadence, not the business wait,
+ * and #450 treats such busy-replays as a bug to *surface*, not to coalesce away in the scheduler.
+ * Advancing engine time + one settle fires the same boundary in ~2ms.
+ *
+ * Use ONLY when the assertions target **engine state** — taken sequence-flows (`app.snapshot()`) or
+ * instance state — which is populated by `engine.advanceTime` + `engine.drain` (run inside
+ * `settle`). Do NOT use it when an assertion depends on a **read model the reconcile pollers
+ * project**: for that the pollers must actually run, so use {@link TestApp.advanceTime}. The
+ * scheduler's virtual clock intentionally does not track this jump.
+ */
+export async function advancePastTimer(
+  app: Pick<TestApp, "engine" | "settle">,
+  ms: number,
+): Promise<void> {
+  await app.engine.advanceTime(ms);
+  await app.settle();
+}