moflo 4.10.4 → 4.10.6

package/bin/gate.cjs

@@ -82,6 +82,53 @@ var command = process.argv[2];
 
 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'];
+
+// #1132 — Bash memory-first gate.
+//
+// CREDIT: the legacy detector that marks the gate satisfied when Claude
+// manually invokes a memory-search CLI (flo-search, the moflo MCP search via
+// shell, etc.). Preserved verbatim from the pre-#1132 behaviour so existing
+// recipes keep crediting the gate.
+var CREDIT_MEMORY_SEARCH_RE = /semantic-search|memory search|memory retrieve|memory-search/;
+// BLOCK: read-like Bash commands that bypass the existing check-before-read /
+// check-before-scan gates by going through the shell. Anchored to the start of
+// the line so subcommands inside pipelines or `npm install grep` don't trip.
+// Covers POSIX read/search tools, Windows cmd `type`, and PowerShell readers.
+var READ_LIKE_BASH_RE = new RegExp([
+  '^\\s*(?:cat|head|tail|less|more|bat|xxd|od|hexdump)\\b',
+  '^\\s*(?:grep|rg|ag|fgrep|egrep|find|fd)\\b',
+  '^\\s*sed\\s+-n\\b',
+  '^\\s*awk\\s+(?!.*<<)',
+  // `type <path>` on Windows. No `$` anchor so a piped form
+  // (`type src\foo.ts | grep x`) still matches and gets blocked. The argument
+  // must contain a slash, backslash, or dot — otherwise it's the shell-builtin
+  // command-lookup form (`type ls`, `type cd`) which the gate has no business
+  // blocking. False-negative trade: extension-less filenames like `type Makefile`
+  // pass through. Acceptable — source files all have extensions, and the
+  // primary risk pattern is leaking past the gate via `type src\foo.ts`.
+  '^\\s*type\\s+\\S*[\\\\/.]',
+  '^\\s*(?:Get-Content|gc|Select-String|sls)\\b',
+].join('|'), 'i');
+// CARVE-OUT: commands that LOOK read-like but are operational. Anchored to the
+// LEADING command — the pipe-filter case (`npm test | grep FAIL`) is already
+// handled by READ_LIKE's `^\s*` anchor never matching the leading `npm`, so
+// there is intentionally no pipe arm here: catching the leading command lets
+// `grep -r TODO src/ | head -5` reach the BLOCK exit (which it must, that's
+// the gap the ticket exists to close). #1132.
+var BASH_CARVE_OUT_RE = new RegExp([
+  '^\\s*(npm|npx|pnpm|yarn|bun|node|deno|tsx|ts-node)\\s',
+  '^\\s*(git|gh|hub)\\s',
+  '^\\s*(docker|kubectl|helm|terraform)\\s',
+  '^\\s*(curl|wget|http|fetch)\\s',
+  '^\\s*(jq|yq|xq)\\s',
+  '^\\s*(echo|printf|true|false|sleep|test|\\[)\\s',
+  '^\\s*cat\\s+(<<|<<<)',
+  '^\\s*cat\\s+[^|]*\\s*>',
+  '^\\s*tee\\b',
+  // Lazy `.+?` instead of `.+\s` to avoid catastrophic backtracking on long
+  // `find` commands that lack a `-delete` / `-exec rm` suffix.
+  '^\\s*find\\s+.+?-(delete|exec\\s+rm)\\b',
+].join('|'));
 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;
 
@@ -146,6 +193,29 @@ function classifyNamespaceHint(promptText) {
   return '';
 }
 
+// #1132 — command-shape namespace classifier for the bash-BLOCK message.
+// Used when the prompt-derived `lastNamespaceHint` is empty (e.g. subagents,
+// which never see the user prompt) so the block message still routes to a
+// useful namespace rather than the generic "pick one of five" list. Returns a
+// full sentence in the same shape as classifyNamespaceHint so the BLOCK arm
+// can write either source's hint without branching on format.
+//
+// SYNC: duplicated verbatim in src/cli/init/helpers-generator.ts.
+function classifyBashNamespaceHint(cmd) {
+  // Search-like tools — the user is hunting for a symbol/file, code-map wins.
+  if (/^\s*(?:grep|rg|ag|fgrep|egrep|find|fd|Select-String|sls)\b/i.test(cmd)) {
+    return 'Memory namespace hint: use "code-map" for codebase navigation.';
+  }
+  // Reading a .md / RST / TXT, or a well-known doc file — guidance/learnings win.
+  // `.*` (not `\S*`) so flag-prefixed forms like `head -50 README.md` match.
+  // Anchored on the leading reader so a piped `cmd | grep foo.md` doesn't trip.
+  if (/^\s*(?:cat|head|tail|less|more|bat|type|Get-Content|gc)\b.*\.(?:md|mdx|rst|txt)\b/i.test(cmd)
+   || /^\s*(?:cat|head|tail|less|more|bat|type|Get-Content|gc)\b.*\b(?:README|CLAUDE|CHANGELOG|CONTRIBUTING|LICENSE)\b/i.test(cmd)) {
+    return 'Memory namespace hint: search "guidance" and "learnings" for project rules and decisions.';
+  }
+  return '';
+}
+
 // Apply per-prompt state reset shared by `prompt-reminder` (full) and
 // `prompt-state-reset` (defensive safety-net, no emission). Idempotent — both
 // UserPromptSubmit hooks can run it without compounding any field. Caller
@@ -402,11 +472,41 @@ switch (command) {
     break;
   }
   case 'check-bash-memory': {
+    // #1132 — preserve CREDIT side-effect AND add a BLOCK arm for read-like
+    // Bash commands. Wired as PreToolUse[Bash] (was PostToolUse before #1132)
+    // so process.exit(2) actually prevents the read from reaching the shell.
     var cmd = process.env.TOOL_INPUT_command || '';
-    if (/semantic-search|memory search|memory retrieve|memory-search/.test(cmd)) {
+
+    // 1) CREDIT — preserved behavior. A real memory-search invocation flips
+    // the gate flag so subsequent Read/Grep/Glob within this prompt pass.
+    if (CREDIT_MEMORY_SEARCH_RE.test(cmd)) {
       var s = readState();
       if (markMemorySearched(s)) writeState(s);
+      break;
     }
+
+    // 2) BLOCK — new behavior. Cheap regex checks come BEFORE readState() so
+    // the overwhelming majority of Bash invocations (git/npm/curl/echo/etc.)
+    // never touch the filesystem. Order: config flag → command-shape regexes
+    // → state read → memory gate.
+    if (!config.memory_first) break;
+    if (!READ_LIKE_BASH_RE.test(cmd)) break;
+    if (BASH_CARVE_OUT_RE.test(cmd)) break;
+    var s2 = readState();
+    if (!s2.memoryRequired || isMemorySearchedFor(s2)) break;
+    // Hint precedence: prompt-derived classification (set by applyPromptStateReset
+    // from the user prompt text) → command-shape classification (works for
+    // subagents that never saw the user prompt). Either source returns a full
+    // "Memory namespace hint: ..." sentence so the BLOCK message stays uniform.
+    var hint = s2.lastNamespaceHint || classifyBashNamespaceHint(cmd) || '';
+    process.stderr.write(
+      'BLOCKED: Search memory before reading files via Bash.\n' +
+      'Example: mcp__moflo__memory_search { query: "<topic>", namespace: "<one of: guidance | code-map | patterns | learnings | tests>" }\n' +
+      (hint ? hint + '\n' : '') +
+      'On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' +
+      'Disable per-gate via moflo.yaml: gates: memory_first: false\n'
+    );
+    process.exit(2);
     break;
   }
   case 'check-task-transition': {

package/bin/lib/daemon-recycler.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Detached recycler for §2a of session-start-launcher.mjs.
+ *
+ * The launcher used to inline the kill-and-restart synchronously, which kept
+ * up to 500ms of liveness-polling in the foreground — fine on Linux, but on
+ * Windows under the SessionStart hook's 3000ms timeout it eroded the budget
+ * that's supposed to be spent on real work. Per the launcher's contract
+ * ("spawns background tasks via spawn(detached + unref) and exits
+ * immediately"), the daemon recycle belongs in a detached worker.
+ *
+ * Invocation (from §2a, via fireAndForget):
+ *   node bin/lib/daemon-recycler.mjs <projectRoot> <pid> <installedVersion>
+ *
+ * Steps:
+ *   1. Force-kill <pid> (Windows: taskkill /F /T, Unix: SIGKILL). Skip
+ *      graceful — by this point the launcher has already decided the daemon
+ *      is running stale code and its shutdown handlers are stale too.
+ *   2. Poll liveness up to 5s. Unlink the lockfile only once the PID is gone,
+ *      so a surviving daemon can't re-attach to the unlinked path.
+ *   3. Spawn `node node_modules/moflo/bin/cli.js daemon start --quiet`
+ *      detached + unref so this recycler can exit immediately.
+ *
+ * Output is intentionally silent — there's no parent to read it. Failures are
+ * surfaced via `.moflo/daemon-recycle.last.json` for `flo doctor` to read.
+ */
+
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, openSync, closeSync, unlinkSync, writeFileSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const [, , projectRootArg, pidArg, installedVersion] = process.argv;
+
+if (!projectRootArg || !pidArg) {
+  // No way to surface this — the launcher fire-and-forgets us, no parent
+  // captures stderr. Bail silently.
+  process.exit(2);
+}
+
+const projectRoot = resolve(projectRootArg);
+const pid = Number.parseInt(pidArg, 10);
+const lockFile = join(projectRoot, '.moflo', 'daemon.lock');
+
+// EPERM means "exists but owned by another user" — treat as alive (matches
+// launcher's isDaemonPidAlive contract). ESRCH means "no such process" — dead.
+//
+// Linux zombie handling: on Linux, `kill(pid, 0)` succeeds for zombie processes
+// (exited but not yet reaped). A zombie can't write to the DB or hold locks, so
+// treating it as alive exhausts the 5s kill budget polling a corpse. Read
+// /proc/<pid>/stat and treat 'Z' as dead — same logic the launcher uses (#1083).
+function isAlive(p) {
+  if (!p || p <= 0) return false;
+  try {
+    process.kill(p, 0);
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+  if (process.platform === 'linux') {
+    try {
+      const stat = readFileSync(`/proc/${p}/stat`, 'utf-8');
+      const lastParen = stat.lastIndexOf(')');
+      if (lastParen !== -1 && stat.charAt(lastParen + 2) === 'Z') return false;
+    } catch (err) {
+      if (err && err.code === 'ENOENT') return false;
+      // /proc unavailable — fall through with the kill(0) verdict.
+    }
+  }
+  return true;
+}
+
+function sleepSyncMs(ms) {
+  const buf = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(buf, 0, 0, ms);
+}
+
+function writeOutcome(status, detail) {
+  try {
+    writeFileSync(
+      join(projectRoot, '.moflo', 'daemon-recycle.last.json'),
+      JSON.stringify(
+        {
+          status,
+          detail,
+          pid,
+          installedVersion: installedVersion ?? null,
+          completedAt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ),
+    );
+  } catch { /* best-effort — doctor reads this file optionally */ }
+}
+
+// ── 0. Single-recycler advisory lock ────────────────────────────────────────
+// Two session starts within the same second can both fire §2a, both detect
+// behind, both spawn this recycler against the same PID. Without the lock,
+// both call `daemon start` and race for daemon-lock acquisition — only one
+// daemon wins but the other wastes a spawn cycle. Use O_EXCL on a sentinel
+// file so the second invocation exits early.
+const recycleLock = join(projectRoot, '.moflo', 'recycle.lock');
+let lockFd;
+let lockAcquired = false;
+try {
+  lockFd = openSync(recycleLock, 'wx'); // O_CREAT | O_EXCL
+  lockAcquired = true;
+} catch (err) {
+  if (err && err.code === 'EEXIST') {
+    // Another recycler is mid-flight. Bail silently — it will handle the kill.
+    writeOutcome('already-running', `another recycler holds ${recycleLock}`);
+    process.exit(0);
+  }
+  // Unexpected — proceed without the lock rather than blocking the recycle.
+}
+
+// Release the advisory lock on every exit path, including process.exit() and
+// crashes. Idempotent: if the lock wasn't acquired this becomes a no-op.
+process.on('exit', () => {
+  if (!lockAcquired) return;
+  try { closeSync(lockFd); } catch { /* already closed */ }
+  try { unlinkSync(recycleLock); } catch { /* already gone */ }
+});
+
+// ── 1. Force-kill ───────────────────────────────────────────────────────────
+// EPERM on the kill attempt means the daemon is owned by another user. Can't
+// kill it. Don't proceed to unlink + restart — that'd resurrect a fresh daemon
+// alongside the foreign-owned one, double-writing the DB.
+let killBlockedByEperm = false;
+if (Number.isFinite(pid) && pid > 0 && isAlive(pid)) {
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('taskkill', ['/F', '/T', '/PID', String(pid)], { windowsHide: true, timeout: 5000 });
+    } else {
+      process.kill(pid, 'SIGKILL');
+    }
+  } catch (err) {
+    if (err && (err.code === 'EPERM' || err.code === 'EACCES')) {
+      killBlockedByEperm = true;
+    }
+    // Other errors (ESRCH = already dead) — fall through; liveness poll confirms.
+  }
+}
+
+if (killBlockedByEperm) {
+  writeOutcome('kill-permission-denied', `PID ${pid} owned by another user — leaving daemon alive, not spawning replacement`);
+  process.exit(1);
+}
+
+// ── 2. Wait for death, then unlink the lockfile ─────────────────────────────
+const deadline = Date.now() + 5000;
+let killed = !isAlive(pid);
+while (!killed && Date.now() < deadline) {
+  sleepSyncMs(100);
+  killed = !isAlive(pid);
+}
+
+if (!killed) {
+  writeOutcome('kill-failed', `PID ${pid} survived 5s force-kill window`);
+  process.exit(1);
+}
+
+// Only unlink once we know nothing's holding the lock file's old identity.
+// A surviving daemon would re-write a lockfile with its stale PID + version
+// and defeat the whole purpose of the recycle.
+try {
+  if (existsSync(lockFile)) {
+    // Defensive: if the lockfile has been re-written under us (another
+    // recycler raced), only unlink if the PID still matches what we killed.
+    try {
+      const current = JSON.parse(readFileSync(lockFile, 'utf-8'));
+      if (typeof current?.pid === 'number' && current.pid !== pid) {
+        writeOutcome('lock-changed', `another daemon (PID ${current.pid}) wrote the lock; leaving it alone`);
+        process.exit(0);
+      }
+    } catch { /* unreadable / malformed — fall through and unlink */ }
+    unlinkSync(lockFile);
+  }
+} catch { /* non-fatal */ }
+
+// ── 3. Spawn fresh daemon, detached + unref ─────────────────────────────────
+const cliPath = join(projectRoot, 'node_modules', 'moflo', 'bin', 'cli.js');
+if (existsSync(cliPath)) {
+  try {
+    const child = spawn('node', [cliPath, 'daemon', 'start', '--quiet'], {
+      cwd: projectRoot,
+      stdio: 'ignore',
+      detached: true,
+      shell: false,
+      windowsHide: true,
+    });
+    child.unref();
+    writeOutcome('ok', 'fresh daemon spawn requested');
+  } catch (err) {
+    writeOutcome('spawn-failed', err && err.message ? err.message : String(err));
+    process.exit(1);
+  }
+} else {
+  writeOutcome('cli-missing', `node_modules/moflo/bin/cli.js not present at ${cliPath}`);
+  process.exit(1);
+}
+
+// Recycler's job is done. Exit fast.
+process.exit(0);

package/bin/session-start-launcher.mjs

@@ -432,41 +432,49 @@ function stopDaemon(lockFile) {
 
   let killed = false;
   if (stalePid !== null && isDaemonPidAlive(stalePid)) {
-    // Graceful signal — platform-aware. On Windows, `process.kill(pid, 'SIGTERM')`
-    // silently force-kills (skipping the daemon's shutdown handlers that flush
-    // sql.js + release lock cleanly), so use bare `taskkill` (no /F) for a
-    // close-event signal.
-    try {
-      if (process.platform === 'win32') {
-        execFileSync('taskkill', ['/PID', String(stalePid)], { windowsHide: true, timeout: 5000 });
-      } else {
-        process.kill(stalePid, 'SIGTERM');
-      }
-    } catch { /* signal/spawn failed — fall through to liveness poll + force */ }
-
-    // Poll for death up to 3s. The daemon's shutdown handler does a final
-    // sql.js dump + lock release, which under load can take ~1s.
-    const gracefulDeadline = Date.now() + 3000;
-    while (Date.now() < gracefulDeadline) {
-      if (!isDaemonPidAlive(stalePid)) { killed = true; break; }
-      sleepSyncMs(100);
-    }
-
-    // Force-kill if still alive.
-    if (!killed) {
+    // Platform-split shutdown. On Linux/macOS, SIGTERM lets the daemon's
+    // shutdown handler run a final sql.js dump + lock release before we
+    // escalate.
+    //
+    // On Windows there is no SIGTERM equivalent for our headless detached
+    // Node daemon — `taskkill /PID` (no /F) sends a window-close message
+    // that a non-GUI process can't receive and always fails with the visible
+    // error 'process can only be terminated forcefully'. The prior
+    // implementation invoked it anyway, swallowed the error, then polled
+    // alive for 3s before escalating — exactly the time-waste that pushed
+    // §3's stopDaemon past the 3000ms SessionStart hook timeout. Go
+    // straight to /F /T (tree-kill, in case a worker child outlived its
+    // parent) on Win.
+    if (process.platform === 'win32') {
       try {
-        if (process.platform === 'win32') {
-          execFileSync('taskkill', ['/F', '/T', '/PID', String(stalePid)], { windowsHide: true, timeout: 5000 });
-        } else {
-          process.kill(stalePid, 'SIGKILL');
-        }
-      } catch { /* dead or unreachable */ }
-      // Short grace period for OS reap.
+        execFileSync('taskkill', ['/F', '/T', '/PID', String(stalePid)], { windowsHide: true, timeout: 5000 });
+      } catch { /* dead or unreachable — liveness poll below confirms */ }
+      // Short grace period for OS reap (typically ~ms).
       const forceDeadline = Date.now() + 1000;
       while (Date.now() < forceDeadline) {
         if (!isDaemonPidAlive(stalePid)) { killed = true; break; }
         sleepSyncMs(100);
       }
+    } else {
+      try { process.kill(stalePid, 'SIGTERM'); } catch { /* signal failed — escalate below */ }
+
+      // Poll for death up to 3s. The daemon's shutdown handler does a final
+      // sql.js dump + lock release, which under load can take ~1s.
+      const gracefulDeadline = Date.now() + 3000;
+      while (Date.now() < gracefulDeadline) {
+        if (!isDaemonPidAlive(stalePid)) { killed = true; break; }
+        sleepSyncMs(100);
+      }
+
+      // Force-kill if still alive.
+      if (!killed) {
+        try { process.kill(stalePid, 'SIGKILL'); } catch { /* dead or unreachable */ }
+        const forceDeadline = Date.now() + 1000;
+        while (Date.now() < forceDeadline) {
+          if (!isDaemonPidAlive(stalePid)) { killed = true; break; }
+          sleepSyncMs(100);
+        }
+      }
     }
 
     if (!killed) {
@@ -499,6 +507,42 @@ function recycleDaemon(lockFile, label) {
   return true;
 }
 
+// Numeric semver compare. Returns -1 / 0 / +1 for a vs b. Treats missing
+// segments as 0 so '4.10' < '4.10.4'. Strips pre-release tags ('1.2.3-beta'
+// compares as '1.2.3') — close enough for "is the daemon's version behind
+// the installed package's version", which is all §2a needs.
+function compareVersionsSemver(a, b) {
+  const norm = (v) => String(v || '').split('-')[0].split('.').map((s) => {
+    const n = parseInt(s, 10);
+    return Number.isFinite(n) ? n : 0;
+  });
+  const aa = norm(a);
+  const bb = norm(b);
+  const len = Math.max(aa.length, bb.length);
+  for (let i = 0; i < len; i++) {
+    const av = aa[i] ?? 0;
+    const bv = bb[i] ?? 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+// Resolve `bin/lib/daemon-recycler.mjs` across the three places it can live:
+//   1. node_modules/moflo/bin/lib/  (consumer install, always present)
+//   2. .claude/scripts/lib/         (synced copy in consumer/dogfood projects)
+//   3. bin/lib/                     (dogfood source tree)
+// Returns null when not found — §2a falls back to inline force-kill in that
+// case, which is the pre-recycler behavior.
+function resolveDaemonRecyclerPath() {
+  const candidates = [
+    resolve(projectRoot, 'node_modules/moflo/bin/lib/daemon-recycler.mjs'),
+    resolve(projectRoot, '.claude/scripts/lib/daemon-recycler.mjs'),
+    resolve(projectRoot, 'bin/lib/daemon-recycler.mjs'),
+  ];
+  return candidates.find((p) => existsSync(p)) || null;
+}
+
 // ── 2. Reset workflow state for new session ──────────────────────────────────
 const stateDir = resolve(projectRoot, '.claude');
 const stateFile = resolve(stateDir, 'workflow-state.json');
@@ -514,6 +558,84 @@ try {
   // Non-fatal - workflow gate will use defaults
 }
 
+// ── 2a. Recycle daemon when behind installed version (#1054 follow-up) ──────
+// Promoted from §3a-pre to run BEFORE §3's file-sync work. The launcher has
+// a 3000ms SessionStart hook timeout (src/cli/services/hook-block-hash.ts);
+// §0c (DB repair) + §3 (file-sync, manifest, cherry-pick) + stopDaemon's
+// up-to-4s graceful poll routinely exceeds it on upgrade sessions, killing
+// the launcher mid-§3. Result: §3a-pre never ran on the very sessions that
+// needed it, leaving a stale-version daemon alive after `npm install moflo`
+// + Claude restart — `📊 ?` in the statusline (this bug's tell).
+//
+// Semver-BEHIND only — a downgrade-test daemon ahead of installed is left
+// alone. Pre-#1054 daemons (no `version` field in the lock) are treated as
+// behind because by construction they predate version publishing.
+//
+// Force-kill skips the graceful poll: a stale-code daemon's flush handlers
+// are themselves stale, and losing one in-flight flush beats running past
+// the hook timeout. fireAndForget the fresh `daemon start` so spawn returns
+// immediately and the launcher can move on to §3.
+try {
+  const mofloPkgPath = resolve(projectRoot, 'node_modules/moflo/package.json');
+  const lockFile = resolve(projectRoot, '.moflo', 'daemon.lock');
+  // Single readFileSync each (try/catch instead of existsSync + readFileSync)
+  // — halves the syscalls in the hot path and closes the TOCTOU window where
+  // the file existed for existsSync but was unlinked before readFileSync.
+  let installedVersion;
+  let daemonVersion;
+  let daemonPid;
+  try {
+    installedVersion = JSON.parse(readFileSync(mofloPkgPath, 'utf-8')).version;
+  } catch { /* node_modules/moflo absent — fresh consumer or fatal, nothing §2a can do */ }
+  let lockReadOk = false;
+  try {
+    const lock = JSON.parse(readFileSync(lockFile, 'utf-8'));
+    lockReadOk = true;
+    if (typeof lock?.version === 'string') daemonVersion = lock.version;
+    if (typeof lock?.pid === 'number' && lock.pid > 0) daemonPid = lock.pid;
+  } catch { /* no lock or corrupt — no daemon to recycle, skip the block below */ }
+
+  if (installedVersion && lockReadOk) {
+    const isBehind = !daemonVersion || compareVersionsSemver(daemonVersion, installedVersion) < 0;
+    if (isBehind) {
+      const observed = daemonVersion ?? '<pre-1054 / unknown>';
+      const recyclerPath = resolveDaemonRecyclerPath();
+      if (recyclerPath && daemonPid && daemonPid > 0) {
+        // Fire-and-forget the detached recycler. Per the launcher's contract
+        // ("spawns background tasks ... and exits immediately"), the
+        // kill+wait+restart sequence runs in a separate process so §2a's
+        // foreground cost is ~ms instead of up-to-5s. The recycler writes
+        // .moflo/daemon-recycle.last.json on completion for doctor to read.
+        fireAndForget(
+          'node',
+          [recyclerPath, projectRoot, String(daemonPid), installedVersion],
+          'daemon-behind-recycle',
+        );
+        emitMutation(
+          'recycled stale daemon',
+          `behind: daemon v${observed} → installed v${installedVersion}`,
+        );
+      } else if (!recyclerPath) {
+        // Recycler script missing — happens during the transition release
+        // where the launcher upgraded but bin/lib/daemon-recycler.mjs hasn't
+        // synced yet. Surface so /healer can flag; §3 below will sync the
+        // recycler on this session and §2a covers it on the next.
+        emitWarning(
+          `daemon-behind recycle: bin/lib/daemon-recycler.mjs not resolvable — ` +
+          `daemon v${observed} stays alive this session, will recycle on the next`,
+        );
+      } else {
+        // No PID — lockfile is corrupt or malformed. Unlink it so a fresh
+        // daemon can start cleanly on the next worker request.
+        try { unlinkSync(lockFile); } catch { /* non-fatal */ }
+        emitMutation('cleared malformed daemon lock', `version field: ${observed}`);
+      }
+    }
+  }
+} catch (err) {
+  emitWarning(`daemon-behind check failed: ${errMessage(err)}`);
+}
+
 // ── 3. Auto-sync scripts and helpers on version change ───────────────────────
 // Controlled by `auto_update.enabled` in moflo.yaml (default: true).
 // When moflo is upgraded (npm install), scripts and helpers may be stale.
@@ -931,12 +1053,14 @@ try {
       // prune when the consumer's file matches a known-shipped hash —
       // customized files (different hash) get preserved with a one-line
       // notice the user can act on.
+      let prunedRetiredPaths = new Set();
       try {
         const retiredManifestPath = resolve(
           projectRoot,
           'node_modules/moflo/retired-files.json',
         );
         const report = applyRetiredPrune(projectRoot, retiredManifestPath);
+        prunedRetiredPaths = new Set(report.pruned);
         if (report.pruned.length > 0) {
           emitMutation(
             'pruned retired shipped files',
@@ -988,10 +1112,23 @@ try {
 
       // Manifest reflects synced files immediately; version stamp is deferred
       // to 3g so an aborted launcher re-runs upgrade detection (#730).
+      //
+      // Exclude paths that `applyRetiredPrune` just deleted from disk —
+      // recording a non-existent file in `installed-files.json` triggers
+      // false drift detection on the next launcher run (`manifestDrifted`
+      // flips true because the recorded path doesn't exist), which spuriously
+      // re-fires the cherry-pick + manifest-sync pipeline. Widening
+      // `retired-files.json`'s hash window in #1133 exposed this — more
+      // legitimate matches → more pruned files → guaranteed false drift on
+      // the next launcher and re-imported legacy rows (knowledge namespace
+      // came back even though the migration deleted it).
+      const persistedManifest = prunedRetiredPaths.size > 0
+        ? currentManifest.filter((e) => !prunedRetiredPaths.has(e.path))
+        : currentManifest;
       try {
         const cfDir = resolve(projectRoot, '.moflo');
         if (!existsSync(cfDir)) mkdirSync(cfDir, { recursive: true });
-        writeFileSync(manifestPath, JSON.stringify(currentManifest, null, 2));
+        writeFileSync(manifestPath, JSON.stringify(persistedManifest, null, 2));
         pendingVersionStampWrite = { path: versionStampPath, version: installedVersion };
       } catch (err) {
         // #854: manifest write must surface — without it the next launcher
@@ -1009,53 +1146,12 @@ try {
   emitWarning(`upgrade section failed (${errMessage(err)})`);
 }
 
-// ── 3a-pre. Recycle daemons started before the current moflo install ────────
-// The version-bump block above only fires when `installedVersion !== cachedVersion`.
-// That misses the common case where a user upgraded moflo, ran ONE session
-// (which bumped the stamp + recycled the daemon), then on a subsequent session
-// the version stamp matches but the daemon they started long-ago is still
-// holding stale module cache from a pre-collapse moflo image. The
-// `[neural-tools] @moflo/embeddings not resolvable` spam (#639) is the
-// observable symptom of exactly this: a daemon running pre-#592 code that no
-// longer exists in source, calling a require helper that prints the warning
-// every time `neural_predict` / `neural_patterns` fires.
-//
-// Fix (epic #1054): compare the daemon-lock's reported moflo `version` against
-// the installed `node_modules/moflo/package.json` version. If they differ —
-// or the lock predates #1054 and has no `version` field at all — recycle the
-// daemon. This is exact (not a heuristic margin like the prior mtime-based
-// check) and named explicitly so the doctor's Daemon Version Skew check
-// (#1059) can share the diagnosis.
-//
-// Pre-#1054 daemons have no `version` in their lock payload — treated as a
-// mismatch by definition because by construction they were launched before
-// version publishing existed.
-try {
-  const mofloPkgPathForRecycle = resolve(projectRoot, 'node_modules/moflo/package.json');
-  const lockFile = resolve(projectRoot, '.moflo', 'daemon.lock');
-  // Cheap stat first — if either file is gone, no skew check is possible.
-  if (existsSync(mofloPkgPathForRecycle) && existsSync(lockFile)) {
-    const installedVersion = JSON.parse(readFileSync(mofloPkgPathForRecycle, 'utf-8')).version;
-    let daemonVersion;
-    try {
-      const lock = JSON.parse(readFileSync(lockFile, 'utf-8'));
-      if (typeof lock?.version === 'string') daemonVersion = lock.version;
-    } catch { /* corrupt lock — recycleDaemon will unlink it */ }
-    if (daemonVersion !== installedVersion) {
-      if (recycleDaemon(lockFile, 'daemon-version-skew')) {
-        const observed = daemonVersion ?? '<pre-1054 / unknown>';
-        emitMutation(
-          'recycled stale daemon',
-          `version skew: installed ${installedVersion}, daemon ${observed}`,
-        );
-      }
-    }
-  }
-} catch (err) {
-  // Non-fatal; surface via emitWarning per feedback_no_layered_workarounds —
-  // no silent catch on the upgrade path (#854).
-  emitWarning(`daemon version-skew check failed: ${errMessage(err)}`);
-}
+// ── 3a-pre. (removed) Daemon-version-skew recycle moved to §2a. ─────────────
+// The previous version of this block ran AFTER §3's heavy file-sync work,
+// which routinely exceeded the 3000ms SessionStart hook timeout and was
+// killed before reaching this point. §2a now runs early and force-kills the
+// stale daemon before §3 can starve out. Don't restore §3a-pre — keep the
+// recycle in one place so the two paths can't drift.
 
 // ── 3a. Auto-migrate settings.json (npx flo → node helpers, PATH setup) ────
 // Existing users may have stale settings.json with `npx flo` hooks that break