feat(watcher): forward FS events as workspace/didChangeWatchedFiles

LSP servers maintain their own workspace index built at initialize time
and rely on the client to push file-system events. Previously the daemon
only synced the single file being queried, so externally created/changed
files (codegen, build scripts, git checkout, the agent's own writes from
the perspective of other open files) left the server's index stale until
manual /lsp-destroy.

Each ClientEntry now lazily owns a WorkspaceWatcher (chokidar + picomatch)
that translates FS events into workspace/didChangeWatchedFiles batches.
Patterns come from the server via client/registerCapability (no
speculative watching). Ignores layer a tiny baseline (.git, .DS_Store)
over the repo's root .gitignore, with a fallback list for non-git
workspaces. Events debounce 50ms quiet / 500ms max wait.

Notable: gopls registers absolute-path globs (/abs/root/**/*.go) rather
than relative ones, so compileWatchers() matches each event against both
relative and absolute path forms. Caught by the integration test; unit
regression test added.

Rollback: PI_LSP_DISABLE_WATCHERS=1 disables all watcher creation.

- src/client.ts: honor register/unregisterCapability for
  workspace/didChangeWatchedFiles; advertise dynamicRegistration;
  expose getFileWatchers/onWatchersChanged/sendNotification
- src/watcher.ts: new WorkspaceWatcher with layered ignores,
  debounce+batch, Created+Deleted coalescing, dual-form glob matching
- src/daemon.ts: per-entry watcher lifecycle, PI_LSP_DISABLE_WATCHERS,
  LSP_DEBUG-gated pattern/event logging
- test/unit/watcher.test.ts: 11 tests against real chokidar + temp dir
- test/integration/watcher-gopls.test.ts: end-to-end against gopls
- AGENTS.md: new "Workspace File Watching" section
- flake.nix: add go (required by gopls integration test)

src/client.ts

@@ -7,8 +7,11 @@ import {
   type MessageConnection,
 } from "vscode-jsonrpc/node.js";
 import type {
+  FileSystemWatcher,
   InitializeParams,
   PublishDiagnosticsParams,
+  Registration,
+  Unregistration,
 } from "vscode-languageserver-protocol";
 import type { ServerConfig } from "./types.ts";
 import { ServerNotFoundError } from "./types.ts";
@@ -40,6 +43,12 @@ export class LspClient {
   // version numbers in didOpen/didChange. We track them so the daemon
   // can resync files via notifyChange after on-disk edits.
   private versions = new Map<string, number>();
+  // File Watcher Registrations - Servers announce which globs they care
+  // about via client/registerCapability("workspace/didChangeWatchedFiles").
+  // Stored by registration id so unregister can remove them; listeners
+  // are notified so the daemon can (re)build a chokidar watcher.
+  private fileWatchers = new Map<string, FileSystemWatcher[]>();
+  private watchersListeners = new Set<() => void>();
 
   constructor(private readonly server: ServerConfig) {}
 
@@ -115,8 +124,34 @@ export class LspClient {
         );
       },
     );
-    this.conn.onRequest("client/registerCapability", () => null);
-    this.conn.onRequest("client/unregisterCapability", () => null);
+    this.conn.onRequest(
+      "client/registerCapability",
+      (params: { registrations?: Registration[] }) => {
+        let changed = false;
+        for (const reg of params.registrations ?? []) {
+          if (reg.method !== "workspace/didChangeWatchedFiles") continue;
+          const opts = reg.registerOptions as
+            | { watchers?: FileSystemWatcher[] }
+            | undefined;
+          this.fileWatchers.set(reg.id, opts?.watchers ?? []);
+          changed = true;
+        }
+        if (changed) for (const l of this.watchersListeners) l();
+        return null;
+      },
+    );
+    this.conn.onRequest(
+      "client/unregisterCapability",
+      (params: { unregisterations?: Unregistration[] }) => {
+        let changed = false;
+        for (const unreg of params.unregisterations ?? []) {
+          if (unreg.method !== "workspace/didChangeWatchedFiles") continue;
+          if (this.fileWatchers.delete(unreg.id)) changed = true;
+        }
+        if (changed) for (const l of this.watchersListeners) l();
+        return null;
+      },
+    );
 
     this.conn.listen();
 
@@ -135,7 +170,13 @@ export class LspClient {
           publishDiagnostics: {},
           synchronization: { didSave: true },
         },
-        workspace: { workspaceFolders: true, configuration: true },
+        workspace: {
+          workspaceFolders: true,
+          configuration: true,
+          // Dynamic Registration - Required for servers like gopls to send
+          // client/registerCapability("workspace/didChangeWatchedFiles").
+          didChangeWatchedFiles: { dynamicRegistration: true },
+        },
       },
     };
     await this.conn.sendRequest("initialize", {
@@ -217,6 +258,28 @@ export class LspClient {
     return this.conn.sendRequest(method, params) as Promise<R>;
   }
 
+  // Send Raw LSP Notification - Used by the daemon's workspace watcher to
+  // push workspace/didChangeWatchedFiles batches without going through the
+  // typed command surface.
+  sendNotification(method: string, params: unknown): void {
+    this.conn.sendNotification(method, params);
+  }
+
+  // Get File Watchers - Flat list of all watcher patterns the server has
+  // registered across all registration ids.
+  getFileWatchers(): FileSystemWatcher[] {
+    return Array.from(this.fileWatchers.values()).flat();
+  }
+
+  // On Watchers Changed - Subscribe to register/unregister events for
+  // workspace/didChangeWatchedFiles. Returns an unsubscribe fn.
+  onWatchersChanged(listener: () => void): () => void {
+    this.watchersListeners.add(listener);
+    return () => {
+      this.watchersListeners.delete(listener);
+    };
+  }
+
   // Clear Diagnostics - Drops the cached diagnostics for a URI so callers
   // can force waitForDiagnostics to await a fresh publish after didChange.
   clearDiagnostics(uri: string): void {

src/daemon.ts

@@ -8,6 +8,7 @@ import * as path from "node:path";
 import { LspClient } from "./client.ts";
 import { findRoot, findServerById, pathToUri } from "./root.ts";
 import type { ServerConfig } from "./types.ts";
+import { WorkspaceWatcher, type FileEvent } from "./watcher.ts";
 import {
   logPath,
   socketPath,
@@ -37,6 +38,11 @@ interface ClientEntry {
   idleTimer: NodeJS.Timeout | null;
   ttlMs: number;
   lastUsed: number;
+  // watcher: Lazy - created on first registerCapability for watched files,
+  // disposed on eviction. Null if the server never registered any watchers
+  // (or if PI_LSP_DISABLE_WATCHERS is set).
+  watcher: WorkspaceWatcher | null;
+  unsubscribeWatchers: (() => void) | null;
 }
 
 const entries = new Map<string, ClientEntry>();
@@ -88,6 +94,8 @@ async function getOrCreateEntry(
     idleTimer: null,
     ttlMs,
     lastUsed: Date.now(),
+    watcher: null,
+    unsubscribeWatchers: null,
   };
   entries.set(key, entry);
   try {
@@ -96,10 +104,52 @@ async function getOrCreateEntry(
     entries.delete(key);
     throw err;
   }
+  attachWatcher(entry);
   bumpIdle(entry);
   return entry;
 }
 
+// Attach Watcher - Subscribes to the client's watcher-registration events.
+// The first non-empty registration lazily creates the WorkspaceWatcher;
+// subsequent register/unregister calls update its pattern set in place.
+// Honors PI_LSP_DISABLE_WATCHERS for emergency rollback.
+function attachWatcher(entry: ClientEntry): void {
+  if (process.env.PI_LSP_DISABLE_WATCHERS) return;
+  const sync = () => {
+    const patterns = entry.client.getFileWatchers();
+    if (patterns.length === 0 && !entry.watcher) return;
+    if (!entry.watcher) {
+      entry.watcher = new WorkspaceWatcher(entry.rootDir, (events) =>
+        forwardEvents(entry, events),
+      );
+      log(`watcher`, entry.server.id, entry.rootDir, `patterns=${patterns.length}`);
+    }
+    if (process.env.LSP_DEBUG) {
+      log(`watcher patterns`, entry.server.id, JSON.stringify(patterns));
+    }
+    entry.watcher.setPatterns(patterns);
+  };
+  entry.unsubscribeWatchers = entry.client.onWatchersChanged(sync);
+  // Initial Sync - Server may have already sent registerCapability during
+  // initialize before we subscribed.
+  sync();
+}
+
+// Forward Events - Sends a batched workspace/didChangeWatchedFiles to the
+// server. We catch errors so a downed transport doesn't crash the daemon.
+function forwardEvents(entry: ClientEntry, events: FileEvent[]): void {
+  try {
+    if (process.env.LSP_DEBUG) {
+      log(`watcher fire`, entry.server.id, JSON.stringify(events));
+    }
+    entry.client.sendNotification("workspace/didChangeWatchedFiles", {
+      changes: events,
+    });
+  } catch (err) {
+    log(`watcher send failed`, entry.server.id, (err as Error).message);
+  }
+}
+
 // Bump Idle - Resets the idle eviction timer. Called on every request that
 // touches the entry. We log evictions so the daemon's behavior is visible.
 function bumpIdle(entry: ClientEntry) {
@@ -113,6 +163,8 @@ function evict(entry: ClientEntry, reason: string) {
   log(`evict`, entry.key, reason);
   entries.delete(entry.key);
   if (entry.idleTimer) clearTimeout(entry.idleTimer);
+  if (entry.unsubscribeWatchers) entry.unsubscribeWatchers();
+  void entry.watcher?.dispose();
   void entry.client.dispose();
   // Auto Shutdown - If this was the last entry, there's nothing left to
   // manage. Tear down the daemon so it doesn't sit idle forever.
@@ -292,6 +344,8 @@ function shutdownDaemon(reason: string) {
   if (server) server.close();
   for (const entry of entries.values()) {
     if (entry.idleTimer) clearTimeout(entry.idleTimer);
+    if (entry.unsubscribeWatchers) entry.unsubscribeWatchers();
+    void entry.watcher?.dispose();
     void entry.client.dispose();
   }
   entries.clear();

src/watcher.ts

@@ -0,0 +1,265 @@
+// Workspace Watcher - Per-entry filesystem watcher that translates chokidar
+// events into LSP `workspace/didChangeWatchedFiles` notifications. One
+// instance lives on each daemon ClientEntry; it's torn down on eviction.
+//
+// Design:
+//   - Patterns come from the server via `client/registerCapability`. If the
+//     server registers nothing, we don't watch anything (no speculative
+//     watching - wastes inotify slots and risks event storms).
+//   - We honor the repo's `.gitignore` (root level only for v1) plus a tiny
+//     always-ignore baseline so the watcher tracks the same set the LSP
+//     server would naturally care about.
+//   - Events are debounced (50ms quiet period) but force-flushed every 500ms
+//     so sustained event streams (e.g. `git checkout` of a big branch)
+//     can't stall the batch indefinitely.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import chokidar, { type FSWatcher } from "chokidar";
+import ignore, { type Ignore } from "ignore";
+import picomatch from "picomatch";
+import type { FileSystemWatcher } from "vscode-languageserver-protocol";
+import { pathToUri } from "./root.ts";
+
+// LSP Constants - Inlined to avoid pulling the enum into a hot path. See
+// https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#fileChangeType
+const FILE_CHANGE_CREATED = 1;
+const FILE_CHANGE_CHANGED = 2;
+const FILE_CHANGE_DELETED = 3;
+
+// WatchKind - Bitmask the server uses to opt out of specific event kinds.
+// Default (when `kind` is omitted) is 7 = Create | Change | Delete.
+const WATCH_KIND_CREATE = 1;
+const WATCH_KIND_CHANGE = 2;
+const WATCH_KIND_DELETE = 4;
+
+// Debounce Settings - Quiet period before flushing, plus a max wait so a
+// continuous stream of events still gets delivered in bounded time.
+const DEBOUNCE_QUIET_MS = 50;
+const DEBOUNCE_MAX_WAIT_MS = 500;
+
+// Always-Ignore Baseline - Things that are never interesting to an LSP
+// server regardless of gitignore contents. `.git/` is the obvious one
+// (gitignore won't list itself); the rest are OS/editor noise.
+export const BASELINE_IGNORES = [
+  "**/.git/**",
+  "**/.DS_Store",
+  "**/.hg/**",
+  "**/.svn/**",
+];
+
+// Fallback Ignores - Used only when no `.gitignore` exists at rootDir.
+// Conservative list to keep non-git workspaces from blowing up.
+const NO_GITIGNORE_FALLBACK = ["**/node_modules/**", "**/.git/**"];
+
+export interface FileEvent {
+  uri: string;
+  type: 1 | 2 | 3;
+}
+
+// Build Ignore Matcher - Returns a function that takes a path relative to
+// rootDir and returns true if it should be ignored. Reads root .gitignore
+// once at construction; nested gitignores are intentionally not supported
+// in v1 (covers ~95% of repos; add nesting if it becomes a real problem).
+function buildIgnoreMatcher(rootDir: string): (relPath: string) => boolean {
+  const gitignorePath = path.join(rootDir, ".gitignore");
+  let ig: Ignore | null = null;
+  if (fs.existsSync(gitignorePath)) {
+    try {
+      ig = ignore().add(fs.readFileSync(gitignorePath, "utf8"));
+    } catch {
+      // Treat parse failure as no gitignore. The fallback will catch the
+      // worst offenders (node_modules) so we don't watch everything.
+      ig = null;
+    }
+  }
+  // Baseline always applies; gitignore (or fallback) layers on top.
+  const baselineMatcher = picomatch(BASELINE_IGNORES);
+  if (ig) {
+    return (relPath) => {
+      if (baselineMatcher(relPath)) return true;
+      // `ignore` requires posix-style paths and bare relative paths.
+      const posixRel = relPath.split(path.sep).join("/");
+      if (!posixRel || posixRel === ".") return false;
+      return ig!.ignores(posixRel);
+    };
+  }
+  const fallbackMatcher = picomatch(NO_GITIGNORE_FALLBACK);
+  return (relPath) => baselineMatcher(relPath) || fallbackMatcher(relPath);
+}
+
+// Compile Watcher Patterns - Turns the server-supplied FileSystemWatcher[]
+// into a single matcher that returns the matched `kind` bitmask (or 0 if
+// no pattern matched). Returning the kind lets us filter individual event
+// types (Created/Changed/Deleted) per the spec.
+//
+// Servers send patterns in mixed forms: bare relative globs (`**/*.ts`),
+// absolute path globs (gopls sends `/abs/root/**/*.go`), or RelativePattern
+// objects. We try matching the candidate path in both relative and absolute
+// form so we accept any of those without server-specific special casing.
+function compileWatchers(
+  watchers: FileSystemWatcher[],
+  rootDir: string,
+): (relPath: string, absPath: string) => number {
+  const compiled = watchers.map((w) => {
+    const pattern = typeof w.globPattern === "string"
+      ? w.globPattern
+      : resolveRelativePattern(w.globPattern, rootDir);
+    return {
+      match: picomatch(pattern, { dot: true }),
+      kind: w.kind ?? (WATCH_KIND_CREATE | WATCH_KIND_CHANGE | WATCH_KIND_DELETE),
+    };
+  });
+  return (relPath, absPath) => {
+    const posixRel = relPath.split(path.sep).join("/");
+    const posixAbs = absPath.split(path.sep).join("/");
+    let kind = 0;
+    for (const c of compiled) {
+      if (c.match(posixRel) || c.match(posixAbs)) kind |= c.kind;
+    }
+    return kind;
+  };
+}
+
+// Resolve Relative Pattern - LSP 3.17 added RelativePattern with a baseUri
+// that may be a string or WorkspaceFolder. We collapse to a glob relative
+// to rootDir; out-of-root patterns fall back to the raw pattern (won't
+// match anything inside rootDir, which is the safe behavior).
+function resolveRelativePattern(
+  rp: { baseUri: string | { uri: string }; pattern: string },
+  rootDir: string,
+): string {
+  const baseUri = typeof rp.baseUri === "string" ? rp.baseUri : rp.baseUri.uri;
+  if (!baseUri.startsWith("file://")) return rp.pattern;
+  const basePath = decodeURIComponent(baseUri.slice("file://".length));
+  const relBase = path.relative(rootDir, basePath);
+  if (relBase.startsWith("..") || path.isAbsolute(relBase)) return rp.pattern;
+  return relBase ? `${relBase.split(path.sep).join("/")}/${rp.pattern}` : rp.pattern;
+}
+
+export class WorkspaceWatcher {
+  private chokidar: FSWatcher | null = null;
+  private isIgnored: (relPath: string) => boolean;
+  private matchKind: (relPath: string, absPath: string) => number = () => 0;
+  private pending = new Map<string, 1 | 2 | 3>();
+  private quietTimer: NodeJS.Timeout | null = null;
+  private maxWaitTimer: NodeJS.Timeout | null = null;
+  private disposed = false;
+
+  constructor(
+    private readonly rootDir: string,
+    private readonly onEvents: (events: FileEvent[]) => void,
+  ) {
+    this.isIgnored = buildIgnoreMatcher(rootDir);
+  }
+
+  // Set Patterns - Called whenever the server's registered watchers change.
+  // First non-empty call lazily starts chokidar; subsequent calls update
+  // the matcher in place (chokidar already watches everything under
+  // rootDir minus ignores, so we just recompile filtering).
+  setPatterns(watchers: FileSystemWatcher[]): void {
+    if (this.disposed) return;
+    this.matchKind = compileWatchers(watchers, this.rootDir);
+    if (watchers.length === 0) {
+      // Server unregistered everything - stop watching but keep instance
+      // alive so re-registration works without recreating chokidar state.
+      void this.stopChokidar();
+      return;
+    }
+    if (!this.chokidar) this.startChokidar();
+  }
+
+  private startChokidar(): void {
+    this.chokidar = chokidar.watch(this.rootDir, {
+      ignoreInitial: true,
+      followSymlinks: false,
+      // Ignore Function - Called by chokidar for each path; returning true
+      // prevents both watching and event emission. Cheaper than emitting
+      // and filtering afterward.
+      ignored: (absPath: string) => {
+        if (absPath === this.rootDir) return false;
+        const rel = path.relative(this.rootDir, absPath);
+        return this.isIgnored(rel);
+      },
+      // Atomic Writes - Many editors write-via-rename; awaitWriteFinish
+      // coalesces those into a single change event. Conservative thresholds
+      // keep latency low while still suppressing partial-write noise.
+      awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
+    });
+    this.chokidar.on("add", (p) => this.queue(p, FILE_CHANGE_CREATED));
+    this.chokidar.on("change", (p) => this.queue(p, FILE_CHANGE_CHANGED));
+    this.chokidar.on("unlink", (p) => this.queue(p, FILE_CHANGE_DELETED));
+    // ENOSPC and friends - log but don't crash the entry.
+    this.chokidar.on("error", (err) => {
+      process.stderr.write(`[pi-lsp:watcher] ${this.rootDir}: ${String(err)}\n`);
+    });
+  }
+
+  private async stopChokidar(): Promise<void> {
+    if (!this.chokidar) return;
+    const w = this.chokidar;
+    this.chokidar = null;
+    await w.close();
+  }
+
+  private queue(absPath: string, type: 1 | 2 | 3): void {
+    const rel = path.relative(this.rootDir, absPath);
+    const kind = this.matchKind(rel, absPath);
+    if (kind === 0) return;
+    // Per-Spec Filter - Skip events the server explicitly opted out of.
+    if (type === FILE_CHANGE_CREATED && !(kind & WATCH_KIND_CREATE)) return;
+    if (type === FILE_CHANGE_CHANGED && !(kind & WATCH_KIND_CHANGE)) return;
+    if (type === FILE_CHANGE_DELETED && !(kind & WATCH_KIND_DELETE)) return;
+    const uri = pathToUri(absPath);
+    // Coalesce per URI - Last event wins. The exception is Created followed
+    // by Deleted (and vice versa), which we collapse to "nothing happened"
+    // by deleting the entry; the server doesn't need to learn about a file
+    // that briefly existed.
+    const prev = this.pending.get(uri);
+    if (
+      (prev === FILE_CHANGE_CREATED && type === FILE_CHANGE_DELETED) ||
+      (prev === FILE_CHANGE_DELETED && type === FILE_CHANGE_CREATED)
+    ) {
+      this.pending.delete(uri);
+    } else {
+      this.pending.set(uri, type);
+    }
+    this.scheduleFlush();
+  }
+
+  private scheduleFlush(): void {
+    if (this.quietTimer) clearTimeout(this.quietTimer);
+    this.quietTimer = setTimeout(() => this.flush(), DEBOUNCE_QUIET_MS);
+    if (!this.maxWaitTimer) {
+      this.maxWaitTimer = setTimeout(() => this.flush(), DEBOUNCE_MAX_WAIT_MS);
+    }
+  }
+
+  private flush(): void {
+    if (this.quietTimer) clearTimeout(this.quietTimer);
+    if (this.maxWaitTimer) clearTimeout(this.maxWaitTimer);
+    this.quietTimer = null;
+    this.maxWaitTimer = null;
+    if (this.pending.size === 0) return;
+    const events: FileEvent[] = Array.from(this.pending, ([uri, type]) => ({
+      uri,
+      type,
+    }));
+    this.pending.clear();
+    try {
+      this.onEvents(events);
+    } catch (err) {
+      process.stderr.write(
+        `[pi-lsp:watcher] onEvents threw: ${(err as Error).message}\n`,
+      );
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.quietTimer) clearTimeout(this.quietTimer);
+    if (this.maxWaitTimer) clearTimeout(this.maxWaitTimer);
+    this.pending.clear();
+    await this.stopChokidar();
+  }
+}