@sensigo/realm 0.26.0 → 0.28.0

package/dist/engine/execution-loop.js

@@ -1,11 +1,13 @@
 import { extensionIdentityDiffers } from '../types/extension-identity.js';
 import { WorkflowError } from '../types/workflow-error.js';
 import { persistsField } from '../store/store-fidelity.js';
+import { storeDeclaresSeal, storeDeclaresNonceCarriage } from '../store/trace-buffer-store.js';
+import { partitionBufferedEntries } from './trace-adoption.js';
 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';
@@ -34,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);
     });
@@ -348,13 +352,75 @@ export function buildNextActions(definition, run) {
         .map((name) => stepToNextAction(name, definition.steps[name], context));
 }
 /**
- * Merges call-scoped trace-schema warnings with an optional cleanup warning into
- * a single warnings array. Trace warnings are listed first (deterministic order).
+ * Merges call-scoped trace-schema warnings with any number of optional extra warnings into a
+ * single warnings array. Trace warnings are listed first (deterministic order); `extraWarnings`
+ * entries are appended in call order, `undefined` entries skipped. Variadic since issue #207
+ * PR-2 (the success-settle path now has TWO independent optional warnings to merge — a
+ * handler-level warning and a WAL-cleanup warning — where every earlier call site had at most
+ * one).
  */
-function mergeWarnings(traceWarnings, cleanupWarning) {
-    if (traceWarnings.length === 0 && cleanupWarning === undefined)
+function mergeWarnings(traceWarnings, ...extraWarnings) {
+    const defined = extraWarnings.filter((w) => w !== undefined);
+    if (traceWarnings.length === 0 && defined.length === 0)
         return [];
-    return cleanupWarning !== undefined ? [...traceWarnings, cleanupWarning] : [...traceWarnings];
+    return [...traceWarnings, ...defined];
+}
+/**
+ * Compensating un-claim (issue #207 PR-2, D3 §5): built from `pendingRun` — the record OUR OWN
+ * `claimStep` call returned, never a fresh get — removing the step from `in_progress_steps` AND
+ * `claims[step]` in the SAME mutation (the settle-site invariant every other settle path in this
+ * file upholds), plus an audit-evidence entry. The caller CAS's this against `pendingRun.version`
+ * (by passing the returned record straight to `store.update`): any intervening write (a
+ * concurrent settle, reclaim, or second claim) bumps version, so this compensating un-claim can
+ * never stomp it — a CAS mismatch means some other actor already resolved the claim, and the
+ * caller must stop immediately rather than retry, leaving the claim exactly as that actor left
+ * it. A step already absent from `in_progress_steps` (should not happen here, but the filter is
+ * naturally idempotent) is simply a no-op mutation, not a special case.
+ */
+function buildCompensatingUnclaim(pendingRun, stepName, now) {
+    const auditEvidence = captureEvidence({
+        stepId: stepName,
+        startedAt: now,
+        completedAt: now,
+        input: {},
+        output: {
+            compensating_unclaim: true,
+            reason: 'adoption-read failure after claim',
+            unclaimed_at: now.toISOString(),
+        },
+    });
+    return {
+        ...pendingRun,
+        in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== stepName),
+        claims: omitClaim(pendingRun.claims, stepName),
+        evidence: [...pendingRun.evidence, auditEvidence],
+    };
+}
+/**
+ * Guard for the settle-time seal attempt (issue #197 PR-2, deliverable 1f) — ONE lock-free
+ * `store.get` re-verifying the run exists and this step has actually LEFT `in_progress_steps`
+ * (i.e. our own settling `store.update` already landed) — the "purge-guard shape" (mirrors
+ * #184's terminal-re-verify-under-lock precedent). In the normal case this always passes: by the
+ * time either settle site calls `sealFenced`, the settling update has already committed
+ * synchronously just above it. A run genuinely gone (e.g. concurrently purged) surfaces as
+ * `store.get`'s own typed `STATE_RUN_NOT_FOUND` throw — deliberately NOT special-cased here; it
+ * propagates as an ordinary guard THROW, which the caller's uniform "a throw ⇒ warn + skip the
+ * delete" handling already covers correctly (residue-not-loss either way).
+ */
+function buildSettleSealGuard(store, runId, stepName) {
+    return async () => {
+        const fresh = await store.get(runId);
+        if (fresh.in_progress_steps.includes(stepName)) {
+            throw new WorkflowError(`Refusing to seal trace buffer for run '${runId}' step '${stepName}': the step is still ` +
+                'in_progress (the settling update has not yet landed) — residue-not-loss, the live WAL ' +
+                'is left intact.', {
+                code: 'STATE_STEP_PENDING',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: true,
+            });
+        }
+    };
 }
 /**
  * Issue #185 Fix 1 (budget-priority): builds the merged, canonicalized trace for an agent step,
@@ -617,17 +683,57 @@ export async function executeStep(store, definition, options) {
     let preNormalizedTrace;
     let walEntries = [];
     let preClaimSchemaResult;
+    // issue #197 PR-2 (design §3, the activation gate): computed once — options.traceBufferStore
+    // is invariant for this whole call. `carriageActive` also gates whether the NEW
+    // adopted_own/adopted_anonymous/preserved_foreign fields are surfaced on the 'ok' envelope
+    // (absent entirely on a bare-floor store, never just zeroed) — see the settle-site comment.
+    const carriageActive = options.traceBufferStore !== undefined && storeDeclaresNonceCarriage(options.traceBufferStore);
+    const effectiveClaimantNonce = carriageActive ? options.writerNonce : undefined;
+    // Post-claim adoption partition (issue #197 PR-2) — lifted to this outer scope because it is
+    // read again at the settle sites (seal-vs-delete decision) and at 'ok' envelope build, both far
+    // below the post-claim block that computes it. `undefined` for a non-agent step (never computed
+    // there) — the settle sites and envelope build both treat that as "nothing to preserve/report".
+    let adoptionPartition;
     if (stepDef?.execution === 'agent') {
-        walEntries =
-            options.traceBufferStore !== undefined
-                ? await options.traceBufferStore.read(options.runId, options.command)
-                : [];
+        // issue #207 PR-2 (D3 §5): wrapped — a rejection here (e.g. lock contention under a fenced
+        // trio's serialized reads) happens BEFORE claimStep, so no claim exists to compensate for;
+        // return a typed, retryable envelope instead of letting the read throw uncaught.
+        try {
+            walEntries =
+                options.traceBufferStore !== undefined
+                    ? await options.traceBufferStore.read(options.runId, options.command)
+                    : [];
+        }
+        catch (err) {
+            return makeErrorEnvelope(options, run, new WorkflowError('Failed to read trace buffer before claiming step', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: true,
+                details: {
+                    step_id: options.command,
+                    cause: err instanceof Error ? err.message : String(err),
+                },
+            }), definition);
+        }
+        // issue #197 PR-2 (design §3, missing-leg advisory): a caller-supplied nonce this store
+        // cannot carry is IGNORED for adoption purposes (carriageActive is false) — loudly, once per
+        // call, so a minting client discovers the silent floor rather than assuming attribution.
+        if (options.writerNonce !== undefined && !carriageActive) {
+            traceWarnings.push('writer_nonce ignored: the trace-buffer store does not declare writer_nonce_carriage — ' +
+                'adoption falls back to the honest floor');
+        }
         const hasAnyTrace = walEntries.length > 0 || (options.trace !== undefined && options.trace.length > 0);
         if (hasAnyTrace) {
+            // issue #197 PR-2 (design §2, ADOPTION_CONGRUENCE): the pre-claim enforce-gate validates
+            // ONLY the adopted subset — a foreign-nonce-only WAL must never gate a (nonced) claimant.
+            // Congruence with the post-claim partition below is mandatory: both call the SAME
+            // `partitionBufferedEntries` helper against the SAME `effectiveClaimantNonce`.
+            const prClaimPartition = partitionBufferedEntries(walEntries, effectiveClaimantNonce);
             // issue #185 Fix 1: budget-priority merge (see buildPriorityMergedTrace's own doc) — this
             // pre-claim pass exists only to feed validateTraceSchema below; its RESULT is discarded
             // (not stored into the outer preNormalizedTrace) once the enforce-gate decision is made.
-            const preClaimNormalized = buildPriorityMergedTrace(walEntries, options.trace);
+            const preClaimNormalized = buildPriorityMergedTrace(prClaimPartition.adopted, options.trace);
             // Validate trace schema if configured (unchanged call site).
             if (stepDef.trace_schema !== undefined) {
                 const mode = stepDef.trace_validation_mode ?? 'warn';
@@ -709,14 +815,51 @@ export async function executeStep(store, definition, options) {
     // complete, post-claim set, which is also what the captureEvidence call site further below
     // keys its `stepDef?.execution === 'agent' && walEntries.length > 0` check on.
     if (stepDef?.execution === 'agent') {
-        walEntries =
-            options.traceBufferStore !== undefined
-                ? await options.traceBufferStore.read(options.runId, options.command)
-                : [];
+        // issue #207 PR-2 (D3 §5): wrapped — a rejection here happens AFTER claimStep, so a claim IS
+        // outstanding. COMPENSATING UN-CLAIM: built from `pendingRun` (our own claimStep result,
+        // never a fresh get) and CAS'd against `pendingRun.version` — an intervening write (someone
+        // else already resolved this claim) makes the CAS fail with STATE_SNAPSHOT_MISMATCH, in
+        // which case we stop immediately and leave the claim exactly as it is. Either way (compensated
+        // or left in place), the caller always gets the same typed retryable envelope — see
+        // buildCompensatingUnclaim's own doc for the full contract.
+        try {
+            walEntries =
+                options.traceBufferStore !== undefined
+                    ? await options.traceBufferStore.read(options.runId, options.command)
+                    : [];
+        }
+        catch (err) {
+            try {
+                await store.update(buildCompensatingUnclaim(pendingRun, options.command, new Date()));
+            }
+            catch {
+                // CAS mismatch (someone else already resolved the claim) or any other failure to even
+                // un-claim: stop immediately, leave the claim exactly as it is — never retry here.
+            }
+            return makeErrorEnvelope(options, pendingRun, new WorkflowError('Failed to read trace buffer after claiming step', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: true,
+                details: {
+                    step_id: options.command,
+                    cause: err instanceof Error ? err.message : String(err),
+                },
+            }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+        }
+        // issue #197 PR-2 (design §2): the SAME predicate as the pre-claim pass, now over the
+        // complete post-claim set. Lifted to `adoptionPartition` (outer scope) — read again at the
+        // settle sites (seal-vs-delete) and at 'ok' envelope build, both below this block.
+        adoptionPartition = partitionBufferedEntries(walEntries, effectiveClaimantNonce);
+        // issue #197 PR-2 (design §2, the "keying pin"): this condition stays keyed on the FULL
+        // post-claim WAL set, NOT the adopted subset — a foreign-only WAL (adoptionPartition.adopted
+        // empty) with no options.trace must still enter this block so foreign_lines_preserved below
+        // is captured into trace_summary; otherwise that count is silently lost.
         if (walEntries.length > 0 || (options.trace !== undefined && options.trace.length > 0)) {
             // issue #185 Fix 1: same budget-priority merge as the pre-claim pass, now over the
-            // complete post-claim set — this is the value captured into evidence.
-            preNormalizedTrace = buildPriorityMergedTrace(walEntries, options.trace);
+            // complete post-claim ADOPTED subset only — a foreign line never reaches canonical
+            // evidence (issue #197 PR-2, design §2).
+            preNormalizedTrace = buildPriorityMergedTrace(adoptionPartition.adopted, options.trace);
             // Carry over the enforce-gate's schema-validation result (computed pre-claim against a
             // possibly-incomplete set) rather than re-validating here — Fix 2 deliberately keeps
             // validation pre-claim (see that block's comment); this just republishes its verdict onto
@@ -726,13 +869,48 @@ export async function executeStep(store, definition, options) {
                 preNormalizedTrace.summary.validation_mode = preClaimSchemaResult.validation_mode;
                 preNormalizedTrace.summary.validation_errors = preClaimSchemaResult.validation_errors;
             }
-            // issue #185 Fix 3: the honest label. Any buffer/WAL line adopted here is NOT attributable
-            // to this execution — the agent trace buffer has no single owner, so an adopted line may
-            // originate from a prior attempt (e.g. a crashed run this one resumed) or a concurrent one
-            // racing on the same (run, step). Present only when buffer lines were actually adopted;
-            // an options.trace-only execution carries no caveat.
-            if (walEntries.length > 0) {
-                preNormalizedTrace.summary.buffered_lines_adopted = walEntries.length;
+            // issue #185 Fix 3 / issue #197 PR-2 (design §2/§6): the three-way honest split.
+            // buffered_lines_adopted now counts ONLY the adopted-ANONYMOUS entries (bare-adopted by a
+            // ⊥ claimant) — for all-bare traffic this is numerically IDENTICAL to before #197 (every
+            // adopted line was, and still is, bare). attributed_lines_adopted counts own-nonce
+            // adoptions — NO caveat (design §6 wording, verbatim below). foreign_lines_preserved counts
+            // lines from a different writer, preserved (sealed where supported) but never adopted —
+            // its accompanying pointer warning is the only way an agent learns to retrieve them.
+            if (adoptionPartition.adopted_anonymous > 0) {
+                preNormalizedTrace.summary.buffered_lines_adopted = adoptionPartition.adopted_anonymous;
+            }
+            if (adoptionPartition.adopted_own > 0) {
+                preNormalizedTrace.summary.attributed_lines_adopted = adoptionPartition.adopted_own;
+            }
+            if (adoptionPartition.preserved_foreign > 0) {
+                preNormalizedTrace.summary.foreign_lines_preserved = adoptionPartition.preserved_foreign;
+                traceWarnings.push(`${adoptionPartition.preserved_foreign} buffered line(s) from a different writer were ` +
+                    'preserved, not adopted — retrieve via `realm run export`');
+            }
+            // issue #197 PR-2 (design §6, the half-minted advisory): signature heuristics over the RAW
+            // walEntries/foreign set (never the adopted subset — these two cases are both about
+            // content this claimant did NOT adopt), neutral phrasing, values never echoed. Mutually
+            // exclusive by claimant type (nonced vs ⊥), so an if/else-if is exact, not a simplification.
+            if (effectiveClaimantNonce !== undefined &&
+                walEntries.length > 0 &&
+                walEntries.every((e) => e._nonce === undefined)) {
+                // A nonced claimant found nothing but bare lines — if those are this SAME attempt's own
+                // earlier append() calls, the client minted inconsistently (nonce on execute_step but not
+                // on the preceding append_trace calls, or vice versa).
+                traceWarnings.push(`the ${walEntries.length} buffered line(s) were bare and were preserved, not adopted — ` +
+                    'if they are yours from this same attempt, you minted inconsistently (mint on both ' +
+                    'calls, or neither)');
+            }
+            else if (effectiveClaimantNonce === undefined && adoptionPartition.foreign.length > 0) {
+                const distinctForeignNonces = new Set(adoptionPartition.foreign.map((e) => e._nonce));
+                if (distinctForeignNonces.size === 1) {
+                    // A bare claimant found every foreign line under exactly ONE other nonce — if that
+                    // nonce is this SAME attempt's own (minted on append_trace but the execute_step call
+                    // stayed bare), the client minted inconsistently.
+                    traceWarnings.push(`${adoptionPartition.foreign.length} line(s) under a different writer_nonce were ` +
+                        'preserved, not adopted — if these are yours from this same attempt, you minted ' +
+                        'inconsistently');
+                }
             }
         }
     }
@@ -819,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
@@ -839,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) {
@@ -874,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) {
@@ -938,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,
@@ -990,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
@@ -1009,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');
@@ -1040,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 } : {}),
                 },
             });
@@ -1092,14 +1388,15 @@ export async function executeStep(store, definition, options) {
             catch (storeErr) {
                 blockStoreWarning = `Failed to persist capability block: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
             }
-            let blockWalWarning;
-            try {
-                // Delete WAL after run state is written — the step's entries are now in evidence.
-                await options.traceBufferStore?.delete(options.runId, options.command);
-            }
-            catch (walErr) {
-                blockWalWarning = `Failed to clean up trace buffer after capability block: ${walErr instanceof Error ? walErr.message : String(walErr)}`;
-            }
+            // issue #207 PR-2 (D3 §5): NO WAL delete belongs on this capability-block settle path — the
+            // prior try/catch here was removed, not just gated. Contract-consistency hygiene, not a
+            // functional fix: capability-block is reachable ONLY for `execution: 'auto'` steps
+            // (ENGINE_HANDLER_NOT_REGISTERED/ENGINE_ADAPTER_NOT_REGISTERED mint only in the
+            // auto-dispatch branches), and a WAL only ever exists for `execution: 'agent'` steps
+            // (`append_trace` refuses non-agent steps) — DISJOINT populations; there is no in-repo
+            // blocked-path WAL to clean up. A custom embedder whose dispatcher throws NOT_REGISTERED
+            // for an agent step would leave WAL residue reaped at purge (an enumerated, accepted
+            // residue class — D3 §8 residual 6), never silently destroyed here.
             // Non-terminal 'stop' → 'report_to_user' via the existing mapping: a human must provision the
             // runner (or re-run on a capable one); no further progress is possible on THIS runner.
             const blockedAction = resolvePostDispatchAgentAction(dispatchError, false);
@@ -1124,7 +1421,7 @@ export async function executeStep(store, definition, options) {
                 status: 'error',
                 data: {},
                 evidence: allEvidence,
-                warnings: mergeWarnings(traceWarnings, blockStoreWarning ?? blockWalWarning),
+                warnings: mergeWarnings(traceWarnings, blockStoreWarning),
                 errors: [dispatchError.message],
                 agent_action: blockedAction,
                 error_code: recoverableCode,
@@ -1179,12 +1476,60 @@ export async function executeStep(store, definition, options) {
             storeCleanupWarning = `Failed to persist step failure: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
         }
         let walCleanupWarning;
-        try {
-            // Delete WAL after run state is written for failure — entries are now in evidence.
-            await options.traceBufferStore?.delete(options.runId, options.command);
-        }
-        catch (walErr) {
-            walCleanupWarning = `Failed to clean up trace buffer after step failure: ${walErr instanceof Error ? walErr.message : String(walErr)}`;
+        // issue #207 PR-2 (D3 §5): gate the WAL cleanup on the preceding store.update having actually
+        // SUCCEEDED (persistedRun defined) — a failed persist leaves the step in_progress with its
+        // trace already read into an evidence write that never landed anywhere durable; the WAL is
+        // the SOLE remaining evidence copy until reclaim recovers the wedge (#186 posture). Reclaim's
+        // own drain (reclaim-step.ts) warns with the destroyed entry count when it eventually clears
+        // this same buffer.
+        //
+        // issue #197 PR-2 (deliverable 1f): when this step's post-claim read found foreign (preserved,
+        // not adopted) lines AND the store declares `seal`, retire the WAL to a sealed artifact
+        // instead of destroying it — `preserved_foreign === 0` (the overwhelming common case, and the
+        // ONLY case on a non-seal-declaring store, since carriage requires seal by the ladder) takes
+        // the exact same plain `delete()` this always has, below, byte-identical.
+        if (persistedRun !== undefined) {
+            let performPlainDelete = true;
+            if (adoptionPartition !== undefined &&
+                adoptionPartition.preserved_foreign > 0 &&
+                options.traceBufferStore !== undefined &&
+                storeDeclaresSeal(options.traceBufferStore)) {
+                try {
+                    const sealResult = await options.traceBufferStore.sealFenced(options.runId, options.command, buildSettleSealGuard(store, options.runId, options.command));
+                    if (sealResult.sealed) {
+                        performPlainDelete = false;
+                        walCleanupWarning =
+                            `${adoptionPartition.preserved_foreign} foreign line(s) preserved (sealed) — ` +
+                                'retrieve via `realm run export`';
+                    }
+                    else if (sealResult.reason === 'capped') {
+                        // Fall back to the SAME plain delete below (loud + bounded, never a silent eviction
+                        // of an already-sealed artifact to make room) — the destroyed-count warning names
+                        // exactly what happened; performPlainDelete stays true.
+                        walCleanupWarning = 'preservation cap reached — foreign lines destroyed, not preserved';
+                    }
+                    else {
+                        // 'absent' — the live WAL vanished between the post-claim read and this seal attempt
+                        // (e.g. a concurrent purge/reclaim) — nothing left to delete either; residue-not-loss.
+                        performPlainDelete = false;
+                    }
+                }
+                catch (err) {
+                    // A THROW (lock contention, genuine I/O failure) ⇒ warn + SKIP the delete
+                    // (residue-not-loss; the fence refuses further appends; purge reaps).
+                    performPlainDelete = false;
+                    walCleanupWarning = `Failed to seal trace buffer after step failure: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
+            if (performPlainDelete) {
+                try {
+                    // Delete WAL after run state is written for failure — entries are now in evidence.
+                    await options.traceBufferStore?.delete(options.runId, options.command);
+                }
+                catch (walErr) {
+                    walCleanupWarning = `Failed to clean up trace buffer after step failure: ${walErr instanceof Error ? walErr.message : String(walErr)}`;
+                }
+            }
         }
         // Derive the agent_action from the error semantics and run termination state.
         //
@@ -1223,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 }
                 : {}),
@@ -1413,8 +1766,54 @@ export async function executeStep(store, definition, options) {
         });
         return makeErrorEnvelope(options, pendingRun, internal, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
     }
-    // Delete WAL after successful run update — entries are now in evidence.
-    await options.traceBufferStore?.delete(options.runId, options.command);
+    // Delete WAL after successful run update — entries are now in evidence. issue #207 PR-2 (D3
+    // §5, clause (a) of the unified deletion contract): wrapped in try/catch-to-warning — the
+    // settlement already committed and is durably visible, so a cleanup failure here (e.g. lock
+    // contention) must degrade to a warning, never surface as though the STEP itself failed (this
+    // was previously unwrapped and would have thrown straight out of executeStep).
+    //
+    // issue #197 PR-2 (deliverable 1f): same seal-vs-delete decision as the failure-settle site
+    // above — see its comment for the full outcome table. preserved_foreign === 0 (the common case,
+    // and the ONLY case on a non-seal-declaring store) takes the exact same plain delete() this
+    // always has, byte-identical.
+    let successWalCleanupWarning;
+    {
+        let performPlainDelete = true;
+        if (adoptionPartition !== undefined &&
+            adoptionPartition.preserved_foreign > 0 &&
+            options.traceBufferStore !== undefined &&
+            storeDeclaresSeal(options.traceBufferStore)) {
+            try {
+                const sealResult = await options.traceBufferStore.sealFenced(options.runId, options.command, buildSettleSealGuard(store, options.runId, options.command));
+                if (sealResult.sealed) {
+                    performPlainDelete = false;
+                    successWalCleanupWarning =
+                        `${adoptionPartition.preserved_foreign} foreign line(s) preserved (sealed) — ` +
+                            'retrieve via `realm run export`';
+                }
+                else if (sealResult.reason === 'capped') {
+                    successWalCleanupWarning =
+                        'preservation cap reached — foreign lines destroyed, not preserved';
+                }
+                else {
+                    // 'absent' — residue-not-loss; nothing left to delete either.
+                    performPlainDelete = false;
+                }
+            }
+            catch (err) {
+                performPlainDelete = false;
+                successWalCleanupWarning = `Failed to seal trace buffer after step completion: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+        if (performPlainDelete) {
+            try {
+                await options.traceBufferStore?.delete(options.runId, options.command);
+            }
+            catch (err) {
+                successWalCleanupWarning = `Failed to clean up trace buffer after step completion: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+    }
     // Step 7: Build and return ResponseEnvelope.
     const nextActions = savedRun.terminal_state ? [] : buildNextActions(definition, savedRun);
     const orientation = savedRun.terminal_state
@@ -1429,11 +1828,22 @@ export async function executeStep(store, definition, options) {
         status: 'ok',
         data: output,
         evidence: allEvidence,
-        warnings: mergeWarnings(traceWarnings, currentWarn),
+        warnings: mergeWarnings(traceWarnings, currentWarn, successWalCleanupWarning),
         errors: [],
         context_hint: orientation,
         run_phase: savedRun.run_phase,
         next_actions: nextActions,
+        // issue #197 PR-2 (deliverable 2e): additive per-partition counts, SET BY THE ENGINE (never
+        // the MCP tool layer, which strips data/evidence and never sees per-line nonces). Gated on
+        // `carriageActive` (store CAPABILITY), not on whether a nonce happened to be provided this
+        // call — "absent for bare-floor stores" means incapable, not merely unused-this-time.
+        ...(carriageActive && adoptionPartition !== undefined
+            ? {
+                adopted_own: adoptionPartition.adopted_own,
+                adopted_anonymous: adoptionPartition.adopted_anonymous,
+                preserved_foreign: adoptionPartition.preserved_foreign,
+            }
+            : {}),
     };
 }
 /**
@@ -1824,7 +2234,19 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
     }
     return { ...record, terminal_state: true };
 }
-async function executeChainInternal(store, definition, options, depth, chainedSteps) {
+async function executeChainInternal(store, definition, options, depth, chainedSteps, 
+/**
+ * issue #197 PR-2 (chain-replacement disposition, accepted): a settled DEPTH-0 step (typically
+ * an agent step — never itself recorded in `chainedSteps`, which is auto-steps-only, feeding
+ * the VISIBLE `chained_auto_steps` list) whose own envelope is about to be discarded in favor
+ * of a deeper auto step's envelope would otherwise silently lose its OWN warnings (seal
+ * outcome / half-minted / missing-carriage-leg advisories) — this separate accumulator exists
+ * ONLY to carry those forward; it never touches `chainedSteps`'/`chained_auto_steps`'s shape.
+ * The three NEW adoption counts on that depth-0 envelope are NOT similarly rescued — they
+ * persist authoritatively in the settled step's own `trace_summary` regardless (see
+ * `ResponseEnvelope.adopted_own`'s own doc) — only the warnings are a load-bearing rescue.
+ */
+depth0Warnings) {
     if (depth > MAX_CHAIN_DEPTH) {
         return {
             command: options.command,
@@ -1966,7 +2388,20 @@ async function executeChainInternal(store, definition, options, depth, chainedSt
         // Only agent steps or nothing — stop chain, return with latest next_actions.
         return result;
     }
-    return executeChainInternal(store, definition, { ...options, command: nextAutoStep, input: {} }, depth + 1, chainedSteps);
+    // issue #197 PR-2 (chain-replacement disposition): THIS step's own result is about to be
+    // discarded in favor of the recursive call's — capture its warnings now, before that happens.
+    // Every step past depth 0 in this recursion is guaranteed 'auto' (nextAutoStep's own filter),
+    // so depth === 0 is the ONLY case where a non-auto (agent) step's warnings would otherwise be
+    // lost here (an 'auto' depth-0 step's warnings are already captured above via `chainedSteps`,
+    // so this would double them — the `depth === 0` guard is exact, not merely conservative:
+    // `chainedSteps` only records 'auto' steps, so a depth-0 'auto' step's warnings are recorded
+    // there, never here, avoiding any double-count).
+    if (depth === 0 &&
+        definition.steps[options.command]?.execution !== 'auto' &&
+        result.warnings.length > 0) {
+        depth0Warnings.push(...result.warnings);
+    }
+    return executeChainInternal(store, definition, { ...options, command: nextAutoStep, input: {} }, depth + 1, chainedSteps, depth0Warnings);
 }
 /**
  * Executes a step and automatically chains into subsequent `execution: auto` steps.
@@ -2018,8 +2453,11 @@ export async function executeChain(store, definition, options) {
         registry: options.registry ?? createDefaultRegistry(),
     };
     const chained = [];
-    const result = await executeChainInternal(store, definition, effectiveOptions, 0, chained);
-    const chainWarnings = chained.flatMap((s) => s.warnings ?? []);
+    // issue #197 PR-2 (chain-replacement disposition) — see executeChainInternal's own doc on this
+    // parameter for the full contract.
+    const depth0Warnings = [];
+    const result = await executeChainInternal(store, definition, effectiveOptions, 0, chained, depth0Warnings);
+    const chainWarnings = [...depth0Warnings, ...chained.flatMap((s) => s.warnings ?? [])];
     const envelope = {
         ...result,
         command: options.command,