claude-recall 0.24.1 → 0.25.0

package/README.md

@@ -291,7 +291,9 @@ tail -20 ~/.claude-recall/hook-logs/memory-stop.log
 tail -20 ~/.claude-recall/hook-logs/correction-detector.log
 
 # "Something is broken, start fresh"
-claude-recall repair                     # Clean up old hooks, reinstall skills
+claude-recall repair                     # Conservative: fix broken hook paths in settings.json (preserves your customizations)
+claude-recall repair --dry-run           # Preview what repair would change
+claude-recall repair --reinstall-hooks   # Opinionated: rewrite entire hook block from current template
 claude-recall setup --install            # Reinstall skills + hooks
 claude-recall mcp cleanup --all          # Stop all stale MCP servers
 ```
@@ -305,7 +307,11 @@ claude-recall setup                      # Show activation instructions
 claude-recall setup --install            # Install skills + hooks
 claude-recall upgrade                    # One-shot upgrade: global binary + clear stale MCP servers
 claude-recall status                     # Installation and system status
-claude-recall repair                     # Clean up old hooks, install skills
+claude-recall repair                     # Fix broken claude-recall hook paths (conservative: preserves user customizations)
+claude-recall repair --auto              # Non-interactive; apply safe fixes without prompting (used by postinstall)
+claude-recall repair --dry-run           # Report what would change without writing
+claude-recall repair --scope user|project|all  # Scope the scan (default: all)
+claude-recall repair --reinstall-hooks   # Opinionated: rewrite entire hook block from current template
 claude-recall hooks check                # Verify hook files exist and are valid
 claude-recall hooks test-enforcement     # Test if search enforcer hook works
 

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

@@ -49,6 +49,7 @@ const skill_generator_1 = require("../services/skill-generator");
 const mcp_commands_1 = require("./commands/mcp-commands");
 const project_commands_1 = require("./commands/project-commands");
 const hook_commands_1 = require("./commands/hook-commands");
+const repair_1 = require("./commands/repair");
 const program = new commander_1.Command();
 class ClaudeRecallCLI {
     constructor(options) {
@@ -391,43 +392,51 @@ class ClaudeRecallCLI {
         }
         console.log(`Installed: ${current}`);
         console.log(`Latest:    ${latest}`);
-        if (current === latest) {
-            console.log('\n✓ Already up to date.');
-            return;
+        const needsInstall = current !== latest;
+        if (needsInstall) {
+            console.log(`\n📦 Upgrading ${current} → ${latest}...\n`);
+            // Run npm install -g, streaming output so the user sees progress / errors live
+            const install = spawnSync('npm', ['install', '-g', 'claude-recall@latest'], {
+                stdio: 'inherit',
+            });
+            if (install.status !== 0) {
+                // npm prints its own error — add the practical remediation on top
+                console.error('\n❌ Install failed.');
+                console.error('\nMost common cause: your global npm prefix is owned by root (EACCES).');
+                console.error('\nQuick fix:');
+                console.error('  sudo npm install -g claude-recall');
+                console.error('\nPermanent fix (no more sudo for any global install on this machine):');
+                console.error('  mkdir -p ~/.npm-global');
+                console.error("  npm config set prefix ~/.npm-global");
+                console.error("  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc");
+                console.error('  source ~/.bashrc');
+                console.error('\nThen re-run: claude-recall upgrade');
+                process.exit(install.status ?? 1);
+            }
+            // Kill any running MCP servers so Claude Code respawns them with the new binary
+            console.log('\n🧹 Cleaning up running MCP servers (Claude Code respawns them on next tool call)...');
+            try {
+                spawnSync('claude-recall', ['mcp', 'cleanup', '--all'], { stdio: 'inherit' });
+            }
+            catch {
+                // Non-fatal — the user can restart Claude Code manually if this fails
+            }
         }
-        console.log(`\n📦 Upgrading ${current} → ${latest}...\n`);
-        // Run npm install -g, streaming output so the user sees progress / errors live
-        const install = spawnSync('npm', ['install', '-g', 'claude-recall@latest'], {
-            stdio: 'inherit',
-        });
-        if (install.status !== 0) {
-            // npm prints its own error — add the practical remediation on top
-            console.error('\n❌ Install failed.');
-            console.error('\nMost common cause: your global npm prefix is owned by root (EACCES).');
-            console.error('\nQuick fix:');
-            console.error('  sudo npm install -g claude-recall');
-            console.error('\nPermanent fix (no more sudo for any global install on this machine):');
-            console.error('  mkdir -p ~/.npm-global');
-            console.error("  npm config set prefix ~/.npm-global");
-            console.error("  echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc");
-            console.error('  source ~/.bashrc');
-            console.error('\nThen re-run: claude-recall upgrade');
-            process.exit(install.status ?? 1);
-        }
-        // Kill any running MCP servers so Claude Code respawns them with the new binary
-        console.log('\n🧹 Cleaning up running MCP servers (Claude Code respawns them on next tool call)...');
-        try {
-            spawnSync('claude-recall', ['mcp', 'cleanup', '--all'], { stdio: 'inherit' });
+        // Detect stale project-local installs that would shadow the global binary
+        // when invoked via `npx claude-recall`. Runs on every upgrade invocation,
+        // including when already up-to-date — so `claude-recall upgrade` doubles
+        // as a diagnostic for the npx-walks-up-and-finds-stale-local trap, and
+        // `claude-recall upgrade --clean-locals` works as a one-shot cleanup
+        // command even when no version change is pending.
+        this.warnOrCleanStaleLocals(latest, opts.cleanLocals === true);
+        if (needsInstall) {
+            console.log(`\n✓ Upgraded to ${latest}. No need to re-run \`claude mcp add\` — existing`);
+            console.log('  registrations point at the `claude-recall` command and pick up the new');
+            console.log('  binary automatically. Just run any tool in Claude Code.');
         }
-        catch {
-            // Non-fatal — the user can restart Claude Code manually if this fails
+        else {
+            console.log('\n✓ Already up to date.');
         }
-        // Detect stale project-local installs that would shadow the just-installed
-        // global binary when invoked via `npx claude-recall`.
-        this.warnOrCleanStaleLocals(latest, opts.cleanLocals === true);
-        console.log(`\n✓ Upgraded to ${latest}. No need to re-run \`claude mcp add\` — existing`);
-        console.log('  registrations point at the `claude-recall` command and pick up the new');
-        console.log('  binary automatically. Just run any tool in Claude Code.');
     }
     /**
      * Demote rules loaded often but never cited — excludes them from future load_rules payloads.
@@ -1281,14 +1290,41 @@ async function main() {
         }
         process.exit(0);
     });
-    // Repair command - cleans up old hooks and installs skills
+    // Repair command — conservative by default: fix broken hook paths without
+    // touching user customizations. --reinstall-hooks (or legacy --force) runs
+    // the opinionated installer that rewrites the entire hook block from template.
     program
         .command('repair')
-        .description('Clean up old hooks and install skills (v0.9.0+ migration)')
-        .option('--force', 'Force overwrite existing configuration')
-        .action((options) => {
-        installSkillsAndHook(options.force || false);
-        process.exit(0);
+        .description('Fix broken claude-recall hook paths in settings.json (conservative)')
+        .option('--auto', 'Non-interactive; apply safe fixes without prompting')
+        .option('--dry-run', 'Report what would change without writing any files')
+        .option('--reinstall-hooks', 'Rewrite the entire hook block from current template (opinionated)')
+        .option('--scope <scope>', 'user | project | all', 'all')
+        .option('--force', '[deprecated alias for --reinstall-hooks]')
+        .action(async (options) => {
+        if (options.reinstallHooks || options.force) {
+            installSkillsAndHook(true);
+            process.exit(0);
+        }
+        const scope = (options.scope || 'all');
+        if (!['user', 'project', 'all'].includes(scope)) {
+            console.error(`Invalid --scope: ${scope}. Use user, project, or all.`);
+            process.exit(2);
+        }
+        try {
+            const result = await (0, repair_1.runRepair)({
+                auto: !!options.auto,
+                dryRun: !!options.dryRun,
+                scope,
+            });
+            process.exit(result.exitCode);
+        }
+        catch (err) {
+            // Never crash postinstall. Log and exit 0 on unexpected errors so
+            // `npm install` continues. Surface via non-zero only for interactive runs.
+            console.error(`repair: unexpected error: ${err.message}`);
+            process.exit(options.auto ? 0 : 1);
+        }
     });
     // Check hooks function
     function checkHooks() {

package/dist/cli/commands/repair.js

@@ -0,0 +1,402 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOnPath = resolveOnPath;
+exports.classifyHook = classifyHook;
+exports.findSettingsFiles = findSettingsFiles;
+exports.scanFile = scanFile;
+exports.applyFixes = applyFixes;
+exports.runRepair = runRepair;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const CLAUDE_RECALL_CLI_RE = /claude[-_]recall[-_]cli(?:\.js)?/i;
+const HOOK_RUN_ID_RE = /hook\s+run\s+(\S+)/i;
+/**
+ * Resolve a binary name against PATH. POSIX-first; on Windows tries common
+ * extensions. Returns the first matching absolute path, or null.
+ */
+function resolveOnPath(binName) {
+    const pathEnv = process.env.PATH || '';
+    const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, binName + ext);
+            try {
+                const st = fs.statSync(candidate);
+                if (st.isFile())
+                    return candidate;
+            }
+            catch {
+                // not present — keep looking
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Decide whether a hook command belongs to claude-recall and, if so, whether
+ * its invocation target actually resolves on disk / on PATH. Pure function —
+ * no I/O except for the filesystem check on absolute script paths and the
+ * PATH probe (which the caller can stub via `claudeRecallResolver`).
+ */
+function classifyHook(command, claudeRecallResolver) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return { status: 'non-claude-recall' };
+    const tokens = trimmed.split(/\s+/);
+    const first = tokens[0] || '';
+    const base = path.basename(first);
+    const looksLikeCR = CLAUDE_RECALL_CLI_RE.test(trimmed) ||
+        base === 'claude-recall' ||
+        /\bclaude-recall\b/.test(trimmed);
+    if (!looksLikeCR)
+        return { status: 'non-claude-recall' };
+    const hookIdMatch = trimmed.match(HOOK_RUN_ID_RE);
+    const hookId = hookIdMatch ? hookIdMatch[1] : null;
+    // Case A: `node /abs/path/to/claude-recall-cli.js hook run ...`
+    //         or `/abs/path/to/node /abs/path/.../claude-recall-cli.js ...`
+    if (base === 'node' || /\/node$/.test(first)) {
+        const script = tokens[1];
+        if (script && path.isAbsolute(script) && CLAUDE_RECALL_CLI_RE.test(script)) {
+            if (!fs.existsSync(script)) {
+                return { status: 'broken-absolute', scriptPath: script, hookId };
+            }
+            return { status: 'ok' };
+        }
+        // Unusual node invocation we don't recognize — don't touch.
+        return { status: 'ok' };
+    }
+    // Case B: `claude-recall hook run ...` (PATH-resolved form — what we rewrite to)
+    if (base === 'claude-recall') {
+        if (claudeRecallResolver())
+            return { status: 'ok' };
+        return { status: 'broken-path', binary: 'claude-recall', hookId };
+    }
+    // Case C: `npx claude-recall ...` — npx resolves at runtime; treat as OK.
+    if (base === 'npx')
+        return { status: 'ok' };
+    // Anything else mentioning claude-recall — leave alone.
+    return { status: 'ok' };
+}
+/**
+ * Given the closest settings.json-like file path, return the list of paths
+ * to scan (settings.json + settings.local.json if present).
+ */
+function pickSiblings(settingsPath) {
+    const dir = path.dirname(settingsPath);
+    const out = [];
+    for (const name of ['settings.json', 'settings.local.json']) {
+        const p = path.join(dir, name);
+        if (fs.existsSync(p))
+            out.push(p);
+    }
+    return out;
+}
+function findSettingsFiles(cwd, home, scope) {
+    const results = [];
+    if (scope === 'user' || scope === 'all') {
+        const userDir = path.join(home, '.claude');
+        for (const p of pickSiblings(path.join(userDir, 'settings.json'))) {
+            if (!results.includes(p))
+                results.push(p);
+        }
+    }
+    if (scope === 'project' || scope === 'all') {
+        // Walk up looking for the CLOSEST .claude dir containing a settings file
+        // (matches Claude Code's own resolution). We don't scan ancestors beyond
+        // the first match — those belong to other projects.
+        let dir = cwd;
+        while (dir !== path.dirname(dir)) {
+            const claudeDir = path.join(dir, '.claude');
+            const s = path.join(claudeDir, 'settings.json');
+            const l = path.join(claudeDir, 'settings.local.json');
+            const hasAny = fs.existsSync(s) || fs.existsSync(l);
+            if (hasAny) {
+                if (fs.existsSync(s) && !results.includes(s))
+                    results.push(s);
+                if (fs.existsSync(l) && !results.includes(l))
+                    results.push(l);
+                break;
+            }
+            dir = path.dirname(dir);
+        }
+    }
+    return results;
+}
+function scanFile(settingsPath, claudeRecallResolver) {
+    const report = { settingsPath, findings: [] };
+    let raw;
+    try {
+        raw = fs.readFileSync(settingsPath, 'utf8');
+    }
+    catch (e) {
+        report.parseError = `cannot read: ${e.message}`;
+        return report;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        report.parseError = `invalid JSON: ${e.message}`;
+        return report;
+    }
+    if (typeof parsed.hooksVersion === 'string') {
+        report.hooksVersion = parsed.hooksVersion;
+    }
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== 'object')
+        return report;
+    const hasCR = () => claudeRecallResolver();
+    // Cache resolver result within a single scan to avoid hammering stat().
+    let cached;
+    const cachingResolver = () => {
+        if (cached === undefined)
+            cached = hasCR();
+        return cached ?? null;
+    };
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        groups.forEach((group, groupIndex) => {
+            if (!group || !Array.isArray(group.hooks))
+                return;
+            group.hooks.forEach((hook, hookIndex) => {
+                if (!hook || typeof hook.command !== 'string')
+                    return;
+                const classification = classifyHook(hook.command, cachingResolver);
+                if (classification.status === 'non-claude-recall')
+                    return;
+                const finding = {
+                    location: { settingsPath, event, groupIndex, hookIndex },
+                    originalCommand: hook.command,
+                    classification,
+                };
+                if (classification.status === 'broken-absolute') {
+                    const crPath = cachingResolver();
+                    if (crPath) {
+                        const id = classification.hookId;
+                        if (id) {
+                            finding.proposedCommand = `claude-recall hook run ${id}`;
+                        }
+                        // If we can't extract a hook id we don't know what subcommand to
+                        // invoke. Leave proposedCommand unset — reported as unfixable.
+                    }
+                }
+                report.findings.push(finding);
+            });
+        });
+    }
+    return report;
+}
+function applyFixes(report, opts) {
+    if (report.parseError)
+        return { changed: false, applied: 0, backupPath: null };
+    const fixable = report.findings.filter(f => f.proposedCommand);
+    if (fixable.length === 0)
+        return { changed: false, applied: 0, backupPath: null };
+    const raw = fs.readFileSync(report.settingsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed.hooks)
+        return { changed: false, applied: 0, backupPath: null };
+    let applied = 0;
+    for (const f of fixable) {
+        const { event, groupIndex, hookIndex } = f.location;
+        const group = parsed.hooks[event]?.[groupIndex];
+        const entry = group?.hooks?.[hookIndex];
+        if (!entry)
+            continue;
+        // Sanity: only rewrite if the command still matches what we scanned.
+        if (entry.command !== f.originalCommand)
+            continue;
+        entry.command = f.proposedCommand;
+        applied++;
+    }
+    if (applied === 0)
+        return { changed: false, applied: 0, backupPath: null };
+    if (opts.dryRun) {
+        return { changed: true, applied, backupPath: null };
+    }
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${report.settingsPath}.bak.${ts}`;
+    fs.writeFileSync(backupPath, raw);
+    fs.writeFileSync(report.settingsPath, JSON.stringify(parsed, null, 2));
+    return { changed: true, applied, backupPath };
+}
+function classify(finding) {
+    const c = finding.classification;
+    if (c.status === 'ok' || c.status === 'non-claude-recall')
+        return 'ok';
+    return finding.proposedCommand ? 'fixable' : 'unfixable';
+}
+function describe(finding) {
+    const c = finding.classification;
+    const loc = `${finding.location.event}[${finding.location.groupIndex}].hooks[${finding.location.hookIndex}]`;
+    if (c.status === 'broken-absolute') {
+        return `${loc}  missing script: ${c.scriptPath}`;
+    }
+    if (c.status === 'broken-path') {
+        return `${loc}  '${c.binary}' not on PATH`;
+    }
+    return `${loc}  ok`;
+}
+async function runRepair(options = {}) {
+    const log = options.logger ?? { log: console.log.bind(console), warn: console.warn.bind(console) };
+    const cwd = options.cwd ?? process.cwd();
+    const home = options.home ?? os.homedir();
+    const scope = options.scope ?? 'all';
+    const resolver = options.claudeRecallOnPath ?? (() => resolveOnPath('claude-recall'));
+    log.log('\n🩺 Claude Recall repair (conservative)\n');
+    const files = findSettingsFiles(cwd, home, scope);
+    if (files.length === 0) {
+        log.log(`No settings files found (scope: ${scope}).`);
+        log.log('Nothing to repair. If you meant to install hooks, run:');
+        log.log('  claude-recall setup --install\n');
+        return { exitCode: 0, filesScanned: 0, filesModified: 0, fixesApplied: 0, unfixable: 0, reports: [] };
+    }
+    const reports = [];
+    let totalFixable = 0;
+    let totalUnfixable = 0;
+    let totalOk = 0;
+    for (const f of files) {
+        const report = scanFile(f, resolver);
+        reports.push(report);
+        if (report.parseError) {
+            log.warn(`  ⚠  ${f}: ${report.parseError}`);
+            continue;
+        }
+        let fixable = 0, unfixable = 0, ok = 0;
+        for (const finding of report.findings) {
+            const kind = classify(finding);
+            if (kind === 'fixable')
+                fixable++;
+            else if (kind === 'unfixable')
+                unfixable++;
+            else
+                ok++;
+        }
+        totalFixable += fixable;
+        totalUnfixable += unfixable;
+        totalOk += ok;
+        const versionTag = report.hooksVersion ? ` (hooksVersion: ${report.hooksVersion})` : '';
+        log.log(`  ${f}${versionTag}`);
+        log.log(`    ${ok} OK, ${fixable} fixable, ${unfixable} unfixable`);
+        for (const finding of report.findings) {
+            if (classify(finding) === 'ok')
+                continue;
+            log.log(`    - ${describe(finding)}`);
+            if (finding.proposedCommand) {
+                log.log(`        proposed: ${finding.proposedCommand}`);
+            }
+        }
+    }
+    if (totalFixable === 0) {
+        if (totalUnfixable > 0) {
+            log.log(`\n${totalUnfixable} broken claude-recall hook(s) found but no safe fix available.`);
+            log.log('Install claude-recall on PATH so repair can rewrite the broken paths:');
+            log.log('  npm install -g claude-recall\n');
+            // Don't fail postinstall — user's current install was fine until their
+            // PATH/hook config drifted; this is diagnostic, not an error.
+            return {
+                exitCode: 0,
+                filesScanned: files.length,
+                filesModified: 0,
+                fixesApplied: 0,
+                unfixable: totalUnfixable,
+                reports,
+            };
+        }
+        log.log(`\n✅ All ${totalOk} claude-recall hook(s) look healthy. Nothing to do.\n`);
+        return {
+            exitCode: 0,
+            filesScanned: files.length,
+            filesModified: 0,
+            fixesApplied: 0,
+            unfixable: 0,
+            reports,
+        };
+    }
+    if (!options.auto && !options.dryRun && options.prompt) {
+        const proceed = await options.prompt(`\nApply ${totalFixable} fix(es)? [y/N] `);
+        if (!proceed) {
+            log.log('Aborted. No files changed.\n');
+            return {
+                exitCode: 0,
+                filesScanned: files.length,
+                filesModified: 0,
+                fixesApplied: 0,
+                unfixable: totalUnfixable,
+                reports,
+            };
+        }
+    }
+    let filesModified = 0;
+    let fixesApplied = 0;
+    for (const report of reports) {
+        const { changed, applied, backupPath } = applyFixes(report, { dryRun: !!options.dryRun });
+        if (changed && !options.dryRun) {
+            filesModified++;
+            fixesApplied += applied;
+            log.log(`  ✓ ${report.settingsPath}: applied ${applied} fix(es)`);
+            if (backupPath)
+                log.log(`    backup: ${backupPath}`);
+        }
+        else if (changed && options.dryRun) {
+            fixesApplied += applied;
+            log.log(`  (dry-run) ${report.settingsPath}: would apply ${applied} fix(es)`);
+        }
+    }
+    if (options.dryRun) {
+        log.log(`\nDry run complete. ${fixesApplied} fix(es) would be applied across ${reports.filter(r => r.findings.some(f => f.proposedCommand)).length} file(s).\n`);
+    }
+    else {
+        log.log(`\n✅ Repaired ${fixesApplied} hook(s) across ${filesModified} file(s).`);
+        if (totalUnfixable > 0) {
+            log.log(`   ${totalUnfixable} issue(s) still need manual attention (see above).`);
+        }
+        log.log('');
+    }
+    return {
+        exitCode: 0,
+        filesScanned: files.length,
+        filesModified,
+        fixesApplied,
+        unfixable: totalUnfixable,
+        reports,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-recall",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Persistent memory for Claude Code and Pi with native Skills integration, automatic capture, failure learning, and project scoping",
   "main": "dist/index.js",
   "bin": {

package/scripts/postinstall.js

@@ -117,6 +117,30 @@ try {
   // `claude-recall setup` invocation by the user, which is conscious and
   // produces a diff the user can see.
 
+  // Conservative repair on upgrade: fix broken absolute hook paths in
+  // ~/.claude/settings.json that reference a defunct claude-recall install
+  // (common when node/nvm versions change, or when the package was reinstalled
+  // into a different location). The --auto --scope user flags mean:
+  //   • only user-global settings are touched (no project files)
+  //   • only commands pointing at MISSING absolute scripts get rewritten
+  //   • user customizations (timeouts, matchers, sibling hooks) preserved
+  //   • writes a .bak.<timestamp> before any change
+  //   • never installs hooks where none exist — satisfies the "don't clobber"
+  //     rule above
+  try {
+    const cliPath = path.join(__dirname, '..', 'dist', 'cli', 'claude-recall-cli.js');
+    if (fs.existsSync(cliPath)) {
+      execSync(`node "${cliPath}" repair --auto --scope user`, {
+        stdio: 'inherit',
+        timeout: 15000
+      });
+    }
+  } catch (repairError) {
+    // Non-fatal: postinstall must never fail the npm install. Any repair
+    // problem can be fixed manually with `claude-recall repair`.
+    console.log('⚠️  Auto-repair skipped (non-fatal):', repairError.message);
+  }
+
   console.log('\n✅ Installation complete!\n');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('📌 ACTIVATE CLAUDE RECALL:');