fix: write workspace SSH hosts to a shared glob include that ssh reads first

[EhabY]

Fixes SSH config precedence without letting VS Code-based editors overwrite one another's generated Coder hosts.

Approach

Shared SSH config directory

Each editor writes one generated file per deployment into a directory shared by all editors under the platform data dir ($XDG_DATA_HOME, ~/Library/Application Support, %APPDATA%):

~/.local/share/coder.coder-remote/ssh/vscode--dev.coder.com.conf
~/.local/share/coder.coder-remote/ssh/cursor--dev.coder.com.conf

The user's SSH config gets a single editor-agnostic block, placed first because OpenSSH uses the first value it finds:

# --- START CODER ---
# Moves back to the top on connect; override options via coder.sshConfig.
Include "~/.local/share/coder.coder-remote/ssh/*.conf"
# --- END CODER ---

On connect, the extension:

1. fully regenerates the current (editor, deployment) file, so its mtime marks the last connect;
2. adds or moves the shared Include block to the top of the effective user config;
3. removes the released direct block for that deployment from the effective user config;
4. sweeps *.conf files (from any editor) not connected to for a week; the next connect recreates them.

Correctness without locking: each generated file has a single writer, and concurrent writers of the same file produce equivalent content, so last-writer-wins is correct. The Include block is byte-identical from every editor, so once placed the user's config stops changing and concurrent editors converge instead of racing. Host patterns are namespaced per editor and deployment, so glob ordering between the files is irrelevant.

Other deployments' direct blocks and the deployment-unaware historical block are preserved; hosts matching the historical coder-vscode--* pattern parse as foreign, so their windows keep connecting through the preserved block instead of failing setup.

Since first-line placement now guarantees the managed options apply, the post-write check that recomputed them and aborted the connection with "Unexpected SSH Config Option" on a mismatch (typically from a catch-all Host *) is removed. Validation of deployment-sent options (the deny list) is unchanged.

Generated files carry a do-not-edit header, since they are rewritten on every connection. A new Coder: Open Generated SSH Configuration File command opens them read-only: a connected window opens its own deployment's file, a local window offers a deployment picker.

Include paths inside $HOME are emitted as ~/..., so quirks in the home path (spaces, %, glob characters) never reach the argument ssh reads. Paths outside $HOME are quoted with Windows separators normalized and glob characters escaped; CR, LF, NUL, ", and % are rejected because ssh cannot read them back (OpenSSH 9.9+ percent-expands Include arguments and exits fatally on unknown tokens).

Which file gains the include

Microsoft's and Cursor's Remote-SSH pass remote.SSH.configFile to ssh with -F, and VSCodium's fork parses that file in-process, so the setting is honored there. Antigravity and Windsurf/Devin renamed the setting but spawn ssh without -F, so ssh always reads ~/.ssh/config; on those two the setting (or a stale synced remote.SSH.configFile) is ignored rather than writing the include where the connection never looks.

Editor-specific authorities

The SSH host prefix uses vscode.env.uriScheme unchanged — coder-vscode, coder-cursor, coder-windsurf, coder-vscode-insiders — and the generated wildcard host and CLI --ssh-host-prefix use the same prefix.

Legacy authority migration

Only the actual historical coder-vscode authority is migrated in other editors; foreign coder-* authorities are ignored rather than retargeted.

Important

Migration reopens the window automatically. Connecting to a legacy authority in another editor retargets it and reopens the same folder or saved workspace once, preserving the full URI (scheme, path, query, and fragment). Empty windows reopen with the retargeted authority.

An untitled multi-root workspace cannot be reopened without dropping folders, so it keeps connecting through the old host and a modal explains how to finish the switch (save the workspace, then reload). Recent-folder entries with legacy authorities stay compatible when reopening a workspace. Plain, URI-wrapped, and nested ssh-remote+ authorities retain their surrounding wrappers when retargeted.

Concurrent config changes

All writes are atomic temp-file renames with retries for transient Windows errors, following the CLI config-ssh shape: read, merge, skip when unchanged, write. No locks or optimistic retries; every editor writes an identical Include block, so concurrent updates converge, and a lost update stays shadowed by the include (first value wins) until the next connect rewrites it.

Compatibility

• New integration tests run the real ssh -G against generated configs: a quoted glob include in a path with spaces wins over a later Host *, escaped glob characters in the directory name resolve, two deployments and two editors are served through one glob include, and deleting the generated directory degrades gracefully instead of breaking ssh.
• Verified against the jeanp413/open-remote-ssh source (VSCodium's Remote-SSH): it parses the config in-process via ssh-config, follows top-level quoted Includes (untildify + glob), and implements first-value-wins, on both current and years-old releases.
• Verified against PowerShell/openssh-portable source and release history: every in-box Windows ssh.exe resolves Include arguments through glob(3) (wildcard or not) since the first bundled 7.7p1, 8.1p1+ (Windows 10 2004+) also honors quoted forward-slash absolute paths, and a missing include directory is a non-fatal "matched no files".

Diff size

Relative to main (15d4c8f2):

Area	Added	Removed	Net
Production (src/)	507	295	+212
Tests (test/)	1,163	1,146	+17
Docs and manifest	75	13	+62

Validation

• pnpm test: 2,374 passed, 1 skipped (includes the real-OpenSSH tests, skipped where ssh is absent)
• pnpm typecheck
• pnpm lint
• pnpm format:check
• pnpm build
• git diff --check

Implementation plan and decisions

• Use vscode.env.uriScheme unchanged and require a non-empty editor ID where it is consumed.
• Generate one config per (editor, deployment) in a shared platform data dir; the filename carries the editor and deployment, and the user's config includes the directory with a glob.
• Use START|END CODER <hostname> markers in generated files and one parameterless START|END CODER include block in the user's config. Legacy CODER VSCODE <hostname> markers are still matched for user-config cleanup.
• Emit home-relative include paths with a tilde; reject characters ssh cannot read back rather than half-escape them.
• Migrate only coder-vscode, preserving wrappers and complete URI/workspace state; parse deployment-unaware coder-vscode--* hosts as foreign.
• Keep an unsaved untitled multi-root workspace on the old host with an explanatory modal rather than dropping folders or failing setup.
• Preserve other deployments' direct blocks for lazy migration; sweep generated files unused for a week (connects always rewrite, so mtime marks the last connect).
• Ignore the renamed config-file setting on editors whose ssh never reads it; keep honoring remote.SSH.configFile where ssh (or an in-process parser) does.
• Keep the Node typeof-based filesystem interface; tests mock node:fs/promises with memfs instead of hand-rolled fixtures.
• Open the generated file read-only from the new command, since the extension rewrites it on every connection.
• Match the CLI's read-merge-write on the user's config instead of a lock or optimistic retries; generated files are single-writer last-write-wins.

Generated by Coder Agents for @EhabY.

[code-asher]

Nice, I like how minimal the edits are to my main config now. One comment on the path for our config.

[code-asher]

I think this is the right direction! The main concern I have is if we should use a different file structure to account for concurrency, or just not worry about concurrency at all.

Also I have not been able to test it yet because every time I build I get a timeout for one of the dependencies. Not sure why pnpm insists on downloading every time I build...

[linear-code]

DEVEX-728

[code-asher]

I think we have to still do remote setup in this case rather than aborting.

Because currently in this case we skip the remote setup, which may mean the connection will fail (for example if the SSH config needs to be regenerated), and now there will be no way to save the workspace file since it requires being connected.

[EhabY]

Oooh good catch, I made it continue using the legacy authority which means it might fight with the VS Code one (though unlikely and this is better than breaking). This is also self-healing so the next run without an untitled workspace should migrate it!

[code-asher]

IMO we should not do this; IDE sessions can be long lived (leaving editors open for weeks, the only interruption being putting the machine to sleep).

If we need to clean up, we could have the plugin periodically touch the file or something like that. But I feel like the number of deployment/IDE combinations will be so small it is probably not worth the effort.

We were not previously cleaning them up either, maybe we can revisit if we end up needing this?

[EhabY]

Fair enough, I've removed this. Though tbh having something that deletes every month for example should be safe. Like on the next reconnect it's recreated, so the only issue is if we do not reconnect BUT the SSH itself reconnects.

[code-asher]

I think we need a more unique prefix because JetBrains may end up doing something similar and having its own wildcard includes.

Maybe we can still use VSCODE? Kinda unfortunate though because it implies just the main VS Code IDE.

CODER CODE-OSS maybe? To indicate anything based off the Code OSS? CODER VSCODE FAMILY perhaps? CODER.CODER-REMOTE?

Also...if we do this with JetBrains (and maybe one day the cli) they will fight over who gets to be at the top which seems unfortunate. Still wondering if we should leave it in place if it already exists in the file.

Or...not sure how sketchy this is but we could share a directory with all the plugins and the cli. Put it in $data/coderv2/ssh for example. Or sub-directories for each plugin, and include with */*.conf.

[EhabY]

I've went with CODER.CODER-REMOTE since this is the extension ID so it seems like a natural fit + I added a comment explaining this.

Regarding the include fight, how about we just ignore CODER include blocks at the top? Of course, every IDE has to follow through but that's always gonna be the case. In fact, I've just changed the block to START CODER INCLUDE CODER-REMOTE, Jetbrains can do START CODER INCLUDE JETBRAINS, etc...
I have not implemented the ignore logic here though since we do not have another client yet. wdyt?

[code-asher]

Oo nice I like the idea, seems better compared to splitting on +.

Just a thought but it could maybe be more stable to pass in the host by parsing the URL via new URL(authority).host or URI.parse or something so we avoid having to sort of jankily handle @ and ://.

[EhabY]

I gave it a shot, but two of the three shapes we receive are not URLs: the bare ssh-remote+host form has no scheme, and in nested remotes like dev-container+abc@ssh-remote+host the @ is VS Code authority nesting, not userinfo. new URL (and URI.parse) throws on those, so we'd keep the same string handling anyway.

Where it does parse, new URL also lowercases the host, which would mangle case-sensitive usernames and workspace names (those currently are all lowercase but yeah).