For context: this PR is independent of #206 (the multiplexer-abstraction / WezTerm-backend work).

• WezTerm multiplexer backend + Windows support via multiplexer abstraction #206 introduces a BaseMultiplexer abstraction with TmuxMultiplexer + WezTermMultiplexer backends. It's a larger architectural change.
• This PR (Windows support fixes (psmux-compatible) #207) keeps CAO single-backend and tmux-coupled, but makes the existing tmux client compatible with psmux — a Rust tmux-compatible multiplexer that runs natively on Windows. It's a smaller, more conservative path to Windows support.

The two paths are complementary, not competing:

• A reviewer who prefers minimal architectural change can take Windows support fixes (psmux-compatible) #207 alone — vanilla CAO + psmux on Windows.
• A reviewer who wants long-term flexibility (WezTerm, future backends) takes WezTerm multiplexer backend + Windows support via multiplexer abstraction #206.
• Both can coexist: psmux compatibility helps the TmuxMultiplexer backend in WezTerm multiplexer backend + Windows support via multiplexer abstraction #206 work on Windows too.

A few of the smaller fixes in here (e.g. the os.path.isabs() working-directory check, the Path.home() RuntimeError guard, FileHandler(delay=True)) are pure Windows-portability fixes that apply regardless of which backend you ship with — they could be cherry-picked independently if useful.

Happy to split / rework as preferred.

@psmux — flagging for confirmation. Thanks again for offering help in #206.

While porting CAO to run with psmux as a drop-in tmux replacement on Windows, we hit a handful of behavioural deltas vs upstream tmux. We've worked around all of them on the CAO side (every site tagged with `# psmux-workaround: …` in clients/tmux.py for grep-ability), but it would be ideal to land upstream fixes so the workarounds can be removed.

Tested against psmux 3.3 on Windows 11 with libtmux 0.51.0 in the loop.

Findings

1. `list-sessions` ignores `-F` — the default `NAME: N windows (created DATE) [(attached)]` text is returned regardless of the format string. libtmux requests `-F #{session_id}…` and got the default text → empty parse → `TmuxObjectDoesNotExist`. We worked around by parsing the default output.

2. `-F` is only honoured when separated from the format token in argv. `-F#{session_id}` (libtmux's default form, concatenated) is ignored; `-F #{session_id}` (space-separated argv entries) works. This caused `new-session -P -F#{session_id}` to echo back `-sNAME` instead of the session id, breaking libtmux's session-creation lookup.

3. `has-session -t =NAME` exact-prefix not supported — libtmux uses the `=` prefix to disambiguate name vs prefix matches. We call without `=`.

4. `new-session -e KEY=VAL` records the env on the session but doesn't propagate it into the spawned shell. CAO uses this to inject `CAO_TERMINAL_ID` and provider auth flags (e.g. `CLAUDE_CODE_USE_BEDROCK`); children couldn't see them on Windows. Workaround: stamp `$env:K = 'V'; ...` into the launch command before exec'ing the agent.

5. Named paste buffers don't exist — `paste_buffers` appears to be a `Vec` capped at 10, with `-b NAME` parsing the name as a `usize` index that silently falls back to slot 0 when parse fails. CAO's UUID-named buffers all collapsed to the same slot under concurrent windows. We worked around by using one fixed buffer name and serialising calls per window. (Pointer based on user investigation: `src/types.rs:392` and `src/server/connection.rs:1050`.)

6. `paste-buffer -p` ignores `-p` — dispatches `SendText` instead of `SendPaste`, so the bracketed-paste sequences (`\x1b[200~` / `\x1b[201~`) are never emitted. Not currently a blocker for CAO's flow on Windows but worth noting. (Pointer: `src/server/connection.rs:~1058`.)

Ask

Could you confirm any of these are accurate / scoped correctly? Findings #1–#4 in particular feel like one-or-two-line server-side fixes that would let libtmux drive psmux directly without our subprocess workaround layer.

Will look into it and help you get it up and running in a short bit.

Also, you don't need to workaround except for OS specific issues. I will help you undo the workarounds if it's because of Psmux (except specific OS related stuff)

Hey @marcfargas, great work on this PR. I went through every single workaround you documented and tested them all thoroughly. Here is a complete status report with proof.

All 6 Workarounds Tested and Verified

I wrote three separate test suites to verify each finding:

1. 26/26 PowerShell E2E tests (tests/test_pr207_workaround_elimination.ps1) covering all 6 workarounds plus TCP path verification
2. 25/25 Python subprocess tests (tests/test_pr207_libtmux.py) replicating the EXACT subprocess patterns from your tmux.py code, including the full CAO send_keys() workflow
3. 22 Rust unit tests for the named buffer implementation (tests-rs/test_named_buffers.rs)

Full cargo test suite: 5619 tests, 0 failures.

Workaround Status

WA1: list-sessions ignores -F >> FIXED in psmux 3.3.3

list-sessions -F '#{session_name}' returns just the session name, not the default NAME: N windows text. Complex multi field formats like #{session_id} #{session_name} #{session_windows} all work correctly. Your workaround of parsing default output can be removed.

WA2: -F#{fmt} (concatenated) ignored >> FIXED in psmux 3.3.3

Both -F#{session_name} (concatenated) and -F '#{session_name}' (space separated) produce identical output. Tested across list-sessions, list-windows, and new-session -P. Your workaround of forcing space separated argv can be removed.

WA3: has-session -t =NAME not supported >> FIXED in psmux 3.3.3

Exact match semantics work correctly: =NAME matches only the exact session name, not prefixes. =pr207w_exact does NOT match a session named pr207w_exactmatch_full. Your workaround of calling without = can be removed.

WA4: -e KEY=VAL not propagated >> WORKS on psmux 3.3.3

Environment variables set via -e KEY=VAL on new-session are propagated into the child shell. Tested by setting CAO_TEST_VAR=hello_from_cao and reading it with $env:CAO_TEST_VAR inside the session. Your workaround of stamping $env:K = 'V' into the launch command is not needed.

WA5: Named paste buffers >> FIXED in psmux 3.3.3

This was the biggest gap. I implemented a full HashMap<String, String> named buffer system alongside the existing positional Vec<String> stack. UUID style buffer names now work exactly like tmux:

• set-buffer -b <uuid> "content" stores in the named map
• show-buffer -b <uuid> retrieves from the named map
• delete-buffer -b <uuid> removes only that buffer
• paste-buffer -b <uuid> -t session pastes into the target pane
• load-buffer -b <uuid> - loads from stdin (your exact CAO pattern)
• Multiple concurrent UUID named buffers are fully independent (no collision)
• Numeric -b 0 still indexes the positional stack for backward compat

Your workaround of using a fixed buffer name and serializing per window can be removed.

WA6: paste-buffer -p (bracketed paste) >> Known limitation

As you noted, this is not currently a blocker for CAO. The -p flag does paste content into the pane, but does not wrap with \x1b[200~ / \x1b[201~ sequences. This is on the roadmap.

About libtmux's Server.sessions

You correctly identified that libtmux's session lookup breaks. I dug into the root cause: libtmux 0.55 generates a 126 field format string using U+241E (visible Record Separator symbol) as the delimiter. On Windows, Python's subprocess.Popen defaults to cp1252 encoding for stdout, which cannot represent U+241E. The UTF8 bytes E2 90 9E get decoded as a + z (mojibake), and the parse fails with zip() argument 2 is shorter. This is a libtmux encoding bug on Windows, not a psmux issue. Your approach of using direct subprocess.run() calls is actually the correct solution regardless.

Full CAO Workflow Proof

I replicated the EXACT send_keys() sequence from your tmux.py:

# Step 1: load-buffer from stdin
subprocess.run([psmux, "load-buffer", "-b", cao_uuid, "-"], input=command)
# Step 2: paste-buffer
subprocess.run([psmux, "paste-buffer", "-p", "-b", cao_uuid, "-t", session])
# Step 3: sleep
time.sleep(0.3)
# Step 4: send Enter
subprocess.run([psmux, "send-keys", "-t", session, "Enter"])
# Step 5: delete-buffer (finally)
subprocess.run([psmux, "delete-buffer", "-b", cao_uuid])

This full workflow passes end to end. The command is pasted, executed, and the buffer is cleaned up.

Summary

Workarounds 1 through 5 are proven unnecessary in psmux 3.3.3. I am happy to help you strip them out if you want, or you can grep for # psmux-workaround: and remove them yourselves. Let me know what works best.

All test files are in the psmux repo under tests/ if you want to verify independently.

Update: All 6 Workarounds Eliminated + libtmux Native API Works

Commit: 10ebb81 (tag v3.3.0.4)

Install

cargo install --git https://github.com/psmux/psmux --tag v3.3.0.4

What's Fixed

Every workaround in PR #207 is now provably unnecessary with psmux:

libtmux Native API Compatibility

libtmux's Server.sessions, .windows, .panes, new_window(), send_keys(), kill() all work natively with psmux — no workarounds needed:

• $N session ID targets (e.g. -t $0) now resolve correctly
• @N window ID targets (e.g. list-panes -t @2) now target the correct window
• list-panes -t @N returns panes of the specified window (not just the active window)

Note: libtmux 0.55.1 on Windows requires a one-line patch to common.py (add encoding="utf-8" to subprocess.Popen) due to cp1252 locale on Windows. This is a libtmux upstream issue, not a psmux issue — tmux on Linux works because locale.getpreferredencoding() returns UTF-8 there.

Test Evidence

33 Python tests (all pass):

• 25 subprocess-based tests covering all 6 workarounds + CAO workflow + concurrency
• 8 libtmux native API tests: Server.sessions, .windows, .panes, new_window(), send_keys(), kill()

26 PowerShell E2E workaround elimination tests (all pass)

22 PowerShell E2E PR207 compat tests (all pass)

33 Rust unit tests (22 named buffers + 11 PR207 compat) (all pass)

1861 cargo tests (all pass)

@marcfargas @haofeif Please try it and let me know how it goes

Thanks @psmux — that's a comprehensive set of fixes. One snag on our end: we don't have a Rust toolchain on the test box, so cargo install --git ... --tag v3.3.0.4 isn't available. The Docker route also fails (Windows containers don't run on Windows ARM here).

The v3.3.0.4 tag is published but no GitHub release was cut for it, so there's no binary to download. The CI workflow doesn't upload artifacts either, and your release workflow is workflow_dispatch-only since 7e721a3.

Could you dispatch the Release workflow to publish a binary? Two options that would work for us:

1. Tag v3.3.4 off current master (42ab3899) — gets the WA fixes plus the 3 doc commits since 10ebb81, and scoop will auto-update users from 3.3.3 → 3.3.4.
2. Dispatch against the existing v3.3.0.4 tag — faster, but the version string won't trigger a scoop upgrade from 3.3.3.

Once a binary is out, I'll upgrade locally, strip workarounds 1–5 from clients/tmux.py, re-run the Windows test suite, and push. Will document psmux ≥ <version> as a hard requirement in the PR.

Okay I need to run comprehensive testing overall which will go for several hours. Please give me sometime for the release

Codecov Report

❌ Patch coverage is 6.21469% with 166 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@3df3fa0). Learn more about missing BASE report.

@@           Coverage Diff           @@
##             main     #207   +/-   ##
=======================================
  Coverage        ?   10.81%           
=======================================
  Files           ?       52           
  Lines           ?     4326           
  Branches        ?        0           
=======================================
  Hits            ?      468           
  Misses          ?     3858           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Quick upstream status update on the remaining psmux workarounds:

• psmux/psmux#264 (paste-buffer): maintainer could not reproduce on current master and added a proof harness in 10d8da6; this looks likely fixed post-3.3.4, but not yet in a released build we've verified against, so CAO keeps the send-keys -l workaround for now.
• psmux/psmux#265 (trailing \\ in env values): no change; CAO still strips trailing backslashes as a workaround.
• psmux/psmux#266 (automatic-rename overriding explicit -n NAME): maintainer reproduced it, then fixed it upstream in 4f31cde / tag v3.3.4-fix-266; CAO keeps the workaround until a released psmux build includes that fix.

I also updated the PR body to reflect this, but adding this comment so subscribers get notified.