moflo 4.9.0-rc.13 → 4.9.0-rc.14

package/.claude/helpers/statusline.cjs

@@ -382,7 +382,7 @@ function getSwarmStatus() {
 function getSystemMetrics() {
   const memoryMB = Math.floor(process.memoryUsage().heapUsed / 1024 / 1024);
   const learning = getLearningStats();
-  const agentdb = getAgentDBStats();
+  const embeddings = getEmbeddingsStats();
 
   // Intelligence from learning.json
   const learningData = readJSON(path.join(CWD, '.moflo', 'metrics', 'learning.json'));
@@ -393,7 +393,7 @@ function getSystemMetrics() {
     intelligencePct = Math.min(100, Math.floor(learningData.intelligence.score));
   } else {
     const fromPatterns = learning.patterns > 0 ? Math.min(100, Math.floor(learning.patterns / 10)) : 0;
-    const fromVectors = agentdb.vectorCount > 0 ? Math.min(100, Math.floor(agentdb.vectorCount / 100)) : 0;
+    const fromVectors = embeddings.vectorCount > 0 ? Math.min(100, Math.floor(embeddings.vectorCount / 100)) : 0;
     intelligencePct = Math.max(fromPatterns, fromVectors);
   }
 
@@ -423,7 +423,7 @@ function getSystemMetrics() {
     subAgents = activityData.processes.estimated_agents;
   }
 
-  return { memoryMB, contextPct, intelligencePct, subAgents };
+  return { memoryMB, contextPct, intelligencePct, subAgents, embeddings };
 }
 
 // ADR status (count files only — don't read contents)
@@ -484,9 +484,9 @@ function getHooksStatus() {
   return { enabled, total };
 }
 
-// AgentDB stats — reads from cache file written by embedding/memory operations.
+// Embeddings stats — reads from cache file written by embedding/memory ops.
 // No subprocess spawning. Falls back to DB file size estimate if cache is missing.
-function getAgentDBStats() {
+function getEmbeddingsStats() {
   let vectorCount = 0;
   let dbSizeKB = 0;
   let namespaces = 0;
@@ -601,20 +601,25 @@ function getIntegrationStatus() {
   return { mcpServers, hasDatabase, hasApi };
 }
 
-// Upgrade notice (#636, #738, #743) — written by the session-start launcher
-// ONLY while upgrade work is in flight; the launcher deletes the file when
-// work completes. We render it strictly for status='in-progress' so a stale
-// notice (legacy "complete" file from pre-#738 launchers, zombie write from
-// an aborted launcher, future writer mistakes) cannot turn the statusline
-// segment into a permanent column. The launcher's section 0-pre also drops
-// any leftover file at session start as a second line of defence.
+// Upgrade notice (#636, #738, #743) — written by the session-start launcher.
+//   status='in-progress' — work is running; rendered with "(updating…)".
+//   status='completed'   — work just finished; short-TTL post-upgrade badge so
+//                          the user sees something on the very next render
+//                          (Claude Code only paints the statusline AFTER the
+//                          SessionStart hook returns, so the in-progress badge
+//                          has effectively zero visibility window).
+// Anything else is dropped (legacy "complete" pre-#738 files, zombie writes,
+// future writer mistakes) so a stale notice can never turn the segment into a
+// permanent column. Section 0-pre of the launcher also wipes any leftover at
+// session start as a second line of defence.
 function getUpgradeNotice() {
   const data = readJSON(path.join(CWD, '.moflo', 'upgrade-notice.json'));
   if (!data || typeof data !== 'object') return null;
-  if (data.status !== 'in-progress') return null;
+  if (data.status !== 'in-progress' && data.status !== 'completed') return null;
   const expiresAt = data.expiresAt ? new Date(data.expiresAt).getTime() : 0;
   if (!expiresAt || Date.now() > expiresAt) return null;
   return {
+    status: data.status,
     kind: data.kind === 'repair' ? 'repair' : 'upgrade',
     from: typeof data.from === 'string' ? data.from : '',
     to: typeof data.to === 'string' ? data.to : '',
@@ -623,14 +628,20 @@ function getUpgradeNotice() {
 
 function formatUpgradeNoticeSegment(notice) {
   if (!notice) return '';
-  const suffix = ` ${c.dim}(updating…)${c.reset}`;
+  const inFlight = notice.status === 'in-progress';
+  const suffix = inFlight ? ` ${c.dim}(updating…)${c.reset}` : '';
+  // Pick body text: repair > in-flight version range > completed "upgraded to"
+  // > bare "upgraded" fallback when no version is known.
+  let body;
   if (notice.kind === 'repair') {
-    return `${c.brightYellow}📦 install repaired${c.reset}${suffix}`;
+    body = 'install repaired';
+  } else if (inFlight) {
+    body = notice.from && notice.to ? `${notice.from} → ${notice.to}` : (notice.to || 'upgraded');
+  } else {
+    const target = notice.to || notice.from || '';
+    body = target ? `upgraded to ${target}` : 'upgraded';
   }
-  const versions = notice.from && notice.to
-    ? `${notice.from} → ${notice.to}`
-    : (notice.to || 'upgraded');
-  return `${c.brightYellow}📦 ${versions}${c.reset}${suffix}`;
+  return `${c.brightYellow}📦 ${body}${c.reset}${suffix}`;
 }
 
 // Session stats (pure file reads)
@@ -784,6 +795,25 @@ function generateDashboard() {
     );
   }
 
+  // Embeddings line \u2014 vector store stats from .moflo/vector-stats.json.
+  // Reuses `system.embeddings` (already computed by getSystemMetrics()) instead
+  // of re-probing the cache file on every render.
+  {
+    const vec = system.embeddings;
+    if (vec.vectorCount > 0) {
+      const hnswInd = vec.hasHnsw ? `${c.brightGreen}\u26A1${c.reset}` : '';
+      const sizeDisp = vec.dbSizeKB >= 1024 ? `${(vec.dbSizeKB / 1024).toFixed(1)}MB` : `${vec.dbSizeKB}KB`;
+      const eParts = [
+        `${c.cyan}Vectors${c.reset} ${c.brightGreen}\u25CF${vec.vectorCount}${c.reset}${hnswInd}`,
+        `${c.cyan}Size${c.reset} ${c.brightWhite}${sizeDisp}${c.reset}`,
+      ];
+      if (vec.namespaces > 0) {
+        eParts.push(`${c.cyan}NS${c.reset} ${c.brightWhite}${vec.namespaces}${c.reset}`);
+      }
+      lines.push(`${c.brightCyan}\uD83D\uDCCA Embeddings${c.reset}  ${eParts.join(`  ${c.dim}\u2502${c.reset}  `)}`);
+    }
+  }
+
   // MCP line
   if (SL_CONFIG.show_mcp) {
     const parts = [];
@@ -795,7 +825,7 @@ function generateDashboard() {
     }
     if (integration.hasDatabase) parts.push(`${c.brightGreen}\u25C6${c.reset}DB`);
     if (parts.length > 0) {
-      lines.push(`${c.brightCyan}\uD83D\uDCCA MCP${c.reset}  ${parts.join(`  ${c.dim}\u2502${c.reset}  `)}`);
+      lines.push(`${c.brightCyan}\uD83D\uDD0C MCP${c.reset}  ${parts.join(`  ${c.dim}\u2502${c.reset}  `)}`);
     }
   }
 
@@ -835,7 +865,7 @@ function generateCompactDashboard() {
   pushUpgradeNoticeSegment(lines);
   lines.push(header);
 
-  // Combined swarm + mcp line
+  // Combined swarm + embeddings + mcp line
   const segments = [];
   if (SL_CONFIG.show_swarm) {
     const swarm = getSwarmStatus();
@@ -845,6 +875,18 @@ function generateCompactDashboard() {
       `${c.brightYellow}\uD83E\uDD16${c.reset} ${swarmInd}[${agentsColor}${swarm.activeAgents}${c.reset}/${c.brightWhite}${swarm.maxAgents}${c.reset}]`
     );
   }
+  // Embeddings \u2014 always-on when vectorCount > 0; self-hides on a fresh install.
+  // Compact doesn't call getSystemMetrics() so this is the only probe per render.
+  {
+    const vec = getEmbeddingsStats();
+    if (vec.vectorCount > 0) {
+      const hnswInd = vec.hasHnsw ? '\u26A1' : '';
+      const sizeDisp = vec.dbSizeKB >= 1024 ? `${(vec.dbSizeKB / 1024).toFixed(1)}MB` : `${vec.dbSizeKB}KB`;
+      segments.push(
+        `${c.brightCyan}\uD83D\uDCCA${c.reset} ${c.brightGreen}${vec.vectorCount}${hnswInd}${c.reset} ${c.dim}(${sizeDisp})${c.reset}`
+      );
+    }
+  }
   if (SL_CONFIG.show_mcp) {
     const integration = getIntegrationStatus();
     if (integration.mcpServers.total > 0) {
@@ -863,15 +905,16 @@ function generateCompactDashboard() {
 // JSON output
 function generateJSON() {
   const git = getGitInfo();
+  const system = getSystemMetrics();
   return {
     user: { name: git.name, gitBranch: git.gitBranch, modelName: getModelName() },
     v3Progress: getV3Progress(),
     security: getSecurityStatus(),
     swarm: getSwarmStatus(),
-    system: getSystemMetrics(),
+    system,
     adrs: getADRStatus(),
     hooks: getHooksStatus(),
-    agentdb: getAgentDBStats(),
+    embeddings: system.embeddings,
     tests: getTestStats(),
     git: { modified: git.modified, untracked: git.untracked, staged: git.staged, ahead: git.ahead, behind: git.behind },
     upgradeNotice: getUpgradeNotice(),

package/README.md

@@ -293,16 +293,16 @@ For simple epics with independent stories, `/flo <epic>` is all you need. For co
 `flo epic` is the robust epic runner — it adds persistent state, resume from failure, and per-story auto-merge on top of `/flo`. It takes a GitHub epic issue number:
 
 ```bash
-flo epic run 42                            # Fetch epic #42, run all stories sequentially
-flo epic run 42 --dry-run                  # Preview execution plan without running
-flo epic run 42 --strategy auto-merge      # Per-story PRs with auto-merge between stories
+flo epic 42                                # Fetch epic #42, run all stories sequentially
+flo epic 42 --dry-run                      # Preview execution plan without running
+flo epic 42 --strategy auto-merge          # Per-story PRs with auto-merge between stories
 flo epic status 42                         # Check progress (which stories passed/failed)
 flo epic reset 42                          # Reset state for re-run
 ```
 
-`flo epic` fetches the epic from GitHub, extracts child stories from checklists, numbered references, and `## Stories` / `## Tasks` sections, then runs each through `/flo` with state tracking. If a story fails, you can fix the issue and `flo epic run 42` again — it resumes from where it left off, skipping already-passed stories.
+`flo epic` fetches the epic from GitHub, extracts child stories from checklists, numbered references, and `## Stories` / `## Tasks` sections, then runs each through `/flo` with state tracking. If a story fails, you can fix the issue and re-run `flo epic 42` — it resumes from where it left off, skipping already-passed stories. (`flo epic run 42` is an explicit alias for the same shorthand.)
 
-| | `/flo <epic>` | `flo epic run <epic>` |
+| | `/flo <epic>` | `flo epic <epic>` |
 |---|---|---|
 | **State tracking** | No | Yes (`epic-state` memory namespace) |
 | **Resume from failure** | No | Yes (skips passed stories) |
@@ -583,7 +583,7 @@ flo --version                    # Show version
 
 ### Hooks (enabled OOTB)
 
-Hooks are shell commands that Claude Code runs automatically at specific points in its lifecycle. MoFlo installs 20 hook bindings across 8 lifecycle events. You don't invoke these — they fire automatically.
+Hooks are shell commands that Claude Code runs automatically at specific points in its lifecycle. MoFlo installs 23 hook bindings across 8 lifecycle events. You don't invoke these — they fire automatically.
 
 | Hook Event | What fires | What it does | Enabled OOTB |
 |------------|-----------|-------------|:---:|
@@ -593,9 +593,12 @@ Hooks are shell commands that Claude Code runs automatically at specific points
 | **PreToolUse: Bash** | `flo gate check-dangerous-command` | Safety check on shell commands | Yes |
 | **PreToolUse: Bash** | `flo gate check-before-pr` | Validates PR readiness before `gh pr create` | Yes |
 | **PostToolUse: Write/Edit** | `flo hooks post-edit` | Records edit outcome, optionally trains neural patterns | Yes |
+| **PostToolUse: Write/Edit** | `flo gate reset-edit-gates` | Resets edit-related gate state after the write completes | Yes |
 | **PostToolUse: Agent** | `flo hooks post-task` | Records task completion, feeds outcome into routing learner | Yes |
 | **PostToolUse: TaskCreate** | `flo gate record-task-created` | Records that a task was registered (clears TaskCreate gate) | Yes |
 | **PostToolUse: Bash** | `flo gate check-bash-memory` | Detects memory search commands in Bash (clears memory gate) | Yes |
+| **PostToolUse: Bash** | `flo gate record-test-run` | Records test runs from Bash for the test-output gate | Yes |
+| **PostToolUse: Skill** | `flo gate record-skill-run` | Records that a skill was invoked (clears skill-related gates) | Yes |
 | **PostToolUse: memory_search** | `flo gate record-memory-searched` | Records that memory was searched (clears memory-first gate) | Yes |
 | **PostToolUse: TaskUpdate** | `flo gate check-task-transition` | Validates task state transitions (prevents skipping states) | Yes |
 | **PostToolUse: memory_store** | `flo gate record-learnings-stored` | Records that learnings were persisted to memory | Yes |

package/bin/session-start-launcher.mjs

@@ -63,35 +63,36 @@ let upgradeNoticeContext = null;
 let pendingVersionStampWrite = null;
 
 // 5-min TTL is a safety net for zombie launchers (statusline ignores past-TTL
-// files). The launcher deletes the notice when upgrade work finishes — no
-// "complete" state lingers, see #738.
+// files). The 2-min "completed" TTL lets the user see the post-upgrade badge
+// briefly in the next session render (Claude Code renders the statusline only
+// AFTER the SessionStart hook returns, so the in-progress badge has effectively
+// zero visibility window). The next session-start's section 0-pre wipes any
+// leftover, so a stale completed notice can't linger past one session.
 const UPGRADE_NOTICE_INPROGRESS_TTL_MS = 5 * 60 * 1000;
+const UPGRADE_NOTICE_COMPLETED_TTL_MS = 2 * 60 * 1000;
 const UPGRADE_NOTICE_PATH = () => join(mofloDir(projectRoot), 'upgrade-notice.json');
 
-function writeInProgressUpgradeNotice() {
+function writeUpgradeNotice(status) {
   if (!upgradeNoticeContext) return;
+  const ttlMs = status === 'completed'
+    ? UPGRADE_NOTICE_COMPLETED_TTL_MS
+    : UPGRADE_NOTICE_INPROGRESS_TTL_MS;
   try {
     mkdirSync(mofloDir(projectRoot), { recursive: true });
     const now = Date.now();
     const notice = {
-      status: 'in-progress',
+      status,
       kind: upgradeNoticeContext.kind,
       from: upgradeNoticeContext.from,
       to: upgradeNoticeContext.to,
       at: new Date(now).toISOString(),
-      expiresAt: new Date(now + UPGRADE_NOTICE_INPROGRESS_TTL_MS).toISOString(),
+      expiresAt: new Date(now + ttlMs).toISOString(),
       changes: 0,
     };
     writeFileSync(UPGRADE_NOTICE_PATH(), JSON.stringify(notice, null, 2));
   } catch { /* non-fatal — statusline just won't show the segment */ }
 }
 
-function clearUpgradeNotice() {
-  try {
-    unlinkSync(UPGRADE_NOTICE_PATH());
-  } catch { /* non-fatal — already gone or never existed */ }
-}
-
 // ── 0-pre. Drop any stale upgrade notice (#738, #743) ───────────────────────
 // `upgrade-notice.json` is a transient handshake between launcher and
 // statusline — it should never survive past the launcher run that wrote it.
@@ -313,9 +314,9 @@ try {
       }
       // Surface a transient "(updating…)" badge in the statusline before the
       // long-running upgrade work (manifest sync, daemon recycle, embeddings
-      // migration). See #738 — the launcher clears this file after work
-      // completes, so the badge naturally disappears once the user is unblocked.
-      writeInProgressUpgradeNotice();
+      // migration). See #738 — section 3f flips this to a 2-min "completed"
+      // badge once work finishes (TTL rationale at the constants above).
+      writeUpgradeNotice('in-progress');
       const binDir = resolve(projectRoot, 'node_modules/moflo/bin');
 
       // ── Manifest-based auto-update ──────────────────────────────────────
@@ -855,12 +856,11 @@ try {
   } catch { /* writing the failure itself must not throw */ }
 }
 
-// ── 3f. Clear the in-progress upgrade notice (#636, #738) ───────────────────
-// Upgrade work is finished; drop the notice so the statusline badge disappears
-// immediately. Change summary is already in stdout emits (Claude's
-// `additionalContext`); a lingering "you upgraded a while ago" badge is noise.
+// ── 3f. Flip the upgrade notice to "completed" (#636, #738) ─────────────────
+// See the TTL rationale at the constants above for why we switch to a
+// short-TTL completed badge instead of clearing the file.
 if (upgradeNoticeContext) {
-  clearUpgradeNotice();
+  writeUpgradeNotice('completed');
 }
 
 // ── 3g. Commit deferred version stamp (#730) ────────────────────────────────

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

@@ -1416,7 +1416,7 @@ export const doctorCommand = {
         async function checkSandboxTier() {
             try {
                 const { detectSandboxCapability, loadSandboxConfigFromProject, resolveEffectiveSandbox, } = await import('../spells/index.js');
-                const cap = detectSandboxCapability();
+                const cap = await detectSandboxCapability();
                 const config = await loadSandboxConfigFromProject(process.cwd());
                 // If sandboxing isn't enabled in moflo.yaml, just report capability.
                 if (!config.enabled) {
@@ -1441,7 +1441,7 @@ export const doctorCommand = {
                 }
                 // Sandboxing is enabled — run the real resolver and surface any error.
                 try {
-                    const effective = resolveEffectiveSandbox(config);
+                    const effective = await resolveEffectiveSandbox(config);
                     if (effective.useOsSandbox) {
                         const imageHint = effective.config.dockerImage ? `, ${effective.config.dockerImage}` : '';
                         return {

package/dist/src/cli/init/executor.js

@@ -403,24 +403,24 @@ export async function executeUpgrade(targetDir, _upgradeSettings = false) {
         // Must mirror the list in bin/session-start-launcher.mjs — divergence
         // here means the launcher's drift-repair will delete files this upgrade
         // didn't track, even though they ship in the package (#777).
-        const UPGRADE_SCRIPT_MAP = {
-            'hooks.mjs': 'hooks.mjs',
-            'session-start-launcher.mjs': 'session-start-launcher.mjs',
-            'index-guidance.mjs': 'index-guidance.mjs',
-            'build-embeddings.mjs': 'build-embeddings.mjs',
-            'generate-code-map.mjs': 'generate-code-map.mjs',
-            'semantic-search.mjs': 'semantic-search.mjs',
-            'index-tests.mjs': 'index-tests.mjs',
-            'index-patterns.mjs': 'index-patterns.mjs',
-            'index-all.mjs': 'index-all.mjs',
-            'setup-project.mjs': 'setup-project.mjs',
-            'run-migrations.mjs': 'run-migrations.mjs',
-        };
+        const UPGRADE_SCRIPT_MAP = [
+            'hooks.mjs',
+            'session-start-launcher.mjs',
+            'index-guidance.mjs',
+            'build-embeddings.mjs',
+            'generate-code-map.mjs',
+            'semantic-search.mjs',
+            'index-tests.mjs',
+            'index-patterns.mjs',
+            'index-all.mjs',
+            'setup-project.mjs',
+            'run-migrations.mjs',
+        ];
         const binDir = findMofloBinDir();
         if (binDir) {
-            for (const [destName, srcName] of Object.entries(UPGRADE_SCRIPT_MAP)) {
-                const srcPath = path.join(binDir, srcName);
-                const destPath = path.join(scriptsDir, destName);
+            for (const name of UPGRADE_SCRIPT_MAP) {
+                const srcPath = path.join(binDir, name);
+                const destPath = path.join(scriptsDir, name);
                 if (!fs.existsSync(srcPath))
                     continue;
                 try {
@@ -435,10 +435,10 @@ export async function executeUpgrade(targetDir, _upgradeSettings = false) {
                         fs.copyFileSync(srcPath, destPath);
                     }
                     if (destExists) {
-                        result.updated.push(`.claude/scripts/${destName}`);
+                        result.updated.push(`.claude/scripts/${name}`);
                     }
                     else {
-                        result.created.push(`.claude/scripts/${destName}`);
+                        result.created.push(`.claude/scripts/${name}`);
                     }
                 }
                 catch {

package/dist/src/cli/init/moflo-init.js

@@ -701,15 +701,23 @@ ${MOFLO_MARKER_END}
 // These scripts are used by session-start hooks for indexing, code map, etc.
 // Always overwrite to keep them in sync with the installed moflo version.
 // ============================================================================
-const SCRIPT_MAP = {
-    'hooks.mjs': 'hooks.mjs',
-    'session-start-launcher.mjs': 'session-start-launcher.mjs',
-    'index-guidance.mjs': 'index-guidance.mjs',
-    'build-embeddings.mjs': 'build-embeddings.mjs',
-    'generate-code-map.mjs': 'generate-code-map.mjs',
-    'semantic-search.mjs': 'semantic-search.mjs',
-    'index-tests.mjs': 'index-tests.mjs',
-};
+// Must mirror UPGRADE_SCRIPT_MAP in src/cli/init/executor.ts and the
+// scriptFiles array in bin/session-start-launcher.mjs — first-init drops any
+// script missing here, and the launcher's manifest cleanup later treats it as
+// orphan residue and deletes it (#777, feedback_scriptfiles_sync.md).
+const SCRIPT_MAP = [
+    'hooks.mjs',
+    'session-start-launcher.mjs',
+    'index-guidance.mjs',
+    'build-embeddings.mjs',
+    'generate-code-map.mjs',
+    'semantic-search.mjs',
+    'index-tests.mjs',
+    'index-patterns.mjs',
+    'index-all.mjs',
+    'setup-project.mjs',
+    'run-migrations.mjs',
+];
 function syncScripts(root, force) {
     const scriptsDir = path.join(root, '.claude', 'scripts');
     if (!fs.existsSync(scriptsDir)) {
@@ -731,9 +739,9 @@ function syncScripts(root, force) {
         return { name: '.claude/scripts/', status: 'skipped', detail: 'moflo bin/ not found' };
     }
     let copied = 0;
-    for (const [dest, src] of Object.entries(SCRIPT_MAP)) {
-        const srcPath = path.join(binDir, src);
-        const destPath = path.join(scriptsDir, dest);
+    for (const name of SCRIPT_MAP) {
+        const srcPath = path.join(binDir, name);
+        const destPath = path.join(scriptsDir, name);
         if (!fs.existsSync(srcPath))
             continue;
         // Always overwrite scripts to keep in sync (they're derived, not user-edited)

package/dist/src/cli/spells/core/platform-sandbox.js

@@ -11,11 +11,12 @@
  *
  * @see https://github.com/eric-cielo/moflo/issues/409
  */
-import { execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { platform } from 'node:os';
 import { join } from 'node:path';
-import { escapeShellArg } from './shell.js';
+import { commandExists } from './prerequisite-checker.js';
+import { execFileAsync } from './shell.js';
 export const DEFAULT_SANDBOX_CONFIG = {
     enabled: false,
     tier: 'auto',
@@ -25,7 +26,15 @@ export const RECOMMENDED_DOCKER_IMAGE = 'ghcr.io/eric-cielo/moflo-sandbox:latest
 // ============================================================================
 // Detection (cached)
 // ============================================================================
-let _cached;
+// Detection runs once per process and is cached, so timeouts can be generous.
+// Cold-start `docker info` on Windows can take 5-10s on the named-pipe
+// handshake, so a tight budget would falsely report the daemon down.
+const BINARY_EXISTS_TIMEOUT_MS = 10_000;
+const DOCKER_DAEMON_TIMEOUT_MS = 15_000;
+// Cache the in-flight Promise rather than the resolved value so concurrent
+// callers share one detection probe (avoids racing two `docker info` calls if
+// e.g. doctor and runner ask within the same tick).
+let _cachedDetection;
 /**
  * Detect the available sandbox tool for the current platform.
  *
@@ -33,17 +42,22 @@ let _cached;
  * are expensive and the answer doesn't change mid-process.
  */
 export function detectSandboxCapability() {
-    if (_cached)
-        return _cached;
-    _cached = detectUncached();
-    return _cached;
+    if (!_cachedDetection) {
+        // Don't cache rejection — sticky failure across the process lifetime would
+        // be a hard-to-diagnose footgun if a caller ever surfaces an error.
+        _cachedDetection = detectUncached().catch((err) => {
+            _cachedDetection = undefined;
+            throw err;
+        });
+    }
+    return _cachedDetection;
 }
 /** Reset the cached result (for testing). */
 export function resetSandboxCache() {
-    _cached = undefined;
+    _cachedDetection = undefined;
     _imageExistsCache.clear();
 }
-function detectUncached() {
+async function detectUncached() {
     const os = platform();
     if (os === 'darwin') {
         return detectMacOS();
@@ -68,8 +82,8 @@ function detectMacOS() {
     };
 }
 // ── Linux ──────────────────────────────────────────────────────────────
-function detectLinux() {
-    const available = binaryExists('bwrap');
+async function detectLinux() {
+    const available = await commandExists('bwrap', { timeoutMs: BINARY_EXISTS_TIMEOUT_MS });
     return {
         platform: 'linux',
         available,
@@ -78,11 +92,11 @@ function detectLinux() {
     };
 }
 // ── Windows ────────────────────────────────────────────────────────────
-function detectWindows() {
-    if (!binaryExists('docker')) {
+async function detectWindows() {
+    if (!(await commandExists('docker', { timeoutMs: BINARY_EXISTS_TIMEOUT_MS }))) {
         return { platform: 'win32', available: false, tool: null, overhead: null };
     }
-    if (!dockerDaemonRunning()) {
+    if (!(await dockerDaemonRunning())) {
         return { platform: 'win32', available: false, tool: null, overhead: null };
     }
     return {
@@ -95,25 +109,13 @@ function detectWindows() {
 // ============================================================================
 // Helpers
 // ============================================================================
-function binaryExists(name) {
-    try {
-        const cmd = platform() === 'win32' ? `where ${name}` : `which ${name}`;
-        execSync(cmd, { stdio: 'ignore', timeout: 5000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function dockerDaemonRunning() {
-    try {
-        execSync('docker info', { stdio: 'ignore', timeout: 4000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
+// Single source of truth for docker probe outcome semantics — `execFileAsync`
+// from shell.ts never throws, so we branch on exitCode instead of try/catch.
+async function dockerProbe(args) {
+    const { exitCode } = await execFileAsync('docker', args, DOCKER_DAEMON_TIMEOUT_MS);
+    return exitCode === 0;
 }
+const dockerDaemonRunning = () => dockerProbe(['info']);
 // ============================================================================
 // Config Resolution
 // ============================================================================
@@ -174,13 +176,14 @@ export async function loadSandboxConfigFromProject(projectRoot) {
  * @returns EffectiveSandbox — includes display status for spell-start logging.
  * @throws Error if tier is 'full' but no OS sandbox is available.
  */
-export function resolveEffectiveSandbox(config, capability = detectSandboxCapability()) {
+export async function resolveEffectiveSandbox(config, capability) {
+    const cap = capability ?? await detectSandboxCapability();
     let resolved = config;
     // Config disabled or tier is denylist-only => no OS sandbox
     if (!resolved.enabled || resolved.tier === 'denylist-only') {
         return {
             useOsSandbox: false,
-            capability,
+            capability: cap,
             config: resolved,
             displayStatus: `OS sandbox: disabled (denylist active)`,
         };
@@ -188,36 +191,36 @@ export function resolveEffectiveSandbox(config, capability = detectSandboxCapabi
     // Windows: Docker is required for OS sandboxing. If Docker is available,
     // auto-default the image and auto-pull it on first use so the user doesn't
     // have to do manual setup. Only throw if Docker itself isn't installed/running.
-    if (capability.platform === 'win32') {
-        if (!capability.available) {
+    if (cap.platform === 'win32') {
+        if (!cap.available) {
             throw new Error(formatWindowsDockerNotReadyMessage());
         }
         const image = resolved.dockerImage || RECOMMENDED_DOCKER_IMAGE;
         if (!resolved.dockerImage) {
             resolved = { ...resolved, dockerImage: image };
         }
-        if (!dockerImageExists(image)) {
-            dockerPullImage(image);
+        if (!(await dockerImageExists(image))) {
+            await dockerPullImage(image);
         }
     }
     // tier: full — require OS sandbox on non-Windows platforms
-    if (resolved.tier === 'full' && !capability.available) {
-        throw new Error(`Sandbox tier "full" requires an OS sandbox but none was detected on ${capability.platform}. ` +
+    if (resolved.tier === 'full' && !cap.available) {
+        throw new Error(`Sandbox tier "full" requires an OS sandbox but none was detected on ${cap.platform}. ` +
             `Install bubblewrap (Linux) or set sandbox.tier to "auto".`);
     }
-    if (!capability.available) {
+    if (!cap.available) {
         return {
             useOsSandbox: false,
-            capability,
+            capability: cap,
             config: resolved,
-            displayStatus: `OS sandbox: not available (${capability.platform})`,
+            displayStatus: `OS sandbox: not available (${cap.platform})`,
         };
     }
     return {
         useOsSandbox: true,
-        capability,
+        capability: cap,
         config: resolved,
-        displayStatus: `OS sandbox: ${capability.tool} (${capability.platform})`,
+        displayStatus: `OS sandbox: ${cap.tool} (${cap.platform})`,
     };
 }
 const _imageExistsCache = new Map();
@@ -225,35 +228,53 @@ const _imageExistsCache = new Map();
  * Check whether a Docker image is available locally (already pulled).
  * Result is cached per image name for the process lifetime.
  */
-function dockerImageExists(image) {
+async function dockerImageExists(image) {
     const cached = _imageExistsCache.get(image);
     if (cached !== undefined)
         return cached;
-    try {
-        execSync(`docker image inspect ${escapeShellArg(image)}`, { stdio: 'ignore', timeout: 5000 });
+    // `dockerProbe` shares the cold-start timeout/error-swallow policy with
+    // `dockerDaemonRunning` — both hit the Docker Desktop named-pipe handshake.
+    // Only positive outcomes are cached: a missing image must re-probe after
+    // `dockerPullImage` populates the cache, so symmetric caching would break
+    // the pull-then-recheck flow.
+    const ok = await dockerProbe(['image', 'inspect', image]);
+    if (ok)
         _imageExistsCache.set(image, true);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return ok;
 }
 /**
  * Pull a Docker image, printing a one-time setup banner so the user knows
  * what's happening and why. Throws if the pull fails.
  */
-function dockerPullImage(image) {
+async function dockerPullImage(image) {
     console.log(`[spell] One-time setup: pulling Docker image ${image} for sandboxing...\n` +
         `        This only happens once — Docker caches the image afterwards.`);
+    // `spawn` (not execFileAsync) so the docker pull progress streams live to
+    // the user's terminal. execFileAsync buffers stdout, defeating the banner.
     try {
-        execSync(`docker pull ${escapeShellArg(image)}`, { stdio: 'inherit', timeout: 300_000 });
-        _imageExistsCache.set(image, true);
-        console.log(`[spell] Docker image ${image} is ready.`);
+        await new Promise((resolve, reject) => {
+            let timedOut = false;
+            const proc = spawn('docker', ['pull', image], { stdio: 'inherit' });
+            const timer = setTimeout(() => { timedOut = true; proc.kill('SIGTERM'); }, 300_000);
+            proc.on('error', (err) => { clearTimeout(timer); reject(err); });
+            proc.on('exit', (code) => {
+                clearTimeout(timer);
+                if (code === 0)
+                    resolve();
+                else if (timedOut)
+                    reject(new Error('docker pull timed out after 5 minutes'));
+                else
+                    reject(new Error(`docker pull exited with code ${code}`));
+            });
+        });
     }
-    catch {
-        throw new Error(`Failed to pull Docker image "${image}".\n\n` +
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to pull Docker image "${image}": ${detail}\n\n` +
             'Make sure Docker Desktop is running and you have internet access, then try again.');
     }
+    _imageExistsCache.set(image, true);
+    console.log(`[spell] Docker image ${image} is ready.`);
 }
 // ── Beginner-friendly setup messages (Windows) ──────────────────────────
 function formatWindowsDockerNotReadyMessage() {

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

@@ -19,11 +19,16 @@ import { promisify } from 'node:util';
 import { acquireTTYLock } from './tty-lock.js';
 import { readLineFromStdin } from './stdin-reader.js';
 const execFileAsync = promisify(execFile);
-/** Check whether a CLI command is available on the system PATH. */
-export async function commandExists(cmd) {
+/**
+ * Check whether a CLI command is available on the system PATH.
+ *
+ * `timeoutMs` caps the lookup probe — important for callers that probe under
+ * fork/GC pressure where `where`/`which` can stall (see platform-sandbox).
+ */
+export async function commandExists(cmd, opts) {
     try {
         const bin = process.platform === 'win32' ? 'where' : 'which';
-        await execFileAsync(bin, [cmd]);
+        await execFileAsync(bin, [cmd], opts?.timeoutMs ? { timeout: opts.timeoutMs } : undefined);
         return true;
     }
     catch {

package/dist/src/cli/spells/core/runner.js

@@ -139,7 +139,7 @@ export class SpellCaster {
         let effectiveSandbox;
         try {
             const sandboxCfg = options.sandboxConfig ?? DEFAULT_SANDBOX_CONFIG;
-            effectiveSandbox = resolveEffectiveSandbox(sandboxCfg);
+            effectiveSandbox = await resolveEffectiveSandbox(sandboxCfg);
             console.log(formatSandboxLog(effectiveSandbox));
         }
         catch (err) {

package/dist/src/cli/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.0-rc.13",
+  "version": "4.9.0-rc.14",
   "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",
@@ -79,7 +79,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.0-rc.12",
+    "moflo": "^4.9.0-rc.13",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"