feat: refresh file tabs and review diffs when files change on disk (#159)

## Summary

- File tabs (`FileView`) and working-tree review diffs
(`ReviewDiffPane`) now refresh automatically when the underlying file is
changed on disk — e.g. when an agent in another Harness tab edits the
file.
- Introduces a refcounted per-file `fs.watch` manager
(`FileContentWatcher`) and a `file:contentChanged` signal carried by the
shared `ServerTransport` so both Electron-IPC and WebSocket backends are
covered.
- Dirty-buffer guard: if the user has unsaved edits when the file
changes on disk, the in-flight value is preserved and a "File changed on
disk" banner appears with Reload / Keep editing actions instead of
clobbering work. Clean buffers reload silently. Binary files (image/pdf)
always refetch.

## Architecture

- `src/main/file-content-watcher.ts` — new refcounted watcher (one
`fs.watch` handle per absolute path), debounced ~150ms, handles
atomic-save `rename` events by re-arming after a short delay.
- `src/main/index.ts` — `file:watchSubscribe` / `file:watchUnsubscribe`
signals managed per-client; `file:contentChanged` rebroadcast over
`transport.sendSignal`.
- `src/renderer/hooks/useFileContentChange.ts` — thin hook around
`backend.watchFile` + `onFileContentChanged`, callback held in a ref so
subscription stays stable across parent re-renders.
- No new state slice — disk-change notifications are high-frequency
side-effect signals (same model as PTY data and the existing
`worktree:changedFilesInvalidated` signal).

## Test plan

- [x] `npm run typecheck` clean
- [x] `npx electron-vite build` clean
- [x] `npx vitest run src/main/file-content-watcher.test.ts` — 10 new
tests pass (subscribe/notify, debounce, multi-subscriber, refcount,
shutdown, missing-file resilience, atomic-save rearm)
- [ ] Manual: open a file tab, write to the file from another terminal,
confirm FileView updates within ~200ms
- [ ] Manual: make uncommitted edits in FileView, then write to the file
externally — banner appears with Reload / Keep editing; user edits
preserved until Reload
- [ ] Manual: open Review pane on a working-tree diff, edit the file
from another terminal, confirm diff refreshes (no flicker since spinner
suppressed on watcher refresh)
- [ ] Manual: save from FileView — no infinite loop (watcher fires,
content matches savedValue, no UI change)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: frenchie4111

src/main/file-content-watcher.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import fs from 'fs'
+
+import { FileContentWatcher } from './file-content-watcher'
+
+type FsCallback = (eventType: string, filename: string | null) => void
+
+interface FakeWatcher {
+  path: string
+  listener: FsCallback
+  close: ReturnType<typeof vi.fn>
+}
+
+let fakeWatchers: FakeWatcher[] = []
+
+function fireFsEvent(path: string, eventType: string): void {
+  for (const w of fakeWatchers) {
+    if (w.path === path) w.listener(eventType, null)
+  }
+}
+
+function activeWatchers(path: string): FakeWatcher[] {
+  return fakeWatchers.filter((w) => !w.close.mock.calls.length && w.path === path)
+}
+
+beforeEach(() => {
+  fakeWatchers = []
+  vi.useFakeTimers()
+  vi.spyOn(fs, 'watch').mockImplementation(((
+    path: fs.PathLike,
+    optionsOrListener?: unknown,
+    maybeListener?: unknown
+  ) => {
+    const listener = (typeof optionsOrListener === 'function'
+      ? optionsOrListener
+      : maybeListener) as FsCallback
+    const w: FakeWatcher = {
+      path: String(path),
+      listener,
+      close: vi.fn()
+    }
+    fakeWatchers.push(w)
+    return {
+      close: w.close
+    } as unknown as fs.FSWatcher
+  }) as unknown as typeof fs.watch)
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+describe('FileContentWatcher', () => {
+  it('notifies a single subscriber after debounce window elapses', () => {
+    const watcher = new FileContentWatcher()
+    const listener = vi.fn()
+    watcher.subscribe('/wt/a/file.txt', listener)
+
+    fireFsEvent('/wt/a/file.txt', 'change')
+    expect(listener).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(149)
+    expect(listener).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(1)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('coalesces multiple events within the debounce window into one notification', () => {
+    const watcher = new FileContentWatcher()
+    const listener = vi.fn()
+    watcher.subscribe('/wt/a/file.txt', listener)
+
+    fireFsEvent('/wt/a/file.txt', 'change')
+    fireFsEvent('/wt/a/file.txt', 'change')
+    fireFsEvent('/wt/a/file.txt', 'change')
+
+    vi.advanceTimersByTime(150)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('notifies every subscriber on the same path', () => {
+    const watcher = new FileContentWatcher()
+    const a = vi.fn()
+    const b = vi.fn()
+    watcher.subscribe('/wt/a/file.txt', a)
+    watcher.subscribe('/wt/a/file.txt', b)
+
+    fireFsEvent('/wt/a/file.txt', 'change')
+    vi.advanceTimersByTime(150)
+
+    expect(a).toHaveBeenCalledTimes(1)
+    expect(b).toHaveBeenCalledTimes(1)
+  })
+
+  it('reuses the underlying fs.watch handle across subscribers', () => {
+    const watcher = new FileContentWatcher()
+    watcher.subscribe('/wt/a/file.txt', vi.fn())
+    watcher.subscribe('/wt/a/file.txt', vi.fn())
+
+    expect(activeWatchers('/wt/a/file.txt')).toHaveLength(1)
+  })
+
+  it('reference-counts: unsubscribing one keeps the watcher alive for the rest', () => {
+    const watcher = new FileContentWatcher()
+    const a = vi.fn()
+    const b = vi.fn()
+    const offA = watcher.subscribe('/wt/a/file.txt', a)
+    watcher.subscribe('/wt/a/file.txt', b)
+
+    offA()
+
+    fireFsEvent('/wt/a/file.txt', 'change')
+    vi.advanceTimersByTime(150)
+
+    expect(a).not.toHaveBeenCalled()
+    expect(b).toHaveBeenCalledTimes(1)
+    expect(activeWatchers('/wt/a/file.txt')).toHaveLength(1)
+  })
+
+  it('closes the underlying fs.watch handle when the last subscriber leaves', () => {
+    const watcher = new FileContentWatcher()
+    const offA = watcher.subscribe('/wt/a/file.txt', vi.fn())
+    const offB = watcher.subscribe('/wt/a/file.txt', vi.fn())
+
+    const created = fakeWatchers.filter((w) => w.path === '/wt/a/file.txt')
+    expect(created).toHaveLength(1)
+    expect(created[0].close).not.toHaveBeenCalled()
+
+    offA()
+    expect(created[0].close).not.toHaveBeenCalled()
+
+    offB()
+    expect(created[0].close).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps subscriptions on different paths independent', () => {
+    const watcher = new FileContentWatcher()
+    const a = vi.fn()
+    const b = vi.fn()
+    watcher.subscribe('/wt/a/file.txt', a)
+    watcher.subscribe('/wt/b/file.txt', b)
+
+    fireFsEvent('/wt/a/file.txt', 'change')
+    vi.advanceTimersByTime(150)
+
+    expect(a).toHaveBeenCalledTimes(1)
+    expect(b).not.toHaveBeenCalled()
+  })
+
+  it('shutdown closes every open watcher and clears entries', () => {
+    const watcher = new FileContentWatcher()
+    watcher.subscribe('/wt/a/file.txt', vi.fn())
+    watcher.subscribe('/wt/b/file.txt', vi.fn())
+
+    const aWatcher = fakeWatchers.find((w) => w.path === '/wt/a/file.txt')!
+    const bWatcher = fakeWatchers.find((w) => w.path === '/wt/b/file.txt')!
+
+    watcher.shutdown()
+
+    expect(aWatcher.close).toHaveBeenCalledTimes(1)
+    expect(bWatcher.close).toHaveBeenCalledTimes(1)
+  })
+
+  it('survives fs.watch throwing (e.g. file missing) and produces no notifications', () => {
+    ;(fs.watch as unknown as ReturnType<typeof vi.fn>).mockImplementationOnce(() => {
+      throw new Error('ENOENT')
+    })
+
+    const watcher = new FileContentWatcher()
+    const listener = vi.fn()
+    expect(() => watcher.subscribe('/wt/missing/file.txt', listener)).not.toThrow()
+
+    vi.advanceTimersByTime(500)
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('re-arms the watcher after a rename event (atomic save)', () => {
+    const watcher = new FileContentWatcher()
+    const listener = vi.fn()
+    watcher.subscribe('/wt/a/file.txt', listener)
+
+    expect(activeWatchers('/wt/a/file.txt')).toHaveLength(1)
+    const original = fakeWatchers.find((w) => w.path === '/wt/a/file.txt')!
+
+    // Atomic-save: editor renames-over the inode. fs.watch fires 'rename'.
+    fireFsEvent('/wt/a/file.txt', 'rename')
+
+    // Debounced notify fires for the rename event itself.
+    vi.advanceTimersByTime(150)
+    expect(listener).toHaveBeenCalledTimes(1)
+
+    // After the rearm delay the original watcher is closed and a fresh
+    // one is opened against the same path.
+    vi.advanceTimersByTime(50)
+    expect(original.close).toHaveBeenCalledTimes(1)
+    expect(activeWatchers('/wt/a/file.txt')).toHaveLength(1)
+
+    // Subsequent change on the re-armed watcher still notifies.
+    fireFsEvent('/wt/a/file.txt', 'change')
+    vi.advanceTimersByTime(150)
+    expect(listener).toHaveBeenCalledTimes(2)
+  })
+})

src/main/file-content-watcher.ts

@@ -0,0 +1,143 @@
+// Reference-counted fs.watch manager for per-file content notifications.
+// Mirrors WorktreeWatcher's structure but watches a single absolute file
+// path per entry instead of the worktree's .git/ directory. Used by the
+// file:watchSubscribe IPC so FileView / ReviewDiffPane can refresh when an
+// agent in another tab (or any external tool) edits the file on disk.
+//
+// Atomic-save robustness: many editors (Vim, IntelliJ, some Claude-Code
+// edit flows) replace the file's inode on save. fs.watch loses the
+// underlying handle on rename; we detect that via the 'rename' event and
+// re-arm by re-opening fs.watch after a small delay, retrying once if
+// the file is briefly missing. If the file is gone after the retry we
+// give up — subscribers stay registered but get no notifications until
+// the file reappears via a fresh subscribe.
+//
+// If the very first fs.watch open fails (file missing, EPERM, etc.), the
+// entry is created without a watcher and listeners never fire. This is
+// intentional and matches WorktreeWatcher — the watcher is best-effort
+// and the renderer has its own ways to refresh as a fallback.
+//
+// Notifications are debounced ~150ms (slightly tighter than the worktree
+// watcher's 200ms) to coalesce editor multi-write saves.
+
+import fs, { type FSWatcher } from 'fs'
+
+const DEBOUNCE_MS = 150
+const REARM_DELAY_MS = 50
+
+export type FileContentChangeListener = () => void
+
+interface Entry {
+  listeners: Set<FileContentChangeListener>
+  watcher: FSWatcher | null
+  debounceTimer: NodeJS.Timeout | null
+  rearmTimer: NodeJS.Timeout | null
+}
+
+export class FileContentWatcher {
+  private readonly entries = new Map<string, Entry>()
+
+  subscribe(absolutePath: string, listener: FileContentChangeListener): () => void {
+    let entry = this.entries.get(absolutePath)
+    if (!entry) {
+      entry = {
+        listeners: new Set(),
+        watcher: null,
+        debounceTimer: null,
+        rearmTimer: null
+      }
+      this.entries.set(absolutePath, entry)
+      entry.watcher = this.openWatcher(absolutePath)
+    }
+    entry.listeners.add(listener)
+    return () => this.unsubscribe(absolutePath, listener)
+  }
+
+  shutdown(): void {
+    for (const [path, entry] of this.entries) {
+      this.teardownEntry(entry)
+      this.entries.delete(path)
+    }
+  }
+
+  private unsubscribe(absolutePath: string, listener: FileContentChangeListener): void {
+    const entry = this.entries.get(absolutePath)
+    if (!entry) return
+    entry.listeners.delete(listener)
+    if (entry.listeners.size === 0) {
+      this.teardownEntry(entry)
+      this.entries.delete(absolutePath)
+    }
+  }
+
+  private teardownEntry(entry: Entry): void {
+    if (entry.debounceTimer) {
+      clearTimeout(entry.debounceTimer)
+      entry.debounceTimer = null
+    }
+    if (entry.rearmTimer) {
+      clearTimeout(entry.rearmTimer)
+      entry.rearmTimer = null
+    }
+    if (entry.watcher) {
+      try {
+        entry.watcher.close()
+      } catch {
+        // already closed, ignore
+      }
+      entry.watcher = null
+    }
+  }
+
+  private openWatcher(absolutePath: string): FSWatcher | null {
+    const onEvent = (eventType: string): void => {
+      this.scheduleNotify(absolutePath)
+      if (eventType === 'rename') {
+        this.scheduleRearm(absolutePath)
+      }
+    }
+    try {
+      return fs.watch(absolutePath, { persistent: false }, onEvent)
+    } catch {
+      return null
+    }
+  }
+
+  private scheduleNotify(absolutePath: string): void {
+    const entry = this.entries.get(absolutePath)
+    if (!entry) return
+    if (entry.debounceTimer) return
+    entry.debounceTimer = setTimeout(() => {
+      const current = this.entries.get(absolutePath)
+      if (!current) return
+      current.debounceTimer = null
+      for (const listener of current.listeners) {
+        try {
+          listener()
+        } catch {
+          // listener errors must not break sibling listeners
+        }
+      }
+    }, DEBOUNCE_MS)
+  }
+
+  private scheduleRearm(absolutePath: string): void {
+    const entry = this.entries.get(absolutePath)
+    if (!entry) return
+    if (entry.rearmTimer) return
+    entry.rearmTimer = setTimeout(() => {
+      const current = this.entries.get(absolutePath)
+      if (!current) return
+      current.rearmTimer = null
+      if (current.watcher) {
+        try {
+          current.watcher.close()
+        } catch {
+          // ignore
+        }
+        current.watcher = null
+      }
+      current.watcher = this.openWatcher(absolutePath)
+    }, REARM_DELAY_MS)
+  }
+}