moflo 4.9.5 → 4.9.7

package/bin/index-all.mjs

@@ -15,6 +15,16 @@ import { fileURLToPath } from 'url';
 import { spawn, spawnSync } from 'child_process';
 import { platform } from 'os';
 import { hnswIndexPath } from './lib/moflo-paths.mjs';
+import { decideIndexGate, saveFingerprint } from './lib/index-fingerprint.mjs';
+
+// Cap fastembed/ONNX thread count when spawning the heavy steps. Without
+// this, ONNX defaults to one thread per CPU core (22+ on a modern dev box),
+// pegging the entire machine while the indexer runs. 2 threads keeps
+// re-embedding throughput acceptable while leaving the box usable.
+const ONNX_THREAD_CAP = {
+  OMP_NUM_THREADS: '2',
+  ONNXRUNTIME_INTRA_OP_NUM_THREADS: '2',
+};
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -110,7 +120,7 @@ function killProcessTree(child) {
   }
 }
 
-function runStep(label, cmd, args, timeoutMs = 120_000) {
+function runStep(label, cmd, args, timeoutMs = 120_000, extraEnv = null) {
   return new Promise((resolveStep) => {
     const start = Date.now();
     log(`START ${label}`);
@@ -119,6 +129,7 @@ function runStep(label, cmd, args, timeoutMs = 120_000) {
       stdio: 'ignore',
       windowsHide: true,
       detached: platform() !== 'win32', // POSIX: own process group for tree-kill
+      env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
     });
     let timedOut = false;
     const timer = setTimeout(() => {
@@ -150,7 +161,19 @@ function runStep(label, cmd, args, timeoutMs = 120_000) {
 
 async function main() {
   const startTime = Date.now();
-  log('Sequential indexing chain started');
+
+  // ── Fingerprint gate ─────────────────────────────────────────────────────
+  // Skip the entire chain when none of {memory.db, moflo pkg, moflo.yaml,
+  // .claude/guidance/} have changed since the last successful run. Without
+  // this gate the chain re-embeds + rebuilds HNSW on every Claude session-
+  // start even when nothing changed — the customer-visible CPU peg this
+  // module exists to fix. Override with FLO_FORCE_INDEX=1.
+  const gate = decideIndexGate(projectRoot);
+  if (gate.skip) {
+    log(`SKIP  full chain — ${gate.reason} (no inputs changed since last run)`);
+    return;
+  }
+  log(`Sequential indexing chain started (gate: ${gate.reason})`);
 
   // 1. Guidance indexer
   if (isIndexEnabled('guidance')) {
@@ -211,9 +234,10 @@ async function main() {
   // 6. Build embeddings — single pass for ALL namespaces, after all indexers finish.
   //    Individual indexers are called with --no-embeddings to prevent background
   //    embedding spawns that race with this chain (sql.js last-write-wins).
+  //    Thread-capped: fastembed/ONNX would otherwise pin every CPU core.
   const embeddingsScript = resolveBin('flo-embeddings', 'build-embeddings.mjs');
   if (embeddingsScript) {
-    await runStep('build-embeddings', 'node', [embeddingsScript], 300_000);
+    await runStep('build-embeddings', 'node', [embeddingsScript], 300_000, ONNX_THREAD_CAP);
   } else {
     log('SKIP  build-embeddings (script not found)');
   }
@@ -222,9 +246,10 @@ async function main() {
   //    rebuild-index now also writes the binary HNSW sidecar at
   //    .moflo/hnsw.index, which can take longer than the default 120s on a
   //    populated consumer DB — match build-embeddings' 300s budget.
+  //    Thread-capped: same fastembed CPU-peg risk as build-embeddings.
   let hnswOk = true;
   if (localCli) {
-    const ok = await runStep('hnsw-rebuild', 'node', [localCli, 'memory', 'rebuild-index', '--force'], 300_000);
+    const ok = await runStep('hnsw-rebuild', 'node', [localCli, 'memory', 'rebuild-index', '--force'], 300_000, ONNX_THREAD_CAP);
     if (ok) {
       const sidecar = hnswIndexPath(projectRoot);
       if (!existsSync(sidecar)) {
@@ -243,6 +268,19 @@ async function main() {
 
   const totalElapsed = ((Date.now() - startTime) / 1000).toFixed(1);
   log(`Sequential indexing chain complete (${totalElapsed}s)`);
+
+  // Save the fingerprint AFTER a successful chain run. If hnsw failed, we
+  // intentionally don't save — the next session-start will retry. Save
+  // failures are non-fatal (next run will recompute and just re-run the
+  // chain, no correctness hazard).
+  if (hnswOk) {
+    if (saveFingerprint(projectRoot, gate.current)) {
+      log('Saved index-all fingerprint for next-session gate');
+    } else {
+      log('WARN  fingerprint save failed (next session will re-run chain)');
+    }
+  }
+
   if (!hnswOk) process.exit(1);
 }
 

package/bin/lib/index-fingerprint.mjs

@@ -0,0 +1,162 @@
+/**
+ * Fingerprint gate for the session-start indexer chain.
+ *
+ * The chain `index-all.mjs` runs on every Claude Code session-start. Without
+ * a gate it does full indexing + embedding + HNSW work even when nothing has
+ * meaningfully changed — pegging the box for several minutes per session.
+ *
+ * This module computes a small "did anything that matters change" fingerprint
+ * and persists it after each successful run. The chain skips entirely when
+ * the current fingerprint matches the saved one.
+ *
+ * Inputs we consider "changes that warrant re-indexing":
+ *   - `.moflo/moflo.db` mtime          → memory writes (new entries, deletes)
+ *   - `node_modules/moflo/package.json` mtime → moflo upgrade
+ *   - `moflo.yaml` mtime               → config change (auto_index toggles)
+ *   - `.claude/guidance/**` recursive newest-mtime → shipped or local guidance
+ *     content changed (the launcher rewrites these on upgrade)
+ *
+ * Inputs we DON'T consider:
+ *   - Source files (src/, app/, lib/, etc.) — individual indexers already
+ *     have incremental detection, so re-running the chain on a source edit
+ *     would be redundant. If a consumer reports stale codemap on edits,
+ *     extend the fingerprint in a follow-up. Keeping the set small makes
+ *     the gate cheap (no broad project tree walks at session-start).
+ *
+ * Override: set `FLO_FORCE_INDEX=1` in the environment to bypass the gate
+ * (useful for `flo doctor --fix` or manual rebuilds).
+ *
+ * Failure posture:
+ *   - Errors reading the fingerprint or computing inputs → return null,
+ *     which forces the chain to run (safe fallback).
+ *   - Errors saving the fingerprint → don't fail the run; the next run will
+ *     also recompute and run, no correctness hazard.
+ */
+
+import { existsSync, readFileSync, writeFileSync, statSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const FINGERPRINT_FILE_REL = '.moflo/index-all-fingerprint.json';
+export const FINGERPRINT_VERSION = 1;
+export const FORCE_ENV = 'FLO_FORCE_INDEX';
+
+function safeMtime(path) {
+  try { return statSync(path).mtimeMs; } catch { return 0; }
+}
+
+/**
+ * Newest mtime across all files under `dir`, recursive. Skips dot-dirs and
+ * `node_modules` to avoid walking irrelevant trees.
+ *
+ * Capped depth keeps the cost bounded (.claude/guidance/ has ~2 levels in
+ * the wild; cap at 6 for safety).
+ */
+function newestMtimeRecursive(dir, depth = 6) {
+  if (depth <= 0) return 0;
+  let max = 0;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') && entry.name !== '.') continue;
+      if (entry.name === 'node_modules' || entry.name === 'dist') continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const m = newestMtimeRecursive(full, depth - 1);
+        if (m > max) max = m;
+      } else if (entry.isFile()) {
+        const m = safeMtime(full);
+        if (m > max) max = m;
+      }
+    }
+  } catch {
+    // Unreadable dir — return 0; caller will compare equality and fall through.
+  }
+  return max;
+}
+
+/**
+ * Compute the current fingerprint for `projectRoot`. Cheap (a handful of
+ * stat() calls + one bounded recursive walk over .claude/guidance/).
+ *
+ * Returns a flat object of { input → mtimeMs }. Missing files contribute 0,
+ * which still produces a stable fingerprint as long as their absence is
+ * stable.
+ */
+export function computeFingerprint(projectRoot) {
+  return {
+    memoryDb: safeMtime(resolve(projectRoot, '.moflo/moflo.db')),
+    mofloPkg: safeMtime(resolve(projectRoot, 'node_modules/moflo/package.json')),
+    mofloYaml: safeMtime(resolve(projectRoot, 'moflo.yaml')),
+    guidance: newestMtimeRecursive(resolve(projectRoot, '.claude/guidance')),
+  };
+}
+
+/**
+ * Compare two fingerprints by exact equality on every recorded key. Either
+ * side being null/undefined returns false — forces a run when the saved
+ * record is missing or unparseable.
+ */
+export function fingerprintsEqual(a, b) {
+  if (!a || !b) return false;
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}
+
+/**
+ * Read the saved fingerprint payload from disk. Returns the bare fingerprint
+ * object (not the wrapper), or null if missing/corrupt/version-mismatched.
+ */
+export function readSavedFingerprint(projectRoot) {
+  const path = resolve(projectRoot, FINGERPRINT_FILE_REL);
+  if (!existsSync(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    if (!data || data.version !== FINGERPRINT_VERSION) return null;
+    return data.fingerprint || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the fingerprint after a successful run. Wrapper carries a version
+ * and timestamp so a future schema change can invalidate gracefully.
+ *
+ * Returns true on success; false on write failure (caller should not fail
+ * the run on this).
+ */
+export function saveFingerprint(projectRoot, fp) {
+  const path = resolve(projectRoot, FINGERPRINT_FILE_REL);
+  const payload = {
+    version: FINGERPRINT_VERSION,
+    savedAt: new Date().toISOString(),
+    fingerprint: fp,
+  };
+  try {
+    writeFileSync(path, JSON.stringify(payload, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * High-level gate decision. Returns one of:
+ *   { skip: true,  reason: 'unchanged' }
+ *   { skip: false, reason: 'forced' | 'no-saved-fingerprint' | 'inputs-changed', current }
+ *
+ * `current` is included on the run path so the caller can save it after a
+ * successful run without recomputing.
+ */
+export function decideIndexGate(projectRoot, env = process.env) {
+  if (env[FORCE_ENV]) {
+    return { skip: false, reason: 'forced', current: computeFingerprint(projectRoot) };
+  }
+  const current = computeFingerprint(projectRoot);
+  const saved = readSavedFingerprint(projectRoot);
+  if (!saved) return { skip: false, reason: 'no-saved-fingerprint', current };
+  if (fingerprintsEqual(current, saved)) return { skip: true, reason: 'unchanged' };
+  return { skip: false, reason: 'inputs-changed', current };
+}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.5",
+  "version": "4.9.7",
   "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",
@@ -40,14 +40,15 @@
     "README.md",
     "LICENSE",
     "scripts/prune-native-binaries.mjs",
-    "scripts/post-install-notice.mjs"
+    "scripts/post-install-notice.mjs",
+    "scripts/post-install-bootstrap.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 && node scripts/post-install-notice.mjs",
+    "postinstall": "node scripts/prune-native-binaries.mjs && node scripts/post-install-notice.mjs && node scripts/post-install-bootstrap.mjs",
     "test": "node scripts/test-runner.mjs",
     "test:ui": "vitest --ui",
     "test:smoke": "node harness/consumer-smoke/run.mjs",
@@ -80,7 +81,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.4",
+    "moflo": "^4.9.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/scripts/post-install-bootstrap.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * Postinstall self-update bootstrap (#857).
+ *
+ * Problem this solves:
+ *   The launcher in <consumer>/.claude/scripts/session-start-launcher.mjs
+ *   is responsible for copying itself + helpers from node_modules/moflo/
+ *   on every upgrade. Pre-#854 launchers wrap each copyFileSync in a bare
+ *   `catch { /* non-fatal *\/ }` and can't reliably replace themselves on
+ *   Windows under file-lock contention (EBUSY/EPERM/EACCES from concurrent
+ *   helper invocation, AV real-time scan, npm verification handles).
+ *
+ *   The fix for that lives in the new launcher (#854/#855), but the old
+ *   launcher has to work to deploy the new one. It doesn't, and consumers
+ *   stay stuck across 8+ version bumps until manually unstuck.
+ *
+ * Fix:
+ *   This script runs at npm postinstall — driven by npm, not by the broken
+ *   launcher — and copies bin/ scripts + helpers DIRECTLY into the
+ *   consumer's .claude/scripts/ and .claude/helpers/. After the bootstrap
+ *   runs, the next session-start launches the NEW launcher, which then
+ *   handles the rest of the upgrade work (guidance sync, manifest, version
+ *   stamp, daemon recycle, HNSW rebuild).
+ *
+ *   The bootstrap only has to do enough to break the deadlock.
+ *
+ * The lists below MUST stay aligned with bin/session-start-launcher.mjs
+ * section 3 (the launcher's own sync). A unit test asserts list parity
+ * (mcp-tools-drift-guard pattern). See SCRIPT_FILES / BIN_HELPER_FILES /
+ * SOURCE_HELPER_FILES exports.
+ *
+ * Failure posture:
+ *   - Surface per-file failures on stderr with `flo doctor --fix` advice
+ *   - Skip silently if <consumer>/.claude doesn't exist (consumer hasn't
+ *     run `flo init` yet — bootstrap is a no-op for first-time installs)
+ *   - Never exit non-zero (postinstall failures block npm install)
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const MOFLO_ROOT = resolve(dirname(SCRIPT_PATH), '..');
+
+// ── Sync lists — keep in lockstep with bin/session-start-launcher.mjs §3 ─────
+//
+// Drift guard: tests/unit/post-install-bootstrap-drift.test.ts asserts these
+// arrays match the launcher's section-3 sync lists by parsing both files.
+
+export const SCRIPT_FILES = [
+  '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',
+];
+
+export const BIN_HELPER_FILES = [
+  'gate.cjs',
+  'gate-hook.mjs',
+  'prompt-hook.mjs',
+  'hook-handler.cjs',
+];
+
+export const SOURCE_HELPER_FILES = [
+  'auto-memory-hook.mjs',
+  'statusline.cjs',
+  'intelligence.cjs',
+  'subagent-start.cjs',
+  'subagent-bootstrap.json',
+  'pre-commit',
+  'post-commit',
+];
+
+// ── Retry + circuit breaker (#854 contract) ──────────────────────────────────
+//
+// Mirrors the launcher's syncWithRetry. Backoff [50,200,800]ms covers Windows
+// EBUSY windows from concurrent helper invocation + AV real-time scan. The
+// breaker opens after 5 distinct files exhaust retries so a sick host
+// (AV mid-scan over node_modules) doesn't compound wall-clock cost.
+
+const TRANSIENT_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+const RETRY_BACKOFF_MS = [50, 200, 800];
+const CIRCUIT_BREAK_THRESHOLD = 5;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function makeSyncer() {
+  let circuitOpen = false;
+  const failures = [];
+
+  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 && failures.length + 1 >= CIRCUIT_BREAK_THRESHOLD) {
+      circuitOpen = true;
+    }
+    return { ok: false, err: lastErr, code: lastCode };
+  }
+
+  async function syncFile(src, dest, manifestKey) {
+    if (!existsSync(src)) return { skipped: true };
+    try {
+      mkdirSync(dirname(dest), { recursive: true });
+    } catch (err) {
+      failures.push({ key: manifestKey, message: errMessage(err) });
+      return { ok: false };
+    }
+    const result = await syncWithRetry(() => copyFileSync(src, dest));
+    if (result.ok) return { ok: true };
+    const tail = TRANSIENT_CODES.has(result.code)
+      ? ` (retried ${RETRY_BACKOFF_MS.length}× after ${result.code}${circuitOpen ? '; circuit open' : ''})`
+      : '';
+    failures.push({ key: manifestKey, message: `${errMessage(result.err)}${tail}` });
+    return { ok: false };
+  }
+
+  return { syncFile, failures };
+}
+
+function errMessage(err) {
+  if (!err) return 'unknown error';
+  return err.code ? `${err.code} ${err.message || ''}`.trim() : (err.message || String(err));
+}
+
+// ── Project root discovery ──────────────────────────────────────────────────
+//
+// npm sets INIT_CWD to the directory where the user originally ran
+// `npm install`. That's the consumer's project root regardless of which
+// package's postinstall is running. Falls back to cwd for direct execution.
+
+function consumerProjectRoot() {
+  return process.env.INIT_CWD || process.cwd();
+}
+
+// ── Main bootstrap ──────────────────────────────────────────────────────────
+
+export async function runBootstrap({
+  projectRoot = consumerProjectRoot(),
+  mofloRoot = MOFLO_ROOT,
+  log = (msg) => process.stderr.write(`${msg}\n`),
+} = {}) {
+  const claudeDir = resolve(projectRoot, '.claude');
+  if (!existsSync(claudeDir)) {
+    return { ran: false, reason: 'no-claude-dir' };
+  }
+
+  // moflo's own dogfood install: don't bootstrap into the source repo.
+  // The source repo's .claude/ IS the truth source — we'd be copying
+  // the very files we just built ON TOP of themselves, which on Windows
+  // hits the same file-lock issues we're trying to avoid.
+  if (resolve(projectRoot) === resolve(mofloRoot)) {
+    return { ran: false, reason: 'moflo-self-install' };
+  }
+
+  const binDir = resolve(mofloRoot, 'bin');
+  if (!existsSync(binDir)) {
+    return { ran: false, reason: 'no-bin-dir' };
+  }
+
+  const { syncFile, failures } = makeSyncer();
+  let synced = 0;
+
+  // 1. Top-level scripts → .claude/scripts/
+  const scriptsDir = resolve(claudeDir, 'scripts');
+  if (!existsSync(scriptsDir)) mkdirSync(scriptsDir, { recursive: true });
+  for (const file of SCRIPT_FILES) {
+    const result = await syncFile(
+      resolve(binDir, file),
+      resolve(scriptsDir, file),
+      `.claude/scripts/${file}`,
+    );
+    if (result.ok) synced++;
+  }
+
+  // 2. bin/lib/ → .claude/scripts/lib/ (read entire dir)
+  const libSrcDir = resolve(binDir, 'lib');
+  const libDestDir = resolve(scriptsDir, 'lib');
+  if (existsSync(libSrcDir)) {
+    if (!existsSync(libDestDir)) mkdirSync(libDestDir, { recursive: true });
+    let libEntries;
+    try {
+      libEntries = readdirSync(libSrcDir);
+    } catch (err) {
+      log(`bootstrap: lib readdir failed (${errMessage(err)})`);
+      libEntries = [];
+    }
+    for (const file of libEntries) {
+      const src = resolve(libSrcDir, file);
+      try {
+        if (!statSync(src).isFile()) continue;
+      } catch { continue; }
+      const result = await syncFile(src, resolve(libDestDir, file), `.claude/scripts/lib/${file}`);
+      if (result.ok) synced++;
+    }
+  }
+
+  // 3. bin/migrations/ → .claude/scripts/migrations/ (recursive)
+  const migrationsSrcDir = resolve(binDir, 'migrations');
+  const migrationsDestDir = resolve(scriptsDir, 'migrations');
+  if (existsSync(migrationsSrcDir)) {
+    if (!existsSync(migrationsDestDir)) mkdirSync(migrationsDestDir, { recursive: true });
+    let migEntries;
+    try {
+      migEntries = readdirSync(migrationsSrcDir, { recursive: true, withFileTypes: true });
+    } catch (err) {
+      log(`bootstrap: migrations readdir failed (${errMessage(err)})`);
+      migEntries = [];
+    }
+    for (const entry of migEntries) {
+      if (!entry.isFile()) continue;
+      const parent = entry.parentPath || entry.path || migrationsSrcDir;
+      const absSrc = resolve(parent, entry.name);
+      const rel = absSrc.slice(migrationsSrcDir.length + 1).split(/[\\/]/).join('/');
+      const result = await syncFile(absSrc, resolve(migrationsDestDir, rel), `.claude/scripts/migrations/${rel}`);
+      if (result.ok) synced++;
+    }
+  }
+
+  // 4. bin/ helpers → .claude/helpers/
+  const helpersDir = resolve(claudeDir, 'helpers');
+  if (!existsSync(helpersDir)) mkdirSync(helpersDir, { recursive: true });
+  for (const file of BIN_HELPER_FILES) {
+    const result = await syncFile(
+      resolve(binDir, file),
+      resolve(helpersDir, file),
+      `.claude/helpers/${file}`,
+    );
+    if (result.ok) synced++;
+  }
+
+  // 5. moflo's own .claude/helpers/ → consumer .claude/helpers/
+  // (these never lived in bin/ — they're shipped via .claude/helpers/** in files[])
+  const sourceHelpersDir = resolve(mofloRoot, '.claude/helpers');
+  if (existsSync(sourceHelpersDir)) {
+    for (const file of SOURCE_HELPER_FILES) {
+      const src = resolve(sourceHelpersDir, file);
+      if (!existsSync(src)) continue;
+      const result = await syncFile(src, resolve(helpersDir, file), `.claude/helpers/${file}`);
+      if (result.ok) synced++;
+    }
+  }
+
+  // Surface failures so npm log + Claude relay catches them, with the same
+  // healer advice the launcher uses.
+  if (failures.length > 0) {
+    const sample = failures.slice(0, 5).map((f) => `  - ${f.key}: ${f.message}`).join('\n');
+    const more = failures.length > 5 ? `\n  …and ${failures.length - 5} more` : '';
+    log(
+      `moflo: postinstall bootstrap left ${failures.length} file(s) unsynced — run 'flo doctor --fix' to repair:\n${sample}${more}`,
+    );
+  }
+
+  return { ran: true, synced, failed: failures.length, failures };
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runBootstrap()
+    .catch((err) => {
+      // Never block install. Log and exit 0.
+      process.stderr.write(`moflo: bootstrap failed (${errMessage(err)})\n`);
+    })
+    .finally(() => process.exit(0));
+}