moflo 4.9.1 → 4.9.2

package/bin/lib/moflo-paths.mjs

@@ -1,29 +1,16 @@
 /**
- * Pure-JS counterpart to src/cli/services/moflo-paths.ts (#699, #727).
+ * Pure-JS counterpart to src/cli/services/moflo-paths.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
- * mirrors the same algorithm so migration also runs from the consumer
- * launcher path. Algorithm parity is enforced by the parity case in
- * src/cli/__tests__/services/moflo-paths-migration.test.ts.
+ * exposes the same path constants + helpers.
+ *
+ * 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 {
-  closeSync,
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  readSync,
-  readdirSync,
-  renameSync,
-  rmdirSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 
 export const MOFLO_DIR = '.moflo';
 export const MEMORY_DB_FILE = 'moflo.db';
@@ -70,199 +57,3 @@ export function memoryDbCandidatePaths(projectRoot) {
     join(projectRoot, '.claude', LEGACY_MEMORY_DB_FILE),
   ];
 }
-
-/**
- * One-time migration of `.claude-flow/` → `.moflo/`. Idempotent — safe to call
- * on every session start. See moflo-paths.ts for the full contract.
- *
- * Returns `{ migrated, reason?, movedCount?, collisions? }`. The launcher
- * uses `movedCount` for the "migrated N files" message and `collisions` to
- * warn about subdirs (e.g. models/) that exist in both locations.
- */
-export function migrateClaudeFlowToMoflo(projectRoot) {
-  const legacy = legacyClaudeFlowDir(projectRoot);
-  const target = mofloDir(projectRoot);
-
-  if (!existsSync(legacy)) return { migrated: false, reason: 'no-legacy' };
-
-  if (!existsSync(target)) {
-    let movedCount = 0;
-    try { movedCount = readdirSync(legacy).length; } catch { /* count is cosmetic */ }
-    renameSync(legacy, target);
-    rewriteEmbeddingsModelPath(projectRoot);
-    return { migrated: true, movedCount };
-  }
-
-  let entries;
-  try {
-    entries = readdirSync(legacy);
-  } catch {
-    return { migrated: false, reason: 'legacy-unreadable' };
-  }
-
-  let moved = 0;
-  let modelsMoved = false;
-  const collisions = [];
-  for (const name of entries) {
-    const dst = join(target, name);
-    if (existsSync(dst)) {
-      collisions.push(name);
-      continue;
-    }
-    try {
-      renameSync(join(legacy, name), dst);
-      moved++;
-      if (name === 'models') modelsMoved = true;
-    } catch {
-      // Best-effort — single failed move shouldn't abort the rest.
-    }
-  }
-
-  try {
-    if (readdirSync(legacy).length === 0) rmdirSync(legacy);
-  } catch {
-    // Non-fatal — leftover legacy dir means migration runs next time.
-  }
-
-  if (modelsMoved) rewriteEmbeddingsModelPath(projectRoot);
-
-  if (moved === 0) {
-    return { migrated: false, reason: 'merged-nothing', movedCount: 0, collisions };
-  }
-  return { migrated: true, movedCount: moved, collisions };
-}
-
-/**
- * Rewrite `.moflo/embeddings.json:modelPath` if it still references the
- * legacy `.claude-flow/` location (#735). Best-effort: file-not-present,
- * malformed JSON, missing field, or already-correct path → silent no-op.
- * Mirrors the TS twin in src/cli/services/moflo-paths.ts. Uses tmp+rename
- * so SIGINT mid-flush can't leave embeddings.json truncated.
- */
-export function rewriteEmbeddingsModelPath(projectRoot) {
-  const cfgPath = join(projectRoot, MOFLO_DIR, 'embeddings.json');
-
-  let raw;
-  try { raw = readFileSync(cfgPath, 'utf8'); } catch { return false; }
-
-  let cfg;
-  try { cfg = JSON.parse(raw); } catch { return false; }
-
-  if (typeof cfg.modelPath !== 'string') return false;
-  if (!cfg.modelPath.includes(LEGACY_CLAUDE_FLOW_DIR)) return false;
-
-  cfg.modelPath = cfg.modelPath.split(LEGACY_CLAUDE_FLOW_DIR).join(MOFLO_DIR);
-
-  const tmpPath = `${cfgPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
-  try {
-    writeFileSync(tmpPath, JSON.stringify(cfg, null, 2));
-    renameSync(tmpPath, cfgPath);
-    return true;
-  } catch {
-    try { unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
-    return false;
-  }
-}
-
-const SQLITE_MAGIC_HEADER = Buffer.from('SQLite format 3\0', 'utf8');
-
-function looksLikeSqliteFile(filePath) {
-  let fd = null;
-  try {
-    fd = openSync(filePath, 'r');
-    const buf = Buffer.alloc(SQLITE_MAGIC_HEADER.length);
-    const read = readSync(fd, buf, 0, buf.length, 0);
-    if (read < SQLITE_MAGIC_HEADER.length) return false;
-    return buf.equals(SQLITE_MAGIC_HEADER);
-  } catch {
-    return false;
-  } finally {
-    if (fd !== null) try { closeSync(fd); } catch { /* non-fatal */ }
-  }
-}
-
-function verifyByteEqual(srcPath, dstPath) {
-  try {
-    const srcStat = statSync(srcPath);
-    const dstStat = statSync(dstPath);
-    if (srcStat.size !== dstStat.size) return false;
-    const srcBuf = readFileSync(srcPath);
-    const dstBuf = readFileSync(dstPath);
-    return srcBuf.equals(dstBuf);
-  } catch {
-    return false;
-  }
-}
-
-function tryUnlink(filePath) {
-  try { unlinkSync(filePath); } catch { /* non-fatal */ }
-}
-
-function migrateHnswIndex(projectRoot) {
-  const src = legacyHnswIndexPath(projectRoot);
-  const dst = hnswIndexPath(projectRoot);
-
-  if (!existsSync(src)) return false;
-  if (existsSync(dst)) return false;
-
-  try {
-    mkdirSync(dirname(dst), { recursive: true });
-    copyFileSync(src, dst);
-  } catch {
-    tryUnlink(dst);
-    return false;
-  }
-
-  if (!verifyByteEqual(src, dst)) {
-    tryUnlink(dst);
-    return false;
-  }
-
-  tryUnlink(src);
-  return true;
-}
-
-/**
- * One-time relocation of memory DB from `.swarm/memory.db` → `.moflo/moflo.db`
- * (story #727). Idempotent. See moflo-paths.ts for the full contract and the
- * SQLite-header / byte-equal verification rationale.
- *
- * MUST run before any long-lived sql.js consumer (MCP server, daemon) opens
- * the DB — sql.js dumps the whole snapshot on every flush and would clobber
- * the relocated file. Launcher section 0b is the safe boundary.
- */
-export function migrateMemoryDbToMoflo(projectRoot) {
-  const target = memoryDbPath(projectRoot);
-  if (existsSync(target)) return { migrated: false, reason: 'target-exists' };
-
-  const source = legacyMemoryDbPath(projectRoot);
-  if (!existsSync(source)) return { migrated: false, reason: 'no-legacy' };
-
-  try {
-    mkdirSync(dirname(target), { recursive: true });
-  } catch {
-    return { migrated: false, reason: 'copy-failed' };
-  }
-
-  try {
-    copyFileSync(source, target);
-  } catch {
-    tryUnlink(target);
-    return { migrated: false, reason: 'copy-failed' };
-  }
-
-  if (!verifyByteEqual(source, target) || !looksLikeSqliteFile(target)) {
-    tryUnlink(target);
-    return { migrated: false, reason: 'verify-failed' };
-  }
-
-  const hnswMoved = migrateHnswIndex(projectRoot);
-
-  try {
-    renameSync(source, legacyMemoryDbBakPath(projectRoot));
-  } catch {
-    return { migrated: true, reason: 'rename-failed', hnswMoved };
-  }
-
-  return { migrated: true, hnswMoved };
-}

package/bin/session-start-launcher.mjs

@@ -11,7 +11,7 @@ import { spawn, execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync, readdirSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { migrateClaudeFlowToMoflo, migrateMemoryDbToMoflo, mofloDir } from './lib/moflo-paths.mjs';
+import { mofloDir } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -116,56 +116,21 @@ try {
   unlinkSync(join(mofloDir(projectRoot), 'upgrade-notice.json'));
 } catch { /* non-fatal — file usually doesn't exist */ }
 
-// ── 0. LEGACY state migration (#699, #735) ──────────────────────────────────
-// Consumers upgrading from older moflo builds (inherited from upstream Ruflo)
-// get a one-time auto-migration of LEGACY `.claude-flow/` → `.moflo/` so claim
-// files, models cache, metrics, and the version stamp survive the rename.
-// The migration helper is idempotent — see bin/lib/moflo-paths.mjs for the
-// algorithm.
+// ── 0. Legacy whole-DB / directory migrations have been retired (#851) ─────
+// LEGACY-V2: Pre-#851 the launcher renamed `.claude-flow/` → `.moflo/` and
+// byte-copied `.swarm/memory.db` → `.moflo/moflo.db` on every session start.
+// Both blocks ran silently against a daemon that was still holding the old
+// paths in memory, leaving consumers with ghost runtime files reappearing
+// in legacy dirs and a `.gitignore` deletion that exposed 30+ daemon-state
+// files for commit. See docs/moflo-4.9.1-upgrade-experience-2026-05-02.md
+// for the full UX failure report.
 //
-// Staged removal contract (#735):
-//   1. THIS release ships Phase 1 (writers redirected to `.moflo/`) + Phase 2 // LEGACY
-//      (this migration call moves stragglers + warns on collisions).
-//   2. The release AFTER Phase 1 is steady-state should hard-delete any
-//      remaining empty `.claude-flow/` directory — until then, the helper // LEGACY
-//      drops the dir naturally once everything's been moved.
-// LEGACY: every emit below stops firing once `.claude-flow/` is gone.
-try {
-  const cfMigration = migrateClaudeFlowToMoflo(projectRoot);
-  if (cfMigration?.migrated) {
-    const count = cfMigration.movedCount ?? 0;
-    emitMutation(`migrated ${plural(count, 'entry')} from legacy .claude-flow/`); // LEGACY
-  }
-  // Surface collisions so users notice that BOTH locations now hold the same
-  // subdir name (most often `models/` after a partial pre-#735 migration).
-  // Manual cleanup is needed — moflo refuses to silently choose.
-  if ((cfMigration?.collisions?.length ?? 0) > 0) {
-    const collisionMsg = 'kept legacy .claude-flow/ entries to avoid clobbering .moflo/'; // LEGACY
-    emitMutation(collisionMsg, `collisions: ${cfMigration.collisions.join(', ')}`);
-  }
-} catch {
-  // Non-fatal — anything left behind by the migration just means it runs
-  // again next session. Better to keep launching than to block on it.
-}
-
-// ── 0b. LEGACY memory DB relocation (#727) ──────────────────────────────────
-// Run BEFORE long-lived sql.js consumers (MCP server, daemon) — see the
-// `migrateMemoryDbToMoflo` JSDoc for the copy-verify-delete contract and
-// the sql.js write-back hazard.
-try {
-  const dbMigration = migrateMemoryDbToMoflo(projectRoot);
-  if (dbMigration?.migrated) {
-    const detail = dbMigration.hnswMoved
-      ? '.swarm/memory.db → .moflo/moflo.db (with hnsw.index)'
-      : '.swarm/memory.db → .moflo/moflo.db';
-    emitMutation('relocated memory db', detail);
-    if (dbMigration.reason === 'rename-failed') {
-      emitMutation('legacy .swarm/memory.db remains', 'rename to .bak failed — flo doctor will warn');
-    }
-  }
-} catch {
-  // Non-fatal — failed migration leaves both DBs in place; next session retries.
-}
+// The version-bump-gated cherry-pick now lives inside section 3 (which is
+// already the gate on the `.moflo/moflo-version` stamp). It stops the daemon
+// first, then `INSERT OR IGNORE`s only the user-authored `learnings` /
+// `knowledge` namespaces — every other DB row is derived and rebuilds via
+// the indexers. LEGACY-V2 directories (`.swarm/`, `.claude-flow/`) are left
+// in place as recovery sources; users delete them at their leisure.
 
 // ── 0c. Memory DB index repair (#743) ───────────────────────────────────────
 // The .moflo/moflo.db SQLite file accumulates index corruption ("row N missing
@@ -215,16 +180,14 @@ function fireAndForget(cmd, args, label) {
   }
 }
 
-// Stop the daemon recorded in `lockFile` (if any) and start a fresh one. Used
-// from two recycle paths in this launcher: (a) the version-bump branch when
-// installed moflo just changed, and (b) the stale-daemon branch when the
-// running daemon predates the current install by a meaningful margin.
+// Stop the daemon recorded in `lockFile` (if any) without restarting. Used by
+// the upgrade flow before any DB work — the daemon must not be holding old
+// path resolution in memory, and a concurrent sql.js flush would clobber the
+// cherry-picked rows. Returns true when a live PID was actually killed.
 //
-// Reads the lock, SIGTERMs the recorded PID, removes the lock, and fires a
-// `daemon start --quiet` against `node_modules/moflo/bin/cli.js`. Every
-// failure mode (no lock, dead PID, missing CLI) is silently absorbed — the
-// recycle is best-effort and must never block session start.
-function recycleDaemon(lockFile, label) {
+// Section 4's `hooks.mjs session-start` spawn is responsible for starting a
+// fresh daemon under the current code; this function intentionally does not.
+function stopDaemon(lockFile) {
   if (!existsSync(lockFile)) return false;
   let stalePid = null;
   try {
@@ -235,16 +198,20 @@ function recycleDaemon(lockFile, label) {
     try { process.kill(stalePid, 'SIGTERM'); } catch { /* already dead */ }
   }
   try { unlinkSync(lockFile); } catch { /* non-fatal */ }
-  // Respawn only if a live daemon was actually recorded — no point starting
-  // one when there wasn't one before.
-  if (stalePid !== null) {
-    const localCliPath = resolve(projectRoot, 'node_modules/moflo/bin/cli.js');
-    if (existsSync(localCliPath)) {
-      fireAndForget('node', [localCliPath, 'daemon', 'start', '--quiet'], label);
-    }
-    return true;
+  return stalePid !== null;
+}
+
+// Stop-and-restart helper for the stale-daemon branch (section 3a-pre). The
+// version-bump branch uses stopDaemon directly + relies on section 4 for the
+// fresh start.
+function recycleDaemon(lockFile, label) {
+  const stopped = stopDaemon(lockFile);
+  if (!stopped) return false;
+  const localCliPath = resolve(projectRoot, 'node_modules/moflo/bin/cli.js');
+  if (existsSync(localCliPath)) {
+    fireAndForget('node', [localCliPath, 'daemon', 'start', '--quiet'], label);
   }
-  return false;
+  return true;
 }
 
 // ── 2. Reset workflow state for new session ──────────────────────────────────
@@ -326,6 +293,63 @@ try {
       // migration). See #738 — section 3f flips this to a 2-min "completed"
       // badge once work finishes (TTL rationale at the constants above).
       writeUpgradeNotice('in-progress');
+
+      // Stop the daemon BEFORE any DB writes (#851). It was started under the
+      // previous moflo image and holds old path resolution + module cache in
+      // memory; a concurrent sql.js flush would clobber the cherry-picked
+      // rows below, and old-path writes would resurrect ghost files in legacy
+      // dirs. Section 4's `hooks.mjs session-start` spawns a fresh daemon
+      // under the current code once 3g writes the version stamp.
+      const upgradeDaemonLock = resolve(projectRoot, '.moflo', 'daemon.lock');
+      if (stopDaemon(upgradeDaemonLock)) {
+        emitMutation('stopped daemon for upgrade', 'will restart fresh after upgrade work');
+      }
+
+      // Cherry-pick durable rows from any legacy DBs (#851). Replaces the
+      // pre-#851 full-DB byte-copy migration. The service is idempotent
+      // (INSERT OR IGNORE on UNIQUE(namespace, key)) so an aborted launcher
+      // re-runs cleanly without duplicate rows. Sources are read-only —
+      // .swarm/memory.db is preserved as a recovery source.
+      try {
+        const cherryPickPaths = [
+          resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/cherry-pick-learnings.js'),
+          resolve(projectRoot, 'dist/src/cli/services/cherry-pick-learnings.js'),
+        ];
+        const cherryPickPath = cherryPickPaths.find((p) => existsSync(p));
+        if (cherryPickPath) {
+          const mod = await import(`file://${cherryPickPath.replace(/\\/g, '/')}`);
+          if (typeof mod.cherryPickLearningsFromLegacy === 'function') {
+            const result = await mod.cherryPickLearningsFromLegacy({ projectRoot });
+            if (result.copied > 0) {
+              emitMutation(
+                'copied learnings forward',
+                `${plural(result.copied, 'learning/knowledge entry')} cherry-picked from legacy db`,
+              );
+            }
+            // LEGACY-V2: One-time hint that legacy dirs are recoverable.
+            // Only emit when the user actually has legacy state — silent
+            // fast-path for fresh installs and consumers who already cleaned
+            // up. The legacy dirs are intentionally never auto-deleted; they
+            // exist as recovery sources for the cherry-pick (#851).
+            const hasLegacy =
+              existsSync(resolve(projectRoot, '.swarm', 'memory.db')) || // LEGACY-V2
+              existsSync(resolve(projectRoot, '.swarm', 'memory.db.bak')) || // LEGACY-V2
+              existsSync(resolve(projectRoot, '.claude-flow')); // LEGACY-V2
+            if (hasLegacy) {
+              emitMutation(
+                'legacy .swarm/ + .claude-flow/ left in place', // LEGACY-V2
+                'safe to delete — derived data rebuilds on demand',
+              );
+            }
+          }
+        }
+      } catch (err) {
+        try {
+          const msg = err && err.message ? err.message : String(err);
+          process.stderr.write(`cherry-pick learnings skipped: ${msg}\n`);
+        } catch { /* stderr write must not throw */ }
+      }
+
       const binDir = resolve(projectRoot, 'node_modules/moflo/bin');
 
       // ── Manifest-based auto-update ──────────────────────────────────────
@@ -480,21 +504,10 @@ try {
         emitMutation('cleaned up retired files', `${removedFiles} removed`);
       }
 
-      // Recycle the running daemon — its in-process module cache holds the
-      // previous moflo image. After an upgrade that cache is stale, which
-      // shows up as warnings from removed code paths (e.g. the
-      // `[neural-tools] @moflo/embeddings not resolvable` spam from #639,
-      // emitted by pre-#592 collapse code that no longer exists in source)
-      // and means freshly-disabled workers keep running.
-      //
-      // `daemon.autoStart` only governs the cold-start case (no daemon
-      // existed); here a daemon was actually running, so replacing it with a
-      // current-code copy is the desired behaviour regardless of that flag.
-      try {
-        if (recycleDaemon(resolve(projectRoot, '.moflo', 'daemon.lock'), 'daemon-recycle')) {
-          emitMutation('recycled daemon', 'load fresh moflo code');
-        }
-      } catch { /* non-fatal — daemon recycle is best-effort */ }
+      // The daemon was already stopped above so the lock file is gone and
+      // there's no live PID to recycle here. Section 4's `hooks.mjs
+      // session-start` will spawn a fresh daemon under the current moflo
+      // image once 3g writes the version stamp.
 
       // Manifest reflects synced files immediately; version stamp is deferred
       // to 3g so an aborted launcher re-runs upgrade detection (#730).

package/dist/src/cli/commands/memory.js

@@ -2582,11 +2582,68 @@ const refreshCommand = {
         return { success: true };
     },
 };
+// Manual recovery for legacy DBs the launcher's auto cherry-pick can't reach
+// — schema mismatches that made the auto-run skip, an even older legacy DB
+// the candidate list doesn't include, or a friend's exported DB.
+const restoreLearningsCommand = {
+    name: 'restore-learnings',
+    description: 'Cherry-pick learnings/knowledge entries from a legacy DB into .moflo/moflo.db',
+    options: [
+        {
+            name: 'from',
+            description: 'Path to the legacy DB to read from (e.g. .swarm/memory.db)',
+            type: 'string',
+            required: true,
+        },
+    ],
+    examples: [
+        { command: 'flo memory restore-learnings --from .swarm/memory.db', description: 'Recover from a legacy memory DB' },
+        { command: 'flo memory restore-learnings --from .swarm/memory.db.bak', description: 'Recover from a post-upgrade .bak' },
+    ],
+    action: async (ctx) => {
+        const from = ctx.flags.from;
+        if (!from) {
+            output.printError('Source DB path is required. Use --from <path>');
+            return { success: false, exitCode: 1 };
+        }
+        const sourcePath = pathModule.resolve(from);
+        if (!fs.existsSync(sourcePath)) {
+            output.printError(`Source DB not found: ${sourcePath}`);
+            return { success: false, exitCode: 1 };
+        }
+        try {
+            const { cherryPickLearningsFromLegacy, CHERRY_PICK_SKIP_REASONS } = await import('../services/cherry-pick-learnings.js');
+            const result = await cherryPickLearningsFromLegacy({
+                projectRoot: process.cwd(),
+                legacyPaths: [sourcePath],
+            });
+            const report = result.sources[0];
+            if (report?.reason === CHERRY_PICK_SKIP_REASONS.SCHEMA_MISMATCH) {
+                output.printWarning(`Source DB has no memory_entries table — nothing to copy: ${sourcePath}`);
+                return { success: true, data: result };
+            }
+            if (report?.reason === CHERRY_PICK_SKIP_REASONS.OPEN_FAILED) {
+                output.printError(`Could not open source DB: ${sourcePath}`);
+                return { success: false, exitCode: 1, data: result };
+            }
+            output.printSuccess(`Cherry-picked ${result.copied} of ${result.considered} learning/knowledge entries from ${sourcePath}`);
+            if (result.copied < result.considered) {
+                output.printInfo(`${result.considered - result.copied} duplicate row${result.considered - result.copied === 1 ? '' : 's'} skipped (INSERT OR IGNORE)`);
+            }
+            output.printInfo(`Target: ${result.target}`);
+            return { success: true, data: result };
+        }
+        catch (error) {
+            output.printError(`restore-learnings failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return { success: false, exitCode: 1 };
+        }
+    },
+};
 // Main memory command
 export const memoryCommand = {
     name: 'memory',
     description: 'Memory management commands',
-    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, indexGuidanceCommand, rebuildIndexCommand, codeMapCommand, refreshCommand],
+    subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, indexGuidanceCommand, rebuildIndexCommand, codeMapCommand, refreshCommand, restoreLearningsCommand],
     options: [],
     examples: [
         { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },
@@ -2616,7 +2673,8 @@ export const memoryCommand = {
             `${output.highlight('index-guidance')}  - Index .claude/guidance/ files with RAG segments`,
             `${output.highlight('rebuild-index')}   - Regenerate embeddings for memory entries`,
             `${output.highlight('code-map')}        - Generate structural code map`,
-            `${output.highlight('refresh')}         - Reindex all content, rebuild embeddings, cleanup, and vacuum`
+            `${output.highlight('refresh')}         - Reindex all content, rebuild embeddings, cleanup, and vacuum`,
+            `${output.highlight('restore-learnings')} - Cherry-pick learnings/knowledge from a legacy DB`
         ]);
         return { success: true };
     }

package/dist/src/cli/services/cherry-pick-learnings.js

@@ -0,0 +1,209 @@
+/**
+ * Selective cherry-pick of durable memory rows on upgrade (#851).
+ *
+ * Replaces the full-DB byte-copy migration that epic #726 / story #727
+ * shipped (`migrateMemoryDbToMoflo`). That approach moved the entire 50+ MB
+ * of accumulated memory state across paths, then left the daemon writing to
+ * stale paths from its in-memory module cache. The user-visible result was
+ * "git went haywire" — see docs/moflo-4.9.1-upgrade-experience-2026-05-02.md.
+ *
+ * Almost all DB content is derived (code-map, embeddings, patterns, guidance
+ * chunks) and rebuilds on demand from the indexers. Only the `learnings`
+ * and `knowledge` namespaces are user-authored and worth carrying forward
+ * across upgrades. Everything else is regenerated cheaply.
+ *
+ * Algorithm:
+ *   1. Probe legacy DB candidates (`.swarm/memory.db.bak`, `.swarm/memory.db`,
+ *      etc.) read-only — sources are NEVER mutated.
+ *   2. Ensure the target `.moflo/moflo.db` exists with V3 schema (idempotent
+ *      `CREATE TABLE IF NOT EXISTS`).
+ *   3. `SELECT … WHERE namespace IN ('learnings', 'knowledge')` from each
+ *      legacy source.
+ *   4. `INSERT OR IGNORE INTO memory_entries` keyed on the existing
+ *      `UNIQUE(namespace, key)` constraint — duplicates skip silently, which
+ *      is what makes a re-run of an interrupted migration safe.
+ *   5. `atomicWriteFileSync` the target so a SIGINT mid-flush can't truncate.
+ *
+ * Caller (the launcher) is responsible for stopping the daemon before this
+ * runs — sql.js holds a full snapshot in memory and a concurrent flush from
+ * a stale daemon would clobber the cherry-picked rows.
+ *
+ * @module cli/services/cherry-pick-learnings
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as fs from 'fs';
+import * as path from 'path';
+import { mofloImport } from './moflo-require.js';
+import { atomicWriteFileSync } from './atomic-file-write.js';
+import { legacyMemoryDbBakPath, memoryDbCandidatePaths, memoryDbPath, } from './moflo-paths.js';
+import { MEMORY_SCHEMA_V3 } from '../memory/memory-initializer.js';
+/** Namespaces preserved across upgrades. Everything else is derived. */
+export const DURABLE_NAMESPACES = ['learnings', 'knowledge'];
+/**
+ * Reasons a single source contributed zero rows. Exported so callers can
+ * branch on the cause without duplicating string literals.
+ */
+export const CHERRY_PICK_SKIP_REASONS = {
+    OPEN_FAILED: 'open-failed',
+    SCHEMA_MISMATCH: 'schema-mismatch',
+    NO_ROWS: 'no-rows',
+    SELF_REFERENCE: 'self-reference',
+};
+/**
+ * Composed off `memoryDbCandidatePaths` so any future addition there
+ * (statusline, doctor, etc. all share that probe order) automatically
+ * extends the cherry-pick. The `.bak` path is added at highest priority
+ * because it's the post-#727 migration backup and ranks above the live
+ * legacy file. The canonical `.moflo/moflo.db` is dropped — the
+ * self-reference guard would skip it anyway, and including it would just
+ * confuse the report.
+ */
+function defaultLegacyCandidates(projectRoot) {
+    const canonical = memoryDbPath(projectRoot);
+    const tail = memoryDbCandidatePaths(projectRoot).filter((p) => p !== canonical);
+    return [legacyMemoryDbBakPath(projectRoot), ...tail];
+}
+/**
+ * Cherry-pick durable memory rows from any legacy DBs into `.moflo/moflo.db`.
+ *
+ * Returns a report — never throws on per-source failures. The caller (launcher)
+ * surfaces the count via `emitMutation`; a missing source / schema mismatch /
+ * locked file is recorded in `sources[].reason` and the upgrade continues.
+ *
+ * Hard failures (sql.js unavailable, target write failure) propagate so the
+ * launcher can choose to swallow + retry next session-start.
+ */
+export async function cherryPickLearningsFromLegacy(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const target = path.resolve(options.toPath ?? memoryDbPath(projectRoot));
+    const namespaces = options.namespaces ?? DURABLE_NAMESPACES;
+    const legacyPaths = (options.legacyPaths ?? defaultLegacyCandidates(projectRoot)).map((p) => path.resolve(p));
+    const result = {
+        copied: 0,
+        considered: 0,
+        sources: [],
+        target,
+    };
+    const initSqlJs = (await mofloImport('sql.js'))?.default;
+    if (!initSqlJs)
+        return result;
+    const SQL = (await initSqlJs());
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const targetExists = fs.existsSync(target);
+    const targetDb = targetExists
+        ? new SQL.Database(fs.readFileSync(target))
+        : new SQL.Database();
+    let insertStmt = null;
+    try {
+        targetDb.run(MEMORY_SCHEMA_V3);
+        const placeholders = namespaces.map(() => '?').join(',');
+        const selectSql = `SELECT id, key, namespace, content, type, embedding, embedding_model, ` +
+            `embedding_dimensions, tags, metadata, owner_id, created_at, updated_at, status ` +
+            `FROM memory_entries WHERE namespace IN (${placeholders})`;
+        // Hoisted prepare — avoids re-parsing the SQL inside sql.js for every
+        // INSERT. Matters for legacy DBs with hundreds of learnings rows.
+        insertStmt = targetDb.prepare(`INSERT OR IGNORE INTO memory_entries ` +
+            `(id, key, namespace, content, type, embedding, embedding_model, ` +
+            ` embedding_dimensions, tags, metadata, owner_id, created_at, updated_at, status) ` +
+            `VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const sourcePath of legacyPaths) {
+            if (sourcePath === target) {
+                result.sources.push({
+                    path: sourcePath,
+                    rowsRead: 0,
+                    rowsInserted: 0,
+                    reason: CHERRY_PICK_SKIP_REASONS.SELF_REFERENCE,
+                });
+                continue;
+            }
+            if (!fs.existsSync(sourcePath))
+                continue;
+            const report = readAndInsert(SQL, sourcePath, targetDb, insertStmt, selectSql, namespaces);
+            result.sources.push(report);
+            result.copied += report.rowsInserted;
+            result.considered += report.rowsRead;
+        }
+        // Skip the atomic write when there's nothing to persist:
+        //  - copied=0 + target didn't exist → don't materialize an empty DB
+        //    (the regular initializer creates it on first real write).
+        //  - copied=0 + target already existed → no diff, nothing to flush.
+        if (result.copied > 0) {
+            atomicWriteFileSync(target, Buffer.from(targetDb.export()));
+        }
+    }
+    finally {
+        if (insertStmt) {
+            try {
+                insertStmt.free();
+            }
+            catch { /* best-effort cleanup */ }
+        }
+        targetDb.close();
+    }
+    return result;
+}
+function readAndInsert(SQL, sourcePath, targetDb, insertStmt, selectSql, namespaces) {
+    let sourceDb;
+    try {
+        sourceDb = new SQL.Database(fs.readFileSync(sourcePath));
+    }
+    catch {
+        return {
+            path: sourcePath,
+            rowsRead: 0,
+            rowsInserted: 0,
+            reason: CHERRY_PICK_SKIP_REASONS.OPEN_FAILED,
+        };
+    }
+    try {
+        // Older / unrelated DBs may not have memory_entries.
+        const probe = sourceDb.exec(`SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries' LIMIT 1`);
+        if (!probe[0]?.values?.[0]) {
+            return {
+                path: sourcePath,
+                rowsRead: 0,
+                rowsInserted: 0,
+                reason: CHERRY_PICK_SKIP_REASONS.SCHEMA_MISMATCH,
+            };
+        }
+        let rowsRead = 0;
+        let rowsInserted = 0;
+        const selectStmt = sourceDb.prepare(selectSql);
+        selectStmt.bind(namespaces.slice());
+        while (selectStmt.step()) {
+            rowsRead++;
+            const row = selectStmt.getAsObject();
+            insertStmt.bind([
+                row.id,
+                row.key,
+                row.namespace,
+                row.content,
+                row.type ?? 'semantic',
+                row.embedding ?? null,
+                row.embedding_model ?? null,
+                row.embedding_dimensions ?? null,
+                row.tags ?? null,
+                row.metadata ?? null,
+                row.owner_id ?? null,
+                row.created_at ?? null,
+                row.updated_at ?? null,
+                row.status ?? 'active',
+            ]);
+            insertStmt.step();
+            if (targetDb.getRowsModified() > 0)
+                rowsInserted++;
+            insertStmt.reset();
+        }
+        selectStmt.free();
+        return {
+            path: sourcePath,
+            rowsRead,
+            rowsInserted,
+            reason: rowsRead === 0 ? CHERRY_PICK_SKIP_REASONS.NO_ROWS : undefined,
+        };
+    }
+    finally {
+        sourceDb.close();
+    }
+}
+//# sourceMappingURL=cherry-pick-learnings.js.map

package/dist/src/cli/services/moflo-paths.js

@@ -1,24 +1,25 @@
 /**
- * MoFlo runtime state directory constants + legacy migrations (#699, #727).
+ * MoFlo runtime state directory constants.
  *
  * MoFlo owns its state under `.moflo/` at the project root. The upstream Ruflo
- * fork used `.claude-flow/`; consumers upgrading from older moflo builds (which
- * inherited that path) get a one-time auto-migration so they don't lose claim
- * files, daemon state, metrics, etc.
+ * fork used `.claude-flow/`; both legacy locations are still recognized as
+ * read-only sources for the version-bump-gated cherry-pick (#851) but are
+ * never relocated or renamed automatically — leaving them in place gives
+ * consumers a recovery source and avoids the failure modes that motivated
+ * the issue (silent migrations, daemon-held stale paths, .gitignore deletion).
  *
  * Anything that touches a runtime state path under the project root must
  * compose it from `MOFLO_DIR`. Plain string literals like `'.moflo'` are
  * tolerated where a constant import is awkward (shell templates, tests) but
  * production code is checked by `published-package-drift-guard.test.ts`.
  *
- * The pure-JS twin at `bin/lib/moflo-paths.mjs` mirrors the algorithm so
- * `bin/session-start-launcher.mjs` can run the migration before any TS has
- * been compiled. The parity test in moflo-paths-migration.test.ts catches
- * algorithm divergence between the two.
+ * The pure-JS twin at `bin/lib/moflo-paths.mjs` mirrors these constants so
+ * `bin/session-start-launcher.mjs` can resolve paths before any TS is
+ * compiled. The cherry-pick logic itself lives in
+ * `cli/services/cherry-pick-learnings.ts` and is dynamically imported from
+ * the compiled `dist/` by the launcher.
  */
-import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmdirSync, statSync, unlinkSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { atomicWriteFileSync } from '../shared/utils/atomic-file-write.js';
+import { join } from 'node:path';
 export const MOFLO_DIR = '.moflo';
 /** Canonical memory DB filename (post-#727). Lives at `<root>/.moflo/moflo.db`. */
 export const MEMORY_DB_FILE = 'moflo.db';
@@ -77,249 +78,4 @@ export function memoryDbCandidatePaths(projectRoot) {
         join(projectRoot, '.claude', LEGACY_MEMORY_DB_FILE),
     ];
 }
-/**
- * One-time migration of `.claude-flow/` → `.moflo/`.
- *
- * - Legacy missing → no-op (the steady state after first run).
- * - Legacy present + target missing → atomic rename (preserves mtimes).
- * - Both present → merge: target wins on collision, leaving the colliding
- *   entry behind in legacy/ so the launcher can warn and a future run can
- *   retry. Drops the legacy dir if everything moved cleanly.
- *
- * When the models cache moves (legacy `.claude-flow/models/` lands at
- * `.moflo/models/`), `.moflo/embeddings.json:modelPath` is rewritten in the
- * same call so the next embedder run finds the relocated ONNX bytes instead
- * of re-downloading multi-MB binaries (#735).
- *
- * Idempotent and safe to call from session start.
- */
-export function migrateClaudeFlowToMoflo(projectRoot) {
-    const legacy = legacyClaudeFlowDir(projectRoot);
-    const target = mofloDir(projectRoot);
-    if (!existsSync(legacy))
-        return { migrated: false, reason: 'no-legacy' };
-    if (!existsSync(target)) {
-        // Wholesale rename — count what's about to move so the launcher can
-        // report `migrated N files` instead of opaque "migrated runtime state".
-        let movedCount = 0;
-        try {
-            movedCount = readdirSync(legacy).length;
-        }
-        catch { /* count is cosmetic */ }
-        renameSync(legacy, target);
-        rewriteEmbeddingsModelPath(projectRoot);
-        return { migrated: true, movedCount };
-    }
-    let entries;
-    try {
-        entries = readdirSync(legacy);
-    }
-    catch {
-        return { migrated: false, reason: 'legacy-unreadable' };
-    }
-    let moved = 0;
-    let modelsMoved = false;
-    const collisions = [];
-    for (const name of entries) {
-        const dst = join(target, name);
-        if (existsSync(dst)) {
-            collisions.push(name); // target wins — but the launcher must warn
-            continue;
-        }
-        try {
-            renameSync(join(legacy, name), dst);
-            moved++;
-            if (name === 'models')
-                modelsMoved = true;
-        }
-        catch {
-            // Best-effort merge — a failed move on one entry shouldn't abort the rest.
-        }
-    }
-    // Drop empty legacy dir so future runs short-circuit at existsSync(legacy).
-    try {
-        if (readdirSync(legacy).length === 0)
-            rmdirSync(legacy);
-    }
-    catch {
-        // Non-fatal — leftover legacy dir just means migration runs next time.
-    }
-    if (modelsMoved)
-        rewriteEmbeddingsModelPath(projectRoot);
-    if (moved === 0) {
-        return { migrated: false, reason: 'merged-nothing', movedCount: 0, collisions };
-    }
-    return { migrated: true, movedCount: moved, collisions };
-}
-/**
- * Rewrite `.moflo/embeddings.json:modelPath` if it still references the
- * legacy `.claude-flow/` location. Called after a models/ relocation so the
- * stale path doesn't force a multi-MB re-download (#735).
- *
- * Best-effort: file-not-present, malformed JSON, missing `modelPath`, or
- * already-correct path are all silent no-ops. Returns true only when the
- * file was actually rewritten. Uses atomicWriteFileSync so a SIGINT mid-flush
- * can't truncate embeddings.json and break every subsequent embedder run.
- */
-export function rewriteEmbeddingsModelPath(projectRoot) {
-    const cfgPath = join(projectRoot, MOFLO_DIR, 'embeddings.json');
-    let raw;
-    try {
-        raw = readFileSync(cfgPath, 'utf8');
-    }
-    catch {
-        return false;
-    }
-    let cfg;
-    try {
-        cfg = JSON.parse(raw);
-    }
-    catch {
-        return false;
-    }
-    if (typeof cfg.modelPath !== 'string')
-        return false;
-    if (!cfg.modelPath.includes(LEGACY_CLAUDE_FLOW_DIR))
-        return false;
-    // split-join handles every occurrence and works with both `/` and `\\`
-    // (escaped) forms in JSON-encoded Windows paths.
-    cfg.modelPath = cfg.modelPath.split(LEGACY_CLAUDE_FLOW_DIR).join(MOFLO_DIR);
-    try {
-        atomicWriteFileSync(cfgPath, JSON.stringify(cfg, null, 2));
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-const SQLITE_MAGIC_HEADER = Buffer.from('SQLite format 3\0', 'utf8');
-function looksLikeSqliteFile(filePath) {
-    let fd = null;
-    try {
-        fd = openSync(filePath, 'r');
-        const buf = Buffer.alloc(SQLITE_MAGIC_HEADER.length);
-        const read = readSync(fd, buf, 0, buf.length, 0);
-        if (read < SQLITE_MAGIC_HEADER.length)
-            return false;
-        return buf.equals(SQLITE_MAGIC_HEADER);
-    }
-    catch {
-        return false;
-    }
-    finally {
-        if (fd !== null)
-            try {
-                closeSync(fd);
-            }
-            catch { /* non-fatal */ }
-    }
-}
-function verifyByteEqual(srcPath, dstPath) {
-    try {
-        const srcStat = statSync(srcPath);
-        const dstStat = statSync(dstPath);
-        if (srcStat.size !== dstStat.size)
-            return false;
-        const srcBuf = readFileSync(srcPath);
-        const dstBuf = readFileSync(dstPath);
-        return srcBuf.equals(dstBuf);
-    }
-    catch {
-        return false;
-    }
-}
-function tryUnlink(filePath) {
-    try {
-        unlinkSync(filePath);
-    }
-    catch { /* non-fatal */ }
-}
-/**
- * Move `.swarm/hnsw.index` → `.moflo/hnsw.index` using the same
- * copy-verify-delete pattern as the DB. Returns true on success, false when
- * source absent or copy/verify failed (caller treats as best-effort).
- */
-function migrateHnswIndex(projectRoot) {
-    const src = legacyHnswIndexPath(projectRoot);
-    const dst = hnswIndexPath(projectRoot);
-    if (!existsSync(src))
-        return false;
-    if (existsSync(dst))
-        return false; // already there — leave both alone
-    try {
-        mkdirSync(dirname(dst), { recursive: true });
-        copyFileSync(src, dst);
-    }
-    catch {
-        tryUnlink(dst);
-        return false;
-    }
-    if (!verifyByteEqual(src, dst)) {
-        tryUnlink(dst);
-        return false;
-    }
-    tryUnlink(src); // sidecar can be regenerated; no .bak retention needed
-    return true;
-}
-/**
- * One-time relocation of the memory DB from the upstream `.swarm/memory.db`
- * layout to the canonical `.moflo/moflo.db` (story #727).
- *
- * Algorithm — copy-verify-delete, never `mv`:
- *   1. If `.moflo/moflo.db` exists → no-op (`target-exists`).
- *   2. If `.swarm/memory.db` absent → no-op (`no-legacy`).
- *   3. Ensure `.moflo/` exists.
- *   4. `copyFileSync(.swarm/memory.db, .moflo/moflo.db)`.
- *   5. Verify byte-equal (size + content) AND SQLite header magic.
- *   6. Move `.swarm/hnsw.index` → `.moflo/hnsw.index` (best-effort).
- *   7. Rename `.swarm/memory.db` → `.swarm/memory.db.bak` (kept one upgrade cycle).
- *
- * Any failure between 4–7 deletes the partial target and returns failure;
- * next session-start retries.
- *
- * MUST run BEFORE any long-lived consumer (MCP server, daemon) opens the DB —
- * sql.js holds a full snapshot in RAM and would clobber the relocated file
- * on its next flush. The launcher's section before the fire-and-forget block
- * is the safe boundary; see feedback memory `feedback_sqljs_writeback_clobber`.
- *
- * Idempotent.
- */
-export function migrateMemoryDbToMoflo(projectRoot) {
-    const target = memoryDbPath(projectRoot);
-    if (existsSync(target))
-        return { migrated: false, reason: 'target-exists' };
-    const source = legacyMemoryDbPath(projectRoot);
-    if (!existsSync(source))
-        return { migrated: false, reason: 'no-legacy' };
-    try {
-        mkdirSync(dirname(target), { recursive: true });
-    }
-    catch {
-        return { migrated: false, reason: 'copy-failed' };
-    }
-    try {
-        copyFileSync(source, target);
-    }
-    catch {
-        tryUnlink(target);
-        return { migrated: false, reason: 'copy-failed' };
-    }
-    if (!verifyByteEqual(source, target) || !looksLikeSqliteFile(target)) {
-        tryUnlink(target);
-        return { migrated: false, reason: 'verify-failed' };
-    }
-    const hnswMoved = migrateHnswIndex(projectRoot);
-    // Final step: retire the source by renaming to .bak. Only after the new
-    // file is verified — never lose data. If this rename fails we leave the
-    // source in place; a stale `.swarm/memory.db` next to a healthy
-    // `.moflo/moflo.db` is harmless (the bridge reads only the new path) and
-    // surfaces as a `flo doctor` warning.
-    try {
-        renameSync(source, legacyMemoryDbBakPath(projectRoot));
-    }
-    catch {
-        return { migrated: true, reason: 'rename-failed', hnswMoved };
-    }
-    return { migrated: true, hnswMoved };
-}
 //# sourceMappingURL=moflo-paths.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.9.1';
+export const VERSION = '4.9.2';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.1",
+  "version": "4.9.2",
   "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",
@@ -79,7 +79,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.0",
+    "moflo": "^4.9.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"