@visorcraft/idlehands 2.2.5 → 2.2.8

package/dist/agent.js

@@ -16,6 +16,9 @@ import { PromptGuard } from './security/prompt-guard.js';
 import { ResponseCache } from './agent/response-cache.js';
 import { resilientCall } from './agent/resilient-provider.js';
 import { ToolLoopGuard } from './agent/tool-loop-guard.js';
+import { CaptureManager } from './agent/capture.js';
+import { ClientPool } from './agent/client-pool.js';
+import { ConversationBranch } from './agent/conversation-branch.js';
 import { isLspTool, isMutationTool, isReadOnlyTool, planModeSummary } from './agent/tool-policy.js';
 import { buildToolsSchema } from './agent/tools-schema.js';
 import { OpenAIClient } from './client.js';
@@ -33,10 +36,12 @@ import { BASE_MAX_TOKENS, deriveContextWindow, deriveGenerationParams, supportsV
 import { ReplayStore } from './replay.js';
 import { checkExecSafety, checkPathSafety } from './safety.js';
 import { decideTurnRoute } from './routing/turn-router.js';
+import { RouteHysteresis } from './routing/hysteresis.js';
 import { normalizeApprovalMode } from './shared/config-utils.js';
 import { collectSnapshot } from './sys/context.js';
 import { ToolError, ValidationError } from './tools/tool-error.js';
 import * as tools from './tools.js';
+import { EditTransaction } from './tools/transaction.js';
 import { stateDir, timestampedId } from './utils.js';
 import { VaultStore } from './vault.js';
 export { parseToolCallsFromContent };
@@ -219,13 +224,19 @@ export async function createSession(opts) {
     const mcpHasEnabledTools = (mcpManager?.listTools().length ?? 0) > 0;
     const mcpLazySchemaMode = Boolean(mcpManager && mcpHasEnabledTools);
     let mcpToolsLoaded = !mcpLazySchemaMode;
-    const getToolsSchema = () => buildToolsSchema({
+    const routeHysteresis = new RouteHysteresis({
+        minDwell: cfg.routing?.hysteresisMinDwell ?? 2,
+        enabled: cfg.routing?.hysteresis !== false,
+    });
+    const conversationBranch = new ConversationBranch();
+    const getToolsSchema = (slimFast) => buildToolsSchema({
         activeVaultTools,
         passiveVault: !activeVaultTools && vaultEnabled && vaultMode === 'passive',
         sysMode: cfg.mode === 'sys',
         lspTools: lspManager?.hasServers() === true,
         mcpTools: mcpToolsLoaded ? (mcpManager?.getEnabledToolSchemas() ?? []) : [],
         allowSpawnTask: spawnTaskEnabled,
+        slimFast,
     });
     const vault = vaultEnabled
         ? (opts.runtime?.vault ??
@@ -394,6 +405,27 @@ export async function createSession(opts) {
             console.warn(`[warn] sys-eager snapshot failed: ${e?.message ?? e}`);
         }
     }
+    const buildCompactSessionMeta = () => {
+        const caps = [];
+        if (vaultEnabled)
+            caps.push('vault');
+        if (lspManager?.hasServers())
+            caps.push('lsp');
+        if (mcpManager)
+            caps.push('mcp');
+        if (spawnTaskEnabled)
+            caps.push('subagents');
+        const lines = [
+            `[cwd: ${cfg.dir}]`,
+            `[harness: ${harness.id}]`,
+            '[fast-lane prelude: concise response by default; ask for details if needed.]',
+            caps.length ? `[optional capabilities: ${caps.join(', ')}]` : '',
+        ].filter(Boolean);
+        const maxChars = cfg.routing?.fastCompactPreludeMaxChars ?? 320;
+        const joined = lines.join('\n');
+        return joined.length > maxChars ? `${joined.slice(0, maxChars - 1)}…` : joined;
+    };
+    const compactSessionMeta = buildCompactSessionMeta();
     const defaultSystemPromptBase = SYSTEM_PROMPT;
     let activeSystemPromptBase = (cfg.system_prompt_override ?? '').trim() || defaultSystemPromptBase;
     let systemPromptOverridden = (cfg.system_prompt_override ?? '').trim().length > 0;
@@ -431,6 +463,8 @@ export async function createSession(opts) {
         lastEditedPath = undefined;
         initialConnectionProbeDone = false;
         mcpToolsLoaded = !mcpLazySchemaMode;
+        routeHysteresis.reset();
+        conversationBranch.reset();
     };
     const restore = (next) => {
         if (!Array.isArray(next) || next.length < 2) {
@@ -456,6 +490,7 @@ export async function createSession(opts) {
     let inFlight = null;
     let initialConnectionProbeDone = false;
     let lastEditedPath;
+    let lastTurnTransaction;
     // Plan mode state (Phase 8)
     let planSteps = [];
     // Sub-agent queue state (Phase 18): enforce sequential execution on single-GPU setups.
@@ -1058,6 +1093,7 @@ export async function createSession(opts) {
     const ppSamples = [];
     const tgSamples = [];
     let lastTurnMetrics;
+    let lastTurnDebug;
     let lastServerHealth;
     let lastToolLoopStats = {
         totalHistory: 0,
@@ -1076,70 +1112,35 @@ export async function createSession(opts) {
         },
     };
     let lastModelsProbeMs = 0;
-    const capturesDir = path.join(stateDir(), 'captures');
-    let captureEnabled = false;
-    let capturePath;
-    let lastCaptureRecord = null;
-    const routedClients = new Map();
-    const probedEndpoints = new Set();
+    const capture = new CaptureManager(stateDir());
     const normalizeEndpoint = (endpoint) => endpoint.trim().replace(/\/+$/, '');
-    const defaultCapturePath = () => {
-        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-        return path.join(capturesDir, `${stamp}.jsonl`);
-    };
-    const appendCaptureRecord = async (record, outPath) => {
-        await fs.mkdir(path.dirname(outPath), { recursive: true });
-        await fs.appendFile(outPath, JSON.stringify(record) + '\n', 'utf8');
-    };
+    const clientPool = new ClientPool({
+        primary: client,
+        primaryEndpoint: cfg.endpoint,
+        apiKey: opts.apiKey,
+        cfg,
+        capture,
+        ClientCtor: OpenAIClient,
+    });
+    // Thin wrapper used by setEndpoint when primary client is replaced.
     const applyClientRuntimeOptions = (target) => {
-        if (typeof target.setVerbose === 'function') {
+        if (typeof target.setVerbose === 'function')
             target.setVerbose(cfg.verbose);
-        }
-        if (typeof cfg.response_timeout === 'number' && cfg.response_timeout > 0) {
+        if (typeof cfg.response_timeout === 'number' && cfg.response_timeout > 0)
             target.setResponseTimeout(cfg.response_timeout);
-        }
-        if (typeof target.setConnectionTimeout === 'function' &&
-            typeof cfg.connection_timeout === 'number' &&
-            cfg.connection_timeout > 0) {
+        if (typeof target.setConnectionTimeout === 'function' && typeof cfg.connection_timeout === 'number' && cfg.connection_timeout > 0)
             target.setConnectionTimeout(cfg.connection_timeout);
-        }
-        if (typeof target.setInitialConnectionCheck === 'function' &&
-            typeof cfg.initial_connection_check === 'boolean') {
+        if (typeof target.setInitialConnectionCheck === 'function' && typeof cfg.initial_connection_check === 'boolean')
             target.setInitialConnectionCheck(cfg.initial_connection_check);
-        }
-        if (typeof target.setInitialConnectionProbeTimeout === 'function' &&
-            typeof cfg.initial_connection_timeout === 'number' &&
-            cfg.initial_connection_timeout > 0) {
+        if (typeof target.setInitialConnectionProbeTimeout === 'function' && typeof cfg.initial_connection_timeout === 'number' && cfg.initial_connection_timeout > 0)
             target.setInitialConnectionProbeTimeout(cfg.initial_connection_timeout);
-        }
     };
     const attachCaptureHook = (target) => {
         if (typeof target.setExchangeHook !== 'function')
             return;
-        target.setExchangeHook(async (record) => {
-            lastCaptureRecord = record;
-            if (!captureEnabled)
-                return;
-            const outFile = capturePath || defaultCapturePath();
-            capturePath = outFile;
-            await appendCaptureRecord(record, outFile);
-        });
-    };
-    const getClientForEndpoint = (endpoint) => {
-        if (!endpoint)
-            return client;
-        const normalized = normalizeEndpoint(endpoint);
-        if (!normalized || normalized === normalizeEndpoint(cfg.endpoint))
-            return client;
-        const existing = routedClients.get(normalized);
-        if (existing)
-            return existing;
-        const routed = new OpenAIClient(normalized, opts.apiKey, cfg.verbose);
-        applyClientRuntimeOptions(routed);
-        attachCaptureHook(routed);
-        routedClients.set(normalized, routed);
-        return routed;
+        target.setExchangeHook(capture.createExchangeHook());
     };
+    const getClientForEndpoint = (endpoint) => clientPool.getForEndpoint(endpoint);
     let runtimeRoutingModules = null;
     let runtimeRoutingUnavailable = false;
     let runtimeModelIdsCache = null;
@@ -1351,8 +1352,8 @@ export async function createSession(opts) {
             client = new OpenAIClient(normalized, opts.apiKey, cfg.verbose);
         }
         applyClientRuntimeOptions(client);
-        routedClients.clear();
-        probedEndpoints.clear();
+        clientPool.setPrimary(client);
+        clientPool.reset();
         wireCaptureHook();
         modelsList = normalizeModelsResponse(await client.models());
         const chosen = modelName?.trim()
@@ -1361,25 +1362,12 @@ export async function createSession(opts) {
                 (await autoPickModel(client, modelsList)));
         setModel(chosen);
     };
-    const captureOn = async (filePath) => {
-        const target = filePath?.trim() ? path.resolve(filePath) : defaultCapturePath();
-        await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.appendFile(target, '', 'utf8');
-        captureEnabled = true;
-        capturePath = target;
-        return target;
-    };
-    const captureOff = () => {
-        captureEnabled = false;
-    };
-    const captureLast = async (filePath) => {
-        if (!lastCaptureRecord) {
-            throw new Error('No captured request/response pair is available yet.');
-        }
-        const target = filePath?.trim() ? path.resolve(filePath) : capturePath || defaultCapturePath();
-        await appendCaptureRecord(lastCaptureRecord, target);
-        return target;
-    };
+    const captureOn = (filePath) => capture.on(filePath);
+    const captureOff = () => capture.off();
+    const captureSetRedact = (enabled) => capture.setRedact(enabled);
+    const captureGetRedact = () => capture.getRedact();
+    const captureOpen = () => capture.open();
+    const captureLast = (filePath) => capture.last(filePath);
     const listMcpServers = () => {
         return mcpManager?.listServers() ?? [];
     };
@@ -1410,7 +1398,7 @@ export async function createSession(opts) {
     const close = async () => {
         await mcpManager?.close().catch(() => { });
         await lspManager?.close().catch(() => { });
-        routedClients.clear();
+        await clientPool.closeAll();
         vault?.close();
         lens?.close();
     };
@@ -1511,16 +1499,38 @@ export async function createSession(opts) {
             : cfg.max_iterations;
         const wallStart = Date.now();
         const delegationForbiddenByUser = userDisallowsDelegation(instruction);
+        const rawInstructionText = userContentToText(instruction).trim();
+        // Route early so first-turn prelude/tool choices can adapt.
+        const turnRoute = decideTurnRoute(cfg, rawInstructionText, model);
+        // Apply hysteresis to suppress rapid lane thrashing in auto mode.
+        const hysteresisResult = routeHysteresis.apply(turnRoute.selectedMode, turnRoute.selectedModeSource);
+        if (hysteresisResult.suppressed) {
+            // Override the selected mode with the hysteresis-stabilized lane.
+            turnRoute.selectedMode = hysteresisResult.lane;
+            turnRoute.selectedModeSource = 'hysteresis';
+        }
+        const routeFastByAuto = turnRoute.requestedMode === 'auto' &&
+            turnRoute.selectedMode === 'fast' &&
+            turnRoute.selectedModeSource !== 'override';
+        const compactPreludeEnabled = cfg.routing?.fastCompactPrelude !== false;
+        // Never use compact prelude when the harness injected format reminders
+        // (e.g. tool_calls format for nemotron) — those are critical for correctness.
+        const hasHarnessInjection = sessionMetaPending
+            ? sessionMetaPending.includes('Use the tool_calls mechanism') ||
+                sessionMetaPending.includes('[Format reminder]')
+            : false;
+        const useCompactPrelude = Boolean(sessionMetaPending && compactPreludeEnabled && routeFastByAuto && !hasHarnessInjection);
         // Prepend session meta to the first user instruction (§9b: variable context
         // goes in first user message, not system prompt, to preserve KV cache).
         // This avoids two consecutive user messages without an assistant response.
         let userContent = instruction;
         if (sessionMetaPending) {
+            const prelude = useCompactPrelude ? compactSessionMeta : sessionMetaPending;
             if (typeof instruction === 'string') {
-                userContent = `${sessionMetaPending}\n\n${instruction}`;
+                userContent = `${prelude}\n\n${instruction}`;
             }
             else {
-                userContent = [{ type: 'text', text: sessionMetaPending }, ...instruction];
+                userContent = [{ type: 'text', text: prelude }, ...instruction];
             }
             sessionMetaPending = null;
         }
@@ -1559,6 +1569,8 @@ export async function createSession(opts) {
                 // Vault search is best-effort; don't fail the turn
             }
         }
+        // Save rollback checkpoint before this turn (captures pre-turn state).
+        conversationBranch.checkpoint(messages.length, typeof instruction === 'string' ? instruction : '[multimodal]');
         messages.push({ role: 'user', content: userContent });
         const hookObj = typeof hooks === 'function' ? { onToken: hooks } : (hooks ?? {});
         let turns = 0;
@@ -1684,7 +1696,6 @@ export async function createSession(opts) {
             }
             return { text: finalText, turns, toolCalls };
         };
-        const rawInstructionText = userContentToText(instruction).trim();
         lastAskInstructionText = rawInstructionText;
         lastCompactionReminderObjective = '';
         if (hooksEnabled)
@@ -1699,7 +1710,7 @@ export async function createSession(opts) {
                 await client.probeConnection();
                 initialConnectionProbeDone = true;
                 if (typeof client.getEndpoint === 'function') {
-                    probedEndpoints.add(normalizeEndpoint(client.getEndpoint()));
+                    clientPool.markProbed(client.getEndpoint());
                 }
             }
         }
@@ -1747,12 +1758,24 @@ export async function createSession(opts) {
             });
             return await finalizeAsk(miss);
         }
-        const turnRoute = decideTurnRoute(cfg, rawInstructionText, model);
         const primaryRoute = turnRoute.providerTargets[0];
         const runtimeModelIds = await loadRuntimeModelIds();
         const routeRuntimeFallbackModels = (primaryRoute?.fallbackModels ?? []).filter((m) => runtimeModelIds.has(m));
-        const routeApiFallbackModels = (primaryRoute?.fallbackModels ?? []).filter((m) => !runtimeModelIds.has(m));
+        const apiProviderTargets = turnRoute.providerTargets.map((target) => ({
+            ...target,
+            fallbackModels: (target.fallbackModels ?? []).filter((m) => !runtimeModelIds.has(m)),
+        }));
+        const routeApiFallbackModels = apiProviderTargets[0]?.fallbackModels ?? [];
         const primaryUsesRuntimeModel = !!primaryRoute?.model && runtimeModelIds.has(primaryRoute.model);
+        const fastLaneToolless = cfg.routing?.fastLaneToolless !== false &&
+            routeFastByAuto &&
+            turnRoute.classificationHint === 'fast';
+        // Fast-lane slim tools: on subsequent turns of a fast-route ask, include only
+        // read-only / lightweight tools to reduce per-turn token overhead (~40-50%).
+        // Only active when the classifier explicitly said 'fast' (not heuristic/fallback).
+        const fastLaneSlimTools = cfg.routing?.fastLaneSlimTools !== false &&
+            routeFastByAuto &&
+            turnRoute.classificationHint === 'fast';
         // Non-runtime route models can be selected directly in-session.
         if (!primaryUsesRuntimeModel && primaryRoute?.model && primaryRoute.model !== model) {
             setModel(primaryRoute.model);
@@ -1777,6 +1800,10 @@ export async function createSession(opts) {
             else if (routeApiFallbackModels.length) {
                 routeParts.push(`api_fallbacks=${routeApiFallbackModels.join(',')}`);
             }
+            if (useCompactPrelude)
+                routeParts.push('compact_prelude=on');
+            if (fastLaneToolless)
+                routeParts.push('fast_toolless=on');
             console.error(`[routing] ${routeParts.join(' ')}`);
         }
         const persistReviewArtifact = async (finalText) => {
@@ -2176,10 +2203,38 @@ export async function createSession(opts) {
                 let resp;
                 try {
                     try {
-                        const toolsForTurn = cfg.no_tools || forceToollessRecoveryTurn
+                        // turns is 1-indexed (incremented at loop top), so first iteration = 1.
+                        const forceToollessByRouting = fastLaneToolless && turns === 1;
+                        // On fast-lane subsequent turns, slim the schema to read-only tools.
+                        const useSlimFast = !forceToollessByRouting && fastLaneSlimTools && turns > 1;
+                        const toolsForTurn = cfg.no_tools || forceToollessRecoveryTurn || forceToollessByRouting
                             ? []
-                            : getToolsSchema().filter((t) => !suppressedTools.has(t.function.name));
-                        const toolChoiceForTurn = cfg.no_tools || forceToollessRecoveryTurn ? 'none' : 'auto';
+                            : getToolsSchema(useSlimFast).filter((t) => !suppressedTools.has(t.function.name));
+                        const toolChoiceForTurn = cfg.no_tools || forceToollessRecoveryTurn || forceToollessByRouting ? 'none' : 'auto';
+                        const promptBytesEstimate = Buffer.byteLength(JSON.stringify(messages), 'utf8');
+                        const toolSchemaBytesEstimate = toolsForTurn.length
+                            ? Buffer.byteLength(JSON.stringify(toolsForTurn), 'utf8')
+                            : 0;
+                        const toolSchemaTokenEstimate = estimateToolSchemaTokens(toolsForTurn);
+                        lastTurnDebug = {
+                            requestedMode: turnRoute.requestedMode,
+                            selectedMode: turnRoute.selectedMode,
+                            selectedModeSource: turnRoute.selectedModeSource,
+                            classificationHint: turnRoute.classificationHint,
+                            provider: primaryRoute?.name ?? 'default',
+                            model: primaryRoute?.model ?? model,
+                            runtimeRoute: primaryUsesRuntimeModel,
+                            compactPrelude: useCompactPrelude,
+                            fastLaneToolless,
+                            fastLaneSlimTools: useSlimFast,
+                            promptBytes: promptBytesEstimate,
+                            toolSchemaBytes: toolSchemaBytesEstimate,
+                            toolSchemaTokens: toolSchemaTokenEstimate,
+                            toolCount: toolsForTurn.length,
+                        };
+                        if (cfg.verbose) {
+                            console.error(`[turn-debug] prompt_bytes=${promptBytesEstimate} tools=${toolsForTurn.length} tool_schema_bytes=${toolSchemaBytesEstimate} tool_schema_tokens~=${toolSchemaTokenEstimate}`);
+                        }
                         // ── Response cache: check for cached response ──────────────
                         // Only cache tool-less turns (final answers, explanations) since
                         // tool-calling turns have side effects that shouldn't be replayed.
@@ -2252,42 +2307,67 @@ export async function createSession(opts) {
                                 });
                             }
                             else {
-                                const routeEndpoint = primaryRoute?.endpoint;
-                                const activeClient = getClientForEndpoint(routeEndpoint);
-                                const endpointKey = routeEndpoint ? normalizeEndpoint(routeEndpoint) : undefined;
-                                if (endpointKey && !probedEndpoints.has(endpointKey)) {
-                                    if (typeof activeClient.probeConnection === 'function') {
-                                        try {
-                                            await activeClient.probeConnection();
+                                const isLikelyAuthError = (errMsg) => {
+                                    const lower = errMsg.toLowerCase();
+                                    return (lower.includes('refresh_token_reused') ||
+                                        lower.includes('missing bearer') ||
+                                        lower.includes('missing api key') ||
+                                        lower.includes('invalid api key') ||
+                                        lower.includes('authentication failed') ||
+                                        lower.includes('unauthorized') ||
+                                        lower.includes('forbidden') ||
+                                        lower.includes('invalid token'));
+                                };
+                                const providerFailures = [];
+                                for (const target of apiProviderTargets.length
+                                    ? apiProviderTargets
+                                    : [{
+                                            name: primaryRoute?.name ?? 'default',
+                                            endpoint: primaryRoute?.endpoint,
+                                            model: primaryRoute?.model ?? model,
+                                            fallbackModels: routeApiFallbackModels,
+                                        }]) {
+                                    const routeEndpoint = target.endpoint;
+                                    const activeClient = getClientForEndpoint(routeEndpoint);
+                                    if (routeEndpoint) {
+                                        await clientPool.probeIfNeeded(routeEndpoint);
+                                    }
+                                    const routeModel = target.model || model;
+                                    const modelFallbackMap = {};
+                                    if (target.fallbackModels?.length) {
+                                        modelFallbackMap[routeModel] = target.fallbackModels;
+                                    }
+                                    try {
+                                        resp = await resilientCall([
+                                            {
+                                                name: target.name ?? 'default',
+                                                execute: (m) => activeClient.chatStream({ ...chatOptsBase, model: m }),
+                                            },
+                                        ], routeModel, {
+                                            maxRetries: 0,
+                                            modelFallbacks: modelFallbackMap,
+                                            onRetry: (info) => {
+                                                if (cfg.verbose) {
+                                                    console.error(`[routing] retry: provider=${info.provider} model=${info.model} attempt=${info.attempt}/${info.maxAttempts} reason=${info.reason}`);
+                                                }
+                                            },
+                                        });
+                                        break;
+                                    }
+                                    catch (providerErr) {
+                                        const errMsg = String(providerErr?.message ?? providerErr ?? 'unknown error');
+                                        const compactErr = errMsg.replace(/\s+/g, ' ').trim();
+                                        providerFailures.push(`${target.name}: ${compactErr}`);
+                                        if (cfg.verbose && isLikelyAuthError(errMsg)) {
+                                            console.warn(`[routing] auth/provider failure on ${target.name}; trying next provider fallback`);
                                         }
-                                        catch {
-                                            // best-effort: if probe fails we still try the call
+                                        if (isContextWindowExceededError(providerErr)) {
+                                            throw providerErr;
                                         }
-                                        probedEndpoints.add(endpointKey);
                                     }
                                 }
-                                const routeModel = primaryRoute?.model ?? model;
-                                if (routeApiFallbackModels.length > 0) {
-                                    const modelFallbackMap = {
-                                        [routeModel]: routeApiFallbackModels,
-                                    };
-                                    resp = await resilientCall([
-                                        {
-                                            name: primaryRoute?.name ?? 'default',
-                                            execute: (m) => activeClient.chatStream({ ...chatOptsBase, model: m }),
-                                        },
-                                    ], routeModel, {
-                                        maxRetries: 1,
-                                        modelFallbacks: modelFallbackMap,
-                                        onRetry: (info) => {
-                                            if (cfg.verbose) {
-                                                console.error(`[routing] retry: provider=${info.provider} model=${info.model} attempt=${info.attempt}/${info.maxAttempts} reason=${info.reason}`);
-                                            }
-                                        },
-                                    });
-                                }
-                                else {
-                                    resp = await activeClient.chatStream({ ...chatOptsBase, model: routeModel });
+                                if (!resp) {
+                                    throw new Error(`All routed providers failed for this turn. ${providerFailures.join(' | ')}`);
                                 }
                             }
                         } // end if (!resp) — cache miss path
@@ -2924,6 +3004,8 @@ export async function createSession(opts) {
                             const absPath = args.path.startsWith('/')
                                 ? args.path
                                 : path.resolve(projectDir, args.path);
+                            // Track in turn transaction for potential atomic rollback.
+                            turnTransaction.track(absPath);
                             // ── Pre-dispatch: block edits to files in a mutation spiral ──
                             if (fileMutationBlocked.has(absPath)) {
                                 const basename = path.basename(absPath);
@@ -3059,6 +3141,7 @@ export async function createSession(opts) {
                         let content = '';
                         let reusedCachedReadOnlyExec = false;
                         let reusedCachedReadTool = false;
+                        let toolFallbackNote = null;
                         if (name === 'exec' && repeatedReadOnlyExecSigs.has(sig)) {
                             const cached = execObservationCacheBySig.get(sig);
                             if (cached) {
@@ -3092,7 +3175,92 @@ export async function createSession(opts) {
                                     toolName: name,
                                     onToolStream: emitToolStream,
                                 };
-                                const value = await builtInFn(callCtx, args);
+                                let value;
+                                try {
+                                    value = await builtInFn(callCtx, args);
+                                }
+                                catch (err) {
+                                    const msg = String(err?.message ?? err ?? '');
+                                    // Fallback #1: edit_file mismatch -> targeted edit_range based on closest-match hint.
+                                    const isEditMismatch = name === 'edit_file' && /edit_file:\s*old_text not found/i.test(msg);
+                                    if (isEditMismatch && typeof args?.path === 'string') {
+                                        const best = msg.match(/Closest match at line\s+(\d+)\s*\((\d+)% similarity\)/i);
+                                        const bestLine = best ? Number.parseInt(best[1], 10) : NaN;
+                                        const similarity = best ? Number.parseInt(best[2], 10) : NaN;
+                                        const oldTextForRange = String(args?.old_text ?? '');
+                                        const oldLineCount = Math.max(1, oldTextForRange.split(/\r?\n/).length);
+                                        const endLine = Number.isFinite(bestLine)
+                                            ? bestLine + oldLineCount - 1
+                                            : Number.NaN;
+                                        const editRangeFn = tools['edit_range'];
+                                        if (editRangeFn &&
+                                            Number.isFinite(bestLine) &&
+                                            Number.isFinite(endLine) &&
+                                            Number.isFinite(similarity) &&
+                                            similarity >= 70) {
+                                            const fallbackArgs = {
+                                                path: args.path,
+                                                start_line: bestLine,
+                                                end_line: endLine,
+                                                replacement: args.new_text,
+                                            };
+                                            if (cfg.verbose) {
+                                                console.warn(`[edit_file] auto-fallback to edit_range at ${bestLine}-${endLine} (${similarity}% similarity)`);
+                                            }
+                                            value = await editRangeFn(callCtx, fallbackArgs);
+                                            args = fallbackArgs;
+                                            toolFallbackNote = 'auto edit_range fallback';
+                                        }
+                                        else {
+                                            throw err;
+                                        }
+                                    }
+                                    else {
+                                        const isWriteRefusal = name === 'write_file' &&
+                                            !args?.overwrite &&
+                                            !args?.force &&
+                                            /write_file:\s*refusing to overwrite existing non-empty file/i.test(msg);
+                                        if (!isWriteRefusal)
+                                            throw err;
+                                        // Fallback #2 (preferred): rewrite existing file via edit_range first.
+                                        const editRangeFn = tools['edit_range'];
+                                        let usedEditRangeFallback = false;
+                                        if (editRangeFn && typeof args?.path === 'string') {
+                                            try {
+                                                const absWritePath = args.path.startsWith('/')
+                                                    ? args.path
+                                                    : path.resolve(projectDir, args.path);
+                                                const curText = await fs.readFile(absWritePath, 'utf8');
+                                                const totalLines = Math.max(1, curText.split(/\r?\n/).length);
+                                                const fallbackArgs = {
+                                                    path: args.path,
+                                                    start_line: 1,
+                                                    end_line: totalLines,
+                                                    replacement: args.content,
+                                                };
+                                                if (cfg.verbose) {
+                                                    console.warn(`[write_file] auto-fallback to edit_range for existing file (${totalLines} lines)`);
+                                                }
+                                                value = await editRangeFn(callCtx, fallbackArgs);
+                                                args = fallbackArgs;
+                                                toolFallbackNote = 'auto edit_range fallback';
+                                                usedEditRangeFallback = true;
+                                            }
+                                            catch {
+                                                // fall through to explicit overwrite retry below
+                                            }
+                                        }
+                                        if (!usedEditRangeFallback) {
+                                            const retryArgs = { ...args, overwrite: true };
+                                            if (cfg.verbose) {
+                                                console.warn('[write_file] auto-retrying with overwrite=true after explicit overwrite refusal');
+                                            }
+                                            value = await builtInFn(callCtx, retryArgs);
+                                            args = retryArgs;
+                                            toolFallbackNote = 'auto overwrite fallback';
+                                        }
+                                    }
+                                }
                                 content = typeof value === 'string' ? value : JSON.stringify(value);
                                 if (READ_FILE_CACHE_TOOLS.has(name) &&
                                     typeof content === 'string' &&
@@ -3178,6 +3346,9 @@ export async function createSession(opts) {
                         let summary = reusedCachedReadOnlyExec
                             ? 'cached read-only exec observation (unchanged)'
                             : toolResultSummary(name, args, content, true);
+                        if (toolFallbackNote) {
+                            summary = `${summary} (${toolFallbackNote})`;
+                        }
                         const resultEvent = {
                             id: callId,
                             name,
@@ -3326,6 +3497,7 @@ export async function createSession(opts) {
                         return { id: callId, content: truncated.content };
                     };
                     const results = [];
+                    const turnTransaction = new EditTransaction();
                     let invalidArgsThisTurn = false;
                     // Helper: catch tool errors but re-throw AgentLoopBreak (those must break the outer loop)
                     const catchToolError = async (e, tc) => {
@@ -3480,6 +3652,11 @@ export async function createSession(opts) {
                             });
                         }
                     }
+                    // Store the turn transaction for potential post-turn rollback.
+                    if (turnTransaction.hasChanges) {
+                        turnTransaction.commit();
+                        lastTurnTransaction = turnTransaction;
+                    }
                     // Bail immediately if cancelled during tool execution
                     if (ac.signal.aborted)
                         break;
@@ -3751,6 +3928,25 @@ export async function createSession(opts) {
             return currentContextTokens > 0 ? currentContextTokens : estimateTokensFromMessages(messages);
         },
         ask,
+        rollbackLastTurnEdits: async () => {
+            if (!lastTurnTransaction || !lastTurnTransaction.hasChanges) {
+                return { ok: false, error: 'No file edits to roll back.' };
+            }
+            const tx = lastTurnTransaction;
+            lastTurnTransaction = undefined;
+            const callCtx = { cwd: projectDir, noConfirm: true, dryRun: false };
+            const results = await tx.rollback(callCtx);
+            return { ok: true, results };
+        },
+        rollback: () => {
+            const cp = conversationBranch.rollback();
+            if (!cp)
+                return null;
+            const removed = messages.length - cp.messageCount;
+            messages.length = cp.messageCount;
+            return { preview: cp.preview, removedMessages: removed };
+        },
+        listCheckpoints: () => conversationBranch.list(),
         setModel,
         setEndpoint,
         listModels,
@@ -3763,8 +3959,11 @@ export async function createSession(opts) {
         captureOn,
         captureOff,
         captureLast,
+        captureSetRedact,
+        captureGetRedact,
+        captureOpen,
         get capturePath() {
-            return capturePath;
+            return capture.path;
         },
         getSystemPrompt: () => messages[0]?.role === 'system' ? String(messages[0].content) : activeSystemPromptBase,
         setSystemPrompt,
@@ -3791,6 +3990,9 @@ export async function createSession(opts) {
         get lastTurnMetrics() {
             return lastTurnMetrics;
         },
+        get lastTurnDebug() {
+            return lastTurnDebug;
+        },
         get lastServerHealth() {
             return lastServerHealth;
         },