Summary

Describe the problem and fix in 2-5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: Chat auto-follow in the Control UI could re-engage too aggressively when the user manually scrolled slightly upward during streaming, because the logic only used a broad "near bottom" threshold.
• Why it matters: Users trying to read slightly older messages could get pulled back to the bottom, which makes streaming chats feel jumpy and hard to control.
• What changed: Added an explicit manual-scroll release lock, only reacquire follow when the user is truly back at the bottom, ignore upward wheel intent from nested scrollables, and cover the smooth auto-scroll edge cases in ui/src/ui/app-scroll.test.ts.
• Rebase note: Rechecked against latest main after feat(ui): add WebChat auto-scroll mode selector #81629 landed the separate persisted WebChat chatAutoScroll mode selector. This PR remains the manual-scroll follow-lock / sticky-bottom bug-fix lane, not a duplicate of the setting work.
• What did NOT change (scope boundary): No session-management refactors, no tool-call visibility changes, no settings/auth/token behavior changes, and no unrelated UI restructuring.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Control UI] Chat auto-scroll overrides user scroll during streaming #37500
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: The chat scroll state treated "near bottom" as equivalent to "should still auto-follow", so a small upward manual scroll could still satisfy follow conditions and snap the user back down on subsequent updates.
• Missing detection / guardrail: There was no explicit "user took over scrolling" lock and no test coverage for slight upward manual scrolling during streaming.
• Contributing context (if known): Smooth auto-scroll progress and user-driven upward scroll were both funneled through the same scroll-state path, which made intent ambiguous.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: ui/src/ui/app-scroll.test.ts
• Scenario the test should lock in: When the user wheels or scrolls slightly upward from the bottom during chat streaming, auto-follow disengages immediately and does not re-enable until the user actually returns to the bottom.
• Why this is the smallest reliable guardrail: The behavior is contained in the chat scroll state machine and can be deterministically exercised with direct scroll/wheel events.
• Existing test that already covers this (if any): Existing tests covered broad near-bottom behavior, but not manual release/reacquire intent or the smooth auto-scroll edge cases.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

List user-visible changes (including defaults/config).
If none, write None.

• Chat no longer snaps back to the bottom as easily when the user manually scrolls slightly upward during streaming.
• Auto-follow resumes only when the user truly returns to the bottom.
• Wheel events coming from nested scrollable content inside the chat do not incorrectly disable or fight chat scroll state.
• The persisted chatAutoScroll setting from feat(ui): add WebChat auto-scroll mode selector #81629 is preserved and respected; the follow-lock only tightens the default/manual sticky-bottom state machine around that setting.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

Before:
[user scrolls slightly up] -> [still "near bottom"] -> [next stream update] -> [auto-follow re-engages]

After:
[user scrolls slightly up] -> [follow locked off] -> [next stream update] -> [stays in place]
[user returns to bottom] -> [follow unlocked] -> [next stream update] -> [auto-follow resumes]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Node/Vite dev setup
• Model/provider: N/A
• Integration/channel (if any): Control UI chat
• Relevant config (redacted): local gateway on ws://127.0.0.1:18789

Steps

1. Open the Control UI chat while a response is streaming.
2. Scroll slightly upward from the bottom or wheel upward during streaming.
3. Continue streaming, then return fully to the bottom.

Expected

• Slight upward manual scrolling disengages auto-follow.
• Streaming updates do not snap the view back down.
• Auto-follow resumes only after returning to the bottom.

Actual

• Before fix: chat could snap back down while the user was still trying to read upward.
• After fix: chat stays released until the bottom is reached again.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Real behavior proof

• Behavior or issue addressed: Control UI WebChat streaming should not snap back to the bottom after the user manually scrolls slightly upward; follow-lock should release on manual upward intent and reacquire only when the user returns to the bottom.
• Real environment tested: macOS local OpenClaw checkout, Node 24.14.0, rebased on current main with feat(ui): add WebChat auto-scroll mode selector #81629's persisted chatAutoScroll setting present. The proof command imports the actual ui/src/ui/app-scroll.ts implementation and exercises the WebChat scroll state used by the Control UI.
• Exact steps or command run after this patch: Ran a local pnpm exec tsx proof command against ui/src/ui/app-scroll.ts with chatAutoScroll: "near-bottom", simulating a user scroll from bottom to scrollTop=1540, a streaming scheduleChatScroll() tick, then returning to bottom at scrollTop=1576.
• Evidence after fix: Copied terminal output from the local proof command:

{
  "proof": "Control UI WebChat manual-scroll follow-lock after patch",
  "afterManual": {
    "scrollTop": 1540,
    "chatUserNearBottom": false,
    "chatFollowLocked": true,
    "chatNewMessagesBelow": false,
    "chatAutoScroll": "near-bottom"
  },
  "afterStreamTick": {
    "scrollTop": 1540,
    "chatUserNearBottom": false,
    "chatFollowLocked": true,
    "chatNewMessagesBelow": true
  },
  "afterReturnBottom": {
    "scrollTop": 1576,
    "chatUserNearBottom": true,
    "chatFollowLocked": false,
    "chatNewMessagesBelow": false
  }
}

• Observed result after fix: After manual upward scroll, chatFollowLocked is true and the streaming tick leaves scrollTop at 1540 instead of snapping to 2000; chatNewMessagesBelow becomes true. After returning to bottom, chatFollowLocked clears and chatNewMessagesBelow clears. The persisted chatAutoScroll mode remains near-bottom.
• What was not tested: Full end-to-end multi-browser matrix, authenticated live gateway streaming, and non-chat surfaces.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Rebasing against current main kept feat(ui): add WebChat auto-scroll mode selector #81629's chatAutoScroll selector/settings path intact, then ran pnpm test ui/src/ui/app-scroll.test.ts ui/src/ui/app-chat.test.ts.
• Edge cases checked: Slight upward scroll near bottom, re-enable only at the bottom, nested scrollable wheel intent, post-wheel near-bottom lock behavior, and smooth auto-scroll transition handling.
• What you did not verify: Full end-to-end multi-browser matrix, full UI suite, and non-chat surfaces.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: The new release/reacquire thresholds could feel slightly different than before for some users near the bottom of the thread.
  • Mitigation: Thresholds are small and targeted, and focused unit tests lock in the intended behavior.
• Risk: Wheel-based intent handling could interfere with nested scrollable UI inside messages.
  • Mitigation: Nested scrollable ancestors are explicitly ignored and covered by tests.