Next psmux tag: re-verify the switch-client/select-window paths and drop the psmux#497 and other workarounds

[dracic]

Summary

This is the single "when the next psmux tag lands" tracker for the psmux family under #288. Two separate upstream fixes are sitting on psmux main with no release carrying them — 3.3.7 (2026-07-20) is still the newest tag, and the only one our version gate admits:

upstream	what it fixes	commits on main
psmux/psmux#483	switch-client window/pane targets silently ignored (rc-0 no-op)	d56d777 + 6c76ff9
psmux/psmux#497	select-window -t sess:@N rejected CLI-side; and the server focusing @N as index on ≥3-window sessions	33ea109

Everything below is what changes for us the day a tag ships both. Sections are split by what each item is actually gated on — the tag alone, the tag plus a code removal here, or something no release will ever fix.

---

A. Gated on the tag only — live smoke, real attached client, Windows 11

Several forms we rely on (or plan to, see #221) were never live-verified because 3.3.7 cannot exercise them.

• switch-client -t %N same-session: the parked-window trailer's return move now actually lands on the originating pane (maintainer verified; confirm through our trailer end-to-end)
• Unresolvable target exits non-zero → the trailer's switch-client -l fallback is now reachable; confirm the fallback itself works
• switch-client -l semantics across psmux's per-session servers: does "last session" survive the server hop at all? (never live-tested; both trailers and switch_client(last_fallback=True) depend on it)
• Cross-session sess:win selection: TUI/CLI attach to a control-session window from inside psmux (switch-client -t =bmad-loop-ctl:<win>) lands on that window, not the session's active one (fixed upstream in 6c76ff9; on 3.3.7 the window part is ignored)
• = exact-match prefix in a qualified target (=sess:win): does the new dedicated switch-client handler parse it? (untested upstream form; upstream tests use bare sess:win)
• Whichever return-target form Parked-window return target is a bare pane id — unresolvable cross-session on psmux (one server per session) #221 lands (sess:idx.idx or sess:%N): verify it live cross-session (ctl session → user session)
• switch_client() seam no longer returns a false True on a no-op (rc-0 trust — self-heals with the release, confirm)
• select-window -t sess:@N focuses the right window on a ≥3-window session — the select-window -t session:@id: client-side existence check rejects window-id targets the server supports (3.3.7) psmux/psmux#497 part 2 defect (server fell back to id-number-as-index) only manifests there; a 2-window control is not a valid check
• select-window -t sess:@N.pane (select-window -t session:@id: client-side existence check rejects window-id targets the server supports (3.3.7) psmux/psmux#497 part 3, parse_target dropping the pane suffix) — we do not target this form today, but confirm before anyone relies on it

B. Gated on the tag and a workaround removal here — psmux/psmux#497

Removal recipe and the reasoning are in the #291 comment. All in src/bmad_loop/adapters/psmux_backend.py, and the whole group goes at once:

• Bump _LAST_UNSUPPORTED from (3, 3, 6) to the last release without 33ea109 — this is the actual gate. While available() still admits 3.3.7, the workaround is load-bearing: on that build the id form does not merely fail, it focuses the wrong window on ≥3-window ctl sessions.
• Delete the PsmuxMultiplexer.select_window override (base select-window -t session:@N works directly)
• Delete _window_index — sole caller is that override; its renumber-race ceiling disappears with it
• Delete the _QUALIFIED_ID class attribute — sole consumer is that override
• Module docstring: drop the "select_window is the one verb that cannot take that form…" sentence; every id-taking verb becomes uniform
• tests/test_psmux_backend.py: invert the id→index resolution tests (and the unresolvable-id pass-through case) to assert the qualified id reaches the verb untranslated

Not affected, do not touch: the session-qualification of new_window / list_window_ids / new_parked_window / list_windows / current_window_id. That is psmux/psmux#483's per-server-id model property, permanent, and independent of #497.

Also tag-dependent: #228's version gate (the rc-0 no-op ceiling) — it needs the same tag, and its _LAST_UNSUPPORTED bump is the same edit as the first box above. Sequence them together, not as two PRs fighting over one constant.

C. Not release-gated — no psmux tag fixes these

Recorded here so the "next tag" pass does not re-litigate them:

• Per-window user options do not exist in psmux's model (one option scope per server; maintainer in Fall back to global window options psmux/psmux#321) → tracked in psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310. Consequence for this checklist: the two trailer end-to-end items in section A fail at the read step on any release — show-options -wqv @bmad_return_pane returns '' unconditionally, so neither the switch-client nor the detach branch ever fires. They need the RETURN_OPTION channel re-homed first (session-scoped option with the window id encoded in the option name, or run-dir sidecar state — both live-verified working on stock 3.3.7). The pure grammar items are unaffected: smoke them by feeding a target by hand. Update 2026-07-26: the re-homing is implemented on the psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310 branch (session-scoped @opt_@N keys; trailer self-probes its window id via display-message -p -t $env:TMUX_PANE), so once that PR merges the section-A trailer items become exercisable on the next tag.
• set_return_pane's write (set-option -w) silently lands at session scope (rc 0), so even a fixed read channel must not assume the value is per-window. Update 2026-07-26: moot on the psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310 branch — @-option writes no longer use -w at all.
• One-shot ;-token splitting is not quote-aware (found in psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310 round-4 verification, live-reproduced on 3.3.7): the one-shot CLI path chains commands through split_chained_commands (config.rs:1282), which cuts on whitespace-delimited ;/\; tokens with no quote-awareness — psmux set-option @k "a ; b" stores a and hands the rest to the server as a command; "a; b" (mid-token) is safe. The control-mode (-C) splitter (connection.rs:20) is quote-aware, so upstream likely never sees this on iTerm2-style clients. Workaround: the psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310 _transportable gate refuses values containing standalone ;/\; tokens. Filed upstream as set-option: ";" inside a double-quoted value splits the one-shot command line (value truncated, remainder executed) psmux/psmux#499 (repro incl. remainder-execution proof); when a tag ships the fix, the refusal can narrow to mirror the quote-aware splitter.
• show-options listing can answer empty-with-success while keys exist: the plugin-drain copy of the ShowOptions handler (server/mod.rs:465-468 at v3.3.7) replies "" rc 0. Source-verified, not live-reproduced (race window). The psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310 backend treats {} as a real answer, so a read landing there degrades to "every key unset" for that one call; documented in _scoped_options' docstring, self-heals on the next sweep/list. No workaround worth its weight; recorded so a future mis-fallback debug does not start from zero.

Notes

• The 3.3.7 live-smoke evidence and the phantom-client cosmetic issue live in psmux backend: live smoke on the first post-3.3.6 release #185 and Ghost-client leak: a dead client's ClientInfo is never reaped, and ClientDetach over-decrements attached_clients psmux/psmux#434.
• fix(adapters): session-qualify psmux window ids #290's target forms were deliberately restricted to what stock 3.3.7 already resolves, so the tag widens options rather than invalidating anything.

Refs: psmux/psmux#483, psmux/psmux#497, psmux/psmux#321, #221, #185, #228, #291, #310

[coderabbitai]

🔗 Related PRs

#137 - feat(mux): herdr TUI-launch surface [merged]
#141 - feat(mux): seam-canonical window targets [merged]
#225 - fix(tui): record session-qualified parked-window return target [merged]
#290 - fix(adapters): session-qualify psmux window ids [merged]
#312 - fix(adapters): session-qualify psmux TUI-side window ids [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[pbean]

Triage: blocked:upstream. Filed under #288 with the rest of the psmux target-resolution family.

Confirmed as of 2026-07-24: psmux/psmux#483 is CLOSED and fixed on main (d56d777 + 6c76ff9),
but v3.3.7 (2026-07-20) is still the newest tag — so the fix has shipped in no release and
every checklist item here still cannot pass. This stays blocked until the next psmux tag; the
version gate itself needs no change (it already admits any >3.3.6).

[dracic]

Heads-up from the #291 probe work: the next psmux tag alone will not make the trailer end-to-end items here pass — there is a second, independent blocker upstream of switch-client, on our read side.

Both return paths obtain the recorded target by reading RETURN_OPTION as a window option — the post-exit trailer runs show-options -wqv @bmad_return_pane in-pane, and the in-process replay (return_attached_client) calls show_window_option() on the current window. On psmux that read returns the empty string unconditionally: per-window user options do not exist in psmux's model (one option scope per server; the -w read surface is a builtin-allowlist emulation for libtmux compat — maintainer's own statement in psmux/psmux#321, source chain in the #291 correction comment). This is a permanent model boundary, same family as per-server ids — no upstream release changes it.

Concretely for the checklist:

• The two end-to-end items (trailer return move; whichever Parked-window return target is a bare pane id — unresolvable cross-session on psmux (one server per session) #221 form is recorded) will fail on any psmux release at the read step — $ret is empty, so neither the switch-client nor the detach branch ever executes. They need a precondition item: re-channel RETURN_OPTION storage/read on psmux (session-scoped option with the window id encoded in the option name, or run-dir sidecar state — both channels live-verified working on stock 3.3.7; the natural home is the backend seam psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 is already touching).
• The pure switch-client grammar items (same-session %N, non-zero exit on unresolvable, -l across per-session servers, cross-session sess:win, = prefix) are unaffected — they can be smoked by feeding a target by hand, without going through the option read.
• set_return_pane's write (set-option -w) also silently lands at session scope on psmux (rc 0), so even a fixed read channel must not assume the recorded value is per-window — with two parked windows the last write wins at session scope.

Suggest splitting the checklist accordingly when the tag lands: "psmux release gated" (grammar items) vs "gated on the #291 return-channel rework" (end-to-end items).

[dracic]

One more item for the next-psmux-tag pass, so the sequence doesn't get lost: alongside the switch-client checklist above, re-verify psmux/psmux#497 (select-window -t sess:@N rejected by the CLI's pre-send existence check; deterministic repro in that report). If the fix ships in the tag:

• flip the psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 select path from the JIT id→index fallback to the plain qualified id form, behind the existing available() version gate (fallback stays for stock 3.3.7);
• if it does not ship, the JIT fallback simply remains — nothing else in psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 depends on it (kill/list/option surfaces are #497-independent, see the psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 acceptance matrix).