fix(transcript): stop auto-jump to the bottom when a reply completes

A detached reader gets yanked to the bottom the moment a run finishes,
through two independent paths:

1. Settle shrink re-attach (both ends). When a reply settles, the row
   list briefly shrinks (desktop persistence can lag the run's end; the
   WebUI drops its pending bubble). The browser clamps scrollTop to the
   new bottom and emits a scroll event, and the follow reducer's clamp
   branch attached unconditionally — so the regrowth that lands right
   after pinned the reader to the bottom.

   Gate the clamp attach on evidence of intent: our own pin write
   echoing back (still following) or an arrival inside the 500ms
   gesture latch. Every deliberate return-to-bottom still attaches
   (wheel/touch/key arrivals ride the latch chain, thumb drags
   re-engage on release, the jump button uses forceFollow); a shrink
   clamp carries no input and no latch, so it can no longer re-engage
   follow.

2. Queued-turn auto-start pin (GUI). Draining the chat queue after a
   run completes went through markConversationRunStarted, which
   force-pinned the visible conversation. Queue auto-starts are not a
   user gesture — skip the pin for them (preserveComposerOnStart is
   the queue-only marker); manual sends keep pinning.

The old "landing at the physical clamp always attaches with no latch
and no pointer" test codified the hole; it is rewritten as a latched
arrival (preserving its fractional-DPR tolerance intent), with new
regression coverage for the shrink clamp and the pin echo.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: su-fen

crates/agent-gateway/web/src/lib/chat-scroll/scrollFollowCore.ts

@@ -14,11 +14,16 @@
 //   after a programmatic pin (the abort lands with the next main-thread
 //   commit); those frames carry no input and no drag, so they can never
 //   detach.
-// - ATTACH is position-driven: landing at the physical clamp always attaches;
-//   a gesture-latched downward arrival inside the reattach zone attaches; a
-//   pointer released inside the zone after downward movement attaches. The
-//   gesture latch is the only timing heuristic left and it gates attach only —
-//   a false positive re-pins, it can never tear follow down.
+// - ATTACH is position-driven and intent-gated: landing at the physical clamp
+//   attaches while following (our own pin write echoing back) or inside an
+//   active gesture latch; a gesture-latched downward arrival inside the
+//   reattach zone attaches; a pointer released inside the zone after downward
+//   movement attaches. Content shrinking under a detached reader (a reply
+//   settling out of the row list, a collapsing block) also clamps scrollTop
+//   to the bottom with no input — that arrival carries no latch, so it can
+//   never re-engage follow and the next growth cannot yank the reader down.
+//   The gesture latch is the only timing heuristic left and it gates attach
+//   only — a false positive re-pins, it can never tear follow down.
 // - While following, a scroll event that leaves a gap open is corrected by
 //   re-pinning rather than classified.
 // - ResizeObserver deliveries (contentGrowth) never change follow state; they
@@ -194,11 +199,17 @@ export function reduceFollowEvent(
       const next = { ...state, lastGap: gap };
 
       if (isAtBottom(gap, config)) {
-        // At the physical clamp — attaching is always safe, whether the user
-        // landed here or our own pin write echoed back. Also counts as
-        // downward movement for the pointer-release re-check.
-        next.following = true;
+        // At the physical clamp. Counts as downward movement for the
+        // pointer-release re-check, but attaching needs evidence of intent:
+        // our own pin write echoing back (still following) or an arrival
+        // inside an active gesture latch. Content shrinking under a detached
+        // reader (a reply settling out of the row list, a collapsing block)
+        // also clamps scrollTop here with no input — attaching on that would
+        // let the next growth yank the reader to the bottom.
         next.dragTowardBottom = true;
+        if (state.following || now <= state.latchUntil) {
+          next.following = true;
+        }
         return { state: next, pin: false };
       }
 

crates/agent-gateway/web/test/scroll-follow-core.test.mjs

@@ -50,10 +50,39 @@ test("constants coupling: reserve band and DPR tolerance", () => {
   assert.ok(BOTTOM_ATTACH_THRESHOLD_PX >= 4);
 });
 
-test("fractional-DPR clamp shortfall still attaches (c4d6471)", () => {
+test("fractional-DPR clamp shortfall attaches inside the latch (c4d6471)", () => {
   // Windows 125%/150% scaling clamps scrollTop 1-3px short of the physical
-  // bottom; landing there must attach with no latch and no pointer.
-  const { state } = run([wheelUp(), growth(500), scroll(3, 10_000)]);
+  // bottom; a latched downward arrival landing there must still attach (the
+  // attach threshold covers the shortfall).
+  const { state } = run([
+    wheelUp({ now: 0 }),
+    growth(500),
+    wheelDown({ now: 9_800 }), // latch until 10_300
+    scroll(3, 10_000),
+  ]);
+  assert.equal(state.following, true);
+});
+
+test("content shrink clamping a detached reader never re-attaches", () => {
+  // A reply settling out of the row list (or a collapsing block) shrinks
+  // scrollHeight; the browser clamps scrollTop and emits a scroll event at
+  // the bottom with no input and no latch. Follow must stay off, and the
+  // regrowth that lands right after must not pin — this was the "jump to
+  // the bottom when the reply finishes" bug.
+  const clamped = run([wheelUp({ now: 0 }), growth(2000), scroll(0, 10_000)]);
+  assert.equal(clamped.state.following, false);
+  // The clamp still counts as downward movement for a later release check.
+  assert.equal(clamped.state.dragTowardBottom, true);
+
+  const regrown = run([growth(1800)], { state: clamped.state });
+  assert.equal(regrown.state.following, false);
+  assert.equal(regrown.pin, false);
+});
+
+test("pin echo at the clamp keeps following without a latch", () => {
+  // While following, our own pin write echoes back as a scroll event at the
+  // clamp long after any input; it must keep follow engaged.
+  const { state } = run([growth(0), scroll(2, 10_000)]);
   assert.equal(state.following, true);
 });
 

crates/agent-gui/src/lib/chat-scroll/scrollFollowCore.ts

@@ -14,11 +14,16 @@
 //   after a programmatic pin (the abort lands with the next main-thread
 //   commit); those frames carry no input and no drag, so they can never
 //   detach.
-// - ATTACH is position-driven: landing at the physical clamp always attaches;
-//   a gesture-latched downward arrival inside the reattach zone attaches; a
-//   pointer released inside the zone after downward movement attaches. The
-//   gesture latch is the only timing heuristic left and it gates attach only —
-//   a false positive re-pins, it can never tear follow down.
+// - ATTACH is position-driven and intent-gated: landing at the physical clamp
+//   attaches while following (our own pin write echoing back) or inside an
+//   active gesture latch; a gesture-latched downward arrival inside the
+//   reattach zone attaches; a pointer released inside the zone after downward
+//   movement attaches. Content shrinking under a detached reader (a reply
+//   settling out of the row list, a collapsing block) also clamps scrollTop
+//   to the bottom with no input — that arrival carries no latch, so it can
+//   never re-engage follow and the next growth cannot yank the reader down.
+//   The gesture latch is the only timing heuristic left and it gates attach
+//   only — a false positive re-pins, it can never tear follow down.
 // - While following, a scroll event that leaves a gap open is corrected by
 //   re-pinning rather than classified.
 // - ResizeObserver deliveries (contentGrowth) never change follow state; they
@@ -194,11 +199,17 @@ export function reduceFollowEvent(
       const next = { ...state, lastGap: gap };
 
       if (isAtBottom(gap, config)) {
-        // At the physical clamp — attaching is always safe, whether the user
-        // landed here or our own pin write echoed back. Also counts as
-        // downward movement for the pointer-release re-check.
-        next.following = true;
+        // At the physical clamp. Counts as downward movement for the
+        // pointer-release re-check, but attaching needs evidence of intent:
+        // our own pin write echoing back (still following) or an arrival
+        // inside an active gesture latch. Content shrinking under a detached
+        // reader (a reply settling out of the row list, a collapsing block)
+        // also clamps scrollTop here with no input — attaching on that would
+        // let the next growth yank the reader to the bottom.
         next.dragTowardBottom = true;
+        if (state.following || now <= state.latchUntil) {
+          next.following = true;
+        }
         return { state: next, pin: false };
       }
 

crates/agent-gui/src/pages/ChatPage.tsx

@@ -3831,7 +3831,11 @@ export function ChatPage(props: ChatPageProps) {
       resetLiveTranscript(transcriptStore);
       setConversationAbortController(conversationId, cancellation.userStop);
       setConversationSendingState(conversationId, true);
-      if (isConversationVisible()) {
+      // Queue-drained auto-starts are not a user gesture: the reader may be
+      // deep in history when the previous run finishes, and force-pinning
+      // for the next queued turn would yank them to the bottom. Manual sends
+      // still pin (here and via resetVisibleTransientState below).
+      if (isConversationVisible() && !overrides?.preserveComposerOnStart) {
         scrollFollowRef.current?.stickToBottom();
       }
     }

crates/agent-gui/test/chat/scroll-follow-core.test.mjs

@@ -48,10 +48,39 @@ test("constants coupling: reserve band and DPR tolerance", () => {
   assert.ok(BOTTOM_ATTACH_THRESHOLD_PX >= 4);
 });
 
-test("fractional-DPR clamp shortfall still attaches (c4d6471)", () => {
+test("fractional-DPR clamp shortfall attaches inside the latch (c4d6471)", () => {
   // Windows 125%/150% scaling clamps scrollTop 1-3px short of the physical
-  // bottom; landing there must attach with no latch and no pointer.
-  const { state } = run([wheelUp(), growth(500), scroll(3, 10_000)]);
+  // bottom; a latched downward arrival landing there must still attach (the
+  // attach threshold covers the shortfall).
+  const { state } = run([
+    wheelUp({ now: 0 }),
+    growth(500),
+    wheelDown({ now: 9_800 }), // latch until 10_300
+    scroll(3, 10_000),
+  ]);
+  assert.equal(state.following, true);
+});
+
+test("content shrink clamping a detached reader never re-attaches", () => {
+  // A reply settling out of the row list (or a collapsing block) shrinks
+  // scrollHeight; the browser clamps scrollTop and emits a scroll event at
+  // the bottom with no input and no latch. Follow must stay off, and the
+  // regrowth that lands right after must not pin — this was the "jump to
+  // the bottom when the reply finishes" bug.
+  const clamped = run([wheelUp({ now: 0 }), growth(2000), scroll(0, 10_000)]);
+  assert.equal(clamped.state.following, false);
+  // The clamp still counts as downward movement for a later release check.
+  assert.equal(clamped.state.dragTowardBottom, true);
+
+  const regrown = run([growth(1800)], { state: clamped.state });
+  assert.equal(regrown.state.following, false);
+  assert.equal(regrown.pin, false);
+});
+
+test("pin echo at the clamp keeps following without a latch", () => {
+  // While following, our own pin write echoes back as a scroll event at the
+  // clamp long after any input; it must keep follow engaged.
+  const { state } = run([growth(0), scroll(2, 10_000)]);
   assert.equal(state.following, true);
 });