style(screentracker): use Given/When/Then comments in writeStabilize tests

Restructure test comments to follow Cucumber-style Given/When/Then
pattern for clarity. Also fix send-no-echo-agent-reacts assertion
to scan for the user message instead of assuming it's the last
message in the conversation (the snapshot loop may append an agent
message after Send returns).

Author: johnstcn

lib/screentracker/pty_conversation_test.go

@@ -450,137 +450,139 @@ func TestMessages(t *testing.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..."
+		t.Run("send-no-echo-agent-reacts", func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+			t.Cleanup(cancel)
+
+			// Given: an agent that doesn't echo typed input but
+			// reacts to carriage return by updating the screen.
+			agent := &testAgent{screen: "prompt"}
+			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)),
 			}
-		}
-		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)
+			c := st.NewPTY(ctx, cfg, &testEmitter{})
+			c.Start(ctx)
+			advanceFor(ctx, t, mClock, interval*threshold)
 
-		// Stabilize.
-		advanceFor(ctx, t, mClock, interval*threshold)
+			// When: a message is sent. Phase 1 times out (no echo),
+			// Phase 2 writes \r and the agent reacts.
+			sendAndAdvance(ctx, t, c, mClock, st.MessagePartText{Content: "hello"})
 
-		// 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")
-	})
-}
+			// Then: Send succeeds and the user message is recorded.
+			msgs := c.Messages()
+			require.True(t, len(msgs) >= 2)
+			var foundUserMsg bool
+			for _, msg := range msgs {
+				if msg.Role == st.ConversationRoleUser && msg.Message == "hello" {
+					foundUserMsg = true
+					break
+				}
+			}
+			assert.True(t, foundUserMsg, "expected user message 'hello' in conversation")
+		})
+		t.Run("send-no-echo-no-react", func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+			t.Cleanup(cancel)
+
+			// Given: an agent that is completely unresponsive — it
+			// neither echoes input nor reacts to carriage return.
+			agent := &testAgent{screen: "prompt"}
+			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)
+			advanceFor(ctx, t, mClock, interval*threshold)
+
+			// When: a message is sent. Both Phase 1 (echo) and
+			// Phase 2 (processing) time out.
+			// Note: can't use sendAndAdvance here 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() })
+
+			// Then: Send fails with a Phase 2 error (not Phase 1).
+			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.
+			//
+			// See lib/httpapi/claude.go formatClaudeCodeMessage for
+			// the full format; this test focuses on the ESC
+			// invariant only.
+			ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+			t.Cleanup(cancel)
+
+			// Given: a TUI agent showing a selection prompt where
+			// ESC cancels the selection and changes the screen.
+			agent := &testAgent{screen: "selection prompt"}
+			selectionCancelled := false
+			agent.onWrite = func(data []byte) {
+				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)
+			advanceFor(ctx, t, mClock, interval*threshold)
+
+			// When: a message is sent using bracketed paste, which
+			// contains ESC in the start sequence (\x1b[200~).
+			sendAndAdvance(ctx, t, c, mClock,
+				st.MessagePartText{Content: "\x1b[200~", Hidden: true},
+				st.MessagePartText{Content: "2"},
+				st.MessagePartText{Content: "\x1b[201~", Hidden: true},
+			)
+
+			// Then: Send succeeds, but the selection was cancelled
+			// by ESC — option "2" was never delivered to the
+			// selection handler.
+			assert.True(t, selectionCancelled,
+				"ESC in bracketed paste cancels TUI selection prompts; "+
+					"use MessageTypeRaw for selection prompts instead")
+		})}
 
 func TestStatePersistence(t *testing.T) {
 	t.Run("SaveState creates file with correct structure", func(t *testing.T) {