moflo 4.9.36 → 4.10.0

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

@@ -0,0 +1,95 @@
+/**
+ * Migration: strip the legacy `[Context from previous section:]` /
+ * `[Context from next section:]` preamble blocks from every existing chunk
+ * (#1053 S5). The chunker no longer writes them — they were a workaround for
+ * missing traversal, and once memory_get_neighbors is wired (S2),
+ * prevChunk/nextChunk metadata + a real call is the alternative path.
+ *
+ * For every chunk whose content carries a preamble marker:
+ *   1. Strip the preamble block(s) in place
+ *   2. NULL the embedding column so build-embeddings regenerates it from the
+ *      cleaned content on the next indexer pass
+ *
+ * Idempotent: chunks already in the new shape (no preamble markers) are
+ * untouched.
+ *
+ * @module bin/migrations/strip-context-preambles
+ */
+
+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
+// ordering keeps this independent of fs sort order.
+export const order = 20;
+
+// Validated against real chunks; the back-to-back `---` runs that earlier
+// drafts mishandled are absorbed by the trailing `(?:---\n\n)*` / leading
+// `(?:\n\n---)+` greediness.
+const PREV_PREAMBLE = /\[Context from previous section:\][\s\S]*?\n\n---\n\n(?:---\n\n)*/g;
+const NEXT_PREAMBLE = /(?:\n\n---)+\n\n\[Context from next section:\][\s\S]*$/g;
+
+function strip(content) {
+  // Reset lastIndex defensively — global regex state can leak across calls
+  // when reused on a hot path.
+  PREV_PREAMBLE.lastIndex = 0;
+  NEXT_PREAMBLE.lastIndex = 0;
+  return content.replace(PREV_PREAMBLE, '').replace(NEXT_PREAMBLE, '');
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{stripped:number, untouched:number}>}
+ */
+export async function run(projectRoot) {
+  const dbPath = memoryDbPath(projectRoot);
+  if (!existsSync(dbPath)) return { stripped: 0, untouched: 0 };
+
+  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
+  // memory entries containing the literal string are extremely unlikely and
+  // the strip is a no-op for them anyway.
+  const stmt = db.prepare(
+    `SELECT id, content FROM memory_entries WHERE key LIKE 'chunk-%' AND status = 'active'`,
+  );
+  const rows = [];
+  while (stmt.step()) rows.push(stmt.getAsObject());
+  stmt.free();
+
+  if (rows.length === 0) {
+    db.close();
+    return { stripped: 0, untouched: 0 };
+  }
+
+  let stripped = 0;
+  let untouched = 0;
+  const update = db.prepare(`UPDATE memory_entries SET content = ?, embedding = NULL WHERE id = ?`);
+  try {
+    for (const row of rows) {
+      const original = String(row.content || '');
+      // Cheap prefix-check to avoid running the regex on chunks that have no
+      // preamble — covers the common idempotent re-run case in O(1).
+      if (!original.includes('[Context from previous section:]') && !original.includes('[Context from next section:]')) {
+        untouched++;
+        continue;
+      }
+      const cleaned = strip(original);
+      if (cleaned === original) {
+        untouched++;
+        continue;
+      }
+      update.run([cleaned, row.id]);
+      stripped++;
+    }
+  } finally {
+    update.free();
+  }
+
+  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 = {}) {
@@ -164,6 +153,7 @@ async function semanticSearch(queryText, options = {}) {
         preview: entry.content.substring(0, 150).replace(/\n/g, ' '),
         type: metadata.type || 'unknown',
         parentDoc: metadata.parentDoc || null,
+        parentPath: metadata.parentPath || null,
         chunkTitle: metadata.chunkTitle || null,
       });
     } catch (err) {
@@ -262,7 +252,9 @@ async function main() {
     console.log(`  Key: ${top.key}`);
     console.log(`  Score: ${top.score.toFixed(4)}`);
     if (top.chunkTitle) console.log(`  Section: ${top.chunkTitle}`);
-    if (top.parentDoc) console.log(`  Parent: ${top.parentDoc}`);
+    // #1053 S4: doc-* retired — parentPath is the actionable source location.
+    if (top.parentPath) console.log(`  Parent: ${top.parentPath}`);
+    else if (top.parentDoc) console.log(`  Parent: ${top.parentDoc}`);
     console.log(`  Preview: ${top.preview}...`);
   } catch (err) {
     console.error(`[semantic-search] Error: ${err.message}`);

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,71 +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',
-  };
-
-  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 ──────────────────────────────────────────────

package/bin/simplify-classify.cjs

@@ -45,34 +45,55 @@ const SECURITY_PATHS = [
   /(?:^|[\\\/])\.claude[\\\/]helpers[\\\/]gate/i,
 ];
 
-function safeExec(cmd) {
-  try { return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }); }
-  catch { return ''; }
+function safeExec(cmd, opts) {
+  try {
+    return execSync(cmd, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      ...(opts && opts.cwd ? { cwd: opts.cwd } : {}),
+    });
+  } catch { return ''; }
 }
 
 // Detect the consumer's default branch. Hardcoding 'main' silently miscalibrates
 // classification on repos that use 'master', 'develop', etc. — empty diff →
 // TRIVIAL → gate stamps clean without any real review.
 let _cachedDefaultBranch = null;
-function detectDefaultBranch() {
-  if (_cachedDefaultBranch !== null) return _cachedDefaultBranch;
+function detectDefaultBranch(cwd) {
+  // Cache by cwd so tests probing multiple repos in-process don't return a
+  // single stale value; CLI use passes no cwd and benefits from the cache.
+  if (cwd === undefined && _cachedDefaultBranch !== null) return _cachedDefaultBranch;
+  const opts = cwd ? { cwd } : undefined;
 
   // Preferred: origin/HEAD points to whatever the remote considers default.
-  const symbolic = safeExec('git symbolic-ref --short refs/remotes/origin/HEAD').trim();
-  if (symbolic.startsWith('origin/')) return (_cachedDefaultBranch = symbolic.slice('origin/'.length));
+  const symbolic = safeExec('git symbolic-ref --short refs/remotes/origin/HEAD', opts).trim();
+  if (symbolic.startsWith('origin/')) {
+    const v = symbolic.slice('origin/'.length);
+    if (cwd === undefined) _cachedDefaultBranch = v;
+    return v;
+  }
 
   // Fallback: local init.defaultBranch (set by `git init -b <name>` or config).
-  const configured = safeExec('git config --get init.defaultBranch').trim();
-  if (configured) return (_cachedDefaultBranch = configured);
+  const configured = safeExec('git config --get init.defaultBranch', opts).trim();
+  if (configured) {
+    if (cwd === undefined) _cachedDefaultBranch = configured;
+    return configured;
+  }
 
   // Last resort: 'main' (most common modern default).
-  return (_cachedDefaultBranch = 'main');
+  if (cwd === undefined) _cachedDefaultBranch = 'main';
+  return 'main';
+}
+
+function _resetCacheForTest() {
+  _cachedDefaultBranch = null;
 }
 
-function readDiffFromGit(base) {
+function readDiffFromGit(base, cwd) {
+  const opts = cwd ? { cwd } : undefined;
   // Combined diff: committed-since-base + working-tree
-  const committed = safeExec(`git diff ${base}...HEAD`);
-  const working = safeExec('git diff HEAD');
+  const committed = safeExec(`git diff ${base}...HEAD`, opts);
+  const working = safeExec('git diff HEAD', opts);
   return committed + (working ? '\n' + working : '');
 }
 
@@ -206,9 +227,9 @@ function classifyDiff(diffText) {
   return decide(parseDiff(diffText));
 }
 
-function classifyFromGit(base) {
-  const resolved = base || detectDefaultBranch();
-  return classifyDiff(readDiffFromGit(resolved));
+function classifyFromGit(base, cwd) {
+  const resolved = base || detectDefaultBranch(cwd);
+  return classifyDiff(readDiffFromGit(resolved, cwd));
 }
 
 if (require.main === module) {
@@ -232,4 +253,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { parseDiff, decide, classifyDiff, classifyFromGit, detectDefaultBranch };
+module.exports = { parseDiff, decide, classifyDiff, classifyFromGit, detectDefaultBranch, _resetCacheForTest };

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

@@ -14,6 +14,32 @@ import { spawn, execFileSync } from 'child_process';
 import { join, resolve } from 'path';
 import * as fs from 'fs';
 import { errorDetail } from '../shared/utils/error-detail.js';
+/**
+ * Resolve the dashboard port from CLI flag and env, in that precedence order.
+ *
+ * Precedence (highest first):
+ *   1. `--dashboard-port` flag (explicit caller intent)
+ *   2. `MOFLO_DAEMON_PORT` env (shared contract with `daemon-write-client.ts`)
+ *   3. `DEFAULT_DASHBOARD_PORT` (3117)
+ *
+ * The env fallback (#1067) eliminates the client/server asymmetry: prior to
+ * this, the client honored `MOFLO_DAEMON_PORT` but the server only read
+ * `--dashboard-port`. A consumer pinning the env (e.g. the smoke harness)
+ * would point clients at one port while the server bound the default.
+ *
+ * Exported for unit testing — the command handler calls this once per start.
+ */
+export function resolveDashboardPort(flagValue, envValue) {
+    const source = flagValue ?? envValue;
+    if (!source)
+        return { ok: true, port: DEFAULT_DASHBOARD_PORT };
+    const parsed = parseInt(source, 10);
+    if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        const label = flagValue ? 'dashboard port' : 'MOFLO_DAEMON_PORT';
+        return { ok: false, error: `Invalid ${label}: ${source} (must be 1-65535)` };
+    }
+    return { ok: true, port: parsed };
+}
 // Start daemon subcommand
 const startCommand = {
     name: 'start',
@@ -43,16 +69,13 @@ const startCommand = {
         const rawDashboardPort = ctx.flags.dashboardPort;
         const projectRoot = process.cwd();
         const isDaemonProcess = process.env.CLAUDE_FLOW_DAEMON === '1';
-        // Parse dashboard port
-        let dashboardPort = DEFAULT_DASHBOARD_PORT;
-        if (rawDashboardPort) {
-            const parsed = parseInt(rawDashboardPort, 10);
-            if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
-                output.printError(`Invalid dashboard port: ${rawDashboardPort} (must be 1-65535)`);
-                return { success: false, exitCode: 1 };
-            }
-            dashboardPort = parsed;
+        // Resolve dashboard port; see `resolveDashboardPort` for precedence.
+        const portResult = resolveDashboardPort(rawDashboardPort, process.env.MOFLO_DAEMON_PORT);
+        if (!portResult.ok) {
+            output.printError(portResult.error);
+            return { success: false, exitCode: 1 };
         }
+        const dashboardPort = portResult.port;
         // Parse resource threshold overrides from CLI flags
         const config = {};
         const rawMaxCpu = ctx.flags.maxCpuLoad;
@@ -433,9 +456,13 @@ const stopCommand = {
     },
 };
 /**
- * Kill background daemon process using lock file
+ * Kill background daemon process using lock file.
+ *
+ * Exported so `memory init --force` can stop the daemon before unlinking
+ * moflo.db — on Windows the daemon's open file handle otherwise blocks
+ * unlinkSync with EBUSY (#1098).
  */
-async function killBackgroundDaemon(projectRoot) {
+export async function killBackgroundDaemon(projectRoot) {
     const holderPid = getDaemonLockHolder(projectRoot);
     if (!holderPid) {
         // No live daemon — clean up any stale lock