moflo 4.8.42 → 4.8.44

package/.claude/scripts/lib/moflo-resolve.mjs

@@ -0,0 +1,14 @@
+/**
+ * Shared dependency resolver for moflo bin scripts.
+ * Resolves packages from moflo's own node_modules (not the consuming project's).
+ * On Windows, converts native paths to file:// URLs required by ESM import().
+ */
+
+import { createRequire } from 'module';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __require = createRequire(fileURLToPath(import.meta.url));
+
+export function mofloResolveURL(specifier) {
+  return pathToFileURL(__require.resolve(specifier)).href;
+}

package/.claude/scripts/lib/process-manager.mjs

@@ -0,0 +1,256 @@
+/**
+ * Shared background process manager for moflo.
+ *
+ * All background spawn paths (hooks.mjs, hook-handler.cjs, session-start-launcher.mjs)
+ * delegate here so that PID tracking, dedup, and cleanup happen in one place.
+ *
+ * API:
+ *   spawn(cmd, args, label)  — spawn with label-based dedup + PID tracking
+ *   killAll()                — SIGTERM every tracked process, prune registry
+ *   getActive()              — list currently alive tracked processes
+ *   prune()                  — remove dead entries from registry
+ *
+ * Registry: .claude-flow/background-pids.json
+ * Lock:     .claude-flow/spawn.lock  (30 s TTL — prevents thundering-herd)
+ */
+
+import { spawn } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, unlinkSync, statSync, openSync, closeSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const LOCK_TTL_MS = 30_000;
+
+/** Resolve the project root (two levels up from bin/lib/). */
+function defaultRoot() {
+  return resolve(__dirname, '../..');
+}
+
+/** Ensure .claude-flow/ directory exists. */
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/** Check if a PID is alive (cross-platform). */
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Registry I/O ────────────────────────────────────────────────────────────
+
+function registryPath(root) {
+  return resolve(root, '.claude-flow', 'background-pids.json');
+}
+
+function lockPath(root) {
+  return resolve(root, '.claude-flow', 'spawn.lock');
+}
+
+function readRegistry(root) {
+  const p = registryPath(root);
+  if (!existsSync(p)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf-8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Atomic write: write to tmp file then rename to avoid torn reads. */
+function writeRegistry(root, entries) {
+  const p = registryPath(root);
+  const tmp = p + '.tmp.' + process.pid;
+  ensureDir(dirname(p));
+  writeFileSync(tmp, JSON.stringify(entries, null, 2));
+  renameSync(tmp, p);
+}
+
+// ── Lock (30 s TTL) ────────────────────────────────────────────────────────
+
+function checkLock(root) {
+  const lp = lockPath(root);
+  if (!existsSync(lp)) return false;
+  try {
+    const age = Date.now() - statSync(lp).mtimeMs;
+    return age < LOCK_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+/** Atomic lock acquisition using exclusive-create flag. */
+function writeLock(root) {
+  const lp = lockPath(root);
+  ensureDir(dirname(lp));
+  try {
+    writeFileSync(lp, String(Date.now()), { flag: 'wx' });
+  } catch {
+    // File already exists — overwrite if stale, otherwise skip
+    try {
+      const age = Date.now() - statSync(lp).mtimeMs;
+      if (age >= LOCK_TTL_MS) {
+        unlinkSync(lp);
+        writeFileSync(lp, String(Date.now()), { flag: 'wx' });
+      }
+    } catch { /* lost race on stale cleanup — non-fatal */ }
+  }
+}
+
+function clearLock(root) {
+  const lp = lockPath(root);
+  try {
+    if (existsSync(lp)) unlinkSync(lp);
+  } catch { /* non-fatal */ }
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a ProcessManager bound to a project root.
+ * @param {string} [root] — project root (defaults to two levels above bin/lib/)
+ */
+export function createProcessManager(root) {
+  const projectRoot = root || defaultRoot();
+
+  return {
+    /**
+     * Spawn a background process with label-based dedup and PID tracking.
+     *
+     * If a process with the same `label` is already alive, the spawn is skipped.
+     *
+     * @param {string} cmd   — executable (e.g. 'node')
+     * @param {string[]} args — arguments
+     * @param {string} label — unique label for dedup (e.g. 'index-guidance')
+     * @returns {{ pid: number|null, skipped: boolean }}
+     */
+    spawn(cmd, args, label) {
+      // Dedup: skip if same label is already alive
+      const entries = readRegistry(projectRoot);
+      const existing = entries.find(e => e.label === label);
+      if (existing && isAlive(existing.pid)) {
+        return { pid: existing.pid, skipped: true };
+      }
+
+      try {
+        // Redirect background process output to log file instead of /dev/null
+        // This ensures errors from background indexers/pretrain are captured
+        let stdio = 'ignore';
+        try {
+          const swarmDir = resolve(projectRoot, '.swarm');
+          ensureDir(swarmDir);
+          const logPath = resolve(swarmDir, 'background.log');
+          const fd = openSync(logPath, 'a');
+          stdio = ['ignore', fd, fd];
+        } catch {
+          // Fall back to ignore if log file can't be opened
+        }
+
+        const proc = spawn(cmd, args, {
+          cwd: projectRoot,
+          stdio,
+          detached: true,
+          shell: false,
+          windowsHide: true,
+        });
+
+        // Swallow async spawn errors (e.g. ENOENT for bad command)
+        proc.on('error', () => {});
+        proc.unref();
+
+        if (proc.pid) {
+          // Remove any stale entry with the same label, then append new
+          const fresh = entries.filter(e => e.label !== label);
+          fresh.push({
+            pid: proc.pid,
+            label,
+            cmd: `${cmd} ${args.join(' ')}`.substring(0, 200),
+            startedAt: new Date().toISOString(),
+          });
+          writeRegistry(projectRoot, fresh);
+        }
+
+        return { pid: proc.pid || null, skipped: false };
+      } catch {
+        return { pid: null, skipped: false };
+      }
+    },
+
+    /**
+     * Kill all tracked background processes.
+     * @returns {{ killed: number, total: number }}
+     */
+    killAll() {
+      const entries = readRegistry(projectRoot);
+      let killed = 0;
+
+      for (const entry of entries) {
+        if (!isAlive(entry.pid)) continue;
+        try {
+          process.kill(entry.pid, 'SIGTERM');
+          killed++;
+        } catch { /* already gone */ }
+      }
+
+      // Clear registry and lock
+      writeRegistry(projectRoot, []);
+      clearLock(projectRoot);
+
+      return { killed, total: entries.length };
+    },
+
+    /**
+     * Return list of currently alive tracked processes.
+     * @returns {Array<{ pid: number, label: string, cmd: string, startedAt: string }>}
+     */
+    getActive() {
+      const entries = readRegistry(projectRoot);
+      return entries.filter(e => isAlive(e.pid));
+    },
+
+    /**
+     * Remove dead entries from the registry.
+     * @returns {{ pruned: number, remaining: number }}
+     */
+    prune() {
+      const entries = readRegistry(projectRoot);
+      const alive = entries.filter(e => isAlive(e.pid));
+      writeRegistry(projectRoot, alive);
+      return { pruned: entries.length - alive.length, remaining: alive.length };
+    },
+
+    /**
+     * Check if the spawn lock is held (another session-restore spawned recently).
+     */
+    isLocked() {
+      return checkLock(projectRoot);
+    },
+
+    /**
+     * Acquire the spawn lock (30 s TTL).
+     */
+    acquireLock() {
+      writeLock(projectRoot);
+    },
+
+    /**
+     * Release the spawn lock.
+     */
+    releaseLock() {
+      clearLock(projectRoot);
+    },
+
+    /** Expose the project root for callers that need it. */
+    get root() {
+      return projectRoot;
+    },
+  };
+}

package/.claude/scripts/lib/registry-cleanup.cjs

@@ -0,0 +1,41 @@
+/**
+ * Synchronous cleanup of the ProcessManager background-pids registry.
+ *
+ * Safe to call from CJS hooks that run under process.exit() — no async,
+ * no ESM imports, pure fs + process.kill.
+ *
+ * Used by: .claude/helpers/hook-handler.cjs, bin/hook-handler.cjs (session-end)
+ */
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+/**
+ * Kill all tracked background processes and clear the registry.
+ * @param {string} projectDir - absolute path to the project root
+ * @returns {number} count of processes killed
+ */
+function killTrackedSync(projectDir) {
+  var pidFile = path.join(projectDir, '.claude-flow', 'background-pids.json');
+  var lockFile = path.join(projectDir, '.claude-flow', 'spawn.lock');
+  var killed = 0;
+
+  try {
+    if (fs.existsSync(pidFile)) {
+      var entries = JSON.parse(fs.readFileSync(pidFile, 'utf-8'));
+      if (!Array.isArray(entries)) entries = [];
+      for (var i = 0; i < entries.length; i++) {
+        try { process.kill(entries[i].pid, 0); } catch (e) { continue; }
+        try { process.kill(entries[i].pid, 'SIGTERM'); killed++; } catch (e) { /* ok */ }
+      }
+      fs.writeFileSync(pidFile, '[]');
+    }
+  } catch (e) { /* non-fatal */ }
+
+  try { if (fs.existsSync(lockFile)) fs.unlinkSync(lockFile); } catch (e) { /* ok */ }
+
+  return killed;
+}
+
+module.exports = { killTrackedSync };

package/.claude/scripts/semantic-search.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * Semantic search using 384-dim embeddings (Xenova/all-MiniLM-L6-v2 or hash fallback)
  *

package/.claude/scripts/session-start-launcher.mjs

@@ -13,7 +13,22 @@ import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const projectRoot = resolve(__dirname, '../..');
+
+// Detect project root by walking up from cwd to find package.json.
+// IMPORTANT: Do NOT use resolve(__dirname, '..') or '../..' — this script lives
+// in bin/ during development but gets synced to .claude/scripts/ in consumer
+// projects, so __dirname-relative paths break. findProjectRoot() works everywhere.
+function findProjectRoot() {
+  let dir = process.cwd();
+  const root = resolve(dir, '/');
+  while (dir !== root) {
+    if (existsSync(resolve(dir, 'package.json'))) return dir;
+    dir = dirname(dir);
+  }
+  return process.cwd();
+}
+
+const projectRoot = findProjectRoot();
 
 // ── 1. Helper: fire-and-forget a background process ─────────────────────────
 function fireAndForget(cmd, args, label) {

package/README.md

@@ -273,29 +273,29 @@ When you pass an issue number, `/flo` automatically checks if it's an epic — n
 
 When an epic is detected, `/flo` processes each child story sequentially — full workflow per story (research → implement → test → PR), one at a time, in the order listed.
 
-For simple epics with independent stories, `/flo <epic>` is all you need. For complex features where you want state tracking, resume capability, and auto-merge between stories, use `flo orc` instead.
+For simple epics with independent stories, `/flo <epic>` is all you need. For complex features where you want state tracking, resume capability, and auto-merge between stories, use `flo epic` instead.
 
-### Feature Orchestration (`flo orc`)
+### Feature Orchestration (`flo epic`)
 
-`flo orc` is the robust epic runner — it adds persistent state, resume from failure, and auto-merge between stories on top of `/flo`. It accepts either a GitHub issue number or a YAML file:
+`flo epic` is the robust epic runner — it adds persistent state, resume from failure, and auto-merge between stories on top of `/flo`. It accepts either a GitHub issue number or a YAML file:
 
 ```bash
 # From a GitHub epic (auto-detects stories)
-flo orc run 42                        # Fetch epic #42, run all stories sequentially
-flo orc run 42 --dry-run              # Preview execution plan without running
-flo orc run 42 --no-merge             # Skip auto-merge between stories
+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 --no-merge             # Skip auto-merge between stories
 
 # From a YAML definition (explicit dependencies)
-flo orc run feature.yaml              # Execute stories in dependency order
-flo orc run feature.yaml --dry-run    # Show execution plan
-flo orc run feature.yaml --verbose    # Stream Claude output to terminal
+flo epic run feature.yaml              # Execute stories in dependency order
+flo epic run feature.yaml --dry-run    # Show execution plan
+flo epic run feature.yaml --verbose    # Stream Claude output to terminal
 
 # State management
-flo orc status epic-42                # Check progress (which stories passed/failed)
-flo orc reset epic-42                 # Reset state for re-run
+flo epic status epic-42                # Check progress (which stories passed/failed)
+flo epic reset epic-42                 # Reset state for re-run
 ```
 
-When given an issue number, `flo orc` fetches the epic from GitHub, extracts child stories from checklists and numbered references, then runs each through `/flo` with state tracking. If a story fails, you can fix the issue and `flo orc run 42` again — it resumes from where it left off, skipping already-passed stories.
+When given an issue number, `flo epic` fetches the epic from GitHub, extracts child stories from checklists and numbered references, 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.
 
 For features with inter-story dependencies (story B requires story A to be merged first), use a YAML definition:
 
@@ -317,9 +317,9 @@ feature:
       depends_on: [story-1]
 ```
 
-| | `/flo <epic>` | `flo orc run <epic>` |
+| | `/flo <epic>` | `flo epic run <epic>` |
 |---|---|---|
-| **State tracking** | No | Yes (`.claude-orc/state.json`) |
+| **State tracking** | No | Yes (`.claude-epic/state.json`) |
 | **Resume from failure** | No | Yes (skips passed stories) |
 | **Auto-merge PRs** | No | Yes (between stories) |
 | **Dry-run preview** | No | Yes |
@@ -522,7 +522,7 @@ Here's how a typical task flows through both layers:
 
 The key insight: **your client handles execution, MoFlo handles knowledge.** Your client is good at spawning agents and running code. MoFlo is good at remembering what happened, routing to the right agent, and ensuring prior knowledge is checked before exploring from scratch.
 
-For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both the client's task system and MoFlo's coordination layer. The full integration pattern is documented in `.claude/guidance/task-swarm-integration.md`.
+For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both the client's task system and MoFlo's coordination layer. The full integration pattern is documented in `.claude/guidance/moflo-claude-swarm-cohesion.md`.
 
 The `/flo` skill ties both systems together for GitHub issues — driving a full workflow (research → enhance → implement → test → simplify → PR) with your client's agents for execution and MoFlo's memory for continuity.