linksee-memory 0.17.0 → 0.17.2

package/dist/db/migrate.js

@@ -1,19 +1,142 @@
 import Database from 'better-sqlite3';
 import { readFileSync } from 'node:fs';
-import { mkdirSync, renameSync, existsSync } from 'node:fs';
+import { mkdirSync, renameSync, existsSync, statSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { normalizeEntityName } from '../lib/normalize.js';
+import { isNativeLoadError } from '../lib/native-hint.js';
 const DEFAULT_DB_DIR = process.env.LINKSEE_MEMORY_DIR ?? join(homedir(), '.linksee-memory');
 const DB_PATH = join(DEFAULT_DB_DIR, 'memory.db');
 export function getDbPath() {
     return DB_PATH;
 }
+/** This package's version (dist/db/migrate.js → ../../package.json), for exact-version guidance. */
+export function packageVersion() {
+    try {
+        const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        return String(JSON.parse(readFileSync(pkg, 'utf8')).version || '');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The command that migrates / recovers this file. Pinned to this exact version: an unpinned
+ * `npx linksee-memory` could resolve to a cached older version, and versions before 0.17.2 have
+ * no `migrate` subcommand — they would start the MCP server instead (L-1-130).
+ */
+export function migrateCommand() {
+    const v = packageVersion();
+    // Never fall back to an unpinned command (Codex review of #19): if this version cannot be read,
+    // name the first version that has `migrate`, as a fixed string.
+    return /^\d+\.\d+\.\d+/.test(v) ? `npx -y linksee-memory@${v} migrate` : `npx -y linksee-memory@${MIGRATE_SINCE} migrate`;
+}
+/** First version with the `migrate` subcommand. */
+export const MIGRATE_SINCE = '0.17.2';
+/**
+ * Read the schema through a read-only connection (no checkpoint, no rollback). Returns what it
+ * found plus `tidy`, which removes the -wal/-shm that the read-only open itself added.
+ * Throws the native load error as is, and PrecheckError when the file could not be checked at all.
+ */
+export function probeReadonly(path) {
+    if (!existsSync(path))
+        return { probe: { kind: 'missing' }, tidy: () => { } };
+    const had = { wal: existsSync(path + '-wal'), shm: existsSync(path + '-shm') };
+    const walStat = had.wal ? statSync(path + '-wal') : null;
+    // Remove only what the read-only open itself added: a -wal that was absent and is still empty,
+    // and a -shm that was absent (e.g. a leftover -wal with no -shm — the reader builds one).
+    // 0.17.2 (Codex fifth review of #15, P2): another process may open the file in the same instant
+    // and start using the -shm. Two guards: (1) if the -wal changed while we looked (size or mtime),
+    // someone else is active → leave both; (2) the -shm is renamed aside first — on Windows a file
+    // another process has open cannot be renamed, so an in-use -shm stays. On POSIX an open -shm can
+    // still be renamed, so a writer that starts in the exact window remains a known limit.
+    const tidy = () => {
+        try {
+            if (had.wal) {
+                const now = existsSync(path + '-wal') ? statSync(path + '-wal') : null;
+                if (!now || !walStat || now.size !== walStat.size || now.mtimeMs !== walStat.mtimeMs)
+                    return;
+            }
+            else if (existsSync(path + '-wal')) {
+                if (statSync(path + '-wal').size !== 0)
+                    return; // someone wrote to it: not ours
+                unlinkSync(path + '-wal');
+            }
+            if (!had.shm && existsSync(path + '-shm')) {
+                const aside = `${path}-shm.tidy-${process.pid}`;
+                renameSync(path + '-shm', aside);
+                unlinkSync(aside);
+            }
+        }
+        catch { /* leave them; memory.db itself is untouched either way */ }
+    };
+    let v = 0;
+    try {
+        const ro = new Database(path, { readonly: true, fileMustExist: true });
+        try {
+            v = readSchemaVersion(ro);
+        }
+        finally {
+            ro.close();
+        }
+    }
+    catch (e) {
+        const code = e?.code ?? '';
+        const msg = e?.message ?? String(e);
+        // The file vanished between the check and the open: a new DB, as above.
+        if (!existsSync(path) && (code === 'SQLITE_CANTOPEN' || code === 'ENOENT' || /unable to open|does not exist/i.test(msg))) {
+            return { probe: { kind: 'missing' }, tidy: () => { } };
+        }
+        // The native addon itself failed: let it surface as such (the hooks turn it into one line).
+        if (isNativeLoadError(e))
+            throw e;
+        // Not a database at all.
+        if (code === 'SQLITE_NOTADB' || code === 'SQLITE_CORRUPT' || /not a database|malformed|disk image/i.test(msg)) {
+            return { probe: { kind: 'notadb' }, tidy };
+        }
+        tidy();
+        if (code === 'SQLITE_READONLY_ROLLBACK')
+            return { probe: { kind: 'hot' }, tidy: () => { } };
+        // Anything else (SQLITE_BUSY, locked, permission, I/O): we could not check it, so we do not
+        // write to it either — fail closed (0.17.1, Codex third review of #15).
+        throw new PrecheckError(path, code || msg.split('\n')[0]);
+    }
+    return { probe: { kind: 'version', version: v }, tidy };
+}
+/**
+ * Decide, WITHOUT a writable connection, whether this file may be opened for writing at all.
+ * (0.17.1, Codex re-review of #15.) A writable connection that is the last one to close
+ * checkpoints a leftover WAL into memory.db and deletes it, and rolls back a hot journal — both
+ * are writes to a file we are about to refuse. So the schema is read through a read-only
+ * connection first (SQLITE_OPEN_READONLY: no checkpoint, no rollback, memory.db and -wal untouched).
+ *   • schema 1–5                 → LegacySchemaError
+ *   • a hot rollback journal     → HotJournalError (it cannot be read without rolling back)
+ *   • not a DB                   → return; the normal open's corruption path moves it aside
+ *   • native addon failed        → rethrown as is
+ *   • anything else (busy, locked, unreadable) → PrecheckError: could not check, so no writing
+ * When the file is refused, the -wal/-shm that the read-only open itself created are removed
+ * again, so the folder is left as it was.
+ */
+function precheckBeforeWrite(path) {
+    const { probe, tidy } = probeReadonly(path);
+    if (probe.kind === 'hot')
+        throw new HotJournalError(path);
+    if (probe.kind === 'version' && probe.version > 0 && probe.version < MIN_SUPPORTED_SCHEMA) {
+        tidy();
+        throw new LegacySchemaError(probe.version, path);
+    }
+}
 function openAt(path) {
+    precheckBeforeWrite(path);
     const db = new Database(path);
     try {
-        db.pragma('journal_mode = WAL'); // first real read of the file header — throws if it isn't a DB
+        // Second line (the read-only precheck is the real gate): refuse before the journal-mode pragma.
+        // This is also the first real read of the file — it throws if the file isn't a DB.
+        const v = readSchemaVersion(db);
+        if (v > 0 && v < MIN_SUPPORTED_SCHEMA)
+            throw new LegacySchemaError(v, path);
+        db.pragma('journal_mode = WAL');
         db.pragma('foreign_keys = ON');
         return db;
     }
@@ -54,32 +177,102 @@ export function openDb() {
         throw err; // not a corruption we recognize — surface it
     }
 }
-export function runMigrations(db) {
+/** Oldest schema this version migrates in place. Older files are refused before any write. */
+export const MIN_SUPPORTED_SCHEMA = 6;
+/** Base class: openDb() refused this file without writing to it. The message says what to do. */
+export 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). 0.17.2: `linksee-memory migrate` (src/bin/migrate-legacy.ts).
+ */
+export class LegacySchemaError extends DbRefusedError {
+    schemaVersion;
+    constructor(schemaVersion, dbPath) {
+        super(`[linksee-memory] ${dbPath} is at schema ${schemaVersion}; this version migrates schema ${MIN_SUPPORTED_SCHEMA} and newer only. ` +
+            `Stopped before writing anything to the file.
+\n` +
+            `  1. Close every Claude Code / Cursor / other client using linksee-memory.
+\n` +
+            `  2. Back up the folder that holds memory.db (copy memory.db and any memory.db-wal / -shm / -journal) and keep the copy.
+\n` +
+            `  3. Do not open this file with another linksee-memory version in the meantime — older versions can delete or half-migrate rows.
+\n` +
+            `  4. Migrate it (it backs the file up first; --dry only reports): ${migrateCommand()} --dry, then the same without --dry.
+\n` +
+            `To start fresh instead, point LINKSEE_MEMORY_DIR at an empty folder.`);
+        this.name = 'LegacySchemaError';
+        this.schemaVersion = schemaVersion;
+    }
+}
+/** The read-only check could not run (busy, locked, unreadable): refused rather than guessed. */
+export class PrecheckError extends DbRefusedError {
+    reason;
+    constructor(dbPath, reason) {
+        super(`[linksee-memory] could not check ${dbPath} before opening it for writing (${reason}). ` +
+            `Stopped before writing anything. Another client may have it open or locked: close other ` +
+            `Claude Code / Cursor / linksee-memory processes and try again.`);
+        this.name = 'PrecheckError';
+        this.reason = reason;
+    }
+}
+/** A rollback journal left by an interrupted write: it cannot be read without being rolled back. */
+export class HotJournalError extends DbRefusedError {
+    constructor(dbPath) {
+        super(`[linksee-memory] ${dbPath} has an unfinished write from an interrupted process (memory.db-journal), ` +
+            `so it cannot be checked without changing it. Stopped before writing anything.
+\n` +
+            `  Back up the folder that holds memory.db (all memory.db* files) before anything else opens it, ` +
+            `then run: ${migrateCommand()} (it copies the files first, then lets SQLite roll the unfinished write back).`);
+        this.name = 'HotJournalError';
+    }
+}
+/** Read meta.schema_version without writing (0 when the table or row is absent). */
+export function readSchemaVersion(db) {
+    const metaTable = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();
+    if (!metaTable?.name)
+        return 0;
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+    return row ? Number(row.value) || 0 : 0;
+}
+export function runMigrations(db, opts = {}) {
+    const step = (name) => opts.onStep?.(name, db);
     const __filename = fileURLToPath(import.meta.url);
     const schemaPath = join(dirname(__filename), 'schema.sql');
     const sql = readFileSync(schemaPath, 'utf8');
     // Safely read current schema version. On a fresh DB the meta table doesn't
     // exist yet, which is fine — treat that as "version 0, full schema apply".
-    let currentVersion = 0;
-    const metaTable = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();
-    if (metaTable?.name) {
-        const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
-        if (versionRow)
-            currentVersion = Number(versionRow.value) || 0;
+    const currentVersion = readSchemaVersion(db);
+    // 0.17.1 (L-1-106 / audit F3): refuse schema 1–5 BEFORE any write. Their path through here
+    // (v5 → v6 generated columns, then the v5 entity merge running after the version has already
+    // been bumped to 16, with no transaction around it) can leave a half-migrated file. A safe,
+    // tested path is the `migrate` command (0.17.2): it backs up, sets allowLegacy and runs all of
+    // this inside one transaction. openDb() already refused these before any write; this is the
+    // second line for callers that hand in their own connection.
+    if (currentVersion > 0 && currentVersion < MIN_SUPPORTED_SCHEMA && !opts.allowLegacy) {
+        throw new LegacySchemaError(currentVersion, getDbPath());
     }
     // v3 → v4: rebuild memories_fts with trigram tokenizer for JP/CJK support.
     // Only runs when upgrading an existing DB from schema v1-3.
     if (currentVersion > 0 && currentVersion < 4) {
-        db.exec(`
-      DROP TRIGGER IF EXISTS trg_memories_fts_ai;
-      DROP TRIGGER IF EXISTS trg_memories_fts_ad;
-      DROP TRIGGER IF EXISTS trg_memories_fts_au;
-      DROP TABLE IF EXISTS memories_fts;
+        step('v3-v4');
+        db.exec(`
+      DROP TRIGGER IF EXISTS trg_memories_fts_ai;
+      DROP TRIGGER IF EXISTS trg_memories_fts_ad;
+      DROP TRIGGER IF EXISTS trg_memories_fts_au;
+      DROP TABLE IF EXISTS memories_fts;
     `);
     }
     // v4 → v5: add normalized_name column BEFORE schema.sql runs,
     // so the CREATE INDEX IF NOT EXISTS on (kind, normalized_name) succeeds.
     if (currentVersion > 0 && currentVersion < 5) {
+        step('v4-v5');
         const cols = db.prepare("PRAGMA table_info(entities)").all();
         if (!cols.some(c => c.name === 'normalized_name')) {
             db.exec('ALTER TABLE entities ADD COLUMN normalized_name TEXT');
@@ -93,6 +286,7 @@ export function runMigrations(db) {
     // NOTE: VIRTUAL generated columns are hidden from PRAGMA table_info.
     // Use PRAGMA table_xinfo (hidden=2 = VIRTUAL generated column) to detect them.
     if (currentVersion > 0 && currentVersion < 6) {
+        step('v5-v6');
         const xcols = db.prepare("PRAGMA table_xinfo(memories)").all();
         const hasAltitude = xcols.some(c => c.name === 'altitude' && c.hidden === 2);
         if (hasAltitude) {
@@ -113,14 +307,15 @@ export function runMigrations(db) {
     // thread_id groups related memories (session-level or decision chains).
     // memory_edges creates directed relationships between individual memories.
     if (currentVersion > 0 && currentVersion < 7) {
+        step('v6-v7');
         const cols = db.prepare("PRAGMA table_info(memories)").all();
         if (!cols.some(c => c.name === 'thread_id')) {
             db.exec('ALTER TABLE memories ADD COLUMN thread_id TEXT');
         }
         // Backfill thread_id from content JSON session_id for existing memories
-        db.exec(`
-      UPDATE memories SET thread_id = json_extract(content, '$.session_id')
-      WHERE thread_id IS NULL AND json_valid(content) AND json_extract(content, '$.session_id') IS NOT NULL
+        db.exec(`
+      UPDATE memories SET thread_id = json_extract(content, '$.session_id')
+      WHERE thread_id IS NULL AND json_valid(content) AND json_extract(content, '$.session_id') IS NOT NULL
     `);
     }
     // v8 → v9: ProjectCoreNode — extend drift_anchors into the Current Truth Map node.
@@ -128,7 +323,13 @@ export function runMigrations(db) {
     // detector/dashboard (which read the original columns + status active/retired) are unaffected.
     // `lifecycle` carries the rich state; `status` stays the coarse scan-gate. New tables
     // (reality_events, memory_write_candidates) are created by db.exec(sql) below (CREATE IF NOT EXISTS).
-    if (currentVersion > 0 && currentVersion < 9) {
+    // 0.17.1 (L-1-106 / audit F3): drift_anchors only exists from v8 on. On an older DB the table is
+    // missing, PRAGMA table_info returns nothing, and every ALTER below threw "no such table" — so
+    // any pre-0.12 DB could not start. If the table is absent, skip: db.exec(sql) below creates it
+    // with all of these columns.
+    const hasDriftAnchors = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='drift_anchors'").get();
+    if (currentVersion > 0 && currentVersion < 9 && hasDriftAnchors) {
+        step('v8-v9');
         const have = new Set(db.prepare('PRAGMA table_info(drift_anchors)').all().map((c) => c.name));
         const addCol = (name, ddl) => {
             if (!have.has(name))
@@ -151,6 +352,7 @@ export function runMigrations(db) {
     // without them). Only ALTER if map_nodes already exists; a v10→v12 jump creates
     // it fresh (with the columns) via db.exec(sql) below.
     if (currentVersion > 0 && currentVersion < 12) {
+        step('v11-v12');
         const hasMapNodes = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='map_nodes'").get();
         if (hasMapNodes) {
             const have = new Set(db.prepare('PRAGMA table_info(map_nodes)').all().map((c) => c.name));
@@ -164,6 +366,7 @@ export function runMigrations(db) {
     }
     // v12 → v13: edge strength + accounted-for expiry (anti-noise / anti-graveyard).
     if (currentVersion > 0 && currentVersion < 13) {
+        step('v12-v13');
         const has = (table, col) => db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === col);
         if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='map_edges'").get()) {
             if (!has('map_edges', 'strength'))
@@ -181,8 +384,10 @@ export function runMigrations(db) {
     // node or a `readme→docs-site` edge. SQLite can't alter a PK/UNIQUE, so drop + recreate;
     // safe because importMap rebuilds both from map.yaml on every run.
     if (currentVersion > 0 && currentVersion < 14) {
+        step('v13-v14');
         db.exec('DROP TABLE IF EXISTS map_nodes; DROP TABLE IF EXISTS map_edges;');
     }
+    step('schema.sql');
     db.exec(sql);
     if (currentVersion > 0 && currentVersion < 4) {
         db.exec(`INSERT INTO memories_fts(rowid, content) SELECT id, content FROM memories;`);
@@ -204,13 +409,14 @@ export function runMigrations(db) {
     // v4 → v5: entity name normalization for dedup prevention.
     // Adds normalized_name column + backfills from existing entity names.
     if (currentVersion > 0 && currentVersion < 5) {
-        migrateV5EntityNormalization(db);
+        step('v5-backfill');
+        migrateV5EntityNormalization(db, opts.mergeDuplicateEntities !== false);
     }
 }
 /**
  * v5 migration: add normalized_name column and backfill + merge duplicates.
  */
-function migrateV5EntityNormalization(db) {
+function migrateV5EntityNormalization(db, merge) {
     // Column + index already added before db.exec(sql) above.
     // Now backfill normalized_name for all entities.
     const entities = db.prepare('SELECT id, name FROM entities').all();
@@ -221,13 +427,17 @@ function migrateV5EntityNormalization(db) {
         }
     })();
     // 4. Auto-merge duplicate entities (same kind + normalized_name)
-    const dupes = db.prepare(`
-    SELECT kind, normalized_name, GROUP_CONCAT(id) as ids
-    FROM entities
-    WHERE normalized_name IS NOT NULL
-    GROUP BY kind, normalized_name
-    HAVING COUNT(*) > 1
+    const dupes = db.prepare(`
+    SELECT kind, normalized_name, GROUP_CONCAT(id) as ids
+    FROM entities
+    WHERE normalized_name IS NOT NULL
+    GROUP BY kind, normalized_name
+    HAVING COUNT(*) > 1
   `).all();
+    if (dupes.length > 0 && !merge) {
+        console.log(`[linksee-memory] v5 migration: ${dupes.length} duplicate entity clusters left as they are (not merged)`);
+        return;
+    }
     if (dupes.length > 0) {
         console.log(`[linksee-memory] v5 migration: merging ${dupes.length} duplicate entity clusters`);
         db.transaction(() => {
@@ -247,12 +457,12 @@ function mergeEntityCluster(db, ids) {
     if (ids.length < 2)
         return;
     // Score each entity: prefer most memories, then has canonical_key, then lowest id
-    const rows = db.prepare(`
-    SELECT e.id, e.name, e.canonical_key, COUNT(m.id) as mem_count
-    FROM entities e LEFT JOIN memories m ON m.entity_id = e.id
-    WHERE e.id IN (${ids.map(() => '?').join(',')})
-    GROUP BY e.id
-    ORDER BY mem_count DESC, (e.canonical_key IS NOT NULL) DESC, e.id ASC
+    const rows = db.prepare(`
+    SELECT e.id, e.name, e.canonical_key, COUNT(m.id) as mem_count
+    FROM entities e LEFT JOIN memories m ON m.entity_id = e.id
+    WHERE e.id IN (${ids.map(() => '?').join(',')})
+    GROUP BY e.id
+    ORDER BY mem_count DESC, (e.canonical_key IS NOT NULL) DESC, e.id ASC
   `).all(...ids);
     const keep = rows[0];
     const mergeIds = rows.slice(1).map(r => r.id);
@@ -273,16 +483,16 @@ function mergeEntityCluster(db, ids) {
         db.prepare('UPDATE events SET entity_id = ? WHERE entity_id = ?').run(keep.id, mid);
         // Reassign edges (both directions)
         // Handle UNIQUE constraint: delete duplicates first
-        db.prepare(`
-      DELETE FROM edges WHERE from_id = ? AND EXISTS (
-        SELECT 1 FROM edges e2 WHERE e2.from_id = ? AND e2.to_id = edges.to_id AND e2.relation = edges.relation
-      )
+        db.prepare(`
+      DELETE FROM edges WHERE from_id = ? AND EXISTS (
+        SELECT 1 FROM edges e2 WHERE e2.from_id = ? AND e2.to_id = edges.to_id AND e2.relation = edges.relation
+      )
     `).run(mid, keep.id);
         db.prepare('UPDATE edges SET from_id = ? WHERE from_id = ?').run(keep.id, mid);
-        db.prepare(`
-      DELETE FROM edges WHERE to_id = ? AND EXISTS (
-        SELECT 1 FROM edges e2 WHERE e2.to_id = ? AND e2.from_id = edges.from_id AND e2.relation = edges.relation
-      )
+        db.prepare(`
+      DELETE FROM edges WHERE to_id = ? AND EXISTS (
+        SELECT 1 FROM edges e2 WHERE e2.to_id = ? AND e2.from_id = edges.from_id AND e2.relation = edges.relation
+      )
     `).run(mid, keep.id);
         db.prepare('UPDATE edges SET to_id = ? WHERE to_id = ?').run(keep.id, mid);
         // Reassign consolidations

package/dist/lib/consolidate.d.ts

@@ -13,3 +13,12 @@ export declare function consolidate(db: Database.Database, opts?: {
     scope?: 'all' | 'session';
     min_age_days?: number;
 }): ConsolidateResult;
+/**
+ * Should the MCP server run consolidate on its own at start-up? (0.17.1, L-1-106 / audit F1)
+ *
+ * No, unless the user asked: consolidate deletes the original rows (keeping a 3 × 200-char
+ * summary) and their edges, so it must not run without an explicit opt-in.
+ * Opt in with LINKSEE_AUTO_CONSOLIDATE=1|true|on|weekly, or `--auto-consolidate` on the server
+ * command line. The weekly gate inside the server still applies once enabled.
+ */
+export declare function autoConsolidateEnabled(env: Record<string, string | undefined>, argv: readonly string[]): boolean;

package/dist/lib/consolidate.js

@@ -186,4 +186,18 @@ export function consolidate(db, opts = {}) {
     }
     return result;
 }
+/**
+ * Should the MCP server run consolidate on its own at start-up? (0.17.1, L-1-106 / audit F1)
+ *
+ * No, unless the user asked: consolidate deletes the original rows (keeping a 3 × 200-char
+ * summary) and their edges, so it must not run without an explicit opt-in.
+ * Opt in with LINKSEE_AUTO_CONSOLIDATE=1|true|on|weekly, or `--auto-consolidate` on the server
+ * command line. The weekly gate inside the server still applies once enabled.
+ */
+export function autoConsolidateEnabled(env, argv) {
+    if (argv.includes('--auto-consolidate'))
+        return true;
+    const v = (env.LINKSEE_AUTO_CONSOLIDATE ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'on' || v === 'yes' || v === 'weekly';
+}
 //# sourceMappingURL=consolidate.js.map

package/dist/lib/drift-anchors.js

@@ -74,9 +74,9 @@ export function declareAnchor(db, input) {
         throw new Error(`${input.kind} anchors need at least one violation_signal term (the forbidden act / rejected alternative) — otherwise the detector can never deduce a contradiction`);
     }
     const info = db
-        .prepare(`INSERT INTO drift_anchors
-         (kind, statement, rationale, affects, detect_terms, violation_signal, tier, source, source_memory_id)
-       VALUES
+        .prepare(`INSERT INTO drift_anchors
+         (kind, statement, rationale, affects, detect_terms, violation_signal, tier, source, source_memory_id)
+       VALUES
          (@kind, @statement, @rationale, @affects, @detect_terms, @violation_signal, @tier, @source, @source_memory_id)`)
         .run({
         kind: input.kind,

package/dist/lib/drift-detection.js

@@ -110,7 +110,7 @@ export function detectDrift(db, opts = {}) {
         samples: [],
     };
     const anchors = db
-        .prepare(`SELECT id, kind, statement, affects, detect_terms, violation_signal, tier, created_at
+        .prepare(`SELECT id, kind, statement, affects, detect_terms, violation_signal, tier, created_at
          FROM drift_anchors WHERE status = 'active'`)
         .all();
     res.anchorsScanned = anchors.length;
@@ -120,8 +120,8 @@ export function detectDrift(db, opts = {}) {
     // the "why this edit" text, not just path + snippet. (session_file_edits.memory_id →
     // memories.id; memories_fts.rowid = memories.id.)
     const edits = db
-        .prepare(`SELECT e.id, e.file_path, e.context_snippet, e.memory_id, m.content AS memory_content, e.occurred_at
-         FROM session_file_edits e
+        .prepare(`SELECT e.id, e.file_path, e.context_snippet, e.memory_id, m.content AS memory_content, e.occurred_at
+         FROM session_file_edits e
          LEFT JOIN memories m ON m.id = e.memory_id`)
         .all();
     res.editsScanned = edits.length;
@@ -137,19 +137,19 @@ export function detectDrift(db, opts = {}) {
     // Write paths prepared only when persisting — keeps dryRun safe on a readonly connection.
     const upsertContradicts = opts.dryRun
         ? null
-        : db.prepare(`
-        INSERT INTO drift_edges (anchor_id, edit_id, verdict, confidence, evidence, status)
-        VALUES (@anchor_id, @edit_id, 'contradicts', @confidence, @evidence, 'open')
-        ON CONFLICT(anchor_id, edit_id, verdict) DO UPDATE SET
-          confidence = excluded.confidence,
-          evidence   = excluded.evidence
-        WHERE drift_edges.status = 'open'
+        : db.prepare(`
+        INSERT INTO drift_edges (anchor_id, edit_id, verdict, confidence, evidence, status)
+        VALUES (@anchor_id, @edit_id, 'contradicts', @confidence, @evidence, 'open')
+        ON CONFLICT(anchor_id, edit_id, verdict) DO UPDATE SET
+          confidence = excluded.confidence,
+          evidence   = excluded.evidence
+        WHERE drift_edges.status = 'open'
       `);
     const insertAbsent = opts.dryRun
         ? null
-        : db.prepare(`
-        INSERT OR IGNORE INTO drift_edges (anchor_id, edit_id, verdict, confidence, evidence, status)
-        VALUES (@anchor_id, NULL, 'absent', @confidence, @evidence, 'open')
+        : db.prepare(`
+        INSERT OR IGNORE INTO drift_edges (anchor_id, edit_id, verdict, confidence, evidence, status)
+        VALUES (@anchor_id, NULL, 'absent', @confidence, @evidence, 'open')
       `);
     const apply = () => {
         for (const a of anchors) {
@@ -351,13 +351,13 @@ export function detectFileViolations(db, opts = {}) {
         .all();
     const upsert = opts.dryRun
         ? null
-        : db.prepare(`
-        INSERT INTO drift_edges (anchor_id, edit_id, verdict, confidence, evidence, status)
-        VALUES (@anchor_id, @edit_id, 'contradicts', @confidence, @evidence, 'open')
-        ON CONFLICT(anchor_id, edit_id, verdict) DO UPDATE SET
-          confidence = excluded.confidence,
-          evidence   = excluded.evidence
-        WHERE drift_edges.status = 'open'
+        : db.prepare(`
+        INSERT INTO drift_edges (anchor_id, edit_id, verdict, confidence, evidence, status)
+        VALUES (@anchor_id, @edit_id, 'contradicts', @confidence, @evidence, 'open')
+        ON CONFLICT(anchor_id, edit_id, verdict) DO UPDATE SET
+          confidence = excluded.confidence,
+          evidence   = excluded.evidence
+        WHERE drift_edges.status = 'open'
       `);
     const apply = () => {
         for (const a of anchors) {

package/dist/lib/drift-view.js

@@ -27,14 +27,14 @@ function parseEvidence(s) {
 export function getDriftHeadline(db, opts = {}) {
     const limit = opts.limit ?? 3;
     const rows = db
-        .prepare(`SELECT d.id AS edge_id, d.anchor_id, a.kind, a.statement, a.rationale,
-              e.file_path, e.context_snippet, e.occurred_at,
-              d.confidence, d.evidence
-         FROM drift_edges d
-         JOIN drift_anchors a ON a.id = d.anchor_id
-         JOIN session_file_edits e ON e.id = d.edit_id
-        WHERE d.verdict = 'contradicts' AND d.status = 'open' AND a.status = 'active'
-        ORDER BY d.confidence DESC, (a.tier = 'human') DESC, e.occurred_at DESC
+        .prepare(`SELECT d.id AS edge_id, d.anchor_id, a.kind, a.statement, a.rationale,
+              e.file_path, e.context_snippet, e.occurred_at,
+              d.confidence, d.evidence
+         FROM drift_edges d
+         JOIN drift_anchors a ON a.id = d.anchor_id
+         JOIN session_file_edits e ON e.id = d.edit_id
+        WHERE d.verdict = 'contradicts' AND d.status = 'open' AND a.status = 'active'
+        ORDER BY d.confidence DESC, (a.tier = 'human') DESC, e.occurred_at DESC
         LIMIT ?`)
         .all(limit);
     return rows.map((r) => {
@@ -61,12 +61,12 @@ export function getDriftHeadline(db, opts = {}) {
 export function getDriftAbsences(db, opts = {}) {
     const limit = opts.limit ?? 10;
     const rows = db
-        .prepare(`SELECT d.id AS edge_id, d.anchor_id, a.kind, a.statement, a.rationale,
-              d.confidence, d.evidence, d.detected_at
-         FROM drift_edges d
-         JOIN drift_anchors a ON a.id = d.anchor_id
-        WHERE d.verdict = 'absent' AND d.status = 'open' AND a.status = 'active'
-        ORDER BY a.created_at ASC
+        .prepare(`SELECT d.id AS edge_id, d.anchor_id, a.kind, a.statement, a.rationale,
+              d.confidence, d.evidence, d.detected_at
+         FROM drift_edges d
+         JOIN drift_anchors a ON a.id = d.anchor_id
+        WHERE d.verdict = 'absent' AND d.status = 'open' AND a.status = 'active'
+        ORDER BY a.created_at ASC
         LIMIT ?`)
         .all(limit);
     return rows.map((r) => {
@@ -85,8 +85,8 @@ export function getDriftAbsences(db, opts = {}) {
 }
 function countOpen(db, verdict) {
     return db
-        .prepare(`SELECT COUNT(*) AS n
-           FROM drift_edges d JOIN drift_anchors a ON a.id = d.anchor_id
+        .prepare(`SELECT COUNT(*) AS n
+           FROM drift_edges d JOIN drift_anchors a ON a.id = d.anchor_id
           WHERE d.verdict = ? AND d.status = 'open' AND a.status = 'active'`)
         .get(verdict).n;
 }

package/dist/lib/guard-wiring.d.ts

@@ -16,7 +16,53 @@ export declare const GUARD_EVENTS: readonly ["SessionStart", "PreToolUse"];
 export type GuardEvent = (typeof GUARD_EVENTS)[number];
 /** The bin every wiring form resolves to; used as the idempotency key. */
 export declare const GUARD_BIN = "linksee-memory-guard";
+/** The npx form setup wrote before 0.17.1. Still the fallback when no stable install exists. */
 export declare const GUARD_COMMAND = "npx -y linksee-memory guard";
+export declare const SYNC_COMMAND = "npx -y linksee-memory sync";
+export type HookKind = 'guard' | 'sync';
+export type HookCommands = Record<HookKind, string>;
+export declare const NPX_HOOK_COMMANDS: HookCommands;
+/**
+ * Marker setup appends to every direct-node hook it writes. It is an ordinary trailing argument
+ * (the hook scripts ignore argv), so it survives cmd.exe and sh alike — a `#` comment would not
+ * (cmd.exe has no inline comments). Only a command carrying it is treated as setup-owned.
+ */
+export declare const MANAGED_MARKER = "--linksee-managed";
+/**
+ * Direct `node` form (0.17.1, L-1-106 / audit F11): `npx -y` costs 6–9 s per call on a warm
+ * cache (npm start-up + a registry check), against an 8 s PreToolUse timeout — so the guard
+ * could time out and silently not fire. `"<node>" "<root>/dist/bin/<bin>.js" --linksee-managed`
+ * starts in well under a second.
+ *
+ * Shells: Claude Code runs a hook command through cmd.exe on Windows and through sh on POSIX
+ * (PowerShell is not used for hooks — assumed here; under PowerShell this form would need `&`).
+ * Double quotes protect spaces in both. They do NOT neutralise `$` or backticks (sh) or `%`
+ * (cmd.exe), and a path containing `"` cannot be quoted at all — see `shellSafePath`; setup falls
+ * back to the npx form for such paths instead of writing a command that might expand.
+ */
+export declare function nodeHookCommands(nodePath: string, packageRoot: string): HookCommands;
+/** Can this path go inside double quotes in both cmd.exe and sh without being expanded? */
+export declare function shellSafePath(p: string): boolean;
+/**
+ * Is this command one setup wrote — (a) the exact 0.17.0-and-earlier npx string, or (b) the
+ * 0.17.1+ direct form carrying MANAGED_MARKER? Anything else (wrappers, unquoted paths, extra
+ * flags, someone else's script) is not ours to change.
+ */
+export declare function setupWrittenKind(command: string | undefined): HookKind | null;
+/**
+ * Point the setup-written hooks of the given kinds at `commands`. Exec-form hooks (`args`), other
+ * tools' hooks and hand-edited commands are never touched. Only `command` changes — matcher,
+ * timeout and any other field stay. Mutates `settings`; returns the replaced commands.
+ */
+export declare function rewireLegacyHooks(settings: ClaudeSettings, commands: HookCommands, kinds?: readonly HookKind[]): {
+    replaced: string[];
+};
+/**
+ * Hooks that look like ours (they run the guard or the sync script) but were not written by setup —
+ * hand-wired paths, wrappers, exec form. setup leaves them alone and lists them so the user knows.
+ */
+export declare function unmanagedLinkseeHooks(settings: ClaudeSettings): string[];
+export declare function guardHooks(command?: string): Record<GuardEvent, HookEntry>;
 export declare const GUARD_HOOKS: Record<GuardEvent, HookEntry>;
 /**
  * Is one of OUR hooks of `kind` already wired for this event?
@@ -48,7 +94,7 @@ export declare function guardFullyWired(settings: ClaudeSettings): boolean;
  * Add the guard to any event it does not already own. Mutates and returns `settings`, plus the
  * events that were actually added (empty when it was already wired).
  */
-export declare function wireGuard(settings: ClaudeSettings): {
+export declare function wireGuard(settings: ClaudeSettings, command?: string): {
     settings: ClaudeSettings;
     added: GuardEvent[];
 };