claude-mem-lite 6.25.0 → 6.25.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.25.0",
+      "version": "6.25.1",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.0",
+  "version": "6.25.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/hook-update.mjs

@@ -828,11 +828,15 @@ export async function verifyReleaseAuthenticity(extractedDir, assets, publicKey
 // updater that was killed mid-swap (it applies the same staleness bound).
 const SWAP_MARKER = join(STATE_DIR, 'runtime', 'swap-in-progress'); // runtime-dir:stays-put — installation identity
 // Intent journal, written INSIDE the backup dir before each rename. On a hard kill
-// the backup dir survives (every normal exit deletes it) and this file says exactly
+// the backup dir survives (a normal exit deletes it, unless its journal cannot be
+// removed, D#283) and this file says exactly
 // which paths were in flight, so the next entry can finish the rollback at the right
 // granularity — a bare directory walk cannot tell a nested relPath from a directory
 // relPath like `node_modules`.
-const SWAP_JOURNAL = '.swap-journal.json';
+const SWAP_JOURNAL = '.swap-journal.json'; // doctor and cleanup spell it SWAP_JOURNAL_NAME (lib/doctor-stale-temp.mjs)
+// Written into the backup dir when its swap is over (committed, or rolled back): never replay it
+// (D#292 C). Doctor and cleanup spell it SWAP_RESOLVED_NAME.
+const SWAP_RESOLVED = '.swap-resolved';
 
 function markSwapStart() {
   try {
@@ -856,19 +860,131 @@ function clearSwapMarker() {
 // backup dir but nothing records it — recovery would then delete the backup dir with
 // the only copy of that file inside it. rollbackInstall guards every entry with
 // existsSync/force, so an intent that never happened is a harmless no-op.
+//
+// By temp file and rename, and it throws (D#289). writeFileSync truncates the journal before it
+// writes it, so a kill or ENOSPC in between left an empty journal, which recovery read as "nothing
+// moved" and then deleted the backups. A write error was swallowed, so the rename it was meant to
+// record went ahead unrecorded. Now the previous journal stays whole until the new one replaces
+// it, and a swap that cannot journal stops before the rename, through the rollback in the caller.
+//
+// Retried for a moment on EPERM/EBUSY/EACCES: the rename replaces a file just written, about twice
+// per switched path, and on Windows a scanner holding that file makes a rename over it fail
+// briefly. Each failure stopped the update and rolled it back, and a rollback is where a restore
+// can fail (D#292 A). Bounded at about 0.7 s, then it throws as before.
+const JOURNAL_RETRY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
 function journalSwap(backupDir, backedUp, installed) {
+  const data = JSON.stringify({ backedUp, installed });
+  for (let attempt = 1; ; attempt++) {
+    try {
+      atomicWriteFileSync(join(backupDir, SWAP_JOURNAL), data);
+      return;
+    } catch (e) {
+      if (attempt >= 8 || !JOURNAL_RETRY_CODES.has(e.code)) throw e;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25 * attempt);
+    }
+  }
+}
+
+// Clean up after a swap that is over: committed, or rolled back. Never throws, because a cleanup
+// that throws reaches the caller's catch, which rolls the swap back again (D#283; EBUSY is
+// ordinary on Windows and `force` does not suppress it).
+//
+// The dir is marked resolved first (D#292 C). A journal left behind (it could not be removed, or a
+// kill came first) was replayed by the next recovery: over a committed swap that put the previous
+// release back, and over a rolled-back one whose journal outlived a later swap it deleted a path
+// that swap had installed. Recovery, install, cleanup and doctor leave a resolved dir's journal
+// alone. The marker is a new empty file, so it needs no access to the journal a failed removal
+// could not get. With the marker written, a journal that stays is inert and the backups go anyway,
+// child by child around the journal and the marker: a recursive removal of the dir takes children
+// in directory order and stops at the first failure, so it could take the marker and then stop at
+// the journal (v6.25.1 delta review). If the marker cannot be written either, the journal still
+// goes before the backups, and if it stays, so do the backups, complete, so that a replay restores
+// one whole release.
+function discardBackupDir(backupDir) {
+  let resolved = false;
+  try {
+    writeFileSync(join(backupDir, SWAP_RESOLVED), '');
+    resolved = true;
+  } catch (e) {
+    debugCatch(e, 'mark-swap-resolved');
+  }
+  try {
+    rmSync(join(backupDir, SWAP_JOURNAL), { force: true });
+  } catch (e) {
+    debugCatch(e, 'discard-swap-journal');
+    if (resolved) removeBackupsBeside(backupDir);
+    return;
+  }
+  try {
+    rmSync(backupDir, { recursive: true, force: true });
+  } catch (e) {
+    debugCatch(e, 'discard-backup-dir');
+  }
+}
+
+function removeBackupsBeside(backupDir) {
+  let names = [];
+  try {
+    names = readdirSync(backupDir);
+  } catch (e) {
+    debugCatch(e, 'discard-backups-list');
+  }
+  for (const name of names) {
+    if (name === SWAP_JOURNAL || name === SWAP_RESOLVED) continue;
+    try {
+      rmSync(join(backupDir, name), { recursive: true, force: true });
+    } catch (e) {
+      debugCatch(e, 'discard-backup');
+    }
+  }
+}
+
+// Mark resolved the backup dirs a swap found left over and unfinished (recovery leaves one whose
+// journal it cannot read right now). Called once that swap has committed: it replaced every path
+// it switches, so a later replay of an older journal, once it can be read, would only mix the
+// releases back (v6.25.1 delta review). The same retirement install does after writing the tree.
+function retireUnresolvedBackups(targetDir, names) {
+  for (const name of names) {
+    try {
+      writeFileSync(join(targetDir, name, SWAP_RESOLVED), '');
+      debugLog('WARN', 'hook-update', `Retired ${name}: the committed swap replaced what its journal names`);
+    } catch (e) {
+      debugCatch(e, 'retire-unresolved-backup');
+    }
+  }
+}
+
+// The `.update-backup-*` dirs in targetDir that carry no resolved marker.
+function unresolvedBackups(targetDir) {
+  try {
+    return readdirSync(targetDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('.update-backup-'))
+      .map((e) => e.name)
+      .filter((name) => !existsSync(join(targetDir, name, SWAP_RESOLVED)));
+  } catch (e) {
+    debugCatch(e, 'list-unresolved-backups');
+    return [];
+  }
+}
+
+// The backup dir is resolved before staging goes: removing a whole staging tree takes long enough
+// for a kill to land in, and a kill there left a committed swap's journal to be replayed.
+function discardSwapDirs(stagingDir, backupDir) {
+  discardBackupDir(backupDir);
   try {
-    writeFileSync(join(backupDir, SWAP_JOURNAL), JSON.stringify({ backedUp, installed }));
+    rmSync(stagingDir, { recursive: true, force: true });
   } catch (e) {
-    debugCatch(e, 'journalSwap');
+    debugCatch(e, 'discard-staging-dir');
   }
 }
 
 /**
  * Finish any swap a previous process was killed in the middle of, then clear its
  * residue. Called on every install entry, under the install lock, BEFORE a new
- * staging/backup pair is created.
- * @returns {number} number of interrupted swaps rolled back
+ * staging/backup pair is created; and by install.mjs, under the same lock, before
+ * `install` (and so `repair`) writes the tree and from `cleanup` (D#289).
+ * @returns {number} number of backup dirs processed, with a journal or without; one left in place
+ *   because its journal cannot be read is not counted
  */
 export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
   let entries;
@@ -895,21 +1011,43 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
     }
     if (!entry.name.startsWith('.update-backup-')) continue;
 
-    let journal;
-    try {
-      journal = JSON.parse(readFileSync(join(dir, SWAP_JOURNAL), 'utf8'));
-    } catch {
-      journal = null;
+    // Its swap is over and only its cleanup failed: remove what is left, never replay it (D#292 C).
+    if (existsSync(join(dir, SWAP_RESOLVED))) {
+      discardBackupDir(dir);
+      recovered++;
+      continue;
     }
-    const backedUp = Array.isArray(journal?.backedUp) ? journal.backedUp : [];
-    const installed = Array.isArray(journal?.installed) ? journal.installed : [];
-    // Copies: rollbackInstall reverses the arrays in place.
-    rollbackInstall([...installed], [...backedUp], dir, targetDir);
+
+    // No journal: the swap is over and its journal is gone (or it was killed before its first
+    // rename), so there is nothing to replay and the dir is residue. A journal that is there but
+    // cannot be read, or not as one (an in-place write of 6.25.0 or older torn by a kill), says
+    // nothing about what moved, and the dir may hold the only copy of it: leave it. It used to be
+    // read as "nothing moved" and deleted (v6.25.1 review). doctor and cleanup name it; the next
+    // swap that commits, or an install, retires it.
+    let journal = { backedUp: [], installed: [] };
+    let raw = null;
     try {
-      rmSync(dir, { recursive: true, force: true });
+      raw = readFileSync(join(dir, SWAP_JOURNAL), 'utf8');
     } catch (e) {
-      debugCatch(e, 'recover-backup');
+      if (e.code !== 'ENOENT') {
+        debugCatch(e, 'recover-read-journal');
+        continue;
+      }
+    }
+    if (raw !== null) {
+      try {
+        journal = JSON.parse(raw);
+      } catch {
+        journal = null;
+      }
+      if (!Array.isArray(journal?.backedUp) || !Array.isArray(journal?.installed)) {
+        debugLog('WARN', 'hook-update', `Left ${entry.name} in place: its swap journal cannot be read`);
+        continue;
+      }
     }
+    const { backedUp, installed } = journal;
+    rollbackInstall(installed, backedUp, dir, targetDir);
+    discardBackupDir(dir);
     recovered++;
     debugLog(
       'WARN',
@@ -923,17 +1061,27 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
 // A rollback swaps a file SET back just as the install swapped it in, so it holds the same
 // marker for the same reason (D#239 g). After the MED-5 smoke gate the loop has already cleared
 // it; after a throw inside the loop it is still set, and this call takes it over.
+//
+// Safe to run twice over one journal (D#283). A backed-up path whose backup is gone holds the OLD
+// file already, restored by an earlier rollback or never moved out, so it is not deleted: a
+// second rollback used to delete every installed path, by then the only copy of the old install.
+// That holds for a journal this code wrote: its cleanup removes the journal before any backup, and
+// when the journal cannot be removed, the resolved marker keeps it from being replayed. A backup
+// dir 6.25.0 or older left half deleted beside its journal can still replay to a mix.
+// The arrays are copied, not reversed in place, so a caller's journal is left as it was.
 function rollbackInstall(installed, backedUp, backupDir, targetDir) {
   markSwapStart();
   try {
-    for (const relPath of installed.reverse()) {
+    const restored = new Set(backedUp.filter((relPath) => !existsSync(join(backupDir, relPath))));
+    for (const relPath of [...installed].reverse()) {
+      if (restored.has(relPath)) continue;
       try {
         rmSync(join(targetDir, relPath), { recursive: true, force: true });
       } catch {
         /* best-effort */
       }
     }
-    for (const relPath of backedUp.reverse()) {
+    for (const relPath of [...backedUp].reverse()) {
       const backupPath = join(backupDir, relPath);
       const targetPath = join(targetDir, relPath);
       try {
@@ -1049,6 +1197,7 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
   const backupDir = join(targetDir, `.update-backup-${ts}`);
   const backedUp = [];
   const installed = [];
+  let committed = false;
 
   const manifest = await loadReleaseManifest(sourceDir);
   const switchablePaths = buildSwitchablePaths(manifest.SOURCE_FILES);
@@ -1058,6 +1207,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // one — otherwise this install stacks on top of a mixed-version tree and its
     // own backup can no longer restore a coherent state.
     recoverInterruptedSwaps(targetDir);
+    // What recovery left unfinished (a journal it cannot read right now) is retired if this swap
+    // commits, and left for the next entry if it rolls back.
+    const leftUnresolved = unresolvedBackups(targetDir);
 
     mkdirSync(stagingDir, { recursive: true });
     mkdirSync(backupDir, { recursive: true });
@@ -1106,13 +1258,14 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // keeps working rather than leaving a broken install with no way back.
     if (!opts.skipSmoke && !smokeInstalledRelease(targetDir)) {
       rollbackInstall(installed, backedUp, backupDir, targetDir);
-      rmSync(stagingDir, { recursive: true, force: true });
-      rmSync(backupDir, { recursive: true, force: true });
+      discardSwapDirs(stagingDir, backupDir);
       return false;
     }
 
-    rmSync(stagingDir, { recursive: true, force: true });
-    rmSync(backupDir, { recursive: true, force: true });
+    // Committed: from here on the catch below must not roll back (D#283).
+    committed = true;
+    retireUnresolvedBackups(targetDir, leftUnresolved);
+    discardSwapDirs(stagingDir, backupDir);
 
     // Post-update migration: reconcile settings.json against the release we just
     // swapped in. `configureHooks()` already strips stale mem entries — but its only
@@ -1198,17 +1351,11 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     return true;
   } catch (err) {
     debugCatch(err, 'installExtractedRelease');
+    // Past the commit point the backups are gone and the new release IS the install: a rollback
+    // would delete the paths it added and restore nothing (D#283).
+    if (committed) return true;
     rollbackInstall(installed, backedUp, backupDir, targetDir);
-    try {
-      rmSync(stagingDir, { recursive: true, force: true });
-    } catch {
-      /* best-effort */
-    }
-    try {
-      rmSync(backupDir, { recursive: true, force: true });
-    } catch {
-      /* best-effort */
-    }
+    discardSwapDirs(stagingDir, backupDir);
     return false;
   } finally {
     release();

package/install.mjs

@@ -73,10 +73,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';
 
@@ -1298,6 +1300,115 @@ 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[],
+ *   left: string[]}>} kept: left on purpose because its journal cannot be read; deferred: an
+ *   unfinished swap left because hook-update could not load; left: anything else still there
+ */
+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: [], 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 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) is retired once the tree is written.
+  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 +1421,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 +1855,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 +1880,36 @@ 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 = dataDirDenied && e.code === 'SQLITE_READONLY_DIRECTORY';
+      const why = walBlocked
+        ? 'exists, but SQLite cannot open a WAL database without creating its -wal/-shm files beside it'
+        : '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 +2128,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) => Boolean(dataDirDenied) && code === 'SQLITE_READONLY_DIRECTORY';
+  const notCheckedWal = (what, scope = '') =>
+    dwarn(
+      `${what}: not checked${scope} — SQLite cannot open a WAL database without creating its -wal/-shm files beside it, 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 +2163,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 +2214,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 +2287,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 +2373,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 +2385,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}`);
@@ -2474,24 +2641,37 @@ 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 {
+        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 +3002,38 @@ 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). 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 what cleanup will decline. That one is
+  // milder than D#53 — cleanup SAYS it is skipping — and the unfinished-update line says a
+  // running update looks the same.
   try {
-    const { stale, inFlight } = scanStaleTempFiles({
-      dataDir: MEM_DATA_DIR,
+    const { stale, inFlight, unfinishedSwaps, unreadableJournals, notChecked } = scanStaleTempFiles({
+      codeDir: INSTALL_DIR,
       runtimeDir: MEM_RUNTIME_DIR,
+      legacyDir: codeIsDataDir ? undefined : MEM_DATA_DIR,
     });
-    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 is running right now (run: ${installer} cleanup — it finishes an interrupted one, and skips while an update holds install.lock)`,
+      );
+    }
+    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)`,
+      );
+    }
+    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)` : ''),
+      );
+    } else if (stale > 0) {
+      dwarn(`Stale temp files: ${stale} found (run: ${installer} cleanup)`);
     } else {
       ok('Stale temp files: none');
     }
@@ -2875,7 +3075,8 @@ 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 dwarn('DB stats: ' + e.message);
     }
   }
 
@@ -3229,7 +3430,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 +3439,80 @@ 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.
+  // 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;
   const updateLock = acquireLock(join(MEM_DATA_DIR, 'runtime', 'install.lock')); // runtime-dir:stays-put — install lock serialises real installers
   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.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 +3564,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 ───────────────────────────────────────────────────────────
@@ -3710,14 +3956,19 @@ 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. EROFS is the file system,
+// not the mode bits: accessSync(W_OK) on a read-only mount fails with it, and chmod cannot help
+// there (D#287).
+export const dataDirAccessRemedy = (code) =>
+  code === 'EROFS'
+    ? `the file system holding ${shellWord(MEM_DATA_DIR)} is mounted read-only — remount it read-write`
+    : `chmod u+rwx ${shellWord(MEM_DATA_DIR)} (or chown it back to your user if a sudo run created it)`;
 
 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 +4075,7 @@ async function dispatch(cmd) {
       await cleanupHooks();
       break;
     case 'cleanup':
-      cleanup();
+      await cleanup();
       break;
     case 'self-update':
     case 'update':

package/lib/doctor-stale-temp.mjs

@@ -21,13 +21,31 @@
  * A leaf: node:fs, node:path, and one constants module that imports nothing.
  */
 
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { ORPHAN_EPISODE_AGE_MS } from './time-constants.mjs';
 
-/** Residue from an interrupted self-update, written under the data dir by hook-update. */
+/**
+ * Residue of a self-update. hook-update's installExtractedRelease stages and backs up beside the
+ * tree it swaps: the CODE dir (~/.claude-mem-lite), which CLAUDE_MEM_DIR does not move (D#289).
+ * Before v2.90.0 the code lived in the data dir, so an updater then swapped into a relocated data
+ * dir; residue it left there is stale whatever it holds (scanStaleTempFiles' legacyDir).
+ */
 const UPDATE_RESIDUE_PREFIXES = ['.update-staging-', '.update-backup-'];
 
+/**
+ * The journal a swap keeps inside its backup dir. A literal, not an import: hook-update.mjs is on
+ * the repair path and stays off this leaf's load graph; tests/update-residue-faces.test.mjs holds
+ * the two spellings equal.
+ */
+export const SWAP_JOURNAL_NAME = '.swap-journal.json';
+
+/**
+ * Written into a backup dir when its swap is over (committed, or rolled back), before the journal
+ * is removed: a journal left beside it is never replayed (D#292 C). Same arrangement as above.
+ */
+export const SWAP_RESOLVED_NAME = '.swap-resolved';
+
 /** Episode hand-off files under the runtime dir. Age-gated: see classifyEpisodeFile. */
 const EPISODE_RESIDUE_PREFIXES = ['pending-', 'ep-flush-'];
 
@@ -35,6 +53,67 @@ export const isUpdateResidue = (name) => UPDATE_RESIDUE_PREFIXES.some((p) => nam
 
 export const isEpisodeResidue = (name) => EPISODE_RESIDUE_PREFIXES.some((p) => name.startsWith(p));
 
+/**
+ * Is this update residue the leftover of a swap that is over, or a swap that never finished?
+ *
+ * A backup dir that holds its journal and no resolved marker is a swap whose updater was killed:
+ * it holds the only copy of every file the swap had moved out, and the next update entry replays
+ * the journal to put them back. Deleting it as stale temp kept the half-swapped tree for good
+ * (D#289). A swap that is over (committed, or rolled back) writes the resolved marker and then
+ * removes its journal, so a backup dir with the marker or without a journal, and any staging dir,
+ * is residue. A dir from 6.25.0 or older carries no marker; one whose journal survived a finished
+ * swap there still reads as unfinished.
+ *
+ * A swap running right now looks the same as one that was killed; cleanup tells them apart by
+ * install.lock, doctor cannot, and says so.
+ *
+ * 'unreadable-journal' is an unresolved backup dir whose journal is there but cannot be read now,
+ * or not as one (a write of 6.25.0 or older torn by a kill). Recovery cannot replay it and it may
+ * hold the only copy of what moved, so recovery leaves it (the same rule as hook-update's
+ * recoverInterruptedSwaps); the next swap that commits, or an install, retires it. One whose read
+ * error clears before that would be replayed like any unfinished swap.
+ *
+ * Only a real directory is a swap: recovery skips a file or a symlink with the name (its Dirent is
+ * not a directory), so the classifier calls those leftover too, judged by lstat as recovery does.
+ *
+ * @returns {'unfinished-swap'|'unreadable-journal'|'stale'|null} null when not update residue
+ */
+export function classifyUpdateResidue(codeDir, name) {
+  if (!isUpdateResidue(name)) return null;
+  const dir = join(codeDir, name);
+  let st;
+  try {
+    st = lstatSync(dir);
+  } catch {
+    return 'stale';
+  }
+  if (!st.isDirectory() || !name.startsWith('.update-backup-')) return 'stale';
+  if (existsSync(join(dir, SWAP_RESOLVED_NAME))) return 'stale';
+  let raw;
+  try {
+    raw = readFileSync(join(dir, SWAP_JOURNAL_NAME), 'utf8');
+  } catch (e) {
+    return e.code === 'ENOENT' ? 'stale' : 'unreadable-journal';
+  }
+  try {
+    const j = JSON.parse(raw);
+    if (Array.isArray(j?.backedUp) && Array.isArray(j?.installed)) return 'unfinished-swap';
+  } catch {
+    /* not a journal */
+  }
+  return 'unreadable-journal';
+}
+
+/** A directory's names; [] when it does not exist. Any other error throws: absent is not unreadable. */
+function listDir(dir) {
+  try {
+    return readdirSync(dir);
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+}
+
 /**
  * How the age gate is SPOKEN, derived from the gate itself rather than hand-written.
  *
@@ -87,25 +166,49 @@ export function classifyEpisodeFile(
  * detail rather than a warning, because a file that is supposed to exist right now is not
  * a fault. Note the asymmetry, which is deliberate and is NOT the age gate being applied
  * inconsistently: update residue is guarded by install.lock in cleanup, not by age, so
- * there is no age gate here for it to mirror.
+ * there is no age gate here for it to mirror. `unfinishedSwaps` are backup dirs with a readable
+ * journal and no resolved marker: cleanup finishes those swaps rather than removing them, and
+ * `unreadableJournals` it leaves (classifyUpdateResidue).
  *
- * @returns {{stale: number, inFlight: number}}
+ * @param {{codeDir: string, runtimeDir: string, legacyDir?: string, now?: number, episodeAgeMs?: number}} args
+ *   codeDir is where update residue lives; runtimeDir is where episode files live. legacyDir is a
+ *   data dir CLAUDE_MEM_DIR keeps apart from the code dir: update residue there was left by an
+ *   updater older than v2.90.0, which swapped into it, so all of it is stale and none of it is
+ *   replayed. (It holds no journal either: journals came in v3.57.0.)
+ * @returns {{stale: number, inFlight: number, unfinishedSwaps: number, unreadableJournals: number,
+ *   notChecked: Array<{dir: string, code: string}>}} A directory that exists but cannot be listed
+ *   goes in notChecked, never counted as empty, and the others are still counted.
  */
-export function scanStaleTempFiles({ dataDir, runtimeDir, now = Date.now(), episodeAgeMs }) {
+export function scanStaleTempFiles({ codeDir, runtimeDir, legacyDir, now = Date.now(), episodeAgeMs }) {
   let stale = 0;
   let inFlight = 0;
+  let unfinishedSwaps = 0;
+  let unreadableJournals = 0;
+  const notChecked = [];
+  const list = (dir) => {
+    try {
+      return listDir(dir);
+    } catch (e) {
+      notChecked.push({ dir, code: e.code || 'error' });
+      return [];
+    }
+  };
 
-  if (existsSync(dataDir)) {
-    for (const f of readdirSync(dataDir)) if (isUpdateResidue(f)) stale++;
+  for (const f of list(codeDir)) {
+    const kind = classifyUpdateResidue(codeDir, f);
+    if (kind === 'unfinished-swap') unfinishedSwaps++;
+    else if (kind === 'unreadable-journal') unreadableJournals++;
+    else if (kind === 'stale') stale++;
+  }
+  if (legacyDir) {
+    for (const f of list(legacyDir)) if (isUpdateResidue(f)) stale++;
   }
 
-  if (existsSync(runtimeDir)) {
-    for (const f of readdirSync(runtimeDir)) {
-      if (!isEpisodeResidue(f)) continue;
-      if (classifyEpisodeFile(runtimeDir, f, { now, episodeAgeMs }) === 'in-flight') inFlight++;
-      else stale++;
-    }
+  for (const f of list(runtimeDir)) {
+    if (!isEpisodeResidue(f)) continue;
+    if (classifyEpisodeFile(runtimeDir, f, { now, episodeAgeMs }) === 'in-flight') inFlight++;
+    else stale++;
   }
 
-  return { stale, inFlight };
+  return { stale, inFlight, unfinishedSwaps, unreadableJournals, notChecked };
 }

package/lib/schema-skew.mjs

@@ -273,7 +273,7 @@ export function schemaCompatProbeSource(root, dbPath) {
     ' const r = d.prepare("SELECT version FROM schema_version LIMIT 1").get();' +
     ' d.close();' +
     ' out.dbVersion = r && typeof r.version === "number" ? r.version : null; }' +
-    ' catch (e) { out.dbError = String((e && e.message) || e); }' +
+    ' catch (e) { out.dbError = String((e && e.message) || e); out.dbErrorCode = (e && e.code) || null; }' +
     `process.stdout.write(${open} + JSON.stringify(out) + ${close}); })()`
   );
 }
@@ -318,7 +318,7 @@ function extractProbePayload(stdout) {
  * (a native crash leaving both streams empty, a spawn that never starts).
  *
  * @param {{timeoutMs?: number, spawn?: (cmd: string, args: string[], opts: object) => object}} [opts]
- * @returns {{status: 'ok'|'skew'|'unknown', supported?: number|null, dbVersion?: number|null, error?: string}}
+ * @returns {{status: 'ok'|'skew'|'unknown', supported?: number|null, dbVersion?: number|null, error?: string, errorCode?: string}}
  */
 export function probeSchemaCompatInFreshProcess(
   root,
@@ -350,6 +350,9 @@ export function probeSchemaCompatInFreshProcess(
       supported: supported ?? null,
       dbVersion: dbVersion ?? null,
       error: out.supportedError || out.dbError || 'probe returned no version',
+      // The DB open's own code, only when that is the error reported: a caller classifies on the
+      // code, never on SQLite's message, which several codes share (D#287).
+      ...(!out.supportedError && out.dbErrorCode && { errorCode: out.dbErrorCode }),
     };
   }
   return { status: supported < dbVersion ? 'skew' : 'ok', supported, dbVersion };

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.0",
+  "version": "6.25.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.25.0",
+      "version": "6.25.1",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.25.0",
+  "version": "6.25.1",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",