linksee-memory 0.17.0 → 0.17.1

package/dist/bin/guard-hook.js

@@ -14,8 +14,14 @@
 //       "hooks": [ { "type": "command", "command": "node",
 //                    "args": ["${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js"], "timeout": 8 } ] } ] } }
 import { pathToFileURL } from 'node:url';
-import { openDb, runMigrations } from '../db/migrate.js';
-import { gateAction, buildBootDigest } from '../lib/guard.js';
+import { NATIVE_HINT, isNativeLoadError, hookLog } from '../lib/native-hint.js';
+/** Fail open (exit 0). Native-load failures say so once on stderr; anything else goes to hook.log only. */
+function bail(where, e) {
+    if (isNativeLoadError(e))
+        process.stderr.write(`${NATIVE_HINT}\n`);
+    hookLog(`guard: ${where}: ${String(e?.message ?? e).split('\n')[0]}`);
+    process.exit(0);
+}
 function readStdin() {
     return new Promise((resolve) => {
         const chunks = [];
@@ -37,14 +43,23 @@ async function main() {
     }
     if (!ev || typeof ev !== 'object')
         process.exit(0);
+    let openDb, runMigrations;
+    let gateAction, buildBootDigest;
+    try {
+        ({ openDb, runMigrations } = await import('../db/migrate.js'));
+        ({ gateAction, buildBootDigest } = await import('../lib/guard.js'));
+    }
+    catch (e) {
+        bail('import', e);
+    }
     let db;
     try {
         db = openDb();
         db.pragma('busy_timeout = 2000'); // MCP server may hold a write lock; wait briefly, else fail-open
         runMigrations(db); // ensures injection_log exists even when run standalone
     }
-    catch {
-        process.exit(0); // can't open DB → never block
+    catch (e) {
+        bail('open', e); // can't open DB → never block
     }
     try {
         if (ev.hook_event_name === 'PreToolUse') {

package/dist/bin/setup.js

@@ -36,11 +36,14 @@
 // detect_terms / violation_signal, so cross-repo noise is bounded by what you declared.
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
-import { guardFullyWired, wireGuard, syncWiredFor } from '../lib/guard-wiring.js';
+import Database from 'better-sqlite3';
+import { guardFullyWired, wireGuard, syncWiredFor, rewireLegacyHooks, unmanagedLinkseeHooks } from '../lib/guard-wiring.js';
+import { resolveHookRuntime, formatBytes } from '../lib/hook-runtime.js';
+import { readSettingsFile, stripBom, writeSettingsFile } from '../lib/settings-file.js';
 const args = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
 const autoYes = args.includes('--yes') || args.includes('-y');
@@ -49,20 +52,25 @@ const noGuard = args.includes('--no-guard');
 const projectGuard = args.includes('--project-guard');
 const showHelp = args.includes('--help') || args.includes('-h');
 if (showHelp) {
-    console.log(`linksee-memory-setup — One-command setup for Linksee Memory
-
-Usage:
-  npx linksee-memory setup          Interactive setup
-  npx linksee-memory setup --yes    Accept all defaults, no prompts
-  npx linksee-memory setup --dry-run Show what would happen
-
-What it does:
-  1. Registers linksee-memory MCP server with Claude Code
-  2. Installs SKILL.md (teaches the agent when to recall/remember)
-  3. Configures Stop hook (auto-captures every session)
-  4. Offers to wire the re-injection guard into THIS project's .claude/settings.json
-
-After setup, just chat with Claude Code normally.
+    console.log(`linksee-memory-setup — One-command setup for Linksee Memory
+
+Usage:
+  npx linksee-memory setup          Interactive setup
+  npx linksee-memory setup --yes    Accept all defaults, no prompts
+  npx linksee-memory setup --dry-run Show what would happen
+
+What it does:
+  1. Registers linksee-memory MCP server with Claude Code
+  2. Installs SKILL.md (teaches the agent when to recall/remember)
+  3. Configures Stop hook (auto-captures every session)
+  4. Wires the re-injection guard into ~/.claude/settings.json (every repo)
+     --project-guard: this repo only · --no-guard: skip
+
+Writes ~/.claude/settings.json (one settings.json.bak-<timestamp> kept before changing it),
+~/.claude/skills/linksee-memory/SKILL.md, and — when run through npx — a pinned copy under
+~/.linksee-memory/runtime/<version>/ that the hooks call with node directly.
+
+After setup, just chat with Claude Code normally.
 Add "Use Linksee" to any prompt to trigger memory recall.`);
     process.exit(0);
 }
@@ -76,12 +84,21 @@ const __filename = fileURLToPath(import.meta.url);
 const SKILL_SRC = join(dirname(__filename), '..', 'skill', 'SKILL.md');
 const SERVER_NAME = 'linksee';
 const MCP_COMMAND = `claude mcp add -s user ${SERVER_NAME} -- npx -y linksee-memory`;
-// Subcommand form (npx -y linksee-memory <sub>) so the hooks resolve for a cold user —
-// npx can resolve the package name, but not sibling bin names like linksee-memory-sync.
-const HOOK_COMMAND = 'npx -y linksee-memory sync';
-// Re-injection guard: command + merge rules live in lib/guard-wiring.ts (shared with the tests).
-// It points at the globally-installed bin rather than a dist path, so it ships without a build
-// step, and the shell form is resolved at run time so it survives npx-cache eviction.
+// Hook commands (0.17.1, L-1-106): `"<node>" "<package>/dist/bin/<bin>.js"` — node called directly,
+// not `npx -y linksee-memory <sub>` (6–9 s per call vs the 8 s PreToolUse timeout). When setup runs
+// from npx's temporary cache, lib/hook-runtime.ts installs this version under
+// <memory dir>/runtime/<version> (npm install, once) and the hooks point there; if that fails it
+// keeps the npx form and says so.
+// Merge / replace rules live in lib/guard-wiring.ts (shared with the tests).
+const PACKAGE_ROOT = join(dirname(__filename), '..', '..');
+const PACKAGE_VERSION = (() => {
+    try {
+        return String(JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version);
+    }
+    catch {
+        return 'unknown';
+    }
+})();
 const PROJECT_DIR = process.cwd();
 const PROJECT_CLAUDE_DIR = join(PROJECT_DIR, '.claude');
 const PROJECT_SETTINGS_PATH = join(PROJECT_CLAUDE_DIR, 'settings.json');
@@ -107,7 +124,7 @@ try {
         if (!existsSync(confFile))
             continue;
         try {
-            const conf = JSON.parse(readFileSync(confFile, 'utf8'));
+            const conf = JSON.parse(stripBom(readFileSync(confFile, 'utf8')));
             if (conf?.mcpServers?.[SERVER_NAME]) {
                 mcpAlreadyRegistered = true;
                 break;
@@ -198,40 +215,85 @@ else {
 console.log('');
 // ── Step 3: Configure Stop hook ──────────────────────────
 console.log(`${BOLD}[3/4]${RESET} Configuring auto-capture hook...`);
-let settings = {};
-if (existsSync(SETTINGS_PATH)) {
+const runtime = resolveHookRuntime({
+    packageRoot: PACKAGE_ROOT,
+    nodePath: process.execPath,
+    memoryDir: TELEMETRY_DIR,
+    version: PACKAGE_VERSION,
+    dryRun,
+    // For testing an unpublished build: what to npm-install instead of linksee-memory@<version>.
+    spec: process.env.LINKSEE_RUNTIME_SPEC || undefined,
+});
+const HOOK_COMMANDS = runtime.commands;
+const HOOK_COMMAND = HOOK_COMMANDS.sync;
+if (runtime.mode === 'npx') {
+    console.log(`  ${SKIP} Hooks use npx (slower, ~6–9 s per call): ${runtime.note ?? ''}`);
+}
+else {
+    console.log(`  ${DIM}Hooks call node directly: ${runtime.root}${runtime.note ? ` (${runtime.note})` : ''}${RESET}`);
+}
+// Hooks that run our scripts but were wired by hand (wrappers, unquoted paths, exec form) are
+// never rewritten; list them at the end so the user can update them if they want to.
+function handWiredNotice(path) {
+    const r = readSettingsFile(path);
+    if (!r.ok)
+        return;
+    for (const c of unmanagedLinkseeHooks(r.settings))
+        handWired.add(`${c}   (${path})`);
+}
+const handWired = new Set();
+/** writeSettingsFile that reports instead of throwing (a failed write leaves the file as it was). */
+function safeWrite(path, settings) {
     try {
-        settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'));
+        return writeSettingsFile(path, settings);
     }
-    catch {
-        console.log(`  ${FAIL} Could not parse ${SETTINGS_PATH}`);
-        settings = {};
+    catch (e) {
+        console.log(`  ${FAIL} Could not write ${path} (${e?.message ?? e}) — left as it was`);
+        return null;
     }
 }
-// Check if hook already exists
-const stopHooks = settings?.hooks?.Stop ?? [];
-// Recognise every shape the sync hook has been wired in (npx subcommand, global bin, dist
-// path, exec form) — a narrower probe appended a second copy, see lib/guard-wiring.ts.
-const alreadyHooked = syncWiredFor(settings, 'Stop');
-if (alreadyHooked) {
-    console.log(`  ${SKIP} Stop hook already configured`);
-}
-else if (dryRun) {
-    console.log(`  ${DIM}[dry-run] Would add Stop hook to ${SETTINGS_PATH}${RESET}`);
+// Same protection as the guard step below (lib/settings-file.ts): BOM stripped, an unparseable
+// file is left untouched, one .bak before the first write, temp file + rename.
+const stopRead = readSettingsFile(SETTINGS_PATH);
+if (!stopRead.ok) {
+    console.log(`  ${FAIL} Could not parse ${SETTINGS_PATH} (${stopRead.reason}) — left untouched`);
+    console.log(`  ${DIM}Fix the file, or add the Stop hook by hand: ${HOOK_COMMAND}${RESET}`);
 }
 else {
-    // Add hook
-    if (!settings.hooks)
-        settings.hooks = {};
-    if (!settings.hooks.Stop)
-        settings.hooks.Stop = [];
-    settings.hooks.Stop.push({
-        matcher: '',
-        hooks: [{ type: 'command', command: HOOK_COMMAND }],
-    });
-    mkdirSync(CLAUDE_DIR, { recursive: true });
-    writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf8');
-    console.log(`  ${CHECK} Stop hook added → ${SETTINGS_PATH}`);
+    const settings = stopRead.settings;
+    // Swap the Stop hook forms setup wrote (the exact 0.17.0 npx string, or our marked direct form).
+    // Only the sync kind here: the guard hooks are step 4's, after its --no-guard check.
+    const replaced = rewireLegacyHooks(settings, HOOK_COMMANDS, ['sync']).replaced;
+    // Recognise every shape the sync hook has been wired in (npx subcommand, global bin, dist
+    // path, exec form) — a narrower probe appended a second copy, see lib/guard-wiring.ts.
+    const alreadyHooked = syncWiredFor(settings, 'Stop');
+    if (alreadyHooked && replaced.length === 0) {
+        console.log(`  ${SKIP} Stop hook already configured`);
+    }
+    else if (dryRun) {
+        console.log(`  ${DIM}[dry-run] Would ${alreadyHooked ? 'switch the npx hooks to direct node calls in' : 'add Stop hook to'} ${SETTINGS_PATH}${RESET}`);
+    }
+    else {
+        if (!alreadyHooked) {
+            if (!settings.hooks)
+                settings.hooks = {};
+            if (!settings.hooks.Stop)
+                settings.hooks.Stop = [];
+            settings.hooks.Stop.push({
+                matcher: '',
+                hooks: [{ type: 'command', command: HOOK_COMMAND }],
+            });
+        }
+        const w = safeWrite(SETTINGS_PATH, settings);
+        if (w) {
+            if (replaced.length)
+                console.log(`  ${CHECK} Repointed ${replaced.length} hook(s) to ${HOOK_COMMANDS.sync.startsWith('npx') ? 'npx' : 'a direct node call'} → ${SETTINGS_PATH}`);
+            if (!alreadyHooked)
+                console.log(`  ${CHECK} Stop hook added → ${SETTINGS_PATH}`);
+            if (w.backup)
+                console.log(`  ${DIM}Previous file kept at ${w.backup}${RESET}`);
+        }
+    }
 }
 console.log('');
 // ── Step 4: Wire the re-injection guard (user-global by default) ─────────
@@ -259,24 +321,29 @@ async function configureGuard() {
         console.log(`  ${SKIP} Skipped (--no-guard). Enable later: npx -y linksee-memory setup`);
         return false;
     }
-    let settings = {};
-    if (existsSync(targetPath)) {
-        try {
-            // Strip a leading BOM (U+FEFF) — Windows editors (Notepad) emit UTF-8+BOM, which JSON.parse rejects.
-            const raw = readFileSync(targetPath, 'utf8');
-            settings = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
-        }
-        catch {
-            // Never clobber a file we can't parse — the user may have hand-authored it.
-            console.log(`  ${FAIL} Could not parse ${targetPath} — left untouched`);
-            console.log(`  ${DIM}Add the guard block by hand (see README → Re-injection Guard).${RESET}`);
-            return false;
-        }
+    // BOM stripped; never clobber a file we can't parse — the user may have hand-authored it.
+    const read = readSettingsFile(targetPath);
+    if (!read.ok) {
+        console.log(`  ${FAIL} Could not parse ${targetPath} (${read.reason}) — left untouched`);
+        console.log(`  ${DIM}Add the guard block by hand (see README → Re-injection Guard).${RESET}`);
+        return false;
     }
-    if (guardFullyWired(settings)) {
+    const settings = read.settings;
+    // Known npx forms → direct node call (exact matches only; see lib/guard-wiring.ts).
+    const { replaced } = rewireLegacyHooks(settings, HOOK_COMMANDS, ['guard']);
+    if (guardFullyWired(settings) && replaced.length === 0) {
         console.log(`  ${SKIP} Guard already wired in ${targetPath}`);
         return true;
     }
+    if (guardFullyWired(settings) && !dryRun) {
+        const w = safeWrite(targetPath, settings);
+        if (!w)
+            return false;
+        console.log(`  ${CHECK} Repointed ${replaced.length} guard hook(s) → ${targetPath}`);
+        if (w.backup)
+            console.log(`  ${DIM}Previous file kept at ${w.backup}${RESET}`);
+        return true;
+    }
     if (dryRun) {
         console.log(`  ${DIM}[dry-run] Would merge SessionStart + PreToolUse guard hooks into ${targetPath}${RESET}`);
         return false;
@@ -294,10 +361,13 @@ async function configureGuard() {
         }
     }
     // Merge, don't replace (see lib/guard-wiring.ts for the rules it holds to).
-    wireGuard(settings);
-    mkdirSync(targetDir, { recursive: true });
-    writeFileSync(targetPath, JSON.stringify(settings, null, 2), 'utf8');
+    wireGuard(settings, HOOK_COMMANDS.guard);
+    const w = safeWrite(targetPath, settings);
+    if (!w)
+        return false;
     console.log(`  ${CHECK} Guard wired → ${targetPath} ${DIM}(${scopeLabel})${RESET}`);
+    if (w.backup)
+        console.log(`  ${DIM}Previous file kept at ${w.backup}${RESET}`);
     if (!projectGuard) {
         console.log(`  ${DIM}Active in every repo. Scope an anchor with \`affects\` globs to limit where it fires;`);
         console.log(`  --no-guard to skip, --project-guard for this repo only.${RESET}`);
@@ -307,6 +377,25 @@ async function configureGuard() {
 const guardConfigured = await configureGuard();
 console.log('');
 // ── Telemetry consent (opt-in, anonymous, off unless you agree) ──────────
+/** True when there is no memory yet (or it cannot be read) — used only to pick the first-try text. */
+function memoryIsEmpty() {
+    const dbPath = join(TELEMETRY_DIR, 'memory.db');
+    if (!existsSync(dbPath))
+        return true;
+    try {
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            const row = db.prepare('SELECT COUNT(*) AS c FROM memories').get();
+            return !row || row.c === 0;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return true;
+    }
+}
 async function configureTelemetryConsent() {
     console.log(`${BOLD}Anonymous usage stats${RESET} ${DIM}(optional)${RESET}`);
     const env = (process.env.LINKSEE_TELEMETRY || '').toLowerCase().trim();
@@ -355,19 +444,45 @@ console.log('');
 console.log(`${BOLD}Setup complete!${RESET}`);
 console.log('');
 console.log('How it works:');
-console.log(`  ${DIM}• Every session is auto-captured (decisions, caveats, learnings)${RESET}`);
+console.log(`  ${DIM}• Every Claude Code session is auto-captured (decisions, caveats, learnings)${RESET}`);
 console.log(`  ${DIM}• Agent auto-recalls past context when starting a task${RESET}`);
 console.log(`  ${DIM}• Memory is local-first (your memory never leaves your machine)${RESET}`);
-console.log(`  ${DIM}• Works across Claude Code, Cursor, Windsurf, Codex, Gemini (cross-agent)${RESET}`);
+console.log(`  ${DIM}• The memory is shared over MCP by 5 clients (Claude Code, Cursor, Windsurf, Codex, Gemini CLI);${RESET}`);
+console.log(`  ${DIM}  auto-capture and the guard run in Claude Code only. Codex: codex mcp add linksee -- npx -y linksee-memory${RESET}`);
 if (guardConfigured) {
-    console.log(`  ${DIM}• Re-injection guard re-surfaces this project's accepted decisions before edits${RESET}`);
+    console.log(`  ${DIM}• Re-injection guard re-surfaces your accepted decisions before edits (${projectGuard ? 'this project' : 'every repo'})${RESET}`);
 }
 console.log('');
-console.log('Test by asking:');
-console.log(`  ${BOLD}"How did we solve this before?"${RESET}`);
-console.log(`  ${BOLD}"Same error again"${RESET}`);
-console.log(`  ${BOLD}"Remember: I prefer TypeScript over JavaScript"${RESET}`);
-console.log(`  ${BOLD}「前にこの問題どう解決したっけ」${RESET}`);
+// 0.17.1 never deletes pinned runtimes (Codex fourth review of #15: any automatic delete risked
+// removing one a hook still uses). Say what they cost and how to remove old ones by hand.
+if (runtime.mode === 'pinned' && runtime.runtimeBase && !dryRun) {
+    console.log(`  ${DIM}• Hooks run from ${runtime.runtimeBase}${sep}<version> (${runtime.bytes !== undefined ? formatBytes(runtime.bytes) : 'about 35 MB'} each). Older versions are not removed automatically;${RESET}`);
+    console.log(`  ${DIM}  0.17.2 adds \`linksee-memory runtime prune\`. Until then you can delete old ones by hand: ${runtime.runtimeBase}${RESET}`);
+    console.log('');
+}
+handWiredNotice(SETTINGS_PATH);
+if (projectGuard)
+    handWiredNotice(PROJECT_SETTINGS_PATH);
+if (handWired.size) {
+    console.log('Left as you wired them (not written by setup, so not changed):');
+    for (const c of handWired)
+        console.log(`  ${DIM}• ${c}${RESET}`);
+    console.log(`  ${DIM}setup writes "<node>" "<package>/dist/bin/<script>.js" --linksee-managed; switch to that form if you want setup to manage them.${RESET}`);
+    console.log('');
+}
+if (memoryIsEmpty()) {
+    // A fresh install has nothing to recall, so "how did we solve this before?" always comes back
+    // empty — the first thing a new user tries would fail. Offer a round trip that cannot.
+    console.log('Try it (your memory is empty, so start by giving it something):');
+    console.log(`  1. Say: ${BOLD}"Remember: in this repo we decided to use X, because Y."${RESET}`);
+    console.log(`  2. Open a ${BOLD}new${RESET} session and ask: ${BOLD}"What did we decide about X?"${RESET}`);
+}
+else {
+    console.log('Test by asking:');
+    console.log(`  ${BOLD}"How did we solve this before?"${RESET}`);
+    console.log(`  ${BOLD}"Same error again"${RESET}`);
+    console.log(`  ${BOLD}「前にこの問題どう解決したっけ」${RESET}`);
+}
 console.log('');
 console.log(`Or add ${BOLD}"Use Linksee"${RESET} to any prompt to trigger memory recall.`);
 console.log('');

package/dist/bin/share-draft.js

@@ -7,34 +7,34 @@
 //   npx -y linksee-memory share-draft --service freee --task "..." --symptom "..." \
 //     --tried "..." --result "..." --kind execution [--conditions "..."] [--runtime claude] [--json]
 import { buildShareDraft, ALLOWED_KEYS, KINDS, RUNTIMES, NOTICE, NOTICE_EN, DRAFT_PAGE, URL_MAX } from '../lib/share-draft.js';
-const HELP = `linksee-memory share-draft — make a link to a reviewed draft of a fix, for other agents
-
-Linksee sends nothing. This prints a URL to ${DRAFT_PAGE}
-The page opens with the fields filled; you read them there, and only your click sends.
-If you never run this (or the MCP tool share_draft), nothing happens.
-
-Usage:
-  npx -y linksee-memory share-draft --service <id> --task <text> --symptom <text> \\
-    --tried <text> --result <text> --kind <${KINDS.join('|')}> \\
-    [--conditions <text>] [--runtime <${RUNTIMES.join('|')}>] [--json]
-
-Fields (nothing else is accepted):
-  --service     KanseiLINK service_id, lowercase: ^[a-z0-9_.-]{1,160}$   (required)
-  --task        what you were trying to do, ≤300 chars                     (required)
-  --symptom     the KIND of error, no values, ≤600 chars                   (required)
-  --tried       steps you tried, ≤2,000 chars                              (required)
-  --result      how it was solved / that it was not, ≤1,000 chars          (required)
-  --conditions  tool + version, kind of environment, ≤600 chars
-  --kind        execution | documentation | hypothesis                     (required)
-  --runtime     claude | codex | gpt | gemini | other
-
-Stops (no link) when a field looks like a token / API key / JWT / Bearer value, an e-mail,
-a tenant URL (acme.slack.com …), an IP address, a local path (C:\\, /Users/, /home/), or a
-long hex / base64 run (32+), and says which field. The whole URL must be ≤${URL_MAX} chars
-(one Japanese character takes 9) — it asks you to shorten; it never cuts.
-
-${NOTICE[0]}
-${NOTICE[1]}
+const HELP = `linksee-memory share-draft — make a link to a reviewed draft of a fix, for other agents
+
+Linksee sends nothing. This prints a URL to ${DRAFT_PAGE}
+The page opens with the fields filled; you read them there, and only your click sends.
+If you never run this (or the MCP tool share_draft), nothing happens.
+
+Usage:
+  npx -y linksee-memory share-draft --service <id> --task <text> --symptom <text> \\
+    --tried <text> --result <text> --kind <${KINDS.join('|')}> \\
+    [--conditions <text>] [--runtime <${RUNTIMES.join('|')}>] [--json]
+
+Fields (nothing else is accepted):
+  --service     KanseiLINK service_id, lowercase: ^[a-z0-9_.-]{1,160}$   (required)
+  --task        what you were trying to do, ≤300 chars                     (required)
+  --symptom     the KIND of error, no values, ≤600 chars                   (required)
+  --tried       steps you tried, ≤2,000 chars                              (required)
+  --result      how it was solved / that it was not, ≤1,000 chars          (required)
+  --conditions  tool + version, kind of environment, ≤600 chars
+  --kind        execution | documentation | hypothesis                     (required)
+  --runtime     claude | codex | gpt | gemini | other
+
+Stops (no link) when a field looks like a token / API key / JWT / Bearer value, an e-mail,
+a tenant URL (acme.slack.com …), an IP address, a local path (C:\\, /Users/, /home/), or a
+long hex / base64 run (32+), and says which field. The whole URL must be ≤${URL_MAX} chars
+(one Japanese character takes 9) — it asks you to shorten; it never cuts.
+
+${NOTICE[0]}
+${NOTICE[1]}
 `;
 function parse(argv) {
     const fields = {};

package/dist/bin/sync-session.js

@@ -15,7 +15,9 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { isTelemetryEnabled, buildPayload, sendTelemetry } from '../lib/telemetry.js';
-import Database from 'better-sqlite3';
+import { NATIVE_HINT, isNativeLoadError } from '../lib/native-hint.js';
+// better-sqlite3 is imported dynamically below, so a broken native addon goes through the same
+// one-line hint as everything else instead of failing at module load (Codex third review of #15).
 const LOG_DIR = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
 const LOG_FILE = join(LOG_DIR, 'hook.log');
 const LOG_MAX_BYTES = 1024 * 1024; // 1 MB → rotate
@@ -86,6 +88,10 @@ async function main() {
     }
     else if (r.status !== 0) {
         log(`importer exited ${r.status} (session=${sessionId}, ${elapsed}ms): ${(r.stderr || '').slice(0, 500)}`);
+        // The native addon loads at `new Database()` inside the importer; after a Node major upgrade
+        // that is where it fails. Say so once — still exit 0, the Stop hook never blocks.
+        if (isNativeLoadError(r.stderr || ''))
+            process.stderr.write(`${NATIVE_HINT}\n`);
         process.exit(0);
     }
     const out = (r.stdout || '').trim().split('\n').slice(-1)[0] || '';
@@ -114,6 +120,7 @@ async function main() {
             const dbDir = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
             const dbPath = join(dbDir, 'memory.db');
             if (existsSync(dbPath)) {
+                const { default: Database } = await import('better-sqlite3');
                 const db = new Database(dbPath, { readonly: true });
                 try {
                     const payload = buildPayload(db, sessionId, { mcpServersInUse: mcpServers });
@@ -132,6 +139,8 @@ async function main() {
         }
         catch (e) {
             log(`telemetry: error (non-fatal): ${e?.message ?? e}`);
+            if (isNativeLoadError(e))
+                process.stderr.write(`${NATIVE_HINT}\n`);
         }
     }
     process.exit(0);

package/dist/db/migrate.d.ts

@@ -1,4 +1,34 @@
 import Database from 'better-sqlite3';
 export declare function getDbPath(): string;
 export declare function openDb(): Database.Database;
+/** Oldest schema this version migrates in place. Older files are refused before any write. */
+export declare const MIN_SUPPORTED_SCHEMA = 6;
+/** Base class: openDb() refused this file without writing to it. The message says what to do. */
+export declare class DbRefusedError extends Error {
+}
+/**
+ * Thrown for a schema older than MIN_SUPPORTED_SCHEMA (a DB last opened by a 2026-05-or-earlier
+ * version). Raised by openDb() from a read-only connection, before any writable connection exists,
+ * and again by runMigrations() as a second line.
+ *
+ * No old version is recommended as a stepping stone: 0.8.0–0.17.0 stop on `no such table:
+ * drift_anchors` after partly altering the file, and 0.7.2 has no subcommands — `npx
+ * linksee-memory@0.7.2 <anything>` starts its MCP server, whose start-up consolidate can delete
+ * original rows (Codex review of PR #15). A migration command for these files is 0.17.2 work.
+ */
+export declare class LegacySchemaError extends DbRefusedError {
+    readonly schemaVersion: number;
+    constructor(schemaVersion: number, dbPath: string);
+}
+/** The read-only check could not run (busy, locked, unreadable): refused rather than guessed. */
+export declare class PrecheckError extends DbRefusedError {
+    readonly reason: string;
+    constructor(dbPath: string, reason: string);
+}
+/** A rollback journal left by an interrupted write: it cannot be read without being rolled back. */
+export declare class HotJournalError extends DbRefusedError {
+    constructor(dbPath: string);
+}
+/** Read meta.schema_version without writing (0 when the table or row is absent). */
+export declare function readSchemaVersion(db: Database.Database): number;
 export declare function runMigrations(db: Database.Database): void;