Compatibility gaps: Gas Town tmux argv vs psmux

Context: Gas Town invokes tmux with a specific set of subcommands and flags. These were, derived from gastown's internal/tmux/tmux.go. This issue summarizes where psmux diverges so we can track parity work.

Scope: Flags and argv shapes Gas Town actually passes—not the full tmux manual.

I expect this issue will be broken down into smaller issues and addressed by area. I have also started a discussion #210

Executive summary

Several Gas Town call sites are not handled the same way in psmux. The worst gaps are list-sessions (CLI ignores -F/-f), list-panes -s (server treats -s like “all panes”), resize-window (CLI no-op), list-keys (filters ignored), and CLI parsing for display-message -d and send-keys -X (server may support some of these; CLI does not forward them correctly).

Gap checklist

Details (by command)

list-sessions

• Expected: list-sessions -F '<format>'; filtered checks with -F and -f.
• Gap: The standalone psmux list-sessions CLI path lists sessions from port files and does not apply -F or -f. Filtering comparable to tmux is not implemented end-to-end.

list-panes

• Expected: Session listing uses -s, -t, session name, and -F
• Gap: In src/server/connection.rs, -s is treated like -a for “all panes,” which breaks session-scoped Gas Town usage.

resize-window

• Expected: -t, -x (width).
• Gap: src/main.rs handles resize-window as a no-op and does not forward flags to the server.

list-keys

• Expected: e.g. list-keys -T prefix <key> in tests.
• Gap: CLI drops arguments; server listing does not narrow by -T/key from argv.

display-message (CLI)

• Expected: -t, -d (milliseconds), message—without -p.
• Gap: CLI parser does not consume -d and its value the way the server does; duration can end up in the message.

send-keys (CLI)

• Expected: -X plus a key/command name (e.g. copy-mode).
• Gap: Server supports -X; CLI does not treat -X as a flag and can mis-encode the command line.

respawn-pane

• Expected: Optional -c workdir (non-Windows in upstream tmux usage).
• Gap: CLI parser does not forward -c.

show-options

• Expected: show-options -gv <option> (combined short options as in tmux).
• Gap: If argv uses a single -gv token, behavior should be verified against servers that test *a == "-v" only.

set-option / set-window-option

• Expected: Multiple shapes including -wt, window targets, unset -u.
• Gap: Complex tmux argv orderings may not round-trip; worth validating against Gas Town call sites.

Items that look broadly OK (for this doc)

• capture-pane: -p, -t, -S present in CLI.
• new-session: -d, -s, -c, repeated -e parsed in new-session path.
• split-window: -t, -d, trailing command handled.
• bind-key / unbind-key: Full argv forwarded as a command string (server must still interpret -T / tables correctly—spot-check if issues remain).
• kill-server, has-session, switch-client, set-environment, show-environment, set-hook, clear-history, kill-session: Generally present; edge cases may still differ from tmux.

Suggested next steps

1. Fix list-panes semantics for -s vs -a (session-scoped vs all).
2. Implement or forward list-sessions -F/-f for the CLI path (or document that external tools must use control mode / server).
3. Implement resize-window forwarding or document intentional no-op.
4. Plumb list-keys -T and optional key through CLI and server.
5. Align CLI parsers for display-message and send-keys with server behavior (-d, -X).

References

• src/main.rs — CLI parsing and forwarding
• src/server/connection.rs — server command dispatch

cc: @ghbaud