GeezerVison

P3 A template version mismatch drops agent entries without a warning.

This compares against the template version of the latest build, not the template's active version. If an update fails (the latest build is a failed start on the new version), the workspace's agent entries disappear on the next run and nothing is printed, while a fetch error does print a warning. Is the silence intended? Returning a sentinel error that the caller reports with the existing Skipping agent host entries warning would make the missing entries explainable.

The docs sentence at index.md:118 has the same ambiguity. See the comment there.

Nit ws-delta and ws-gamma also sort after ws-beta by name, so this list can't tell running-first ordering apart from name ordering. Either drop the clause, or name a stopped workspace so it sorts first (for example ws-aaa) if the ordering matters.

P3 Entries for agents with uppercase names are written but can't connect.

provisioner.AgentNameRegex is case-insensitive, so Dev is a valid agent name, and this regex accepts it. OpenSSH lowercases the destination it hands to the ProxyCommand: with OpenSSH 10.2, ssh -G Main.ws.alice.coder against a Host Main.ws.alice.coder block reports hostname main.ws.alice.coder, which is what %h expands to. coder ssh then looks up main, and getWorkspaceAgent (cli/ssh.go:1181) compares names exactly, so it fails with agent not found by name "main".

Wildcard mode already has this bug, but this PR now writes these hosts into the config, where tools like Gateway list them. strings.EqualFold in getWorkspaceAgent would fix both modes. Skipping names that aren't lowercase here would also work.

Optional: this tip says the command writes entries for each agent, but nothing in this PR shows what an agent host looks like, so readers can't tell what to type or look for in a host list. #31188, which is stacked on this PR, adds the format to this section. If the two might merge far apart, consider adding it here:

P3 Entries for devcontainer sub-agents created at runtime go stale when the workspace stops.

The agent deletes the sub-agents it injected when it shuts down (agent/agentcontainers/api.go:2208), and GetWorkspaceAgentsByResourceIDs filters deleted agents out. The entry stays in ~/.ssh/config until the next config-ssh run. ssh to it starts the workspace and then fails with agent not found, because GetWorkspaceAndAgent looks up the agent as soon as the build finishes, before the sub-agent registers again. Running config-ssh while the workspace is stopped removes these entries, so host lists in Gateway and VS Code change with workspace state.

The autostart race isn't new to this PR, so accepting it is reasonable. Could the docs at least say that sub-agent entries only appear while the workspace is running?

P2 Each history lookup loads up to 20 full builds, and there's no page cap.

GET /workspaces/{id}/builds returns every build on the page fully loaded: job with queue position, resources, agents, apps, app statuses, scripts and log sources (workspaceBuilds calls workspaceBuildsData with wsrelated.AllLatestBuild()). This runs on every config-ssh --no-wildcard for every workspace whose latest build has no agents.

• Common case: the latest build is a stop and the answer is build N-1, so 19 of the 20 builds are thrown away on every run.
• Worst case: failed and canceled builds are skipped before the version check, so a workspace with a long streak of failed autostarts, or one that never started successfully, pages through its whole history one sequential request per 20 builds.

Giving up already falls back to the workspace entry, so could this ask for a small page (say 5) and stop after a few pages? Fetching build N-1 directly with WorkspaceBuildByUsernameAndWorkspaceNameAndBuildNumber, and paging only on a miss, would also work.

Nit Go doc comments usually start with the identifier. This one also implies the regex excludes --, but that check lives in startAgentNames.

Nit The guarantee covers agent entries only. ws.Name is appended at line 1030, before the NameValid check, so the workspace entry is still written as returned. That predates this PR, but this comment reads as covering every name.

P3 Two cheap coverage gaps:

• No row has an invalid owner name, so removing codersdk.NameValid(ws.OwnerName) from the guard wouldn't fail any test. The workspace helper hardcodes OwnerName: "alice", so one row that overrides it (for example "bad owner") would pin that check.
• Nothing calls workspaceAgentResources directly, so the Skipping agent host entries warning is untested. A small httptest server that fails one workspace's history, plus assertions on the warning and the bare entry, would cover it.

This paragraph sits outside the tip and never says it applies only to --no-wildcard, so someone who ran plain coder config-ssh will read it as applying to them. "The workspace's current template version" also reads as the template's active version, but the code compares against the version of the workspace's latest build (configssh.go:1116).