fix(client): refresh workspace files after disk changes

[PixPMusic]

Summary

• revalidate cached workspace files whenever a preview opens
• subscribe mounted file queries to debounced native filesystem change events instead of polling contents
• dispose file queries and watchers when no preview is mounted
• skip file queries entirely when no web preview path is selected

Verification

• vp test run apps/server/src/workspace/WorkspaceFileSystem.test.ts packages/client-runtime/src/state/runtime.test.ts apps/web/src/components/files/projectFilesQueryState.test.ts
• targeted contracts, server, client-runtime, web, and mobile typechecks
• targeted formatting and lint checks
• isolated web and iOS verification covering external edits while open and unmount → disk edit → remount

---

Note

Medium Risk
New per-open-file WebSocket subscriptions and fs watchers increase server/client load; read caching behavior changes (more refetch on mount) but auth and path-safety rules match existing read paths.

Overview
Workspace file previews now stay in sync when files change on disk outside the app, using native filesystem watches instead of long-lived cached reads.

Server & RPC: Adds a streaming projects.watchFile RPC (orchestration read scope) backed by WorkspaceFileSystem.watchFile, which debounces directory watches, handles missing files and in-workspace symlink targets, and keeps the same workspace-root escape checks as reads.

Client state: Introduces refreshQueryOnSuccess so a projectsReadFile query re-fetches whenever the matching projectsWatchFile subscription emits a success. readFile atoms use zero stale/idle TTL so watchers and queries drop when nothing is mounted; mobile preload applies a 1s idle TTL so preloaded reads still hand off cleanly to the live query.

UI: useProjectFileQuery no longer subscribes when relativePath is null, even if the hook is enabled.

^{Reviewed by Cursor Bugbot for commit 06025a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add projects.watchFile streaming RPC to auto-refresh workspace file queries on disk changes

• Adds a watchFile method to WorkspaceFileSystem that emits debounced ProjectFileChangeEvent stream entries when a workspace-relative file changes, including symlink target changes; rejects paths that escape the workspace root.
• Exposes this as a streaming projects.watchFile WebSocket RPC (with orchestration read scope required) via ws.ts and the updated contracts in rpc.ts.
• Introduces refreshQueryOnSuccess in runtime.ts — a helper that wraps a query atom with a signal atom so the query auto-refreshes on each success event from the subscription.
• Wires readFile queries in projectCommands.ts to revalidate on mount and refresh automatically when the projects.watchFile subscription fires, replacing the previous static query atom family.
• Risk: readFile queries now have zero idle TTL and stale time, meaning they are evicted immediately when idle; the preload path compensates with a 1s WORKSPACE_FILE_PRELOAD_RETAIN_MS idle TTL.

^{Macroscope summarized 06025a7.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 775be6df-ecfd-4a1b-a83a-24208af92087

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new file watching feature with a streaming RPC endpoint, new server-side watch logic including symlink and security handling, and new client-side state management patterns. Despite the "fix" title, this is a new capability spanning multiple layers that warrants human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 394b9a9. Configure here.}