psmux 3.3.8: attended console pass for the client-movement paths, then rebase switch_client's verdict source

[dracic]

Follow-up to #222, carrying its F8/F9 half per the closure proposal. The grammar half of every item below is already green on psmux 3.3.8 (66cf613) (smoke tables, §2/§8); what is unproven is only the client-movement half, because a detached probe registers no client (#{session_attached} stayed 0 through a backgrounded psmux attach). This needs a human at a real console on Windows 11, with the #658 floor bump in place.

F8 — the attended pass (blocks F9)

• switch-client -t %N same-session lands on the originating pane, through our parked-window trailer end-to-end
• the trailer's switch-client -l fallback actually returns the client
• switch-client -l across psmux's per-session servers: does "last session" survive the server hop? (3.3.8 made -l per-client and rc-1-on-no-last-session — psmux#566 — but cross-server movement was never live-verified)
• cross-session switch-client -t =bmad-loop-ctl:<win> lands on that window, not the session's active one
• whichever return-target form Parked-window return target is a bare pane id — unresolvable cross-session on psmux (one server per session) #221 landed, verified live ctl-session → user session

F9 — switch_client's same-session residue (needs F8's measurements first)

With psmux#483 live, a same-session move is real but produces zero #{session_attached} delta, so TerminalMultiplexer.switch_client returns False deterministically — tui/launch.py then records ATTENDED for a client that did leave, and a later --repeat cycle calls input() in a window nobody is viewing.

Proposed shape, to confirm against F8's measurements before writing it: at ≥3.3.8 take switch-client -t's exit code as the verdict (meaningful in the failure direction since psmux#483/#555/#558; it is what the parked trailer already does), and keep the #{session_attached} delta probe for -l and detach-client, where rc still proves dispatch, not effect (test_premise_client_verbs_exit_zero_with_no_client_to_move is green on 3.3.8).

Out of scope

The headless removals and doc pass — #658. If the psmux/psmux#580 question opens the pane store to user @ keys in a future tag, retiring the @opt_@N substitute becomes a separate follow-up with its own tag gate, not part of this issue.

[coderabbitai]

🔗 Related PRs

#434 - fix(adapters): seam-owned psmux option-key namespace, kill-order containment [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]
#670 - fix(psmux): rebase switch_client's verdict on the exit code it can trust [open]
#661 - psmux 3.3.8: bump the floor and retire the workarounds it makes dead [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]

F8 — attended pass done, all five items green

psmux 3.3.8 (66cf613), Windows 11, real attached client. Each item below is a measured state transition, not a report: #{session_attached} for both sessions plus the session's active window were read around every verb, so "where the client landed" is observable rather than eyeballed. Topology was a two-session mirror of the real one — a ctl session holding the parked/driver windows and a separate user session as the return destination.

#	Item	Measured	Verdict
1	-t %N same-session lands on the originating pane	rc 0, attached 1 → 1, active window @3 → @4	✅ moves, invisible to the count
1e2e	…through the parked-window trailer, end to end	parked window armed with a cross-session return target, Enter at the park prompt → window gone, client on the named pane, option key freed	✅ (cross-session target on purpose: a window that merely dies leaves the client in ctl, so the two outcomes are distinguishable)
2	the trailer's -l fallback actually returns the client	dead target → rc 1, can't find pane: %7, counts unchanged; then -l → rc 0, ctl 1 → 0, user 0 → 1	✅ and rc is honest in the failure direction
3	-l across psmux's per-session servers	issued on the user session's server: rc 0, user 1 → 0, ctl 0 → 1	✅ "last session" survives the server hop
4	cross-session -t =ctl:<win> lands on that window, not the active one	ctl's active window was the driver; rc 0, user 1 → 0, ctl 0 → 1, and the named window's process registered the arrival	✅ named window wins
5	the #221 return form live, ctl → user	-t =<user>:%N: rc 0, ctl 1 → 0, user 0 → 1	✅

What the pass turned up beyond the checklist

F9's premise was understated. The delta verdict is not merely a conservative False. With last_fallback=True — how tui.launch.return_attached_client always calls it — the wrong verdict fires switch-client -l, which relocates the operator into an unrelated session, and that produces the delta the correct move never could. So the call returns True, the caller reports RETURNED and clears its return option. Measured end to end on the real path: return_attached_client() answered returned while the client had been thrown into the other session entirely.

The proposed shape held up with one correction: rc alone is not enough, because switch-client -t still exits 0 with nothing to move (the existing premise probe stays green). The verdict is rc gated on a client having been attached to this session, with the count read before the verb. Implemented in #670.

A separate defect, filed as #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. Measured: a probe running in window @8 / pane %10 answered @3 / %4 while a different window was active. Independent of this issue's verdict change, hence its own issue.

On the "needs a human" premise

It needed a real attached client, which is not the same thing. The client was attached inside a terminal-multiplexer pane driven from outside, and every verb was issued by an in-pane executor while landings were read back from psmux itself — so the pass is scripted and repeatable rather than a one-off manual session. Worth knowing before the next item gets deferred for wanting a console.