psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server

[dracic]

Summary

#254 (fixed by #290) session-qualified the engine-side window-id seam: PsmuxMultiplexer.new_window and list_window_ids now emit session:@N. The TUI-side surfaces were deliberately excluded from that diff (per the issue's implementation notes) and still hand around bare @N ids on psmux. Both #290 review passes independently confirmed the remaining surfaces, so this files the promised follow-up audit.

Affected surfaces

• new_parked_window (inherited from the base backend) still returns a bare #{window_id}. Consumers replay it as a -t target: set_window_option(win_id, PROJECT_OPTION, ...) and window selection in tui/launch.py, plus attach targeting in the TUI app.
• list_windows field rows: window_id columns stay bare, and prune_ctl_windows passes those ids straight to kill_window — a destructive verb, against the shared cross-project ctl session.
• select_ctl_window_id / ctl window selection takes bare @N values from callers.

Why this is the same bug class as #254

psmux runs one server per session; a bare -t @N routes by the caller's $TMUX, else the most-recent-session fallback. The TUI process frequently runs outside any psmux pane (user launches from a plain shell), so its bare-id verbs land on whatever server the fallback picks. The #254 forensics also showed warm-recycled panes carrying stale env, making the fallback nondeterministic across sessions — in a controlled two-session test a bare kill-window -t '@2' issued in session A killed session B's @2 with rc 0. The prune path uses exactly this verb shape.

Notes for the fix

• Mirror the fix(adapters): session-qualify psmux window ids #290 approach: qualify at the psmux backend's minting/listing seams, not per caller. new_parked_window should return the same session:@N form as new_window; list_windows should qualify window_id fields identically.
• Symmetry hazards to watch: current_window_id() comparisons in the ctl-candidate scan (win_id == current) must compare like with like, and any caller that composes mux.target(CTL_SESSION, window) from an already-qualified id would double-qualify.
• The session:@N target grammar is already verified on stock psmux 3.3.7 for kill-window, send-keys, pipe-pane, list-panes, and capture-pane (see fix(adapters): session-qualify psmux window ids #290's verification notes); only the TUI-side consumers and their id round-trips need auditing here.

Refs: #254, #290, #221, psmux/psmux#483

[coderabbitai]

🔗 Related PRs

#137 - feat(mux): herdr TUI-launch surface [merged]
#141 - feat(mux): seam-canonical window targets [merged]
#148 - fix(tui): guard raiser-side multiplexer calls in action handlers [merged]
#225 - fix(tui): record session-qualified parked-window return target [merged]
#290 - fix(adapters): session-qualify psmux window ids [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]

Pre-implementation probe results — the unknowns here were probed on stock 3.3.7 (05cc5d4) before writing any code, using the #254 methodology: two live servers with deliberately colliding window ids (both sessions hold @2), all verbs driven from outside any pane (the TUI's usual routing context). Two of the unknowns turned out to be hard blockers for a straight port of the #290 recipe, and one finding is a today-broken behavior independent of this issue.

Per-verb target-form results (stock 3.3.7, from outside any pane)

verb	sess:@N	sess:name	sess:index
kill-window	✅ (verified in #254 probes)	✅	✅
select-window	❌ rc 1 can't find window: @N — even for an existing window	✅ correct window activated, no cross-server bleed	✅
set-option -w / -wu	⚠️ rc 0, window part ignored	⚠️ rc 0, window part ignored	⚠️ rc 0, window part ignored
show-options -wqv	⚠️ always '', rc 0 (nonexistent windows too)	⚠️ always ''	⚠️ always ''

• The -w option verbs accept every form with rc 0, but the value actually lands at session scope: after set-option -w -t A:@2 @opt vid, every targeted -wqv read returns '', while show-options -qv -t A @opt (session scope, no -w) returns vid.
• Format expansion follows the same model: after setting @opt "on" one window, list-windows -t A -F '#{window_name}=[#{@opt}]' prints the value for every window of the session (pwsh=[TAGVAL] wina=[TAGVAL]).
• display-message -p '#{window_id}' returns a bare @N (source: format.rs prints @{id}), so the current_window_id() comparison seam stays bare unless qualified in the backend.

Consequences for this issue's design

1. session:@N cannot be the universal TUI target token on stock 3.3.7. It is correct for kill-window (the prune path — the destructive one), but select-window rejects the id form outright and the window-option verbs ignore the window slot entirely. A psmux new_parked_window returning sess:@N would feed select_window targets that fail rc 1.
2. Name/index are the working forms for select-window, but ctl window names are {kind}-{run_id} and the start_detached docstring already warns names can collide — the stable-id contract exists precisely because of that. The practical option for psmux is a just-in-time id→index resolve (one list-windows -F '#{window_id}|#{window_index}' before the verb), accepting the renumber race, or an upstream fix.
3. Per-window user options are effectively session-scoped on psmux 3.3.7 — this part is broken today, before any psmux: TUI-side window ids are still bare — parked mint, list_windows fields, and prune kill targets replay @N cross-server #291 work:
   • PROJECT_OPTION prune scoping: every ctl window's #{@bmad_project} row expands to the last-set session value, so per-window ownership discrimination (the cross-project protection in the candidate scan) does not discriminate at all on psmux.
   • RETURN_OPTION: with two parked windows in the ctl session, both trailers read the same session-scoped value — last writer wins, so an earlier parked window returns the client to the newer window's origin. (The trailer's untargeted in-pane show-options -wqv read works only because the value is session-scoped.)

Suggested split

• This issue: psmux backend qualifies new_parked_window/list_windows id fields for the verbs that honor ids (kill-window), and routes select-window through name/index resolution — with the target grammar above as the acceptance matrix.
• The window-option scoping defect (point 3) 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: set-option -w silently session-scopes and select-window rejects @N in the window slot of a qualified target. Worth filing upstream before building workarounds here, since both are exactly the kind of thing a future release may fix under our feet.

Probe environment: psmux 3.3.7 (05cc5d4 2026-07-20, chocolatey), Windows 11, PowerShell 7; sessions p291a/p291b, colliding @2, all probes repeated with and without the = prefix (stripped by parse_target, no behavior difference).

[dracic]

Correction + model clarification after a source pass on psmux master (0b962b0, 28 commits past v3.3.7 — none touch any of this), prompted by a "is this really a bug, or are we assuming tmux semantics again" review of my previous comment.

Correction: the parked-window return mechanism is fully inert on psmux — not "last writer wins"

My previous comment claimed the trailer's untargeted in-pane show-options -wqv read "works only because the value is session-scoped, last writer wins". That was still a tmux-shaped assumption, and it is wrong. The actual read path (server/options.rs::get_window_option_value_for) gates on is_window_option(name) — a hard allowlist of 14 builtin names — before ever consulting the user-options map. A @-prefixed user option is never in that list, so every -w read of RETURN_OPTION returns the empty string, targeted or not, in-pane or not. The trailer's $ret is therefore always empty and neither the detach nor the switch-client branch ever fires: the parked-window return mechanism does nothing at all on psmux today. (Doubly dead on stock 3.3.7: even if the read produced a value, the pre-#483 switch-client window/pane no-op would swallow the replay — which is consistent with what the #185 live smoke observed and why #221 deferred live psmux verification to #222.)

The PROJECT_OPTION consequence from my previous comment stands as written (session-scoped storage + #{@opt} expansion bleeding the same value into every list-windows row — live-verified).

Model, not regression: psmux has exactly one option scope per server

To avoid repeating the mistake this project made once already with server-global ids (#254 / psmux/psmux#483 — "bare ids are only resolvable in the current session" turned out to be a deliberate property of the one-server-per-session model, not a bug to wait out), the right reading of the source is:

• Window (types.rs) has no options storage of any kind; all user options live in App.user_options, one map per server = per session.
• The set-option/setw handler parses -w only as "a flag that consumes no argument" and skips -t values; the request sent to the server carries the option and value only — no scope, no target, on every code path.
• The maintainer has stated the model in Fall back to global window options psmux/psmux#321 in as many words: options "only exist at the global level in psmux" (the -w read surface exists for libtmux/tmuxp compatibility, backed by the builtin allowlist + a global fallback for a few names).

So: per-window options should be treated as a permanent model boundary of psmux, same family as per-server ids — not as a defect an upstream release will fix under us. The only genuinely bug-shaped edges (not filed, per our current decision) are the silent rc-0 acceptance of a -w -t <target> that is ignored, and the write/read asymmetry (a set that succeeded is unreadable through the same flags that set it) — but a fix for those would make the calls error, not make per-window options exist.

Design consequence for this issue

Any part of the TUI story that needs per-window state on psmux must not ride window options. Two channels that DO work on stock 3.3.7 (both live-verified): session-scoped user options (set-option/show-options -qv round-trip works) with the window id encoded in the option name (e.g. @bmad_return_%40N, readable in-pane after a display-message -p '#{window_id}'), or state keyed by window id outside the multiplexer entirely (run-dir sidecar, as the engine already does for its own state). The backend override seam from #290 stays the right place to hide whichever channel is chosen, so the tmux path keeps real window options.

[dracic]

The select-window -t sess:@N rejection from the acceptance matrix above turned out to be a clean upstream bug, not a model boundary — the CLI's pre-send existence check only matches window index/name while the server's focus path fully supports id targets (FocusWindowById). Filed as psmux/psmux#497 with a deterministic repro and a suggested one-line fix. Design impact here: if the fix ships in the next psmux tag, the TUI select path can stay on the qualified id form behind the existing version gate, and the name/index fallback only needs to cover stock 3.3.7.