@mnemonik/scanner 5.120.1 → 5.131.4

package/src/doctor.ts

@@ -0,0 +1,239 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { pidIsScanner } from './pid.js';
+
+/**
+ * `mnemonik-scanner doctor` — the guard that turns the prose upgrade procedure
+ * into an executable check. It asserts the invariants that every past botched
+ * reinstall violated, and prints the one blessed remediation. Any single ✗
+ * exits non-zero so a wrapper (or a human) can react.
+ *
+ * Invariants:
+ *  1. Exactly one `mnemonik-scanner` on PATH, inside the user npm prefix
+ *     (a second copy under /usr is the classic PATH-shadow version skew).
+ *  2. If a systemd user unit exists, it is active and its ExecStart points at
+ *     that same binary.
+ *  3. Exactly one live daemon, and under systemd its PID == the unit MainPID
+ *     (a stray `node …/scanner/dist/index.js` is a duplicate local-build daemon).
+ *  4. No leftover legacy per-project daemons.
+ *  5. Installed version is not behind npm latest (warning, not failure).
+ */
+
+const HOME = homedir();
+const MNEMONIK_DIR = join(HOME, '.mnemonik');
+const PID_FILE = join(MNEMONIK_DIR, 'daemon.pid');
+const LEGACY_DAEMONS_DIR = join(MNEMONIK_DIR, 'daemons');
+const UNIT_FILE = join(HOME, '.config/systemd/user/mnemonik-scanner.service');
+
+type Level = 'ok' | 'warn' | 'fail';
+interface Check {
+  level: Level;
+  label: string;
+  detail?: string;
+}
+
+function sh(cmd: string, args: string[], timeoutMs = 5000): string | null {
+  try {
+    return execFileSync(cmd, args, {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutMs,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  // Existence alone is not identity — after PID reuse the recorded number can
+  // belong to an unrelated process. A live-but-foreign PID is dead to us.
+  return pidIsScanner(pid);
+}
+
+function installedVersion(): string | null {
+  try {
+    const here = fileURLToPath(new URL('.', import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf-8')) as {
+      version?: string;
+    };
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function runDoctor(): Promise<void> {
+  const checks: Check[] = [];
+
+  // 1. Binary uniqueness + location.
+  const prefix = sh('npm', ['config', 'get', 'prefix']);
+  const whichOut = sh('which', ['-a', 'mnemonik-scanner']);
+  const binPaths = whichOut
+    ? whichOut
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+  if (binPaths.length === 0) {
+    checks.push({
+      level: 'fail',
+      label: 'binary on PATH',
+      detail: 'mnemonik-scanner not found on PATH',
+    });
+  } else if (binPaths.length > 1) {
+    checks.push({
+      level: 'fail',
+      label: 'single binary on PATH',
+      detail: `found ${binPaths.length} copies (PATH shadow → version skew):\n    ${binPaths.join('\n    ')}`,
+    });
+  } else if (prefix && !binPaths[0]!.startsWith(prefix)) {
+    checks.push({
+      level: 'warn',
+      label: 'binary in user npm prefix',
+      detail: `${binPaths[0]} is not under npm prefix ${prefix}`,
+    });
+  } else {
+    checks.push({ level: 'ok', label: 'single binary on PATH', detail: binPaths[0] });
+  }
+  const binPath = binPaths.length === 1 ? binPaths[0]! : null;
+
+  // 2. systemd unit health + ExecStart match.
+  let unitMainPid: number | null = null;
+  const hasUnit = existsSync(UNIT_FILE);
+  if (hasUnit) {
+    const show = sh('systemctl', [
+      '--user',
+      'show',
+      'mnemonik-scanner',
+      '-p',
+      'ActiveState',
+      '-p',
+      'MainPID',
+      '-p',
+      'ExecStart',
+    ]);
+    const active = /ActiveState=active/.test(show ?? '');
+    const mainPidMatch = /MainPID=(\d+)/.exec(show ?? '');
+    unitMainPid = mainPidMatch ? parseInt(mainPidMatch[1]!, 10) : null;
+    const execMatch = /path=([^\s;]+)/.exec(show ?? '');
+    const execPath = execMatch ? execMatch[1]! : null;
+
+    if (!active) {
+      checks.push({ level: 'fail', label: 'systemd unit active', detail: 'unit is not active' });
+    } else if (binPath && execPath && execPath !== binPath) {
+      checks.push({
+        level: 'fail',
+        label: 'ExecStart matches binary',
+        detail: `unit runs ${execPath} but PATH resolves ${binPath}`,
+      });
+    } else {
+      checks.push({
+        level: 'ok',
+        label: 'systemd unit active',
+        detail: `MainPID ${unitMainPid ?? '?'}`,
+      });
+    }
+  } else {
+    checks.push({
+      level: 'warn',
+      label: 'systemd unit',
+      detail: 'no user unit — daemon must be supervised another way',
+    });
+  }
+
+  // 3. Single live daemon; under systemd it must equal MainPID.
+  let filePid: number | null = null;
+  try {
+    filePid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10);
+    if (Number.isNaN(filePid)) filePid = null;
+  } catch {
+    filePid = null;
+  }
+  const psOut = sh('ps', ['-eo', 'pid,cmd']);
+  const daemonPids = (psOut ?? '')
+    .split('\n')
+    // Only the long-running `start` daemon counts — never a `doctor`/`status`/
+    // `log`/`stop` invocation (which also runs …/scanner/dist/index.js), and
+    // never this doctor process itself.
+    .filter((l) => /(mnemonik-scanner|scanner\/dist\/index\.js)/.test(l) && /\bstart\b/.test(l))
+    .map((l) => parseInt(l.trim().split(/\s+/)[0]!, 10))
+    .filter((n) => !Number.isNaN(n) && n !== process.pid);
+  if (daemonPids.length === 0) {
+    checks.push({ level: 'fail', label: 'daemon running', detail: 'no daemon process found' });
+  } else if (daemonPids.length > 1) {
+    checks.push({
+      level: 'fail',
+      label: 'single daemon',
+      detail: `${daemonPids.length} daemon processes (duplicate) — PIDs ${daemonPids.join(', ')}`,
+    });
+  } else if (hasUnit && unitMainPid && daemonPids[0] !== unitMainPid) {
+    checks.push({
+      level: 'fail',
+      label: 'daemon is the systemd one',
+      detail: `running PID ${daemonPids[0]} != unit MainPID ${unitMainPid} (stray local-build daemon)`,
+    });
+  } else if (filePid && !pidAlive(filePid)) {
+    checks.push({
+      level: 'warn',
+      label: 'PID file fresh',
+      detail: `stale ${PID_FILE} (PID ${filePid} dead)`,
+    });
+  } else {
+    checks.push({ level: 'ok', label: 'single daemon', detail: `PID ${daemonPids[0]}` });
+  }
+
+  // 4. Legacy per-project daemons.
+  try {
+    const legacy = readdirSync(LEGACY_DAEMONS_DIR)
+      .filter((f) => f.endsWith('.pid'))
+      .map((f) => parseInt(readFileSync(join(LEGACY_DAEMONS_DIR, f), 'utf-8').trim(), 10))
+      .filter((n) => !Number.isNaN(n) && pidAlive(n));
+    if (legacy.length > 0) {
+      checks.push({
+        level: 'fail',
+        label: 'no legacy daemons',
+        detail: `legacy per-project daemons alive: ${legacy.join(', ')}`,
+      });
+    }
+  } catch {
+    // dir absent — nothing to check
+  }
+
+  // 5. Version vs npm latest (informational).
+  const local = installedVersion();
+  const latest = sh('npm', ['view', '@mnemonik/scanner', 'version'], 15000);
+  if (local && latest && local !== latest) {
+    checks.push({
+      level: 'warn',
+      label: 'up to date',
+      detail: `installed ${local}, npm latest ${latest} — run: make scanner-deploy`,
+    });
+  } else if (local) {
+    checks.push({ level: 'ok', label: 'up to date', detail: `v${local}` });
+  }
+
+  // Report.
+  const icon = { ok: '✓', warn: '⚠', fail: '✗' } as const;
+  console.log('mnemonik-scanner doctor\n');
+  for (const c of checks) {
+    console.log(`  ${icon[c.level]} ${c.label}${c.detail ? `: ${c.detail}` : ''}`);
+  }
+  const failed = checks.filter((c) => c.level === 'fail');
+  if (failed.length > 0) {
+    console.log(
+      `\n${failed.length} problem(s). Canonical fix: \`make scanner-deploy\` (build → publish shared-first → npm i -g → systemctl restart → re-verify).\n` +
+        'Do NOT hand-copy dist/ or run `make daemon-*` on a systemd host — those are what cause this.'
+    );
+    process.exit(1);
+  }
+  console.log('\nAll invariants hold.');
+  process.exit(0);
+}

package/src/fileLog.ts

@@ -0,0 +1,67 @@
+import { appendFileSync, renameSync, statSync } from 'fs';
+
+/**
+ * Append-only sink that mirrors the daemon's console output to a file the
+ * `mnemonik-scanner log` command can tail. Rotates to `<file>.old` once the
+ * file would pass `maxSize`, so a daemon that runs for weeks can't grow it
+ * without bound. Every operation is best-effort: a logging failure must never
+ * crash the daemon, so all filesystem errors are swallowed.
+ */
+export function createRotatingFileSink(logFile: string, maxSize: number): (chunk: string) => void {
+  let size = 0;
+  try {
+    size = statSync(logFile).size;
+  } catch {
+    size = 0;
+  }
+
+  return (chunk: string): void => {
+    if (!chunk) return;
+    try {
+      const bytes = Buffer.byteLength(chunk);
+      if (size > 0 && size + bytes > maxSize) {
+        try {
+          renameSync(logFile, logFile + '.old');
+        } catch {
+          // Rotation failed (e.g. cross-device) — keep appending to the
+          // current file rather than losing the line.
+        }
+        size = 0;
+      }
+      appendFileSync(logFile, chunk);
+      size += bytes;
+    } catch {
+      // Never let logging break the daemon.
+    }
+  };
+}
+
+/**
+ * Tee `process.stdout`/`process.stderr` into `logFile` on top of their normal
+ * destination. This is what makes `mnemonik-scanner log` reflect live activity
+ * regardless of how the daemon is supervised: under systemd stdout is wired to
+ * the journal (a socket), under a bare shell to the terminal — either way the
+ * file now receives the same lines. Call once at daemon start, before the
+ * daemon writes anything worth capturing.
+ */
+export function installFileLogging(logFile: string, maxSize: number): void {
+  const sink = createRotatingFileSink(logFile, maxSize);
+
+  for (const stream of [process.stdout, process.stderr]) {
+    const original = stream.write.bind(stream) as (...args: unknown[]) => boolean;
+    stream.write = ((chunk: unknown, encoding?: unknown, cb?: unknown): boolean => {
+      try {
+        if (typeof chunk === 'string') {
+          sink(chunk);
+        } else if (Buffer.isBuffer(chunk)) {
+          const enc = typeof encoding === 'string' ? (encoding as BufferEncoding) : 'utf8';
+          sink(chunk.toString(enc));
+        }
+      } catch {
+        // ignore — mirroring is best-effort
+      }
+      // Preserve the real stream's overloads (chunk, cb) / (chunk, enc, cb).
+      return original(chunk, encoding, cb);
+    }) as typeof stream.write;
+  }
+}

package/src/index.ts

@@ -5,6 +5,9 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { ScannerDaemon } from './daemon.js';
+import { installFileLogging } from './fileLog.js';
+import { runDoctor } from './doctor.js';
+import { pidIsScanner } from './pid.js';
 
 const DEFAULT_SERVER = 'https://api.mnemonik.dev';
 const MNEMONIK_DIR = join(homedir(), '.mnemonik');
@@ -21,7 +24,7 @@ interface ScannerConfig {
 }
 
 interface CliArgs {
-  command: 'start' | 'stop' | 'status' | 'log' | 'help';
+  command: 'start' | 'stop' | 'status' | 'log' | 'doctor' | 'help';
   key?: string;
   server?: string;
   roots?: string[];
@@ -31,7 +34,7 @@ function parseCliArgs(): CliArgs {
   const args = process.argv.slice(2);
   const command = (args[0] ?? 'help') as CliArgs['command'];
 
-  if (!['start', 'stop', 'status', 'log', 'help'].includes(command)) {
+  if (!['start', 'stop', 'status', 'log', 'doctor', 'help'].includes(command)) {
     return { command: 'help' };
   }
 
@@ -81,18 +84,6 @@ async function checkConfigPermissions(): Promise<void> {
   }
 }
 
-async function rotateLogIfNeeded(): Promise<void> {
-  try {
-    const { rename } = await import('fs/promises');
-    const s = await stat(LOG_FILE);
-    if (s.size > MAX_LOG_SIZE) {
-      await rename(LOG_FILE, LOG_FILE + '.old');
-    }
-  } catch {
-    // Log file doesn't exist yet
-  }
-}
-
 async function acquireLock(retried = false): Promise<boolean> {
   try {
     const { open: fsOpen } = await import('fs/promises');
@@ -113,7 +104,12 @@ async function acquireLock(retried = false): Promise<boolean> {
       const pid = parseInt(existing.trim(), 10);
       try {
         process.kill(pid, 0);
-        return false; // Process alive, lock is valid
+        // Alive is not enough — after PID reuse the number can belong to an
+        // unrelated process. Only an actual scanner holds the lock.
+        if (pidIsScanner(pid)) {
+          return false; // Process alive and is the scanner — lock is valid
+        }
+        // Live but foreign PID — treat as stale and reclaim below.
       } catch {
         // Holder is dead — remove stale lock and retry once
       }
@@ -136,10 +132,13 @@ async function readPid(): Promise<number | null> {
     // Check if process is actually alive
     try {
       process.kill(pid, 0);
-      return pid;
     } catch {
       return null; // Stale PID
     }
+    // Alive but foreign (PID reuse) is just as stale — never report it as
+    // the daemon, and never let handleStop() SIGTERM it.
+    if (!pidIsScanner(pid)) return null;
+    return pid;
   } catch {
     return null;
   }
@@ -154,6 +153,7 @@ Usage:
   mnemonik-scanner stop               Stop the running daemon
   mnemonik-scanner status             Show daemon status
   mnemonik-scanner log                Tail the scanner log file
+  mnemonik-scanner doctor             Check install health (drift detection)
   mnemonik-scanner help               Show this help
 
 Options (for start):
@@ -225,6 +225,13 @@ async function handleStart(cli: CliArgs): Promise<void> {
   // Ensure directories exist
   await mkdir(MNEMONIK_DIR, { recursive: true });
 
+  // Mirror all console output into scanner.log so `mnemonik-scanner log`
+  // reflects live activity regardless of supervisor. Under systemd, stdout is
+  // wired to the journal socket, not this file — without the tee the on-disk
+  // log goes stale and `log` shows nothing current. Install before any daemon
+  // output so the whole session is captured.
+  installFileLogging(LOG_FILE, MAX_LOG_SIZE);
+
   // Save config for future runs (never save env var key to file)
   const configToSave: ScannerConfig = {
     roots,
@@ -240,8 +247,6 @@ async function handleStart(cli: CliArgs): Promise<void> {
   await writeConfig(configToSave);
   await checkConfigPermissions();
 
-  await rotateLogIfNeeded();
-
   const locked = await acquireLock();
   if (!locked) {
     const pid = await readPid();
@@ -342,7 +347,11 @@ async function handleStatus(): Promise<void> {
         const oldPid = parseInt(content.trim(), 10);
         try {
           process.kill(oldPid, 0);
-          staleOldDaemons.push(`${f} (PID ${oldPid})`);
+          // Same PID-reuse guard as readPid(): only report genuinely live
+          // scanner processes, not whatever now occupies a recycled PID.
+          if (pidIsScanner(oldPid)) {
+            staleOldDaemons.push(`${f} (PID ${oldPid})`);
+          }
         } catch {
           // Dead process, just a stale file
         }
@@ -388,6 +397,9 @@ async function main(): Promise<void> {
     case 'log':
       await handleLog();
       break;
+    case 'doctor':
+      await runDoctor();
+      break;
     case 'help':
     default:
       printHelp();

package/src/pid.ts

@@ -0,0 +1,37 @@
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+
+/**
+ * PID-reuse guard shared by the CLI lock paths (index.ts) and doctor.
+ *
+ * `process.kill(pid, 0)` only proves that *some* process is alive at that
+ * PID, not that it is ours. After a reboot or plain PID recycling the number
+ * in daemon.pid can belong to an unrelated process — SIGTERMing it from
+ * `stop`, or refusing to `start` because of it, would be wrong. So a live PID
+ * only counts as the scanner when its command line matches the daemon's
+ * signature (same pattern doctor uses to find daemon processes via `ps`).
+ */
+const SCANNER_CMD_PATTERN = /(mnemonik-scanner|scanner\/dist\/index\.js)/;
+
+function processCmdline(pid: number): string | null {
+  // Linux: /proc/<pid>/cmdline is NUL-separated argv — cheap and exact.
+  try {
+    return readFileSync(`/proc/${pid}/cmdline`, 'utf-8').replace(/\0/g, ' ');
+  } catch {
+    // /proc unavailable (macOS) or unreadable — fall back to ps below.
+  }
+  try {
+    return execFileSync('ps', ['-o', 'args=', '-p', String(pid)], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null; // No such process, or ps unavailable — cannot confirm identity.
+  }
+}
+
+export function pidIsScanner(pid: number): boolean {
+  const cmdline = processCmdline(pid);
+  return cmdline !== null && SCANNER_CMD_PATTERN.test(cmdline);
+}

package/src/watcher.ts

@@ -1,6 +1,6 @@
 import { watch, type FSWatcher } from 'fs';
 import { join, relative } from 'path';
-import { readdir } from 'fs/promises';
+import { readdir, stat } from 'fs/promises';
 import { isGitBoundary } from '@mnemonik/shared';
 
 const SKIP_DIRS = new Set([
@@ -27,7 +27,15 @@ export type ChangeHandler = (changedFiles: string[]) => void;
 export type ErrorHandler = (err: Error) => void;
 
 export class FileWatcher {
-  private watchers: FSWatcher[] = [];
+  // Keyed by directory so a watcher can be closed and re-attached when the
+  // directory is deleted and recreated at the same path.
+  private watchers = new Map<string, FSWatcher>();
+  private watchedDirs = new Set<string>();
+  // Inode per watched directory: a delete+recreate faster than the delete
+  // event's stat() presents as "directory exists and is already watched",
+  // but the live watcher is bound to the OLD inode and is inert. Comparing
+  // inodes at event time detects the swap so the subtree can re-attach.
+  private watchedDirInodes = new Map<string, number>();
   private pendingFiles = new Set<string>();
   private flushTimer: ReturnType<typeof setTimeout> | null = null;
   private debounceMs: number;
@@ -49,10 +57,12 @@ export class FileWatcher {
   }
 
   stop(): void {
-    for (const w of this.watchers) {
+    for (const w of this.watchers.values()) {
       w.close();
     }
-    this.watchers = [];
+    this.watchers.clear();
+    this.watchedDirs.clear();
+    this.watchedDirInodes.clear();
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
@@ -74,14 +84,29 @@ export class FileWatcher {
   private async watchDir(dir: string): Promise<void> {
     const dirName = dir.split('/').pop() ?? '';
     if (SKIP_DIRS.has(dirName)) return;
+    // Dedup guard — the change callback re-enters watchDir for new
+    // subdirectories, and a rapid create/rename burst can resolve the same
+    // path twice before the first watch is registered.
+    if (this.watchedDirs.has(dir)) return;
+    this.watchedDirs.add(dir);
 
     try {
-      const watcher = watch(dir, { persistent: true }, (_event, filename) => {
+      // Record the inode BEFORE attaching so watchNewDir can distinguish a
+      // benign event on this directory from a recreate-at-same-path.
+      this.watchedDirInodes.set(dir, (await stat(dir)).ino);
+      const watcher = watch(dir, { persistent: true }, (event, filename) => {
         if (!filename) return;
         const fullPath = join(dir, filename);
         const relPath = relative(this.rootPath, fullPath);
         this.pendingFiles.add(relPath);
         this.scheduleFlush();
+        // fs.watch is non-recursive: the initial recursion below only covers
+        // directories that existed at start(). When this event is a newly
+        // created directory, attach a watcher to it too — otherwise the
+        // subtree is a permanent blind spot until restart. Fire-and-forget;
+        // watchNewDir no-ops for plain files, skip dirs, git boundaries, and
+        // already-watched paths.
+        void this.watchNewDir(fullPath, event);
       });
 
       watcher.on('error', (err) => {
@@ -91,7 +116,7 @@ export class FileWatcher {
         }
       });
 
-      this.watchers.push(watcher);
+      this.watchers.set(dir, watcher);
 
       const entries = await readdir(dir, { withFileTypes: true });
       for (const entry of entries) {
@@ -104,8 +129,91 @@ export class FileWatcher {
           await this.watchDir(child);
         }
       }
+    } catch (err) {
+      // Watch registration failed. Never fatal for the subtree's parent, but
+      // the *reason* matters: inotify/fd limit exhaustion means silently
+      // growing blind spots, while permission-denied is a benign property of
+      // the directory itself. Drop the bookkeeping (and any watcher that did
+      // attach before the failure) so a later retry can re-enter cleanly.
+      this.watchedDirs.delete(dir);
+      this.watchedDirInodes.delete(dir);
+      const stale = this.watchers.get(dir);
+      if (stale) {
+        stale.close();
+        this.watchers.delete(dir);
+      }
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOSPC' || code === 'EMFILE' || code === 'ENFILE') {
+        console.warn(
+          `[scanner] Watch limit reached (${code}) — subtree unwatched: ${dir}. ` +
+            'Raise fs.inotify.max_user_watches or trim scanner roots.'
+        );
+        // Surface to the daemon only for the root — losing the root means the
+        // whole project is blind; a subtree gap must not tear the project down
+        // (the daemon's onError removes the project entirely).
+        if (dir === this.rootPath && this.onError) {
+          this.onError(err as Error);
+        }
+      } else {
+        // Permission denied or inaccessible directory
+        console.warn(`[scanner] Cannot watch ${dir}: ${(err as Error).message}`);
+      }
+    }
+  }
+
+  /**
+   * Attach a watcher to a directory created after start(). Called from the
+   * per-directory change callback with every event path; stats the path and
+   * only recurses when it is a genuinely new, watchable directory.
+   */
+  private async watchNewDir(fullPath: string, eventType: string): Promise<void> {
+    try {
+      // Stat before the dedup check: a delete event arrives with the same
+      // path as the original create, and the stale watchedDirs entry must
+      // not short-circuit the vanish detection below.
+      const s = await stat(fullPath);
+      if (!s.isDirectory()) return;
+      if (this.watchedDirs.has(fullPath)) {
+        // Already watched — but a delete+recreate faster than this stat
+        // presents exactly like this, with the live watcher bound to the
+        // OLD (dead) inode and inert. A 'rename' event means the entry's
+        // identity changed (created / deleted / moved), so re-attach
+        // unconditionally — comparing inodes is NOT sufficient there
+        // because ext4 routinely hands the freed inode straight back to
+        // the recreated directory. 'change' events are attrib noise (a
+        // write inside the child bumps its mtime, which fires on the
+        // parent), so the cheap inode check keeps those churn-free.
+        if (eventType !== 'rename' && this.watchedDirInodes.get(fullPath) === s.ino) return;
+        this.unwatchSubtree(fullPath);
+      }
+      if (await isGitBoundary(fullPath)) return;
+      await this.watchDir(fullPath);
     } catch {
-      // Permission denied or inaccessible directory
+      // Path vanished between event and stat. If it (or anything under it)
+      // was a watched directory, drop the bookkeeping and close the dead
+      // watchers — otherwise the dedup guards in watchDir/watchNewDir block
+      // re-attachment forever when the path is recreated (build-output
+      // wipes, codegen, rm -rf && mkdir).
+      this.unwatchSubtree(fullPath);
+    }
+  }
+
+  /**
+   * Forget a deleted directory and everything watched beneath it. fs.watch
+   * emits no per-descendant events on a recursive delete, so the whole
+   * prefix must be purged here for a recreate to re-watch the full subtree.
+   */
+  private unwatchSubtree(root: string): void {
+    const prefix = root + '/';
+    for (const dir of this.watchedDirs) {
+      if (dir !== root && !dir.startsWith(prefix)) continue;
+      this.watchedDirs.delete(dir);
+      this.watchedDirInodes.delete(dir);
+      const w = this.watchers.get(dir);
+      if (w) {
+        w.close();
+        this.watchers.delete(dir);
+      }
     }
   }
 }