status: an aria remembers how its last turn ended

`figaro status 94f0752b` said:

    state:        idle

and that was the whole answer, while three prompts sat in the log with
nothing after them and the last turn had died on a provider error. Nothing
was lying. "idle" is a statement about the INBOX; it says nothing about
whether the last thing the user asked for worked, and reporting only the
first is exactly how a failed turn gets reported as a hang.

The outcome was already computed - finishTurn(reason) has always known, and
fans it out on turn.done - and then dropped on the floor, visible only to
whoever happened to be attached at that instant. Retaining one string and one
timestamp turns "it is not responding" into "its last turn failed nine
minutes ago, and here is what the provider said":

    figaro       94f0752b
      state:      idle
      last-turn:  error: anthropic: rate_limit_error (429): the provider
                  asked us to wait 1h0m0s ... (9m0s ago)
      unanswered: 3 prompt(s) with no reply

unanswered counts input messages at the tail with no assistant message after
them: work taken and nothing produced. It is distinct from a queue backlog -
these are already committed to the log, which is why `queue ls` came back
empty while three questions went unanswered. The scan is bounded; only the
tail can be unanswered.

A turn that simply completed earns no row. A status panel that reports every
success teaches people to skim past the one line that mattered.

Also: `figaro listen` now surfaces an error reason through lt.report rather
than writing it straight to stderr, which is what `send` has done since the
pager landed. Straight-to-stderr lands ON the footer while the pager owns the
terminal and scrolls the grid out from under the painter, so a turn that
failed while you were tailing it could leave no visible trace at all. report
picks the right door and puts it in the status row's red notice.

Author: gluck

internal/angelus/protocol.go

@@ -1482,6 +1482,11 @@ func (h *handlers) list(ctx context.Context, params json.RawMessage) (interface{
 			Mantra:           info.Mantra,
 			Cwd:              info.Cwd,
 			BoundPIDs:        boundPIDs[info.ID],
+			LastTurnReason:   info.LastTurnReason,
+			UnansweredInputs: info.UnansweredInputs,
+		}
+		if !info.LastTurnAt.IsZero() {
+			entry.LastTurnAt = info.LastTurnAt.UnixMilli()
 		}
 		result = append(result, entry)
 	}

internal/cli/listen.go

@@ -160,7 +160,15 @@ func tailFigaro(ctx context.Context, cancel context.CancelFunc, ep transport.End
 			_ = json.Unmarshal(params, &d)
 			lt.finishTurn(d.Reason)
 			if strings.HasPrefix(d.Reason, "error:") {
-				sessionLine(os.Stderr, "\r\n"+d.Reason)
+				// Through lt.report, not straight to stderr: report picks
+				// the right door for whichever renderer owns the terminal,
+				// so the reason lands in the status row's red notice while
+				// the pager is up instead of being written over the footer
+				// (and scrolling the grid out from under the painter). send
+				// has done it this way since the pager landed; listen was
+				// left behind, which meant a turn that failed while you were
+				// tailing it could leave no visible trace at all.
+				lt.report(d.Reason)
 			}
 		}
 	}

internal/cli/status.go

@@ -290,6 +290,20 @@ func printStatusPanel(out *os.File, f *rpc.FigaroInfoResponse, more bool, forkTu
 
 	fmt.Fprintf(w, "figaro\t%s\n", f.ID)
 	row("state", dash(f.State))
+	// STATE IS NOT AN OUTCOME. "idle" says the inbox is empty; it says
+	// nothing about whether the last thing the user asked for worked. An
+	// aria whose last turn died on a provider error reported "idle" and
+	// nothing else, and that gap is precisely how a failed turn gets
+	// reported as a hang. When the last turn failed, say so on the line
+	// under state, where it cannot be missed.
+	if reason := lastTurnRow(f); reason != "" {
+		row("last-turn", reason)
+	}
+	if f.UnansweredInputs > 0 {
+		// Work taken and nothing produced. Distinct from a queue backlog:
+		// these are already committed to the log.
+		row("unanswered", fmt.Sprintf("%d prompt(s) with no reply", f.UnansweredInputs))
+	}
 	row("mantra", dash(f.Mantra))
 	row("provider", dash(f.Provider))
 	row("model", dash(f.Model))
@@ -364,3 +378,23 @@ func truncateDuration(d time.Duration) string {
 		return d.Round(time.Minute).String()
 	}
 }
+
+// lastTurnRow renders how the last turn ended, or "" when there is nothing
+// worth saying. A turn that simply completed needs no row: state already
+// covers the healthy case, and a status panel that reports every success
+// teaches people to skim past the one line that mattered.
+func lastTurnRow(f *rpc.FigaroInfoResponse) string {
+	reason := strings.TrimSpace(f.LastTurnReason)
+	if reason == "" {
+		return ""
+	}
+	low := strings.ToLower(reason)
+	failed := strings.HasPrefix(low, "error:")
+	if !failed && !strings.Contains(low, "interrupt") {
+		return ""
+	}
+	if f.LastTurnAt != 0 {
+		return fmt.Sprintf("%s (%s ago)", reason, truncateDuration(time.Since(time.UnixMilli(f.LastTurnAt))))
+	}
+	return reason
+}

internal/cli/status_last_turn_test.go

@@ -0,0 +1,56 @@
+package cli
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/jack-work/figaro/internal/rpc"
+)
+
+// "idle" is a statement about the inbox. It says nothing about whether the
+// last thing you asked for worked, and reporting only the first is exactly
+// how a failed turn gets reported as a hang: three prompts in the log,
+// nothing produced, and every surface saying idle.
+func TestStatusReportsAFailedLastTurn(t *testing.T) {
+	f := &rpc.FigaroInfoResponse{
+		ID:             "94f0752b",
+		State:          "idle",
+		LastTurnReason: "error: anthropic: rate_limit_error (429): the provider asked us to wait 1h0m0s",
+		LastTurnAt:     time.Now().Add(-9 * time.Minute).UnixMilli(),
+	}
+	got := lastTurnRow(f)
+	if !strings.Contains(got, "rate_limit_error") {
+		t.Fatalf("the reason must survive to the panel: %q", got)
+	}
+	if !strings.Contains(got, "ago") {
+		t.Errorf("when it failed matters as much as that it failed: %q", got)
+	}
+}
+
+// A status panel that reports every success teaches people to skim past the
+// one line that mattered.
+func TestStatusSaysNothingAboutAHealthyTurn(t *testing.T) {
+	for _, reason := range []string{"", "end_turn", "stop_sequence", "max_tokens"} {
+		f := &rpc.FigaroInfoResponse{State: "idle", LastTurnReason: reason}
+		if got := lastTurnRow(f); got != "" {
+			t.Errorf("reason %q produced a row %q; only trouble earns one", reason, got)
+		}
+	}
+}
+
+// An interrupt is not a failure but it is not a completion either, and a user
+// coming back to a conversation deserves to know which one happened.
+func TestStatusReportsAnInterruptedTurn(t *testing.T) {
+	f := &rpc.FigaroInfoResponse{State: "idle", LastTurnReason: "interrupted"}
+	if got := lastTurnRow(f); !strings.Contains(got, "interrupted") {
+		t.Errorf("interrupted turn not reported: %q", got)
+	}
+}
+
+func TestStatusRowSurvivesAMissingTimestamp(t *testing.T) {
+	f := &rpc.FigaroInfoResponse{State: "idle", LastTurnReason: "error: boom"}
+	if got := lastTurnRow(f); got != "error: boom" {
+		t.Errorf("got %q", got)
+	}
+}

internal/figaro/agent.go

@@ -203,23 +203,28 @@ type Agent struct {
 	// is the single source of both figaro.aria pushes and figaro.read pulls.
 	ariaSrv *aria.Server
 
-	createdAt     time.Time
-	lastActive    time.Time
-	tokensIn      int
-	tokensOut     int
-	cacheRead     int
-	cacheWrite    int
-	messageCount  int
-	turnCount     int
-	metricsLT     uint64
-	contextTokens int
-	contextLimit  int
-	contextExact  bool
-	model         string
-	mantra        string
-	cwd           string
-	outfitName    string
-	outfitVer     string
+	createdAt  time.Time
+	lastActive time.Time
+	// lastTurnReason is how the most recent turn ENDED - a stop reason, or
+	// "interrupted", or "error: ...". State says whether a turn is running;
+	// this says whether the last one worked.
+	lastTurnReason string
+	lastTurnAt     time.Time
+	tokensIn       int
+	tokensOut      int
+	cacheRead      int
+	cacheWrite     int
+	messageCount   int
+	turnCount      int
+	metricsLT      uint64
+	contextTokens  int
+	contextLimit   int
+	contextExact   bool
+	model          string
+	mantra         string
+	cwd            string
+	outfitName     string
+	outfitVer      string
 
 	cancel context.CancelFunc
 	done   chan struct{}
@@ -780,8 +785,11 @@ func (a *Agent) Info() FigaroInfo {
 		OutfitName:       a.outfitName,
 		OutfitVersion:    a.outfitVer,
 		LastFigaroLT:     a.metricsLT,
+		LastTurnReason:   a.lastTurnReason,
+		LastTurnAt:       a.lastTurnAt,
 	}
 	a.mu.RUnlock()
+	info.UnansweredInputs = a.unansweredInputs()
 	return info
 }
 
@@ -1233,6 +1241,15 @@ func (a *Agent) finishTurn(reason string) {
 	idle := a.inbox.IsIdle()
 	a.mu.Lock()
 	a.lastActive = time.Now()
+	// REMEMBER HOW THE TURN ENDED. The reason has always been computed here
+	// and fanned out to whoever happened to be attached at that instant, then
+	// dropped. So an aria whose last turn died on a provider error reported
+	// "idle" forever after, which is true and useless: idle is a statement
+	// about the inbox, not about whether the last thing you asked for
+	// worked. Retaining one string is the difference between "it is not
+	// responding" and "its last turn failed nine minutes ago, here is why".
+	a.lastTurnReason = reason
+	a.lastTurnAt = a.lastActive
 	a.mu.Unlock()
 	a.fanOut(rpc.Notification{
 		JSONRPC: "2.0",
@@ -1342,3 +1359,39 @@ func (a *Agent) DeleteQueued(epoch string, ids []uint64, all bool) (string, []rp
 func (a *Agent) UpdateQueued(epoch string, id uint64, text string) (string, rpc.QueueResult) {
 	return a.inbox.UpdatePrompt(epoch, id, text)
 }
+
+// unansweredInputs counts input messages at the tail of the log with no
+// assistant message after them.
+//
+// It exists because of a state figaro had no word for: three prompts sitting
+// in the log, consumed off the queue (so `queue ls` is empty) and answered by
+// nothing (so the conversation ends in user messages), while `status` reported
+// "idle". Every surface was individually truthful and the aggregate was a lie.
+// A nonzero count here means the aria took work and produced nothing - which
+// is the definition of the failure people report as "it hangs".
+//
+// Bounded read: only the tail can be unanswered, and a healthy aria answers
+// within one message, so a short page is enough. A pathological run of more
+// than unansweredScanDepth inputs reports the depth, which is already alarming
+// enough to act on.
+func (a *Agent) unansweredInputs() int {
+	if a.figLog == nil {
+		return 0
+	}
+	page, _ := a.figLog.ReadPage(0, ^uint64(0), unansweredScanDepth)
+	if len(page) == 0 {
+		return 0
+	}
+	n := 0
+	// The page is ascending, so walk it backwards from the tail.
+	for i := len(page) - 1; i >= 0; i-- {
+		if page[i].Payload.Role != message.RoleInput {
+			return n
+		}
+		n++
+	}
+	return n
+}
+
+// unansweredScanDepth bounds the tail scan. Past this the answer is "many".
+const unansweredScanDepth = 32

internal/figaro/figaro.go

@@ -7,6 +7,7 @@
 package figaro
 
 import (
+	"strings"
 	"time"
 )
 
@@ -47,4 +48,23 @@ type FigaroInfo struct {
 	OutfitName       string    `json:"outfit_name"`
 	OutfitVersion    string    `json:"outfit_version"`
 	LastFigaroLT     uint64    `json:"last_figaro_lt"`
+
+	// LastTurnReason is how the most recent turn ENDED: a stop reason,
+	// "interrupted", or "error: ...". State reports whether a turn is running
+	// now; this reports whether the last one worked, and the two answer
+	// different questions. An aria whose last turn died on a provider error
+	// is idle, and saying only "idle" is how a failure reads as a hang.
+	LastTurnReason string    `json:"last_turn_reason,omitempty"`
+	LastTurnAt     time.Time `json:"last_turn_at,omitempty"`
+	// UnansweredInputs counts prompts at the tail of the log that no
+	// assistant message followed. Nonzero means the aria took work and
+	// produced nothing.
+	UnansweredInputs int `json:"unanswered_inputs,omitempty"`
+}
+
+// LastTurnFailed reports whether the most recent turn ended in an error. The
+// reason string is the wire format the turn loop already produced; this is the
+// one place that knows its shape.
+func (i FigaroInfo) LastTurnFailed() bool {
+	return strings.HasPrefix(i.LastTurnReason, "error:")
 }

internal/figaro/last_turn_test.go

@@ -0,0 +1,80 @@
+package figaro
+
+import (
+	"testing"
+
+	"github.com/jack-work/figaro/internal/message"
+	"github.com/jack-work/figaro/internal/store"
+)
+
+// The state figaro had no word for: prompts consumed off the queue (so
+// `queue ls` is empty) and answered by nothing (so the log ends in user
+// messages), while status reported idle. Every surface individually truthful,
+// the aggregate a lie.
+func TestUnansweredInputsCountsTheTail(t *testing.T) {
+	a := &Agent{figLog: store.NewMemLog[message.Message]()}
+	appendRole := func(role message.Role) {
+		if _, err := a.figLog.Append(store.Entry[message.Message]{Payload: message.Message{Role: role}}); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	if got := a.unansweredInputs(); got != 0 {
+		t.Errorf("empty log: got %d, want 0", got)
+	}
+
+	appendRole(message.RoleInput)
+	appendRole(message.RoleOutput)
+	if got := a.unansweredInputs(); got != 0 {
+		t.Errorf("an answered prompt is not unanswered: got %d", got)
+	}
+
+	appendRole(message.RoleInput)
+	appendRole(message.RoleInput)
+	appendRole(message.RoleInput)
+	if got := a.unansweredInputs(); got != 3 {
+		t.Errorf("got %d, want 3 - this is the number that says work was taken and nothing produced", got)
+	}
+
+	// An assistant reply clears it.
+	appendRole(message.RoleOutput)
+	if got := a.unansweredInputs(); got != 0 {
+		t.Errorf("got %d, want 0 after a reply", got)
+	}
+}
+
+// The scan is bounded: only the tail can be unanswered, and an aria with more
+// than the scan depth of unanswered prompts is already alarming enough to act
+// on without an unbounded read.
+func TestUnansweredInputsIsBounded(t *testing.T) {
+	a := &Agent{figLog: store.NewMemLog[message.Message]()}
+	for i := 0; i < unansweredScanDepth*2; i++ {
+		if _, err := a.figLog.Append(store.Entry[message.Message]{Payload: message.Message{Role: message.RoleInput}}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if got := a.unansweredInputs(); got != unansweredScanDepth {
+		t.Errorf("got %d, want the scan depth %d", got, unansweredScanDepth)
+	}
+}
+
+func TestUnansweredInputsToleratesNoLog(t *testing.T) {
+	a := &Agent{}
+	if got := a.unansweredInputs(); got != 0 {
+		t.Errorf("got %d, want 0", got)
+	}
+}
+
+func TestLastTurnFailedReadsTheReason(t *testing.T) {
+	for reason, want := range map[string]bool{
+		"":                     false,
+		"end_turn":             false,
+		"interrupted":          false,
+		"error: boom":          true,
+		"error: anthropic 429": true,
+	} {
+		if got := (FigaroInfo{LastTurnReason: reason}).LastTurnFailed(); got != want {
+			t.Errorf("LastTurnFailed(%q) = %v, want %v", reason, got, want)
+		}
+	}
+}

internal/rpc/methods.go

@@ -495,6 +495,16 @@ type FigaroInfoResponse struct {
 	OutfitVer        string `json:"outfit_ver,omitempty"`    // "live" if the stamped hash matches the current outfit, else its short hash
 	BoundPIDs        []int  `json:"bound_pids"`
 
+	// LastTurnReason is how the most recent turn ENDED: a stop reason,
+	// "interrupted", or "error: ...". State answers "is a turn running"; this
+	// answers "did the last one work", and reporting only the first is how a
+	// failed turn reads as a hang. LastTurnAt is when it ended, unix millis.
+	LastTurnReason string `json:"last_turn_reason,omitempty"`
+	LastTurnAt     int64  `json:"last_turn_at,omitempty"`
+	// UnansweredInputs counts prompts at the tail of the log that no
+	// assistant message followed: work taken and nothing produced.
+	UnansweredInputs int `json:"unanswered_inputs,omitempty"`
+
 	// Fork-forest position (conversation nodes). Vector is the
 	// child-index path (0, 0.0, 0.1, …); Trunk is the thread id that
 	// flows down the continuation line; Parent is the aria branched from.