claude-mem-lite 6.30.7 → 6.30.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,15 +23,30 @@
23
23
  // one, on a condition that never heals by itself. That is the schema-skew shape exactly, and
24
24
  // this module is deliberately its mirror image so the two cannot drift apart.
25
25
  //
26
- // It imports no native binding: the static graph is 10 modules and zero package edges (the
27
- // only bare specifiers anywhere in it are the `node:` builtins). That is the property that
26
+ // It imports no native binding: its static graph has zero package edges (the only bare
27
+ // specifiers anywhere in it are the `node:` builtins). That is the property that
28
28
  // matters — a classifier the hook path may need while the binding is the broken thing must
29
29
  // not sit behind a native import. It is NOT as tight as schema-skew.mjs, which imports
30
30
  // `node:` builtins and nothing else; this one reaches `db-backup → utils → …` for
31
31
  // `readSnapshots`. Same guarantee, larger graph — do not restate it as "same discipline".
32
32
 
33
- import { basename, dirname } from 'node:path';
33
+ import { spawnSync } from 'node:child_process';
34
+ import {
35
+ constants as fsConstants,
36
+ chmodSync,
37
+ copyFileSync,
38
+ existsSync,
39
+ lstatSync,
40
+ mkdtempSync,
41
+ readdirSync,
42
+ rmSync,
43
+ statSync,
44
+ } from 'node:fs';
45
+ import { basename, dirname, join } from 'node:path';
46
+ import { fileURLToPath } from 'node:url';
34
47
  import { readSnapshots } from './db-backup.mjs';
48
+ import { CODE_DIR } from './data-paths.mjs';
49
+ import { SCHEMA_SKEW_CODE } from './schema-skew.mjs';
35
50
  import { shellWord, CLI_INVOKE } from '../cli-path.mjs';
36
51
 
37
52
  /** Marker prefix for lib/record-once.mjs. Per project, like the skew one. */
@@ -85,8 +100,8 @@ export function isFtsCorruptionError(err) {
85
100
  * nothing" rather than "search is broken".
86
101
  *
87
102
  * ONE STRING FOR BOTH CHANNELS, unlike the file-level family below. The split there exists
88
- * because that remedy OVERWRITES the database and must not be handed ready-to-run to an
89
- * agent holding Bash. This one re-derives every index from its own content table: the rows
103
+ * because that remedy moves the database file out from under every session and must not be
104
+ * handed ready-to-run to an agent holding Bash. This one re-derives every index from its own content table: the rows
90
105
  * are never read from the index, so a rebuild is lossless and idempotent, and `doctor`
91
106
  * already runs it unprompted. Naming "intact" is load-bearing — the reading this line
92
107
  * exists to prevent is "my memories are corrupt".
@@ -140,81 +155,446 @@ export function isDbUnusableError(err) {
140
155
  return UNUSABLE_RE.test(msg) || SCHEMA_UNREADABLE_RE.test(msg);
141
156
  }
142
157
 
158
+ /** The child checkSnapshot runs: lib/snapshot-probe.mjs, beside this file. */
159
+ const SNAPSHOT_PROBE = join(dirname(fileURLToPath(import.meta.url)), 'snapshot-probe.mjs');
160
+ /** checkSnapshot's private directories in the data directory: `<prefix><pid>-XXXXXX`, the pid
161
+ * being the process that made it. */
162
+ const CHECK_DIR_PREFIX = '.snapshot-check-';
163
+ const CHECK_DIR_RE = /^\.snapshot-check-(\d+)-[A-Za-z0-9]{6}$/;
164
+ /** The probe's run on one copy: open (migrations included), index rebuild, integrity check. The
165
+ * copy before it is not bounded by this. */
166
+ const CHECK_TIMEOUT_MS = 10 * 60 * 1000;
167
+ /** No check runs this long, so a private directory this old was left by a killed check even when
168
+ * its pid now names a live process. */
169
+ const STALE_CHECK_MS = 24 * 60 * 60 * 1000;
170
+ // SQLite codes about the check's own copy rather than about the snapshot: the copy lives in the
171
+ // data directory, so a full or failing disk there says nothing about what a restore would give,
172
+ // and neither does a path SQLite cannot open (the private directory makes it longer than the
173
+ // store's: v6.30.6 r1 defects P3-3).
174
+ const CHECK_OWN_CODE_RE = /^SQLITE_(FULL|IOERR|CANTOPEN)/;
175
+
176
+ function nonEmptyFile(path) {
177
+ try {
178
+ const st = statSync(path);
179
+ return st.isFile() && st.size > 0;
180
+ } catch {
181
+ return false;
182
+ }
183
+ }
184
+
185
+ /**
186
+ * What restoring the snapshot at `path` would give (D#558). The snapshot is copied into a private
187
+ * directory beside it, with its own `-wal` when it has a non-empty one (a hand-made `cp` of a live
188
+ * store), and lib/snapshot-probe.mjs opens the copy in a child process with the opener every
189
+ * product face uses, rebuilds its indexes as the restore command's last step (`fts-check rebuild`)
190
+ * does, then runs SQLite's integrity check and counts observations. The directory is removed
191
+ * before this returns.
192
+ *
193
+ * - `ok`: the copy opens, its indexes rebuild, it passes the integrity check, and it holds
194
+ * `observations`, or `otherRows` in the other tables a user's rows live in (at least one);
195
+ * - `empty`: the same with no row in either, so restoring it gives what a fresh store gives;
196
+ * - `bad`: the product's opener throws on it (`why: 'open'`), an index does not rebuild
197
+ * (`why: 'rebuild'`), or the integrity check fails or throws (`why: 'integrity'`), `reason`
198
+ * saying how;
199
+ * - `unchecked`: the check itself could not run (the copy, the child, a full or failing disk, a
200
+ * copy SQLite cannot open, whichever step met it), or the snapshot was written by a newer
201
+ * claude-mem-lite, `reason` saying why and `where` naming the directory when making the private
202
+ * one failed.
203
+ *
204
+ * `listed`, when present, is how many observations the copy's own index listed before the rebuild,
205
+ * more than its table holds after it: the table lost rows, or the index kept entries for rows a
206
+ * delete removed. The restore gives what the table holds; doctor prints both numbers.
207
+ *
208
+ * `withLog` says whether the snapshot's own `-wal` was part of the copy, so the restore command
209
+ * copies it too. The first attempt checked the file itself with integrity_check, which rejects a
210
+ * snapshot whose damage an index rebuild repairs, and could not read a file over 2 GiB; this one
211
+ * checks what a restore gives.
212
+ *
213
+ * @param {string} path
214
+ * @param {{probe?: string, timeoutMs?: number}} [opts] `probe` replaces the child script (tests)
215
+ * @returns {{verdict: 'ok'|'empty'|'bad'|'unchecked', withLog: boolean, observations?: number, otherRows?: number, listed?: number, why?: 'open'|'rebuild'|'integrity', reason?: string, where?: string}}
216
+ */
217
+ export function checkSnapshot(path, { probe = SNAPSHOT_PROBE, timeoutMs = CHECK_TIMEOUT_MS } = {}) {
218
+ let dir = null;
219
+ let withLog = false;
220
+ const unchecked = (reason) => ({ verdict: 'unchecked', withLog, reason });
221
+ const bad = (why, reason) => ({ verdict: 'bad', withLog, why, reason: String(reason).slice(0, 200) });
222
+ try {
223
+ try {
224
+ dir = mkdtempSync(join(dirname(path), `${CHECK_DIR_PREFIX}${process.pid}-`));
225
+ } catch (e) {
226
+ return { ...unchecked(e?.code || e?.message || 'unwritable'), where: dirname(path) };
227
+ }
228
+ const copy = join(dir, 'claude-mem-lite.db');
229
+ // FICLONE: a reflink where the filesystem has them, a plain streamed copy elsewhere.
230
+ copyFileSync(path, copy, fsConstants.COPYFILE_FICLONE);
231
+ withLog = nonEmptyFile(`${path}-wal`);
232
+ if (withLog) copyFileSync(`${path}-wal`, `${copy}-wal`, fsConstants.COPYFILE_FICLONE);
233
+ // The copy takes the snapshot's mode, and a read-only one opened read-only and read as damage
234
+ // (v6.30.6 r1 defects P2-3); the restore command makes the restored store writable the same way.
235
+ for (const f of withLog ? [copy, `${copy}-wal`] : [copy]) chmodSync(f, 0o600);
236
+ // SQLite's sort files and Node's temporary files go into the private directory too, so a full
237
+ // /tmp is not read as the snapshot's (v6.30.6 r1 defects P3-4). So does the home directory:
238
+ // an opener that finds no store moves one from ~/claude-mem-lite (v6.30.8 r1 defects F7).
239
+ const r = spawnSync(process.execPath, [probe], {
240
+ env: {
241
+ ...process.env,
242
+ CLAUDE_MEM_DIR: dir,
243
+ SQLITE_TMPDIR: dir,
244
+ TMPDIR: dir,
245
+ HOME: dir,
246
+ USERPROFILE: dir,
247
+ },
248
+ encoding: 'utf8',
249
+ timeout: timeoutMs,
250
+ stdio: ['ignore', 'pipe', 'pipe'],
251
+ });
252
+ if (r.error) {
253
+ if (r.error.code === 'ETIMEDOUT') return unchecked(`ETIMEDOUT, over ${elapsed(timeoutMs)}`);
254
+ return unchecked(r.error.code || r.error.message);
255
+ }
256
+ let out = null;
257
+ try {
258
+ out = JSON.parse(String(r.stdout).trim().split('\n').pop());
259
+ } catch {
260
+ /* no result line: the probe did not run to its end */
261
+ }
262
+ if (r.status !== 0 || !out || typeof out !== 'object') {
263
+ const how = r.signal ? `probe killed by ${r.signal}` : `probe exited ${r.status}`;
264
+ // The error line, not the first one: Node prints a source location above a load failure.
265
+ const lines = String(r.stderr)
266
+ .split('\n')
267
+ .map((l) => l.trim())
268
+ .filter(Boolean);
269
+ const said = (lines.find((l) => /^\w*Error\b/.test(l)) ?? lines[0] ?? '').slice(0, 200);
270
+ return unchecked(said ? `${how}: ${said}` : how);
271
+ }
272
+ const rebuildErrors = Array.isArray(out.rebuildErrors) ? out.rebuildErrors : [];
273
+ const own = [out.error, ...rebuildErrors].find((e) => CHECK_OWN_CODE_RE.test(e?.code ?? ''));
274
+ if (own) return unchecked(own.code);
275
+ // This version refuses a store a newer one wrote, which says nothing about the snapshot; an
276
+ // older snapshot named past it could hold less (v6.30.6 r1 defects P2-1).
277
+ if (out.error?.code === SCHEMA_SKEW_CODE) {
278
+ return unchecked('written by a newer claude-mem-lite; update claude-mem-lite, then run doctor again');
279
+ }
280
+ if (out.error && !out.opened) return bad('open', out.error.code || out.error.message);
281
+ if (rebuildErrors.length > 0) return bad('rebuild', rebuildErrors[0].message);
282
+ if (out.error) return bad('integrity', out.error.code || out.error.message);
283
+ if (out.integrity !== 'ok') return bad('integrity', out.integrity);
284
+ const otherRows = Number.isInteger(out.otherRows) ? out.otherRows : 0;
285
+ const passed = {
286
+ verdict: out.observations > 0 || otherRows > 0 ? 'ok' : 'empty',
287
+ withLog,
288
+ observations: out.observations,
289
+ otherRows,
290
+ };
291
+ if (Number.isInteger(out.listed) && out.listed > out.observations) passed.listed = out.listed;
292
+ return passed;
293
+ } catch (e) {
294
+ return unchecked(e?.code || e?.message || 'unreadable');
295
+ } finally {
296
+ if (dir) {
297
+ try {
298
+ rmSync(dir, { recursive: true, force: true });
299
+ } catch {
300
+ /* left behind: sweepSnapshotChecks removes it once this process has exited */
301
+ }
302
+ }
303
+ }
304
+ }
305
+
306
+ function elapsed(ms) {
307
+ return ms >= 1000 ? `${Math.round(ms / 1000)} s` : `${ms} ms`;
308
+ }
309
+
310
+ /** Whether `pid` names a running process (EPERM: one this user may not signal, still running). */
311
+ function running(pid) {
312
+ try {
313
+ process.kill(pid, 0);
314
+ return true;
315
+ } catch (e) {
316
+ return e?.code === 'EPERM';
317
+ }
318
+ }
319
+
320
+ /**
321
+ * Remove the private directories checkSnapshot leaves when it is killed mid-check (each holds a
322
+ * full copy of a snapshot): those whose process has exited, and any older than a check can run
323
+ * (its pid may name another process by then). A doctor checking in another terminal keeps its
324
+ * own. Only directories named exactly as checkSnapshot names them; never a link. doctor calls
325
+ * this before its database check, healthy store or not, so a copy left by an interrupted check
326
+ * goes on the next doctor run even once the store is restored.
327
+ * @param {string} dir the data directory
328
+ * @param {{nowMs?: number}} [opts]
329
+ */
330
+ export function sweepSnapshotChecks(dir, { nowMs = Date.now() } = {}) {
331
+ let names;
332
+ try {
333
+ names = readdirSync(dir);
334
+ } catch {
335
+ return;
336
+ }
337
+ for (const n of names) {
338
+ const m = CHECK_DIR_RE.exec(n);
339
+ if (!m) continue;
340
+ const full = join(dir, n);
341
+ try {
342
+ const st = lstatSync(full);
343
+ if (!st.isDirectory()) continue;
344
+ if (running(Number(m[1])) && nowMs - st.mtimeMs < STALE_CHECK_MS) continue;
345
+ rmSync(full, { recursive: true, force: true });
346
+ } catch {
347
+ /* raced away, or not ours to remove */
348
+ }
349
+ }
350
+ }
351
+
352
+ /**
353
+ * The CLI, run against `dbPath`'s data directory. A relocated one gets a `CLAUDE_MEM_DIR=` prefix,
354
+ * since it may be set only in Claude Code's environment; the default one gets none, which
355
+ * PowerShell, cmd and csh cannot run (v6.30.6 r1 defects P3-7), so there a CLAUDE_MEM_DIR the
356
+ * shell exports for another store wins.
357
+ */
358
+ function cliFor(dbPath, args) {
359
+ const dir = dirname(dbPath);
360
+ return dir === CODE_DIR
361
+ ? `${CLI_INVOKE} ${args}`
362
+ : `CLAUDE_MEM_DIR=${shellWord(dir)} ${CLI_INVOKE} ${args}`;
363
+ }
364
+
365
+ function doctorCommand(dbPath) {
366
+ return cliFor(dbPath, 'doctor');
367
+ }
368
+
143
369
  /**
144
370
  * What the user should actually run. Three outcomes, never two — the same rule schema-skew.mjs
145
371
  * states: "there is no backup" and "I could not look for one" must not print in the same
146
372
  * voice, because a green-sounding line ends the reader's search.
147
373
  *
148
- * `snapshotCount` is part of the return rather than something a caller re-derives: doctor's
149
- * sentence names it ("Restore the newest of 2 backup snapshot(s)"), and a second
150
- * `readSnapshots` call to recover a number this function already had would be a second
151
- * directory read that can disagree with the first.
374
+ * A snapshot goes into a command only after `check` (doctor passes checkSnapshot) calls it `ok`,
375
+ * newest first: `bad` and `empty` ones are passed over and counted; one the check could not run on
376
+ * before any passes stops the walk with no command (kind 'unknown', or 'schema'), since an older
377
+ * snapshot named past it could hold less. The command restores the newest that passes; every older
378
+ * snapshot is checked as well, and each that passes is listed in `found` with its counts and given
379
+ * its own command in `alternatives`, newest first (D#577). Without `check` (the SessionStart notice, which must not copy and open every
380
+ * candidate on each session start while the store is broken) no snapshot goes into a command:
381
+ * kind 'unknown' counts them and points at doctor, the kind every version's doctor renders as its
382
+ * note (a killed update can leave an older install.mjs beside this file). None `ok`, or none at
383
+ * all: the set-aside. Only regular files count as snapshots: a directory or a device named like
384
+ * one is not a copy of anything, and copying it fails. Every doctor named in a note carries a
385
+ * relocated data directory, which the shell the user runs it from may not (cliFor).
386
+ *
387
+ * Both commands keep every byte they replace (D#539): the broken file and its `-wal` move to
388
+ * `keptAs` and `keptAs-wal`, the names SQLite pairs, and only the `-shm` is deleted. The restore
389
+ * ends with `fts-check rebuild`, the step the check ran after the product's open. Each starts
390
+ * with a guard so running it a second time stops before overwriting the first kept copy, and
391
+ * `touch` gives `mv` a log to move when there is none (an empty `-wal` reads as no log).
392
+ * Chained with `&&` only: fish has no `{ }` grouping. The kept name carries the broken file's
393
+ * mtime, not the clock, so every doctor run on one broken file prints the same command (and the
394
+ * --json face matches the human one); a later broken file gets another name. When that name or its
395
+ * `-wal` already exists (a kept file moved back keeps its mtime) a `-1`, `-2`, … is added, so the
396
+ * command doctor prints never stops at its own guard.
397
+ *
398
+ * `found` is the sentence about the snapshots, which doctor puts in front of its own command
399
+ * sentence; `note` is what the SessionStart notice prints. `snapshotCount` counts the non-empty
400
+ * snapshots, so a caller does not re-read the directory for it.
152
401
  *
153
402
  * `err`, when given, picks the family: a schema SQLite cannot read gets kind 'schema', which
154
403
  * carries no command (see SCHEMA_UNREADABLE_RE).
155
404
  *
156
405
  * @param {string} dbPath
157
406
  * @param {unknown} [err]
158
- * @returns {{kind: 'restore'|'set-aside'|'unknown'|'schema', command: string, note: string, snapshotCount: number}}
407
+ * @param {{check?: (path: string) => ReturnType<typeof checkSnapshot>, stampMs?: number}} [opts]
408
+ * `stampMs` replaces the broken file's mtime in the kept name (tests)
409
+ * @returns {{kind: 'restore'|'set-aside'|'unknown'|'schema', command: string, keptAs: string, found: string, note: string, snapshotCount: number, alternatives?: Array<{path: string, command: string}>}}
159
410
  */
160
- export function dbUnusableRemedy(dbPath, err) {
161
- const clear = `rm -f ${shellWord(`${dbPath}-wal`)} ${shellWord(`${dbPath}-shm`)}`;
411
+ export function dbUnusableRemedy(dbPath, err, { check, stampMs } = {}) {
162
412
  const schema = SCHEMA_UNREADABLE_RE.test(String(err?.message ?? err ?? ''));
413
+ let stamp = stampMs;
414
+ if (stamp === undefined) {
415
+ try {
416
+ stamp = statSync(dbPath).mtimeMs;
417
+ } catch {
418
+ stamp = Date.now();
419
+ }
420
+ }
421
+ const keptBase = `${dbPath}.corrupt-${new Date(Math.floor(stamp)).toISOString().replace(/[:.]/g, '-')}`;
422
+ let keptAs = keptBase;
423
+ for (let i = 1; existsSync(keptAs) || existsSync(`${keptAs}-wal`); i++) keptAs = `${keptBase}-${i}`;
424
+ const setAsideCommand = [
425
+ `test ! -e ${shellWord(keptAs)}`,
426
+ `test ! -e ${shellWord(`${keptAs}-wal`)}`,
427
+ `rm -f ${shellWord(`${dbPath}-shm`)}`,
428
+ `touch ${shellWord(`${dbPath}-wal`)}`,
429
+ `mv ${shellWord(dbPath)} ${shellWord(keptAs)}`,
430
+ `mv ${shellWord(`${dbPath}-wal`)} ${shellWord(`${keptAs}-wal`)}`,
431
+ ].join(' && ');
432
+ const keeps = `as ${keptAs} and ${keptAs}-wal`;
433
+ const noCommand = (kind, found, note = found, snapshotCount = 0) => ({
434
+ kind,
435
+ command: '',
436
+ keptAs: '',
437
+ snapshotCount,
438
+ found,
439
+ note,
440
+ });
163
441
  const snap = readSnapshots(dbPath);
164
442
  if (!snap.ok) {
165
- return {
166
- kind: schema ? 'schema' : 'unknown',
167
- command: '',
168
- snapshotCount: 0,
169
- note:
170
- `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
171
- `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`,
172
- };
173
- }
174
- // A 0-byte `.bak` is what a failed snapshot of a damaged store left before 6.31.0 (D#551),
175
- // usually the newest one; it is not a copy of anything.
176
- const snapshots = snap.snapshots.filter((s) => s.size > 0);
177
- const empty = snap.snapshots.length - snapshots.length;
178
- const none =
179
- empty > 0
180
- ? `No backup snapshot beside the database holds any data (${empty} empty .bak file${empty === 1 ? '' : 's'} skipped).`
181
- : 'No backup snapshot exists beside the database.';
182
- if (schema && snapshots.length === 0) {
183
- return {
184
- kind: 'schema',
185
- command: '',
186
- snapshotCount: 0,
187
- note: none,
188
- };
443
+ const found =
444
+ `Could not read ${dirname(dbPath)} to look for a backup snapshot (${snap.reason}) — ` +
445
+ `fix that directory first, then look for ${basename(dbPath)}.*.bak beside the database.`;
446
+ return noCommand(schema ? 'schema' : 'unknown', found);
189
447
  }
448
+ // A 0-byte `.bak` is what a failed snapshot of a damaged store left before 6.30.4 (D#551),
449
+ // usually the newest one; it is not a copy of anything. Newest first by mtime, ties broken by
450
+ // path so the order is total rather than readdir's — the D#9 shape.
451
+ const files = snap.snapshots.filter((s) => s.isFile);
452
+ const snapshots = files
453
+ .filter((s) => s.size > 0)
454
+ .sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1));
455
+ const empty = files.length - snapshots.length;
456
+ const skipped = empty > 0 ? ` (${empty} empty .bak file${empty === 1 ? '' : 's'} skipped)` : '';
457
+ const count = `${snapshots.length} backup snapshot(s) beside the database${skipped}`;
458
+ const setAside = (found) => ({
459
+ kind: 'set-aside',
460
+ command: setAsideCommand,
461
+ keptAs,
462
+ snapshotCount: snapshots.length,
463
+ found,
464
+ note: `${found} That command moves the broken file and its log aside, ${keeps}, so a fresh store is created on the next session.`,
465
+ });
190
466
  if (snapshots.length === 0) {
191
- return {
192
- kind: 'set-aside',
193
- command: `${clear} && mv ${shellWord(dbPath)} ${shellWord(`${dbPath}.corrupt`)}`,
194
- snapshotCount: 0,
195
- note: `${none} That command sets the broken file aside so a fresh store is created on the next session.`,
196
- };
467
+ const found =
468
+ empty > 0
469
+ ? `No backup snapshot beside the database holds any data${skipped}.`
470
+ : 'No backup snapshot exists beside the database.';
471
+ return schema ? noCommand('schema', found) : setAside(found);
472
+ }
473
+ if (!check) {
474
+ const found = `${snapshots.length} backup snapshot(s) exist beside the database${skipped}.`;
475
+ const checks = schema
476
+ ? 'checks which ones restore'
477
+ : 'checks which ones restore before it gives a command';
478
+ const note = `${found} \`${doctorCommand(dbPath)}\` ${checks}.`;
479
+ return noCommand(schema ? 'schema' : 'unknown', found, note, snapshots.length);
480
+ }
481
+ // doctor prints which one it is checking: a large snapshot takes seconds (v6.30.6 r1 defects P3-2).
482
+ const ask = (i) => check(snapshots[i].path, { nth: i + 1, of: snapshots.length });
483
+ const reject = (counts, r) => {
484
+ counts[r.verdict === 'empty' ? 'empty' : r.why === 'rebuild' || r.why === 'integrity' ? r.why : 'open'] +=
485
+ 1;
486
+ };
487
+ const rejectedText = (counts) =>
488
+ [
489
+ counts.open && `${counts.open} ${counts.open === 1 ? 'does' : 'do'} not open`,
490
+ counts.rebuild && `${counts.rebuild} ${counts.rebuild === 1 ? 'fails' : 'fail'} the index rebuild`,
491
+ counts.integrity &&
492
+ `${counts.integrity} ${counts.integrity === 1 ? 'fails' : 'fail'} the integrity check`,
493
+ counts.empty && `${counts.empty} ${counts.empty === 1 ? 'holds' : 'hold'} no rows`,
494
+ ]
495
+ .filter(Boolean)
496
+ .join(', ');
497
+ const rejected = { open: 0, rebuild: 0, integrity: 0, empty: 0 };
498
+ let at = 0;
499
+ let result;
500
+ for (; at < snapshots.length; at++) {
501
+ result = ask(at);
502
+ if (result.verdict === 'ok' || result.verdict === 'unchecked') break;
503
+ reject(rejected, result);
504
+ }
505
+ const why = rejectedText(rejected);
506
+ if (at === snapshots.length) {
507
+ const found = `None of the ${count} restores cleanly (${why}).`;
508
+ return schema ? noCommand('schema', found, found, snapshots.length) : setAside(found);
509
+ }
510
+ const passedOver =
511
+ at === 0
512
+ ? ''
513
+ : `Of the ${count}, the newest ${at === 1 ? 'one does' : `${at} do`} not restore cleanly (${why}); the next one`;
514
+ if (result.verdict === 'unchecked') {
515
+ const found = `${passedOver || `The newest of the ${count}`} could not be checked (${result.reason}): ${result.where ?? snapshots[at].path}.`;
516
+ const note = `${found} Once that is resolved, run \`${doctorCommand(dbPath)}\` again; no snapshot goes into a command before then.`;
517
+ return noCommand(schema ? 'schema' : 'unknown', found, note, snapshots.length);
197
518
  }
198
- // Newest by mtime, ties broken by name (which carries an ISO stamp) so the answer is total
199
- // rather than dependent on readdir order — the D#9 shape.
200
- const newest = snapshots.slice().sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? 1 : -1))[0];
519
+ // The command restores the newest snapshot that passes, and every older one is checked too, so
520
+ // each that passes is listed with its counts before the command and given its own (D#577). The
521
+ // fourth attempt named an older one when the newest was short of its own index (`listed`), but
522
+ // that shape has two causes: the table lost rows, or a delete's write to an index page was lost
523
+ // and the index still lists the rows the user removed (v6.30.7 r1 claims P2-1). Doctor chooses
524
+ // by age alone, as the established tools do, and the user chooses between them with the numbers
525
+ // in front of them (the survey in docs/audits, 2026-10-24). One the check cannot run on is named
526
+ // with its reason; the command restores a snapshot newer than it, so it passes over nothing newer.
527
+ const older = [];
528
+ const olderUnchecked = [];
529
+ const olderRejected = { open: 0, rebuild: 0, integrity: 0, empty: 0 };
530
+ for (let j = at + 1; j < snapshots.length; j++) {
531
+ const r = ask(j);
532
+ if (r.verdict === 'ok') older.push({ path: snapshots[j].path, result: r });
533
+ else if (r.verdict === 'unchecked') olderUnchecked.push(`${r.where ?? snapshots[j].path} (${r.reason})`);
534
+ else reject(olderRejected, r);
535
+ }
536
+ const holds = (r) =>
537
+ `${r.observations} observation(s)${r.observations === 0 && r.otherRows ? ` and ${r.otherRows} other row(s)` : ''}`;
538
+ const what = `a copy of it, restored with its indexes rebuilt the way the command does it, opens in this version, passes SQLite's integrity check and holds ${holds(result)}${result.listed ? `, ${result.listed - result.observations} fewer than its own index lists` : ''}`;
539
+ const restores = result.listed ? 'restores, but short' : passedOver ? 'does' : 'restores cleanly';
540
+ let found = `${passedOver || `The newest of the ${count}`} ${restores}: ${what}.`;
541
+ if (result.listed) {
542
+ found +=
543
+ ' Short of its own index means its table lost those rows or its index still lists rows a delete removed.';
544
+ }
545
+ if (older.length > 0) {
546
+ const each = older.map(
547
+ ({ path, result: r }) => `${path}, ${holds(r)}${r.listed ? ` (its index lists ${r.listed})` : ''}`,
548
+ );
549
+ found += ` ${older.length === 1 ? 'An older snapshot also restores' : `${older.length} older snapshots also restore`}: ${each.join('; ')}.`;
550
+ if (older.some(({ result: r }) => r.observations > result.observations)) {
551
+ found += ` ${older.length === 1 ? 'It holds' : 'One of them holds'} more observations than the one the command restores.`;
552
+ }
553
+ found +=
554
+ ' Restoring an older one instead loses what was written after it was taken and brings back what was deleted since.';
555
+ }
556
+ if (olderUnchecked.length > 0) {
557
+ found += ` ${olderUnchecked.length === 1 ? 'An older snapshot' : `${olderUnchecked.length} older snapshots`} could not be checked: ${olderUnchecked.join('; ')}.`;
558
+ }
559
+ const olderWhy = rejectedText(olderRejected);
560
+ if (olderWhy) found += ` Of the older ones, ${olderWhy}.`;
561
+ // The restore puts the snapshot (and its own -wal, when the check used one) in place writable, as
562
+ // the check's copy was, then rebuilds the indexes as the check did. `test -s` first: with the
563
+ // snapshot gone, nothing moves (v6.30.6 r1 defects P3-5).
564
+ const restoreCommand = (path, withLog) => {
565
+ const db = shellWord(dbPath);
566
+ const wal = shellWord(`${dbPath}-wal`);
567
+ return [
568
+ `test -s ${shellWord(path)}`,
569
+ ...(withLog ? [`test -s ${shellWord(`${path}-wal`)}`] : []),
570
+ setAsideCommand,
571
+ `cp ${shellWord(path)} ${db}`,
572
+ `chmod 600 ${db}`,
573
+ ...(withLog ? [`cp ${shellWord(`${path}-wal`)} ${wal}`, `chmod 600 ${wal}`] : []),
574
+ // The rebuild is part of what the check vouched for: an FTS5 index whose damage FTS5's own
575
+ // check does not see (a shadow table's rows out of key order), and an ordinary index whose
576
+ // entries no longer match its table, both pass doctor and fail integrity_check until rebuilt.
577
+ cliFor(dbPath, 'fts-check rebuild'),
578
+ ].join(' && ');
579
+ };
580
+ const named = snapshots[at].path;
201
581
  if (schema) {
202
- return {
203
- kind: 'schema',
204
- command: '',
205
- snapshotCount: snapshots.length,
206
- note:
207
- `${snapshots.length} backup snapshot(s) exist beside it; the newest is ${newest.path}. ` +
208
- 'Restoring one replaces the database file, so copy the broken file aside first.',
209
- };
582
+ const note = `${found} It is ${named}. Restoring it replaces the database file, so copy the broken file aside first.`;
583
+ return noCommand('schema', found, note, snapshots.length);
210
584
  }
585
+ // Each starts with the same set-aside, so once one has run every other stops at its guard.
586
+ const alternatives = older.map(({ path, result: r }) => ({
587
+ path,
588
+ command: restoreCommand(path, r.withLog),
589
+ }));
211
590
  return {
212
591
  kind: 'restore',
213
- command: `${clear} && cp ${shellWord(newest.path)} ${shellWord(dbPath)}`,
592
+ command: restoreCommand(named, result.withLog),
593
+ keptAs,
214
594
  snapshotCount: snapshots.length,
215
- note:
216
- `Restores the newest of ${snapshots.length} backup snapshot(s). Move the broken ` +
217
- 'file aside first if you want to keep it for inspection.',
595
+ found,
596
+ note: `${found} The command keeps the broken file and its log ${keeps}, and rebuilds the store's indexes.`,
597
+ alternatives,
218
598
  };
219
599
  }
220
600
 
@@ -233,13 +613,13 @@ export function formatDbUnusableNotice({ dbPath, remedy }) {
233
613
  : ` ${dbPath} exists but SQLite does not recognise it as a database.`,
234
614
  ];
235
615
  if (remedy.command) {
236
- // Before the command: it deletes the -wal and -shm, then replaces or moves the database file,
616
+ // Before the command: it moves the database file and its -wal aside and deletes the -shm,
237
617
  // under any session still holding the store (D#534). doctor says the same.
238
618
  lines.push(' Once every Claude Code session is closed, this one included, run:');
239
619
  lines.push(` ${remedy.command}`);
240
620
  }
241
621
  if (remedy.note) lines.push(` ${remedy.note}`);
242
- lines.push(` Saves and recall are disabled. \`${CLI_INVOKE} doctor\` re-checks.`);
622
+ lines.push(` Saves and recall are disabled. \`${doctorCommand(dbPath)}\` re-checks.`);
243
623
  return lines.join('\n');
244
624
  }
245
625
 
@@ -247,22 +627,23 @@ export function formatDbUnusableNotice({ dbPath, remedy }) {
247
627
  * The same fact, with NO COMMAND IN IT, for the model channel.
248
628
  *
249
629
  * The schema-skew twin sends one string to both channels and that is safe there — its
250
- * commands are `git pull` / `claude plugin update` / `npm i -g`. This family's remedy is
251
- * `rm -f …-wal …-shm && cp "<snapshot>" "<db>"`, which OVERWRITES the database, and handing
252
- * a ready-to-run irreversible shell line to an agent that has Bash — with no addressee and no
253
- * "ask first" — is a different proposition. Worse, the restore arm defeats its own advice: a
254
- * reader who acts on the command line destroys the broken file the next line tells them to
255
- * keep for inspection.
630
+ * commands are `git pull` / `claude plugin update` / `npm i -g`. This family's remedy moves the
631
+ * database file and its log out from under every session and copies a snapshot into place, which
632
+ * is safe only once every Claude Code session is closed, and handing that as a ready-to-run shell
633
+ * line to an agent that has Bash, from inside one of those sessions, with no addressee and no
634
+ * "ask first", is a different proposition.
256
635
  *
257
636
  * So the human gets the command and the model gets the situation. Both still learn memory is
258
637
  * off, which is the point of using both channels at all.
259
638
  *
639
+ * @param {string} [dbPath] absent when an update killed partway left a hook.mjs from 6.30.7 or
640
+ * earlier beside this file (it calls this with no argument)
260
641
  * @returns {string}
261
642
  */
262
- export function formatDbUnusableModelNotice() {
643
+ export function formatDbUnusableModelNotice(dbPath) {
263
644
  return [
264
645
  '⚠️ [claude-mem-lite] Memory is OFF for this session: the database file is unreadable.',
265
646
  ' Saves and recall are disabled. Do not attempt to repair it yourself — tell the user to',
266
- ` run \`${CLI_INVOKE} doctor\`.`,
647
+ ` run \`${dbPath ? doctorCommand(dbPath) : `${CLI_INVOKE} doctor`}\`.`,
267
648
  ].join('\n');
268
649
  }