psmux 3.3.8 -> 3.3.9 adoption: umbrella for the floor bump, workaround retirement, and the follow-on tracks

Bắt đầu bằng cách đọc các issue con đã hoàn tất #658, #659 và #537, sau đó kiểm tra psmux_backend.py và tests/test_psmux_live.py. Issue tổng này không có mục tiêu triển khai độc lập: các nhánh công việc của nó đã hoàn tất hoặc được chuyển sang các issue tiếp theo, vì vậy việc hoàn tất phụ thuộc vào phần công việc được tham chiếu trong các issue con và phạm vi bao phủ CI, chứ không phải một thay đổi đơn lẻ có quy mô phù hợp cho người đóng góp lần đầu.

Umbrella for the psmux 3.3.8 adoption family, in the shape of #288 (which closed when its target-resolution children were done). The children below are separate work tracks with one shared premise: every upstream defect this backend works around is fixed and released — psmux 3.3.8 (66cf613 2026-08-18) is byte-identical to the v3.3.8 tag and to master, all 19 reports filed from this project are closed and released in it, and each workaround premise was re-measured against the installed binary (smoke tables and the F1–F9 proposal).

The one sequencing rule

_LAST_UNSUPPORTED → (3,3,7) (the F1 gate in #658) is the single constant everything hangs on: it refuses 3.3.7 and admits 3.3.8+, and 3.3.8 is the first tag carrying every fix at once — there is no per-workaround floor. Workaround deletions land only behind it (on a 3.3.7 install the pipe-pane -o transport, for one, silently kills run-log capture). F6/F7 in #658 are the exception: correct on both versions, landable any time.

Children

• #658 — floor bump + workaround retirement (F1–F7): the select_window override group, the pipe-pane sidecar, the _transportable narrowing, the kill_session =name override, kill-window failure surfacing, and the doc-rot pass. Actionable now. Its merge closes #222.
• #222 — the historical upstream-wait tracker; carries the evidence. Closes when #658's set merges, per the closure proposal.
• #659 — attended console pass for the five client-movement items, then the switch_client verdict-source rework (F8/F9). F8 done: all five items measured green against a real attached client (results) — the console premise is discharged, and the pass was scripted rather than hand-run, so it repeats. F9 implemented in #670; the issue closes on that merge. The pass also produced #669 and showed F9's premise was understated: the wrong verdict did not just answer False, it fired -l and relocated the operator, then read the relocation as success.
• #537 — PSMUX_DATA_DIR as a per-project registry root, seam-wide. Unblocked by the same F1 gate (the installed build honours the variable, measured); still needs-design for the root derivation and the cross-process contract.

Not children, but watched from here

• psmux/psmux#583 — a -u-shaped option value still deletes the key at rc 0 on 3.3.8, so _transportable's value.startswith("-") clause stays after #658's F4. When a tag ships that fix, its retirement is a small follow-up with its own tag gate.
• psmux/psmux#580 question — if the new pane-scoped option store ever opens to user @ keys, retiring the @opt_@N substitute channel becomes a follow-up with its own tag gate and live smoke. If the allowlist is declared deliberate, the psmux#321 boundary is double-confirmed and nothing changes.

Permanent boundaries — no child should try to retire these

Per-window user options do not exist in psmux's model (psmux#321); -EncodedCommand stays the window-command transport (quoted command strings still die on 3.3.8, root-caused in the psmux#402 comment); _qualified_window_id stays (a bare @N still routes by caller's server); the #{session_attached} delta probes stay for switch-client -l / detach-client, where rc proves dispatch, not effect.

Refs: #288, psmux/psmux#483, psmux/psmux#497, psmux/psmux#482, psmux/psmux#563, psmux/psmux#558, psmux/psmux#545, psmux/psmux#583

Related, deliberately outside the umbrella

Open issues that mention psmux but are bmad-loop-side work no psmux tag affects — defects, plus the coverage the family's own claims lean on. Listed so the boundary is a decision, not an omission:

• #525 / #562 — the seam folds non-zero exits and transport faults to empty listings. Same swallow family as #658's F6, and 3.3.8 makes it worse to keep (more verbs now return meaningful non-zero), but the fix is seam honesty, not adoption. Whoever lands F6 should read both first.
• #531 / #538 — ctl-window collision and ownership proof outliving the run dir. Backend-agnostic design work; the per-project -L namespace idea recorded on #222 (opportunity 2) is one candidate shape for #538.
• #669 — _display_message probes without -t $env:TMUX_PANE, so current_window_id / current_pane_id / current_return_target answer for the server's active window rather than the calling pane. Surfaced and measured by #659's attended pass, but no psmux tag moves it: the fix is the leaf pinning its own probe, exactly as _parked_trailer already does. Blast radius is the ctl-window prune's self-exclusion and the return-option read, not the adoption.
• #671 — the same leaf's other probe-targeting residuals, both pre-dating the adoption: an unguarded :-bearing session name goes straight into display-message -t <session> (the #221 rule the sibling call sites already apply), and the attached-client count is read with a target a foreign server can answer (#315). The second one is why it is listed here rather than parked: #659's F9 made that count load-bearing in the NONZERO direction, where a borrowed count would vouch for a switch that moved nobody.
• #311 — document the qualified-id obligation once at the seam. Adjacent to #658's F7 doc pass but homed in the adapter guide, not psmux_backend.py.
• #662 (PR #668) — install psmux on the Windows CI runner. Not a defect, and the reason it sits here rather than in the children: every test_premise_* and test_adopted_* probe this family added lives in tests/test_psmux_live.py, which no CI job runs today — the Linux matrix skips it on sys.platform, and the Windows runner has no psmux on PATH. The adoption's entire evidence base is therefore observed only by hand on a developer box, and #659's F9 raised the stakes by putting two upstream exit-code premises under the same skipped module. Until this lands, a psmux behaviour drift is a silent green.