moflo 4.9.36 → 4.10.0

package/dist/src/cli/commands/doctor-checks-coverage-truth.js

@@ -0,0 +1,136 @@
+/**
+ * Embedding Coverage Truth doctor check (epic #1054.S5 / #1059).
+ *
+ * Stricter complement to `checkEmbeddings`: any disagreement between
+ * `.moflo/vector-stats.json` and the live DB count fails the check and
+ * forces doctor to report the LOWER number. The existing check allowed a
+ * 20% skew tolerance — that tolerance is what let #1054.repro-1 keep saying
+ * 100% even after the daemon-tick clobber drove the live count below the
+ * cached count.
+ *
+ * @module cli/commands/doctor-checks-coverage-truth
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { memoryDbCandidatePaths } from '../services/moflo-paths.js';
+import { errorDetail } from '../shared/utils/error-detail.js';
+import { openDaemonDatabase } from '../memory/daemon-backend.js';
+async function liveEmbeddedRowCount(dbPath) {
+    // Read-only COUNT(*) — open via the unified factory so the engine choice
+    // is consistent with every other writer (Phase 5 / #1084).
+    try {
+        const db = openDaemonDatabase(dbPath);
+        try {
+            const res = db.exec("SELECT COUNT(*) FROM memory_entries WHERE status = 'active' AND embedding IS NOT NULL AND embedding != ''");
+            const cell = res?.[0]?.values?.[0]?.[0];
+            const n = typeof cell === 'number' ? cell : Number(cell ?? 0);
+            return Number.isFinite(n) ? n : null;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function readCachedStats(cwd) {
+    const p = join(cwd, '.moflo', 'vector-stats.json');
+    if (!existsSync(p))
+        return null;
+    try {
+        const stats = JSON.parse(readFileSync(p, 'utf8'));
+        return {
+            vectorCount: typeof stats.vectorCount === 'number' ? stats.vectorCount : 0,
+            missing: typeof stats.missing === 'number' ? stats.missing : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readCoverage(cwd = process.cwd()) {
+    const cached = readCachedStats(cwd);
+    const dbPath = memoryDbCandidatePaths(cwd).find((p) => existsSync(p)) ?? null;
+    const live = dbPath ? await liveEmbeddedRowCount(dbPath) : null;
+    return {
+        cached: cached?.vectorCount ?? null,
+        live,
+        missing: cached?.missing ?? null,
+    };
+}
+/**
+ * Refuses to report 100% when the on-disk cache disagrees with the live DB.
+ * Always reports the LOWER number with the discrepancy noted.
+ *
+ * Pass cases:
+ *   - No cache + no DB: nothing to compare, neutral pass
+ *   - Cache and live agree exactly
+ * Warn cases:
+ *   - Cache present but DB unreadable (sql.js missing, etc.) — defer to the
+ *     existing checkEmbeddings instead of double-warning
+ * Fail cases:
+ *   - Cache and live disagree → report the lower value, note discrepancy
+ */
+export async function checkEmbeddingCoverageTruth(cwd = process.cwd()) {
+    const name = 'Embedding Coverage Truth';
+    try {
+        const { cached, live, missing } = await readCoverage(cwd);
+        if (cached === null && live === null) {
+            return { name, status: 'pass', message: 'No memory database or cache yet — nothing to reconcile' };
+        }
+        if (cached !== null && live === null) {
+            // Cache exists but live count unreadable — checkEmbeddings owns the
+            // "DB unreadable" diagnosis; this check stays neutral so we don't
+            // double-warn.
+            return {
+                name,
+                status: 'pass',
+                message: `Cache reports ${cached} vectors (live count unverified — DB unreadable)`,
+            };
+        }
+        if (cached === null && live !== null) {
+            if (live === 0) {
+                // Cold-boot fresh-install state — no rows to vectorise, no cache to
+                // diverge from. The check is about coverage DRIFT; empty isn't drift.
+                return { name, status: 'pass', message: 'No embedded rows yet — nothing to reconcile' };
+            }
+            return {
+                name,
+                status: 'warn',
+                message: `Live DB has ${live} embedded rows but no .moflo/vector-stats.json cache exists`,
+                fix: 'node node_modules/moflo/bin/build-embeddings.mjs',
+            };
+        }
+        // Both readings present.
+        const cachedN = cached ?? 0;
+        const liveN = live ?? 0;
+        if (cachedN === liveN) {
+            const totalRows = liveN + (missing ?? 0);
+            const pct = totalRows > 0 ? Math.round((liveN / totalRows) * 100) : 100;
+            return {
+                name,
+                status: 'pass',
+                message: `${liveN} vectors confirmed live ${missing && missing > 0 ? `(${pct}% of ${totalRows}, ${missing} missing)` : '(100%)'}`,
+            };
+        }
+        const lower = Math.min(cachedN, liveN);
+        const direction = cachedN > liveN ? 'cache higher than DB' : 'DB higher than cache';
+        return {
+            name,
+            status: 'fail',
+            message: `Coverage mismatch: cache=${cachedN}, live=${liveN} (${direction}); ` +
+                `reporting the lower value ${lower}. ` +
+                `Likely cause: writer clobber or stale cache (#1054 bug class).`,
+            fix: 'node node_modules/moflo/bin/build-embeddings.mjs',
+        };
+    }
+    catch (e) {
+        return {
+            name,
+            status: 'warn',
+            message: `Unable to verify coverage: ${errorDetail(e, { firstLineOnly: true })}`,
+        };
+    }
+}
+//# sourceMappingURL=doctor-checks-coverage-truth.js.map

package/dist/src/cli/commands/doctor-checks-memory-access.js

@@ -22,7 +22,10 @@
  * Cleanup runs even on assertion failure so a fail doesn't leave orphaned
  * agents/hive workers.
  */
+import { existsSync } from 'fs';
 import { errorDetail } from '../shared/utils/error-detail.js';
+import { memoryDbPath } from '../services/moflo-paths.js';
+import { findProjectRoot } from '../services/project-root.js';
 import { loadToolArrays, getTool, pushDetail, summarizeFunctional, } from './doctor-checks-functional-shared.js';
 const MEMORY_ACCESS_CHECK = 'Memory Access Functional';
 const MEMORY_ACCESS_FAIL_FIX = 'Run `flo doctor --json` for per-subcheck details. Common fixes: ensure fastembed installed (memory_store.hasEmbedding=false), explicit threshold:0 honored (#837), or rebuild HNSW index (`flo memory rebuild-index`)';
@@ -36,7 +39,14 @@ async function invokeOrThrow(tools, name, input) {
  * Run a memory_store + memory_search round-trip and append three details
  * (store, search, value-match). Returns the unique key/namespace used so the
  * caller can clean up. Never throws — assertion failures land in `details`.
+ *
+ * Exported (under `_` prefix) for the #1111 regression test that simulates
+ * the empty-HNSW race with a synthetic `memoryTools` array. Not part of the
+ * public doctor surface; use `checkMemoryAccessFunctional` from real callers.
  */
+export async function _runMemoryRoundTripForTest(ctx) {
+    return runMemoryRoundTrip(ctx);
+}
 async function runMemoryRoundTrip(ctx) {
     const stamp = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const key = `doctor-memprobe-${ctx.persona}-${stamp}`;
@@ -69,12 +79,21 @@ async function runMemoryRoundTrip(ctx) {
     // 2. memory_search with threshold=0 — must find the row we just stored.
     // threshold=0 is the explicit "no threshold" value (#837); regressions
     // there silently filter out matches even when the row is in the index.
+    //
+    // #1111: when search returns 0 results we do a literal-key fallback via
+    // memory_retrieve. On a fresh consumer install pretrain is still computing
+    // embeddings async, so the HNSW index can be empty (`0 vectors indexed`)
+    // even when the row IS in the DB. The check tests memory access, not
+    // embedding-index readiness — a successful literal retrieve demotes the
+    // search fail to a warn so the doctor surfaces the race without misreporting
+    // it as broken memory access.
     const searchMeta = {
         id: `${ctx.idPrefix}.memory_search`,
         mcpTool: 'memory_search',
-        expected: 'total>=1 with backend including HNSW',
+        expected: 'total>=1 via semantic search, OR row retrievable by key when HNSW is unpopulated',
     };
     let searchOut;
+    let hnswIndexEmpty = false;
     try {
         searchOut = (await invokeOrThrow(ctx.memoryTools, 'memory_search', {
             query: sentinel,
@@ -83,7 +102,23 @@ async function runMemoryRoundTrip(ctx) {
             limit: 5,
         }));
         const failReason = assertSearch(searchOut);
-        pushDetail(ctx.details, searchMeta, failReason ? searchOut : { total: searchOut?.total, backend: searchOut?.backend, topKey: searchOut?.results?.[0]?.key }, failReason);
+        if (failReason && searchOut?.total === 0) {
+            const retrievable = await literalKeyReachable(ctx.memoryTools, key, namespace);
+            if (retrievable) {
+                hnswIndexEmpty = true;
+                ctx.details.push({
+                    ...searchMeta, status: 'warn',
+                    observed: { total: 0, backend: searchOut.backend, literalRetrieve: 'found' },
+                    message: 'search returned 0 results despite threshold=0, but row IS reachable by key — HNSW index not yet populated (likely pretrain/embeddings race on fresh install; memory access path works, only the vector index is empty)',
+                });
+            }
+            else {
+                pushDetail(ctx.details, searchMeta, searchOut, failReason);
+            }
+        }
+        else {
+            pushDetail(ctx.details, searchMeta, failReason ? searchOut : { total: searchOut?.total, backend: searchOut?.backend, topKey: searchOut?.results?.[0]?.key }, failReason);
+        }
     }
     catch (err) {
         const detail = errorDetail(err, { firstLineOnly: true });
@@ -96,8 +131,21 @@ async function runMemoryRoundTrip(ctx) {
     // 3. The just-stored row must come back from search so callers can find
     // what they wrote. memory_search returns a 60-char content snippet, so
     // full-value verification belongs in the retrieve subcheck below.
-    const top = searchOut.results?.find(r => r.key === key);
-    pushDetail(ctx.details, { id: `${ctx.idPrefix}.search-finds-key`, mcpTool: 'memory_search', expected: `result containing key=${key}` }, top ? { topKey: top.key, similarity: top.similarity } : { allKeys: searchOut.results?.map(r => r.key) }, top ? null : `stored key ${key} not in results (got: ${searchOut?.results?.map(r => r.key).join(', ') ?? 'none'})`);
+    // When step 2 already observed the HNSW index as empty, the literal retrieve
+    // in step 4 covers reachability; mark this subcheck warn instead of double-
+    // failing on the same root cause.
+    if (hnswIndexEmpty) {
+        ctx.details.push({
+            id: `${ctx.idPrefix}.search-finds-key`, mcpTool: 'memory_search', status: 'warn',
+            observed: { hnswEmpty: true },
+            expected: `result containing key=${key} via semantic search`,
+            message: 'skipped semantic match — HNSW index empty (see memory_search subcheck); literal-key retrieve below covers reachability',
+        });
+    }
+    else {
+        const top = searchOut.results?.find(r => r.key === key);
+        pushDetail(ctx.details, { id: `${ctx.idPrefix}.search-finds-key`, mcpTool: 'memory_search', expected: `result containing key=${key}` }, top ? { topKey: top.key, similarity: top.similarity } : { allKeys: searchOut.results?.map(r => r.key) }, top ? null : `stored key ${key} not in results (got: ${searchOut?.results?.map(r => r.key).join(', ') ?? 'none'})`);
+    }
     // 4. memory_retrieve returns the full value (search content is truncated
     // to a 60-char snippet). Catches write clobber and namespace bleed — we
     // get back exactly what we wrote, not someone else's row at the same key.
@@ -160,6 +208,175 @@ async function safeDelete(memoryTools, key, namespace) {
     }
     catch { /* best-effort */ }
 }
+/**
+ * #1111: Probe whether a row is reachable via literal-key lookup. Used to
+ * distinguish a real memory-access failure (row missing) from the HNSW-empty
+ * race (row written, but vector index not yet populated by pretrain).
+ *
+ * Best-effort: a thrown handler or missing tool returns false rather than
+ * propagating, so the caller still reports the original search failure.
+ */
+async function literalKeyReachable(memoryTools, key, namespace) {
+    try {
+        const out = (await invokeOrThrow(memoryTools, 'memory_retrieve', { key, namespace }));
+        return out?.found === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #1053 S2: probe `memory_get_neighbors` round-trip.
+ *
+ * Same #798 protected-functionality posture as the swarm/agent/task probes:
+ * if a future refactor stubs the handler to literals (or unwires it from
+ * the metadata-passthrough plumbing in S1), this probe fails BEFORE the
+ * stub ships to consumers.
+ *
+ * Three chunks are stored via `memory_store` with the chunk-shaped metadata
+ * passed in-band (#1064 — the chokepoint now accepts `metadata` so producers
+ * no longer have to open their own DB handle). The middle chunk's neighbors
+ * are then fetched and verified to carry navigation back, proving S1 + S2 +
+ * the metadata column passthrough survive end-to-end.
+ */
+async function probeMemoryGetNeighbors(memoryTools, details) {
+    const tool = getTool(memoryTools, 'memory_get_neighbors');
+    if (!tool?.handler) {
+        details.push({
+            id: 'neighbors.registered',
+            mcpTool: 'memory_get_neighbors',
+            status: 'fail',
+            observed: { registered: false },
+            expected: 'memory_get_neighbors registered in MCP tool surface (#1053 S2)',
+            message: 'memory_get_neighbors is not registered — has the tool been removed or its name changed?',
+        });
+        return null;
+    }
+    details.push({
+        id: 'neighbors.registered',
+        mcpTool: 'memory_get_neighbors',
+        status: 'pass',
+        observed: { registered: true },
+        expected: 'memory_get_neighbors registered',
+    });
+    const stamp = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const namespace = `doctor-neighbors-${stamp}`;
+    const prefix = `chunk-doctor-neighbors-${stamp}`;
+    const chunkKeys = [`${prefix}-0`, `${prefix}-1`, `${prefix}-2`];
+    const middleKey = chunkKeys[1];
+    // Seed three chunks through `memory_store` with metadata in-band (#1064).
+    // The chokepoint now accepts `metadata`, so we no longer open our own
+    // node:sqlite handle here — the bridge's TieredCache stays consistent with
+    // disk, and the writer-audit no longer has to whitelist a probe-only bypass.
+    const dbPath = memoryDbPath(findProjectRoot());
+    if (!existsSync(dbPath)) {
+        details.push({
+            id: 'neighbors.seed',
+            mcpTool: 'memory_get_neighbors',
+            status: 'warn',
+            observed: { dbPath, exists: false },
+            expected: 'memory.db present so the neighbors probe can seed chunks',
+            message: 'memory.db missing — skip the neighbors probe (run `flo memory init` first)',
+        });
+        return { key: middleKey, namespace, chunkKeys };
+    }
+    for (let i = 0; i < chunkKeys.length; i++) {
+        const meta = {
+            type: 'chunk',
+            parentDoc: 'doc-doctor-neighbors',
+            parentPath: '/doctor-neighbors.md',
+            chunkIndex: i,
+            totalChunks: chunkKeys.length,
+            prevChunk: i > 0 ? chunkKeys[i - 1] : null,
+            nextChunk: i < chunkKeys.length - 1 ? chunkKeys[i + 1] : null,
+            siblings: chunkKeys,
+            hierarchicalParent: null,
+            hierarchicalChildren: null,
+            chunkTitle: `Doctor Probe Chunk ${i}`,
+            headerLevel: 2,
+            docContentHash: stamp,
+        };
+        try {
+            const out = (await invokeOrThrow(memoryTools, 'memory_store', {
+                key: chunkKeys[i],
+                value: `chunk body ${i}`,
+                namespace,
+                metadata: meta,
+            }));
+            if (!out?.success) {
+                details.push({
+                    id: 'neighbors.seed',
+                    mcpTool: 'memory_get_neighbors',
+                    status: 'fail',
+                    observed: { chunk: chunkKeys[i], error: out?.error ?? 'unknown' },
+                    expected: 'memory_store accepts chunk-shaped metadata in-band',
+                    message: `seed failed at chunk ${i}: ${out?.error ?? 'unknown'}`,
+                });
+                return { key: middleKey, namespace, chunkKeys };
+            }
+        }
+        catch (err) {
+            const msg = errorDetail(err, { firstLineOnly: true });
+            details.push({
+                id: 'neighbors.seed',
+                mcpTool: 'memory_get_neighbors',
+                status: 'fail',
+                observed: { error: msg },
+                expected: 'three chunk rows seeded via memory_store with chunk-shaped metadata',
+                message: `seed failed: ${msg}`,
+            });
+            return { key: middleKey, namespace, chunkKeys };
+        }
+    }
+    // 3. The probe itself — fetch prev + next of the middle chunk.
+    let result;
+    try {
+        result = (await invokeOrThrow(memoryTools, 'memory_get_neighbors', {
+            key: middleKey,
+            namespace,
+        }));
+    }
+    catch (err) {
+        const msg = errorDetail(err, { firstLineOnly: true });
+        details.push({
+            id: 'neighbors.roundtrip',
+            mcpTool: 'memory_get_neighbors',
+            status: 'fail',
+            observed: { error: msg },
+            expected: 'memory_get_neighbors returns success=true with prev + next',
+            message: `handler threw: ${msg}`,
+        });
+        return { key: middleKey, namespace, chunkKeys };
+    }
+    const failReason = assertNeighbors(result, [chunkKeys[0], chunkKeys[2]]);
+    pushDetail(details, {
+        id: 'neighbors.roundtrip',
+        mcpTool: 'memory_get_neighbors',
+        expected: `success=true, total=2, neighbors include ${chunkKeys[0]} + ${chunkKeys[2]} with navigation`,
+    }, failReason ? result : { total: result.total, neighborKeys: result.neighbors?.map(n => n.key) }, failReason);
+    return { key: middleKey, namespace, chunkKeys };
+}
+function assertNeighbors(result, expectedKeys) {
+    if (!result?.success) {
+        return `success=${result?.success} (error: ${result?.error ?? 'unknown'}) — handler did not return success`;
+    }
+    if (result.total !== expectedKeys.length) {
+        return `expected total=${expectedKeys.length}, got ${result.total} — neighbors traversal returned wrong count`;
+    }
+    const got = (result.neighbors ?? []).map(n => n.key).sort();
+    const want = [...expectedKeys].sort();
+    if (JSON.stringify(got) !== JSON.stringify(want)) {
+        return `expected neighbor keys ${JSON.stringify(want)}, got ${JSON.stringify(got)} — wrong neighbors returned`;
+    }
+    // Every neighbor must carry navigation (S1 metadata passthrough). A stub
+    // that returns shaped envelopes but null nav would pass the count check;
+    // this catches it.
+    const missingNav = (result.neighbors ?? []).filter(n => !n.navigation);
+    if (missingNav.length > 0) {
+        return `${missingNav.length} neighbor(s) returned with navigation=null — S1 metadata passthrough may be broken`;
+    }
+    return null;
+}
 export async function checkMemoryAccessFunctional() {
     const details = [];
     const mods = await loadToolArrays({
@@ -186,13 +403,35 @@ export async function checkMemoryAccessFunctional() {
         // The "subagent" path is what Claude's Task tool ends up calling: direct
         // MCP tools with no surrounding coordinator state. Failures here indicate
         // the memory subsystem itself is broken before we even get to coordinator
-        // interactions.
+        // interactions. Runs first so the bridge initializes `.moflo/moflo.db`
+        // (schema + first WAL commit) before the neighbors probe seeds chunks.
+        //
+        // Phase 4 (#1083) flipped the engine to node:sqlite + WAL: every
+        // node:sqlite connection on the same DB shares the WAL coherently, so
+        // the legacy "neighbors first or sql.js snapshot clobbers it" ordering
+        // is obsolete. Subagent first means moflo.db exists by the time the
+        // neighbors seed's `existsSync` gate runs (probe degraded to warn in
+        // the temp-dir test fixture before this reorder).
         {
             const { key, namespace } = await runMemoryRoundTrip({
                 persona: 'subagent', idPrefix: 'subagent', memoryTools, details,
             });
             cleanups.push(() => safeDelete(memoryTools, key, namespace));
         }
+        // ── Probe 0: memory_get_neighbors (#1053 S2) ──────────────────────────
+        // Seeds three chunk rows directly via the node:sqlite factory and asserts
+        // memory_get_neighbors returns the prev+next pair. Cross-engine clobber
+        // is no longer a concern under Phase 4 (#1083) — every writer on
+        // .moflo/moflo.db goes through node:sqlite + WAL.
+        {
+            const probeResult = await probeMemoryGetNeighbors(memoryTools, details);
+            if (probeResult) {
+                const { namespace, chunkKeys } = probeResult;
+                for (const key of chunkKeys) {
+                    cleanups.push(() => safeDelete(memoryTools, key, namespace));
+                }
+            }
+        }
         // ── Probe 2: swarm-agent context ──────────────────────────────────────
         // After `swarm_init` + `agent_spawn` the UnifiedSwarmCoordinator holds
         // live state. A regression that opens long-lived sql.js handles in the

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

@@ -8,24 +8,19 @@ import { existsSync, readFileSync, statSync } from 'fs';
 import { join } from 'path';
 import { memoryDbCandidatePaths } from '../services/moflo-paths.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
+import { openDaemonDatabase } from '../memory/daemon-backend.js';
 /** Skew (cached / live count delta) above which the cache is treated as stale. */
 const VECTOR_STATS_SKEW_WARN_THRESHOLD = 0.2;
 /**
- * Open `dbPath` via moflo's bundled sql.js and return the count of memory_entries
- * rows that have an embedding. Returns null if sql.js can't be loaded, the file
- * isn't a v3 schema, or the query fails — every error is treated as "unknown
- * truth", letting the caller fall back to the cached stats rather than masking
- * a healthy DB as broken.
+ * Open `dbPath` via the unified node:sqlite factory and return the count of
+ * memory_entries rows that have an embedding. Returns null on any error
+ * (corrupt DB, missing column, schema mismatch) — every error is treated as
+ * "unknown truth", letting the caller fall back to the cached stats rather
+ * than masking a healthy DB as broken.
  */
 async function countEmbeddedRowsFromDb(dbPath) {
     try {
-        const { mofloImport } = await import('../services/moflo-require.js');
-        const initSqlJs = (await mofloImport('sql.js'))?.default;
-        if (!initSqlJs)
-            return null;
-        const SQL = await initSqlJs();
-        const buffer = readFileSync(dbPath);
-        const db = new SQL.Database(buffer);
+        const db = openDaemonDatabase(dbPath);
         try {
             const res = db.exec("SELECT COUNT(*) FROM memory_entries WHERE embedding IS NOT NULL AND embedding != ''");
             const cell = res?.[0]?.values?.[0]?.[0];
@@ -137,21 +132,21 @@ export async function checkEmbeddings() {
             message: `Memory DB initialized (v${info.version}, vectors enabled)`,
         };
     }
-    catch (sqlJsError) {
-        // sql.js not available — fall back to file-size heuristic
-        const sqlDetail = errorDetail(sqlJsError);
+    catch (sqliteError) {
+        // node:sqlite open / introspection failed — fall back to file-size heuristic.
+        const sqlDetail = errorDetail(sqliteError);
         try {
             const stats = statSync(foundDbPath);
             const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
             return {
                 name: 'Embeddings',
                 status: 'warn',
-                message: `Memory DB exists (${sizeMB} MB) — cannot verify vectors (sql.js not available: ${sqlDetail})`,
-                fix: 'npm install sql.js && npx moflo embeddings init',
+                message: `Memory DB exists (${sizeMB} MB) — cannot verify vectors (DB unreadable: ${sqlDetail})`,
+                fix: 'npx moflo embeddings init',
             };
         }
         catch (statError) {
-            return { name: 'Embeddings', status: 'warn', message: `Unable to check: sql.js failed (${sqlDetail}), stat failed (${errorDetail(statError)})` };
+            return { name: 'Embeddings', status: 'warn', message: `Unable to check: DB read failed (${sqlDetail}), stat failed (${errorDetail(statError)})` };
         }
     }
 }

package/dist/src/cli/commands/doctor-checks-version-skew.js

@@ -0,0 +1,94 @@
+/**
+ * Daemon Version Skew doctor check (epic #1054.S5 / #1059).
+ *
+ * Surfaces the failure mode that silently masked the #1054 bug class for two
+ * version bumps: a long-lived daemon that survived `npm install moflo@<new>`
+ * keeps running pre-upgrade code while the on-disk package.json reads `<new>`.
+ *
+ * Distinct failure mode — NOT buried in "stale cache". Consumes the same
+ * signal the launcher acts on (`bin/session-start-launcher.mjs` section 3a-pre)
+ * via `getDaemonLockPayload` so the diagnosis and the auto-recycle path share
+ * one source of truth.
+ *
+ * @module cli/commands/doctor-checks-version-skew
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getDaemonLockPayload, readOwnMofloVersion } from '../services/daemon-lock.js';
+import { errorDetail } from '../shared/utils/error-detail.js';
+/**
+ * Resolve the installed package version from `node_modules/moflo/package.json`.
+ * Falls back to the daemon's own version (same package on consumers; same
+ * dogfood layout in this repo).
+ */
+function readInstalledVersion(cwd) {
+    const pkgPath = join(cwd, 'node_modules', 'moflo', 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            if (typeof pkg.version === 'string')
+                return pkg.version;
+        }
+        catch {
+            // unreadable / malformed — fall through
+        }
+    }
+    // Dogfood path (this repo): no `node_modules/moflo`; read the root package
+    // via the same walker the daemon uses.
+    return readOwnMofloVersion() ?? null;
+}
+/**
+ * Distinct doctor entry — fails when the running daemon's `version` (recorded
+ * in `.moflo/daemon.lock` by S2) does not match the installed package version.
+ *
+ * Pre-#1054 daemons have no `version` in their lock — treated as a mismatch
+ * because by construction they were launched before version publishing
+ * existed.
+ *
+ * No daemon running → pass with a neutral message (the daemon-status check
+ * already owns the "not running" diagnosis).
+ */
+export async function checkDaemonVersionSkew(cwd = process.cwd()) {
+    const name = 'Daemon Version Skew';
+    try {
+        const installed = readInstalledVersion(cwd);
+        if (!installed) {
+            return {
+                name,
+                status: 'warn',
+                message: 'Cannot resolve installed moflo version (no node_modules/moflo/package.json)',
+            };
+        }
+        const payload = getDaemonLockPayload(cwd);
+        if (!payload) {
+            return {
+                name,
+                status: 'pass',
+                message: `No daemon running — installed v${installed}`,
+            };
+        }
+        const observed = payload.version ?? '<pre-1054 / unknown>';
+        if (payload.version === installed) {
+            return {
+                name,
+                status: 'pass',
+                message: `Daemon v${observed} matches installed v${installed} (PID ${payload.pid})`,
+            };
+        }
+        return {
+            name,
+            status: 'fail',
+            message: `Daemon (PID ${payload.pid}) running v${observed} but installed package is v${installed}. ` +
+                `Stale pre-upgrade daemon — every write it makes is against pre-upgrade code paths (#1054 bug class).`,
+            fix: 'npx moflo daemon stop && npx moflo daemon start',
+        };
+    }
+    catch (e) {
+        return {
+            name,
+            status: 'warn',
+            message: `Unable to check version skew: ${errorDetail(e, { firstLineOnly: true })}`,
+        };
+    }
+}
+//# sourceMappingURL=doctor-checks-version-skew.js.map