linksee-memory 0.16.1 → 0.17.1

package/dist/db/migrate.js

@@ -1,19 +1,91 @@
 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;
 }
+/**
+ * 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) {
+    if (!existsSync(path))
+        return; // new DB: nothing to protect, create it
+    const had = { wal: existsSync(path + '-wal'), shm: existsSync(path + '-shm') };
+    // 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).
+    // Known limit (0.17.2): if another process opens the file in the same instant, the -shm deleted
+    // here may already be in use by it. The tests check a single process only, not concurrency.
+    const tidy = () => {
+        try {
+            if (!had.wal && existsSync(path + '-wal') && statSync(path + '-wal').size === 0)
+                unlinkSync(path + '-wal');
+            if (!had.shm && existsSync(path + '-shm'))
+                unlinkSync(path + '-shm');
+        }
+        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;
+        // 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: the normal open's corruption path moves it aside (nothing lost).
+        if (code === 'SQLITE_NOTADB' || code === 'SQLITE_CORRUPT' || /not a database|malformed|disk image/i.test(msg))
+            return;
+        tidy();
+        if (code === 'SQLITE_READONLY_ROLLBACK')
+            throw new HotJournalError(path);
+        // 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]);
+    }
+    if (v > 0 && v < MIN_SUPPORTED_SCHEMA) {
+        tidy();
+        throw new LegacySchemaError(v, 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,18 +126,82 @@ export function openDb() {
         throw err; // not a corruption we recognize — surface it
     }
 }
+/** 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). A migration command for these files is 0.17.2 work.
+ */
+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` +
+            `A migration command for this schema is planned for 0.17.2. 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. ` +
+            `A recovery command is planned for 0.17.2.`);
+        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) {
     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 migration is 0.17.2 work. 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) {
+        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.
@@ -128,7 +264,12 @@ 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) {
         const have = new Set(db.prepare('PRAGMA table_info(drift_anchors)').all().map((c) => c.name));
         const addCol = (name, ddl) => {
             if (!have.has(name))

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/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[];
 };

package/dist/lib/guard-wiring.js

@@ -10,17 +10,119 @@
 export const GUARD_EVENTS = ['SessionStart', 'PreToolUse'];
 /** The bin every wiring form resolves to; used as the idempotency key. */
 export const GUARD_BIN = 'linksee-memory-guard';
+/** The npx form setup wrote before 0.17.1. Still the fallback when no stable install exists. */
 export const GUARD_COMMAND = 'npx -y linksee-memory guard';
-export const GUARD_HOOKS = {
-    SessionStart: {
-        matcher: 'startup|resume|compact',
-        hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 15 }],
-    },
-    PreToolUse: {
-        matcher: 'Edit|Write|Bash',
-        hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 8 }],
-    },
+export const SYNC_COMMAND = 'npx -y linksee-memory sync';
+export const NPX_HOOK_COMMANDS = { guard: GUARD_COMMAND, sync: SYNC_COMMAND };
+/**
+ * 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 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 function nodeHookCommands(nodePath, packageRoot) {
+    const fwd = (p) => p.replace(/\\/g, '/');
+    const bin = (file) => `"${fwd(nodePath)}" "${fwd(packageRoot).replace(/\/$/, '')}/dist/bin/${file}" ${MANAGED_MARKER}`;
+    return { guard: bin('guard-hook.js'), sync: bin('sync-session.js') };
+}
+/** Can this path go inside double quotes in both cmd.exe and sh without being expanded? */
+export function shellSafePath(p) {
+    return !/["$`%!\r\n]/.test(p);
+}
+/** Exactly the npx strings setup wrote up to 0.17.0. */
+const LEGACY_NPX = {
+    guard: 'npx -y linksee-memory guard',
+    sync: 'npx -y linksee-memory sync',
 };
+/** The form setup itself writes from 0.17.1 on — quoted node, quoted script, the marker. */
+const MANAGED_NODE_FORM = /^"[^"]+" "[^"]+\/dist\/bin\/(guard-hook|sync-session)\.js" --linksee-managed$/;
+/**
+ * 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 function setupWrittenKind(command) {
+    if (typeof command !== 'string')
+        return null;
+    const c = command.trim();
+    for (const kind of ['guard', 'sync'])
+        if (LEGACY_NPX[kind] === c)
+            return kind;
+    const m = MANAGED_NODE_FORM.exec(c);
+    if (m)
+        return m[1] === 'guard-hook' ? 'guard' : 'sync';
+    return null;
+}
+function eachCommandHook(settings, fn) {
+    for (const entries of Object.values(settings.hooks ?? {})) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries)
+            for (const h of entry?.hooks ?? [])
+                if (h && h.type === 'command')
+                    fn(h);
+    }
+}
+/**
+ * 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 function rewireLegacyHooks(settings, commands, kinds = ['guard', 'sync']) {
+    const replaced = [];
+    eachCommandHook(settings, (h) => {
+        if (Array.isArray(h.args) && h.args.length)
+            return;
+        const kind = setupWrittenKind(h.command);
+        if (!kind || !kinds.includes(kind) || h.command === commands[kind])
+            return;
+        replaced.push(h.command);
+        h.command = commands[kind];
+    });
+    return { replaced };
+}
+/**
+ * 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 function unmanagedLinkseeHooks(settings) {
+    const out = [];
+    eachCommandHook(settings, (h) => {
+        const hay = [h.command, ...(h.args ?? [])].filter((x) => typeof x === 'string').join(' ');
+        const looksOurs = /guard-hook|sync-session/.test(hay) || (/linksee-memory/.test(hay) && /\b(guard|sync)\b/.test(hay));
+        if (!looksOurs)
+            return;
+        if ((!h.args || !h.args.length) && setupWrittenKind(h.command))
+            return;
+        out.push(hay);
+    });
+    return out;
+}
+export function guardHooks(command = GUARD_COMMAND) {
+    return {
+        SessionStart: {
+            matcher: 'startup|resume|compact',
+            hooks: [{ type: 'command', command, timeout: 15 }],
+        },
+        PreToolUse: {
+            matcher: 'Edit|Write|Bash',
+            hooks: [{ type: 'command', command, timeout: 8 }],
+        },
+    };
+}
+export const GUARD_HOOKS = guardHooks();
 /** Everything a hook entry could carry an identifier in: `command`, or `args` for the exec form. */
 function hookHaystack(h) {
     return [h?.command, ...(h?.args ?? [])].filter((x) => typeof x === 'string').join(' ');
@@ -69,14 +171,15 @@ export function guardFullyWired(settings) {
  * 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 function wireGuard(settings) {
+export function wireGuard(settings, command = GUARD_COMMAND) {
     const hooks = (settings.hooks ??= {});
     const added = [];
+    const wanted = guardHooks(command);
     for (const ev of GUARD_EVENTS) {
         if (!Array.isArray(hooks[ev]))
             hooks[ev] = [];
         if (!guardWiredFor(settings, ev)) {
-            hooks[ev].push(GUARD_HOOKS[ev]);
+            hooks[ev].push(wanted[ev]);
             added.push(ev);
         }
     }

package/dist/lib/hook-runtime.d.ts

@@ -0,0 +1,41 @@
+import { type HookCommands } from './guard-wiring.js';
+export type HookRuntime = {
+    commands: HookCommands;
+    /** 'direct' = this install is stable; 'pinned' = installed under runtime/; 'npx' = fallback. */
+    mode: 'direct' | 'pinned' | 'npx';
+    root?: string;
+    note?: string;
+    /** runtime/ folder and the version kept there, when pinned (setup reports where runtimes live). */
+    runtimeBase?: string;
+    version?: string;
+    /** Size of the pinned runtime in bytes, when one is in use. */
+    bytes?: number;
+};
+/** Is this package root inside a cache that npm / pnpm / bun may rebuild or delete? */
+export declare function isEphemeralRoot(packageRoot: string): boolean;
+/** Can a node process load the native dependency from this root? (the part most likely to break) */
+export declare function verifyRoot(root: string, nodePath: string): boolean;
+/** Locate npm's CLI script so it can be run with this node, without a shell. */
+export declare function findNpmCli(nodePath: string, env?: NodeJS.ProcessEnv): string | null;
+export type Installer = (spec: string, prefix: string, nodePath: string) => {
+    ok: boolean;
+    detail?: string;
+};
+/** `npm install --prefix <prefix> --no-save --omit=dev <spec>` with this node, no shell. */
+export declare const npmInstall: Installer;
+export declare function dirBytes(dir: string): number;
+export declare function formatBytes(n: number): string;
+export type ResolveOpts = {
+    packageRoot: string;
+    nodePath: string;
+    memoryDir: string;
+    version: string;
+    /** What to install; defaults to linksee-memory@<version>. */
+    spec?: string;
+    dryRun?: boolean;
+    /** Injected in tests; default = real child-process load check. */
+    verify?: (root: string, nodePath: string) => boolean;
+    /** Injected in tests; default = npm install with this node. */
+    install?: Installer;
+};
+export declare function resolveHookRuntime(o: ResolveOpts): HookRuntime;