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

package/package.json

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