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 four children are separate defects on
separate call paths, but three of them are the same root cause and the fourth 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

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]
#141 - feat(mux): seam-canonical window targets [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 [merged]

---

📝 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.
• Live re-verification of switch-client paths on the next psmux release (post psmux#483 fix) #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).
• Live re-verification of switch-client paths on the next psmux release (post psmux#483 fix) #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 Live re-verification of switch-client paths on the next psmux release (post psmux#483 fix) #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).