moflo 4.10.0 → 4.10.1

package/bin/lib/db-repair.mjs

@@ -1,32 +1,54 @@
 /**
- * Memory-DB integrity check + auto-REINDEX (story #743).
+ * Memory-DB integrity check + tiered repair (#743, #1090-followup).
  *
- * The `.moflo/moflo.db` SQLite file routinely accumulates index corruption of
- * the form `row N missing from index sqlite_autoindex_memory_entries_1` —
- * the row data is intact, only the unique-key index has drifted. The most
- * common trigger is sql.js's whole-file dump-on-flush behaviour racing with
- * concurrent writes (see `feedback_sqljs_writeback_clobber.md` and #714).
+ * The `.moflo/moflo.db` SQLite file picks up corruption in two distinct modes:
+ *
+ *  1. **Index drift** — `row N missing from sqlite_autoindex_memory_entries_1`.
+ *     Row data is intact; only the unique-key b-tree is wrong. Trigger: sql.js's
+ *     whole-file dump-on-flush racing with concurrent writes (#714, #743 —
+ *     fixed for new installs by Phase 5 / #1084 which removed sql.js entirely).
+ *     **REINDEX** rebuilds the index from canonical row data.
+ *
+ *  2. **Table b-tree corruption** — `Tree N page M cell K: Rowid X out of
+ *     order`, where Tree N is a TABLE root page (not just an index). Row data
+ *     is partly intact, but page ordering is broken. Triggers we've seen:
+ *      - sql.js → node:sqlite migration: an old 4.9.x sql.js daemon flushes its
+ *        full-file dump OVER a WAL frame that the new 4.10 backend has already
+ *        written, leaving WAL referencing pages that no longer exist in main.
+ *      - Concurrent multi-process writes when the daemon was disabled (#981).
+ *     **REINDEX cannot fix this** — the table itself is broken. Recovery path:
+ *      a) `VACUUM INTO` a fresh file (single-shot rebuild; fails fast if
+ *         iteration hits an unreadable page),
+ *      b) row-level salvage — chunked `SELECT rowid > ?` per table, catching
+ *         per-chunk errors and skipping past corrupt page ranges,
+ *      c) atomic swap with .corrupt.<TS> backup retained for forensics.
+ *
+ *  3. **Unrecoverable** — header damage, encrypted-by-malware, etc. We can't
+ *     fix this; surface a clear failure and let the user decide between manual
+ *     `flo memory rebuild-index` (destructive) and offline recovery tools.
  *
  * Symptoms when uncorrected:
  *  - `index-guidance.mjs` and `index-patterns.mjs` fail mid-write with
  *    `database disk image is malformed`, leaving partial state.
  *  - The ephemeral-namespace purge (#729) fails silently, so hive-mind /
  *    tasklist / epic-state / test-bridge-fix rows accumulate.
- *  - Vector counts in the statusline stay inflated (observed: 4415 with
- *    1025 unpurged ephemeral rows).
+ *  - Vector counts in the statusline stay inflated.
+ *  - Healer's deep checks throw with "database disk image is malformed",
+ *    surfacing as the synthetic 'Check' failure (doctor.ts:214).
  *
- * Fix shape: REINDEX rebuilds indexes from the canonical row data — much less
- * destructive than a full rebuild and works for the typical drift mode. If
- * REINDEX itself fails to restore integrity we leave the file alone and
- * report; manual `flo memory rebuild-index` is the fallback.
- *
- * MUST run BEFORE any long-lived sql.js consumer (MCP server, daemon) opens
- * the DB and BEFORE the embeddings migration / soft-delete purge / ephemeral
- * purge — those all swallow corruption errors and silently no-op.
+ * MUST run BEFORE any long-lived consumer (MCP server, daemon) opens the DB
+ * and BEFORE the embeddings migration / soft-delete purge / ephemeral purge —
+ * those all swallow corruption errors and silently no-op.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, renameSync, unlinkSync } from 'node:fs';
 import { memoryDbPath } from './moflo-paths.mjs';
 import { openBackend } from './get-backend.mjs';
+import './suppress-sqlite-warning.mjs';
+// Resolve node:sqlite once at module load — get-backend.mjs has already
+// loaded it by this point, so the dynamic import is a cache hit. Avoids
+// three independent `await import('node:sqlite')` calls inside the repair
+// functions (style cleanup; was producing no functional difference).
+const { DatabaseSync } = await import('node:sqlite');
 
 function isOk(execResult) {
   const rows = execResult?.[0]?.values ?? [];
@@ -38,42 +60,337 @@ function corruptionCount(execResult) {
 }
 
 /**
- * Probe the memory DB for index corruption and run REINDEX in place if
- * found. Returns `{ repaired, errors, persistent }`:
- *  - `repaired: true` and `errors > 0` when REINDEX restored integrity.
- *  - `repaired: false, errors: 0` when the DB is healthy or absent.
- *  - `repaired: false, errors > 0, persistent: true` when corruption survives
- *    REINDEX (caller should surface to the user — manual rebuild needed).
+ * Open `.moflo/moflo.db` raw via node:sqlite in readonly mode and run
+ * `PRAGMA integrity_check`. Bypasses {@link openBackend} because that path
+ * sets `journal_mode=WAL`, `busy_timeout`, and `synchronous=NORMAL` on every
+ * non-readonly open — those PRAGMAs can themselves throw against a corrupt
+ * file, and the pre-#1090 code path caught those throws and reported the DB
+ * as healthy. Readonly + no PRAGMAs = the probe always reaches the
+ * `integrity_check` call regardless of file health.
+ *
+ * Exported so the TS doctor check (`checkMemoryDbIntegrity` in
+ * `src/cli/commands/doctor-checks-config.ts`) can call into the same
+ * implementation instead of re-deriving the readonly-no-PRAGMAs probe.
+ *
+ * @param {string} dbPath
+ * @returns {Promise<{ ok: boolean, errors: number, openFailed?: boolean }>}
+ */
+export async function probeIntegrityRaw(dbPath) {
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+  } catch {
+    return { ok: false, errors: 0, openFailed: true };
+  }
+  try {
+    const rows = db.prepare('PRAGMA integrity_check').all();
+    if (rows.length === 1 && String(rows[0]?.integrity_check ?? '').toLowerCase() === 'ok') {
+      return { ok: true, errors: 0 };
+    }
+    return { ok: false, errors: rows.length };
+  } catch {
+    return { ok: false, errors: 0, openFailed: true };
+  } finally {
+    try { db.close(); } catch { /* already-dead handle */ }
+  }
+}
+
+/**
+ * Tier-2 recovery: `VACUUM INTO` a fresh file. Single SQLite call that
+ * iterates every row of every table and writes them to a brand-new database
+ * with rebuilt indexes. Fails fast if iteration hits an unreadable page —
+ * caller falls back to row-level salvage.
+ *
+ * @param {string} srcPath
+ * @param {string} dstPath
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+async function tryVacuumInto(srcPath, dstPath) {
+  try { if (existsSync(dstPath)) unlinkSync(dstPath); } catch { /* best effort */ }
+  let db;
+  try {
+    // Open writable (not readonly) — VACUUM needs to checkpoint WAL first.
+    // Skip our standard WAL pragmas (they can throw on corrupt files); SQLite
+    // applies its defaults which are sufficient for VACUUM INTO.
+    db = new DatabaseSync(srcPath);
+  } catch (err) {
+    return { ok: false, error: err?.message ?? 'open failed' };
+  }
+  try {
+    try { db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); } catch { /* corrupt WAL ok */ }
+    db.exec(`VACUUM INTO '${dstPath.replace(/'/g, "''")}'`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? 'vacuum failed' };
+  } finally {
+    try { db.close(); } catch { /* */ }
+  }
+}
+
+/**
+ * Tier-3 recovery: row-level salvage. Iterate each non-empty table in
+ * `rowid > ?` chunks; on any chunk-read failure, skip past that chunk's
+ * rowid range and continue. Per-table loss stats returned so the caller can
+ * surface what was preserved vs lost.
+ *
+ * Schema is copied verbatim from `sqlite_master.sql` so triggers/indexes/views
+ * are preserved alongside tables. `INSERT OR IGNORE` handles unique-key
+ * collisions from any duplicate-rowid corruption mode.
+ *
+ * @param {string} srcPath
+ * @param {string} dstPath
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   error?: string,
+ *   lossStats?: Record<string, { read: number, written: number, errors: number }>,
+ * }>}
+ */
+async function trySalvageRowByRow(srcPath, dstPath) {
+  try { if (existsSync(dstPath)) unlinkSync(dstPath); } catch { /* */ }
+
+  let src;
+  try {
+    src = new DatabaseSync(srcPath, { readOnly: true });
+  } catch (err) {
+    return { ok: false, error: err?.message ?? 'src open failed' };
+  }
+
+  // Open dst defensively. If this throws (e.g. permissions, dst path in a
+  // dir we can't create, or a concurrent lock on dstPath), keep the
+  // "never throws" contract by returning the failure shape — otherwise the
+  // open exception would escape past `repairMemoryDbIfCorrupt` and block
+  // session start, which is the failure mode this whole module exists to
+  // prevent.
+  let dst;
+  try {
+    dst = new DatabaseSync(dstPath);
+  } catch (err) {
+    try { src.close(); } catch { /* */ }
+    return { ok: false, error: err?.message ?? 'dst open failed' };
+  }
+
+  const lossStats = {};
+  const CHUNK = 500;
+
+  try {
+    // Copy schema. Order matters: tables first (else indexes/triggers/views
+    // reference nonexistent tables), then everything else. sqlite_* objects
+    // (sqlite_sequence, sqlite_autoindex_*) are created implicitly by SQLite.
+    const schemaRows = src
+      .prepare(
+        "SELECT type, name, tbl_name, sql FROM sqlite_master " +
+          "WHERE sql IS NOT NULL ORDER BY CASE type " +
+          "WHEN 'table' THEN 1 WHEN 'index' THEN 2 WHEN 'view' THEN 3 ELSE 4 END",
+      )
+      .all();
+    for (const s of schemaRows) {
+      if (String(s.name).startsWith('sqlite_')) continue;
+      try { dst.exec(s.sql + ';'); } catch { /* malformed schema row — skip */ }
+    }
+
+    // Salvage rows table-by-table.
+    const tables = src
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+      .all();
+
+    for (const t of tables) {
+      const name = String(t.name);
+      lossStats[name] = { read: 0, written: 0, errors: 0 };
+
+      const cols = src.prepare(`PRAGMA table_info('${name.replace(/'/g, "''")}')`).all();
+      if (cols.length === 0) continue;
+      const colList = cols.map((c) => '"' + String(c.name).replace(/"/g, '""') + '"').join(',');
+      const placeholders = cols.map(() => '?').join(',');
+      const insert = dst.prepare(
+        `INSERT OR IGNORE INTO "${name.replace(/"/g, '""')}" (${colList}) VALUES (${placeholders})`,
+      );
+
+      let lastRowid = 0;
+      let safetyCap = 0;
+      const MAX_ITERATIONS = 100_000;
+
+      while (safetyCap++ < MAX_ITERATIONS) {
+        let rows;
+        try {
+          rows = src
+            .prepare(
+              `SELECT rowid as __rid, * FROM "${name.replace(/"/g, '""')}" ` +
+                `WHERE rowid > ? ORDER BY rowid LIMIT ${CHUNK}`,
+            )
+            .all(lastRowid);
+        } catch {
+          lossStats[name].errors++;
+          lastRowid += CHUNK;
+          continue;
+        }
+        if (!rows || rows.length === 0) break;
+        lossStats[name].read += rows.length;
+        for (const r of rows) {
+          try {
+            insert.run(...cols.map((c) => r[c.name]));
+            lossStats[name].written++;
+          } catch {
+            lossStats[name].errors++;
+          }
+          lastRowid = Number(r.__rid);
+        }
+        if (rows.length < CHUNK) break;
+      }
+    }
+
+    // Verify the recovered file. If integrity_check still fails, the
+    // salvage didn't actually produce a clean file — surface as failure
+    // (caller will keep the corrupted original in place).
+    const checkRows = dst.prepare('PRAGMA integrity_check').all();
+    const recoveredOk =
+      checkRows.length === 1 &&
+      String(checkRows[0]?.integrity_check ?? '').toLowerCase() === 'ok';
+    if (!recoveredOk) {
+      return { ok: false, error: 'recovered file failed integrity_check', lossStats };
+    }
+    return { ok: true, lossStats };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? 'salvage failed' };
+  } finally {
+    try { src.close(); } catch { /* */ }
+    try { dst.close(); } catch { /* */ }
+  }
+}
+
+/**
+ * Atomically swap a freshly recovered DB into the canonical path, keeping the
+ * corrupted original (+ its WAL/SHM sidecars if present) under `.corrupt.<TS>`
+ * suffixes for forensics. Caller must guarantee no live writer holds the
+ * canonical file open before invoking this — see `stopWritersBeforeRepair`
+ * for the daemon-coordinated entry point.
+ *
+ * @param {string} canonicalPath
+ * @param {string} recoveredPath
+ * @returns {{ ok: boolean, error?: string, corruptSuffix: string }}
+ */
+function atomicSwap(canonicalPath, recoveredPath) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').replace(/Z$/, '');
+  const corruptSuffix = `.corrupt.${ts}`;
+  try {
+    if (existsSync(canonicalPath)) {
+      renameSync(canonicalPath, canonicalPath + corruptSuffix);
+    }
+    const walPath = canonicalPath + '-wal';
+    const shmPath = canonicalPath + '-shm';
+    if (existsSync(walPath)) {
+      try { renameSync(walPath, walPath + corruptSuffix); } catch { /* not always present */ }
+    }
+    if (existsSync(shmPath)) {
+      try { renameSync(shmPath, shmPath + corruptSuffix); } catch { /* not always present */ }
+    }
+    renameSync(recoveredPath, canonicalPath);
+    return { ok: true, corruptSuffix };
+  } catch (err) {
+    return { ok: false, error: err?.message ?? 'swap failed', corruptSuffix };
+  }
+}
+
+/**
+ * Probe the memory DB for corruption and run a tiered repair if found:
+ *
+ *  - Tier 1: `REINDEX` in place (index-only corruption — #743).
+ *  - Tier 2: `VACUUM INTO` fresh file + atomic swap (table b-tree corruption).
+ *  - Tier 3: row-level salvage + atomic swap (deep corruption with partial
+ *    row loss).
+ *
+ * Returns a structured result:
+ *  - `{ repaired: false, errors: 0 }` — healthy or absent.
+ *  - `{ repaired: true, errors: N, tier: 'reindex' }` — Tier 1 worked.
+ *  - `{ repaired: true, errors: N, tier: 'vacuum', corruptBackup }` — Tier 2.
+ *  - `{ repaired: true, errors: N, tier: 'salvage', corruptBackup, lossStats }`
+ *    — Tier 3 (partial row loss possible; see `lossStats`).
+ *  - `{ repaired: false, errors: N, persistent: true }` — nothing worked;
+ *    manual recovery needed.
  *
  * Never throws; any internal failure becomes `{ repaired: false, errors: 0 }`
  * so a probe failure cannot block session start.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<{
+ *   repaired: boolean,
+ *   errors: number,
+ *   tier?: 'reindex' | 'vacuum' | 'salvage',
+ *   persistent?: boolean,
+ *   corruptBackup?: string,
+ *   lossStats?: Record<string, { read: number, written: number, errors: number }>,
+ * }>}
  */
 export async function repairMemoryDbIfCorrupt(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { repaired: false, errors: 0 };
 
-  let db = null;
-  try {
-    db = await openBackend(projectRoot, { create: false });
+  // Step 1 — defensive readonly probe (cannot throw on WAL-setup errors
+  // against corrupt files). If the open itself fails, fall through to the
+  // openBackend path which has retry semantics for transient lock issues;
+  // truly unopenable files surface as persistent below.
+  const probe = await probeIntegrityRaw(dbPath);
+  if (probe.ok) return { repaired: false, errors: 0 };
 
-    const before = db.exec('PRAGMA integrity_check');
-    if (isOk(before)) {
-      return { repaired: false, errors: 0 };
-    }
+  const errors = probe.errors;
 
-    const errors = corruptionCount(before);
-    db.run('REINDEX');
+  // Step 2 — Tier 1: REINDEX via the existing backend path. Fast for the
+  // common index-drift mode and preserves the file in place.
+  if (!probe.openFailed) {
+    try {
+      const db = await openBackend(projectRoot, { create: false });
+      try {
+        db.run('REINDEX');
+        const after = db.exec('PRAGMA integrity_check');
+        if (isOk(after)) {
+          db.save();
+          return { repaired: true, errors, tier: 'reindex' };
+        }
+      } finally {
+        try { db.close(); } catch { /* */ }
+      }
+    } catch {
+      // REINDEX path failed (often because openBackend's WAL pragmas throw
+      // on a corrupt file). Fall through to deeper recovery.
+    }
+  }
 
-    const after = db.exec('PRAGMA integrity_check');
-    if (!isOk(after)) {
-      return { repaired: false, errors, persistent: true };
+  // Step 3 — Tier 2: VACUUM INTO a fresh file.
+  const recoveredPath = dbPath + '.recovered';
+  const vacuum = await tryVacuumInto(dbPath, recoveredPath);
+  if (vacuum.ok) {
+    const recoveredProbe = await probeIntegrityRaw(recoveredPath);
+    if (recoveredProbe.ok) {
+      const swap = atomicSwap(dbPath, recoveredPath);
+      if (swap.ok) {
+        return {
+          repaired: true,
+          errors: errors || corruptionCount(recoveredProbe),
+          tier: 'vacuum',
+          corruptBackup: dbPath + swap.corruptSuffix,
+        };
+      }
     }
+    try { unlinkSync(recoveredPath); } catch { /* */ }
+  }
 
-    db.save();
-    return { repaired: true, errors };
-  } catch {
-    return { repaired: false, errors: 0 };
-  } finally {
-    if (db) try { db.close(); } catch { /* non-fatal */ }
+  // Step 4 — Tier 3: row-level salvage.
+  const salvage = await trySalvageRowByRow(dbPath, recoveredPath);
+  if (salvage.ok) {
+    const swap = atomicSwap(dbPath, recoveredPath);
+    if (swap.ok) {
+      return {
+        repaired: true,
+        errors,
+        tier: 'salvage',
+        corruptBackup: dbPath + swap.corruptSuffix,
+        lossStats: salvage.lossStats,
+      };
+    }
+    try { unlinkSync(recoveredPath); } catch { /* */ }
+  } else {
+    try { if (existsSync(recoveredPath)) unlinkSync(recoveredPath); } catch { /* */ }
   }
+
+  // Step 5 — give up.
+  return { repaired: false, errors, persistent: true };
 }

package/bin/session-start-launcher.mjs

@@ -268,15 +268,51 @@ try {
 try {
   const repair = await repairMemoryDbIfCorrupt(projectRoot);
   if (repair?.repaired) {
-    emitMutation(
-      'repaired memory db index',
-      `${plural(repair.errors, 'index error')} fixed via REINDEX`,
-    );
+    // Three recovery tiers, three messages. Tier surfaces what level of
+    // damage the DB had so the user (and any downstream telemetry) knows
+    // whether row data was lost. See bin/lib/db-repair.mjs for the cascade.
+    if (repair.tier === 'reindex') {
+      emitMutation(
+        'repaired memory db index',
+        `${plural(repair.errors, 'index error')} fixed via REINDEX`,
+      );
+    } else if (repair.tier === 'vacuum') {
+      emitMutation(
+        'rebuilt memory db',
+        `${plural(repair.errors, 'integrity violation')} fixed via VACUUM INTO; corrupt original kept at ${repair.corruptBackup ?? '.moflo/moflo.db.corrupt.*'}`,
+      );
+    } else if (repair.tier === 'salvage') {
+      // Row-level salvage may have dropped rows; summarise loss so the
+      // user sees what's gone before downstream consumers (indexer,
+      // embeddings) re-process the survivors.
+      let lossSummary = '';
+      if (repair.lossStats) {
+        const losses = Object.entries(repair.lossStats)
+          .map(([tbl, s]) => {
+            const lost = Math.max(0, s.read - s.written);
+            return lost > 0 ? `${tbl} ${s.written}/${s.read}` : null;
+          })
+          .filter(Boolean);
+        if (losses.length > 0) lossSummary = ` (rows preserved: ${losses.join(', ')})`;
+      }
+      emitMutation(
+        'salvaged memory db',
+        `${plural(repair.errors, 'integrity violation')} recovered via row-level salvage${lossSummary}; corrupt original kept at ${repair.corruptBackup ?? '.moflo/moflo.db.corrupt.*'}`,
+      );
+    } else {
+      // Older db-repair without a `tier` field — fall back to legacy text.
+      emitMutation(
+        'repaired memory db',
+        `${plural(repair.errors, 'integrity violation')} fixed`,
+      );
+    }
   } else if (repair?.persistent) {
     // Surface to stderr — Claude additionalContext + the user both see this.
-    // Manual `flo memory rebuild-index` is the next step.
+    // Every recovery tier exhausted; user options are destructive only.
     process.stderr.write(
-      `moflo: memory db has ${plural(repair.errors, 'index error')} REINDEX could not fix — run 'flo memory rebuild-index'\n`,
+      `moflo: memory db has ${plural(repair.errors, 'integrity violation')} ` +
+      `that REINDEX / VACUUM INTO / row-level salvage could not fix — ` +
+      `run 'flo memory rebuild-index' (destructive) or restore from backup\n`,
     );
   }
 } catch {

package/dist/src/cli/commands/doctor-checks-config.js

@@ -8,6 +8,7 @@ import { join } from 'path';
 import os from 'os';
 import { getDaemonLockHolder } from '../services/daemon-lock.js';
 import { legacyMemoryDbPath, memoryDbCandidatePaths, memoryDbPath, } from '../services/moflo-paths.js';
+import { probeDbIntegrity } from '../services/memory-db-integrity-repair.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 export async function checkConfigFile() {
     // JSON configs (parse-validated). LEGACY-CONFIG: `.claude-flow.json` and
@@ -131,6 +132,65 @@ export async function checkMemoryDatabase() {
     }
     return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
 }
+/**
+ * Tier-1 corruption probe for `.moflo/moflo.db`. Runs `PRAGMA integrity_check`
+ * via a raw node:sqlite readonly handle — bypasses `openBackend` because that
+ * path sets WAL pragmas on open and those throw on deeply-corrupt files,
+ * masking the real failure as a generic "Check" error (doctor.ts:214).
+ *
+ * Owns the corruption signal so downstream checks (Embeddings, Semantic
+ * Quality, Memory Access Functional, etc.) don't end up doing it implicitly
+ * via their own swallow-all error paths. The companion fix in
+ * doctor-fixes.ts coordinates daemon stop + tiered repair via the JS-side
+ * `repairMemoryDbIfCorrupt` (bin/lib/db-repair.mjs).
+ *
+ * Status semantics:
+ *  - `pass` — DB absent OR `integrity_check` returns 'ok'.
+ *  - `fail` — corruption detected. `fix` field points at the healer's
+ *    auto-recovery path (which runs REINDEX → VACUUM INTO → row-level
+ *    salvage in order of escalation).
+ *  - `warn` — probe itself crashed (rare; surfaces the diagnostic rather
+ *    than masking it).
+ */
+export async function checkMemoryDbIntegrity(cwd = process.cwd()) {
+    const dbPath = memoryDbPath(cwd);
+    if (!existsSync(dbPath)) {
+        return { name: 'Memory DB Integrity', status: 'pass', message: 'DB absent (no integrity probe needed)' };
+    }
+    // Delegate to the single readonly-no-PRAGMAs probe in
+    // `bin/lib/db-repair.mjs` (via the TS service bridge). Avoids re-deriving
+    // the same DatabaseSync({ readOnly: true }) + integrity_check sequence in
+    // two places and keeps the "what counts as healthy" semantics in one file.
+    try {
+        const probe = await probeDbIntegrity(dbPath);
+        if (probe.ok) {
+            return { name: 'Memory DB Integrity', status: 'pass', message: 'PRAGMA integrity_check: ok' };
+        }
+        const message = probe.openFailed
+            ? 'Unable to probe DB (readonly open failed — likely deep corruption)'
+            : `${probe.errors} integrity violation(s) detected`;
+        return {
+            name: 'Memory DB Integrity',
+            status: 'fail',
+            message,
+            fix: 'flo healer --fix -c memory-db-integrity',
+        };
+    }
+    catch (e) {
+        // The probe itself maps "readonly open failed" to `openFailed: true`
+        // and we surface that as `fail` above. Reaching the catch means the
+        // probe *module* couldn't be loaded — `findMofloPackageRoot()` returned
+        // null (broken install / wrong cwd) or the dynamic import threw. Both
+        // are first-class diagnostic failures — a broken install must not be
+        // silently downgraded to `warn` and hidden from the healer summary.
+        return {
+            name: 'Memory DB Integrity',
+            status: 'fail',
+            message: `Integrity probe unavailable: ${errorDetail(e)}`,
+            fix: 'flo healer --fix -c memory-db-integrity',
+        };
+    }
+}
 /**
  * Standard MCP-config search paths: home (Claude Desktop on macOS/Linux),
  * XDG config dir, project-local `.mcp.json`, and APPDATA on Windows.

package/dist/src/cli/commands/doctor-fixes.js

@@ -243,6 +243,63 @@ export async function autoFixCheck(check) {
                 return false;
             }
         },
+        // Tiered recovery for `.moflo/moflo.db` corruption (REINDEX → VACUUM
+        // INTO → row-level salvage). The TS service stops the daemon
+        // automatically (cross-platform via `process.kill('SIGTERM')`) so the
+        // atomic swap doesn't race a live writer; we restart it via the
+        // existing `npx moflo daemon start` shorthand after. The MCP server,
+        // started by Claude Code outside our process tree, isn't stopped here —
+        // explicit user guidance covers that case at the end.
+        'Memory DB Integrity': async () => {
+            try {
+                const { repairMemoryDbIntegrity } = await import('../services/memory-db-integrity-repair.js');
+                const result = await repairMemoryDbIntegrity(process.cwd());
+                if (result.repaired) {
+                    const tierLabel = result.tier === 'reindex' ? 'REINDEX (index rebuild)'
+                        : result.tier === 'vacuum' ? 'VACUUM INTO (fresh-file rebuild)'
+                            : result.tier === 'salvage' ? 'row-level salvage'
+                                : 'repaired';
+                    output.writeln(output.dim(`  Recovered via ${tierLabel}.`));
+                    if (result.corruptBackup) {
+                        output.writeln(output.dim(`  Pre-repair backup retained: ${result.corruptBackup}`));
+                    }
+                    if (result.lossStats) {
+                        for (const [tbl, s] of Object.entries(result.lossStats)) {
+                            if (s.read > 0) {
+                                const lost = Math.max(0, s.read - s.written);
+                                if (lost > 0) {
+                                    output.writeln(output.warning(`  ${tbl}: ${s.written}/${s.read} rows preserved (lost ${lost} across ${s.errors} unreadable chunk(s))`));
+                                }
+                            }
+                        }
+                        output.writeln(output.dim('  Embeddings for lost rows will be regenerated on next index pass — run `npx moflo embeddings init` to force.'));
+                    }
+                    // Restart the daemon if we stopped it. The launcher's own
+                    // section-4 spawn handles this on next session-start, but a
+                    // mid-session healer call shouldn't leave the daemon down.
+                    if (result.daemonStopped) {
+                        output.writeln(output.dim('  Restarting daemon...'));
+                        await runFixCommand('npx moflo daemon start');
+                    }
+                    // Cross-platform note for the MCP server (out-of-tree, can't
+                    // SIGTERM). On Windows the swap would have failed if MCP was
+                    // holding the file; on POSIX the swap succeeds but MCP keeps
+                    // reading the stale inode until restart. Either way: restart
+                    // Claude Code to fully apply.
+                    output.writeln(output.dim('  Restart Claude Code so the MCP server re-opens the recovered DB.'));
+                    return true;
+                }
+                if (result.persistent) {
+                    output.writeln(output.warning('  Corruption survived every recovery tier. Manual options: ' +
+                        '`npx moflo memory rebuild-index` (destructive) or restore from a known-good backup.'));
+                }
+                return false;
+            }
+            catch (e) {
+                output.writeln(output.warning(`  Repair failed: ${errorDetail(e)}`));
+                return false;
+            }
+        },
         'Status Line': async () => {
             const settingsPath = join(process.cwd(), '.claude', 'settings.json');
             if (!existsSync(settingsPath))

package/dist/src/cli/commands/doctor-registry.js

@@ -12,7 +12,7 @@ import { checkWritersAudit } from './doctor-checks-writers-audit.js';
 import { checkSwarmFunctional, checkHiveMindFunctional, } from './doctor-checks-swarm.js';
 import { checkMemoryAccessFunctional } from './doctor-checks-memory-access.js';
 import { checkBuildTools, checkClaudeCode, checkDiskSpace, checkGit, checkGitRepo, checkNodeVersion, checkNpmVersion, } from './doctor-checks-runtime.js';
-import { checkConfigFile, checkDaemonStatus, checkDaemonWriteRouting, checkMcpServers, checkMemoryDatabase, checkMofloYamlCompliance, checkStatusLine, checkTestDirs, } from './doctor-checks-config.js';
+import { checkConfigFile, checkDaemonStatus, checkDaemonWriteRouting, checkMcpServers, checkMemoryDatabase, checkMemoryDbIntegrity, checkMofloYamlCompliance, checkStatusLine, checkTestDirs, } from './doctor-checks-config.js';
 import { checkSpellEngine, checkSandboxTier } from './doctor-checks-platform.js';
 import { checkEmbeddings, checkSemanticQuality, } from './doctor-checks-memory.js';
 import { checkIntelligence } from './doctor-checks-intelligence.js';
@@ -40,6 +40,12 @@ export const allChecks = [
     checkDaemonWriteRouting,
     checkWritersAudit,
     checkMemoryDatabase,
+    // Owns the corruption signal so downstream checks (Embeddings, Semantic
+    // Quality, Memory Access Functional) don't surface it as the synthetic
+    // "Check" failure (doctor.ts:214). MUST run after checkMemoryDatabase
+    // (which confirms the file exists) and before any check that opens the
+    // DB via openBackend.
+    checkMemoryDbIntegrity,
     checkEmbeddings,
     checkEmbeddingHygiene,
     checkEmbeddingCoverageTruth,
@@ -91,6 +97,9 @@ export const componentMap = {
     'writers-audit': checkWritersAudit,
     'writers': checkWritersAudit,
     'memory': checkMemoryDatabase,
+    'memory-db-integrity': checkMemoryDbIntegrity,
+    'integrity': checkMemoryDbIntegrity,
+    'memory-integrity': checkMemoryDbIntegrity,
     'embeddings': checkEmbeddings,
     'embedding-hygiene': checkEmbeddingHygiene,
     'embedding-coverage': checkEmbeddingCoverageTruth,

package/dist/src/cli/memory/bridge-embedder.js

@@ -54,9 +54,14 @@ export const EMBEDDING_MODEL_LEGACY_DEFAULT = 'local';
  * - `epic-state`    — Epic progress (epic-N, story-M) written by commands/epic.ts
  * - `test-bridge-fix` — Single 2026-04-23 row left over from a one-off test
  *
+ * Membership is also extended by {@link EPHEMERAL_NAMESPACE_PREFIXES} for
+ * dynamic-name namespaces (e.g. `doctor-memprobe-<persona>`). Most callers
+ * should use {@link isEphemeralNamespace} which checks both sets.
+ *
  * See story #729 for the source-trace and rationale. The session-start
- * launcher only purges {@link PURGE_ON_SESSION_START_NAMESPACES} — a strict
- * subset that *excludes* `tasklist`, because the dashboard's Flo Runs tab
+ * launcher only purges {@link PURGE_ON_SESSION_START_NAMESPACES} +
+ * {@link PURGE_ON_SESSION_START_PREFIXES} — a strict subset that *excludes*
+ * `tasklist`, because the dashboard's Flo Runs tab
  * (`daemon-dashboard.ts handleSpells`) reads tasklist; purging it on every
  * session would empty the tab between sessions (#968).
  */
@@ -66,6 +71,26 @@ export const EPHEMERAL_NAMESPACES = new Set([
     'epic-state',
     'test-bridge-fix',
 ]);
+/**
+ * Prefix patterns that extend {@link EPHEMERAL_NAMESPACES} for namespaces
+ * whose suffix is generated at runtime. Any namespace beginning with one of
+ * these prefixes is treated as ephemeral (skips embedding).
+ *
+ * NOTE — design distinction from {@link PURGE_ON_SESSION_START_PREFIXES}:
+ * a namespace can be auto-purgeable WITHOUT being skip-embed. For example,
+ * `doctor-memprobe-<persona>` rows are intentionally purged on every
+ * session start (the cleanup is best-effort and accumulates across
+ * sessions) but MUST still get embeddings — the probe's whole purpose is
+ * to validate the embedder is wired (`Memory Access Functional` check
+ * asserts `hasEmbedding=true`). Skipping embedding for those rows breaks
+ * the doctor check. Put a prefix here only when both properties apply.
+ *
+ * Currently empty — there's no namespace today that needs both skip-embed
+ * AND prefix-match. Kept as an explicit export so the bridge embedder's
+ * call site is uniform and future skip-embed prefixes have an obvious
+ * home.
+ */
+export const EPHEMERAL_NAMESPACE_PREFIXES = new Set([]);
 /**
  * Subset of {@link EPHEMERAL_NAMESPACES} that the session-start launcher
  * hard-purges via `services/ephemeral-namespace-purge.ts`. Excludes
@@ -77,6 +102,62 @@ export const PURGE_ON_SESSION_START_NAMESPACES = new Set([
     'epic-state',
     'test-bridge-fix',
 ]);
+/**
+ * Prefix patterns purged alongside {@link PURGE_ON_SESSION_START_NAMESPACES}
+ * by the session-start launcher.
+ *
+ * Members:
+ * - `doctor-memprobe-` — `flo healer`'s `Memory Access` round-trip probe
+ *   writes a sentinel into `doctor-memprobe-<persona>` (persona is one of
+ *   `subagent`, `swarm-agent`, `hive-mind-worker`, plus test variants).
+ * - `doctor-neighbors-` — `flo healer`'s neighbor-traversal probe creates a
+ *   fresh `doctor-neighbors-<timestamp>` namespace for each run and seeds
+ *   three chunk rows. Unlike memprobe (fixed personas), every healer run
+ *   spawns a NEW namespace, so namespace pollution grows linearly with
+ *   healer-run count if cleanup races fail.
+ *
+ * Both probes register an explicit cleanup via `safeDelete`, but the
+ * cleanup is best-effort and silently swallows failures (e.g. daemon
+ * races, MCP transport errors) — so rows accumulate across consumer
+ * sessions. Auto-purging matches the pattern for
+ * `hive-mind`/`epic-state`/`test-bridge-fix`. These rows MUST still get
+ * embeddings (see {@link EPHEMERAL_NAMESPACE_PREFIXES} for why) — only
+ * their persistence across sessions is curtailed.
+ */
+export const PURGE_ON_SESSION_START_PREFIXES = new Set([
+    'doctor-memprobe-',
+    'doctor-neighbors-',
+]);
+/**
+ * Return `true` if a namespace is ephemeral — either an exact member of
+ * {@link EPHEMERAL_NAMESPACES} or one whose name begins with a prefix in
+ * {@link EPHEMERAL_NAMESPACE_PREFIXES}. Callers checking embedding-skip
+ * behavior should use this helper rather than `.has()` on the Set directly.
+ */
+export function isEphemeralNamespace(namespace) {
+    if (EPHEMERAL_NAMESPACES.has(namespace))
+        return true;
+    for (const prefix of EPHEMERAL_NAMESPACE_PREFIXES) {
+        if (namespace.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Return `true` if a namespace should be hard-purged on session start —
+ * either an exact member of {@link PURGE_ON_SESSION_START_NAMESPACES} or one
+ * whose name begins with a prefix in
+ * {@link PURGE_ON_SESSION_START_PREFIXES}.
+ */
+export function shouldPurgeOnSessionStart(namespace) {
+    if (PURGE_ON_SESSION_START_NAMESPACES.has(namespace))
+        return true;
+    for (const prefix of PURGE_ON_SESSION_START_PREFIXES) {
+        if (namespace.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
 /**
  * Maximum number of `tasklist` rows kept across session restarts. The
  * session-start retention pass deletes oldest rows beyond this cap, so the
@@ -140,7 +221,7 @@ export async function resolveBridgeEmbedding(value, precomputed, generateEmbeddi
     // Ephemeral namespaces (run-tracking, never user knowledge) skip embeddings
     // unconditionally — even precomputed vectors are dropped. Result row has
     // `embedding IS NULL` and `embedding_model IS NULL`. See #729.
-    if (namespace && EPHEMERAL_NAMESPACES.has(namespace)) {
+    if (namespace && isEphemeralNamespace(namespace)) {
         return { ok: true, json: null, dimensions: 0, model: null };
     }
     const wantsEmbedding = generateEmbeddingFlag !== false && value.length > 0;

package/dist/src/cli/memory/memory-initializer.js

@@ -20,7 +20,7 @@ import * as path from 'path';
 import { formatEmbeddingError } from './embedding-errors.js';
 import { HnswLite } from './hnsw-lite.js';
 import { tryLoadHnswSidecar } from './hnsw-persistence.js';
-import { EMBEDDING_MODEL_OPT_OUT, EPHEMERAL_NAMESPACES, getBridgeEmbedder } from './bridge-embedder.js';
+import { EMBEDDING_MODEL_OPT_OUT, getBridgeEmbedder, isEphemeralNamespace } from './bridge-embedder.js';
 import { parseEmbeddingJson, toFloat32 } from './controllers/_shared.js';
 import { writeVectorStatsJson } from './bridge-core.js';
 import { serialiseMetadata } from './bridge-entries.js';
@@ -1619,7 +1619,7 @@ export async function storeEntry(options) {
         let embeddingJson = null;
         let embeddingDimensions = null;
         let embeddingModel = EMBEDDING_MODEL_OPT_OUT;
-        const isEphemeralNs = EPHEMERAL_NAMESPACES.has(namespace);
+        const isEphemeralNs = isEphemeralNamespace(namespace);
         if (isEphemeralNs) {
             embeddingModel = null;
         }

package/dist/src/cli/services/ephemeral-namespace-purge.js

@@ -27,7 +27,7 @@
  * @module cli/services/ephemeral-namespace-purge
  */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { PURGE_ON_SESSION_START_NAMESPACES, TASKLIST_RETENTION_CAP, } from '../memory/bridge-embedder.js';
+import { PURGE_ON_SESSION_START_NAMESPACES, PURGE_ON_SESSION_START_PREFIXES, TASKLIST_RETENTION_CAP, } from '../memory/bridge-embedder.js';
 import { memoryDbPath } from './moflo-paths.js';
 import { openDaemonDatabase } from '../memory/daemon-backend.js';
 /**
@@ -56,18 +56,28 @@ export async function purgeEphemeralNamespaces(options = {}) {
         // Single COUNT pass to gate both DELETEs — a clean DB is the steady
         // state and we don't want two no-op DELETEs (with their query-planner
         // overhead) on every session start.
+        //
+        // Match shape: exact namespace IN (...) OR namespace LIKE 'prefix-%'.
+        // The prefix clause covers runtime-suffixed namespaces like
+        // `doctor-memprobe-<persona>` whose set of suffixes isn't known upfront.
         const namespaces = Array.from(PURGE_ON_SESSION_START_NAMESPACES);
+        const prefixes = Array.from(PURGE_ON_SESSION_START_PREFIXES);
         const cap = options.tasklistRetentionCap ?? TASKLIST_RETENTION_CAP;
-        const placeholders = namespaces.map(() => '?').join(', ');
+        const exactClause = namespaces.length
+            ? `namespace IN (${namespaces.map(() => '?').join(', ')})`
+            : '0';
+        const prefixClause = prefixes.map(() => 'namespace LIKE ?').join(' OR ');
+        const purgeWhere = prefixClause ? `(${exactClause} OR ${prefixClause})` : exactClause;
+        const purgeBindings = [...namespaces, ...prefixes.map((p) => `${p}%`)];
         const countRows = db.exec(`SELECT
-         (SELECT COUNT(*) FROM memory_entries WHERE namespace IN (${placeholders})) AS purgeable,
-         (SELECT COUNT(*) FROM memory_entries WHERE namespace = 'tasklist') AS tasklistTotal`, namespaces);
+         (SELECT COUNT(*) FROM memory_entries WHERE ${purgeWhere}) AS purgeable,
+         (SELECT COUNT(*) FROM memory_entries WHERE namespace = 'tasklist') AS tasklistTotal`, purgeBindings);
         const counts = countRows[0]?.values?.[0] ?? [0, 0];
         const purgeable = Number(counts[0] ?? 0);
         const tasklistTotal = Number(counts[1] ?? 0);
         let purged = 0;
         if (purgeable > 0) {
-            db.run(`DELETE FROM memory_entries WHERE namespace IN (${placeholders})`, namespaces);
+            db.run(`DELETE FROM memory_entries WHERE ${purgeWhere}`, purgeBindings);
             purged = db.getRowsModified?.() ?? 0;
         }
         let trimmed = 0;

package/dist/src/cli/services/memory-db-integrity-repair.js

@@ -0,0 +1,119 @@
+/**
+ * TS bridge for `flo healer --fix -c memory-db-integrity` and any other
+ * caller that wants the tiered repair (REINDEX → VACUUM INTO → row-level
+ * salvage) implemented in {@link
+ * "../../../bin/lib/db-repair.mjs".repairMemoryDbIfCorrupt} but with the
+ * caller-side daemon coordination that the launcher path gets for free.
+ *
+ * The launcher (bin/session-start-launcher.mjs § 0c) runs the same repair
+ * at session start after the daemon is already stopped. A mid-session
+ * healer call needs to stop the daemon itself first — a live writer would
+ * race the atomic swap on Windows (EBUSY on `renameSync`) and leak
+ * corruption back through stale POSIX inodes elsewhere.
+ *
+ * Cross-platform notes:
+ *  - `process.kill(pid, 'SIGTERM')` maps to `TerminateProcess` on Windows
+ *    (Node maps every signal name to immediate termination on win32);
+ *    behaves like POSIX SIGTERM on Linux/macOS. Either way the daemon
+ *    exits before we touch the DB file.
+ *  - Path resolution uses `import.meta.url` so dist/ and bin/ stay
+ *    siblings whether moflo is running from a dogfood checkout or from a
+ *    consumer's `node_modules/moflo/` install.
+ *  - The MCP server (spawned by Claude Code per `.mcp.json`, not by moflo)
+ *    is out of our process tree and cannot be stopped here. We surface
+ *    explicit guidance to restart Claude Code in the caller's UX.
+ */
+import { existsSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getDaemonLockHolder, getDaemonLockPayload } from './daemon-lock.js';
+import { findMofloPackageRoot } from './moflo-require.js';
+async function loadJsDbRepairModule() {
+    // Resolve the JS module via the moflo package root walk so the path
+    // works identically in three contexts:
+    //   - Dogfood TS source (vitest): walks up from the .ts location to the
+    //     repo's package.json → joins `bin/lib/db-repair.mjs`
+    //   - Compiled dist (CLI runtime): walks up from dist/src/cli/services/
+    //     to package root → joins `bin/lib/db-repair.mjs`
+    //   - Consumer install: walks up from
+    //     node_modules/moflo/dist/src/cli/services/ to
+    //     node_modules/moflo/ → joins `bin/lib/db-repair.mjs`
+    // The previous `new URL('../../../../bin/lib/...', import.meta.url)` only
+    // worked in the dist context — source-tree depth is one level shallower
+    // so vitest hit "Cannot find module" on the wrong path.
+    const root = findMofloPackageRoot();
+    if (!root) {
+        throw new Error('moflo package root not found — cannot locate bin/lib/db-repair.mjs');
+    }
+    const repairPath = join(root, 'bin', 'lib', 'db-repair.mjs');
+    const repairUrl = pathToFileURL(repairPath).href;
+    return (await import(repairUrl));
+}
+/**
+ * Probe `.moflo/moflo.db` for corruption without WAL pragmas — the readonly
+ * raw-DatabaseSync open that bypasses the openBackend code path which itself
+ * throws on corrupt files (pre-#1090's silent-"healthy"-reporting bug).
+ *
+ * Single source of truth: delegates to {@link
+ * "../../../bin/lib/db-repair.mjs".probeIntegrityRaw}. Callers in the TS tree
+ * (currently `checkMemoryDbIntegrity` doctor check) should use this rather
+ * than re-deriving the readonly+no-PRAGMAs probe so the implementation
+ * stays in one place.
+ */
+export async function probeDbIntegrity(dbPath) {
+    const mod = await loadJsDbRepairModule();
+    return mod.probeIntegrityRaw(dbPath);
+}
+/**
+ * Send a SIGTERM-equivalent to the daemon PID and clear the lockfile.
+ * Returns true if a live daemon was actually stopped. Cross-platform:
+ * `process.kill` accepts the signal name on all platforms; Node treats it
+ * as an immediate terminate on Windows.
+ */
+function stopDaemon(projectRoot) {
+    const payload = getDaemonLockPayload(projectRoot);
+    if (!payload?.pid || payload.pid <= 0)
+        return false;
+    try {
+        process.kill(payload.pid, 'SIGTERM');
+    }
+    catch {
+        // ESRCH (already dead) or EPERM — treat both as "nothing to stop".
+        return false;
+    }
+    const lockFile = join(projectRoot, '.moflo', 'daemon.lock');
+    try {
+        if (existsSync(lockFile))
+            unlinkSync(lockFile);
+    }
+    catch { /* */ }
+    return true;
+}
+/**
+ * Run the tiered repair against the project's `.moflo/moflo.db`.
+ *
+ * Default behavior is to stop the daemon if alive (cross-platform via
+ * `process.kill('SIGTERM')`) so the atomic swap doesn't race a live writer.
+ * Pass `stopDaemonFirst: false` to suppress that — the launcher path uses
+ * this because its own daemon-stop already ran before § 0c.
+ *
+ * Never throws; any internal error surfaces as
+ * `{ repaired: false, errors: 0, persistent: true }`.
+ */
+export async function repairMemoryDbIntegrity(projectRoot = process.cwd(), options = {}) {
+    const root = resolve(projectRoot);
+    const stopFirst = options.stopDaemonFirst !== false;
+    let daemonStopped = false;
+    if (stopFirst && getDaemonLockHolder(root) !== null) {
+        daemonStopped = stopDaemon(root);
+    }
+    try {
+        const mod = await loadJsDbRepairModule();
+        const result = await mod.repairMemoryDbIfCorrupt(root);
+        return { ...result, daemonStopped };
+    }
+    catch {
+        return { repaired: false, errors: 0, persistent: true, daemonStopped };
+    }
+}
+//# sourceMappingURL=memory-db-integrity-repair.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.10.0';
+export const VERSION = '4.10.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.0",
+  "version": "4.10.1",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.37",
+    "moflo": "^4.10.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"