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
Increases server read traffic for open file previews (no long-lived read cache) and adds per-subscriber filesystem watchers; behavior is scoped to mounted file queries with zero idle TTL.

Overview
Workspace file previews now stay in sync with disk when files change outside T3 Code (editor saves, git, etc.), instead of serving long-lived cached reads.

Server: Adds WorkspaceFileSystem.watchFile — debounced native directory watches with workspace-root safety checks and symlink-aware paths — and exposes it as the streaming RPC projects.watchFile.

Client runtime: readFile query atoms are wired to refreshQueryOnSuccess, which re-fetches file contents when the watch stream signals a change. File reads use zero stale/idle TTL so mounted previews always revalidate; watch subscriptions dispose when nothing is subscribed.

Web/mobile: Skips file queries when no path is selected; mobile preload uses a 1s idle TTL on read atoms so preloads survive handoff to the preview consumer.

^{Reviewed by Cursor Bugbot for commit a27510d. 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 a27510d.}

[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: c7aef252-5e7c-4e51-b60c-df95a7121470

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.}