refactor(tui): keybinding precedence - promote hardcoded keys to actions (#333)

## Summary
- Refactors TUI key dispatch so the configurable `KeybindingResolver` is
the single source of truth for overridable keys, eliminating the
silent-shadow bug where hardcoded `switch keyStr` blocks short-circuited
user-configured bindings.
- Promotes every previously-hardcoded overridable key (`q`, `?`, `g`,
`v`, up/k, down/j, `/`, `:`, `G`) into a proper `action.Type` registered
as a default `UserCommand` and bound via `defaultViewsConfig`. Layer-1
system keys (`ctrl+c`, `esc`, `tab`, `shift+tab`) and modal-dismissal
keys remain hardcoded by design.
- Adds a model-level global-scope-only fallback so a view-scoped binding
for `q`/`?` cannot leak into the global `Quit`/`ShowHelp` handler.

## Phases
1. `0393dfd` Phase 1 — Action enums (`Sessions*`,
`GoToTop`/`GoToBottom`, `Quit`, `ShowHelp`), default `UserCommand`
registrations, `handleGlobalAction` extension.
2. `44fb686` Phase 2 — Sessions view: register defaults, delete
hardcoded blocks, wire view-internal `IsAction` dispatch.
3. `e6d082e` Phase 3 — Global `q`/`?` migration with `commandFor` helper
and global-scope-only model fallback.
4. `9df2818` Phase 4 — Tasks tree-pane + review view `g`/`G` migration
(detail-pane viewport navigation left hardcoded).
5. `4c7377c` Phase 5 — Precedence regression tests including
`TestPromotedKeysAreOverridable` driving `Model.Update` end-to-end
(resolver-only tests would have been GREEN on the original bug).
6. `2cd968f` Phase 6 — `AGENTS.md` precedence rule + help-text
regression test.
7. `9b8670f` Post-review polish — godocs, why-comments, additional
coverage (review-focus `?` carve-out, default-binding e2e, modal
`q`-under-override, out-of-scope-binding case).

## Test plan
- [ ] `mise run test` — full suite passes
- [ ] `env GOTOOLCHAIN=go1.26.2 golangci-lint run ./internal/core/config
./internal/tui ./internal/tui/views/tasks ./internal/tui/views/review` —
scoped lint clean
- [ ] Manually verify default keybindings still behave: in TUI, `q`
quits, `?` opens help, `g`/`v` work in sessions, `g`/`G` jump in
tasks/review, `/` enters filter mode, `:` opens command palette.
- [ ] Manually verify user override: configure a custom `g` binding in
sessions scope and confirm it takes precedence over
`SessionsRefreshGitStatuses`.
- [ ] Manually verify modal dismissal: open help modal, press `q` (or
`esc`) — closes regardless of user binding.

Author: hay-kot

AGENTS.md

@@ -198,6 +198,16 @@ Available variables vary by context - see `internal/core/config/validate.go` for
 
 Never silently discard errors. If an error cannot be presented to the user (e.g., in background polling, cache refresh, or TUI status fetching), log it at an appropriate level (`debug` for expected/transient failures, `warn` for configuration problems). Prefer degraded behavior with logging over silent fallbacks — for example, show a `StatusMissing` indicator instead of dropping an item from the UI.
 
+### Keybinding Precedence
+
+The TUI dispatches keystrokes through three layers, in this order:
+
+1. **Layer 1: hardcoded, non-overridable** - `ctrl+c`, `esc`, `tab`, and `shift+tab` in normal-mode handling, plus modal-lifecycle dismissal keys (`esc` / `q`) inside dialogs and modals.
+2. **Layer 2: configurable via `KeybindingResolver`** - every other user-overridable key. Default bindings live in `defaultViewsConfig` (`internal/core/config/config_views.go`), and user config in `cfg.Views.{Global,Sessions,Tasks,Review}.Keybindings` overrides those defaults because `maps.Copy(merged, user)` overlays user values onto the merged map.
+3. **Layer 3: bubbles list internals** - the underlying list component claims keys like `g`, `G`, `j`, `k`, `h`, `l`, `u`, `d`, `f`, `b`, `/`, `?`, `q`, and `esc`. This is intentionally out of scope for hive keybinding configuration: the resolver consumes configured bindings before the list sees them.
+
+When adding a new overridable key, do not add a new `if keyStr == "X"` block in view code. Register an `action.Type` in `internal/core/action/type.go`, add a default `UserCommand` in `defaultUserCommands` (`internal/core/config/config.go`), bind it in `defaultViewsConfig`, and dispatch it from `internal/tui/model_handlers.go`.
+
 ### Session States
 
 ```

internal/core/action/type.go

@@ -47,6 +47,16 @@ package action
 //	DocsTogglePreview
 //	DocsToggleTree
 //	DocsSelectRepo
+//	SessionsRefreshGitStatuses
+//	SessionsTogglePreview
+//	SessionsNavigateUp
+//	SessionsNavigateDown
+//	SessionsFilterStart
+//	SessionsCommandPaletteOpen
+//	GoToTop
+//	GoToBottom
+//	Quit
+//	ShowHelp
 //
 // )
 type Type string

internal/core/action/type_enum.go

@@ -303,6 +303,64 @@ var defaultUserCommands = map[string]UserCommand{
 		Silent: true,
 		Scope:  []string{"review"},
 	},
+	"SessionsRefreshGitStatuses": {
+		Action: action.TypeSessionsRefreshGitStatuses,
+		Help:   "refresh git status",
+		Silent: true,
+		Scope:  []string{"sessions"},
+	},
+	"SessionsTogglePreview": {
+		Action: action.TypeSessionsTogglePreview,
+		Help:   "toggle preview pane",
+		Silent: true,
+		Scope:  []string{"sessions"},
+	},
+	"SessionsNavigateUp": {
+		Action: action.TypeSessionsNavigateUp,
+		Help:   "move selection up",
+		Silent: true,
+		Scope:  []string{"sessions"},
+	},
+	"SessionsNavigateDown": {
+		Action: action.TypeSessionsNavigateDown,
+		Help:   "move selection down",
+		Silent: true,
+		Scope:  []string{"sessions"},
+	},
+	"SessionsFilterStart": {
+		Action: action.TypeSessionsFilterStart,
+		Help:   "start filter",
+		Silent: true,
+		Scope:  []string{"sessions"},
+	},
+	"SessionsCommandPaletteOpen": {
+		Action: action.TypeSessionsCommandPaletteOpen,
+		Help:   "open command palette",
+		Silent: true,
+		Scope:  []string{"sessions"},
+	},
+	"GoToTop": {
+		Action: action.TypeGoToTop,
+		Help:   "jump to top",
+		Silent: true,
+		Scope:  []string{"tasks", "review"},
+	},
+	"GoToBottom": {
+		Action: action.TypeGoToBottom,
+		Help:   "jump to bottom",
+		Silent: true,
+		Scope:  []string{"tasks", "review"},
+	},
+	"Quit": {
+		Action: action.TypeQuit,
+		Help:   "quit",
+		Silent: true,
+	},
+	"ShowHelp": {
+		Action: action.TypeShowHelp,
+		Help:   "show help",
+		Silent: true,
+	},
 	"SendBatch": {
 		Sh: `{{ range .Form.targets }}
 {{ agentSend }} {{ .Name | shq }}:claude {{ $.Form.message | shq }}

internal/core/config/config.go

@@ -85,13 +85,24 @@ func (m MessagesViewConfig) SplitRatioOrDefault(defaultPct int) int {
 // defaultViewsConfig provides built-in per-view keybindings that users can override.
 var defaultViewsConfig = ViewsConfig{
 	Global: GlobalViewConfig{
-		Keybindings: map[string]Keybinding{},
+		Keybindings: map[string]Keybinding{
+			"q": {Cmd: "Quit"},
+			"?": {Cmd: "ShowHelp"},
+		},
 	},
 	Sessions: SessionsViewConfig{
 		Keybindings: map[string]Keybinding{
 			"r":      {Cmd: "Recycle"},
 			"d":      {Cmd: "Delete"},
 			"n":      {Cmd: "NewSession"},
+			"g":      {Cmd: "SessionsRefreshGitStatuses"},
+			"v":      {Cmd: "SessionsTogglePreview"},
+			"up":     {Cmd: "SessionsNavigateUp"},
+			"k":      {Cmd: "SessionsNavigateUp"},
+			"down":   {Cmd: "SessionsNavigateDown"},
+			"j":      {Cmd: "SessionsNavigateDown"},
+			"/":      {Cmd: "SessionsFilterStart"},
+			":":      {Cmd: "SessionsCommandPaletteOpen"},
 			"enter":  {Cmd: "TmuxOpen"},
 			"ctrl+d": {Cmd: "TmuxKill"},
 			"A":      {Cmd: "AgentSend"},
@@ -108,6 +119,8 @@ var defaultViewsConfig = ViewsConfig{
 		Keybindings: map[string]Keybinding{
 			"r": {Cmd: "TasksRefresh"},
 			"f": {Cmd: "TasksFilter"},
+			"g": {Cmd: "GoToTop"},
+			"G": {Cmd: "GoToBottom"},
 			"y": {Cmd: "TasksCopyID"},
 			"v": {Cmd: "TasksTogglePreview"},
 			"s": {Cmd: "TasksSelectRepo"},
@@ -127,6 +140,8 @@ var defaultViewsConfig = ViewsConfig{
 			"o": {Cmd: "DocsOpen"},
 			"v": {Cmd: "DocsTogglePreview"},
 			"r": {Cmd: "DocsSelectRepo"},
+			"g": {Cmd: "GoToTop"},
+			"G": {Cmd: "GoToBottom"},
 		},
 	},
 }