@nanobpm/nano-workforce 0.79.0 → 0.81.0

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollIncidentsImpl, repoEnvelopeVars, submitPr } from "./service.ts";
+import { parsePr, pollIncidentsImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -331,6 +331,109 @@ test("submitPr defaults convergeOnly to false so the global auto-merge default g
   });
 });
 
+// Lineage threading (issue #245): `submitPr` persists the origin `root_request_key` on the PR row
+// and carries it onto the convergence instance; `startMerge` reads it back off the row onto the
+// merge instance. A human/webhook submit that supplies no root self-roots on the `pr_key` (its own
+// root), and a resubmit that omits the root must not clobber a root already learned.
+function captureRoot() {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" },
+    escalations: { rows: [], key: "id" },
+    pr_dependencies: { rows: [], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+  let captured: unknown;
+  const engine = {
+    createInstance: (req: { variables?: Record<string, unknown> }) => {
+      captured = req.variables?.rootRequestKey;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  } as any;
+  return { data, engine, stores, get: () => captured };
+}
+
+test("submitPr persists root_request_key and threads it onto the convergence instance", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, get } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 8, url: "https://github.com/owner/repo/pull/8", prKey: "owner/repo#8" },
+      [],
+      20,
+      false,
+      "owner/repo#1",
+    );
+    assertEquals(get(), "owner/repo#1");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.root_request_key, "owner/repo#1");
+  });
+});
+
+test("submitPr self-roots root_request_key on the pr_key for a human/webhook submit (its own root)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, get } = captureRoot();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 9,
+      url: "https://github.com/owner/repo/pull/9",
+      prKey: "owner/repo#9",
+    });
+    assertEquals(get(), "owner/repo#9");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.root_request_key, "owner/repo#9");
+  });
+});
+
+test("submitPr resubmit does not clobber an already-learned root when omitted", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, get } = captureRoot();
+    (stores.pull_requests.rows as unknown[]).push({
+      pr_key: "owner/repo#8",
+      repo: "owner/repo",
+      number: 8,
+      url: "https://github.com/owner/repo/pull/8",
+      status: "abandoned", // terminal -> re-open path
+      current_round: 3,
+      root_request_key: "owner/repo#1",
+    });
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 8,
+      url: "https://github.com/owner/repo/pull/8",
+      prKey: "owner/repo#8",
+    });
+    assertEquals(get(), "owner/repo#1", "resubmit re-threads the learned root");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.root_request_key, "owner/repo#1");
+  });
+});
+
+test("startMerge reads root_request_key off the PR row onto the merge instance", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, get } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 8, url: "https://github.com/owner/repo/pull/8", prKey: "owner/repo#8" },
+      [],
+      20,
+      false,
+      "owner/repo#1",
+    );
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 8,
+      url: "https://github.com/owner/repo/pull/8",
+      prKey: "owner/repo#8",
+      round: 2,
+    });
+    assertEquals(get(), "owner/repo#1");
+  });
+});
+
 // The repository envelope drives the c8ctl harness's isolated workspace provisioning: it is
 // emitted under the reserved `io.nanobpm.agentTask` namespace with the PR head branch as the
 // checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness

package/app/service.ts

@@ -11,6 +11,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
+import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
 import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -26,6 +27,7 @@ import {
   type PrState,
   requestCopilotReview,
 } from "./github.ts";
+import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
@@ -122,77 +124,6 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
 
 const now = () => new Date().toISOString();
 
-/** A PR is "done" in exactly these states; everything else (converging, waiting_review,
- * escalated, and the merge-stage waiting_deps/waiting_merge/waiting_lane/queued) is in flight. `converged`
- * is terminal only in review-only mode (AUTO_MERGE off); with auto-merge on, a converged PR
- * transitions into the merge stage and lands as `merged`. The status endpoint and the cancel
- * guard both key off this set. */
-export const TERMINAL_STATUSES: readonly string[] = ["converged", "merged", "abandoned"];
-
-/** The derived epic delivery signal (issue #171). Distinct from `plan.status`: `status = done`
- * means "the fan-out finished and ≥1 slice opened a PR, dispatched to convergence" (record-results
- * sets it as soon as one PR opened — other slices may be blocked/skipped), which conflates hand-off
- * with landing. `delivery` reports whether those slice PRs have actually MERGED. */
-export type Delivery = "converging" | "landed";
-
-/** Rollup of a plan's slice-PR landing state, derived by joining `plan_tasks.pr_key` →
- * `pull_requests.status`. Pure and read-only — the single source of truth for the denormalised
- * `plans.delivery` / `plans.delivery_label` columns the poller projects. */
-export interface DeliveryRollup {
-  delivery: Delivery | null;
-  label: string | null;
-  prsOpened: number;
-  prsMerged: number;
-  prsInFlight: number;
-}
-
-/** Derive the delivery signal for one plan from its status and the statuses of its slice PRs.
- *
- * - `converging` — the plan is `done` but ≥1 slice PR is still non-terminal (in flight).
- * - `landed` — every slice PR merged: `prsInFlight == 0 && prsMerged == prsOpened && prsOpened > 0`.
- * - `null` — no positive signal yet: the plan isn't `done`, it opened no PRs, or every PR is
- *   terminal but not all merged (some `abandoned`/`converged` — resolved-not-landed, per the issue).
- *
- * A slice's PR status is "in flight" iff it is NOT in `TERMINAL_STATUSES`; `abandoned`/`converged`
- * count as resolved-not-landed (terminal but not merged), so they never make an epic `landed`. */
-export function deriveDelivery(
-  planStatus: string,
-  prStatuses: readonly string[],
-): DeliveryRollup {
-  const prsOpened = prStatuses.length;
-  let prsMerged = 0;
-  let prsInFlight = 0;
-  for (const s of prStatuses) {
-    if (s === "merged") prsMerged++;
-    else if (!TERMINAL_STATUSES.includes(s)) prsInFlight++;
-  }
-  // `delivery` is only meaningful once the fan-out has been dispatched (`status = done`) and at
-  // least one slice PR exists; otherwise there is nothing to have landed yet.
-  if (planStatus !== "done" || prsOpened === 0) {
-    return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
-  }
-  if (prsInFlight > 0) {
-    return {
-      delivery: "converging",
-      label: `${prsMerged}/${prsOpened} slices merged, ${prsInFlight} converging`,
-      prsOpened,
-      prsMerged,
-      prsInFlight,
-    };
-  }
-  if (prsMerged === prsOpened) {
-    return {
-      delivery: "landed",
-      label: `${prsOpened}/${prsOpened} slices merged`,
-      prsOpened,
-      prsMerged,
-      prsInFlight,
-    };
-  }
-  // Every slice PR is terminal but not all merged (some abandoned/converged): resolved, not landed.
-  return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
-}
-
 interface PullRequest {
   pr_key: string;
   repo: string;
@@ -233,6 +164,13 @@ interface PullRequest {
   // workflow stage.
   incident_key: string | null;
   incident_message: string | null;
+  // Lineage projection (037_lineage.sql, issue #245): the stable ORIGIN identity (the issue =
+  // feature_key / plan_key) threaded onto this PR by `submitPr`, and passed as a `createInstance`
+  // variable onto the convergence + merge instances so every descendant carries the root. For a
+  // human-opened / webhook PR with no originating request, `submitPr` self-roots it to its own
+  // `pr_key` so the Lineage UI join resolves; a legacy NULL is tolerated the same way by the
+  // lineage read projection (`pollLineage`), which self-roots on `pr_key`.
+  root_request_key: string | null;
 }
 
 interface PrDependency {
@@ -413,6 +351,7 @@ export async function submitPr(
   dependsOn: string[] = [],
   maxRounds: number = MAX_ROUNDS,
   convergeOnly = false,
+  rootRequestKey: string | null = null,
 ) {
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
@@ -447,6 +386,15 @@ export async function submitPr(
   // Cooperative abandon check (#76): reuse the PR's existing capability token across re-runs (and
   // the later merge instance), or mint one for a first submission.
   const abandonToken = existing?.abandon_token ?? mintAbandonToken();
+  // Lineage (issue #245): the origin identity threaded onto this PR + its convergence/merge
+  // instances. A caller (feature/epic hand-off) supplies it on the first submit; a resubmit that
+  // omits it must not clobber a root already learned, so coalesce onto the existing row's value. A
+  // human/webhook submit supplies none → the PR is its OWN root, so self-root on its `pr_key`
+  // (never NULL): the Lineage page drills into a thread's member PRs by joining
+  // `lineage_threads.root_request_key` → `pull_requests.root_request_key`, and a self-rooted
+  // thread's key IS the `pr_key`, so leaving the PR row NULL would render an empty PR list for it.
+  // Persisting `pr_key` keeps that join honest (the projection self-roots the same key either way).
+  const effectiveRoot = rootRequestKey ?? existing?.root_request_key ?? parsed.prKey;
   if (existing) {
     // A prior run (cancelled, converged, or otherwise superseded) may have left an OPEN
     // escalation row. A fresh convergence run must not inherit that stale answer — the
@@ -474,6 +422,7 @@ export async function submitPr(
       converged_at: null,
       merged_at: null,
       abandon_token: abandonToken,
+      root_request_key: effectiveRoot,
       updated_at: ts,
     });
   } else {
@@ -488,6 +437,7 @@ export async function submitPr(
       status: "converging",
       current_round: 1,
       abandon_token: abandonToken,
+      root_request_key: effectiveRoot,
       created_at: ts,
       updated_at: ts,
     });
@@ -503,6 +453,10 @@ export async function submitPr(
       round: 1,
       maxRounds: clampRounds(maxRounds, MAX_ROUNDS),
       reviewWaitTimeout: REVIEW_WAIT_TIMEOUT,
+      // Lineage (issue #245): carry the origin identity onto the convergence instance so every
+      // descendant (and any message it correlates) is stitched back to the originating request.
+      // A human/webhook PR that is its own root carries its own `pr_key` (never NULL — see above).
+      rootRequestKey: effectiveRoot,
       // Per-request review-only override: carried on the instance so `pr.finalize` can stop at
       // `converged` for this PR without handing off to the merge-loop, independent of the global
       // NANO_PR_AUTO_MERGE default. Only ever narrows (never forces merge on when auto-merge is off).
@@ -539,6 +493,11 @@ export async function startMerge(
   if (!existing?.abandon_token) {
     await prs(data).update(pr.prKey, { abandon_token: abandonToken, updated_at: now() });
   }
+  // Lineage (issue #245): the origin identity was persisted on the PR row at submit; carry it onto
+  // the merge instance too so the merge stage stays stitched to the originating request. A
+  // self-rooted PR carries its own `pr_key`; `?? null` only tolerates a legacy row predating the
+  // column.
+  const rootRequestKey = existing?.root_request_key ?? null;
   const abUrl = abandonUrl(abandonToken);
   // Resolve the PR head branch so the merge agents (fix-ci, rebase) get an isolated clone checked
   // out on it (same host-git provisioning path as review-round). Best-effort: an unresolved head
@@ -566,6 +525,8 @@ export async function startMerge(
       rebaseRound: 0,
       rebaseMax: MAX_REBASE_ROUNDS,
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
+      // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
+      rootRequestKey,
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
@@ -1610,6 +1571,7 @@ export async function pollOnce(
   await pollWaveGates(data, engine, token);
   await pollDelivery(data);
   await pollFeatureDelivery(data);
+  await pollLineage(data);
   await pollFeatureEscalations(data, engine);
   await pollFeatureBlocked(data, engine);
   await pollUserTasks(data, engine);

package/db/migrations/037_lineage.sql

@@ -0,0 +1,69 @@
+-- Lineage projection (issue #245): thread user intent → progress as one arc.
+--
+-- The lineage already exists in the data layer (feature_runs.pr_key ↔ pull_requests.pr_key,
+-- plan_tasks.pr_key ↔ pull_requests.pr_key, and message correlation by prKey/planKey) but is not
+-- projected as a single narrative. This migration adds the two pieces the read model needs:
+--
+--   1. `pull_requests.root_request_key` — the stable ORIGIN identity (the issue = feature_key /
+--      plan_key) threaded onto every PR a request spawns. `submitPr` persists it and passes it as a
+--      `createInstance` variable onto the convergence + merge instances; `startMerge` reads it back
+--      off the row. A human-opened / webhook PR with no originating request is self-rooted by
+--      `submitPr` (`root_request_key = pr_key`); a legacy pre-migration NULL is backfilled below to
+--      the SAME root submitPr would persist (feature/epic origin key, else self-rooted pr_key), and
+--      the projection tolerates any residual NULL by self-rooting on `pr_key`.
+--
+--   2. `lineage_threads` — a DERIVED read table, one row per `root_request_key` (or a self-rooted
+--      PR's own key), recomputed idempotently each poll pass by `pollLineage` (app/lineage.ts) from
+--      the existing gateway joins. It stitches `request → implementation run → PR(s) → convergence →
+--      merge → outcome` into one ordered thread, exposing the active frontier (`stage`/`stage_label`/
+--      `process_key`) plus whether the whole arc has settled (`active`). Urban's datasource cannot
+--      read a SQL VIEW (gateway.ts schema() whitelists only type='table'), so — following the
+--      codebase convention for read-model projections (`plans.delivery`, `feature_runs.delivery_label`)
+--      — this is a denormalised flat table the schema-driven pages read directly.
+--
+-- Forward-only, additive (expand): a nullable column with no default, a new table/indexes, and an
+-- origin-aware backfill of the new column. Numbered after the current highest prefix (036). The
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE pull_requests ADD COLUMN root_request_key TEXT;
+CREATE INDEX IF NOT EXISTS idx_pr_root ON pull_requests(root_request_key);
+
+-- Backfill: every pre-migration PR row has root_request_key = NULL, which breaks the Lineage page's
+-- `lineage_threads.root_request_key → pull_requests.root_request_key` drill-down join (a NULL never
+-- matches a thread key), rendering an empty PR list. Backfill each row with the SAME root `submitPr`
+-- persists going forward, so the join resolves for already-tracked PRs at deploy time too:
+--   1. a PR spawned by a feature run roots on its origin `feature_runs.feature_key` (submitPr passes
+--      `featureKey` — workers/converge-feature);
+--   2. a PR spawned by an epic slice roots on its origin `plan_tasks.plan_key` (submitPr passes
+--      `planKey` — workers/record-wave);
+--   3. any remaining origin-less PR (human/webhook, or an origin row that no longer survives) is
+--      self-rooted on its own `pr_key`, exactly as `submitPr` self-roots a human/webhook PR.
+-- Origin-aware steps run first so a tracked PR keeps its true origin key rather than being self-rooted
+-- (which would orphan it from its feature/epic thread in the drill-down). All idempotent.
+UPDATE pull_requests SET root_request_key = (
+    SELECT fr.feature_key FROM feature_runs fr WHERE fr.pr_key = pull_requests.pr_key
+  )
+  WHERE root_request_key IS NULL
+    AND EXISTS (SELECT 1 FROM feature_runs fr WHERE fr.pr_key = pull_requests.pr_key);
+UPDATE pull_requests SET root_request_key = (
+    SELECT pt.plan_key FROM plan_tasks pt WHERE pt.pr_key = pull_requests.pr_key
+  )
+  WHERE root_request_key IS NULL
+    AND EXISTS (SELECT 1 FROM plan_tasks pt WHERE pt.pr_key = pull_requests.pr_key);
+UPDATE pull_requests SET root_request_key = pr_key WHERE root_request_key IS NULL;
+
+CREATE TABLE IF NOT EXISTS lineage_threads (
+  root_request_key TEXT PRIMARY KEY,        -- origin issue key (feature_key/plan_key), or a self-rooted pr_key
+  kind             TEXT NOT NULL,            -- feature | epic | pr
+  title            TEXT,                     -- best-effort origin/PR title
+  issue_url        TEXT,                     -- origin issue URL (NULL for self-rooted PRs)
+  stage            TEXT NOT NULL,            -- active-frontier machine label (implementing|converging|merged|…)
+  stage_label      TEXT,                     -- human narrative rollup for the timeline
+  process_key      TEXT,                     -- active-frontier process instance (for the processExplorer link)
+  pr_keys          TEXT,                     -- JSON array of the member PR keys (fan-out for epics)
+  pr_count         INTEGER NOT NULL DEFAULT 0,
+  active           INTEGER NOT NULL DEFAULT 1, -- 1 while the arc has an active frontier, 0 once settled
+  created_at       TEXT NOT NULL,
+  updated_at       TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_lineage_active ON lineage_threads(active);

package/e2e/readiness-gate.e2e.ts

@@ -0,0 +1,285 @@
+// End-to-end proof for the durable artifact-readiness wait-gate (ADR 0001 §2, issue #258).
+//
+// Boots this whole Urban app in-process against the WASM engine + virtual clock via `bootTestApp`
+// and drives the real `readiness-gate` process — the reusable primitive: a parallel fork arms the
+// `pr.readiness-probe` service task (an app-hosted worker) alongside an event-based gateway that
+// races the `readiness-ready` message the probe publishes against a bounded timer catch.
+//
+// Two load-bearing behaviours are proven end to end:
+//   • READY — a `command` probe that is green immediately (`true`) drives the probe worker to
+//     publish `readiness-ready`, the gateway correlates it, and the gate releases through
+//     `wait-ready → gate-ready`.
+//   • BOUNDED (the red-first "the wait cannot hang" gate) — a `command` probe that is never green
+//     (`false`) exhausts the worker's local budget WITHOUT publishing; the wait does not hang, and
+//     when the engine timer (the authoritative bound) fires it escalates onto the native
+//     `readiness-escalation` userTask. A gate modelled without the timer arm could never satisfy
+//     this — the token would sit on `wait-ready` forever.
+//
+// The probes are deterministic shell builtins (`true`/`false`) so the flow is hermetic — no
+// network, no GitHub. GitHub transport is still forced offline to match the sibling e2es.
+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";
+
+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}`);
+}
+
+// Each scenario boots its own app so `takenSequenceFlows` (engine-global + cumulative) reflects
+// exactly one instance's history.
+async function boot(): Promise<{ app: TestApp; dbDir: string }> {
+  const dbDir = mkdtempSync(join(tmpdir(), "nwf-readiness-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dbDir, "app.db")}` } });
+  return { app, dbDir };
+}
+
+describe("nano-workforce artifact-readiness wait-gate (readiness-gate.bpmn)", () => {
+  before(() => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+  });
+
+  after(() => {
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  test("READY: a green probe publishes readiness-ready and the gate releases through wait-ready → gate-ready", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      await app.engine.createInstance({
+        processDefinitionId: "readiness-gate",
+        variables: {
+          gateKey: "gate-ready-1",
+          probe: { kind: "command", target: "true", poll: { everyMs: 5, timeoutMs: 5000, backoff: "fixed" } },
+          // A long engine timer that must NOT fire — readiness wins the race first.
+          probeTimeout: "PT30M",
+          onTimeout: "escalate",
+        },
+      });
+      await app.settle();
+
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("wait-ready->gate-ready"),
+        `the gate released on the readiness signal (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(
+        flows.includes("probe->probe-done"),
+        "the probe branch settled after publishing the readiness signal",
+      );
+      // The gate never timed out — no escalation userTask exists.
+      const tasks = await app.engine.searchUserTasks({});
+      assert.equal(
+        tasks.filter((t) => t.elementId === "readiness-escalation").length,
+        0,
+        "a probe that went green never escalates",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("BOUNDED: a never-green probe cannot hang — the engine timer fires and escalates onto the userTask", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      const { processInstanceKey } = await app.engine.createInstance({
+        processDefinitionId: "readiness-gate",
+        variables: {
+          gateKey: "gate-timeout-1",
+          // `false` is never ready; a tiny local budget makes the worker exhaust fast (real time),
+          // leaving the ENGINE timer as the authoritative bound.
+          probe: { kind: "command", target: "false", poll: { everyMs: 5, timeoutMs: 40, backoff: "fixed" } },
+          probeTimeout: "PT1M",
+          onTimeout: "escalate",
+        },
+      });
+      await app.settle();
+
+      // The wait has NOT hung and has NOT yet escalated: the probe branch settled not-ready, and the
+      // gate is parked on the timer catch — no escalation userTask before the timer's duration.
+      const beforeTimer = await app.engine.searchUserTasks({ processInstanceKey });
+      assert.equal(
+        beforeTimer.filter((t) => t.elementId === "readiness-escalation").length,
+        0,
+        "the gate is still bounded-waiting on the timer, not prematurely escalated",
+      );
+      const beforeFlows = takenFlows(app);
+      assert.ok(!beforeFlows.includes("wait-ready->gate-ready"), "a never-green probe never releases as ready");
+
+      // Advancing past the engine timer is the ONLY thing that ends the wait — proving the bound is
+      // engine-owned. The token races off the timer catch onto the escalation userTask.
+      await app.advanceTime(61_000);
+
+      const afterFlows = takenFlows(app);
+      assert.ok(
+        afterFlows.includes("wait-timeout->gw-onTimeout") && afterFlows.includes("gw-onTimeout->readiness-escalation"),
+        `the timer bounded the wait and routed to escalation (flows: ${afterFlows.join(", ")})`,
+      );
+      const escalations = (await app.engine.searchUserTasks({ processInstanceKey })).filter(
+        (t) => t.elementId === "readiness-escalation",
+      );
+      assert.equal(escalations.length, 1, "the bounded timeout opened exactly one escalation userTask");
+
+      // Completing the escalation with `acknowledge` releases the gate to its `escalated` terminal
+      // via the resolution gateway (default arm) — the primitive is fully durable.
+      await app.engine.completeUserTask(escalations[0].userTaskKey, { resolution: "acknowledge" });
+      await app.settle();
+      const ackFlows = takenFlows(app);
+      assert.ok(
+        ackFlows.includes("readiness-escalation->gw-resolution") && ackFlows.includes("gw-resolution->gate-escalated"),
+        "acknowledging the escalation routes through the resolution gateway to gate-escalated",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("ABANDON: an operator who abandons the escalation drives the gate to its `failed` terminal, not `escalated`", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      const { processInstanceKey } = await app.engine.createInstance({
+        processDefinitionId: "readiness-gate",
+        variables: {
+          gateKey: "gate-abandon-1",
+          probe: { kind: "command", target: "false", poll: { everyMs: 5, timeoutMs: 40, backoff: "fixed" } },
+          probeTimeout: "PT1M",
+          onTimeout: "escalate",
+        },
+      });
+      await app.settle();
+      await app.advanceTime(61_000);
+
+      const escalations = (await app.engine.searchUserTasks({ processInstanceKey })).filter(
+        (t) => t.elementId === "readiness-escalation",
+      );
+      assert.equal(escalations.length, 1, "the bounded timeout opened exactly one escalation userTask");
+
+      // `abandon` ("give up on this gate") must NOT be a no-op: it routes to gate-failed, not gate-escalated.
+      await app.engine.completeUserTask(escalations[0].userTaskKey, { resolution: "abandon" });
+      await app.settle();
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("gw-resolution->gate-failed"),
+        `abandoning the escalation routes to gate-failed (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(
+        !flows.includes("gw-resolution->gate-escalated"),
+        "abandon must not reach the escalated terminal",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("onTimeout=continue: a bounded timeout proceeds (no escalation) when the caller declares continue", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      await app.engine.createInstance({
+        processDefinitionId: "readiness-gate",
+        variables: {
+          gateKey: "gate-continue-1",
+          probe: { kind: "command", target: "false", poll: { everyMs: 5, timeoutMs: 40, backoff: "fixed" } },
+          probeTimeout: "PT1M",
+          onTimeout: "continue",
+        },
+      });
+      await app.settle();
+      await app.advanceTime(61_000);
+
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("gw-onTimeout->gate-continued"),
+        `a continue-on-timeout gate proceeds past the bounded wait (flows: ${flows.join(", ")})`,
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("DEFAULT SAFETY: an omitted onTimeout escalates (the gateway default is the safety path, not continue)", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      await app.engine.createInstance({
+        processDefinitionId: "readiness-gate",
+        variables: {
+          gateKey: "gate-default-1",
+          // Neither probe.onTimeout nor a top-level onTimeout is declared.
+          probe: { kind: "command", target: "false", poll: { everyMs: 5, timeoutMs: 40, backoff: "fixed" } },
+          probeTimeout: "PT1M",
+        },
+      });
+      await app.settle();
+      await app.advanceTime(61_000);
+
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("gw-onTimeout->readiness-escalation"),
+        `an omitted onTimeout must default to escalation, never silently continue (flows: ${flows.join(", ")})`,
+      );
+      assert.ok(
+        !flows.includes("gw-onTimeout->gate-continued"),
+        "the safety default must not route to continue",
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+
+  test("probe.onTimeout wins: the descriptor field is preferred over a top-level onTimeout (one source of truth)", async () => {
+    const { app, dbDir } = await boot();
+    try {
+      await app.engine.createInstance({
+        processDefinitionId: "readiness-gate",
+        variables: {
+          gateKey: "gate-probe-pref-1",
+          // The descriptor asks to continue; a stale top-level onTimeout says escalate. probe wins.
+          probe: { kind: "command", target: "false", onTimeout: "continue", poll: { everyMs: 5, timeoutMs: 40, backoff: "fixed" } },
+          probeTimeout: "PT1M",
+          onTimeout: "escalate",
+        },
+      });
+      await app.settle();
+      await app.advanceTime(61_000);
+
+      const flows = takenFlows(app);
+      assert.ok(
+        flows.includes("gw-onTimeout->gate-continued"),
+        `probe.onTimeout ("continue") must win over the top-level onTimeout ("escalate") (flows: ${flows.join(", ")})`,
+      );
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  });
+});

package/nano.app.json

@@ -165,6 +165,10 @@
     {
       "taskType": "pr.converge-gate",
       "handler": "workers/converge-gate/worker.ts"
+    },
+    {
+      "taskType": "pr.readiness-probe",
+      "handler": "workers/readiness-probe/worker.ts"
     }
   ],
   "externalTaskTypes": [