moflo 4.9.9 → 4.9.11

package/.claude/skills/simplify/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: simplify
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Sizes review effort to the diff — trivial edits get a self-review, substantial edits get parallel agents.
+---
+
+# /simplify — Adaptive Code Review
+
+Review changed code for reuse opportunities, quality issues, and efficiency improvements. **Effort scales with diff size** — a 5-line comment trim doesn't get the same treatment as a 500-line refactor.
+
+## Phase 1: Identify changes
+
+Run `git diff HEAD` (working tree) and `git diff main...HEAD` (committed) to get the full set of changes since the branch diverged. If on `main` with uncommitted changes, just `git diff HEAD`.
+
+Treat the union of staged + unstaged + committed-since-base as the diff to review.
+
+## Phase 2: Classify the diff
+
+Pick the **smallest tier** the diff genuinely fits. When in doubt, escalate.
+
+### TRIVIAL — self-review, no agent spawn
+ALL of these must hold:
+- ≤10 net LOC changed (insertions + deletions, excluding pure whitespace)
+- Single file
+- No logic changes — only comments, formatting, renames of local vars, JSDoc, or string-literal edits
+- No new imports, no new exports, no new function/class declarations
+- No removed safety checks, error handlers, or guards
+
+Examples that qualify: trimming a comment, fixing a typo in a log message, renaming a private helper, reformatting a single block.
+Examples that DON'T qualify: changing an `if` condition, reordering function args, deleting a try/catch.
+
+### SMALL — single agent, all three categories
+ALL of these must hold:
+- ≤50 net LOC changed
+- ≤2 files
+- No structural changes (no new modules, no API additions/removals, no contract changes)
+
+Examples that qualify: extracting a constant, inlining a one-liner, swapping a `for` for a `forEach`, adding one early-return.
+
+### NORMAL — three parallel agents (the original flow)
+Anything that doesn't fit TRIVIAL or SMALL. Includes any diff that:
+- Spans 3+ files
+- Adds/removes/renames a public API
+- Changes control flow in a non-trivial way
+- Introduces or removes a dependency
+- Touches `bin/`, hooks, MCP tool handlers, or anything called out in `CLAUDE.md` as critical surface
+
+When CLAUDE.md flags a file as critical surface (SessionStart, launcher, hooks, MCP coordinator wiring, swarm/hive-mind), **always escalate to NORMAL** regardless of LOC count. Risk-weighted, not size-weighted.
+
+## Phase 3: Run the appropriate review
+
+### TRIVIAL: self-review
+Run the same three category checks (reuse / quality / efficiency) yourself, in one pass, against the diff. Most TRIVIAL diffs will be clean — the goal is to confirm, not to fan out. If you find an issue, fix it; otherwise stamp clean. Total budget: ~30 seconds, no Agent calls.
+
+### SMALL: one agent
+Launch a SINGLE Agent with subagent_type `reviewer` covering all three categories in one prompt. Pass the diff inline. Budget: ~1 minute.
+
+```
+Agent — subagent_type: "reviewer", prompt: "Review this diff for reuse, quality, and efficiency. <diff inline>. Flag specific issues with file:line; skip generic advice. Under 200 words."
+```
+
+### NORMAL: three parallel agents (original flow)
+Launch three agents in a single message — Reuse, Quality, Efficiency — passing the full diff to each. Use the original flow's category checklists.
+
+**Reuse**: existing helpers/utilities that should be used instead; duplicated patterns; new functions that re-implement something already in the codebase.
+
+**Quality**: redundant state, parameter sprawl, copy-paste with variation, leaky abstractions, stringly-typed code, nested conditionals 3+ levels, unnecessary comments (WHAT-explanations, task references).
+
+**Efficiency**: unnecessary work, missed concurrency, hot-path bloat, recurring no-op updates, TOCTOU existence checks, unbounded structures, over-broad reads.
+
+## Phase 4: Fix or skip
+
+Aggregate findings. Fix each one directly. False positives or not-worth-fixing — note and skip without arguing. If TRIVIAL self-review found nothing, just confirm clean and exit.
+
+If fixes were made, re-run tests to confirm nothing broke. If tests fail after a fix, revert it.
+
+## Phase 5: Stamp the gate
+
+Whatever tier ran, the gate (`check-before-pr`) registers /simplify as having executed. The skill is satisfied.
+
+## Briefly summarize
+
+End with one or two sentences: which tier, what was fixed (or "clean — no changes"). No headers, no bullets unless needed.

package/.claude/skills/spell-builder/SKILL.md

@@ -356,7 +356,7 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 **Runtime source:** `src/cli/spells/commands/` — each step is a TypeScript file registered in `index.ts`.
 
-**Adding a new step:** Create a directory under `steps/<name>/` with a `README.md`. Follow `.claude/guidance/internal/guidance-rules.md` and use existing step READMEs as templates. The step command source goes in `src/cli/spells/commands/` and is registered in `index.ts`. No changes to this SKILL.md needed.
+**Adding a new step:** Create a directory under `steps/<name>/` with a `README.md`. Follow `.claude/guidance/shipped/moflo-guidance-rules.md` and use existing step READMEs as templates. The step command source goes in `src/cli/spells/commands/` and is registered in `index.ts`. No changes to this SKILL.md needed.
 
 ### Connectors
 
@@ -371,7 +371,7 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 **Runtime source:** `src/cli/spells/connectors/` — each connector is a TypeScript file registered in `index.ts`.
 
-**Adding a new connector:** Create a directory under `connectors/<name>/` with a `README.md`. Follow `.claude/guidance/internal/guidance-rules.md` and use existing connector READMEs as templates. The connector source goes in `src/cli/spells/connectors/` and is registered in `index.ts`. No changes to this SKILL.md needed.
+**Adding a new connector:** Create a directory under `connectors/<name>/` with a `README.md`. Follow `.claude/guidance/shipped/moflo-guidance-rules.md` and use existing connector READMEs as templates. The connector source goes in `src/cli/spells/connectors/` and is registered in `index.ts`. No changes to this SKILL.md needed.
 
 **When to create a new connector vs composing existing ones:** See [architecture.md](architecture.md) for the decision tree.
 

package/.claude/skills/spell-builder/architecture.md

@@ -153,7 +153,7 @@ steps:
 
 ## Documentation Rules for New Components
 
-**Every new step, connector, or spell MUST include a README.md.** Apply the rules in `.claude/guidance/internal/guidance-rules.md` automatically — do not wait for the user to ask. Use existing READMEs in `steps/` and `connectors/` as templates.
+**Every new step, connector, or spell MUST include a README.md.** Apply the rules in `.claude/guidance/shipped/moflo-guidance-rules.md` automatically — do not wait for the user to ask. Use existing READMEs in `steps/` and `connectors/` as templates.
 
 **Where to put the README:**
 - Steps: `.claude/skills/spell-builder/steps/<name>/README.md`

package/.claude/skills/spell-schedule/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: spell-schedule
+description: |
+  Schedule a moflo spell to run on the local machine via the moflo daemon (cron, interval, or one-time).
+  Use when the user wants to schedule, automate, or recurringly run one of THEIR spells locally —
+  e.g. "schedule the oap spell every hour", "run my audit spell every weekday at 9am", "fire X once tomorrow morning".
+  This is the LOCAL daemon path. For remote Anthropic-cloud agents, use /schedule instead.
+arguments: "[spell-name-or-alias]"
+---
+
+# /spell-schedule — Schedule a Local Spell
+
+This skill walks the user through scheduling a moflo spell on the **local** moflo daemon.
+Schedules live in moflo's memory store and are evaluated once per minute by the daemon's poll loop.
+Execution goes through the same engine path as `flo spell cast`.
+
+> Not the same as `/schedule`. `/schedule` creates **remote** Anthropic-cloud routines; this skill drives the **local** daemon scheduler.
+
+**Arguments:** `$ARGUMENTS` (optional spell name/alias to pre-select)
+
+## When to use
+
+The user says any of:
+- "schedule the X spell"
+- "run X every <interval>"
+- "fire X once at <time>"
+- "set up a recurring run for X"
+- "I want X to run every morning"
+
+If the user wants a **cloud** agent (mentions "remote", "GitHub Actions", "Anthropic cloud", or specifies a repo to clone), redirect them to `/schedule`.
+
+## Workflow
+
+### Step 1 — Verify the daemon is running
+
+```bash
+npx flo doctor 2>&1 | grep -i daemon
+```
+
+If the daemon is not running, prompt the user:
+- "The moflo daemon isn't running. Schedules only fire while the daemon is up. Start it now?"
+- If yes: `npx flo daemon start` (or instruct them to enable OS autostart for survival across reboots).
+- If they decline, warn the user that the schedule will be created but won't fire until the daemon is started.
+
+### Step 2 — Identify the target spell
+
+If `$ARGUMENTS` was provided, use it as the spell name/alias. Otherwise, list spells and let the user pick:
+
+```bash
+npx flo spell list 2>&1
+```
+
+The output is a markdown table with columns: name, alias, description, source. Both `name` and `alias` are valid for `flo spell schedule create -n <value>` — prefer the full name to avoid alias conflicts.
+
+If the user-named spell is not in the list, stop and ask. Do NOT silently create a schedule for a missing spell — it will be auto-disabled on first fire.
+
+### Step 3 — Pick the cadence
+
+Use AskUserQuestion to offer four options:
+
+| Option | When to suggest | CLI form |
+|--------|-----------------|----------|
+| **Cron** | Specific time of day, day of week, or month boundary | `--cron "<5-field cron>"` (UTC, 5 fields: minute hour day-of-month month day-of-week) |
+| **Interval** | "Every N seconds/minutes/hours/days" with no specific clock anchor | `--interval <N><s\|m\|h\|d>` (e.g., `30m`, `6h`, `1d`) |
+| **One-time** | "Run once at..." or "remind me to..." | `--at <ISO 8601 datetime>` |
+| **Embedded in spell** | The schedule should travel with the spell definition (registered every daemon start) | Edit the spell YAML to add a `schedule:` block; no CLI |
+
+#### Timezone conversion (CRITICAL)
+
+Cron expressions and `--at` timestamps are **always UTC**. The user almost always means their local time.
+
+1. **Look up the user's timezone** — derive from system. On Windows, `[System.TimeZoneInfo]::Local.Id` or read the auto-memory `currentDate` block. **Never** guess.
+2. **Convert to UTC** explicitly using PowerShell (cross-platform-safe):
+   ```powershell
+   [System.TimeZoneInfo]::ConvertTimeToUtc((Get-Date "9:00am"), [System.TimeZoneInfo]::Local)
+   ```
+3. **Echo back the conversion**: "9am America/Guatemala = 15:00 UTC, so the cron would be `0 15 * * 1-5`. Confirm?"
+4. **Re-check current time before any `--at`** — long conversations drift. Run `date -u +%Y-%m-%dT%H:%M:%SZ` (or PowerShell equivalent) before computing the absolute timestamp. If the resolved time is in the past, ask for clarification — do not silently roll forward.
+
+#### Constraints
+
+- Minimum poll interval is 1 minute (the daemon polls once per `pollIntervalMs`, default 60000). Sub-minute schedules are rejected.
+- Interval units: `s`, `m`, `h`, `d` ONLY. `--interval 1w` is rejected at load time.
+- `--at` must be a valid ISO 8601 datetime in the future.
+- Exactly one of `--cron`, `--interval`, `--at` per schedule.
+
+### Step 4 — Confirm and create
+
+Show the full plan to the user before creating:
+
+```
+Spell:    outlook-attachment-processor (alias: oap)
+Cadence:  every weekday at 9am America/Guatemala (15:00 UTC)
+Cron:     0 15 * * 1-5
+Daemon:   running ✓
+```
+
+After user confirms, run:
+
+```bash
+npx flo spell schedule create -n <spell-name> --cron "<cron>" 2>&1
+# or --interval <value>
+# or --at <iso-datetime>
+```
+
+Capture the schedule ID from output and surface it to the user along with the next computed run time.
+
+### Step 5 — Verify the wiring
+
+Tail the schedule executions for the first fire so the user can confirm the daemon actually picks it up:
+
+```bash
+npx flo spell schedule list 2>&1
+```
+
+If the user wants to wait for the first fire (interval ≤ 5m), poll `flo spell schedule list` or the daemon dashboard. Otherwise, summarize and exit:
+
+```
+Scheduled: <schedule-id>
+Next run:  <ISO datetime UTC> (<local-equivalent>)
+Cancel:    npx flo spell schedule cancel <schedule-id>
+```
+
+## Sub-actions (when not creating)
+
+If the user asks to **list** schedules:
+```bash
+npx flo spell schedule list 2>&1
+```
+
+If the user asks to **cancel** a schedule:
+1. Run `flo spell schedule list` and let them pick.
+2. `npx flo spell schedule cancel <schedule-id>`.
+3. Confirm the entry is gone from the list.
+
+If the user asks to **run now** without altering the cadence:
+- Use the dashboard's "Run now" button if available, or the daemon's `runScheduleNow` API.
+- The CLI does not currently expose this — surface that limitation if asked, and offer `flo spell cast -n <name>` as a manual alternative.
+
+## Important — gotchas
+
+- **Daemon prerequisite**: schedules only fire while the daemon is running. Tell the user this explicitly. For survival across reboots, `flo daemon install` registers the OS-level autostart service.
+- **Catch-up window** (default 1h, `scheduler.catchUpWindowMs` in `moflo.yaml`): if the daemon was offline when a run was due, runs within the window still fire on the next poll. Older missed runs are skipped with a `schedule:skipped` event.
+- **maxConcurrent** (default 2): caps the number of scheduled spells running concurrently. Same-schedule overlap is never allowed.
+- **No update CLI yet**: `flo spell schedule` exposes create/list/cancel only. To change a cadence, cancel + recreate.
+- **Spell-required sandboxing** (#878): when that ships, scheduled runs honor it just like manual casts — a missing sandbox skips the run with a `schedule:skipped` event.
+
+## Output
+
+End the session with a single-block summary:
+
+```
+Schedule Created
+────────────────
+Spell:       <name>
+Cadence:     <human-readable>
+Cron/At:     <UTC expression>
+ID:          <schedule-id>
+Next run:    <UTC + local>
+Cancel:      npx flo spell schedule cancel <id>
+Daemon:      running | needs-start
+```
+
+## Reference
+
+- Full daemon scheduler docs: https://github.com/eric-cielo/moflo/blob/main/docs/SPELLS.md#scheduling
+- Tracking issue: https://github.com/eric-cielo/moflo/issues/877

package/bin/generate-code-map.mjs

@@ -32,6 +32,7 @@ import { execSync, execFileSync, spawn } from 'child_process';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
@@ -914,11 +915,9 @@ async function main() {
 }
 
 async function runEmbeddings() {
-  const embedCandidates = [
-    resolve(dirname(fileURLToPath(import.meta.url)), 'build-embeddings.mjs'),
-    resolve(projectRoot, '.claude/scripts/build-embeddings.mjs'),
-  ];
-  const embedScript = embedCandidates.find(p => existsSync(p));
+  const embedScript = resolveMofloBin(
+    projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+  );
   if (!embedScript) return;
 
   log('Generating embeddings for code-map...');

package/bin/hooks.mjs

@@ -25,6 +25,7 @@ import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -449,21 +450,10 @@ function spawnWindowless(cmd, args, description) {
   return result;
 }
 
-// Resolve a moflo npm bin script, falling back to local .claude/scripts/ copy
+// Resolve a moflo bin script via the shared helper (bin/lib/resolve-bin.mjs).
+// Bin-first ordering — see #866 / #869.
 function resolveBinOrLocal(binName, localScript) {
-  // 1. npm bin from moflo package (always up to date with published version)
-  const mofloScript = resolve(projectRoot, 'node_modules/moflo/bin', localScript);
-  if (existsSync(mofloScript)) return mofloScript;
-
-  // 2. npm bin from .bin (symlinked by npm install)
-  const npmBin = resolve(projectRoot, 'node_modules/.bin', binName);
-  if (existsSync(npmBin)) return npmBin;
-
-  // 3. Local .claude/scripts/ copy (may be stale but better than nothing)
-  const localPath = resolve(projectRoot, '.claude/scripts', localScript);
-  if (existsSync(localPath)) return localPath;
-
-  return null;
+  return resolveMofloBin(projectRoot, binName, localScript);
 }
 
 // Run the guidance indexer in background (non-blocking - used for session start and file changes)

package/bin/index-all.mjs

@@ -25,6 +25,7 @@ import {
   saveStepFingerprint,
   cleanupLegacyFingerprint,
 } from './lib/index-fingerprint.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 // Cap fastembed/ONNX thread count when spawning the heavy steps. Without
 // this, ONNX defaults to one thread per CPU core (22+ on a modern dev box),
@@ -61,16 +62,7 @@ function log(msg) {
 }
 
 function resolveBin(binName, localScript) {
-  const mofloScript = resolve(projectRoot, 'node_modules/moflo/bin', localScript);
-  if (existsSync(mofloScript)) return mofloScript;
-  const npmBin = resolve(projectRoot, 'node_modules/.bin', binName);
-  if (existsSync(npmBin)) return npmBin;
-  const localPath = resolve(projectRoot, '.claude/scripts', localScript);
-  if (existsSync(localPath)) return localPath;
-  // Also check bin/ directory (for development use)
-  const binPath = resolve(projectRoot, 'bin', localScript);
-  if (existsSync(binPath)) return binPath;
-  return null;
+  return resolveMofloBin(projectRoot, binName, localScript, { includeDevFallback: true });
 }
 
 function getLocalCliPath() {

package/bin/index-guidance.mjs

@@ -27,6 +27,7 @@ import { resolve, relative, dirname, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath } from './lib/moflo-paths.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
@@ -873,14 +874,11 @@ if (!skipEmbeddings && needsEmbeddings) {
 
   const { spawn } = await import('child_process');
 
-  // Look for build-embeddings script in multiple locations:
-  // 1. Shipped with moflo (node_modules/moflo/bin/)
-  // 2. Project-local (.claude/scripts/)
-  const mofloScript = resolve(__dirname, 'build-embeddings.mjs');
-  const projectLocalScript = resolve(projectRoot, '.claude/scripts/build-embeddings.mjs');
-  const embeddingScript = existsSync(mofloScript) ? mofloScript : projectLocalScript;
+  const embeddingScript = resolveMofloBin(
+    projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+  );
 
-  if (existsSync(embeddingScript)) {
+  if (embeddingScript) {
     const embeddingArgs = ['--namespace', NAMESPACE];
 
     // Create log file for background process output

package/bin/index-patterns.mjs

@@ -28,10 +28,10 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 import { resolve, dirname, relative, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -75,6 +75,9 @@ function ensureDbDir() {
 
 async function getDb() {
   ensureDbDir();
+  // Lazy: hash-cache-match and no-source-files early-exits in main() never
+  // reach this, and the sql.js wasm cold-load is ~400ms otherwise wasted.
+  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
   const SQL = await initSqlJs();
   let db;
   if (existsSync(DB_PATH)) {
@@ -341,14 +344,9 @@ async function main() {
 
   // Trigger embedding generation in background
   try {
-    // Check __dirname first (works in both dev bin/ and consumer .claude/scripts/),
-    // then fall back to node_modules/moflo/bin/ for consumer projects
-    const candidates = [
-      resolve(__dirname, 'build-embeddings.mjs'),
-      resolve(projectRoot, 'node_modules/moflo/bin/build-embeddings.mjs'),
-      resolve(projectRoot, '.claude/scripts/build-embeddings.mjs'),
-    ];
-    const embeddingScript = candidates.find(p => existsSync(p));
+    const embeddingScript = resolveMofloBin(
+      projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+    );
     if (embeddingScript) {
       const child = spawn('node', [embeddingScript, '--namespace', NAMESPACE], {
         cwd: projectRoot,

package/bin/index-tests.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from 'url';
 import { execSync, execFileSync, spawn } from 'child_process';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
@@ -687,11 +688,9 @@ async function main() {
 }
 
 async function runEmbeddings() {
-  const embedCandidates = [
-    resolve(dirname(fileURLToPath(import.meta.url)), 'build-embeddings.mjs'),
-    resolve(projectRoot, '.claude/scripts/build-embeddings.mjs'),
-  ];
-  const embedScript = embedCandidates.find(p => existsSync(p));
+  const embedScript = resolveMofloBin(
+    projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+  );
   if (!embedScript) return;
 
   log('Generating embeddings for tests...');

package/bin/lib/resolve-bin.mjs

@@ -0,0 +1,62 @@
+/**
+ * Shared moflo bin-script path resolver.
+ *
+ * Resolves a moflo bin script in a consumer project, preferring the
+ * npm-installed copy over the .claude/scripts/ mirror so the spawned process
+ * matches the installed package version.
+ *
+ * Resolution order (intentional — see #866):
+ *   1. <projectRoot>/node_modules/moflo/bin/<localScript>  — published, atomic
+ *   2. <projectRoot>/node_modules/.bin/<binName>           — npm-managed alias (only if binName given)
+ *   3. <projectRoot>/.claude/scripts/<localScript>         — derived sync, can lag a session
+ *   4. <projectRoot>/bin/<localScript>                     — DEV ONLY, opt-in via includeDevFallback
+ *
+ * Why bin-first matters: the .claude/scripts/ mirror is updated by a sync
+ * step that races the launcher's section-3 file copies during the very
+ * upgrade session, so a still-stale mirror can spawn pre-upgrade argv into
+ * a post-upgrade chain (#866). The npm package copy is updated atomically
+ * by `npm install moflo`, so spawning from there guarantees the running
+ * script matches the installed package.
+ *
+ * Cross-platform: paths are joined via `node:path.resolve`, which normalises
+ * separators on Windows + POSIX. Callers compute `projectRoot` themselves
+ * (typically via findProjectRoot()) so this helper has no implicit cwd.
+ */
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * @param {string} projectRoot     Consumer's project root (caller-computed).
+ * @param {string|null} binName    npm bin alias (e.g. 'flo-index'), or null/undefined when no alias exists.
+ * @param {string} localScript     Script filename (e.g. 'index-guidance.mjs').
+ * @param {{ includeDevFallback?: boolean }} [opts]
+ *   includeDevFallback: also probe `<projectRoot>/bin/<localScript>` for source-tree dev.
+ * @returns {string|null}          Resolved absolute path, or null when no candidate exists.
+ */
+export function resolveMofloBin(projectRoot, binName, localScript, opts = {}) {
+  for (const candidate of mofloBinCandidates(projectRoot, binName, localScript, opts)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Pure-function variant — returns the candidate list in resolution order
+ * without touching the filesystem. Used by the source-invariant test that
+ * pins the bin-first ordering, and by callers that want to log what was
+ * probed when nothing resolved.
+ */
+export function mofloBinCandidates(projectRoot, binName, localScript, opts = {}) {
+  const candidates = [
+    resolve(projectRoot, 'node_modules', 'moflo', 'bin', localScript),
+  ];
+  if (binName) {
+    candidates.push(resolve(projectRoot, 'node_modules', '.bin', binName));
+  }
+  candidates.push(resolve(projectRoot, '.claude', 'scripts', localScript));
+  if (opts.includeDevFallback) {
+    candidates.push(resolve(projectRoot, 'bin', localScript));
+  }
+  return candidates;
+}

package/bin/session-start-launcher.mjs

@@ -13,6 +13,7 @@ import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { mofloDir } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 // Headless skip (#860). The daemon's headless workers spawn `claude --print`
 // with CLAUDE_CODE_HEADLESS=true (see src/cli/services/headless-worker-
@@ -837,8 +838,11 @@ try {
       settingsChanges.push('added statusLine');
     }
 
-    // 3a-iv. Repair missing required hook wirings (same logic as doctor --fix
-    // and moflo upgrade — shared via hook-wiring.js to stay DRY)
+    // 3a-iv. Repair missing required hook wirings AND rewrite known-bad
+    // wirings from older moflo versions (#879 — record-memory-searched
+    // wired to gate.cjs directly skips session_id forwarding and deadlocks
+    // the per-actor gate). Both passes share hook-wiring.js so doctor --fix,
+    // upgrade-merge, and the launcher stay DRY.
     try {
       const hwPaths = [
         resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/hook-wiring.js'),
@@ -846,11 +850,21 @@ try {
       ];
       const hwPath = hwPaths.find(p => existsSync(p));
       if (hwPath) {
-        const { repairHookWiring } = await import(`file://${hwPath.replace(/\\/g, '/')}`);
-        const { repaired } = repairHookWiring(settings);
-        if (repaired.length > 0) {
-          dirty = true;
-          settingsChanges.push(`repaired ${plural(repaired.length, 'hook wiring')}`);
+        const mod = await import(`file://${hwPath.replace(/\\/g, '/')}`);
+        if (typeof mod.rewriteIncorrectHookWiring === 'function') {
+          const { rewrites } = mod.rewriteIncorrectHookWiring(settings);
+          if (rewrites.length > 0) {
+            dirty = true;
+            const total = rewrites.reduce((n, r) => n + r.count, 0);
+            settingsChanges.push(`rewrote ${plural(total, 'stale hook wiring')}`);
+          }
+        }
+        if (typeof mod.repairHookWiring === 'function') {
+          const { repaired } = mod.repairHookWiring(settings);
+          if (repaired.length > 0) {
+            dirty = true;
+            settingsChanges.push(`repaired ${plural(repaired.length, 'hook wiring')}`);
+          }
         }
       }
     } catch (err) {
@@ -1125,19 +1139,15 @@ if (mutationCount > 0) {
 // ── 4. Spawn background tasks ───────────────────────────────────────────────
 
 // hooks.mjs session-start (daemon, indexer, pretrain, HNSW, neural patterns).
-// Prefer the npm-bin copy over the `.claude/scripts/` mirror (#866). The mirror
-// is a derived sync that races the launcher's section-3 file copies during the
-// very upgrade session — spawning the still-stale `.claude/scripts/hooks.mjs`
-// then chaining `__dirname/index-all.mjs` produces an orphan running pre-
-// upgrade argv (e.g. `rebuild-index --force` after #859 had already dropped
-// it). The bin/ copy is updated atomically by `npm install moflo` (single-
-// step), so spawning from there guarantees the running hook code matches the
-// installed package. Falls back to the mirror only when the package copy is
-// unresolvable (development / symlinked installs).
-const hooksPkg = resolve(projectRoot, 'node_modules/moflo/bin/hooks.mjs');
-const hooksMirror = resolve(projectRoot, '.claude/scripts/hooks.mjs');
-const hooksScript = existsSync(hooksPkg) ? hooksPkg : hooksMirror;
-if (existsSync(hooksScript)) {
+// Bin-first ordering via resolveMofloBin — prefers the npm-package copy over
+// the `.claude/scripts/` mirror (#866). The mirror is a derived sync that
+// races the launcher's section-3 file copies during the very upgrade session;
+// spawning the still-stale mirror produces an orphan running pre-upgrade argv
+// (e.g. `rebuild-index --force` after #859 had already dropped it). The pkg
+// copy is updated atomically by `npm install moflo`, so spawning from there
+// guarantees the running hook code matches the installed package.
+const hooksScript = resolveMofloBin(projectRoot, null, 'hooks.mjs');
+if (hooksScript) {
   fireAndForget('node', [hooksScript, 'session-start'], 'hooks session-start');
 }
 
@@ -1152,10 +1162,8 @@ if (existsSync(hooksScript)) {
 // Run synchronously (capture stdout) so each completed migration surfaces
 // through emitMutation — Claude's session-start hook captures launcher
 // stdout and that's the only channel that reaches the user.
-const runMigrationsPkg = resolve(projectRoot, 'node_modules/moflo/bin/run-migrations.mjs');
-const runMigrationsMirror = resolve(projectRoot, '.claude/scripts/run-migrations.mjs');
-const runMigrations = existsSync(runMigrationsPkg) ? runMigrationsPkg : runMigrationsMirror;
-if (existsSync(runMigrations)) {
+const runMigrations = resolveMofloBin(projectRoot, null, 'run-migrations.mjs');
+if (runMigrations) {
   runMigrationsAndAnnounce(runMigrations);
 }