moflo 4.9.30 → 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/index.js

@@ -132,6 +132,20 @@ export class FlagEmbedding {
         const session = await InferenceSession.create(modelPath, {
             executionProviders: ['cpu'],
             graphOptimizationLevel: 'all',
+            // Suppress ORT's WARNING-level chatter on session bring-up. ORT 1.26.0
+            // emits a `[W:onnxruntime ... GetPciBusId] Skipping pci_bus_id` line on
+            // Linux Azure VMs whose `/sys/devices/...` filenames don't match the
+            // `[0-9a-f]+:[0-9a-f]+:[0-9a-f]+.[0-9a-f]+` PCI pattern; the warning
+            // is harmless (we run on the CPU EP only) but leaks to stderr and
+            // confuses users into thinking moflo is broken. 0=verbose, 1=info,
+            // 2=warning (default), 3=error, 4=fatal — error is the right level
+            // because session bring-up genuine failures still surface.
+            //
+            // Re-audit when bumping fastembed or onnxruntime-node: ORT
+            // occasionally promotes deprecation / model-compatibility notices to
+            // WARNING that would now be hidden. If a model upgrade ever lands
+            // alongside this suppression, drop to 2 once to scan the output.
+            logSeverityLevel: 3,
         });
         return new FlagEmbedding(tokenizer, session);
     }

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/memory/bridge-entries.js

@@ -112,6 +112,30 @@ export async function bridgeStoreEntry(options) {
         const now = Date.now();
         const guardResult = await guardValidate(registry, 'store', { key, namespace, size: value.length });
         if (!guardResult.allowed) {
+            // Dedupe rejection means the same `(op, params)` write just succeeded
+            // — the caller's data is already durable. Look up the existing row so
+            // we can return its id with success:true; this matches what the
+            // dedupe semantically means (a no-op, not a failure). Other rejection
+            // reasons (rate limit, etc.) remain real failures. Match the literal
+            // reason string rather than a substring regex so a future rejection
+            // worded with "duplicate mutation" but different semantics doesn't
+            // get silently swallowed.
+            if (guardResult.reason === 'duplicate mutation within dedupe window') {
+                let existingId = null;
+                const probe = ctx.db.prepare(`SELECT id FROM memory_entries WHERE namespace = ? AND key = ? AND status = 'active' LIMIT 1`);
+                try {
+                    probe.bind([namespace, key]);
+                    if (probe.step()) {
+                        existingId = String(probe.getAsObject().id);
+                    }
+                }
+                finally {
+                    probe.free();
+                }
+                if (existingId) {
+                    return { success: true, id: existingId };
+                }
+            }
             return { success: false, id, error: `MutationGuard rejected: ${guardResult.reason}` };
         }
         const resolved = await resolveBridgeEmbedding(value, options.precomputedEmbedding, options.generateEmbeddingFlag, namespace);
@@ -120,6 +144,48 @@ export async function bridgeStoreEntry(options) {
         }
         const { json: embeddingJson, dimensions, model } = resolved;
         const embeddingResponse = embeddingResponseFrom(resolved);
+        // Idempotency guard, mirrors the one in `memory-initializer.ts`'s raw-
+        // sql.js fallback. When the daemon route just wrote this exact row but
+        // the client missed the ack, we land here with the row already on disk;
+        // a plain INSERT would trip UNIQUE and surface as `[moflo] bridge
+        // operation failed:` stderr noise even though the data is durable.
+        // Probe first so withDb never sees the throw.
+        //
+        // Limitations carried forward: only `content` is compared, not `tags`
+        // or `ttl`. The targeted scenario is the same caller's request being
+        // processed twice (daemon write + client retry), where every option is
+        // identical by definition — a different caller varying `tags` after a
+        // missed-ack would still see this as an idempotent no-op rather than
+        // an update. `cached: false, attested: false` because the prior writer
+        // already ran post-persist bookkeeping; this process's in-memory cache
+        // stays cold for one retrieve until the read path warms it (perf only,
+        // not correctness).
+        if (!options.upsert) {
+            let existingId = null;
+            let existingContent = null;
+            const probe = ctx.db.prepare(`SELECT id, content FROM memory_entries WHERE namespace = ? AND key = ? AND status = 'active' LIMIT 1`);
+            try {
+                probe.bind([namespace, key]);
+                if (probe.step()) {
+                    const row = probe.getAsObject();
+                    existingId = String(row.id);
+                    existingContent = row.content;
+                }
+            }
+            finally {
+                probe.free();
+            }
+            if (existingId && existingContent === value) {
+                return {
+                    success: true,
+                    id: existingId,
+                    embedding: embeddingResponse,
+                    guarded: true,
+                    cached: false,
+                    attested: false,
+                };
+            }
+        }
         const insertSql = options.upsert
             ? `INSERT OR REPLACE INTO memory_entries (
           id, key, namespace, content, type,

package/dist/src/cli/memory/memory-initializer.js

@@ -1650,6 +1650,42 @@ export async function storeEntry(options) {
                 embeddingModel = embResult.model;
             }
         }
+        // Idempotency guard. By the time we reach the raw-sql.js fallback, an
+        // earlier write attempt — daemon route via `tryDaemonStore`, or bridge
+        // via `bridgeStoreEntry` — may have already persisted this exact row to
+        // disk. If a post-persist throw escaped the bridge's inner guards (#994,
+        // #982), `bridgeStoreEntry` returned null and we landed here. Re-running
+        // a plain INSERT would then trip the UNIQUE constraint on `(namespace,
+        // key)` and surface as `exit 1` even though the data is durable on disk
+        // — exactly the cascade described in `bridge-entries.ts:205`. If the
+        // existing row matches the value the caller asked us to write, treat
+        // this as a successful no-op and propagate the existing id instead of
+        // re-inserting. If the content differs, fall through to INSERT — the
+        // UNIQUE error is then a real "key already taken with other content"
+        // signal that the caller deserves to see.
+        if (!upsert) {
+            let existingRow = null;
+            const probe = db.prepare(`SELECT id, content FROM memory_entries WHERE namespace = ? AND key = ? AND status = 'active' LIMIT 1`);
+            try {
+                probe.bind([namespace, key]);
+                if (probe.step()) {
+                    existingRow = probe.getAsObject();
+                }
+            }
+            finally {
+                probe.free();
+            }
+            if (existingRow && existingRow.content === value) {
+                db.close();
+                return {
+                    success: true,
+                    id: String(existingRow.id),
+                    embedding: embeddingJson
+                        ? { dimensions: embeddingDimensions, model: embeddingModel }
+                        : undefined,
+                };
+            }
+        }
         // Insert or update entry (upsert mode uses REPLACE)
         const insertSql = upsert
             ? `INSERT OR REPLACE INTO memory_entries (

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/spells/core/credential-validation.js

@@ -1,24 +1,31 @@
 /**
  * Credential Validation
  *
- * Lightweight, no-config shape checks applied to values pulled from the
- * encrypted credential store before they are promoted to `process.env`.
+ * Shape checks applied to values pulled from the encrypted credential store
+ * before they are promoted to `process.env`. Two layers:
  *
- * Two heuristics, both conservative — only invalidate when there is
- * positive evidence the stored value is bad. Anything we can't classify
- * passes through unchanged.
+ *   1. **Author-declared format** (preferred): the YAML prereq sets
+ *      `format: jwt`, and the validator enforces JWT shape + expiry. Any
+ *      non-JWT value (e.g. a value with no dots) is rejected outright,
+ *      catching the failure mode where a stored value isn't even a JWT
+ *      and the spell would otherwise fail mid-cast with a 401.
  *
- *   - JWT-shaped values (3 base64url segments) get their `exp` claim
- *     parsed and compared to "now". An expired JWT is reported as such.
- *   - Env keys ending in `_URL` must parse via the WHATWG `URL`
- *     constructor and have a non-empty host.
+ *   2. **Conservative heuristics** (fallback when no format is declared):
+ *        - JWT-shaped values (3 base64url segments) get their `exp` claim
+ *          parsed and rejected when expired.
+ *        - Env keys ending in `_URL` must parse via the WHATWG `URL`
+ *          constructor and have a non-empty host.
+ *      Anything else passes through.
  *
- * Story #1007: avoid silently reusing stale stored credentials (e.g.
- * Microsoft Graph access tokens, which expire in ~1h) so the resolver
- * can fall through to the prompt path and the user understands why.
+ * Story #1007: catch expired JWTs that survived past their TTL.
+ * Story #1009: extend to catch values that aren't even JWT-shaped when
+ * the prereq has declared `format: jwt`.
  */
 const VALID_JWT_SEGMENT = /^[A-Za-z0-9_-]+$/;
-export function validateStoredCredential(envKey, value) {
+export function validateStoredCredential(envKey, value, format) {
+    if (format === 'jwt') {
+        return validateJwtFormat(value);
+    }
     if (envKey.endsWith('_URL')) {
         return validateUrlValue(value);
     }
@@ -27,6 +34,15 @@ export function validateStoredCredential(envKey, value) {
     }
     return { valid: true };
 }
+function validateJwtFormat(value) {
+    if (!looksLikeJwt(value)) {
+        return {
+            valid: false,
+            reason: 'stored value is not a JWT (expected three base64url segments separated by ".")',
+        };
+    }
+    return validateJwtExpiry(value);
+}
 function validateUrlValue(value) {
     try {
         const parsed = new URL(value);

package/dist/src/cli/spells/core/prerequisite-checker.js

@@ -72,6 +72,7 @@ export function compilePrerequisiteSpec(spec) {
         description: spec.description,
         promptOnMissing,
         envKey,
+        format: spec.format,
     };
 }
 function defaultHintForDetect(spec) {
@@ -205,7 +206,7 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
             const stored = await credentials.get(prereq.envKey);
             if (typeof stored !== 'string' || stored.length === 0)
                 return;
-            const validation = validateStoredCredential(prereq.envKey, stored);
+            const validation = validateStoredCredential(prereq.envKey, stored, prereq.format);
             if (!validation.valid) {
                 rejectedFromStore.push({ envKey: prereq.envKey, reason: validation.reason });
                 return;

package/dist/src/cli/spells/schema/validators/prerequisites.js

@@ -6,6 +6,7 @@
  * deliberately small so step validation can delegate here.
  */
 const VALID_DETECT_TYPES = ['env', 'command', 'file'];
+const VALID_FORMATS = ['jwt'];
 export function validatePrerequisites(prereqs, errors, path) {
     if (!Array.isArray(prereqs)) {
         errors.push({ path, message: 'prerequisites must be an array' });
@@ -39,6 +40,13 @@ export function validatePrerequisites(prereqs, errors, path) {
         if (p.promptOnMissing !== undefined && typeof p.promptOnMissing !== 'boolean') {
             errors.push({ path: `${pPath}.promptOnMissing`, message: 'promptOnMissing must be a boolean' });
         }
+        if (p.format !== undefined
+            && !VALID_FORMATS.includes(p.format)) {
+            errors.push({
+                path: `${pPath}.format`,
+                message: `format must be one of: ${VALID_FORMATS.join(', ')}`,
+            });
+        }
         const detect = p.detect;
         if (!detect || typeof detect !== 'object') {
             errors.push({ path: `${pPath}.detect`, message: 'detect is required and must be an object' });
@@ -66,6 +74,14 @@ export function validatePrerequisites(prereqs, errors, path) {
                 errors.push({ path: `${pPath}.detect.path`, message: 'detect.path is required for file detector' });
             }
         }
+        // `format` only applies to stored env values — silently ignoring it on
+        // command/file detectors would mask author mistakes.
+        if (p.format !== undefined && detect.type !== 'env') {
+            errors.push({
+                path: `${pPath}.format`,
+                message: 'format is only valid on env-type prerequisites',
+            });
+        }
     });
 }
 //# sourceMappingURL=prerequisites.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.30';
+export const VERSION = '4.9.32';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.30",
+  "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.29",
+    "moflo": "^4.9.31",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"