Agent Sessions: make Additional SSH hosts visibly editable and improve remote diagnostics
P2clawsweeper:no-new-fix-prclawsweeper:needs-maintainer-reviewclawsweeper:needs-product-decisionissue-rating: 🦞 diamond lobsterclawsweeper:source-reproimpact:ux-friction
## Summary
The **Settings → Menu → Agent sessions → Additional SSH hosts** row does not present a visible editing affordance in the grouped macOS form. It renders like a static label rather than an editable setting: there is no visible field boundary, placeholder, example, or add action.
This report is based on the public implementation and intentionally contains no user configuration or environment details.
## Current implementation
```swift
TextField(L("agent_sessions_hosts_title"), text: self.$settings.agentSessionsManualHosts)
.disabled(!self.settings.agentSessionsEnabled)
```
In this form layout, the localized title is visible while the empty editing area is not visually discoverable. A user can reasonably interpret the row as inert text.
The public documentation describes the value as a comma-separated list of SSH destinations such as `user@host`, but the settings UI does not expose that format or the remote prerequisites in context.
## Expected UI
At minimum, render an explicit labeled editor:
```swift
LabeledContent(L("agent_sessions_hosts_title")) {
TextField("user@host, user@host", text: self.$settings.agentSessionsManualHosts)
.labelsHidden()
.textFieldStyle(.roundedBorder)
.frame(minWidth: 240)
}
.disabled(!self.settings.agentSessionsEnabled)
```
A structured editor would be clearer than a comma-separated string:
- one row per SSH destination;
- visible **Add** and **Remove** controls;
- separate host/SSH-user fields, or a clearly labeled `user@host` field;
- optional port/SSH-alias support through normal SSH configuration;
- a **Test Connection** action;
- inline status and a useful accessibility label/help description.
## Remote diagnostic UX
The menu currently reduces remote failures to broad states such as `unreachable` or a generic timeout. The app should preserve privacy while distinguishing actionable failure classes:
- peer offline or hostname resolution failure;
- TCP/SSH connection timeout;
- SSH authorization rejected;
- interactive authentication required despite batch mode;
- remote `codexbar` missing from the non-interactive `PATH`;
- incompatible remote CLI/protocol;
- remote session scan failure.
The UI need not expose raw command output. A sanitized, categorized message plus a troubleshooting disclosure would be sufficient.
The settings section should also explain the remote contract in generic terms: remote hosts require non-interactive SSH and a compatible CodexBar CLI available to the remote shell.
## Acceptance criteria
- The empty Additional SSH hosts control is visibly editable in light and dark appearances.
- The accepted input format is shown in the UI.
- Keyboard focus and VoiceOver identify the control as editable.
- Users can test a configured destination without waiting for periodic refresh.
- Common remote failures have distinct, sanitized guidance.
- Tests cover empty/non-empty layout, disabled state, keyboard/accessibility behavior, and representative error classification.
- Relevant localized strings and user documentation are updated.
## Scope
This issue concerns remote-session setup and diagnostic usability. Destructive session lifecycle actions, such as stopping or terminating an agent process, should be designed and reviewed separately.
2 条评论