@elvisw/dsh-magic-context 0.0.0-stage → 0.14.0

package/lib/dsh/management-pass.js

@@ -0,0 +1,564 @@
+/**
+ * The management pass — everything the adapter does inside the execute band,
+ * in one place, in Magic Context's order:
+ *
+ *   1. land queued ctx_reduce marks as `[dropped §N§]` placeholders;
+ *   2. publish historian compartments as `[compacted §C<n>§]` range
+ *      replacements (the digest itself travels in the baseline node);
+ *   3. force reclaim when pressure reaches the force band;
+ *   4. refresh the m[0]/m[1] baseline node — but ONLY when its rendered
+ *      content actually changed (a no-op pass must not bust the cache);
+ *   5. fire the historian out of band (it writes a store row; nothing on the
+ *      wire changes because of it).
+ *
+ * All surface work happens here and only here: the execute band is the one
+ * bust permission, and every step above is a durable mutation that spends it.
+ */
+import { compactedPlaceholder, estimateTokens, findBaselineRange, renderBaseline, renderMemoryUpdates, stripBaseline, } from "../core/compartments.js";
+import { renderMemoryLine } from "../core/memory-bridge.js";
+import { errText } from "../core/types.js";
+import { reclaimForEmergency } from "./emergency.js";
+import { runHistorian } from "./historian.js";
+import { landPendingDrops } from "./drop-landing.js";
+import { enumerateSurfaceNodes, enumerateSurfaceToolResults, magicContextSource, pairingClosedWindow, replaceSurfaceRange, syntheticNodeId, wireStrandedResults, } from "./seams.js";
+/** Estimated tokens of every current surface node (shared with the emergency
+ * lane in index.ts — the #731 fit guard needs the whole-surface estimate). */
+export function surfaceTokens(session) {
+    return enumerateSurfaceNodes(session).reduce((total, node) => total + (node.hasText ? estimateTokens(node.text) : 0), 0);
+}
+/** The baseline block currently carried by a node, when it has one. */
+function baselineBlockOf(text) {
+    const range = findBaselineRange(text);
+    return range === undefined ? undefined : text.slice(range.start, range.end);
+}
+/** Compose the baseline block ahead of the node's own (baseline-free) content. */
+function composeBaselineContent(node, block) {
+    const stripped = stripBaseline(node.text);
+    const content = [{ type: 'text', text: block }];
+    if (stripped.length > 0)
+        content.push({ type: 'text', text: stripped });
+    return content;
+}
+/** Split stored compartments into the frozen m[0] set and the m[1] delta. */
+export function splitBaselineSets(compartments, state) {
+    if (state === undefined)
+        return { baseline: [...compartments], delta: [] };
+    return {
+        baseline: compartments.filter(compartment => compartment.createdAt <= state.frozenAt),
+        delta: compartments.filter(compartment => compartment.createdAt > state.frozenAt),
+    };
+}
+function publishCompartments(input) {
+    const published = [];
+    let factsPromoted = 0;
+    let factsSeenAgain = 0;
+    const baselineNodeSeq = input.stores.baselineState(input.sessionId)?.nodeSeq;
+    for (const compartment of input.stores.listUnlandedCompartments(input.sessionId)) {
+        const covered = new Set(compartment.coveredSeqs);
+        // The host shadows every node in the POSITIONAL range between the two
+        // endpoints, not the subset the compartment covered
+        // (`host: packages/core/session/src/surface.ts:433`, asserted at `:363`).
+        // Citing only the covered subset threw on the first node that had entered
+        // the range since the compartment was drafted, and that threw the whole
+        // pass — every pass, so nothing ever landed. Enumerate the live surface here
+        // (the snapshot at the call site predates the previous replacement) and cite
+        // the whole range.
+        const live = enumerateSurfaceNodes(input.session);
+        const positions = [];
+        live.forEach((node, index) => {
+            if (covered.has(node.seq))
+                positions.push(index);
+        });
+        if (positions.length === 0 || (baselineNodeSeq !== undefined && covered.has(baselineNodeSeq))) {
+            input.stores.markCompartmentLanded(input.sessionId, compartment.compartmentId, 0);
+            continue;
+        }
+        const rawFirst = positions[0];
+        const rawLast = positions[positions.length - 1];
+        // Drop placeholders re-sequence a result to the surface tail while its
+        // tool_use stays inside the covered span; a range that cuts between them
+        // strands the result and the next provider request fails validation
+        // (live 2026-10-09). Widen to tool-pairing closure before cutting.
+        const span = pairingClosedWindow(live, rawFirst, rawLast);
+        const range = live.slice(span.first, span.last + 1);
+        // m[0] is frozen at the head of the surface: folding it into a compartment
+        // would leave the next refresh rewriting an unrelated `user` node as the
+        // baseline. Defer instead; the guard clears once the surface moves on.
+        if (baselineNodeSeq !== undefined && range.some(node => node.seq === baselineNodeSeq)) {
+            input.journal?.warn('compartment-published', `compartment §C${String(compartment.compartmentId)}§ deferred: its range now contains the m[0] baseline node`, {
+                compartmentId: compartment.compartmentId,
+                reason: 'baseline-in-range',
+                nodes: range.length,
+            }, input.sessionId);
+            continue;
+        }
+        // NOTE (2026-10-16): the fusion-v7 publish guard stood here (observe /
+        // enforce over drift + no-gain verdicts). RETIRED by user decision: across
+        // its whole observation window (2026-10-09 commit 96337e00b → 2026-10-16)
+        // the journal recorded 0 `compartment-guard` hits against 58 clean
+        // `compartment-published` rows, so even `enforce` would never have acted —
+        // zero benefit, one more way to hold up a publish. The positional range +
+        // pairing closure above remains the whole landing discipline.
+        const first = range[0];
+        const last = range[range.length - 1];
+        // A host validator refusal here (2026-10-08 live incident: the pre-fix
+        // shadow list missed range entrants, 69 journal errors across 2 sessions —
+        // the same poisoned draft threw on EVERY pass) must be terminal for THIS
+        // draft, never a retry loop, and must never starve the drafts behind it:
+        // retire it as rejected (covered claims stay claimed, no re-digest flood;
+        // the span stays on the wire, honestly) and let the loop move on.
+        let landedSeq;
+        try {
+            landedSeq = replaceSurfaceRange(input.session, first.seq, last.seq, [{ type: 'text', text: compactedPlaceholder(compartment.compartmentId) }], range.map(node => node.seq), syntheticNodeId(`mc-compacted-${String(compartment.compartmentId)}`), magicContextSource(`Magic Context · compartment §C${String(compartment.compartmentId)}§ replaced ${String(range.length)} node(s) on the wire`));
+        }
+        catch (error) {
+            input.stores.markCompartmentRejected(input.sessionId, compartment.compartmentId, 'replace-failed');
+            input.journal?.error('compartment-published', `compartment §C${String(compartment.compartmentId)}§ replace refused; retired as rejected (span stays on the wire)`, {
+                compartmentId: compartment.compartmentId,
+                reason: 'replace-failed',
+                nodes: range.length,
+                error: errText(error),
+            }, input.sessionId);
+            continue;
+        }
+        input.stores.markCompartmentLanded(input.sessionId, compartment.compartmentId, landedSeq);
+        published.push(compartment.compartmentId);
+        input.journal?.info('compartment-published', `compartment §C${String(compartment.compartmentId)}§ replaced ${String(range.length)} nodes on the wire`, {
+            compartmentId: compartment.compartmentId,
+            nodes: range.length,
+            coveredTokens: compartment.coveredTokens,
+            estTokensReclaimed: range.reduce((total, node) => total + estimateTokens(node.text), 0),
+            nodeSeq: landedSeq,
+            importance: compartment.importance,
+            ...((span.first !== rawFirst || span.last !== rawLast)
+                ? { pairingClosure: { rawFirst, rawLast, first: span.first, last: span.last } }
+                : {}),
+        }, input.sessionId);
+        // Magic Context promotes the compartment's facts in the same publish step
+        // (`compartment-runner-incremental.ts:1077`). Ours is not one SQLite
+        // transaction (the compartment store and the memory store are different
+        // databases and different owners), so a failure is journaled and the facts
+        // stay durably in the compartment row for a later retry — reclaim must not
+        // stall on a memory problem.
+        if (input.memoryPromote !== undefined && input.memoryIdentity !== undefined && compartment.facts.length > 0) {
+            try {
+                const outcome = input.memoryPromote({
+                    identity: input.memoryIdentity,
+                    facts: compartment.facts,
+                    sessionId: input.sessionId,
+                });
+                factsPromoted += outcome.inserted.length;
+                factsSeenAgain += outcome.seenAgain.length;
+                input.journal?.info('memory-promote', `promoted ${String(outcome.inserted.length)} fact(s) into project memory`
+                    + `${outcome.seenAgain.length > 0 ? `, ${String(outcome.seenAgain.length)} already known` : ''}`, {
+                    compartmentId: compartment.compartmentId,
+                    identity: input.memoryIdentity,
+                    inserted: outcome.inserted.map(row => ({ id: row.id, category: row.category })),
+                    seenAgain: outcome.seenAgain.map(row => row.id),
+                    skipped: outcome.skipped,
+                }, input.sessionId);
+            }
+            catch (error) {
+                const detail = errText(error);
+                input.journal?.error('error', `memory promotion failed: ${detail}`, {
+                    scope: 'memory-promote',
+                    detail,
+                    compartmentId: compartment.compartmentId,
+                }, input.sessionId);
+            }
+        }
+    }
+    return { ids: published, factsPromoted, factsSeenAgain };
+}
+/**
+ * Publish ready compartments OUTSIDE a management pass — the provider-overflow
+ * path (index.ts `agent/request-error`) lands the bank before it drops tool
+ * results: one replacement reclaims a whole digested span, an emergency drop
+ * only individual tool results, and the request has already failed once, so
+ * the bust cannot lose more than the failed retry did.
+ *
+ * The request-error lane is a forced execute band in everything but name —
+ * the same exception family as the wire-repair iron rule (the provider
+ * rejected the wire as-is). Same surface discipline as the pass's publish
+ * lane (pairing closure, m[0]-baseline defer). NO baseline refresh and NO
+ * fact promotion here: both belong to the next execute pass, the facts stay
+ * durable in the compartment row, and the promotion retry is idempotent
+ * (seen-again dedup).
+ */
+export function publishReadyCompartments(input) {
+    return { ids: publishCompartments(input).ids };
+}
+/**
+ * Refresh the baseline node: the first current `user` node carries the
+ * m[0]/m[1] block ahead of its own content. Returns whether the surface
+ * changed. A HARD rebuild (no state yet, route change, memory-digest change)
+ * freezes m[0] again and empties the delta; otherwise the delta grows.
+ */
+function refreshBaseline(input, nodes) {
+    const now = input.now?.() ?? Date.now();
+    const compartments = input.stores.listCompartments(input.sessionId);
+    const memories = input.memories;
+    const profile = input.profile;
+    const updates = input.memoryUpdates;
+    const previous = input.stores.baselineState(input.sessionId);
+    const routeChanged = previous !== undefined
+        && (previous.provider !== input.route?.provider || previous.model !== input.route?.model);
+    const memoriesChanged = previous !== undefined
+        && previous.memoriesDigest !== undefined
+        && memories !== undefined
+        && previous.memoriesDigest !== memories.digest;
+    // The external-writer signal: Magic Context bumps
+    // `project_state.project_memory_epoch` when an external edit (or a domain
+    // /identity change) invalidates a running session's snapshot. Both the m[0]
+    // pool AND the mutation cursor were built against the old epoch, so this is
+    // a HARD rebuild — reusing the old cursor would render a misaligned delta.
+    const epochChanged = previous !== undefined
+        && previous.projectEpochFingerprint !== undefined
+        && updates?.projectEpochFingerprint !== undefined
+        && previous.projectEpochFingerprint !== updates.projectEpochFingerprint;
+    // One-time upgrade fold: a baseline written before the cursor column existed
+    // cannot order its delta, so the first pass that actually has pending change
+    // rows folds them into m[0] and stamps the cursor instead of rendering a
+    // delta read from zero.
+    const cursorUpgrade = previous !== undefined
+        && previous.maxMemoryMutationId === undefined
+        && updates !== undefined
+        && updates.updates.length > 0;
+    // WP8: the profile's fold trigger. An entry ABOVE the frozen watermark is an
+    // addition and rides m[1] without touching the prefix. A row AT or below it
+    // being rewritten or dismissed changes the digest — and here, unlike Magic
+    // Context whose version bump deliberately never folded m[0], the stale block
+    // is rebuilt: a profile the agent keeps reading after it was retracted is
+    // worse than one cache bust. The `''` sentinel recorded by an emptying fold
+    // keeps a switched-off profile from rebuilding on every later pass.
+    const profileChanged = previous !== undefined && (profile === undefined
+        ? previous.profileM0Digest !== undefined && previous.profileM0Digest !== ''
+        : previous.profileM0Digest === undefined
+            ? true
+            : previous.profileM0Digest !== profile.digest);
+    const hard = previous === undefined || routeChanged || memoriesChanged || epochChanged || cursorUpgrade || profileChanged;
+    // Freeze targets for a HARD fold. Falling back to the previous values keeps a
+    // pass that has no mutation lane (bridge unavailable) from rewinding them.
+    const frozenCursor = updates?.cursor ?? previous?.maxMemoryMutationId;
+    const frozenEpochFingerprint = updates?.projectEpochFingerprint ?? previous?.projectEpochFingerprint;
+    const state = hard
+        ? {
+            sessionId: input.sessionId,
+            epoch: (previous?.epoch ?? 0) + 1,
+            ...previous?.nodeSeq === undefined ? {} : { nodeSeq: previous.nodeSeq },
+            ...input.route === undefined ? {} : { provider: input.route.provider, model: input.route.model },
+            frozenAt: now,
+            ...memories === undefined ? {} : { memoriesDigest: memories.digest },
+            // The watermark moves only on a HARD rebuild: everything written since
+            // the previous fold becomes part of the frozen m[0] pool here.
+            ...memories?.maxMemoryId === undefined ? {} : { maxMemoryId: memories.maxMemoryId },
+            // WP8: the profile freeze. The digest recorded is the FOLD digest (every
+            // active row), because this fold renders the whole profile and the next
+            // pass's pool is exactly that set — recording the pool digest here would
+            // buy a second, useless rebuild.
+            profileM0Digest: profile?.foldDigest ?? '',
+            ...profile === undefined
+                ? previous?.profileWatermark === undefined ? {} : { profileWatermark: previous.profileWatermark }
+                : { profileWatermark: profile.currentMaxId },
+            // Same rule for the mutation cursor (§7.5 step 4): folding m[0] bakes the
+            // pending updates in, so the `<memory-updates>` block disappears.
+            ...frozenCursor === undefined ? {} : { maxMemoryMutationId: frozenCursor },
+            ...frozenEpochFingerprint === undefined ? {} : { projectEpochFingerprint: frozenEpochFingerprint },
+            updatedAt: now,
+        }
+        : { ...previous, updatedAt: now };
+    const sets = hard
+        ? { baseline: compartments, delta: [] }
+        : splitBaselineSets(compartments, previous);
+    // A1 (MC inject-compartments.ts:2822-2869): collect the forced ids first,
+    // render their lines from the eligible rows, and hand both to renderBaseline.
+    const forcedRender = renderMemoryUpdates(hard ? [] : updates?.updates ?? [], {
+        ...memories?.newMemoryIds === undefined ? {} : { renderedIds: new Set(memories.newMemoryIds) },
+        ...memories?.baselineIds === undefined ? {} : { baselineIds: new Set(memories.baselineIds) },
+        ...memories?.eligibleIds === undefined ? {} : { eligibleIds: new Set(memories.eligibleIds) },
+    });
+    const forcedRowsById = new Set((memories?.eligibleRows ?? []).map(row => row.id));
+    const forcedMemoryLines = forcedRender.forcedMemoryIds
+        .filter(id => forcedRowsById.has(id))
+        .map(id => renderMemoryLine((memories?.eligibleRows ?? []).find(row => row.id === id)));
+    // WP8: a HARD fold swallows the profile delta (the whole profile becomes
+    // m[0]); a soft pass renders the pool in m[0] and the new entries in m[1].
+    const profilePoolLines = hard
+        ? [...(profile?.lines ?? []), ...(profile?.newLines ?? [])]
+        : profile?.lines ?? [];
+    const profileDeltaLines = hard ? [] : profile?.newLines ?? [];
+    const block = renderBaseline({
+        now,
+        baseline: sets.baseline,
+        delta: sets.delta,
+        memories: memories?.lines ?? [],
+        ...profilePoolLines.length === 0 ? {} : { profileLines: profilePoolLines },
+        ...profileDeltaLines.length === 0 ? {} : { newProfileLines: profileDeltaLines },
+        ...memories?.newLines === undefined ? {} : { newMemories: memories.newLines },
+        ...memories?.newMemoryIds === undefined ? {} : { newMemoryIds: memories.newMemoryIds },
+        ...memories?.baselineIds === undefined ? {} : { baselineIds: memories.baselineIds },
+        ...memories?.eligibleIds === undefined ? {} : { eligibleIds: memories.eligibleIds },
+        ...(forcedMemoryLines.length > 0 ? { forcedMemoryLines } : {}),
+        // A HARD fold swallows the delta: the changes are part of the rebuilt m[0].
+        // Otherwise the pending (post-cursor) changes render in m[1].
+        ...hard || updates === undefined ? {} : { memoryUpdates: updates.updates },
+        budgetTokens: input.policy.baselineTokens,
+    });
+    if (block.length === 0)
+        return false;
+    // The baseline rides the first ordinary user node — never a compaction
+    // checkpoint (host or engine). Attaching it to a checkpoint let that
+    // checkpoint's own text ride inside m[0] forever: every later refresh
+    // re-emitted the foreign summary and rewrote the node, and the GUI lost the
+    // card it correlates by `source.kind === 'compact-checkpoint'` + compactionId.
+    const target = nodes.find(node => node.role === 'user' && node.sourceKind !== 'compact-checkpoint');
+    if (target === undefined)
+        return false;
+    if (baselineBlockOf(target.text) === block) {
+        // Byte-identical: no durable mutation, no priced bust (MC's defer pass).
+        if (state.nodeSeq !== target.seq || state.updatedAt !== previous?.updatedAt) {
+            input.stores.saveBaselineState({
+                ...state,
+                nodeSeq: target.seq,
+                ...input.route === undefined ? {} : { provider: input.route.provider, model: input.route.model },
+                ...memories === undefined ? {} : { memoriesDigest: memories.digest },
+            });
+        }
+        return false;
+    }
+    const landedSeq = replaceSurfaceRange(input.session, target.seq, target.seq, composeBaselineContent(target, block), [target.seq], syntheticNodeId('mc-baseline'), magicContextSource(`Magic Context · baseline ${hard ? 'HARD rebuild' : 'soft refresh'} `
+        + `(m[0] ${String(sets.baseline.length)} · m[1] ${String(sets.delta.length)} · ${String(memories?.lines.length ?? 0)} memories)`));
+    input.stores.saveBaselineState({
+        ...state,
+        nodeSeq: landedSeq,
+        ...input.route === undefined ? {} : { provider: input.route.provider, model: input.route.model },
+        ...memories === undefined ? {} : { memoriesDigest: memories.digest },
+    });
+    input.journal?.info('baseline', `baseline ${hard ? 'HARD rebuild' : 'soft refresh'} (epoch ${String(state.epoch)})`, {
+        mode: hard ? 'hard' : 'soft',
+        epoch: state.epoch,
+        nodeSeq: landedSeq,
+        compartments: { baseline: sets.baseline.length, delta: sets.delta.length },
+        memories: { rows: memories?.lines.length ?? 0, digest: memories?.digest.slice(0, 12) },
+        profile: {
+            rows: profile?.lines.length ?? 0,
+            newRows: hard ? 0 : profile?.newLines.length ?? 0,
+            digest: profile?.digest.slice(0, 12),
+            watermark: state.profileWatermark,
+        },
+        memoryUpdates: {
+            pending: updates?.updates.length ?? 0,
+            rendered: hard ? 0 : updates?.updates.length ?? 0,
+            cursor: state.maxMemoryMutationId,
+            epochFingerprint: state.projectEpochFingerprint,
+        },
+        bytes: block.length,
+        estTokens: estimateTokens(block),
+        ...memoriesChanged ? { reason: 'memory-digest-changed' } : {},
+        ...profileChanged ? { reason: 'profile-digest-changed' } : {},
+        ...routeChanged ? { reason: 'route-changed' } : {},
+        ...epochChanged ? { reason: 'project-memory-epoch-changed' } : {},
+        ...cursorUpgrade ? { reason: 'mutation-cursor-upgrade' } : {},
+        ...previous === undefined ? { reason: 'first-baseline' } : {},
+    }, input.sessionId);
+    return true;
+}
+/** Upper bound of wire repairs per pass, so a pathological surface cannot monopolize the bust. */
+const WIRE_REPAIR_CAP = 16;
+/**
+ * The iron-rule repair: sweep live `tool/result` nodes whose tool_use left
+ * the wire. One of them 400s every strict-provider request — the only adapter
+ * failure mode that can take the whole conversation down — so they are
+ * replaced with a tiny user note no matter what else this pass does. The
+ * original content stays recoverable in the event log (the replacement cites
+ * it); only the wire copy goes.
+ * @returns the number of results swept this pass.
+ */
+function repairWirePairing(input) {
+    const stranded = wireStrandedResults(input.session);
+    if (stranded.length === 0)
+        return 0;
+    const sweep = stranded.slice(0, WIRE_REPAIR_CAP);
+    for (const defect of sweep) {
+        replaceSurfaceRange(input.session, defect.seq, defect.seq, [{ type: 'text', text: '[magic-context] removed a tool result whose call left the wire' }], [defect.seq], syntheticNodeId(`mc-wire-repair-${String(defect.seq)}`), magicContextSource(`Magic Context · wire repair · removed stranded tool result ${String(defect.seq)}`));
+    }
+    input.journal?.warn('wire-repair', `swept ${String(sweep.length)} stranded tool result(s) off the wire`, {
+        swept: sweep.length,
+        seqs: sweep.map(defect => defect.seq),
+        callIds: sweep.map(defect => defect.callId),
+        remaining: stranded.length - sweep.length,
+    }, input.sessionId);
+    return sweep.length;
+}
+/**
+ * Run the management pass. Every step is independently guarded: a failure in
+ * one must not wedge the turn (MC per-turn fail-open), and the next pass
+ * re-decides from durable state.
+ */
+export function runManagementPass(input) {
+    const landedDrops = [];
+    let wireRepaired = 0;
+    const tokensBefore = surfaceTokens(input.session);
+    const result = {
+        landedDrops,
+        published: [],
+        forceDropped: 0,
+        wireRepaired: 0,
+        baselineUpdated: false,
+        historianStarted: false,
+        tokensBefore,
+        tokensAfter: tokensBefore,
+        factsPromoted: 0,
+        factsSeenAgain: 0,
+    };
+    // 1. Queued ctx_reduce marks.
+    let forceToolNodes = [];
+    try {
+        // Snapshot before landing: the force band historically reclaims from the
+        // pre-landing surface (and must not start dropping the placeholders it
+        // just created). Flush has already landed before this pass, so the
+        // snapshot is naturally post-flush for that path.
+        forceToolNodes = enumerateSurfaceToolResults(input.session, callId => input.stores.getTag(input.sessionId, { kind: 'tool-result', callId }));
+        const landing = landPendingDrops({
+            session: input.session,
+            sessionId: input.sessionId,
+            stores: input.stores,
+            tags: input.stores.listPendingDrops(input.sessionId),
+            journal: input.journal,
+            // Record each replacement before the durable write. If a later tag
+            // throws, the pass result and error logs still name what the surface
+            // already lost.
+            onReplaced: tag => {
+                landedDrops.push(tag);
+            },
+        });
+        // Filter the force-band snapshot by the tags this pass touched; their old
+        // seqs are shadowed by the placeholder replacement and must not be handed
+        // to reclaimForEmergency.
+        const touched = new Set([...landing.landed, ...landing.already]);
+        forceToolNodes = forceToolNodes.filter(node => node.tagNumber === undefined || !touched.has(node.tagNumber));
+        // 1.5 Wire-pairing repair (the iron rule): sweep stranded results off the
+        // wire before anything else reads the surface.
+        wireRepaired = repairWirePairing(input);
+        // 3. Force-band reclaim (before publishing, so a compartment range that
+        //    lost its content to a drop still replaces the same nodes).
+        let forceDropped = 0;
+        if (input.pressureStale === true && input.pressure !== undefined && input.pressure >= input.policy.forceThreshold) {
+            // The reading says "over the force band" but it was recorded before the
+            // surface changed: reclaiming again would drop against a prompt that no
+            // longer exists (upstream MC v0.49.49's half of issue 828). Reclaim is
+            // irreversible, so it waits for a reading that describes the current wire.
+            input.journal?.info('emergency-reclaim', `force band: skipped — the ${input.pressure.toFixed(1)}% reading predates a surface change; no reclaim against a stale measurement`, {
+                dropped: 0,
+                reason: 'stale-reading',
+                tier: 'skipped-stale-reading',
+                pressure: input.pressure,
+            }, input.sessionId);
+        }
+        else if (input.pressure !== undefined && input.pressure >= input.policy.forceThreshold) {
+            const generationBefore = input.session.surface.replaceGeneration;
+            // #731: pass the whole-surface estimate so the drop lane can refuse a
+            // reclaim that cannot fit the request even at zero tool results. The
+            // node snapshot is the pre-landing one from step 1, preserving the
+            // historical force-band set.
+            const reclaim = reclaimForEmergency(input.session, forceToolNodes, input.policy, input.contextWindow, surfaceTokens(input.session));
+            forceDropped = reclaim.dropped.length;
+            if (forceDropped > 0) {
+                input.journal?.warn('emergency-reclaim', `force band: dropped ${String(forceDropped)} tool output(s) beyond the protected window`, {
+                    dropped: forceDropped,
+                    protected: reclaim.protectedCount,
+                    reason: 'force-threshold',
+                    pressure: input.pressure,
+                    generationBefore,
+                    generationAfter: input.session.surface.replaceGeneration,
+                }, input.sessionId);
+            }
+            else if (reclaim.skipped === 'cannot-fit') {
+                input.journal?.warn('emergency-reclaim', `force band: reclaim skipped — dropping every reclaimable output still leaves ~${String(reclaim.residualTokens)} tokens against a ${String(input.contextWindow)}-token window (#731)`, {
+                    dropped: 0,
+                    protected: reclaim.protectedCount,
+                    reason: 'force-threshold',
+                    pressure: input.pressure,
+                    skipped: reclaim.skipped,
+                    residualTokens: reclaim.residualTokens,
+                    contextWindow: input.contextWindow,
+                    generationBefore,
+                    generationAfter: input.session.surface.replaceGeneration,
+                }, input.sessionId);
+            }
+        }
+        // 2 + 4: publish compartments, then refresh the baseline over the result.
+        const nodes = enumerateSurfaceNodes(input.session);
+        const { ids: published, factsPromoted, factsSeenAgain } = publishCompartments(input);
+        const afterPublish = published.length === 0 ? nodes : enumerateSurfaceNodes(input.session);
+        const baselineUpdated = refreshBaseline(input, afterPublish);
+        // 5. Fire the historian out of band; it only writes a store row.
+        let historianStarted = false;
+        if (input.historian !== undefined) {
+            const deps = {
+                stores: input.stores,
+                policy: input.policy,
+                llm: input.historian.llm,
+                logger: input.logger,
+                ...input.journal === undefined ? {} : { journal: input.journal },
+                ...input.historian.route === undefined ? {} : { route: input.historian.route },
+                ...input.historian.now === undefined ? {} : { now: input.historian.now },
+                ...input.profileCollect === undefined ? {} : { profileCollect: input.profileCollect },
+            };
+            void runHistorian(deps, {
+                sessionId: input.sessionId,
+                session: input.session,
+                nodes: enumerateSurfaceNodes(input.session),
+                ...input.stores.baselineState(input.sessionId)?.nodeSeq === undefined
+                    ? {}
+                    : { baselineNodeSeq: input.stores.baselineState(input.sessionId)?.nodeSeq },
+                ...input.contextWindow === undefined ? {} : { contextWindow: input.contextWindow },
+                ...input.route === undefined ? {} : { route: input.route },
+            }).catch((error) => {
+                const why = errText(error);
+                input.logger.warn(`magic-context historian failed (continuing): ${why}`);
+                // runHistorian journals its own terminal events; this row fires only
+                // if the promise itself rejects — a bug in the guard plumbing. Better
+                // a phase-less error row than a silent failure.
+                input.journal?.error('error', `historian promise rejected: ${why}`, {
+                    scope: 'historian-unhandled',
+                    detail: why,
+                    errorName: error instanceof Error ? error.name : typeof error,
+                }, input.sessionId);
+            });
+            historianStarted = true;
+        }
+        input.logger.info(`magic-context: execute pass (${input.pass.reason}) pressure=${input.pressure?.toFixed(1) ?? '?'}% `
+            + `landed=[${landedDrops.map(tag => `§${String(tag)}§`).join(', ')}] `
+            + `published=[${published.map(id => `§C${String(id)}§`).join(', ')}] `
+            + `forceDropped=${String(forceDropped)} baseline=${baselineUpdated ? 'refreshed' : 'unchanged'} `
+            + `tokens ${String(tokensBefore)}→${String(surfaceTokens(input.session))}`);
+        return {
+            ...result,
+            published,
+            forceDropped,
+            wireRepaired,
+            baselineUpdated,
+            historianStarted,
+            tokensAfter: surfaceTokens(input.session),
+            factsPromoted,
+            factsSeenAgain,
+        };
+    }
+    catch (error) {
+        // A failed management pass must never wedge the turn: log and continue
+        // with the tagged messages (MC per-turn fail-open). The journal row is
+        // what makes the failure diagnosable — the logger line alone is why a
+        // run of silent failures could survive unnoticed (test-design audit P1-3).
+        const why = errText(error);
+        input.logger.warn(`magic-context: management pass failed (continuing): ${why}`);
+        input.journal?.error('error', `management pass failed: ${why}`, {
+            scope: 'management-pass',
+            detail: why,
+            errorName: error instanceof Error ? error.name : typeof error,
+            pressure: input.pressure,
+            trigger: input.pass.reason,
+        }, input.sessionId);
+        return result;
+    }
+}