moflo 4.9.0-rc.9 → 4.9.1

package/.claude/helpers/gate-hook.mjs

@@ -25,6 +25,13 @@ try { if (stdinData.trim()) hookContext = JSON.parse(stdinData); } catch (e) {}
 // Pass tool info as env vars for gate.cjs
 var env = Object.assign({}, process.env);
 if (hookContext.tool_name) env.TOOL_NAME = hookContext.tool_name;
+// Forward Claude Code's session_id so gate.cjs can enforce memory-first
+// per-actor (#838) — each spawned subagent gets its own session_id, so a
+// shared workflow-state.json no longer lets one subagent's directive be
+// silently satisfied by the parent's earlier search.
+if (typeof hookContext.session_id === 'string' && hookContext.session_id) {
+  env.HOOK_SESSION_ID = hookContext.session_id;
+}
 if (hookContext.tool_input && typeof hookContext.tool_input === 'object') {
   Object.keys(hookContext.tool_input).forEach(function(key) {
     if (typeof hookContext.tool_input[key] === 'string') {

package/.claude/helpers/gate.cjs

@@ -6,7 +6,37 @@ var path = require('path');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+
+// Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
+// is session-wide, so once the parent searches memory, every spawned subagent
+// inherits the satisfied flag and the directive's "WILL BLOCK" promise becomes
+// false. When gate-hook.mjs forwards Claude Code's stdin `session_id` as
+// HOOK_SESSION_ID, prefer the per-session map so each subagent must search
+// memory itself before its first Glob/Grep/Read. Falls back to the legacy
+// boolean when no session id is present (CLI invocations, tests, older hosts).
+function isMemorySearchedFor(state) {
+  var sid = process.env.HOOK_SESSION_ID || '';
+  if (sid) {
+    var map = state.memorySearchedBy || {};
+    return map[sid] === true;
+  }
+  return state.memorySearched === true;
+}
+
+// Stamp the legacy bool plus (when HOOK_SESSION_ID is set) the per-actor map.
+// Returns true if anything actually changed — callers gate writeState() on it
+// to avoid redundant fsyncs in tight bash-memory loops.
+function markMemorySearched(state) {
+  var sid = process.env.HOOK_SESSION_ID || '';
+  var changed = false;
+  if (state.memorySearched !== true) { state.memorySearched = true; changed = true; }
+  if (sid) {
+    if (!state.memorySearchedBy) state.memorySearchedBy = {};
+    if (state.memorySearchedBy[sid] !== true) { state.memorySearchedBy[sid] = true; changed = true; }
+  }
+  return changed;
+}
 
 function readState() {
   try {
@@ -48,7 +78,7 @@ function loadGateConfig() {
 var config = loadGateConfig();
 var command = process.argv[2];
 
-var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules'];
+var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
 var DANGEROUS = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda'];
 var DIRECTIVE_RE = /^(yes|no|yeah|yep|nope|sure|ok|okay|correct|right|exactly|perfect)\b/i;
 var TASK_RE = /\b(fix|bug|error|implement|add|create|build|write|refactor|debug|test|feature|issue|security|optimi)\b/i;
@@ -77,7 +107,7 @@ switch (command) {
   case 'check-before-scan': {
     if (!config.memory_first) break;
     var s = readState();
-    if (s.memorySearched || !s.memoryRequired) break;
+    if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
     process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search.\n');
@@ -86,7 +116,7 @@ switch (command) {
   case 'check-before-read': {
     if (!config.memory_first) break;
     var s = readState();
-    if (s.memorySearched || !s.memoryRequired) break;
+    if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var fp = process.env.TOOL_INPUT_file_path || '';
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
@@ -102,18 +132,14 @@ switch (command) {
   }
   case 'record-memory-searched': {
     var s = readState();
-    if (!s.memorySearched) {
-      s.memorySearched = true;
-      writeState(s);
-    }
+    if (markMemorySearched(s)) writeState(s);
     break;
   }
   case 'check-bash-memory': {
     var cmd = process.env.TOOL_INPUT_command || '';
     if (/semantic-search|memory search|memory retrieve|memory-search/.test(cmd)) {
       var s = readState();
-      s.memorySearched = true;
-      writeState(s);
+      if (markMemorySearched(s)) writeState(s);
     }
     break;
   }
@@ -196,6 +222,9 @@ switch (command) {
   case 'prompt-reminder': {
     var s = readState();
     s.memorySearched = false;
+    // Wipe per-actor memory tracking too — a new user prompt is a fresh window
+    // for both parent AND any subagents the parent may spawn during this turn.
+    s.memorySearchedBy = {};
     // learningsStored is session-scoped — once stored, it stays true until session reset.
     // Resetting per-prompt caused false blocks when PR creation was on a later prompt.
     var prompt = process.env.CLAUDE_USER_PROMPT || '';
@@ -218,7 +247,7 @@ switch (command) {
     break;
   }
   case 'session-reset': {
-    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null });
+    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null });
     break;
   }
   default:

package/.claude/helpers/statusline.cjs

@@ -382,7 +382,7 @@ function getSwarmStatus() {
 function getSystemMetrics() {
   const memoryMB = Math.floor(process.memoryUsage().heapUsed / 1024 / 1024);
   const learning = getLearningStats();
-  const agentdb = getAgentDBStats();
+  const embeddings = getEmbeddingsStats();
 
   // Intelligence from learning.json
   const learningData = readJSON(path.join(CWD, '.moflo', 'metrics', 'learning.json'));
@@ -393,7 +393,7 @@ function getSystemMetrics() {
     intelligencePct = Math.min(100, Math.floor(learningData.intelligence.score));
   } else {
     const fromPatterns = learning.patterns > 0 ? Math.min(100, Math.floor(learning.patterns / 10)) : 0;
-    const fromVectors = agentdb.vectorCount > 0 ? Math.min(100, Math.floor(agentdb.vectorCount / 100)) : 0;
+    const fromVectors = embeddings.vectorCount > 0 ? Math.min(100, Math.floor(embeddings.vectorCount / 100)) : 0;
     intelligencePct = Math.max(fromPatterns, fromVectors);
   }
 
@@ -423,7 +423,7 @@ function getSystemMetrics() {
     subAgents = activityData.processes.estimated_agents;
   }
 
-  return { memoryMB, contextPct, intelligencePct, subAgents };
+  return { memoryMB, contextPct, intelligencePct, subAgents, embeddings };
 }
 
 // ADR status (count files only — don't read contents)
@@ -484,9 +484,9 @@ function getHooksStatus() {
   return { enabled, total };
 }
 
-// AgentDB stats — reads from cache file written by embedding/memory operations.
+// Embeddings stats — reads from cache file written by embedding/memory ops.
 // No subprocess spawning. Falls back to DB file size estimate if cache is missing.
-function getAgentDBStats() {
+function getEmbeddingsStats() {
   let vectorCount = 0;
   let dbSizeKB = 0;
   let namespaces = 0;
@@ -601,20 +601,25 @@ function getIntegrationStatus() {
   return { mcpServers, hasDatabase, hasApi };
 }
 
-// Upgrade notice (#636, #738, #743) — written by the session-start launcher
-// ONLY while upgrade work is in flight; the launcher deletes the file when
-// work completes. We render it strictly for status='in-progress' so a stale
-// notice (legacy "complete" file from pre-#738 launchers, zombie write from
-// an aborted launcher, future writer mistakes) cannot turn the statusline
-// segment into a permanent column. The launcher's section 0-pre also drops
-// any leftover file at session start as a second line of defence.
+// Upgrade notice (#636, #738, #743) — written by the session-start launcher.
+//   status='in-progress' — work is running; rendered with "(updating…)".
+//   status='completed'   — work just finished; short-TTL post-upgrade badge so
+//                          the user sees something on the very next render
+//                          (Claude Code only paints the statusline AFTER the
+//                          SessionStart hook returns, so the in-progress badge
+//                          has effectively zero visibility window).
+// Anything else is dropped (legacy "complete" pre-#738 files, zombie writes,
+// future writer mistakes) so a stale notice can never turn the segment into a
+// permanent column. Section 0-pre of the launcher also wipes any leftover at
+// session start as a second line of defence.
 function getUpgradeNotice() {
   const data = readJSON(path.join(CWD, '.moflo', 'upgrade-notice.json'));
   if (!data || typeof data !== 'object') return null;
-  if (data.status !== 'in-progress') return null;
+  if (data.status !== 'in-progress' && data.status !== 'completed') return null;
   const expiresAt = data.expiresAt ? new Date(data.expiresAt).getTime() : 0;
   if (!expiresAt || Date.now() > expiresAt) return null;
   return {
+    status: data.status,
     kind: data.kind === 'repair' ? 'repair' : 'upgrade',
     from: typeof data.from === 'string' ? data.from : '',
     to: typeof data.to === 'string' ? data.to : '',
@@ -623,14 +628,20 @@ function getUpgradeNotice() {
 
 function formatUpgradeNoticeSegment(notice) {
   if (!notice) return '';
-  const suffix = ` ${c.dim}(updating…)${c.reset}`;
+  const inFlight = notice.status === 'in-progress';
+  const suffix = inFlight ? ` ${c.dim}(updating…)${c.reset}` : '';
+  // Pick body text: repair > in-flight version range > completed "upgraded to"
+  // > bare "upgraded" fallback when no version is known.
+  let body;
   if (notice.kind === 'repair') {
-    return `${c.brightYellow}📦 install repaired${c.reset}${suffix}`;
+    body = 'install repaired';
+  } else if (inFlight) {
+    body = notice.from && notice.to ? `${notice.from} → ${notice.to}` : (notice.to || 'upgraded');
+  } else {
+    const target = notice.to || notice.from || '';
+    body = target ? `upgraded to ${target}` : 'upgraded';
   }
-  const versions = notice.from && notice.to
-    ? `${notice.from} → ${notice.to}`
-    : (notice.to || 'upgraded');
-  return `${c.brightYellow}📦 ${versions}${c.reset}${suffix}`;
+  return `${c.brightYellow}📦 ${body}${c.reset}${suffix}`;
 }
 
 // Session stats (pure file reads)
@@ -784,6 +795,25 @@ function generateDashboard() {
     );
   }
 
+  // Embeddings line \u2014 vector store stats from .moflo/vector-stats.json.
+  // Reuses `system.embeddings` (already computed by getSystemMetrics()) instead
+  // of re-probing the cache file on every render.
+  {
+    const vec = system.embeddings;
+    if (vec.vectorCount > 0) {
+      const hnswInd = vec.hasHnsw ? `${c.brightGreen}\u26A1${c.reset}` : '';
+      const sizeDisp = vec.dbSizeKB >= 1024 ? `${(vec.dbSizeKB / 1024).toFixed(1)}MB` : `${vec.dbSizeKB}KB`;
+      const eParts = [
+        `${c.cyan}Vectors${c.reset} ${c.brightGreen}\u25CF${vec.vectorCount}${c.reset}${hnswInd}`,
+        `${c.cyan}Size${c.reset} ${c.brightWhite}${sizeDisp}${c.reset}`,
+      ];
+      if (vec.namespaces > 0) {
+        eParts.push(`${c.cyan}NS${c.reset} ${c.brightWhite}${vec.namespaces}${c.reset}`);
+      }
+      lines.push(`${c.brightCyan}\uD83D\uDCCA Embeddings${c.reset}  ${eParts.join(`  ${c.dim}\u2502${c.reset}  `)}`);
+    }
+  }
+
   // MCP line
   if (SL_CONFIG.show_mcp) {
     const parts = [];
@@ -795,7 +825,7 @@ function generateDashboard() {
     }
     if (integration.hasDatabase) parts.push(`${c.brightGreen}\u25C6${c.reset}DB`);
     if (parts.length > 0) {
-      lines.push(`${c.brightCyan}\uD83D\uDCCA MCP${c.reset}  ${parts.join(`  ${c.dim}\u2502${c.reset}  `)}`);
+      lines.push(`${c.brightCyan}\uD83D\uDD0C MCP${c.reset}  ${parts.join(`  ${c.dim}\u2502${c.reset}  `)}`);
     }
   }
 
@@ -835,7 +865,7 @@ function generateCompactDashboard() {
   pushUpgradeNoticeSegment(lines);
   lines.push(header);
 
-  // Combined swarm + mcp line
+  // Combined swarm + embeddings + mcp line
   const segments = [];
   if (SL_CONFIG.show_swarm) {
     const swarm = getSwarmStatus();
@@ -845,6 +875,18 @@ function generateCompactDashboard() {
       `${c.brightYellow}\uD83E\uDD16${c.reset} ${swarmInd}[${agentsColor}${swarm.activeAgents}${c.reset}/${c.brightWhite}${swarm.maxAgents}${c.reset}]`
     );
   }
+  // Embeddings \u2014 always-on when vectorCount > 0; self-hides on a fresh install.
+  // Compact doesn't call getSystemMetrics() so this is the only probe per render.
+  {
+    const vec = getEmbeddingsStats();
+    if (vec.vectorCount > 0) {
+      const hnswInd = vec.hasHnsw ? '\u26A1' : '';
+      const sizeDisp = vec.dbSizeKB >= 1024 ? `${(vec.dbSizeKB / 1024).toFixed(1)}MB` : `${vec.dbSizeKB}KB`;
+      segments.push(
+        `${c.brightCyan}\uD83D\uDCCA${c.reset} ${c.brightGreen}${vec.vectorCount}${hnswInd}${c.reset} ${c.dim}(${sizeDisp})${c.reset}`
+      );
+    }
+  }
   if (SL_CONFIG.show_mcp) {
     const integration = getIntegrationStatus();
     if (integration.mcpServers.total > 0) {
@@ -863,15 +905,16 @@ function generateCompactDashboard() {
 // JSON output
 function generateJSON() {
   const git = getGitInfo();
+  const system = getSystemMetrics();
   return {
     user: { name: git.name, gitBranch: git.gitBranch, modelName: getModelName() },
     v3Progress: getV3Progress(),
     security: getSecurityStatus(),
     swarm: getSwarmStatus(),
-    system: getSystemMetrics(),
+    system,
     adrs: getADRStatus(),
     hooks: getHooksStatus(),
-    agentdb: getAgentDBStats(),
+    embeddings: system.embeddings,
     tests: getTestStats(),
     git: { modified: git.modified, untracked: git.untracked, staged: git.staged, ahead: git.ahead, behind: git.behind },
     upgradeNotice: getUpgradeNotice(),

package/.claude/helpers/subagent-bootstrap.json

@@ -0,0 +1,3 @@
+{
+  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/shipped/moflo-subagents.md` protocol."
+}

package/.claude/helpers/subagent-start.cjs

@@ -1,22 +1,58 @@
-#!/usr/bin/env node
-/**
- * SubagentStart Hook — injects a directive into every subagent's context
- * telling it to read the subagent protocol guidance before doing any work.
- *
- * Output format: JSON with additionalContext (Claude Code hook protocol).
- * Exit 0 = allow (SubagentStart cannot block).
- */
-'use strict';
-
-const output = {
-  hookSpecificOutput: {
-    hookEventName: 'SubagentStart',
-    additionalContext:
-      'MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). ' +
-      'The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. ' +
-      'After memory search, follow `.claude/guidance/shipped/moflo-subagents.md` protocol.',
-  },
-};
-
-process.stdout.write(JSON.stringify(output));
-process.exit(0);
+#!/usr/bin/env node
+/**
+ * SubagentStart Hook — injects a directive into every subagent's context
+ * telling it to read the subagent protocol guidance before doing any work.
+ *
+ * Output format: JSON with additionalContext (Claude Code hook protocol).
+ * Exit 0 = allow (SubagentStart cannot block).
+ *
+ * Source of truth: ./subagent-bootstrap.json (sibling). The TS export at
+ * `src/cli/services/subagent-bootstrap.ts` reads the same file so future
+ * agent_spawn surfaces (epic #798 stories 3 + 9) inject byte-identical text.
+ *
+ * Inline FALLBACK keeps the hook functional if the JSON sibling is ever
+ * missing — a SubagentStart that emits nothing leaves the memory-first gate
+ * un-announced and silently regresses subagent behavior.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Defense-in-depth copy of the canonical directive in subagent-bootstrap.json.
+// Kept as a single-line literal so the parity test in tests/bin/subagent-start.test.ts
+// can verify it matches the JSON via plain substring containment.
+const FALLBACK_DIRECTIVE = 'MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/shipped/moflo-subagents.md` protocol.';
+
+function loadDirective() {
+  const jsonPath = path.join(__dirname, 'subagent-bootstrap.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(jsonPath, 'utf8');
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') {
+      process.stderr.write(`[subagent-start] read failed: ${err.message} — using inline fallback\n`);
+    }
+    return FALLBACK_DIRECTIVE;
+  }
+  try {
+    const data = JSON.parse(raw);
+    if (typeof data.directive === 'string' && data.directive.length > 0) {
+      return data.directive;
+    }
+    process.stderr.write('[subagent-start] subagent-bootstrap.json missing string `directive` — using inline fallback\n');
+  } catch (err) {
+    process.stderr.write(`[subagent-start] subagent-bootstrap.json parse failed: ${err.message} — using inline fallback\n`);
+  }
+  return FALLBACK_DIRECTIVE;
+}
+
+const output = {
+  hookSpecificOutput: {
+    hookEventName: 'SubagentStart',
+    additionalContext: loadDirective(),
+  },
+};
+
+process.stdout.write(JSON.stringify(output));
+process.exit(0);

package/.claude/skills/swarm-advanced/SKILL.md

@@ -33,6 +33,83 @@ mcp__moflo__agent_spawn({ type: "researcher", name: "swarm-advanced" })
 // 3. Orchestrate tasks
 ```
 
+### Dynamic Scaling
+Use `mcp__moflo__swarm_scale` to grow or shrink the agent pool to a target size
+without re-initializing the swarm. Three strategies are available:
+
+```javascript
+// Burst-spawn 8 workers all at once (load test, big batch)
+mcp__moflo__swarm_scale({
+  targetAgents: 8,
+  scaleStrategy: "immediate",
+  agentTypes: ["worker"],
+  reason: "load-test ramp"
+})
+
+// Rate-limited ramp (1 agent / 200ms) — gentler on the coordinator
+mcp__moflo__swarm_scale({
+  targetAgents: 12,
+  scaleStrategy: "gradual",
+  agentTypes: ["coder", "tester"]
+})
+
+// Adaptive: chunks scale with current coordinator load
+mcp__moflo__swarm_scale({ targetAgents: 4, scaleStrategy: "adaptive" })
+```
+
+The tool returns `{ previousAgents, currentAgents, scalingStatus, addedAgents,
+removedAgents }` so callers can verify the swarm reached the target. Scale-down
+prefers idle agents first, then oldest by heartbeat.
+
+### Task Orchestration
+
+The `task_*` family talks to the same UnifiedSwarmCoordinator that
+`swarm_init` / `agent_spawn` use, so tasks created here flow through the
+same scoring scheduler that load-balances across idle agents.
+
+```javascript
+// Single task — coordinator picks the lowest-workload agent automatically
+mcp__moflo__task_create({
+  type: "coding",
+  description: "Implement OAuth refresh flow",
+  priority: "high"
+})
+
+// Direct dispatch to a known agent (skip the scheduler)
+mcp__moflo__task_assign({
+  taskId: "task_swarm-…_3",
+  agentId: "agent-coder-…"
+})
+
+// Domain-routed dispatch (queen / security / core / integration / support)
+mcp__moflo__task_assign({
+  taskId: "task_swarm-…_4",
+  domain: "security"
+})
+
+// Submit a batch — load-balanced across available agents in one call.
+// 5 tasks across 3 idle agents → no agent ends up with more than 2.
+mcp__moflo__task_orchestrate({
+  tasks: [
+    { type: "coding", description: "endpoint A" },
+    { type: "coding", description: "endpoint B" },
+    { type: "testing", description: "tests for A" },
+    { type: "testing", description: "tests for B" },
+    { type: "review",  description: "PR review" }
+  ]
+})
+
+// Mark a task done and record its outcome
+mcp__moflo__task_complete({
+  taskId: "task_swarm-…_3",
+  result: { ok: true, summary: "merged in PR #842" }
+})
+```
+
+`task_orchestrate` returns `{ submitted, assigned, queued, rejected, tasks,
+errors }` — `assigned` is the count whose agents accepted them on submit;
+the rest are queued and will be picked up as agents go idle.
+
 ## Core Concepts
 
 ### Swarm Topologies

package/README.md

@@ -21,7 +21,7 @@ Restart Claude Code (or your MCP client). That's it — memory, indexing, gates,
 
 Or — just ask Claude to install MoFlo into your project and initialize it!
 
-To verify everything is running, ask Claude to run `flo doctor` with full diagnostics after restarting. If anything fails, ask Claude to fix it with `flo doctor --fix`.
+To verify everything is running, ask Claude to run `flo healer` with full diagnostics after restarting. If anything fails, ask Claude to fix it with `flo healer --fix`. (`flo doctor` is still accepted as an alias.)
 
 ## Opinionated Defaults
 
@@ -97,7 +97,7 @@ In interactive mode (`flo init` without `--yes`), it shows what it found and let
 If `flo init` detects an existing `.claude/settings.json` or `.claude-flow/` directory (from a prior Claude Flow or Ruflo installation), it treats the project as already initialized and runs in **update mode** — merging MoFlo's hooks and configuration into your existing setup without overwriting your data. Specifically:
 
 - **Hooks** — If your `.claude/settings.json` already has MoFlo-style gate hooks (`flo gate`), the hooks step is skipped. Otherwise, MoFlo's hooks are written into the file (existing non-MoFlo hooks are not removed).
-- **MCP servers** — MoFlo registers itself as the `moflo` server in `.mcp.json`. If you had `claude-flow` or `ruflo` MCP servers configured previously, those entries remain untouched — you can remove them manually once you've verified MoFlo is working. The `flo doctor` command checks for the `moflo` server specifically.
+- **MCP servers** — MoFlo registers itself as the `moflo` server in `.mcp.json`. If you had `claude-flow` or `ruflo` MCP servers configured previously, those entries remain untouched — you can remove them manually once you've verified MoFlo is working. The `flo healer` command checks for the `moflo` server specifically.
 - **Config files** — `moflo.yaml`, `CLAUDE.md`, and `.claude/skills/flo/` follow the same skip-if-exists logic. Use `--force` to regenerate them.
 
 To force a clean re-initialization over an existing setup:
@@ -162,7 +162,7 @@ code_map:
 ```bash
 flo memory index-guidance    # Index your guidance docs
 flo memory code-map          # Index your code structure
-flo doctor                   # Verify everything works
+flo healer                   # Verify everything works (alias: flo doctor)
 ```
 
 Both indexes run automatically at session start after this, so you only need to run them manually on first setup or after major structural changes. The first index may take a minute or two on large codebases (1,000+ files) but runs in the background — you can start working immediately. Subsequent indexes are incremental and typically finish in under a second. To reindex everything at once:
@@ -293,16 +293,16 @@ For simple epics with independent stories, `/flo <epic>` is all you need. For co
 `flo epic` is the robust epic runner — it adds persistent state, resume from failure, and per-story auto-merge on top of `/flo`. It takes a GitHub epic issue number:
 
 ```bash
-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 --strategy auto-merge      # Per-story PRs with auto-merge between stories
+flo epic 42                                # Fetch epic #42, run all stories sequentially
+flo epic 42 --dry-run                      # Preview execution plan without running
+flo epic 42 --strategy auto-merge          # Per-story PRs with auto-merge between stories
 flo epic status 42                         # Check progress (which stories passed/failed)
 flo epic reset 42                          # Reset state for re-run
 ```
 
-`flo epic` fetches the epic from GitHub, extracts child stories from checklists, numbered references, and `## Stories` / `## Tasks` sections, 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.
+`flo epic` fetches the epic from GitHub, extracts child stories from checklists, numbered references, and `## Stories` / `## Tasks` sections, then runs each through `/flo` with state tracking. If a story fails, you can fix the issue and re-run `flo epic 42` — it resumes from where it left off, skipping already-passed stories. (`flo epic run 42` is an explicit alias for the same shorthand.)
 
-| | `/flo <epic>` | `flo epic run <epic>` |
+| | `/flo <epic>` | `flo epic <epic>` |
 |---|---|---|
 | **State tracking** | No | Yes (`epic-state` memory namespace) |
 | **Resume from failure** | No | Yes (skips passed stories) |
@@ -484,16 +484,18 @@ flo gate session-reset           # Reset gate state
 ### Diagnostics
 
 ```bash
-flo doctor                       # Quick health check (environment, deps, config)
-flo doctor --fix                 # Auto-fix issues (memory DB, daemon, config, MCP, zombies)
+flo healer                       # Quick health check (environment, deps, config)
+flo healer --fix                 # Auto-fix issues (memory DB, daemon, config, MCP, zombies)
 flo diagnose                     # Full integration test (memory, swarm, hive, hooks, neural)
 flo diagnose --suite memory      # Run only memory tests
 flo diagnose --json              # JSON output for CI/automation
 ```
 
-#### `flo doctor` — Health Check
+`flo doctor` is still accepted as an alias for `flo healer` — every flag and subcommand below works under either name.
 
-`flo doctor` runs 28 parallel health checks against your environment and reports pass/warn/fail for each:
+#### `flo healer` — Health Check
+
+`flo healer` runs 28 parallel health checks against your environment and reports pass/warn/fail for each:
 
 | Check | What it verifies |
 |-------|-----------------|
@@ -526,7 +528,7 @@ flo diagnose --json              # JSON output for CI/automation
 | **MofloDb Bridge** | Memory DB adapter (sql.js + HNSW) is wired and routable |
 | **Sandbox Tier** | Detects which sandbox backend is available (Docker / bwrap / sandbox-exec / none) |
 
-**Auto-fix mode** (`flo doctor --fix`) attempts to repair each failing check automatically:
+**Auto-fix mode** (`flo healer --fix`) attempts to repair each failing check automatically:
 
 | Issue | What `--fix` does |
 |-------|------------------|
@@ -539,21 +541,21 @@ flo diagnose --json              # JSON output for CI/automation
 | Claude Code CLI missing | Installs `@anthropic-ai/claude-code` globally |
 | Zombie processes | Kills orphaned MoFlo processes (tracked + OS-level scan) |
 
-After auto-fixing, doctor re-runs all checks and shows the updated results. Issues that can't be fixed automatically are listed with manual fix commands.
+After auto-fixing, healer re-runs all checks and shows the updated results. Issues that can't be fixed automatically are listed with manual fix commands.
 
 Additional flags:
 
 ```bash
-flo doctor --install             # Auto-install missing Claude Code CLI
-flo doctor --kill-zombies        # Find and kill orphaned MoFlo processes
-flo doctor -c memory             # Check only a specific component
-flo doctor -c embeddings         # Check only embeddings health
-flo doctor --verbose             # Verbose output
+flo healer --install             # Auto-install missing Claude Code CLI
+flo healer --kill-zombies        # Find and kill orphaned MoFlo processes
+flo healer -c memory             # Check only a specific component
+flo healer -c embeddings         # Check only embeddings health
+flo healer --verbose             # Verbose output
 ```
 
 #### `flo diagnose` — Integration Tests
 
-While `doctor` checks your environment, `diagnose` exercises every subsystem end-to-end: memory CRUD, embedding generation, semantic search, swarm lifecycle, hive-mind consensus, task management, hooks, config, neural patterns, and init idempotency. All test data is cleaned up after each test — nothing is left behind.
+While `healer` checks your environment, `diagnose` exercises every subsystem end-to-end: memory CRUD, embedding generation, semantic search, swarm lifecycle, hive-mind consensus, task management, hooks, config, neural patterns, and init idempotency. All test data is cleaned up after each test — nothing is left behind.
 
 ### GitHub Repository Setup
 
@@ -583,7 +585,7 @@ flo --version                    # Show version
 
 ### Hooks (enabled OOTB)
 
-Hooks are shell commands that Claude Code runs automatically at specific points in its lifecycle. MoFlo installs 20 hook bindings across 8 lifecycle events. You don't invoke these — they fire automatically.
+Hooks are shell commands that Claude Code runs automatically at specific points in its lifecycle. MoFlo installs 23 hook bindings across 8 lifecycle events. You don't invoke these — they fire automatically.
 
 | Hook Event | What fires | What it does | Enabled OOTB |
 |------------|-----------|-------------|:---:|
@@ -593,9 +595,12 @@ Hooks are shell commands that Claude Code runs automatically at specific points
 | **PreToolUse: Bash** | `flo gate check-dangerous-command` | Safety check on shell commands | Yes |
 | **PreToolUse: Bash** | `flo gate check-before-pr` | Validates PR readiness before `gh pr create` | Yes |
 | **PostToolUse: Write/Edit** | `flo hooks post-edit` | Records edit outcome, optionally trains neural patterns | Yes |
+| **PostToolUse: Write/Edit** | `flo gate reset-edit-gates` | Resets edit-related gate state after the write completes | Yes |
 | **PostToolUse: Agent** | `flo hooks post-task` | Records task completion, feeds outcome into routing learner | Yes |
 | **PostToolUse: TaskCreate** | `flo gate record-task-created` | Records that a task was registered (clears TaskCreate gate) | Yes |
 | **PostToolUse: Bash** | `flo gate check-bash-memory` | Detects memory search commands in Bash (clears memory gate) | Yes |
+| **PostToolUse: Bash** | `flo gate record-test-run` | Records test runs from Bash for the test-output gate | Yes |
+| **PostToolUse: Skill** | `flo gate record-skill-run` | Records that a skill was invoked (clears skill-related gates) | Yes |
 | **PostToolUse: memory_search** | `flo gate record-memory-searched` | Records that memory was searched (clears memory-first gate) | Yes |
 | **PostToolUse: TaskUpdate** | `flo gate check-task-transition` | Validates task state transitions (prevents skipping states) | Yes |
 | **PostToolUse: memory_store** | `flo gate record-learnings-stored` | Records that learnings were persisted to memory | Yes |

package/bin/gate-hook.mjs

@@ -25,6 +25,13 @@ try { if (stdinData.trim()) hookContext = JSON.parse(stdinData); } catch (e) {}
 // Pass tool info as env vars for gate.cjs
 var env = Object.assign({}, process.env);
 if (hookContext.tool_name) env.TOOL_NAME = hookContext.tool_name;
+// Forward Claude Code's session_id so gate.cjs can enforce memory-first
+// per-actor (#838) — each spawned subagent gets its own session_id, so a
+// shared workflow-state.json no longer lets one subagent's directive be
+// silently satisfied by the parent's earlier search.
+if (typeof hookContext.session_id === 'string' && hookContext.session_id) {
+  env.HOOK_SESSION_ID = hookContext.session_id;
+}
 if (hookContext.tool_input && typeof hookContext.tool_input === 'object') {
   Object.keys(hookContext.tool_input).forEach(function(key) {
     if (typeof hookContext.tool_input[key] === 'string') {