moflo 4.9.20 → 4.9.21

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

@@ -236,6 +236,18 @@ function generateHooksConfig(config) {
                     { type: 'command', command: gateHookCmd('check-before-pr'), timeout: 2000 },
                 ],
             },
+            // #931 — TaskCreate REMINDER + namespace hint moved here from
+            // UserPromptSubmit. They only matter when Claude is about to spawn an
+            // Agent; emitting per-prompt cost ~90 tokens × every prompt × every
+            // consumer. Advisory only — never blocks. Routed through gate-hook.mjs
+            // so Claude Code's session_id is forwarded as HOOK_SESSION_ID — the
+            // namespace hint emission tracks per-actor (mirror of #879's fix for
+            // record-memory-searched), so subagents that spawn their own agents
+            // still get the hint on their first check.
+            {
+                matcher: '^Agent$',
+                hooks: [{ type: 'command', command: gateHookCmd('check-before-agent'), timeout: 2000 }],
+            },
         ];
     }
     // PostToolUse — record outcomes for learning
@@ -270,13 +282,16 @@ function generateHooksConfig(config) {
                 hooks: [{ type: 'command', command: gateHookCmd('record-skill-run'), timeout: 2000 }],
             },
             {
-                // Simplified matcher — anchored regex with parens doesn't match MCP tool names reliably.
-                // Use gateHookCmd (not gateCmd) so the wrapper forwards Claude Code's session_id as
-                // HOOK_SESSION_ID — record-memory-searched needs this to mark the per-actor map
-                // (memorySearchedBy[sid]) that check-before-read consults under #838's per-actor gating.
-                // Without it, the legacy boolean is set but the per-actor map stays empty, and the gate
-                // blocks every Read forever within the turn (issue #879).
-                matcher: 'mcp__moflo__memory_',
+                // Anchored alternation — Claude Code anchors hook matchers (`^…$` semantics),
+                // so a bare `mcp__moflo__memory_` never matches any real MCP tool name and the
+                // hook silently no-ops (#929 regression). Listing the explicit suffixes keeps
+                // the matcher narrow while still catching every memory_* tool we ship.
+                // Use gateHookCmd (not gateCmd) so the wrapper forwards Claude Code's session_id
+                // as HOOK_SESSION_ID — record-memory-searched needs this to mark the per-actor
+                // map (memorySearchedBy[sid]) that check-before-read consults under #838's
+                // per-actor gating. Without it, the legacy boolean is set but the per-actor map
+                // stays empty, and the gate blocks every Read forever within the turn (#879).
+                matcher: '^mcp__moflo__memory_(search|retrieve|list|stats|store)$',
                 hooks: [{ type: 'command', command: gateHookCmd('record-memory-searched'), timeout: 3000 }],
             },
             {
@@ -289,12 +304,15 @@ function generateHooksConfig(config) {
             },
         ];
     }
-    // UserPromptSubmit — gate reminders + intelligent task routing.
-    // The prompt-reminder hook is REQUIRED — it resets memorySearched / memorySearchedBy
-    // and reclassifies memoryRequired from the new prompt. Without it, gate state leaks
-    // across prompts: a previous turn's "satisfied" state survives, OR a previous turn's
-    // "armed" state never clears. Two separate hook entries (not chained) so an exception
-    // in prompt-hook.mjs doesn't skip the reset.
+    // UserPromptSubmit — per-prompt state reset + Context warnings.
+    // Two separate hook entries (not chained) so an exception in prompt-hook.mjs
+    // doesn't skip the reset. The first hook runs prompt-hook.mjs which invokes
+    // gate.cjs `prompt-reminder` (full reset + interactionCount + Context
+    // warnings). The second hook runs `prompt-state-reset` — a defensive
+    // safety-net that re-applies the idempotent state reset (memorySearched,
+    // memorySearchedBy, memoryRequired, lastNamespaceHint) without
+    // double-incrementing interactionCount or duplicating any user-visible
+    // emission (#931).
     if (config.userPromptSubmit) {
         hooks.UserPromptSubmit = [
             {
@@ -304,7 +322,7 @@ function generateHooksConfig(config) {
             },
             {
                 hooks: [
-                    { type: 'command', command: gateHookCmd('prompt-reminder'), timeout: 3000 },
+                    { type: 'command', command: gateHookCmd('prompt-state-reset'), timeout: 3000 },
                 ],
             },
         ];

package/dist/src/cli/services/hook-block-hash.js

@@ -59,6 +59,10 @@ export function getReferenceHookBlock() {
                 matcher: '^Bash$',
                 hooks: [gateHook('check-dangerous-command', 2000), gateHook('check-before-pr', 2000)],
             },
+            // #931 — TaskCreate REMINDER + namespace hint advisory at Agent-spawn time.
+            // Routed via gate-hook.mjs so HOOK_SESSION_ID is forwarded for per-actor
+            // single-shot emission of the namespace hint.
+            { matcher: '^Agent$', hooks: [gateHook('check-before-agent', 2000)] },
         ],
         PostToolUse: [
             {
@@ -72,13 +76,14 @@ export function getReferenceHookBlock() {
                 hooks: [gateHook('check-bash-memory', 2000), gateHook('record-test-run', 2000)],
             },
             { matcher: '^Skill$', hooks: [gateHook('record-skill-run', 2000)] },
-            { matcher: 'mcp__moflo__memory_', hooks: [gateHook('record-memory-searched', 3000)] },
+            { matcher: '^mcp__moflo__memory_(search|retrieve|list|stats|store)$', hooks: [gateHook('record-memory-searched', 3000)] },
             { matcher: '^TaskUpdate$', hooks: [gateCjs('check-task-transition', 2000)] },
             { matcher: '^mcp__moflo__memory_store$', hooks: [gateCjs('record-learnings-stored', 2000)] },
         ],
         UserPromptSubmit: [
             { hooks: [helperHook('prompt-hook.mjs', '', 3000)] },
-            { hooks: [gateHook('prompt-reminder', 3000)] },
+            // #931 — Defensive safety-net hook. State reset only, no emission.
+            { hooks: [gateHook('prompt-state-reset', 3000)] },
         ],
         SubagentStart: [
             { hooks: [helperHook('subagent-start.cjs', '', 2000)] },

package/dist/src/cli/services/hook-wiring.js

@@ -18,6 +18,9 @@ export const REQUIRED_HOOK_WIRING = [
     { event: 'PreToolUse', pattern: 'check-before-read' },
     { event: 'PreToolUse', pattern: 'check-dangerous-command' },
     { event: 'PreToolUse', pattern: 'check-before-pr' },
+    // #931 — TaskCreate REMINDER + namespace hint emit only at Agent spawn now,
+    // not on every prompt. Saves ~90 tokens × every prompt × every consumer.
+    { event: 'PreToolUse', pattern: 'check-before-agent' },
     { event: 'PostToolUse', pattern: 'record-task-created' },
     { event: 'PostToolUse', pattern: 'record-memory-searched' },
     { event: 'PostToolUse', pattern: 'check-task-transition' },
@@ -26,7 +29,14 @@ export const REQUIRED_HOOK_WIRING = [
     { event: 'PostToolUse', pattern: 'record-test-run' },
     { event: 'PostToolUse', pattern: 'record-skill-run' },
     { event: 'PostToolUse', pattern: 'reset-edit-gates' },
-    { event: 'UserPromptSubmit', pattern: 'prompt-reminder' },
+    // First UserPromptSubmit hook (prompt-hook.mjs internally calls
+    // `gate.cjs prompt-reminder`). Substring check tolerates either the
+    // shipped helper-script command or an inlined gate call.
+    { event: 'UserPromptSubmit', pattern: 'prompt-hook.mjs' },
+    // Second (defensive) UserPromptSubmit hook — state reset only. Replaced
+    // the duplicate `prompt-reminder` wiring that was emitting the TaskCreate
+    // REMINDER twice per prompt (#931).
+    { event: 'UserPromptSubmit', pattern: 'prompt-state-reset' },
 ];
 /**
  * Map gate pattern → hook entry to add when missing from settings.json.
@@ -41,14 +51,29 @@ export const HOOK_ENTRY_MAP = {
     // record-memory-searched MUST go through gate-hook.mjs (not gate.cjs directly)
     // — the wrapper forwards Claude Code's session_id as HOOK_SESSION_ID, which
     // markMemorySearched needs to stamp the per-actor map (#879).
-    'record-memory-searched': { event: 'PostToolUse', matcher: 'mcp__moflo__memory_', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-memory-searched', timeout: 3000 } },
+    // Matcher MUST be a fully-anchored regex: Claude Code anchors hook matchers
+    // (`^...$` semantics), so a bare `mcp__moflo__memory_` never fires for any
+    // tool name (#929 regression — the hook silently no-ops, leaving every
+    // memory_search uncounted by the gate).
+    'record-memory-searched': { event: 'PostToolUse', matcher: '^mcp__moflo__memory_(search|retrieve|list|stats|store)$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-memory-searched', timeout: 3000 } },
     'check-task-transition': { event: 'PostToolUse', matcher: '^TaskUpdate$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" check-task-transition', timeout: 2000 } },
     'record-learnings-stored': { event: 'PostToolUse', matcher: '^mcp__moflo__memory_store$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" record-learnings-stored', timeout: 2000 } },
     'check-bash-memory': { event: 'PostToolUse', matcher: '^Bash$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" check-bash-memory', timeout: 2000 } },
     'record-test-run': { event: 'PostToolUse', matcher: '^Bash$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-test-run', timeout: 2000 } },
     'record-skill-run': { event: 'PostToolUse', matcher: '^Skill$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" record-skill-run', timeout: 2000 } },
     'reset-edit-gates': { event: 'PostToolUse', matcher: '^(Write|Edit|MultiEdit)$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" reset-edit-gates', timeout: 2000 } },
-    'prompt-reminder': { event: 'UserPromptSubmit', matcher: '', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" prompt-reminder', timeout: 3000 } },
+    // #931 — Agent-time advisory; never blocks. Pulled the TaskCreate REMINDER
+    // and namespace hint out of prompt-reminder so they fire only when Claude is
+    // actually about to spawn an Agent. Routed via gate-hook.mjs so Claude Code's
+    // session_id is forwarded as HOOK_SESSION_ID — the namespace hint emission
+    // is per-actor single-shot (mirror of #879's record-memory-searched fix).
+    'check-before-agent': { event: 'PreToolUse', matcher: '^Agent$', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" check-before-agent', timeout: 2000 } },
+    // Re-add the prompt-hook.mjs wiring as its own bare UserPromptSubmit block
+    // when missing. Empty matcher = bare block, like settings-generator emits.
+    'prompt-hook.mjs': { event: 'UserPromptSubmit', matcher: '', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/prompt-hook.mjs"', timeout: 3000 } },
+    // Defensive safety-net — runs gate.cjs `prompt-state-reset` if prompt-hook.mjs
+    // throws before completing the per-prompt state reset. State-only, no emission.
+    'prompt-state-reset': { event: 'UserPromptSubmit', matcher: '', hook: { type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" prompt-state-reset', timeout: 3000 } },
 };
 /**
  * Inspect a parsed settings.json object for missing required hook wirings
@@ -104,6 +129,42 @@ export const HOOK_REWRITE_RULES = [
         from: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" check-bash-memory',
         to: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" check-bash-memory',
     },
+    // Issue #931 — the second UserPromptSubmit hook used to invoke
+    // gate-hook.mjs `prompt-reminder`, which (a) duplicated the first hook's
+    // emission of `REMINDER: Use TaskCreate...` per prompt and (b) double-
+    // incremented `interactionCount`. The first hook (prompt-hook.mjs) still
+    // calls gate.cjs `prompt-reminder` internally for the full reset + Context
+    // warnings; the safety-net hook now runs `prompt-state-reset` instead —
+    // idempotent state reset, no emission, no increment.
+    {
+        name: '#931: dedupe UserPromptSubmit prompt-reminder → prompt-state-reset',
+        from: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" prompt-reminder',
+        to: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" prompt-state-reset',
+    },
+    // Issue #931 — `check-before-agent` was first wired through gate.cjs
+    // directly (no stdin parsing). Without HOOK_SESSION_ID the namespace hint's
+    // per-actor tracking falls back to a single `_legacy_` bucket, so a
+    // subagent spawning its own agent would silently miss the hint after the
+    // parent already consumed it. Route through gate-hook.mjs (the same wrapper
+    // that fixed #879) so each session_id gets its own single-shot.
+    {
+        name: '#931: route check-before-agent → gate-hook.mjs (forwards HOOK_SESSION_ID)',
+        from: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" check-before-agent',
+        to: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" check-before-agent',
+    },
+];
+export const MATCHER_REWRITE_RULES = [
+    // Issue #929 — Claude Code anchors hook matchers (`^…$` semantics), so a
+    // bare `mcp__moflo__memory_` never matches any real MCP tool name and the
+    // record-memory-searched stamp silently no-ops on every memory_search.
+    // The fix is anchored alternation. Existing consumers that upgrade through
+    // this version self-heal here without needing `flo doctor --fix`.
+    {
+        name: '#929: anchor record-memory-searched matcher',
+        from: 'mcp__moflo__memory_',
+        to: '^mcp__moflo__memory_(search|retrieve|list|stats|store)$',
+        cmdContains: 'record-memory-searched',
+    },
 ];
 /**
  * Apply HOOK_REWRITE_RULES to every hook command in `settings.hooks.*`.
@@ -135,6 +196,28 @@ export function rewriteIncorrectHookWiring(settings) {
         if (count > 0)
             rewrites.push({ name: rule.name, count });
     }
+    for (const rule of MATCHER_REWRITE_RULES) {
+        let count = 0;
+        for (const eventName of Object.keys(hooks)) {
+            const eventArray = hooks[eventName];
+            if (!Array.isArray(eventArray))
+                continue;
+            for (const block of eventArray) {
+                if (block.matcher !== rule.from)
+                    continue;
+                const blockHooks = block.hooks;
+                if (!Array.isArray(blockHooks))
+                    continue;
+                const hasMatchingCmd = blockHooks.some((h) => typeof h.command === 'string' && h.command.includes(rule.cmdContains));
+                if (!hasMatchingCmd)
+                    continue;
+                block.matcher = rule.to;
+                count++;
+            }
+        }
+        if (count > 0)
+            rewrites.push({ name: rule.name, count });
+    }
     return { settings, rewrites };
 }
 //# sourceMappingURL=hook-wiring.js.map

package/dist/src/cli/services/subagent-bootstrap.js

@@ -21,7 +21,7 @@ const BOOTSTRAP_JSON_REL = '.claude/helpers/subagent-bootstrap.json';
 // Defense-in-depth copy of the canonical directive in subagent-bootstrap.json.
 // Kept as a single-line literal so the parity test 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.';
+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/moflo-subagents.md` protocol.';
 function loadDirective() {
     const jsonPath = locateMofloRootPath(BOOTSTRAP_JSON_REL);
     if (!jsonPath) {

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.20",
+  "version": "4.9.21",
   "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.19",
+    "moflo": "^4.9.20",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"

package/scripts/post-install-bootstrap.mjs

@@ -41,6 +41,7 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
+  readFileSync,
   statSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -175,9 +176,27 @@ export async function runBootstrap({
   // 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.
+  //
+  // Two paths can hit this branch:
+  //   1. The source's own postinstall: mofloRoot === projectRoot (path equality).
+  //   2. The DEPENDENCY's postinstall on `npm ci` of the moflo source repo:
+  //      mofloRoot = <src>/node_modules/moflo/, projectRoot = <src>/. Path
+  //      equality fails — moflo-as-its-own-devDep would clobber the source
+  //      .claude/helpers/ with the OLDER published artifacts, breaking CI
+  //      against any in-flight fixes. Detect by reading projectRoot's
+  //      package.json name and bailing whenever it's "moflo".
   if (resolve(projectRoot) === resolve(mofloRoot)) {
     return { ran: false, reason: 'moflo-self-install' };
   }
+  try {
+    const projectPkgPath = resolve(projectRoot, 'package.json');
+    if (existsSync(projectPkgPath)) {
+      const projectPkg = JSON.parse(readFileSync(projectPkgPath, 'utf-8'));
+      if (projectPkg.name === 'moflo') {
+        return { ran: false, reason: 'moflo-self-dev-install' };
+      }
+    }
+  } catch { /* unparseable package.json — fall through, treat as consumer */ }
 
   const binDir = resolve(mofloRoot, 'bin');
   if (!existsSync(binDir)) {

package/.claude/guidance/shipped/moflo-session-start.md

@@ -1,154 +0,0 @@
-# MoFlo Session-Start Lifecycle
-
-**Purpose:** Document everything that runs when Claude Code fires the `SessionStart` hook in a moflo-enabled project. The launcher does substantially more than "start the daemon" — it heals stale state, migrates DBs, syncs scripts, and reconciles hook wiring. Knowing what runs (and in what order) makes diagnosis fast.
-
-**Audience:** Agents and developers diagnosing slow session starts, unexpected mutations to `.claude/`, embedded migrations, daemon recycling, and post-upgrade behaviour.
-
----
-
-## Quick reference
-
-The launcher (`bin/session-start-launcher.mjs`, synced to `.claude/scripts/session-start-launcher.mjs`) is the single SessionStart hook moflo registers. Everything below runs in one process, in the listed order, before Claude Code begins the session. Total cost on a healthy install with no version change is typically < 200 ms; an upgrade or DB heal can extend it to several seconds.
-
-When anything runs, the launcher prints `moflo: <action> (<details>)` to stdout. Claude Code captures stdout as session-start `additionalContext`, so the agent sees every mutation. Failures land on stderr and similarly surface.
-
----
-
-## Stages, in execution order
-
-### 0. Headless skip
-
-If `CLAUDE_CODE_HEADLESS=true` is set in the environment, the launcher exits immediately. The moflo daemon spawns headless Claude processes (for indexing, pretraining, etc.); without this guard each spawned Claude would re-enter the launcher and fork the indexer chain on every daemon worker tick. ([#860](https://github.com/eric-cielo/moflo/issues/860).)
-
-### 0-pre. Drop stale upgrade-notice files
-
-`.moflo/upgrade-notice.json` is a transient handshake between launcher and statusline. Pre-#738 launchers wrote a 1-hour-TTL "complete" notice that could survive past the launcher run that wrote it. The launcher unconditionally removes any leftover before its own run begins.
-
-### 0c. Memory DB index repair
-
-Probes `.moflo/moflo.db` for `sqlite_autoindex_memory_entries_1` corruption and runs `REINDEX` in place if found. Must run before any sql.js consumer (embeddings migration, ephemeral-namespace purge, MCP server, daemon) — those swallow corruption errors and silently drop work otherwise. Cost on the happy path: one PRAGMA check (~10 ms). ([#743](https://github.com/eric-cielo/moflo/issues/743).)
-
-### 0d. Clear post-install restart notice
-
-If `.moflo/restart-pending.json` was written by `scripts/post-install-notice.mjs` after the last `npm install moflo` and the running version now matches the pending version, the file is removed. The user has restarted; the notice has done its job. ([#867](https://github.com/eric-cielo/moflo/issues/867).)
-
-### 2. Reset workflow state
-
-Writes a fresh `.claude/workflow-state.json` for the new session: `tasksCreated: false`, `memorySearched: false`, `sessionStart: <ISO timestamp>`. The gate scripts read this on every tool call.
-
-### 3. Auto-sync on version change (or drift)
-
-This is the biggest stage. It fires when **either** condition is true:
-
-- The installed version (`node_modules/moflo/package.json`) differs from the cached version stamp (`.moflo/moflo-version`), OR
-- Any file in `.moflo/installed-files.json` (the manifest from the previous successful sync) is missing or has drifted in size since we last wrote it.
-
-When triggered, the launcher walks the following sub-steps in order:
-
-| Sub-step | What runs | Why |
-|---------|-----------|-----|
-| Stop daemon | Kills the daemon recorded in `.moflo/daemon.lock` | The daemon was started under the previous moflo image; old module-cache + path resolution would clobber the upgrade. ([#851](https://github.com/eric-cielo/moflo/issues/851).) |
-| Cherry-pick learnings | `cherry-pick-learnings.js` reads legacy `.swarm/memory.db` and `INSERT OR IGNORE`s into `.moflo/moflo.db` | Carries user-authored knowledge forward across the v3 DB rename. Idempotent. |
-| Sync scripts | Copy `bin/*.mjs` and `bin/lib/**` and `bin/migrations/**` into `.claude/scripts/` | Hooks always run the latest version |
-| Sync helpers | Copy `bin/{gate.cjs,gate-hook.mjs,prompt-hook.mjs,hook-handler.cjs}` plus `.claude/helpers/{auto-memory-hook.mjs,statusline.cjs,...}` into `.claude/helpers/` | Same |
-| Sync shipped guidance | Copy every `node_modules/moflo/.claude/guidance/shipped/moflo-*.md` into `.claude/guidance/`, prefixing each with the auto-generated mirror header | These are the files indexed by the consumer's memory namespace |
-| Cleanup retired files | Anything in the OLD manifest but NOT in the new manifest is unlinked | Auto-removes files moflo no longer ships |
-| Per-file retry/circuit | Each copy retries `[50, 200, 800] ms` on `EBUSY`/`EPERM`/`EACCES` (Windows file lock, AV scan); after 5 distinct failures the circuit opens and the rest of the sync runs without retries | Prevents a sick host from compounding wall-clock cost; persistent failures land on stderr |
-| Manifest write | New `{path, size}` manifest committed to `.moflo/installed-files.json` | Drift detection on next launcher run |
-| Defer version stamp | Pending write of `.moflo/moflo-version` queued for stage 3g | Stamp is "launcher fully completed" — writing it mid-flight strands consumers on a half-applied upgrade ([#730](https://github.com/eric-cielo/moflo/issues/730)) |
-
-### 3a-pre. Recycle stale daemons
-
-Even when the version hasn't changed, the daemon-lock's `startedAt` is compared against `node_modules/moflo`'s install mtime. If the daemon predates the current install (with a 5 s skew margin), it's recycled. This catches the "user upgraded ages ago, ran one session that bumped the stamp + recycled the daemon, but the daemon they started long-ago is still alive holding stale module cache" failure mode.
-
-### 3a. Settings.json migration and self-heal
-
-See `moflo-settings-injection.md` for the full mechanism. The launcher applies, in order:
-
-1. **Drop stale `PATH` override** — pre-4.x settings injected `${PATH}` which Claude Code didn't expand, breaking node resolution.
-2. **Replace `npx flo` hook commands with direct `node "$CLAUDE_PROJECT_DIR/..."` invocations** — saves 2–5 s of `npx` cold-start per hook.
-3. **Ensure `statusLine` is wired** — the helper script is synced by stage 3 but the config block may be absent.
-4. **Repair + rewrite hook wirings** — `repairHookWiring()` adds missing required hooks; `rewriteIncorrectHookWiring()` rewrites known-stale hook commands (e.g. [#879](https://github.com/eric-cielo/moflo/issues/879) `gate.cjs record-memory-searched` → `gate-hook.mjs record-memory-searched`).
-
-### 3b. Restore + prune shipped guidance mirrors
-
-Even when stage 3 didn't fire (no version change, no drift), the launcher checks that every `moflo-*.md` from `node_modules/moflo/.claude/guidance/shipped/` exists at `.claude/guidance/<file>` with the auto-generated mirror header. Missing files are restored; mirror files whose source has been removed (and which still carry the `<!-- AUTO-GENERATED by moflo session-start.` marker) are pruned. ([#839](https://github.com/eric-cielo/moflo/issues/839).)
-
-### 3b-714, 3c. Legacy cleanup
-
-- `.swarm/vector-stats.json` (replaced by `.moflo/vector-stats.json` post-#699) is unlinked.
-- Pre-4.8.45 double-prefixed guidance files (`moflo-moflo-*.md`) are unlinked.
-
-### 3d-yaml. Append missing top-level sections to `moflo.yaml`
-
-`bin/lib/yaml-upgrader.mjs` walks the user's `moflo.yaml` and idempotently appends any registered top-level section that's absent (e.g., `sandbox:`, `auto_update:`, `daemon:`). Never modifies user-set values; never reorders or reformats. Surfaces appended section names so the user can find what changed. (Pattern documented in `internal/upgrade-contract.md` "Yaml upgrade pattern".)
-
-### 3d. Install global `flo` shim
-
-Best-effort install of a shim into npm's global bin so bare `flo` resolves to the local project's `node_modules/.bin/flo`. Idempotent — skips when already present. Non-fatal on failure: `flo` still works via `npx`.
-
-### 3e. Foreground embeddings migration
-
-`runEmbeddingsMigrationIfNeeded` checks `.moflo/moflo.db` for embeddings-version drift and, if needed, re-embeds rows in chunks. Runs synchronously with piped stdio so the renderer's progress bar reaches the user. Returns fast (~ms) when no migration is needed.
-
-### 3e-728, 3e-729. Hard-purge legacy memory rows
-
-- Soft-deleted tombstones (status='deleted' rows from pre-#728 builds) are hard-deleted and the DB is VACUUMed.
-- Ephemeral-namespace rows (`hive-mind`, `tasklist`, `epic-state`, `test-bridge-fix`) accumulated by pre-#729 builds are hard-deleted; going forward, writes to those namespaces skip embedding generation entirely.
-
-Both run **before** the daemon is restarted in stage 4 so a concurrent sql.js flush can't clobber the foreground purge.
-
-### 3f. Flip upgrade notice to "completed"
-
-If stage 3 wrote an "in-progress" upgrade notice for the statusline, it's flipped to "completed" with a 2-minute TTL. The next session-start's stage 0-pre wipes any leftover.
-
-### 3g. Commit deferred version stamp
-
-`.moflo/moflo-version` is finally written with the installed version. Any abort above leaves the stamp unchanged so the next launcher re-detects the upgrade and re-runs stage 3. ([#730](https://github.com/eric-cielo/moflo/issues/730).)
-
-### 4. Spawn background tasks
-
-- `node bin/hooks.mjs session-start` is spawned detached + unref'd. That script starts the daemon, the indexer, the pretrain pass, the HNSW build, and the neural-pattern training. None of it blocks the session.
-- Migrations (`run-migrations.mjs`) consult `.moflo/migrations.json` and run any unmigrated steps synchronously, then announce completed migrations via `moflo:` mutation lines.
-
-### 5. Exit
-
-`process.exit(0)`. Claude Code now begins the session with the launcher's stdout captured as additionalContext.
-
----
-
-## Diagnosing slow session starts
-
-Bottlenecks, in rough order of likelihood:
-
-| Symptom | Likely stage | Mitigation |
-|---------|-------------|------------|
-| Several-second delay on first start after `npm install` | Stage 3 (script + helper + guidance sync) | Expected — one-shot cost. Subsequent starts are ms. |
-| 30–60 s delay on first start after a major upgrade | Stage 3e (embeddings migration) | Surfaces a progress bar via stderr; cannot be skipped. |
-| Repeated multi-second delay on every start | Stage 3 firing every time = manifest drift loop | Check `moflo: repaired stale install` lines on stdout — usually means a file copy keeps failing (Windows AV, file lock). Run `flo doctor --fix`. |
-| Daemon appears to restart on every start | Stage 3a-pre — daemon predates install | Expected if you just upgraded; should stop after one session. |
-
-If a stage hangs, the launcher's per-step timeouts (5–30 s depending on the operation) protect against deadlock. A blocked stage that times out lands an error on stderr; the next launcher run retries.
-
----
-
-## Adding a new stage (developer note)
-
-Before adding work to the launcher, ask:
-
-1. Is this **per-session** work (hook reset, mirror restore) or **per-version** work (script sync, manifest)? Per-version belongs in stage 3 under the version-change gate; per-session goes in stage 2 or as its own gated stage.
-2. Does it touch `sql.js`? It must run **before** stage 4's daemon spawn — concurrent flushes from a long-lived sql.js consumer will clobber a foreground write.
-3. Does it mutate consumer state? It must `emitMutation()` so the user sees what changed via additionalContext. Silent mutations are a regression of the upgrade contract.
-4. Does it depend on a fresh-state invariant (e.g., daemon stopped, manifest written, version stamp committed)? Order matters — see the existing 3 → 3a → 3a-pre → ... → 3g → 4 sequence and slot in accordingly.
-
-Full ordering rules and historical violations live in `internal/upgrade-contract.md`.
-
----
-
-## See Also
-
-- `moflo-settings-injection.md` — the contract for what moflo writes into `.claude/settings.json` and how the surgical self-heal works.
-- `moflo-core-guidance.md` (Helper Script Auto-Sync) — the file lists for stage 3.
-- `moflo-memorydb-maintenance.md` — what runs against `.moflo/moflo.db` (embeddings, soft-delete, ephemeral purge).
-- Internal-only: `internal/upgrade-contract.md` — the "user must never re-run init" invariant the launcher enforces, with historical violations to learn from.
-- Internal-only: `internal/guidance-sync.md` — Stages 3 and 3b documented end-to-end as part of the three-layer guidance sync (filesystem → DB → HNSW).

package/.claude/guidance/shipped/moflo-spell-engine-architecture.md

@@ -1,145 +0,0 @@
-# Spell Engine & Messaging Architecture
-
-**Purpose:** Architectural decisions and analysis findings for Epic #100 (Generalized Spell Engine) and Epic #110 (Messaging Migration). Reference when working on stories #100-#117.
-
----
-
-## Epic #100: Generalized Spell Engine
-
-**Ships as part of moflo** — not a separate project. Heavy deps (Playwright, isolated-vm) are optional peer dependencies, same pattern as cli's embeddings module requiring `sql.js`.
-
-### Command Pattern for Steps
-
-Every spell step type implements a `StepCommand` interface with `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. Register step commands via a plugin-style `StepCommandRegistry` — follow the existing `PluginRegistry` pattern in `src/cli/plugins/`.
-
-### Spell Definitions
-
-Spells are YAML/JSON files in `workflows/` or `.claude/workflows/`. Each declares:
-- `name` and `abbreviation` (short name for `/flo -wf {abbrev}`)
-- Typed `arguments` with `required`, `default`, `enum`, `description`
-- Ordered `steps` with `{stepId.outputKey}` variable interpolation
-
-### MoFlo Integration Levels Per Step
-
-| Level | Capabilities | Default For |
-|-------|-------------|-------------|
-| `none` | No MoFlo access | `bash`, `condition`, `wait` |
-| `memory` | search/store/list | `agent` steps |
-| `hooks` | Above + pre/post task hooks | — |
-| `full` | Above + swarm/hive-mind spawning | — |
-| `recursive` | Above + nested `/flo -wf` invocation | — |
-
-Capabilities only narrow going deeper — a nested spell cannot escalate beyond its parent.
-
-### Sandboxing Tiers
-
-| Tier | Mechanism | Status |
-|------|-----------|--------|
-| 1 | Capability declarations + enforcement | Build first |
-| 2 | Node `--experimental-permission` for bash steps | Build second |
-| 3 | `isolated-vm` for expression evaluation | Build third |
-| 4 | Linux namespaces (optional) | Defer |
-| 5 | WASM sandbox for community commands | Defer |
-
-### Build Order (no circular dependencies)
-
-| Phase | Stories | Can Start |
-|-------|---------|-----------|
-| 1 | #101 (Interface), #103 (Schema) | Immediately |
-| 2 | #102 (Commands), #106 (Credentials) | After Phase 1 |
-| 3 | #104 (Runner) | After Phase 2 |
-| 4 | #105 (Registry), #108 (Sandboxing T1-2), #107 (Playwright) | After Phase 3 |
-| 5 | #109 (Integration Levels), #117 (Scheduling) | After Phase 4 + Epic #110 |
-
-### Critical Findings
-
-- **Existing `spell_execute` is a no-op placeholder.** The engine is greenfield.
-- **`js-yaml` already a dependency** — used in `moflo-config.ts` and `epic.ts`.
-- **Plugin registry pattern is directly reusable** for `StepCommandRegistry`.
-- **No cron support exists** — needs `node-cron` dependency for #117.
-- **Retry logic is consumer-side**, not bus-side. Steps implement their own retry.
-
----
-
-## Epic #110: Messaging Migration to Memory DB
-
-**Migrate inter-agent messaging** from in-memory EventEmitter bus to memory DB namespace. The current bus only works within a single process — spawned subagents cannot participate.
-
-### Session Isolation
-
-All messages scoped by `sessionId`. Queries implicitly filter by current session. `endSession()` expires unhandled messages. `gc()` cleans up abandoned sessions after configurable TTL.
-
-### Build Order
-
-| Phase | Stories |
-|-------|---------|
-| 1 | #111 (Schema + CRUD) |
-| 2 | #112 (Notification/Pub-Sub) |
-| 3 | #113, #114, #115 (parallel) |
-| 4 | #116 (Deprecate old bus — last) |
-
-**Minimum viable to unblock Epic #100:** #111 + #112 only.
-
-### Critical Findings
-
-- **`queen-coordinator.ts` does NOT use MessageBus.** Hive-mind operates via MCP tools. Story #114 is greenfield, not migration.
-- **`unified-coordinator.ts` is coupled to concrete `MessageBus` class**, not `IMessageBus` interface. Must refactor.
-- **Zero existing message bus tests.** Write baseline suite first, then verify both backends pass.
-- **Two competing Message types:** `SwarmMessage` (shared/types.ts) vs `Message` (swarm/types.ts). Story #111 must reconcile.
-- **Memory DB supports namespaces and TTL** but needs queue semantics and metadata indexing added.
-- **`enablePersistence` config flag exists but was never implemented** — now being properly built.
-
-### Interface Incompatibility: Not a Clean Swap
-
-The `MemoryDbMessageBus` adapter (~300 lines) must handle:
-
-| Aspect | Current `IMessageBus` | New `MessageStore` |
-|--------|----------------------|-------------------|
-| Subscribe | Push-based callback | Pull-based `receive()` |
-| Acknowledge | `acknowledge(ack)` | `markRead()` |
-| Timestamps | `Date` objects | `number` (epoch ms) |
-| Sessions | None | `sessionId` required |
-| Channels | None (per-agent queues) | Channel-based routing |
-
----
-
-## Epic #118: Consolidate Messaging Systems (Pre-req for #110)
-
-**Three messaging systems → one layered broker.** Must complete before Epic #110 migration.
-
-| Story | What | Depends On |
-|-------|------|------------|
-| #119 | Unified Message Type & Extended IMessageBus | — |
-| #120 | SwarmCommunication → MessageBus consumer | #119 |
-| #121 | Hive-Mind → MessageBus + Memory DB write-through | #119, #120 |
-
-**Key decisions:**
-- MessageBus keeps its Deque hot path for delivery (~1000+ msg/sec)
-- Memory DB write-through is fire-and-forget, initially only for hive-mind namespace
-- TTL reaper lives in the broker (60s sweep), not the daemon
-- Daemon can do deeper GC pass but system must not depend on it
-
-**Build order:** Epic #118 → remaining #110 stories (#111, #115, #116) → Epic #100 Phase 5.
-
----
-
-## Cross-Epic Dependencies
-
-**Most of Epic #100 can proceed without Epic #110.** Only two things are hard-blocked:
-
-| Blocked Story | Needs from #110 | Why |
-|--------------|-----------------|-----|
-| #109 `full` tier | #113 (Swarm Migration) | Swarm spawning needs DB-backed messaging |
-| #109 `recursive` tier | #113 + #114 | Nested spells with hive-mind need consensus messaging |
-
-Stories #101-#108, #105, #117 have no dependency on Epic #110.
-
-**Epic #118 simplifies #110:** #112 (pub/sub) largely solved, #113 (swarm) done via #120, #114 (hive-mind) done via #121.
-
----
-
-## See Also
-
-- `.claude/guidance/shipped/moflo-core-guidance.md` — CLI, hooks, swarm, memory reference
-- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — Task & swarm coordination
-- `.claude/guidance/shipped/moflo-subagents.md` — Subagents protocol