moflo 4.9.4 → 4.9.6

package/dist/src/cli/init/claudemd-generator.js

@@ -44,6 +44,10 @@ flo-search "[query]" --namespace guidance   # Semantic search
 flo doctor --fix                             # Health check
 \`\`\`
 
+### After upgrading MoFlo
+
+After running \`npm install moflo@*\` (or \`npm install\` that touches moflo), check \`.moflo/restart-pending.json\`. If it exists, surface the \`message\` field to the user verbatim (Claude Code can't pick up new hooks/MCP tools/launcher mid-session — they're only loaded at session-start), then delete the file.
+
 ### Full Reference
 
 - **Subagents protocol:** \`.claude/guidance/shipped/moflo-subagents.md\`

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.4",
+  "version": "4.9.6",
   "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.3",
+    "moflo": "^4.9.5",
     "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));
+}

package/scripts/post-install-notice.mjs

@@ -1,25 +1,37 @@
 #!/usr/bin/env node
 /**
- * Postinstall restart-nudge banner.
+ * Postinstall restart-nudge — drops a notice file Claude reads after upgrade.
  *
- * 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.
+ * Problem this solves:
+ *   When `npm install` runs inside Claude Code (typically because the user
+ *   asked Claude to upgrade moflo), the just-installed bits are on disk but
+ *   the running session still has the OLD launcher, hooks, MCP server, and
+ *   statusline loaded. The launcher only re-reads them on the NEXT
+ *   session-start — the upgrade is inert until the user restarts.
  *
- * 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.
+ *   The original v4.9.4 design printed a banner to stdout, expecting npm to
+ *   relay it. It does not: npm 7+ defaults to `foreground-scripts: false`
+ *   and captures install-script stdout/stderr into log files. The banner
+ *   never reached Claude. (#856.)
+ *
+ * Fix:
+ *   This script drops `<project>/.moflo/restart-pending.json` on every
+ *   relevant install. Claude is instructed (via the moflo CLAUDE.md
+ *   injection) to read + surface + delete the file after running
+ *   `npm install moflo@*`. No reliance on npm cooperating with stdout.
+ *
+ *   The banner is still printed to stdout for the rare `--foreground-scripts`
+ *   user, and the dedup tracker is preserved so repeat postinstalls of the
+ *   same version don't double-write the notice.
+ *
+ * Files written:
+ *   - .moflo/restart-pending.json       (the payload Claude reads)
+ *   - .moflo/last-install-banner.json   (dedup tracker, version-stamped)
  *
  * 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`.
+ *   - Only fires when CLAUDE_PROJECT_DIR or CLAUDECODE is set; non-Claude
+ *     installs and CI stay silent.
+ *   - Dedupes by version: same (project, version) pair won't re-write.
  *
  * Failure posture: never blocks an install. Errors are swallowed; exit 0.
  */
@@ -52,7 +64,7 @@ function installedVersion() {
   }
 }
 
-function readLastBanner(trackerPath) {
+function readTrackedVersion(trackerPath) {
   if (!existsSync(trackerPath)) return null;
   try {
     return JSON.parse(readFileSync(trackerPath, 'utf-8')).version || null;
@@ -61,33 +73,36 @@ function readLastBanner(trackerPath) {
   }
 }
 
-function writeLastBanner(trackerPath, version) {
+function writeJson(filePath, payload) {
   try {
-    mkdirSync(dirname(trackerPath), { recursive: true });
-    writeFileSync(trackerPath, JSON.stringify({
-      version,
-      shownAt: new Date().toISOString(),
-    }, null, 2));
-  } catch { /* non-fatal */ }
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(payload, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-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.`,
+function buildMessage(version) {
+  // Plain-text payload Claude relays verbatim. Names Claude Code explicitly
+  // so the assistant frames it as a restart instruction, not a log line.
+  return [
+    `MoFlo ${version} installed.`,
     '',
-    '  ⚠ Claude Code: please restart your session to load the new MoFlo.',
+    'Please restart Claude Code 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'));
+    '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.',
+  ].join('\n');
+}
+
+function printBanner(version, message) {
+  // Stdout fallback for --foreground-scripts users. With npm's default
+  // config this output is captured and never seen — that's why the notice
+  // file exists. Kept anyway because it costs nothing.
+  const border = '═'.repeat(67);
+  process.stdout.write(`\n${border}\n  MoFlo ${version} installed.\n\n  ⚠ ${message.split('\n')[2]}\n${border}\n\n`);
 }
 
 function run() {
@@ -98,12 +113,19 @@ function run() {
 
   const projectRoot = consumerProjectRoot();
   const trackerPath = join(projectRoot, '.moflo', 'last-install-banner.json');
-  const lastShown = readLastBanner(trackerPath);
+  const noticePath = join(projectRoot, '.moflo', 'restart-pending.json');
+
+  const lastShown = readTrackedVersion(trackerPath);
   if (lastShown === version) return { fired: false, reason: 'already-shown' };
 
-  printBanner(version);
-  writeLastBanner(trackerPath, version);
-  return { fired: true, version };
+  const writtenAt = new Date().toISOString();
+  const message = buildMessage(version);
+
+  writeJson(noticePath, { version, writtenAt, message });
+  writeJson(trackerPath, { version, shownAt: writtenAt });
+
+  printBanner(version, message);
+  return { fired: true, version, noticePath };
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {