mixdog 0.9.1 → 0.9.3

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

@@ -4,6 +4,12 @@ import {
     dedupToolResultBodies,
     reconcileDedupStubs,
     estimateMessagesTokens,
+    DEFAULT_COMPACTION_BUFFER_TOKENS,
+    DEFAULT_COMPACTION_BUFFER_RATIO,
+    MAX_COMPACTION_BUFFER_RATIO,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+    normalizeCompactionBufferRatio,
+    compactionBufferTokensForBoundary,
 } 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.';
@@ -15,10 +21,14 @@ export const SUMMARY_PREFIX = 'A previous model worked on this task and produced
 // 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 {
+    DEFAULT_COMPACTION_BUFFER_TOKENS,
+    DEFAULT_COMPACTION_BUFFER_RATIO,
+    MAX_COMPACTION_BUFFER_RATIO,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+    normalizeCompactionBufferRatio,
+    compactionBufferTokensForBoundary,
+};
 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
@@ -221,6 +231,20 @@ function isProtectedContextUserMessage(m) {
     return m.content.trimStart().startsWith('<system-reminder>');
 }
 
+// An injected Skill-body user message (the general newMessages channel carries
+// the full SKILL.md body as a role:'user' message after the Skill tool_result).
+// Like isSummaryMessage / isProtectedContextUserMessage, it is detected by
+// content prefix (the `<skill>` envelope from buildSkillResultEnvelope) so the
+// check survives even if the synthetic `meta` field is dropped during a tail
+// rebuild. It is NOT the human's latest prompt and must be excluded from
+// "latest human request" selection (deriveCurrentRequest /
+// buildRecallFastTrackQuery). The `meta:'skill'` marker is also honoured.
+function isInjectedSkillBodyMessage(m) {
+    if (m?.role !== 'user') return false;
+    if (m.meta === 'skill') return true;
+    return typeof m.content === 'string' && m.content.trimStart().startsWith('<skill>');
+}
+
 function isProtectedContextAckMessage(m) {
     return m?.role === 'assistant'
         && typeof m.content === 'string'
@@ -365,29 +389,26 @@ export function redactToolCallSecretsInMessages(messages) {
     return messages.map((m) => redactMessageToolCallSecrets(m));
 }
 
-export function normalizeCompactionBufferRatio(value, fallback = DEFAULT_COMPACTION_BUFFER_RATIO) {
-    const n = Number(value);
-    if (Number.isFinite(n) && n > 0) return n > 1 ? n / 100 : n;
-    return fallback;
-}
-
-export function compactionBufferTokensForBoundary(boundaryTokens, opts = {}) {
-    const boundary = Math.max(0, Math.floor(Number(boundaryTokens) || 0));
-    const explicit = Math.max(0, Math.floor(Number(opts.explicitTokens) || 0));
-    if (!boundary) return explicit;
-    const maxRatio = normalizeCompactionBufferRatio(opts.maxRatio, MAX_COMPACTION_BUFFER_RATIO);
-    const cap = Math.max(0, Math.floor(boundary * maxRatio));
-    if (explicit > 0) return Math.max(0, Math.min(explicit, cap));
-    const ratio = normalizeCompactionBufferRatio(opts.ratio, DEFAULT_COMPACTION_BUFFER_RATIO);
-    return Math.max(0, Math.min(Math.floor(boundary * ratio), cap));
-}
-
-function effectiveBudget(budgetTokens, opts) {
+// Floor for the reserve-adjusted compact budget. When the tool-schema/request
+// reserve rivals the whole budget (huge agent tool surfaces), subtracting the
+// full reserve could leave a degenerate target; keep enough room to attempt a
+// summary and let the final fit check decide. Logged as degraded because a
+// floored budget can still overflow on the next send.
+const MIN_EFFECTIVE_COMPACT_BUDGET_TOKENS = 1024;
+export function effectiveBudget(budgetTokens, opts) {
     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));
-    return Math.max(1, budgetTokens - effectiveReserve);
+    // Subtract the FULL reserve so an accepted compact actually fits next to
+    // the request reserve on the following send. The previous 50%-of-budget cap
+    // under-reserved large tool surfaces (agent sessions): a compact could be
+    // "accepted" at budget/2 while the true remaining room was smaller, then
+    // overflow immediately on the next request.
+    const remaining = budgetTokens - reserve;
+    if (remaining >= MIN_EFFECTIVE_COMPACT_BUDGET_TOKENS) return remaining;
+    const floored = Math.max(1, Math.min(budgetTokens, MIN_EFFECTIVE_COMPACT_BUDGET_TOKENS));
+    try { process.stderr.write(`[compact] degraded budget: reserve=${reserve} leaves ${remaining} of budget=${budgetTokens}; flooring to ${floored}\n`); } catch { /* best-effort */ }
+    return floored;
 }
 
 const PRUNE_TOOL_OUTPUT_MAX_CHARS = 2_000;
@@ -434,6 +455,39 @@ export function compactTypeIsRecallFastTrack(value) {
     return normalizeCompactType(value) === COMPACT_TYPE_RECALL_FASTTRACK;
 }
 
+function compactDebugEnabled() {
+    return String(process.env.MIXDOG_COMPACT_DEBUG || '').trim() === '1';
+}
+
+function compactDebugLog(scope, details = {}) {
+    if (!compactDebugEnabled()) return;
+    try {
+        process.stderr.write(`[compact] ${scope} ${JSON.stringify(details)}\n`);
+    } catch { /* best-effort diagnostics only */ }
+}
+
+function safeEstimateMessagesTokens(messages) {
+    try { return estimateMessagesTokens(messages); }
+    catch { return null; }
+}
+
+function textByteLength(text) {
+    try { return Buffer.byteLength(String(text || ''), 'utf8'); }
+    catch { return String(text || '').length; }
+}
+
+function messageContentHasMarker(m, marker) {
+    if (!m || !marker) return false;
+    if (typeof m.content === 'string') return m.content.includes(marker);
+    if (Array.isArray(m.content)) {
+        return m.content.some((part) => {
+            if (!part || typeof part !== 'object') return false;
+            return String(part.text || part.content || '').includes(marker);
+        });
+    }
+    return false;
+}
+
 // 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.
@@ -679,6 +733,39 @@ export function pruneToolOutputs(messages, budgetTokens, opts = {}) {
     return reconcileDedupStubs(result);
 }
 
+// Anchor-independent tool-output prune (loop overflow safety net).
+//
+// pruneToolOutputs protects the most-recent tailTurns of USER-anchored history,
+// so a single-turn transcript with no user boundary yields protectFrom=0 and
+// prunes nothing. This variant needs no user anchor: it middle-truncates the
+// OLDEST oversized tool_result bodies first, walking forward, until the
+// transcript fits the budget. The newest tool_result is truncated last (and
+// only if still necessary) so fresh state is preserved as long as possible.
+// Structure/pairing is preserved (only string content shrinks), and the result
+// is re-reconciled so tool pairing stays provider-valid.
+export function pruneToolOutputsUnanchored(messages, budgetTokens, opts = {}) {
+    const budget = effectiveBudget(budgetTokens, opts);
+    let result = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
+    if (estimateMessagesTokens(result) <= budget) return result;
+
+    const maxChars = Math.max(256, Number(opts?.maxToolOutputChars) || PRUNE_TOOL_OUTPUT_MAX_CHARS);
+    // Oldest -> newest so recent tool output survives longest. No user-turn
+    // protection: every oversized tool_result is a candidate.
+    for (let i = 0; i < result.length; i += 1) {
+        const m = result[i];
+        if (m?.role !== 'tool' || typeof m.content !== 'string') continue;
+        if (m.content.length <= maxChars) continue;
+        result[i] = {
+            ...m,
+            content: pruneToolOutputText(m.content, maxChars, m.toolCallId),
+            compacted: true,
+            compactedKind: 'tool_output_prune',
+        };
+        if (estimateMessagesTokens(result) <= budget) break;
+    }
+    return reconcileDedupStubs(result);
+}
+
 function preserveRecentBudget(budget, opts = {}) {
     const maxForBudget = Math.max(1, Math.floor(Number(budget || 0) * 0.8));
     const explicit = Number(opts.preserveRecentTokens ?? opts.keepTokens);
@@ -743,14 +830,29 @@ function splitLiveCompactionContext(messages) {
     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');
+// A tail may begin ONLY at an index that is not a tool result: a tool result
+// must stay paired with the assistant tool_call that precedes it, so it can
+// never be the first message of the preserved tail. Every other role (user /
+// assistant / developer / ...) is a valid tail boundary. This replaces the old
+// "the tail must begin at a real user turn" rule, which threw whenever the
+// recent window carried no user message (single-turn agent sessions whose tail
+// is assistant/tool only).
+function findValidCutIndices(live) {
+    const out = [];
+    for (let i = 0; i < live.length; i += 1) {
+        if (live[i]?.role === 'tool') continue;
+        out.push(i);
+    }
+    return out;
+}
 
-    const tailTurns = Math.max(1, Number(opts.tailTurns) || DEFAULT_TAIL_TURNS);
-    const recentBudget = preserveRecentBudget(budget, opts);
+// User-anchored path (unchanged behaviour): keep up to tailTurns recent turns
+// bounded by recentBudget, splitting the newest turn's suffix when it alone is
+// too large. Preserved verbatim so Lead / normal sessions with real user turns
+// compact exactly as before.
+function selectTailStartByTurns(live, recentBudget, tailTurns, previousSummary, opts) {
     const indexedTurns = indexLiveTurns(live);
-    if (indexedTurns.length === 0) throw new Error('semanticCompactMessages: no user turn to preserve');
+    if (indexedTurns.length === 0) return live.length;
 
     let tailStartIdx = live.length;
     let keptTurns = 0;
@@ -786,20 +888,90 @@ function selectCompactionWindow(messages, budget, opts = {}) {
         break;
     }
 
+    if (opts.force === true && !previousSummary && tailStartIdx <= 0) {
+        if (indexedTurns.length >= 2) {
+            tailStartIdx = indexedTurns[1].start;
+        } else if (indexedTurns.length === 1) {
+            const onlyTurn = indexedTurns[0];
+            const splitIdx = splitTurnStartIndexForBudget(onlyTurn, recentBudget);
+            if (splitIdx > onlyTurn.start && splitIdx < onlyTurn.end) {
+                tailStartIdx = splitIdx;
+            } else if (onlyTurn.end > onlyTurn.start + 1) {
+                tailStartIdx = onlyTurn.start + 1;
+            }
+        }
+    }
+    return tailStartIdx;
+}
+
+// No-user path: pick the tail boundary from valid cut points. Walk newest ->
+// oldest, growing the tail across valid cut points while its suffix still fits
+// recentBudget, and stop before it overflows. Never anchors on a user turn, so
+// an assistant/tool-only single-turn transcript still yields a head to
+// summarize and a paired tail to keep.
+function selectTailStartByCutPoint(live, recentBudget, previousSummary) {
+    const validCuts = findValidCutIndices(live);
+    if (validCuts.length === 0) return live.length; // degenerate: only tool results
+
+    let chosen = null;
+    for (let k = validCuts.length - 1; k >= 0; k -= 1) {
+        const idx = validCuts[k];
+        if (estimateMessagesTokens(live.slice(idx)) <= recentBudget) {
+            chosen = idx; // fits — try to grow the tail toward an older cut
+            continue;
+        }
+        break; // this cut overflows recentBudget; keep the previous (newer) choice
+    }
+
+    if (chosen === null) {
+        // Even the newest valid cut's suffix exceeds recentBudget (a single huge
+        // message run). Keep the minimal tail from the newest valid cut so a head
+        // remains to summarize; if that cut is at index 0 there is nothing to
+        // split off, so keep everything in the head instead. The oversized tail
+        // is tolerated downstream (mandatory-cost budget raise) rather than
+        // throwing.
+        const newestCut = validCuts[validCuts.length - 1];
+        return newestCut > 0 ? newestCut : live.length;
+    }
+
+    if (chosen <= 0) {
+        // Whole transcript would become the tail => nothing to compact. With no
+        // prior summary to build on, pull the tail start forward to the next
+        // valid cut so the leading message(s) become the compactable head.
+        if (!previousSummary && validCuts.length >= 2) return validCuts[1];
+        // Only ONE valid cut (or a leading tool run before it) and no prior
+        // summary: there is no older cut to pull forward to. Returning 0 would
+        // make the whole transcript the tail with an empty head, and
+        // semanticCompactMessages throws on head.length===0 && !previousSummary.
+        // Keep everything in the HEAD instead (empty tail) so a head remains to
+        // summarize; an empty tail is valid downstream (mandatory = system+tail).
+        if (!previousSummary && validCuts.length < 2) return live.length;
+        return chosen;
+    }
+    return chosen;
+}
+
+function selectCompactionWindow(messages, budget, opts = {}) {
+    const { system, live, previousSummary } = splitLiveCompactionContext(messages);
+    const tailTurns = Math.max(1, Number(opts.tailTurns) || DEFAULT_TAIL_TURNS);
+    const recentBudget = preserveRecentBudget(budget, opts);
+
+    const tailStartIdx = userIndexes(live).length
+        ? selectTailStartByTurns(live, recentBudget, tailTurns, previousSummary, opts)
+        : selectTailStartByCutPoint(live, recentBudget, previousSummary);
+
     const head = live.slice(0, tailStartIdx);
     let tail = live.slice(tailStartIdx);
+    // sanitizeToolPairs/dedup/reconcile repairs any orphan tool_result the cut
+    // may have left; because valid cut points never start on a tool result, an
+    // assistant tool_call and its trailing tool_results always land on the same
+    // side of the boundary, so pairing stays provider-valid.
     tail = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(tail)));
 
+    // Only a genuinely empty live window is unrecoverable. Absence of a user
+    // turn in the tail is no longer an error.
     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');
-        }
+        throw new Error('semanticCompactMessages: nothing to compact (empty live window)');
     }
 
     const preservedFacts = extractPreservedFacts(head);
@@ -970,7 +1142,47 @@ function fitCompactionPrompt(input, targetTokens) {
             { role: 'user', content: withFacts },
         ]) <= targetTokens) return withFacts;
     }
-    return tryFit(false);
+    const fitted = tryFit(false);
+    if (fitted) return fitted;
+
+    // Emergency deterministic reduction: even at perMessageChars=0 the prompt can
+    // overflow when the head carries a very large NUMBER of messages (each still
+    // emits a `N. role` line). Keep only the newest K head messages and collapse
+    // the rest into a single `[K older messages omitted]` stub line, binary
+    // searching the largest K that fits. This bounds the head by COUNT, not just
+    // per-message chars, so a huge-head transcript still yields a minimal prompt
+    // instead of null (which surfaced as a hard compaction throw).
+    const head = Array.isArray(input.head) ? input.head : [];
+    const baseNoFacts = { ...input, preservedFacts: null };
+    const buildReduced = (k) => {
+        const kept = k > 0 ? head.slice(head.length - k) : [];
+        const omitted = head.length - kept.length;
+        const stubHead = omitted > 0
+            ? [{ role: 'user', content: `[${omitted} older messages omitted]` }, ...kept]
+            : kept;
+        let inp = { ...baseNoFacts, head: stubHead };
+        // Also shrink/drop a prior <previous-summary> (same as the normal fitAt
+        // path) — a large prior summary can keep the prompt over budget even at
+        // K=0. fitPreviousSummaryForCompactionPrompt is a no-op when there is no
+        // previousSummary, so this is safe for the summary-less case.
+        if (estimateCompactionPromptTokens(inp, 0) > targetTokens) {
+            const fitted = fitPreviousSummaryForCompactionPrompt(inp, 0, targetTokens);
+            if (!fitted) return null;
+            inp = fitted;
+            if (estimateCompactionPromptTokens(inp, 0) > targetTokens) return null;
+        }
+        return buildCompactionPrompt(inp, 0);
+    };
+    let lo = 0;
+    let hi = head.length;
+    let best = null;
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const candidate = buildReduced(mid);
+        if (candidate) { best = candidate; lo = mid + 1; }
+        else hi = mid - 1;
+    }
+    return best;
 }
 
 function extractResponseText(response) {
@@ -1072,7 +1284,7 @@ function deriveRelevantFilesBullets(head) {
 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)) {
+        if (m?.role === 'user' && !isProtectedContextUserMessage(m) && !isInjectedSkillBodyMessage(m)) {
             const text = truncateMiddle(extractText(m).trim(), 400);
             if (text) return text;
         }
@@ -1263,7 +1475,7 @@ export function buildRecallFastTrackQuery(messages, opts = {}) {
         const text = extractText(m).trim();
         if (!text) continue;
         if (recent.length < 6) recent.unshift(text);
-        if (!latestUser && m?.role === 'user' && !isProtectedContextUserMessage(m)) {
+        if (!latestUser && m?.role === 'user' && !isProtectedContextUserMessage(m) && !isInjectedSkillBodyMessage(m)) {
             latestUser = text;
         }
         if (latestUser && recent.length >= 6) break;
@@ -1443,6 +1655,144 @@ function fitRecallFastTrackSummaryMessage(oldHistory, recallText, remainingToken
     return best;
 }
 
+// --- Smart-compact root-based fitting (arrival-time replacement) -----------
+//
+// dump_session_roots (memory/index.mjs dumpSessionRootChunks) renders chunks
+// TIME-ORDERED (oldest first; chunks.sort by sourceTurn/ts/id ascending),
+// each root/raw block starting with one of:
+//   # chunk N root=ID[ category=X]
+//   # raw_pending N id=ID
+//   # raw_terminal N id=ID
+// and blocks joined by "\n\n". runRecallFastTrackForSession additionally
+// prepends a "session_id=..." / cycle1-drain-status preamble before the dump
+// text (also "\n\n"-joined) — preserved verbatim as a non-block segment.
+//
+// Unlike fitRecallFastTrackSummaryMessage (character-slice binary search,
+// used by the LLM-summary-free but still-mid-turn recall-fasttrack compact
+// path), the smart-compact arrival path must never cut a root block
+// mid-entry — losing half a root's content silently corrupts that entry.
+// This splitter finds block boundaries by the label pattern (robust to
+// blank lines inside member/raw content, since it anchors on the distinctive
+// "# chunk /raw_pending/raw_terminal" line rather than a blank-line split).
+const RECALL_ROOT_BLOCK_HEADER_RE = /^# (?:chunk \d+ root=\d+(?: category=\S+)?|raw_pending \d+ id=\d+|raw_terminal \d+ id=\d+)[ \t]*$/;
+
+export function splitRecallRootBlocks(text) {
+    const value = String(text || '');
+    if (!value.trim()) return { preamble: '', blocks: [] };
+    const re = new RegExp(RECALL_ROOT_BLOCK_HEADER_RE.source, 'gm');
+    const starts = [];
+    let m;
+    while ((m = re.exec(value)) !== null) {
+        starts.push(m.index);
+        if (re.lastIndex === m.index) re.lastIndex += 1; // zero-width guard, defensive
+    }
+    if (starts.length === 0) return { preamble: value.trim(), blocks: [] };
+    const preamble = value.slice(0, starts[0]).trim();
+    const blocks = [];
+    for (let i = 0; i < starts.length; i += 1) {
+        const start = starts[i];
+        const end = i + 1 < starts.length ? starts[i + 1] : value.length;
+        const raw = value.slice(start, end).trim();
+        if (raw) blocks.push(raw);
+    }
+    return { preamble, blocks };
+}
+
+// Minimal-header summary-message wrapper for the smart-compact roots path.
+// Keeps the SUMMARY_PREFIX anchor (isSummaryMessage / selectCompactionWindow
+// / clear-preserve / TUI all key off startsWith(SUMMARY_PREFIX)) but skips the
+// full sha256/roleCounts header line that fitRecallFastTrackSummaryMessage
+// computes — smart-arrival replacement is a lightweight prefix swap, not the
+// anchored LLM-summary compact, so a heavy per-call header is unneeded cost.
+function makeRecallRootsSummaryMessageParts(oldHistory, rootsPart, priorPart, recallMeta = {}) {
+    const header = `${SUMMARY_PREFIX}\nmessages=${(oldHistory || []).length} compact_type=${COMPACT_TYPE_RECALL_FASTTRACK} source=smart-arrival query_sha=${recallMeta.querySha || 'none'}`;
+    const parts = [header];
+    const priorBlock = formatPriorCompactedContextBlock(priorPart);
+    if (priorBlock) parts.push(priorBlock);
+    const roots = String(rootsPart || '').trim();
+    if (roots) parts.push(roots);
+    return makeSummaryMessage(parts.join('\n\n'));
+}
+
+// Root-block-aware fit for the smart-compact arrival path (Step1). Mirrors
+// fitRecallFastTrackSummaryMessage's prior-block binary-search fit, but the
+// recall body is fit at ROOT-BLOCK granularity: when the full set of root
+// blocks (kept in original time order) exceeds remainingTokens, the OLDEST
+// blocks are dropped WHOLE (never character-truncated mid-block) until the
+// remaining (newest-biased) suffix fits. Because dropping more leading
+// blocks can only shrink (never grow) the serialized size, the minimal-drop
+// threshold is found via binary search on the drop count.
+export function fitRecallRootsMessage(oldHistory, recallText, remainingTokens, recallMeta = {}, priorPart = '') {
+    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 = makeRecallRootsSummaryMessageParts(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 = makeRecallRootsSummaryMessageParts(oldHistory, '', RECALL_TAIL_TRUNCATION_MARKER, recallMeta);
+            if (estimateMessagesTokens([markerOnly]) <= remainingTokens) {
+                fittedPrior = RECALL_TAIL_TRUNCATION_MARKER;
+            }
+        }
+    }
+
+    const minimal = makeRecallRootsSummaryMessageParts(oldHistory, '', fittedPrior, recallMeta);
+    if (estimateMessagesTokens([minimal]) > remainingTokens) return null;
+
+    const { preamble, blocks } = splitRecallRootBlocks(recallText);
+    if (blocks.length === 0) {
+        // No parseable root-block boundaries (empty / non-dump recallText) —
+        // degrade to keep-whole-if-it-fits, else drop entirely. Never
+        // mid-truncates: a non-block body is treated as a single atomic unit.
+        const whole = String(recallText || '').trim();
+        if (!whole) return minimal;
+        const full = makeRecallRootsSummaryMessageParts(oldHistory, whole, fittedPrior, recallMeta);
+        if (estimateMessagesTokens([full]) <= remainingTokens) return full;
+        return minimal;
+    }
+
+    let loB = 0;
+    let hiB = blocks.length;
+    let bestLo = -1;
+    while (loB <= hiB) {
+        const mid = Math.floor((loB + hiB) / 2);
+        const kept = blocks.slice(mid);
+        const body = [preamble, ...kept].filter(Boolean).join('\n\n');
+        const candidate = makeRecallRootsSummaryMessageParts(oldHistory, body, fittedPrior, recallMeta);
+        if (estimateMessagesTokens([candidate]) <= remainingTokens) {
+            bestLo = mid;
+            hiB = mid - 1;
+        } else {
+            loB = mid + 1;
+        }
+    }
+    if (bestLo >= 0) {
+        const kept = blocks.slice(bestLo);
+        const body = [preamble, ...kept].filter(Boolean).join('\n\n');
+        return makeRecallRootsSummaryMessageParts(oldHistory, body, fittedPrior, recallMeta);
+    }
+    // Even zero root blocks (preamble alone) overflows alongside the fitted
+    // prior — try preamble alone, else the no-recall minimal header.
+    if (preamble) {
+        const preambleOnly = makeRecallRootsSummaryMessageParts(oldHistory, preamble, fittedPrior, recallMeta);
+        if (estimateMessagesTokens([preambleOnly]) <= remainingTokens) return preambleOnly;
+    }
+    return minimal;
+}
+
 function combinedSignal(parent, timeoutMs) {
     const ms = Number(timeoutMs);
     if (!Number.isFinite(ms) || ms <= 0) return parent || undefined;
@@ -1455,13 +1805,29 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
     if (!provider || typeof provider.send !== 'function') {
         throw new Error('semanticCompactMessages: provider.send is required');
     }
+    const startedAt = Date.now();
     let budget = effectiveBudget(budgetTokens, opts);
     const baseSanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
+    const baseTokens = safeEstimateMessagesTokens(baseSanitized);
     // 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 };
+    if (baseTokens != null && baseTokens <= budget && opts.force !== true) {
+        return {
+            messages: baseSanitized,
+            usage: null,
+            semantic: false,
+            compactType: COMPACT_TYPE_SEMANTIC,
+            diagnostics: {
+                noOp: true,
+                reason: 'fits_budget',
+                inputMessages: Array.isArray(messages) ? messages.length : 0,
+                baseMessages: baseSanitized.length,
+                baseTokens,
+                budgetTokens: budget,
+                durationMs: Date.now() - startedAt,
+            },
+        };
     }
     // Compaction will proceed: redact sensitive tool-call argument VALUES before
     // window selection so the preserved tail/system that survive verbatim are
@@ -1478,6 +1844,7 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
 
     const mandatory = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs([...selected.system, ...selected.tail])));
     const mandatoryCost = estimateMessagesTokens(mandatory);
+    const originalBudget = budget;
     // 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
@@ -1487,6 +1854,7 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
     if (mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS > budget) {
         budget = mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS;
     }
+    const budgetRaisedBy = Math.max(0, budget - originalBudget);
 
     const callBudget = Math.max(1, Math.floor((opts.compactionInputBudgetTokens || budget) * COMPACTION_PROMPT_HEADROOM));
     const prompt = fitCompactionPrompt(selected, callBudget);
@@ -1553,6 +1921,41 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
     if (finalTokens > budget) {
         throw new Error(`semanticCompactMessages: compacted result exceeds budget=${budget} (result=${finalTokens})`);
     }
+    const diagnostics = {
+        noOp: false,
+        inputMessages: Array.isArray(messages) ? messages.length : 0,
+        baseMessages: baseSanitized.length,
+        baseTokens,
+        systemMessages: selected.system.length,
+        headMessages: selected.head.length,
+        originalHeadMessages: selected.originalHead.length,
+        tailMessages: selected.tail.length,
+        mandatoryMessages: mandatory.length,
+        finalMessages: result.length,
+        systemTokens: safeEstimateMessagesTokens(selected.system),
+        headTokens: safeEstimateMessagesTokens(selected.head),
+        tailTokens: safeEstimateMessagesTokens(selected.tail),
+        mandatoryCost,
+        finalTokens,
+        originalBudgetTokens: originalBudget,
+        budgetTokens: budget,
+        budgetRaised: budgetRaisedBy > 0,
+        budgetRaisedBy,
+        remainingTokens: budget - mandatoryCost,
+        callBudgetTokens: callBudget,
+        promptChars: String(prompt || '').length,
+        promptBytes: textByteLength(prompt),
+        promptTokens: safeEstimateMessagesTokens([
+            { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
+            { role: 'user', content: prompt },
+        ]),
+        summaryChars: String(summary || '').length,
+        rawSummaryChars: String(rawSummary || '').length,
+        summaryRepaired: enforced.repaired === true,
+        previousSummary: !!selected.previousSummary,
+        durationMs: Date.now() - startedAt,
+    };
+    compactDebugLog('semantic result', diagnostics);
     return {
         messages: result,
         usage: response?.usage || null,
@@ -1561,6 +1964,7 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
         compactType: COMPACT_TYPE_SEMANTIC,
         summary,
         summaryRepaired: enforced.repaired === true,
+        diagnostics,
     };
 }
 
@@ -1664,7 +2068,54 @@ function fitSingleRecallTurnToCap(turn, cap) {
 function truncateTailToCap(messages, cap) {
     const turn = Array.isArray(messages) ? messages : [];
     if (turn.length === 0) return [];
-    return fitSingleRecallTurnToCap(turn, cap);
+    // No user anchor in this turn: keep the NEWEST messages that fit `cap`,
+    // walking backward. (Previously this delegated back to
+    // fitSingleRecallTurnToCap, which re-entered here on a no-user turn —
+    // infinite mutual recursion. Unreachable while a no-user tail threw upstream;
+    // now that a no-user tail is allowed, this path must terminate on its own.)
+    let out = [];
+    let startIdx = turn.length; // index in `turn` where `out` begins
+    for (let i = turn.length - 1; i >= 0; i -= 1) {
+        const candidate = [turn[i], ...out];
+        if (estimateMessagesTokens(candidate) <= cap) {
+            out = candidate;
+            startIdx = i;
+            continue;
+        }
+        if (out.length === 0) {
+            // Even the newest single message exceeds cap: middle-truncate its
+            // string content so at least one message survives.
+            const m = turn[i];
+            const text = typeof m?.content === 'string' ? m.content : extractText(m);
+            const truncated = truncateMessageForRecallTail(text, Math.max(1, cap * RECALL_TAIL_CHARS_PER_TOKEN));
+            out = [{ ...m, content: truncated }];
+            startIdx = i;
+        }
+        break;
+    }
+    // A leading tool_result with no preceding assistant tool_call is an orphan
+    // that sanitizeToolPairs drops — which could empty the whole tail. Extend the
+    // window backward to swallow the preceding non-tool boundary (the assistant
+    // that owns the tool_call), so the pair survives sanitize. Bounded by
+    // startIdx so it always terminates.
+    while (startIdx > 0 && out[0]?.role === 'tool') {
+        startIdx -= 1;
+        out = [turn[startIdx], ...out];
+    }
+    let sanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(out)));
+    // Final guard: if sanitize still emptied the tail but the turn has a non-tool
+    // message, rebuild from the newest non-tool message forward so the tail is
+    // never empty when preservable content exists.
+    if (sanitized.length === 0) {
+        let nt = -1;
+        for (let i = turn.length - 1; i >= 0; i -= 1) {
+            if (turn[i]?.role !== 'tool') { nt = i; break; }
+        }
+        if (nt >= 0) {
+            sanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(turn.slice(nt))));
+        }
+    }
+    return sanitized;
 }
 
 function stripNestedSummaryHeaderLines(text) {
@@ -1713,10 +2164,10 @@ function selectRecallPreservedTail(live, opts = {}) {
         tail = fitSingleRecallTurnToCap(kept[kept.length - 1], cap);
     }
 
-    if (!tail.some((m) => m?.role === 'user')) {
-        throw new Error('recallFastTrackCompactMessages: preserved tail missing user anchor');
-    }
-
+    // A no-user tail is valid: a single-turn agent session may keep only
+    // assistant/tool structure recently. Mirror the semantic cut-point model —
+    // preserve the recent structured turn(s) verbatim without demanding a user
+    // anchor rather than throwing. tool-pairing is already reconciled above.
     const tailStartIdx = recallTailStartIndex(msgs, tail);
     const head = msgs.slice(0, tailStartIdx);
     return { tail, head, tailStartIdx };
@@ -1730,10 +2181,26 @@ function selectRecallTailUserMessages(tail, opts = {}) {
 }
 
 function _recallFastTrackCompactMessages(messages, budgetTokens, opts = {}) {
+    const startedAt = Date.now();
     let budget = effectiveBudget(budgetTokens, opts);
     const baseSanitized = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs(messages)));
-    if (estimateMessagesTokens(baseSanitized) <= budget && opts.force !== true) {
-        return { messages: baseSanitized, recallFastTrack: false };
+    const baseTokens = safeEstimateMessagesTokens(baseSanitized);
+    if (baseTokens != null && baseTokens <= budget && opts.force !== true) {
+        return {
+            messages: baseSanitized,
+            recallFastTrack: false,
+            compactType: COMPACT_TYPE_RECALL_FASTTRACK,
+            query: opts.query || '',
+            diagnostics: {
+                noOp: true,
+                reason: 'fits_budget',
+                inputMessages: Array.isArray(messages) ? messages.length : 0,
+                baseMessages: baseSanitized.length,
+                baseTokens,
+                budgetTokens: budget,
+                durationMs: Date.now() - startedAt,
+            },
+        };
     }
     const sanitized = redactToolCallSecretsInMessages(baseSanitized);
 
@@ -1751,9 +2218,11 @@ function _recallFastTrackCompactMessages(messages, budgetTokens, opts = {}) {
 
     const mandatory = reconcileDedupStubs(dedupToolResultBodies(sanitizeToolPairs([...safeSystem, ...recallTail])));
     const mandatoryCost = estimateMessagesTokens(mandatory);
+    const originalBudget = budget;
     if (mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS > budget) {
         budget = mandatoryCost + COMPACT_SUMMARY_MIN_ROOM_TOKENS;
     }
+    const budgetRaisedBy = Math.max(0, budget - originalBudget);
 
     if (!recallFit.recall && !recallFit.prior && opts.allowEmptyRecall !== true) {
         throw new Error('recallFastTrackCompactMessages: recall text is empty');
@@ -1779,10 +2248,50 @@ function _recallFastTrackCompactMessages(messages, budgetTokens, opts = {}) {
     if (finalTokens > budget) {
         throw new Error(`recallFastTrackCompactMessages: compacted result exceeds budget=${budget} (result=${finalTokens})`);
     }
+    const summaryContent = String(summaryMessage?.content || '');
+    const diagnostics = {
+        noOp: false,
+        inputMessages: Array.isArray(messages) ? messages.length : 0,
+        baseMessages: baseSanitized.length,
+        baseTokens,
+        systemMessages: safeSystem.length,
+        liveMessages: live.length,
+        headMessages: recallHead.length,
+        tailMessages: recallTail.length,
+        mandatoryMessages: mandatory.length,
+        finalMessages: result.length,
+        systemTokens: safeEstimateMessagesTokens(safeSystem),
+        liveTokens: safeEstimateMessagesTokens(live),
+        headTokens: safeEstimateMessagesTokens(recallHead),
+        tailTokens: safeEstimateMessagesTokens(recallTail),
+        mandatoryCost,
+        finalTokens,
+        originalBudgetTokens: originalBudget,
+        budgetTokens: budget,
+        budgetRaised: budgetRaisedBy > 0,
+        budgetRaisedBy,
+        remainingTokens: budget - mandatoryCost,
+        recallChars: recallFit.recall.length,
+        recallBytes: textByteLength(recallFit.recall),
+        priorChars: recallFit.prior.length,
+        priorBytes: textByteLength(recallFit.prior),
+        summaryMessageChars: summaryContent.length,
+        summaryMessageBytes: textByteLength(summaryContent),
+        recallEmpty: !recallFit.recall,
+        priorEmpty: !recallFit.prior,
+        recallTruncatedInSummary: !!recallFit.recall && !summaryContent.includes(recallFit.recall),
+        priorTruncatedInSummary: !!recallFit.prior && !summaryContent.includes(recallFit.prior),
+        tailTruncated: recallTail.some((m) => messageContentHasMarker(m, RECALL_TAIL_TRUNCATION_MARKER) || messageContentHasMarker(m, RECALL_TAIL_SHORT_TRUNCATION_MARKER)),
+        tailOptions: recallTailOpts,
+        previousSummary: !!previousSummary,
+        durationMs: Date.now() - startedAt,
+    };
+    compactDebugLog('recall-fasttrack result', diagnostics);
     return {
         messages: result,
         recallFastTrack: true,
         compactType: COMPACT_TYPE_RECALL_FASTTRACK,
         query: opts.query || '',
+        diagnostics,
     };
 }