@sensigo/realm 0.27.0 → 0.29.0

package/dist/engine/claim-liveness.d.ts

@@ -1,5 +1,5 @@
 import type { RunRecord, ClaimRecord } from '../types/run-record.js';
-import type { WorkflowDefinition, StepDefinition } from '../types/workflow-definition.js';
+import type { WorkflowDefinition, StepDefinition, RetryConfig } from '../types/workflow-definition.js';
 /**
  * Default execution timeout (issue A3) enforced on every `execution: 'auto'` step that declares no
  * `timeout_seconds` — bounds a hung adapter/handler call so it fails loudly (`STEP_TIMEOUT`)
@@ -33,6 +33,40 @@ export declare const RECLAIM_MARGIN_SECONDS = 60;
  * deadline-carrying claim — finalizer-bearing steps get `deadline: null` → `claim_unknown_age`.)
  */
 export declare const RECLAIM_FLOOR_SECONDS = 900;
+/**
+ * Computes the worst-case wall-clock (SECONDS) across every attempt of a retry-configured step:
+ * `max_attempts × perAttemptSec` + the sum of the DECLARED backoff delays between attempts (n-1 of
+ * them, for attemptNum 1..n-1 — matches the retry loop's own schedule in execution-loop.ts;
+ * computeBackoff returns ms). Pure — the declared schedule only; does not model a runtime
+ * rate-limit `retry_after` override (execution-loop.ts applies that separately). This is the
+ * SHARED formula (issue #140) consumed by BOTH `computeClaimDeadline` below (the claim DETECTION
+ * horizon) and `resolveCapMs` (the engine's ENFORCEMENT cap) so the two can never independently
+ * drift apart — see the congruence-by-construction test in claim-liveness.test.ts.
+ */
+export declare function worstCaseScheduleSeconds(retry: RetryConfig, perAttemptSec: number): number;
+/**
+ * Resolves the total-time cap (MILLISECONDS) enforced across every attempt of a retry-configured
+ * `execution: 'auto'` step (issue #140, AMENDED default): the explicit `retry.total_timeout_seconds`
+ * when declared — `!== undefined`, NEVER truthiness, so a hand-built `total_timeout_seconds: 0` is
+ * honored as a present (already-exhausted) cap rather than falling through to the default — else
+ * the shared `worstCaseScheduleSeconds` formula above. The default equals the step's own declared
+ * schedule, so the cap binds only when a runtime wait pushes an attempt's actual wall-clock
+ * MATERIALLY past it. Call only when enforcement applies and `retryConfig` is defined
+ * (execution-loop.ts gates the call on `enforceTimeout && retryConfig !== undefined`) — `timeoutMs`
+ * is guaranteed defined in that case. Seconds-in (`total_timeout_seconds`, `timeoutMs / 1000`),
+ * MILLISECONDS-out — the same convention `timeoutMs` itself uses.
+ */
+export declare function resolveCapMs(retry: RetryConfig, timeoutMs: number): number;
+/**
+ * Pure predicate for the engine's site-(c) sleep guard (issue #140 correction, S2): whether
+ * sleeping `waitMs` more, on top of `elapsedMs` already spent, would meet or exceed the total-time
+ * cap `capMs`. `>=`, not `>` — an exact-fit sleep is doomed too (never sleep into a wall). Module
+ * export ONLY (not re-exported from `packages/core/src/index.ts`) — this exists purely so the
+ * boundary itself can be unit-pinned without depending on real-timer elapsed-time precision (a
+ * real clock is never observed to read EXACTLY `capMs - waitMs`, so a test driving this through
+ * `executeStep` cannot discriminate `>=` from `>` at the boundary — seeing this in isolation can).
+ */
+export declare function sleepWouldExceedCap(elapsedMs: number, waitMs: number, capMs: number): boolean;
 /**
  * Computes the claim deadline for `stepName` at claim time. A CONCRETE deadline is returned ONLY
  * for a reliably time-boundable claim: an `execution: 'auto'` (handler-driven) step in a workflow
@@ -42,16 +76,30 @@ export declare const RECLAIM_FLOOR_SECONDS = 900;
  * any step in a finalizer-bearing workflow may hold its claim through the terminal drain.
  *
  * The horizon is the WORST-CASE wall-clock across every retry attempt (issue #101 follow-up —
- * Design Reviewer finding #4 from the A3 debate): a single-attempt bound understates a retrying
- * step's real claim span (`max_attempts × per-attempt-timeout + the declared backoffs between
- * attempts`), so a legitimately-retrying step could be labeled `claim_stale` — and, if
- * `idempotent`, become eligible for a premature `realm run reclaim --all --force` re-drive —
- * while still on an early attempt. For `n = 1` (no `retry:`, or `max_attempts: 1`) this reduces
- * EXACTLY to the prior single-attempt formula `max(RECLAIM_FLOOR, perAttemptSec + MARGIN)`, so
- * non-retry steps' horizons are byte-unchanged. This uses the DECLARED backoff schedule only — a
- * runtime `retry_after` (rate-limit 429 override, applied in execution-loop.ts) is not knowable at
- * claim time; the horizon stays a best-effort, floored, advisory bound (Phase 1 gates no action on
- * this label) and does not attempt to model `retry_after`.
+ * Design Reviewer finding #4 from the A3 debate), via the shared `worstCaseScheduleSeconds`
+ * formula above: a single-attempt bound understates a retrying step's real claim span, so a
+ * legitimately-retrying step could be labeled `claim_stale` — and, if `idempotent`, become
+ * eligible for a premature `realm run reclaim --all --force` re-drive — while still on an early
+ * attempt. For `n = 1` (no `retry:`, or `max_attempts: 1`) this reduces EXACTLY to the prior
+ * single-attempt formula `max(RECLAIM_FLOOR, perAttemptSec + MARGIN)`, so non-retry steps'
+ * horizons are byte-unchanged.
+ *
+ * Issue #140 AMENDMENT + correction (B2): the horizon now consumes the SAME resolved cap the
+ * engine enforces — `(explicit total_timeout_seconds ?? worstCaseScheduleSeconds) + margin`,
+ * via `resolveCapMs` (record §3: `(cap ?? worstCase) + margin`). This is NOT merely "the runtime
+ * enforcement side changed; this function's formula did not" (an earlier, INCORRECT claim this
+ * paragraph made) — the horizon's own formula changed too, and had to: a step declaring an
+ * EXPLICIT `total_timeout_seconds` ABOVE its worst-case schedule (the legitimate long-wait
+ * opt-in this feature exists to support) would otherwise sleep past a horizon computed from the
+ * worst-case schedule ALONE, well before its declared cap — a premature `claim_stale` mid-
+ * legitimate-sleep, exactly the silent-duplicate hazard this program closes. Consuming
+ * `resolveCapMs` closes it: retry-no-cap still reduces to the worst-case schedule (unchanged,
+ * every pre-existing pin stays byte-identical), no-retry still reduces to `perAttemptSec`
+ * (unchanged), and retry-WITH-an-explicit-cap now widens the horizon to `cap + margin` — the
+ * record's mandate. The prior "does not attempt to model `retry_after`" caveat remains retired
+ * for the DEFAULT-cap population for the same reason as before (enforcement now tracks the
+ * declared schedule there too); it is now ALSO honestly retired for the explicit-cap population,
+ * which this correction is what actually makes true.
  */
 export declare function computeClaimDeadline(definition: WorkflowDefinition, stepName: string, now: Date): string | null;
 /**

package/dist/engine/claim-liveness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-liveness.d.ts","sourceRoot":"","sources":["../../src/engine/claim-liveness.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAG1F;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAElE;AAKD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,qGAAqG;AACrG,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,IAAI,GACR,MAAM,GAAG,IAAI,CAgBf;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,EAC/C,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAI7B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEzE,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,UAAU,CAGnF;AAED,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,SAAS,EACd,GAAG,GAAE,IAAiB,GACrB,mBAAmB,EAAE,CAKvB"}
+{"version":3,"file":"claim-liveness.d.ts","sourceRoot":"","sources":["../../src/engine/claim-liveness.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,WAAW,EACZ,MAAM,iCAAiC,CAAC;AAGzC;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,OAAO,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAElE;AAKD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,qGAAqG;AACrG,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAa1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,IAAI,GACR,MAAM,GAAG,IAAI,CAgBf;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,EAC/C,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAI7B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEzE,wGAAwG;AACxG,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,EAAE,IAAI,GAAG,UAAU,CAGnF;AAED,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,SAAS,EACd,GAAG,GAAE,IAAiB,GACrB,mBAAmB,EAAE,CAKvB"}

package/dist/engine/claim-liveness.js

@@ -36,6 +36,58 @@ export const RECLAIM_MARGIN_SECONDS = 60; // 1 min
  * deadline-carrying claim — finalizer-bearing steps get `deadline: null` → `claim_unknown_age`.)
  */
 export const RECLAIM_FLOOR_SECONDS = 900; // 15 min
+/**
+ * Computes the worst-case wall-clock (SECONDS) across every attempt of a retry-configured step:
+ * `max_attempts × perAttemptSec` + the sum of the DECLARED backoff delays between attempts (n-1 of
+ * them, for attemptNum 1..n-1 — matches the retry loop's own schedule in execution-loop.ts;
+ * computeBackoff returns ms). Pure — the declared schedule only; does not model a runtime
+ * rate-limit `retry_after` override (execution-loop.ts applies that separately). This is the
+ * SHARED formula (issue #140) consumed by BOTH `computeClaimDeadline` below (the claim DETECTION
+ * horizon) and `resolveCapMs` (the engine's ENFORCEMENT cap) so the two can never independently
+ * drift apart — see the congruence-by-construction test in claim-liveness.test.ts.
+ */
+export function worstCaseScheduleSeconds(retry, perAttemptSec) {
+    // issue #140 correction (B1): the loader ADMITS an absent `max_attempts` (only validates its
+    // shape IF present — see yaml-loader.ts's retry-block walk; W1's own comment says so), so a
+    // loader-legal `retry: {backoff: fixed, base_delay_ms: 1000}` step reaches here with
+    // `retry.max_attempts === undefined` despite the TYPE declaring it required. An unguarded read
+    // is a NaN cascade: NaN capMs arms every guard, NaN effectiveMs instant-timeouts attempt 1 via
+    // setTimeout's own NaN→0 coercion, and `new Date(NaN).toISOString()` THROWS inside
+    // computeClaimDeadline (called from claimStep) — every execute_step on such a step would crash.
+    // Mirror execution-loop's own `retryConfig?.max_attempts ?? 1` default idiom exactly.
+    const n = retry.max_attempts ?? 1;
+    let backoffSec = 0;
+    for (let a = 1; a < n; a++)
+        backoffSec += computeBackoff(retry, a) / 1000;
+    return n * perAttemptSec + backoffSec;
+}
+/**
+ * Resolves the total-time cap (MILLISECONDS) enforced across every attempt of a retry-configured
+ * `execution: 'auto'` step (issue #140, AMENDED default): the explicit `retry.total_timeout_seconds`
+ * when declared — `!== undefined`, NEVER truthiness, so a hand-built `total_timeout_seconds: 0` is
+ * honored as a present (already-exhausted) cap rather than falling through to the default — else
+ * the shared `worstCaseScheduleSeconds` formula above. The default equals the step's own declared
+ * schedule, so the cap binds only when a runtime wait pushes an attempt's actual wall-clock
+ * MATERIALLY past it. Call only when enforcement applies and `retryConfig` is defined
+ * (execution-loop.ts gates the call on `enforceTimeout && retryConfig !== undefined`) — `timeoutMs`
+ * is guaranteed defined in that case. Seconds-in (`total_timeout_seconds`, `timeoutMs / 1000`),
+ * MILLISECONDS-out — the same convention `timeoutMs` itself uses.
+ */
+export function resolveCapMs(retry, timeoutMs) {
+    return (retry.total_timeout_seconds ?? worstCaseScheduleSeconds(retry, timeoutMs / 1000)) * 1000;
+}
+/**
+ * Pure predicate for the engine's site-(c) sleep guard (issue #140 correction, S2): whether
+ * sleeping `waitMs` more, on top of `elapsedMs` already spent, would meet or exceed the total-time
+ * cap `capMs`. `>=`, not `>` — an exact-fit sleep is doomed too (never sleep into a wall). Module
+ * export ONLY (not re-exported from `packages/core/src/index.ts`) — this exists purely so the
+ * boundary itself can be unit-pinned without depending on real-timer elapsed-time precision (a
+ * real clock is never observed to read EXACTLY `capMs - waitMs`, so a test driving this through
+ * `executeStep` cannot discriminate `>=` from `>` at the boundary — seeing this in isolation can).
+ */
+export function sleepWouldExceedCap(elapsedMs, waitMs, capMs) {
+    return elapsedMs + waitMs >= capMs;
+}
 /**
  * Computes the claim deadline for `stepName` at claim time. A CONCRETE deadline is returned ONLY
  * for a reliably time-boundable claim: an `execution: 'auto'` (handler-driven) step in a workflow
@@ -45,16 +97,30 @@ export const RECLAIM_FLOOR_SECONDS = 900; // 15 min
  * any step in a finalizer-bearing workflow may hold its claim through the terminal drain.
  *
  * The horizon is the WORST-CASE wall-clock across every retry attempt (issue #101 follow-up —
- * Design Reviewer finding #4 from the A3 debate): a single-attempt bound understates a retrying
- * step's real claim span (`max_attempts × per-attempt-timeout + the declared backoffs between
- * attempts`), so a legitimately-retrying step could be labeled `claim_stale` — and, if
- * `idempotent`, become eligible for a premature `realm run reclaim --all --force` re-drive —
- * while still on an early attempt. For `n = 1` (no `retry:`, or `max_attempts: 1`) this reduces
- * EXACTLY to the prior single-attempt formula `max(RECLAIM_FLOOR, perAttemptSec + MARGIN)`, so
- * non-retry steps' horizons are byte-unchanged. This uses the DECLARED backoff schedule only — a
- * runtime `retry_after` (rate-limit 429 override, applied in execution-loop.ts) is not knowable at
- * claim time; the horizon stays a best-effort, floored, advisory bound (Phase 1 gates no action on
- * this label) and does not attempt to model `retry_after`.
+ * Design Reviewer finding #4 from the A3 debate), via the shared `worstCaseScheduleSeconds`
+ * formula above: a single-attempt bound understates a retrying step's real claim span, so a
+ * legitimately-retrying step could be labeled `claim_stale` — and, if `idempotent`, become
+ * eligible for a premature `realm run reclaim --all --force` re-drive — while still on an early
+ * attempt. For `n = 1` (no `retry:`, or `max_attempts: 1`) this reduces EXACTLY to the prior
+ * single-attempt formula `max(RECLAIM_FLOOR, perAttemptSec + MARGIN)`, so non-retry steps'
+ * horizons are byte-unchanged.
+ *
+ * Issue #140 AMENDMENT + correction (B2): the horizon now consumes the SAME resolved cap the
+ * engine enforces — `(explicit total_timeout_seconds ?? worstCaseScheduleSeconds) + margin`,
+ * via `resolveCapMs` (record §3: `(cap ?? worstCase) + margin`). This is NOT merely "the runtime
+ * enforcement side changed; this function's formula did not" (an earlier, INCORRECT claim this
+ * paragraph made) — the horizon's own formula changed too, and had to: a step declaring an
+ * EXPLICIT `total_timeout_seconds` ABOVE its worst-case schedule (the legitimate long-wait
+ * opt-in this feature exists to support) would otherwise sleep past a horizon computed from the
+ * worst-case schedule ALONE, well before its declared cap — a premature `claim_stale` mid-
+ * legitimate-sleep, exactly the silent-duplicate hazard this program closes. Consuming
+ * `resolveCapMs` closes it: retry-no-cap still reduces to the worst-case schedule (unchanged,
+ * every pre-existing pin stays byte-identical), no-retry still reduces to `perAttemptSec`
+ * (unchanged), and retry-WITH-an-explicit-cap now widens the horizon to `cap + margin` — the
+ * record's mandate. The prior "does not attempt to model `retry_after`" caveat remains retired
+ * for the DEFAULT-cap population for the same reason as before (enforcement now tracks the
+ * declared schedule there too); it is now ALSO honestly retired for the explicit-cap population,
+ * which this correction is what actually makes true.
  */
 export function computeClaimDeadline(definition, stepName, now) {
     const step = definition.steps[stepName];
@@ -63,16 +129,14 @@ export function computeClaimDeadline(definition, stepName, now) {
     const hasFinalizers = Object.values(definition.steps).some((s) => s.execution === 'finalizer');
     if (step.execution !== 'auto' || hasFinalizers)
         return null;
-    const n = step.retry?.max_attempts ?? 1;
     const perAttemptSec = step.timeout_seconds ?? DEFAULT_EXECUTION_TIMEOUT_SECONDS;
-    // Backoffs occur BETWEEN attempts: n-1 of them, for attemptNum 1..n-1 (matches the retry loop's
-    // schedule in execution-loop.ts). computeBackoff returns ms; the horizon is seconds.
-    let backoffSec = 0;
-    if (step.retry !== undefined) {
-        for (let a = 1; a < n; a++)
-            backoffSec += computeBackoff(step.retry, a) / 1000;
-    }
-    const worstCaseSec = n * perAttemptSec + backoffSec;
+    // B2: consume the resolved cap (explicit total_timeout_seconds, when declared, else the shared
+    // worst-case formula) — NOT worstCaseScheduleSeconds directly — so an explicit cap ABOVE the
+    // worst-case schedule widens the horizon instead of leaving it silently short. resolveCapMs
+    // returns MILLISECONDS; this function works in SECONDS throughout, hence the /1000.
+    const worstCaseSec = step.retry !== undefined
+        ? resolveCapMs(step.retry, perAttemptSec * 1000) / 1000
+        : perAttemptSec;
     const horizonSeconds = Math.max(RECLAIM_FLOOR_SECONDS, worstCaseSec + RECLAIM_MARGIN_SECONDS);
     return new Date(now.getTime() + horizonSeconds * 1000).toISOString();
 }

package/dist/engine/claim-liveness.js.map

@@ -1 +1 @@
-{"version":3,"file":"claim-liveness.js","sourceRoot":"","sources":["../../src/engine/claim-liveness.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claim-liveness.js","sourceRoot":"","sources":["../../src/engine/claim-liveness.ts"],"names":[],"mappings":"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"}

package/dist/engine/execution-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-loop.d.ts","sourceRoot":"","sources":["../../src/engine/execution-loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution-loop.d.ts","sourceRoot":"","sources":["../../src/engine/execution-loop.ts"],"names":[],"mappings":"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"}

package/dist/engine/execution-loop.js

@@ -7,7 +7,7 @@ import { captureEvidence } from '../evidence/snapshot.js';
 import { validateInputSchema, validateOutputSchema, validateTraceSchema, } from '../validation/input-schema.js';
 import { normalizeTrace } from './trace-normalizer.js';
 import { TERMINAL_PHASES, isTerminalPhase, DRAIN_CEILING_SECONDS } from './lifecycle.js';
-import { omitClaim, shouldEnforceTimeout, DEFAULT_EXECUTION_TIMEOUT_SECONDS, } from './claim-liveness.js';
+import { omitClaim, shouldEnforceTimeout, DEFAULT_EXECUTION_TIMEOUT_SECONDS, resolveCapMs, sleepWouldExceedCap, } from './claim-liveness.js';
 import { computeBackoff } from './backoff.js';
 import { checkPreconditions, evaluateAllPreconditions, evaluateGuardConditions, } from './precondition.js';
 import { ExtensionRegistry } from '../extensions/registry.js';
@@ -36,7 +36,9 @@ function withTimeout(dispatch, ms, stepName) {
                 category: 'ENGINE',
                 agentAction: 'report_to_user',
                 retryable: false,
-                details: { stepName, timeout_ms: ms },
+                // issue #140: details gain `stepId` alongside the pre-existing `stepName` — additive,
+                // never removes stepName (byte-identical shape for any existing consumer of that key).
+                details: { stepName, stepId: stepName, timeout_ms: ms },
             }));
         }, ms);
     });
@@ -995,14 +997,58 @@ export async function executeStep(store, definition, options) {
     // A3: every `execution: 'auto'` step is bounded — authored timeout_seconds if declared, else the
     // generous DEFAULT_EXECUTION_TIMEOUT_SECONDS default. Resolved ONCE here (before the retry loop
     // below), not per-attempt. Agent/guard steps (shouldEnforceTimeout false) are untouched: agent
-    // dispatch stays the instant-return no-op it always was, never wrapped in withTimeout.
-    // effectiveTimeoutSeconds is the single source of truth; timeoutMs is derived from it so the
-    // two can never diverge. It is also surfaced onto the evidence snapshot below.
+    // dispatch stays the instant-return no-op it always was, never wrapped in withTimeout — this
+    // A3 invariant is preserved verbatim by issue #140 below (the finalizer-drain withTimeout at
+    // buildFinalizedSeal is a separate, DRAIN_CEILING-bounded wrap, outside this cap's scope).
+    // effectiveTimeoutSeconds is the single source of truth for the step's OWN declared/default
+    // per-attempt bound; timeoutMs is derived from it so the two can never diverge.
+    //
+    // Issue #140 (retryable timeout + total-time cap): capMs/capStart/capExhausted resolve ONCE
+    // here too (same as timeoutMs), gated on `enforceTimeout && retryConfig !== undefined` — every
+    // retry-configured auto step now gets a default total-time cap (resolveCapMs), whether or not it
+    // opts into `retry.on_timeout`. What is NOT resolved once anymore is the PER-ATTEMPT bound
+    // actually passed to withTimeout: each attempt clips to whatever budget remains (see
+    // `effectiveMs` inside the loop below) — a later attempt's evidence `effective_timeout_seconds`
+    // can therefore be SMALLER than this outer `effectiveTimeoutSeconds` once the cap starts biting.
+    //
+    // Zombie-stacking split (A3 caveat, sharpened by #140's `on_timeout` in-place retry): a timeout
+    // frees the RUNNER, not the work — `withTimeout` races the dispatch against a timer and moves on
+    // the instant the timer wins, but does not stop a handler/adapter that ignores the abort signal
+    // (or a remote server still processing an already-aborted request). Whether an abandoned call
+    // can STACK behind a subsequent retry attempt splits on the handler's own shape: a SYNCHRONOUS
+    // (blocking) handler can never stack one — it monopolizes the event loop, so nothing else
+    // (including the next attempt's own dispatch) can even begin until it returns or the process is
+    // killed. An ASYNCHRONOUS handler that ignores its abort signal CAN stack: each timed-out-and-
+    // retried attempt leaves its own abandoned promise running, so up to `max_attempts − 1` zombies
+    // can accumulate behind the one currently-live attempt (attempts 1..max_attempts−1 each
+    // potentially zombie-and-retry; the final attempt is the "+1" that is never itself abandoned by
+    // this loop). This was always true pre-#140 for a step whose retry consumed a NORMAL retryable
+    // error mid-flight of a slow-but-not-yet-timed-out prior attempt; #140 sharpens it because
+    // `on_timeout` now lets a STEP_TIMEOUT itself mint a retry, so a maximally adversarial handler
+    // can produce the full max_attempts−1 zombie count from timeouts alone. The zombie count stays
+    // cap-BOUNDED (the total-time cap bounds how many attempts the ENGINE'S retry loop can mint —
+    // it does not, and cannot, reach into an already-abandoned zombie running on a remote server
+    // outside realm's control).
     const enforceTimeout = stepDef !== undefined && shouldEnforceTimeout(stepDef);
     const effectiveTimeoutSeconds = enforceTimeout
         ? (stepDef.timeout_seconds ?? DEFAULT_EXECUTION_TIMEOUT_SECONDS)
         : undefined;
     const timeoutMs = effectiveTimeoutSeconds !== undefined ? effectiveTimeoutSeconds * 1000 : undefined;
+    const capMs = enforceTimeout && retryConfig !== undefined ? resolveCapMs(retryConfig, timeoutMs) : undefined;
+    const capStart = Date.now(); // wall-clock — the SAME clock the claim horizon is measured against
+    let capExhausted = false;
+    const remainingMs = () => capMs - (Date.now() - capStart);
+    // Programmatic-gate advisory (#119-preserving): the loader refuses `on_timeout: true` without
+    // `idempotent: true` at load (E1) — but a hand-built WorkflowDefinition (a custom embedder, or a
+    // test) can bypass the loader entirely. Surface the same rule here, at the engine surface, as a
+    // pure advisory (never gates, never changes behavior — the willRetry conjunct below already
+    // requires `idempotent === true` independently). Threaded through `traceWarnings` so it reaches
+    // every settle path this function has, INCLUDING the handler-abort return path below (which
+    // otherwise hardcodes `warnings: []`).
+    if (stepDef !== undefined && retryConfig?.on_timeout === true && stepDef.idempotent !== true) {
+        traceWarnings.push(`retry.on_timeout ignored: step '${options.command}' is not declared idempotent — declare ` +
+            `both 'idempotent: true' and 'retry.on_timeout: true'; YAML workflows are refused at load.`);
+    }
     // Create a stable rate-limiter registry for all retry attempts of this step.
     // Shared state ensures that a pause() triggered on attempt N is still in effect
     // when the proactive acquire() runs on attempt N+1. When the caller provides an
@@ -1015,11 +1061,34 @@ export async function executeStep(store, definition, options) {
     const allEvidence = [];
     let currentWarn;
     for (let attemptNum = 1; attemptNum <= maxAttempts; attemptNum++) {
+        // SITE (a) — issue #140, loop-top, BEFORE attemptsUsed is assigned: attempt 1 ALWAYS
+        // proceeds regardless of capMs (the `attemptNum > 1` conjunct) — this guard exists solely for
+        // the clock-anomaly window between `capStart` above and here (a suspend/resume or NTP forward
+        // jump), never to gate the very first attempt.
+        if (capMs !== undefined && attemptNum > 1 && remainingMs() <= 0) {
+            capExhausted = true;
+            break;
+        }
         attemptsUsed = attemptNum;
         const startedAt = new Date();
         let attemptOutput = {};
         let attemptError = null;
         let resolvedParams;
+        // Per-attempt effective timeout (issue #140): uniform full-clip to whatever cap budget
+        // remains. Clip floor `max(0, remainingMs())` ensures a clock anomaly (see SITE (a) above)
+        // never passes a negative ms to withTimeout. capMs undefined ⇒ effectiveMs === timeoutMs,
+        // byte-identical to pre-#140 behavior (every non-retry-configured, or unopted-uncapped-by-
+        // total_timeout_seconds-being-absent-pre-amendment, auto step). `clippedToMs` records the
+        // per-attempt evidence value ONLY when the cap actually reduced the bound below the step's
+        // own declared/default timeout — never on an uncapped or not-yet-biting attempt.
+        const effectiveMs = timeoutMs !== undefined
+            ? capMs !== undefined
+                ? Math.min(timeoutMs, Math.max(0, remainingMs()))
+                : timeoutMs
+            : undefined;
+        const clippedToMs = capMs !== undefined && effectiveMs !== undefined && effectiveMs < timeoutMs
+            ? effectiveMs
+            : undefined;
         try {
             const makeCall = (signal) => {
                 if (stepDef?.execution === 'auto' && stepDef.uses_service !== undefined) {
@@ -1050,8 +1119,8 @@ export async function executeStep(store, definition, options) {
                         .then((result) => ({ output: result, resolvedParams: undefined }));
                 }
             };
-            const callResult = timeoutMs !== undefined
-                ? await withTimeout((signal) => makeCall(signal), timeoutMs, options.command)
+            const callResult = effectiveMs !== undefined
+                ? await withTimeout((signal) => makeCall(signal), effectiveMs, options.command)
                 : await makeCall();
             // Handle graceful abort from a handler returning { abort: { message } }.
             if (callResult.handlerAbort !== undefined) {
@@ -1114,7 +1183,9 @@ export async function executeStep(store, definition, options) {
                     status: 'ok',
                     data: {},
                     evidence: [abortEvidence],
-                    warnings: [],
+                    // Issue #140: was hardcoded `[]` — now threads traceWarnings (e.g. the programmatic
+                    // on_timeout/idempotent gate advisory above) so it survives this settle path too.
+                    warnings: mergeWarnings(traceWarnings),
                     errors: [],
                     context_hint: `Handler step '${options.command}' aborted the run: ${abortMessage}`,
                     run_phase: (persistedAbortRun ?? abortedRun).run_phase,
@@ -1166,7 +1237,11 @@ export async function executeStep(store, definition, options) {
             ...(options.stepMeta?.toolCalls !== undefined
                 ? { toolCalls: options.stepMeta.toolCalls }
                 : {}),
-            ...(effectiveTimeoutSeconds !== undefined ? { effectiveTimeoutSeconds } : {}),
+            // issue #140: PER-ATTEMPT value (may be smaller than the outer effectiveTimeoutSeconds once
+            // the cap starts clipping) — byte-identical to the pre-#140 outer value whenever capMs is
+            // undefined or hasn't bitten yet.
+            ...(effectiveMs !== undefined ? { effectiveTimeoutSeconds: effectiveMs / 1000 } : {}),
+            ...(clippedToMs !== undefined ? { clippedToMs } : {}),
             // Gate trace to agent steps only — drop silently for auto/adapter/handler steps.
             // When pre-normalized (WAL merge + schema validation ran), pass the pre-normalized
             // result to avoid double normalization. Also handle WAL-only case (options.trace may
@@ -1185,24 +1260,68 @@ export async function executeStep(store, definition, options) {
             break;
         }
         dispatchError = attemptError;
-        const willRetry = retryConfig !== undefined && attemptError.retryable && attemptNum < maxAttempts;
+        // SITE (b) — issue #140, post-attempt, AFTER dispatchError is set, BEFORE willRetry: the
+        // primary capExhausted setter (site (a) above only catches the loop-top clock-anomaly window;
+        // site (c) below re-checks once more right before an actual sleep). Fires on ANY dispatch
+        // error once the cap is spent, not just STEP_TIMEOUT — the cap bounds the step's total
+        // budget, regardless of which error exhausted it.
+        if (capMs !== undefined && remainingMs() <= 0) {
+            capExhausted = true;
+        }
+        const willRetry = (retryConfig !== undefined && attemptError.retryable && attemptNum < maxAttempts) ||
+            // issue #140 (AMENDED): a STEP_TIMEOUT may ALSO retry in place when the step opted in via
+            // `retry.on_timeout: true` AND attested `idempotent: true` (the concurrency-safety gate).
+            // ALL SIX conjuncts are required; `capMs !== undefined` enforces opted⇒capped
+            // structurally — this disjunct is inert off the enforced auto class even for a hand-built
+            // definition bypassing the loader's E1 gate on a non-auto step, since capMs is undefined
+            // there (shouldEnforceTimeout false ⇒ enforceTimeout false ⇒ capMs undefined) — see R11 in
+            // the design record.
+            (attemptError.code === 'STEP_TIMEOUT' &&
+                capMs !== undefined &&
+                retryConfig?.on_timeout === true &&
+                stepDef.idempotent === true &&
+                !capExhausted &&
+                attemptNum < maxAttempts);
         if (willRetry) {
             const baseBackoff = computeBackoff(retryConfig, attemptNum);
             const retryAfterMs = attemptError instanceof WorkflowError && attemptError.retry_after !== undefined
                 ? attemptError.retry_after * 1000
                 : 0;
-            await delayMs(Math.max(baseBackoff, retryAfterMs));
+            const waitMs = Math.max(baseBackoff, retryAfterMs);
+            // SITE (c) — issue #140, sleep guard, BEFORE every backoff/retry_after sleep (`>=`: an
+            // exact-fit sleep is doomed too — never sleep into a wall). dispatchError already holds the
+            // ACTUAL last error (e.g. a 429 with retry_after in its details); the post-loop wrap gate
+            // below decides whether/how to wrap it — this site only decides whether to sleep at all.
+            if (capMs !== undefined && sleepWouldExceedCap(Date.now() - capStart, waitMs, capMs)) {
+                capExhausted = true;
+                break;
+            }
+            await delayMs(waitMs);
         }
         else {
             break;
         }
     }
-    if (dispatchError !== null && retryConfig !== undefined && attemptsUsed === maxAttempts) {
+    if (dispatchError !== null &&
+        retryConfig !== undefined &&
+        (attemptsUsed === maxAttempts || capExhausted)) {
         const lastError = dispatchError;
+        // issue #140: stamp the discriminator on the LAST evidence snapshot regardless of whether the
+        // #134 carve-out below actually wraps dispatchError — the carve-out's recoverable settle path
+        // (Step 5) never wraps, so this evidence stamp is the ONLY durable record of *why* the step
+        // stopped retrying in that case. `exhausted_by: 'total_timeout'` wins the both-true tie (a
+        // step whose LAST attempt both used its final slot and drained the cap is reported as
+        // cap-caused — the more actionable of the two labels for an operator).
+        const lastSnap = allEvidence[allEvidence.length - 1];
+        if (lastSnap !== undefined) {
+            lastSnap.exhausted_by = capExhausted ? 'total_timeout' : 'attempts';
+        }
         // #134: do NOT wrap a recoverable-incapability error (a max_attempts:1 not-registered failure
         // hits attemptsUsed === maxAttempts). The STEP_RETRY_EXHAUSTED wrap discards the inner code, which
         // would rob Step 5 of the discriminator it needs to settle recoverably. Leave dispatchError as the
-        // original not-registered error; all other codes wrap unchanged.
+        // original not-registered error; all other codes wrap unchanged. This carve-out guards BOTH
+        // disjuncts above (attempts-exhaustion and cap-exhaustion alike) — a capped-but-not-registered
+        // step never wraps into STEP_RETRY_EXHAUSTED either.
         const isRecoverableIncapability = lastError instanceof WorkflowError &&
             (lastError.code === 'ENGINE_HANDLER_NOT_REGISTERED' ||
                 lastError.code === 'ENGINE_ADAPTER_NOT_REGISTERED');
@@ -1216,6 +1335,7 @@ export async function executeStep(store, definition, options) {
                     stepName: options.command,
                     attempts: attemptsUsed,
                     lastError: lastError.message,
+                    exhausted_by: capExhausted ? 'total_timeout' : 'attempts',
                     ...(lastError.retry_after !== undefined ? { retry_after: lastError.retry_after } : {}),
                 },
             });
@@ -1448,6 +1568,14 @@ export async function executeStep(store, definition, options) {
             warnings: mergeWarnings(traceWarnings, storeCleanupWarning ?? walCleanupWarning),
             errors: [dispatchError.message],
             agent_action: effectiveAction,
+            // issue #140 (D3 §2, discriminator OBSERVABLE): additive-optional — lets a caller
+            // discriminate `STEP_RETRY_EXHAUSTED`'s `exhausted_by` (or any other terminal code) without
+            // parsing `errors[0]`'s message text. Mirrors the errorEnvelope()/buildPreExecutionErrorEnvelope
+            // pattern used elsewhere in this file.
+            error_code: dispatchError.code,
+            ...(Object.keys(dispatchError.details).length > 0
+                ? { error_details: dispatchError.details }
+                : {}),
             ...(dispatchError.retry_after !== undefined
                 ? { retry_after: dispatchError.retry_after }
                 : {}),