feat(agent): experimental Claude (Interactive) backend (tmux + sidecar host)

.github/copilot-instructions.md

@@ -1,9 +1,11 @@
 # Claudette Repository Instructions
 
-Claudette is a cross-platform desktop orchestrator for parallel Claude Code agents. It uses a Tauri 2 Rust backend, a React/TypeScript frontend, SQLite via rusqlite, Tokio process management, git worktrees, xterm.js terminals, Lua plugins, and a local CLI that talks to the running GUI over IPC.
+Claudette is a cross-platform desktop orchestrator for parallel Claude Code agents. It uses a Tauri 2 Rust backend, a React/TypeScript frontend, SQLite via rusqlite, Tokio process management, git worktrees, xterm.js terminals, Lua plugins, and a local CLI that talks to the running GUI over IPC. A fifth workspace crate, `claudette-session-host` (`src-session-host/`), is a bundled sidecar that owns interactive Claude PTYs via `portable-pty` — required on Windows and an opt-in Unix fallback when tmux is unavailable.
 
 Follow the existing architecture. Core behavior belongs in the `claudette` crate under `src/`. `src-tauri/src/commands/` should stay thin Tauri wrappers. Shared data types belong in `src/model/` and must derive `Serialize`. Frontend state lives in Zustand slices under `src/ui/src/stores/slices/`, not ad hoc globals.
 
+The chat-send resolver dispatches on a per-backend `runtime_harness` (`AgentBackendConfig::effective_harness` in `src/agent_backend.rs`), not on `AgentBackendKind` directly. A second Anthropic harness, `AgentHarnessKind::ClaudeInteractive` (`src/agent/claude_interactive.rs`), runs the real `claude` TUI inside a long-lived PTY — gated behind the `claudeInteractiveEnabled` experimental flag and surfaced as the "Claude (Interactive)" card in Settings > Models > Runtime. Two hosts back it: `TmuxHost` (Unix, when `tmux >= 3.4` is available and the flag is on) and `SidecarHost` (Windows + opt-in Unix), both implementing `InteractiveHost` in `src/agent/interactive_host/`. The framed JSON wire protocol with the sidecar lives in `src/agent/interactive_protocol.rs`. Turn boundaries flow over Claude Code hooks: the `claudette chat hook` CLI subcommand sends a `chat_hook` IPC request that `AppState::dispatch_interactive_hook` routes into per-session channels, which the frontend assembler (`useInteractiveTurnAssembler`) turns into per-turn xterm.js views (`InteractiveTurnView` and friends in `src/ui/src/components/chat/`, with `services/interactive.ts` as the Tauri bridge). The interactive surface lives in sibling files next to `ChatPanel.tsx` (a god file) — keep new runtime-specific UI in dedicated components, not inside ChatPanel. **Known limitation:** `SidecarHost` does not yet recover from a dropped sidecar connection — the cached `ConnHandle` in `OnceCell` is never reset, so if `claudette-session-host` exits (e.g., its 600s idle timer fires) while Claudette is still running, subsequent `interactive_*` commands fail with "conn closed" errors until Claudette is restarted. Tracked as follow-up work.
+
 Treat regressions as the main risk. Before changing behavior, identify the current contract: persisted DB fields, Tauri command payloads, CLI output, plugin manifests, settings keys, localized strings, terminal/session semantics, worktree behavior, and visible UI workflows. Do not remove, rename, or silently reinterpret any of these unless the task explicitly asks for that change.
 
 If a behavior change is intentional, call it out plainly in the PR summary or review response and add/update tests that pin the new behavior. If the change was incidental, preserve compatibility instead.
@@ -14,7 +16,7 @@ Control god files. Do not make already-large files the default destination for n
 
 When touching a god file, keep the diff surgical or extract cohesive behavior first. New code should reduce or isolate complexity, not add another unrelated responsibility.
 
-Use the repo's tools. Rust CI expects `cargo fmt --all --check`, `cargo clippy -p claudette -p claudette-server -p claudette-cli --all-targets --all-features` with `RUSTFLAGS=-Dwarnings`, tests for the same three crates on Linux (run via `cargo llvm-cov -p claudette -p claudette-server -p claudette-cli --all-features` for coverage), and `scripts/stage-cli-sidecar.sh --profile debug` followed by `cargo test -p claudette-tauri --no-default-features --features devtools,server,voice,alternative-backends,pi-sdk --no-run` with Linux Tauri system libraries installed (`--no-run` compiles the binary crate's test targets so a broken `claudette-tauri` test fixture is caught — the coverage `test` job only builds `claudette` / `-server` / `-cli`). The Tauri check should stay cache-friendly: use the shared Rust cache and Bun package cache for Pi harness sidecar staging instead of release-building extra artifacts. A separate macOS job also runs `cargo clippy -p claudette-mobile --target aarch64-apple-darwin --all-targets --locked` and `cargo test -p claudette-mobile --locked`. Frontend CI expects `cd src/ui && bun install --frozen-lockfile`, `bunx tsc --noEmit`, `bun run lint:css`, `bun run build`, and `bun run test` (ESLint via `bun run lint` is available locally but not run in CI).
+Use the repo's tools. Rust CI expects `cargo fmt --all --check`, `cargo clippy -p claudette -p claudette-server -p claudette-cli --all-targets --all-features` with `RUSTFLAGS=-Dwarnings`, tests for the same three crates on Linux (run via `cargo llvm-cov -p claudette -p claudette-server -p claudette-cli --all-features` for coverage), and `scripts/stage-cli-sidecar.sh --profile debug` followed by `cargo test -p claudette-tauri --no-default-features --features devtools,server,voice,alternative-backends,pi-sdk --no-run` with Linux Tauri system libraries installed (`--no-run` compiles the binary crate's test targets so a broken `claudette-tauri` test fixture is caught — the coverage `test` job only builds `claudette` / `-server` / `-cli`). The Tauri check should stay cache-friendly: use the shared Rust cache and Bun package cache for Pi harness sidecar staging instead of release-building extra artifacts. A separate macOS job also runs `cargo clippy -p claudette-mobile --target aarch64-apple-darwin --all-targets --locked` and `cargo test -p claudette-mobile --locked`. CI also runs the Claude Interactive patch-coverage gate via `scripts/coverage-interactive.sh` + `scripts/check-coverage-interactive.sh` — informational until Task G1 flips it blocking at >=85% line coverage. Frontend CI expects `cd src/ui && bun install --frozen-lockfile`, `bunx tsc --noEmit`, `bun run lint:css`, `bun run build`, and `bun run test` (ESLint via `bun run lint` is available locally but not run in CI).
 
 Always run `cd src/ui && bunx tsc -b` after TypeScript changes. Vitest uses esbuild and does not type-check the project.
 

.github/workflows/ci.yml

@@ -148,6 +148,16 @@ jobs:
           slug: utensils/claudette
           files: lcov.info
           fail_ci_if_error: false
+      # Claude Interactive patch-coverage gate (blocking — Task G1).
+      # See scripts/check-coverage-interactive.sh and CLAUDE.md. Files
+      # excluded from the gate (e.g. tmux.rs, sidecar.rs) are documented
+      # inline in the check script with their structural rationale.
+      - name: Run llvm-cov (interactive patch JSON)
+        run: ./scripts/coverage-interactive.sh
+      - name: Check interactive patch coverage
+        env:
+          COVERAGE_GATE_BLOCKING: "1"
+        run: ./scripts/check-coverage-interactive.sh
 
   frontend:
     name: Frontend
@@ -165,6 +175,10 @@ jobs:
       - run: bun run lint:css
       - run: bun run build
       - run: bun run test
+      # Claude Interactive patch-coverage gate for the frontend (blocking —
+      # Task G1). Per-file thresholds live in `vitest.config.ts` and vitest
+      # exits non-zero if any of them regresses.
+      - run: bun run test:coverage:interactive
 
   frontend-smoke:
     name: Frontend Bundle Smoke