moflo 4.9.2 → 4.9.4

package/.claude/guidance/shipped/moflo-error-handling.md

@@ -43,6 +43,31 @@
 
 ---
 
+## Transient Errors Must Use Retry + Circuit Breaker
+
+**Wrap every transient-failure-capable operation in a retry helper with exponential backoff and a circuit breaker.** One-shot try-and-log on a transient class strands users in partial-state loops (#854: Windows file-lock + AV scan race left stale `.claude/helpers/gate.cjs` across 8+ moflo bumps).
+
+| Element | Default |
+|---------|---------|
+| Retryable codes | `EBUSY`, `EPERM`, `EACCES`, `EAGAIN`, `ETIMEDOUT`, `ECONNRESET`; HTTP 5xx/429/408 |
+| Hard codes (no retry) | `ENOENT`, `EISDIR`, `EEXIST`, validation errors |
+| Backoff (filesystem) | `[50, 200, 800]ms` — 3 retries |
+| Circuit breaker | Open after 5 distinct failures; tail runs with `maxAttempts=1` |
+| Exhaustion handling | Log error AND name the healer (e.g. `run 'flo doctor --fix' to repair`) |
+
+**Reference implementation:** `syncWithRetry` in `bin/session-start-launcher.mjs`. Use it; do not invent ad-hoc retries.
+
+```js
+// FORBIDDEN
+try { copyFileSync(src, dest); } catch (err) { console.warn(err.message); }
+
+// CORRECT
+const result = await syncWithRetry(() => copyFileSync(src, dest));
+if (!result.ok) syncFailures.push({ key, message: `${errMessage(result.err)} (retried after ${result.code})` });
+```
+
+---
+
 ## See Also
 
 - `.claude/guidance/shipped/moflo-source-hygiene.md` — General source code standards

package/.claude/guidance/shipped/moflo-source-hygiene.md

@@ -68,6 +68,22 @@ Compiled output is generated by `npm run build` (single `tsc` run from repo root
 
 ---
 
+## Async-Eligible Operations Must Be Async By Default
+
+**Use the async API for any operation that has one, unless a documented reason forces sync.** Sync IO and busy-waits block the event loop — on a hot path that pins a CPU core, stalls timers, and turns a "best-effort" failure into a hang. Issue #854 burned 5s of CPU to a `while (Date.now() < end)` busy-wait inside an already-async launcher.
+
+| Operation | Use | Avoid |
+|-----------|-----|-------|
+| File IO inside an `async` function | `fs/promises` (`readFile`, `copyFile`, `mkdir`) | `*Sync` variants |
+| Delays | `await new Promise(r => setTimeout(r, ms))` | `while (Date.now() < end)` busy-wait |
+| Spawning long-running children | `await new Promise` around `spawn`/`execFile` | `execFileSync`/`spawnSync` (Windows timeouts orphan children — #744) |
+
+**Sync is OK only when:** the function cannot be `async` (top-level config reader before any await; certain CommonJS hooks); the IO is microscopic on a known-fast path (one `existsSync` probe, one tiny `readFileSync`); or conversion churn outweighs the benefit. Document the reason in a one-line comment.
+
+**Rule of thumb:** if anything in your call stack already `await`s, every IO/delay below it must be async too — mixing sync IO inside an async function is a smell.
+
+---
+
 ## When Creating New Files
 
 Before creating any new source file, verify:

package/bin/build-embeddings.mjs

@@ -203,6 +203,29 @@ function writeVectorStatsCache(stats, nsStats) {
 // Main
 // ============================================================================
 
+// Build (or skip) the HNSW sidecar — shared between the all-embedded fast path
+// and the post-embedding finalize path. Issue #854: the early-return path used
+// to skip this entirely, leaving consumers with `hasHnsw: false` permanently
+// after the embeddings migration deleted the stale sidecar without rebuilding.
+// `stats` is passed in by both call sites so we don't redundantly run the
+// COUNT aggregate the caller already executed. `alwaysRebuild` is set by the
+// post-embedding path because newly-embedded rows always invalidate the
+// existing sidecar.
+async function ensureHnswSidecar(stats, { alwaysRebuild = false } = {}) {
+  if (stats.withEmbeddings <= 0) return false;
+  const sidecarExists = existsSync(hnswIndexPath(projectRoot));
+  if (sidecarExists && !force && !alwaysRebuild) return false;
+  log(sidecarExists ? 'Rebuilding HNSW sidecar...' : 'Building HNSW sidecar...');
+  const result = await buildAndWriteHnswSidecar(DB_PATH, projectRoot, {
+    dimensions: EMBEDDING_DIMS,
+  });
+  log(`HNSW sidecar: ${result.vectorCount} vectors → ${result.sidecarPath} (${(result.bytes / 1024).toFixed(1)} KB)`);
+  if (!existsSync(result.sidecarPath)) {
+    throw new Error(`HNSW sidecar missing after write: ${result.sidecarPath}`);
+  }
+  return true;
+}
+
 async function main() {
   console.log('');
   log('═══════════════════════════════════════════════════════════');
@@ -217,6 +240,8 @@ async function main() {
     log('All entries already have embeddings');
     const stats = getEmbeddingStats(db);
     log(`Total: ${stats.withEmbeddings}/${stats.total} entries embedded`);
+    // HNSW first so vector-stats reports the post-rebuild `hasHnsw` (#854).
+    await ensureHnswSidecar(stats);
     writeVectorStatsCache(stats, getNamespaceStats(db));
     db.close();
     return;
@@ -312,22 +337,14 @@ async function main() {
   }
   log('═══════════════════════════════════════════════════════════');
 
+  // Rebuild the HNSW sidecar before vector-stats so `hasHnsw` reflects the
+  // post-rebuild state in the same session (#854). Newly-embedded rows
+  // invalidate the existing sidecar, so we force the rebuild here even
+  // when the sidecar already exists.
+  await ensureHnswSidecar(stats, { alwaysRebuild: true });
+
   writeVectorStatsCache(stats, nsStats);
   db.close();
-
-  // Rebuild + persist the HNSW sidecar so cold-start memory searches skip
-  // the SQL→graph rebuild. Failure here exits non-zero — index-all.mjs and
-  // any caller of this script depend on the sidecar landing on disk.
-  if (stats.withEmbeddings > 0) {
-    log('Building HNSW sidecar...');
-    const result = await buildAndWriteHnswSidecar(DB_PATH, projectRoot, {
-      dimensions: EMBEDDING_DIMS,
-    });
-    log(`HNSW sidecar: ${result.vectorCount} vectors → ${result.sidecarPath} (${(result.bytes / 1024).toFixed(1)} KB)`);
-    if (!existsSync(result.sidecarPath)) {
-      throw new Error(`HNSW sidecar missing after write: ${result.sidecarPath}`);
-    }
-  }
 }
 
 main().catch(err => {

package/bin/lib/process-manager.mjs

@@ -217,12 +217,17 @@ export function createProcessManager(root) {
         if (!isAlive(entry.pid)) continue;
         try {
           if (process.platform === 'win32') {
-            execFileSync('taskkill', ['/T', '/F', '/PID', String(entry.pid)], { windowsHide: true, timeout: 5000 });
+            execFileSync('taskkill', ['/T', '/F', '/PID', String(entry.pid)], { windowsHide: true, timeout: 10000 });
           } else {
             process.kill(entry.pid, 'SIGTERM');
           }
           killed++;
-        } catch { /* already gone */ }
+        } catch {
+          // Wrapper call threw (e.g. taskkill exceeded its timeout under load).
+          // The process itself may still have been terminated — count it as
+          // killed if it is no longer alive.
+          if (!isAlive(entry.pid)) killed++;
+        }
       }
 
       // Clear registry and lock

package/bin/session-start-launcher.mjs

@@ -60,6 +60,48 @@ function emitMutation(action, details) {
   }
 }
 
+// Stderr counterpart to emitMutation for non-fatal failures (#854). Every
+// previously-bare `catch {}` in the upgrade flow is routed through here so
+// partial-migration regressions can never go silent again. The inner try
+// guards against a broken stderr pipe — writing the failure itself must
+// never throw, otherwise a fast session-end would surface as a crash.
+function emitWarning(message) {
+  try {
+    process.stderr.write(`moflo: ${message}\n`);
+  } catch { /* stderr write must not throw */ }
+}
+function errMessage(err) {
+  return err && err.message ? err.message : String(err);
+}
+
+// Manifest schema (#854 hardening). Originally `string[]`; now `{path,size}[]`
+// so the launcher can detect *content* drift, not just *missing-file* drift.
+// Reading accepts both forms — a legacy v1 manifest is reported via
+// `isLegacy=true` so the drift check forces one re-sync to migrate to v2,
+// closing the failure mode where a v4.9.2 launcher writes a stamp+manifest
+// in stage 1 of an upgrade and the v4.9.3 launcher (with this fix) sees
+// `installedVersion === cachedVersion` + no file-missing drift, then skips
+// section 3 leaving stale `gate.cjs` etc. stuck.
+function readInstallManifest(manifestPath) {
+  let raw;
+  try { raw = readFileSync(manifestPath, 'utf-8'); } catch { return { entries: [], isLegacy: false }; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return { entries: [], isLegacy: false }; }
+  if (!Array.isArray(parsed)) return { entries: [], isLegacy: false };
+  let isLegacy = false;
+  const entries = [];
+  for (const item of parsed) {
+    if (typeof item === 'string') {
+      isLegacy = true;
+      entries.push({ path: item, size: null });
+    } else if (item && typeof item === 'object' && typeof item.path === 'string') {
+      entries.push({ path: item.path, size: typeof item.size === 'number' ? item.size : null });
+    }
+    // malformed entries are silently dropped — not surfaceable, never written by us
+  }
+  return { entries, isLegacy };
+}
+
 const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 
 // Captured inside the upgrade/drift branch so the post-spawn notice writer
@@ -246,7 +288,11 @@ try {
     if (scriptsMatch) autoUpdateConfig.scripts = scriptsMatch[1] === 'true';
     if (helpersMatch) autoUpdateConfig.helpers = helpersMatch[1] === 'true';
   }
-} catch { /* non-fatal — use defaults (all true) */ }
+} catch (err) {
+  // Defaults (all true) keep the upgrade flow alive but the user should
+  // see when their moflo.yaml fails to parse (#854).
+  emitWarning(`moflo.yaml parse failed (${errMessage(err)}) — using defaults`);
+}
 
 try {
   const mofloPkgPath = resolve(projectRoot, 'node_modules/moflo/package.json');
@@ -256,18 +302,27 @@ try {
     let cachedVersion = '';
     try { cachedVersion = readFileSync(versionStampPath, 'utf-8').trim(); } catch {}
 
-    // Drift healing: re-sync if any previously-installed file is missing, even
-    // when version stamp matches. Guards against out-of-band deletions (manual
-    // rm, botched merges, dedup commits, etc.) that would otherwise silently
-    // leave .claude/scripts/ incomplete until the next moflo upgrade.
+    // Drift healing: re-sync if any previously-installed file is missing
+    // OR has drifted in size since we last wrote it. Guards against:
+    //   - out-of-band deletions (manual rm, botched merges, dedup commits)
+    //   - stale-content drift (a prior partial migration left the file at
+    //     pre-upgrade content even though it still exists — #854)
+    //   - legacy v1 manifests written by an older launcher (force one
+    //     re-sync to migrate to v2 so subsequent runs can size-check)
     const manifestPath = resolve(projectRoot, '.moflo', 'installed-files.json');
-    let manifestDrifted = false;
-    try {
-      const prev = JSON.parse(readFileSync(manifestPath, 'utf-8'));
-      if (Array.isArray(prev)) {
-        manifestDrifted = prev.some(f => !existsSync(resolve(projectRoot, f)));
+    const { entries: priorEntries, isLegacy: manifestIsLegacy } = readInstallManifest(manifestPath);
+    let manifestDrifted = manifestIsLegacy;
+    if (!manifestDrifted) {
+      for (const { path: rel, size } of priorEntries) {
+        const abs = resolve(projectRoot, rel);
+        if (!existsSync(abs)) { manifestDrifted = true; break; }
+        if (size !== null) {
+          try {
+            if (statSync(abs).size !== size) { manifestDrifted = true; break; }
+          } catch { manifestDrifted = true; break; }
+        }
       }
-    } catch { /* no manifest yet — version check handles first install */ }
+    }
 
     if (installedVersion !== cachedVersion || manifestDrifted) {
       if (installedVersion !== cachedVersion) {
@@ -366,23 +421,86 @@ try {
       //  3. That's it — cleanup is automatic on the next upgrade
       // ────────────────────────────────────────────────────────────────────
 
-      // Load the previous manifest so we can diff after syncing
-      let previousManifest = [];
-      try { previousManifest = JSON.parse(readFileSync(manifestPath, 'utf-8')); } catch { /* ok */ }
+      // Load the previous manifest so we can diff after syncing.
+      // Both v1 (string[]) and v2 ({path,size}[]) are normalized to entries
+      // by readInstallManifest — the cleanup loop only needs the path field.
+      const { entries: previousManifest } = readInstallManifest(manifestPath);
 
       // Track every file we install this round
       const currentManifest = [];
+      // Per-file copy failures used to be invisible (#854): a Windows file
+      // lock / AV real-time scan / concurrent helper invocation would EBUSY
+      // the copy, the bare catch swallowed it, and the file stayed at its
+      // pre-upgrade content forever because it was never recorded in the
+      // manifest. Surface failures on stderr — Claude Code captures
+      // session-start stderr as additionalContext so the user sees them too.
+      const syncFailures = [];
+
+      // Standard retry with exponential backoff + circuit breaker for the
+      // transient error class (EBUSY / EPERM / EACCES — Windows file lock,
+      // AV real-time scan, concurrent helper invocation). Hard errors
+      // (ENOENT, etc.) fall through immediately. Once 5 distinct files have
+      // exhausted retries the circuit opens and the tail of the sync runs
+      // with maxAttempts=1 so a sick host (AV mid-scan over node_modules)
+      // doesn't compound the wall-clock cost. Async setTimeout — never
+      // busy-wait in a session-start hook (CPU pinning during EBUSY backoff
+      // is the worst possible response when the OS is the bottleneck).
+      const TRANSIENT_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+      const RETRY_BACKOFF_MS = [50, 200, 800];
+      const CIRCUIT_BREAK_THRESHOLD = 5;
+      let circuitOpen = false;
+      const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+      async function syncWithRetry(operation) {
+        const maxAttempts = circuitOpen ? 1 : RETRY_BACKOFF_MS.length + 1;
+        let lastErr = null;
+        let lastCode = null;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+          if (attempt > 0) await sleep(RETRY_BACKOFF_MS[attempt - 1]);
+          try {
+            operation();
+            return { ok: true };
+          } catch (err) {
+            lastErr = err;
+            lastCode = err && err.code ? err.code : null;
+            if (!TRANSIENT_CODES.has(lastCode)) break;
+          }
+        }
+        if (!circuitOpen && syncFailures.length + 1 >= CIRCUIT_BREAK_THRESHOLD) {
+          circuitOpen = true;
+        }
+        return { ok: false, err: lastErr, code: lastCode };
+      }
 
-      /** Copy src → dest if src exists, record in manifest. */
-      function syncFile(src, dest, manifestKey) {
-        if (existsSync(src)) {
-          try { copyFileSync(src, dest); currentManifest.push(manifestKey); } catch { /* non-fatal */ }
+      /** Copy src → dest if src exists, record `{path, size}` in manifest.
+       * Retries the transient error class with backoff (#854); failures land
+       * in syncFailures for the post-block stderr summary. The recorded size
+       * is read from the just-written destination so a subsequent launcher
+       * can detect content drift via size mismatch. */
+      function recordManifestEntry(manifestKey, dest) {
+        let size = null;
+        try { size = statSync(dest).size; } catch { /* size left null — drift check still works on file-existence */ }
+        currentManifest.push({ path: manifestKey, size });
+      }
+      async function syncFile(src, dest, manifestKey) {
+        if (!existsSync(src)) return;
+        const result = await syncWithRetry(() => copyFileSync(src, dest));
+        if (result.ok) {
+          recordManifestEntry(manifestKey, dest);
+          return;
         }
+        const tail = TRANSIENT_CODES.has(result.code)
+          ? ` (retried ${RETRY_BACKOFF_MS.length}× after ${result.code}${circuitOpen ? '; circuit open' : ''})`
+          : '';
+        syncFailures.push({ key: manifestKey, message: `${errMessage(result.err)}${tail}` });
       }
 
       // Version changed — sync scripts from bin/
       if (autoUpdateConfig.scripts) {
         const scriptsDir = resolve(projectRoot, '.claude/scripts');
+        // Ensure the destination dir exists — first-install consumers may
+        // not have it yet, in which case every copyFileSync below would
+        // silently ENOENT (#854).
+        if (!existsSync(scriptsDir)) mkdirSync(scriptsDir, { recursive: true });
         const scriptFiles = [
           'hooks.mjs', 'session-start-launcher.mjs', 'index-guidance.mjs',
           'build-embeddings.mjs', 'generate-code-map.mjs', 'semantic-search.mjs',
@@ -390,7 +508,7 @@ try {
           'setup-project.mjs', 'run-migrations.mjs',
         ];
         for (const file of scriptFiles) {
-          syncFile(resolve(binDir, file), resolve(scriptsDir, file), `.claude/scripts/${file}`);
+          await syncFile(resolve(binDir, file), resolve(scriptsDir, file), `.claude/scripts/${file}`);
         }
 
         // Sync lib/ subdirectory (process-manager.mjs, registry-cleanup.cjs, etc.)
@@ -401,7 +519,7 @@ try {
         if (existsSync(libSrcDir)) {
           if (!existsSync(libDestDir)) mkdirSync(libDestDir, { recursive: true });
           for (const file of readdirSync(libSrcDir)) {
-            syncFile(resolve(libSrcDir, file), resolve(libDestDir, file), `.claude/scripts/lib/${file}`);
+            await syncFile(resolve(libSrcDir, file), resolve(libDestDir, file), `.claude/scripts/lib/${file}`);
           }
         }
 
@@ -415,7 +533,8 @@ try {
           let migrationEntries;
           try {
             migrationEntries = readdirSync(migrationsSrcDir, { recursive: true, withFileTypes: true });
-          } catch {
+          } catch (err) {
+            emitWarning(`migrations source readdir failed (${errMessage(err)})`);
             migrationEntries = [];
           }
           for (const entry of migrationEntries) {
@@ -424,8 +543,10 @@ try {
             const absSrc = resolve(parent, entry.name);
             const rel = absSrc.slice(migrationsSrcDir.length + 1).split(/[\\/]/).join('/');
             const absDest = resolve(migrationsDestDir, rel);
-            try { mkdirSync(dirname(absDest), { recursive: true }); } catch { /* non-fatal */ }
-            syncFile(absSrc, absDest, `.claude/scripts/migrations/${rel}`);
+            try { mkdirSync(dirname(absDest), { recursive: true }); } catch (err) {
+              emitWarning(`migrations subdir mkdir failed for ${rel} (${errMessage(err)})`);
+            }
+            await syncFile(absSrc, absDest, `.claude/scripts/migrations/${rel}`);
           }
         }
       }
@@ -440,7 +561,7 @@ try {
           'gate.cjs', 'gate-hook.mjs', 'prompt-hook.mjs', 'hook-handler.cjs',
         ];
         for (const file of binHelperFiles) {
-          syncFile(resolve(binDir, file), resolve(helpersDir, file), `.claude/helpers/${file}`);
+          await syncFile(resolve(binDir, file), resolve(helpersDir, file), `.claude/helpers/${file}`);
         }
 
         // Other helpers from .claude/helpers/ and CLI .claude/helpers/
@@ -458,7 +579,19 @@ try {
           for (const srcDir of helperSources) {
             const src = resolve(srcDir, file);
             if (existsSync(src)) {
-              try { copyFileSync(src, dest); currentManifest.push(`.claude/helpers/${file}`); } catch { /* non-fatal */ }
+              const inlineResult = await syncWithRetry(() => copyFileSync(src, dest));
+              if (inlineResult.ok) {
+                recordManifestEntry(`.claude/helpers/${file}`, dest);
+              } else {
+                const code = inlineResult.code;
+                const tail = TRANSIENT_CODES.has(code)
+                  ? ` (retried ${RETRY_BACKOFF_MS.length}× after ${code}${circuitOpen ? '; circuit open' : ''})`
+                  : '';
+                syncFailures.push({
+                  key: `.claude/helpers/${file}`,
+                  message: `${errMessage(inlineResult.err)}${tail}`,
+                });
+              }
               break; // first source wins
             }
           }
@@ -477,26 +610,31 @@ try {
             const dest = resolve(guidanceDir, file);
             const content = readFileSync(src, 'utf-8');
             writeFileSync(dest, sessionStartMirrorHeader(file) + content);
-            currentManifest.push(`.claude/guidance/${file}`);
+            recordManifestEntry(`.claude/guidance/${file}`, dest);
           }
-        } catch { /* non-fatal */ }
+        } catch (err) {
+          emitWarning(`shipped guidance sync failed (${errMessage(err)})`);
+        }
       }
 
       // ── Clean up files we installed previously but no longer ship ──
       // Only remove files that are in the OLD manifest but NOT in the new one.
       // This ensures we never delete user-created or runtime-generated files.
+      // Both v1 (string) and v2 ({path,size}) old entries are normalized to
+      // entries by readInstallManifest; we only need the path for cleanup.
       let removedFiles = 0;
       if (previousManifest.length > 0) {
-        const currentSet = new Set(currentManifest);
-        for (const rel of previousManifest) {
-          if (!currentSet.has(rel)) {
-            const abs = resolve(projectRoot, rel);
-            try {
-              if (existsSync(abs)) {
-                unlinkSync(abs);
-                removedFiles++;
-              }
-            } catch { /* non-fatal */ }
+        const currentSet = new Set(currentManifest.map((e) => e.path));
+        for (const { path: rel } of previousManifest) {
+          if (currentSet.has(rel)) continue;
+          const abs = resolve(projectRoot, rel);
+          try {
+            if (existsSync(abs)) {
+              unlinkSync(abs);
+              removedFiles++;
+            }
+          } catch (err) {
+            emitWarning(`cleanup unlink failed for ${rel} (${errMessage(err)})`);
           }
         }
       }
@@ -509,6 +647,18 @@ try {
       // session-start` will spawn a fresh daemon under the current moflo
       // image once 3g writes the version stamp.
 
+      // Surface per-file copy failures so the user / Claude can see what
+      // didn't sync (#854). The file isn't in the manifest either, so the
+      // next-upgrade cleanup pass can never reconcile it on its own —
+      // direct the user at `flo doctor --fix` as the compensating healer.
+      if (syncFailures.length > 0) {
+        const sample = syncFailures.slice(0, 5).map((f) => `  - ${f.key}: ${f.message}`).join('\n');
+        const more = syncFailures.length > 5 ? `\n  …and ${syncFailures.length - 5} more` : '';
+        emitWarning(
+          `${plural(syncFailures.length, 'file')} failed to sync during upgrade — run 'flo doctor --fix' to repair:\n${sample}${more}`,
+        );
+      }
+
       // Manifest reflects synced files immediately; version stamp is deferred
       // to 3g so an aborted launcher re-runs upgrade detection (#730).
       try {
@@ -516,11 +666,19 @@ try {
         if (!existsSync(cfDir)) mkdirSync(cfDir, { recursive: true });
         writeFileSync(manifestPath, JSON.stringify(currentManifest, null, 2));
         pendingVersionStampWrite = { path: versionStampPath, version: installedVersion };
-      } catch {}
+      } catch (err) {
+        // #854: manifest write must surface — without it the next launcher
+        // can't tell what was installed and the version stamp never gets
+        // queued for 3g.
+        emitWarning(`manifest write failed (${errMessage(err)})`);
+      }
     }
   }
-} catch {
-  // Non-fatal — scripts will still work, just may be stale
+} catch (err) {
+  // #854: bare catches here hid upgrade regressions across multiple 4.8.x
+  // bumps. We keep the catch so a single throw doesn't crash the launcher,
+  // but we never silence it.
+  emitWarning(`upgrade section failed (${errMessage(err)})`);
 }
 
 // ── 3a-pre. Recycle daemons started before the current moflo install ────────
@@ -667,14 +825,19 @@ try {
           settingsChanges.push(`repaired ${plural(repaired.length, 'hook wiring')}`);
         }
       }
-    } catch { /* non-fatal — doctor can still fix later */ }
+    } catch (err) {
+      emitWarning(`hook-wiring repair skipped (${errMessage(err)})`);
+    }
 
     if (dirty) {
       writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
       emitMutation('updated .claude/settings.json', settingsChanges.join(', '));
     }
   }
-} catch { /* non-fatal — stale hooks won't block session, just emit warnings */ }
+} catch (err) {
+  // #854: silent fail-loop hid hook breakage — surface so the user can act.
+  emitWarning(`settings.json migration failed (${errMessage(err)})`);
+}
 
 // ── 3b. Ensure shipped guidance files exist (even without version change) ──
 // Subagents need these files on disk for direct reads without memory search.
@@ -719,7 +882,9 @@ try {
       }
     }
   }
-} catch { /* non-fatal */ }
+} catch (err) {
+  emitWarning(`shipped guidance restore failed (${errMessage(err)})`);
+}
 
 // ── 3b-714. Retire legacy `.swarm/vector-stats.json` parallel write (#714) ─
 // `.moflo/vector-stats.json` is canonical post-#699; pre-#714 builds also
@@ -909,11 +1074,15 @@ if (upgradeNoticeContext) {
 
 // ── 3g. Commit deferred version stamp (#730) ────────────────────────────────
 // Written LAST so an abort above leaves the stamp unchanged and the next
-// launcher re-detects the upgrade.
+// launcher re-detects the upgrade. Failure here is surfaced (#854) so a
+// permanently-broken stamp write (filesystem permissions, AV holds) doesn't
+// silently strand consumers in re-detect-on-every-session loops.
 if (pendingVersionStampWrite) {
   try {
     writeFileSync(pendingVersionStampWrite.path, pendingVersionStampWrite.version);
-  } catch { /* non-fatal — next launcher re-detects + retries the upgrade */ }
+  } catch (err) {
+    emitWarning(`version stamp write failed (${errMessage(err)}) — next launcher will re-detect the upgrade`);
+  }
 }
 
 // Bypasses emitMutation — framing, not a mutation, so it must not inflate the count.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.2",
+  "version": "4.9.4",
   "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",
@@ -39,14 +39,15 @@
     "!.claude/**/*.map",
     "README.md",
     "LICENSE",
-    "scripts/prune-native-binaries.mjs"
+    "scripts/prune-native-binaries.mjs",
+    "scripts/post-install-notice.mjs"
   ],
   "scripts": {
     "dev": "tsx watch src/cli/index.ts",
     "prebuild": "node scripts/sync-version.mjs && node scripts/clean-dist.mjs",
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/prune-native-binaries.mjs",
+    "postinstall": "node scripts/prune-native-binaries.mjs && node scripts/post-install-notice.mjs",
     "test": "node scripts/test-runner.mjs",
     "test:ui": "vitest --ui",
     "test:smoke": "node harness/consumer-smoke/run.mjs",
@@ -79,7 +80,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.1",
+    "moflo": "^4.9.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/scripts/post-install-notice.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Postinstall restart-nudge banner.
+ *
+ * When `npm install` runs inside Claude Code (typically because the user
+ * asked Claude to upgrade moflo), the just-installed bits are sitting on
+ * disk but the running session still has the OLD launcher, hooks, MCP
+ * server, and statusline loaded. The session-start launcher only re-reads
+ * them on the NEXT session-start — so the upgrade is inert until the user
+ * exits and reopens Claude Code.
+ *
+ * This script prints a banner that npm relays back to Claude as the install
+ * stdout. The phrasing names Claude Code explicitly so the assistant
+ * surfaces it to the user as a restart prompt.
+ *
+ * Gating:
+ *   - Only prints when CLAUDE_PROJECT_DIR or CLAUDECODE is set (avoids
+ *     noise on CI and non-Claude installs).
+ *   - Dedupes by version: only prints once per (consumer-project, version)
+ *     pair, so unrelated `npm install` runs that re-trigger postinstall
+ *     don't re-spam the banner. Tracker lives at
+ *     `<project>/.moflo/last-install-banner.json`.
+ *
+ * Failure posture: never blocks an install. Errors are swallowed; exit 0.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+
+function isClaudeSession() {
+  return Boolean(process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDECODE);
+}
+
+function consumerProjectRoot() {
+  // npm sets INIT_CWD to the original directory where the user ran `npm
+  // install` — the consumer's project root, regardless of which package's
+  // postinstall is running.
+  return process.env.INIT_CWD || process.cwd();
+}
+
+function installedVersion() {
+  // package.json sits one level above scripts/.
+  const pkgPath = resolve(dirname(SCRIPT_PATH), '..', 'package.json');
+  if (!existsSync(pkgPath)) return null;
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf-8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+function readLastBanner(trackerPath) {
+  if (!existsSync(trackerPath)) return null;
+  try {
+    return JSON.parse(readFileSync(trackerPath, 'utf-8')).version || null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLastBanner(trackerPath, version) {
+  try {
+    mkdirSync(dirname(trackerPath), { recursive: true });
+    writeFileSync(trackerPath, JSON.stringify({
+      version,
+      shownAt: new Date().toISOString(),
+    }, null, 2));
+  } catch { /* non-fatal */ }
+}
+
+function printBanner(version) {
+  // Phrased to name Claude Code by name so the assistant surfaces it as a
+  // restart instruction rather than a generic install log line.
+  const lines = [
+    '',
+    '═══════════════════════════════════════════════════════════════════',
+    `  MoFlo ${version} installed.`,
+    '',
+    '  ⚠ Claude Code: please restart your session to load the new MoFlo.',
+    '',
+    '  Hooks, MCP tools, statusline, and the session-start launcher are',
+    '  loaded once at session-start — the running session is still on',
+    '  the previous moflo until you exit and reopen Claude Code.',
+    '═══════════════════════════════════════════════════════════════════',
+    '',
+  ];
+  process.stdout.write(lines.join('\n'));
+}
+
+function run() {
+  if (!isClaudeSession()) return { fired: false, reason: 'not-claude' };
+
+  const version = installedVersion();
+  if (!version) return { fired: false, reason: 'no-version' };
+
+  const projectRoot = consumerProjectRoot();
+  const trackerPath = join(projectRoot, '.moflo', 'last-install-banner.json');
+  const lastShown = readLastBanner(trackerPath);
+  if (lastShown === version) return { fired: false, reason: 'already-shown' };
+
+  printBanner(version);
+  writeLastBanner(trackerPath, version);
+  return { fired: true, version };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    run();
+  } catch { /* never block install */ }
+  process.exit(0);
+}