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

[dracic]

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

• psmux 3.3.8 adoption: bump the floor to (3,3,7) and drop the retired workarounds #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 psmux 3.3.8: adopt as installed floor, re-verify the switch-client/select-window paths, and drop the psmux#497 and other workarounds #222.
• psmux 3.3.8: adopt as installed floor, re-verify the switch-client/select-window paths, and drop the psmux#497 and other workarounds #222 — the historical upstream-wait tracker; carries the evidence. Closes when psmux 3.3.8 adoption: bump the floor to (3,3,7) and drop the retired workarounds #658's set merges, per the closure proposal.
• psmux 3.3.8: attended console pass for the client-movement paths, then rebase switch_client's verdict source #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 fix(psmux): rebase switch_client's verdict on the exit code it can trust #670; the issue closes on that merge. The pass also produced psmux: current_window_id/current_pane_id answer for the server's active window, not the calling pane #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.
• psmux: adopt PSMUX_DATA_DIR as a per-project registry root — seam-wide, not a create-call env tweak #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

• set-option parses flags after the option name: a dash-leading value is eaten — -u deletes the key at rc 0, and there is no -- end-of-options (3.3.8) 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 psmux 3.3.8 adoption: bump the floor to (3,3,7) and drop the retired workarounds #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:

• BaseTmuxBackend.list_window_ids folds every nonzero exit to [], so a failed listing reads as an empty session #525 / list_windows folds a transport fault to an empty listing, so a faulted ctl candidate scan reads as "nothing to prune" #562 — the seam folds non-zero exits and transport faults to empty listings. Same swallow family as psmux 3.3.8 adoption: bump the floor to (3,3,7) and drop the retired workarounds #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.
• TUI: ctl_window_id admits an untagged control window on run-id collision, so two projects can attach to or kill each other's #531 / Untagged sessions still have no ownership proof that outlives the run dir (#419 direction 2, now unhomed) #538 — ctl-window collision and ownership proof outliving the run dir. Backend-agnostic design work; the per-project -L namespace idea recorded on psmux 3.3.8: adopt as installed floor, re-verify the switch-client/select-window paths, and drop the psmux#497 and other workarounds #222 (opportunity 2) is one candidate shape for Untagged sessions still have no ownership proof that outlives the run dir (#419 direction 2, now unhomed) #538.
• psmux: current_window_id/current_pane_id answer for the server's active window, not the calling pane #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 psmux 3.3.8: attended console pass for the client-movement paths, then rebase switch_client's verdict source #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.
• psmux: the client-verb probes aim their -t at an unguarded session name, and read the attached count with a substitutable target #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 Parked-window return target is a bare pane id — unresolvable cross-session on psmux (one server per session) #221 rule the sibling call sites already apply), and the attached-client count is read with a target a foreign server can answer (fix(adapters): give psmux a per-window option channel #315). The second one is why it is listed here rather than parked: psmux 3.3.8: attended console pass for the client-movement paths, then rebase switch_client's verdict source #659's F9 made that count load-bearing in the NONZERO direction, where a borrowed count would vouch for a switch that moved nobody.
• adapter seam: document the qualified-id obligation once, not per backend #311 — document the qualified-id obligation once at the seam. Adjacent to psmux 3.3.8 adoption: bump the floor to (3,3,7) and drop the retired workarounds #658's F7 doc pass but homed in the adapter guide, not psmux_backend.py.
• ci: install psmux on Windows runner to enable live multiplexer gates in CI #662 (PR ci(windows): run the psmux live gate in CI instead of before releases #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 psmux 3.3.8: attended console pass for the client-movement paths, then rebase switch_client's verdict source #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.

[coderabbitai]

🔗 Related PRs

#427 - fix(adapters): guarantee a single-line multiplexer version() (#321) [merged]
#517 - test(adapters): probe psmux workaround premises, not just our reaction [merged]
#523 - fix(runs,tui): tag project ownership with a transportable digest [merged]
#661 - psmux 3.3.8: bump the floor and retire the workarounds it makes dead [merged]
#670 - fix(psmux): rebase switch_client's verdict on the exit code it can trust [open]
#668 - ci(windows): run the psmux live gate in CI instead of before releases [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]

Status pass from the 2026-08-20 tracker overhaul — three of the four children are now closed, and two of the umbrella's own caveats are discharged.

Children: #658 ✅, #222 ✅, #659 ✅ (F9 shipped in PR #670). #537 is the only one left open.

Two things this umbrella flagged as outstanding have since landed, so the text around them is now stale in your favour:

• The "silent green" bullet is discharged. ci: install psmux on Windows runner to enable live multiplexer gates in CI #662 merged as PR ci(windows): run the psmux live gate in CI instead of before releases #668 — .github/workflows/ci.yml now resolves the latest psmux windows-x64 release asset, installs it on the Windows runner, and runs the live gate in its own serial step. The adoption's evidence base is no longer observed only by hand on a developer box, which was the stated reason that item sat here rather than in the children.
• The [ ] #659 reasoning is discharged by PR fix(psmux): rebase switch_client's verdict on the exit code it can trust #670 and PR fix(psmux): pin display-message self-probes to the calling pane #672. psmux: current_window_id/current_pane_id answer for the server's active window, not the calling pane #669 also closed with fix(psmux): pin display-message self-probes to the calling pane #672, so the one piece of rot you called out in the "deliberately outside the umbrella" map is gone.

This issue stays open. I proposed closing it during triage on the #288 precedent — three of four children done — and the adversarial pass refuted that, correctly. The umbrella carries content that lives nowhere else: the "Permanent boundaries — no child should try to retire these" section, and the watch entries for psmux/psmux#583 and psmux/psmux#580. Closing would strand both. The close becomes right the moment #537 lands, or #537 is explicitly re-parked on-thread as pure design-wait.

One suggestion before that day comes: give psmux/psmux#583's retirement trigger a home — either a test_premise_* probe beside the #580 one in tests/test_psmux_live.py, or a line on #537's thread. Right now the trigger for retiring _transportable's value.startswith("-") clause exists only in this issue's prose, and that is precisely the content a close would lose.

Labels: added P4 (the issue carried no priority). Deliberately not adding blocked:upstream or needs-design — the remaining action here is a status comment, not code, and #537 carries the design question itself.