claude-recall 0.25.1 → 0.26.0

package/README.md

@@ -29,7 +29,7 @@ Your preferences, project structure, workflows, corrections, and coding style ar
 
 | Component | Version                 | Notes                       |
 | --------- | ----------------------- | --------------------------- |
-| Node.js   | **20+**                 | required for better-sqlite3 |
+| Node.js   | **20.19+**              | required for better-sqlite3 (Node 20+) and chalk 5 (ESM `require()` needs ≥20.19) |
 | OS        | macOS / Linux / Windows | WSL supported               |
 
 ### Install for Claude Code
@@ -137,7 +137,7 @@ claude-recall search "preference"
 
 ## How It Works
 
-Claude Recall provides four memory tools backed by a local SQLite database with WAL mode, content-hash deduplication, and automatic compaction. The tools are exposed differently depending on the agent:
+Claude Recall provides six memory tools (`load_rules`, `store_memory`, `search_memory`, `delete_memory`, `save_checkpoint`, `load_checkpoint`) backed by a local SQLite database with WAL mode, content-hash deduplication, and automatic compaction. The tools are exposed differently depending on the agent:
 
 - **Claude Code** — MCP server with four tools and seven prompts, plus file-system hooks for automatic capture
 - **Pi** — native extension with registered tools and event handlers, plus a skill file for behavioral guidance
@@ -218,9 +218,11 @@ claude-recall monitor                    # Memory search monitoring stats
 ```bash
 claude-recall store "content"                # Store a memory (default type: preference)
 claude-recall store "content" -t correction  # Store with specific type
-claude-recall export backup.json             # Export all memories to JSON
+claude-recall export backup.json             # Export current project's memories to JSON
+claude-recall export backup.json --global    # Export ALL projects' memories
 claude-recall import backup.json             # Import memories from JSON
-claude-recall clear --force                  # Delete all memories (irreversible)
+claude-recall clear --force                  # Delete current project's memories (auto-backup written first)
+claude-recall clear --force --global         # Delete ALL projects' memories
 ```
 
 ### Task Checkpoints
@@ -324,9 +326,11 @@ claude-recall search "query" --json      # Output as JSON
 claude-recall search "query" --project <id>  # Search specific project
 claude-recall store "content"            # Store memory directly
 claude-recall store "content" -t <type>  # Store with type (preference, correction, failure, devops, project-knowledge)
-claude-recall export backup.json         # Export memories to JSON
+claude-recall export backup.json         # Export current project's memories to JSON
+claude-recall export backup.json --global # Export all projects
 claude-recall import backup.json         # Import memories from JSON
-claude-recall clear --force              # Clear all memories
+claude-recall clear --force              # Clear current project (auto-backup written first)
+claude-recall clear --force --global     # Clear all projects
 claude-recall failures                   # View failure memories
 claude-recall failures --limit 20        # Limit results
 claude-recall outcomes                   # Outcome-aware learning status
@@ -363,7 +367,7 @@ claude-recall mcp status                 # Current project's server status
 claude-recall mcp ps                     # List all running servers
 claude-recall mcp stop                   # Stop server
 claude-recall mcp stop --force           # Force stop
-claude-recall mcp restart                # Restart server
+claude-recall mcp restart                # Stop server + print start instructions (a stdio server can't self-respawn; Claude Code restarts it on next session)
 claude-recall mcp cleanup                # Remove stale PID files
 claude-recall mcp cleanup --all          # Stop all servers
 
@@ -374,12 +378,9 @@ claude-recall project register           # Register current project
 claude-recall project unregister [id]    # Unregister a project
 claude-recall project clean              # Remove stale registry entries
 
-# ── Database Migration ──────────────────────────────────────────────
-claude-recall migrate check              # Check if migration needed
-claude-recall migrate schema             # Show current schema version
-claude-recall migrate export             # Export pre-migration backup
-claude-recall migrate import             # Import from backup
-claude-recall migrate complete           # Run pending migrations
+# ── Database Maintenance ─────────────────────────────────────────────
+claude-recall compact                    # Dedup + prune retention overflow + VACUUM (also runs automatically on MCP boot)
+claude-recall compact --dry-run          # Preview what compaction would remove
 
 # ── Auto-Capture Hooks (run automatically, registered via setup --install) ──
 claude-recall hook run correction-detector   # UserPromptSubmit hook
@@ -443,6 +444,8 @@ Runtime behavior can be tuned via environment variables. Defaults are chosen so
 | `CLAUDE_RECALL_COMPACT_THRESHOLD`        | `10MB`  | DB size at which automatic compaction kicks in.                                                          |
 | `CLAUDE_RECALL_MAX_MEMORIES`             | `10000` | Memory-row soft cap.                                                                                     |
 | `CLAUDE_RECALL_ENFORCE_MODE`             | `on`    | Set to `off` to bypass the search-enforcer hook.                                                         |
+| `CLAUDE_RECALL_LLM_TIMEOUT_MS`           | `5000`  | Timeout for hook-context LLM calls (classification, hindsight hints). Hooks fall back to regex when it fires. |
+| `CLAUDE_RECALL_STOP_DEBOUNCE_MS`         | `300000` | Debounce for the heavy Stop-hook pipeline (episodes, session extraction, promotion). Citations still scan every turn. `0` disables. |
 
 ---
 

package/dist/cli/claude-recall-cli.js

@@ -42,7 +42,6 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const pattern_service_1 = require("../services/pattern-service");
-const migrate_1 = require("./commands/migrate");
 const server_1 = require("../mcp/server");
 const search_monitor_1 = require("../services/search-monitor");
 const skill_generator_1 = require("../services/skill-generator");
@@ -678,19 +677,22 @@ class ClaudeRecallCLI {
     async export(outputPath, options) {
         const format = options.format || 'json';
         try {
-            // Export all memories from the current project (+ universal). For a
-            // true cross-project dump, the user can run `--project` per project.
+            // Default: current project (+ universal/unscoped). --global dumps every
+            // project — use that before a global `clear --force --global`.
             const projectId = config_1.ConfigService.getInstance().getProjectId();
-            const memories = this.memoryService.getAllByProject(projectId);
+            const memories = options.global
+                ? this.memoryService.getAllMemories()
+                : this.memoryService.getAllByProject(projectId);
             if (format === 'json') {
                 const exportData = {
                     version: '0.2.0',
                     exportDate: new Date().toISOString(),
+                    scope: options.global ? 'all-projects' : projectId,
                     count: memories.length,
                     memories: memories
                 };
                 fs.writeFileSync(outputPath, JSON.stringify(exportData, null, 2));
-                console.log(`✅ Exported ${memories.length} memories to ${outputPath}`);
+                console.log(`✅ Exported ${memories.length} memories to ${outputPath}${options.global ? ' (all projects)' : ` (project: ${projectId})`}`);
             }
             else {
                 console.error(`❌ Unsupported format: ${format}`);
@@ -744,25 +746,44 @@ class ClaudeRecallCLI {
         }
     }
     /**
-     * Clear memories
+     * Clear memories. Project-scoped by default; --global wipes ALL projects.
+     * Always writes a full-DB backup file first so a mistaken clear is recoverable.
      */
     async clear(options) {
+        const projectId = options.global ? undefined : config_1.ConfigService.getInstance().getProjectId();
         if (!options.force) {
-            console.log('⚠️  This will permanently delete memories.');
+            if (options.global) {
+                console.log('⚠️  This will permanently delete memories from ALL projects.');
+            }
+            else {
+                console.log(`⚠️  This will permanently delete memories for project "${projectId}".`);
+                console.log('   (Universal/unscoped memories shared across projects are kept.)');
+                console.log('   Use --global to clear every project.');
+            }
             console.log('Use --force to confirm.');
             return;
         }
         try {
+            // Safety net: copy the DB file before deleting anything
+            const dbPath = config_1.ConfigService.getInstance().getDatabasePath();
+            let backupPath = null;
+            if (fs.existsSync(dbPath)) {
+                backupPath = `${dbPath}.backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+                fs.copyFileSync(dbPath, backupPath);
+            }
             const memoryService = memory_1.MemoryService.getInstance();
-            // Actually clear the memories
-            const count = memoryService.clear(options.type);
+            const count = memoryService.clear(options.type, projectId);
+            const scopeLabel = options.global ? 'all projects' : `project "${projectId}"`;
             if (options.type) {
-                console.log(`✅ Cleared ${count} memories of type: ${options.type}`);
+                console.log(`✅ Cleared ${count} memories of type ${options.type} (${scopeLabel})`);
             }
             else {
-                console.log(`✅ Cleared ${count} memories`);
+                console.log(`✅ Cleared ${count} memories (${scopeLabel})`);
             }
-            this.logger.info('CLI', 'Clear completed', { type: options.type, count });
+            if (backupPath) {
+                console.log(`   Backup written to: ${backupPath}`);
+            }
+            this.logger.info('CLI', 'Clear completed', { type: options.type, project: projectId || 'all', count });
         }
         catch (error) {
             console.error('❌ Clear failed:', error);
@@ -1013,7 +1034,8 @@ async function main() {
         }
     }
     // Install skills + minimal enforcement hook
-    function installSkillsAndHook(force = false) {
+    // TODO: honor force — currently `repair --reinstall-hooks` behaves identically to `setup --install`
+    function installSkillsAndHook(_force = false) {
         const cwd = process.cwd();
         const projectName = path.basename(cwd);
         console.log('\n📦 Claude Recall Setup\n');
@@ -1139,13 +1161,10 @@ async function main() {
                     hooks: [
                         {
                             type: "command",
-                            command: `${hookCmd} tool-outcome-watcher`,
-                            timeout: 3
-                        },
-                        {
-                            type: "command",
-                            command: `${hookCmd} rule-injection-resolver`,
-                            timeout: 3
+                            // Both handlers share one process — each extra node invocation
+                            // cold-boots the CLI and reopens the DB on every tool call
+                            command: `${hookCmd} tool-outcome-watcher rule-injection-resolver`,
+                            timeout: 5
                         }
                     ]
                 }
@@ -1155,13 +1174,8 @@ async function main() {
                     hooks: [
                         {
                             type: "command",
-                            command: `${hookCmd} tool-failure`,
-                            timeout: 3
-                        },
-                        {
-                            type: "command",
-                            command: `${hookCmd} rule-injection-resolver`,
-                            timeout: 3
+                            command: `${hookCmd} tool-failure rule-injection-resolver`,
+                            timeout: 5
                         }
                     ]
                 }
@@ -1187,7 +1201,11 @@ async function main() {
                     hooks: [
                         {
                             type: "command",
-                            command: `${hookCmd} correction-detector`
+                            command: `${hookCmd} correction-detector`,
+                            // Blocks prompt submission — must stay tight. The in-process
+                            // LLM call is capped at 5s (llm-classifier getClient), this
+                            // covers process startup on top.
+                            timeout: 8
                         }
                     ]
                 }
@@ -1197,13 +1215,10 @@ async function main() {
                     hooks: [
                         {
                             type: "command",
-                            command: `${hookCmd} memory-stop`,
-                            timeout: 30
-                        },
-                        {
-                            type: "command",
-                            command: `${hookCmd} memory-sync`,
-                            timeout: 10
+                            // Sequential in one process; memory-sync runs after memory-stop
+                            // so it syncs the rules memory-stop just updated
+                            command: `${hookCmd} memory-stop memory-sync`,
+                            timeout: 40
                         }
                     ]
                 }
@@ -1312,10 +1327,23 @@ async function main() {
             process.exit(2);
         }
         try {
+            // Interactive y/N confirmation when attached to a terminal. Without a
+            // TTY (and without --auto), runRepair fails safe and applies nothing.
+            const interactivePrompt = (!options.auto && !options.dryRun && process.stdin.isTTY)
+                ? (question) => new Promise((resolve) => {
+                    const readline = require('node:readline');
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                    rl.question(question, (answer) => {
+                        rl.close();
+                        resolve(/^y(es)?$/i.test(answer.trim()));
+                    });
+                })
+                : undefined;
             const result = await (0, repair_1.runRepair)({
                 auto: !!options.auto,
                 dryRun: !!options.dryRun,
                 scope,
+                prompt: interactivePrompt,
             });
             process.exit(result.exitCode);
         }
@@ -1722,7 +1750,6 @@ async function main() {
     // Hook commands (automatic memory capture)
     hook_commands_1.HookCommands.register(program);
     // Migration commands
-    migrate_1.MigrateCommand.register(program);
     // Search command
     program
         .command('search <query>')
@@ -1849,8 +1876,9 @@ async function main() {
     // Export command
     program
         .command('export <output>')
-        .description('Export memories to file')
+        .description('Export memories to file (current project by default)')
         .option('-f, --format <format>', 'Export format (json)', 'json')
+        .option('--global', 'Export memories from ALL projects')
         .action(async (output, options) => {
         const cli = new ClaudeRecallCLI(program.opts());
         await cli.export(output, options);
@@ -1868,14 +1896,41 @@ async function main() {
     // Clear command
     program
         .command('clear')
-        .description('Clear memories')
+        .description('Clear memories for the current project (use --global for all projects)')
         .option('-t, --type <type>', 'Clear specific memory type')
+        .option('--global', 'Clear memories from ALL projects, not just the current one')
         .option('--force', 'Confirm deletion')
         .action(async (options) => {
         const cli = new ClaudeRecallCLI(program.opts());
         await cli.clear(options);
         process.exit(0);
     });
+    // Compact command — manual trigger for the same compaction that runs
+    // automatically on MCP server boot when thresholds are exceeded.
+    program
+        .command('compact')
+        .description('Compact the database: dedup identical memories, prune retention overflow, VACUUM')
+        .option('--dry-run', 'Report what would be removed without changing anything')
+        .action(async (options) => {
+        try {
+            const { DatabaseManager } = await Promise.resolve().then(() => __importStar(require('../services/database-manager')));
+            const result = await DatabaseManager.getInstance().compact(!!options.dryRun);
+            const savedMB = ((result.beforeSize - result.afterSize) / 1024 / 1024).toFixed(2);
+            if (options.dryRun) {
+                console.log(`Dry run: would deduplicate ${result.deduplicatedCount} and prune ${result.removedCount} memories.`);
+            }
+            else {
+                console.log(`✅ Compaction done: deduplicated ${result.deduplicatedCount}, pruned ${result.removedCount}, saved ${savedMB}MB.`);
+                if (result.backupPath)
+                    console.log(`   Backup: ${result.backupPath}`);
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            console.error(`❌ Compaction failed: ${error.message}`);
+            process.exit(1);
+        }
+    });
     // Checkpoint command group
     const checkpoint = program
         .command('checkpoint')

package/dist/cli/commands/hook-commands.js

@@ -35,104 +35,139 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HookCommands = void 0;
 const shared_1 = require("../../hooks/shared");
+const AVAILABLE_HOOKS = [
+    'correction-detector',
+    'memory-stop',
+    'memory-sync',
+    'precompact-preserve',
+    'post-compact-reload',
+    'tool-outcome-watcher',
+    'tool-failure',
+    'rule-injector',
+    'rule-injection-resolver',
+    'subagent-start',
+    'subagent-stop',
+    'session-end-checkpoint',
+    'session-end-checkpoint-worker',
+    'bash-failure-watcher',
+];
 /**
  * Hook CLI Commands
  *
- * Dispatches `claude-recall hook run <name>` to the appropriate hook handler.
- * Reads stdin first (before dynamic import) then passes parsed input to the handler.
- * Always exits 0.
+ * Dispatches `claude-recall hook run <name...>` to the appropriate hook
+ * handler(s). Multiple names run sequentially in ONE process — each node
+ * invocation cold-boots the CLI and reopens the database, so hooks that fire
+ * on the same event (e.g. PostToolUse) should share an invocation.
+ * Reads stdin first (before dynamic import) then passes parsed input to the
+ * handlers. Always exits 0.
  */
 class HookCommands {
+    static async runOne(name, input) {
+        switch (name) {
+            case 'correction-detector': {
+                const { handleCorrectionDetector } = await Promise.resolve().then(() => __importStar(require('../../hooks/correction-detector')));
+                await handleCorrectionDetector(input);
+                break;
+            }
+            case 'memory-stop': {
+                const { handleMemoryStop } = await Promise.resolve().then(() => __importStar(require('../../hooks/memory-stop-hook')));
+                await handleMemoryStop(input);
+                break;
+            }
+            case 'precompact-preserve': {
+                const { handlePrecompactPreserve } = await Promise.resolve().then(() => __importStar(require('../../hooks/precompact-preserve')));
+                await handlePrecompactPreserve(input);
+                break;
+            }
+            case 'memory-sync': {
+                const { handleMemorySync } = await Promise.resolve().then(() => __importStar(require('../../hooks/memory-sync-hook')));
+                await handleMemorySync(input);
+                break;
+            }
+            case 'tool-outcome-watcher': {
+                const { handleToolOutcomeWatcher } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));
+                await handleToolOutcomeWatcher(input);
+                break;
+            }
+            case 'tool-failure': {
+                const { handleToolFailure } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));
+                await handleToolFailure(input);
+                break;
+            }
+            case 'post-compact-reload': {
+                const { handlePostCompactReload } = await Promise.resolve().then(() => __importStar(require('../../hooks/post-compact-reload')));
+                await handlePostCompactReload(input);
+                break;
+            }
+            case 'subagent-start': {
+                const { handleSubagentStart } = await Promise.resolve().then(() => __importStar(require('../../hooks/subagent-hooks')));
+                await handleSubagentStart(input);
+                break;
+            }
+            case 'subagent-stop': {
+                const { handleSubagentStop } = await Promise.resolve().then(() => __importStar(require('../../hooks/subagent-hooks')));
+                await handleSubagentStop(input);
+                break;
+            }
+            case 'bash-failure-watcher': {
+                // Backward compat alias — routes to tool-outcome-watcher
+                const { handleBashFailureWatcher } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));
+                await handleBashFailureWatcher(input);
+                break;
+            }
+            case 'session-end-checkpoint': {
+                const { handleSessionEndCheckpoint } = await Promise.resolve().then(() => __importStar(require('../../hooks/session-end-checkpoint')));
+                await handleSessionEndCheckpoint(input);
+                break;
+            }
+            case 'session-end-checkpoint-worker': {
+                const { handleSessionEndCheckpointWorker } = await Promise.resolve().then(() => __importStar(require('../../hooks/session-end-checkpoint-worker')));
+                await handleSessionEndCheckpointWorker(input);
+                break;
+            }
+            case 'rule-injector': {
+                const { handleRuleInjector } = await Promise.resolve().then(() => __importStar(require('../../hooks/rule-injector')));
+                await handleRuleInjector(input);
+                break;
+            }
+            case 'rule-injection-resolver': {
+                const { handleRuleInjectionResolver } = await Promise.resolve().then(() => __importStar(require('../../hooks/rule-injection-resolver')));
+                await handleRuleInjectionResolver(input);
+                break;
+            }
+            default:
+                console.error(`Unknown hook: ${name}`);
+                console.error(`Available: ${AVAILABLE_HOOKS.join(', ')}`);
+        }
+    }
     static register(program) {
         const hookCmd = program
             .command('hook')
             .description('Hook handlers for automatic memory capture');
         hookCmd
-            .command('run <name>')
-            .description('Run a hook handler (correction-detector | memory-stop | precompact-preserve)')
-            .action(async (name) => {
+            .command('run <names...>')
+            .description(`Run one or more hook handlers in a single process (${AVAILABLE_HOOKS.slice(0, 3).join(' | ')} | ...)`)
+            .action(async (names) => {
+            // Read stdin synchronously BEFORE dynamic import to avoid data loss;
+            // every handler receives the same event payload.
+            let input;
             try {
-                // Read stdin synchronously BEFORE dynamic import to avoid data loss
-                const input = (0, shared_1.readStdin)();
-                switch (name) {
-                    case 'correction-detector': {
-                        const { handleCorrectionDetector } = await Promise.resolve().then(() => __importStar(require('../../hooks/correction-detector')));
-                        await handleCorrectionDetector(input);
-                        break;
-                    }
-                    case 'memory-stop': {
-                        const { handleMemoryStop } = await Promise.resolve().then(() => __importStar(require('../../hooks/memory-stop-hook')));
-                        await handleMemoryStop(input);
-                        break;
-                    }
-                    case 'precompact-preserve': {
-                        const { handlePrecompactPreserve } = await Promise.resolve().then(() => __importStar(require('../../hooks/precompact-preserve')));
-                        await handlePrecompactPreserve(input);
-                        break;
-                    }
-                    case 'memory-sync': {
-                        const { handleMemorySync } = await Promise.resolve().then(() => __importStar(require('../../hooks/memory-sync-hook')));
-                        await handleMemorySync(input);
-                        break;
-                    }
-                    case 'tool-outcome-watcher': {
-                        const { handleToolOutcomeWatcher } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));
-                        await handleToolOutcomeWatcher(input);
-                        break;
-                    }
-                    case 'tool-failure': {
-                        const { handleToolFailure } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));
-                        await handleToolFailure(input);
-                        break;
-                    }
-                    case 'post-compact-reload': {
-                        const { handlePostCompactReload } = await Promise.resolve().then(() => __importStar(require('../../hooks/post-compact-reload')));
-                        await handlePostCompactReload(input);
-                        break;
-                    }
-                    case 'subagent-start': {
-                        const { handleSubagentStart } = await Promise.resolve().then(() => __importStar(require('../../hooks/subagent-hooks')));
-                        await handleSubagentStart(input);
-                        break;
-                    }
-                    case 'subagent-stop': {
-                        const { handleSubagentStop } = await Promise.resolve().then(() => __importStar(require('../../hooks/subagent-hooks')));
-                        await handleSubagentStop(input);
-                        break;
-                    }
-                    case 'bash-failure-watcher': {
-                        // Backward compat alias — routes to tool-outcome-watcher
-                        const { handleBashFailureWatcher } = await Promise.resolve().then(() => __importStar(require('../../hooks/tool-outcome-watcher')));
-                        await handleBashFailureWatcher(input);
-                        break;
-                    }
-                    case 'session-end-checkpoint': {
-                        const { handleSessionEndCheckpoint } = await Promise.resolve().then(() => __importStar(require('../../hooks/session-end-checkpoint')));
-                        await handleSessionEndCheckpoint(input);
-                        break;
-                    }
-                    case 'session-end-checkpoint-worker': {
-                        const { handleSessionEndCheckpointWorker } = await Promise.resolve().then(() => __importStar(require('../../hooks/session-end-checkpoint-worker')));
-                        await handleSessionEndCheckpointWorker(input);
-                        break;
-                    }
-                    case 'rule-injector': {
-                        const { handleRuleInjector } = await Promise.resolve().then(() => __importStar(require('../../hooks/rule-injector')));
-                        await handleRuleInjector(input);
-                        break;
-                    }
-                    case 'rule-injection-resolver': {
-                        const { handleRuleInjectionResolver } = await Promise.resolve().then(() => __importStar(require('../../hooks/rule-injection-resolver')));
-                        await handleRuleInjectionResolver(input);
-                        break;
-                    }
-                    default:
-                        console.error(`Unknown hook: ${name}`);
-                        console.error('Available: correction-detector, memory-stop, precompact-preserve, memory-sync, tool-outcome-watcher, session-end-checkpoint');
-                }
+                input = (0, shared_1.readStdin)();
+            }
+            catch (err) {
+                (0, shared_1.hookLog)('hook-dispatcher', `stdin read failed: ${(0, shared_1.safeErrorMessage)(err)}`);
+                process.exit(0);
             }
-            catch {
-                // Hooks must never block Claude — always exit 0
+            for (const name of names) {
+                try {
+                    await HookCommands.runOne(name, input);
+                }
+                catch (err) {
+                    // Hooks must never block Claude — always exit 0. But a swallowed
+                    // error with no log line means a hook can silently stop capturing
+                    // for weeks, so record it.
+                    (0, shared_1.hookLog)('hook-dispatcher', `${name}: ${(0, shared_1.safeErrorMessage)(err)}`);
+                }
             }
             process.exit(0);
         });

package/dist/cli/commands/repair.js

@@ -442,7 +442,22 @@ async function runRepair(options = {}) {
             reports,
         };
     }
-    if (!options.auto && !options.dryRun && options.prompt) {
+    if (!options.auto && !options.dryRun) {
+        // Fail safe: without a way to confirm (non-TTY and no prompt wired),
+        // never mutate settings files. Applying fixes requires explicit consent
+        // (interactive y/N) or an explicit --auto.
+        if (!options.prompt) {
+            log.log(`\n${totalFixable} fix(es) available but not applied: confirmation unavailable in non-interactive mode.`);
+            log.log('Re-run with --auto to apply safe fixes, or --dry-run to preview.\n');
+            return {
+                exitCode: 0,
+                filesScanned: files.length,
+                filesModified: 0,
+                fixesApplied: 0,
+                unfixable: totalUnfixable,
+                reports,
+            };
+        }
         const proceed = await options.prompt(`\nApply ${totalFixable} fix(es)? [y/N] `);
         if (!proceed) {
             log.log('Aborted. No files changed.\n');

package/dist/hooks/failure-detectors.js

@@ -298,7 +298,7 @@ function detectRetryLoops(interactions, consumed) {
             list.push(ix);
             counts.set(hash, list);
         }
-        for (const [hash, ixList] of counts) {
+        for (const ixList of counts.values()) {
             if (ixList.length < 3)
                 continue;
             // All already consumed?

package/dist/hooks/llm-classifier.js

@@ -58,6 +58,12 @@ Rules:
 - If a text is a question, greeting, or code block, classify as "none"`;
 /**
  * Lazy-init the Anthropic client. Returns null if SDK or API key unavailable.
+ *
+ * Hook context: these calls run inside Claude Code hooks, some of them
+ * synchronously blocking the user's prompt (UserPromptSubmit). The SDK's
+ * defaults (10-minute timeout, 2 retries) would stall the session on a slow
+ * or hung connection, so we cap the timeout and disable retries — a missed
+ * classification degrades to the regex fallback, which is the right trade.
  */
 function getClient() {
     if (clientInstance !== undefined)
@@ -69,7 +75,11 @@ function getClient() {
     try {
         // Dynamic require to avoid hard failure when SDK not installed
         const Anthropic = require('@anthropic-ai/sdk');
-        clientInstance = new Anthropic();
+        const timeoutMs = parseInt(process.env.CLAUDE_RECALL_LLM_TIMEOUT_MS || '5000', 10);
+        clientInstance = new Anthropic({
+            timeout: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 5000,
+            maxRetries: 0,
+        });
         return clientInstance;
     }
     catch {
@@ -119,9 +129,9 @@ async function classifyWithLLM(text) {
     }
 }
 /**
- * Classify multiple texts in a single Haiku API call.
- * Returns an array of results (null for unclassifiable items).
- * Falls back to null array on total failure (caller should use regex).
+ * Extract a failure-specific hindsight lesson from a failure description.
+ * Returns null on any failure (no API key, network error, parse error) —
+ * callers fall back to grounding the detector's generic remedy text.
  */
 async function extractHindsightHint(failureDescription, context) {
     const client = getClient();