feat(mux): seam-canonical window targets

[pbean]

What

Makes the window-target contract backend-neutral. Core (runs.py, tui/launch.py, tui/app.py) used to hand-assemble tmux-shaped =session[:window] exact-match strings in 10 places and push them through the seam — so every non-tmux backend had to reverse-engineer tmux target syntax (herdr's _parse_target did; the psmux re-land #58 would have next). The grammar is now owned by the seam:

• TerminalMultiplexer.target(session, window=None) — new concrete encoder, default emits the now-seam-canonical =session[:window] token. Backends MAY override to emit native ids; the docstring pins the constraint (the token must stay a stable by-name reference — core formats targets ahead of use, e.g. a parked window's return target, so eager resolution goes stale).
• multiplexer.parse_target() — the matching module-level decoder: (session, window|None) for a canonical token, None for a backend-native id. One tested helper instead of per-backend re-derivation.
• Core's 10 f-strings swap to target() via two thin helpers that preserve layering: runs.session_target(run_id) and launch.ctl_target(window=None) (tui/app.py keeps importing only runs/launch, never the mux).
• herdr's _parse_target delegates its grammar split to parse_target(); its workspace/tab/pane resolution (and strict/tolerant semantics) is untouched. herdr deliberately does not override target() — pinned by a test.
• tmux backends: zero behavior change — the canonical grammar coincides with tmux exact-match syntax, so BaseTmuxBackend keeps passing targets straight through (now noted in its class docstring).
• Target-taking seam methods' docstrings state the two-family rule (canonical token | native id); the adapter authoring guide gains a Window targets section.

Zero behavior change, by construction

The default target() emits byte-identical strings to the old f-strings, so no existing test assertion was edited — the exact-argv pins in test_tui_launch.py, test_runs.py (attach_argv with and without TMUX), test_cli.py, test_tui_app.py, and the herdr grammar-acceptance tests in test_herdr_backend.py all pass unchanged and double as the compliance proof. New tests in test_multiplexer.py cover the encoder grammar, the parse_target round-trip/edges/native-passthrough, and herdr's inherit-don't-override choice.

Out-of-tree adapters are unaffected: all string-typed method signatures and semantics are unchanged, target() is concrete and inherited. Adapters that already decode the grammar should migrate to parse_target() — it is now documented contract, not reverse-engineered tmux syntax.

Verification

• Full suite green twice — with TMUX in the env and with env -u TMUX (this dev box runs the agent inside tmux).
• grep -rn 'f"={' src/bmad_loop → only backend files (tmux_base.py) and the seam default itself.
• Full trunk check clean.

Follow-up: a small separate PR renames the seam-backed-but-tmux-named helpers (launch.tmux_available, app._tmux_missing, runs.tmux_sessions) so adapter authors aren't misled; kept out of this diff so the "zero assertions changed" property stays reviewable.

Refs: #136, #137 (stacked base), #58, #140.

Summary by CodeRabbit

• New Features

  • Added consistent window-target formatting and parsing across terminal multiplexer backends.
  • Added support for canonical session and window target references, including reusable helpers for attaching to control and agent sessions.
  • Improved backend handling of canonical and native target identifiers.

• Documentation

  • Documented target representation, resolution, and backend customization guidance.
  • Added changelog details for the new target contract.

• Tests

  • Added coverage for target encoding, decoding, round trips, edge cases, and native identifiers.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4ba08282-07e4-4b50-8ed5-11862b69c6b7

📥 Commits

Reviewing files that changed from the base of the PR and between 8ed66e8 and a3998f8.

📒 Files selected for processing (9)

• CHANGELOG.md
• docs/adapter-authoring-guide.md
• src/bmad_loop/adapters/herdr_backend.py
• src/bmad_loop/adapters/multiplexer.py
• src/bmad_loop/adapters/tmux_base.py
• src/bmad_loop/runs.py
• src/bmad_loop/tui/app.py
• src/bmad_loop/tui/launch.py
• tests/test_multiplexer.py

---

Walkthrough

The multiplexer seam now owns canonical =session[:window] target encoding and decoding. Herdr delegates parsing to the shared decoder, while run attachment and TUI control-session flows use centralized target helpers. Documentation and tests describe and validate the contract.

Changes

Canonical target handling

Layer / File(s)	Summary
Define and validate the target contract src/bmad_loop/adapters/multiplexer.py, src/bmad_loop/adapters/tmux_base.py, tests/test_multiplexer.py	Adds canonical target encoding and decoding, clarifies target-taking method contracts, and tests grammar, inheritance, round-tripping, edge cases, and native identifiers.
Delegate Herdr target parsing src/bmad_loop/adapters/herdr_backend.py	Herdr uses parse_target() for canonical tokens while preserving native IDs and existing resolution semantics.
Route callers through canonical helpers src/bmad_loop/runs.py, src/bmad_loop/tui/launch.py, src/bmad_loop/tui/app.py, docs/adapter-authoring-guide.md, CHANGELOG.md	Run attachment and TUI control-session paths use canonical target helpers; documentation and changelog entries describe the updated contract.

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

Suggested reviewers: dracic

Poem

A bunny hops through targets bright,
=session:window lands just right.
Parsers share the trail they know,
Herdr follows in the flow.
TUI paths bloom, consistent and neat—
Ears up for this seam-canonical feat!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: introducing seam-canonical window targets in the multiplexer layer.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mux-target-contract

---

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.}

[pbean]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[pbean]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.