Context governor UX: compaction events, checkpoints, API usage footer

Emit compact stream events to the TUI with spinner status; save pre-compaction
checkpoints under ~/.hawk/sessions/<id>/checkpoints; prefer API prompt tokens
in the footer when usage is available; add Anthropic provider-native compaction
(compact_20260112) when a direct API key and supported Claude model are present.

Author: Patel230

cmd/chat.go

@@ -241,6 +241,7 @@ func newChatModel(ref *progRef, systemPrompt string, settings hawkconfig.Setting
 	if err != nil {
 		return chatModel{}, err
 	}
+	bindChatSession(sess, sid)
 
 	// Initialize conversation DAG for branching support
 	if home, err := os.UserHomeDir(); err == nil {
@@ -926,6 +927,8 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		return m, nil
 
 	case streamChunkMsg:
+		m.compacting = false
+		m.compactStatus = ""
 		m.partial.WriteString(string(msg))
 		m.markPartialDirty()
 		return m, nil
@@ -977,10 +980,26 @@ func (m chatModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		if msg.usage != nil {
 			m.turnInputTokens += msg.usage.PromptTokens
 			m.turnOutputTokens += msg.usage.CompletionTokens
+			m.invalidateConnStatus()
 			m.viewDirty = true
 		}
 
+	case compactMsg:
+		m.compacting = false
+		m.compactStatus = ""
+		line := fmt.Sprintf("Context compacted (%s): ~%s → ~%s tokens",
+			msg.strategy,
+			formatHawkTokenCount(msg.tokensBefore),
+			formatHawkTokenCount(msg.tokensAfter),
+		)
+		m.messages = append(m.messages, displayMsg{role: "system", content: line})
+		m.invalidateConnStatus()
+		m.viewDirty = true
+		return m, nil
+
 	case streamDoneMsg:
+		m.compacting = false
+		m.compactStatus = ""
 		m.flushPartialDirty()
 		if m.partial.Len() > 0 {
 			content := sanitizeIdentity(m.partial.String())
@@ -1216,9 +1235,13 @@ func runChat() error {
 					p.Send(toolUseMsg{name: ev.ToolName, id: ev.ToolID})
 				case "tool_result":
 					p.Send(toolResultMsg{name: ev.ToolName, content: ev.Content})
+				case "compact":
+					p.Send(compactMsg{
+						strategy:     ev.Content,
+						tokensBefore: ev.TokensBefore,
+						tokensAfter:  ev.TokensAfter,
+					})
 				case "usage":
-					// Forward usage events to TUI so the spinner line can show
-					// running ↑/↓ token counts for the current turn.
 					if ev.Usage != nil {
 						p.Send(usageUpdateMsg{usage: ev.Usage})
 					}

cmd/chat_commands_session.go

@@ -73,6 +73,8 @@ func (m *chatModel) handleSessionCommand(cmd string, parts []string, text string
 			msg = fmt.Sprintf("Compacted with fallback: %d → %d messages", before, after)
 		}
 		m.messages = append(m.messages, displayMsg{role: "system", content: msg})
+		m.compacting = false
+		m.compactStatus = ""
 		m.invalidateConnStatus()
 		return m, nil
 

cmd/chat_model.go

@@ -84,6 +84,10 @@ type (
 	blinkTickMsg       struct{}
 	spinnerVerbTickMsg struct{}
 	usageUpdateMsg     struct{ usage *engine.StreamUsage }
+	compactMsg         struct {
+		strategy               string
+		tokensBefore, tokensAfter int
+	}
 )
 
 type (
@@ -174,6 +178,8 @@ type chatModel struct {
 	// Reset each time the user submits a message; updated by usageUpdateMsg.
 	turnInputTokens  int
 	turnOutputTokens int
+	compacting       bool   // true while context governor runs
+	compactStatus    string // short label on spinner line
 	// Display values lerped toward the turn targets each render frame
 	// (factor 0.10). Smooths the counter animation.
 	displayInTok      float64

cmd/chat_status.go

@@ -52,8 +52,12 @@ func (m *chatModel) invalidateConnStatus() {
 func (m chatModel) connStatusFingerprint() string {
 	gw, model := m.sessionGatewayModel()
 	creds := strings.Join(hawkconfig.ConfiguredCredentialProviders(), ",")
+	api := 0
+	if m.session != nil {
+		api = m.session.LastPromptTokens()
+	}
 	used := sessionContextUsedTokens(m.session)
-	return gw + "\x00" + model + "\x00" + creds + "\x00" + fmt.Sprintf("%d", used)
+	return gw + "\x00" + model + "\x00" + creds + "\x00" + fmt.Sprintf("%d", used) + "\x00" + fmt.Sprintf("%d", api)
 }
 
 func (m chatModel) sessionGatewayModel() (gateway, model string) {
@@ -245,7 +249,7 @@ func sessionContextUsedTokens(sess *engine.Session) int {
 	if sess == nil {
 		return 0
 	}
-	return engine.EstimateTokens(sess.RawMessages())
+	return sess.ContextUsedTokens()
 }
 
 func contextUsagePercent(m chatModel, windowLabel string) int {

cmd/chat_status_test.go

@@ -66,9 +66,9 @@ func TestContextPercentColor(t *testing.T) {
 		pct  int
 		want lipgloss.Color
 	}{
-		{0, successTeal},
-		{50, successTeal},
-		{79, successTeal},
+		{0, doneGreen},
+		{50, doneGreen},
+		{79, doneGreen},
 		{80, warnAmber},
 		{94, warnAmber},
 		{95, errorCoral},

cmd/chat_stream.go

@@ -21,6 +21,9 @@ func (m *chatModel) startPromptCommand(display, prompt string) (tea.Model, tea.C
 
 func (m *chatModel) startStream() {
 	m.syncSessionSelection()
+	m.compacting = true
+	m.compactStatus = "Compacting context"
+	m.viewDirty = true
 	sess := m.session
 	ref := m.ref
 	ctx, cancel := context.WithCancel(context.Background())
@@ -43,9 +46,16 @@ func (m *chatModel) startStream() {
 				ref.Send(toolResultMsg{name: ev.ToolName, content: ev.Content})
 			case "blast_radius":
 				ref.Send(blastRadiusMsg{message: ev.Content})
+			case "compact":
+				ref.Send(compactMsg{
+					strategy:     ev.Content,
+					tokensBefore: ev.TokensBefore,
+					tokensAfter:  ev.TokensAfter,
+				})
 			case "usage":
-				// Usage events are only emitted in stream-json print mode
-				// TUI mode ignores them since cost is tracked separately
+				if ev.Usage != nil {
+					ref.Send(usageUpdateMsg{usage: ev.Usage})
+				}
 			case "error":
 				ref.Send(streamErrMsg{err: fmt.Errorf("%s", ev.Content)})
 				return

cmd/chat_view.go

@@ -604,6 +604,10 @@ func (m chatModel) renderWaitingSpinnerLine() string {
 	sep := ansiDim + " " + iconSpinnerSep + " " + ansiReset
 
 	var b strings.Builder
+	if m.compacting && m.compactStatus != "" {
+		b.WriteString(ansiYellow + m.compactStatus + ansiReset)
+		b.WriteString(sep)
+	}
 	b.WriteString(m.brailleSpinner.Frame())
 	b.WriteString(sep)
 	b.WriteString(ansiTeal + fmt.Sprintf("%.1fs", m.spinnerElapsed().Seconds()) + ansiReset)

cmd/options.go

@@ -293,6 +293,16 @@ func configureSession(sess *engine.Session, settings hawkconfig.Settings, maxTur
 	return nil
 }
 
+// bindChatSession wires TUI-only session metadata (persist id, compaction callbacks).
+func bindChatSession(sess *engine.Session, sessionID string) {
+	if sess == nil {
+		return
+	}
+	if id := strings.TrimSpace(sessionID); id != "" {
+		sess.SetPersistID(id)
+	}
+}
+
 func validateRootFlags() error {
 	if outputFormat != "text" && outputFormat != "json" && outputFormat != "stream-json" {
 		return fmt.Errorf("--output-format must be one of: text, json, stream-json")

internal/engine/compact_auto.go

@@ -67,6 +67,7 @@ func (ac *AutoCompactor) AutoCompactIfNeeded(ctx context.Context, sess *Session)
 		return "", false
 	}
 
+	tokensBefore := EstimateTokens(sess.messages)
 	strategy, err := ac.RunCompaction(ctx, sess)
 	if err != nil {
 		ac.mu.Lock()
@@ -77,19 +78,23 @@ func (ac *AutoCompactor) AutoCompactIfNeeded(ctx context.Context, sess *Session)
 			"failures": ac.consecutiveFailures,
 		})
 		sess.compact()
+		tokensAfter := EstimateTokens(sess.messages)
+		sess.recordCompaction("truncate_fallback", tokensBefore, tokensAfter, false)
 		return "truncate_fallback", true
 	}
 
 	ac.mu.Lock()
 	ac.consecutiveFailures = 0
 	ac.mu.Unlock()
+	tokensAfter := EstimateTokens(sess.messages)
+	sess.recordCompaction(strategy, tokensBefore, tokensAfter, false)
 	return strategy, true
 }
 
 // RunCompaction selects and executes the best compaction strategy.
 func (ac *AutoCompactor) RunCompaction(ctx context.Context, sess *Session) (string, error) {
 	tokenCount := EstimateTokens(sess.messages)
-	strategy := ac.registry.SelectStrategy(sess.messages, tokenCount)
+	strategy := ac.registry.SelectStrategy(sess, sess.messages, tokenCount)
 
 	sess.log.Info("running compaction", map[string]interface{}{
 		"strategy": strategy.Name(),
@@ -112,6 +117,7 @@ func (ac *AutoCompactor) RunCompaction(ctx context.Context, sess *Session) (stri
 		"tokens_after":  result.TokensAfter,
 		"reduction":     result.TokensBefore - result.TokensAfter,
 	})
+	// recordCompaction is called by AutoCompactIfNeeded / CompactConversation callers
 
 	return result.Strategy, nil
 }