@sensigo/realm 0.25.0 → 0.27.0

package/dist/engine/execution-loop.js

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