test(adapters): probe psmux workaround premises, not just our reaction

[dracic]

Closes #488

What

Eight premise probes in the Windows live gate. Each drives raw psmux argv against a throwaway
session and asserts the observed upstream behavior that a workaround in psmux_backend exists
because of — never the backend verb the workaround implements.

The failure semantics are inverted on purpose: a red probe is the intended signal, and its
message names the workaround that has become droppable. That is the manual step from #222's
admission checklist turned into an assertion.

Plus the ablation half: every negative assertion the issue listed was ablated for real — guard
deleted, test run, result recorded, guard restored.

Why it was needed, concretely

Four of the eight premises had already flipped on psmux main (d56d777, 6c76ff9,
33ea109, 8edd1cb/194fac0) and nothing in this repo changed colour.

Every premise was observed before it was asserted

All eight were driven against the installed 3.3.7 build first. Two are sharper than the issue
described:

• set-option -w does not merely lack per-window storage — it silently lands at session scope
  (show-options -wqv reads empty while the same key at session scope reads the value back).
• kill-window on an unresolvable target exits 0 and destroys the ACTIVE window. The probe pins
  exactly that: the session survives and the vanished window is precisely the one that was active.

Upstream

Tracing the =-form kill divergence to its cause produced psmux/psmux#558: parse_target
strips the = for routing but PSMUX_TARGET_FULL keeps the raw argument, so the server's
kill-session fallback compares "name" == "=name" and never kills. Verified identical at v3.3.7
and main.

A second candidate (CLI value corruption for ' and non-ASCII whitespace) was traced and
deliberately not filed — e41886f already fixed it on main via a Unicode-aware
quote_arg_if_needed. Consequence worth flagging for the 3.3.8 admission: those two _transportable
branches become droppable, and the round-trip probe here will go red and say so.

Ablation results

verdict	assertions
bite on their own assertion	:276, :404, :957
belts — a neighbouring ==/raises fires first	:96, :114, :824, :1618
vacuous, repaired	:1625 — last_fallback defaulted false, so the -l leg was unreachable regardless of the early-return guard it claimed to cover
wrong-reason failure, repaired	:1647 — reached its assertion only via IndexError from a fixture that ran dry

The issue's list also mislabels :414: it is a positive assertion. The negative one in that test
is :404.

Five further weakly-discriminating negatives outside the issue's scope (they ablate into a
TypeError rather than reaching their assertion) were recorded in the deferred-work ledger rather
than pulled into this change.

Invariants held

• Zero tokens. Parked windows run pwsh -NoProfile -Command exit 0; no coding CLI is launched.
• No developer session is ever reachable. Every probe gets its own throwaway session with a
  verified teardown. PSMUX_DATA_DIR isolation is applied only when the installed build
  demonstrably honors it. Bare switch-client -l is not probed at all — it has no target form, so
  under $TMUX it would move the developer's own client.
• No workaround dropped, no _LAST_UNSUPPORTED bump. This builds the instrument; psmux 3.3.8: adopt as installed floor, re-verify the switch-client/select-window paths, and drop the psmux#497 and other workarounds #222 owns the
  admission.
• CI untouched — the live gate stays a manual gate.

Verification

• tests/test_psmux_live.py + tests/test_psmux_backend.py: 154 passed on Windows with psmux 3.3.7
• full suite: no psmux-related failures
• trunk check: no issues
• the version probe's reachability was proven by inverting its regex and observing the failure —
  as first written it was vacuous, since available() applies the same regex and skips the test
  on the very failure the probe exists to catch

Summary by CodeRabbit

• Bug Fixes

  • Improved validation of fallback switching so successful client moves no longer trigger unnecessary fallback behavior.
  • Corrected test coverage for scripted attachment and switching scenarios.

• Tests

  • Added comprehensive live-environment checks for session targeting, window selection, option handling, client commands, and pipe-pane behavior.
  • Added coverage for edge cases involving unresolved targets and transport of option values.

• Documentation

  • Documented verified compatibility with the supported psmux behavior and recorded the latest validation details in the changelog.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 72900882-b6e8-4681-90cb-3f72b7604a94

📥 Commits

Reviewing files that changed from the base of the PR and between 65e5844 and 8e9ed10.

📒 Files selected for processing (4)

• CHANGELOG.md
• src/bmad_loop/adapters/psmux_backend.py
• tests/test_psmux_backend.py
• tests/test_psmux_live.py

---

Walkthrough

The change adds isolated live probes for raw psmux behavior, documents the upstream version basis, and updates switch-client tests to exercise fallback handling without vacuous assertions.

Changes

psmux premise validation

Layer / File(s)	Summary
Live premise probes tests/test_psmux_live.py, src/bmad_loop/adapters/psmux_backend.py, CHANGELOG.md	The live gate probes psmux version output, target resolution, window selection, option scope, client verbs, option transport, pipe-pane argument handling, and unresolved kill-window behavior. Documentation records the tested source tag and changelog entry.
Switch fallback assertions tests/test_psmux_backend.py	Switch-client tests pass last_fallback=True, script both switch paths, and verify that successful targeted switching skips the fallback command.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• bmad-code-org/bmad-loop#222 — The live premise probes directly implement coverage for upstream behaviors behind the psmux workarounds.

Possibly related PRs

• bmad-code-org/bmad-loop#181 — The switch-client tests extend behavior introduced in the psmux multiplexer implementation.
• bmad-code-org/bmad-loop#218 — The live probe validates the pipe-pane flag handling used by the sidecar sink workaround.
• bmad-code-org/bmad-loop#312 — The target-resolution and window-selection probes cover behaviors used by session-qualified window handling.

Suggested reviewers: pbean

Poem

A rabbit checks each psmux gate,
With little probes that validate state.
Windows park and flags are cleared,
Fallback paths are now well-seared.
“Hop!” says the hare, “the facts are bright!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding premise probes for psmux workarounds.
Linked Issues check	✅ Passed	The changes implement all coding objectives in #488, including eight premise probes, isolation, zero-token coverage, and ablation repairs.
Out of Scope Changes check	✅ Passed	The changelog, documentation, backend tests, and live probes directly support the requirements in #488.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}