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

Empieza leyendo las issues hijas completadas #658, #659 y #537; después inspecciona psmux_backend.py y tests/test_psmux_live.py. Esta issue paraguas no tiene un objetivo de implementación independiente: sus líneas de trabajo ya se han completado o se han trasladado a issues de seguimiento, por lo que su finalización depende del trabajo de las issues hijas referenciadas y de la cobertura de CI, no de un único cambio del tamaño adecuado para alguien que hace su primera contribución.

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.