fix(screentracker): make statusLocked() honest about initialPromptReady

statusLocked() used to report 'stable' when the screen was calm,
blissfully unaware that initialPromptReady was false. Send() would
trust this optimistic status, enqueue a message, and then wait
forever for a stableSignal that would never arrive — like waiting
for a bus that got cancelled.

Return 'changing' when initialPromptReady is false so Send() rejects
immediately with ErrMessageValidationChanging instead of ghosting the
caller.

Fixes: #209

Author: johnstcn

lib/screentracker/pty_conversation.go

@@ -571,6 +571,14 @@ func (c *PTYConversation) statusLocked() ConversationStatus {
 		return ConversationStatusChanging
 	}
 
+	// The send loop gates outbound messages on initialPromptReady.
+	// Report "changing" until readiness is detected so that Send()
+	// rejects with ErrMessageValidationChanging instead of blocking
+	// indefinitely on a stableSignal that will never fire.
+	if !c.initialPromptReady {
+		return ConversationStatusChanging
+	}
+
 	// Handle initial prompt readiness: report "changing" until the queue is drained
 	// to avoid the status flipping "changing" -> "stable" -> "changing"
 	if len(c.outboundQueue) > 0 || c.sendingMessage {

lib/screentracker/pty_conversation_test.go

@@ -1200,7 +1200,7 @@ func TestStatePersistence(t *testing.T) {
 func TestInitialPromptReadiness(t *testing.T) {
 	discardLogger := slog.New(slog.NewTextHandler(io.Discard, nil))
 
-	t.Run("agent not ready - status is stable until agent becomes ready", func(t *testing.T) {
+	t.Run("agent not ready - status is changing until agent becomes ready", func(t *testing.T) {
 		ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
 		t.Cleanup(cancel)
 		mClock := quartz.NewMock(t)
@@ -1223,9 +1223,9 @@ func TestInitialPromptReadiness(t *testing.T) {
 		// Take a snapshot with "loading...". Threshold is 1 (stability 0 / interval 1s = 0 + 1 = 1).
 		advanceFor(ctx, t, mClock, 1*time.Second)
 
-		// Screen is stable and agent is not ready, so initial prompt hasn't been enqueued yet.
-		// Status should be stable.
-		assert.Equal(t, st.ConversationStatusStable, c.Status())
+		// Screen is stable but agent is not ready. Status must be
+		// "changing" so that Send() rejects instead of blocking.
+		assert.Equal(t, st.ConversationStatusChanging, c.Status())
 	})
 
 	t.Run("agent becomes ready - prompt enqueued and status changes to changing", func(t *testing.T) {
@@ -1248,10 +1248,9 @@ func TestInitialPromptReadiness(t *testing.T) {
 		c := st.NewPTY(ctx, cfg, &testEmitter{})
 		c.Start(ctx)
 
-		// Agent not ready initially, status should be stable
-		advanceFor(ctx, t, mClock, 1*time.Second)
-		assert.Equal(t, st.ConversationStatusStable, c.Status())
-
+			// Agent not ready initially, status should be changing.
+			advanceFor(ctx, t, mClock, 1*time.Second)
+			assert.Equal(t, st.ConversationStatusChanging, c.Status())
 		// Agent becomes ready, prompt gets enqueued, status becomes "changing"
 		agent.setScreen("ready")
 		advanceFor(ctx, t, mClock, 1*time.Second)
@@ -1283,10 +1282,9 @@ func TestInitialPromptReadiness(t *testing.T) {
 		c := st.NewPTY(ctx, cfg, &testEmitter{})
 		c.Start(ctx)
 
-		// Status is "stable" while waiting for readiness (prompt not yet enqueued).
-		advanceFor(ctx, t, mClock, 1*time.Second)
-		assert.Equal(t, st.ConversationStatusStable, c.Status())
-
+			// Status is "changing" while waiting for readiness (prompt not yet enqueued).
+			advanceFor(ctx, t, mClock, 1*time.Second)
+			assert.Equal(t, st.ConversationStatusChanging, c.Status())
 		// Agent becomes ready. The snapshot loop detects this, enqueues the prompt,
 		// then sees queue + stable + ready and signals the send loop.
 		// writeStabilize runs with onWrite changing the screen, so it completes.
@@ -1304,7 +1302,7 @@ func TestInitialPromptReadiness(t *testing.T) {
 		assert.Equal(t, st.ConversationStatusStable, c.Status())
 	})
 
-	t.Run("no initial prompt - normal status logic applies", func(t *testing.T) {
+	t.Run("no initial prompt - status is changing when readiness never fires", func(t *testing.T) {
 		ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
 		t.Cleanup(cancel)
 		mClock := quartz.NewMock(t)
@@ -1325,8 +1323,10 @@ func TestInitialPromptReadiness(t *testing.T) {
 
 		advanceFor(ctx, t, mClock, 1*time.Second)
 
-		// Status should be stable because no initial prompt to wait for.
-		assert.Equal(t, st.ConversationStatusStable, c.Status())
+		// Even without an initial prompt, the send loop gates on
+		// initialPromptReady. Status must reflect that Send()
+		// would block.
+		assert.Equal(t, st.ConversationStatusChanging, c.Status())
 	})
 
 	t.Run("no initial prompt configured - normal status logic applies", func(t *testing.T) {
@@ -1736,10 +1736,45 @@ func TestInitialPromptSent(t *testing.T) {
 
 		// Verify no prompt was sent (should only have the initial screen message)
 		messages := c.Messages()
-		for _, msg := range messages {
-			if msg.Role == st.ConversationRoleUser {
-				t.Errorf("Unexpected user message sent: %q (empty prompt should not be restored)", msg.Message)
+			for _, msg := range messages {
+				if msg.Role == st.ConversationRoleUser {
+					t.Errorf("Unexpected user message sent: %q (empty prompt should not be restored)", msg.Message)
+				}
 			}
-		}
-	})
+		})
 }
+
+func TestSendRejectsWhenInitialPromptNotReady(t *testing.T) {
+	// Regression test for https://github.com/coder/agentapi/issues/209.
+	// Send() used to block forever when ReadyForInitialPrompt never
+	// returned true, because statusLocked() reported "stable" while
+	// stableSignal required initialPromptReady. Now statusLocked()
+	// returns "changing" and Send() rejects immediately.
+	ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+	t.Cleanup(cancel)
+
+	mClock := quartz.NewMock(t)
+	agent := &testAgent{screen: "onboarding screen without message box"}
+	cfg := st.PTYConversationConfig{
+		Clock:                 mClock,
+		SnapshotInterval:      100 * time.Millisecond,
+		ScreenStabilityLength: 200 * time.Millisecond,
+		AgentIO:               agent,
+		ReadyForInitialPrompt: func(screen string) bool {
+			return false // Simulates failed message box detection.
+		},
+		Logger: slog.New(slog.NewTextHandler(io.Discard, nil)),
+	}
+	c := st.NewPTY(ctx, cfg, &testEmitter{})
+	c.Start(ctx)
+
+	// Fill snapshot buffer to reach stability.
+	advanceFor(ctx, t, mClock, 300*time.Millisecond)
+
+	// Status reports "changing" because initialPromptReady is false.
+	assert.Equal(t, st.ConversationStatusChanging, c.Status())
+
+	// Send() rejects immediately instead of blocking forever.
+	err := c.Send(st.MessagePartText{Content: "hello"})
+	assert.ErrorIs(t, err, st.ErrMessageValidationChanging)
+}