@nanobpm/nano-workforce 0.120.0 → 0.120.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.120.1](https://github.com/nanobpm/nano-workforce/compare/v0.120.0...v0.120.1) (2026-08-22)
+
+
+### Bug Fixes
+
+* **readiness:** make pr.readiness-probe single-shot; engine owns retry cadence ([#428](https://github.com/nanobpm/nano-workforce/issues/428)) ([#429](https://github.com/nanobpm/nano-workforce/issues/429)) ([07db031](https://github.com/nanobpm/nano-workforce/commit/07db031f0d5e3f63ff47ffa51583bdef3012a2ab))
+
 # [0.120.0](https://github.com/nanobpm/nano-workforce/compare/v0.119.0...v0.120.0) (2026-08-22)
 
 

package/app/capabilityNeed.test.ts

@@ -106,9 +106,11 @@ test("capabilityNeedToProbeInput: maps a need to the readiness-gate capability p
     planKey: "owner/repo#289",
     taskId: "issue-289",
     probeTimeout: "PT12H",
+    probePollEvery: "PT15S",
   });
   assertEquals(input.gateKey, "owner/repo#289:issue-289:nanobpm/nano-ide#274:@nanobpm/urban");
   assertEquals(input.probeTimeout, "PT12H");
+  assertEquals(input.probePollEvery, "PT15S");
   assertEquals(input.onTimeout, "escalate");
   assertEquals(input.probe.kind, "capability");
   assertEquals(input.probe.target, "github-releases:nanobpm/nano-ide");
@@ -121,7 +123,7 @@ test("capabilityNeedToProbeInput: maps a need to the readiness-gate capability p
 test("capabilityNeedToProbeInput: omits verifyCommand when the need has none", () => {
   const input = capabilityNeedToProbeInput(
     { capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban" },
-    { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H" },
+    { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H", probePollEvery: "PT15S" },
   );
   assertEquals(input.probe.match?.verifyCommand, undefined);
 });
@@ -131,7 +133,7 @@ test("capabilityNeedToProbeInput: throws when the handle names no releases sourc
     () =>
       capabilityNeedToProbeInput(
         { capabilityRef: "#274", package: "@nanobpm/urban" },
-        { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H" },
+        { planKey: "o/r#1", taskId: "t1", probeTimeout: "PT1H", probePollEvery: "PT15S" },
       ),
     UnresolvableCapabilityRefError,
     "names no owner/repo releases source",

package/app/capabilityNeed.ts

@@ -36,6 +36,7 @@ export interface CapabilityNeed {
 export interface ReadinessProbeInput {
   readonly gateKey: string;
   readonly probeTimeout: string;
+  readonly probePollEvery: string;
   readonly onTimeout?: OnTimeout;
   readonly probe: ReadinessProbe;
 }
@@ -152,7 +153,7 @@ export function capabilityTaskBarrierKey(planKey: string, taskId: string): strin
  * the handle names no releases source. */
 export function capabilityNeedToProbeInput(
   need: CapabilityNeed,
-  opts: { planKey: string; taskId: string; probeTimeout: string },
+  opts: { planKey: string; taskId: string; probeTimeout: string; probePollEvery: string },
 ): ReadinessProbeInput {
   const repo = capabilityReleasesRepo(need.capabilityRef);
   if (!repo) throw new UnresolvableCapabilityRefError(need.capabilityRef);
@@ -170,6 +171,7 @@ export function capabilityNeedToProbeInput(
   return {
     gateKey: capabilityGateKey(opts.planKey, opts.taskId, need.capabilityRef, need.package),
     probeTimeout: opts.probeTimeout,
+    probePollEvery: opts.probePollEvery,
     onTimeout: "escalate",
     probe,
   };

package/app/deliveryGraphCompiler.test.ts

@@ -85,10 +85,10 @@ test("determinism: the same JSON always yields byte-identical bpmn/diagram/resol
 
 test("trust bound: every node inlines an embedded subProcess delegating to an allowlisted body — no other activity type", () => {
   const r = compileOk(RELEASE_RUNBOOK);
-  // Each of the 4 nodes compiles to an EMBEDDED subProcess (call activities are a no-op on the pinned
+  // Each of the 4 nodes compiles to an EMBEDDED subProcess; wait adds one nested retry-loop subProcess (call activities are a no-op on the pinned
   // WASM engine, so delegation is an inlined subProcess sharing the parent scope — never a callActivity).
   assertEquals((r.bpmn.match(/<bpmn:callActivity/g) ?? []).length, 0);
-  assertEquals((r.bpmn.match(/<bpmn:subProcess /g) ?? []).length, 4);
+  assertEquals((r.bpmn.match(/<bpmn:subProcess /g) ?? []).length, 5);
   assert(!r.bpmn.includes("<bpmn:scriptTask"), "no script task is ever emitted");
   // Each node's inner body delegates to an allowlisted engine-native body: a `serviceTask` typed to a
   // worker (agent → its `senior:*` job; wait → `pr.readiness-probe`; connector → `pr.delivery-connector`)

package/app/deliveryGraphCompiler.ts

@@ -604,6 +604,7 @@ function ioMappingLines(w: NodeWiring, boundInputs: readonly BoundInput[]): stri
       inputs.push({ source: cfg("gateKey"), target: "gateKey" });
       inputs.push({ source: cfg("probe"), target: "probe" });
       inputs.push({ source: cfg("probeTimeout"), target: "probeTimeout" });
+      inputs.push({ source: cfg("probePollEvery"), target: "probePollEvery" });
       break;
     case "human":
       inputs.push({ source: cfg("escalationSlaTimeout"), target: "escalationSlaTimeout" });
@@ -712,33 +713,78 @@ function waitBodyLines(el: string, nodeId: string): string[] {
   const esc = escalationTaskElement(el);
   return [
     `      <bpmn:startEvent id="${el}_start"><bpmn:outgoing>${el}_i0</bpmn:outgoing></bpmn:startEvent>`,
-    `      <bpmn:serviceTask id="${el}_task" name="Probe readiness: ${escapeXml(nodeId)}">`,
+    `      <bpmn:subProcess id="${el}_probeLoop" name="Probe readiness loop: ${escapeXml(nodeId)}">`,
+    "        <bpmn:extensionElements>",
+    "          <zeebe:ioMapping>",
+    '            <zeebe:output source="=ready" target="ready" />',
+    '            <zeebe:output source="=if (is defined(detail)) then detail else null" target="detail" />',
+    '            <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="resolvedArtifact" />',
+    '            <zeebe:output source="=if (is defined(mergedSha)) then mergedSha else null" target="mergedSha" />',
+    "          </zeebe:ioMapping>",
+    "        </bpmn:extensionElements>",
+    `        <bpmn:incoming>${el}_i0</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_i1</bpmn:outgoing>`,
+    `        <bpmn:startEvent id="${el}_loopStart"><bpmn:outgoing>${el}_li0</bpmn:outgoing></bpmn:startEvent>`,
+    `        <bpmn:serviceTask id="${el}_task" name="Probe readiness: ${escapeXml(nodeId)}">`,
+    "          <bpmn:extensionElements>",
+    `            <zeebe:taskDefinition type="${DELEGATE_TASK_TYPE.wait}" />`,
+    "            <zeebe:properties>",
+    '              <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReadinessProbeIn" />',
+    '              <zeebe:property name="io.nanobpm.dataEnvelope.out" value="ReadinessProbeOut" />',
+    "            </zeebe:properties>",
+    "          </bpmn:extensionElements>",
+    `          <bpmn:incoming>${el}_li0</bpmn:incoming>`,
+    `          <bpmn:incoming>${el}_li4</bpmn:incoming>`,
+    `          <bpmn:outgoing>${el}_li1</bpmn:outgoing>`,
+    "        </bpmn:serviceTask>",
+    `        <bpmn:exclusiveGateway id="${el}_gw" name="ready?" default="${el}_li3">`,
+    `          <bpmn:incoming>${el}_li1</bpmn:incoming>`,
+    `          <bpmn:outgoing>${el}_li2</bpmn:outgoing>`,
+    `          <bpmn:outgoing>${el}_li3</bpmn:outgoing>`,
+    "        </bpmn:exclusiveGateway>",
+    `        <bpmn:intermediateCatchEvent id="${el}_waitPoll" name="Wait poll interval">`,
+    `          <bpmn:incoming>${el}_li3</bpmn:incoming>`,
+    `          <bpmn:outgoing>${el}_li4</bpmn:outgoing>`,
+    `          <bpmn:timerEventDefinition id="${el}_pollTed"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=probePollEvery</bpmn:timeDuration></bpmn:timerEventDefinition>`,
+    "        </bpmn:intermediateCatchEvent>",
+    `        <bpmn:endEvent id="${el}_loopEnd"><bpmn:incoming>${el}_li2</bpmn:incoming></bpmn:endEvent>`,
+    flow(`${el}_li0`, `${el}_loopStart`, `${el}_task`),
+    flow(`${el}_li1`, `${el}_task`, `${el}_gw`),
+    `      <bpmn:sequenceFlow id="${el}_li2" name="ready" sourceRef="${el}_gw" targetRef="${el}_loopEnd"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=ready = true</bpmn:conditionExpression></bpmn:sequenceFlow>`,
+    `        <bpmn:sequenceFlow id="${el}_li3" name="not ready" sourceRef="${el}_gw" targetRef="${el}_waitPoll" />`,
+    flow(`${el}_li4`, `${el}_waitPoll`, `${el}_task`),
+    "      </bpmn:subProcess>",
+    `      <bpmn:boundaryEvent id="${el}_be" name="Gate timed out" attachedToRef="${el}_probeLoop">`,
+    `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
+    `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=probeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
+    "      </bpmn:boundaryEvent>",
+    `      <bpmn:serviceTask id="${el}_lastAttempt" name="Probe readiness at boundary: ${escapeXml(nodeId)}">`,
     "        <bpmn:extensionElements>",
     `          <zeebe:taskDefinition type="${DELEGATE_TASK_TYPE.wait}" />`,
     "          <zeebe:properties>",
     '            <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReadinessProbeIn" />',
     '            <zeebe:property name="io.nanobpm.dataEnvelope.out" value="ReadinessProbeOut" />',
     "          </zeebe:properties>",
+    "          <zeebe:ioMapping>",
+    '            <zeebe:input source="=true" target="lastAttempt" />',
+    "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",
-    `        <bpmn:incoming>${el}_i0</bpmn:incoming>`,
-    `        <bpmn:outgoing>${el}_i1</bpmn:outgoing>`,
+    `        <bpmn:incoming>${el}_i2</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_i6</bpmn:outgoing>`,
     "      </bpmn:serviceTask>",
-    `      <bpmn:boundaryEvent id="${el}_be" name="Gate timed out" attachedToRef="${el}_task">`,
-    `        <bpmn:outgoing>${el}_i2</bpmn:outgoing>`,
-    `        <bpmn:timerEventDefinition id="${el}_ted"><bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=probeTimeout</bpmn:timeDuration></bpmn:timerEventDefinition>`,
-    "      </bpmn:boundaryEvent>",
-    `      <bpmn:exclusiveGateway id="${el}_gw" name="ready?" default="${el}_i4">`,
-    `        <bpmn:incoming>${el}_i1</bpmn:incoming>`,
-    `        <bpmn:outgoing>${el}_i3</bpmn:outgoing>`,
+    `      <bpmn:exclusiveGateway id="${el}_lastGw" name="ready after boundary?" default="${el}_i4">`,
+    `        <bpmn:incoming>${el}_i6</bpmn:incoming>`,
+    `        <bpmn:outgoing>${el}_i7</bpmn:outgoing>`,
     `        <bpmn:outgoing>${el}_i4</bpmn:outgoing>`,
     "      </bpmn:exclusiveGateway>",
-    ...escalationTaskLines(esc, nodeId, [`${el}_i2`, `${el}_i4`], `${el}_i5`),
-    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i3</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming></bpmn:endEvent>`,
-    flow(`${el}_i0`, `${el}_start`, `${el}_task`),
-    flow(`${el}_i1`, `${el}_task`, `${el}_gw`),
-    flow(`${el}_i2`, `${el}_be`, esc),
-    `      <bpmn:sequenceFlow id="${el}_i3" name="ready" sourceRef="${el}_gw" targetRef="${el}_end"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=ready = true</bpmn:conditionExpression></bpmn:sequenceFlow>`,
-    `      <bpmn:sequenceFlow id="${el}_i4" name="not ready" sourceRef="${el}_gw" targetRef="${esc}" />`,
+    ...escalationTaskLines(esc, nodeId, [`${el}_i4`], `${el}_i5`),
+    `      <bpmn:endEvent id="${el}_end"><bpmn:incoming>${el}_i1</bpmn:incoming><bpmn:incoming>${el}_i5</bpmn:incoming><bpmn:incoming>${el}_i7</bpmn:incoming></bpmn:endEvent>`,
+    flow(`${el}_i0`, `${el}_start`, `${el}_probeLoop`),
+    flow(`${el}_i1`, `${el}_probeLoop`, `${el}_end`),
+    flow(`${el}_i2`, `${el}_be`, `${el}_lastAttempt`),
+    flow(`${el}_i6`, `${el}_lastAttempt`, `${el}_lastGw`),
+    `      <bpmn:sequenceFlow id="${el}_i7" name="ready" sourceRef="${el}_lastGw" targetRef="${el}_end"><bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=ready = true</bpmn:conditionExpression></bpmn:sequenceFlow>`,
+    `      <bpmn:sequenceFlow id="${el}_i4" name="not ready" sourceRef="${el}_lastGw" targetRef="${esc}" />`,
     flow(`${el}_i5`, esc, `${el}_end`),
   ];
 }

package/app/deliveryRunner.test.ts

@@ -64,6 +64,7 @@ test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMappin
   const wait = byField((v) => "gateKey" in v);
   assertEquals(wait?.gateKey, "run-7:n3");
   assertEquals(wait?.probeTimeout, "PT20M");
+  assertEquals(wait?.probePollEvery, "PT15S");
   assert(wait?.probe && typeof wait.probe === "object", "the wait node carries its ReadinessProbe descriptor");
 
   const human = byField((v) => "escalationSlaTimeout" in v);

package/app/deliveryRunner.ts

@@ -17,6 +17,7 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
+import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
  * content-addressed deploy id (`delivery-graph-<digest>`) AND the S5 dispatch door's approval token /
@@ -35,6 +36,8 @@ export interface DeliveryRunTimeouts {
   probeTimeout?: string;
   /** `human` node SLA before it records an `escalated` outcome and settles. */
   escalationSlaTimeout?: string;
+  /** `wait` gate retry cadence owned by the engine. */
+  probePollEvery?: string;
   /** Optional explicit assignee for `human` nodes + escalation tasks (else candidate-group routed). */
   escalationAssignee?: string | null;
 }
@@ -51,6 +54,7 @@ export interface DeliveryRunOptions extends DeliveryRunTimeouts {
 const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
   nodeTimeout: "PT30M",
   probeTimeout: "PT30M",
+  probePollEvery: msToIsoDuration(DEFAULT_EVERY_MS),
   escalationSlaTimeout: "P1D",
 };
 
@@ -59,7 +63,7 @@ const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
  * silently seeds `null` into a node body), so both derive from the same node kinds. */
 type NodeInput =
   | { jobType: string; appendPrompt: string; timeout: string }
-  | { gateKey: string; probe: unknown; probeTimeout: string }
+  | { gateKey: string; probe: unknown; probeTimeout: string; probePollEvery: string }
   | { escalationSlaTimeout: string; escalationAssignee: string | null }
   | { target: string; dedupeKey: string | null; payload: Record<string, unknown> | null; timeout: string };
 
@@ -105,6 +109,7 @@ export function prepareDeliveryGraph(graph: DeliveryGraph, options: DeliveryRunO
   const timeouts = {
     nodeTimeout: options.nodeTimeout ?? DEFAULTS.nodeTimeout,
     probeTimeout: options.probeTimeout ?? DEFAULTS.probeTimeout,
+    probePollEvery: options.probePollEvery ?? DEFAULTS.probePollEvery,
     escalationSlaTimeout: options.escalationSlaTimeout ?? DEFAULTS.escalationSlaTimeout,
     escalationAssignee: options.escalationAssignee ?? null,
   };
@@ -155,13 +160,20 @@ function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
  * subProcess ioMapping pulls. Total over the closed kind set. */
 function buildNodeInput(
   node: DeliveryNode,
-  ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; escalationSlaTimeout: string; escalationAssignee: string | null },
+  ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; probePollEvery: string; escalationSlaTimeout: string; escalationAssignee: string | null },
 ): NodeInput {
   switch (node.kind) {
     case "agent":
       return { jobType: node.agent.jobType, appendPrompt: node.agent.prompt ?? "", timeout: ctx.nodeTimeout };
-    case "wait":
-      return { gateKey: `${ctx.runKey}:${ctx.element}`, probe: node.wait, probeTimeout: ctx.probeTimeout };
+    case "wait": {
+      const probe = parseProbe(node.wait);
+      return {
+        gateKey: `${ctx.runKey}:${ctx.element}`,
+        probe: node.wait,
+        probeTimeout: ctx.probeTimeout,
+        probePollEvery: probe.poll?.everyMs ? readinessPollEvery(probe, {}) : ctx.probePollEvery,
+      };
+    }
     case "human":
       return { escalationSlaTimeout: ctx.escalationSlaTimeout, escalationAssignee: ctx.escalationAssignee };
     case "connector":

package/app/feature.test.ts

@@ -320,6 +320,7 @@ test("startFeature: no readiness ⇒ readinessProbes/probeTimeout/gateKey seeded
   const v = captured.variables;
   assertEquals(v.readinessProbes, null);
   assertEquals(v.probeTimeout, null);
+  assertEquals(v.probePollEvery, null);
   assertEquals(v.gateKey, null);
   assertEquals(v.resolvedArtifacts, null);
 });
@@ -348,11 +349,12 @@ test("startFeature: readiness probes seed the gate variables + a non-blank corre
     false,
     false,
     null,
-    { probes, probeTimeout: "PT30M" },
+    { probes, probeTimeout: "PT30M", probePollEvery: "PT15S" },
   );
   const v = captured.variables;
   assertEquals(v.readinessProbes, probes);
   assertEquals(v.probeTimeout, "PT30M");
+  assertEquals(v.probePollEvery, "PT15S");
   // The preflight probe worker requires a non-blank gateKey to publish readiness-ready on.
   assertEquals(v.gateKey, "feature-readiness:owner/repo#42");
   assertEquals(v.resolvedArtifacts, null);

package/app/feature.ts

@@ -29,6 +29,7 @@ import { deriveListBucket, deriveStage } from "./stage.ts";
 export interface FeatureReadinessOptions {
   readonly probes?: ReadinessProbe[];
   readonly probeTimeout?: string | null;
+  readonly probePollEvery?: string | null;
 }
 
 /** The BPMN process this module drives (resources/processes/feature.bpmn). */
@@ -367,6 +368,13 @@ export async function startFeature(
         "a non-blank bound. Derive it via parseFeatureReadiness before starting a gated feature.",
     );
   }
+  if (readinessProbes && (readiness.probePollEvery ?? "").trim() === "") {
+    throw new Error(
+      `startFeature(${parsed.planKey}): ${readinessProbes.length} readiness probe(s) seeded without a ` +
+        "probePollEvery — the preflight retry timers (=probePollEvery) require a non-blank cadence. " +
+        "Derive it via parseFeatureReadiness before starting a gated feature.",
+    );
+  }
   // Operator free-text steering for the implementation agent (issue #172 follow-on): blank/absent →
   // null so the implement task's `appendPrompt` FEEL (`customInstructions = null`) skips the block
   // rather than appending an empty "Operator custom instructions" heading.
@@ -487,6 +495,7 @@ export async function startFeature(
       // gate-less run still resolves the variable in that FEEL instead of raising an incident.
       readinessProbes,
       probeTimeout: readinessProbes ? (readiness.probeTimeout ?? null) : null,
+      probePollEvery: readinessProbes ? (readiness.probePollEvery ?? null) : null,
       gateKey: readinessProbes ? `feature-readiness:${parsed.planKey}` : null,
       resolvedArtifacts: null,
     },

package/app/featureReadiness.test.ts

@@ -9,12 +9,12 @@ import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import { parseFeatureReadiness } from "./featureReadiness.ts";
 
-const ENV = { NANO_READINESS_POLL_TIMEOUT: "PT30M" } as Record<string, string | undefined>;
+const ENV = { NANO_READINESS_POLL_TIMEOUT: "PT30M", NANO_READINESS_POLL_EVERY_MS: "15000" } as Record<string, string | undefined>;
 
 test("parseFeatureReadiness: no intake ⇒ empty probes, null bound (gate skipped)", () => {
-  assertEquals(parseFeatureReadiness(undefined, ENV), { probes: [], probeTimeout: null });
-  assertEquals(parseFeatureReadiness({}, ENV), { probes: [], probeTimeout: null });
-  assertEquals(parseFeatureReadiness({ readiness: [], blockedOn: [] }, ENV), { probes: [], probeTimeout: null });
+  assertEquals(parseFeatureReadiness(undefined, ENV), { probes: [], probeTimeout: null, probePollEvery: null });
+  assertEquals(parseFeatureReadiness({}, ENV), { probes: [], probeTimeout: null, probePollEvery: null });
+  assertEquals(parseFeatureReadiness({ readiness: [], blockedOn: [] }, ENV), { probes: [], probeTimeout: null, probePollEvery: null });
 });
 
 test("parseFeatureReadiness: blockedOn + consumerPackage ⇒ capability probes with derived bound", () => {
@@ -32,6 +32,7 @@ test("parseFeatureReadiness: blockedOn + consumerPackage ⇒ capability probes w
   assertEquals(out.probes[1].match?.capabilityRef, "nanobpm/nano-bpm#808");
   // Every derived probe shares the env default, so the bound is that default.
   assertEquals(out.probeTimeout, "PT30M");
+  assertEquals(out.probePollEvery, "PT15S");
 });
 
 test("parseFeatureReadiness: blockedOn without consumerPackage ⇒ command state probes (merged-is-enough)", () => {
@@ -43,6 +44,7 @@ test("parseFeatureReadiness: blockedOn without consumerPackage ⇒ command state
     onTimeout: "escalate",
   });
   assertEquals(out.probeTimeout, "PT30M");
+  assertEquals(out.probePollEvery, "PT15S");
 });
 
 test("parseFeatureReadiness: full readiness descriptors round-trip through parseProbe", () => {
@@ -82,6 +84,7 @@ test("parseFeatureReadiness: a longer per-probe budget wins the derived bound",
     ENV,
   );
   assertEquals(out.probeTimeout, "PT3600S");
+  assertEquals(out.probePollEvery, "PT15S");
 });
 
 test("parseFeatureReadiness: a bare repo#N handle is rejected (cannot name a provenance repo)", () => {

package/app/featureReadiness.ts

@@ -26,6 +26,7 @@ import {
   DEFAULT_READINESS_TIMEOUT,
   parseProbe,
   type ReadinessProbe,
+  readinessPollEvery,
   readinessTimeout,
 } from "./readiness.ts";
 import { isoDurationToMs } from "./reviewWait.ts";
@@ -47,6 +48,7 @@ export interface FeatureReadinessInput {
 export interface FeatureReadiness {
   readonly probes: ReadinessProbe[];
   readonly probeTimeout: string | null;
+  readonly probePollEvery: string | null;
 }
 
 function isNonEmptyString(v: unknown): v is string {
@@ -104,7 +106,7 @@ function desugarHandle(handle: string, consumerPackage: string | null): Readines
 }
 
 /** 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
+ * `probeTimeout`/`probePollEvery`. 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
@@ -139,7 +141,7 @@ export function parseFeatureReadiness(
     }
   }
 
-  if (probes.length === 0) return { probes: [], probeTimeout: null };
+  if (probes.length === 0) return { probes: [], probeTimeout: null, probePollEvery: 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
@@ -147,5 +149,8 @@ export function parseFeatureReadiness(
   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 };
+  const probePollEvery = probes
+    .map((p) => readinessPollEvery(p, env))
+    .reduce((a, b) => (isoDurationToMs(b, DEFAULT_READINESS_TIMEOUT) < isoDurationToMs(a, DEFAULT_READINESS_TIMEOUT) ? b : a));
+  return { probes, probeTimeout, probePollEvery };
 }

package/app/plan.test.ts

@@ -350,7 +350,7 @@ test("startPlan fails fast when readiness probes are seeded without a probeTimeo
         engine,
         { repo: "owner/repo", number: 292, url: "https://github.com/owner/repo/issues/292", planKey: PLAN_KEY },
         "epic/gate-branch",
-        { readinessProbes: [probe] as any, probeTimeout: "   " },
+        { readinessProbes: [probe] as any, probeTimeout: "   ", probePollEvery: "PT15S" },
       ),
     Error,
     "probeTimeout",

package/app/plan.ts

@@ -964,6 +964,7 @@ function assertAcyclic(adjacency: Map<string, Set<string>>): void {
 export interface StartPlanOptions {
   readinessProbes?: ReadinessProbe[];
   probeTimeout?: string;
+  probePollEvery?: string;
 }
 
 /** Register a plan row (if new) and start the plan-fanout process. Idempotent on
@@ -988,6 +989,13 @@ export async function startPlan(
         "bound. Derive it via readinessTimeout (see planLowering) before starting a gated dependent.",
     );
   }
+  if (probes && (opts.probePollEvery ?? "").trim() === "") {
+    throw new Error(
+      `startPlan(${parsed.planKey}): ${probes.length} readiness probe(s) seeded without a probePollEvery — ` +
+        "the preflight retry timers (=probePollEvery) require a non-blank cadence. Derive it via " +
+        "readinessPollEvery (see planLowering) before starting a gated dependent.",
+    );
+  }
   const table = plans(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !PLAN_TERMINAL_STATUSES.includes(existing.status)) {
@@ -1108,6 +1116,7 @@ export async function startPlan(
       // the variable in that FEEL expression instead of raising an incident.
       readinessProbes: probes,
       probeTimeout: opts.probeTimeout ?? null,
+      probePollEvery: opts.probePollEvery ?? null,
       // The preflight probe worker (`pr.readiness-probe`) requires a non-blank `gateKey` correlation
       // key (it publishes `readiness-ready` on it). The typed `ReadinessProbeIn` envelope projects it
       // from THIS process scope (not task-local ioMapping), so it is seeded here — one per dependent

package/app/planFanoutPreflight.test.ts

@@ -48,21 +48,21 @@ test("the preflight is a multi-instance subprocess over =readinessProbes collect
 });
 
 test("the preflight reuses the pr.readiness-probe worker and the readiness-escalation form (no reinvention)", () => {
-  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/)![0];
-  assertStringIncludes(sub, 'type="pr.readiness-probe"', "reuses the existing capability probe worker");
-  assertStringIncludes(sub, 'value="ReadinessProbeIn"', "feeds the shared probe input envelope");
-  assertStringIncludes(sub, 'value="ReadinessProbeOut"', "reads the shared probe output envelope");
-  assertStringIncludes(sub, 'formId="readiness-escalation"', "reuses the existing readiness escalation form");
+  assertStringIncludes(flat, 'type="pr.readiness-probe"', "reuses the existing capability probe worker");
+  assertStringIncludes(flat, 'value="ReadinessProbeIn"', "feeds the shared probe input envelope");
+  assertStringIncludes(flat, 'value="ReadinessProbeOut"', "reads the shared probe output envelope");
+  assertStringIncludes(flat, 'formId="readiness-escalation"', "reuses the existing readiness escalation form");
 });
 
 test("a never-green producer escalates (bounded) without wedging: probe timeout + SLA both settle the gate", () => {
-  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/)![0];
-  // The probe carries an interrupting timeout bound (reuses the gate's =probeTimeout), and the human
-  // escalation carries the shared SLA bound — so a stuck producer can never wedge the dependent.
-  assertStringIncludes(sub, "=probeTimeout", "the probe is bounded by the reused =probeTimeout");
-  assertStringIncludes(sub, "=escalationSlaTimeout", "the escalation is bounded by the shared SLA");
-  assert(hasFlow("be_pf_probe_timeout", "readiness-escalation-pf"), "a timed-out probe routes to escalation");
-  assert(hasFlow("pf_gw", "readiness-escalation-pf"), "a not-ready probe routes to escalation");
+  // The probe loop carries an interrupting timeout bound (reuses the gate's =probeTimeout), and the
+  // human escalation carries the shared SLA bound — so a stuck producer can never wedge the dependent.
+  assertStringIncludes(flat, "=probeTimeout", "the probe loop is bounded by the reused =probeTimeout");
+  assertStringIncludes(flat, "=probePollEvery", "retry cadence is driven by the engine timer");
+  assertStringIncludes(flat, "=escalationSlaTimeout", "the escalation is bounded by the shared SLA");
+  assert(hasFlow("be_pf_probe_timeout", "preflight-probe-last-attempt"), "a timed-out loop routes to one last empirical probe");
+  assert(hasFlow("preflight-probe-last-attempt", "pf_gw"), "the last attempt can still take the ready path");
+  assert(hasFlow("pf_gw", "readiness-escalation-pf"), "a not-ready final probe routes to escalation");
   assert(hasFlow("be_pf_sla", "pf_end"), "an elapsed escalation SLA settles the preflight instead of wedging");
 });
 

package/app/planLowering.test.ts

@@ -139,6 +139,7 @@ test("deriveEpicSchedule: a dependent with MULTIPLE inbound edges waits for ALL
   assertEquals(dep.producers.sort(), ["o/r#1", "o/r#2"]);
   assertEquals(dep.probes.length, 2); // one probe per producer — must satisfy both to fan out
   assert(dep.probeTimeout.startsWith("PT") || dep.probeTimeout.startsWith("P"), "an ISO-8601 bound");
+  assert(dep.probePollEvery.startsWith("PT") || dep.probePollEvery.startsWith("P"), "an ISO-8601 cadence");
 });
 
 // ── lowerAdmittedSet ────────────────────────────────────────────────────────────────────────────
@@ -160,6 +161,7 @@ test("lowerAdmittedSet starts roots with no probe and dependents with their seed
   const depProbes = byKey.get("o/r#2")?.["readinessProbes"] as unknown[] | null;
   assert(Array.isArray(depProbes) && depProbes.length === 1, "dependent seeded with one capability probe");
   assert(byKey.get("o/r#2")?.["probeTimeout"] != null, "dependent seeded with a bounded timeout");
+  assert(byKey.get("o/r#2")?.["probePollEvery"] != null, "dependent seeded with a poll cadence");
 
   // Durable edge materialized (after the plans rows exist), and a plans row per epic.
   assertEquals((tables.get("plan_deps") ?? []).length, 1);

package/app/planLowering.ts

@@ -35,7 +35,7 @@ import {
   recordPlanDep,
   startPlan,
 } from "./plan.ts";
-import { type ReadinessProbe, readinessTimeout } from "./readiness.ts";
+import { type ReadinessProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 
 /** Derive the `capability` readiness probe for ONE inbound inter-epic edge: it goes green when the
  * producer epic (`depends_on_plan_key`) has published a release of `package` whose provenance carries
@@ -64,6 +64,7 @@ export interface DependentGate {
   probes: ReadinessProbe[];
   producers: string[];
   probeTimeout: string;
+  probePollEvery: string;
 }
 
 /** The pure schedule derived from a validated set: the ROOTS to start immediately and the
@@ -104,7 +105,10 @@ export function deriveEpicSchedule(
     const probeTimeout = probes
       .map((p) => readinessTimeout(p, env))
       .reduce((a, b) => (isoLonger(a, b) ? a : b));
-    dependents.push({ planKey, probes, producers: edgesForKey.map((e) => e.depends_on_plan_key), probeTimeout });
+    const probePollEvery = probes
+      .map((p) => readinessPollEvery(p, env))
+      .reduce((a, b) => (isoLonger(a, b) ? b : a));
+    dependents.push({ planKey, probes, producers: edgesForKey.map((e) => e.depends_on_plan_key), probeTimeout, probePollEvery });
   }
   return { roots, dependents };
 }
@@ -161,6 +165,7 @@ export async function lowerAdmittedSet(
     await startPlan(data, engine, parsed, staged.base_branch, {
       readinessProbes: gate?.probes,
       probeTimeout: gate?.probeTimeout,
+      probePollEvery: gate?.probePollEvery,
     });
   }
 

package/app/readiness.test.ts

@@ -37,6 +37,7 @@ import {
   type ProbeExec,
   type PrObservation,
   prViewCommand,
+  readinessPollEvery,
   readinessTimeout,
   readinessTimeoutMs,
   redactString,
@@ -585,6 +586,14 @@ test("readinessTimeoutMs: the ms twin of readinessTimeout — same precedence, n
   );
 });
 
+
+test("readinessPollEvery: derives the engine retry cadence from descriptor/env/default with clamp", () => {
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x", poll: { everyMs: 1500 } }), {}), "PT2S");
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x" }), { NANO_READINESS_POLL_EVERY_MS: "2500" }), "PT3S");
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x", poll: { everyMs: MAX_EVERY_MS + 1 } }), {}), msToIsoDuration(MAX_EVERY_MS));
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x" }), { NANO_READINESS_POLL_EVERY_MS: "bad" }), msToIsoDuration(DEFAULT_EVERY_MS));
+});
+
 test("probeBudgetMs: prefers the seeded probeTimeout (the gate timer's bound), falling back to the env twin", () => {
   const probe = parseProbe({ kind: "http", target: "x" });
   // The seeded probeTimeout wins over the ambient env — binding worker and engine to ONE per-instance

package/app/readiness.ts

@@ -776,6 +776,31 @@ export function readinessTimeout(
   return isoDuration(readEnvOr("NANO_READINESS_POLL_TIMEOUT", DEFAULT_READINESS_TIMEOUT, env), DEFAULT_READINESS_TIMEOUT);
 }
 
+/** The poll cadence (an ISO-8601 duration) seeded onto a readiness-gate instance as `probePollEvery`:
+ * the descriptor's `poll.everyMs` when present, else `NANO_READINESS_POLL_EVERY_MS`, else the built-in
+ * {@link DEFAULT_EVERY_MS}, clamped to {@link MAX_EVERY_MS}. Since Option A (#428), the engine — not the
+ * worker — owns the retry cadence: the `wait-poll` timers in `readiness-gate.bpmn` (and the preflight
+ * loops in `feature.bpmn`/`plan-fanout.bpmn`) read `=probePollEvery`, re-activating the now single-shot
+ * `pr.readiness-probe` once per interval. Derived here so whoever seeds a gate derives the cadence from
+ * ONE place (mirroring {@link readinessTimeout} for the bound), and worker/engine can never drift.
+ * `msToIsoDuration` rounds up (via `Math.ceil`) to a whole second, with a one-second minimum, so the
+ * timer never rounds to an immediately-refiring zero-length duration (which would reintroduce a
+ * busy-spin — the very defect Option A removes). */
+export function readinessPollEvery(
+  probe: ReadinessProbe,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const declared = probe.poll?.everyMs;
+  const ms =
+    typeof declared === "number" && declared >= 1
+      ? Math.min(Math.trunc(declared), MAX_EVERY_MS)
+      : (() => {
+          const envEvery = Number(readEnvOr("NANO_READINESS_POLL_EVERY_MS", String(DEFAULT_EVERY_MS), env));
+          return Number.isFinite(envEvery) && envEvery >= 1 ? Math.min(Math.trunc(envEvery), MAX_EVERY_MS) : DEFAULT_EVERY_MS;
+        })();
+  return msToIsoDuration(ms);
+}
+
 /** The effective gate budget in **milliseconds** — the ms twin of {@link readinessTimeout}, resolved
  * by the SAME precedence (descriptor `poll.timeoutMs`, else `NANO_READINESS_POLL_TIMEOUT`, else the
  * built-in default) and sharing its env key + default. The worker's local poll budget MUST use this