moflo 4.9.37 → 4.10.0

package/bin/lib/incremental-write.mjs

@@ -66,16 +66,30 @@ export function computeContentListHash(files) {
 }
 
 /**
- * Load `key → content` for every active row in the namespace.
+ * Load `key → content` for every active row in the namespace, optionally
+ * scoped to keys starting with `keyPrefix` (one doc's chunks at a time —
+ * lets per-file indexers like `index-guidance.mjs` content-diff without
+ * loading every chunk across every file).
+ *
  * @param {object} db - sql.js Database
  * @param {string} namespace
+ * @param {string} [keyPrefix] — when set, restricts the scan to `key LIKE '<prefix>%'`.
+ *   The same prefix scopes the orphan sweep in {@link applyIncrementalChunks}.
  * @returns {Map<string,string>}
  */
-export function loadExistingContent(db, namespace) {
-  const stmt = db.prepare(
-    `SELECT key, content FROM memory_entries WHERE namespace = ? AND status = 'active'`,
-  );
-  stmt.bind([namespace]);
+export function loadExistingContent(db, namespace, keyPrefix) {
+  const stmt = keyPrefix
+    ? db.prepare(
+        `SELECT key, content FROM memory_entries WHERE namespace = ? AND key LIKE ? AND status = 'active'`,
+      )
+    : db.prepare(
+        `SELECT key, content FROM memory_entries WHERE namespace = ? AND status = 'active'`,
+      );
+  if (keyPrefix) {
+    stmt.bind([namespace, `${keyPrefix}%`]);
+  } else {
+    stmt.bind([namespace]);
+  }
   const map = new Map();
   while (stmt.step()) {
     const row = stmt.getAsObject();
@@ -95,11 +109,17 @@ export function loadExistingContent(db, namespace) {
  * @param {object} [opts]
  * @param {boolean} [opts.serialize=true] - JSON.stringify metadata/tags before
  *   writing. Set false when callers already pass strings.
+ * @param {string} [opts.keyPrefix] — when set, the existing-content load AND
+ *   the orphan sweep are restricted to keys matching `<prefix>%`. Use this
+ *   when processing a single file's chunks at a time (e.g. index-guidance.mjs
+ *   iterates files independently) — without it the sweep would delete every
+ *   chunk from every OTHER file as an orphan on each call.
  * @returns {{inserted:number, updated:number, unchanged:number, removed:number}}
  */
 export function applyIncrementalChunks(db, namespace, chunks, opts = {}) {
   const serialize = opts.serialize !== false;
-  const existing = loadExistingContent(db, namespace);
+  const keyPrefix = opts.keyPrefix;
+  const existing = loadExistingContent(db, namespace, keyPrefix);
   const newKeys = new Set();
   let inserted = 0;
   let updated = 0;

package/bin/lib/moflo-paths.mjs

@@ -1,16 +1,19 @@
 /**
- * Pure-JS counterpart to src/cli/services/moflo-paths.ts.
+ * Pure-JS counterpart to src/cli/services/moflo-paths.ts and the
+ * findProjectRoot helper in src/cli/services/project-root.ts.
  *
  * Lives in bin/lib because session-start-launcher.mjs and other bin/ scripts
  * run before any TS compilation has happened — they can't import the .ts
- * source. The TS version is the canonical programmatic API; this version
- * exposes the same path constants + helpers.
+ * source. The TS versions are the canonical programmatic API; this file
+ * exposes the same path constants + helpers and MUST stay algorithmically
+ * identical (see tests/system/project-root-twin.test.ts).
  *
  * Per #851, the legacy `.claude-flow/` rename + `.swarm/memory.db` byte-copy
  * helpers no longer ship: the version-bump-gated cherry-pick lives entirely
  * in the launcher and the TS service `cli/services/cherry-pick-learnings.ts`.
  */
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
 
 export const MOFLO_DIR = '.moflo';
 export const MEMORY_DB_FILE = 'moflo.db';
@@ -57,3 +60,60 @@ export function memoryDbCandidatePaths(projectRoot) {
     join(projectRoot, '.claude', LEGACY_MEMORY_DB_FILE),
   ];
 }
+
+/**
+ * Resolve the project root the same way the TS bridge does. Every bin/
+ * script that touches `.moflo/moflo.db` (or any sibling state under
+ * `.moflo/`) MUST go through this so its writes land on the SAME file the
+ * bridge reads from.
+ *
+ * Algorithmic twin of `src/cli/services/project-root.ts:findProjectRoot()`
+ * and `src/cli/memory/bridge-core.ts:getProjectRoot()`. See those files for
+ * the canonical algorithm comment.
+ *
+ * @param {{ cwd?: string; honorEnv?: boolean }} [opts]
+ * @returns {string} absolute project root
+ */
+export function findProjectRoot(opts) {
+  const honorEnv = opts?.honorEnv !== false;
+  if (honorEnv && process.env.CLAUDE_PROJECT_DIR) {
+    return process.env.CLAUDE_PROJECT_DIR;
+  }
+  const startDir = opts?.cwd ?? process.cwd();
+  const start = resolve(startDir);
+  const fsRoot = parse(start).root;
+
+  // High-priority pass: memory markers + CLAUDE.md/package.json pair.
+  let dir = start;
+  while (dir !== fsRoot) {
+    if (basename(dir) === 'node_modules') {
+      dir = dirname(dir);
+      continue;
+    }
+    if (existsSync(join(dir, '.moflo', 'moflo.db'))) return dir;
+    if (existsSync(join(dir, '.swarm', 'memory.db'))) return dir;
+    if (existsSync(join(dir, 'CLAUDE.md')) && existsSync(join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Low-priority pass: bare package.json or .git.
+  dir = start;
+  while (dir !== fsRoot) {
+    if (basename(dir) === 'node_modules') {
+      dir = dirname(dir);
+      continue;
+    }
+    if (existsSync(join(dir, 'package.json')) || existsSync(join(dir, '.git'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return startDir;
+}

package/bin/lib/suppress-sqlite-warning.mjs

@@ -0,0 +1,57 @@
+/**
+ * Filter out Node's `(node:NNN) ExperimentalWarning: SQLite is an experimental
+ * feature and might change at any time` line that fires once per process the
+ * first time `node:sqlite` is loaded.
+ *
+ * Why we suppress: moflo committed to node:sqlite as the only backend in
+ * Phase 5 (#1084). The warning is informational from Node's perspective but
+ * actively harmful for us because:
+ *   1. It lands on stderr → the consumer-smoke harness's 200-char stderr
+ *      tails (`recordExit`) get filled with the warning prefix, hiding the
+ *      real failure message behind it (#1098 — `Memory Access Functional`
+ *      failures looked like ExperimentalWarning failures in CI logs).
+ *   2. It appears in every consumer's `flo doctor` / `flo memory init` /
+ *      `flo daemon start` invocation, polluting their terminal output for
+ *      something they can't act on.
+ *
+ * Implementation: replace `process.emitWarning` with a thin filter ONLY for
+ * the SQLite warning. Every other warning passes through unchanged — we
+ * specifically don't want to broadly mute `--no-warnings`-style suppression
+ * because that would also hide e.g. import-attributes ExperimentalWarning
+ * which IS something we'd want to know about.
+ *
+ * The filter is idempotent: re-importing the module is a no-op. Must run
+ * BEFORE the first `import 'node:sqlite'` anywhere in the process tree;
+ * called from `bin/cli.js`, `bin/lib/get-backend.mjs`, and the daemon-
+ * backend module loader.
+ *
+ * @module bin/lib/suppress-sqlite-warning
+ */
+
+const INSTALLED = Symbol.for('moflo.suppressSqliteWarning.installed');
+
+function shouldSuppress(message) {
+  if (typeof message === 'string') {
+    return message.includes('SQLite is an experimental feature');
+  }
+  if (message && typeof message === 'object') {
+    return typeof message.message === 'string' && message.message.includes('SQLite is an experimental feature');
+  }
+  return false;
+}
+
+if (!globalThis[INSTALLED]) {
+  globalThis[INSTALLED] = true;
+  const originalEmitWarning = process.emitWarning;
+  process.emitWarning = function (warning, ...args) {
+    // Two emit signatures: (message, type, code, ctor) and (message, options).
+    // Inspect both `warning` and `args[0]` (which is `type` in the legacy
+    // form or `options.type` in the new form) before deciding.
+    if (shouldSuppress(warning)) return;
+    const typeArg = typeof args[0] === 'string'
+      ? args[0]
+      : (args[0] && typeof args[0] === 'object' ? args[0].type : undefined);
+    if (typeArg === 'ExperimentalWarning' && typeof warning === 'string' && warning.includes('SQLite')) return;
+    return originalEmitWarning.apply(this, [warning, ...args]);
+  };
+}

package/bin/migrations/knowledge-purge.mjs

@@ -15,9 +15,9 @@
  * @module bin/migrations/knowledge-purge
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
+import { existsSync } from 'fs';
 import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
 import { hasMigrationRun } from '../lib/migrations.mjs';
 import { MIGRATED_FROM_KNOWLEDGE } from './lib/markers.mjs';
 
@@ -44,11 +44,10 @@ export async function run(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { purged: 0, skipped: 0 };
 
-  // Lazy-load sql.js — keeps the manifest-stamped no-op path off the WASM
-  // init cost (~30ms cold).
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  const db = new SQL.Database(readFileSync(dbPath));
+  // Lazy-load via the backend factory — keeps the manifest-stamped no-op
+  // path off the WASM init cost (~30ms cold). Engine selection lives in
+  // openBackend() (default: node:sqlite as of #1083 Phase 4).
+  const db = await openBackend(projectRoot, { create: false });
 
   const knowledgeStmt = db.prepare(
     `SELECT id, key, status FROM memory_entries
@@ -101,7 +100,7 @@ export async function run(projectRoot) {
     deleteStmt.free();
   }
 
-  if (purged > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  if (purged > 0) db.save();
   db.close();
   return { purged, skipped };
 }

package/bin/migrations/knowledge-to-learnings.mjs

@@ -10,11 +10,10 @@
  * @module bin/migrations/knowledge-to-learnings
  */
 
-import { existsSync, readFileSync } from 'fs';
-import { writeFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { randomBytes } from 'crypto';
-import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
 import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
 import { MIGRATED_FROM_KNOWLEDGE } from './lib/markers.mjs';
 
 export const name = 'knowledge-to-learnings';
@@ -45,11 +44,10 @@ export async function run(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { rowsMigrated: 0, rowsSkipped: 0 };
 
-  // Lazy-load sql.js — top-level await would pay ~30ms WASM init even on the
-  // no-op fast-path where the manifest already records this migration as done.
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  const db = new SQL.Database(readFileSync(dbPath));
+  // Lazy-load via the backend factory — top-level await would pay the engine
+  // init cost even on the no-op fast-path where the manifest already records
+  // this migration as done.
+  const db = await openBackend(projectRoot, { create: false });
 
   const sourceStmt = db.prepare(
     `SELECT id, key, content, type, metadata, tags, embedding, embedding_dimensions,
@@ -119,7 +117,7 @@ export async function run(projectRoot) {
     insertStmt.free();
   }
 
-  if (migrated > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  if (migrated > 0) db.save();
   db.close();
   return { rowsMigrated: migrated, rowsSkipped: skipped };
 }

package/bin/migrations/purge-doc-entries.mjs

@@ -9,9 +9,9 @@
  * @module bin/migrations/purge-doc-entries
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
+import { existsSync } from 'fs';
 import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
 
 export const name = 'purge-doc-entries';
 
@@ -23,11 +23,10 @@ export async function run(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { purged: 0 };
 
-  // Lazy-load sql.js — keeps the manifest-stamped no-op path off the WASM
-  // init cost (~30ms cold).
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  const db = new SQL.Database(readFileSync(dbPath));
+  // Lazy-load via the backend factory — keeps the manifest-stamped no-op
+  // path off the WASM init cost (~30ms cold). Engine selection lives in
+  // openBackend() (default: node:sqlite as of #1083 Phase 4).
+  const db = await openBackend(projectRoot, { create: false });
 
   // Scope: every namespace, since both `flo memory index-guidance` and
   // `bin/index-guidance.mjs` historically wrote doc-* across whatever
@@ -47,7 +46,7 @@ export async function run(projectRoot) {
   db.run(`DELETE FROM memory_entries WHERE key LIKE 'doc-%'`);
   const purged = db.getRowsModified?.() ?? beforeCount;
 
-  if (purged > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  if (purged > 0) db.save();
   db.close();
   return { purged };
 }

package/bin/migrations/strip-context-preambles.mjs

@@ -16,9 +16,9 @@
  * @module bin/migrations/strip-context-preambles
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
+import { existsSync } from 'fs';
 import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
 
 export const name = 'strip-context-preambles';
 // Run after purge-doc-entries (which itself has order=0 default). Explicit
@@ -47,9 +47,7 @@ export async function run(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { stripped: 0, untouched: 0 };
 
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  const db = new SQL.Database(readFileSync(dbPath));
+  const db = await openBackend(projectRoot, { create: false });
 
   // Only chunks can carry the preamble — the chunker is the only writer of
   // those markers. Filter on key prefix to keep the LIKE selective; manual
@@ -91,7 +89,7 @@ export async function run(projectRoot) {
     update.free();
   }
 
-  if (stripped > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  if (stripped > 0) db.save();
   db.close();
   return { stripped, untouched };
 }

package/bin/run-migrations.mjs

@@ -23,19 +23,10 @@ import { existsSync, readdirSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { hasMigrationRun, markMigrationDone, listMigrations, clearMigration } from './lib/migrations.mjs';
+import { findProjectRoot } from './lib/moflo-paths.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 const args = process.argv.slice(2);
 const verbose = args.includes('--verbose') || args.includes('-v');

package/bin/semantic-search.mjs

@@ -17,23 +17,12 @@
  *   flo-search "query" --threshold 0.3
  */
 
-import { existsSync, readFileSync } from 'fs';
-import { resolve, dirname } from 'path';
-import { mofloResolveURL, mofloInternalURL } from './lib/moflo-resolve.mjs';
-import { memoryDbPath } from './lib/moflo-paths.mjs';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
+import { existsSync } from 'fs';
+import { mofloInternalURL } from './lib/moflo-resolve.mjs';
+import { memoryDbPath, findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
 const FASTEMBED_INLINE = 'dist/src/cli/embeddings/fastembed-inline/index.js';
 
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 const DB_PATH = memoryDbPath(projectRoot);
 
@@ -108,9 +97,9 @@ async function getDb() {
   if (!existsSync(DB_PATH)) {
     throw new Error(`Database not found: ${DB_PATH}`);
   }
-  const SQL = await initSqlJs();
-  const buffer = readFileSync(DB_PATH);
-  return new SQL.Database(buffer);
+  // Read-only: search must never trigger WAL creation in a freshly-cloned
+  // consumer repo, and the factory guarantees the same shape across engines.
+  return openBackend(projectRoot, { create: false, readOnly: true });
 }
 
 async function semanticSearch(queryText, options = {}) {

package/bin/session-start-launcher.mjs

@@ -11,7 +11,7 @@ import { spawn, execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
-import { mofloDir } from './lib/moflo-paths.mjs';
+import { mofloDir, findProjectRoot } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { applyRetiredPrune } from './lib/retired-files.mjs';
@@ -39,20 +39,13 @@ function sessionStartMirrorHeader(file) {
   return `${SESSION_START_MIRROR_MARKER} Do not edit — changes will be overwritten. -->\n<!-- Source: node_modules/moflo/.claude/guidance/shipped/${file} -->\n\n`;
 }
 
-// Detect project root by walking up from cwd to find package.json.
 // IMPORTANT: Do NOT use resolve(__dirname, '..') or '../..' — this script lives
 // in bin/ during development but gets synced to .claude/scripts/ in consumer
-// projects, so __dirname-relative paths break. findProjectRoot() works everywhere.
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
+// projects, so __dirname-relative paths break. findProjectRoot() (lib/moflo-
+// paths.mjs) resolves identically to the TS bridge (#1057): CLAUDE_PROJECT_DIR
+// first, then walk up for .moflo/moflo.db / .swarm/memory.db / CLAUDE.md+pkg /
+// package.json / .git. Inline walks here have caused N writers to land on
+// different DBs than the bridge reads from — never reintroduce one.
 const projectRoot = findProjectRoot();
 
 // Dogfood guard (#928). When this launcher runs inside the moflo repo itself,
@@ -884,37 +877,42 @@ try {
 // longer exists in source, calling a require helper that prints the warning
 // every time `neural_predict` / `neural_patterns` fires.
 //
-// Fix: compare the daemon-lock's `startedAt` against `node_modules/moflo/`'s
-// install mtime. If the daemon predates the current install, recycle it. The
-// install mtime is a stable proxy because npm rewrites the package.json on
-// every `npm install`, even when the resolved version is unchanged.
+// Fix (epic #1054): compare the daemon-lock's reported moflo `version` against
+// the installed `node_modules/moflo/package.json` version. If they differ —
+// or the lock predates #1054 and has no `version` field at all — recycle the
+// daemon. This is exact (not a heuristic margin like the prior mtime-based
+// check) and named explicitly so the doctor's Daemon Version Skew check
+// (#1059) can share the diagnosis.
 //
-// Margin absorbs clock skew between npm's mtime write and the daemon-lock
-// `startedAt` clock — within this window the daemon is likely the post-install
-// daemon, not a stale predecessor.
-const STALE_DAEMON_MTIME_SKEW_MS = 5_000;
+// Pre-#1054 daemons have no `version` in their lock payload — treated as a
+// mismatch by definition because by construction they were launched before
+// version publishing existed.
 try {
   const mofloPkgPathForRecycle = resolve(projectRoot, 'node_modules/moflo/package.json');
   const lockFile = resolve(projectRoot, '.moflo', 'daemon.lock');
-  // Cheap stat first — if the daemon-lock or package.json is gone we're done.
-  // statSync throws ENOENT on a missing file; the outer catch absorbs it.
-  const installedAt = statSync(mofloPkgPathForRecycle).mtimeMs;
-  const lockMtime = statSync(lockFile).mtimeMs;
-  // Quick reject: if the lock file itself is younger than the install, the
-  // daemon was started after install — no read of lock contents needed.
-  if (installedAt - lockMtime > STALE_DAEMON_MTIME_SKEW_MS) {
-    let daemonStartedAt = 0;
+  // Cheap stat first — if either file is gone, no skew check is possible.
+  if (existsSync(mofloPkgPathForRecycle) && existsSync(lockFile)) {
+    const installedVersion = JSON.parse(readFileSync(mofloPkgPathForRecycle, 'utf-8')).version;
+    let daemonVersion;
     try {
       const lock = JSON.parse(readFileSync(lockFile, 'utf-8'));
-      if (typeof lock?.startedAt === 'number') daemonStartedAt = lock.startedAt;
-    } catch { /* corrupt lock — fall through, recycleDaemon will unlink it */ }
-    if (daemonStartedAt > 0 && (installedAt - daemonStartedAt) > STALE_DAEMON_MTIME_SKEW_MS) {
-      if (recycleDaemon(lockFile, 'daemon-stale-recycle')) {
-        emitMutation('recycled stale daemon', 'predates current install');
+      if (typeof lock?.version === 'string') daemonVersion = lock.version;
+    } catch { /* corrupt lock — recycleDaemon will unlink it */ }
+    if (daemonVersion !== installedVersion) {
+      if (recycleDaemon(lockFile, 'daemon-version-skew')) {
+        const observed = daemonVersion ?? '<pre-1054 / unknown>';
+        emitMutation(
+          'recycled stale daemon',
+          `version skew: installed ${installedVersion}, daemon ${observed}`,
+        );
       }
     }
   }
-} catch { /* non-fatal — best-effort stale-daemon detection */ }
+} catch (err) {
+  // Non-fatal; surface via emitWarning per feedback_no_layered_workarounds —
+  // no silent catch on the upgrade path (#854).
+  emitWarning(`daemon version-skew check failed: ${errMessage(err)}`);
+}
 
 // ── 3a. Auto-migrate settings.json (npx flo → node helpers, PATH setup) ────
 // Existing users may have stale settings.json with `npx flo` hooks that break
@@ -1490,6 +1488,75 @@ try {
   } catch { /* writing the failure itself must not throw */ }
 }
 
+// ── 3e-1057. Run unmet schema migrations BEFORE daemon spawn ────────────────
+// run-migrations.mjs walks `bin/migrations/*.mjs` and invokes each that has
+// not been recorded in `.moflo/migrations.json`. Each migration opens sql.js
+// directly and persists with atomicWriteFileSync. They MUST run before the
+// daemon spawns or the daemon's in-RAM snapshot races their on-disk writes
+// — the bug class S2 detects (#1056 version-skew kill) and S3 (#1057)
+// closes for good. Pre-#1057 this ran in Section 4 AFTER `hooks session-
+// start` fired off the daemon, which is exactly the race fixed here.
+//
+// Synchronous on purpose: blocking by ≤30s on a one-time migration is the
+// right trade vs. an inconsistent post-upgrade DB. The runner short-circuits
+// to a no-op when nothing is pending, so steady-state cost is just the node
+// startup + ESM graph (~80ms on a warm fs).
+const runMigrations = resolveMofloBin(projectRoot, null, 'run-migrations.mjs');
+if (runMigrations) {
+  runMigrationsAndAnnounce(runMigrations);
+}
+
+function runMigrationsAndAnnounce(runnerPath) {
+  let raw;
+  try {
+    raw = execFileSync('node', [runnerPath], {
+      cwd: projectRoot,
+      timeout: 30_000,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'inherit'],
+    });
+  } catch (err) {
+    // Migrations are best-effort — a failure here must never block session
+    // start. But silent swallowing hides hangs (30s timeout) and corrupted
+    // DBs from the user, so leave a stderr crumb.
+    process.stderr.write(`moflo: migration runner failed (${err.code || err.message}); will retry next session\n`);
+    return;
+  }
+
+  const labels = {
+    'knowledge-to-learnings': 'consolidated knowledge → learnings',
+    'knowledge-purge': 'removed legacy knowledge namespace rows',
+    'purge-doc-entries': 'pruned legacy doc-* rows (chunk-only RAG, #1053)',
+    'strip-context-preambles': 'stripped chunk preambles; embeddings will rebuild on next index pass (#1053)',
+  };
+
+  for (const line of raw.split(/\r?\n/)) {
+    const m = line.match(/^\[migrations\]\s+([\w-]+):\s+done\s+in\s+\d+ms\s*(.*)$/);
+    if (!m) continue;
+    const migrationName = m[1];
+    let parsed = null;
+    try { parsed = m[2] ? JSON.parse(m[2]) : null; } catch { parsed = null; }
+
+    // Silent fast-path: don't announce zero-work runs (no point telling the
+    // user the launcher did nothing). If every numeric detail field is 0,
+    // skip the emit. Stamped migrations don't even reach this loop because
+    // the runner short-circuits via the manifest.
+    if (parsed) {
+      const nums = Object.values(parsed).filter((v) => typeof v === 'number');
+      if (nums.length > 0 && nums.every((v) => v === 0)) continue;
+    }
+
+    let detail = '';
+    if (parsed) {
+      if (typeof parsed.purged === 'number') detail = `${parsed.purged} ${parsed.purged === 1 ? 'row' : 'rows'}`;
+      else if (typeof parsed.rowsMigrated === 'number') detail = `${parsed.rowsMigrated} ${parsed.rowsMigrated === 1 ? 'entry' : 'entries'}`;
+    }
+
+    const label = labels[migrationName] || `migration ${migrationName}`;
+    emitMutation(label, detail);
+  }
+}
+
 // ── 3f. Flip the upgrade notice to "completed" (#636, #738) ─────────────────
 // See the TTL rationale at the constants above for why we switch to a
 // short-TTL completed badge instead of clearing the file.
@@ -1569,73 +1636,6 @@ if (hooksScript) {
   fireAndForget('node', [hooksScript, 'session-start'], 'hooks session-start');
 }
 
-// Migration runner — consults `.moflo/migrations.json` and runs only
-// migrations that haven't been recorded. Fast-paths to a no-op when the
-// manifest is current; the runner module loads with lazy sql.js init in
-// each migration, so a stamped session pays only node startup + ESM graph.
-//
-// Prefer the npm-package path so first-install consumers run unmet
-// migrations without waiting for a script-sync round-trip.
-//
-// Run synchronously (capture stdout) so each completed migration surfaces
-// through emitMutation — Claude's session-start hook captures launcher
-// stdout and that's the only channel that reaches the user.
-const runMigrations = resolveMofloBin(projectRoot, null, 'run-migrations.mjs');
-if (runMigrations) {
-  runMigrationsAndAnnounce(runMigrations);
-}
-
-function runMigrationsAndAnnounce(runnerPath) {
-  let raw;
-  try {
-    raw = execFileSync('node', [runnerPath], {
-      cwd: projectRoot,
-      timeout: 30_000,
-      encoding: 'utf-8',
-      stdio: ['ignore', 'pipe', 'inherit'],
-    });
-  } catch (err) {
-    // Migrations are best-effort — a failure here must never block session
-    // start. But silent swallowing hides hangs (30s timeout) and corrupted
-    // DBs from the user, so leave a stderr crumb.
-    process.stderr.write(`moflo: migration runner failed (${err.code || err.message}); will retry next session\n`);
-    return;
-  }
-
-  const labels = {
-    'knowledge-to-learnings': 'consolidated knowledge → learnings',
-    'knowledge-purge': 'removed legacy knowledge namespace rows',
-    'purge-doc-entries': 'pruned legacy doc-* rows (chunk-only RAG, #1053)',
-    'strip-context-preambles': 'stripped chunk preambles; embeddings will rebuild on next index pass (#1053)',
-  };
-
-  for (const line of raw.split('\n')) {
-    const m = line.match(/^\[migrations\]\s+([\w-]+):\s+done\s+in\s+\d+ms\s*(.*)$/);
-    if (!m) continue;
-    const migrationName = m[1];
-    let parsed = null;
-    try { parsed = m[2] ? JSON.parse(m[2]) : null; } catch { parsed = null; }
-
-    // Silent fast-path: don't announce zero-work runs (no point telling the
-    // user the launcher did nothing). If every numeric detail field is 0,
-    // skip the emit. Stamped migrations don't even reach this loop because
-    // the runner short-circuits via the manifest.
-    if (parsed) {
-      const nums = Object.values(parsed).filter((v) => typeof v === 'number');
-      if (nums.length > 0 && nums.every((v) => v === 0)) continue;
-    }
-
-    let detail = '';
-    if (parsed) {
-      if (typeof parsed.purged === 'number') detail = `${parsed.purged} ${parsed.purged === 1 ? 'row' : 'rows'}`;
-      else if (typeof parsed.rowsMigrated === 'number') detail = `${parsed.rowsMigrated} ${parsed.rowsMigrated === 1 ? 'entry' : 'entries'}`;
-    }
-
-    const label = labels[migrationName] || `migration ${migrationName}`;
-    emitMutation(label, detail);
-  }
-}
-
 // Patches are now baked into moflo@4.0.0 source — no runtime patching needed.
 
 // ── 5. Done — exit immediately ──────────────────────────────────────────────