psmux backend: per-server bare-id targets and the pre-#483 rc-0 no-op ceiling

[pbean]

Umbrella issue for the psmux target-resolution family. The five children are separate defects on
separate call paths, but four of them are the same root cause — psmux reporting execution rather
than effect — and the fifth is the audit that found them.

Root cause: ids are per-server, and psmux runs one server per session

On tmux a bare @N (window) or %N (pane) id is server-global and unambiguous. On psmux it
is only meaningful on the server that minted it, and the CLI resolves it against the caller's
current-session server. In a normal TUI-launched run there are at least two servers — the
bmad-loop-ctl session's and the agent session's — with colliding ids (@1 exists on both). So
a bare-id -t from inside the ctl pane silently binds to the wrong pane and exits 0.

This was already root-caused once, for switch-client, in #221 / psmux/psmux#483 and fixed in
#225 by composing a session-qualified target in the backend that knows its own target grammar.
The fix was applied to one call path, not to the class. #254 is the same bug on pipe_pane.

Compounding factor: the pre-#483 rc-0 no-op

psmux builds without the #483 fix exit 0 as a no-op when switch-client gets an unresolvable
target. Every fallback in this codebase that keys off a nonzero exit code — the POSIX trailer in
adapters/tmux_base.py (switch-client -t "$ret" || switch-client -l), the pwsh override in
adapters/psmux_backend.py, and BaseTmuxBackend.switch_client — is therefore structurally
unreachable on those builds. The knowledge currently lives only in a CHANGELOG entry.

psmux/psmux#483 is CLOSED, fixed on main (d56d777 + 6c76ff9), but v3.3.7 (2026-07-20) is
still the newest tag and carries the no-op. Two children are gated on the next release.

Children

#254	pipe_pane targets a bare @N → run logs empty on TUI-launched runs	actionable now
#227	return_attached_client reports success even when switch_client fails	actionable now (backend-agnostic — affects tmux too)
#228	version-gate the rc-0 no-op + document the fallback ceiling	comment half actionable; version gate needs the tag
#222	live re-verification of the switch-client paths on the next psmux release	blocked on the next psmux tag
#317	the seam's switch_client / detach_client booleans are vacuously True — return_attached_client trusts them	latent until #310 lands, then live

Worth doing once, here

#254 offers two shapes: qualify the target inside PsmuxBackend.pipe_pane (smallest diff), or
have new_window return a session-qualified id so every downstream -t consumer is safe. The
second is the class-level fix, and given that this is now the second instance of the same bug,
an audit of the remaining bare @N / %N uses on the psmux path is cheap while someone is in
there.

Refs: psmux/psmux#483, psmux/psmux#482, #221, #225, #185, #217.

[coderabbitai]

🔗 Related PRs

#137 - feat(mux): herdr TUI-launch surface [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 [merged]
#316 - fix(tui): report the parked-window return honestly (#227) [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!

[dracic]

Sorry @pbean, haven't seen this...

[dracic]

Status map after the #254 work landed in PR #290 — this umbrella wasn't on our radar during implementation, but the PR ended up taking exactly the shape recommended here, so closing the loop explicitly:

• psmux: pipe_pane targets a bare @N window id — per-server ambiguity binds the sink to the wrong server's pane (empty run logs) #254 → PR fix(adapters): session-qualify psmux window ids #290 (open). Option 2, the class-level fix: PsmuxMultiplexer.new_window returns session:@N and list_window_ids emits the identical form (the symmetry keeps the engine's native_id in list_window_ids(...) liveness membership honest). Every engine-side -t consumer — pipe_pane, send_text, kill_window, window_pane_pids — inherits the qualified target with zero changes to the generic adapter. Grammar verified three ways on stock 3.3.7 (source audit at the tag, colliding-id CLI probes per verb, end-to-end smoke through the backend); verification details are in the PR body.
• The "audit the remaining bare-id uses while someone is in there" item is done — filed as psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 rather than grown into the PR. The audit found the remaining surfaces (new_parked_window return, list_windows field ids, ctl prune targets, select_ctl_window_id) and, more importantly, that the TUI half is not a straight port of the fix(adapters): session-qualify psmux window ids #290 recipe: on stock 3.3.7 select-window rejects sess:@N outright (rc 1, even for an existing window; only sess:name/sess:index work), and the window-option verbs (set-option -w, show-options -wqv) accept any target with rc 0 but silently ignore the window slot — window options actually land at session scope, and #{@opt} format expansion bleeds the value to every window row. The full per-verb acceptance matrix is in the #291 comment. The option-scoping defect also means the per-window PROJECT_OPTION/RETURN_OPTION semantics are broken on psmux today, independent of target qualification — that half is upstream-shaped (same class as pipe-pane strips every dash-flag token from the piped command — pwsh -EncodedCommand sinks can never start (3.3.7) psmux/psmux#482/#483) and not yet filed.
• return_attached_client reports success even when switch_client fails #227 / psmux pre-#483-fix rc-0 no-op: gate the version and document the fallback ceiling #228 untouched by fix(adapters): session-qualify psmux window ids #290 (different call paths), but the probes produced one datapoint for psmux pre-#483-fix rc-0 no-op: gate the version and document the fallback ceiling #228's documentation half: on stock 3.3.7 the rc-0-no-op ceiling is verb-specific, not uniform — select-window with an unresolvable qualified window errors rc 1, while show-options on a nonexistent window stays rc 0 silent. Worth folding into the fallback-ceiling writeup when that lands.
• Next psmux tag: re-verify the switch-client/select-window paths and drop the psmux#497 and other workarounds #222 unchanged — still gated on the next psmux tag; fix(adapters): session-qualify psmux window ids #290's forms were deliberately restricted to what stock 3.3.7 already resolves, so the next tag widens options rather than invalidating anything.

[dracic]

Two updates to my status map above, after a source pass on psmux master (0b962b0) prompted by a "is this a bug or the model" review:

• The option-scoping half is reclassified: model boundary, not an upstream-shaped defect — withdrawing the "worth filing upstream" framing. psmux has exactly one option scope per server (no per-window storage exists structurally; maintainer's own words in Fall back to global window options psmux/psmux#321: options "only exist at the global level"). Same family as the per-server bare-id boundary this umbrella is about. Full source chain and the correction of my earlier "last writer wins" claim are in the #291 correction comment — the sharper consequence is that the parked-window return mechanism is fully inert on psmux today (the trailer's show-options -wqv read returns '' unconditionally, so no branch ever fires).
• Next psmux tag: re-verify the switch-client/select-window paths and drop the psmux#497 and other workarounds #222 is therefore gated on more than the next psmux tag: the switch-client grammar items remain release-gated, but the trailer end-to-end items additionally need the RETURN_OPTION channel reworked on psmux (noted on Next psmux tag: re-verify the switch-client/select-window paths and drop the psmux#497 and other workarounds #222 with a suggested checklist split; the natural home is the psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 backend seam).

[dracic]

Status update — the class-level fix this umbrella recommended is now done on both sides, and the audit it asked for turned up one more family member that is not a target-resolution bug at all.

Children, current state

#254	pipe_pane / engine-side bare @N	closed by #290 — took the class-level shape this issue recommended: new_window returns session:@N and list_window_ids mirrors it, so every downstream -t consumer inherits the qualification instead of each call site being patched
#291	TUI-side bare ids (parked mint, list_windows id columns, prune kill targets)	in progress — the audit #288 asked for, filed as its own issue; fix in flight
#310	psmux per-window user options are session-scoped	new — surfaced by the #291 audit; see below, it is a different root cause
#227	return_attached_client reports success even when switch_client fails	open, backend-agnostic
#228	version-gate the rc-0 no-op + document the fallback ceiling	open
#222	live re-verification of the switch-client paths on the next psmux release	still blocked — v3.3.7 (2026-07-20) remains the newest tag

The audit's finding: the TUI half was not a straight port of the #254 recipe

Two of this umbrella's assumptions did not survive contact with stock 3.3.7. Both were verified in the psmux source at tag v3.3.7 (the installed build, 05cc5d4), not inferred from tmux semantics:

1. session:@N is not a universal target token. It is correct for kill-window (the destructive prune path), but select-window rejects it outright: src/main.rs:93 cli_window_exists compares the window part only against #{window_index} and #{window_name}, never #{window_id}, and select-window exits 1 on that check whenever the target contains :. This is purely a client-side pre-send gate — the server already dispatches FocusWindowById for id targets (src/server/connection.rs:895) — so psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 resolves the id to an index before sending rather than waiting on upstream. Filed as select-window -t session:@id: client-side existence check rejects window-id targets the server supports (3.3.7) psmux/psmux#497 with a repro.

2. Per-window user options do not exist on psmux, and that is a model boundary, not a bug. set-option -w is accepted with rc 0 while the window slot is ignored; every -w read of an @-prefixed name returns '' because get_window_option_value_for gates on a 14-name builtin allowlist before consulting the user-options map (src/server/options.rs:4,155), and Window in src/types.rs has no options storage at all — all user options live in one per-server map. The maintainer states the model directly in Fall back to global window options psmux/psmux#321.

   Consequence: two bmad-loop mechanisms that ride window options are inert on psmux today, independently of any id work — the PROJECT_OPTION cross-project prune guard cannot discriminate (one session-scoped value bleeds into every list-windows row), and the RETURN_OPTION parked-return mechanism never fires in either branch. That is psmux: per-window user options are session-scoped - the ctl-window project guard cannot discriminate and the parked-return mechanism is inert #310, and it needs a different state channel rather than a different target form.

Scope note for this umbrella

#288 framed the family as "bare-id targets + the pre-#483 rc-0 no-op". The audit says it is really two families sharing one cause (one server per session): ids are per-server, which qualification fixes and #254/#291 now cover end to end; and options are per-server, which qualification cannot fix at all. Worth tracking #310 here so the second one does not get re-derived as a targeting bug the next time someone reads a -w call and assumes tmux semantics.

Refs: #290, #291, #310, psmux/psmux#497, psmux/psmux#321, psmux/psmux#483