Thinking Path

• Hermes WebUI's streaming chat lets the user scroll up to read earlier output mid-stream while staying out of the way of the live token append
• That requires a clear "user-pinned" vs "bottom-following" distinction, with the boundary forgiving enough to survive trackpad momentum (bug(streaming): auto-scroll still overrides user scroll position on macOS app — #677 regression / edge case #1360) but strict enough to actually let small upward scrolls escape the live region (bug(streaming): small upward scrolls during streaming are overridden until user escapes near-bottom threshold #1731)
• The current scroll listener picked the same threshold (250px + _nearBottomCount >= 2 hysteresis) for both directions. That's correct for re-pinning (entering the dead zone), but for unpinning it stranded users who scrolled up by less than 250px — every upward sample still landed inside the near-bottom region, so the counter kept incrementing and _scrollPinned stayed true. The next streaming token then snapped them back
• The 250px dead zone is locked in by bug(streaming): auto-scroll still overrides user scroll position on macOS app — #677 regression / edge case #1360 / bug(streaming): auto-scroll overrides user scroll position during streaming — cannot read up while AI is responding #677 (macOS small window + trackpad momentum re-pin protection — covered by tests/test_issue1360_streaming_scroll_hardening.py::test_scroll_repin_dead_zone_is_wider_for_mac_app_windows) so the fix has to make the asymmetry of the two directions explicit rather than relax the threshold
• Track _lastScrollTop in the listener closure: an explicit upward delta (>2px) unpins immediately and resets the counter; downward / stationary samples keep the original hysteresis re-pin path so bug(streaming): auto-scroll still overrides user scroll position on macOS app — #677 regression / edge case #1360 stays protected
• Programmatic scrolls already bail before the rAF schedule via _programmaticScroll, so _lastScrollTop only ever sees user-driven motion and scrollToBottom() cannot accidentally unpin

What Changed

static/ui.js — scroll listener inside the #messages container:

• Add _lastScrollTop tracker (closure-scoped, not exported)
• In the rAF callback, compute movedUp = _lastScrollTop !== null && top < _lastScrollTop - 2
• Update _lastScrollTop = top every sample (only when the listener actually runs, i.e. user-driven scrolls)
• Branch:
  • movedUp → _nearBottomCount = 0; _scrollPinned = false; (no hysteresis, immediate unpin) — bug(streaming): small upward scrolls during streaming are overridden until user escapes near-bottom threshold #1731
  • else → original _nearBottomCount = nearBottom ? +1 : 0; _scrollPinned = count >= 2; path — bug(streaming): auto-scroll still overrides user scroll position on macOS app — #677 regression / edge case #1360

tests/test_issue1731_upward_scroll_unpins.py — new regression suite covering:

• direction tracker (_lastScrollTop) exists and is updated each sample
• the movedUp flag is computed with a small (~2px) tolerance
• upward branch sets _scrollPinned=false and resets _nearBottomCount, with no >=2 gate
• downward / stationary branch preserves both _nearBottomCount=nearBottom?+1:0 and _scrollPinned=_nearBottomCount>=2
• 250px re-pin dead zone is still present
• _programmaticScroll early-return still runs before requestAnimationFrame

Net change: +23 / -7 in static/ui.js, +159 in tests. Most of the diff is updated comments; the live-code delta is ~10 lines.

Why It Matters

Reporter (Cygnus, Discord, May 5) hit this on every small scroll-up during a streaming reply. It's an interaction bug, not a visual one — and small enough that it doesn't trigger the scrollToBottomBtn either, since _scrollPinned stays true. The user has no obvious escape hatch except a fling-scroll past the entire 250px zone. Direction detection makes "I want to read what you just wrote" work the way it should.

Verification

Automated

pytest tests/test_issue1731_upward_scroll_unpins.py \
       tests/test_issue677.py \
       tests/test_issue1360_streaming_scroll_hardening.py \
       tests/test_issue1690_scroll_completion.py \
       tests/test_parallel_session_switch.py -v --timeout=60

→ 58 passed (6 new, 52 pre-existing scroll regression tests, all green).

Full repo pytest tests/ is also clean on this branch except for 10 pre-existing failures on master (test_ctl_script.py, test_issue609.py, test_sprint3.py — environment / sandbox-dependent, unrelated to this change). Verified by stashing the diff and re-running on plain master @ d8cd556 — same 10 fail there too.

Manual

Repro page (vendored copy of the listener with a fix toggle): simulated streaming + a 100px upward wheel mid-stream.

• Before fix on: _scrollPinned stays true after the upward scroll, next streaming token snaps the viewport back to the bottom — exactly what the reporter described.
• After fix on: _scrollPinned flips to false immediately, the "scrolled up" banner appears, subsequent tokens append below without yanking the viewport. Scrolling back into the dead zone (downward, 2 consecutive near-bottom samples) re-pins as before.
• macOS trackpad momentum case (downward fling that decelerates inside the dead zone): unchanged — falls through the else branch, hysteresis still gates re-pin until 2 consecutive near-bottom samples settle. bug(streaming): auto-scroll still overrides user scroll position on macOS app — #677 regression / edge case #1360 protection intact.

(Before/after screenshots attached below.)

Risks / Follow-ups

• macOS momentum re-pin (bug(streaming): auto-scroll still overrides user scroll position on macOS app — #677 regression / edge case #1360) — protected. The hysteresis counter and 250px threshold are both unchanged on the downward / stationary path. Verified by tests/test_issue1360_streaming_scroll_hardening.py still passing.
• Programmatic snap-to-bottom polluting _lastScrollTop — guarded. _programmaticScroll short-circuits before the rAF schedule, so programmatic scrolls never write to _lastScrollTop and can't trigger spurious unpins on the next user wheel event. Asserted by test_programmatic_scroll_guard_still_skips_listener.
• Single-pixel jitter / rAF reflow — the >2px tolerance absorbs sub-pixel rounding without missing a real wheel/trackpad up-tick.
• Reload / new session — _lastScrollTop initializes to null, first sample skips the upward branch, falls into hysteresis path. Identical behavior to today on first load.
• Initial render bottom-pin — unchanged. _scrollPinned still defaults to true; the listener only runs on actual scroll events.
• No new dependencies, no build step changes, no CSS changes, no API changes. Pure listener logic.

Possible follow-up (not in this PR): wire _lastScrollTop reset into scrollToBottom() for the rare case where a programmatic snap is followed immediately by a user wheel — currently safe via _programmaticScroll, but could be a defensive nicety. Out of scope here.

Model Used

• AI-assisted via OpenClaw — Anthropic claude-opus-4-7 (xhigh thinking)
• Diagnosis and fix authored in collaboration with the user; investigation traces, comment block phrasing, and test scaffolding came from the model. All assertions and code paths reviewed against the existing scroll regression suite before push.