claude-mem-lite 6.25.0 → 6.25.2

package/install.mjs

@@ -16,7 +16,6 @@ import {
   readdirSync,
   statSync,
   lstatSync,
-  accessSync,
   constants as fsConstants,
 } from 'fs';
 import { join, resolve, dirname, basename, sep } from 'path';
@@ -73,10 +72,12 @@ import { doctorDbModeHint } from './lib/doctor-modes.mjs';
 import { checkHookInterpreter } from './lib/doctor-hook-interpreter.mjs';
 import {
   classifyEpisodeFile,
+  classifyUpdateResidue,
   EPISODE_AGE_LABEL,
   isEpisodeResidue,
   isUpdateResidue,
   scanStaleTempFiles,
+  SWAP_RESOLVED_NAME,
 } from './lib/doctor-stale-temp.mjs';
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
@@ -96,9 +97,10 @@ import {
 import { detectInstallShape, probeRuntimeRoots, hasAnyManagedCode } from './lib/install-shape.mjs';
 import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
-import { acquireLock } from './lib/proc-lock.mjs';
+import { acquireLock, lockHeld } from './lib/proc-lock.mjs';
 import { atomicWriteFileSync, atomicCopyFileSync } from './lib/atomic-write.mjs';
 import { shellWord } from './cli-path.mjs';
+import { dirAccessError, walOpenBlocked, dataDirRemedy, WAL_BLOCKED_WHY } from './lib/wal-open-blocked.mjs';
 import {
   claudeConfigDir,
   claudeConfigDirFor,
@@ -1298,6 +1300,123 @@ function offerCleanOldVectorDb() {
   }
 }
 
+// A path, a dangling symlink included (existsSync follows the link).
+function pathPresent(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Update residue in the code dir, each entry with what it is (lib/doctor-stale-temp.mjs).
+function listUpdateResidue() {
+  return readdirSync(INSTALL_DIR)
+    .map((f) => ({ f, kind: classifyUpdateResidue(INSTALL_DIR, f) }))
+    .filter((r) => r.kind);
+}
+
+/**
+ * Finish what interrupted updates left in the code dir, the way the next update entry would:
+ * hook-update's recoverInterruptedSwaps replays each journal, then removes the residue. Reports
+ * every entry by what became of it. The caller holds install.lock.
+ *
+ * Never throws: install calls it before writing the tree, and a recovery that threw would stop
+ * the install it exists to protect. If hook-update cannot load, the residue of finished swaps is
+ * still removed and an unfinished swap is left whole (for install, which retires it once the
+ * tree is written, or for a later entry that can replay it).
+ * @param {{f: string, kind: string}[]} found entries from listUpdateResidue
+ * @returns {Promise<{finished: string[], removed: string[], kept: string[], deferred: string[],
+ *   unfinished: string[], left: string[]}>} kept: left on purpose because its journal cannot be
+ *   read; deferred: an unfinished swap left because hook-update could not load; unfinished: one the
+ *   replay did not finish, because a file could not be put back from it, or a later one that must be
+ *   finished first could not be finished or read (D#293); left: anything else
+ */
+async function recoverUpdateResidue(found) {
+  let replayed = true;
+  try {
+    const { recoverInterruptedSwaps } = await import('./hook-update.mjs');
+    recoverInterruptedSwaps(INSTALL_DIR);
+  } catch (e) {
+    replayed = false;
+    warn(`Could not finish an interrupted update here (${e.message}) — it is left in place`);
+  }
+  // Leftovers recovery did not take: a file or a symlink with the name (it replays only real
+  // directories), or everything when hook-update could not load. Only 'stale' ones go.
+  for (const { f, kind } of found) {
+    if (kind !== 'stale' || !pathPresent(join(INSTALL_DIR, f))) continue;
+    try {
+      rmSync(join(INSTALL_DIR, f), { recursive: true, force: true });
+    } catch {
+      /* reported below as left */
+    }
+  }
+  const out = { finished: [], removed: [], kept: [], deferred: [], unfinished: [], left: [] };
+  for (const { f, kind } of found) {
+    if (!pathPresent(join(INSTALL_DIR, f))) (kind === 'unfinished-swap' ? out.finished : out.removed).push(f);
+    else if (kind === 'unreadable-journal') out.kept.push(f);
+    else if (kind === 'unfinished-swap' && !replayed) out.deferred.push(f);
+    else if (kind === 'unfinished-swap' && classifyUpdateResidue(INSTALL_DIR, f) === 'unfinished-swap')
+      out.unfinished.push(f);
+    else out.left.push(f);
+  }
+  return out;
+}
+
+// A swap an updater was killed in the middle of is finished BEFORE this install writes the tree
+// (D#289). Its journal names an older release's paths; left for the next update entry, it was
+// replayed over the tree written here: it deleted the files the killed swap had added and put the
+// older ones back. Runs before the swap barrier, because the recovery arms and clears that marker.
+async function finishInterruptedSwaps() {
+  let found;
+  try {
+    found = listUpdateResidue();
+  } catch {
+    return; // no code dir yet, so nothing to finish
+  }
+  if (!found.some((r) => r.kind === 'unfinished-swap')) return;
+  const r = await recoverUpdateResidue(found);
+  if (r.finished.length > 0)
+    ok(`Finished ${r.finished.length} interrupted update(s) before installing: ${r.finished.join(', ')}`);
+  // A swap left unfinished here (deferred, kept, unfinished) is retired once the tree is written.
+  for (const f of r.unfinished)
+    warn(
+      `Could not finish the interrupted update ${f}: a file it moved aside could not be put back, or a later one that must be finished first could not be. This install writes over it and then retires it.`,
+    );
+  for (const f of r.left) warn(`Could not remove ${f} from ${INSTALL_DIR}`);
+}
+
+const isUnresolvedSwap = (f) => {
+  const kind = classifyUpdateResidue(INSTALL_DIR, f);
+  return kind === 'unfinished-swap' || kind === 'unreadable-journal';
+};
+
+// A journal still unresolved once deployCodeTree has written the code tree names paths of a
+// release this install has just replaced, and a later update entry would replay it over this tree:
+// delete the files the install wrote and put that release's back (v6.25.1 review; reached when
+// hook-update cannot load, or a journal cannot be read or removed). Marked resolved, it is never
+// replayed, and cleanup removes it as leftover. node_modules is written after this, by
+// installDependencies: if that fails, a node_modules the retired dir held is not put back (D#293).
+function retireLeftoverJournals() {
+  let names;
+  try {
+    names = readdirSync(INSTALL_DIR).filter(isUnresolvedSwap);
+  } catch {
+    return;
+  }
+  for (const f of names) {
+    try {
+      writeFileSync(join(INSTALL_DIR, f, SWAP_RESOLVED_NAME), '');
+      ok(`Retired ${f}: this install replaced the release it belongs to (cleanup removes it)`);
+    } catch (e) {
+      warn(
+        `Could not retire ${f} (${e.code || e.message}): delete it, or the next update puts back the files it holds`,
+      );
+    }
+  }
+}
+
 async function install() {
   console.log('\nclaude-mem-lite installer\n');
   // Refuse an unparseable settings.json BEFORE the first side effect (throws
@@ -1310,12 +1429,14 @@ async function install() {
   const IS_DEV = flags.has('--dev');
 
   prepareInstallDirs();
+  await finishInterruptedSwaps();
   // Both steps rewrite the tree hooks import — the code, then node_modules — so one swap
   // barrier spans them (D#223), for its first two minutes: the launcher ignores an older marker,
   // and npm install has no timeout. installDependencies may process.exit(1): the marker it leaves
   // names a dead pid, which the launcher ignores.
   await withSwapBarrier(async () => {
     deployCodeTree(IS_DEV);
+    retireLeftoverJournals();
     await installDependencies(IS_DEV);
   });
   createCliSymlink();
@@ -1742,14 +1863,22 @@ async function status() {
   }
 
   // Database. A data dir this process cannot enter reads as an empty one (D#199), and
-  // `exists: false` would be a guess — null says nobody could look.
+  // `exists: false` would be a guess — null says nobody could look. One it can read but not write
+  // (the 755 a `sudo` run leaves owned by root) is read where SQLite can open the store there: its
+  // counts are real, under a ✗ (D#284). A closed WAL store there cannot be opened; see the catch.
   const dataDirDenied = dataDirAccessError();
-  if (dataDirDenied) {
+  const dataDirUnreadable = dataDirDenied
+    ? dataDirAccessError(MEM_DATA_DIR, fsConstants.R_OK | fsConstants.X_OK)
+    : null;
+  const unwritable = dataDirDenied
+    ? ` — ${MEM_DATA_DIR} can be read but not written (${dataDirDenied}). Fix: ${dataDirAccessRemedy(dataDirDenied)}`
+    : '';
+  if (dataDirUnreadable) {
     push(
       'fail',
       'database',
-      `Database: ${MEM_DATA_DIR} is not accessible (${dataDirDenied}) — Fix: ${dataDirAccessRemedy()}`,
-      { exists: null, error: dataDirDenied },
+      `Database: ${MEM_DATA_DIR} is not accessible (${dataDirUnreadable}) — Fix: ${dataDirAccessRemedy(dataDirUnreadable)}`,
+      { exists: null, error: dataDirUnreadable },
     );
   } else if (existsSync(DB_PATH)) {
     try {
@@ -1759,19 +1888,38 @@ async function status() {
       // DISTINCT, like stats: a session can own several summary rows (legacy duplicates).
       const sess = db.prepare('SELECT COUNT(DISTINCT memory_session_id) as c FROM session_summaries').get();
       db.close();
-      push('ok', 'database', `Database: ${obs.c} observations, ${sess.c} sessions`, {
-        exists: true,
-        observations: obs.c,
-        sessions: sess.c,
-      });
+      push(
+        dataDirDenied ? 'fail' : 'ok',
+        'database',
+        `Database: ${obs.c} observations, ${sess.c} sessions${unwritable}`,
+        {
+          exists: true,
+          observations: obs.c,
+          sessions: sess.c,
+          ...(dataDirDenied && { error: dataDirDenied }),
+        },
+      );
     } catch (e) {
-      push('warn', 'database', 'Database: exists but check failed — ' + e.message, {
+      // The store is WAL (schema.mjs), and even a read-only open needs its -wal and -shm files, which
+      // SQLite creates beside the DB: in a directory it cannot write, a closed store cannot be opened
+      // in place (a copy elsewhere could be read) — 6.24.0 could not open it either. Say so rather than relay "attempt to write a readonly database".
+      // The errno stands in for SQLite's message only where the directory is the cause.
+      const walBlocked = walOpenBlocked(e.code, dataDirDenied, DB_PATH);
+      const why = walBlocked
+        ? `exists, but ${WAL_BLOCKED_WHY}`
+        : bindingMissing(e)
+          ? `exists, but not checked — ${BINDING_MISSING_WHY}`
+          : 'exists but check failed — ' + e.message;
+      push(dataDirDenied ? 'fail' : 'warn', 'database', `Database: ${why}${unwritable}`, {
         exists: true,
-        error: e.message,
+        error: walBlocked ? dataDirDenied : e.message,
       });
     }
   } else {
-    push('warn', 'database', 'Database: not found', { exists: false });
+    push(dataDirDenied ? 'fail' : 'warn', 'database', 'Database: not found' + unwritable, {
+      exists: false,
+      ...(dataDirDenied && { error: dataDirDenied }),
+    });
   }
 
   // CLI.
@@ -1990,12 +2138,21 @@ async function doctor() {
     fail(
       `Data directory: ${MEM_DATA_DIR} is not accessible (${dataDirDenied}) — ` +
         (dataDirUnreadable ? 'checks that read it say "not checked"' : 'it can be read but not written') +
-        `. Fix: ${dataDirAccessRemedy()}`,
+        `. Fix: ${dataDirAccessRemedy(dataDirDenied)}`,
     );
     issues++;
   }
   const notCheckedDenied = (what, dir = MEM_DATA_DIR) =>
     dwarn(`${what}: not checked — ${dir} is not accessible`);
+  // A closed WAL store in a data dir that can be read but not written: even a read-only open has to
+  // create the -wal/-shm files beside it, so every check that opens the DB fails, for the fault the
+  // Data directory line names and counts. Those checks say they did not look, in the words status
+  // uses (D#287, the D#199 shape). Keyed on SQLite's code: its message is shared with other faults.
+  const walBlocked = (code) => walOpenBlocked(code, dataDirDenied, DB_PATH);
+  const notCheckedWal = (what, scope = '') =>
+    dwarn(
+      `${what}: not checked${scope} — ${WAL_BLOCKED_WHY}, and ${MEM_DATA_DIR} cannot be written (see Data directory above)`,
+    );
   // The code dir is the data dir in the default shape; under CLAUDE_MEM_DIR it is checked apart.
   const codeIsDataDir = sameDir(INSTALL_DIR, MEM_DATA_DIR);
   const codeDirDenied = codeIsDataDir ? dataDirUnreadable : dataDirAccessError(INSTALL_DIR, readMode);
@@ -2016,7 +2173,10 @@ async function doctor() {
   // process.
   const rootProbes = probeRuntimeRoots(shape.runtimeRoots);
   const brokenRoots = rootProbes.filter((r) => !r.ok);
-  if (rootProbes.length === 0) {
+  if (rootProbes.length === 0 && codeDirDenied) {
+    // The code home is locked, so it may own a binding nobody could look at (D#284 review P3-4).
+    notCheckedDenied('better-sqlite3', INSTALL_DIR);
+  } else if (rootProbes.length === 0) {
     fail('better-sqlite3: no install on this machine owns a native binding — nothing here can open the DB');
     issues++;
   } else if (brokenRoots.length === 0) {
@@ -2064,6 +2224,8 @@ async function doctor() {
     notCheckedDenied('DB schema');
   } else if (!existsSync(DB_PATH)) {
     ok('DB schema: no database yet — nothing to compare');
+  } else if (rootProbes.length === 0 && codeDirDenied) {
+    notCheckedDenied('DB schema', INSTALL_DIR); // the locked code home may own one (D#284 review)
   } else if (rootProbes.length === 0) {
     // The fourth outcome the first cut had and did not print. The `fail` above already tells
     // the reader no install owns a binding, but a block whose stated design point is "three
@@ -2135,7 +2297,8 @@ async function doctor() {
       // printed as a green line is the defect the v6.2.0 round wrote and its pre-ship review
       // caught before the tag — a check that says "nothing to check" and "I could not look"
       // in the same voice ends the reader's search instead of directing it.
-      dwarn(`DB schema: could not determine compatibility for ${u.label} (${u.error})`);
+      if (walBlocked(u.errorCode)) notCheckedWal('DB schema', ` for ${u.label}`);
+      else dwarn(`DB schema: could not determine compatibility for ${u.label} (${u.error})`);
     }
   }
 
@@ -2220,7 +2383,11 @@ async function doctor() {
   // is 6h-rate-limited stderr nobody reads), the live probe says "is it broken
   // right now". A Node upgrade breaks every DB-touching path at once, so this is
   // the single highest-value line in doctor when it fires.
-  const breakage = readNativeBindingBreakage(MEM_RUNTIME_DIR);
+  // The marker sits in the runtime dir: in a locked data dir it reads as absent (D#284).
+  const breakageUnread = dataDirUnreadable && runtimeInDataDir;
+  const breakage = breakageUnread ? null : readNativeBindingBreakage(MEM_RUNTIME_DIR);
+  const breakageSeen = (b) =>
+    `~${Math.round((Date.now() - (b.ts || 0)) / 3600000)}h ago (${b.reason || 'unknown'})`;
   // Reuses the per-root probes above — same trees, same question, and doctor
   // should not pay for another round of child spawns to ask it twice.
   if (brokenRoots.length > 0) {
@@ -2228,10 +2395,20 @@ async function doctor() {
       `Native DB binding: unusable in ${brokenRoots.map((b) => b.label).join(', ')} — run \`node ${shellWord(join(PROJECT_DIR, 'cli.mjs'))} rebuild-binding\` (repairs every broken install, not just this one)`,
     );
     issues++;
+  } else if (rootProbes.length === 0) {
+    // Nothing was probed: a ✓ here sat under the better-sqlite3 ✗ for the same machine. Said, not
+    // left silent, like DB schema's fourth outcome above; a marker it could read still shows.
+    const why = codeDirDenied
+      ? `${INSTALL_DIR} is not accessible`
+      : 'no install on this machine owns a native binding to probe';
+    dwarn(
+      `Native DB binding: not checked — ${why}${breakage ? `; a fire failed ${breakageSeen(breakage)}` : ''}`,
+    );
+  } else if (breakageUnread) {
+    notCheckedDenied(`Native DB binding: loadable on Node ${process.version}, past failures`);
   } else if (breakage) {
-    const ageH = Math.round((Date.now() - (breakage.ts || 0)) / 3600000);
     dwarn(
-      `Native DB binding: healthy now, but a fire failed ~${ageH}h ago (${breakage.reason || 'unknown'}) — stale marker clears on the next successful rebuild-binding`,
+      `Native DB binding: healthy now, but a fire failed ${breakageSeen(breakage)} — stale marker clears on the next successful rebuild-binding`,
     );
   } else {
     ok(`Native DB binding: loadable on Node ${process.version}`);
@@ -2334,9 +2511,17 @@ async function doctor() {
   // with require-error noise every session. README's Uninstall section warns
   // about the right ordering; this check flags the broken state so it surfaces
   // even when the user skipped the README.
-  const orphanPaths = settings === null ? null : collectOrphanHookPaths(settings);
+  const unreadableHookPaths = [];
+  const orphanPaths =
+    settings === null ? null : collectOrphanHookPaths(settings, INSTALL_DIR, unreadableHookPaths);
   if (orphanPaths === null) {
     dwarn('Orphan hooks: not checked (settings.json unreadable)');
+  } else if (orphanPaths.length === 0 && unreadableHookPaths.length > 0) {
+    // A hook that points into a code home this user cannot enter is not an orphan: the file may
+    // well be there, and the Entry points line names and counts the locked dir (D#297).
+    dwarn(
+      `Orphan hooks: not checked — ${unreadableHookPaths.length} hook target(s) cannot be read (${unreadableHookPaths[0]}${unreadableHookPaths.length > 1 ? ', …' : ''})`,
+    );
   } else if (orphanPaths.length > 0) {
     fail(
       `Orphan hooks: ${orphanPaths.length} settings.json entr${orphanPaths.length === 1 ? 'y references a missing file' : 'ies reference missing files'}`,
@@ -2474,24 +2659,39 @@ async function doctor() {
         dwarn('FTS5 index: missing (will be created on server start)');
       }
     } catch (e) {
-      fail('Database: ' + e.message);
-      // Every other ✗ on this screen carries a remedy; this one used to be the exception,
-      // and a corrupt store is the failure a user is least able to diagnose unaided.
-      // dbCheckRemedy returns null rather than invent one for an error it cannot classify.
-      // Pre-ship review 2026-09-09: dbCheckRemedy became async and lazy (P1-1), which moved
-      // its failure mode from load time into THIS catch — and an unhandled rejection here
-      // aborts doctor exactly as the static import did, so `--json` still emitted zero bytes
-      // on the compound shape "a file is missing AND the database will not open". A remedy
-      // is an extra sentence on a check that has already failed; never let it take the run.
-      let remedy = null;
-      try {
-        remedy = await dbCheckRemedy(DB_PATH, e);
-      } catch (remedyErr) {
-        log(`    (could not build a repair hint: ${remedyErr.message})`);
+      if (walBlocked(e.code)) {
+        notCheckedWal('Database');
+      } else if (bindingMissing(e)) {
+        dwarn(`Database: not checked — ${BINDING_MISSING_WHY}`);
+      } else {
+        fail('Database: ' + e.message);
+        // Every other ✗ on this screen carries a remedy; this one used to be the exception,
+        // and a corrupt store is the failure a user is least able to diagnose unaided.
+        // dbCheckRemedy returns null rather than invent one for an error it cannot classify.
+        // Pre-ship review 2026-09-09: dbCheckRemedy became async and lazy (P1-1), which moved
+        // its failure mode from load time into THIS catch — and an unhandled rejection here
+        // aborts doctor exactly as the static import did, so `--json` still emitted zero bytes
+        // on the compound shape "a file is missing AND the database will not open". A remedy
+        // is an extra sentence on a check that has already failed; never let it take the run.
+        let remedy = null;
+        try {
+          remedy = await dbCheckRemedy(DB_PATH, e);
+        } catch (remedyErr) {
+          log(`    (could not build a repair hint: ${remedyErr.message})`);
+        }
+        if (remedy) log(`    ${remedy}`);
+        issues++;
       }
-      if (remedy) log(`    ${remedy}`);
-      issues++;
     }
+  } else if (rootProbes.length === 0) {
+    // "will be created" beside the better-sqlite3 line's "nothing here can open the DB" was a
+    // promise this screen had just contradicted (D#287). With the code home locked the binding
+    // was not looked for, so neither half is claimed.
+    dwarn(
+      codeDirDenied
+        ? 'Database: not found'
+        : 'Database: not found — and nothing here can create it until an install has a native binding (see better-sqlite3 above)',
+    );
   } else {
     dwarn('Database: not found (will be created)');
   }
@@ -2822,18 +3022,45 @@ async function doctor() {
   // Stale temp files. The rules live in lib/doctor-stale-temp.mjs because this scanner and
   // cleanup's deleter are the same question asked twice and had drifted twice — see that
   // file. Counting is all that differs here; the classification is shared, so "what doctor
-  // calls stale" and "what cleanup removes" agree on the age gate, which is the axis they
-  // last diverged on. Not on every axis: cleanup skips update residue entirely while
-  // install.lock is held and the scanner has no such gate, so mid-self-update doctor still
-  // counts a file cleanup will decline. That one is milder than D#53 — cleanup SAYS it is
-  // skipping rather than answering "No stale files found" — and it predates this change.
+  // calls stale" and "what cleanup removes" agree on the age gate and on the directory, the
+  // axes they diverged on (the third time, D#289: both looked for update residue in the data
+  // dir, which CLAUDE_MEM_DIR moves away from the code dir it lives in). And on the lock: while
+  // install.lock is held, cleanup skips update residue (a running update's own staging and backup
+  // dirs among it), so doctor does not count it either, and says it did not look (D#297). The holder
+  // may be any installer: an update, install, repair, a binding rebuild. It asks without taking it.
   try {
-    const { stale, inFlight } = scanStaleTempFiles({
-      dataDir: MEM_DATA_DIR,
+    const lockHeldNow = lockHeld(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
+    const { stale, inFlight, unfinishedSwaps, unreadableJournals, notChecked } = scanStaleTempFiles({
+      codeDir: INSTALL_DIR,
       runtimeDir: MEM_RUNTIME_DIR,
+      legacyDir: codeIsDataDir ? undefined : MEM_DATA_DIR,
+      installLockHeld: lockHeldNow,
     });
-    if (stale > 0) {
-      dwarn(`Stale temp files: ${stale} found (run: node install.mjs cleanup)`);
+    const installer = `node ${shellWord(join(PROJECT_DIR, 'install.mjs'))}`;
+    if (unfinishedSwaps > 0) {
+      dwarn(
+        `Unfinished update: ${unfinishedSwaps} backup dir(s) in ${INSTALL_DIR} still hold a swap journal — an update was interrupted, or could not put back every file it moved aside (run: ${installer} cleanup — it finishes them newest first, and stops at one it cannot read or put back)`,
+      );
+    }
+    if (unreadableJournals > 0) {
+      dwarn(
+        `Unfinished update: ${unreadableJournals} backup dir(s) in ${INSTALL_DIR} whose journal cannot be read, so nothing can finish that update; they hold the files it moved aside (run: ${installer} repair — it reinstalls over them; cleanup then removes them)`,
+      );
+    }
+    const skipped = lockHeldNow
+      ? `update residue not checked — install.lock is held (by a running install, update, repair or binding rebuild, or as a lock file this user cannot read), and cleanup skips it too`
+      : '';
+    if (notChecked.length > 0) {
+      const where = notChecked.map((n) => `${n.dir} is not accessible (${n.code})`).join('; ');
+      dwarn(
+        `Stale temp files: not checked — ${where}` +
+          (stale > 0 ? `; ${stale} found elsewhere (run: ${installer} cleanup)` : '') +
+          (skipped ? `; ${skipped}` : ''),
+      );
+    } else if (stale > 0) {
+      dwarn(`Stale temp files: ${stale} found (run: ${installer} cleanup)${skipped ? `; ${skipped}` : ''}`);
+    } else if (skipped) {
+      dwarn(`Stale temp files: ${skipped}`);
     } else {
       ok('Stale temp files: none');
     }
@@ -2875,7 +3102,9 @@ async function doctor() {
         dwarn(`${stats} — but the install you are running cannot use this database (see DB schema above)`);
       else ok(stats);
     } catch (e) {
-      dwarn('DB stats: ' + e.message);
+      if (walBlocked(e.code)) notCheckedWal('DB stats');
+      else if (bindingMissing(e)) dwarn(`DB stats: not checked — ${BINDING_MISSING_WHY}`);
+      else dwarn('DB stats: ' + e.message);
     }
   }
 
@@ -3000,9 +3229,31 @@ function looksLikeHookPath(p) {
   return HOOK_PATH_EXTS.some((ext) => p.endsWith(ext));
 }
 
-export function collectOrphanHookPaths(settings, installDir = INSTALL_DIR) {
+// 'missing' when the path is not there, 'unreadable' when it cannot be looked at (a directory on the
+// way this user cannot enter). existsSync answers false to both, so hooks pointing into a locked code
+// home were orphans, a second ✗ beside the Entry points line that names the lock (D#297).
+function hookTargetState(p) {
+  try {
+    statSync(p);
+    return 'present';
+  } catch (e) {
+    return e.code === 'ENOENT' || e.code === 'ENOTDIR' ? 'missing' : 'unreadable';
+  }
+}
+
+/**
+ * @param {string[]|null} [unreadable] collects the targets that could not be looked at, which are
+ *   not returned as missing
+ */
+export function collectOrphanHookPaths(settings, installDir = INSTALL_DIR, unreadable = null) {
   if (!settings?.hooks) return [];
   const out = [];
+  const judge = (p) => {
+    if (out.includes(p) || unreadable?.includes(p)) return;
+    const state = hookTargetState(p);
+    if (state === 'missing') out.push(p);
+    else if (state === 'unreadable') unreadable?.push(p);
+  };
   for (const configs of Object.values(settings.hooks)) {
     if (!Array.isArray(configs)) continue;
     for (const cfg of configs) {
@@ -3019,7 +3270,7 @@ export function collectOrphanHookPaths(settings, installDir = INSTALL_DIR) {
         // ERR_MODULE_NOT_FOUND — and doctor went back to printing "Orphan hooks: none".
         // Both files have to exist for the hook to run, so both are reportable.
         const entry = launcherEntryPath(cmd, installDir);
-        if (entry && !existsSync(entry) && !out.includes(entry)) out.push(entry);
+        if (entry) judge(entry);
         // v2.80: scan ALL quoted tokens (was: only the first), prefer ones
         // that look like a hook path. Fixes a footgun where a wrapper command
         // like `bash -c "some inline" "/real/path.sh"` would pick "some inline"
@@ -3038,7 +3289,7 @@ export function collectOrphanHookPaths(settings, installDir = INSTALL_DIR) {
           path = parts.find((p) => looksLikeHookPath(p)) || null;
         }
         if (!path) continue;
-        if (!existsSync(path) && !out.includes(path)) out.push(path);
+        judge(path);
       }
     }
   }
@@ -3229,7 +3480,7 @@ function writeSettings(settings) {
 
 // ─── Cleanup Stale Files ─────────────────────────────────────────────────────
 
-function cleanup() {
+async function cleanup() {
   // Dogfood-7 addition: --dry-run lists which files would be removed without
   // touching disk. Useful before running cleanup on a remote/CI machine where
   // accidentally pruning the wrong file would be costly. Doctor reports stale
@@ -3238,39 +3489,87 @@ function cleanup() {
   console.log(`\nclaude-mem-lite cleanup${dryRun ? ' (--dry-run)' : ''}\n`);
   let removed = 0;
 
-  // Clean .update-staging-* / .update-backup-* — hook-update writes these under
-  // DB_DIR (= MEM_DATA_DIR, env-aware), so scan the data dir, not the homedir code dir.
+  // Update residue: `.update-staging-*` / `.update-backup-*` in the CODE dir, where hook-update's
+  // swap writes them. Under CLAUDE_MEM_DIR this scanned only the data dir, where nothing has written
+  // them since v2.90.0; residue an older updater left there is still removed, below. A backup dir
+  // that holds its journal and no resolved marker is a swap whose updater was killed, holding the
+  // only copy of every file the swap had moved out: cleanup finishes it, by replaying the journal
+  // the way the next update entry would, instead of deleting it (D#289).
   //
-  // R10 P2-10: take install.lock first. `.update-backup-*` is the ONLY rollback copy of an
-  // in-flight update and it holds the journal hook-update replays; `.update-staging-*` is
-  // the tree being swapped in. Deleting either mid-update leaves the install unrecoverable,
-  // and the window is long — it spans the source-compile fallback, up to five minutes —
-  // while doctor is actively telling the user to run cleanup. Non-blocking: if an installer
-  // holds the lock we skip only these two patterns, not the rest of cleanup.
-  const updateLock = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
+  // R10 P2-10: take install.lock first. A backup dir of a swap running now holds a journal too,
+  // and the staging dir is the tree being swapped in; touching either mid-update leaves the install
+  // unrecoverable. The window is long (it spans the source-compile fallback, up to five minutes),
+  // and doctor tells the user to run cleanup. Non-blocking: if an installer holds the lock we skip
+  // only the update residue, not the rest of cleanup.
+  let finished = 0;
+  // --dry-run writes nothing, so it asks whether the lock is held instead of taking it: taking it
+  // created the data dir, its runtime dir and the lock on a machine with nothing installed (D#297).
+  const lockPath = join(MEM_DATA_DIR, 'runtime', 'install.lock'); // runtime-dir:stays-put — install lock serialises real installers
+  const updateLock = dryRun ? (lockHeld(lockPath) ? null : () => {}) : acquireLock(lockPath);
   if (!updateLock) {
     warn('Update residue skipped: install in progress (install.lock held)');
-  } else if (existsSync(MEM_DATA_DIR)) {
-    for (const f of readdirSync(MEM_DATA_DIR)) {
-      if (isUpdateResidue(f)) {
-        if (dryRun) {
-          ok(`Would remove: ${f}`);
-          removed++;
-          continue;
+  } else {
+    try {
+      let found = [];
+      try {
+        found = existsSync(INSTALL_DIR) ? listUpdateResidue() : [];
+      } catch (e) {
+        warn(`Update residue: could not list ${INSTALL_DIR} (${e.code || e.message})`);
+      }
+      if (dryRun) {
+        for (const { f, kind } of found) {
+          if (kind === 'unfinished-swap') {
+            ok(`Would finish an interrupted update: ${f} (puts back the files its journal lists)`);
+            finished++;
+          } else if (kind === 'unreadable-journal') {
+            warn(`Would leave in place: ${f} (its journal cannot be read)`);
+          } else {
+            ok(`Would remove: ${f}`);
+            removed++;
+          }
         }
-        try {
-          rmSync(join(MEM_DATA_DIR, f), { recursive: true, force: true });
-          ok(`Removed: ${f}`);
-          removed++;
-        } catch (e) {
-          warn(`Failed to remove ${f}: ${e.message}`);
+      } else if (found.length > 0) {
+        const r = await recoverUpdateResidue(found);
+        for (const f of r.finished)
+          ok(`Finished an interrupted update: ${f} (put back the files it had moved out)`);
+        for (const f of r.removed) ok(`Removed: ${f}`);
+        for (const f of r.kept)
+          warn(
+            `Left in place: ${f} — its journal cannot be read, so nothing can finish that update, and it holds the files the update moved aside. repair reinstalls over it; cleanup removes it after that.`,
+          );
+        for (const f of r.unfinished)
+          warn(
+            `Could not finish the interrupted update ${f}: a file it moved aside could not be put back (held open, or in a directory that cannot be emptied), or a later one that must be finished first could not be. It stays in place holding what it moved aside; cleanup tries again, and repair reinstalls over it instead.`,
+          );
+        for (const f of r.left) warn(`Failed to remove ${f}`);
+        finished += r.finished.length;
+        removed += r.removed.length;
+      }
+      // A relocated data dir that an updater older than v2.90.0 swapped into: its residue is stale,
+      // whatever it holds, and is never replayed (lib/doctor-stale-temp.mjs, legacyDir).
+      if (!sameDir(INSTALL_DIR, MEM_DATA_DIR) && existsSync(MEM_DATA_DIR)) {
+        for (const f of readdirSync(MEM_DATA_DIR)) {
+          if (!isUpdateResidue(f)) continue;
+          if (dryRun) {
+            ok(`Would remove: ${join(MEM_DATA_DIR, f)}`);
+            removed++;
+            continue;
+          }
+          try {
+            rmSync(join(MEM_DATA_DIR, f), { recursive: true, force: true });
+            ok(`Removed: ${join(MEM_DATA_DIR, f)}`);
+            removed++;
+          } catch (e) {
+            warn(`Failed to remove ${join(MEM_DATA_DIR, f)}: ${e.message}`);
+          }
         }
       }
+    } finally {
+      // Released here: the rest of cleanup touches runtime scratch that no installer owns, and
+      // holding install.lock across it would block a self-heal for no reason.
+      updateLock();
     }
   }
-  // Release immediately: the rest of cleanup touches runtime scratch that no installer owns,
-  // and holding install.lock across it would block a self-heal for no reason.
-  if (updateLock) updateLock();
 
   // Clean pending-* / ep-flush-* in runtime/ (env-aware, and honouring the runtime override).
   //
@@ -3322,7 +3621,11 @@ function cleanup() {
   // start of every run (tests/global-setup.mjs → lib/tmp-fixture-sweep.mjs).
 
   const verb = dryRun ? 'would be removed' : 'removed';
-  console.log(`\n  ${removed === 0 ? 'No stale files found.' : `${removed} stale file(s) ${verb}.`}\n`);
+  const done = [];
+  if (removed > 0) done.push(`${removed} stale file(s) ${verb}`);
+  if (finished > 0)
+    done.push(`${finished} interrupted update(s) ${dryRun ? 'would be finished' : 'finished'}`);
+  console.log(`\n  ${done.length === 0 ? 'No stale files found.' : `${done.join('; ')}.`}\n`);
 }
 
 // ─── Manual Update ───────────────────────────────────────────────────────────
@@ -3690,12 +3993,7 @@ function dataDirAccessError(
   dir = MEM_DATA_DIR,
   mode = fsConstants.R_OK | fsConstants.W_OK | fsConstants.X_OK,
 ) {
-  try {
-    accessSync(dir, mode);
-    return null;
-  } catch (e) {
-    return e.code === 'ENOENT' ? null : e.code || 'EACCES';
-  }
+  return dirAccessError(dir, mode);
 }
 
 // Same directory however it is spelled (a trailing slash, a symlinked HOME). stat works on a
@@ -3710,14 +4008,22 @@ function sameDir(a, b) {
   }
 }
 
-const dataDirAccessRemedy = () =>
-  `chmod u+rwx ${shellWord(MEM_DATA_DIR)} (or chown it back to your user if a sudo run created it)`;
+// The fix for a data dir this user cannot use, chosen by the error code (lib/wal-open-blocked.mjs).
+export const dataDirAccessRemedy = (code) => dataDirRemedy(code, MEM_DATA_DIR);
+
+// This process cannot load better-sqlite3: none installed where it runs (a checkout, or a plugin
+// cache before its first launch installed node_modules), or one that will not load (a stale ABI, a
+// damaged prebuild). The better-sqlite3 line names and counts that; a line that would open the DB
+// says it did not look, rather than count the same fault again (D#297, pre-ship review P3-4).
+const bindingMissing = (e) =>
+  (e?.code === 'ERR_MODULE_NOT_FOUND' && /'better-sqlite3'/.test(e.message)) || isNativeBindingError(e);
+const BINDING_MISSING_WHY = `better-sqlite3 cannot be loaded from ${PROJECT_DIR}`;
 
 async function runLockedInstall() {
   const denied = dataDirAccessError();
   if (denied) {
     console.error(
-      `[install] ${MEM_DATA_DIR} is not accessible (${denied}) — nothing was done. Fix: ${dataDirAccessRemedy()}`,
+      `[install] ${MEM_DATA_DIR} is not accessible (${denied}) — nothing was done. Fix: ${dataDirAccessRemedy(denied)}`,
     );
     process.exitCode = 1;
     return;
@@ -3824,7 +4130,7 @@ async function dispatch(cmd) {
       await cleanupHooks();
       break;
     case 'cleanup':
-      cleanup();
+      await cleanup();
       break;
     case 'self-update':
     case 'update':