fix(desktop): skip file watcher on $HOME and filesystem root

[vzwjustin]

Desktop could persist and boot instances for the entire home directory or /, causing inotify subscribe timeouts and pegging opencode-cli CPU. Skip watching broad roots, sanitize persisted project lists, and add a Flatpak workaround script plus troubleshooting guide.

Issue for this PR
Closes # (no linked issue — reproduced locally on Flatpak 1.4 / Linux)

Type of change

Bug fix

New feature

Refactor / code improvement

Documentation
What does this PR do?
On Linux desktop, OpenCode could end up with an instance rooted at $HOME or / (persisted in server.projects and recreated workspace state). The sidecar then subscribed inotify on that tree, hit subscribe timeouts, and retried in a loop — opencode-cli sat at ~100% CPU.

This PR:

Core — adds isBroadWatchRoot() and skips the file watcher when the instance directory is $HOME or / (still watches normal project dirs).
App — on load, strips home/root from persisted desktop project lists; projects.open() refuses those paths so they are not re-added from the UI.
Docs/script — docs/guides/desktop-file-watcher-cpu.md and scripts/opencode-safe.sh for Flatpak users who cannot run a fixed build yet.
Why it works: the CPU peg was not random load — logs showed repeated service=file.watcher dir=/home/... cause=TimeoutError. Stopping watches on those two broad roots removes the failure mode; project-scoped dirs are unchanged.

How did you verify your code works?
Added unit tests: packages/core/test/filesystem/watch-root.test.ts, extended packages/app/src/context/server.test.ts for sanitize/open behavior.
Reproduced the bug on Flatpak desktop (logs showing dir=$HOME, high opencode-cli CPU), then confirmed the client workaround (opencode-safe + flatpak HOME override) scopes the watcher to a single repo.
(Maintainers: bun test on the two test files above — bun was not available in the agent environment that opened this PR.)
Screenshots / recordings
N/A — backend/desktop sidecar behavior, no UI layout change.

Checklist

I have tested my changes locally

I have not included unrelated changes in this PR

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[github-actions]

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

• PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Found a potentially related PR:

PR #30209: fix(opencode): skip watching $HOME to avoid slow FSEvents exclusion setup
#30209

This PR appears to address a similar issue—skipping the $HOME directory to avoid slow file watcher setup. The current PR (32610) extends this concept to also skip the filesystem root. You should verify if PR #30209 was already merged and whether the current PR builds upon it or duplicates its solution.

[github-actions]

This pull request has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new pull request that follows our guidelines.