@sensigo/realm 0.31.2 → 0.33.0

package/dist/engine/execution-loop.js

@@ -3,10 +3,12 @@ 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 { deriveDefaultedSteps } from './defaulted-steps.js';
+import { selectFinalizers } from './settlement.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 { TERMINAL_PHASES, DRAIN_CEILING_SECONDS } from './lifecycle.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';
@@ -376,11 +378,11 @@ function mergeWarnings(traceWarnings, ...extraWarnings) {
     return [...traceWarnings, ...defined];
 }
 /**
- * Pure helper (issue #220 PR-2, D6): scans `sealDraft`'s evidence for entries stamped
- * `diagnostics.settled_by_default === true` and, if any exist, returns the record with
- * `defaulted_steps` set to their distinct step names (declaration order of first occurrence) —
- * else returns the SAME record reference unchanged, so a run with no default-settle anywhere is
- * byte-identical to pre-PR-2 behavior (the damage-rail this preserves). Pure, no I/O.
+ * Pure helper (issue #220 PR-2, D6): if `sealDraft`'s evidence has any entries default-settled
+ * (per {@link deriveDefaultedSteps}, issue #232 — the SHARED derivation the read surfaces also
+ * use), returns the record with `defaulted_steps` set to their distinct step names — else returns
+ * the SAME record reference unchanged, so a run with no default-settle anywhere is byte-identical
+ * to pre-PR-2 behavior (the damage-rail this preserves). Pure, no I/O.
  *
  * Applied by WRAPPING the `buildFinalizedSeal` call inside the TERMINAL branch of each seal
  * ternary — `buildFinalizedSeal` itself stays byte-untouched (a chokepoint insertion was
@@ -388,21 +390,36 @@ function mergeWarnings(traceWarnings, ...extraWarnings) {
  * fragile two-touch above the damage-rail fast-path). Callers must pass ONLY a sealed record from
  * the `'complete'` branch — never a non-terminal draft, and never a fail/abort seal — so
  * `defaulted_steps` never leaks onto a persisted non-terminal record that a later FAIL seal
- * inherits (the FM-5 residual this guards).
+ * inherits (the FM-5 residual this guards). issue #232 note: this complete-only stamping is
+ * UNCHANGED — a run that fails/aborts still carries no persisted `defaulted_steps`; the failure-
+ * path disclosure gap is closed by the READ surfaces calling `deriveDefaultedSteps` directly, not
+ * by widening what gets persisted here.
  */
 function stampDefaultedSteps(sealDraft) {
-    const steps = [];
-    const seen = new Set();
-    for (const snap of sealDraft.evidence) {
-        if (snap.diagnostics?.settled_by_default === true && !seen.has(snap.step_id)) {
-            seen.add(snap.step_id);
-            steps.push(snap.step_id);
-        }
-    }
+    const steps = deriveDefaultedSteps(sealDraft.evidence);
     if (steps.length === 0)
         return sealDraft;
     return { ...sealDraft, defaulted_steps: steps };
 }
+/**
+ * The compensating un-claim's own audit-evidence entry (issue #207 PR-2, D3 §5; extracted issue
+ * #279, increment 2, PR-D, Deliverable 1e — the `:679` semantics both the legacy
+ * `buildCompensatingUnclaim` below AND the migrated `release_step` delta's `evidence` field share
+ * verbatim).
+ */
+function buildCompensatingUnclaimEvidence(stepName, now) {
+    return captureEvidence({
+        stepId: stepName,
+        startedAt: now,
+        completedAt: now,
+        input: {},
+        output: {
+            compensating_unclaim: true,
+            reason: 'adoption-read failure after claim',
+            unclaimed_at: now.toISOString(),
+        },
+    });
+}
 /**
  * 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
@@ -416,17 +433,7 @@ function stampDefaultedSteps(sealDraft) {
  * 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(),
-        },
-    });
+    const auditEvidence = buildCompensatingUnclaimEvidence(stepName, now);
     return {
         ...pendingRun,
         in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== stepName),
@@ -595,6 +602,174 @@ function makeErrorEnvelope(options, run, err, definition, extraWarnings) {
     }
     return baseWithWarnings;
 }
+/**
+ * Design record §6: a claim-time refusal envelope's advisory line when the fresh run carries
+ * finalizer_ledger pendings — points the caller at the recovery verb. `undefined` when there is
+ * nothing pending (the common case — never emits an empty/placeholder advisory).
+ */
+function finalizerDrainAdvisory(run) {
+    const pendingCount = Object.values(run.finalizer_ledger ?? {}).filter((e) => e.status === 'pending').length;
+    if (pendingCount === 0)
+        return undefined;
+    return `${pendingCount} finalizer(s) not yet delivered — realm run drain ${run.id}`;
+}
+/**
+ * Re-arm disclosure (final-gate F10b, design record §6) — the settling caller's own comparison,
+ * NEVER inside the frozen `applySettlement` transform: any finalizer that was `'voided'` (an
+ * operator `--void`) in `before.finalizer_ledger` and is `'pending'` again in
+ * `after.finalizer_ledger` was just RE-ARMED by mintFresh on THIS terminal edge (a later
+ * fail-then-complete-differently — or any outcome that newly selects it — re-mints a clean pending
+ * entry per §4's mint rule; mintFresh has no memory of a prior void, by design). Called only when
+ * `result.transitioned === true` (mintFresh only ever runs on the terminal false→true edge).
+ */
+function computeReArmWarnings(before, after) {
+    const warnings = [];
+    for (const [name, afterEntry] of Object.entries(after ?? {})) {
+        const beforeEntry = before?.[name];
+        if (beforeEntry?.status === 'voided' && afterEntry.status === 'pending') {
+            warnings.push(`finalizer '${name}' was operator-voided; re-armed by this terminal edge`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Builds the ResponseEnvelope for a `settle_step`/`open_gate` REFUSAL (design record §7's
+ * result/code table) — shared by the three migrated `settle_step` seal sites (issue #279,
+ * increment 1, PR-B) AND the migrated gate-open site (issue #279, increment 2, PR-D; `kind:
+ * 'open_gate'`). `allEvidence` is attached ONLY for `claim_lost`: the dispatch DID run and produce
+ * evidence; it just was not recorded, so the caller should still see what happened. The reasons
+ * both callers can actually return are enumerated explicitly; every OTHER `SettlementRefusalReason`
+ * member is lease/mark/settle_gate/settle_guard/release_step-only and structurally unreachable
+ * here (a `default` throws rather than silently mis-rendering one) — `choice_not_eligible` +
+ * `gate_choice_conflict` + the settle_gate `gate_mismatch`/`run_terminal` variants are consumed at
+ * 1b's own `errorEnvelope` (submitHumanResponse), never here; `gate_open_wait` is chain-consumed
+ * (executeChainInternal's guard loop); `already_released` is site-handled at 1d/1e (never routed
+ * through this shared builder).
+ */
+function buildSettlementRefusalEnvelope(options, definition, result, allEvidence, traceWarnings, kind = 'settle_step') {
+    const extraWarnings = traceWarnings.length > 0 ? traceWarnings : undefined;
+    switch (result.reason) {
+        case 'already_settled_by_other':
+        case 'settled_outcome_divergence': {
+            const persisted = result.run.settled?.[options.command]?.outcome;
+            // N1 (design record §2/§11): neutral wording — never amplify a "by_other" white lie. When
+            // the persisted entry's outcome is 'gate', the step was settled by a COMPLETED GATE (a
+            // human decision resolved elsewhere), not literally "a different attempt".
+            const settledByText = persisted === 'gate' ? 'by a completed gate' : 'by a different attempt';
+            const err = new WorkflowError(`Step '${options.command}' was already settled` +
+                (persisted !== undefined ? ` with outcome '${persisted}'` : '') +
+                ` ${settledByText}.`, {
+                code: 'STATE_STEP_ALREADY_SETTLED',
+                category: 'STATE',
+                agentAction: 'resolve_precondition',
+                retryable: false,
+                details: {
+                    runId: options.runId,
+                    step: options.command,
+                    reason: result.reason,
+                    ...(persisted !== undefined ? { persisted_outcome: persisted } : {}),
+                },
+            });
+            return makeErrorEnvelope(options, result.run, err, definition, extraWarnings);
+        }
+        case 'claim_lost': {
+            const err = new WorkflowError(`Step '${options.command}': this attempt's outcome was NOT recorded — the claim was lost ` +
+                `(settled by another writer, or the run advanced).`, {
+                code: 'STATE_CLAIM_LOST',
+                category: 'STATE',
+                agentAction: 'resolve_precondition',
+                retryable: false,
+                details: { runId: options.runId, step: options.command },
+            });
+            return {
+                ...makeErrorEnvelope(options, result.run, err, definition, extraWarnings),
+                evidence: allEvidence,
+            };
+        }
+        case 'run_terminal': {
+            const err = new WorkflowError(`Run '${options.runId}' is terminal; cannot settle step '${options.command}'.`, {
+                code: 'STATE_RUN_TERMINAL',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+                details: { runId: options.runId, run_phase: result.run.run_phase },
+            });
+            return makeErrorEnvelope(options, result.run, err, definition, extraWarnings);
+        }
+        case 'gate_mismatch': {
+            // kind-discriminated (Deliverable 2): open_gate's gate_mismatch means a DIFFERENT step's
+            // gate is open (this step stays claimed — L13); settle_step's means THIS step IS the open
+            // gate and must be resolved via submit_human_response instead.
+            const message = kind === 'open_gate'
+                ? `Step '${options.command}': a gate is open on another step — wait for its resolution; ` +
+                    `this step stays claimed.`
+                : `Step '${options.command}' is the currently open gate; resolve it via ` +
+                    `submit_human_response instead of settling it directly.`;
+            const err = new WorkflowError(message, {
+                code: 'STATE_BLOCKED',
+                category: 'STATE',
+                agentAction: 'resolve_precondition',
+                retryable: false,
+                details: { runId: options.runId, step: options.command },
+            });
+            return makeErrorEnvelope(options, result.run, err, definition, extraWarnings);
+        }
+        default:
+            // run_not_terminal / ledger_not_pending / lease_held / lease_lost / rank_blocked /
+            // not_eligible / already_leased / already_marked / already_open / already_released /
+            // gate_choice_conflict / choice_not_eligible / gate_open_wait are all consumed elsewhere
+            // (lease_finalizer/mark_finalizer's own drain loop; open_gate's own NOOP arms at the 1a call
+            // site; 1b's own errorEnvelope; 1d/1e's own site-handling; the guard chain) — settle_step and
+            // open_gate never return them here (design record §7).
+            throw new Error(`buildSettlementRefusalEnvelope: unreachable '${kind}' refusal reason '${result.reason}'`);
+    }
+}
+/**
+ * Ok-shaped envelope for a `settle_step` NOOP (`already_settled`) — the idempotent-retry case
+ * (design record §7: ok-shaped, calm context_hint, never `report_to_user`). Drain-aware: when the
+ * fresh run still carries pending finalizers, this retry attempts the SAME post-commit drain a
+ * fresh apply would have run — recovering an ambiguous-retry crash window (§6). A drain failure
+ * degrades to a warning (never an error status) — the settle itself is not in question here.
+ */
+async function buildAlreadySettledEnvelope(store, definition, options, result, traceWarnings) {
+    let run = result.run;
+    let drainWarnings = [];
+    const hasPending = Object.values(run.finalizer_ledger ?? {}).some((e) => e.status === 'pending');
+    if (hasPending) {
+        try {
+            const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+            run = drainOutcome.run;
+            drainWarnings = drainOutcome.warnings;
+        }
+        catch (err) {
+            drainWarnings = [
+                `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+            ];
+        }
+    }
+    const nextActions = run.terminal_state ? [] : buildNextActions(definition, run);
+    return {
+        command: options.command,
+        run_id: options.runId,
+        run_version: run.version,
+        status: 'ok',
+        data: {},
+        evidence: [],
+        warnings: mergeWarnings(traceWarnings, ...drainWarnings),
+        errors: [],
+        context_hint: `Step '${options.command}' was already settled (a duplicate/retried attempt) — no action was taken.`,
+        run_phase: run.run_phase,
+        next_actions: nextActions,
+    };
+}
+/**
+ * Design record §10 (I16, fail-closed dormancy): the ONE advisory warning every legacy
+ * (dormancy-fallback) seal-site envelope carries when `store.settleStep` is undeclared — never a
+ * hard requirement; the legacy read-then-update path remains fully functional. This dual branch
+ * persists until a major version (final-gate F4/R13).
+ */
+const DORMANCY_ADVISORY = 'settled via the legacy compatibility path — this store does not declare atomic settlement ' +
+    '(RunStore.settleStep); upgrade the store to close the fan-out seal race (issue #279)';
 /**
  * Validates eligibility, claims the step, executes it through the dispatcher with retry
  * and timeout support, captures evidence, persists the updated run record, and returns
@@ -958,6 +1133,8 @@ export async function executeStep(store, definition, options) {
         if (err instanceof WorkflowError) {
             if (err.code === 'STATE_STEP_ALREADY_CLAIMED') {
                 const freshRun = await store.get(options.runId).catch(() => run);
+                // Design record §6: append the drain advisory when the fresh run carries pendings.
+                const claimedAdvisory = finalizerDrainAdvisory(freshRun);
                 return {
                     command: options.command,
                     run_id: options.runId,
@@ -965,7 +1142,7 @@ export async function executeStep(store, definition, options) {
                     status: 'blocked',
                     data: {},
                     evidence: [],
-                    warnings: [],
+                    warnings: claimedAdvisory !== undefined ? [claimedAdvisory] : [],
                     errors: [],
                     agent_action: 'resolve_precondition',
                     context_hint: `Step '${options.command}' was already claimed by another process.`,
@@ -977,6 +1154,19 @@ export async function executeStep(store, definition, options) {
                     },
                 };
             }
+            // Design record §6: STATE_STEP_NOT_ELIGIBLE (a claim-time eligibility re-check race) also
+            // gets the drain advisory when the fresh run carries pendings — a fresh re-read since `run`
+            // (Step 1's load) may be stale by the time claimStep's own re-check inside its lock raced.
+            if (err.code === 'STATE_STEP_NOT_ELIGIBLE') {
+                const freshRun = await store.get(options.runId).catch(() => run);
+                const notEligibleAdvisory = finalizerDrainAdvisory(freshRun);
+                const extraWarnings = notEligibleAdvisory !== undefined
+                    ? [...traceWarnings, notEligibleAdvisory]
+                    : traceWarnings.length > 0
+                        ? traceWarnings
+                        : undefined;
+                return makeErrorEnvelope(options, freshRun, err, definition, extraWarnings);
+            }
             return makeErrorEnvelope(options, run, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
         }
         return makeErrorEnvelope(options, run, new WorkflowError('Failed to claim step', {
@@ -1013,13 +1203,43 @@ export async function executeStep(store, definition, options) {
                     : [];
         }
         catch (err) {
-            try {
-                await store.update(buildCompensatingUnclaim(pendingRun, options.command, new Date()));
+            // issue #279 (increment 2, PR-D, Deliverable 1e): the migrated path — settles this release
+            // atomically against FRESH state via the store's own settleStep, evidence = the SAME
+            // compensating_unclaim audit line (:679 semantics). LOG-ONLY for ALL results (applied / NOOP
+            // / any refusal / a thrown infra error) — no envelope change on any settle outcome; the
+            // ENGINE_STORE_FAILED envelope below is the disclosure regardless. Dormancy: an undeclaring
+            // store falls through to the byte-identical legacy path (I16/#169 fail-closed dormancy).
+            let unclaimDormancyWarning;
+            if (store.settleStep !== undefined) {
+                const unclaimToken = pendingRun.claims?.[options.command]?.token;
+                const delta = {
+                    kind: 'release_step',
+                    step: options.command,
+                    ...(unclaimToken !== undefined ? { claimToken: unclaimToken } : {}),
+                    evidence: [buildCompensatingUnclaimEvidence(options.command, new Date())],
+                };
+                try {
+                    await store.settleStep(options.runId, delta, definition);
+                }
+                catch {
+                    // Log-only — see the comment above; never surfaces as its own error.
+                }
             }
-            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.
+            else {
+                // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
+                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.
+                }
+                // issue #279 (increment 2, PR-D): + the ONE dormancy advisory (I16) — this IS the legacy
+                // path (store.settleStep undeclared); the ENGINE_STORE_FAILED envelope below is its only
+                // carrier since this release is log-only.
+                unclaimDormancyWarning = DORMANCY_ADVISORY;
             }
+            const unclaimEnvelopeWarnings = mergeWarnings(traceWarnings, unclaimDormancyWarning);
             return makeErrorEnvelope(options, pendingRun, new WorkflowError('Failed to read trace buffer after claiming step', {
                 code: 'ENGINE_STORE_FAILED',
                 category: 'ENGINE',
@@ -1029,7 +1249,7 @@ export async function executeStep(store, definition, options) {
                     step_id: options.command,
                     cause: err instanceof Error ? err.message : String(err),
                 },
-            }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }), definition, unclaimEnvelopeWarnings.length > 0 ? unclaimEnvelopeWarnings : 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
@@ -1335,6 +1555,75 @@ export async function executeStep(store, definition, options) {
                         }),
                         status: 'skipped',
                     };
+                    // issue #279 (increment 1, PR-B): the migrated path — a store declaring settleStep
+                    // settles this abort atomically against FRESH state (not `pendingRun`, which may be
+                    // stale relative to a concurrent sibling settle). Dormancy: an undeclaring store falls
+                    // through to the byte-identical legacy path below (I16/#169 fail-closed dormancy).
+                    if (store.settleStep !== undefined) {
+                        const abortClaimToken = pendingRun.claims?.[options.command]?.token;
+                        const delta = {
+                            kind: 'settle_step',
+                            step: options.command,
+                            outcome: 'abort',
+                            ...(abortClaimToken !== undefined ? { claimToken: abortClaimToken } : {}),
+                            evidence: [abortEvidence],
+                            abort: { stepId: options.command, abortMessage },
+                        };
+                        let result;
+                        try {
+                            result = await store.settleStep(options.runId, delta, definition);
+                        }
+                        catch (err) {
+                            // THROWN infra errors (lock exhaustion, run-not-found, I/O) — the complete-site's
+                            // existing catch shape, replicated at all three migrated sites.
+                            if (err instanceof WorkflowError) {
+                                return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+                            }
+                            const internal = new WorkflowError('Failed to persist run update', {
+                                code: 'ENGINE_STORE_FAILED',
+                                category: 'ENGINE',
+                                agentAction: 'stop',
+                                retryable: false,
+                            });
+                            return makeErrorEnvelope(options, pendingRun, internal, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+                        }
+                        if (!result.applied) {
+                            if (result.reason === 'already_settled') {
+                                return buildAlreadySettledEnvelope(store, definition, options, { ...result, reason: 'already_settled' }, traceWarnings);
+                            }
+                            return buildSettlementRefusalEnvelope(options, definition, result, [abortEvidence], traceWarnings);
+                        }
+                        // applied: true — abort is UNCONDITIONALLY terminal (transitioned is always true here;
+                        // isTerminal(fresh) was already refused above inside applySettlement).
+                        let finalRun = result.run;
+                        let drainWarnings = [];
+                        const reArmWarnings = computeReArmWarnings(pendingRun.finalizer_ledger, result.run.finalizer_ledger);
+                        try {
+                            const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                            finalRun = drainOutcome.run;
+                            drainWarnings = drainOutcome.warnings;
+                        }
+                        catch (err) {
+                            // A drain failure is NEVER the step's own failure — the abort already committed.
+                            drainWarnings = [
+                                `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+                            ];
+                        }
+                        return {
+                            command: options.command,
+                            run_id: options.runId,
+                            run_version: finalRun.version,
+                            status: 'ok',
+                            data: {},
+                            evidence: [abortEvidence],
+                            warnings: mergeWarnings(traceWarnings, ...reArmWarnings, ...drainWarnings),
+                            errors: [],
+                            context_hint: `Handler step '${options.command}' aborted the run: ${abortMessage}`,
+                            run_phase: finalRun.run_phase,
+                            next_actions: [],
+                        };
+                    }
+                    // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
                     const withHandlerSkipped = {
                         ...pendingRun,
                         in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
@@ -1382,7 +1671,9 @@ export async function executeStep(store, definition, options) {
                         evidence: [abortEvidence],
                         // 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),
+                        // Issue #279 (increment 1, PR-B): + the ONE dormancy advisory (I16) — this IS the
+                        // legacy path (store.settleStep undeclared).
+                        warnings: mergeWarnings(traceWarnings, DORMANCY_ADVISORY),
                         errors: [],
                         context_hint: `Handler step '${options.command}' aborted the run: ${abortMessage}`,
                         run_phase: (persistedAbortRun ?? abortedRun).run_phase,
@@ -1694,13 +1985,61 @@ export async function executeStep(store, definition, options) {
             // Non-terminal: recompute the phase so the store-fail fallback below is correct too
             // (on the happy path store.update recomputes it identically via deriveRunPhase).
             const blockedRun = { ...blockedDraft, run_phase: deriveRunPhase(blockedDraft) };
+            // issue #279 (increment 2, PR-D, Deliverable 1d): the migrated path — settles this release
+            // atomically against FRESH state via the store's own settleStep. This site NEVER calls the
+            // shared buildSettlementRefusalEnvelope: regardless of write outcome (applied / NOOP
+            // already_released / any OTHER refusal / a thrown infra error), the RETURNED envelope is
+            // ALWAYS this SAME capability-block report — only whether the internal capability_blocks
+            // marker got durably persisted varies, disclosed via blockStoreWarning. Dormancy: an
+            // undeclaring store falls through to the byte-identical legacy path below (I16/#169
+            // fail-closed dormancy).
             let persistedBlockedRun;
             let blockStoreWarning;
-            try {
-                persistedBlockedRun = await store.update(blockedRun);
+            let dormancyWarning;
+            if (store.settleStep !== undefined) {
+                const releaseClaimToken = pendingRun.claims?.[options.command]?.token;
+                const delta = {
+                    kind: 'release_step',
+                    step: options.command,
+                    ...(releaseClaimToken !== undefined ? { claimToken: releaseClaimToken } : {}),
+                    capabilityBlock: {
+                        requirement: requirement !== undefined
+                            ? { kind: requirement.kind, name: requirement.name }
+                            : {
+                                kind: recoverableCode === 'ENGINE_HANDLER_NOT_REGISTERED' ? 'handler' : 'adapter',
+                                name: 'unknown',
+                            },
+                        code: recoverableCode,
+                    },
+                    // The current :2490 append — legacy parity; the compensating un-claim's own :679
+                    // audit-line channel belongs to Deliverable 1e ONLY.
+                    evidence: allEvidence,
+                };
+                try {
+                    const releaseResult = await store.settleStep(options.runId, delta, definition);
+                    persistedBlockedRun = releaseResult.run;
+                    // applied / NOOP already_released ⇒ the block envelope exactly as today (NOOP merges
+                    // silently — no extra warning). ANY OTHER refusal ⇒ the same block envelope + a typed
+                    // warning (never STATE_CLAIM_LOST framing) — the claim survives for reclaim either way.
+                    if (!releaseResult.applied && releaseResult.reason !== 'already_released') {
+                        blockStoreWarning = `capability block not persisted: ${releaseResult.reason}`;
+                    }
+                }
+                catch (storeErr) {
+                    blockStoreWarning = `Failed to persist capability block: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
+                }
             }
-            catch (storeErr) {
-                blockStoreWarning = `Failed to persist capability block: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
+            else {
+                // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
+                try {
+                    persistedBlockedRun = await store.update(blockedRun);
+                }
+                catch (storeErr) {
+                    blockStoreWarning = `Failed to persist capability block: ${storeErr instanceof Error ? storeErr.message : String(storeErr)}`;
+                }
+                // issue #279 (increment 2, PR-D): + the ONE dormancy advisory (I16) — this IS the legacy
+                // path (store.settleStep undeclared).
+                dormancyWarning = DORMANCY_ADVISORY;
             }
             // 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
@@ -1735,7 +2074,7 @@ export async function executeStep(store, definition, options) {
                 status: 'error',
                 data: {},
                 evidence: allEvidence,
-                warnings: mergeWarnings(traceWarnings, blockStoreWarning),
+                warnings: mergeWarnings(traceWarnings, blockStoreWarning, dormancyWarning),
                 errors: [dispatchError.message],
                 agent_action: blockedAction,
                 error_code: recoverableCode,
@@ -1744,6 +2083,141 @@ export async function executeStep(store, definition, options) {
                 next_actions: blockedNextActions,
             };
         }
+        // issue #279 (increment 1, PR-B): the migrated path — settles this failure atomically against
+        // FRESH state via the store's own settleStep. Dormancy: an undeclaring store falls through to
+        // the byte-identical legacy path below (I16/#169 fail-closed dormancy).
+        if (store.settleStep !== undefined) {
+            const failClaimToken = pendingRun.claims?.[options.command]?.token;
+            const delta = {
+                kind: 'settle_step',
+                step: options.command,
+                outcome: 'fail',
+                ...(failClaimToken !== undefined ? { claimToken: failClaimToken } : {}),
+                evidence: allEvidence,
+                failureMessage: dispatchError.message,
+            };
+            let result;
+            try {
+                result = await store.settleStep(options.runId, delta, definition);
+            }
+            catch (err) {
+                // THROWN infra errors — the same catch shape replicated at all three migrated sites.
+                if (err instanceof WorkflowError) {
+                    return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+                }
+                const internal = new WorkflowError('Failed to persist run update', {
+                    code: 'ENGINE_STORE_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                });
+                return makeErrorEnvelope(options, pendingRun, internal, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }
+            if (!result.applied) {
+                if (result.reason === 'already_settled') {
+                    return buildAlreadySettledEnvelope(store, definition, options, { ...result, reason: 'already_settled' }, traceWarnings);
+                }
+                // WAL/sealFenced gates become result.applied (BU-12): claim_lost ⇒ the WAL SURVIVES
+                // (reclaim's drain owns it) — no WAL cleanup attempted on ANY refusal.
+                return buildSettlementRefusalEnvelope(options, definition, result, allEvidence, traceWarnings);
+            }
+            let finalRun = result.run;
+            let drainWarnings = [];
+            const reArmWarnings = result.transitioned
+                ? computeReArmWarnings(pendingRun.finalizer_ledger, result.run.finalizer_ledger)
+                : [];
+            if (result.transitioned) {
+                try {
+                    const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                    finalRun = drainOutcome.run;
+                    drainWarnings = drainOutcome.warnings;
+                }
+                catch (err) {
+                    drainWarnings = [
+                        `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+                    ];
+                }
+            }
+            // WAL cleanup — placement stays post-commit (unchanged), now gated on result.applied
+            // (BU-12) rather than a separate persistedRun-defined check (the settle already committed
+            // by the time we reach here, so there is no "did the persist succeed" ambiguity to gate on).
+            let migratedWalCleanupWarning;
+            {
+                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;
+                            migratedWalCleanupWarning =
+                                `${adoptionPartition.preserved_foreign} foreign line(s) preserved (sealed) — ` +
+                                    'retrieve via `realm run export`';
+                        }
+                        else if (sealResult.reason === 'capped') {
+                            migratedWalCleanupWarning =
+                                'preservation cap reached — foreign lines destroyed, not preserved';
+                        }
+                        else {
+                            performPlainDelete = false;
+                        }
+                    }
+                    catch (err) {
+                        performPlainDelete = false;
+                        migratedWalCleanupWarning = `Failed to seal trace buffer after step failure: ${err instanceof Error ? err.message : String(err)}`;
+                    }
+                }
+                if (performPlainDelete) {
+                    try {
+                        await options.traceBufferStore?.delete(options.runId, options.command);
+                    }
+                    catch (walErr) {
+                        migratedWalCleanupWarning = `Failed to clean up trace buffer after step failure: ${walErr instanceof Error ? walErr.message : String(walErr)}`;
+                    }
+                }
+            }
+            const migratedEffectiveAction = resolvePostDispatchAgentAction(dispatchError, finalRun.terminal_state);
+            let migratedNextActions = [];
+            if (migratedEffectiveAction !== 'stop') {
+                try {
+                    migratedNextActions = buildNextActions(definition, finalRun);
+                }
+                catch {
+                    // buildNextActions can throw for unresolvable template references; fall back to [].
+                }
+            }
+            const migratedContextHint = migratedEffectiveAction === 'stop'
+                ? `Step '${options.command}' failed. Run is terminated.`
+                : migratedEffectiveAction === 'wait_and_proceed'
+                    ? `Step '${options.command}' was rate-limited. Wait ${dispatchError.retry_after !== undefined ? `${dispatchError.retry_after} second(s)` : 'a moment'} then follow next_actions — no human intervention required.`
+                    : migratedEffectiveAction === 'wait_for_human'
+                        ? `Step '${options.command}' failed due to external service unavailability. Wait for service recovery, then proceed with the steps in next_actions.`
+                        : `Step '${options.command}' failed. ${result.transitioned ? 'Run is terminated.' : 'Recovery steps are available in next_actions.'}`;
+            return {
+                command: options.command,
+                run_id: options.runId,
+                run_version: finalRun.version,
+                status: 'error',
+                data: {},
+                evidence: allEvidence,
+                warnings: mergeWarnings(traceWarnings, migratedWalCleanupWarning, ...reArmWarnings, ...drainWarnings),
+                errors: [dispatchError.message],
+                agent_action: migratedEffectiveAction,
+                error_code: dispatchError.code,
+                ...(Object.keys(dispatchError.details).length > 0
+                    ? { error_details: dispatchError.details }
+                    : {}),
+                ...(dispatchError.retry_after !== undefined
+                    ? { retry_after: dispatchError.retry_after }
+                    : {}),
+                context_hint: migratedContextHint,
+                run_phase: finalRun.run_phase,
+                next_actions: migratedNextActions,
+            };
+        }
+        // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
         // Pure in-memory derivations — no I/O, no try required.
         const afterFail = {
             ...pendingRun,
@@ -1879,7 +2353,9 @@ export async function executeStep(store, definition, options) {
             status: 'error',
             data: {},
             evidence: allEvidence,
-            warnings: mergeWarnings(traceWarnings, storeCleanupWarning ?? walCleanupWarning),
+            // Issue #279 (increment 1, PR-B): + the ONE dormancy advisory (I16) — this IS the legacy
+            // path (store.settleStep undeclared).
+            warnings: mergeWarnings(traceWarnings, storeCleanupWarning ?? walCleanupWarning, DORMANCY_ADVISORY),
             errors: [dispatchError.message],
             agent_action: effectiveAction,
             // issue #140 (D3 §2, discriminator OBSERVABLE): additive-optional — lets a caller
@@ -1952,37 +2428,21 @@ export async function executeStep(store, definition, options) {
             resolvedGateMessage = raw;
         }
         const gateConfig = stepDef.gate;
-        let gateRun;
-        try {
-            gateRun = await store.update({
-                ...pendingRun,
-                // Step stays in in_progress_steps while gate is open — moved to completed on submit.
-                evidence: [...pendingRun.evidence, ...allEvidence],
-                pending_gate: {
-                    gate_id,
-                    step_name,
-                    preview: output,
-                    choices,
-                    opened_at: new Date().toISOString(),
-                    ...(gateConfig?.owner !== undefined ? { owner: gateConfig.owner } : {}),
-                    ...(resolvedGateMessage !== undefined ? { resolved_message: resolvedGateMessage } : {}),
-                    ...(gateConfig?.resolution_messages !== undefined
-                        ? { resolution_messages: gateConfig.resolution_messages }
-                        : {}),
-                },
-            });
-        }
-        catch (err) {
-            if (err instanceof WorkflowError) {
-                return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
-            }
-            return makeErrorEnvelope(options, pendingRun, new WorkflowError('Failed to open gate', {
-                code: 'ENGINE_STORE_FAILED',
-                category: 'ENGINE',
-                agentAction: 'stop',
-                retryable: false,
-            }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
-        }
+        // The PendingGate object is built EXACTLY as before, regardless of which path commits it below
+        // (issue #279, increment 2, PR-D, Deliverable 1a — the migrated `open_gate` delta carries this
+        // SAME object verbatim; the legacy fallback writes it via `store.update` unchanged).
+        const pendingGate = {
+            gate_id,
+            step_name,
+            preview: output,
+            choices,
+            opened_at: new Date().toISOString(),
+            ...(gateConfig?.owner !== undefined ? { owner: gateConfig.owner } : {}),
+            ...(resolvedGateMessage !== undefined ? { resolved_message: resolvedGateMessage } : {}),
+            ...(gateConfig?.resolution_messages !== undefined
+                ? { resolution_messages: gateConfig.resolution_messages }
+                : {}),
+        };
         // gate.display fallback chain: gate.message resolved → step.prompt resolved → absent
         const resolvedGateDisplay = resolvedGateMessage !== undefined
             ? resolvedGateMessage
@@ -2000,19 +2460,155 @@ export async function executeStep(store, definition, options) {
                 ...wfCtxSpreadEarly,
             })
             : undefined;
-        const gateNextAction = {
-            instruction: {
-                tool: 'submit_human_response',
-                params: { run_id: options.runId, gate_id },
-                call_with: {
-                    run_id: options.runId,
+        function buildGateNextAction(id, gateChoices, forStep) {
+            return {
+                instruction: {
+                    tool: 'submit_human_response',
+                    params: { run_id: options.runId, gate_id: id },
+                    call_with: {
+                        run_id: options.runId,
+                        gate_id: id,
+                        choice: `<${gateChoices.join('|')}>`,
+                    },
+                },
+                human_readable: `Human review required for step '${forStep}'. Present gate.display to the user, wait for their choice from gate.response_spec.choices, then call submit_human_response.`,
+                orientation: `Run is paused at gate '${id}'. Available choices: ${gateChoices.join(', ')}.`,
+            };
+        }
+        // issue #279 (increment 2, PR-D, Deliverable 1a): the migrated path — opens this gate
+        // atomically against FRESH state via the store's own settleStep. Dormancy: an undeclaring
+        // store falls through to the byte-identical legacy path below (I16/#169 fail-closed dormancy).
+        if (store.settleStep !== undefined) {
+            const openClaimToken = pendingRun.claims?.[options.command]?.token;
+            const delta = {
+                kind: 'open_gate',
+                step: options.command,
+                ...(openClaimToken !== undefined ? { claimToken: openClaimToken } : {}),
+                pendingGate,
+                evidence: allEvidence,
+            };
+            let result;
+            try {
+                result = await store.settleStep(options.runId, delta, definition);
+            }
+            catch (err) {
+                // THROWN infra errors — the same catch shape replicated at every migrated site.
+                if (err instanceof WorkflowError) {
+                    return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+                }
+                const internal = new WorkflowError('Failed to open gate', {
+                    code: 'ENGINE_STORE_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                });
+                return makeErrorEnvelope(options, pendingRun, internal, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }
+            if (!result.applied) {
+                if (result.reason === 'already_settled') {
+                    // Ok-shaped NOOP — buildAlreadySettledEnvelope's SHAPE but WITHOUT its drain clause:
+                    // gate-open NEVER drains (design record §6 row 1 — the crashed-drain recovery paths are
+                    // the resolution site's own NOOP drain and the drain verb).
+                    const noopRun = result.run;
+                    const noopNextActions = noopRun.terminal_state
+                        ? []
+                        : buildNextActions(definition, noopRun);
+                    return {
+                        command: options.command,
+                        run_id: options.runId,
+                        run_version: noopRun.version,
+                        status: 'ok',
+                        data: {},
+                        evidence: [],
+                        warnings: [...traceWarnings],
+                        errors: [],
+                        context_hint: `Step '${options.command}' was already settled (a duplicate/retried attempt) — no action was taken.`,
+                        run_phase: noopRun.run_phase,
+                        next_actions: noopNextActions,
+                    };
+                }
+                if (result.reason === 'already_open') {
+                    // D-1: the LIVE gate wins — rendered VERBATIM (this delta's own rebuilt gate is
+                    // discarded). Calm, confirm_required (the gate genuinely IS still open) — never
+                    // report_to_user (no `agent_action` set, matching the fresh-open confirm_required shape).
+                    const liveGate = result.gate;
+                    return {
+                        command: options.command,
+                        run_id: options.runId,
+                        run_version: result.run.version,
+                        status: 'confirm_required',
+                        data: liveGate.preview,
+                        evidence: [],
+                        warnings: [...traceWarnings],
+                        errors: [],
+                        context_hint: `Run is already paused at gate '${liveGate.gate_id}'. Available choices: ${liveGate.choices.join(', ')}.`,
+                        run_phase: result.run.run_phase,
+                        next_actions: [
+                            buildGateNextAction(liveGate.gate_id, liveGate.choices, liveGate.step_name),
+                        ],
+                        gate: {
+                            gate_id: liveGate.gate_id,
+                            step_name: liveGate.step_name,
+                            preview: liveGate.preview,
+                            choices: liveGate.choices,
+                            ...(liveGate.resolved_message !== undefined
+                                ? { display: liveGate.resolved_message }
+                                : {}),
+                            response_spec: { choices: liveGate.choices },
+                        },
+                    };
+                }
+                return buildSettlementRefusalEnvelope(options, definition, result, allEvidence, traceWarnings, 'open_gate');
+            }
+            // applied: true — never terminalizes (design record §4.1); build confirm_required off
+            // result.run.
+            const gateRun = result.run;
+            return {
+                command: options.command,
+                run_id: options.runId,
+                run_version: gateRun.version,
+                status: 'confirm_required',
+                data: output,
+                evidence: allEvidence,
+                warnings: [...traceWarnings],
+                errors: [],
+                context_hint: `Run is paused at gate '${gate_id}'. Available choices: ${choices.join(', ')}.`,
+                run_phase: gateRun.run_phase,
+                next_actions: [buildGateNextAction(gate_id, choices, step_name)],
+                gate: {
                     gate_id,
-                    choice: `<${choices.join('|')}>`,
+                    step_name,
+                    preview: output,
+                    choices,
+                    ...(resolvedGateDisplay !== undefined ? { display: resolvedGateDisplay } : {}),
+                    ...(resolvedGateInstructions !== undefined
+                        ? { agent_hint: resolvedGateInstructions }
+                        : {}),
+                    response_spec: { choices },
                 },
-            },
-            human_readable: `Human review required for step '${options.command}'. Present gate.display to the user, wait for their choice from gate.response_spec.choices, then call submit_human_response.`,
-            orientation: `Run is paused at gate '${gate_id}'. Available choices: ${choices.join(', ')}.`,
-        };
+            };
+        }
+        // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
+        let gateRun;
+        try {
+            gateRun = await store.update({
+                ...pendingRun,
+                // Step stays in in_progress_steps while gate is open — moved to completed on submit.
+                evidence: [...pendingRun.evidence, ...allEvidence],
+                pending_gate: pendingGate,
+            });
+        }
+        catch (err) {
+            if (err instanceof WorkflowError) {
+                return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }
+            return makeErrorEnvelope(options, pendingRun, new WorkflowError('Failed to open gate', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            }), definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+        }
         return {
             command: options.command,
             run_id: options.runId,
@@ -2020,11 +2616,11 @@ export async function executeStep(store, definition, options) {
             status: 'confirm_required',
             data: output,
             evidence: allEvidence,
-            warnings: [...traceWarnings],
+            warnings: mergeWarnings(traceWarnings, DORMANCY_ADVISORY),
             errors: [],
             context_hint: `Run is paused at gate '${gate_id}'. Available choices: ${choices.join(', ')}.`,
             run_phase: gateRun.run_phase,
-            next_actions: [gateNextAction],
+            next_actions: [buildGateNextAction(gate_id, choices, step_name)],
             gate: {
                 gate_id,
                 step_name,
@@ -2037,6 +2633,134 @@ export async function executeStep(store, definition, options) {
         };
     }
     // Step 6: Move step from in_progress to completed, compute terminal state.
+    // issue #279 (increment 1, PR-B): the migrated path — settles this completion atomically
+    // against FRESH state via the store's own settleStep. Dormancy: an undeclaring store falls
+    // through to the byte-identical legacy path below (I16/#169 fail-closed dormancy).
+    if (store.settleStep !== undefined) {
+        const completeClaimToken = pendingRun.claims?.[options.command]?.token;
+        const delta = {
+            kind: 'settle_step',
+            step: options.command,
+            outcome: 'complete',
+            ...(completeClaimToken !== undefined ? { claimToken: completeClaimToken } : {}),
+            evidence: allEvidence,
+        };
+        let result;
+        try {
+            result = await store.settleStep(options.runId, delta, definition);
+        }
+        catch (err) {
+            // THROWN infra errors — the same catch shape replicated at all three migrated sites.
+            if (err instanceof WorkflowError) {
+                return makeErrorEnvelope(options, pendingRun, err, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+            }
+            const internal = new WorkflowError('Failed to persist run update', {
+                code: 'ENGINE_STORE_FAILED',
+                category: 'ENGINE',
+                agentAction: 'stop',
+                retryable: false,
+            });
+            return makeErrorEnvelope(options, pendingRun, internal, definition, traceWarnings.length > 0 ? traceWarnings : undefined);
+        }
+        if (!result.applied) {
+            if (result.reason === 'already_settled') {
+                return buildAlreadySettledEnvelope(store, definition, options, { ...result, reason: 'already_settled' }, traceWarnings);
+            }
+            // WAL/sealFenced gates become result.applied (BU-12): claim_lost ⇒ the WAL SURVIVES.
+            return buildSettlementRefusalEnvelope(options, definition, result, allEvidence, traceWarnings);
+        }
+        let finalRun = result.run;
+        let drainWarnings = [];
+        const reArmWarnings = result.transitioned
+            ? computeReArmWarnings(pendingRun.finalizer_ledger, result.run.finalizer_ledger)
+            : [];
+        if (result.transitioned) {
+            try {
+                const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                finalRun = drainOutcome.run;
+                drainWarnings = drainOutcome.warnings;
+            }
+            catch (err) {
+                drainWarnings = [
+                    `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+                ];
+            }
+        }
+        // WAL cleanup — placement stays post-commit (unchanged), gated on result.applied (BU-12).
+        let migratedSuccessWalCleanupWarning;
+        {
+            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;
+                        migratedSuccessWalCleanupWarning =
+                            `${adoptionPartition.preserved_foreign} foreign line(s) preserved (sealed) — ` +
+                                'retrieve via `realm run export`';
+                    }
+                    else if (sealResult.reason === 'capped') {
+                        migratedSuccessWalCleanupWarning =
+                            'preservation cap reached — foreign lines destroyed, not preserved';
+                    }
+                    else {
+                        performPlainDelete = false;
+                    }
+                }
+                catch (err) {
+                    performPlainDelete = false;
+                    migratedSuccessWalCleanupWarning = `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) {
+                    migratedSuccessWalCleanupWarning = `Failed to clean up trace buffer after step completion: ${err instanceof Error ? err.message : String(err)}`;
+                }
+            }
+        }
+        const migratedDefaultedStepsDurabilityWarning = finalRun.defaulted_steps !== undefined &&
+            finalRun.defaulted_steps.length > 0 &&
+            !persistsField(store, 'defaulted_steps')
+            ? 'run-level defaultedness marker (defaulted_steps) not durable on this store'
+            : undefined;
+        const migratedNextActions = finalRun.terminal_state
+            ? []
+            : buildNextActions(definition, finalRun);
+        const migratedOrientation = finalRun.terminal_state
+            ? `Run completed (phase: '${finalRun.run_phase}'). Call get_run_state with run_id '${options.runId}' to retrieve the full evidence record.`
+            : migratedNextActions.length > 0
+                ? `Step '${options.command}' completed. ${migratedNextActions.length} step(s) now available.`
+                : `Step '${options.command}' completed. Waiting for other steps to complete.`;
+        return {
+            command: options.command,
+            run_id: options.runId,
+            run_version: finalRun.version,
+            status: 'ok',
+            data: output,
+            evidence: allEvidence,
+            warnings: mergeWarnings(traceWarnings, currentWarn, migratedSuccessWalCleanupWarning, migratedDefaultedStepsDurabilityWarning, ...reArmWarnings, ...drainWarnings),
+            errors: [],
+            context_hint: migratedOrientation,
+            run_phase: finalRun.run_phase,
+            next_actions: migratedNextActions,
+            ...(carriageActive && adoptionPartition !== undefined
+                ? {
+                    adopted_own: adoptionPartition.adopted_own,
+                    adopted_anonymous: adoptionPartition.adopted_anonymous,
+                    preserved_foreign: adoptionPartition.preserved_foreign,
+                }
+                : {}),
+            ...(settledByDefault ? { settled_by_default: true } : {}),
+            ...(finalRun.defaulted_steps?.length ? { defaulted_steps: finalRun.defaulted_steps } : {}),
+        };
+    }
+    // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
     const afterComplete = {
         ...pendingRun,
         in_progress_steps: pendingRun.in_progress_steps.filter((s) => s !== options.command),
@@ -2158,7 +2882,9 @@ export async function executeStep(store, definition, options) {
         status: 'ok',
         data: output,
         evidence: allEvidence,
-        warnings: mergeWarnings(traceWarnings, currentWarn, successWalCleanupWarning, defaultedStepsDurabilityWarning),
+        // Issue #279 (increment 1, PR-B): + the ONE dormancy advisory (I16) — this IS the legacy
+        // path (store.settleStep undeclared).
+        warnings: mergeWarnings(traceWarnings, currentWarn, successWalCleanupWarning, defaultedStepsDurabilityWarning, DORMANCY_ADVISORY),
         errors: [],
         context_hint: orientation,
         run_phase: savedRun.run_phase,
@@ -2187,6 +2913,39 @@ export async function executeStep(store, definition, options) {
  * Submits a human response for a gate-waiting run.
  * Validates the gate_id and choice, then moves the step to completed_steps.
  */
+/** Finds the settled step name for a resolved gate matching `gateId` (issue #279, increment 2,
+ *  PR-D) — a LOCAL mirror of settlement.ts's own `findSettledGateEntry` (not imported: this file
+ *  touches settlement.ts ONLY for Deliverable 3's cancel-trail `gate_id` addition). Used to recover
+ *  a reliable step name off `result.run.settled` for the `already_settled`/`gate_choice_conflict`
+ *  envelopes, since the caller's own pre-read may already be stale by the time either of those
+ *  fires (the gate could have resolved before this call's own Step-1 read). */
+function findGateStepName(run, gateId) {
+    for (const [step, entry] of Object.entries(run.settled ?? {})) {
+        if (entry.outcome === 'gate' && entry.token === gateId)
+            return step;
+    }
+    return undefined;
+}
+/** Builds the gate_response evidence snapshot (issue #279, increment 2, PR-D, Deliverable 1b) —
+ *  the SAME shape submitHumanResponse's legacy path has always built (mirrors execution-loop.ts's
+ *  own pre-PR-D Step 5), extracted so both the migrated and legacy paths construct it identically.
+ *  `respondedBy`, when supplied, populates the snapshot's own `responded_by` field (design record
+ *  D-5) in addition to the delta's own field. */
+function buildGateResponseSnapshot(gate, choice, respondedAt, respondedBy) {
+    const gateEvidence = captureEvidence({
+        stepId: gate.step_name,
+        startedAt: new Date(gate.opened_at),
+        completedAt: respondedAt,
+        input: { choice },
+        output: { ...gate.preview, choice },
+    });
+    return {
+        ...gateEvidence,
+        kind: 'gate_response',
+        ...(gate.resolved_message !== undefined ? { gate_message: gate.resolved_message } : {}),
+        ...(respondedBy !== undefined ? { responded_by: respondedBy } : {}),
+    };
+}
 export async function submitHumanResponse(store, definition, options) {
     // 1. Load run.
     let run;
@@ -2204,6 +2963,227 @@ export async function submitHumanResponse(store, definition, options) {
             });
         return errorEnvelope('submit_gate', options.runId, 0, e);
     }
+    // issue #279 (increment 2, PR-D, Deliverable 1b): the migrated path — the four legacy
+    // verify-arms below (1a-4) become settle_gate's OWN predicate arms; this branch skips them
+    // entirely and settles atomically against FRESH state via the store's own settleStep. Dormancy:
+    // an undeclaring store falls through to the byte-identical legacy path below (I16/#169
+    // fail-closed dormancy).
+    if (store.settleStep !== undefined) {
+        const respondedAt = new Date();
+        // Evidence rule (design record §6 lens-3 S2): built from the PRE-READ `pending_gate` IFF it
+        // matches options.gateId — else `[]` (the arm can never APPLY against a non-matching fresh
+        // read either, so an empty evidence array is inert there; a matching pre-read is guaranteed
+        // fresh enough to be correct on `applied: true`, since gate_id is a per-attempt-minted UUID
+        // that can never "come back" once resolved/absent).
+        const gateResponseEvidence = run.pending_gate !== undefined && run.pending_gate.gate_id === options.gateId
+            ? [
+                buildGateResponseSnapshot(run.pending_gate, options.choice, respondedAt, options.respondedBy),
+            ]
+            : [];
+        const delta = {
+            kind: 'settle_gate',
+            gateId: options.gateId,
+            choice: options.choice,
+            ...(options.respondedBy !== undefined ? { respondedBy: options.respondedBy } : {}),
+            evidence: gateResponseEvidence,
+        };
+        let result;
+        try {
+            result = await store.settleStep(options.runId, delta, definition);
+        }
+        catch (err) {
+            // Thrown infra errors keep the SAME shape as the legacy path's own final-persist catch,
+            // below (design record §6: "thrown infra errors ALSO keep the :3563-3581 shape").
+            const e = err instanceof WorkflowError
+                ? err
+                : new WorkflowError('Failed to persist gate response', {
+                    code: 'ENGINE_STORE_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'stop',
+                    retryable: false,
+                });
+            return errorEnvelope(run.pending_gate?.step_name ?? 'submit_gate', options.runId, run.version, e, `Failed to persist gate response.`, run.run_phase);
+        }
+        if (!result.applied) {
+            switch (result.reason) {
+                case 'already_settled': {
+                    // Calm ok envelope stating the resolution already committed (same choice) — never
+                    // report_to_user. Drain: on already_settled ∧ pending ledger entries non-empty — hand-
+                    // rolled here (buildAlreadySettledEnvelope is ExecuteStepOptions-shaped, not reusable at
+                    // this call site) — recovers a crashed-drain RESOLVE on a duplicate submit (design record
+                    // §6 row 2, the buildAlreadySettledEnvelope drain-on-NOOP pattern reused verbatim).
+                    const stepName = findGateStepName(result.run, options.gateId) ?? 'submit_gate';
+                    let noopRun = result.run;
+                    let noopDrainWarnings = [];
+                    const hasPending = Object.values(noopRun.finalizer_ledger ?? {}).some((e) => e.status === 'pending');
+                    if (hasPending) {
+                        try {
+                            const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                            noopRun = drainOutcome.run;
+                            noopDrainWarnings = drainOutcome.warnings;
+                        }
+                        catch (err) {
+                            noopDrainWarnings = [
+                                `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+                            ];
+                        }
+                    }
+                    return {
+                        command: stepName,
+                        run_id: options.runId,
+                        run_version: noopRun.version,
+                        status: 'ok',
+                        data: {},
+                        evidence: [],
+                        warnings: mergeWarnings([], ...noopDrainWarnings),
+                        errors: [],
+                        context_hint: `Gate '${options.gateId}' was already resolved with choice '${options.choice}' — no action was taken.`,
+                        run_phase: noopRun.run_phase,
+                        next_actions: noopRun.terminal_state ? [] : buildNextActions(definition, noopRun),
+                    };
+                }
+                case 'gate_choice_conflict': {
+                    const stepName = findGateStepName(result.run, options.gateId);
+                    const err = new WorkflowError(`Gate '${options.gateId}' was already resolved with choice '${result.winningChoice}' ` +
+                        `— your choice '${options.choice}' was not recorded.`, {
+                        code: 'STATE_BLOCKED',
+                        category: 'STATE',
+                        agentAction: 'report_to_user',
+                        retryable: false,
+                        details: {
+                            runId: options.runId,
+                            gateId: options.gateId,
+                            winning_choice: result.winningChoice,
+                        },
+                    });
+                    return errorEnvelope(stepName ?? 'submit_gate', options.runId, result.run.version, err, err.message, result.run.run_phase);
+                }
+                case 'choice_not_eligible': {
+                    // VALIDATION_INPUT_SCHEMA envelope — parity with the legacy path's own step 4 (below).
+                    const stepName = result.run.pending_gate.step_name; // the arm only reaches this check
+                    // when fresh.pending_gate.gate_id === gateId, so this is reliably the live gate's step.
+                    const expected = (result.choices ?? []).join(', ');
+                    const err = new WorkflowError(`Choice '${options.choice}' is not valid. Expected one of: ${expected}`, {
+                        code: 'VALIDATION_INPUT_SCHEMA',
+                        category: 'VALIDATION',
+                        agentAction: 'report_to_user',
+                        retryable: false,
+                    });
+                    return errorEnvelope(stepName, options.runId, result.run.version, err, `Invalid choice '${options.choice}' for gate '${stepName}'.`, result.run.run_phase);
+                }
+                case 'gate_mismatch': {
+                    const err = new WorkflowError(`Gate '${options.gateId}' is not the open gate and matches no committed resolution.`, {
+                        code: 'STATE_BLOCKED',
+                        category: 'STATE',
+                        agentAction: 'report_to_user',
+                        retryable: false,
+                        details: { runId: options.runId, gateId: options.gateId },
+                    });
+                    return errorEnvelope('submit_gate', options.runId, result.run.version, err, err.message, result.run.run_phase);
+                }
+                case 'run_terminal': {
+                    // Composed cancelled-predicate (design record §5 D-4/§11 N10): any gate_cancelled_by_abort
+                    // skip detail ⇒ the cancelled variant ("your choice was NOT recorded" + cause) — bound by
+                    // gate_id equality once that field is populated (PR-D+), else by presence alone (pre-PR-D
+                    // records, N10). No match ⇒ the zombie/grandfathered variant + the resume-clears/purge
+                    // pointer.
+                    const cancelEntry = Object.entries(result.run.skip_details ?? {}).find(([, d]) => d.kind === 'gate_cancelled_by_abort');
+                    const cancelDetail = cancelEntry?.[1];
+                    const isCancelledMatch = cancelEntry !== undefined &&
+                        (cancelDetail.gate_id === undefined || cancelDetail.gate_id === options.gateId);
+                    if (isCancelledMatch) {
+                        const [cancelledStep] = cancelEntry;
+                        const abortedBy = result.run.aborted_at?.step_id;
+                        const err = new WorkflowError(`Gate '${options.gateId}' on '${cancelledStep}' was cancelled when ` +
+                            `'${abortedBy ?? 'another step'}' aborted the run — your choice was NOT recorded.`, {
+                            code: 'STATE_RUN_TERMINAL',
+                            category: 'STATE',
+                            agentAction: 'report_to_user',
+                            retryable: false,
+                            details: {
+                                runId: options.runId,
+                                run_phase: result.run.run_phase,
+                                gate_id: options.gateId,
+                                step_name: cancelledStep,
+                                ...(abortedBy !== undefined ? { aborted_by: abortedBy } : {}),
+                            },
+                        });
+                        return errorEnvelope(cancelledStep, options.runId, result.run.version, err, err.message, result.run.run_phase);
+                    }
+                    // Zombie/grandfathered variant — the #282 class: a terminal record may still carry a
+                    // stale pending_gate (never cleared), which is the best-effort step label here.
+                    const zombieStep = result.run.pending_gate?.step_name ?? 'submit_gate';
+                    const err = new WorkflowError(`Run '${options.runId}' is terminal; cannot submit a gate response — 'realm resume' ` +
+                        `clears a stale pending gate on a resumable run, or 'realm run purge' removes the ` +
+                        `record entirely.`, {
+                        code: 'STATE_RUN_TERMINAL',
+                        category: 'STATE',
+                        agentAction: 'report_to_user',
+                        retryable: false,
+                        details: { runId: options.runId, run_phase: result.run.run_phase },
+                    });
+                    return errorEnvelope(zombieStep, options.runId, result.run.version, err, err.message, result.run.run_phase);
+                }
+                default:
+                    // gate_open_wait/already_open/already_released/choice_not_eligible's siblings and every
+                    // other kind's own reason are unreachable here — settle_gate never returns them (design
+                    // record §7).
+                    throw new Error(`submitHumanResponse: unreachable settle_gate refusal reason '${result.reason}'`);
+            }
+        }
+        // applied: true. Reliable step name: the pre-read's pending_gate.step_name (guaranteed
+        // correct whenever `applied` is true — see the evidence-rule comment above).
+        const resolvedGateStepName = run.pending_gate.step_name;
+        // Drain: on transitioned OR (already_settled ∧ pending ledger entries non-empty) — hand-rolled
+        // (buildAlreadySettledEnvelope is ExecuteStepOptions-shaped, not reusable here). `applied:
+        // true` never reaches the already_settled leg, so only the `transitioned` disjunct applies at
+        // THIS call site (design record §6 row 2).
+        let finalRun = result.run;
+        let drainWarnings = [];
+        if (result.transitioned) {
+            try {
+                const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                finalRun = drainOutcome.run;
+                drainWarnings = drainOutcome.warnings;
+            }
+            catch (err) {
+                drainWarnings = [
+                    `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+                ];
+            }
+        }
+        // Convergence hint (design record D-2 N8 narrowing, pedestal steal — must not drop): after a
+        // committed RESOLVE, when a guard is thereby eligible, append one line per eligible guard.
+        // findEligibleGuardSteps self-filters terminal runs (returns [] there), so this is inert on a
+        // gate-completion terminal transition.
+        const convergenceHints = findEligibleGuardSteps(definition, finalRun).map((name) => `guard '${name}' now eligible — converges at the next drive`);
+        const defaultedStepsDurabilityWarning = finalRun.defaulted_steps !== undefined &&
+            finalRun.defaulted_steps.length > 0 &&
+            !persistsField(store, 'defaulted_steps')
+            ? 'run-level defaultedness marker (defaulted_steps) not durable on this store'
+            : undefined;
+        const migratedNextActions = finalRun.terminal_state
+            ? []
+            : buildNextActions(definition, finalRun);
+        const migratedOrientation = finalRun.terminal_state
+            ? `Run completed (phase: '${finalRun.run_phase}'). Call get_run_state with run_id '${options.runId}' to retrieve the full evidence record.`
+            : `Gate '${resolvedGateStepName}' resolved with choice '${options.choice}'. ${migratedNextActions.length} step(s) now available.`;
+        return {
+            command: resolvedGateStepName,
+            run_id: options.runId,
+            run_version: finalRun.version,
+            status: 'ok',
+            data: { ...run.pending_gate.preview, choice: options.choice },
+            evidence: [],
+            warnings: mergeWarnings(convergenceHints, ...drainWarnings, defaultedStepsDurabilityWarning),
+            errors: [],
+            context_hint: migratedOrientation,
+            run_phase: finalRun.run_phase,
+            next_actions: migratedNextActions,
+            ...(finalRun.defaulted_steps?.length ? { defaulted_steps: finalRun.defaulted_steps } : {}),
+        };
+    }
+    // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
     // 1a. Defensive terminal guard (mirrors #91/#95): a late gate response must never re-drive a
     // run that has already reached a terminal phase.
     if (run.terminal_state) {
@@ -2334,7 +3314,9 @@ export async function submitHumanResponse(store, definition, options) {
         // envelope flag (do NOT add an evidence scan to recompute it). Its disclosure surface is the
         // run-level `defaulted_steps` marker below, plus whatever the gate-open envelope already
         // warned the human with.
-        warnings: mergeWarnings([], defaultedStepsDurabilityWarning),
+        // issue #279 (increment 2, PR-D): + the ONE dormancy advisory (I16) — this IS the legacy path
+        // (store.settleStep undeclared).
+        warnings: mergeWarnings([], defaultedStepsDurabilityWarning, DORMANCY_ADVISORY),
         errors: [],
         context_hint: orientation,
         run_phase: savedRun.run_phase,
@@ -2462,13 +3444,6 @@ async function executeGuardStep(stepName, stepDef, definition, run) {
         },
     };
 }
-/** Normalizes a finalizer's `on_outcome` to a set of triggers. */
-function finalizerTriggers(stepDef) {
-    const raw = stepDef.on_outcome;
-    if (raw === undefined)
-        return new Set();
-    return new Set(Array.isArray(raw) ? raw : [raw]);
-}
 /**
  * Drains the finalizers matching a run's terminal `outcome` and returns the FINALIZED
  * RunRecord — the workflow-level try/catch/finally at the seal. Modeled on
@@ -2496,22 +3471,15 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
     const hasFinalizers = Object.values(definition.steps).some((s) => s.execution === 'finalizer');
     if (!hasFinalizers)
         return sealDraft;
+    // issue #279 (increment 1, PR-A extraction): the grouping/ordering logic itself now lives in
+    // settlement.ts's selectFinalizers, shared with `mintFresh` — this call passes the SAME inputs
+    // the inline loop used to compute over, so the returned name list is byte-identical to what
+    // `[...groupA, ...groupB]` produced before the extraction.
     const settled = new Set([...sealDraft.completed_steps, ...sealDraft.failed_steps]);
-    const groupA = [];
-    const groupB = [];
-    for (const [name, step] of Object.entries(definition.steps)) {
-        if (step.execution !== 'finalizer')
-            continue;
-        if (settled.has(name))
-            continue; // at-most-once per run (resume / re-drive safety)
-        const triggers = finalizerTriggers(step);
-        if (triggers.has(outcome))
-            groupA.push([name, step]);
-        else if (triggers.has('always'))
-            groupB.push([name, step]);
-    }
+    const selected = selectFinalizers(definition, settled, outcome);
     let record = sealDraft;
-    for (const [name, step] of [...groupA, ...groupB]) {
+    for (const name of selected) {
+        const step = definition.steps[name];
         const now = new Date();
         const evidenceByStep = buildEvidenceByStep(record);
         const timeoutMs = (step.timeout_seconds ?? DRAIN_CEILING_SECONDS) * 1000;
@@ -2585,6 +3553,185 @@ async function buildFinalizedSeal(definition, sealDraft, outcome, registry) {
     }
     return { ...record, terminal_state: true };
 }
+/** Every currently-`'pending'` finalizer in `run`'s ledger, ascending by rank — the order the
+ *  drain loop below consumes (design record §6). */
+function pendingByRank(run) {
+    return Object.entries(run.finalizer_ledger ?? {})
+        .filter(([, e]) => e.status === 'pending')
+        .sort(([, a], [, b]) => a.rank - b.rank)
+        .map(([name]) => name);
+}
+/** Bounded retry count for `mark_finalizer` on a thrown `STATE_RUN_BUSY` (design record §6: "bounded
+ *  retry on thrown STATE_RUN_BUSY"). Small and fixed — lock contention self-heals quickly; this is
+ *  not a backoff schedule, just enough attempts to ride out a transient contender. */
+const DRAIN_MARK_BUSY_RETRIES = 3;
+/**
+ * Post-commit finalizer drain (design record §6, D2, issue #279 increment 1 PR-B). Drains the
+ * LOWEST-ranked pending finalizer, re-reading the record returned by the LAST settle/lease/mark at
+ * every step — NEVER a pass-start snapshot (the DRAIN_REREADS_LEDGER pin: a snapshot taken once at
+ * the top of this function would go stale the instant the first lease/mark commits, silently
+ * reintroducing exactly the kind of pre-commit assumption #279 exists to eliminate).
+ *
+ * Lives here (not in settlement.ts) so the module-private `withTimeout`/`callHandler` — already
+ * proven by `buildFinalizedSeal` above — are reused without exporting them; `settlement.ts` stays
+ * pure/no-I/O (design record §7 CS-purity).
+ *
+ * Registry pre-check: an absent handler leaves the entry pending and discloses why, rather than
+ * burning it (leasing it, failing the call, and marking it 'failed' would destroy the "recoverable
+ * on a capable runner" property a still-pending entry carries). Rank-monotonic: a pass HALTS at the
+ * first entry it cannot lease/execute, so a lower-ranked absent-handler or held-lease entry
+ * withholds every higher-ranked (later) finalizer behind it (R11) — this is deliberate: rank order
+ * is a DELIVERY order guarantee, not just a preference.
+ *
+ * `not_eligible` at lease OR mark time is a contract violation (an unknown finalizer id — mintFresh
+ * only ever mints real workflow finalizer names) and aborts the pass LOUD (throws), distinct from
+ * `ledger_not_pending` at lease time, which ADVANCES (someone else already resolved it). A
+ * non-BUSY infra throw from `mark_finalizer` also aborts loud, with the remaining-pending list in
+ * the message. The executed-but-not-recorded warning (three reasons: `lease_lost`,
+ * `ledger_not_pending`-AFTER-execution, `run_not_terminal`) halts the pass rather than continuing —
+ * each of those three reasons refuses the mark WITHOUT mutating the ledger entry's `'pending'`
+ * status, so continuing would re-select the SAME entry next iteration (an infinite loop); halting
+ * is the only forward-progress-safe response until an operator or a later terminal edge resolves it.
+ */
+export async function drainFinalizers(store, definition, registry, runId) {
+    // .bind(store): a bare `store.settleStep` reference loses its `this` binding — the store's own
+    // method body (e.g. JsonFileStore's `this.ensureDir()`/`this.filePath()`) would throw on
+    // `this === undefined` once called through the detached reference below.
+    const settleStep = store.settleStep?.bind(store);
+    if (settleStep === undefined) {
+        // Defensive — every caller only invokes this once it has already confirmed the store
+        // declares settleStep. A fresh read is still the correct degenerate response.
+        return { run: await store.get(runId), warnings: [] };
+    }
+    const warnings = [];
+    let run = await store.get(runId);
+    for (;;) {
+        const pending = pendingByRank(run);
+        if (pending.length === 0)
+            break;
+        const finalizerName = pending[0];
+        const stepDef = definition.steps[finalizerName];
+        const handlerName = stepDef?.handler;
+        const handler = handlerName !== undefined ? registry?.getHandler(handlerName) : undefined;
+        // Registry pre-check — never burn an absent handler; rank-monotonic HALT (R11).
+        if (stepDef === undefined || handlerName === undefined || handler === undefined) {
+            warnings.push(`finalizer '${finalizerName}' left pending — handler not available on this surface`);
+            break;
+        }
+        const leaseToken = crypto.randomUUID();
+        const leaseSeconds = stepDef.timeout_seconds ?? DRAIN_CEILING_SECONDS;
+        const leaseResult = await settleStep(runId, { kind: 'lease_finalizer', finalizer: finalizerName, leaseToken, leaseSeconds }, definition);
+        if (!leaseResult.applied) {
+            if (leaseResult.reason === 'lease_held' || leaseResult.reason === 'rank_blocked') {
+                run = leaseResult.run;
+                break; // HALT the pass — a peer holds this lease, or a lower rank is still pending.
+            }
+            if (leaseResult.reason === 'ledger_not_pending') {
+                run = leaseResult.run;
+                continue; // ADVANCE — a peer already resolved this entry.
+            }
+            // not_eligible — unknown finalizer id; a contract violation (mintFresh never mints one).
+            throw new Error(`drainFinalizers: lease refused '${leaseResult.reason}' for finalizer '${finalizerName}' ` +
+                `on run '${runId}' — remaining pending: ${pendingByRank(leaseResult.run).join(', ')}`);
+        }
+        run = leaseResult.run;
+        // callHandler under withTimeout, OUTSIDE any critical section (the store's CS ends the
+        // instant the lease-apply write above returned).
+        const startedAt = new Date();
+        const evidenceByStep = buildEvidenceByStep(run);
+        const callOptions = {
+            runId,
+            command: finalizerName,
+            input: {},
+            dispatcher: async () => ({}),
+            ...(registry !== undefined ? { registry } : {}),
+        };
+        let markResult;
+        let evidenceSnapshot;
+        try {
+            const callResult = await withTimeout((signal) => callHandler(stepDef, callOptions, run, evidenceByStep, signal), leaseSeconds * 1000, finalizerName);
+            if (callResult.kind === 'abort') {
+                markResult = 'failed';
+                evidenceSnapshot = captureEvidence({
+                    stepId: finalizerName,
+                    startedAt,
+                    completedAt: new Date(),
+                    input: {},
+                    output: { aborted: true, abort_message: callResult.message },
+                    error: `Finalizer '${finalizerName}' returned abort: ${callResult.message}`,
+                });
+            }
+            else {
+                markResult = 'completed';
+                evidenceSnapshot = captureEvidence({
+                    stepId: finalizerName,
+                    startedAt,
+                    completedAt: new Date(),
+                    input: {},
+                    output: callResult.output,
+                    ...(callResult.kind === 'warn' ? { warn: callResult.message } : {}),
+                });
+            }
+        }
+        catch (err) {
+            markResult = 'failed';
+            const message = err instanceof Error ? err.message : String(err);
+            evidenceSnapshot = captureEvidence({
+                stepId: finalizerName,
+                startedAt,
+                completedAt: new Date(),
+                input: {},
+                output: {},
+                error: `Finalizer '${finalizerName}' failed: ${message}`,
+            });
+        }
+        // mark_finalizer — same lease token; bounded retry on a THROWN STATE_RUN_BUSY only.
+        let markOutcome;
+        for (let attempt = 1; attempt <= DRAIN_MARK_BUSY_RETRIES; attempt++) {
+            try {
+                markOutcome = await settleStep(runId, {
+                    kind: 'mark_finalizer',
+                    finalizer: finalizerName,
+                    leaseToken,
+                    result: markResult,
+                    evidence: evidenceSnapshot,
+                }, definition);
+                break;
+            }
+            catch (err) {
+                const isBusy = err instanceof WorkflowError && err.code === 'STATE_RUN_BUSY';
+                if (isBusy && attempt < DRAIN_MARK_BUSY_RETRIES)
+                    continue;
+                // Non-BUSY infra throw (or BUSY exhausted) ⇒ abort the pass loud, remaining-pending named.
+                throw new Error(`drainFinalizers: mark_finalizer failed for '${finalizerName}' on run '${runId}' — ` +
+                    `remaining pending: ${pendingByRank(run).join(', ')}: ` +
+                    `${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+        }
+        /* istanbul ignore next -- the for-loop above always either assigns markOutcome or throws */
+        if (markOutcome === undefined) {
+            throw new Error(`drainFinalizers: mark_finalizer produced no outcome for '${finalizerName}' on run '${runId}'`);
+        }
+        if (!markOutcome.applied) {
+            if (markOutcome.reason === 'not_eligible') {
+                throw new Error(`drainFinalizers: mark refused 'not_eligible' for finalizer '${finalizerName}' on run ` +
+                    `'${runId}' — contract violation (mintFresh never mints an unknown id)`);
+            }
+            // lease_lost / ledger_not_pending(-after-execution) / run_not_terminal: the handler DID
+            // execute, but the outcome could not be durably recorded — the three-reason
+            // executed-but-not-recorded warning (design record §6). Halt: none of these three mutate
+            // the entry's 'pending' status, so continuing would re-select the SAME entry forever.
+            run = markOutcome.run;
+            warnings.push(`finalizer '${finalizerName}' executed but its outcome may not have been recorded ` +
+                `(${markOutcome.reason}) — it may re-execute at the next terminal edge`);
+            break;
+        }
+        run = markOutcome.run;
+        // result:'failed' is settled too (a recorded terminal outcome for this finalizer) — the loop
+        // continues to the next rank regardless of markResult.
+    }
+    return { run, warnings };
+}
 async function executeChainInternal(store, definition, options, depth, chainedSteps, 
 /**
  * issue #197 PR-2 (chain-replacement disposition, accepted): a settled DEPTH-0 step (typically
@@ -2642,15 +3789,242 @@ depth0Warnings) {
     // Execute any eligible guard steps inline before looking for the next auto step.
     // Guard steps are synchronous engine decisions — not returned to the agent.
     // Loop to handle cascading guards (guard A passes → guard B becomes eligible).
+    // issue #279 (increment 2, PR-D, Deliverable 1c): non-abort settled_outcome_divergence warnings
+    // ADVANCE the chain but must still surface somewhere — carried here and merged into whichever
+    // envelope eventually returns (the guardsRan rebuild below, or a migrated terminal return).
+    const guardWarnings = [];
     let guardEligible = findEligibleGuardSteps(definition, run);
     while (guardEligible.length > 0) {
         const guardName = guardEligible[0];
         const guardStepDef = definition.steps[guardName];
-        // Execute inline (pure in-memory; returns updated RunRecord).
+        // Execute inline (pure in-memory; returns updated RunRecord). executeGuardStep stays PURE and
+        // UNTOUCHED (design record §1) — both the migrated and legacy paths below call it identically.
         const guardResult = await executeGuardStep(guardName, guardStepDef, definition, run);
         // Capture the guard's OWN evidence (its last entry) BEFORE the finalizer drain appends
         // finalizer evidence — the terminal return below surfaces only the guard's evidence.
         const guardOwnEvidence = guardResult.evidence.slice(-1);
+        // issue #279 (increment 2, PR-D, Deliverable 1c): the migrated path — settles this guard's
+        // evaluated outcome atomically against FRESH state via the store's own settleStep. Dormancy:
+        // an undeclaring store falls through to the byte-identical legacy path below (I16/#169
+        // fail-closed dormancy).
+        if (store.settleStep !== undefined) {
+            // Extraction rule (design record §2, normative): reverse-classify guardResult's SEALED
+            // output by MEMBERSHIP — NEVER the terminal_state ternary below (wrong for a non-terminal
+            // pass, which never sets terminal_state at all).
+            const guardSettleOutcome = guardResult.aborted_at !== undefined
+                ? 'abort'
+                : guardResult.failed_steps.includes(guardName)
+                    ? 'resolution_error'
+                    : 'pass'; // the only remaining membership — completed_steps.includes(guardName)
+            let resolutionError;
+            if (guardSettleOutcome === 'resolution_error') {
+                // Rails-compliant re-derivation (normative): normalize abort_unless to string[] (the
+                // executeGuardStep :3632-3635 shape) and re-run evaluateGuardConditions against the SAME
+                // pre-seal `run` passed to executeGuardStep — pure + deterministic, so this reproduces the
+                // discarded internal result byte-for-byte.
+                const conditions = Array.isArray(guardStepDef.abort_unless)
+                    ? guardStepDef.abort_unless
+                    : [guardStepDef.abort_unless];
+                const reEvaluated = evaluateGuardConditions(conditions, buildEvidenceByStep(run));
+                if (reEvaluated.kind === 'resolution_error') {
+                    resolutionError = {
+                        condition: reEvaluated.condition,
+                        unresolvable_path: reEvaluated.unresolvable_path,
+                    };
+                }
+            }
+            const delta = {
+                kind: 'settle_guard',
+                step: guardName,
+                outcome: guardSettleOutcome,
+                evidence: guardOwnEvidence[0],
+                ...(resolutionError !== undefined ? { resolutionError } : {}),
+                ...(guardSettleOutcome === 'abort'
+                    ? {
+                        abort: {
+                            conditions: guardResult.aborted_at.conditions ?? [],
+                            ...(guardResult.aborted_at.abort_message !== undefined
+                                ? { abort_message: guardResult.aborted_at.abort_message }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                // evaluatedAtVersion (design record §2, lane-B steal 2): the chain's OWN evaluation
+                // snapshot — this iteration's pre-settle `run.version`.
+                evaluatedAtVersion: run.version,
+            };
+            let guardSettleResult;
+            try {
+                guardSettleResult = await store.settleStep(options.runId, delta, definition);
+            }
+            catch (storeErr) {
+                // Thrown infra errors — the same persist-failure envelope shape the legacy path's own
+                // store.update catch (below) has always returned.
+                const msg = storeErr instanceof Error ? storeErr.message : String(storeErr);
+                return {
+                    command: options.command,
+                    run_id: options.runId,
+                    run_version: run.version,
+                    status: 'error',
+                    data: {},
+                    evidence: [],
+                    warnings: [],
+                    errors: [`Failed to persist guard step '${guardName}': ${msg}`],
+                    agent_action: 'stop',
+                    context_hint: `Guard step '${guardName}' could not be persisted. Run state may be inconsistent.`,
+                    run_phase: run.run_phase,
+                    next_actions: [],
+                };
+            }
+            if (!guardSettleResult.applied) {
+                // Chain-consumption table (design record §6, adjudicated):
+                if (guardSettleResult.reason === 'already_settled' ||
+                    guardSettleResult.reason === 'gate_open_wait' ||
+                    (guardSettleResult.reason === 'settled_outcome_divergence' &&
+                        guardSettleOutcome !== 'abort')) {
+                    // already_settled / gate_open_wait ⇒ ADVANCE, threading result.run (findEligibleGuardSteps
+                    // self-filters both a now-settled guard and an open gate, so the loop naturally converges).
+                    // settled_outcome_divergence on a NON-abort attempt ⇒ ADVANCE + a warning line.
+                    if (guardSettleResult.reason === 'settled_outcome_divergence') {
+                        guardWarnings.push(`guard '${guardName}' outcome diverged from a concurrent settle` +
+                            (guardSettleResult.persisted !== undefined
+                                ? ` (persisted: '${guardSettleResult.persisted}')`
+                                : '') +
+                            ' — chain advanced on the persisted outcome.');
+                    }
+                    if (guardSettleResult.reason !== 'gate_open_wait') {
+                        // "quiet" end-of-pass for gate_open_wait only — nothing was decided, so nothing is
+                        // recorded; already_settled/divergence DID decide something (elsewhere), so it is.
+                        chainedSteps.push({ step: guardName, run_phase: guardSettleResult.run.run_phase });
+                    }
+                    run = guardSettleResult.run;
+                    // Drain: on already_settled ∧ pending ledger entries non-empty (design record §6, "same
+                    // clause" as the transitioned leg below) — recovers a crashed-drain RESOLVE that a
+                    // sibling's own settle committed but never drained.
+                    if (guardSettleResult.reason === 'already_settled') {
+                        const hasPending = Object.values(run.finalizer_ledger ?? {}).some((e) => e.status === 'pending');
+                        if (hasPending) {
+                            try {
+                                const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                                run = drainOutcome.run;
+                                if (drainOutcome.warnings.length > 0)
+                                    guardWarnings.push(...drainOutcome.warnings);
+                            }
+                            catch (err) {
+                                guardWarnings.push(`post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`);
+                            }
+                        }
+                    }
+                    guardEligible = findEligibleGuardSteps(definition, run);
+                    continue;
+                }
+                if (guardSettleResult.reason === 'settled_outcome_divergence') {
+                    // ABORT leg only ⇒ report_to_user + chain-RETURN (design record §6/§7) — this attempt's
+                    // abort was never recorded.
+                    const err = new WorkflowError(`Guard step '${guardName}' was already settled` +
+                        (guardSettleResult.persisted !== undefined
+                            ? ` (persisted: '${guardSettleResult.persisted}')`
+                            : '') +
+                        ` by a different attempt — your abort was NOT recorded.`, {
+                        code: 'STATE_STEP_ALREADY_SETTLED',
+                        category: 'STATE',
+                        agentAction: 'report_to_user',
+                        retryable: false,
+                        details: {
+                            runId: options.runId,
+                            step: guardName,
+                            reason: guardSettleResult.reason,
+                            ...(guardSettleResult.persisted !== undefined
+                                ? { persisted: guardSettleResult.persisted }
+                                : {}),
+                        },
+                    });
+                    return {
+                        command: options.command,
+                        run_id: options.runId,
+                        run_version: guardSettleResult.run.version,
+                        status: 'error',
+                        data: {},
+                        evidence: [],
+                        warnings: [],
+                        errors: [err.message],
+                        error_code: err.code,
+                        ...(Object.keys(err.details).length > 0 ? { error_details: err.details } : {}),
+                        agent_action: 'report_to_user',
+                        context_hint: err.message,
+                        run_phase: guardSettleResult.run.run_phase,
+                        next_actions: [],
+                    };
+                }
+                if (guardSettleResult.reason === 'run_terminal') {
+                    // Terminal by OTHER (a sibling settle raced this guard's own evaluation) — INLINE
+                    // construction, parity with the entry-terminal envelope (executeChain's own early
+                    // return).
+                    return {
+                        command: options.command,
+                        run_id: options.runId,
+                        run_version: guardSettleResult.run.version,
+                        status: 'ok',
+                        data: {},
+                        evidence: [],
+                        warnings: [],
+                        errors: [],
+                        agent_action: 'stop',
+                        context_hint: `Run '${options.runId}' is already terminal (${guardSettleResult.run.run_phase}); guard '${guardName}' was not evaluated.`,
+                        run_phase: guardSettleResult.run.run_phase,
+                        next_actions: [],
+                    };
+                }
+                // gate_mismatch/choice_not_eligible/already_open/already_released and every other kind's
+                // own reason are unreachable here — settle_guard never returns them (design record §7).
+                throw new Error(`executeChainInternal: unreachable settle_guard refusal reason '${guardSettleResult.reason}'`);
+            }
+            // applied: true.
+            chainedSteps.push({ step: guardName, run_phase: guardSettleResult.run.run_phase });
+            if (guardSettleResult.transitioned) {
+                // Drain IMMEDIATELY after a transitioned settle result, BEFORE building the in-loop
+                // terminal envelope (design record §6/R5 — a post-loop drain would be dead code on this
+                // leg: this function RETURNS before ever reaching a post-loop point).
+                let finalGuardRun = guardSettleResult.run;
+                let guardDrainWarnings;
+                try {
+                    const drainOutcome = await drainFinalizers(store, definition, options.registry, options.runId);
+                    finalGuardRun = drainOutcome.run;
+                    guardDrainWarnings = drainOutcome.warnings;
+                }
+                catch (err) {
+                    guardDrainWarnings = [
+                        `post-commit finalizer drain failed: ${err instanceof Error ? err.message : String(err)}`,
+                    ];
+                }
+                const migratedContextHint = guardSettleOutcome === 'abort'
+                    ? `Guard step '${guardName}' aborted the run.`
+                    : guardSettleOutcome === 'resolution_error'
+                        ? `Guard step '${guardName}' failed with a resolution error. Run is terminated.`
+                        : `Guard step '${guardName}' passed and completed the run.`;
+                return {
+                    command: options.command,
+                    run_id: options.runId,
+                    run_version: finalGuardRun.version,
+                    status: 'ok',
+                    data: {},
+                    evidence: guardOwnEvidence,
+                    warnings: mergeWarnings(guardWarnings, ...guardDrainWarnings),
+                    errors: [],
+                    context_hint: migratedContextHint,
+                    run_phase: finalGuardRun.run_phase,
+                    next_actions: [],
+                    ...(finalGuardRun.defaulted_steps?.length
+                        ? { defaulted_steps: finalGuardRun.defaulted_steps }
+                        : {}),
+                };
+            }
+            // Non-terminal pass — continue the chain.
+            run = guardSettleResult.run;
+            guardEligible = findEligibleGuardSteps(definition, run);
+            continue;
+        }
+        // --- Legacy path (dormancy fallback — byte-identical to pre-#279 behavior) ---
         // Blocking fix #1: classify the terminal outcome by the SEALED record, not aborted_at
         // alone. executeGuardStep sets terminal_state in THREE cases — abort (aborted_at set),
         // resolution-error (failed, no aborted_at), and a PASS that completes the run
@@ -2719,7 +4093,9 @@ depth0Warnings) {
                 data: {},
                 // The guard's own evidence entry, captured before the finalizer drain appended any.
                 evidence: guardOwnEvidence,
-                warnings: mergeWarnings([], guardDefaultedStepsDurabilityWarning),
+                // issue #279 (increment 2, PR-D): + the ONE dormancy advisory (I16) — this IS the legacy
+                // path (store.settleStep undeclared).
+                warnings: mergeWarnings([], guardDefaultedStepsDurabilityWarning, DORMANCY_ADVISORY),
                 errors: [],
                 context_hint: contextHint,
                 run_phase: persistedGuardRun.run_phase,
@@ -2743,6 +4119,12 @@ depth0Warnings) {
             ...result,
             run_version: run.version,
             next_actions: freshNextActions,
+            // issue #279 (increment 2, PR-D): non-abort settled_outcome_divergence warnings accumulated
+            // during the guard loop above (the ADVANCE leg) must reach whichever envelope returns —
+            // this rebuild is the first point after the loop `result` is touched again.
+            ...(guardWarnings.length > 0
+                ? { warnings: mergeWarnings(result.warnings, ...guardWarnings) }
+                : {}),
         };
     }
     if (run.terminal_state || run.pending_gate !== undefined) {
@@ -2799,7 +4181,13 @@ export async function executeChain(store, definition, options) {
             throw err;
         }
     }
-    if (entryRun !== undefined && isTerminalPhase(entryRun.run_phase)) {
+    // issue #279 (increment 2, PR-C — D-3 leg v): keyed on terminal_state, never the persisted
+    // run_phase — a grandfathered terminal-with-stale-gate record (the #282 class) must still be
+    // recognized as terminal here.
+    if (entryRun !== undefined && entryRun.terminal_state === true) {
+        // Derive-for-message (D-3 leg v): render the TRUE (derived) phase, never the possibly-stale
+        // persisted one.
+        const derivedPhase = deriveRunPhase(entryRun);
         return {
             command: options.command,
             run_id: options.runId,
@@ -2810,8 +4198,8 @@ export async function executeChain(store, definition, options) {
             warnings: [],
             errors: [],
             agent_action: 'stop',
-            context_hint: `Run '${options.runId}' is already terminal (${entryRun.run_phase}); no steps executed.`,
-            run_phase: entryRun.run_phase,
+            context_hint: `Run '${options.runId}' is already terminal (${derivedPhase}); no steps executed.`,
+            run_phase: derivedPhase,
             next_actions: [],
         };
     }