fix(screentracker): stop writeStabilize from fatally timing out when agents don't echo input

Phase 1 of writeStabilize waited 15s for the screen to change after
writing message text (echo detection), returning HTTP 500 if it didn't.
Many TUI agents using bracketed paste don't echo input until Enter is
pressed, causing every message send to fail.

Phase 1 timeout is now non-fatal (2s) — if the screen doesn't change,
we log at Info level and proceed to Phase 2 (send carriage return).
Phase 2 remains the real indicator of agent responsiveness.

Key changes:
- Guard non-fatal path with errors.Is(err, util.WaitTimedOut) so
  context cancellation still propagates as a fatal error
- Reduce Phase 1 timeout from 15s to 2s (echo is near-instant)
- Extract named constants for both timeouts
- Add tests for no-echo-success and no-echo-no-react-failure
- Add documentation test for TUI selection prompt ESC limitation

Closes #123

Author: johnstcn

lib/screentracker/pty_conversation.go

@@ -3,6 +3,7 @@ package screentracker
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log/slog"
 	"os"
@@ -16,6 +17,24 @@ import (
 	"golang.org/x/xerrors"
 )
 
+const (
+	// writeStabilizeEchoTimeout is the maximum time to wait for
+	// the screen to change after writing message text to the PTY
+	// (echo detection). This is intentionally short: terminal
+	// echo is near-instant when it occurs. Non-echoing agents
+	// (e.g. TUI agents using bracketed paste) will hit this
+	// timeout, which is non-fatal — see the Phase 1 error
+	// handler in writeStabilize. Move to PTYConversationConfig
+	// if agents need different echo detection windows.
+	writeStabilizeEchoTimeout = 2 * time.Second
+
+	// writeStabilizeProcessTimeout is the maximum time to wait
+	// for the screen to change after sending a carriage return.
+	// This detects whether the agent is actually processing the
+	// input.
+	writeStabilizeProcessTimeout = 15 * time.Second
+)
+
 // A screenSnapshot represents a snapshot of the PTY at a specific time.
 type screenSnapshot struct {
 	timestamp time.Time
@@ -411,7 +430,19 @@ func (c *PTYConversation) sendMessage(ctx context.Context, messageParts ...Messa
 	return nil
 }
 
-// writeStabilize writes messageParts to the screen and waits for the screen to stabilize after the message is written.
+// writeStabilize writes messageParts to the PTY and waits for
+// the agent to process them. It operates in two phases:
+//
+// Phase 1 (echo detection): writes the message text and waits
+// for the screen to change and stabilize. This detects agents
+// that echo typed input. If the screen doesn't change within
+// writeStabilizeEchoTimeout, this is non-fatal — many TUI
+// agents buffer bracketed-paste input without rendering it.
+//
+// Phase 2 (processing detection): writes a carriage return
+// and waits for the screen to change, indicating the agent
+// started processing. This phase is fatal on timeout — if the
+// agent doesn't react to Enter, it's unresponsive.
 func (c *PTYConversation) writeStabilize(ctx context.Context, messageParts ...MessagePart) error {
 	screenBeforeMessage := c.cfg.AgentIO.ReadScreen()
 	for _, part := range messageParts {
@@ -421,7 +452,7 @@ func (c *PTYConversation) writeStabilize(ctx context.Context, messageParts ...Me
 	}
 	// wait for the screen to stabilize after the message is written
 	if err := util.WaitFor(ctx, util.WaitTimeout{
-		Timeout:     15 * time.Second,
+		Timeout:     writeStabilizeEchoTimeout,
 		MinInterval: 50 * time.Millisecond,
 		InitialWait: true,
 		Clock:       c.cfg.Clock,
@@ -438,14 +469,25 @@ func (c *PTYConversation) writeStabilize(ctx context.Context, messageParts ...Me
 		}
 		return false, nil
 	}); err != nil {
-		return xerrors.Errorf("failed to wait for screen to stabilize: %w", err)
+		if !errors.Is(err, util.WaitTimedOut) {
+			// Context cancellation or condition errors are fatal.
+			return xerrors.Errorf("failed to wait for screen to stabilize: %w", err)
+		}
+		// Phase 1 timeout is non-fatal: the agent may not echo
+		// input (e.g. TUI agents buffer bracketed-paste content
+		// internally). Proceed to Phase 2 to send the carriage
+		// return.
+		c.cfg.Logger.Info(
+			"screen did not stabilize after writing message, proceeding to send carriage return",
+			"timeout", writeStabilizeEchoTimeout,
+		)
 	}
 
 	// wait for the screen to change after the carriage return is written
 	screenBeforeCarriageReturn := c.cfg.AgentIO.ReadScreen()
 	lastCarriageReturnTime := time.Time{}
 	if err := util.WaitFor(ctx, util.WaitTimeout{
-		Timeout:     15 * time.Second,
+		Timeout:     writeStabilizeProcessTimeout,
 		MinInterval: 25 * time.Millisecond,
 		Clock:       c.cfg.Clock,
 	}, func() (bool, error) {

lib/screentracker/pty_conversation_test.go

@@ -1,13 +1,15 @@
 package screentracker_test
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"io"
 	"log/slog"
 	"os"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -447,6 +449,137 @@ func TestMessages(t *testing.T) {
 		c, _, _ := newConversation(context.Background(), t)
 		assert.ErrorIs(t, c.Send(st.MessagePartText{Content: ""}), st.ErrMessageValidationEmpty)
 	})
+
+	t.Run("send-no-echo-agent-reacts", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+		t.Cleanup(cancel)
+
+		agent := &testAgent{screen: "prompt"}
+		// Agent doesn't echo input text, but reacts to carriage return.
+		agent.onWrite = func(data []byte) {
+			if string(data) == "\r" {
+				agent.screen = "processing..."
+			}
+		}
+		mClock := quartz.NewMock(t)
+		mClock.Set(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC))
+		cfg := st.PTYConversationConfig{
+			Clock:                 mClock,
+			AgentIO:               agent,
+			SnapshotInterval:      interval,
+			ScreenStabilityLength: 200 * time.Millisecond,
+			Logger:                slog.New(slog.NewTextHandler(io.Discard, nil)),
+		}
+		c := st.NewPTY(ctx, cfg, &testEmitter{})
+		c.Start(ctx)
+
+		// Stabilize: fill snapshot buffer so status becomes stable.
+		advanceFor(ctx, t, mClock, interval*threshold)
+
+		// Send and advance. Phase 1 times out (2s, non-fatal),
+		// Phase 2 writes \r → onWrite changes screen → succeeds.
+		sendAndAdvance(ctx, t, c, mClock, st.MessagePartText{Content: "hello"})
+
+		// User message was recorded.
+		msgs := c.Messages()
+		require.True(t, len(msgs) >= 2)
+		assert.Equal(t, st.ConversationRoleUser, msgs[len(msgs)-1].Role)
+		assert.Equal(t, "hello", msgs[len(msgs)-1].Message)
+	})
+
+	t.Run("send-no-echo-no-react", func(t *testing.T) {
+		ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+		t.Cleanup(cancel)
+
+		agent := &testAgent{screen: "prompt"}
+		// Agent is completely unresponsive: no echo, no reaction.
+		agent.onWrite = func(data []byte) {}
+		mClock := quartz.NewMock(t)
+		mClock.Set(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC))
+		cfg := st.PTYConversationConfig{
+			Clock:                 mClock,
+			AgentIO:               agent,
+			SnapshotInterval:      interval,
+			ScreenStabilityLength: 200 * time.Millisecond,
+			Logger:                slog.New(slog.NewTextHandler(io.Discard, nil)),
+		}
+		c := st.NewPTY(ctx, cfg, &testEmitter{})
+		c.Start(ctx)
+
+		// Stabilize.
+		advanceFor(ctx, t, mClock, interval*threshold)
+
+		// Send in a goroutine; can't use sendAndAdvance because it
+		// calls require.NoError internally.
+		var sendErr error
+		var sendDone atomic.Bool
+		go func() {
+			sendErr = c.Send(st.MessagePartText{Content: "hello"})
+			sendDone.Store(true)
+		}()
+		advanceUntil(ctx, t, mClock, func() bool { return sendDone.Load() })
+
+		require.Error(t, sendErr)
+		assert.Contains(t, sendErr.Error(), "failed to wait for processing to start")
+	})
+
+	t.Run("send-tui-selection-esc-cancels", func(t *testing.T) {
+		// Documents a known limitation: when a TUI agent shows a
+		// selection prompt, sending a user message wraps it in
+		// bracketed paste. The ESC (\x1b) in the paste-start
+		// sequence cancels the selection widget. The user's intended
+		// choice never reaches the selection handler.
+		//
+		// For selection prompts, callers should use MessageTypeRaw
+		// to send raw keystrokes directly to the PTY.
+		//
+		// See lib/httpapi/claude.go for the full formatClaudeCodeMessage
+		// format; this test focuses on the ESC invariant only.
+		ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+		t.Cleanup(cancel)
+
+		agent := &testAgent{screen: "selection prompt"}
+		selectionCancelled := false
+		agent.onWrite = func(data []byte) {
+			// Simulate TUI selection widget: ESC cancels the
+			// selection, changing the screen.
+			if bytes.Contains(data, []byte("\x1b")) {
+				selectionCancelled = true
+				agent.screen = "selection cancelled"
+			} else if string(data) == "\r" {
+				agent.screen = "post-cancel"
+			}
+		}
+		mClock := quartz.NewMock(t)
+		mClock.Set(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC))
+		cfg := st.PTYConversationConfig{
+			Clock:                 mClock,
+			AgentIO:               agent,
+			SnapshotInterval:      interval,
+			ScreenStabilityLength: 200 * time.Millisecond,
+			Logger:                slog.New(slog.NewTextHandler(io.Discard, nil)),
+		}
+		c := st.NewPTY(ctx, cfg, &testEmitter{})
+		c.Start(ctx)
+
+		// Stabilize.
+		advanceFor(ctx, t, mClock, interval*threshold)
+
+		// Send using bracketed paste, which contains ESC. The
+		// test focuses on the ESC invariant — any input wrapped
+		// in bracketed paste will trigger this.
+		sendAndAdvance(ctx, t, c, mClock,
+			st.MessagePartText{Content: "\x1b[200~", Hidden: true},
+			st.MessagePartText{Content: "2"},
+			st.MessagePartText{Content: "\x1b[201~", Hidden: true},
+		)
+
+		// The send succeeded, but the selection was cancelled by
+		// ESC — not option "2" being selected.
+		assert.True(t, selectionCancelled,
+			"ESC in bracketed paste cancels TUI selection prompts; "+
+				"use MessageTypeRaw for selection prompts instead")
+	})
 }
 
 func TestStatePersistence(t *testing.T) {