Auto-refresh the active tab's panels (silent, non-disturbing)

Local panels are fs.watched (LocalDirWatcher + setWatchedDirs -> pathRefresh);
remote panels poll every 3s. New refresh({silent}) skips the loading/busy
flags and touches no DOM, snapshotting sessionId+cwd to discard results if the
user navigated mid-flight. Only the active tab is live; switching tabs
refreshes the new pair. A future on/off setting is left as commented
breadcrumbs. Docs updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/architecture.md

@@ -114,6 +114,12 @@ would float over editor windows).
   callback. mtime seconds→ms; mode masked `& 0o7777`.
 - `fs/registry.ts` — sessionId → provider map; `"local"` is built-in;
   `add()` mints `sftp-<n>`; `drop()` (session died) vs `remove()` (clean).
+- `fs/watcher.ts` — `LocalDirWatcher`: `fs.watch` handles keyed by dir,
+  debounced ~150 ms (watch fires bursts). Drives local auto-refresh: the main
+  webview sends `setWatchedDirs` (the active tab's local panel cwds); a change
+  fires `onChange` → `rpc.send.pathRefresh({sessionId:"local", dir})`.
+  `onChange` is late-bound in index.ts (the `events` pattern). SFTP has no
+  watch, so remote panels are polled UI-side instead (see panels.service).
 - `transfers/engine.ts` — FIFO job queue. `Semaphore` with live resize
   (`wake()` reserves slots synchronously — an async waiter increment was a
   race). Per-job worker pool (`MAX_WORKERS_PER_JOB=8`) draws from the shared
@@ -172,7 +178,15 @@ would float over editor windows).
   auto-load `localDir` into an untouched local panel). `connectToken`
   supersedes stale connects. `Workspace` = tab = left/right pair + activeSide.
   Remote goes RIGHT on connect/open-stack (commander convention); per-panel
-  dropdown connects target their own panel.
+  dropdown connects target their own panel. **Auto-refresh** (always on):
+  `refresh({silent})` re-lists without the loading/busy flags and touches no
+  DOM (scroll/cursor/selection/filter preserved), snapshotting sessionId+cwd
+  to discard results if the user navigated mid-flight. Only the active tab is
+  live: its local panels are fs.watched (backend `setWatchedDirs` effect +
+  `pathRefresh` push → silent refresh), its remote panels polled every 3s
+  (`REMOTE_POLL_MS`); switching tabs silently refreshes the newly-active pair.
+  A future on/off setting is stubbed in commented breadcrumbs (types.ts,
+  settings.service, tab-bar).
 - `transfers.service.ts` — jobMap from `transferUpdate` callbacks; EMA speed
   (`SPEED_SMOOTHING=0.7`); `copyToOtherPanel` guards same-fs+same-dir before
   enqueue and runs the collision flow (same-path auto-skip, type-mismatch

docs/gotchas.md

@@ -85,6 +85,12 @@ touching the adjacent code.
   don't shrink the 400 ms debounce.
 - `panel.touched` gates localDir auto-navigation; `connectToken` guards
   against a slow connect resolving into a panel the user already reused.
+- **Silent auto-refresh must snapshot sessionId+cwd and discard a mismatched
+  result.** A normal `refresh()` is masked by `busy` (input blocked), but the
+  silent variant (poll/watch) runs while the user can navigate — without the
+  guard, a poll that started in dir A resolves and stamps A's listing over the
+  dir B the user just opened. It also never calls `scrollCursorIntoView`
+  (scroll must stay put) and returns early if `busy()` or already refreshing.
 
 ## Build / tooling