refactor(web): terminal focus requests name the terminal they focus#25009

Problem

Terminal focus went through a counter. ChatView kept terminalFocusRequestId in state, every terminal action incremented it, the value was passed down through the drawer, the panel and the split panes, and each viewport refocused itself in an effect whenever the counter, its visibility or its active flag changed. The counter also didn't say which terminal it was for, so whichever active viewport saw the change took focus.

Change

• lib/terminalFocus now holds a single pending request, keyed by thread and terminal id, and the newest request wins. Handlers call focusTerminal, focusActiveDrawerTerminal, focusActivePanelTerminal or focusPanelTerminalAfterClose after they update the stores.
• TerminalSessionViewport registers from its container ref callback. It takes a waiting request when it mounts, when it becomes visible (in the existing visibility layout effect) or when it gains the operate grant (in the existing grant layout effect).
• Callers migrated: useChatTerminalActions (open, toggle, split, new, close, run script, panel add/split/activate/close), useRightPanelActions (activating a terminal surface, showing the panel), PersistentThreadTerminals, useWorktreeSetup, revealThreadTerminal, useRightPanelSurfaceClose, DevicePanel (closing a surface focuses the terminal surface the panel falls back to) and WelcomeWizard (autoFocus).
• The focusRequestId prop is gone from ThreadTerminalDrawer, TerminalSplitPanes, TerminalViewport, ChatTerminalDrawers and both PersistentThreadTerminal* components.

Behavior changes

• Focus follows explicit requests. Before, a viewport also refocused whenever it became visible or became the active split. Now a viewport that shows up with no pending request leaves focus where it is. Every path that opens, switches or reveals a terminal makes a request, including the sidebar reveal, worktree setup, panel show/close and device close.
• ChatView's per-thread terminalOpen transition effect is gone. When the drawer closed, it focused the composer one frame later. The existing composer focus effect, which runs on terminalOpen going false, already does the same thing.
• Entering a thread whose drawer is open focuses the drawer terminal on every visit. Before, the per-thread ref map limited this to the first visit, though the viewport's counter effect usually fired on later visits anyway. If a navigating handler made its own request first (sidebar terminal reveal, via focusTerminalOnNavigation), that request wins, even when the revealed viewport already took focus in the layout phase before ChatView's thread-enter effect ran. Only that call marks the thread, and only when it is not the thread ChatView already shows, so ordinary in-thread terminal actions never suppress a later entry. ChatView's effect cleanup clears the entered thread, so coming back to the same thread after ChatView remounts (for example from Pull Requests) focuses the drawer again.
• No logging changes.

What this improves

• Removes sync: the focusRequestId counter state and its prop plumbing through six components. Terminal actions no longer set ChatView state just to move focus. This saves no renders: ChatView subscribes to the terminal UI and right-panel stores these actions already change, and the counter update was batched into the same render.
• Focus goes to the terminal that was asked for, not to whatever active viewport noticed the counter change.
• Bug-fix claims: one, found in review of this PR. The collapsed drawer clips its viewport (grid-rows-[0fr]) rather than hiding it, so the wrapper took focus while the hidden surface refused it, and the request counted as done; reopening the drawer left focus on a wrapper that ignores typing. A hidden viewport now declines focus (focusTerminalViewport), so the request waits for it to show. apps/web/src/lib/terminalFocus.browser.test.ts covers this with real DOM focus and fails without the check. The old counter behavior is otherwise not covered by a browser test that fails on main. apps/web/src/lib/terminalFocus.test.ts covers the new request model: newest request wins, it waits for mount or visibility, it is dropped when the drawer closes, thread entry defers to a navigating handler's request (in React's commit order, with the viewport registered first) for that entry only, re-entering the same thread after in-thread terminal actions focuses the drawer, and panel close falls back to a terminal surface.

Effect report

• Removed: the viewport focus effect, and ChatView's terminalOpen transition effect, which set state.
• Added: a ChatView effect keyed on the active thread ref that calls focusTerminalOnThreadEnter. Entering a thread is a route change, not a handler, and appInit (where a router subscription would go) is not on main yet.
• Kept: the viewport's visibility and grant layout effects, which now also retry a waiting request.
• autoFocus (WelcomeWizard) makes one focus request per viewport, guarded by a ref, so a re-attached container ref cannot pull focus back on each output chunk. When the viewport cannot take focus yet (no operate grant), the request waits like any other.

Render scenarios: mount thread and switch thread render ChatView and the terminal drawers, so they cover the touched code (no render savings expected). Numbers are left to the coordinator.

Verification

• vp test run src/lib/terminalFocus.test.ts src/lib/revealThreadTerminal.test.ts: 16 passed. The re-entry test fails against the previous lastRequestedThreadKey version.
• vp test run src/components/device/DevicePanel.browser.test.tsx: 1 passed (its rightPanelStore mock gained selectThreadRightPanelState)
• vp test run --project browser src/lib/terminalFocus.browser.test.ts: 1 passed, and fails with the visibility check removed.
• vp run check:changed (rebased on main): see the latest commit. scripts/effect-budget.json is left as main has it.
• Render metrics: pending — the harness PR adds them

Model: Claude Opus 5.5, Claude Code harness.

🤖 Generated with Claude Code