moflo 4.9.25 → 4.9.27

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

@@ -1,7 +1,7 @@
 ---
 name: healer
 description: Run moflo's Healer (`flo healer`, alias for `flo doctor`) from inside the Claude session. Audit-only by default; pass `--fix` to apply auto-repairs, `-c <component>` for a single check. Use when something feels off (missing moflo.yaml, daemon dead, statusline empty, hooks not firing) or as a periodic health check. Distinct from Claude Code's built-in `/doctor`, which diagnoses Claude Code itself, not moflo.
-arguments: "[--fix] [-c <component>]"
+arguments: "[options]"
 ---
 
 # /healer — moflo Installation Healer
@@ -43,7 +43,7 @@ Thin wrapper around the `flo healer` CLI. All check + fix logic lives in the CLI
 - **Don't** re-document checks or fixes here. The CLI's `--help` and `src/cli/commands/doctor-*` are the source of truth.
 - **Don't** call `flo doctor` directly — use the `healer` alias for thematic consistency. They're equivalent CLI-side.
 - **Don't** swallow non-zero exit codes silently — surface them in the summary.
-- **Note for users:** Claude Code has its own built-in `/doctor` command that diagnoses Claude Code itself. This skill (`/healer`) diagnoses **moflo**, not Claude Code. The two are complementary, not duplicates — and the healer also runs `claude doctor` internally as a delegated check (`Claude Code Doctor`) so Claude-side issues (auth, settings drift, IDE/extension state) surface in the same report. With `--fix`, the healer re-runs `claude doctor` interactively so you can see and act on its findings; Claude-side fixes typically need user gestures (re-auth, IDE reload) and aren't auto-applied.
+- **Note for users:** Claude Code has its own built-in `/doctor` command that diagnoses Claude Code itself. This skill (`/healer`) diagnoses **moflo**, not Claude Code. The two are complementary, not duplicates. The healer rolls in the user-actionable parts of `claude doctor` (Claude Code version freshness vs npm latest) into its own `Claude Code CLI` check; the rest of `claude doctor` is a TUI on current releases and must be run interactively if you need its full report.
 
 ## See Also
 

package/bin/session-start-launcher.mjs

@@ -447,6 +447,24 @@ try {
           'upgraded',
           cachedVersion ? `${cachedVersion} → ${installedVersion}` : `installed ${installedVersion}`,
         );
+        // #981 / #987 — one-time architecture notice. Single-writer routing
+        // means daemon must be running for safe multi-process writes. Sentinel
+        // file ensures the notice fires once per consumer (across upgrades),
+        // not on every version bump. `flo doctor` surfaces the runtime warning
+        // when the daemon is disabled with MCP configured.
+        try {
+          const noticeSentinel = join(mofloDir(projectRoot), 'single-writer-notice-shown');
+          if (cachedVersion && !existsSync(noticeSentinel)) {
+            emitMutation(
+              'single-writer write architecture active',
+              'memory writes route through the daemon (#981) — keep daemon.auto_start: true to prevent multi-process clobber',
+            );
+            try {
+              mkdirSync(mofloDir(projectRoot), { recursive: true });
+              writeFileSync(noticeSentinel, new Date().toISOString());
+            } catch { /* sentinel best-effort — re-emit next session if write fails */ }
+          }
+        } catch { /* never block the upgrade flow on the notice */ }
       } else {
         upgradeNoticeContext = {
           kind: 'repair',

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

@@ -90,6 +90,16 @@ const startCommand = {
         }
         // Foreground mode: run in current process (blocks terminal)
         try {
+            // #981 — mark this process as the daemon BEFORE any storeEntry /
+            // deleteEntry call runs in this process. The routing preamble in
+            // memory-initializer reads `process.env.MOFLO_IS_DAEMON` per-call (not
+            // at module-load time) and skips routing when set, breaking the loop
+            // that would otherwise recurse: storeEntry → HTTP → daemon RPC →
+            // storeEntry → HTTP. Setting it here covers both direct `flo daemon
+            // start --foreground` and the background spawn (whose daemonEnv
+            // propagates this via process inheritance — see startBackgroundDaemon
+            // below).
+            process.env.MOFLO_IS_DAEMON = '1';
             // Acquire atomic daemon lock (prevents duplicate daemons).
             // Always acquire here — even when spawned as a child (CLAUDE_FLOW_DAEMON=1)
             // because on Windows the parent's child.pid is the shell PID (cmd.exe),
@@ -327,6 +337,8 @@ async function startBackgroundDaemon(projectRoot, quiet, maxCpuLoad, minFreeMemo
     const daemonEnv = {
         ...process.env,
         CLAUDE_FLOW_DAEMON: '1',
+        // #981 — daemon process must skip its own write-routing client.
+        MOFLO_IS_DAEMON: '1',
         // Prevent macOS SIGHUP kill when terminal closes
         ...(process.platform === 'darwin' ? { NOHUP: '1' } : {}),
     };

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

@@ -131,17 +131,43 @@ export async function checkMemoryDatabase() {
     }
     return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
 }
-export async function checkMcpServers() {
-    const mcpConfigPaths = [
+/**
+ * Standard MCP-config search paths: home (Claude Desktop on macOS/Linux),
+ * XDG config dir, project-local `.mcp.json`, and APPDATA on Windows.
+ *
+ * Shared by `checkMcpServers` (which inspects the FIRST config it finds and
+ * reports on flo presence) and `checkDaemonWriteRouting` (which COUNTS
+ * servers across all paths to detect the multi-process-clobber hazard).
+ */
+function mcpConfigSearchPaths(cwd) {
+    return [
         join(os.homedir(), '.claude/claude_desktop_config.json'),
         join(os.homedir(), '.config/claude/mcp.json'),
-        '.mcp.json',
-        // Windows: Claude Desktop stores config under %APPDATA%\Claude\
+        join(cwd, '.mcp.json'),
         ...(process.platform === 'win32' && process.env.APPDATA
             ? [join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json')]
             : []),
     ];
-    for (const configPath of mcpConfigPaths) {
+}
+/** Sum MCP servers across every reachable config. Malformed configs counted as 0. */
+function countMcpServers(cwd) {
+    let total = 0;
+    for (const configPath of mcpConfigSearchPaths(cwd)) {
+        if (!existsSync(configPath))
+            continue;
+        try {
+            const content = JSON.parse(readFileSync(configPath, 'utf8'));
+            const servers = content.mcpServers || content.servers || {};
+            total += Object.keys(servers).length;
+        }
+        catch {
+            // Skip unreadable / malformed config — checkMcpServers reports it.
+        }
+    }
+    return total;
+}
+export async function checkMcpServers() {
+    for (const configPath of mcpConfigSearchPaths(process.cwd())) {
         if (existsSync(configPath)) {
             try {
                 const content = JSON.parse(readFileSync(configPath, 'utf8'));
@@ -202,6 +228,58 @@ export async function checkMofloYamlCompliance(cwd = process.cwd()) {
         fix: 'Restart Claude Code (yaml-upgrader auto-appends) or `npx moflo init --force`',
     };
 }
+/**
+ * #981 / #987 — surfaces the single-writer-architecture safety net.
+ *
+ * When `daemon.auto_start: false` is set in moflo.yaml AND the consumer has
+ * an MCP server configured, every MCP-process write hits sql.js directly
+ * (no daemon-RPC routing). Pre-#981 multi-process clobber + reader-staleness
+ * hazards reappear in that configuration. Warn — never fail — because
+ * disabling the daemon is a legitimate consumer choice and the config
+ * itself isn't broken.
+ *
+ * Pass: daemon enabled (default) → routing protection active.
+ * Pass: daemon disabled but no MCP server detected → no multi-writer hazard.
+ * Warn: daemon disabled AND MCP server detected → hazard window open.
+ */
+export async function checkDaemonWriteRouting(cwd = process.cwd()) {
+    const name = 'Daemon Write Routing';
+    let daemonEnabled = true; // default-on — matches moflo.yaml default
+    try {
+        const { loadMofloConfig } = await import('../config/moflo-config.js');
+        const config = loadMofloConfig(cwd);
+        daemonEnabled = config?.daemon?.auto_start !== false;
+    }
+    catch {
+        // Unreadable config — assume daemon-enabled and let other checks flag
+        // the config error.
+        daemonEnabled = true;
+    }
+    if (daemonEnabled) {
+        return {
+            name,
+            status: 'pass',
+            message: 'Daemon enabled — multi-process writes route through single writer (#981 protection active)',
+        };
+    }
+    // Daemon disabled — count MCP servers across every reachable config.
+    const mcpServerCount = countMcpServers(cwd);
+    if (mcpServerCount === 0) {
+        return {
+            name,
+            status: 'pass',
+            message: 'Daemon disabled and no MCP server configured — no multi-writer hazard',
+        };
+    }
+    return {
+        name,
+        status: 'warn',
+        message: `Daemon disabled (moflo.yaml) and ${mcpServerCount} MCP server(s) configured — ` +
+            `multi-process sql.js writes can clobber each other (#981). ` +
+            `Set daemon.auto_start: true to restore single-writer protection.`,
+        fix: 'Edit moflo.yaml: daemon.auto_start: true',
+    };
+}
 export async function checkTestDirs() {
     const yamlPath = join(process.cwd(), 'moflo.yaml');
     if (!existsSync(yamlPath)) {

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

@@ -10,6 +10,7 @@ import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { output } from '../output.js';
+import { fetchLatestNpmVersion, parseVersion, isOutdated } from './doctor-version.js';
 const execAsync = promisify(exec);
 /**
  * Execute command asynchronously with proper environment inheritance.
@@ -132,11 +133,9 @@ export async function checkBuildTools() {
     }
 }
 export async function checkClaudeCode() {
+    let installedRaw;
     try {
-        const version = await runCommand('claude --version');
-        const versionMatch = version.match(/v?(\d+\.\d+\.\d+)/);
-        const versionStr = versionMatch ? `v${versionMatch[1]}` : version;
-        return { name: 'Claude Code CLI', status: 'pass', message: versionStr };
+        installedRaw = await runCommand('claude --version');
     }
     catch (e) {
         return {
@@ -146,83 +145,38 @@ export async function checkClaudeCode() {
             fix: 'npm install -g @anthropic-ai/claude-code',
         };
     }
-}
-/**
- * Delegate diagnostics to Claude Code's own `claude doctor` command and surface
- * the result. Catches Claude-side issues (settings drift, MCP/auth, IDE/extension
- * state, update channel) that moflo's own checks can't see — since `claude` is
- * not a moflo-owned binary we don't try to parse its output structurally; we
- * just report exit code + a short tail. Skip silently when `claude` isn't
- * installed — `checkClaudeCode` already covers that condition.
- */
-export async function checkClaudeCodeDoctor() {
+    const versionMatch = installedRaw.match(/v?(\d+\.\d+\.\d+)/);
+    const installedClean = versionMatch ? versionMatch[1] : installedRaw.trim();
+    const installedDisplay = versionMatch ? `v${installedClean}` : installedRaw.trim();
+    // Compare against the latest published @anthropic-ai/claude-code on npm.
+    // Replaces the old `claude doctor` delegate (which became a TUI in CC 2.1.x
+    // and could not be parsed from a non-TTY child). Freshness was the only
+    // user-actionable signal that delegate produced; the auto-updater state +
+    // .mcp.json server health it also covered are already verified by the
+    // existing daemon and `MCP Servers` checks.
+    let latest;
     try {
-        await runCommand('claude --version', 3000);
+        latest = await fetchLatestNpmVersion('@anthropic-ai/claude-code');
     }
-    catch {
-        return {
-            name: 'Claude Code Doctor',
-            status: 'pass',
-            message: 'Skipped (claude CLI not installed — see Claude Code CLI check)',
-        };
-    }
-    // Capture both streams + exit code without throwing. `claude doctor` exits
-    // non-zero on findings, so a try/catch over execAsync would lose the body.
-    const result = await new Promise((resolve) => {
-        const child = exec('claude doctor', {
-            encoding: 'utf8',
-            timeout: 30000,
-            shell: process.platform === 'win32' ? 'cmd.exe' : '/bin/sh',
-            env: { ...process.env },
-            windowsHide: true,
-        }, (err, stdout, stderr) => {
-            resolve({
-                code: err && typeof err.code === 'number'
-                    ? (err.code)
-                    : (err ? 1 : 0),
-                stdout: (stdout || '').toString().trim(),
-                stderr: (stderr || '').toString().trim(),
-            });
-        });
-        child.on('error', () => resolve({ code: 1, stdout: '', stderr: '' }));
-    });
-    // claude doctor not recognised → some Claude versions don't ship the
-    // subcommand. Surface as a pass-skip rather than a failure so older Claude
-    // installs aren't penalised.
-    const combined = `${result.stdout}\n${result.stderr}`.toLowerCase();
-    if (/unknown command|command not found|usage:.*claude/.test(combined) &&
-        !combined.includes('check')) {
+    catch (e) {
         return {
-            name: 'Claude Code Doctor',
+            name: 'Claude Code CLI',
             status: 'pass',
-            message: 'Skipped (this Claude version does not expose `claude doctor`)',
+            message: `${installedDisplay} (registry unreachable: ${errorDetail(e, { firstLineOnly: true })})`,
         };
     }
-    if (result.code === 0) {
-        const firstLine = result.stdout.split(/\r?\n/).find((l) => l.trim()) || 'No issues reported';
-        return { name: 'Claude Code Doctor', status: 'pass', message: firstLine.slice(0, 120) };
-    }
-    // Non-zero with zero output → `claude doctor` is interactive in current
-    // Claude Code releases (verified on 2.1.132): it opens a TUI and produces
-    // nothing on a non-TTY child stdout, then our exec timeout kills it. Treat
-    // as a skip — the check can't observe the TUI from here, and warning would
-    // fire on every machine running the same Claude version.
-    if (!result.stdout && !result.stderr) {
+    if (versionMatch && isOutdated(parseVersion(installedClean), parseVersion(latest))) {
         return {
-            name: 'Claude Code Doctor',
-            status: 'pass',
-            message: 'Skipped (claude doctor is interactive — run manually to see findings)',
+            name: 'Claude Code CLI',
+            status: 'warn',
+            message: `${installedDisplay} (latest: v${latest})`,
+            fix: 'npm install -g @anthropic-ai/claude-code@latest',
         };
     }
-    // Non-zero — surface the tail so the user has a hint, and point to the
-    // interactive command for the full report. Don't try to fix from here:
-    // Claude-side fixes (re-auth, settings repair, IDE reload) need user gestures.
-    const tailLines = result.stdout.split(/\r?\n/).filter((l) => l.trim()).slice(-3).join(' | ');
     return {
-        name: 'Claude Code Doctor',
-        status: 'warn',
-        message: `claude doctor reported issues: ${tailLines.slice(0, 200)}`,
-        fix: 'Run `claude doctor` interactively for full report and follow its instructions',
+        name: 'Claude Code CLI',
+        status: 'pass',
+        message: `${installedDisplay} (up to date)`,
     };
 }
 export async function installClaudeCode() {

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

@@ -5,7 +5,6 @@
  * shell-out where possible). Falls back to running the check's `fix` string
  * if it looks like an `npx`/`npm`/`claude` command.
  */
-import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { output } from '../output.js';
@@ -175,27 +174,6 @@ export async function autoFixCheck(check) {
         'Claude Code CLI': async () => {
             return installClaudeCode();
         },
-        // Pass-through to Claude Code's own diagnostic. We don't own its CLI surface
-        // and most Claude-side findings (auth, IDE reload, settings drift) need
-        // user gestures, so the "fix" here is just to re-run with inherited stdio
-        // and let the user act on what they see.
-        'Claude Code Doctor': async () => {
-            try {
-                execSync('claude doctor', {
-                    encoding: 'utf8',
-                    stdio: 'inherit',
-                    windowsHide: true,
-                    timeout: 60000,
-                });
-                return true;
-            }
-            catch {
-                // Non-zero exit is informational here — user has seen the output and
-                // can act on it. Don't claim success, but don't claim failure of OUR
-                // healer either; flag as "needs manual action".
-                return false;
-            }
-        },
         'Zombie Processes': async () => {
             const result = await findZombieProcesses(true);
             return result.killed > 0 || result.details.length === 0;

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

@@ -8,26 +8,32 @@ import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, check
 import { checkEmbeddingHygiene } from './doctor-embedding-hygiene.js';
 import { checkSwarmFunctional, checkHiveMindFunctional, } from './doctor-checks-swarm.js';
 import { checkMemoryAccessFunctional } from './doctor-checks-memory-access.js';
-import { checkBuildTools, checkClaudeCode, checkClaudeCodeDoctor, checkDiskSpace, checkGit, checkGitRepo, checkNodeVersion, checkNpmVersion, } from './doctor-checks-runtime.js';
-import { checkConfigFile, checkDaemonStatus, checkMcpServers, checkMemoryDatabase, checkMofloYamlCompliance, checkStatusLine, checkTestDirs, } from './doctor-checks-config.js';
+import { checkBuildTools, checkClaudeCode, checkDiskSpace, checkGit, checkGitRepo, checkNodeVersion, checkNpmVersion, } from './doctor-checks-runtime.js';
+import { checkConfigFile, checkDaemonStatus, checkDaemonWriteRouting, checkMcpServers, checkMemoryDatabase, checkMofloYamlCompliance, checkStatusLine, checkTestDirs, } from './doctor-checks-config.js';
 import { checkSpellEngine, checkSandboxTier } from './doctor-checks-platform.js';
 import { checkEmbeddings, checkSemanticQuality, } from './doctor-checks-memory.js';
 import { checkIntelligence } from './doctor-checks-intelligence.js';
 import { checkVersionFreshness } from './doctor-version.js';
 import { checkZombieProcesses } from './doctor-zombies.js';
-/** Order matters — top entries surface first under the spinner. */
+/** Order matters — top entries surface first under the spinner.
+ * `checkZombieProcesses` is intentionally NOT in this list — it must run AFTER
+ * the parallel batch settles (see `zombieScanCheck` below and #992). Otherwise
+ * doctor's own subprocess probes (e.g. `checkBuildTools` running `npx tsc
+ * --version`) can be flagged as their own zombies on Windows, where the npx
+ * shim exits before its tsc child finishes.
+ */
 export const allChecks = [
     checkVersionFreshness,
     checkNodeVersion,
     checkNpmVersion,
     checkClaudeCode,
-    checkClaudeCodeDoctor,
     checkGit,
     checkGitRepo,
     checkConfigFile,
     checkMofloYamlCompliance,
     checkStatusLine,
     checkDaemonStatus,
+    checkDaemonWriteRouting,
     checkMemoryDatabase,
     checkEmbeddings,
     checkEmbeddingHygiene,
@@ -38,7 +44,6 @@ export const allChecks = [
     checkSemanticQuality,
     checkIntelligence,
     checkSpellEngine,
-    checkZombieProcesses,
     checkSubagentHealth,
     checkSpellExecution,
     checkMcpToolInvocation,
@@ -57,6 +62,8 @@ export const allChecks = [
     checkMemoryAccessFunctional,
     checkSandboxTier,
 ];
+/** Sequenced check that runs AFTER `allChecks` settles. Issue #992. */
+export const zombieScanCheck = checkZombieProcesses;
 /** Lookup table for `flo doctor -c <name>`. */
 export const componentMap = {
     'version': checkVersionFreshness,
@@ -64,14 +71,14 @@ export const componentMap = {
     'node': checkNodeVersion,
     'npm': checkNpmVersion,
     'claude': checkClaudeCode,
-    'claude-doctor': checkClaudeCodeDoctor,
-    'claude-code-doctor': checkClaudeCodeDoctor,
     'config': checkConfigFile,
     'yaml': checkMofloYamlCompliance,
     'moflo-yaml': checkMofloYamlCompliance,
     'statusline': checkStatusLine,
     'status-line': checkStatusLine,
     'daemon': checkDaemonStatus,
+    'daemon-write-routing': checkDaemonWriteRouting,
+    'write-routing': checkDaemonWriteRouting,
     'memory': checkMemoryDatabase,
     'embeddings': checkEmbeddings,
     'embedding-hygiene': checkEmbeddingHygiene,

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

@@ -66,11 +66,11 @@ function isOutdated(current, latest) {
 // Manual AbortController (NOT AbortSignal.timeout): the latter leaves
 // a libuv timer alive past process exit on Node 24 / Windows and trips
 // an `!(handle->flags & UV_HANDLE_CLOSING)` assertion in src/win/async.c.
-async function fetchLatestVersion() {
+export async function fetchLatestNpmVersion(pkg) {
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), REGISTRY_FETCH_TIMEOUT_MS);
     try {
-        const response = await fetch('https://registry.npmjs.org/moflo/latest', {
+        const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`, {
             headers: { Accept: 'application/json' },
             signal: ac.signal,
         });
@@ -86,6 +86,10 @@ async function fetchLatestVersion() {
         clearTimeout(timer);
     }
 }
+export { parseVersion, isOutdated };
+async function fetchLatestVersion() {
+    return fetchLatestNpmVersion('moflo');
+}
 export async function checkVersionFreshness() {
     try {
         const currentVersion = readCurrentVersion();

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

@@ -11,7 +11,7 @@
  * Created with motailz.com
  */
 import { output } from '../output.js';
-import { allChecks, componentMap } from './doctor-registry.js';
+import { allChecks, componentMap, zombieScanCheck } from './doctor-registry.js';
 import { emitJsonOutput, finalize, formatCheck, maybeAutoInstallClaudeCode, renderSummary, runAutoFix, runKillZombiesBanner, } from './doctor-render.js';
 import { checkEmbeddings } from './doctor-checks-memory.js';
 import { checkMofloYamlCompliance } from './doctor-checks-config.js';
@@ -157,6 +157,20 @@ export const doctorCommand = {
             let checkResults;
             try {
                 checkResults = await Promise.allSettled(checksToRun.map(check => check()));
+                // Issue #992: zombie scan must follow the parallel batch, not race it.
+                // Several parallel checks spawn short-lived subprocesses (notably
+                // `checkBuildTools` running `npx tsc --version`); on Windows the npx
+                // shim exits before its tsc child, leaving a transient orphan that
+                // the zombie scan would otherwise flag as a real leak. Skip in
+                // single-component (`-c`) runs since those are targeted diagnostics.
+                if (!component) {
+                    try {
+                        checkResults.push({ status: 'fulfilled', value: await zombieScanCheck() });
+                    }
+                    catch (reason) {
+                        checkResults.push({ status: 'rejected', reason });
+                    }
+                }
             }
             finally {
                 spinner?.stop();

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

@@ -10,6 +10,29 @@
 import * as readline from 'node:readline';
 import { loadSpellEngine, } from '../services/engine-loader.js';
 import { createDashboardMemoryAccessor } 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
+ * persist failure surfaces only as a `[spell] storeProgress(...) failed`
+ * line buried mid-run, easily missed in shell scrollback.
+ */
+function trackPersistFailures(inner) {
+    const tracker = {
+        failedWrites: 0,
+        async read(ns, key) { return inner.read(ns, key); },
+        async write(ns, key, value) {
+            try {
+                await inner.write(ns, key, value);
+            }
+            catch (err) {
+                tracker.failedWrites++;
+                throw err;
+            }
+        },
+        async search(ns, query) { return inner.search(ns, query); },
+    };
+    return tracker;
+}
 /** Cached memory accessor — created once per process. */
 let memoryAccessor = null;
 /** Prompt the user to accept or decline spell permissions. */
@@ -37,7 +60,8 @@ export async function runEpicSpell(yamlContent, options = {}) {
     // are persisted and visible in the dashboard.
     if (!memoryAccessor) {
         try {
-            memoryAccessor = await createDashboardMemoryAccessor();
+            const inner = await createDashboardMemoryAccessor();
+            memoryAccessor = trackPersistFailures(inner);
             console.log('[epic] Memory accessor ready — spell progress will be persisted');
         }
         catch (err) {
@@ -45,8 +69,26 @@ export async function runEpicSpell(yamlContent, options = {}) {
             console.warn('[epic] ⚠ Spell executions will NOT appear in the dashboard');
         }
     }
+    // memoryAccessor is module-cached, so `failedWrites` is cumulative across
+    // every spell run in this process. Capturing the count BEFORE this run
+    // and computing the delta below isolates "this run's failures" from any
+    // prior run's. Spell runs are sequential per process, so no race.
+    const failuresBefore = memoryAccessor?.failedWrites ?? 0;
     const runOpts = { ...options, projectRoot: process.cwd(), ...(memoryAccessor ? { memory: memoryAccessor } : {}) };
-    const result = await engine.runSpellFromContent(yamlContent, undefined, runOpts);
+    // Print the persist-failure summary on every return path. Without this,
+    // a #982-style failure surfaces only as scattered `[spell] storeProgress
+    // failed` lines mid-run that get lost in scrollback. The summary line is
+    // the user's signal that the dashboard / Luminarium will show empty
+    // history despite a successful-looking spell run.
+    const reportPersistFailures = () => {
+        if (!memoryAccessor)
+            return;
+        const failed = memoryAccessor.failedWrites - failuresBefore;
+        if (failed > 0) {
+            console.warn(`[epic] ⚠ Spell progress was not fully persisted (${failed} write${failed === 1 ? '' : 's'} failed) — run history may be missing from the dashboard.`);
+        }
+    };
+    let result = await engine.runSpellFromContent(yamlContent, undefined, runOpts);
     // Auto-accept permissions on first run: the spell runner already printed
     // the full risk analysis to the console. The user initiated the epic
     // command, so we accept on their behalf and retry immediately.
@@ -55,6 +97,7 @@ export async function runEpicSpell(yamlContent, options = {}) {
     if (hasAcceptanceError) {
         const accepted = await promptAcceptPermissions();
         if (!accepted) {
+            reportPersistFailures();
             return result;
         }
         // Use the already-loaded engine module (dynamic import) for spells internals.
@@ -71,8 +114,9 @@ export async function runEpicSpell(yamlContent, options = {}) {
         const report = analyzeSpellPermissions(parsed.definition, stepRegistry);
         await recordAcceptance(projectRoot, parsed.definition.name, report.permissionHash);
         console.log(`[epic] Permissions accepted for "${parsed.definition.name}" — retrying...\n`);
-        return engine.runSpellFromContent(yamlContent, undefined, runOpts);
+        result = await engine.runSpellFromContent(yamlContent, undefined, runOpts);
     }
+    reportPersistFailures();
     return result;
 }
 //# sourceMappingURL=runner-adapter.js.map

package/dist/src/cli/index.js

@@ -16,9 +16,51 @@ import { VERSION } from './version.js';
 export { VERSION };
 const LONG_RUNNING_COMMANDS = ['mcp', 'daemon'];
 /**
- * Flush stdout/stderr, shut down the memory bridge if it was initialized,
+ * Wait for a writable's userspace buffer to drain, then issue an empty write
+ * whose callback fires after libuv has committed the now-front-of-queue write.
+ *
+ * Issue #996: on Windows async pipes, the empty-write trick alone fires before
+ * prior multi-line writes (e.g. `printBox`) have left libuv's buffer, racing
+ * `process.exit` and either dropping content rows or tripping the libuv
+ * `UV_HANDLE_CLOSING` assertion in `src/win/async.c`.
+ *
+ * Two-stage wait: first await `'drain'` if the userspace buffer is full, then
+ * the empty-write callback for the libuv-level commit. A 250 ms unref'd safety
+ * timeout covers broken pipes where `'drain'` never fires.
+ */
+export function drainStream(stream) {
+    return new Promise((resolve) => {
+        if (!stream.writable || stream.destroyed)
+            return resolve();
+        const finalize = () => {
+            try {
+                stream.write('', () => resolve());
+            }
+            catch {
+                resolve();
+            }
+        };
+        if (stream.writableNeedDrain) {
+            const onDrain = () => {
+                clearTimeout(timer);
+                finalize();
+            };
+            stream.once('drain', onDrain);
+            const timer = setTimeout(() => {
+                stream.removeListener('drain', onDrain);
+                resolve();
+            }, 250);
+            timer.unref();
+        }
+        else {
+            finalize();
+        }
+    });
+}
+/**
+ * Drain stdout/stderr, shut down the memory bridge if it was initialized,
  * then `process.exit(code)`. Prevents the libuv `uv_async_send` assertion
- * on Windows when stdout is an async pipe (issue #504).
+ * on Windows when stdout is an async pipe (issues #504, #996).
  */
 async function drainAndExit(code) {
     try {
@@ -28,12 +70,8 @@ async function drainAndExit(code) {
     catch {
         // Bridge may not have been loaded — that's fine
     }
-    const flush = (stream) => new Promise((resolve) => {
-        if (!stream.writable)
-            return resolve();
-        stream.write('', () => resolve());
-    });
-    await Promise.all([flush(process.stdout), flush(process.stderr)]);
+    process.exitCode = code;
+    await Promise.all([drainStream(process.stdout), drainStream(process.stderr)]);
     process.exit(code);
 }
 /**