@visorcraft/idlehands 1.1.16 → 1.2.0

package/dist/agent.js

@@ -17,6 +17,7 @@ import { LspManager, detectInstalledLspServers } from './lsp.js';
 import { generateMinimalDiff, toolResultSummary, execCommandFromSig, formatDurationMs, looksLikePlanningNarration, capTextByApproxTokens, isLikelyBinaryBuffer, sanitizePathsInMessage, digestToolResult, } from './agent/formatting.js';
 import { parseToolCallsFromContent, getMissingRequiredParams, getArgValidationIssues, stripMarkdownFences } from './agent/tool-calls.js';
 import { ToolError, ValidationError } from './tools/tool-error.js';
+import { ToolLoopGuard } from './agent/tool-loop-guard.js';
 export { parseToolCallsFromContent };
 import { reviewArtifactKeys, looksLikeCodeReviewRequest, looksLikeReviewRetrievalRequest, retrievalAllowsStaleArtifact, parseReviewArtifactStalePolicy, parseReviewArtifact, reviewArtifactStaleReason, gitHead, normalizeModelsResponse, } from './agent/review-artifact.js';
 import fs from 'node:fs/promises';
@@ -28,7 +29,12 @@ function makeAbortController() {
 }
 const CACHED_EXEC_OBSERVATION_HINT = '[idlehands hint] Reused cached output for repeated read-only exec call (unchanged observation).';
 function looksLikeReadOnlyExecCommand(command) {
-    const cmd = String(command || '').trim().toLowerCase();
+    // Strip leading `cd <path> &&` / `cd <path>;` prefixes — cd is read-only
+    // navigation, the actual command that matters comes after.
+    let cmd = String(command || '').trim().toLowerCase();
+    if (!cmd)
+        return false;
+    cmd = cmd.replace(/^(\s*cd\s+[^;&|]+\s*(?:&&|;)\s*)+/i, '').trim();
     if (!cmd)
         return false;
     // Shell redirects are likely writes.
@@ -98,6 +104,25 @@ function withCachedExecObservationHint(content) {
         return `${content}\n${CACHED_EXEC_OBSERVATION_HINT}`;
     }
 }
+const REPLAYED_EXEC_HINT = '[idlehands hint] You already ran this exact command. This is the replayed result from your previous execution. Do NOT re-run it — use the output below to continue your task.';
+function withReplayedExecHint(content) {
+    if (!content)
+        return content;
+    try {
+        const parsed = JSON.parse(content);
+        const out = typeof parsed?.out === 'string' ? parsed.out : '';
+        if (out.includes(REPLAYED_EXEC_HINT))
+            return content;
+        parsed.out = out ? `${REPLAYED_EXEC_HINT}\n${out}` : REPLAYED_EXEC_HINT;
+        parsed.replayed = true;
+        return JSON.stringify(parsed);
+    }
+    catch {
+        if (content.includes(REPLAYED_EXEC_HINT))
+            return content;
+        return `${REPLAYED_EXEC_HINT}\n${content}`;
+    }
+}
 function readOnlyExecCacheable(content) {
     try {
         const parsed = JSON.parse(content);
@@ -116,6 +141,15 @@ function ensureInformativeAssistantText(text, ctx) {
     }
     return `I have no user-visible response text for this turn (turn=${ctx.turns}). Please try again or rephrase your request.`;
 }
+function isContextWindowExceededError(err) {
+    const status = Number(err?.status ?? NaN);
+    const msg = String(err?.message ?? err ?? '');
+    if (status === 413)
+        return true;
+    if (!msg)
+        return false;
+    return /(exceeds?\s+the\s+available\s+context\s+size|exceed_context|context\s+size|context\s+window|maximum\s+context\s+length|too\s+many\s+tokens|request\s*\(\d+\s*tokens\))/i.test(msg);
+}
 /** Errors that should break the outer agent loop, not be caught by per-tool handlers */
 class AgentLoopBreak extends Error {
     constructor(message) {
@@ -133,6 +167,7 @@ Rules:
 - Use read_file with search=... to jump to relevant code; avoid reading whole files.
 - Never call read_file/read_files/list_dir twice in a row with identical arguments (same path/options). Reuse the previous result instead.
 - Prefer apply_patch or edit_range for code edits (token-efficient). Use edit_file only when exact old_text replacement is necessary.
+- write_file is for new files or explicit full rewrites only. Existing non-empty files require overwrite=true/force=true.
 - Use insert_file for insertions (prepend/append/line).
 - Use exec to run commands, tests, builds; check results before reporting success.
 - When running commands in a subdirectory, use exec's cwd parameter — NOT "cd /path && cmd". Each exec call is a fresh shell; cd does not persist.
@@ -305,8 +340,8 @@ function buildToolsSchema(opts) {
             type: 'function',
             function: {
                 name: 'write_file',
-                description: 'Write file (atomic, backup).',
-                parameters: obj({ path: str(), content: str() }, ['path', 'content']),
+                description: 'Write file (atomic, backup). Existing non-empty files require overwrite=true (or force=true).',
+                parameters: obj({ path: str(), content: str(), overwrite: bool(), force: bool() }, ['path', 'content']),
             },
         },
         {
@@ -404,6 +439,11 @@ function buildToolsSchema(opts) {
     if (opts?.activeVaultTools) {
         schemas.push({ type: 'function', function: { name: 'vault_search', description: 'Search vault.', parameters: obj({ query: str(), limit: int() }, ['query']) } }, { type: 'function', function: { name: 'vault_note', description: 'Write vault note.', parameters: obj({ key: str(), value: str() }, ['key', 'value']) } });
     }
+    else if (opts?.passiveVault) {
+        // In passive mode, expose vault_search (read-only) so the model can recover
+        // compacted context on demand, but don't expose vault_note (write).
+        schemas.push({ type: 'function', function: { name: 'vault_search', description: 'Search vault memory for earlier context that was compacted away. Use sparingly — only when you need to recall specific details from earlier in the conversation.', parameters: obj({ query: str(), limit: int() }, ['query']) } });
+    }
     // Phase 9: sys_context tool is only available in sys mode.
     if (opts?.sysMode) {
         schemas.push(SYS_CONTEXT_SCHEMA);
@@ -648,6 +688,7 @@ export async function createSession(opts) {
     let mcpToolsLoaded = !mcpLazySchemaMode;
     const getToolsSchema = () => buildToolsSchema({
         activeVaultTools,
+        passiveVault: !activeVaultTools && vaultEnabled && vaultMode === 'passive',
         sysMode: cfg.mode === 'sys',
         lspTools: lspManager?.hasServers() === true,
         mcpTools: mcpToolsLoaded ? (mcpManager?.getEnabledToolSchemas() ?? []) : [],
@@ -1155,21 +1196,68 @@ export async function createSession(opts) {
     const clearPlan = () => {
         planSteps = [];
     };
+    const getLatestObjectiveText = () => {
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const m = messages[i];
+            if (m.role !== 'user')
+                continue;
+            const text = userContentToText((m.content ?? '')).trim();
+            if (!text)
+                continue;
+            if (text.startsWith('[system]'))
+                continue;
+            if (text.startsWith('[Trifecta Vault'))
+                continue;
+            if (text.startsWith('[Vault context'))
+                continue;
+            return text;
+        }
+        return '';
+    };
+    const compactionVaultGuidance = () => {
+        if (!vault)
+            return '';
+        if (vaultMode === 'active' || activeVaultTools) {
+            return 'Vault memory is available. Retrieve prior context with vault_search(query="...") when needed.';
+        }
+        if (vaultMode === 'passive') {
+            return 'Vault memory is in passive mode; relevant entries may be auto-injected. You can also use vault_search(query="...") to recover specific earlier context if needed.';
+        }
+        return '';
+    };
+    const buildCompactionSystemNote = (kind, dropped) => {
+        const prefix = kind === 'auto'
+            ? `[auto-compacted: ${dropped} old messages dropped to stay within context budget.]`
+            : `[compacted: ${dropped} messages dropped.]`;
+        const guidance = compactionVaultGuidance();
+        return guidance ? `${prefix} ${guidance}` : prefix;
+    };
+    let lastAskInstructionText = '';
+    let lastCompactionReminderObjective = '';
+    const injectCompactionReminder = (reason) => {
+        const objective = (getLatestObjectiveText() || lastAskInstructionText || '').trim();
+        if (!objective)
+            return;
+        const clippedObjective = objective.length > 1600 ? `${objective.slice(0, 1600)}\n[truncated]` : objective;
+        if (clippedObjective === lastCompactionReminderObjective)
+            return;
+        lastCompactionReminderObjective = clippedObjective;
+        const vaultHint = compactionVaultGuidance();
+        messages.push({
+            role: 'user',
+            content: `[system] Context was compacted (${reason}). Continue the SAME task from the current state; do not restart.\n` +
+                `Most recent user objective:\n${clippedObjective}` +
+                (vaultHint ? `\n\n${vaultHint}` : ''),
+        });
+    };
     // Session-level vault context injection: search vault for entries relevant to
-    // the last user message and inject them into the conversation. Used after any
-    // compaction to restore context the model lost when messages were dropped.
+    // the latest substantive objective and inject them into the conversation.
+    // Used after compaction to restore context the model lost when messages were dropped.
     let lastVaultInjectionQuery = '';
     const injectVaultContext = async () => {
         if (!vault)
             return;
-        let lastUser = null;
-        for (let j = messages.length - 1; j >= 0; j--) {
-            if (messages[j].role === 'user') {
-                lastUser = messages[j];
-                break;
-            }
-        }
-        const userText = userContentToText((lastUser?.content ?? '')).trim();
+        const userText = (getLatestObjectiveText() || lastAskInstructionText || '').trim();
         if (!userText)
             return;
         const query = userText.slice(0, 200);
@@ -1190,77 +1278,150 @@ export async function createSession(opts) {
             content: `${vaultContextHeader} Relevant entries for "${query}":\n${lines.join('\n')}`
         });
     };
-    const compactHistory = async (opts) => {
-        const beforeMessages = messages.length;
-        const beforeTokens = estimateTokensFromMessages(messages);
-        let compacted;
-        if (opts?.hard) {
-            const sys = messages[0]?.role === 'system' ? [messages[0]] : [];
-            const tail = messages.slice(-2);
-            compacted = [...sys, ...tail];
+    let compactionLockTail = Promise.resolve();
+    let compactionStats = {
+        inProgress: false,
+        lockHeld: false,
+        runs: 0,
+        failedRuns: 0,
+        beforeMessages: 0,
+        afterMessages: 0,
+        freedTokens: 0,
+        archivedToolMessages: 0,
+        droppedMessages: 0,
+        dryRun: false,
+    };
+    const runCompactionWithLock = async (reason, runner) => {
+        const prev = compactionLockTail;
+        let release = () => { };
+        compactionLockTail = new Promise((resolve) => {
+            release = () => resolve();
+        });
+        await prev;
+        compactionStats = {
+            ...compactionStats,
+            inProgress: true,
+            lockHeld: true,
+            lastReason: reason,
+            lastError: undefined,
+            updatedAt: new Date().toISOString(),
+            // Reset run stats before fresh calculation.
+            beforeMessages: 0,
+            afterMessages: 0,
+            freedTokens: 0,
+            archivedToolMessages: 0,
+            droppedMessages: 0,
+            dryRun: false,
+        };
+        try {
+            const result = await runner();
+            compactionStats = {
+                ...compactionStats,
+                ...result,
+                inProgress: false,
+                lockHeld: false,
+                runs: compactionStats.runs + 1,
+                lastReason: reason,
+                updatedAt: new Date().toISOString(),
+            };
+            return result;
         }
-        else {
-            compacted = enforceContextBudget({
-                messages,
-                contextWindow,
-                maxTokens,
-                minTailMessages: opts?.force ? 2 : 12,
-                compactAt: opts?.force ? 0.5 : (cfg.compact_at ?? 0.8),
-                toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
-                force: opts?.force,
-            });
+        catch (e) {
+            compactionStats = {
+                ...compactionStats,
+                inProgress: false,
+                lockHeld: false,
+                failedRuns: compactionStats.failedRuns + 1,
+                lastReason: reason,
+                lastError: e?.message ?? String(e),
+                updatedAt: new Date().toISOString(),
+            };
+            throw e;
         }
-        const compactedByRefs = new Set(compacted);
-        let dropped = messages.filter((m) => !compactedByRefs.has(m));
-        if (opts?.topic) {
-            const topic = opts.topic.toLowerCase();
-            dropped = dropped.filter((m) => !userContentToText(m.content ?? '').toLowerCase().includes(topic));
-            const keepFromTopic = messages.filter((m) => userContentToText(m.content ?? '').toLowerCase().includes(topic));
-            compacted = [...compacted, ...keepFromTopic.filter((m) => !compactedByRefs.has(m))];
+        finally {
+            release();
         }
-        const archivedToolMessages = dropped.filter((m) => m.role === 'tool').length;
-        const afterMessages = compacted.length;
-        const afterTokens = estimateTokensFromMessages(compacted);
-        const freedTokens = Math.max(0, beforeTokens - afterTokens);
-        if (!opts?.dry) {
-            if (dropped.length && vault) {
-                try {
-                    // Store the original/current user prompt before compaction so it survives context loss.
-                    let userPromptToPreserve = null;
-                    for (let i = messages.length - 1; i >= 0; i--) {
-                        const m = messages[i];
-                        if (m.role === 'user') {
-                            const text = userContentToText((m.content ?? '')).trim();
-                            if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
-                                userPromptToPreserve = text;
-                                break;
+    };
+    const compactHistory = async (opts) => {
+        const reason = opts?.reason
+            ?? (opts?.hard ? 'manual hard compaction'
+                : opts?.force ? 'manual force compaction'
+                    : 'manual compaction');
+        return await runCompactionWithLock(reason, async () => {
+            const beforeMessages = messages.length;
+            const beforeTokens = estimateTokensFromMessages(messages);
+            let compacted;
+            if (opts?.hard) {
+                const sys = messages[0]?.role === 'system' ? [messages[0]] : [];
+                const tail = messages.slice(-2);
+                compacted = [...sys, ...tail];
+            }
+            else {
+                compacted = enforceContextBudget({
+                    messages,
+                    contextWindow,
+                    maxTokens,
+                    minTailMessages: opts?.force ? 2 : 12,
+                    compactAt: opts?.force ? 0.5 : (cfg.compact_at ?? 0.8),
+                    toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
+                    force: opts?.force,
+                });
+            }
+            const compactedByRefs = new Set(compacted);
+            let dropped = messages.filter((m) => !compactedByRefs.has(m));
+            if (opts?.topic) {
+                const topic = opts.topic.toLowerCase();
+                dropped = dropped.filter((m) => !userContentToText(m.content ?? '').toLowerCase().includes(topic));
+                const keepFromTopic = messages.filter((m) => userContentToText(m.content ?? '').toLowerCase().includes(topic));
+                compacted = [...compacted, ...keepFromTopic.filter((m) => !compactedByRefs.has(m))];
+            }
+            const archivedToolMessages = dropped.filter((m) => m.role === 'tool').length;
+            const afterMessages = compacted.length;
+            const afterTokens = estimateTokensFromMessages(compacted);
+            const freedTokens = Math.max(0, beforeTokens - afterTokens);
+            if (!opts?.dry) {
+                if (dropped.length && vault) {
+                    try {
+                        // Store the original/current user prompt before compaction so it survives context loss.
+                        let userPromptToPreserve = null;
+                        for (let i = messages.length - 1; i >= 0; i--) {
+                            const m = messages[i];
+                            if (m.role === 'user') {
+                                const text = userContentToText((m.content ?? '')).trim();
+                                if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
+                                    userPromptToPreserve = text;
+                                    break;
+                                }
                             }
                         }
+                        if (userPromptToPreserve) {
+                            await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                        }
+                        await vault.archiveToolMessages(dropped, new Map());
+                        await vault.note('compaction_summary', `Dropped ${dropped.length} messages (${freedTokens} tokens).`);
                     }
-                    if (userPromptToPreserve) {
-                        await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                    catch {
+                        // best-effort
                     }
-                    await vault.archiveToolMessages(dropped, new Map());
-                    await vault.note('compaction_summary', `Dropped ${dropped.length} messages (${freedTokens} tokens).`);
                 }
-                catch {
-                    // best-effort
+                messages = compacted;
+                if (dropped.length) {
+                    messages.push({ role: 'system', content: buildCompactionSystemNote('manual', dropped.length) });
+                    await injectVaultContext().catch(() => { });
+                    if (opts?.reason || opts?.force) {
+                        injectCompactionReminder(opts?.reason ?? 'history compaction');
+                    }
                 }
             }
-            messages = compacted;
-            if (dropped.length) {
-                messages.push({ role: 'system', content: `[compacted: ${dropped.length} messages archived to Vault - vault_search to recall]` });
-                await injectVaultContext().catch(() => { });
-            }
-        }
-        return {
-            beforeMessages,
-            afterMessages,
-            freedTokens,
-            archivedToolMessages,
-            droppedMessages: dropped.length,
-            dryRun: !!opts?.dry,
-        };
+            return {
+                beforeMessages,
+                afterMessages,
+                freedTokens,
+                archivedToolMessages,
+                droppedMessages: dropped.length,
+                dryRun: !!opts?.dry,
+            };
+        });
     };
     const cumulativeUsage = { prompt: 0, completion: 0 };
     const turnDurationsMs = [];
@@ -1269,6 +1430,17 @@ export async function createSession(opts) {
     const tgSamples = [];
     let lastTurnMetrics;
     let lastServerHealth;
+    let lastToolLoopStats = { totalHistory: 0, signatures: [], outcomes: [], telemetry: {
+            callsRegistered: 0,
+            dedupedReplays: 0,
+            readCacheLookups: 0,
+            readCacheHits: 0,
+            warnings: 0,
+            criticals: 0,
+            recoveryRecommended: 0,
+            readCacheHitRate: 0,
+            dedupeRate: 0,
+        } };
     let lastModelsProbeMs = 0;
     const capturesDir = path.join(stateDir(), 'captures');
     let captureEnabled = false;
@@ -1617,6 +1789,10 @@ export async function createSession(opts) {
             await hookObj.onToolResult?.(result);
             await hookManager.emit('tool_result', { askId, turn: turns, result });
         };
+        const emitToolLoop = async (loop) => {
+            await hookObj.onToolLoop?.(loop);
+            await hookManager.emit('tool_loop', { askId, turn: turns, loop });
+        };
         const emitTurnEnd = async (stats) => {
             await hookObj.onTurnEnd?.(stats);
             await hookManager.emit('turn_end', { askId, stats });
@@ -1627,6 +1803,8 @@ export async function createSession(opts) {
             return { text: finalText, turns, toolCalls };
         };
         const rawInstructionText = userContentToText(instruction).trim();
+        lastAskInstructionText = rawInstructionText;
+        lastCompactionReminderObjective = '';
         await hookManager.emit('ask_start', { askId, instruction: rawInstructionText });
         const projectDir = cfg.dir ?? process.cwd();
         const reviewKeys = reviewArtifactKeys(projectDir);
@@ -1750,12 +1928,50 @@ export async function createSession(opts) {
         const blockedExecAttemptsBySig = new Map();
         // Cache successful read-only exec observations by exact signature.
         const execObservationCacheBySig = new Map();
+        // Cache ALL successful exec results so repeated identical calls under context
+        // pressure can replay the cached result instead of re-executing.
+        const lastExecResultBySig = new Map();
+        // Cache successful read_file/read_files/list_dir results by signature + mtime for invalidation.
+        const readFileCacheBySig = new Map();
+        const READ_FILE_CACHE_TOOLS = new Set(['read_file', 'read_files', 'list_dir']);
+        const toolLoopGuard = new ToolLoopGuard({
+            enabled: cfg.tool_loop_detection?.enabled,
+            historySize: cfg.tool_loop_detection?.history_size,
+            warningThreshold: cfg.tool_loop_detection?.warning_threshold,
+            criticalThreshold: cfg.tool_loop_detection?.critical_threshold,
+            globalCircuitBreakerThreshold: cfg.tool_loop_detection?.global_circuit_breaker_threshold,
+            readCacheTtlMs: cfg.tool_loop_detection?.read_cache_ttl_ms,
+            detectors: {
+                genericRepeat: cfg.tool_loop_detection?.detectors?.generic_repeat,
+                knownPollNoProgress: cfg.tool_loop_detection?.detectors?.known_poll_no_progress,
+                pingPong: cfg.tool_loop_detection?.detectors?.ping_pong,
+            },
+            perTool: Object.fromEntries(Object.entries(cfg.tool_loop_detection?.per_tool ?? {}).map(([tool, policy]) => [
+                tool,
+                {
+                    warningThreshold: policy?.warning_threshold,
+                    criticalThreshold: policy?.critical_threshold,
+                    globalCircuitBreakerThreshold: policy?.global_circuit_breaker_threshold,
+                    detectors: {
+                        genericRepeat: policy?.detectors?.generic_repeat,
+                        knownPollNoProgress: policy?.detectors?.known_poll_no_progress,
+                        pingPong: policy?.detectors?.ping_pong,
+                    },
+                },
+            ])),
+        });
+        const toolLoopWarningKeys = new Set();
+        let forceToollessRecoveryTurn = false;
+        let toollessRecoveryUsed = false;
         // Prevent repeating the same "stop rerunning" reminder every turn.
         const readOnlyExecHintedSigs = new Set();
         // Keep a lightweight breadcrumb for diagnostics on partial failures.
         let lastSuccessfulTestRun = null;
         // One-time nudge to prevent post-success churn after green test runs.
         let finalizeAfterTestsNudgeUsed = false;
+        // Recover once/twice from server-side context-overflow 400/413s by forcing compaction and retrying.
+        let overflowCompactionAttempts = 0;
+        const MAX_OVERFLOW_COMPACTION_ATTEMPTS = 2;
         const archiveToolOutputForVault = async (msg) => {
             if (!lens || !vault || msg.role !== 'tool' || typeof msg.content !== 'string')
                 return msg;
@@ -1869,50 +2085,63 @@ export async function createSession(opts) {
                     throw new Error(`session timeout exceeded (${cfg.timeout}s) after ${wallElapsed.toFixed(1)}s`);
                 }
                 await maybeAutoDetectModelChange();
-                const beforeMsgs = messages;
-                const compacted = enforceContextBudget({
-                    messages: beforeMsgs,
-                    contextWindow,
-                    maxTokens: maxTokens,
-                    minTailMessages: 12,
-                    compactAt: cfg.compact_at ?? 0.8,
-                    toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
-                });
-                const compactedByRefs = new Set(compacted);
-                const dropped = beforeMsgs.filter((m) => !compactedByRefs.has(m));
-                if (dropped.length && vault) {
-                    try {
-                        // Store the original/current user prompt before compaction so it survives context loss.
-                        // Find the last substantive user message that looks like a task/instruction.
-                        let userPromptToPreserve = null;
-                        for (let i = beforeMsgs.length - 1; i >= 0; i--) {
-                            const m = beforeMsgs[i];
-                            if (m.role === 'user') {
-                                const text = userContentToText((m.content ?? '')).trim();
-                                // Skip vault injection messages and short prompts
-                                if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
-                                    userPromptToPreserve = text;
-                                    break;
+                await runCompactionWithLock('auto context-budget compaction', async () => {
+                    const beforeMsgs = messages;
+                    const beforeTokens = estimateTokensFromMessages(beforeMsgs);
+                    const compacted = enforceContextBudget({
+                        messages: beforeMsgs,
+                        contextWindow,
+                        maxTokens: maxTokens,
+                        minTailMessages: 12,
+                        compactAt: cfg.compact_at ?? 0.8,
+                        toolSchemaTokens: estimateToolSchemaTokens(getToolsSchema()),
+                    });
+                    const compactedByRefs = new Set(compacted);
+                    const dropped = beforeMsgs.filter((m) => !compactedByRefs.has(m));
+                    if (dropped.length && vault) {
+                        try {
+                            // Store the original/current user prompt before compaction so it survives context loss.
+                            // Find the last substantive user message that looks like a task/instruction.
+                            let userPromptToPreserve = null;
+                            for (let i = beforeMsgs.length - 1; i >= 0; i--) {
+                                const m = beforeMsgs[i];
+                                if (m.role === 'user') {
+                                    const text = userContentToText((m.content ?? '')).trim();
+                                    // Skip vault injection messages and short prompts
+                                    if (text && !text.startsWith('[Trifecta Vault') && !text.startsWith('[Vault context') && text.length > 20) {
+                                        userPromptToPreserve = text;
+                                        break;
+                                    }
                                 }
                             }
+                            if (userPromptToPreserve) {
+                                await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                            }
+                            const toArchive = lens
+                                ? await Promise.all(dropped.map((m) => archiveToolOutputForVault(m)))
+                                : dropped;
+                            await vault.archiveToolMessages(toArchive, toolNameByCallId);
                         }
-                        if (userPromptToPreserve) {
-                            await vault.upsertNote('current_task', userPromptToPreserve.slice(0, 2000), 'system');
+                        catch (e) {
+                            console.warn(`[warn] vault archive failed: ${e instanceof Error ? e.message : String(e)}`);
                         }
-                        const toArchive = lens
-                            ? await Promise.all(dropped.map((m) => archiveToolOutputForVault(m)))
-                            : dropped;
-                        await vault.archiveToolMessages(toArchive, toolNameByCallId);
                     }
-                    catch (e) {
-                        console.warn(`[warn] vault archive failed: ${e instanceof Error ? e.message : String(e)}`);
+                    messages = compacted;
+                    if (dropped.length) {
+                        messages.push({ role: 'system', content: buildCompactionSystemNote('auto', dropped.length) });
+                        await injectVaultContext().catch(() => { });
+                        injectCompactionReminder('auto context-budget compaction');
                     }
-                }
-                messages = compacted;
-                if (dropped.length) {
-                    messages.push({ role: 'system', content: `[auto-compacted: ${dropped.length} old messages dropped to stay within context budget. Do NOT re-read files or re-run commands you have already seen — use vault_search to recall prior results if needed.]` });
-                    await injectVaultContext().catch(() => { });
-                }
+                    const afterTokens = estimateTokensFromMessages(compacted);
+                    return {
+                        beforeMessages: beforeMsgs.length,
+                        afterMessages: compacted.length,
+                        freedTokens: Math.max(0, beforeTokens - afterTokens),
+                        archivedToolMessages: dropped.filter((m) => m.role === 'tool').length,
+                        droppedMessages: dropped.length,
+                        dryRun: false,
+                    };
+                });
                 const ac = makeAbortController();
                 inFlight = ac;
                 // If caller provided an AbortSignal (bench iteration timeout, etc), propagate it.
@@ -1936,20 +2165,45 @@ export async function createSession(opts) {
                 };
                 let resp;
                 try {
-                    resp = await client.chatStream({
-                        model,
-                        messages,
-                        tools: getToolsSchema(),
-                        tool_choice: 'auto',
-                        temperature,
-                        top_p: topP,
-                        max_tokens: maxTokens,
-                        extra: { cache_prompt: cfg.cache_prompt ?? true },
-                        signal: ac.signal,
-                        requestId: `r${reqCounter}`,
-                        onToken: hookObj.onToken,
-                        onFirstDelta,
-                    });
+                    try {
+                        const toolsForTurn = forceToollessRecoveryTurn ? [] : getToolsSchema();
+                        const toolChoiceForTurn = forceToollessRecoveryTurn ? 'none' : 'auto';
+                        resp = await client.chatStream({
+                            model,
+                            messages,
+                            tools: toolsForTurn,
+                            tool_choice: toolChoiceForTurn,
+                            temperature,
+                            top_p: topP,
+                            max_tokens: maxTokens,
+                            extra: { cache_prompt: cfg.cache_prompt ?? true },
+                            signal: ac.signal,
+                            requestId: `r${reqCounter}`,
+                            onToken: hookObj.onToken,
+                            onFirstDelta,
+                        });
+                        // Successful response resets overflow recovery budget.
+                        overflowCompactionAttempts = 0;
+                    }
+                    catch (e) {
+                        if (isContextWindowExceededError(e) && overflowCompactionAttempts < MAX_OVERFLOW_COMPACTION_ATTEMPTS) {
+                            overflowCompactionAttempts++;
+                            const useHardCompaction = overflowCompactionAttempts > 1;
+                            const compacted = await compactHistory({
+                                force: true,
+                                hard: useHardCompaction,
+                                reason: 'server context-window overflow recovery',
+                            });
+                            const mode = useHardCompaction ? 'hard' : 'force';
+                            messages.push({
+                                role: 'system',
+                                content: `[auto-recovery] Previous request exceeded model context window. Ran ${mode} compaction ` +
+                                    `(freed ~${compacted.freedTokens} tokens, dropped ${compacted.droppedMessages} messages). Continue from latest state; do not restart work.`,
+                            });
+                            continue;
+                        }
+                        throw e;
+                    }
                 }
                 finally {
                     clearTimeout(timer);
@@ -2008,6 +2262,8 @@ export async function createSession(opts) {
                         },
                     }
                     : undefined;
+                const wasToollessRecoveryTurn = forceToollessRecoveryTurn;
+                forceToollessRecoveryTurn = false;
                 const choice0 = resp.choices?.[0] ?? legacyChoice;
                 const finishReason = choice0?.finish_reason ?? 'unknown';
                 const msg = choice0?.message;
@@ -2058,6 +2314,10 @@ export async function createSession(opts) {
                         }
                     }
                 }
+                if (wasToollessRecoveryTurn && toolCallsArr?.length) {
+                    // Recovery turn explicitly disables tools; ignore any stray tool-call output.
+                    toolCallsArr = undefined;
+                }
                 if (cfg.verbose) {
                     console.warn(`[turn ${turns}] finish_reason=${finishReason} content_chars=${content.length} visible_chars=${visible.length} tool_calls=${toolCallsArr?.length ?? 0}`);
                 }
@@ -2136,12 +2396,17 @@ export async function createSession(opts) {
                     // narration chunk starts on a fresh line (avoids wall-of-text output).
                     if (visible && hookObj.onToken)
                         hookObj.onToken('\n');
-                    toolCalls += toolCallsArr.length;
+                    const originalToolCallsArr = toolCallsArr;
+                    const preparedTurn = toolLoopGuard.prepareTurn(originalToolCallsArr);
+                    const replayByCallId = preparedTurn.replayByCallId;
+                    const parsedArgsByCallId = preparedTurn.parsedArgsByCallId;
+                    toolCallsArr = preparedTurn.uniqueCalls;
+                    toolCalls += originalToolCallsArr.length;
                     const assistantToolCallText = visible || '';
                     const compactAssistantToolCallText = assistantToolCallText.length > 900
                         ? `${assistantToolCallText.slice(0, 900)}\n[history-compacted: assistant narration truncated before tool execution]`
                         : assistantToolCallText;
-                    messages.push({ role: 'assistant', content: compactAssistantToolCallText, tool_calls: toolCallsArr });
+                    messages.push({ role: 'assistant', content: compactAssistantToolCallText, tool_calls: originalToolCallsArr });
                     // sigCounts is scoped to the entire ask() run (see above)
                     // Bridge ConfirmationProvider → legacy confirm callback for tools.
                     // If a ConfirmationProvider is given, wrap it; otherwise fall back to raw callback.
@@ -2185,18 +2450,64 @@ export async function createSession(opts) {
                     // We only treat repeated exec as a loop if no file mutations happened since the
                     // last time we saw that exact exec signature.
                     const turnSigs = new Set();
+                    const sigMetaBySig = new Map();
                     for (const tc of toolCallsArr) {
-                        const sig = `${tc.function.name}:${tc.function.arguments ?? '{}'}`;
+                        const callId = resolveCallId(tc);
+                        const parsedArgs = parsedArgsByCallId.get(callId) ?? {};
+                        const sig = toolLoopGuard.computeSignature(tc.function.name, parsedArgs);
                         turnSigs.add(sig);
+                        if (!sigMetaBySig.has(sig)) {
+                            sigMetaBySig.set(sig, { toolName: tc.function.name, args: parsedArgs });
+                        }
                     }
                     // Repeated read-only exec calls can be served from cache instead of hard-breaking.
                     const repeatedReadOnlyExecSigs = new Set();
                     const readOnlyExecTurnHints = [];
+                    // Repeated exec calls (any kind) can replay cached results under pressure.
+                    const replayExecSigs = new Set();
+                    // Repeated read_file/read_files/list_dir calls can be served from cache.
+                    const repeatedReadFileSigs = new Set();
+                    let shouldForceToollessRecovery = false;
+                    const criticalLoopSigs = new Set();
+                    for (const tc of toolCallsArr) {
+                        const callId = resolveCallId(tc);
+                        const args = parsedArgsByCallId.get(callId) ?? {};
+                        const detected = toolLoopGuard.detect(tc.function.name, args);
+                        const warning = toolLoopGuard.formatWarning(detected, tc.function.name);
+                        if (warning) {
+                            const warningKey = `${warning.level}:${warning.detector}:${detected.signature}`;
+                            if (!toolLoopWarningKeys.has(warningKey)) {
+                                toolLoopWarningKeys.add(warningKey);
+                                await emitToolLoop({
+                                    level: warning.level,
+                                    detector: warning.detector,
+                                    toolName: warning.toolName,
+                                    count: warning.count,
+                                    message: warning.message,
+                                });
+                                messages.push({
+                                    role: 'system',
+                                    content: `[tool-loop ${warning.level}] ${warning.message}. Stop repeating ${warning.toolName} with unchanged inputs; continue with analysis or next step.`,
+                                });
+                            }
+                        }
+                        if (toolLoopGuard.shouldDisableToolsNextTurn(detected)) {
+                            shouldForceToollessRecovery = true;
+                            criticalLoopSigs.add(detected.signature);
+                        }
+                    }
                     // Track whether a mutation happened since a given signature was last seen.
                     // (Tool-loop is single-threaded across turns; this is safe to keep in-memory.)
                     for (const sig of turnSigs) {
                         sigCounts.set(sig, (sigCounts.get(sig) ?? 0) + 1);
-                        const toolName = sig.split(':')[0];
+                        const sigMeta = sigMetaBySig.get(sig);
+                        const toolName = sigMeta?.toolName ?? sig.split(':')[0];
+                        if (criticalLoopSigs.has(sig)) {
+                            // Critical detector already fired for this signature; recover next turn
+                            // with tools disabled instead of throwing in per-tool hard-break logic.
+                            shouldForceToollessRecovery = true;
+                            continue;
+                        }
                         // For exec loops, only break if nothing changed since last identical exec.
                         if (toolName === 'exec') {
                             // If this exact exec signature was seen before, record the mutation version at that time.
@@ -2207,6 +2518,18 @@ export async function createSession(opts) {
                             mutationVersionBySig.set(sig, mutationVersion);
                             if (!hasMutatedSince) {
                                 const count = sigCounts.get(sig) ?? 0;
+                                // Early replay: if this exact exec was already run (count >= 2) and
+                                // we have a cached result, replay it instead of re-executing.  This
+                                // prevents the compaction death spiral where tool results get dropped,
+                                // the model forgets it ran the command, and re-runs it endlessly.
+                                // Skip read-only commands that already have their own observation cache —
+                                // those are handled by the dedicated read-only path at loopThreshold.
+                                const command = execCommandFromSig(sig);
+                                const hasReadOnlyCache = looksLikeReadOnlyExecCommand(command) && execObservationCacheBySig.has(sig);
+                                if (count >= 2 && lastExecResultBySig.has(sig) && !hasReadOnlyCache) {
+                                    replayExecSigs.add(sig);
+                                    continue;
+                                }
                                 let loopThreshold = harness.quirks.loopsOnToolError ? 3 : 6;
                                 // If the cached observation already tells the model "no matches found",
                                 // break much earlier — the model is ignoring the hint.
@@ -2219,7 +2542,8 @@ export async function createSession(opts) {
                                     await injectVaultContext().catch(() => { });
                                 }
                                 if (count >= loopThreshold) {
-                                    const command = execCommandFromSig(sig);
+                                    const sigArgs = sigMetaBySig.get(sig)?.args ?? {};
+                                    const command = typeof sigArgs?.command === 'string' ? String(sigArgs.command) : '';
                                     const canReuseReadOnlyObservation = looksLikeReadOnlyExecCommand(command) &&
                                         execObservationCacheBySig.has(sig);
                                     if (canReuseReadOnlyObservation) {
@@ -2230,8 +2554,8 @@ export async function createSession(opts) {
                                         }
                                         continue;
                                     }
-                                    const args = sig.slice(toolName.length + 1);
-                                    const argsPreview = args.length > 220 ? args.slice(0, 220) + '…' : args;
+                                    const argsPreviewRaw = JSON.stringify(sigArgs);
+                                    const argsPreview = argsPreviewRaw.length > 220 ? argsPreviewRaw.slice(0, 220) + '…' : argsPreviewRaw;
                                     throw new Error(`tool ${toolName}: identical call repeated ${loopThreshold}x across turns; breaking loop. ` +
                                         `args=${argsPreview}`);
                                 }
@@ -2250,7 +2574,9 @@ export async function createSession(opts) {
                                 consecutiveCounts.set(sig, 1);
                             }
                             const consec = consecutiveCounts.get(sig) ?? 1;
-                            // At 3x, inject vault context and a strong warning before the hard break at 4x.
+                            const isReadFileTool = READ_FILE_CACHE_TOOLS.has(toolName);
+                            const hardBreakAt = isReadFileTool ? 6 : 4;
+                            // At 3x, inject vault context and first warning
                             if (consec >= 3) {
                                 await injectVaultContext().catch(() => { });
                                 if (consec === 3) {
@@ -2272,18 +2598,45 @@ export async function createSession(opts) {
                                     }
                                 }
                             }
-                            // Hard-break: after 4 consecutive identical reads, stop the session
-                            if (consec >= 4) {
-                                throw new Error(`tool ${toolName}: identical read repeated ${consec}x consecutively; breaking loop. ` +
-                                    `The resource content has not changed between reads.`);
+                            // At 2x, serve from cache if available AND inject final warning
+                            if (consec >= 2 && isReadFileTool) {
+                                if (consec === 4) {
+                                    let resourceType = 'resource';
+                                    if (toolName === 'read_file')
+                                        resourceType = 'file';
+                                    else if (toolName === 'read_files')
+                                        resourceType = 'files';
+                                    else if (toolName === 'list_dir')
+                                        resourceType = 'directory';
+                                    messages.push({
+                                        role: 'system',
+                                        content: `CRITICAL: DO NOT make another identical call for this ${resourceType}. It HAS NOT CHANGED. You already have the content. Move on to the NEXT step NOW.`,
+                                    });
+                                }
+                                const argsForSig = sigMetaBySig.get(sig)?.args ?? {};
+                                const replay = await toolLoopGuard.getReadCacheReplay(toolName, argsForSig, ctx.cwd);
+                                if (replay) {
+                                    repeatedReadFileSigs.add(sig);
+                                    continue;
+                                }
+                            }
+                            // Deterministic recovery at threshold (no hard throw): force one no-tools turn.
+                            if (consec >= hardBreakAt) {
+                                shouldForceToollessRecovery = true;
+                                messages.push({
+                                    role: 'system',
+                                    content: `[tool-loop critical] ${toolName} repeated ${consec}x with unchanged inputs. ` +
+                                        'Next turn will run with tools disabled so you must use existing results and provide a concrete next step/final response.',
+                                });
                             }
                             continue;
                         }
                         // Default behavior for mutating/other tools: break on repeated identical signature.
                         const loopThreshold = harness.quirks.loopsOnToolError ? 2 : 3;
                         if ((sigCounts.get(sig) ?? 0) >= loopThreshold) {
-                            const args = sig.slice(toolName.length + 1);
-                            const argsPreview = args.length > 220 ? args.slice(0, 220) + '…' : args;
+                            const argsObj = sigMetaBySig.get(sig)?.args ?? {};
+                            const argsRaw = JSON.stringify(argsObj);
+                            const argsPreview = argsRaw.length > 220 ? argsRaw.slice(0, 220) + '…' : argsRaw;
                             throw new Error(`tool ${toolName}: identical call repeated ${loopThreshold}x across turns; breaking loop. ` +
                                 `args=${argsPreview}\n` +
                                 `Hint: you repeated the same tool call ${loopThreshold} times with identical arguments. ` +
@@ -2294,6 +2647,31 @@ export async function createSession(opts) {
                     }
                     // Update consecutive tracking: save this turn's signatures for next turn comparison.
                     lastTurnSigs = turnSigs;
+                    if (shouldForceToollessRecovery) {
+                        if (!toollessRecoveryUsed) {
+                            forceToollessRecoveryTurn = true;
+                            toollessRecoveryUsed = true;
+                            messages.push({
+                                role: 'user',
+                                content: '[system] Critical tool loop detected. Next turn will run with tools disabled. ' +
+                                    'Use already available tool results to provide a concrete next step or final response; do not request more tools.',
+                            });
+                            await emitTurnEnd({
+                                turn: turns,
+                                toolCalls,
+                                promptTokens: cumulativeUsage.prompt,
+                                completionTokens: cumulativeUsage.completion,
+                                promptTokensTurn,
+                                completionTokensTurn,
+                                ttftMs,
+                                ttcMs,
+                                ppTps,
+                                tgTps,
+                            });
+                            continue;
+                        }
+                        throw new AgentLoopBreak('critical tool-loop persisted after one tools-disabled recovery turn. Stopping to avoid infinite loop.');
+                    }
                     const runOne = async (tc) => {
                         const name = tc.function.name;
                         const rawArgs = tc.function.arguments ?? '{}';
@@ -2323,6 +2701,7 @@ export async function createSession(opts) {
                             throw new Error(`unknown tool: ${name}`);
                         // Keep parsed args by call-id so we can digest/archive tool outputs with context.
                         toolArgsByCallId.set(callId, args && typeof args === 'object' && !Array.isArray(args) ? args : {});
+                        toolLoopGuard.registerCall(name, args && typeof args === 'object' && !Array.isArray(args) ? args : {}, callId);
                         // Pre-dispatch argument validation.
                         // - Required params
                         // - Type/range/enums
@@ -2427,9 +2806,10 @@ export async function createSession(opts) {
                                 return { id: callId, content: '[skipped by user: step mode]' };
                             }
                         }
-                        const sig = `${name}:${rawArgs || '{}'}`;
+                        const sig = toolLoopGuard.computeSignature(name, args && typeof args === 'object' && !Array.isArray(args) ? args : {});
                         let content = '';
                         let reusedCachedReadOnlyExec = false;
+                        let reusedCachedReadTool = false;
                         if (name === 'exec' && repeatedReadOnlyExecSigs.has(sig)) {
                             const cached = execObservationCacheBySig.get(sig);
                             if (cached) {
@@ -2437,7 +2817,22 @@ export async function createSession(opts) {
                                 reusedCachedReadOnlyExec = true;
                             }
                         }
-                        if (!reusedCachedReadOnlyExec) {
+                        // Replay any exec result (read-only or not) when the loop detector flagged it.
+                        if (name === 'exec' && !reusedCachedReadOnlyExec && replayExecSigs.has(sig)) {
+                            const cached = lastExecResultBySig.get(sig);
+                            if (cached) {
+                                content = withReplayedExecHint(cached);
+                                reusedCachedReadOnlyExec = true; // skip re-execution below
+                            }
+                        }
+                        if (READ_FILE_CACHE_TOOLS.has(name) && repeatedReadFileSigs.has(sig)) {
+                            const replay = await toolLoopGuard.getReadCacheReplay(name, args, ctx.cwd);
+                            if (replay) {
+                                content = replay;
+                                reusedCachedReadTool = true;
+                            }
+                        }
+                        if (!reusedCachedReadOnlyExec && !reusedCachedReadTool) {
                             if (isSpawnTask) {
                                 content = await runSpawnTask(args);
                             }
@@ -2450,9 +2845,16 @@ export async function createSession(opts) {
                                 };
                                 const value = await builtInFn(callCtx, args);
                                 content = typeof value === 'string' ? value : JSON.stringify(value);
+                                if (READ_FILE_CACHE_TOOLS.has(name) && typeof content === 'string' && !content.startsWith('ERROR:')) {
+                                    const baseCwd = typeof args?.cwd === 'string' ? String(args.cwd) : ctx.cwd;
+                                    await toolLoopGuard.storeReadCache(name, args, baseCwd, content);
+                                }
                                 if (name === 'exec') {
                                     // Successful exec clears blocked-loop counters.
                                     blockedExecAttemptsBySig.clear();
+                                    // Cache every exec result so repeated calls under context pressure
+                                    // can replay the result instead of re-executing.
+                                    lastExecResultBySig.set(sig, content);
                                     const cmd = String(args?.command ?? '');
                                     if (looksLikeReadOnlyExecCommand(cmd) && readOnlyExecCacheable(content)) {
                                         execObservationCacheBySig.set(sig, content);
@@ -2591,6 +2993,10 @@ export async function createSession(opts) {
                                 }
                             }
                         }
+                        toolLoopGuard.registerOutcome(name, args, {
+                            toolCallId: callId,
+                            result: content,
+                        });
                         return { id: callId, content };
                     };
                     const results = [];
@@ -2611,7 +3017,8 @@ export async function createSession(opts) {
                         // Applies to direct exec attempts and spawn_task delegation attempts.
                         if (tc.function.name === 'exec' || tc.function.name === 'spawn_task') {
                             const blockedMatch = msg.match(/^exec:\s*blocked\s*\(([^)]+)\)\s*without --no-confirm\/--yolo:\s*(.*)$/i)
-                                || msg.match(/^(spawn_task):\s*blocked\s*—\s*(.*)$/i);
+                                || msg.match(/^(spawn_task):\s*blocked\s*—\s*(.*)$/i)
+                                || msg.match(/^exec:\s*blocked\s+(background command\b[^.]*)\./i);
                             if (blockedMatch) {
                                 const reason = (blockedMatch[1] || blockedMatch[2] || 'blocked command').trim();
                                 let parsedArgs = {};
@@ -2623,7 +3030,8 @@ export async function createSession(opts) {
                                     ? String(parsedArgs?.command ?? '')
                                     : String(parsedArgs?.task ?? '');
                                 const normalizedReason = reason.toLowerCase();
-                                const aggregateByReason = normalizedReason.includes('package install/remove');
+                                const aggregateByReason = normalizedReason.includes('package install/remove')
+                                    || normalizedReason.includes('background command');
                                 const sig = aggregateByReason
                                     ? `${tc.function.name}|${reason}`
                                     : `${tc.function.name}|${reason}|${cmd}`;
@@ -2645,6 +3053,20 @@ export async function createSession(opts) {
                             retryable: te.retryable,
                             result: toolErrorContent,
                         });
+                        let parsedArgs = {};
+                        try {
+                            const parsed = JSON.parse(tc.function.arguments ?? '{}');
+                            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                                parsedArgs = parsed;
+                            }
+                        }
+                        catch {
+                            // keep empty object
+                        }
+                        toolLoopGuard.registerOutcome(tc.function.name, parsedArgs, {
+                            toolCallId: callId,
+                            error: msg,
+                        });
                         return { id: callId, content: toolErrorContent };
                     };
                     // ── Anti-scan guardrails (§ read budget, dir scan, same-search) ──
@@ -2708,6 +3130,19 @@ export async function createSession(opts) {
                             }
                         }
                     }
+                    if (replayByCallId.size > 0) {
+                        const canonicalById = new Map(results.map((r) => [r.id, r.content]));
+                        for (const [dupId, canonicalId] of replayByCallId.entries()) {
+                            const canonical = canonicalById.get(canonicalId);
+                            if (canonical == null)
+                                continue;
+                            results.push({
+                                id: dupId,
+                                content: `[idlehands dedupe] Identical tool call replayed from ${canonicalId}. ` +
+                                    'Use that earlier tool result; no new execution was performed.',
+                            });
+                        }
+                    }
                     // Bail immediately if cancelled during tool execution
                     if (ac.signal.aborted)
                         break;
@@ -2755,6 +3190,8 @@ export async function createSession(opts) {
                                 'Do not narrate. Fix required/mistyped fields and unknown keys.',
                         });
                     }
+                    // Update session-level tool loop stats for observability
+                    lastToolLoopStats = toolLoopGuard.getStats();
                     // Hook: onTurnEnd (Phase 8.5)
                     await emitTurnEnd({
                         turn: turns,
@@ -2928,6 +3365,7 @@ export async function createSession(opts) {
         listModels,
         refreshServerHealth,
         getPerfSummary,
+        getToolLoopStats: () => lastToolLoopStats,
         captureOn,
         captureOff,
         captureLast,
@@ -2965,6 +3403,9 @@ export async function createSession(opts) {
         get planSteps() {
             return planSteps;
         },
+        get compactionStats() {
+            return { ...compactionStats };
+        },
         executePlanStep,
         clearPlan,
         compactHistory