moflo 4.9.31 → 4.9.32

package/.claude/guidance/shipped/moflo-root-cause-discipline.md

@@ -0,0 +1,167 @@
+# Root-Cause Discipline — Measure Twice, Cut Once
+
+**Purpose:** The MoFlo standard for fixing bugs. We do not "shoot first and ask questions later" — we measure twice and cut once. Apply this whenever you are about to write a fix, especially when a previous fix on the same surface didn't fully work.
+
+---
+
+## The Headline Rule
+
+**Measure twice, cut once. Step back, understand the problem holistically, then make the simplest fix that eliminates the cause.** Do not pile patch onto patch onto patch.
+
+This is the single most important engineering posture in this project. Layered patches have produced the worst regressions, the longest debugging sessions, and the most expensive token bills. When you find yourself reaching for "another layer" — stop.
+
+---
+
+## Before You Write Fix N+1
+
+Before adding a new fix on top of an existing one, you MUST answer all four:
+
+| Question | If you can't answer | Action |
+|----------|---------------------|--------|
+| What exactly is the failure mode at the lowest level? (Not the symptom — the actual mechanism.) | You don't understand the bug yet | Investigate further; do not fix |
+| Why didn't fix N work? Is it wrong, or just incomplete? | You're guessing at the gap | Read fix N's code + history; reproduce the failure |
+| Would removing fix N + replacing with one cleaner fix simplify the surface? | You haven't considered consolidation | Try the consolidation first |
+| What's the SIMPLEST change that makes the bug structurally impossible? | You're patching symptoms, not causes | Step back further |
+
+If three answers are vague, you're in patch-on-patch territory. Stop and re-think.
+
+---
+
+## Patch-on-Patch Smoke Alarms
+
+Stop and reconsider when you see yourself doing any of these:
+
+| Smoke alarm | What it usually means | The right move |
+|-------------|----------------------|----------------|
+| Adding a "belt-and-suspenders" cleanup | The first cleanup is racing something — find what | Eliminate the race, not double-cleanup |
+| Adding `try/catch` around code that already has `try/catch` | Outer catch is masking inner failure | Surface the inner error, don't double-wrap |
+| Adding a `setTimeout` retry loop on top of an existing retry | Retry won't fix a logic bug | Fix the logic |
+| Bumping a timeout because tests fail intermittently | The op is slower than expected — find why | Fix the slowness or remove the op |
+| Adding a flag/env-var to "skip the broken path" | You're hiding the bug, not fixing it | Fix the path or delete it |
+| Adding a workaround "until we can fix this properly" | You won't come back; "later" never happens | Fix it now or file with full context |
+| Touching three files to fix one bug | Bug is misdiagnosed; one file usually suffices | Re-diagnose |
+
+When **two or more** of these apply at once, the fix is almost certainly wrong. Throw it away and re-investigate.
+
+---
+
+## The Holistic Step-Back
+
+When fix N didn't work, do these in order — not in parallel, not skipping steps:
+
+1. **Read every prior fix on this surface in full.** Not the commit message — the code. Note what each one was trying to prevent and what it actually does.
+2. **Reproduce the failure deterministically** before touching code. If you can't reproduce it, you don't understand it.
+3. **Trace the data flow.** Where does the bad state originate? What writes it? What reads it? What invariant got violated?
+4. **Question the test, not just the code.** What invariant does the failing test actually encode? Does that invariant match the runtime contract, or is the test stricter? A test stricter than the contract will produce flakes that look like bugs but aren't. (See #1017 case study.)
+5. **Identify the structural cause** — the place where the bug becomes possible, not the place where it becomes visible.
+6. **Now consider fixes.** The cheapest fix at the structural cause beats the cleverest fix at the symptom every time. If the cause is "test asserts X, runtime contract is Y, X is stricter," the fix is in the test.
+
+If step 6 yields a fix smaller and simpler than the existing patches, **delete the existing patches** as part of the same change. Do not stack.
+
+---
+
+## Code Serves the Specification, Not the Test
+
+**Periodically ask: "Am I solving an actual problem, or am I flailing to satisfy a flawed test?"** When several attempted fixes haven't moved the needle, the test framework is a likely suspect — but the response is never to degrade production code to make the test pass.
+
+**Never introduce substandard code to satisfy shortcomings of the testing infrastructure.** Production code expresses the runtime contract. Tests verify the contract. When they disagree:
+
+| Disagreement | Correct response | Wrong response |
+|--------------|------------------|----------------|
+| Test asserts behavior the runtime never promised | Fix the test to match the contract | Add code to satisfy the test's stricter assertion |
+| Test uses an unrealistic environment (mocks the wrong layer, races a SIGKILL'd daemon, single-session asserts on a multi-session contract) | Fix the test environment | Add retry / sleep / workaround in production code |
+| Test framework can't observe a legitimate runtime path | Add a test hook (`_resetForTest`, `getStateForTest`) that doesn't change runtime behavior | Restructure runtime to make the test framework's observation easier |
+| Test is flaky on one platform but the runtime works | Identify why the test, not the runtime, is sensitive | Bump timeouts / retries / sleeps in production paths |
+
+**Code purity check before any "make the test pass" change:** would you ship this change if the test didn't exist? If no, you're degrading the code to satisfy the test. Stop. Fix the test.
+
+**Signals you're flailing for the test, not solving the bug:**
+
+| Signal | What it actually says |
+|--------|----------------------|
+| You've tried 3+ fixes and nothing has moved the needle | The diagnosis is wrong; investigate before patching again |
+| Each fix gets narrower / more defensive without removing the prior layer | You're piling on, not solving |
+| The runtime works fine in real-world usage but the test fails | The test's spec doesn't match the contract — that's the bug |
+| You'd need to add a sleep, retry, lock, or platform-special-case to make the test happy | Production code is paying for a test-environment limitation |
+| Removing the test makes the bug "go away" | The test was right but the fix is wrong, OR the test was the bug — diagnose which |
+
+The user said it directly: **"we never want to introduce substandard code to satisfy shortcomings of our testing infrastructure."** Tests serve the code; the code does not serve the tests.
+
+When you find that the test is the actual problem: change the test, document why in the commit message, and (if the change weakens an invariant) add a separate test that captures the invariant the original was *trying* to encode without the false strictness.
+
+---
+
+## Concrete Example: #1017 Hive-Mind Shutdown
+
+This is the canonical case study for this guidance — and it has a second-order lesson that makes it even more useful.
+
+| Attempt | Approach | Outcome |
+|---------|----------|---------|
+| #1017 first try | Loop list+delete in `clearNamespace` | Race window remained — broadcasts landed mid-loop |
+| #1024 layer 1 | Detach adapter BEFORE `clearNamespace` (after `terminateAgent`) | Race narrowed but not eliminated |
+| #1024 layer 2 | Add `purgeHiveNamespacesDirect` raw sql.js DELETE | Looked bulletproof; actually clobber-prone vs daemon's stale snapshot (#981 single-writer) |
+| #1024 declared green | All 6 CI checks pass once | Same flake reappeared on next PR's CI |
+| #1027 attempt 4 | Move `adapter.detach()` BEFORE `terminateAgent`; delete `purgeHiveNamespacesDirect` | Code simplified by -73 LOC. **Same flake on macos-latest CI.** |
+| #1027 — actual fix | Run launcher a SECOND time after doctor in the populated harness | Test passes. Race is intrinsic to multi-process sql.js + daemon kill timing; the harness assertion was over-strict. |
+
+The first three attempts kept asking "how do we delete this row harder?" The fourth attempt was a structural simplification that was correct on its own merits (-73 LOC, removed dead code, simpler shutdown ordering) but **did not fix the flake**.
+
+The actual root cause was outside the surface every patch had touched: the populated harness was asserting "ephemerals purged after one launcher run" when the **runtime contract is "ephemerals purged at next session-start launcher"**. The doctor's hive-mind probe writes a row intentionally; that row is supposed to live until the NEXT session purges it. The test was conflating "purge mechanism works" with "purge happens within one session" — those are different invariants and only the first is the real product behavior.
+
+**Two lessons stack here:**
+
+1. **Don't pile layers** (the original lesson): four shutdown patches, each narrower than the last, none structurally sufficient.
+2. **Question the test, not just the code** (the second-order lesson): if you've been fighting a race for four PRs and the simplest in-code fix doesn't move the needle, the spec encoded in the test may be wrong. A test that is stricter than the runtime contract WILL produce flakes that look like product bugs but aren't.
+
+Together: when a fix isn't working, ask both "what writes the bad state?" AND "is this state actually bad in the runtime contract, or only in the test's expectation?"
+
+---
+
+## When You Genuinely Need a Belt-and-Suspenders
+
+Belts-and-suspenders are not always wrong. They are right when:
+
+| Condition | Example |
+|-----------|---------|
+| The two layers protect against **different** failure modes | atomic-write tmp+fsync+rename: tmp protects partial writes; fsync protects OS cache; rename protects readers — three concerns, three mechanisms |
+| The first layer's failure is **silent**, the second surfaces it | A retry that logs the first failure before re-attempting |
+| Removing either layer has a **stated, documented reason** for keeping the other | A fallback path with a comment explaining when the primary doesn't reach |
+
+They are wrong when both layers protect against the **same** failure mode and you're hoping at least one wins. That's hope, not engineering.
+
+---
+
+## What This Means for PR Reviews
+
+Reviewers should reject — not just question — PRs that show patch-on-patch signatures:
+
+| Signal | Reviewer action |
+|--------|----------------|
+| Same file/function touched in 3+ recent commits, same bug | Ask: "is the prior fix wrong? remove it" |
+| New fix adds a layer without removing one | Ask: "what was wrong with the prior layer? why does it stay?" |
+| Comment in new code says "for safety" or "just in case" | Ask: "what specific failure is this preventing? cite the line that produces it" |
+| The PR description says "this should fix the flake" without a deterministic repro | Ask: "what was the actual root cause? the writeup doesn't name it" |
+
+These questions are not pedantic. They are the difference between fixing a bug and growing the surface area of bugs.
+
+---
+
+## How to Apply When You Are Stuck
+
+If you genuinely cannot find the root cause after stepping back:
+
+1. **Stop fixing. Start measuring.** Add logging at every state transition. Reproduce. Read the log.
+2. **Ask the user before patching.** A two-line confirmation question costs less than a wrong fix.
+3. **File the issue with what you DO know.** Partial diagnosis with logs is more useful than a guessed fix.
+4. **Never ship "I think this might work."** That phrasing is a self-warning that the diagnosis isn't done.
+
+It is always cheaper to admit uncertainty than to ship a layered patch that creates two new bugs.
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-error-handling.md` — Silent failures are the prerequisite condition for most patch-on-patch saga; fix those first
+- `.claude/guidance/moflo-source-hygiene.md` — When you decide to delete redundant code, the canonical-location rules tell you what's safe to remove
+- `feedback_no_layered_workarounds.md` (auto-memory) — The personal-feedback version of this rule, recorded from prior incidents
+- `feedback_ci_flake_means_not_done.md` (auto-memory) — A flake that "passed on rerun" is not fixed; root-cause it under this discipline

package/dist/src/cli/embeddings/fastembed-inline/model-loader.js

@@ -8,17 +8,30 @@
  * For `fast-all-MiniLM-L6-v2`, the URL slug is `sentence-transformers-all-MiniLM-L6-v2`
  * but the on-disk directory keeps the `fast-` prefix — verbatim from upstream.
  *
- * Concurrency: parallel callers downloading the same model atomic-rename the
- * tarball through a unique temp path, so Windows file locks during extraction
- * never collide. The final model dir is the synchronization point.
+ * Concurrency: a per-model file lock (`<cacheDir>/.<model>.download.lock`,
+ * created with `wx`) serializes the download/extract for any number of
+ * parallel processes — only one process performs the work, the rest poll for
+ * the completion sentinel. This was issue #1021's secondary failure mode:
+ * the smoke harness spawns ~12 parallel doctor + memory probes on a cold
+ * cache, and Windows file locking exposed the race when the in-tree
+ * "synchronization point" was just a shared directory write.
  */
 import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
 import { x as tarExtract } from 'tar';
 const GCS_BASE_URL = 'https://storage.googleapis.com/qdrant-fastembed';
+// Lock-poll: how long a non-holder waits for the holder to finish before
+// concluding the holder crashed. Cold-fetch is ~90 MB on slow CI runners, so
+// a generous timeout avoids false takeovers under network back-pressure.
+const LOCK_TIMEOUT_MS = 120_000;
+const LOCK_POLL_INTERVAL_MS = 250;
+// Standard transient-error retry per feedback_transient_retry_circuit_breaker.md:
+// 50/200/800ms backoff, only on network errors and 5xx (4xx is deterministic).
+const HTTP_BACKOFF_MS = [50, 200, 800];
 /**
  * Sentinel file written into the model directory only after the tarball has
  * been fully downloaded AND extracted. Cache hits without it are treated as
@@ -50,28 +63,121 @@ function gcsSlugFor(model) {
 export function resolveCacheDir(explicit, env = process.env) {
     return explicit ?? env.FASTEMBED_CACHE ?? join(homedir(), '.cache', 'fastembed');
 }
+class TransientHttpError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransientHttpError';
+    }
+}
 /**
  * Stream the tarball to a unique temp path, then atomic-rename to the final
- * tarball path before extracting. The temp suffix prevents two concurrent
- * downloads from clobbering each other's write stream — extraction itself is
- * the slow step on Windows where file-lock contention shows up.
+ * tarball path before extracting. The temp suffix prevents the in-flight
+ * write stream from being observed at the final path — extraction always
+ * sees a complete file.
+ *
+ * Throws `TransientHttpError` on 5xx / network failure (caller retries) and
+ * a plain Error on 4xx (caller fails fast — retrying won't help).
  */
 async function downloadTarball(url, destPath, showProgress, deps) {
     const fetchFn = deps.fetchImpl ?? fetch;
     const tmpPath = `${destPath}.${process.pid}.tmp`;
     mkdirSync(dirname(destPath), { recursive: true });
-    const res = await fetchFn(url);
+    let res;
+    try {
+        res = await fetchFn(url);
+    }
+    catch (err) {
+        throw new TransientHttpError(`Model download failed: GET ${url} → ${err.message}`);
+    }
     if (!res.ok || !res.body) {
-        throw new Error(`Model download failed: GET ${url} → ${res.status} ${res.statusText}`);
+        const msg = `Model download failed: GET ${url} → ${res.status} ${res.statusText}`;
+        if (res.status >= 500)
+            throw new TransientHttpError(msg);
+        throw new Error(msg);
     }
     if (showProgress) {
         const total = Number(res.headers.get('content-length') ?? 0);
         const totalMb = (total / (1024 * 1024)).toFixed(1);
         process.stderr.write(`fastembed: downloading ${totalMb} MB from ${url}\n`);
     }
-    await pipeline(Readable.fromWeb(res.body), createWriteStream(tmpPath));
+    try {
+        await pipeline(Readable.fromWeb(res.body), createWriteStream(tmpPath));
+    }
+    catch (err) {
+        rmSync(tmpPath, { force: true });
+        throw new TransientHttpError(`Model download stream failed mid-transfer (${url}): ${err.message}`);
+    }
     renameSync(tmpPath, destPath);
 }
+async function downloadTarballWithRetry(url, destPath, showProgress, deps) {
+    let lastErr;
+    for (let attempt = 0; attempt <= HTTP_BACKOFF_MS.length; attempt++) {
+        try {
+            await downloadTarball(url, destPath, showProgress, deps);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            if (!(err instanceof TransientHttpError) || attempt === HTTP_BACKOFF_MS.length)
+                break;
+            if (showProgress) {
+                process.stderr.write(`fastembed: download attempt ${attempt + 1} failed (${err.message}); retrying in ${HTTP_BACKOFF_MS[attempt]}ms.\n`);
+            }
+            await delay(HTTP_BACKOFF_MS[attempt]);
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Cross-process serialization for the download/extract step. Lock holder runs
+ * `work`; non-holders poll for the completion sentinel and return as soon as
+ * it appears. If the lock holder crashes (lockfile remains but no sentinel
+ * after the timeout), the next caller cleans up and retries — preventing a
+ * permanently-stuck cache after a Ctrl+C mid-download.
+ */
+async function withModelLock(lockPath, completionPath, work) {
+    try {
+        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+        await waitForCompletionOrTakeover(lockPath, completionPath, work);
+        return;
+    }
+    try {
+        await work();
+    }
+    finally {
+        try {
+            rmSync(lockPath, { force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+async function waitForCompletionOrTakeover(lockPath, completionPath, work) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (existsSync(completionPath))
+            return;
+        if (!existsSync(lockPath)) {
+            // Holder finished without writing the sentinel (crashed). Try to take
+            // over the lock ourselves.
+            await withModelLock(lockPath, completionPath, work);
+            return;
+        }
+        await delay(LOCK_POLL_INTERVAL_MS);
+    }
+    // Stale lock — clear it and let the next caller (or our own retry above)
+    // pick up the work. Force unlinking is safer than leaving the cache
+    // permanently wedged.
+    try {
+        rmSync(lockPath, { force: true });
+    }
+    catch { /* best effort */ }
+    throw new Error(`fastembed: timed out after ${LOCK_TIMEOUT_MS}ms waiting for ${lockPath}. ` +
+        `Stale lock cleared — retry the operation.`);
+}
 /**
  * Ensure the per-model directory exists in the cache. Returns the absolute
  * path. If already present AND the completion sentinel is in place, no
@@ -86,25 +192,34 @@ async function downloadTarball(url, destPath, showProgress, deps) {
  */
 export async function retrieveModel(model, cacheDir, showProgress, deps = {}) {
     const modelDir = join(cacheDir, model);
-    if (existsSync(modelDir)) {
-        if (existsSync(join(modelDir, COMPLETION_SENTINEL)))
-            return modelDir;
-        if (showProgress) {
-            process.stderr.write(`fastembed: cached model at ${modelDir} is incomplete (no completion marker); redownloading.\n`);
-        }
-        rmSync(modelDir, { recursive: true, force: true });
-    }
+    const completionPath = join(modelDir, COMPLETION_SENTINEL);
+    // Fast path: complete cache hit needs no lock, no fs writes.
+    if (existsSync(completionPath))
+        return modelDir;
     mkdirSync(cacheDir, { recursive: true });
+    const lockPath = join(cacheDir, `.${model}.download.lock`);
     const tarballPath = join(cacheDir, `${model}.tar.gz`);
     const url = `${GCS_BASE_URL}/${gcsSlugFor(model)}.tar.gz`;
-    await downloadTarball(url, tarballPath, showProgress, deps);
-    const extract = deps.extract ?? tarExtract;
-    await extract({ file: tarballPath, cwd: cacheDir });
-    rmSync(tarballPath, { force: true });
-    if (!existsSync(modelDir)) {
-        throw new Error(`Model archive extracted but ${modelDir} is missing — corrupt tarball?`);
-    }
-    writeFileSync(join(modelDir, COMPLETION_SENTINEL), '');
+    await withModelLock(lockPath, completionPath, async () => {
+        // Re-check inside the lock — another process may have completed the
+        // download between our fast-path check and our lock acquisition.
+        if (existsSync(completionPath))
+            return;
+        if (existsSync(modelDir)) {
+            if (showProgress) {
+                process.stderr.write(`fastembed: cached model at ${modelDir} is incomplete (no completion marker); redownloading.\n`);
+            }
+            rmSync(modelDir, { recursive: true, force: true });
+        }
+        await downloadTarballWithRetry(url, tarballPath, showProgress, deps);
+        const extract = deps.extract ?? tarExtract;
+        await extract({ file: tarballPath, cwd: cacheDir });
+        rmSync(tarballPath, { force: true });
+        if (!existsSync(modelDir)) {
+            throw new Error(`Model archive extracted but ${modelDir} is missing — corrupt tarball?`);
+        }
+        writeFileSync(completionPath, '');
+    });
     return modelDir;
 }
 //# sourceMappingURL=model-loader.js.map

package/dist/src/cli/epic/runner-adapter.js

@@ -9,7 +9,7 @@
  */
 import * as readline from 'node:readline';
 import { loadSpellEngine, } from '../services/engine-loader.js';
-import { createDashboardMemoryAccessor } from '../services/daemon-dashboard.js';
+import { getSharedMemoryAccessor } from '../services/daemon-dashboard.js';
 /**
  * Wrap a MemoryAccessor with a write-failure counter so the [epic] summary
  * can warn when spell progress didn't reach disk (#982). Without this, a
@@ -56,17 +56,22 @@ async function promptAcceptPermissions() {
  */
 export async function runEpicSpell(yamlContent, options = {}) {
     const engine = await loadSpellEngine();
-    // Lazily initialize a real memory accessor so execution records
-    // are persisted and visible in the dashboard.
+    // Lazily wrap the process-wide shared accessor (#1020) so execution
+    // records are persisted and visible in the dashboard. The shared helper
+    // owns the warn-and-return-null degradation; we only attach the
+    // failed-write counter on top of a successful inner accessor.
     if (!memoryAccessor) {
-        try {
-            const inner = await createDashboardMemoryAccessor();
+        const inner = await getSharedMemoryAccessor();
+        if (inner) {
             memoryAccessor = trackPersistFailures(inner);
             console.log('[epic] Memory accessor ready — spell progress will be persisted');
         }
-        catch (err) {
-            console.warn(`[epic] ⚠ Dashboard memory unavailable: ${err.message ?? err}`);
-            console.warn('[epic] ⚠ Spell executions will NOT appear in the dashboard');
+        else {
+            // The shared helper already emitted `[memory]`-prefixed warns. Add an
+            // `[epic]`-tagged note so a user running `flo epic` can correlate the
+            // missing dashboard history with this command without scanning for a
+            // `[memory]` line elsewhere in the output.
+            console.warn('[epic] ⚠ Memory unavailable — this run will not appear in the dashboard');
         }
     }
     // memoryAccessor is module-cached, so `failedWrites` is cumulative across

package/dist/src/cli/mcp-tools/hive-mind-tools.js

@@ -719,9 +719,22 @@ export const hiveMindTools = [
                     workerCount,
                 };
             }
-            // Story #807: terminate coordinator-side worker records before we
-            // wipe the hive state so swarm agent_list reflects the shutdown.
-            // allSettled so one failed terminate doesn't strand the rest.
+            // #1017 — detach the adapter FIRST, before any code that broadcasts
+            // hive-mind events. terminateAgent below sends agent_terminate
+            // broadcasts on the hive-mind namespace; with the adapter still
+            // listening, those broadcasts register fire-and-forget storeEntry
+            // calls that can land after clearNamespace runs. Detaching first means
+            // every subsequent broadcast hits a dead listener and never persists,
+            // so clearNamespace operates on a deterministic, unchanging set.
+            const adapter = _writeThroughAdapter;
+            if (adapter) {
+                adapter.detach();
+                _writeThroughAdapter = null;
+            }
+            // Story #807: terminate coordinator-side worker records so swarm
+            // agent_list reflects the shutdown. allSettled so one failed terminate
+            // doesn't strand the rest. Broadcasts emitted here are intentionally
+            // ignored by the (now-detached) adapter.
             try {
                 const coordinator = await getSwarmCoordinator();
                 const results = await Promise.allSettled(hiveState.workers.map(id => coordinator.terminateAgent(id, { reason: 'hive-mind_shutdown', force: true })));
@@ -734,23 +747,24 @@ export const hiveMindTools = [
             catch (err) {
                 process.stderr.write(`[hive-mind_shutdown] coordinator cleanup failed: ${err.message}\n`);
             }
-            // Clear write-through namespaces in Memory DB
-            try {
-                const adapter = await getWriteThroughAdapter();
-                await adapter.clearNamespace(HIVE_NS);
-                await adapter.clearNamespace(HIVE_MEMORY_NS);
-            }
-            catch {
-                // Best-effort cleanup
+            // Drain whatever the adapter already had in flight at detach, then
+            // delete the persisted hive-mind rows. Routed through the chokepoint
+            // (deleteEntry → daemon RPC when alive), so the daemon's in-memory
+            // snapshot stays consistent with disk and cannot clobber the cleanup
+            // on its next flush.
+            if (adapter) {
+                try {
+                    await adapter.clearNamespace(HIVE_NS);
+                    await adapter.clearNamespace(HIVE_MEMORY_NS);
+                }
+                catch {
+                    // Best-effort cleanup
+                }
             }
             // Shutdown MessageBus for hive-mind
             try {
                 const bus = await getMessageBus();
                 bus.unsubscribe('hive-mind-system');
-                if (_writeThroughAdapter) {
-                    _writeThroughAdapter.detach();
-                    _writeThroughAdapter = null;
-                }
             }
             catch {
                 // Bus may not be initialized

package/dist/src/cli/mcp-tools/spell-tools.js

@@ -12,6 +12,7 @@ import { findProjectRoot } from '../services/project-root.js';
 import { buildGrimoire } from '../services/grimoire-builder.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { inferSpellTier } from '../spells/core/spell-tier.js';
+import { getSharedMemoryAccessor } from '../services/daemon-dashboard.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -53,16 +54,23 @@ function trackResult(tracked, result) {
     tracked.result = result;
     tracked.completedAt = new Date().toISOString();
 }
+// Memory accessor wiring (#1016): without `getSharedMemoryAccessor()`,
+// runner.storeProgress() writes go to noopMemory and The Luminarium's
+// "Flo Runs" tab never sees flo run / spell_cast invocations. The shared
+// accessor is the same singleton runner-adapter.ts uses for `flo epic`
+// (one cold init per process — see #1020).
 /** Execute a definition via the engine with tracking and error handling. */
 async function executeAndTrack(engine, definition, args, options = {}) {
     const spellId = `sp-${Date.now()}`;
     const tracked = trackStart(spellId, definition.name, definition.description);
     try {
         const sandboxConfig = await engine.loadSandboxConfigFromProject(findProjectRoot());
+        const memory = await getSharedMemoryAccessor();
         const result = await engine.bridgeExecuteSpell(definition, args, {
             spellId,
             sandboxConfig,
             forceCredentialReprompt: options.forceCredentialReprompt,
+            ...(memory ? { memory } : {}),
         });
         trackResult(tracked, result);
         return withSpellSource(serializeResult(result), options.sourceFile, options.tier);

package/dist/src/cli/services/daemon-dashboard.js

@@ -16,6 +16,46 @@ import { createServer } from 'node:http';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { handleMemoryStore, handleMemoryDelete, handleMemoryBatch, matchMemoryRpcRoute, } from './daemon-memory-rpc.js';
 export const DEFAULT_DASHBOARD_PORT = 3117;
+/**
+ * Process-wide promise for the shared MemoryAccessor. Memoized as a *promise*
+ * (not the resolved value) so concurrent first-callers share a single init
+ * — without this, two near-simultaneous calls would each kick off their own
+ * `createDashboardMemoryAccessor()` chain and the loser's accessor would
+ * leak. The race fix originated in #1016 inside `mcp-tools/spell-tools.ts`;
+ * #1020 lifted it into this shared helper so `epic/runner-adapter.ts` (which
+ * had the same latent race) and any future caller benefit from one cold
+ * init per process.
+ */
+let _sharedAccessorPromise = null;
+/**
+ * Return the process-wide MemoryAccessor, lazy-initialized on first call and
+ * cached as a promise thereafter. Returns `null` (with a warn log) if init
+ * fails so callers can degrade gracefully — the spell still runs, the user
+ * just doesn't see the run in The Luminarium.
+ */
+export function getSharedMemoryAccessor() {
+    if (_sharedAccessorPromise)
+        return _sharedAccessorPromise;
+    _sharedAccessorPromise = (async () => {
+        try {
+            return await createDashboardMemoryAccessor();
+        }
+        catch (err) {
+            console.warn(`[memory] dashboard accessor unavailable: ${err.message ?? err}`);
+            console.warn('[memory] runs will NOT appear in The Luminarium');
+            return null;
+        }
+    })();
+    return _sharedAccessorPromise;
+}
+/**
+ * Test-only: reset the cached promise so a subsequent call re-runs init.
+ * Production code MUST NOT call this — leaks the previous accessor's DB
+ * handle if the prior init succeeded.
+ */
+export function _resetSharedMemoryAccessorForTest() {
+    _sharedAccessorPromise = null;
+}
 /**
  * Create a MemoryAccessor backed by the sql.js/HNSW memory database.
  * Lazy-loads memory-initializer to avoid circular deps.

package/dist/src/cli/shared/utils/atomic-file-write.js

@@ -4,11 +4,21 @@
  * processes write to the same target concurrently.
  *
  * Pattern: write to a process-unique temp path `<target>.tmp.<pid>.<rand>`,
- * then rename onto `target`.
- *   - `fs.renameSync` is atomic on POSIX.
- *   - On Windows, Node maps it to `MoveFileExW(..., MOVEFILE_REPLACE_EXISTING)`,
- *     which replaces the destination near-atomically — concurrent readers
- *     always observe either the old file or the new, never a truncated one.
+ * **fsync the temp file**, then rename onto `target`.
+ *   - `writeFileSync` does NOT fsync — the OS keeps data in the write cache.
+ *     On Windows that cache isn't always coherent with what other processes
+ *     see when they open the freshly-renamed target. Issue #1015 surfaced
+ *     this as a flaky `memory-retrieve` race in consumer-smoke: process A
+ *     stores via the daemon → daemon flushes via this helper → daemon
+ *     returns → process B opens the DB and sees stale content.
+ *   - The fix: fsync the temp fd before rename. After fsync, the data is
+ *     durably on disk; the rename then makes that durable data visible
+ *     atomically. Subsequent readers see the new bytes regardless of cache
+ *     state.
+ *   - `fs.renameSync` is atomic on POSIX. On Windows, Node maps it to
+ *     `MoveFileExW(..., MOVEFILE_REPLACE_EXISTING)`, which replaces the
+ *     destination near-atomically — concurrent readers always observe either
+ *     the old file or the new, never a truncated one.
  *   - The unique temp path means concurrent writers can't clobber each other's
  *     in-flight bytes (#635). Last-writer-wins semantics: each rename is fully
  *     atomic, so the destination always reflects exactly one writer's data.
@@ -18,16 +28,28 @@
  * On any failure, the temp file is best-effort removed and the original
  * `target` stays intact. The underlying error is always re-thrown.
  *
+ * Windows-only post-rename verify (#1015): on NTFS with antivirus / Defender
+ * scanning the freshly-renamed file, a sub-process opening the same path
+ * within ~1s can briefly see the file as locked. After a successful rename
+ * we poll-open the target until it's readable (or a 250 ms deadline passes)
+ * so the next reader doesn't race the AV lock window. The rename itself
+ * already succeeded and the data is fsynced, so the verify is best-effort:
+ * a timeout returns silently rather than throwing.
+ *
  * `fs` is injectable so the interrupt-mid-write paths can be exercised in
  * unit tests without depending on ESM-unfriendly module spies.
  *
  * @module moflo/cli/shared/utils/atomic-file-write
  */
 import * as realFs from 'node:fs';
+const IS_WIN32 = process.platform === 'win32';
+const VERIFY_DEADLINE_MS = 250;
+const VERIFY_STEP_MS = 10;
 export function atomicWriteFileSync(targetPath, data, fs = realFs) {
     const tmpPath = `${targetPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
     try {
         fs.writeFileSync(tmpPath, data);
+        fsyncFile(tmpPath, fs);
         fs.renameSync(tmpPath, targetPath);
     }
     catch (err) {
@@ -39,5 +61,61 @@ export function atomicWriteFileSync(targetPath, data, fs = realFs) {
         }
         throw err;
     }
+    if (IS_WIN32)
+        verifyReadableAfterRename(targetPath, fs);
+}
+/**
+ * Open the freshly-written temp file, fsync, close. Ensures the data is
+ * durably on disk before rename makes it visible (#1015). Best-effort: an
+ * fsync error is swallowed because a real filesystem failure will surface
+ * on the rename anyway, and we don't want to mask the more useful error.
+ */
+function fsyncFile(tmpPath, fs) {
+    const openSync = fs.openSync ?? realFs.openSync;
+    const closeSync = fs.closeSync ?? realFs.closeSync;
+    const fsyncSync = fs.fsyncSync ?? realFs.fsyncSync;
+    let fd = null;
+    try {
+        fd = openSync(tmpPath, 'r+');
+        fsyncSync(fd);
+    }
+    catch {
+        /* fsync best-effort — see fn doc */
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* close best-effort */ }
+        }
+    }
+}
+/**
+ * Poll-open the target until a reader can succeed, or the deadline passes.
+ * Closes the AV-scan settle window on NTFS (#1015). No-op everywhere else.
+ *
+ * Yields the thread between probes via `Atomics.wait` so we don't pin a CPU
+ * during the very contention we're waiting out (`feedback_async_by_default`).
+ */
+function verifyReadableAfterRename(targetPath, fs) {
+    const openSync = fs.openSync ?? realFs.openSync;
+    const closeSync = fs.closeSync ?? realFs.closeSync;
+    const deadline = Date.now() + VERIFY_DEADLINE_MS;
+    while (true) {
+        try {
+            closeSync(openSync(targetPath, 'r'));
+            return;
+        }
+        catch {
+            if (Date.now() >= deadline)
+                return;
+            sleepSyncMs(VERIFY_STEP_MS);
+        }
+    }
+}
+const SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function sleepSyncMs(ms) {
+    Atomics.wait(SLEEP_BUF, 0, 0, ms);
 }
 //# sourceMappingURL=atomic-file-write.js.map

package/dist/src/cli/spells/connectors/mcp-client.js

@@ -5,8 +5,10 @@
  * lifecycle. This connector adds server-pool management, lazy spawning, tool
  * discovery caching, and the SpellConnector interface adapter.
  *
- * The SDK is an optionalDependency and is loaded lazily on first use so
- * consumers that don't use the MCP connector don't need it installed.
+ * The SDK is a hard `dependency` (MCP is a headline integration), but it is
+ * loaded lazily on first use so spells that don't use the MCP connector don't
+ * pay its startup cost. The lazy-load also yields an actionable install hint
+ * if a corrupted install lost the package.
  */
 import { loadOptional } from './shared/optional-import.js';
 const MCP_INSTALL_MSG = "MCP connector requires '@modelcontextprotocol/sdk' to be installed. Run: npm i @modelcontextprotocol/sdk";

package/dist/src/cli/spells/connectors/shared/optional-import.js

@@ -1,11 +1,18 @@
 /**
  * Lazy loader for optional SDK dependencies.
  *
- * Connectors wrapping heavy SDKs (imapflow, mailparser, @modelcontextprotocol/sdk)
- * declare them as optionalDependencies so consumers that don't use the connector
- * don't need to install them. This helper centralizes the lazy-import +
- * MODULE_NOT_FOUND translation + module-scope memoization that each connector
- * would otherwise re-implement.
+ * Connectors wrapping truly optional SDKs (imapflow, mailparser) declare them
+ * as `peerDependenciesMeta.optional` so consumers that don't use the connector
+ * don't need to install them. The `@modelcontextprotocol/sdk` is a hard
+ * `dependency` because the MCP connector is a headline feature, but it is still
+ * routed through this helper so a corrupted install still yields an actionable
+ * message instead of a raw MODULE_NOT_FOUND.
+ *
+ * Every specifier passed to `loadOptional()` MUST be declared in package.json
+ * (dependencies, optionalDependencies, or peerDependenciesMeta). The drift
+ * guard at `src/cli/__tests__/spells/connectors/optional-import-declared.test.ts`
+ * enforces this — it walks shipped connectors, extracts every specifier, and
+ * fails the build if one is undeclared.
  */
 const moduleCache = new Map();
 function isModuleNotFound(err) {

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.31';
+export const VERSION = '4.9.32';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.31",
+  "version": "4.9.32",
   "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",
@@ -64,6 +64,7 @@
   },
   "dependencies": {
     "@anush008/tokenizers": "^0.6.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "js-yaml": "^4.1.1",
     "lru-cache": "^11.3.5",
     "onnxruntime-node": "^1.24.3",
@@ -72,6 +73,18 @@
     "tar": "^7.5.11",
     "valibot": "^1.3.1"
   },
+  "peerDependencies": {
+    "imapflow": "^1.0.0",
+    "mailparser": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "imapflow": {
+      "optional": true
+    },
+    "mailparser": {
+      "optional": true
+    }
+  },
   "overrides": {
     "hono": ">=4.11.4",
     "picomatch": ">=2.3.2",
@@ -84,7 +97,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.30",
+    "moflo": "^4.9.31",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"