moflo 4.9.37 → 4.10.1

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

@@ -9,44 +9,44 @@ import * as fs from 'fs';
 import * as crypto from 'crypto';
 import { atomicWriteFileSync } from '../services/atomic-file-write.js';
 import { legacyMemoryDbPath, memoryDbPath, MOFLO_DIR, } from '../services/moflo-paths.js';
+import { findProjectRoot } from '../services/project-root.js';
 // When run via npx, CWD may be node_modules/moflo — walk up to find actual project
 let _projectRoot;
 /**
  * Reset the cached project root. Tests that change `process.cwd()` or
  * `process.env.CLAUDE_PROJECT_DIR` between cases must call this to avoid
  * leaking state across tests.
+ *
+ * Also drops the bridge-coherence cursor (#1058) so a test that re-points the
+ * project root doesn't inherit a stale mtime anchor from the previous root.
  */
 export function _resetProjectRootForTest() {
     _projectRoot = undefined;
+    lastSeenMtimeMs = null;
 }
+/**
+ * Test seam (#1058): peek at the bridge-coherence cursor. Production callers
+ * never invoke this; tests assert that own writes update the anchor and that
+ * another writer's mtime bump triggers reload.
+ */
+export function _getBridgeCoherenceCursorForTest() {
+    return lastSeenMtimeMs;
+}
+/**
+ * Resolve the bridge's project root.
+ *
+ * Delegates to the canonical resolver in `src/cli/services/project-root.ts`
+ * (twin: `bin/lib/moflo-paths.mjs:findProjectRoot()`). The bridge keeps a
+ * module-level cache so the hot path (every withDb call) doesn't redo the
+ * stat sweep. Tests reset via {@link _resetProjectRootForTest}.
+ *
+ * If you find yourself wanting to inline a custom walk here, STOP — every
+ * divergent walk creates a new path-mismatch bug class (see #1057 / #1058).
+ */
 function getProjectRoot() {
     if (_projectRoot)
         return _projectRoot;
-    if (process.env.CLAUDE_PROJECT_DIR) {
-        _projectRoot = process.env.CLAUDE_PROJECT_DIR;
-        return _projectRoot;
-    }
-    let dir = process.cwd();
-    const root = path.parse(dir).root;
-    while (dir !== root) {
-        // `.moflo/moflo.db` is the canonical post-#727 marker. Older consumers
-        // mid-migration may still only have `.swarm/memory.db`; recognise both
-        // so the bridge can find the project root either way.
-        if (fs.existsSync(memoryDbPath(dir)) || fs.existsSync(legacyMemoryDbPath(dir))) {
-            _projectRoot = dir;
-            return _projectRoot;
-        }
-        if (fs.existsSync(path.join(dir, 'CLAUDE.md')) && fs.existsSync(path.join(dir, 'package.json'))) {
-            _projectRoot = dir;
-            return _projectRoot;
-        }
-        if (path.basename(dir) === 'node_modules') {
-            dir = path.dirname(dir);
-            continue;
-        }
-        dir = path.dirname(dir);
-    }
-    _projectRoot = process.cwd();
+    _projectRoot = findProjectRoot();
     return _projectRoot;
 }
 import { ControllerRegistry } from './controller-registry.js';
@@ -57,6 +57,20 @@ let registryPromise = null;
 let resolvedRegistry = null;
 let lastBridgeError = null;
 const schemaInitialized = new WeakSet();
+/**
+ * Last-known disk mtime for the bridge's dbPath. Anchors the bridge-coherence
+ * check (story #1058 / epic #1054): when another process writes to disk, its
+ * persist bumps mtime past this value; the next withDb call shuts the bridge
+ * down so getRegistry re-reads fresh from disk.
+ *
+ * Set after every successful persist (own writes; no self-invalidation) and
+ * after every successful registry init (anchor to load-time disk state).
+ * Reset to null when the bridge is shut down so the next init re-anchors.
+ *
+ * Module-level because the bridge itself is process-wide singleton state —
+ * matches the existing `registryPromise` lifecycle.
+ */
+let lastSeenMtimeMs = null;
 /** Controllers every moflodb_* MCP tool assumes are present when the bridge is available. */
 export const REQUIRED_BRIDGE_CONTROLLERS = Object.freeze([
     'hierarchicalMemory',
@@ -81,6 +95,61 @@ export function logBridgeError(context, err, opts) {
     const msg = errorDetail(err);
     console.error(`[moflo] ${context}: ${msg}`);
 }
+/**
+ * Treats an error as a SQLITE_BUSY lock-contention failure if either the
+ * error code or message indicates it. Belt-and-suspenders around node:sqlite,
+ * whose surface intermittently surfaces busy-conflicts as either `code:
+ * 'SQLITE_BUSY'` or a plain `Error: database is locked`. We match both.
+ */
+function isBusyError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.code === 'SQLITE_BUSY' || e.code === 'SQLITE_BUSY_SNAPSHOT' || e.code === 'SQLITE_BUSY_RECOVERY')
+        return true;
+    return typeof e.message === 'string' && /database is locked|SQLITE_BUSY/i.test(e.message);
+}
+// Exponential backoff with jitter. Total ceiling ≈ 1.55s of waiting (50 +
+// 100 + 200 + 400 + 800), plus the work itself. Sized so a typical short
+// indexer write (a few rows in auto-commit) finishes before we give up,
+// without ballooning bridge latency on a really stuck DB. See #1098.
+const BRIDGE_BUSY_RETRY_DELAYS_MS = [50, 100, 200, 400, 800];
+/**
+ * Run `fn` with a jittered exponential-backoff retry on SQLITE_BUSY errors.
+ *
+ * Why this exists: in CI the bridge's parallel doctor-subcheck workload hit
+ * "database is locked" 5–7 times in a 5ms window while the configured
+ * `busy_timeout=15000ms` should have been retrying for full seconds (#1098).
+ * The hypothesis-in-flight is that `node:sqlite`'s `db.prepare()` bypasses
+ * the engine-level `busy_handler`, so the busy_timeout pragma never engages
+ * for the bridge's prepare-heavy call patterns. Until that's confirmed
+ * (#1098 follow-up — local repro), an explicit retry here is the only
+ * guard between the consumer and a hard fail.
+ *
+ * Jitter scatters parallel retries so the workload doesn't thunder back
+ * onto the same lock at the same instant.
+ */
+async function withBusyRetry(fn) {
+    let lastErr = null;
+    for (let attempt = 0; attempt <= BRIDGE_BUSY_RETRY_DELAYS_MS.length; attempt++) {
+        if (attempt > 0) {
+            const base = BRIDGE_BUSY_RETRY_DELAYS_MS[attempt - 1];
+            const jitter = base * (Math.random() * 0.5 - 0.25); // ±25%
+            const delay = Math.max(0, Math.round(base + jitter));
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isBusyError(err))
+                throw err;
+            // Loop continues — backoff applied at top of next iteration.
+        }
+    }
+    throw lastErr;
+}
 /**
  * Resolve the on-disk DB path the bridge should read/write.
  *
@@ -215,7 +284,34 @@ export function persistBridgeDb(db, dbPath) {
         return;
     try {
         fs.mkdirSync(path.dirname(target), { recursive: true });
-        atomicWriteFileSync(target, db.export());
+        // Phase 4 (#1083) — node:sqlite-backed handles persist incrementally via
+        // WAL; `save()` on the factory adapter is a no-op for them. Doing the
+        // sql.js-style `export()` + `atomicWriteFileSync` against a node:sqlite
+        // handle would CLOBBER the WAL writes (the catastrophic case the epic
+        // was killing). Route through `save()` when the handle is the factory
+        // shape; only fall back to the legacy export-and-write for raw sql.js.
+        if (db && db.kind === 'node-sqlite' && typeof db.save === 'function') {
+            db.save();
+        }
+        else {
+            atomicWriteFileSync(target, db.export());
+        }
+        // Anchor the bridge-coherence cursor to the post-persist mtime so our own
+        // write doesn't trigger a self-invalidation on the next withDb call.
+        // Under WAL the write lands in `-wal` (not the main file), so include
+        // its mtime — must match the read side of checkBridgeCoherence or self-
+        // writes self-invalidate (#1098).
+        try {
+            let anchored = fs.statSync(target).mtimeMs;
+            try {
+                const walStat = fs.statSync(`${target}-wal`);
+                if (walStat.mtimeMs > anchored)
+                    anchored = walStat.mtimeMs;
+            }
+            catch { /* no WAL sidecar — main mtime is authoritative */ }
+            lastSeenMtimeMs = anchored;
+        }
+        catch { /* tolerate; coherence check re-anchors on next read */ }
     }
     catch (err) {
         logBridgeError('bridge persist failed', err, { alwaysLog: true });
@@ -280,20 +376,138 @@ export function getDb(registry) {
     }
     return { db, mofloDb };
 }
+/**
+ * Bridge coherence check (story #1058 / epic #1054 — read-side symmetry to
+ * #981 single-writer). sql.js holds an in-memory DB snapshot per process and
+ * never re-reads disk after init, so any long-lived process — daemon or
+ * not — returns stale rows when another writer has touched the file since
+ * this process loaded its snapshot.
+ *
+ * Solution: stat the dbPath before every bridge op; if the mtime has advanced
+ * past our last-known value, another writer has touched the file — drop the
+ * bridge so `getRegistry` re-loads from disk on the next call.
+ *
+ * The daemon participates in this check too. #1058 originally exempted the
+ * daemon under "daemon is the sole writer", but that assumption breaks every
+ * session-start: `bin/index-guidance.mjs`, migration runners, and repair
+ * tools all write directly to `.moflo/moflo.db` while the daemon is up
+ * (epic #1057 calls these out as in-scope writers to coordinate). Without
+ * the daemon doing the check, daemon-routed MCP reads served the pre-init
+ * snapshot indefinitely, hiding the indexer's chunks from `memory_search` /
+ * `memory_get_neighbors` until the daemon process restarted (#1073, smoke).
+ *
+ * Self-invalidation is still suppressed: `persistBridgeDb` anchors
+ * `lastSeenMtimeMs` to the post-write mtime, so the daemon's own writes never
+ * trip the reload. External writers — whose touches advance mtime past the
+ * anchor — do.
+ */
+async function checkBridgeCoherence(dbPath) {
+    // No registry yet → nothing to invalidate; first init will anchor the cursor.
+    if (!registryPromise)
+        return;
+    const target = dbPath ? path.resolve(dbPath) : getDbPath();
+    if (target === ':memory:')
+        return;
+    // Under WAL (Phase 5 / #1083), commits land in the `-wal` sidecar first —
+    // the main DB file's mtime ONLY advances on checkpoint, which may be many
+    // writes apart. Statting just the main file misses every external WAL
+    // write between checkpoints, leaving the bridge with a stale in-memory
+    // snapshot indefinitely. That's the failure mode in #1098 / #1073 smoke
+    // where doctor's seed-via-openDaemonDatabase then bridge-via-MCP couldn't
+    // see its own freshly-written rows. Stat both files and use whichever is
+    // most recent. Mirrors the same fix in `refreshVectorStatsCache`.
+    let mtimeMs = 0;
+    try {
+        mtimeMs = fs.statSync(target).mtimeMs;
+    }
+    catch {
+        // File missing or unreadable — fall through. Downstream withDb surfaces
+        // the error; we don't synthesize a coherence event from a stat failure.
+        return;
+    }
+    try {
+        const walStat = fs.statSync(`${target}-wal`);
+        if (walStat.mtimeMs > mtimeMs)
+            mtimeMs = walStat.mtimeMs;
+    }
+    catch { /* no WAL sidecar yet — main mtime is authoritative */ }
+    if (lastSeenMtimeMs == null) {
+        // First op after init — anchor and proceed.
+        lastSeenMtimeMs = mtimeMs;
+        return;
+    }
+    if (mtimeMs > lastSeenMtimeMs) {
+        // Another process wrote since we loaded. Drop the bridge so the next
+        // `getRegistry` call re-initializes from fresh disk. Reset the cursor;
+        // the post-reload anchor (after `getRegistry` succeeds) re-sets it.
+        await shutdownBridge();
+        lastSeenMtimeMs = null;
+    }
+}
 /**
  * Resolve registry + db, run fn, return null on any unexpected failure so
  * the caller falls back to raw sql.js. Errors are logged to stderr —
  * silently swallowing them previously masked real bugs in bridge-entries.ts.
+ *
+ * Bridge coherence (#1058): every entry through this gate checks whether the
+ * dbPath's mtime has advanced past our last-known value; if so, the bridge is
+ * torn down so the next op reads fresh disk state. Daemon participates in the
+ * check; its own writes anchor `lastSeenMtimeMs` via `persistBridgeDb` so
+ * self-fire is suppressed.
  */
 export async function withDb(dbPath, fn) {
+    await checkBridgeCoherence(dbPath);
     const registry = await getRegistry(dbPath);
     if (!registry)
         return null;
     const ctx = getDb(registry);
     if (!ctx)
         return null;
+    // Anchor the coherence cursor to load-time disk state once the registry is
+    // resolved. The post-init read of `mofloDb.database` reflects the bytes
+    // that were on disk when `openSqlJsDatabase` ran; pin the matching mtime so
+    // a subsequent unrelated process write triggers reload, not a self-fire.
+    // Include `-wal` since WAL writes don't bump the main file mtime (#1098).
+    const target = dbPath ? path.resolve(dbPath) : getDbPath();
+    if (lastSeenMtimeMs == null && target !== ':memory:') {
+        try {
+            let anchor = fs.statSync(target).mtimeMs;
+            try {
+                const walStat = fs.statSync(`${target}-wal`);
+                if (walStat.mtimeMs > anchor)
+                    anchor = walStat.mtimeMs;
+            }
+            catch { /* no WAL sidecar — main mtime is authoritative */ }
+            lastSeenMtimeMs = anchor;
+        }
+        catch { /* file may not exist yet — first persist will anchor */ }
+    }
     try {
-        return await fn(ctx, registry);
+        const result = await withBusyRetry(() => fn(ctx, registry));
+        // Re-anchor the coherence cursor to the post-op mtime so internal
+        // bridge writes that happen AFTER persistBridgeDb (attestation log,
+        // bumpAccessCounts, cache invalidation row updates, etc.) don't
+        // look like external writes on the next withDb call. Without this
+        // re-anchor, the next call's checkBridgeCoherence sees the
+        // attestation-advanced -wal mtime, tears down the registry, and
+        // any test-injected stubs (cache.set, etc.) get reset — exactly
+        // the failure mode in `bridge-entries.test.ts` #994 after the
+        // WAL-coherence fix (49f91a01a). External writes still get
+        // detected at the START of the next withDb call.
+        if (target !== ':memory:') {
+            try {
+                let anchor = fs.statSync(target).mtimeMs;
+                try {
+                    const walStat = fs.statSync(`${target}-wal`);
+                    if (walStat.mtimeMs > anchor)
+                        anchor = walStat.mtimeMs;
+                }
+                catch { /* no WAL sidecar */ }
+                lastSeenMtimeMs = anchor;
+            }
+            catch { /* tolerate; coherence check re-anchors on next read */ }
+        }
+        return result;
     }
     catch (err) {
         logBridgeError('bridge operation failed', err);
@@ -313,6 +527,9 @@ export async function shutdownBridge() {
     const registry = await registryPromise;
     registryPromise = null;
     resolvedRegistry = null;
+    // Drop the coherence cursor too — the next init will re-anchor against
+    // whatever's on disk by then.
+    lastSeenMtimeMs = null;
     if (registry) {
         try {
             await registry.shutdown();
@@ -388,9 +605,12 @@ export function refreshVectorStatsCache(dbPathOverride) {
         const existing = readExistingVectorStats(root);
         // Mtime short-circuit (#639 perf): refreshVectorStatsCache fires on every
         // bridge store/delete. When the on-disk DB hasn't changed since we last
-        // wrote the cache (the common case mid-session — bridge writes don't
-        // touch the file until persist), running 3 COUNT queries is wasted work.
-        // Skip the rest entirely.
+        // wrote the cache, running 3 COUNT queries is wasted work — skip the rest.
+        //
+        // Phase 4 (#1083) flipped the engine to node:sqlite + WAL: every commit
+        // lands in the `-wal` sidecar (mtime advances there), not the main file.
+        // Stat both so a write to either invalidates the cache. The `-shm` file
+        // is not load-bearing — it tracks WAL readers, not committed writes.
         let dbMtimeMs = 0;
         let dbSizeKB = 0;
         try {
@@ -399,6 +619,12 @@ export function refreshVectorStatsCache(dbPathOverride) {
             dbSizeKB = Math.floor(stat.size / 1024);
         }
         catch { /* file may not exist */ }
+        try {
+            const walStat = fs.statSync(`${dbFile}-wal`);
+            if (walStat.mtimeMs > dbMtimeMs)
+                dbMtimeMs = walStat.mtimeMs;
+        }
+        catch { /* no WAL sidecar — fine, dbMtimeMs already covers it */ }
         if (existing &&
             typeof existing.updatedAt === 'number' &&
             typeof existing.vectorCount === 'number' &&

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

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

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

@@ -30,6 +30,19 @@ function makeEntryCacheKey(namespace, key) {
     const safeKey = String(key).replace(/:/g, '_');
     return `entry:${safeNs}:${safeKey}`;
 }
+/** Normalise `metadata` for the `metadata` TEXT column; `undefined` → `'{}'` (#1064). */
+export function serialiseMetadata(metadata) {
+    if (metadata == null)
+        return '{}';
+    if (typeof metadata === 'string')
+        return metadata;
+    try {
+        return JSON.stringify(metadata);
+    }
+    catch {
+        return '{}';
+    }
+}
 function bm25Score(queryTerms, docContent, avgDocLength, docCount, termDocFreqs) {
     const k1 = 1.2;
     const b = 0.75;
@@ -83,9 +96,29 @@ async function cacheInvalidate(registry, cacheKey) {
 async function guardValidate(registry, operation, params, options) {
     const guard = registry.get('mutationGuard');
     if (!guard)
-        return { allowed: true };
+        return { allowed: true, commit: null };
     const result = guard.validate({ operation, params, timestamp: Date.now(), bypassDedupe: options?.bypassDedupe });
-    return { allowed: result?.allowed === true, reason: result?.reason };
+    const allowed = result?.allowed === true;
+    return {
+        allowed,
+        reason: result?.reason,
+        commit: allowed && result?.token ? { guard, token: result.token } : null,
+    };
+}
+/**
+ * Confirm a previously-validated mutation. Idempotent and null-safe so
+ * call sites can fire it from a `finally`-style success branch without
+ * extra null checking. After commit, the mutation lands in MutationGuard's
+ * dedupe buffer so subsequent identical writes within the window are
+ * correctly rejected.
+ */
+function guardCommit(handle) {
+    if (!handle)
+        return;
+    try {
+        handle.guard.commit(handle.token);
+    }
+    catch { /* commit failure is non-fatal — recording is observability-grade */ }
 }
 async function logAttestation(registry, operation, entryId, metadata) {
     const attestation = registry.get('attestationLog');
@@ -198,12 +231,13 @@ export async function bridgeStoreEntry(options) {
           tags, metadata, created_at, updated_at, expires_at, status
         ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
         // sql.js Statement.run takes an array of bindings — not varargs.
+        const metadataJson = serialiseMetadata(options.metadata);
         const stmt = ctx.db.prepare(insertSql);
         stmt.run([
             id, key, namespace, value,
             embeddingJson, dimensions || null, model,
             tags.length > 0 ? JSON.stringify(tags) : null,
-            '{}',
+            metadataJson,
             now, now,
             ttl ? now + (ttl * 1000) : null,
         ]);
@@ -226,7 +260,16 @@ export async function bridgeStoreEntry(options) {
         const cacheKey = makeEntryCacheKey(namespace, key);
         let cached = true;
         try {
-            await cacheSet(registry, cacheKey, { id, key, namespace, content: value, embedding: embeddingJson });
+            // #1064 — include metadata in the cache value so a subsequent
+            // bridgeGetEntry cache-hit returns the same shape as a fresh disk read.
+            // Without this, chunk-row producers writing through the chokepoint would
+            // get `{}` back from cache and the full metadata from disk — exactly the
+            // divergence the cache is supposed to mask.
+            await cacheSet(registry, cacheKey, {
+                id, key, namespace, content: value,
+                embedding: embeddingJson,
+                metadata: metadataJson,
+            });
         }
         catch (err) {
             cached = false;
@@ -249,6 +292,11 @@ export async function bridgeStoreEntry(options) {
                 logBridgeError('post-persist stats refresh failed', err);
             }
         }
+        // Commit the MutationGuard recording NOW that the row is durable on
+        // disk + cache + attestation log. Order: persist before commit so a
+        // SQLITE_BUSY mid-write doesn't leave a stale dedupe entry that would
+        // reject the withDb retry as a "duplicate" (#1098).
+        guardCommit(guardResult.commit);
         return {
             success: true,
             id,
@@ -316,13 +364,14 @@ export async function bridgeStoreEntries(items, dbPath) {
             embedding, embedding_dimensions, embedding_model,
             tags, metadata, created_at, updated_at, expires_at, status
           ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
+            const metadataJson = serialiseMetadata(opts.metadata);
             try {
                 const stmt = ctx.db.prepare(insertSql);
                 stmt.run([
                     id, key, namespace, value,
                     embeddingJson, dimensions || null, model,
                     tags.length > 0 ? JSON.stringify(tags) : null,
-                    '{}',
+                    metadataJson,
                     now, now,
                     ttl ? now + (ttl * 1000) : null,
                 ]);
@@ -337,7 +386,12 @@ export async function bridgeStoreEntries(items, dbPath) {
                 anyEmbedded = true;
             deferredBookkeeping.push({
                 cacheKey: makeEntryCacheKey(namespace, key),
-                cacheValue: { id, key, namespace, content: value, embedding: embeddingJson },
+                // #1064 — keep cache shape in sync with disk (see single-store path).
+                cacheValue: {
+                    id, key, namespace, content: value,
+                    embedding: embeddingJson,
+                    metadata: metadataJson,
+                },
                 entryId: id,
                 entryKey: key,
                 namespace,
@@ -389,6 +443,11 @@ export async function bridgeStoreEntries(items, dbPath) {
                 logBridgeError('post-persist stats refresh failed', err);
             }
         }
+        // Commit the bulk-store mutation in the dedupe buffer (#1098). At least
+        // one row reached disk, which is sufficient to record the bulk op —
+        // partial-batch persist failure is already reflected per-item via the
+        // results array.
+        guardCommit(guardResult.commit);
         return results;
     });
 }
@@ -663,6 +722,11 @@ export async function bridgeDeleteEntry(options) {
             // Non-fatal — count is informational
         }
         refreshVectorStatsCache();
+        // Commit the delete mutation in the dedupe buffer (#1098). The row is
+        // gone from disk and the cache is invalidated, so this is the safe
+        // point to record — a SQLITE_BUSY mid-DELETE earlier would have caught
+        // in the try/catch above and never reached here.
+        guardCommit(guardResult.commit);
         return {
             success: true,
             deleted: true,

package/dist/src/cli/memory/controller-registry.js

@@ -12,7 +12,7 @@
  */
 import { EventEmitter } from 'node:events';
 import * as path from 'node:path';
-import { openSqlJsDatabase } from './sqljs-backend.js';
+import { openDaemonDatabase } from './daemon-backend.js';
 import { CONTROLLER_SPECS } from './controller-specs.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 // ===== Initialization Levels =====
@@ -213,7 +213,12 @@ export class ControllerRegistry extends EventEmitter {
                     return;
                 }
             }
-            const database = await openSqlJsDatabase(dbPath, config.wasmPath);
+            // Phase 4 (#1083) — open via the node:sqlite-backed adapter (shape-
+            // compatible with sql.js Statement API). Eliminates the cross-process
+            // clobber between `bin/` writers (node:sqlite + WAL) and the daemon's
+            // bridge (was sql.js readFileSync). `config.wasmPath` is now unused —
+            // node:sqlite is built into Node 22+; Phase 5 removes the field.
+            const database = openDaemonDatabase(dbPath);
             this.mofloDb = { database, close: async () => database.close() };
             this.emit('mofloDb:initialized');
         }

package/dist/src/cli/memory/controllers/batch-operations.js

@@ -31,7 +31,11 @@ export class BatchOperations {
         }
         const ids = [];
         const now = Date.now();
-        this.db.run('BEGIN TRANSACTION');
+        // BEGIN IMMEDIATE acquires RESERVED upfront — busy_handler is consulted
+        // for the lock acquisition, so concurrent writers wait out PRAGMA
+        // busy_timeout instead of fail-fasting on the SHARED→RESERVED upgrade
+        // (#1099: the deferred-BEGIN trap surfaced in #1098 CI).
+        this.db.run('BEGIN IMMEDIATE');
         try {
             const stmt = this.db.prepare(`INSERT INTO ${EPISODES_TABLE} (id, key, content, metadata, embedding, ts)
          VALUES (?, ?, ?, ?, ?, ?)`);