psmux pre-#483-fix rc-0 no-op: gate the version and document the fallback ceiling

[dracic]

What

Both parked-trailer replay paths — the POSIX trailer in src/bmad_loop/adapters/tmux_base.py (_parked_trailer, switch-client -t "$ret" || switch-client -l) and the pwsh override in src/bmad_loop/adapters/psmux_backend.py — use a nonzero exit code to trigger the switch-client -l fallback. The Python side (BaseTmuxBackend.switch_client) does the same.

Per psmux/psmux#483 (upstream-final), psmux builds without the #483 fix exit 0 as a no-op when switch-client gets an unresolvable window/pane target. On those builds the fallback is structurally unreachable: the client silently stays parked in the ctl window with no feedback. #225 made the recorded target session-qualified, which resolves correctly on fixed psmux releases — but on pre-fix releases the rc-0 no-op ceiling remains, and the knowledge currently lives only in a CHANGELOG entry.

Suggested follow-ups

1. Version gate: the psmux support gate (_LAST_UNSUPPORTED in psmux_backend.py) currently guards only the PID-kill bug. Once the psmux release carrying the #483 fix is known, bump it (or add a dedicated check) so affected builds are refused or warned about instead of silently misbehaving.
2. Ceiling comment: a one-line note next to the pwsh trailer (and/or switch_client) — "pre-#483-fix psmux exits 0 on an unresolvable target, so the -l fallback cannot fire there" — keeps the limitation next to the code that has it.

Surfaced by a silent-failure audit during review of #225; documented there but unenforced in code.

[coderabbitai]

🔗 Related PRs

#137 - feat(mux): herdr TUI-launch surface [merged]
#146 - refactor(mux)!: extract the herdr backend to pbean/bmad-loop-adapter-herdr [merged]
#181 - feat(adapters): add native-Windows psmux multiplexer backend [merged]
#218 - fix(adapters): pipe psmux pane logs through a positional sidecar sink [merged]
#225 - fix(tui): record session-qualified parked-window return target [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 — but only half of it. Filed under #288.

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 affected builds are still the only
builds.

Splitting the two follow-ups by what actually blocks:

• Ceiling comment (item 2) — actionable now. The one-line note next to the pwsh trailer and
  switch_client ("pre-#483-fix psmux exits 0 on an unresolvable target, so the -l fallback
  cannot fire there") depends on nothing external and can land today. Right now that knowledge
  lives only in a CHANGELOG entry, which is the thing this issue exists to fix.
• Version gate (item 1) — blocked. _LAST_UNSUPPORTED cannot be bumped until the release
  carrying the #483 fix has a number.

Worth doing the comment half now rather than letting it wait on the tag.

[dracic]

Coordination note: the _LAST_UNSUPPORTED bump this issue needs is now the same edit as section B of #222 (dropping the psmux/psmux#497 select_window workaround in psmux_backend.py is gated on the identical constant). Both are waiting on the next psmux tag — land them in one PR rather than two racing over one tuple. #222 carries the consolidated checklist; the documentation half here (verb-specific rc-0 ceiling: select-window errors rc 1 on an unresolvable qualified window, show-options stays rc 0 silent) is still actionable now, independent of the tag.

[dracic]

Source-verified update from the #227 / PR #316 review, in two parts — one broadens this issue's premise, one is a sibling now filed separately as #317.

The rc-0 no-op is not confined to pre-#483 builds. This issue frames the ceiling as "psmux builds without the #483 fix exit 0 as a no-op". At v3.3.7 — the only tag available() admits — the switch-client CLI arm never had a reply path to begin with:

cmd.push('\n');
send_control(cmd)?;
return Ok(());

send_control returns Ok on the TCP round-trip, so ? propagates a transport error only. That is every flag, -t included, not just an unresolvable target. Current main adds send_control_with_response for -t alone, so switch-client -l remains exit-0-regardless on every release to date — which makes the || switch-client -l fallback in _parked_trailer structurally unreachable independently of #483.

detach-client has the same shape, and it was not previously on this issue's radar: the only nonzero exit is an unreachable session server, so it succeeds with zero clients attached, and a flag-less invocation (what the backend issues) is promoted server-side to detach-all. The arm is identical between v3.3.7 and 33ea109.

The consequence for the Python seam booleans — switch_client / detach_client returning a vacuous True that return_attached_client trusts — is a different call path and consumer than this issue's shell trailer, so it is tracked in #317 rather than piled on here. The version-gate suggested in this issue's follow-up list is a candidate fix for both.