Agent Sessions: make Additional SSH hosts visibly editable and improve remote diagnostics

[akshayprabhu200]

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

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:

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.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 12, 2026, 11:06 AM ET / 15:06 UTC.

Summary
Keep open: the editor-discoverability portion shipped via #2806, but connection testing and a privacy-safe SSH diagnostic taxonomy remain unapproved feature work. Likely related people: Peter Steinberger (high), Akshay Prabhu (high), and Will Sarg (medium).

Reproducibility: yes. for the former editor defect: current source proves the visible editor repair now exists. The remaining request is source-reproducible as a missing typed diagnostic/test feature, but no live remote setup was supplied or run.

Root-cause cluster
Relationship: canonical
Canonical: #2804
Summary: This issue remains the canonical record for the unapproved remote-test and diagnostic work; the merged PR resolved only its editor-discoverability subset.

Members:

• partial_overlap: fix: make additional SSH hosts visibly editable #2806 - It shipped the visible host editor, input hint, accessibility label, and tests while intentionally excluding connection testing and richer diagnostics.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Maintainer decision needed

Question	Recommendation
Should CodexBar add an on-demand SSH connection test and which sanitized remote failure categories may be shown in the settings or menu?	Approve a bounded diagnostic phase: Add a manual test action and a small, sanitized error enum covering reachability, authentication, interactive-auth, missing CLI, and protocol/scan failures.

Why: This chooses new network behavior and the privacy boundary for exposing SSH failure information; source evidence cannot safely determine the intended user-facing contract.

Next step
The remaining work is product and privacy direction, not a safe autonomous repair; the narrow editor fix has already merged and shipped.

Review details

Best possible solution:

Keep the released editor repair, then implement a separately approved typed diagnostic model with sanitized guidance and a clearly scoped on-demand test action, plus focused fetcher and settings/menu coverage.

Do we have a high-confidence way to reproduce the issue?

Yes for the former editor defect: current source proves the visible editor repair now exists. The remaining request is source-reproducible as a missing typed diagnostic/test feature, but no live remote setup was supplied or run.

Is this the best way to solve the issue?

Unclear for the full issue: the merged editor change is the narrowest repair for discoverability, while the remaining test and diagnostics need an approved privacy and product boundary before implementation.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A connection-test control and richer error detail add explicit network activity and could expose remote host or authentication information unless the diagnostic vocabulary and redaction boundary are approved first.

Codex review notes: model internal, reasoning high; reviewed against c4ed34d0e44a.

Label changes

Label justifications:

• P2: Remote-session setup remains usable but lacks approved diagnostics and an immediate validation path.
• impact:ux-friction: Users configuring remote hosts have limited in-product guidance when setup or SSH access fails.

Evidence reviewed

What I checked:

• Released editor repair: Current main uses an explicit labeled, rounded-border text field with a visible user@host format prompt, accessibility label, disabled state, and help text. (Sources/CodexBar/PreferencesMenuPane.swift:121, c4ed34d0e44a)
• Current test coverage: The focused settings test covers empty disabled and populated values, confirms the format hint, and verifies persistence; it does not cover connection testing or diagnostic categories. (Tests/CodexBarTests/PreferencesPaneSmokeTests.swift:214, c4ed34d0e44a)
• Remaining diagnostic gap: The remote fetcher stores a localized SSH error string, while the menu descriptor renders every error as “unreachable”; there is no typed, sanitized failure classification or manual test action. (Sources/CodexBarCore/RemoteSessionFetcher.swift:169, c4ed34d0e44a)
• Remote contract already documented: The documentation specifies comma-separated hosts, non-interactive key-based SSH, and the remote CLI locations, so new diagnostics should build on this established contract. (docs/sessions.md:39, c4ed34d0e44a)
• Merged-fix provenance: The linked merged PR’s commit is the specific editor repair and records its merge timestamp; its scope expressly excluded connection testing and richer diagnostics. (Sources/CodexBar/PreferencesMenuPane.swift:115, 6f27b777afba)
• Release provenance: The local release-tag check reports v0.49.1 contains the editor-repair commit; current main also contains the repaired source. (6f27b777afba)

Likely related people:

• Peter Steinberger: He introduced the cross-host Agent Sessions feature and has the dominant history across the remote fetcher, scheduler, and settings area. (role: feature owner and recent area contributor; confidence: high; commits: 8106e7d3, 8eb867c0, 6072edc2; files: Sources/CodexBarCore/RemoteSessionFetcher.swift, Sources/CodexBar/AgentSessionsStore.swift, Sources/CodexBar/PreferencesMenuPane.swift)
• Akshay Prabhu: The merged editor-specific repair is commit 6f27b77 and directly corresponds to the resolved portion of this issue. (role: introduced the merged editor repair; confidence: high; commits: 6f27b777; files: Sources/CodexBar/PreferencesMenuPane.swift, Tests/CodexBarTests/PreferencesPaneSmokeTests.swift)
• Will Sarg: History credits him with keeping Tailscale session discovery headless and retrying invalid status candidates, both relevant to safe remote diagnostics. (role: adjacent remote-discovery contributor; confidence: medium; commits: 55a28f33, 6054a8a6; files: Sources/CodexBarCore/RemoteSessionFetcher.swift)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[akshayprabhu200]

Thanks — agreed on splitting the scope. I’m preparing a narrow PR for the source-reproduced editor defect only: an explicit labeled rounded-border field, a synthetic user@host format hint, and accessibility/help text. The PR will not add a connection-test workflow, structured host persistence, termination controls, or a diagnostic taxonomy. Those remain in this issue for maintainer product/scoping decisions. Validation and screenshots will use isolated synthetic settings only; no real host, account, address, or tailnet data will be included.