psmux: the seam's detach/switch booleans are vacuously True — the parked-return honesty guarantee is tmux-only

[dracic]

Child of #288. Same root cause as #228 — psmux reports execution, not effect — but a different call path and a different consumer, so it does not fit under that issue's title or scope.

#228 is about the shell trailer: switch-client -t "$ret" || switch-client -l cannot reach its fallback because the first command exits 0. This is about the Python seam: TerminalMultiplexer.switch_client / detach_client return a boolean that tui.launch.return_attached_client consumes to decide whether to clear RETURN_OPTION. On psmux that boolean is vacuously True.

Verified in the psmux source at v3.3.7 (the version available() admits)

switch-client (src/main.rs, the "switch-client" | "switchc" arm): every flag is folded into a command string and the arm ends in

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

send_control returns Ok on the TCP round-trip, so ? propagates only a transport error. No form carries a server reply — -t included. Exit 0 whether or not any client moved.

detach-client (same file, the "detach-client" | "detach" arm): the only nonzero exit is an unreachable session server —

if send_control(server_cmd).is_err() {
    eprintln!("psmux: no session '{}'", session_for_routing);
    std::process::exit(1);
}
return Ok(());

— so it succeeds with zero clients attached. It also promotes a flag-less invocation to detach-all, which is what the backend issues:

let effective_all = detach_all || (t_target.is_none() && shell_cmd.is_none());

Post-tag: current main gives switch-client a response path (send_control_with_response), but only for -t. The -l fallback stays exit-0-regardless, and detach-client is unchanged — the arm is identical between v3.3.7 and 33ea109.

Why nothing is broken today

Latent, not live. psmux's per-window option channel is inert (#310), so return_attached_client reads an empty RETURN_OPTION and answers False before reaching either verb. The moment #310 / #315 revives that channel, this becomes reachable: the parked-return path will consume a True that means nothing, clear the return option, and report a hand-back that never happened — reintroducing #227's exact symptom on the platform the psmux backend exists for.

Impact when live

sweep._return_after_decisions journals sweep-returned-after-decisions, prints "✓ decisions recorded", and sets prompting = False — while the human is still attached and the client never moved. Every later decision then defers through the unattended path.

Candidate directions

1. Version-gate the honesty claim — same shape as psmux pre-#483-fix rc-0 no-op: gate the version and document the fallback ceiling #228's proposed gate; the seam answers a typed "unknown" rather than True on builds that cannot report effect.
2. Observe effect instead of trusting the exit code — e.g. compare list-clients before/after, at the cost of an extra round-trip on a path that runs once per decisions phase.
3. Accept and contain — keep the vacuous True but make return_attached_client verify the option was actually consumed. Weakest, but backend-agnostic.

Nothing is actionable until #310 lands; filing now so the reviver of that channel inherits the constraint rather than rediscovering it.

Context

Surfaced by the review of #227 / PR #316, which widened detach_client from None to bool and made the tmux path honest (smoke-measured: detach-client exits 1 with no current client when nothing is attached, 0 with a client). The psmux divergence is recorded in the backend's degradation ledger there; this issue is its tracker.

Refs: #288, #228, #222, #310, #315, #227

[coderabbitai]

🔗 Related PRs

#137 - feat(mux): herdr TUI-launch surface [merged]
#181 - feat(adapters): add native-Windows psmux multiplexer backend [merged]
#225 - fix(tui): record session-qualified parked-window return target [merged]
#315 - fix(adapters): give psmux a per-window option channel [open]
#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!

[pbean]

Reachable as of #315 — the "nothing is broken today" section above is spent. That merged at 23:16Z 2026-07-26 and revived psmux's per-window option channel, so return_attached_client now reads a real RETURN_OPTION on Windows and gets all the way to the verbs.

Addressed in PR #316 by candidate direction 2 (observe effect), not deferred: PsmuxMultiplexer overrides detach_client / switch_client to count the session's attached clients before and after the verb and answer on the drop, discarding the exit code. Never on an absolute count — a -t read against a session whose server is gone answers from whichever server the fallback picks, so "zero attached" alone proves nothing (the #315 lesson); a drop needs two successful reads of the same session, the first nonzero. Unobservable degrades to False, never a vacuous True, and the probe is self-detecting: a build without #{session_attached} cannot echo a plausible integer.

Direction 1 (version-gate) was not taken: it pins the answer to a build number that then rots, while the measurement self-corrects — the switch leg reads as no effect today, exactly as psmux/psmux#483 predicts, and starts reporting True on its own the moment upstream lands that fix, with no change here.

The consumer half moved too, which changes what a False costs: tui.launch.return_attached_client now answers a three-state ReturnOutcome, so a switch that moved nothing reports ATTENDED (the human is still in this window — keep prompting) rather than being confused with a detach that found nobody (UNREACHABLE — go unattended). A vacuously-True psmux switch would have taken the third path and reported a hand-back, which is what made this #227's symptom rather than a cosmetic lie.

Not closing yet. #{session_attached} is verified on live tmux 3.4 (0 with nothing attached, 1 → 0 across a real detach) but not on psmux — no local Windows host. The runbook is on the PR (#316 (comment)). If psmux carries the field, this closes with #316. If it does not, the probe degrades to False and this stays open, re-scoped to "psmux exposes no observable client state" — a narrower issue than the one filed here.

Residue either way: a switch whose target pane lives in the same session moves the client between windows without changing the count, so it reads as no effect. Reachable only when the return target was recorded from inside a control-session window, and the caller then keeps prompting — the safe direction. Recorded in the backend's degradation ledger.

[pbean]

Probed on the Windows VM (psmux, isolated -L probe316 socket) — #{session_attached} is supported and tracks reality: 0 with nothing attached, 1 with a client, back to 0 across a real detach. So the measurement in PR #316 works at the transport, not just under the mocked unit tests, and this closes with that merge rather than being re-scoped.

The direct confirmation of this issue is the no-op case:

psmux -L probe316 detach-client; $LASTEXITCODE      # 0
psmux -L probe316 display-message -p -t probe '#{session_attached}'   # 0, unchanged

Exit 0 for a detach that did nothing — the same exit code an effective detach returns. The source reading said so; this is it observed. Full result table: #316 (comment)

Not proven: the end-to-end sweep hand-back on Windows (no pending decision available on that host), and the switch leg, which is inert at 3.3.7 anyway (psmux/psmux#483) and so reads as no effect either way. Residue stays as documented — a same-session switch changes no attached count, and the caller keeps prompting, which is the safe direction.