fix(server): handle tmux installed but no server running #2

Closed

peter wants to merge 0 commits from codex/tmux-no-server into codex/ignore-local-build-artifacts

peter commented

2026-06-23 19:11:17 +02:00

Owner

Summary

Treat tmux's fresh "no server running" state as tmux being available with no sessions/clients.
Keep real tmux connection failures surfaced instead of silently enabling the launch path.
Add focused coverage for tmux status handlers, terminal window listing, and stderr classification.

Actual issue encountered

While using ocman to create a new OpenCode session for this repository, the UI failed before it could launch a new session. The failure was visible in the "Failed to start session" dialog:

Waiting for OpenCode to come up
Creating session
No running OpenCode instance here, and tmux is unavailable to start one.

This was a real session-start failure observed in ocman, not a theoretical cleanup. The important clue was that tmux was installed, but ocman still reported it as unavailable.

What we observed while debugging

The error message came from ocman's own tmux availability path, not directly from OpenCode.
The backend first checks whether the tmux binary exists, then calls tmux list-sessions / tmux list-clients to populate /api/tmux/sessions and /api/tmux/clients.
tmux list-sessions and tmux list-clients exit non-zero when the tmux binary is installed but no tmux server/socket exists yet. tmux reports this as variants such as no server running ... or error connecting to ... (No such file or directory).
Before this patch, the handlers treated any listing error as available: false, so the frontend concluded tmux was unavailable even in the recoverable "installed, but no server yet" state.

What we assumed / inferred

We inferred the user's failure was caused by conflating "tmux is not installed/unusable" with "tmux is installed, but no server is currently running".
We assumed the no-server state is safe to report as available: true with an empty list, because tmux new-session can create the server on demand.
We did not assume every tmux connection error is recoverable. Permission/socket failures such as (Permission denied), (Operation not permitted), or a generic error connecting to ... still report unavailable so the user gets a real failure instead of a misleading launch attempt.

Caveat

This PR only fixes tmux availability reporting for the fresh no-server state. It does not claim that OpenCode itself will start or be discovered correctly after launch; the next PR in the stack handles fresh OpenCode port discovery during tmux launch.

Stack

Stacked on codex/ignore-local-build-artifacts. Next PR: codex/opencode-fresh-port-discovery.

Validation

Run on codex/tmux-no-server:

go test ./internal/server -run 'Test(IsTmuxServerNotRunningError|HandleTmuxStatus|AllTermWindowNames)'
go test ./internal/server

The stack tip was also previously validated with make test, make lint, make build, and CGO_LDFLAGS="-framework UniformTypeIdentifiers" go build -tags "desktop production" -o ocman-desktop ..

## Summary - Treat tmux's fresh "no server running" state as tmux being available with no sessions/clients. - Keep real tmux connection failures surfaced instead of silently enabling the launch path. - Add focused coverage for tmux status handlers, terminal window listing, and stderr classification. ## Actual issue encountered While using ocman to create a new OpenCode session for this repository, the UI failed before it could launch a new session. The failure was visible in the "Failed to start session" dialog: ```text Waiting for OpenCode to come up Creating session No running OpenCode instance here, and tmux is unavailable to start one. ``` This was a real session-start failure observed in ocman, not a theoretical cleanup. The important clue was that `tmux` was installed, but ocman still reported it as unavailable. ## What we observed while debugging - The error message came from ocman's own tmux availability path, not directly from OpenCode. - The backend first checks whether the `tmux` binary exists, then calls `tmux list-sessions` / `tmux list-clients` to populate `/api/tmux/sessions` and `/api/tmux/clients`. - `tmux list-sessions` and `tmux list-clients` exit non-zero when the tmux binary is installed but no tmux server/socket exists yet. tmux reports this as variants such as `no server running ...` or `error connecting to ... (No such file or directory)`. - Before this patch, the handlers treated any listing error as `available: false`, so the frontend concluded tmux was unavailable even in the recoverable "installed, but no server yet" state. ## What we assumed / inferred - We inferred the user's failure was caused by conflating "tmux is not installed/unusable" with "tmux is installed, but no server is currently running". - We assumed the no-server state is safe to report as `available: true` with an empty list, because `tmux new-session` can create the server on demand. - We did **not** assume every tmux connection error is recoverable. Permission/socket failures such as `(Permission denied)`, `(Operation not permitted)`, or a generic `error connecting to ...` still report unavailable so the user gets a real failure instead of a misleading launch attempt. ## Caveat This PR only fixes tmux availability reporting for the fresh no-server state. It does not claim that OpenCode itself will start or be discovered correctly after launch; the next PR in the stack handles fresh OpenCode port discovery during tmux launch. ## Stack Stacked on `codex/ignore-local-build-artifacts`. Next PR: `codex/opencode-fresh-port-discovery`. ## Validation Run on `codex/tmux-no-server`: - `go test ./internal/server -run 'Test(IsTmuxServerNotRunningError|HandleTmuxStatus|AllTermWindowNames)'` - `go test ./internal/server` The stack tip was also previously validated with `make test`, `make lint`, `make build`, and `CGO_LDFLAGS="-framework UniformTypeIdentifiers" go build -tags "desktop production" -o ocman-desktop .`.

peter added 1 commit

2026-06-23 19:11:17 +02:00