feat: Pi adapter + cmux sink; fix: paste in attached sessions

[dev-jelly]

Summary

Draft. Bundles four related pieces of work that expand muxa's agent + surface coverage. Opening as a single draft for early review; happy to split into focused PRs (Pi adapter / cmux sink / paste fix) before marking ready if reviewers prefer — the four commits are independent and cherry-pickable.

Commit	Type	What
5ccd506	feat	Pi coding agent adapter (AgentKind::Pi, init wizard component, TS extension installer)
0c6d940	fix	Pi wiring: // marker fence + bake absolute muxa path into the extension
dbbcb1a	feat	cmux notification sink (SurfaceKind::Cmux, $CMUX_SURFACE_ID detection, cmux notify)
5ad0129	fix	Support paste (Cmd+V) in attached muxa sessions

1. Pi coding agent adapter

Pi (@earendil-works/pi-coding-agent) has no shell-hook system; it exposes an in-process TypeScript extension API. This mirrors the opencode plugin-first model: a small extension at ~/.pi/agent/extensions/muxa/index.ts forwards one JSON blob per lifecycle signal to muxa hook pi --event event, and PiAdapter discriminates on Pi's native event names (session_start, before_agent_start, tool_execution_start/end, turn_end, agent_end, …) rather than inventing private terms.

• AgentKind::Pi wired into all exhaustive match sites (process_tree, ohmyprompt source/cli mapping, discovery).
• Init wizard auto-detects ~/.pi/agent and installs the extension via the marker-block upsert pattern (symmetric install/uninstall, preserves user-appended content).
• Heartbeat cadence is turn-bounded (turn_end) to keep daemon churn low; model + cost ride on the same heartbeat.
• Extension spawns muxa detached + unref() so a down muxad never blocks the agent loop; all errors swallowed by design (observability must never break the agent).

Verified live against a real Pi session: muxa status shows kind=pi, real session UUID, model + last_prompt captured, state transitions correct.

2. Pi wiring fixes (uncovered in live testing)

Two bugs that silently dropped every Pi event before these fixes:

1. Marker fence — the extension installs into a .ts file but marker.rs hard-coded the shell-style # fence, which is a syntax error in TypeScript. Pi's jiti loader rejected the whole extension at 1:0 with ParseError. Generalized to CommentStyle::{Hash, Slash}; kept upsert/remove as byte-identical Hash wrappers so tmux/opencode callers are unaffected.
2. Bare muxa spawn — the extension spawned a bare muxa, relying on Pi's process PATH. But ~/.cargo/bin is typically absent there, so every spawn hit ENOENT and the fire-and-forget handler swallowed it — zero events, zero logs. Added util::locate_muxa() (mirrors launchd::locate_muxad: PATH → ~/.cargo/bin → homebrew → fallback) and substitute __MUXA_BIN__ at install time so the installed file carries an absolute path.

3. cmux notification sink

Surfaces agent state transitions to the cmux native macOS multiplexer's sidebar via cmux notify. When an agent transitions into an attention-needing state (WaitingInput / WaitingChoice / Error by default), muxa runs:

cmux notify --title <kind> --subtitle <state> --body <prompt> --surface <id>

• Targeting: hook adapter detects $CMUX_SURFACE_ID and attaches SurfaceRef{Cmux}. Notifications fire only when a concrete cmux surface is aimable; agents under tmux/zellij are skipped.
• Surface identity is additive — CMUX_SURFACE_ID does not suppress host pane lookup (only MUXA_SESSION_ID does). An agent can run in tmux nested inside cmux; the two identities are independent. Decoupling avoids a footgun where leaking CMUX_SURFACE_ID into subprocesses blanks the pane used for recap/status-line.
• New SurfaceKind::Cmux is safe to add: all existing SurfaceKind match sites are == Pty equality checks, no exhaustive matches.
• Shape mirrors the webhook sink: best-effort, in-task per-(kind, session, state) rate limit, bounded mpsc decouples broadcast drain from spawn latency, 10s spawn timeout so a wedged cmux app can't freeze the sink loop.
• Binary resolved via PATH (or [sinks.cmux].binary override), validated at startup so a missing cmux surfaces immediately instead of silently no-op'ing.

Config:

[sinks.cmux]
enabled = true
# binary = "/path/to/cmux"
# on_states = ["WaitingInput", "Error"]
# rate_limit_secs = 60

All four shell-hook agents (pi/claude/codex/gemini) inherit cmux surface detection for free via the shared run_hook path.

4. Paste (Cmd+V) in attached sessions

muxa run <cmd> attaches by relaying crossterm key events from stdin to the muxa-owned PTY. Paste was broken three ways:

1. No bracketed-paste negotiation with the parent terminal, so clipboard pastes never arrived as a discrete event.
2. Event::Paste was dropped by the catch-all arm in attach_session_loop.
3. key_to_pty_input ignored the SUPER (Cmd) modifier, so when the terminal did surface Cmd+V it emitted a literal v into the PTY.

Fixes: enable bracketed paste on attach (\x1b[?2004h) and restore on exit, relay Event::Paste payloads to the PTY with LF -> CR conversion, drop SUPER combos from key_to_pty_input.

Test plan

• cargo fmt --check clean
• Workspace tests green (760)
• Live Pi session: muxa status shows correct kind/session/model/prompt/state
• cmux sink: notification lands on the originating surface for WaitingInput; tmux agents skipped
• Reviewer: confirm whether to keep as one PR or split (Pi / cmux / paste)

Known follow-ups (not blocking draft)

• Adapter has defensive arms for permission_asked / waiting_input that the shipped extension does not yet emit — kept for forward-compat, could use a // forward-compat comment.
• Bracketed-paste disable lives in a separate block next to attach_session_loop rather than inside RawModeGuard's Drop; fine for the normal path, but folding it into the guard would make panic/early-return recovery automatic.

[dev-jelly]

Pushed review fixes in 4029296. All six findings addressed:

#	Finding	Fix
P1	New wire variants break v3 clients (empty snapshot)	Bump PROTOCOL_VERSION 3 → 4; extend downgrade_wire: pi → unknown, cmux → pty for protocol < 4. New test v3_hello_downgrades_pi_and_cmux_in_snapshot.
P1	Multi-line paste executes each line	Re-wrap Event::Paste payload in CSI 200~ / CSI 201~ framing before writing to the child PTY.
P1	Pi lifecycle events arrive out of order	Route every muxa hook pi spawn through a single promise chain (deliveryChain); callbacks only append (non-blocking), each step resolves on child exit/close/error or a 5s unref'd timeout.
P2	last_response never populated	extractText() walks AssistantMessage.content blocks and concatenates text blocks.
P2	Cost regresses on cheaper turns	Accumulate per-turn cost in a module counter, reset on session_start, forward the cumulative total.
P2	muxa timeline --agent pi / /api/timeline?agent=pi rejected	Added Pi to AgentKindArg and parse_agent_kind.

cargo fmt clean, workspace tests green (incl. new downgrade test), clippy clean on touched files.

Review doc kept at docs/CODE_REVIEW.md for traceability.