fix(tui): resolve review findings on BTW recovery, scroll geometry, and marker snapshots

- Revoke side-view lifecycle and restore parent view on BTW exit
- Preserve chat and file-view scroll geometry across in-flight reloads
- Trigger conservative unknown-scope file view refresh on hidden mutating tool results
- Add regression coverage for BTW exit, scroll clamping, and mutation invalidation

Author: hazyhaar

internal/tui/btw.go

@@ -195,6 +195,10 @@ func (m model) leaveBTW() (model, tea.Cmd) {
 	if m.compactInFlight {
 		return m.appendSystemNotice("BTW compaction is still running. Wait for it to finish before returning."), nil
 	}
+	// The side surface is being discarded. Revoke its file-view lifetime token so
+	// a load still queued behind BTW cannot run or land after the view closes.
+	// The restored parent keeps its own request and snapshot untouched.
+	m.revokeFileViewRequest()
 	m, _ = m.clearLoopsForSessionSwitch()
 	parent := *m.btw.parent
 	parent.goalContinuationsSuspended = false
@@ -221,7 +225,9 @@ func (m model) leaveBTW() (model, tea.Cmd) {
 	parent.resetFlushFrontier("· returned from btw ·")
 	var goalCmd tea.Cmd
 	parent, goalCmd = parent.launchGoalContinuationIfReady()
-	return parent, batchCommands(sweepCmd, spinnerCmd, goalCmd)
+	var fileCmd tea.Cmd
+	parent, fileCmd = parent.recoverInvalidatedFileView()
+	return parent, batchCommands(sweepCmd, spinnerCmd, goalCmd, fileCmd)
 }
 
 func btwCommandUnavailable(command parsedCommand) bool {
@@ -325,7 +331,9 @@ func (m model) routeBTWMessageToParent(msg tea.Msg) (model, tea.Cmd, bool) {
 	case agentResponseMsg:
 		m.btw.parentNeedsInput = parent.pendingPermission != nil || parent.pendingAskUser != nil
 	}
-	return m, cmd, true
+	var fileCmd tea.Cmd
+	m, fileCmd = m.recoverInvalidatedFileView()
+	return m, batchCommands(cmd, fileCmd), true
 }
 
 func btwMessageRunID(msg tea.Msg) (int, bool) {
@@ -356,6 +364,8 @@ func btwMessageRunID(msg tea.Msg) (int, bool) {
 		return typed.runID, true
 	case specialistProgressMsg:
 		return typed.runID, true
+	case unknownScopeMutationMsg:
+		return typed.runID, true
 	case swarmSessionsMsg:
 		return typed.runID, true
 	case permissionRequestMsg:

internal/tui/btw_test.go

@@ -2,6 +2,7 @@ package tui
 
 import (
 	"context"
+	"errors"
 	"os"
 	"path/filepath"
 	"strings"
@@ -473,3 +474,69 @@ func TestBTWCtrlCDuringRunDoesNotClearDraft(t *testing.T) {
 		t.Fatalf("missing in-flight return guidance: %#v", got.transcript)
 	}
 }
+
+// TestBTWLeaveRevokesSideFileLoad verifies that leaving BTW revokes the side
+// surface's file-view lifetime so a still-queued side load cannot run or land
+// after the view closes, without cancelling the restored parent's own load.
+func TestBTWLeaveRevokesSideFileLoad(t *testing.T) {
+	resetFileViewCacheForTest()
+	m := newBTWTestModel(t)
+	dir := t.TempDir()
+	m.cwd = dir
+	name := "side_view.go"
+	if err := os.WriteFile(filepath.Join(dir, name), []byte("package side\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Open a full view so the side surface inherits an active file view.
+	m, parentLoadCmd := m.openFileView(name)
+	if parentLoadCmd == nil {
+		t.Fatal("expected a pending parent load command")
+	}
+	parentLiveSeq := m.fileView.liveSeq
+	if parentLiveSeq == nil {
+		t.Fatal("parent load token missing")
+	}
+	parentSeq := parentLiveSeq.Load()
+
+	// Enter BTW: the side surface detaches and schedules its own load.
+	side, sideLoadCmd := m.handleBTWCommand("")
+	if !side.btw.active || side.btw.parent == nil {
+		t.Fatal("expected an active BTW conversation")
+	}
+	if sideLoadCmd == nil {
+		t.Fatal("side surface should schedule its own file load")
+	}
+	sideLiveSeq := side.fileView.liveSeq
+	if sideLiveSeq == nil || sideLiveSeq == parentLiveSeq {
+		t.Fatal("side load must own a detached lifetime token")
+	}
+	sideSeq := sideLiveSeq.Load()
+
+	// Return while the side load is still queued.
+	parent, _ := side.leaveBTW()
+	if sideLiveSeq.Load() == sideSeq {
+		t.Fatal("leaveBTW must revoke the side file-view request")
+	}
+	if parentLiveSeq.Load() != parentSeq || parentLiveSeq == sideLiveSeq {
+		t.Fatal("leaveBTW must not revoke the restored parent's request")
+	}
+
+	// The held side command must now be a superseded no-op.
+	held := sideLoadCmd()
+	loaded, ok := held.(fileViewLoadedMsg)
+	if !ok {
+		t.Fatalf("held side command produced %T, want fileViewLoadedMsg", held)
+	}
+	if !errors.Is(loaded.err, errFileViewSuperseded) {
+		t.Fatalf("queued side load must be superseded after leaving BTW, got %v", loaded.err)
+	}
+
+	// The parent's own load still completes and settles its snapshot.
+	parent = deliverCommandMessages(t, parent, parentLoadCmd)
+	if parent.fileView.loading {
+		t.Fatal("parent load must remain valid after the side revocation")
+	}
+	if !strings.Contains(plainRender(t, parent.renderFileViewFull(80)), "package side") {
+		t.Fatal("restored parent must keep its snapshot")
+	}
+}

internal/tui/file_view.go

@@ -1010,9 +1010,14 @@ type fileViewState struct {
 	path               string // workspace-relative, as carried by changedFiles
 	mode               int    // fileViewDiff | fileViewFull
 	parentScrollOffset int
-	// preservedScrollOffset holds the reader's offset while an async reload
-	// swaps the body for the one-line loading placeholder.
+	// preservedScrollOffset holds the reader's latest scroll intent while an
+	// async reload swaps the body for the one-line loading placeholder. Scroll
+	// actions and prompt submission update it during the pending window, and
+	// handleFileViewLoaded reconciles it against the real body.
 	preservedScrollOffset int
+	// completedBodyLines is the rendered body height of the last accepted
+	// snapshot, including screen wrapping. A loading placeholder never updates it.
+	completedBodyLines int
 
 	// View session lifetime identity (UUIDv7 RFC 9562 0-alloc)
 	lifetimeToken [16]byte
@@ -1222,16 +1227,18 @@ func (m model) handleFileViewLoaded(msg fileViewLoadedMsg) (model, tea.Cmd) {
 	m.fileView.loadedRev = msg.requiredSourceRev
 	m.fileView.hasError = (msg.err != nil)
 	// Reconcile the held reading offset against the real body now that the
-	// loading placeholder is gone; clamp in case the file shrank.
+	// loading placeholder is gone. Apply the height delta exactly once to
+	// preserve the absolute position, while offset zero keeps following the tail.
+	current, maxOffset := m.chatScrollMetrics()
 	if m.fileView.preservedScrollOffset > 0 {
-		current, maxOffset := m.chatScrollMetrics()
-		m.chatScrollOffset = clampInt(m.fileView.preservedScrollOffset, 0, maxOffset)
+		m.chatScrollOffset = clampInt(m.fileView.preservedScrollOffset+current-m.fileView.completedBodyLines, 0, maxOffset)
 		if m.chatScrollOffset > 0 {
 			m.chatBodyLines = current
 		} else {
 			m.chatBodyLines = 0
 		}
 	}
+	m.fileView.completedBodyLines = current
 	return m, nil
 }
 
@@ -1355,3 +1362,46 @@ func (m model) fileViewChangedLines() map[string]bool {
 	}
 	return changed
 }
+
+// toolResultMayMutateUnknownScope reports tools that can change workspace files
+// but do not reliably report the affected paths (ChangedFiles). Their completion
+// must trigger the conservative unknown-scope refresh so an open file view
+// cannot keep rendering a stale snapshot. Task/TaskOutput successful results are
+// suppressed from the transcript, so their completion boundaries carry this
+// refresh separately.
+func toolResultMayMutateUnknownScope(name string) bool {
+	switch name {
+	case "bash", "exec_command", "terminal_session", "write_stdin",
+		"swarm_collect", "swarm_status", "Task", "TaskOutput":
+		return true
+	}
+	return false
+}
+
+// invalidateFileViewForUnknownMutation performs the conservative refresh used
+// when a completed action may have changed workspace files but no exact path is
+// known: purge the shared render cache and, when a full file view is open,
+// schedule an async reload so its snapshot cannot stay stale.
+func (m model) invalidateFileViewForUnknownMutation() (model, tea.Cmd) {
+	defaultFileViewCache.invalidateUnknownScope()
+	if m.fileView.active && m.fileView.mode == fileViewFull {
+		return m.startFileViewRefreshCmd(m.chatColumnWidth())
+	}
+	return m, nil
+}
+
+// recoverInvalidatedFileView schedules a snapshot for a surface whose shared
+// cache generation changed while another BTW surface handled the invalidation.
+func (m model) recoverInvalidatedFileView() (model, tea.Cmd) {
+	if !m.fileView.active || m.fileView.mode != fileViewFull {
+		return m, nil
+	}
+	generation := m.fileView.loadedGen
+	if m.fileView.loading {
+		generation = m.fileView.desiredGen
+	}
+	if generation == defaultFileViewCache.generation() {
+		return m, nil
+	}
+	return m.startFileViewLoadCmd(m.chatColumnWidth())
+}