Phase 2: Architecture & maintainability improvements (#4)

* refactor: consolidate 6 per-session maps into sessionHandle struct

Replaces sessions, ptys, cmds, doneChans, frameDetectors, and
responders maps with a single handles map[string]*sessionHandle.
Eliminates the risk of map synchronization drift across handlers.

* refactor: remove Session struct, promote fields into sessionHandle

Eliminates the intermediate Session struct that duplicated SessionMeta
fields. All session state now lives directly in sessionHandle, removing
one layer of indirection and a source of state drift.

* refactor: extract waitForSettle helper from handleSnapshot

Deduplicates the two near-identical settle polling loops in
handleSnapshot into a shared helper function.

* refactor: consolidate send+wait+read into Client.Exec

Extracts the duplicated "send input, wait for output, return new
content" pattern from cmd/exec.go and mcp/tools.go into a single
Client.Exec method. Callers now use daemon.ExecOptions instead of
manually orchestrating Read/Send/ForOutput.

Also refactors MCP ToolRegistry to use registration-based pattern:
adding a tool is now a single register() call instead of coordinated
edits to List() schema, Call() switch, and handler method.

* refactor: add protocol versioning between daemon and client

Client sends ProtocolVersion=1 with every request. Daemon rejects
mismatched versions with a clear error message telling the user to
restart the daemon. Version 0 (omitted) is accepted for backward
compatibility during rollout.

* feat: add --log-file flag and panic recovery to daemon

Daemon previously ran with stdout/stderr discarded, making crash
debugging impossible. Now supports --log-file to capture logs and
redirect stderr. Added panic recovery in handleConn and captureOutput
goroutines to log stack traces instead of crashing silently.

Also fixes unparam lint: waitForSettle return value was unused.

Author: schovi

.claude/skills/tui-test/SKILL.md

@@ -38,7 +38,7 @@ The lead agent (you) does the following:
 
 ### Phase 2: Parallel Testing
 
-Spawn one teammate per app (max 5-6 concurrent to avoid system overload). Use `general-purpose` agent type with `bypassPermissions` mode.
+Spawn one teammate per app (max 5-6 concurrent to avoid system overload). Use `general-purpose` agent type with `bypassPermissions` mode and `model: "sonnet"` (cheaper, sufficient for mechanical test execution).
 
 Each teammate gets:
 - The **Teammate Test Protocol** section below (copy it fully into the prompt)

cmd/daemon.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"fmt"
+	"log"
 	"os"
 	"os/signal"
 	"path/filepath"
@@ -22,6 +23,7 @@ var (
 	daemonDataDirFlag     string
 	daemonMemoryBackend   bool
 	daemonStoppedTTLFlag  string
+	daemonLogFileFlag     string
 )
 
 var daemonCmd = &cobra.Command{
@@ -42,13 +44,27 @@ func init() {
 		"Use in-memory storage instead of file-based (no persistence)")
 	daemonCmd.Flags().StringVar(&daemonStoppedTTLFlag, "stopped-ttl", "",
 		"Auto-cleanup stopped sessions after duration (e.g., 5m, 1h, 24h)")
+	daemonCmd.Flags().StringVar(&daemonLogFileFlag, "log-file", "",
+		"Write daemon logs to file (default: discard)")
 }
 
 func runDaemon(cmd *cobra.Command, args []string) error {
 	if daemonMCPFlag {
 		return runMCPServer()
 	}
 
+	if daemonLogFileFlag != "" {
+		f, err := os.OpenFile(daemonLogFileFlag, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+		if err != nil {
+			return fmt.Errorf("open log file: %w", err)
+		}
+		defer f.Close()
+		log.SetOutput(f)
+		log.SetFlags(log.Ldate | log.Ltime | log.Lmicroseconds)
+		os.Stderr = f
+		log.Println("daemon starting")
+	}
+
 	var opts []daemon.ServerOption
 
 	if daemonDataDirFlag == "" {

cmd/exec.go

@@ -7,7 +7,6 @@ import (
 
 	"github.com/schovi/shelli/internal/ansi"
 	"github.com/schovi/shelli/internal/daemon"
-	"github.com/schovi/shelli/internal/wait"
 	"github.com/spf13/cobra"
 )
 
@@ -59,49 +58,35 @@ func runExec(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("daemon: %w", err)
 	}
 
-	_, startPos, err := client.Read(name, "all", 0, 0)
-	if err != nil {
-		return err
-	}
-
-	if err := client.Send(name, input, true); err != nil {
-		return err
-	}
-
 	var pattern string
 	var settleMs int
 
 	if hasWait {
 		pattern = execWaitFlag
-		settleMs = 0
 	} else {
-		pattern = ""
 		settleMs = execSettleFlag
 	}
 
-	output, pos, err := wait.ForOutput(
-		func() (string, int, error) { return client.Read(name, "all", 0, 0) },
-		wait.Config{
-			Pattern:       pattern,
-			SettleMs:      settleMs,
-			TimeoutSec:    execTimeoutFlag,
-			StartPosition: startPos,
-			SizeFunc:      func() (int, error) { return client.Size(name) },
-		},
-	)
+	result, err := client.Exec(name, daemon.ExecOptions{
+		Input:       input,
+		SettleMs:    settleMs,
+		WaitPattern: pattern,
+		TimeoutSec:  execTimeoutFlag,
+	})
 	if err != nil {
 		return err
 	}
 
+	output := result.Output
 	if execStripAnsiFlag {
 		output = ansi.Strip(output)
 	}
 
 	if execJsonFlag {
 		out := map[string]interface{}{
-			"input":    input,
+			"input":    result.Input,
 			"output":   output,
-			"position": pos,
+			"position": result.Position,
 		}
 		data, err := json.MarshalIndent(out, "", "  ")
 		if err != nil {

internal/daemon/client.go

@@ -7,6 +7,8 @@ import (
 	"os"
 	"os/exec"
 	"time"
+
+	"github.com/schovi/shelli/internal/wait"
 )
 
 type Client struct{}
@@ -372,6 +374,56 @@ func (c *Client) Size(name string) (int, error) {
 	return int(sizeFloat), nil
 }
 
+type ExecOptions struct {
+	Input       string
+	SettleMs    int
+	WaitPattern string
+	TimeoutSec  int
+}
+
+type ExecResult struct {
+	Input    string
+	Output   string
+	Position int
+}
+
+func (c *Client) Exec(name string, opts ExecOptions) (*ExecResult, error) {
+	_, startPos, err := c.Read(name, "all", 0, 0)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := c.Send(name, opts.Input, true); err != nil {
+		return nil, err
+	}
+
+	settleMs := opts.SettleMs
+	if opts.WaitPattern == "" && settleMs == 0 {
+		settleMs = 500
+	}
+
+	timeoutSec := opts.TimeoutSec
+	if timeoutSec == 0 {
+		timeoutSec = 10
+	}
+
+	output, pos, err := wait.ForOutput(
+		func() (string, int, error) { return c.Read(name, "all", 0, 0) },
+		wait.Config{
+			Pattern:       opts.WaitPattern,
+			SettleMs:      settleMs,
+			TimeoutSec:    timeoutSec,
+			StartPosition: startPos,
+			SizeFunc:      func() (int, error) { return c.Size(name) },
+		},
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	return &ExecResult{Input: opts.Input, Output: output, Position: pos}, nil
+}
+
 func (c *Client) send(req Request) (*Response, error) {
 	conn, err := net.Dial("unix", SocketPath())
 	if err != nil {
@@ -381,6 +433,8 @@ func (c *Client) send(req Request) (*Response, error) {
 
 	conn.SetDeadline(time.Now().Add(ClientDeadline))
 
+	req.Version = ProtocolVersion
+
 	if err := json.NewEncoder(conn).Encode(req); err != nil {
 		return nil, err
 	}

internal/daemon/constants.go

@@ -3,6 +3,8 @@ package daemon
 import "time"
 
 const (
+	ProtocolVersion = 1
+
 	ReadBufferSize       = 4096
 	KillGracePeriod      = 100 * time.Millisecond
 	ClientDeadline       = 30 * time.Second