mixdog 0.8.0 → 0.9.0

package/src/runtime/agent/orchestrator/session/compact.mjs

@@ -7,11 +7,27 @@ import {
 } from './context-utils.mjs';
 
 export const SUMMARY_PREFIX = 'A previous model worked on this task and produced the compacted handoff summary below. Build on the work already done and avoid duplicating it; treat the summary as authoritative context for continuing the task. You also retain the preserved recent turns that follow.';
-export const DEFAULT_COMPACTION_BUFFER_TOKENS = 20_000;
-export const DEFAULT_COMPACTION_BUFFER_RATIO = 0.10;
+// Default auto-compact trigger sits below the effective compact boundary by a
+// compaction buffer (10% of boundary, capped at MAX_COMPACTION_BUFFER_RATIO).
+// That headroom lets semantic compact run before the transcript is already at the
+// hard limit (zero buffer caused overflow_failed with no room to summarize).
+// Operators may still set compaction.bufferTokens / bufferPercent / bufferRatio,
+// to tune headroom. Telemetry-persisted bufferTokens/bufferRatio of zero is not
+// operator config; loop/manager strip it and reapply this default (see
+// compactBufferConfigForBoundary).
+export const DEFAULT_COMPACTION_BUFFER_TOKENS = 0;
+export const DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
 export const MAX_COMPACTION_BUFFER_RATIO = 0.25;
 export const DEFAULT_COMPACTION_KEEP_TOKENS = 8_000;
 export const SUMMARY_OUTPUT_TOKENS = 4_096;
+// Minimum room the generated summary needs after the mandatory (system +
+// preserved tail) cost is accounted for. When the configured target budget is
+// smaller than the mandatory cost (e.g. the preserved recent turn carries a
+// large tool result), the compaction MUST still proceed: the old head is the
+// part being summarized away, so dropping it already shrinks the transcript.
+// Refusing with "exceeds budget" here is what surfaced as auto-clear / overflow
+// compact failures. Floor the working budget to mandatory + this room instead.
+export const COMPACT_SUMMARY_MIN_ROOM_TOKENS = 4_000;
 
 const TOOL_CALL_ARGS_MAX_CHARS = 260;
 const TOOL_CALL_FACT_ARGS_MAX_CHARS = 140;
@@ -20,6 +36,50 @@ const TOOL_ARG_STRING_MAX_CHARS = 360;
 const TOOL_ARG_ARRAY_MAX_ITEMS = 8;
 const TOOL_ARG_MAX_DEPTH = 4;
 const SENSITIVE_TOOL_ARG_KEY_RE = /(?:^|[_-])(?:api[_-]?key|authorization|auth|cookie|credential|passwd|password|refresh[_-]?token|secret|token)(?:$|[_-])/i;
+// Word alternation for raw-string (non-JSON) secret redaction. Mirrors the
+// keys in SENSITIVE_TOOL_ARG_KEY_RE and the session-ingest redactor so a raw
+// tool-call argument string like `authorization: Bearer abc.def` or
+// `password="abc def"` never reaches preserved facts or the compaction prompt.
+const SENSITIVE_TOOL_ARG_KEY_WORD = '(?:api[_-]?key|authorization|auth|cookie|credential|passwd|password|refresh[_-]?token|secret|token)';
+// Full key matcher: the sensitive WORD may carry a prefix and/or suffix segment
+// joined by `_`/`-` so prefixed variants like `access_token`, `access-token`,
+// `x-api-key`, and `bearer_token` are matched as whole keys (not just the bare
+// word at key start). Prefix/suffix are bounded by a `_`/`-` separator so the
+// word stays at an identifier boundary.
+const SENSITIVE_TOOL_ARG_KEY_FULL = `(?:[A-Za-z0-9_-]*[_-])?${SENSITIVE_TOOL_ARG_KEY_WORD}(?:[_-][A-Za-z0-9_-]*)?`;
+
+// Redact `key: value` / `key=value` secret pairs inside a raw (non-JSON)
+// string. Consumes the WHOLE value after the key — spaces, `Bearer `/`Basic `
+// scheme words, quoted values with internal spaces, and `;`-separated cookie
+// pairs — so no secret fragment survives. Kept local to compact-core to avoid a
+// cross-module dependency on the memory lib; logic matches session-ingest's
+// redactRawArgString.
+function redactRawSecretString(text) {
+    const value = String(text ?? '');
+    if (!value) return value;
+    const keyRe = new RegExp(`((?:^|[\\s,{(])["']?${SENSITIVE_TOOL_ARG_KEY_FULL}["']?\\s*[:=]\\s*)`, 'gi');
+    let out = '';
+    let last = 0;
+    let match;
+    while ((match = keyRe.exec(value)) !== null) {
+        const prefixEnd = match.index + match[0].length;
+        out += value.slice(last, prefixEnd);
+        let i = prefixEnd;
+        const quote = value[i] === '"' || value[i] === "'" ? value[i] : '';
+        if (quote) {
+            i += 1;
+            while (i < value.length && value[i] !== quote) i += 1;
+            if (i < value.length) i += 1; // include closing quote
+        } else {
+            while (i < value.length && !/[,)}\n]/.test(value[i])) i += 1;
+        }
+        out += '[redacted]';
+        last = i;
+        keyRe.lastIndex = i;
+    }
+    out += value.slice(last);
+    return out;
+}
 
 function sha16(value) {
     const text = typeof value === 'string' ? value : JSON.stringify(value ?? null);
@@ -62,7 +122,10 @@ function truncateMiddle(text, maxChars) {
 function normalizeToolArgValue(value, key = '', depth = 0) {
     if (SENSITIVE_TOOL_ARG_KEY_RE.test(String(key || ''))) return '[redacted]';
     if (typeof value === 'bigint') return String(value);
-    if (typeof value === 'string') return truncateMiddle(value, TOOL_ARG_STRING_MAX_CHARS);
+    // Defense-in-depth: a non-sensitive KEY can still carry a secret embedded
+    // in its string VALUE (e.g. a freeform `headers` string). Redact raw
+    // key:value secret pairs before truncating.
+    if (typeof value === 'string') return truncateMiddle(redactRawSecretString(value), TOOL_ARG_STRING_MAX_CHARS);
     if (!value || typeof value !== 'object') return value ?? null;
     if (depth >= TOOL_ARG_MAX_DEPTH) return Array.isArray(value) ? `[array:${value.length}]` : '[object]';
     if (Array.isArray(value)) {
@@ -86,12 +149,15 @@ function stableToolArgJson(value) {
         if (/^[\[{]/.test(text)) {
             try { return JSON.stringify(normalizeToolArgValue(JSON.parse(text))); } catch { /* keep raw */ }
         }
-        return truncateMiddle(text, TOOL_ARG_STRING_MAX_CHARS);
+        // Non-JSON raw string: redact secret key:value pairs before truncating
+        // so toolCallSummary / preserved facts / compaction prompt metadata
+        // never leak `authorization: Bearer ...`, passwords, cookies, tokens.
+        return truncateMiddle(redactRawSecretString(text), TOOL_ARG_STRING_MAX_CHARS);
     }
     try {
         return JSON.stringify(normalizeToolArgValue(value));
     } catch {
-        return truncateMiddle(String(value || ''), TOOL_ARG_STRING_MAX_CHARS);
+        return truncateMiddle(redactRawSecretString(String(value || '')), TOOL_ARG_STRING_MAX_CHARS);
     }
 }
 
@@ -127,15 +193,6 @@ function toolResultId(m) {
     return m?.role === 'tool' && m.toolCallId ? ` tool_result=${m.toolCallId}` : '';
 }
 
-function lineForMessage(m, index, perMessageChars) {
-    const role = m?.role || 'unknown';
-    const text = truncateMiddle(extractText(m).trim(), perMessageChars);
-    const meta = `${toolCallSummary(m, toolCallArgBudget(perMessageChars))}${toolResultId(m)}`;
-    return text
-        ? `${index + 1}. ${role}${meta}: ${text}`
-        : `${index + 1}. ${role}${meta}`;
-}
-
 function compactHeader(oldHistory) {
     const encoded = JSON.stringify(oldHistory ?? []);
     return [
@@ -144,64 +201,168 @@ function compactHeader(oldHistory) {
     ];
 }
 
-function buildSummaryContent(oldHistory, perMessageChars, factsText = '') {
-    const lines = compactHeader(oldHistory);
-    if (factsText) {
-        lines.push('', factsText);
-    }
-    if (oldHistory.length > 0) {
-        lines.push('timeline:');
-        for (let i = 0; i < oldHistory.length; i += 1) {
-            lines.push(lineForMessage(oldHistory[i], i, perMessageChars));
-        }
-    }
-    return lines.join('\n');
-}
-
 function makeSummaryMessage(content) {
     return { role: 'user', content };
 }
 
-function fitSummaryMessage(oldHistory, remainingTokens) {
-    const factsText = extractPreservedFacts(oldHistory);
-    const tryFit = (withFacts) => {
-        const ft = withFacts ? factsText : '';
-        const minimalText = ft
-            ? `${compactHeader(oldHistory).join('\n')}\n\n${ft}`
-            : compactHeader(oldHistory).join('\n');
-        const minimal = makeSummaryMessage(minimalText);
-        if (estimateMessagesTokens([minimal]) > remainingTokens) return null;
+// A compact summary message is a synthetic role:'user' message carrying the
+// SUMMARY_PREFIX anchor. It is NOT a real user turn: it must be excluded from
+// real user-turn boundary calculations and treated as merge input, otherwise
+// an old summary can sit in the preserved tail as a live user message,
+// duplicate, or fail to merge across repeated compaction.
+function isSummaryMessage(m) {
+    return m?.role === 'user'
+        && typeof m.content === 'string'
+        && m.content.startsWith(SUMMARY_PREFIX);
+}
 
-        let maxText = 0;
-        for (const m of oldHistory) maxText = Math.max(maxText, extractText(m).length);
+function isProtectedContextUserMessage(m) {
+    if (m?.role !== 'user' || typeof m.content !== 'string') return false;
+    return m.content.trimStart().startsWith('<system-reminder>');
+}
 
-        let lo = 0;
-        let hi = Math.max(maxText, 0);
-        let best = minimal;
-        while (lo <= hi) {
-            const mid = Math.floor((lo + hi) / 2);
-            const candidate = makeSummaryMessage(buildSummaryContent(oldHistory, mid, ft));
-            if (estimateMessagesTokens([candidate]) <= remainingTokens) {
-                best = candidate;
-                lo = mid + 1;
-            } else {
-                hi = mid - 1;
-            }
+function isProtectedContextAckMessage(m) {
+    return m?.role === 'assistant'
+        && typeof m.content === 'string'
+        && m.content.trim() === '.'
+        && !Array.isArray(m.toolCalls);
+}
+
+function splitProtectedContext(messages) {
+    const protectedPrefix = [];
+    const conversation = [];
+    let prefixMode = true;
+    let previousWasProtectedContext = false;
+    for (const m of messages || []) {
+        if (m?.role === 'system') {
+            protectedPrefix.push(m);
+            previousWasProtectedContext = false;
+            continue;
         }
-        return best;
-    };
-    if (factsText) {
-        const withFacts = tryFit(true);
-        if (withFacts) return withFacts;
+        if (prefixMode && isProtectedContextUserMessage(m)) {
+            protectedPrefix.push(m);
+            previousWasProtectedContext = true;
+            continue;
+        }
+        if (prefixMode && previousWasProtectedContext && isProtectedContextAckMessage(m)) {
+            protectedPrefix.push(m);
+            previousWasProtectedContext = false;
+            continue;
+        }
+        prefixMode = false;
+        previousWasProtectedContext = false;
+        conversation.push(m);
     }
-    return tryFit(false);
+    return { protectedPrefix, conversation };
 }
 
-function currentTurnStart(nonSystem) {
-    for (let i = nonSystem.length - 1; i >= 0; i -= 1) {
-        if (nonSystem[i]?.role === 'user') return i;
+// Redaction-ONLY recursive walk for tool-call argument VALUES kept verbatim
+// through compaction. Unlike normalizeToolArgValue (which is for prompt-side
+// summaries and truncates/summarizes/key-sorts), this preserves shape exactly:
+//   - sensitive KEY  -> '[redacted]'
+//   - string value   -> redactRawSecretString(value)  (no truncation/middle-cut)
+//   - array          -> same length, items walked in order (no slicing/caps)
+//   - object         -> same keys in INSERTION order (no sorting/depth caps)
+//   - other primitive (number/boolean/bigint/null) -> returned unchanged
+// Returns { value, changed } so callers can preserve byte-exact input when the
+// walk altered nothing. Only sensitive-key values and embedded raw secret pairs
+// inside strings are altered; everything else is structure identical.
+function redactToolArgValueOnly(value, key = '') {
+    if (SENSITIVE_TOOL_ARG_KEY_RE.test(String(key || ''))) {
+        return { value: '[redacted]', changed: value !== '[redacted]' };
+    }
+    if (value == null) return { value, changed: false };
+    if (typeof value === 'string') {
+        const redacted = redactRawSecretString(value);
+        return { value: redacted, changed: redacted !== value };
+    }
+    if (Array.isArray(value)) {
+        let changed = false;
+        const out = value.map((item) => {
+            const r = redactToolArgValueOnly(item, '');
+            if (r.changed) changed = true;
+            return r.value;
+        });
+        return { value: changed ? out : value, changed };
+    }
+    if (typeof value === 'object') {
+        let changed = false;
+        const out = {};
+        for (const k of Object.keys(value)) {
+            const r = redactToolArgValueOnly(value[k], k);
+            if (r.changed) changed = true;
+            out[k] = r.value;
+        }
+        return { value: changed ? out : value, changed };
+    }
+    return { value, changed: false };
+}
+
+// Redact sensitive values inside a single tool-call arguments payload while
+// preserving its original shape (string stays a string, object stays an
+// object) so the provider-valid tool_call structure is not broken. Used to
+// scrub messages that survive compaction VERBATIM (preserved tail / mandatory
+// context), where prompt-side redaction does not apply. Redaction-only — no
+// truncation, summarization, key sorting, or depth/array caps.
+function redactToolCallArgumentsValue(rawArgs) {
+    if (rawArgs == null) return rawArgs;
+    if (typeof rawArgs === 'string') {
+        const trimmed = rawArgs.trim();
+        if (/^[\[{]/.test(trimmed)) {
+            try {
+                // Parse, redaction-only walk; only reserialize when the walk
+                // actually changed a sensitive value. When nothing changed,
+                // return the ORIGINAL string byte-exact (no JSON re-formatting).
+                const { value, changed } = redactToolArgValueOnly(JSON.parse(trimmed));
+                return changed ? JSON.stringify(value) : rawArgs;
+            } catch { /* fall through to raw redaction */ }
+        }
+        return redactRawSecretString(rawArgs);
+    }
+    if (typeof rawArgs === 'object') {
+        try {
+            const { value, changed } = redactToolArgValueOnly(rawArgs);
+            return changed ? value : rawArgs;
+        } catch { return rawArgs; }
+    }
+    return rawArgs;
+}
+
+// Return a copy of a message with sensitive tool-call argument values redacted,
+// keeping role / content / toolCallId / tool names+ids and non-sensitive args
+// intact. Non-tool-bearing messages are returned unchanged (same reference).
+function redactMessageToolCallSecrets(m) {
+    if (!m || typeof m !== 'object' || !Array.isArray(m.toolCalls) || m.toolCalls.length === 0) {
+        return m;
     }
-    return -1;
+    let changed = false;
+    const toolCalls = m.toolCalls.map((tc) => {
+        if (!tc || typeof tc !== 'object') return tc;
+        const out = { ...tc };
+        if ('arguments' in tc && tc.arguments != null) {
+            const redacted = redactToolCallArgumentsValue(tc.arguments);
+            if (redacted !== tc.arguments) { out.arguments = redacted; changed = true; }
+        }
+        if (tc.function && typeof tc.function === 'object' && tc.function.arguments != null) {
+            const redacted = redactToolCallArgumentsValue(tc.function.arguments);
+            if (redacted !== tc.function.arguments) {
+                out.function = { ...tc.function, arguments: redacted };
+                changed = true;
+            }
+        }
+        return out;
+    });
+    if (!changed) return m;
+    return { ...m, toolCalls };
+}
+
+// Scrub an array of messages that are kept verbatim through compaction so a
+// recent assistant tool call carrying a secret (e.g. `authorization: Bearer
+// ...`) cannot survive into the returned compacted transcript. Only assistant
+// toolCalls argument VALUES are touched; structure/order/pairing is preserved.
+export function redactToolCallSecretsInMessages(messages) {
+    if (!Array.isArray(messages)) return messages;
+    return messages.map((m) => redactMessageToolCallSecrets(m));
 }
 
 export function normalizeCompactionBufferRatio(value, fallback = DEFAULT_COMPACTION_BUFFER_RATIO) {
@@ -222,7 +383,7 @@ export function compactionBufferTokensForBoundary(boundaryTokens, opts = {}) {
 }
 
 function effectiveBudget(budgetTokens, opts) {
-    if (!(budgetTokens > 0)) throw new Error('compactMessages: budgetTokens must be > 0');
+    if (!(budgetTokens > 0)) throw new Error('compact: budgetTokens must be > 0');
     const reserve = Number(opts?.reserveTokens) || 0;
     if (reserve <= 0) return budgetTokens;
     const effectiveReserve = Math.min(reserve, Math.floor(budgetTokens * 0.5));
@@ -239,6 +400,99 @@ const COMPACTION_INPUT_MAX_CHARS = 2_000;
 const COMPACTION_PROMPT_HEADROOM = 0.85;
 const PRESERVED_FACTS_MAX_CHARS = 600;
 
+export const COMPACT_TYPE_SEMANTIC = 'semantic';
+export const COMPACT_TYPE_RECALL_FASTTRACK = 'recall-fasttrack';
+export const DEFAULT_COMPACT_TYPE = COMPACT_TYPE_SEMANTIC;
+export const COMPACT_TYPES = Object.freeze([
+    COMPACT_TYPE_SEMANTIC,
+    COMPACT_TYPE_RECALL_FASTTRACK,
+]);
+
+export function normalizeCompactType(value, fallback = DEFAULT_COMPACT_TYPE) {
+    const raw = String(value ?? '').trim().toLowerCase().replace(/_/g, '-');
+    if (!raw) return fallback;
+    if (raw === '1' || raw === 'type1' || raw === 'type-1' || raw === 'bench1' || raw === 'bench-1' || raw === 'semantic' || raw === 'summary') {
+        return COMPACT_TYPE_SEMANTIC;
+    }
+    // Recall fast-track aliases. `replace(/_/g,'-')` above already folds
+    // snake_case (fast_track -> fast-track), but list both dash/no-dash forms
+    // explicitly so callers passing either spelling resolve deterministically.
+    if (raw === '2' || raw === 'type2' || raw === 'type-2' || raw === 'recall' || raw === 'recall-fast' || raw === 'recall-fasttrack' || raw === 'recall-fast-track' || raw === 'fasttrack' || raw === 'fast-track') {
+        return COMPACT_TYPE_RECALL_FASTTRACK;
+    }
+    // Unknown / unrecognized value: fall back to the caller-provided default
+    // (semantic by default). Callers that need to detect an unknown value
+    // should compare the input against COMPACT_TYPES before normalizing.
+    return fallback;
+}
+
+export function compactTypeIsSemantic(value) {
+    return normalizeCompactType(value) === COMPACT_TYPE_SEMANTIC;
+}
+
+export function compactTypeIsRecallFastTrack(value) {
+    return normalizeCompactType(value) === COMPACT_TYPE_RECALL_FASTTRACK;
+}
+
+// Count raw (unchunked) pending rows still present in a dump_session_roots
+// payload. recall-fasttrack must keep cycle1-chunking until this reaches 0 so
+// the injected root is the chunked summary, not the raw transcript tail.
+export function countRawPendingRows(dumpText) {
+    const text = String(dumpText || '');
+    const matches = text.match(/(?:^|\n)# raw_pending\s+\d+\s+id=/gi);
+    return matches ? matches.length : 0;
+}
+
+// Drain a single session's cycle1 in fixed window×concurrency units, looping
+// until no raw rows remain (or a pass stops making progress / the deadline
+// elapses). This replaces the previous single-pass cycle1 so large sessions
+// get fully chunked before their root is injected into the compacted context.
+export async function drainSessionCycle1(runTool, { sessionId, cycleArgs = {}, dumpArgs, maxPasses = 0, deadlineMs = 0 } = {}) {
+    if (typeof runTool !== 'function') throw new Error('drainSessionCycle1: runTool is required');
+    if (!sessionId) throw new Error('drainSessionCycle1: sessionId is required');
+    if (!dumpArgs) throw new Error('drainSessionCycle1: dumpArgs is required');
+    const startedAt = Date.now();
+    const hardPasses = Math.max(1, Number(maxPasses) || 50);
+    const lines = [];
+    let recallText = await runTool('memory', dumpArgs);
+    let rawRemaining = countRawPendingRows(recallText);
+    let pass = 0;
+    while (rawRemaining > 0 && pass < hardPasses) {
+        if (deadlineMs > 0 && (Date.now() - startedAt) >= deadlineMs) break;
+        pass += 1;
+        const passDeadline = deadlineMs > 0
+            ? Math.max(1, deadlineMs - (Date.now() - startedAt))
+            : 0;
+        let passText = '';
+        try {
+            passText = await runTool('memory', {
+                action: 'cycle1',
+                sessionId,
+                ...cycleArgs,
+                ...(passDeadline > 0 ? { _callerDeadlineMs: passDeadline } : {}),
+            });
+        } catch (err) {
+            lines.push(`cycle1 pass=${pass} error=${err?.message || err}`);
+            break;
+        }
+        if (passText) lines.push(`cycle1 pass=${pass}: ${String(passText).trim()}`);
+        recallText = await runTool('memory', dumpArgs);
+        const nextRaw = countRawPendingRows(recallText);
+        // No forward progress (raw not shrinking) — stop instead of spinning.
+        if (nextRaw >= rawRemaining) {
+            rawRemaining = nextRaw;
+            break;
+        }
+        rawRemaining = nextRaw;
+    }
+    return {
+        recallText,
+        cycle1Text: lines.join('\n'),
+        passes: pass,
+        rawRemaining,
+    };
+}
+
 function preservedFactHints() {
     return String(process.env.MIXDOG_COMPACT_FACT_HINTS || '')
         .split(/[\n,;]+/u)
@@ -449,43 +703,113 @@ function userIndexes(messages) {
     return out;
 }
 
-function selectCompactionWindow(messages, budget, opts = {}) {
+function indexLiveTurns(live) {
+    const turns = splitTailIntoTurns(live);
+    const indexed = [];
+    let scan = 0;
+    for (const messages of turns) {
+        while (scan < live.length && live[scan] !== messages[0]) scan += 1;
+        const start = scan;
+        const end = start + messages.length;
+        indexed.push({ start, end, messages });
+        scan = end;
+    }
+    return indexed;
+}
+
+function splitTurnStartIndexForBudget(turn, budget) {
+    const { start, end, messages } = turn;
+    for (let i = 0; i < messages.length; i += 1) {
+        const suffixStart = start + i;
+        const suffix = messages.slice(i);
+        if (suffix.length > 0 && estimateMessagesTokens(suffix) <= budget) {
+            return suffixStart;
+        }
+    }
+    return end;
+}
+
+function splitLiveCompactionContext(messages) {
     const sanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
-    const system = sanitized.filter(m => m?.role === 'system');
-    const nonSystem = sanitized.filter(m => m?.role !== 'system');
-    const users = userIndexes(nonSystem);
-    if (!users.length) throw new Error('semanticCompactMessages: no user turn to preserve');
+    const { protectedPrefix, conversation: nonSystem } = splitProtectedContext(sanitized);
+    let previousSummary = null;
+    for (let i = nonSystem.length - 1; i >= 0; i -= 1) {
+        if (isSummaryMessage(nonSystem[i])) {
+            previousSummary = nonSystem[i].content;
+            break;
+        }
+    }
+    const live = nonSystem.filter((m) => !isSummaryMessage(m));
+    return { system: protectedPrefix, live, previousSummary, sanitized };
+}
+
+function selectCompactionWindow(messages, budget, opts = {}) {
+    const { system, live, previousSummary } = splitLiveCompactionContext(messages);
+    if (!userIndexes(live).length) throw new Error('semanticCompactMessages: no user turn to preserve');
 
     const tailTurns = Math.max(1, Number(opts.tailTurns) || DEFAULT_TAIL_TURNS);
     const recentBudget = preserveRecentBudget(budget, opts);
-    let tailStart = users[users.length - 1];
-    for (let u = users.length - 2, kept = 1; u >= 0 && kept < tailTurns; u -= 1) {
-        const candidateStart = users[u];
-        const candidateTail = nonSystem.slice(candidateStart);
-        if (estimateMessagesTokens(candidateTail) > recentBudget) break;
-        tailStart = candidateStart;
-        kept += 1;
+    const indexedTurns = indexLiveTurns(live);
+    if (indexedTurns.length === 0) throw new Error('semanticCompactMessages: no user turn to preserve');
+
+    let tailStartIdx = live.length;
+    let keptTurns = 0;
+
+    for (let t = indexedTurns.length - 1; t >= 0; t -= 1) {
+        if (keptTurns >= tailTurns) break;
+        const turn = indexedTurns[t];
+        const tailFromTurn = live.slice(turn.start);
+        if (keptTurns === 0) {
+            if (estimateMessagesTokens(tailFromTurn) <= recentBudget) {
+                tailStartIdx = turn.start;
+                keptTurns += 1;
+                continue;
+            }
+            const splitIdx = splitTurnStartIndexForBudget(turn, recentBudget);
+            if (splitIdx < turn.end) {
+                tailStartIdx = splitIdx;
+                keptTurns += 1;
+                break;
+            }
+            // Newest turn has no fitting suffix: keep entire live transcript in head for summarization.
+            tailStartIdx = live.length;
+            keptTurns = 0;
+            break;
+        }
+        const candidateStart = turn.start;
+        const candidateTail = live.slice(candidateStart);
+        if (estimateMessagesTokens(candidateTail) <= recentBudget) {
+            tailStartIdx = candidateStart;
+            keptTurns += 1;
+            continue;
+        }
+        break;
     }
 
-    const head = nonSystem.slice(0, tailStart);
-    const tail = nonSystem.slice(tailStart);
-    let previousSummary = null;
-    let headStart = 0;
-    for (let i = head.length - 1; i >= 0; i -= 1) {
-        const m = head[i];
-        if (m?.role === 'user' && typeof m.content === 'string' && m.content.startsWith(SUMMARY_PREFIX)) {
-            previousSummary = m.content;
-            headStart = i + 1;
-            break;
+    const head = live.slice(0, tailStartIdx);
+    let tail = live.slice(tailStartIdx);
+    tail = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(tail)));
+
+    if (!head.length && !tail.length) {
+        throw new Error('semanticCompactMessages: no user turn to preserve');
+    }
+    if (tail.length && !tail.some((m) => m?.role === 'user')) {
+        const lastUserIdx = live.findLastIndex
+            ? live.findLastIndex((m) => m?.role === 'user')
+            : (() => { for (let i = live.length - 1; i >= 0; i -= 1) { if (live[i]?.role === 'user') return i; } return -1; })();
+        if (lastUserIdx < 0 || lastUserIdx >= tailStartIdx) {
+            throw new Error('semanticCompactMessages: no user turn to preserve');
         }
     }
-    const preservedFacts = extractPreservedFacts(head.slice(headStart));
+
+    const preservedFacts = extractPreservedFacts(head);
+    const originalHead = head;
     return {
         system,
-        head: head.slice(headStart),
+        head,
         tail,
         previousSummary,
-        originalHead: head,
+        originalHead,
         preservedFacts,
     };
 }
@@ -523,29 +847,114 @@ function buildCompactionPrompt({ head, previousSummary, preservedFacts }, perMes
     return lines.join('\n');
 }
 
+function estimateCompactionPromptTokens(input, perMessageChars) {
+    const prompt = buildCompactionPrompt(input, perMessageChars);
+    return estimateMessagesTokens([
+        { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
+        { role: 'user', content: prompt },
+    ]);
+}
+
+function previousSummaryBodyForCompactionPrompt(previousSummary) {
+    const text = String(previousSummary || '').trim();
+    if (!text) return '';
+    return stripNestedSummaryHeaderLines(text);
+}
+
+function priorSummaryNeedsNormalization(text) {
+    const body = String(text || '').trim();
+    if (!body) return false;
+    if (!/^##\s+/m.test(body)) return true;
+    if (!summaryIsSchemaValid(body)) return true;
+    return summaryHasUnrecognizedHeadings(body);
+}
+
+function normalizePriorSummaryForCompactionPrompt(fullBody) {
+    const text = String(fullBody || '').trim();
+    if (!text) return '';
+    if (!priorSummaryNeedsNormalization(text)) return text;
+    return repairSemanticSummary(text, { head: [], tail: [] });
+}
+
+// Shrink or drop a prior anchored summary so the compaction provider prompt fits
+// the call budget. Unstructured/legacy priors are repaired first; section
+// anchors are preserved via truncateSummaryBySections;
+// the last resort is omitting <previous-summary> entirely.
+function fitPreviousSummaryForCompactionPrompt(input, perMessageChars, targetTokens) {
+    if (!input?.previousSummary) return input;
+    const fullBody = normalizePriorSummaryForCompactionPrompt(
+        previousSummaryBodyForCompactionPrompt(input.previousSummary),
+    );
+    const withSummary = (summaryText) => {
+        const trimmed = String(summaryText || '').trim();
+        if (!trimmed) return { ...input, previousSummary: null };
+        return { ...input, previousSummary: trimmed };
+    };
+
+    if (estimateCompactionPromptTokens(withSummary(fullBody), perMessageChars) <= targetTokens) {
+        return withSummary(fullBody);
+    }
+
+    if (fullBody) {
+        let lo = 0;
+        let hi = fullBody.length;
+        let bestChars = -1;
+        while (lo <= hi) {
+            const mid = Math.floor((lo + hi) / 2);
+            const truncated = truncateSummaryBySections(fullBody, mid);
+            const candidate = withSummary(truncated);
+            if (estimateCompactionPromptTokens(candidate, perMessageChars) <= targetTokens) {
+                bestChars = mid;
+                lo = mid + 1;
+            } else {
+                hi = mid - 1;
+            }
+        }
+        if (bestChars >= 0) {
+            return withSummary(truncateSummaryBySections(fullBody, bestChars));
+        }
+    }
+
+    const minimalPrior = minimalSchemaSummary();
+    if (estimateCompactionPromptTokens(withSummary(minimalPrior), perMessageChars) <= targetTokens) {
+        return withSummary(minimalPrior);
+    }
+
+    const withoutPrior = withSummary(null);
+    if (estimateCompactionPromptTokens(withoutPrior, perMessageChars) <= targetTokens) {
+        return withoutPrior;
+    }
+
+    return null;
+}
+
 function fitCompactionPrompt(input, targetTokens) {
     const tryFit = (withFacts) => {
-        const inp = withFacts ? input : { ...input, preservedFacts: null };
-        const minimal = buildCompactionPrompt(inp, 0);
-        const baseMessages = [
-            { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
-            { role: 'user', content: minimal },
-        ];
-        if (estimateMessagesTokens(baseMessages) > targetTokens) return null;
+        const baseInp = withFacts ? input : { ...input, preservedFacts: null };
+
+        const fitAt = (perMessageChars) => {
+            let inp = baseInp;
+            if (estimateCompactionPromptTokens(inp, perMessageChars) > targetTokens) {
+                const fitted = fitPreviousSummaryForCompactionPrompt(inp, perMessageChars, targetTokens);
+                if (!fitted) return null;
+                inp = fitted;
+                if (estimateCompactionPromptTokens(inp, perMessageChars) > targetTokens) return null;
+            }
+            return buildCompactionPrompt(inp, perMessageChars);
+        };
+
+        const minimalPrompt = fitAt(0);
+        if (!minimalPrompt) return null;
 
         let maxText = 0;
-        for (const m of input.head) maxText = Math.max(maxText, extractText(m).length);
+        for (const m of baseInp.head) maxText = Math.max(maxText, extractText(m).length);
         let lo = 0;
         let hi = Math.min(COMPACTION_INPUT_MAX_CHARS, Math.max(maxText, 0));
-        let best = minimal;
+        let best = minimalPrompt;
         while (lo <= hi) {
             const mid = Math.floor((lo + hi) / 2);
-            const candidate = buildCompactionPrompt(inp, mid);
-            const candidateMessages = [
-                { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
-                { role: 'user', content: candidate },
-            ];
-            if (estimateMessagesTokens(candidateMessages) <= targetTokens) {
+            const candidate = fitAt(mid);
+            if (candidate) {
                 best = candidate;
                 lo = mid + 1;
             } else {
@@ -582,8 +991,258 @@ function extractResponseText(response) {
     return '';
 }
 
+// Canonical section anchors the semantic summary template (SUMMARY_TEMPLATE)
+// must contain. Used for lightweight schema validation of provider output.
+const REQUIRED_SUMMARY_SECTIONS = Object.freeze([
+    '## Goal',
+    '## Constraints',
+    '## Progress',
+    '## Key Decisions',
+    '## Next Steps',
+    '## Critical Context',
+    '## Relevant Files',
+]);
+
+// Collect actual top-level (`## `, not `### `) heading lines from a summary.
+// Validation is heading-anchor based (not substring includes) so prose or code
+// that merely mentions "## Relevant Files" inside a bullet body cannot satisfy
+// a section anchor.
+function summaryHeadingLines(summary) {
+    const out = [];
+    for (const rawLine of String(summary || '').split('\n')) {
+        const line = rawLine.trim();
+        if (/^##\s+\S/.test(line) && !/^###\s+/.test(line)) out.push(line);
+    }
+    return out;
+}
+
+// An anchor matches a heading when the heading title equals the anchor title or
+// extends it at a word/punctuation boundary. This lets `## Constraints &
+// Preferences` satisfy the `## Constraints` anchor while NOT letting an
+// unrelated `## Goalkeeper` heading satisfy `## Goal`. Requires a real `## `
+// heading line (not a substring buried in prose).
+function headingMatchesAnchor(heading, anchor) {
+    const anchorTitle = anchor.replace(/^##\s+/, '').trim().toLowerCase();
+    const headingTitle = heading.replace(/^##\s+/, '').trim().toLowerCase();
+    if (headingTitle === anchorTitle) return true;
+    if (!headingTitle.startsWith(anchorTitle)) return false;
+    // Next char after the anchor title must be a boundary (space or &/punct),
+    // not a continuation letter/digit.
+    const nextChar = headingTitle.charAt(anchorTitle.length);
+    return /[\s&:(-]/.test(nextChar);
+}
+
+function summarySchemaScore(summary) {
+    const headings = summaryHeadingLines(summary);
+    let hits = 0;
+    for (const anchor of REQUIRED_SUMMARY_SECTIONS) {
+        if (headings.some((h) => headingMatchesAnchor(h, anchor))) hits += 1;
+    }
+    return hits;
+}
+
+// A summary is schema-valid only when EVERY required section anchor is present
+// as a real heading. A partial summary (e.g. missing Critical Context /
+// Relevant Files) must be repaired rather than injected unchanged.
+function summaryIsSchemaValid(summary) {
+    if (summarySchemaScore(summary) !== REQUIRED_SUMMARY_SECTIONS.length) return false;
+    return !summaryHasUnrecognizedHeadings(summary);
+}
+
+function deriveRelevantFilesBullets(head) {
+    const seen = new Set();
+    const out = [];
+    const fileRe = /(?:[A-Za-z]:[\\/]|\.{1,2}[\\/]|[\w$.-]+[\\/])?[\w$.-]+\.(?:mjs|cjs|js|jsx|ts|tsx|json|md|rs|go|py|java|kt|cs|cpp|c|h|hpp|css|html|yml|yaml|toml|lock|sh|ps1)\b/gi;
+    for (const m of Array.isArray(head) ? head : []) {
+        const text = extractText(m);
+        if (!text) continue;
+        let match;
+        while ((match = fileRe.exec(text)) && out.length < 8) {
+            const file = match[0];
+            const key = file.toLowerCase();
+            if (seen.has(key)) continue;
+            seen.add(key);
+            out.push(`- ${file}`);
+        }
+        if (out.length >= 8) break;
+    }
+    return out;
+}
+
+function deriveCurrentRequest(messages) {
+    for (let i = (Array.isArray(messages) ? messages.length : 0) - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m?.role === 'user' && !isProtectedContextUserMessage(m)) {
+            const text = truncateMiddle(extractText(m).trim(), 400);
+            if (text) return text;
+        }
+    }
+    return '';
+}
+
+// Canonical ordered section headings the structured summary scaffold emits.
+// Each `## ` heading maps to one REQUIRED_SUMMARY_SECTIONS anchor; Progress
+// additionally carries its three `### ` sub-headings.
+const SUMMARY_SECTION_LAYOUT = Object.freeze([
+    { heading: '## Goal', anchor: '## Goal' },
+    { heading: '## Constraints & Preferences', anchor: '## Constraints' },
+    { heading: '## Progress', anchor: '## Progress', sub: ['### Done', '### In Progress', '### Blocked'] },
+    { heading: '## Key Decisions', anchor: '## Key Decisions' },
+    { heading: '## Next Steps', anchor: '## Next Steps' },
+    { heading: '## Critical Context', anchor: '## Critical Context' },
+    { heading: '## Relevant Files', anchor: '## Relevant Files' },
+]);
+
+// Split a markdown summary into a map of top-level `## ` heading -> body lines.
+function parseSummarySections(text) {
+    const map = new Map();
+    let current = null;
+    for (const rawLine of String(text || '').split('\n')) {
+        const trimmed = rawLine.trim();
+        const line = rawLine.replace(/\s+$/, '');
+        if (/^##\s+/.test(trimmed) && !/^###\s+/.test(trimmed)) {
+            current = trimmed;
+            if (!map.has(current)) map.set(current, []);
+            continue;
+        }
+        if (current) map.get(current).push(line);
+    }
+    return map;
+}
+
+function summarySectionIsRecognized(heading) {
+    for (const section of SUMMARY_SECTION_LAYOUT) {
+        if (headingMatchesAnchor(heading, section.anchor)) return true;
+    }
+    return false;
+}
+
+function summaryHasUnrecognizedHeadings(summary) {
+    for (const heading of parseSummarySections(summary).keys()) {
+        if (!summarySectionIsRecognized(heading)) return true;
+    }
+    return false;
+}
+
+function summaryLinesToBullets(text) {
+    return String(text || '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => (l.startsWith('-') ? l : `- ${l}`));
+}
+
+function unrecognizedSummarySectionText(present) {
+    const chunks = [];
+    for (const [heading, body] of present) {
+        if (summarySectionIsRecognized(heading)) continue;
+        const lines = [heading];
+        for (const line of body || []) {
+            const trimmed = String(line).trim();
+            if (trimmed) lines.push(line);
+        }
+        chunks.push(lines.join('\n'));
+    }
+    return chunks.join('\n\n').trim();
+}
+
+// Deterministic schema repair for a non-empty but malformed/partial semantic
+// summary. Preserve every section the provider DID supply (matched by anchor),
+// and scaffold the missing required sections so downstream consumers always
+// receive the full structured anchored shape. Content that lives outside any
+// recognized section is routed into Critical Context so nothing is dropped.
+// Lightly backfill Goal / Relevant Files from the transcript when empty.
+function repairSemanticSummary(summary, { head = [], tail = [] } = {}) {
+    const raw = String(summary || '').trim();
+    const present = parseSummarySections(raw);
+    // Capture any leading content before the first recognized `## ` heading so
+    // an entirely unstructured blob is preserved rather than silently dropped.
+    let preamble = '';
+    if (raw) {
+        const firstHeading = raw.search(/(^|\n)\s*##\s+/);
+        preamble = firstHeading === -1 ? raw : raw.slice(0, firstHeading);
+        preamble = preamble.trim();
+    }
+    const orphanText = unrecognizedSummarySectionText(present);
+    const extraContextParts = [];
+    if (preamble) extraContextParts.push(preamble);
+    if (orphanText) extraContextParts.push(orphanText);
+    const extraContext = extraContextParts.join('\n\n').trim();
+    const bulletize = (lines) => {
+        const cleaned = (Array.isArray(lines) ? lines : [])
+            .map((l) => String(l).trim())
+            .filter(Boolean);
+        return cleaned.length ? cleaned : null;
+    };
+    const findPresent = (anchor) => {
+        for (const [heading, body] of present) {
+            if (headingMatchesAnchor(heading, anchor)) return body;
+        }
+        return null;
+    };
+    const goal = deriveCurrentRequest(tail) || deriveCurrentRequest(head);
+    const files = deriveRelevantFilesBullets(head);
+    const out = [];
+    for (const section of SUMMARY_SECTION_LAYOUT) {
+        if (out.length) out.push('');
+        out.push(section.heading);
+        const body = bulletize(findPresent(section.anchor));
+        if (section.sub) {
+            // Progress: keep provider sub-bodies when present, else scaffold.
+            if (body) {
+                out.push(...body);
+            } else {
+                for (const sub of section.sub) {
+                    out.push(sub, '- (none)');
+                }
+            }
+            continue;
+        }
+        if (section.anchor === '## Critical Context') {
+            const ccLines = [];
+            if (body) ccLines.push(...body);
+            for (const line of summaryLinesToBullets(extraContext)) {
+                if (!ccLines.some((existing) => existing.trim() === line.trim())) ccLines.push(line);
+            }
+            if (ccLines.some((line) => line.trim() !== '- (none)')) {
+                const withoutPlaceholder = ccLines.filter((line) => line.trim() !== '- (none)');
+                out.push(...(withoutPlaceholder.length ? withoutPlaceholder : ccLines));
+            } else {
+                out.push(...(ccLines.length ? ccLines : ['- (none)']));
+            }
+            continue;
+        }
+        if (body) {
+            out.push(...body);
+            continue;
+        }
+        if (section.anchor === '## Goal') {
+            out.push(goal ? `- ${goal}` : '- (none)');
+        } else if (section.anchor === '## Relevant Files') {
+            out.push(...(files.length ? files : ['- (none)']));
+        } else {
+            out.push('- (none)');
+        }
+    }
+    return out.join('\n');
+}
+
+// Validate the provider summary against the required template sections; when it
+// is missing ANY required section anchor (fully or partially malformed) repair
+// it deterministically so a non-empty-but-broken response is never injected as
+// the sole summary. Returns { summary, repaired }.
+function enforceSemanticSummarySchema(summary, ctx = {}) {
+    const text = String(summary || '').trim();
+    if (!text) return { summary: text, repaired: false };
+    if (summaryIsSchemaValid(text)) {
+        return { summary: text, repaired: false };
+    }
+    return { summary: repairSemanticSummary(text, ctx), repaired: true };
+}
+
 function makeSemanticSummaryMessage(oldHistory, summary, semanticMeta = {}, preservedFacts = '') {
     const header = compactHeader(oldHistory);
+    header.push(`compact_type=${COMPACT_TYPE_SEMANTIC}`);
     header.push(`semantic=true provider=${semanticMeta.provider || 'unknown'} model=${semanticMeta.model || 'unknown'}`);
     const facts = String(preservedFacts || '').trim();
     const body = String(summary || '').trim();
@@ -593,19 +1252,103 @@ function makeSemanticSummaryMessage(oldHistory, summary, semanticMeta = {}, pres
     return makeSummaryMessage(parts.join('\n\n'));
 }
 
+export function buildRecallFastTrackQuery(messages, opts = {}) {
+    const maxChars = Math.max(200, Number(opts.maxChars) || 2_000);
+    const hints = String(opts.hints || 'current task decisions constraints file paths changed files verification failures next steps').trim();
+    let latestUser = '';
+    const recent = [];
+    const input = Array.isArray(messages) ? messages : [];
+    for (let i = input.length - 1; i >= 0; i -= 1) {
+        const m = input[i];
+        const text = extractText(m).trim();
+        if (!text) continue;
+        if (recent.length < 6) recent.unshift(text);
+        if (!latestUser && m?.role === 'user' && !isProtectedContextUserMessage(m)) {
+            latestUser = text;
+        }
+        if (latestUser && recent.length >= 6) break;
+    }
+    const parts = [latestUser, hints, recent.join('\n')]
+        .map((s) => String(s || '').trim())
+        .filter(Boolean);
+    return truncateMiddle([...new Set(parts)].join('\n'), maxChars);
+}
+
+// A headings-only structured summary: every required `## ` (and Progress `### `)
+// anchor present with `- (none)` bodies. This is the minimal schema-valid shape
+// the fitter can fall back to when token pressure cannot hold real section
+// bodies — it still passes summaryIsSchemaValid so the injected message is
+// never partial.
+function minimalSchemaSummary() {
+    const out = [];
+    for (const section of SUMMARY_SECTION_LAYOUT) {
+        if (out.length) out.push('');
+        out.push(section.heading);
+        if (section.sub) {
+            for (const sub of section.sub) out.push(sub, '- (none)');
+        } else {
+            out.push('- (none)');
+        }
+    }
+    return out.join('\n');
+}
+
+// Section-aware truncation: keep EVERY `## ` heading and Progress `### `
+// sub-heading intact, trimming only section bodies to `perSectionChars`. Unlike
+// a raw text.slice(0, n) this never drops a trailing required section, so the
+// result stays schema-valid (all anchors present) at any budget.
+function truncateSummaryBySections(summary, perSectionChars) {
+    const sections = parseSummarySections(summary);
+    const out = [];
+    for (const section of SUMMARY_SECTION_LAYOUT) {
+        if (out.length) out.push('');
+        out.push(section.heading);
+        let body = null;
+        for (const [heading, lines] of sections) {
+            if (headingMatchesAnchor(heading, section.anchor)) { body = lines; break; }
+        }
+        const bodyText = (Array.isArray(body) ? body : [])
+            .map((l) => String(l).trim())
+            .filter(Boolean)
+            .join('\n');
+        if (!bodyText) {
+            if (section.sub) for (const sub of section.sub) out.push(sub, '- (none)');
+            else out.push('- (none)');
+            continue;
+        }
+        const trimmed = perSectionChars > 0 ? truncateMiddle(bodyText, perSectionChars) : '';
+        if (trimmed) out.push(trimmed);
+        else if (section.sub) for (const sub of section.sub) out.push(sub, '- (none)');
+        else out.push('- (none)');
+    }
+    return out.join('\n');
+}
+
+// Fit the structured semantic summary into the remaining token budget WITHOUT
+// dropping any required section. The incoming `summary` is already schema-valid
+// (enforceSemanticSummarySchema ran upstream); here we shrink section bodies via
+// section-aware truncation, fall back to a headings-only schema-valid summary,
+// and finally revalidate so the injected SUMMARY_PREFIX message always carries
+// every required anchor. Returns null only when even the minimal schema-valid
+// summary cannot fit (caller throws).
 function fitSemanticSummaryMessage(oldHistory, summary, remainingTokens, semanticMeta, preservedFacts = '') {
     const tryFit = (factsText) => {
-        const minimal = makeSemanticSummaryMessage(oldHistory, '', semanticMeta, factsText);
-        if (estimateMessagesTokens([minimal]) > remainingTokens) return null;
         const text = String(summary || '').trim();
+        // Minimal schema-valid body (headings + "(none)"). If even this does
+        // not fit, this facts variant cannot produce a valid message.
+        const minimalBody = text ? minimalSchemaSummary() : '';
+        const minimal = makeSemanticSummaryMessage(oldHistory, minimalBody, semanticMeta, factsText);
+        if (estimateMessagesTokens([minimal]) > remainingTokens) return null;
         if (!text) return minimal;
+        // Binary search the per-section body budget; keep all anchors intact.
         let lo = 0;
         let hi = text.length;
         let best = minimal;
         while (lo <= hi) {
             const mid = Math.floor((lo + hi) / 2);
-            const candidate = makeSemanticSummaryMessage(oldHistory, text.slice(0, mid), semanticMeta, factsText);
-            if (estimateMessagesTokens([candidate]) <= remainingTokens) {
+            const body = truncateSummaryBySections(text, mid);
+            const candidate = makeSemanticSummaryMessage(oldHistory, body, semanticMeta, factsText);
+            if (estimateMessagesTokens([candidate]) <= remainingTokens && summaryIsSchemaValid(body)) {
                 best = candidate;
                 lo = mid + 1;
             } else {
@@ -614,11 +1357,90 @@ function fitSemanticSummaryMessage(oldHistory, summary, remainingTokens, semanti
         }
         return best;
     };
-    if (preservedFacts) {
-        const withFacts = tryFit(preservedFacts);
-        if (withFacts) return withFacts;
+    let result = null;
+    if (preservedFacts) result = tryFit(preservedFacts);
+    if (!result) result = tryFit('');
+    return result;
+}
+
+// Recall fast-track (compact type 2) does no LLM summarization — it just emits
+// the chunked history in order. Keep the message clean: the mandatory anchor
+// header (so selectCompactionWindow / clear-preserve / TUI can recognize the
+// compact message) plus the chunk text itself. No "Preserved Facts" extraction,
+// no "Recall Fast-Track Context" heading, no "(no recall hits)" filler.
+function makeRecallFastTrackSummaryMessage(oldHistory, recallText, recallMeta = {}) {
+    return makeRecallFastTrackSummaryMessageParts(oldHistory, recallText, '', recallMeta);
+}
+
+const RECALL_TAIL_TRUNCATION_MARKER = '[... truncated during recall tail preservation ...]';
+const RECALL_TAIL_SHORT_TRUNCATION_MARKER = '[truncated]';
+
+const PRIOR_COMPACTED_CONTEXT_OPEN = '<prior-compacted-context>';
+const PRIOR_COMPACTED_CONTEXT_CLOSE = '</prior-compacted-context>';
+
+function formatPriorCompactedContextBlock(priorText) {
+    const prior = String(priorText || '').trim();
+    if (!prior) return '';
+    return `${PRIOR_COMPACTED_CONTEXT_OPEN}\n${prior}\n${PRIOR_COMPACTED_CONTEXT_CLOSE}`;
+}
+
+function makeRecallFastTrackSummaryMessageParts(oldHistory, recallPart, priorPart, recallMeta = {}) {
+    const header = compactHeader(oldHistory);
+    header.push(`compact_type=${COMPACT_TYPE_RECALL_FASTTRACK} source=recall-fasttrack query_sha=${recallMeta.querySha || 'none'}`);
+    const parts = [header.join('\n')];
+    const priorBlock = formatPriorCompactedContextBlock(priorPart);
+    if (priorBlock) parts.push(priorBlock);
+    const recall = String(recallPart || '').trim();
+    if (recall) parts.push(recall);
+    return makeSummaryMessage(parts.join('\n\n'));
+}
+
+function fitRecallFastTrackSummaryMessage(oldHistory, recallText, remainingTokens, recallMeta = {}, priorPart = '') {
+    const recall = String(recallText || '').trim();
+    const prior = String(priorPart || '').trim();
+
+    let fittedPrior = prior;
+    if (prior) {
+        let lo = 0;
+        let hi = prior.length;
+        let bestPriorLen = 0;
+        while (lo <= hi) {
+            const mid = Math.floor((lo + hi) / 2);
+            const candidate = makeRecallFastTrackSummaryMessageParts(oldHistory, '', prior.slice(0, mid), recallMeta);
+            if (estimateMessagesTokens([candidate]) <= remainingTokens) {
+                bestPriorLen = mid;
+                lo = mid + 1;
+            } else {
+                hi = mid - 1;
+            }
+        }
+        fittedPrior = prior.slice(0, bestPriorLen);
+        if (!fittedPrior && prior) {
+            const markerOnly = makeRecallFastTrackSummaryMessageParts(oldHistory, '', RECALL_TAIL_TRUNCATION_MARKER, recallMeta);
+            if (estimateMessagesTokens([markerOnly]) <= remainingTokens) {
+                fittedPrior = RECALL_TAIL_TRUNCATION_MARKER;
+            }
+        }
     }
-    return tryFit('');
+
+    const minimal = makeRecallFastTrackSummaryMessageParts(oldHistory, '', fittedPrior, recallMeta);
+    if (estimateMessagesTokens([minimal]) > remainingTokens) return null;
+    if (!recall) return minimal;
+
+    let lo = 0;
+    let hi = recall.length;
+    let best = minimal;
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const candidate = makeRecallFastTrackSummaryMessageParts(oldHistory, recall.slice(0, mid), fittedPrior, recallMeta);
+        if (estimateMessagesTokens([candidate]) <= remainingTokens) {
+            best = candidate;
+            lo = mid + 1;
+        } else {
+            hi = mid - 1;
+        }
+    }
+    return best;
 }
 
 function combinedSignal(parent, timeoutMs) {
@@ -633,11 +1455,21 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
     if (!provider || typeof provider.send !== 'function') {
         throw new Error('semanticCompactMessages: provider.send is required');
     }
-    const budget = effectiveBudget(budgetTokens, opts);
-    const sanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
-    if (estimateMessagesTokens(sanitized) <= budget && opts.force !== true) {
-        return { messages: sanitized, usage: null, semantic: false };
+    let budget = effectiveBudget(budgetTokens, opts);
+    const baseSanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
+    // No-op fast path: if the original sanitized transcript already fits and we
+    // are not forced, return it UNCHANGED (no preserved-tail redaction applied)
+    // to keep prior no-compaction semantics.
+    if (estimateMessagesTokens(baseSanitized) <= budget && opts.force !== true) {
+        return { messages: baseSanitized, usage: null, semantic: false };
     }
+    // Compaction will proceed: redact sensitive tool-call argument VALUES before
+    // window selection so the preserved tail/system that survive verbatim are
+    // measured AND emitted in their redacted form. Head prompt normalizers
+    // (toolCallSummary/normalizeToolArgValue) still apply on top for the
+    // summarized head. Redaction is shape-preserving, so tool-pair structure
+    // stays provider-valid.
+    const sanitized = redactToolCallSecretsInMessages(baseSanitized);
 
     const selected = selectCompactionWindow(sanitized, budget, opts);
     if (selected.head.length === 0 && !selected.previousSummary) {
@@ -646,8 +1478,14 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
 
     const mandatory = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs([...selected.system, ...selected.tail])));
     const mandatoryCost = estimateMessagesTokens(mandatory);
-    if (mandatoryCost > budget) {
-        throw new Error(`semanticCompactMessages: system+preserved tail exceeds budget=${budget} (base=${mandatoryCost})`);
+    // The preserved tail is kept verbatim and the head is replaced by a much
+    // smaller summary, so the compacted result is always smaller than the
+    // input regardless of how the configured target budget compares to the
+    // mandatory cost. When the budget cannot even hold what we must keep, raise
+    // it to fit (mandatory + summary room) rather than refusing — a refusal
+    // here was the source of auto-clear / overflow compact failures.
+    if (mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS > budget) {
+        budget = mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS;
     }
 
     const callBudget = Math.max(1, Math.floor((opts.compactionInputBudgetTokens || budget) * COMPACTION_PROMPT_HEADROOM));
@@ -666,9 +1504,14 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
         maxOutputTokens: opts.maxOutputTokens || SUMMARY_OUTPUT_TOKENS,
         providerState: undefined,
         onToolCall: undefined,
+        onToolResult: undefined,
+        onTextDelta: undefined,
+        onReasoningDelta: undefined,
+        onUsageDelta: undefined,
         onStreamDelta: undefined,
         onStageChange: undefined,
-        remoteCompact: false,
+        drainSteering: undefined,
+        onSteerMessage: undefined,
         signal: combinedSignal(opts.signal || opts.sendOpts?.signal || null, opts.timeoutMs || 30_000),
     };
     if (opts.sessionId) sendOpts.sessionId = `${opts.sessionId}:compact`;
@@ -683,8 +1526,13 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
         { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
         { role: 'user', content: prompt },
     ], compactModel, undefined, sendOpts);
-    const summary = extractResponseText(response);
-    if (!summary) throw new Error('semanticCompactMessages: compaction agent returned empty summary');
+    const rawSummary = extractResponseText(response);
+    if (!rawSummary) throw new Error('semanticCompactMessages: compaction agent returned empty summary');
+    // Lightweight schema enforcement: a non-empty but malformed provider
+    // response (missing the required template sections) is deterministically
+    // repaired into the structured anchored shape rather than injected blindly.
+    const enforced = enforceSemanticSummarySchema(rawSummary, { head: selected.head, tail: selected.tail });
+    const summary = enforced.summary;
 
     const oldHistory = selected.originalHead;
     const semanticMeta = {
@@ -696,6 +1544,9 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
         throw new Error(`semanticCompactMessages: summary cannot fit remaining budget=${budget - mandatoryCost}`);
     }
 
+    // selected.system / selected.tail already carry redacted tool-call args
+    // (sanitized was redacted before window selection), so the preserved tail
+    // is both measured and emitted in redacted form.
     let result = sanitizeToolPairs([...selected.system, summaryMessage, ...selected.tail]);
     result = reconcileDedupStubs(dedupToolResultBodies(result));
     const finalTokens = estimateMessagesTokens(result);
@@ -707,176 +1558,231 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
         usage: response?.usage || null,
         providerState: response?.providerState,
         semantic: true,
+        compactType: COMPACT_TYPE_SEMANTIC,
         summary,
+        summaryRepaired: enforced.repaired === true,
     };
 }
 
-export function compactMessages(messages, budgetTokens, opts = {}) {
-    const budget = effectiveBudget(budgetTokens, opts);
-    const sanitized = sanitizeToolPairs(messages);
-    if (estimateMessagesTokens(sanitized) <= budget && opts.force !== true) {
-        return reconcileDedupStubs(sanitized);
-    }
-
-    const system = sanitized.filter(m => m?.role === 'system');
-    const nonSystem = sanitized.filter(m => m?.role !== 'system');
-    const turnStart = currentTurnStart(nonSystem);
-    if (turnStart <= 0) {
-        throw new Error(`compactMessages: no compactable prior history before current turn (budget=${budget})`);
-    }
-
-    const oldHistory = nonSystem.slice(0, turnStart);
-    const currentTurn = nonSystem.slice(turnStart);
-    let mandatory = sanitizeToolPairs([...system, ...currentTurn]);
-    mandatory = reconcileDedupStubs(dedupToolResultBodies(mandatory));
-    const mandatoryCost = estimateMessagesTokens(mandatory);
-    if (mandatoryCost > budget) {
-        throw new Error(`compactMessages: mandatory system+current turn exceeds budget=${budget} (base=${mandatoryCost})`);
-    }
-
-    const summary = fitSummaryMessage(oldHistory, budget - mandatoryCost);
-    if (!summary) {
-        throw new Error(`compactMessages: compact summary cannot fit remaining budget=${budget - mandatoryCost}`);
-    }
-
-    let result = sanitizeToolPairs([...system, summary, ...currentTurn]);
-    result = reconcileDedupStubs(dedupToolResultBodies(result));
-    const finalTokens = estimateMessagesTokens(result);
-    if (finalTokens > budget) {
-        throw new Error(`compactMessages: compacted result exceeds budget=${budget} (result=${finalTokens})`);
-    }
-    return result;
+export function recallFastTrackCompactMessages(messages, budgetTokens, opts = {}) {
+    return _recallFastTrackCompactMessages(messages, budgetTokens, opts);
 }
 
-// Split the assistant/tool portion of a single user turn into ordered
-// groups. Each group starts at an assistant message and absorbs the tool
-// results that follow it, so a group is the atomic unit we can drop or
-// prune without orphaning a tool_use/tool_result pair.
-function splitTurnGroups(messages) {
-    const groups = [];
+// Recall fast-track (type 2) tail policy: preserve the most recent turns of the
+// live conversation VERBATIM and STRUCTURED, keeping role semantics for
+// user / assistant / tool / system / developer instead of collapsing the tail
+// to user-only. The chunk summary anchors older history; the preserved tail
+// keeps recent assistant reasoning, tool_calls, and tool_results so fresh
+// state is not silently dropped.
+//
+// Turns are anchored on user-role boundaries: each turn = a user message plus
+// the assistant/tool/system/developer messages that follow it (a leading run of
+// non-user messages before the first user boundary is treated as its own
+// partial turn so nothing is lost). We keep the newest RECALL_TAIL_USER_MAX
+// turns; if the kept set exceeds RECALL_TAIL_TOKEN_CAP we drop whole oldest
+// turns first, then middle-truncate the oldest surviving messages' string
+// content so the set fits while leaving the newest message whole.
+//
+// Partial tool_call/tool_result pairs that truncation might leave behind are
+// repaired by sanitizeToolPairs/reconcileDedupStubs in the caller, so pairing
+// stays valid even after trimming.
+const RECALL_TAIL_USER_MAX = 2;
+const RECALL_TAIL_TOKEN_CAP = DEFAULT_COMPACTION_KEEP_TOKENS; // 8k
+// Rough chars-per-token used only to size a truncation target; the real fit is
+// re-checked with estimateMessagesTokens below.
+const RECALL_TAIL_CHARS_PER_TOKEN = 4;
+
+function splitTailIntoTurns(messages) {
+    const turns = [];
     let current = null;
     for (const m of messages) {
-        if (m?.role === 'assistant') {
-            if (current) groups.push(current);
+        if (isSummaryMessage(m)) continue;
+        if (m?.role === 'user') {
+            if (current) turns.push(current);
             current = [m];
         } else {
             if (!current) current = [];
             current.push(m);
         }
     }
-    if (current) groups.push(current);
-    return groups;
-}
-
-/**
- * Active-turn fallback compaction (bridge/worker only).
- *
- * compactMessages/semanticCompactMessages treat the ENTIRE current turn as
- * mandatory, so a hidden worker with one user turn plus many assistant/tool
- * iterations throws overflow even when older same-turn tool outputs could be
- * safely shrunk. This narrow fallback shrinks the current turn itself while
- * preserving, in priority order:
- *   - all system messages,
- *   - the original task user message (the turn's first user message),
- *   - the latest assistant/tool group(s),
- *   - valid tool_use/tool_result pairing (via sanitizeToolPairs).
- *
- * Older prior history (before the current turn) is condensed to a best-effort
- * summary when it still fits the remaining budget, otherwise dropped — it has
- * already been superseded by completed turns. It NEVER silently drops the task
- * user message or the latest group: if system + task user + the fully-pruned
- * latest group still cannot fit, it throws so the caller surfaces overflow.
- */
-export function compactActiveTurn(messages, budgetTokens, opts = {}) {
-    const budget = effectiveBudget(budgetTokens, opts);
-    const sanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
-    const system = sanitized.filter(m => m?.role === 'system');
-    const nonSystem = sanitized.filter(m => m?.role !== 'system');
-    const turnStart = currentTurnStart(nonSystem);
-    if (turnStart < 0) {
-        throw new Error(`compactActiveTurn: no current user turn to preserve (budget=${budget})`);
-    }
-
-    const oldHistory = nonSystem.slice(0, turnStart);
-    const currentTurn = nonSystem.slice(turnStart);
-    const userMsg = currentTurn[0];
-    const groups = splitTurnGroups(currentTurn.slice(1));
-    const minGroups = Math.max(1, Number(opts.minActiveTurnGroups) || 1);
-    const maxChars = Math.max(256, Number(opts.maxToolOutputChars) || PRUNE_TOOL_OUTPUT_MAX_CHARS);
-    const force = opts.force === true;
-
-    const pruneToolMsg = (m) => (
-        m?.role === 'tool' && typeof m.content === 'string' && m.content.length > maxChars
-            ? {
-                ...m,
-                content: pruneToolOutputText(m.content, maxChars, m.toolCallId),
-                compacted: true,
-                compactedKind: 'active_turn_tool_prune',
-            }
-            : m
-    );
+    if (current && current.length) turns.push(current);
+    return turns;
+}
 
-    // pruneMode: 'older' prunes every group except the latest; 'all' prunes
-    // every kept group (last resort before declaring overflow).
-    const buildTurnMsgs = (keptGroups, pruneMode) => {
-        const out = [userMsg];
-        for (let gi = 0; gi < keptGroups.length; gi += 1) {
-            const isLatest = gi === keptGroups.length - 1;
-            const prune = pruneMode === 'all' || (pruneMode === 'older' && !isLatest);
-            for (const m of keptGroups[gi]) out.push(prune ? pruneToolMsg(m) : m);
+function truncateMessageForRecallTail(text, maxChars) {
+    const marker = RECALL_TAIL_TRUNCATION_MARKER;
+    const value = String(text ?? '').replace(/\r\n/g, '\n');
+    if (value.length <= maxChars) return value;
+    if (maxChars <= 0) return RECALL_TAIL_SHORT_TRUNCATION_MARKER;
+    if (maxChars < marker.length) return RECALL_TAIL_SHORT_TRUNCATION_MARKER;
+    const room = maxChars - marker.length;
+    const head = Math.ceil(room * 0.35);
+    const tailPart = Math.floor(room * 0.65);
+    return `${value.slice(0, head)}${marker}${value.slice(value.length - tailPart)}`;
+}
+
+function fitRecallUserMessageToCap(userMsg, cap, following = []) {
+    const followCost = estimateMessagesTokens(following);
+    const room = Math.max(1, cap - followCost);
+    const base = { ...userMsg };
+    const raw = typeof base.content === 'string' ? base.content : extractText(base);
+    if (estimateMessagesTokens([{ ...base, content: raw }]) <= room) return { ...base, content: raw };
+
+    let lo = 0;
+    let hi = raw.length;
+    let best = truncateMessageForRecallTail(raw, 0);
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const candidateText = truncateMessageForRecallTail(raw, mid);
+        const candidate = { ...base, content: candidateText };
+        if (estimateMessagesTokens([candidate]) <= room) {
+            best = candidateText;
+            lo = mid + 1;
+        } else {
+            hi = mid - 1;
         }
-        return out;
-    };
+    }
+    return { ...base, content: best };
+}
+
+function fitSingleRecallTurnToCap(turn, cap) {
+    const userIdx = turn.findIndex((m) => m?.role === 'user');
+    if (userIdx < 0) {
+        return truncateTailToCap(turn, cap);
+    }
+    const userMsg = turn[userIdx];
+    const following = turn.slice(userIdx + 1);
+    const fittedUser = fitRecallUserMessageToCap(userMsg, cap, following);
+    let out = [fittedUser];
+    for (const m of following) {
+        const candidate = [...out, m];
+        if (estimateMessagesTokens(candidate) <= cap) out.push(m);
+    }
+    return reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(out)));
+}
 
-    const buildWithSummaries = (turnMsgs, { oldSummary = null, activeSummary = null } = {}) => {
-        const [taskUser, ...restTurn] = turnMsgs;
-        return reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs([
-            ...system,
-            ...(oldSummary ? [oldSummary] : []),
-            taskUser,
-            ...(activeSummary ? [activeSummary] : []),
-            ...restTurn,
-        ])));
+function truncateTailToCap(messages, cap) {
+    const turn = Array.isArray(messages) ? messages : [];
+    if (turn.length === 0) return [];
+    return fitSingleRecallTurnToCap(turn, cap);
+}
+
+function stripNestedSummaryHeaderLines(text) {
+    const lines = String(text ?? '').split('\n');
+    const out = [];
+    for (const line of lines) {
+        if (line.startsWith(SUMMARY_PREFIX)) continue;
+        if (/^messages=\d+\s+sha256=/.test(line.trim())) continue;
+        out.push(line);
+    }
+    return out.join('\n').trim();
+}
+
+function splitRecallFitInputs(recallText, previousSummary) {
+    return {
+        recall: String(recallText || '').trim(),
+        prior: previousSummary ? stripNestedSummaryHeaderLines(previousSummary) : '',
     };
+}
 
-    const finalize = (turnMsgs, activeHistory = []) => {
-        let oldSummary = null;
-        let activeSummary = null;
-        let base = buildWithSummaries(turnMsgs);
-        if (activeHistory.length) {
-            const baseCost = estimateMessagesTokens(base);
-            if (baseCost < budget) {
-                activeSummary = fitSummaryMessage(activeHistory, budget - baseCost);
-                if (activeSummary) base = buildWithSummaries(turnMsgs, { activeSummary });
-            }
-        }
-        if (oldHistory.length) {
-            const baseCost = estimateMessagesTokens(base);
-            if (baseCost < budget) {
-                oldSummary = fitSummaryMessage(oldHistory, budget - baseCost);
-                if (oldSummary) base = buildWithSummaries(turnMsgs, { oldSummary, activeSummary });
-            }
-        }
-        return base;
+function recallTailStartIndex(live, tail) {
+    if (!tail.length) return live.length;
+    const first = tail[0];
+    const idx = live.indexOf(first);
+    if (idx >= 0) return idx;
+    return Math.max(0, live.length - tail.length);
+}
+
+function selectRecallPreservedTail(live, opts = {}) {
+    const msgs = (Array.isArray(live) ? live : []).filter((m) => m && !isSummaryMessage(m));
+    if (msgs.length === 0) return { tail: [], head: [], tailStartIdx: 0 };
+    const maxTurns = Math.max(1, Number(opts.maxUsers) || RECALL_TAIL_USER_MAX);
+    const cap = Math.max(1, Number(opts.tokenCap) || RECALL_TAIL_TOKEN_CAP);
+    const turns = splitTailIntoTurns(msgs);
+    if (turns.length === 0) return { tail: [], head: msgs, tailStartIdx: 0 };
+
+    let kept = turns.slice(-maxTurns);
+    while (kept.length > 1 && estimateMessagesTokens(kept.flat()) > cap) {
+        kept = kept.slice(1);
+    }
+
+    let tail;
+    if (estimateMessagesTokens(kept.flat()) <= cap) {
+        tail = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(kept.flat())));
+    } else {
+        tail = fitSingleRecallTurnToCap(kept[kept.length - 1], cap);
+    }
+
+    if (!tail.some((m) => m?.role === 'user')) {
+        throw new Error('recallFastTrackCompactMessages: preserved tail missing user anchor');
+    }
+
+    const tailStartIdx = recallTailStartIndex(msgs, tail);
+    const head = msgs.slice(0, tailStartIdx);
+    return { tail, head, tailStartIdx };
+}
+
+// Kept name as the type-2 tail anchor; behavior now preserves whole structured
+// turns (all roles) rather than only role=user messages.
+function selectRecallTailUserMessages(tail, opts = {}) {
+    const msgs = (Array.isArray(tail) ? tail : []).filter((m) => m && !isSummaryMessage(m));
+    return selectRecallPreservedTail(msgs, opts).tail;
+}
+
+function _recallFastTrackCompactMessages(messages, budgetTokens, opts = {}) {
+    let budget = effectiveBudget(budgetTokens, opts);
+    const baseSanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
+    if (estimateMessagesTokens(baseSanitized) <= budget && opts.force !== true) {
+        return { messages: baseSanitized, recallFastTrack: false };
+    }
+    const sanitized = redactToolCallSecretsInMessages(baseSanitized);
+
+    const { system: safeSystem, live, previousSummary } = splitLiveCompactionContext(sanitized);
+    const recallTailOpts = {
+        maxUsers: opts.recallTailMaxUsers ?? opts.tailTurns ?? RECALL_TAIL_USER_MAX,
+        tokenCap: opts.recallTailTokenCap ?? preserveRecentBudget(budget, opts),
     };
+    const { tail: recallTail, head: recallHead } = selectRecallPreservedTail(live, recallTailOpts);
+    const recallFit = splitRecallFitInputs(opts.recallText, previousSummary);
+    if (recallHead.length === 0 && !previousSummary
+        && !(recallFit.recall || recallFit.prior || opts.allowEmptyRecall === true)) {
+        throw new Error('recallFastTrackCompactMessages: no compactable prior history before preserved tail');
+    }
 
-    const maxDrop = Math.max(0, groups.length - minGroups);
-    const startDrop = force && maxDrop > 0 ? 1 : 0;
-    for (let drop = startDrop; drop <= maxDrop; drop += 1) {
-        const kept = groups.slice(drop);
-        const activeHistory = groups.slice(0, drop).flat();
-        const modes = force && drop === 0 && activeHistory.length === 0
-            ? ['all', 'older']
-            : ['older', 'all'];
-        for (const mode of modes) {
-            const candidate = finalize(buildTurnMsgs(kept, mode), activeHistory);
-            if (estimateMessagesTokens(candidate) <= budget) return candidate;
-        }
+    const mandatory = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs([...safeSystem, ...recallTail])));
+    const mandatoryCost = estimateMessagesTokens(mandatory);
+    if (mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS > budget) {
+        budget = mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS;
     }
 
-    const floor = finalize(buildTurnMsgs(groups.slice(-minGroups), 'all'), groups.slice(0, -minGroups).flat());
-    throw new Error(
-        `compactActiveTurn: system+task user+latest turn group exceeds budget=${budget} ` +
-        `(floor=${estimateMessagesTokens(floor)})`,
+    if (!recallFit.recall && !recallFit.prior && opts.allowEmptyRecall !== true) {
+        throw new Error('recallFastTrackCompactMessages: recall text is empty');
+    }
+    const oldHistory = recallHead;
+    const recallMeta = {
+        querySha: opts.querySha || null,
+    };
+    const summaryMessage = fitRecallFastTrackSummaryMessage(
+        oldHistory,
+        recallFit.recall,
+        budget - mandatoryCost,
+        recallMeta,
+        recallFit.prior,
     );
+    if (!summaryMessage) {
+        throw new Error(`recallFastTrackCompactMessages: summary cannot fit remaining budget=${budget - mandatoryCost}`);
+    }
+
+    let result = sanitizeToolPairs([...safeSystem, summaryMessage, ...recallTail]);
+    result = reconcileDedupStubs(dedupToolResultBodies(result));
+    const finalTokens = estimateMessagesTokens(result);
+    if (finalTokens > budget) {
+        throw new Error(`recallFastTrackCompactMessages: compacted result exceeds budget=${budget} (result=${finalTokens})`);
+    }
+    return {
+        messages: result,
+        recallFastTrack: true,
+        compactType: COMPACT_TYPE_RECALL_FASTTRACK,
+        query: opts.query || '',
+    };
 }