refactor(mux)!: extract the herdr backend to pbean/bmad-loop-adapter-herdr

CHANGELOG.md

@@ -67,39 +67,19 @@ breaking changes may land in a minor release.
   `TerminalMultiplexer` seam instead of living as hand-assembled tmux syntax in core: a new
   concrete `target(session, window=None)` encoder (overridable per backend, tmux inherits the
   default and passes it straight through) and a module-level `parse_target()` decoder that
-  native-id backends reuse instead of re-deriving the grammar (the herdr backend's
-  `_parse_target` now delegates to it). `runs.py`/`tui/launch.py`/`tui/app.py` format every
+  native-id backends reuse instead of re-deriving the grammar (the out-of-tree herdr
+  adapter's `_parse_target` delegates to it). `runs.py`/`tui/launch.py`/`tui/app.py` format every
   target via `target()` (new `runs.session_target` / `launch.ctl_target` helpers) — output is
   byte-identical, so no backend or operator behavior changes; the contract is documented in the
   adapter authoring guide's new "Window targets" section.
-- **Herdr TUI-launch surface.** The herdr backend now covers everything `tui/launch.py` drives:
-  parked orchestrator windows (a typed `exec sh -c '<argv>; banner; read; trailer'` recipe,
-  tmux-identical from the operator's seat, with the return-to-origin target mirrored into a
-  per-window return file the trailer consumes), tmux-style `=session[:window]` target parsing
-  across select/kill/option/attach methods, `list_windows` tmux-field mapping
-  (`window_id`/`window_name`/`@option`), finalized `attach_target_argv` (blocking
-  `terminal attach` outside herdr, fire-and-forget `tab focus` inside), and `switch_client`
-  via `tab focus`. The TUI/CLI attach flows and `in_ctl_session` now ask the seam
-  (`current_pane_id()`/`current_session()`) instead of sniffing `TMUX`, so they work under any
-  backend; the tmux backend's `current_*` gained the TMUX guard that keeps "not inside" honest.
-  Remaining herdr degradations: `detach_client` stays a no-op (the post-exit detach return rides
-  pane-close ending `terminal attach`; only the mid-process hand-back degrades to staying
-  attached), and `switch_client` has no last-client fallback.
-- **Herdr multiplexer backend (opt-in, non-tmux-family).** A new `herdr` transport implements
-  the `TerminalMultiplexer` seam _fresh_ (subclassing nothing) over
-  [herdr](https://herdr.dev)'s cross-platform workspace/tab/pane model — Unix socket on POSIX,
-  named pipe on Windows — a step toward native Windows (#92) plus herdr's agent-status sidebar for
-  watching runs. Opt in per run with `BMAD_LOOP_MUX_BACKEND=herdr` or persist with
-  `bmad-loop mux set herdr`; `_PLATFORM_DEFAULTS` is untouched, so tmux stays the POSIX default and
-  herdr activates on win32 only by first-match until psmux ships. This PR is the **engine run
-  path**: session→workspace / window→tab mapping, an `exec`-based launch with tmux-identical
-  window-death, a content-hash-gated polling `pipe_pane` tee (herdr has no tee), JSON-sidecar
-  session/window options (herdr has none; writes lock-guarded via a new cross-platform
-  `platform_util.file_lock`), lazy server autostart, and a protocol-version guard
-  (fail-below / warn-above). Landed as one registration line plus one sanctioned `probe.py` gate
-  fix — zero portability-guard allowlist changes. The TUI-launch surface landed as a second PR
-  (previous entry); the remaining degradations are in the backend module docstring's ledger and,
-  operator-facing, in `docs/multiplexer-backends.md`.
+- **Herdr multiplexer backend — shipped out-of-tree.** A complete non-tmux-family
+  `TerminalMultiplexer` backend for [herdr](https://herdr.dev)'s cross-platform
+  workspace/tab/pane model was developed in-tree (engine run path #136, TUI-launch surface
+  #137) and extracted before ever shipping in a release to
+  [`bmad-loop-adapter-herdr`](https://github.com/pbean/bmad-loop-adapter-herdr), where it
+  co-installs with bmad-loop and registers through the `bmad_loop.mux_backends` entry-point
+  discovery above. Core bundles only tmux; herdr's capabilities, remaining degradations, and
+  operator notes live in the adapter repo's docs.
 - **Stories mode — a second planning pipeline that drives the loop off a typed `stories.yaml` (folder+id dispatch) instead of `sprint-status.yaml`.** Opt in with `[stories] source = "stories"` + `spec_folder`, or per run with `bmad-loop run --spec <folder>` (overrides policy); `--story` then filters by story id. Each entry dispatches by folder + id — the dev skill creates-or-resumes the story spec at `<folder>/stories/<id>-<slug>.md` and the orchestrator reads that id-keyed path back deterministically (no shared board to line-edit, no result-artifact mtime-scan). Strictly linear schedule (list order, no `depends_on`); `bmad-loop run --dry-run --spec <folder>` and `bmad-loop status` print the board (id · live disk state · checkpoint markers · title). Sprint mode is unchanged and remains the default. Requires a `bmad-dev-auto` new enough for folder+id dispatch — the run preflight checks and remediates.
 - **Per-story human checkpoints (stories mode).** Independent `spec_checkpoint` (pause before code to review the plan — dev halts at `ready-for-dev`; approve to implement, or request a replan that resets the spec to `draft`) and `done_checkpoint` (pause after the story commits, skipped when it is the last story); both additive to `gates.mode`. A blocked story escalates + resolves as in sprint mode, with a pre-planning-halt sentinel auto-deleted (a copy preserved under the run dir) on re-arm.
 - **TUI human-in-the-loop surface for stories mode.** The sprint tree is replaced by a stories board (id · live disk state · spec/done checkpoint markers · title) when a stories-mode run is selected; paused runs carry a per-run pause-kind badge and the run list shows a global _⚑ N need attention_ count; `p` opens the stage-appropriate viewer — plan-checkpoint spec review (Approve & resume / Request replan), story-checkpoint summary card (Continue / Stop), escalation with story context (Resolve / Re-arm & resume), and a gate spec viewer that the existing spec-approval/epic pauses reuse. The start-run modal gains a source select + spec-folder field with a live schedule preview. Every TUI action calls the same code paths as the CLI.
@@ -131,14 +111,12 @@ breaking changes may land in a minor release.
 PATH)`, the TUI notifies `multiplexer backend unavailable — launch/attach disabled` and
   `launched (control session bmad-loop-ctl)`, and the "attach to … bmad-loop-ctl" hints say
   _control session_. The TUI-guide troubleshooting table matches. Behavior is unchanged.
-- **Docs: operator guide for the herdr backend (`docs/multiplexer-backends.md`).** The user-facing
-  docs no longer claim tmux is the only multiplexer backend. The new page covers backend selection
-  (`bmad-loop mux` / `mux set`) and what changes from the operator's seat on herdr — chiefly that
-  herdr has no CLI detach, so the automatic hand-back after answering an attached sweep decision
-  becomes a manual `ctrl+b q`; the rest (polled session logs, the `~/.bmad-loop/herdr-state.json`
-  sidecar, advisory geometry, lazy server autostart, no last-client fallback) is emulated to parity
-  or cosmetic. README, setup guide, TUI guide, and FEATURES now name both backends and link the
-  page.
+- **Docs: multiplexer backend guide (`docs/multiplexer-backends.md`).** The user-facing docs no
+  longer claim tmux is the only multiplexer backend. The new page covers backend selection
+  (`bmad-loop mux` / `mux set`) and how external backends are installed and discovered;
+  backend-specific operator guidance (what changes from your seat on herdr, its degradations)
+  moved out with the extraction and lives in each adapter repo's docs. README, setup guide,
+  TUI guide, and FEATURES name the mechanism and link the page.
 - **Docs: `followup_review_recommended` is now scored upstream.** BMAD-METHOD#2580 replaced the
   skill's convergence-prone significance judgment with a severity-weighted score over patched
   findings and added a fourth default review layer (Intent Alignment Auditor, #2560). README,

README.md

@@ -38,8 +38,8 @@ Inspired by the original [bmad-automator](https://github.com/bmad-code-org/bmad-
 
 ## Requirements
 
-- **Python 3.11+**, **tmux**, and a supported coding CLI — `claude` by default; `codex`, `gemini`, `copilot`, and `antigravity` (`agy`) via [profiles](#other-coding-clis).
-- **Linux or macOS** (or **Windows via WSL**, which _is_ Linux — it runs as-is). tmux is the default of the two bundled terminal-multiplexer backends (the opt-in [herdr](docs/multiplexer-backends.md) is the other), and both sit behind a pluggable **registry** of OS seams (transport, process lifecycle, hook interpreter) with availability-aware selection — env var → persisted `[mux] backend` choice (`bmad-loop mux set <name>`) → platform default (`psmux` on Windows, `tmux` elsewhere) → first available platform match — so a native-Windows backend slots in as new files + a registration line each, with no engine edits — see [Porting bmad-loop to a new OS](docs/porting-to-a-new-os.md). Native Windows is not yet shipped.
+- **Python 3.11+**, a **terminal multiplexer** (tmux is the bundled default), and a supported coding CLI — `claude` by default; `codex`, `gemini`, `copilot`, and `antigravity` (`agy`) via [profiles](#other-coding-clis).
+- **Linux or macOS** (or **Windows via WSL**, which _is_ Linux — it runs as-is). tmux is the bundled terminal-multiplexer backend (externals like the [herdr adapter](https://github.com/pbean/bmad-loop-adapter-herdr) co-install as packages and self-register — see [Terminal multiplexer backends](docs/multiplexer-backends.md)), and all of it sits behind a pluggable **registry** of OS seams (transport, process lifecycle, hook interpreter) with availability-aware selection — env var → persisted `[mux] backend` choice (`bmad-loop mux set <name>`) → platform default (`psmux` on Windows, `tmux` elsewhere) → first available platform match — so a native-Windows backend slots in as new files + a registration line each, with no engine edits — see [Porting bmad-loop to a new OS](docs/porting-to-a-new-os.md). Native Windows is not yet shipped.
 - A **BMAD v6 project** (`_bmad/bmm/config.yaml`, a `sprint-status.yaml` from `bmad-sprint-planning`) with the upstream `bmad-dev-auto` skill (and the three review-hunter skills its step-04 invokes inline: `bmad-review-adversarial-general`, `bmad-review-edge-case-hunter`, `bmad-review-verification-gap`) and the bmad-loop skill module from this repo installed (`bmad-loop-resolve`, `bmad-loop-sweep` — see [Installing the skill module](#installing-the-skill-module)). Standard BMAD skills stay untouched.
 
 ## Quick start
@@ -493,7 +493,7 @@ Each run drives its agents inside a dedicated tmux session, `bmad-loop-<run-id>`
 
 ## Other coding CLIs
 
-One generic driver (`adapters/generic.py`) runs any coding CLI that fits the injection + hook-signal transport; everything CLI-specific lives in a declarative **profile** (`adapters/profile.py`), and the terminal transport itself sits behind a pluggable `TerminalMultiplexer` seam (tmux by default, herdr opt-in — see [Terminal multiplexer backends](docs/multiplexer-backends.md)). Built-in profiles ship as TOML in `bmad_loop/data/profiles/`:
+One generic driver (`adapters/generic.py`) runs any coding CLI that fits the injection + hook-signal transport; everything CLI-specific lives in a declarative **profile** (`adapters/profile.py`), and the terminal transport itself sits behind a pluggable `TerminalMultiplexer` seam (tmux bundled; external backends like the herdr adapter install as packages — see [Terminal multiplexer backends](docs/multiplexer-backends.md)). Built-in profiles ship as TOML in `bmad_loop/data/profiles/`:
 
 | Profile       | Status                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | ------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |