[Task] Consolidate session timeline scroll owners into single state machine

[Astro-Han]

Use this for maintainer or agent execution work that is not a user-facing bug report or feature request.

Keep the issue concrete enough that an agent can understand the target, scope, and verification path.

Goal

Make the session timeline scroll controller the single source of truth for scroll decisions so that upward reading, bottom follow, jump-to-latest, and resize-driven restore behavior no longer depend on three parallel owners that can race each other.

Concretely, when this task is done:

• the controller owns the decision state,
• history reading preserves anchor position instead of snapping back to latest,
• bottom-follow behavior is still preserved when the user is actually pinned to latest,
• and the current workaround logic can be retired from the auxiliary scroll helpers.

Scope

In scope:

• Consolidate scroll ownership around session-timeline-scroll-controller.ts.
• Move createAutoScroll toward a pure measurement + imperative-scroll helper with no independent follow / userScrolled state.
• Remove bottomFollowLock as a parallel decision owner from use-session-scroll-dock.ts.
• Preserve current timeline UX semantics while simplifying ownership.
• Add focused unit and E2E coverage for the consolidated behavior.

Out of scope:

• Any visual redesign of the conversation flow.
• Toolbar, bubble, tooltip, or trow styling work from slice 11b.1.
• Broader message rendering refactors unrelated to scroll ownership.
• Reopening the already-shipped minimum workaround in PR refactor(session): rewrite session view per W1 visual lock for slice 11b.1 #589 unless needed to land the consolidation safely.

Relevant files or context

Background:

• The session timeline currently has 3 parallel scroll owners that can race each other:
  1. createAutoScroll — ResizeObserver auto-snap-bottom with internal userScrolled bookkeeping
  2. use-session-scroll-dock.ts — bottomFollowLock with 3s expiry plus followBottom() scheduling
  3. session-timeline-scroll-controller.ts — high-level scroll intent state machine (following_latest, reading_history, restore_latest, etc.)

Recent regressions that motivated this follow-up:

• First regression: scrolling to a history position, then receiving a new turn, no longer auto-snapped correctly. The minimum patch suppressed createAutoScroll ResizeObserver behavior for 500ms after wheel-up.
• Second regression: scrolling to a position, then scrolling again, snapped the viewport back to bottom. The minimum patch changed controller observe behavior, widened gesture-based lock cancellation, and reordered message-timeline.tsx onScroll handling.

Likely files:

• packages/app/src/pages/session/session-timeline-scroll-controller.ts
• packages/app/src/pages/session/use-session-scroll-dock.ts
• packages/app/src/pages/session/use-session-timeline-interaction.ts
• packages/app/src/pages/session/message-timeline.tsx
• corresponding unit + E2E tests

Related context:

• This follow-up was intentionally split out from slice 11b.1 so the minimum fixes could ship without delaying the current visual rewrite PR.
• Related issue: [Feature] Rewrite packages/ui + packages/app visual layer against PawWork design system (incremental PR series) #440 conversation-flow rewrite planning
• Related issue: refactor(session): rewrite session view per W1 visual lock for slice 11b.1 #589 current slice PR context (not to be merged into this issue body as scope)

Verification

• Unit tests cover:
  • weak wheel or touch gesture transitions the controller into reading_history
  • content_resize during reading_history restores anchor rather than latest
  • submit / layout reset while returning to latest restores the latest position correctly
• E2E covers:
  • scroll up into history, receive a new turn, viewport stays at the history position
  • click Jump to Bottom, viewport returns to latest
• Manual verification confirms:
  • pinned-bottom behavior still follows latest
  • reading history no longer snaps back to bottom unexpectedly
  • nested scroll containers do not hijack main timeline state
• No parallel userScrolled state remains inside createAutoScroll
• No parallel bottomFollowLock remains as an independent owner

Execution mode

Agent should investigate and propose a plan first

[Astro-Han]

补一条和 #615 的边界说明。

#615 里的 scroll stuttering 和这个 issue 有交集，但 #595 只负责一件事：把 session timeline 的滚动决策收敛到一个状态机，避免 reading history、bottom follow、jump-to-latest、resize restore 互相打架。

它不负责解决全部性能问题，也不直接承担 timeline virtualization 或 message rendering cost。那些更应该归到 #600 / #601 里，用 PR0 数据和上游方案一起判断。

[Astro-Han]

RCA from a reproduction on 2026-05-15

While doing manual Electron testing for PR #628 (a pure CSS change to the jump-to-bottom button) the user observed an unrelated regression: scrolling upward in a long session immediately snaps the view back to the bottom. The exported session log (pawwork-session-sunny-orchid-2026-05-15-04-47-31-autoscrolldone.json) makes the controller behaviour explicit.

Of the 1,219 session.timeline.scroll_controller events captured, every single one transitions from following_latest to following_latest — the controller never leaves follow mode, even for real user input.

intent_type / observation_type	reason	count	What it means
wheel_scroll	weak_scroll_observed	639	User wheel events classified as "weak", not strong enough to leave follow mode
scroll_sample	weak_scroll_observed	564	Scroll samples classified the same way
scroll_sample	submit_restore_latest_after_top_reset	14	User scrolled to top → top-reset fired → controller force-restored to latest, pulling the viewport back
scroll_sample	explicit_bottom_navigation	1	jump button click (the user finally gave up)
jump_latest	explicit_bottom_navigation	1	same click

Two distinct root causes both rooted in scroll-owner / scroll-controller divergence:

1. weak_scroll_observed threshold is too strict. Genuine wheel input is being classified as weak, so the controller never demotes from following_latest to a paused/pinned mode. The user feels their wheel doing nothing.
2. submit_restore_latest_after_top_reset overrides user intent. When the user reaches the top, a top-reset fires, but instead of yielding to the user the controller immediately restores latest, snapping the viewport down — this is the literal "scrolls up, jumps down" the user reported.

Both are exactly the kind of cross-owner race this issue is meant to retire. Posting here rather than opening a new issue so the consolidation work has a concrete recent repro.

Reproduction artifact: docs/debug-session-log/pawwork-session-sunny-orchid-2026-05-15-04-47-31-autoscrolldone.json (local; 1.5 MB, 1929 events truncated).