Revisit "dir breaks Coder Desktop file sync" warning after Mutagen fix ships

[aqandrew]

Summary

Once the Coder Desktop file sync fix ships and is adopted, the coder_agent.dir warning about breaking file sync is no longer accurate and should be revisited (likely removed), coordinated with the existing dir deprecation.

Background

Setting coder_agent.dir (or a devcontainer workspaceFolder) to a path other than $HOME breaks Coder Desktop file sync. Root cause: Mutagen copies its agent binary with scp and executes it over ssh using a ~/-prefixed path; when the remote SSH/SFTP working directory isn't $HOME, scp writes the binary relative to that directory while the ssh exec expands ~ to $HOME, so installation fails.

Tracking:

• File sync fails when coder_agent.dir is set to a non-home directory coder-desktop-macos#238 (coder_agent.dir variant)
• Linear DEVEX-522 (devcontainer workspaceFolder variant)

A fix is proposed in the Mutagen fork: coder/mutagen#10 — resolve the absolute remote home directory once and use an absolute path for both the copy and the exec, so they agree regardless of the remote working directory. This addresses both the dir and devcontainer variants.

Where the warning lives

• provider/helpers/validation.go — WarnDirNotHome (the plan/apply-time warning):
  Setting "dir" to a value other than $HOME will break Coder Desktop file sync.
• provider/agent.go — the dir field Description links the same phrasing to the docs.
• docs/resources/agent.md — generated from the schema description.

Why not now

• fix(agent): install agent using an absolute remote path mutagen#10 is still a draft; nothing is released. The fix must land, be released, and be bundled into the desktop clients (.mutagenversion bump in both macOS and Windows) before the warning is stale.
• Version skew: this warning fires at template plan/apply time and cannot know which Coder Desktop / Mutagen version end users run. Removing it before broad adoption would regress users on older clients whose file sync is still broken.
• dir is separately deprecated (IDEs / display_apps reasons). That deprecation stands regardless of the file-sync fix, so the warning/field will likely be retired via the deprecation cleanup rather than reverted here.

Proposed action (revisit when ready)

1. Confirm fix(agent): install agent using an absolute remote path mutagen#10 is merged, released, and bundled into the macOS and Windows Coder Desktop clients, and that both the dir and devcontainer variants are verified fixed.
2. Decide a min-version / adoption-window gate before changing user-facing guidance.
3. Update or remove the "breaks Coder Desktop file sync" wording in WarnDirNotHome and the agent.go dir description (regenerate docs/resources/agent.md), coordinated with the dir deprecation plan.
4. Update related docs references (e.g. coder/coder docs/user-guides/desktop/desktop-connect-sync.md).

Acceptance

• The "breaks Coder Desktop file sync" claim is no longer surfaced once the fix is broadly available, without regressing users on pre-fix clients.

---

_{🤖 Opened by Coder Agents on behalf of @aqandrew.}

[linear-code]

ENG-3307