Native-Windows psmux multiplexer backend: re-land as a thin leaf over the dialect seams

[dracic]

Context

PR #19 (feat/psmux-backend) was the exploratory implementation of a native-Windows terminal-multiplexer backend driving psmux's tmux.exe drop-in (ConPTY, no WSL). It proved the approach end-to-end — real dev sessions ran on native Windows — but it was closed rather than merged: it predates the bmad-loop rename and the adapter seams, and exercising it surfaced engine-level defects that had to land on main first. This issue tracks re-landing the backend as a fresh, thin leaf on top of today's seams.

What the test PR/branch surfaced

• Engine died on uncaught adapter exceptions — a list-windows timeout leaked subprocess.TimeoutExpired out of the polling loop and killed the engine mid-run. Fixed on main: crash recording + multiplexer seam honesty (0.7.9/0.7.10).
• Completion misread → destructive auto-rollback — spec status sampled mid-transition; git reset --hard erased commits the attempt itself made. Fixed on main: fix(engine): preserve an attempt's commits before auto-rollback hard … #29 (preserve attempt commits, follow-ups Cap the lifecycle of attempt-preserve/* recovery refs (follow-up to #29) #32/Cap the lifecycle of refs/attempt-preserve-dirty/* worktree-snapshot refs (follow-up to #32) #49 → PRs feat(scm): bounded retention for attempt-preserve recovery refs #50/feat(scm): bounded retention for attempt-preserve-dirty worktree-snapshot refs #54), fix(engine): bound workflow-session stall nudges + spell out the completion contract #44 (completion contract). Residual completion/durability reports tracked in [BUG] result.json written and complete, but copilot session never signals Stop — hangs to session_timeout, discards work on rollback #34/[BUG] Dev session reported completed from the idle-poll shortcut while the agent window is still alive #48/[BUG] find_result_artifact / parse_auto_run_result treat a fence-quoted heading as a real terminal section #52/[BUG] Completed dev session not persisted before post_session hooks/verification (session-end durability gap) #57.
• Windows process/signal hazards — os.kill(pid, 0) is CTRL_C_EVENT on win32 (phantom KeyboardInterrupts), PID reuse, unreadable-but-existing PIDs. Fixed on main: WindowsProcessHost, persisted PID identity, identity-aware liveness (engine.pid: verify process start-time identity to defend against PID reuse #12, fix(process): identity-aware liveness and win32 console-ctrl safety #30, win32 liveness: bias identity read to alive/unknown on an unreadable-but-existing pid (ACCESS_DENIED) — follow-up #2 to #30 #33, CLI resolve/delete/archive: surface unknown liveness (win32) — TUI/CLI parity follow-up to #36 #38).
• psmux behavioral divergences (verified against the 3.3.6 source and live probes, not assumed from docs): cp1252 garbles -F output; no /bin/sh for the parked-window recipe; the nesting guard silently no-ops new-session from inside a pane (exit 0, nothing created); kill-session -t =name is silently ignored (plain name works); agent-teams env vars are injected at the server level; no native cat for pipe-pane.

Preparation that already landed on main

• Multiplexer _run seam: let subclasses set output encoding and per-call env without reimplementing the spawn primitive #40/refactor(adapters): let tmux _run carry output encoding and per-call env #41 — _run spawn seam carries output decoding (_ENCODING class attr) and a per-call env; no _run override needed.
• Tmux-family base: factor the shell-dialect wrapper out of new_window/new_parked_window into overridable hooks #46/refactor(adapters): extract the shell-dialect seam from new_window/new_parked_window #47 — shell-dialect hooks (_shell_wrap, _join_argv, _source_prefix, _parked_trailer, _window_launch + the _EXIT_CAPTURE/_ECHO/_PARK fragments), designed so a non-POSIX leaf overrides string fragments, never a contract method body.
• ci: parallelize pytest with xdist, trim PR windows matrix, add job timeouts #42 — Windows CI lane + POSIX/win32 test gating.
• docs/adapter-authoring-guide.md and docs/porting-to-a-new-os.md.

Fresh verification on live psmux 3.3.6 (claude CLI 2.1.200, Windows 11 26200)

• Quoted command strings do not survive the tmux→ConPTY→shell layers: psmux joins trailing argv and runs it through an outer shell, so embedded quoting is lost. Window scripts must travel as pwsh -NoProfile -EncodedCommand <base64 UTF-16LE> — no quotes to lose.
• new-session -e VAR=val propagates to later windows; new-window -e is accepted but silently not applied — per-window env must ride an in-source $env:K='v' prelude.
• PSMUX_ALLOW_NESTING=1 bypasses the nesting guard (the documented knob) — one added env var on the create call instead of stripping PSMUX_SESSION/PSMUX_ACTIVE/TMUX.
• Windows inherit the full env of the process that cold-started the server (including any Claude-Code session vars) plus the injected agent-teams vars — so every launched window's source starts by clearing the teammate-mode vars.
• Two previously-suspected external blockers did not reproduce: CLI startup inside a psmux window is fine, and session transcripts persist with TMUX set (print mode; one interactive spot-check remains).

Plan

Additive leaf src/bmad_loop/adapters/psmux_backend.py (~190 lines), no contract-method-body overrides beyond the documented divergences:

1. _ENCODING = "utf-8" plus a small platform-neutral base addition: an _ERRORS class attr (default None = strict, POSIX byte-identical) forwarded to subprocess.run, so a stray ConPTY byte degrades one character instead of raising out of every read.
2. Dialect hooks: _EXIT_CAPTURE = "$ec = $LASTEXITCODE", _ECHO = "Write-Host", _PARK = "Read-Host"; _join_argv → & 'a' 'b' (single-quote escaped); _shell_wrap → pwsh -NoProfile -EncodedCommand; _parked_trailer re-expressed in pwsh (same tmux verbs); _window_launch → teammate-clear + validated env prelude + explicit call, wrapped via _shell_wrap.
3. Divergent methods: new_session spawns with PSMUX_ALLOW_NESTING=1 layered on the parent env; kill_session uses plain -t name; pipe_pane attaches a best-effort pwsh Add-Content sink; available() requires psmux + tmux + pwsh on PATH.
4. Registration: register_multiplexer("psmux", platform == "win32", …) — WSL reports linux and stays on tmux.
5. Deterministic unit tests (mocked spawn seam, green on every OS: encoded-pwsh construction, nesting-guard env, plain-name kill, selection matrix) + a live smoke on a Windows host.
6. Interactive-only follow-up: verify attach -t / switch-client -t targeting and the parked return-trailer on a real client (3.3.6 source says both work; needs a human at a terminal).

[dracic]

Update: pipe_pane is a no-op on psmux 3.3.6 (upstream psmux/psmux#440) — not a blocker

Live smoke of the fresh leaf surfaced that the Plan's step-3 "best-effort pwsh Add-Content sink" for pipe_pane cannot actually capture anything on psmux 3.3.6 — and the cause is upstream, not our sink.

Finding (source + behavior): psmux's pipe-pane spawns the pipe command but never feeds pane output to it. PipePaneState (src/types.rs) is {pane_id, process, stdin, stdout} and the child's stdin handle is never even taken out of process; nothing in the tree writes pane bytes into it. A window streaming one line every 400 ms left the log file at 0 bytes for its whole life. Separately, pipe-pane -t <target> is unparsed — the target value leaks into the shell command and the active pane is piped instead. Filed upstream as psmux/psmux#440 (two defects; the -o toggle handling was audited and matches tmux, so it's excluded).

Why it does not block re-landing the backend: completion and crash detection are independent of the pane log. A normal turn completes on Stop + the on-disk result artifact, and death is detected via window_alive — both on-disk/transport signals, no dependency on tee'd pane text. The pane log only feeds the dev adapter's stall heuristic (re-arming the idle-grace window on log growth), and only inside a result-less-Stop grace window, which is itself backstopped by the wake-nudge budget and bounded by the session timeout. Worst case on Windows is a rare false "stalled" on a long silent post-turn stream — a degraded heuristic, not lost completions or data.

Plan adjustment: land the backend as specced; pipe_pane stays wired but is documented as a psmux no-op pending #440. If an upstream psmux release fixing #440 does not arrive soon, the fallback is to make the stall heuristic's activity probe independent of pipe-pane: sample capture-pane -p on the dev adapter's idle tick and hash it as the activity signature, instead of reading the tee'd log size. That restores full Windows stall sensitivity without waiting on psmux, and is a small, isolated follow-up (touches only the activity-probe helper) rather than a change to the adapter contract. We'll track the psmux release and pick the poll fallback if #440 stalls.