# ConPTY Interactive Sessions — Design

Date: 2026-07-23
Status: Approved (design), implementation not started

## Problem

The current in-app interactive session path streams `stream-json` from a
`claude` process spawned **in the Worker** and renders it as a chat log with a
composer. It does not surface permission requests, AskUser questions, and other
TUI-native interactions well — the rendering is a partial reimplementation of
what the real Claude Code TUI already does. We want full fidelity for
interactive work without rebuilding the TUI.

## Decision

**Hybrid execution model:**

- **Autonomous queue tasks** (`Status=Queued`, picked by the queue): unchanged.
  Headless `stream-json`, full orchestration (status flow, diff, review, merge).
- **Interactive sessions**: an **embedded ConPTY terminal** running the real
  `claude` CLI, rendered in the **UI process**. Full TUI fidelity (permission
  prompts, questions, colors, everything the standalone CLI does). Detached from
  the review/merge/status machinery — these are a manual cockpit.

This is the third direction for interactive (external `wt` terminal → streaming
chat → embedded ConPTY). The streaming interactive stack is **removed**, not run
in parallel — accepted as discarded work in exchange for one interactive path
and full fidelity.

## Architecture

### Process location

ConPTY terminal controls render in-process and spawn their child (`claude`) as a
child of the host process. Therefore interactive sessions move **out of the
Worker and into the UI process**. They no longer flow over SignalR. This mirrors
the existing `ResumeTaskInTerminal` behavior (launch real `claude`), but embedded
instead of via external `wt.exe`.

### Worktree preparation (task-based sessions)

Interactive task sessions get the **same worktree preparation as autonomous
runs**: session-skills seeding, agent files, MCP config, environment. The Worker
performs the prep and returns a launch spec to the UI:

```
LaunchSpec {
  cwd:  string   // worktree path
  exe:  string   // resolved claude executable / shell
  args: string[] // e.g. --resume <sessionId>
  env:  Dictionary<string,string>
}
```

The command construction reuses the existing logic in
`WindowsTerminalLauncher.BuildResumeCommand`. Guards mirror
`ResumeTaskInTerminal`: task not Running/Queued, a persisted SessionId exists,
worktree exists and is Active/Kept.

### Free / ad-hoc sessions

In addition to task-based sessions, the user can open an ad-hoc terminal in a
chosen directory (no task). These also get MCP config + env set up so the
`claudedo` tools are available, but no per-level session-skills seeding tied to a
task.

### Terminal host control — RESOLVED by spike (2026-07-23)

**Library: `Iciclecreek.Avalonia.Terminal` 2.0.3** (namespace `Iciclecreek.Terminal`).
It needs Avalonia >= 12.0.2; the repo is on 12.0.4 → compatible, no bump.
`SvcSystems.UI.Terminal` (latest) needs Avalonia 12.1+ → rejected.

Visual pass (user, 2026-07-23): the real `claude` TUI renders correctly inside
the embedded control — Claude Code opened and was usable.

**Binding approach — drive Porta.Pty ourselves, reuse Iciclecreek's VT engine.**
The convenience `TerminalControl.LaunchProcess()` spawns the child itself and
never sets `PtyOptions.Environment`, and there is no settable pty/env seam on
`TerminalControl`/`TerminalView` (env-building lives in the non-virtual
`TerminalView.LaunchProcess()` using private fields). But the VT parser/renderer
is the public `XTerm.Terminal` object exposed via `TerminalControl.Terminal`, so
we reuse it without forking:

- `Porta.Pty.PtyProvider.SpawnAsync(new PtyOptions { Name, App, Cwd, CommandLine,
  Environment = <fully populated dict> }, ct)` → `IPtyConnection`.
- Do **not** call `TerminalControl.LaunchProcess()` (leaves its `_ptyConnection`
  null).
- Get `TerminalControl.Terminal` (public, `XTerm.Terminal`) after template apply.
- Pump `IPtyConnection.ReaderStream` → `Terminal.Write(text)`; subscribe
  `Terminal.DataReceived` → `IPtyConnection.WriterStream`; mirror
  `Terminal.Resized` ↔ `IPtyConnection.Resize(cols, rows)`.
- Implement our **own** exit-code / kill / wait-for-exit against our
  `IPtyConnection` — do NOT touch `TerminalControl.ExitCode`/`Pid`/`Kill()`/
  `WaitForExit()`, they NRE on the null `_ptyConnection`.

Note on environment: `Porta.Pty.SpawnAsync` already seeds the child from the
current (ClaudeDo) process environment (PATH/APPDATA/etc.) and merges
`PtyOptions.Environment` on top — so we only need to ADD our custom vars (MCP
config path, `MAX_THINKING_TOKENS`, …), not rebuild the whole environment. (The
earlier spike's "child gets zero env vars" claim was wrong.)

### Command Center layout

- `MonitorPaneView` keeps the streamed log for autonomous tasks.
- Interactive panes host the terminal control instead of the log+composer.
- Layout is **toggleable**: focus mode (tabs, one session large) ↔ overview mode
  (grid, several sessions at once).

## Removals

Worker:
- `StreamingClaudeSession`, `InteractiveSessionService`
- `WorkerHub` interactive methods: `OpenInteractiveTerminal`,
  `SendInteractiveMessage`, `RemoveQueuedInteractiveMessage`,
  `StopInteractiveSession`, `InterruptInteractiveSession`
- Broadcast events: `InteractiveSessionStarted/Ended`, `InteractiveQueueChanged`,
  `InteractiveMessageSent`
- `IdleSessionReaper` and `LiveSessionRegistry` **iff** unused elsewhere
  (verify during implementation — do not delete blindly).

UI:
- Composer on `TaskMonitorViewModel`: `ComposerDraft`, `SubmitComposerCommand`,
  `InterruptInteractiveCommand`, `StopInteractiveCommand`, `QueuedMessages`,
  `IsInteractiveLive`.
- The composer + queued-messages portion of `SessionTerminalView` (the log
  portion stays for autonomous panes).
- `IWorkerClient` interactive methods.

## Open items (implementation time)

- Whether `LiveSessionRegistry` is referenced outside the interactive path.
- Session-id availability for a never-run task (no `--resume` → start fresh).

Resolved: env approach (see Terminal host control — add custom vars on top of the
inherited process env via `PtyOptions.Environment`); library + binding seam.

## Non-goals

- No screen-scraping of terminal output back into task status/diff/review.
- No change to the autonomous queue execution path.