moflo 4.10.1 → 4.10.2

package/.claude/skills/healer/SKILL.md

@@ -30,7 +30,9 @@ Thin wrapper around the `flo healer` CLI. All check + fix logic lives in the CLI
    - `✓ N passing` (count only)
    - `⚠ warnings` — list `name: message`; flag with `[auto-fixable]` when the result has a `fix` field
    - `✗ failures` — same
-   - If `--fix` mode, also list which fixes were applied vs which need manual action.
+   - If `--fix` mode, read `fixesApplied[]` from the JSON payload and list `{name, applied}` per entry — applied=true → "fixed", applied=false → "needs manual action". The `results[]` array is post-fix state (re-evaluated), so report the final status.
+   - If `--install` was passed, surface `claudeCodeInstall.installed` from the payload.
+   - If `--kill-zombies` was passed, surface `zombieScan.killed` / `zombieScan.found` from the payload.
 
 4. **Nudge based on what changed.** Only mention next steps for state that *actually* changed:
    - Daemon restarted → `Statusline should refresh within ~5s.`

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

@@ -144,7 +144,33 @@ async function runMemoryRoundTrip(ctx) {
     }
     else {
         const top = searchOut.results?.find(r => r.key === key);
-        pushDetail(ctx.details, { id: `${ctx.idPrefix}.search-finds-key`, mcpTool: 'memory_search', expected: `result containing key=${key}` }, top ? { topKey: top.key, similarity: top.similarity } : { allKeys: searchOut.results?.map(r => r.key) }, top ? null : `stored key ${key} not in results (got: ${searchOut?.results?.map(r => r.key).join(', ') ?? 'none'})`);
+        if (top) {
+            pushDetail(ctx.details, { id: `${ctx.idPrefix}.search-finds-key`, mcpTool: 'memory_search', expected: `result containing key=${key}` }, { topKey: top.key, similarity: top.similarity }, null);
+        }
+        else {
+            // #1120: search returned results but our just-stored key wasn't among
+            // them. Mirrors the #1111 empty-HNSW fallback for the non-zero case:
+            // if the row IS reachable by literal key, demote to warn — memory
+            // access works, the HNSW index just hasn't propagated the new write
+            // yet (stale-neighbor race when healer runs 2+ times in one session
+            // against accumulated probe rows). If literal retrieve also fails,
+            // surface the original fail unchanged.
+            const otherKeys = searchOut?.results?.map(r => r.key).join(', ') ?? 'none';
+            const retrievable = await literalKeyReachable(ctx.memoryTools, key, namespace);
+            if (retrievable) {
+                ctx.details.push({
+                    id: `${ctx.idPrefix}.search-finds-key`,
+                    mcpTool: 'memory_search',
+                    status: 'warn',
+                    observed: { topKeys: searchOut?.results?.map(r => r.key), retrievable: true },
+                    expected: `result containing key=${key}`,
+                    message: `search returned results but our key was not among them (got: ${otherKeys}); row IS reachable by literal retrieve — HNSW stale-neighbor race (newly-written row not yet propagated to the index). Memory access path works.`,
+                });
+            }
+            else {
+                pushDetail(ctx.details, { id: `${ctx.idPrefix}.search-finds-key`, mcpTool: 'memory_search', expected: `result containing key=${key}` }, { allKeys: searchOut.results?.map(r => r.key) }, `stored key ${key} not in results (got: ${otherKeys})`);
+            }
+        }
     }
     // 4. memory_retrieve returns the full value (search content is truncated
     // to a 60-char snippet). Catches write clobber and namespace bleed — we

package/dist/src/cli/commands/doctor-embedding-hygiene.js

@@ -16,6 +16,13 @@
  *      vectors. The Story-2 self-healing migration converges every active
  *      row on the canonical label; this check verifies it actually did.
  *
+ * Story #729 carve-out: ephemeral-namespace rows (tasklist, hive-mind,
+ * epic-state, test-bridge-fix, plus EPHEMERAL_NAMESPACE_PREFIXES) are
+ * intentionally written with `embedding IS NULL AND embedding_model IS
+ * NULL`. They are excluded from the count so they don't trip branch (4)
+ * "unrecognised embedding_model" on every publish — see bridge-embedder.ts
+ * for the writer-side rationale.
+ *
  * Lives next to the doctor command rather than in `doctor.ts` to keep that
  * file under the 500-line decomposition target.
  *
@@ -26,6 +33,7 @@ import { existsSync } from 'fs';
 import { CANONICAL_EMBEDDING_MODEL } from '../embeddings/migration/types.js';
 import { memoryDbCandidatePaths } from '../services/moflo-paths.js';
 import { openDaemonDatabase } from '../memory/daemon-backend.js';
+import { EPHEMERAL_NAMESPACES, EPHEMERAL_NAMESPACE_PREFIXES, } from '../memory/bridge-embedder.js';
 /**
  * Known neural-model labels that all share the all-MiniLM-L6-v2 384-dim
  * vector space. The Story-2 migration retags any of these to the
@@ -155,23 +163,51 @@ async function loadModelGroups(dbPath) {
         }
         if (!hasSchema)
             return [];
-        const groups = [];
-        const result = db.exec(`SELECT
+        // Story #729: ephemeral-namespace rows (tasklist, hive-mind, epic-state,
+        // …) are intentionally written with `embedding IS NULL AND
+        // embedding_model IS NULL`. Without this exclusion every spell run that
+        // logs to `tasklist` re-trips branch (4) "unrecognised embedding_model"
+        // on the next publish, even though the writer is doing the right thing.
+        const ephemeralNames = [...EPHEMERAL_NAMESPACES];
+        const ephemeralPrefixes = [...EPHEMERAL_NAMESPACE_PREFIXES];
+        const matchClauses = [];
+        const params = [];
+        if (ephemeralNames.length > 0) {
+            matchClauses.push(`namespace IN (${ephemeralNames.map(() => '?').join(', ')})`);
+            params.push(...ephemeralNames);
+        }
+        for (const prefix of ephemeralPrefixes) {
+            matchClauses.push(`namespace LIKE ?`);
+            params.push(`${prefix}%`);
+        }
+        const ephemeralExclusion = matchClauses.length > 0
+            ? `AND NOT (embedding IS NULL AND embedding_model IS NULL AND (${matchClauses.join(' OR ')}))`
+            : '';
+        const sql = `SELECT
          COALESCE(embedding_model, 'NULL') AS model,
          COUNT(*) AS n,
          SUM(CASE WHEN embedding IS NULL THEN 1 ELSE 0 END) AS null_count
        FROM memory_entries
        WHERE status = 'active'
-       GROUP BY model`);
-        if (!result || result.length === 0)
-            return [];
-        const rows = result[0]?.values ?? [];
-        for (const row of rows) {
-            groups.push({
-                model: String(row[0]),
-                count: Number(row[1]),
-                hasNullEmbedding: Number(row[2]) > 0,
-            });
+       ${ephemeralExclusion}
+       GROUP BY model`;
+        const groups = [];
+        const stmt = db.prepare(sql);
+        try {
+            stmt.bind(params);
+            while (stmt.step()) {
+                const row = stmt.get();
+                if (Array.isArray(row)) {
+                    groups.push({
+                        model: String(row[0]),
+                        count: Number(row[1]),
+                        hasNullEmbedding: Number(row[2]) > 0,
+                    });
+                }
+            }
+        }
+        finally {
+            stmt.free();
         }
         return groups;
     }

package/dist/src/cli/commands/doctor-render.js

@@ -19,66 +19,95 @@ function tally(results) {
         failed: results.filter(r => r.status === 'fail').length,
     };
 }
-export async function runKillZombiesBanner() {
-    output.writeln(output.bold('Zombie Process Scan'));
-    output.writeln();
+/**
+ * Run the kill-zombies scan, with optional rendering. Issue #1122: in JSON
+ * mode the prose banner would corrupt the single-document contract, so the
+ * caller passes `silent: true` and surfaces the structured result inside the
+ * JSON payload instead.
+ */
+export async function runKillZombies(opts = {}) {
+    const silent = !!opts.silent;
+    if (!silent) {
+        output.writeln(output.bold('Zombie Process Scan'));
+        output.writeln();
+    }
     const registryKilled = killTrackedProcesses();
-    if (registryKilled > 0) {
+    if (!silent && registryKilled > 0) {
         output.writeln(output.success(`  Killed ${registryKilled} tracked background process(es) from registry`));
     }
     // Single OS-level scan + kill — the previous flow scanned twice.
     const result = await findZombieProcesses(true);
     const found = result.details.length;
-    if (found === 0) {
-        if (registryKilled === 0) {
-            output.writeln(output.success('  No orphaned moflo processes found'));
-        }
-    }
-    else {
-        output.writeln(output.warning(`  Found ${found} additional orphaned process(es):`));
-        for (const d of result.details) {
-            output.writeln(output.dim(`    ${formatZombieDetail(d)}`));
-        }
-        if (result.killed > 0) {
-            output.writeln(output.success(`  Killed ${result.killed} zombie process(es)`));
+    if (!silent) {
+        if (found === 0) {
+            if (registryKilled === 0) {
+                output.writeln(output.success('  No orphaned moflo processes found'));
+            }
         }
-        if (result.killed < found) {
-            output.writeln(output.warning(`  ${found - result.killed} process(es) could not be killed`));
+        else {
+            output.writeln(output.warning(`  Found ${found} additional orphaned process(es):`));
+            for (const d of result.details) {
+                output.writeln(output.dim(`    ${formatZombieDetail(d)}`));
+            }
+            if (result.killed > 0) {
+                output.writeln(output.success(`  Killed ${result.killed} zombie process(es)`));
+            }
+            if (result.killed < found) {
+                output.writeln(output.warning(`  ${found - result.killed} process(es) could not be killed`));
+            }
         }
+        output.writeln();
+        output.writeln(output.dim('─'.repeat(50)));
+        output.writeln();
     }
-    output.writeln();
-    output.writeln(output.dim('─'.repeat(50)));
-    output.writeln();
+    return { registryKilled, found, killed: result.killed, details: result.details };
 }
 /**
  * Issue #818: machine-readable output. Emits a single JSON document with
  * per-check fields (and any FunctionalCheckDetail entries from the swarm/
- * hive checks) and exits with the right code. Skips auto-fix entirely —
- * --json is read-only by intent so CI gates can consume it without
- * mutating the working tree.
+ * hive checks) and exits with the right code.
+ *
+ * Issue #1122: action flags (`--fix`, `--install`, `--kill-zombies`) now run
+ * before this is called and their outcomes are passed in so automation can
+ * tell what changed without re-parsing prose. `results` reflects post-fix
+ * state when `fixesApplied` includes any successful fix.
  */
-export function emitJsonOutput({ results, strict, allowWarnList }) {
+export function emitJsonOutput({ results, strict, allowWarnList, fixesApplied, zombieScan, claudeCodeInstall, }) {
     const { passed, warnings, failed } = tally(results);
     const allowSet = new Set(allowWarnList);
     const strictWarningFailures = strict
         ? results.filter(r => r.status === 'warn' && !allowSet.has(r.name)).map(r => r.name)
         : [];
     const exitCode = failed > 0 || strictWarningFailures.length > 0 ? 1 : 0;
-    process.stdout.write(JSON.stringify({
+    const payload = {
         summary: { passed, warnings, failed },
         strict: strict ? { strictMode: true, warningsTriggeringFail: strictWarningFailures } : { strictMode: false },
         results,
-    }, null, 2) + '\n');
+    };
+    if (fixesApplied !== undefined)
+        payload.fixesApplied = fixesApplied;
+    if (zombieScan !== undefined)
+        payload.zombieScan = zombieScan;
+    if (claudeCodeInstall !== undefined)
+        payload.claudeCodeInstall = claudeCodeInstall;
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
     return { success: exitCode === 0, exitCode, data: { passed, warnings, failed, results } };
 }
-/** Re-runs Claude Code CLI install + check if --install was passed and the prior result wasn't pass. */
-export async function maybeAutoInstallClaudeCode(results, fixes) {
+/**
+ * Re-runs Claude Code CLI install + check if --install was passed and the
+ * prior result wasn't pass. Issue #1122: accepts `{silent}` so the JSON path
+ * runs the install without writing prose to the corrupted stdout, and
+ * returns a structured outcome for inclusion in the JSON document.
+ */
+export async function maybeAutoInstallClaudeCode(results, fixes, opts = {}) {
+    const silent = !!opts.silent;
     const claudeCodeResult = results.find(r => r.name === 'Claude Code CLI');
-    if (!claudeCodeResult || claudeCodeResult.status === 'pass')
-        return;
+    if (!claudeCodeResult || claudeCodeResult.status === 'pass') {
+        return { attempted: false, installed: false };
+    }
     const installed = await installClaudeCode();
     if (!installed)
-        return;
+        return { attempted: true, installed: false };
     const newCheck = await checkClaudeCode();
     const idx = results.findIndex(r => r.name === 'Claude Code CLI');
     if (idx !== -1) {
@@ -88,7 +117,9 @@ export async function maybeAutoInstallClaudeCode(results, fixes) {
             fixes.splice(fixIdx, 1);
         }
     }
-    output.writeln(formatCheck(newCheck));
+    if (!silent)
+        output.writeln(formatCheck(newCheck));
+    return { attempted: true, installed: true, postCheck: newCheck };
 }
 export function renderSummary(results) {
     const counts = tally(results);
@@ -103,62 +134,75 @@ export function renderSummary(results) {
     output.writeln(`Summary: ${summaryParts.join(', ')}`);
     return counts;
 }
-/** Auto-fix loop, including the post-fix re-run. Mutates `results` and `fixes` in place when fixes succeed. */
-export async function runAutoFix(results, fixes, checksToRun) {
+/**
+ * Auto-fix loop, including the post-fix re-run. Mutates `results` and `fixes`
+ * in place when fixes succeed and returns a structured outcome.
+ *
+ * Issue #1122: accepts `{silent}` so the JSON path can run the same fix work
+ * without writing prose to a stubbed stdout, and emit `fixesApplied` +
+ * post-fix `results` from the returned data.
+ */
+export async function runAutoFix(results, fixes, checksToRun, opts = {}) {
+    const silent = !!opts.silent;
     if (fixes.length === 0)
-        return;
-    output.writeln();
-    output.writeln(output.bold('Auto-fixing issues...'));
-    output.writeln();
+        return { fixesApplied: [], reEvaluated: null };
+    if (!silent) {
+        output.writeln();
+        output.writeln(output.bold('Auto-fixing issues...'));
+        output.writeln();
+    }
     const fixableResults = results.filter(r => r.fix && (r.status === 'fail' || r.status === 'warn'));
-    let fixed = 0;
-    const unfixed = [];
+    const fixesApplied = [];
     for (const check of fixableResults) {
         const success = await autoFixCheck(check);
-        if (success) {
-            fixed++;
+        fixesApplied.push({ name: check.name, applied: success });
+    }
+    const fixed = fixesApplied.filter(f => f.applied).length;
+    const unfixed = fixesApplied.filter(f => !f.applied);
+    if (!silent) {
+        if (fixed > 0) {
+            output.writeln();
+            output.writeln(output.success(`Auto-fixed ${fixed} issue${fixed > 1 ? 's' : ''}`));
         }
-        else {
-            unfixed.push(`${check.name}: ${check.fix}`);
+        if (unfixed.length > 0) {
+            output.writeln();
+            output.writeln(output.bold('Manual fixes needed:'));
+            const fixByName = new Map(fixableResults.map(r => [r.name, r.fix ?? '']));
+            for (const f of unfixed) {
+                output.writeln(output.dim(`  ${f.name}: ${fixByName.get(f.name) ?? ''}`));
+            }
         }
     }
-    if (fixed > 0) {
+    if (fixed === 0)
+        return { fixesApplied, reEvaluated: null };
+    const reSettled = await Promise.allSettled(checksToRun.map(check => check()));
+    const reEvaluated = reSettled.map((sr) => sr.status === 'fulfilled'
+        ? sr.value
+        : { name: 'Check', status: 'fail', message: sr.reason?.message ?? 'Unknown error' });
+    if (!silent) {
         output.writeln();
-        output.writeln(output.success(`Auto-fixed ${fixed} issue${fixed > 1 ? 's' : ''}`));
-    }
-    if (unfixed.length > 0) {
+        output.writeln(output.dim('Re-checking...'));
         output.writeln();
-        output.writeln(output.bold('Manual fixes needed:'));
-        for (const fix of unfixed) {
-            output.writeln(output.dim(`  ${fix}`));
-        }
-    }
-    if (fixed === 0)
-        return;
-    output.writeln();
-    output.writeln(output.dim('Re-checking...'));
-    output.writeln();
-    const reResults = await Promise.allSettled(checksToRun.map(check => check()));
-    let rePassed = 0, reWarnings = 0, reFailed = 0;
-    for (const sr of reResults) {
-        if (sr.status === 'fulfilled') {
-            output.writeln(formatCheck(sr.value));
-            if (sr.value.status === 'pass')
+        let rePassed = 0, reWarnings = 0, reFailed = 0;
+        for (const r of reEvaluated) {
+            output.writeln(formatCheck(r));
+            if (r.status === 'pass')
                 rePassed++;
-            else if (sr.value.status === 'warn')
+            else if (r.status === 'warn')
                 reWarnings++;
             else
                 reFailed++;
         }
+        output.writeln();
+        output.writeln(output.dim('─'.repeat(50)));
+        const reSummary = [
+            output.success(`${rePassed} passed`),
+            reWarnings > 0 ? output.warning(`${reWarnings} warnings`) : null,
+            reFailed > 0 ? output.error(`${reFailed} failed`) : null,
+        ].filter(Boolean);
+        output.writeln(`After fix: ${reSummary.join(', ')}`);
     }
-    output.writeln();
-    output.writeln(output.dim('─'.repeat(50)));
-    const reSummary = [
-        output.success(`${rePassed} passed`),
-        reWarnings > 0 ? output.warning(`${reWarnings} warnings`) : null,
-        reFailed > 0 ? output.error(`${reFailed} failed`) : null,
-    ].filter(Boolean);
-    output.writeln(`After fix: ${reSummary.join(', ')}`);
+    return { fixesApplied, reEvaluated };
 }
 /**
  * Build the final CommandResult based on pass/warn/fail counts and --strict

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

@@ -12,7 +12,7 @@
  */
 import { output } from '../output.js';
 import { allChecks, componentMap, zombieScanCheck } from './doctor-registry.js';
-import { emitJsonOutput, finalize, formatCheck, maybeAutoInstallClaudeCode, renderSummary, runAutoFix, runKillZombiesBanner, } from './doctor-render.js';
+import { emitJsonOutput, finalize, formatCheck, maybeAutoInstallClaudeCode, renderSummary, runAutoFix, runKillZombies, } from './doctor-render.js';
 import { checkEmbeddings } from './doctor-checks-memory.js';
 import { checkMofloYamlCompliance } from './doctor-checks-config.js';
 // Re-export for tests + external consumers (#639 stale-vector-stats test
@@ -125,24 +125,21 @@ export const doctorCommand = {
             output.writeln(output.warning('--allow-warn requires --strict; ignoring (warnings are tolerated by default).'));
             output.writeln();
         }
-        if (killZombies) {
-            await runKillZombiesBanner();
-        }
         const checksToRun = component && componentMap[component]
             ? [componentMap[component]]
             : allChecks;
         const results = [];
         const fixes = [];
-        // OPTIMIZATION: Run all checks in parallel for 3-5x faster execution
-        const spinner = jsonOutput
-            ? null
-            : output.createSpinner({ text: 'Running health checks in parallel...', spinner: 'dots' });
-        spinner?.start();
+        let zombieScan;
+        let claudeCodeInstall;
+        let fixesApplied;
         // Issue #818: in --json mode, several deep checks (spell engine probe,
         // mcp-spell bridge, etc.) write `[spell] ...` log lines straight to
         // stdout — that breaks the single-JSON-document contract. Capture and
-        // discard stdout writes while checks run; restore in `finally` so a
-        // throw can't leave the process with a stubbed stdout.
+        // discard stdout writes while checks AND post-check actions run; restore
+        // in `finally` so a throw can't leave the process with a stubbed stdout.
+        // Issue #1122: extended to wrap zombie-kill banner, --install, and
+        // --fix work so each runs on the JSON path with prose suppressed.
         const realStdoutWrite = process.stdout.write.bind(process.stdout);
         const restoreStdout = () => {
             if (jsonOutput) {
@@ -153,7 +150,18 @@ export const doctorCommand = {
             process.stdout.write =
                 (..._args) => true;
         }
+        // OPTIMIZATION: Run all checks in parallel for 3-5x faster execution
+        const spinner = jsonOutput
+            ? null
+            : output.createSpinner({ text: 'Running health checks in parallel...', spinner: 'dots' });
         try {
+            // Issue #1122: kill-zombies prose used to write BEFORE the JSON
+            // suppression activated, corrupting the JSON document. Now runs
+            // under suppression and feeds a structured result into the payload.
+            if (killZombies) {
+                zombieScan = await runKillZombies({ silent: jsonOutput });
+            }
+            spinner?.start();
             let checkResults;
             try {
                 checkResults = await Promise.allSettled(checksToRun.map(check => check()));
@@ -174,7 +182,6 @@ export const doctorCommand = {
             }
             finally {
                 spinner?.stop();
-                restoreStdout();
             }
             for (const settledResult of checkResults) {
                 if (settledResult.status === 'fulfilled') {
@@ -197,26 +204,64 @@ export const doctorCommand = {
                         output.writeln(formatCheck(errorResult));
                 }
             }
+            // Issue #1122: action flags must run on BOTH the JSON path and the
+            // formatted path. Previously the JSON branch early-returned before
+            // any of this ran, so `--json --fix` (and `--json --install`) silently
+            // no-op'd. Now they execute under stdout suppression and their
+            // outcomes feed the JSON payload below.
+            if (autoInstall) {
+                claudeCodeInstall = await maybeAutoInstallClaudeCode(results, fixes, { silent: jsonOutput });
+            }
+            if (!jsonOutput)
+                renderSummary(results);
+            if (showFix && fixes.length > 0) {
+                const outcome = await runAutoFix(results, fixes, checksToRun, { silent: jsonOutput });
+                fixesApplied = outcome.fixesApplied;
+                // Replace `results` with post-fix state so JSON consumers see the
+                // re-evaluated truth, not the pre-fix snapshot. Mirror the #992
+                // post-parallel zombie-scan append so the post-fix shape matches
+                // pre-fix shape (otherwise `--json --fix` silently drops the
+                // Zombie Processes entry from the JSON `results[]`).
+                if (outcome.reEvaluated) {
+                    const finalChecks = [...outcome.reEvaluated];
+                    if (!component) {
+                        try {
+                            finalChecks.push(await zombieScanCheck());
+                        }
+                        catch (reason) {
+                            finalChecks.push({
+                                name: 'Zombie Processes',
+                                status: 'fail',
+                                message: reason?.message ?? 'Unknown error',
+                            });
+                        }
+                    }
+                    results.length = 0;
+                    results.push(...finalChecks);
+                }
+            }
+            else if (fixes.length > 0 && !showFix && !jsonOutput) {
+                output.writeln();
+                output.writeln(output.dim(`Run with --fix to auto-fix ${fixes.length} issue${fixes.length > 1 ? 's' : ''}`));
+            }
         }
         catch {
             spinner?.stop();
-            restoreStdout();
             if (!jsonOutput)
                 output.writeln(output.error('Failed to run health checks'));
         }
-        if (jsonOutput) {
-            return emitJsonOutput({ results, strict, allowWarnList });
-        }
-        if (autoInstall) {
-            await maybeAutoInstallClaudeCode(results, fixes);
-        }
-        renderSummary(results);
-        if (showFix && fixes.length > 0) {
-            await runAutoFix(results, fixes, checksToRun);
+        finally {
+            restoreStdout();
         }
-        else if (fixes.length > 0 && !showFix) {
-            output.writeln();
-            output.writeln(output.dim(`Run with --fix to auto-fix ${fixes.length} issue${fixes.length > 1 ? 's' : ''}`));
+        if (jsonOutput) {
+            return emitJsonOutput({
+                results,
+                strict,
+                allowWarnList,
+                fixesApplied,
+                zombieScan,
+                claudeCodeInstall,
+            });
         }
         return finalize({ results, strict, allowWarnList });
     },

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

@@ -95,6 +95,27 @@ export function logBridgeError(context, err, opts) {
     const msg = errorDetail(err);
     console.error(`[moflo] ${context}: ${msg}`);
 }
+/**
+ * Recognises the node:sqlite "operation on closed handle" error shape.
+ *
+ * #1123 — A concurrent `withDb` call's `checkBridgeCoherence` can fire
+ * `shutdownBridge()` between our `getDb(registry)` and `fn(ctx, registry)`,
+ * closing the underlying `DatabaseSync`. Our previously-captured `ctx.db`
+ * then throws `ERR_INVALID_STATE: database is not open` on the next op.
+ *
+ * The operation hadn't started its mutation yet, so a single retry against a
+ * fresh registry is safe (matches the `withBusyRetry` shape for SQLITE_BUSY).
+ * Bounded to one retry so a *genuinely* broken DB still surfaces — we don't
+ * want to mask a registry that can't be re-acquired.
+ */
+function isStaleHandleError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.code === 'ERR_INVALID_STATE')
+        return true;
+    return typeof e.message === 'string' && /database is not open/i.test(e.message);
+}
 /**
  * Treats an error as a SQLITE_BUSY lock-contention failure if either the
  * error code or message indicates it. Belt-and-suspenders around node:sqlite,
@@ -456,6 +477,9 @@ async function checkBridgeCoherence(dbPath) {
  * self-fire is suppressed.
  */
 export async function withDb(dbPath, fn) {
+    return withDbInner(dbPath, fn, 0);
+}
+async function withDbInner(dbPath, fn, attempt) {
     await checkBridgeCoherence(dbPath);
     const registry = await getRegistry(dbPath);
     if (!registry)
@@ -510,6 +534,18 @@ export async function withDb(dbPath, fn) {
         return result;
     }
     catch (err) {
+        // #1123 — stale-handle race: a concurrent withDb's coherence check tore
+        // the registry down between our getDb() and fn() execution, closing the
+        // underlying DatabaseSync. Drop the dead handle and retry once against a
+        // freshly-acquired registry. The first attempt threw BEFORE its mutation
+        // landed (node:sqlite errors at prepare/exec time, not mid-statement), so
+        // a retry is idempotent. Bounded to one retry so a genuinely-unrecoverable
+        // bridge (e.g. corrupt file, missing module) still surfaces as a null
+        // return + logged error, not an infinite loop.
+        if (attempt === 0 && isStaleHandleError(err)) {
+            await shutdownBridge();
+            return await withDbInner(dbPath, fn, attempt + 1);
+        }
         logBridgeError('bridge operation failed', err);
         return null;
     }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.1",
+  "version": "4.10.2",
   "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",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.10.0",
+    "moflo": "^4.10.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"