moflo 4.10.11 → 4.10.13

package/bin/gate.cjs

@@ -81,7 +81,21 @@ var config = loadGateConfig();
 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'];
+// #1171 — DANGEROUS gained PowerShell additions to match the matcher widening
+// that now routes the dedicated `PowerShell` tool through check-dangerous-command.
+// POSIX entries still apply because PS will execute them when invoked. Substring
+// match (case-insensitive) inside the gate.
+var DANGEROUS = [
+  'rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda',
+  // PowerShell destructive patterns. Won't catch every adversarial spelling
+  // (PS aliases let `ri -r -force C:\` mean the same thing) but covers the
+  // common-typo destruction class — symmetric to the POSIX list's intent.
+  'remove-item -recurse -force c:\\',
+  'remove-item -recurse -force /',
+  'remove-item -recurse -force ~',
+  'format-volume',
+  'clear-disk',
+];
 
 // #1132 — Bash memory-first gate.
 //
@@ -94,6 +108,9 @@ var CREDIT_MEMORY_SEARCH_RE = /semantic-search|memory search|memory retrieve|mem
 // 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.
+// #1171 — extended with PowerShell-native exploration forms now that the matcher
+// widens to the `PowerShell` tool. Plain `Get-ChildItem` without -Recurse stays
+// uncovered (it's `ls`-equivalent and plain `ls` is allowed).
 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',
@@ -108,6 +125,17 @@ var READ_LIKE_BASH_RE = new RegExp([
   // 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',
+  // #1171 — PowerShell recursive exploration (parallel to POSIX `find`/`fd`).
+  // The `-Recurse` flag is what makes it expensive enough to gate; plain
+  // `Get-ChildItem` is `ls`-shaped and intentionally not blocked.
+  '^\\s*(?:Get-ChildItem|gci)\\b[^|]*-Recurse\\b',
+  // #1171 — cmd-style recursive listing (`dir /s` or `dir /S`). Only the
+  // Windows `/s` form, NOT POSIX `dir -s` (sort-by-size, where `dir` is aliased
+  // to `ls -l` on many distros) — false-positive blocking that would break
+  // legitimate POSIX listings.
+  '^\\s*dir\\b[^|]*\\s\\/[sS]\\b',
+  // #1171 — PowerShell hex dump, parallel to POSIX `xxd`/`hexdump`.
+  '^\\s*Format-Hex\\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
@@ -129,6 +157,32 @@ var BASH_CARVE_OUT_RE = new RegExp([
   // `find` commands that lack a `-delete` / `-exec rm` suffix.
   '^\\s*find\\s+.+?-(delete|exec\\s+rm)\\b',
 ].join('|'));
+// #1171 follow-up — strip quoted string bodies and heredoc bodies from a shell
+// command for purposes of dangerous-pattern substring matching. Used by
+// check-dangerous-command. Does NOT strip $(...) or `...` because those bodies
+// execute. Double-quoted strings handle escaped quotes (`\"`) correctly so
+// `git commit -m "fix \"X\""` strips the whole quoted body, not just the first
+// `\"` pair. Single quotes don't have escapes in bash/sh — `'[^']*'` is exact.
+function stripQuotedAndHeredocs(cmd) {
+  var out = cmd;
+  // Heredoc tail: `<<TOKEN`, `<<-TOKEN`, `<<'TOKEN'`, `<<"TOKEN"` through end-of-input.
+  // Bash heredocs are multi-line; in single-line tool inputs they show up as the
+  // tail after `<<TOKEN`. Conservative tail-strip — benign content after a heredoc
+  // body on the same logical line is also stripped, harmless for this gate.
+  // Token class includes `-` so hyphenated heredoc tags (`<<END-OF-DOC`) match
+  // the full token, not just the leading word — without this the strip would
+  // halt at `<<END` and leave `-OF-DOC` plus the body as literal text.
+  out = out.replace(/<<-?\s*['"]?[\w-]+['"]?[\s\S]*$/, '');
+  // Here-string `<<<word` — strip the word.
+  out = out.replace(/<<<\s*\S+/g, '');
+  // Single-quoted strings — no escapes inside single quotes in sh/bash.
+  out = out.replace(/'[^']*'/g, "''");
+  // Double-quoted strings — `(?:[^"\\]|\\.)*` matches anything except an
+  // unescaped `"`, so escaped `\"` mid-string doesn't terminate the strip early.
+  out = out.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+  return out;
+}
+
 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;
 
@@ -254,14 +308,27 @@ var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:test|t)(
 // Edits to these don't change runtime behaviour, so they don't invalidate prior test/simplify runs.
 // Lock files and .gitignore are tracked but inert; package.json/*.yaml ARE source — they reset.
 var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^|[\\\/])(CHANGELOG(?:\.md)?|\.env\.example|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb)$/i;
+// #1176 — path-based inert markers. The extension-based RE above can't cover
+// `.github/workflows/*.yml` without also exempting `moflo.yaml` / `tsconfig.yaml`
+// (which ARE source). Anchor on the GitHub-meta directories that hold CI config
+// and template scaffolds — editing those doesn't expose new runtime surface, so
+// they shouldn't reset testsRun/simplifyRun the way a real source edit does.
+// Trailing terminator includes `.` so the single-file template form
+// `.github/PULL_REQUEST_TEMPLATE.md` matches alongside the directory form.
+var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)/i;
 // Test files: invalidate the testing gate (tests are stale once test code changes)
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
 var EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE = /(?:^|[\\\/])(__tests__|__mocks__|tests?|spec|specs|cypress|e2e|fixtures?)[\\\/]|\.(test|spec)\.[mc]?[jt]sx?$|\.fixture\.[mc]?[jt]sx?$/i;
+// #1176 — source-file extensions used by the no-source-files PR exemption.
+// When the cumulative branch diff has zero files matching this RE (i.e. only
+// YAML/MD/JSON/lockfiles/images/templates), the testing/simplify/learnings
+// gates auto-pass at `check-before-pr`. Lists every language moflo ships
+// against — additions here should match TEST_RUNNER_RE's language coverage.
+var SOURCE_FILE_RE = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|rb|java|kt|swift|c|cc|cpp|h|hpp|sh|bash|ps1)$/i;
 // Docs-only PR exemption: text/markup/image extensions that cannot change runtime behaviour.
-// If EVERY file in the PR diff matches this, skip testing/simplify/learnings gates.
-// Anchored to end-of-path so e.g. `foo.md.js` does not match. Excludes lock files / configs
-// on purpose — those are inert for edit-reset (above) but not "documentation".
+// Retained for the transparency message when the diff is *purely* docs (no YAML/JSON either)
+// — gives a more specific reason than "no source files" in that subset.
 var DOCS_ONLY_RE = /\.(md|markdown|txt|rst|adoc|html?|pdf|png|jpe?g|gif|svg|webp|ico|bmp)$/i;
 
 // Classifier-aware simplify gate skip. Returns a string reason if the gate
@@ -285,13 +352,24 @@ function classifyForGateSkip(state) {
   } catch (e) { return null; }
   if (typeof classify !== 'function') return null;
 
-  function tryClassify(diffText, label) {
+  function tryClassify(diffText, label, allowSmallReviewFix) {
     try {
       var dec = classify(diffText);
       if (dec.tier === 'TRIVIAL') {
         var loc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
         return label + ' is TRIVIAL (' + loc + ' LOC, ' + (dec.stats.fileCount || 0) + ' file(s))';
       }
+      // #1176 — SMALL review-fix shape (snapshot path only). A ≤30-LOC delta with
+      // zero new declarations on top of an already-reviewed branch is the typical
+      // "apply 3 review fixes" cycle — re-running /flo-simplify against the same
+      // surface plus a few-line tweak adds no new signal. Baseline path stays
+      // TRIVIAL-only so brand-new SMALL features still get reviewed.
+      if (allowSmallReviewFix && dec.tier === 'SMALL') {
+        var totalLoc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
+        if (totalLoc <= 30 && (dec.stats.declAdded || 0) === 0) {
+          return label + ' is SMALL review-fix shape (' + totalLoc + ' LOC, no new declarations)';
+        }
+      }
     } catch (e) { /* fall through */ }
     return null;
   }
@@ -311,7 +389,9 @@ function classifyForGateSkip(state) {
     var workTreeA = gitDiff(['diff', 'HEAD']) || '';
     if (snapDiff !== null) {
       var combined = snapDiff + (workTreeA ? '\n' + workTreeA : '');
-      var hit = tryClassify(combined, 'delta since last /simplify');
+      // Snapshot path: allow SMALL review-fix shape because the original /simplify
+      // already covered the surface and only tiny no-decl-touching tweaks followed.
+      var hit = tryClassify(combined, 'delta since last /simplify', true);
       if (hit) return hit;
     }
   }
@@ -475,6 +555,11 @@ switch (command) {
     // #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.
+    //
+    // #1171 — the case name is historical. The matcher now also covers the
+    // dedicated `PowerShell` tool, and READ_LIKE_BASH_RE already matched PS
+    // readers (Get-Content/Select-String/Get-ChildItem -Recurse/Format-Hex).
+    // Treat this case as shell-agnostic read-gate logic.
     var cmd = process.env.TOOL_INPUT_command || '';
 
     // 1) CREDIT — preserved behavior. A real memory-search invocation flips
@@ -531,6 +616,15 @@ switch (command) {
         s.testsRun = true;
         writeState(s);
       }
+    } else if (cmd) {
+      // #1176 — emit a stderr crumb when invoked with a non-empty command that
+      // doesn't match the test-runner pattern. Common pitfall: users run the
+      // stamp manually from a terminal to "satisfy the gate"; the silent no-op
+      // looks indistinguishable from success. gate-hook.mjs drops stderr from
+      // exit-0 invocations, so this only surfaces to direct CLI use — exactly
+      // the case where the friction lives.
+      var preview = cmd.length > 80 ? cmd.slice(0, 77) + '...' : cmd;
+      process.stderr.write('gate: record-test-run no-op — TOOL_INPUT_command="' + preview + '" did not match TEST_RUNNER_RE\n');
     }
     break;
   }
@@ -551,13 +645,21 @@ switch (command) {
         if (sha && s.simplifySnapshotSha !== sha) { s.simplifySnapshotSha = sha; changed = true; }
       } catch (e) { /* no git or detached state — skip snapshot, gate still works */ }
       if (changed) writeState(s);
+    } else if (skName) {
+      // #1176 — same rationale as record-test-run. A no-op stamp on a non-simplify
+      // skill name is silent to hooks (gate-hook.mjs drops exit-0 stderr) but
+      // visible when a user runs the stamp directly to "satisfy the gate" and
+      // wonders why simplifyRun stays false.
+      process.stderr.write('gate: record-skill-run no-op — TOOL_INPUT_skill="' + skName + '" is not simplify/flo-simplify\n');
     }
     break;
   }
   case 'reset-edit-gates': {
     var fp = process.env.TOOL_INPUT_file_path || '';
-    // Inert files (markdown, lockfiles, CHANGELOG, .env.example): no gate reset.
-    if (fp && EDIT_RESET_SKIP_BOTH_RE.test(fp)) break;
+    // Inert files (markdown, lockfiles, CHANGELOG, .env.example) AND inert paths
+    // (.github/workflows/, .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE/, #1176):
+    // no gate reset — editing these doesn't expose new runtime surface.
+    if (fp && (EDIT_RESET_SKIP_BOTH_RE.test(fp) || EDIT_RESET_SKIP_PATH_RE.test(fp))) break;
     var s = readState();
     // Test-only edits invalidate testsRun but preserve simplifyRun (#908).
     var isTestOnly = fp && EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE.test(fp);
@@ -580,14 +682,27 @@ switch (command) {
     // optional ENV=val prefix segment catches `GH_TOKEN=x gh pr create`.
     var cmd = process.env.TOOL_INPUT_command || '';
     if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
-    // Docs-only exemption: if every file changed vs the merge-base is a docs/image
-    // file (no runtime-behaviour surface), skip the testing/simplify/learnings gates
+    // No-source-files exemption (#1176, supersedes the original docs-only path).
+    // If every file changed vs the merge-base is either a docs/image file or a
+    // path-inert file (.github/workflows/, ISSUE_TEMPLATE/, PULL_REQUEST_TEMPLATE/)
+    // — i.e. NO source files in the diff — skip testing/simplify/learnings gates
     // and surface a one-line transparency note. Falls through to the standard gate
     // on any failure (no base, no diff, exec error) — fail-safe by design.
+    //
+    // Source-file detection is the inverse of the inert checks: a file is "source"
+    // when it matches SOURCE_FILE_RE AND is not inside an inert path. This catches
+    // `.github/workflows/foo.sh` (sh extension but path-inert → no source).
     var changed = getChangedFilesVsBase();
-    if (changed && changed.length > 0 && changed.every(function(f) { return DOCS_ONLY_RE.test(f); })) {
-      process.stdout.write('Docs-only PR (' + changed.length + ' file' + (changed.length === 1 ? '' : 's') + ') — skipping testing/simplify/learnings gates.\n');
-      break;
+    if (changed && changed.length > 0) {
+      var hasSource = changed.some(function(f) {
+        return SOURCE_FILE_RE.test(f) && !EDIT_RESET_SKIP_PATH_RE.test(f);
+      });
+      if (!hasSource) {
+        var allDocs = changed.every(function(f) { return DOCS_ONLY_RE.test(f); });
+        var reason = allDocs ? 'Docs-only' : 'No source files in branch diff';
+        process.stdout.write(reason + ' (' + changed.length + ' file' + (changed.length === 1 ? '' : 's') + ') — skipping testing/simplify/learnings gates.\n');
+        break;
+      }
     }
     var s = readState();
     // Classifier-aware skip: if delta-since-snapshot or whole-branch diff is
@@ -620,7 +735,17 @@ switch (command) {
     process.exit(2);
   }
   case 'check-dangerous-command': {
-    var cmd = (process.env.TOOL_INPUT_command || '').toLowerCase();
+    // #1171 follow-up — strip quoted string bodies and heredoc bodies before
+    // substring-matching DANGEROUS. Without this, `git commit -m "...remove-item
+    // -recurse -force c:\..."` blocks because the literal pattern appears in
+    // the quoted message body. Quoted text isn't executing — the gate's job is
+    // to catch typo-class destruction in the actual command, not text mentions
+    // inside arguments. Trade-off: `bash -c "rm -rf /"` also bypasses now; the
+    // gate is a typo safety net, not a security boundary, so this is acceptable.
+    // Command substitutions `$(...)` and backticks are NOT stripped — those
+    // bodies execute and dangerous content there is real.
+    var raw = process.env.TOOL_INPUT_command || '';
+    var cmd = stripQuotedAndHeredocs(raw).toLowerCase();
     for (var i = 0; i < DANGEROUS.length; i++) {
       if (cmd.indexOf(DANGEROUS[i]) >= 0) {
         console.log('[BLOCKED] Dangerous command: ' + DANGEROUS[i]);

package/bin/lib/moflo-paths.mjs

@@ -52,6 +52,25 @@ export function legacyMemoryDbBakPath(projectRoot) {
   return join(projectRoot, LEGACY_SWARM_DIR, `${LEGACY_MEMORY_DB_FILE}${LEGACY_MEMORY_DB_BAK_SUFFIX}`);
 }
 
+/**
+ * Common skip-list for any walk that enumerates a project's children looking
+ * for moflo state. Shared by `bin/session-start-launcher.mjs` (depth-1 walk)
+ * and `src/cli/commands/doctor-checks-config.ts` (depth-5 BFS) so the two
+ * can't silently diverge. Matched case-insensitively at the call site —
+ * Windows NTFS + macOS APFS are case-insensitive by default.
+ *
+ * Categories: VCS metadata, build/cache outputs, language-specific output
+ * dirs, IDE state, virtualenv dirs. NOT included: `.moflo*` — every walk
+ * filters that separately so archived residue from `flo doctor --fix` can be
+ * recognised by prefix.
+ */
+export const COMMON_WALK_SKIP_NAMES = Object.freeze(new Set([
+  'node_modules', '.git', '.svn', '.hg',
+  'dist', 'build', 'out', 'target', '.next', '.nuxt', '.cache',
+  'coverage', '.idea', '.vscode', '.turbo', '.svelte-kit',
+  'vendor', '__pycache__', '.venv', 'venv', '.tox',
+]));
+
 export function memoryDbCandidatePaths(projectRoot) {
   return [
     memoryDbPath(projectRoot),
@@ -61,6 +80,40 @@ export function memoryDbCandidatePaths(projectRoot) {
   ];
 }
 
+/**
+ * Walk strictly upward from `dir` (exclusive) and return the nearest ancestor
+ * that has `.moflo/moflo.db`, or `null` if none exists below the filesystem
+ * root.
+ *
+ * Used by the launcher and `flo init` to detect nested-.moflo/ situations
+ * (#1174). Post-resolver-fix `findProjectRoot` already returns the topmost
+ * memory marker, so encountering an ancestor here means either:
+ *   1. `CLAUDE_PROJECT_DIR` explicitly overrode to a sub-directory (legitimate
+ *      user action — log a warning but don't refuse), or
+ *   2. The launcher is running before any `.moflo/moflo.db` exists at the
+ *      current root (e.g. fresh init in a sub-workspace).
+ *
+ * In either case the caller wants to surface a clear diagnostic so the user
+ * can run `flo doctor --fix` to consolidate.
+ *
+ * @param {string} dir absolute path to walk up from
+ * @returns {string | null} ancestor directory containing `.moflo/moflo.db`
+ */
+export function findAncestorMofloRoot(dir) {
+  const start = resolve(dir);
+  const fsRoot = parse(start).root;
+  let cursor = dirname(start);
+  while (cursor !== fsRoot) {
+    if (existsSync(join(cursor, '.moflo', 'moflo.db'))) {
+      return cursor;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+
 /**
  * Resolve the project root the same way the TS bridge does. Every bin/
  * script that touches `.moflo/moflo.db` (or any sibling state under
@@ -83,15 +136,32 @@ export function findProjectRoot(opts) {
   const start = resolve(startDir);
   const fsRoot = parse(start).root;
 
-  // High-priority pass: memory markers + CLAUDE.md/package.json pair.
+  // Pass A — memory markers, topmost wins (#1174). Walks the FULL ancestor
+  // chain, returns the highest ancestor with .moflo/moflo.db or .swarm/memory.db.
+  // Guarantees the root daemon is canonical in a monorepo with nested residue.
+  let topmostMemoryMarker = null;
   let dir = start;
   while (dir !== fsRoot) {
     if (basename(dir) === 'node_modules') {
       dir = dirname(dir);
       continue;
     }
-    if (existsSync(join(dir, '.moflo', 'moflo.db'))) return dir;
-    if (existsSync(join(dir, '.swarm', 'memory.db'))) return dir;
+    if (existsSync(join(dir, '.moflo', 'moflo.db')) || existsSync(join(dir, '.swarm', 'memory.db'))) {
+      topmostMemoryMarker = dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (topmostMemoryMarker) return topmostMemoryMarker;
+
+  // Pass B — CLAUDE.md/package.json pair, nearest wins.
+  dir = start;
+  while (dir !== fsRoot) {
+    if (basename(dir) === 'node_modules') {
+      dir = dirname(dir);
+      continue;
+    }
     if (existsSync(join(dir, 'CLAUDE.md')) && existsSync(join(dir, 'package.json'))) {
       return dir;
     }
@@ -100,7 +170,7 @@ export function findProjectRoot(opts) {
     dir = parent;
   }
 
-  // Low-priority pass: bare package.json or .git.
+  // Pass C — bare package.json or .git, nearest wins.
   dir = start;
   while (dir !== fsRoot) {
     if (basename(dir) === 'node_modules') {

package/bin/session-start-launcher.mjs

@@ -11,7 +11,7 @@ import { spawn, execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
-import { mofloDir, findProjectRoot } from './lib/moflo-paths.mjs';
+import { mofloDir, findProjectRoot, findAncestorMofloRoot, COMMON_WALK_SKIP_NAMES } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { applyRetiredPrune } from './lib/retired-files.mjs';
@@ -48,6 +48,23 @@ function sessionStartMirrorHeader(file) {
 // different DBs than the bridge reads from — never reintroduce one.
 const projectRoot = findProjectRoot();
 
+// Monorepo nested-.moflo guard (#1174). After the resolver fix, findProjectRoot
+// returns the topmost ancestor with .moflo/moflo.db, so an ancestor still
+// having one of those files means CLAUDE_PROJECT_DIR pinned us inside a
+// sub-workspace, or someone reintroduced an inline walk-up. Either way, the
+// daemon spawned from here would NOT be the same one a sibling cwd in the
+// same monorepo resolves to. Emit a clear stderr warning so the user can run
+// `flo doctor --fix` to consolidate.
+try {
+  const ancestor = findAncestorMofloRoot(projectRoot);
+  if (ancestor) {
+    process.stderr.write(
+      `moflo: nested .moflo/ detected — using "${projectRoot}" while ancestor "${ancestor}" also has .moflo/moflo.db. ` +
+      `This fragments monorepo state across multiple daemons (#1174). Run "flo doctor --fix" to consolidate.\n`,
+    );
+  }
+} catch { /* diagnostic-only — must never block session start */ }
+
 // Dogfood guard (#928). When this launcher runs inside the moflo repo itself,
 // .claude/scripts/, .claude/helpers/, and .claude/guidance/ are committed git
 // files — they ARE moflo's source of truth, not destinations to be re-synced
@@ -111,6 +128,82 @@ function errMessage(err) {
   return err && err.message ? err.message : String(err);
 }
 
+// Post-upgrade monorepo consolidation notice (#1174). The resolver change in
+// 4.10.13+ flips project-root resolution from "nearest .moflo/" to "topmost
+// .moflo/". Consumers with pre-fix nested .moflo/ residue will see their
+// effective projectRoot move upward, orphaning sub-daemons and changing the
+// per-project daemon port hash. Write a one-time restart-pending.json so the
+// user (via Claude's CLAUDE.md surface-and-delete rule) sees the guidance and
+// runs `flo doctor --fix -c nested-moflo` before the gate hooks start failing.
+//
+// Sentinel state-machine — re-arms after consolidation:
+//   !sentinel && nested  → notify (write json + sentinel, emit mutation)
+//   sentinel  && nested  → silent (already notified)
+//   sentinel  && !nested → cleanup sentinel (user consolidated; re-arm)
+//   !sentinel && !nested → silent (nothing to do)
+//
+// Best-effort — never blocks session start.
+try {
+  const nestedNoticeSentinel = join(mofloDir(projectRoot), 'nested-moflo-notice-shown');
+
+  // Cheap, depth-1 downward walk: just check the immediate children of
+  // projectRoot for `.moflo/moflo.db`. The full `flo doctor` BFS is depth-5
+  // — that's for the diagnostic. Here we only need a fast signal so the
+  // launcher stays under its perf budget.
+  //
+  // Skip-list is shared with the doctor BFS via COMMON_WALK_SKIP_NAMES to
+  // prevent divergence. Only `.moflo*`-prefixed dirs are filtered separately
+  // — a `.packages/` or `.workspaces/` directory with its own moflo state is
+  // legitimate (rare, but possible) and should still be detected.
+  let firstNested = null;
+  try {
+    const entries = readdirSync(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const name = entry.name;
+      if (COMMON_WALK_SKIP_NAMES.has(name.toLowerCase())) continue;
+      if (name.toLowerCase().startsWith('.moflo')) continue;
+      const childDir = join(projectRoot, name);
+      if (existsSync(join(childDir, '.moflo', 'moflo.db'))) {
+        firstNested = childDir;
+        break;
+      }
+    }
+  } catch { /* depth-1 walk failure — fall through, no notice */ }
+
+  const sentinelExists = existsSync(nestedNoticeSentinel);
+
+  if (firstNested && !sentinelExists) {
+    try {
+      mkdirSync(mofloDir(projectRoot), { recursive: true });
+      const pendingPath = join(mofloDir(projectRoot), 'restart-pending.json');
+      writeFileSync(pendingPath, JSON.stringify({
+        // schemaVersion (not the moflo package version) lets future readers
+        // branch on the notice shape if it ever evolves. The launcher's §0d
+        // version-match cleanup compares `pending.version === installedVersion`
+        // (moflo semver), so this schema field is safely ignored there.
+        schemaVersion: 1,
+        kind: 'nested-moflo',
+        message:
+          `moflo consolidates monorepo state at the repo root (#1174). Nested .moflo/ ` +
+          `directories detected (e.g. ${firstNested}). Run \`flo doctor --fix -c nested-moflo\` ` +
+          `to archive them and stop any orphaned sub-daemons.`,
+        createdAt: new Date().toISOString(),
+      }, null, 2));
+      writeFileSync(nestedNoticeSentinel, new Date().toISOString());
+      emitMutation('nested .moflo/ detected — restart-pending.json written with consolidation guidance');
+    } catch (err) {
+      emitWarning(`nested-moflo notice write failed: ${errMessage(err)}`);
+    }
+  } else if (!firstNested && sentinelExists) {
+    // User has consolidated. Clear the sentinel so a future re-introduction
+    // of nested .moflo/ re-arms the notice path.
+    try {
+      unlinkSync(nestedNoticeSentinel);
+    } catch { /* may have just been removed concurrently */ }
+  }
+} catch { /* diagnostic-only — must never block session start */ }
+
 // Manifest schema (#854 hardening). Originally `string[]`; now `{path,size}[]`
 // so the launcher can detect *content* drift, not just *missing-file* drift.
 // Reading accepts both forms — a legacy v1 manifest is reported via
@@ -189,7 +282,7 @@ function writeUpgradeNotice(status) {
   buildAndWriteNotice(upgradeNoticeContext, status);
 }
 
-// ── 0-pre. Drop any stale upgrade notice (#738, #743) ───────────────────────
+// ── 0-pre. Drop any stale upgrade notice (#738, #743, #1173) ────────────────
 // `upgrade-notice.json` is a transient handshake between launcher and
 // statusline — it should never survive past the launcher run that wrote it.
 // Pre-#738 launchers wrote a 1-hour-TTL "complete" notice after upgrade work
@@ -199,9 +292,46 @@ function writeUpgradeNotice(status) {
 // notice (legacy file, aborted launcher, future writer mistake) gets dropped
 // before the statusline can see it. The in-progress notice for THIS session,
 // if any, is written later in section 3 and cleared in section 3f.
-try {
-  unlinkSync(join(mofloDir(projectRoot), 'upgrade-notice.json'));
-} catch { /* non-fatal — file usually doesn't exist */ }
+//
+// #1173: capture the prior notice's parsed contents BEFORE deleting so §3 can
+// detect "prior session completed upgrade work but never committed the stamp"
+// and recover via eager-stamp (Option B). Without this read, the indefinite
+// re-detect loop reported in #1173 has no signal to break on. Wrapped in an
+// existsSync guard so the common no-upgrade path doesn't pay for an ENOENT
+// throw + stack unwind on every session-start.
+let priorUpgradeNotice = null;
+if (existsSync(UPGRADE_NOTICE_PATH())) {
+  try {
+    priorUpgradeNotice = JSON.parse(readFileSync(UPGRADE_NOTICE_PATH(), 'utf-8'));
+  } catch { /* unparseable — fall through; treat as no signal */ }
+  try {
+    unlinkSync(UPGRADE_NOTICE_PATH());
+  } catch { /* deleted between stat and unlink — fine */ }
+}
+
+// #1173 Option D: defensive cleanup of in-progress upgrade notice if the
+// launcher aborts before §3f writes 'completed'. Without this, a mid-flight
+// abort leaves the (updating…) badge on the statusline until the 5-min TTL
+// expires, even though no upgrade is actually in progress.
+//
+// Coverage matrix:
+//   - normal exit / process.exit() / uncaught exception → 'exit' fires
+//   - POSIX SIGTERM/SIGINT (Claude Code's 5s hook-timeout kill, Ctrl+C) →
+//     kernel terminates without running 'exit'; explicit handlers cover this
+//     path and call process.exit() so we leave with the conventional 128+sig
+//     status. The 'exit' listener also fires on those process.exit() calls,
+//     but the cleanup already ran and the guard returns early.
+//   - Windows TerminateProcess (no signal equivalent for POSIX SIGKILL) →
+//     no Node handler runs; the 5-min in-progress notice TTL is the safety
+//     net for this path.
+let upgradeNoticeFinalized = false;
+function clearAbortedUpgradeNotice() {
+  if (!upgradeNoticeContext || upgradeNoticeFinalized) return;
+  try { unlinkSync(UPGRADE_NOTICE_PATH()); } catch { /* already gone — fine */ }
+}
+process.on('exit', clearAbortedUpgradeNotice);
+process.on('SIGTERM', () => { clearAbortedUpgradeNotice(); process.exit(143); });
+process.on('SIGINT', () => { clearAbortedUpgradeNotice(); process.exit(130); });
 
 // ── 0-bootstrap-sentinel. Surface partial-bootstrap failures (#975) ─────────
 // `scripts/post-install-bootstrap.mjs` writes `.moflo/bootstrap-failed.json`
@@ -706,6 +836,37 @@ try {
     // Dogfood (#928): never drift-heal moflo's own committed copies.
     if (isMofloDogfood) manifestDrifted = false;
 
+    // #1173 Option B: eager-stamp recovery. A prior session reached §3f and
+    // wrote the 'completed' notice but was killed before §3g committed the
+    // stamp (5s SessionStart hook timeout, post-§3f exception, ...). The
+    // upgrade work is already done; we just need to land the stamp so
+    // subsequent sessions stop re-entering this branch. Heuristic: notice
+    // captured at §0-pre shows status='completed' AND to===installedVersion
+    // AND no manifest drift this session (drift means real new work to do).
+    // On success, promote cachedVersion in-memory so the next condition sees
+    // "no upgrade needed" and skips the full upgrade work block naturally —
+    // no else-if chain with a dead `if` body that confuses future readers.
+    // Stamp recovery throws → cachedVersion stays stale → fall through to
+    // the existing full-upgrade path as a safety net.
+    if (
+      installedVersion !== cachedVersion
+      && !manifestDrifted
+      && priorUpgradeNotice?.status === 'completed'
+      && priorUpgradeNotice?.to === installedVersion
+    ) {
+      try {
+        mkdirSync(dirname(versionStampPath), { recursive: true });
+        writeFileSync(versionStampPath, installedVersion);
+        cachedVersion = installedVersion;
+        emitMutation(
+          `recovered version stamp at ${installedVersion}`,
+          'prior session completed upgrade work but stamp write was missed (#1173)',
+        );
+      } catch (err) {
+        emitWarning(`stamp recovery failed (${errMessage(err)}) — running full upgrade as fallback`);
+      }
+    }
+
     if (installedVersion !== cachedVersion || manifestDrifted) {
       if (installedVersion !== cachedVersion) {
         upgradeNoticeContext = {
@@ -1973,8 +2134,15 @@ function runMigrationsAndAnnounce(runnerPath) {
 // ── 3f. Flip the upgrade notice to "completed" (#636, #738) ─────────────────
 // See the TTL rationale at the constants above for why we switch to a
 // short-TTL completed badge instead of clearing the file.
+//
+// #1173: setting upgradeNoticeFinalized signals the exit handler (Option D
+// above) that the notice reached its terminal 'completed' state cleanly, so
+// the handler should NOT clear it on launcher exit. Without this flag the
+// exit cleanup would race with the statusline reader and drop the short-TTL
+// 'completed' badge the user is supposed to see.
 if (upgradeNoticeContext) {
   writeUpgradeNotice('completed');
+  upgradeNoticeFinalized = true;
 }
 
 // ── 3g. Commit deferred version stamp (#730) ────────────────────────────────