projmux 0.6.7 → 0.7.1

package/docs/keybindings.md

@@ -4,7 +4,7 @@ projmux is keyboard-driven, but the guaranteed launch contract is small:
 fresh installs bind `Alt-1` through `Alt-5` as plain Meta sequences
 (`M-1`..`M-5`, bytes `\x1b1`..`\x1b5`). Other actions remain discoverable in
 Settings > Keybindings. Transport-dependent actions keep their built-in
-transport default key, and Settings can add separate safe tmux plain aliases to
+transport default key, and Settings can add separate safe tmux plain keys to
 the same action. They are not installed as terminal-specific User-key
 fallbacks. `UserN` and `CSI-u` are legacy/removal/unsupported targets, not
 supported fallback guidance.
@@ -15,14 +15,26 @@ The recommended path when a key does not fire:
 2. Run `projmux setup` outside tmux to see which bytes reach the process.
 3. For supported terminals, preview `projmux init [terminal]`; add `--apply`
    only after reviewing the merge.
-4. For unsupported terminals, configure plain Meta bytes or add a tmux alias in
+4. For unsupported terminals, configure plain Meta bytes or add a custom key in
    Settings > Keybindings.
 
-Settings writes safe tmux plain chords to
-`~/.config/projmux/keymap.toml`, regenerates
-`~/.config/projmux/tmux.conf`, and hot-reloads the live tmux config when it is
-running inside tmux. Raw escape payloads, Windows Terminal `sendInput` strings,
-and tmux User keys are rejected as aliases.
+Settings saves safe tmux plain chords for actions and automatically applies the
+change to the app config and the running tmux session when Settings is opened
+from inside tmux. After each save/reset it shows the three outcomes together:
+saved, prepared, and running session. Successful in-tmux saves keep those labels
+user-facing; failure and skipped states include diagnostic terms such as
+`keymap.toml`, generated tmux config, or live tmux reload so the broken stage is
+clear. If Settings is run outside tmux, the running-session stage is skipped and
+the recovery/sync action is `projmux tmux apply`. Raw escape payloads, Windows
+Terminal `sendInput` strings, and tmux User keys are rejected as action keys.
+Settings capture diagnostics split the observed result into logical key, raw
+bytes, and the tmux key name that can be saved. Diagnostic states distinguish
+keys that did not arrive, ambiguous bytes such as Enter/Ctrl-M, and keys that
+need a supported terminal adapter. Safe direct keys are logical tmux names such
+as `M-a`, `M-1`, `C-r`, `C-Space`, function/navigation names, or printable
+keys. Raw escape bytes, CSI-u, xterm modified-key payloads, and tmux
+UserKey/UserSequence names stay diagnostic-only and are not promoted into
+`keymap.toml`.
 
 ## Quick Start
 
@@ -32,10 +44,14 @@ These shortcuts are the guaranteed launch defaults. They need no tmux prefix.
 | --- | --- |
 | `Alt-1` | Project sidebar |
 | `Alt-2` | Notify sidebar |
-| `Alt-3` | Existing session popup |
+| `Alt-3` | Recent Windows |
 | `Alt-4` | AI split popup picker |
 | `Alt-5` | Settings |
 
+`RecentWindows:Open` opens the cross-project recent windows queue. It switches
+to the selected live tmux window using that window's current active pane; it is
+separate from `last-pane` and from the existing-session popup.
+
 The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
 session, `Ctrl-b ?` lists the live tmux bindings.
 
@@ -43,19 +59,29 @@ session, `Ctrl-b ?` lists the live tmux bindings.
 
 Settings > Keybindings lists the full action catalogue. In particular, sidebar
 keymap actions, pane switching, window switching, and rename actions remain
-visible. Transport-dependent rows show the default transport key separately
-from editable plain aliases.
-
-The Settings flow is intentionally simple: the root is one action list with
-current key summaries, and each action detail shows the action, current
-keybinding/aliases, `Add alias`, and reset. Diagnostic/probe/init workflows are
-not first-class Settings tabs; use `projmux setup` and `projmux init` from the
-terminal when key delivery needs remediation.
-
-Optional direct aliases can be added for actions such as:
+visible.
+
+The Settings flow is intentionally simple: the root is one action list with a
+key summary and state. The key summary uses the first key plus `+N`, or
+`Not bound` when no key is active. State vocabulary is limited to Default,
+Custom, Available, and Unbound. Each action detail shows the action label,
+state, a flat Keys list with `+ Add key`, Options, and a collapsed
+Troubleshooting row with Test key delivery and Advanced... entry points. Key
+rows open key detail for Remove key and Test key. Add key opens Press a key by
+default; Enter key name, the safe direct key pool, risky/reserved key copy, and
+raw diagnostics live under Advanced. Advanced delivery is still owned by the
+selected Projmux action: supported Ghostty and Windows Terminal mappings are
+previewed/applied through `projmux init`, not by storing raw sequences in the
+primary keymap. Options covers unbinding the action and reset/use-default
+flows. Diagnostic/probe/init workflows are not first-class Settings tabs; use
+`projmux setup` and `projmux init` from the terminal when key delivery needs
+remediation.
+
+Optional direct keys can be added for actions such as:
 
 | Canonical action | Meaning |
 | --- | --- |
+| `RecentWindows:Open` | Recent windows queue across projects |
 | `ProjectSwitcherToggle` | Project switcher popup |
 | `AISplitPickerToggle` | AI split popup picker; pressing again closes the picker popup |
 | `ai-split-right` | Open a new direct AI split to the right |
@@ -77,20 +103,20 @@ movement. Previous/next window remain transport-dependent and the generated app
 tmux config binds `M-S-Left` / `M-S-Right` to the tmux window navigation
 commands. These default transport keys are always rendered by projmux, because
 delivery still depends on the terminal forwarding the modifier-arrow sequence.
-Settings can add extra safe plain aliases, such as `M-[` for
-`previous-window`; those aliases are saved to `keymap.toml` as `keys = [...]`
+Settings can add extra safe plain keys, such as `M-[` for
+`previous-window`; those keys are saved to `keymap.toml` as `keys = [...]`
 without storing or replacing the transport default. Rename actions no longer
 have a built-in terminal fallback; use tmux's prefix rename flow or configure
-an explicit safe alias where the action is editable.
+an explicit safe key where the action is editable.
 
 ## Product Requirements
 
 Settings > Keybindings stays a discovery surface. It must continue to expose
 launch toggles, sidebar keymap actions, picker-local actions, pane switching,
-window switching, and rename actions. The primary Settings flow is not the
-terminal remediation surface: replace-primary, disable-default, typed fallback,
-terminal mapping preview/apply, and init execution rows stay out of the action
-detail.
+window switching, and rename actions. The basic Settings flow is not the
+terminal remediation surface: key-role replacement, disable-default, typed
+fallback, terminal mapping preview/apply, and init execution rows stay out of
+the action detail.
 
 The product model does not support `UserN` or `CSI-u` as fallback guidance.
 Windows Terminal and Ghostty adapters use built-in plain Meta/control bytes or
@@ -110,10 +136,31 @@ by different picker surfaces, while conflicts inside one surface are rejected.
 | `SessionPopup:KillSession` | Kill the focused session |
 | `SessionPopup:CyclePreviewWindowPrev` / `SessionPopup:CyclePreviewWindowNext` | Preview windows |
 | `SessionPopup:CyclePreviewPanePrev` / `SessionPopup:CyclePreviewPaneNext` | Preview panes |
-| `NotifySidebar:Ack` / `NotifySidebar:ClearNonCritical` / `NotifySidebar:ClearAll` | Manage notifications |
-
-Runtime picker footers render key guides from the merged keymap, preferring the
-default alias when it is present and otherwise using the first configured alias.
+| `NotifySidebar:Ack` / `NotifySidebar:AckGroup` / `NotifySidebar:ClearNonCritical` / `NotifySidebar:ClearAll` | Manage notifications |
+
+Notify sidebar Right/Left child-row show/hide behavior is picker-local and is
+not part of the Settings action catalog. `NotifySidebar:AckGroup` defaults to
+uppercase `A`, distinct from `NotifySidebar:Ack` on lowercase `a`.
+
+Runtime picker footers render key guides from the merged keymap, using the
+first active key as the representative key.
+
+In Settings > Keybindings, **Add key** appends a key to the selected action's
+`keys = [...]` list. For catalog popup toggle actions, those keys are used both
+by generated tmux open bindings and by popup-internal close bindings, so the
+same key can close the corresponding already-open popup. This same-key close
+behavior is only for actions cataloged as popup toggles, such as
+`ProjectSidebarToggle`, `NotifySidebarToggle`, `RecentWindows:Open`,
+`AISplitPickerToggle`, `SettingsToggle`, `ProjectSwitcherToggle`, and
+`SessionPopupToggle`. Direct command actions such as `new-window`, pane/window
+navigation, and direct AI split actions remain command bindings and are not
+treated as popup close keys.
+
+Settings is the default apply path for key edits: it writes the key list,
+refreshes the generated config, and reloads the running tmux session when
+possible. Use `projmux tmux apply` as a CLI recovery/sync command after editing
+the keymap file by hand, after an outside-tmux Settings save, or after resolving
+a reported generated-config or live-reload failure.
 
 ## Keymap File
 
@@ -150,7 +197,7 @@ so Settings can distinguish them from the `Alt-4` popup picker toggle.
 ## Diagnose: `projmux setup`
 
 Run `projmux setup` outside tmux to find out which projmux keys reach the raw
-terminal. Settings > Keybindings remains the action/alias editor; setup is the
+terminal. Settings > Keybindings remains the action-key editor; setup is the
 terminal delivery diagnostic.
 
 | Status | Meaning |
@@ -159,6 +206,16 @@ terminal delivery diagnostic.
 | `MISS timeout` | No bytes arrived because the terminal swallowed the key. |
 | `MISS unknown` | Bytes arrived, but they do not match the expected plain sequence. |
 
+Settings capture uses the same underlying probe but reports a read model with
+separate fields:
+
+| Field | Meaning |
+| --- | --- |
+| Logical key | The key the user intended to press, such as `Alt-1`. |
+| Raw bytes | The bytes captured from the terminal, shown escaped. |
+| tmux received key | The logical tmux key name that can be saved, or a diagnostic placeholder when none is safe. |
+| Delivery status | `delivered`, `key-did-not-arrive`, `ambiguous-key`, or `adapter-needed`. |
+
 Useful flags:
 
 ```sh
@@ -184,7 +241,7 @@ projmux init --allow-symlink
 
 The merge is idempotent: matching bindings are no-ops, missing bindings are
 added, and keys already mapped to a different user action are skipped with a
-warning. `projmux init` does not read `keymap.toml`; direct tmux aliases still
+warning. `projmux init` does not read `keymap.toml`; direct tmux keys still
 belong in Settings > Keybindings or the keymap file.
 
 ### Ghostty
@@ -219,7 +276,7 @@ previous/next window:
   "actions": [
     { "command": { "action": "sendInput", "input": "\u001b1" }, "id": "User.projmuxSidebar" },
     { "command": { "action": "sendInput", "input": "\u001b2" }, "id": "User.projmuxNotifySidebar" },
-    { "command": { "action": "sendInput", "input": "\u001b3" }, "id": "User.projmuxSessions" },
+    { "command": { "action": "sendInput", "input": "\u001b3" }, "id": "User.projmuxRecentWindows" },
     { "command": { "action": "sendInput", "input": "\u001b4" }, "id": "User.projmuxAIPicker" },
     { "command": { "action": "sendInput", "input": "\u001b5" }, "id": "User.projmuxSettings" },
     { "command": { "action": "sendInput", "input": "\u0002r" }, "id": "User.projmuxAISplitRight" },

package/docs/native-picker-no-fzf-poc.md

@@ -112,7 +112,7 @@ The fzf compatibility surface for the native engine is tracked in
   the top border off screen.
 - Native preview panes normalize tabs and control bytes before horizontal
   clipping, preventing long preview rows from wrapping and consuming extra
-  vertical viewport rows in Alt-3/session popups.
+  vertical viewport rows in session popups.
 - Native sidebar list scrollbars use the fixed list viewport as their track and
   measure multi-line cards in rendered rows, so the thumb does not shrink or
   jump when card heights vary.
@@ -179,8 +179,9 @@ Manual UX checks for the Docker sandbox:
 - Alt-1 opens with the top border/title visible, not clipped.
 - Vertical borders stay continuous while moving Up/Down.
 - Alt-1 closes the sidebar immediately when pressed again.
-- Alt-2, Alt-3, Alt-4, and Alt-5 open their matching native popups and close
+- Alt-2, Alt-4, and Alt-5 open their matching native popups and close
   on the same Alt key immediately.
+- Alt-3 opens Recent Windows.
 - Arrow keys move selection without leaking `^[[` text into the query.
 
 `fzf` is intentionally not installed in the image.

package/docs/native-picker-parity.md

@@ -47,9 +47,9 @@ native picker engine and is not a public dependency-policy change.
 | fzf navigation keys | interactive selection in searchable lists | Covered | native maps modified-key `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
 | alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
 | frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
-| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective background/foreground SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
-| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg`/`fg` from the same effective theme tmux background/foreground tokens so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
-| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame background/foreground instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
+| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective `surface` / `chrome_foreground` SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
+| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg` from `surface` and `fg` from `chrome_foreground` so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
+| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame `surface` / `chrome_foreground` instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
 | redraw flicker/top clipping | keyboard navigation in exact-height tmux popup | Partially covered | native redraws use synchronized updates plus coalesced row diffs after the first frame, skip unchanged frames, render frame diffs before sidebar focus commands, frame rendering avoids trailing bottom-border CRLF, and screen exit clears the alternate buffer before restore; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; `TestFrameUpdateRendererSkipsUnchangedFrame`; `TestFrameUpdateRendererCoalescesEachFrameUpdate`; `TestRendererRenderFrameUsesCRLFRowsForRawTTY`; `TestNativeInteractiveUsesAlternateScreen` |
 
 ## Native Surface Architecture
@@ -75,7 +75,7 @@ native picker engine and is not a public dependency-policy change.
 
 Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
 Titlebar text, title dividers, and chip-strip gaps inherit the frame
-background/foreground instead of applying a second titlebar overlay ANSI layer;
+`surface` / `chrome_foreground` instead of applying a second titlebar overlay ANSI layer;
 chip bodies can still carry active/inactive/disabled tones. Search prompt and
 footer separators fill the available frame width, and header, row, footer, and
 preview lines close any active SGR style before padding or frame borders can

package/docs/notify-queue.md

@@ -106,21 +106,48 @@ table `ID AGE SEV SRC TARGET TEXT`. `--severity` / `--source` are
 repeatable filters. Without `--live`, this command reads only the queue and
 preserves the stable JSON array used by scripts.
 
-`--ui=sidebar` opens the notify queue as an interactive right-side list when
-run inside the tmux popup surface. Selecting a row focuses the selected target
-pane and acks the row after focus succeeds. The surface actions
-`NotifySidebar:Ack`, `NotifySidebar:ClearNonCritical`, and
-`NotifySidebar:ClearAll` are internal picker actions; direct launch aliases
-are edited in Settings, while internal picker aliases are adjusted in
-`keymap.toml` when needed. Runtime footer key guides read the merged keymap
-and show the default alias when present, otherwise the first configured alias,
-so custom aliases do not make the UI stale. `NotifySidebar:Ack` and
+`--ui=sidebar` opens the notify queue as an interactive right-side pane/session
+inbox when run inside the tmux popup surface. The queue source of truth remains
+flat; the sidebar builds a read-only grouped view for display. The first screen
+shows collapsed group rows keyed by pane when available, then window, then
+session/external fallback. Each group row is a fixed three-line card: line 1
+keeps project/session plus agent/provider with newest age, line 2 keeps
+topic/pane-title/task context plus severity/live-state aggregate
+metadata, and line 3 keeps the latest notification preview. Collapsed group
+cards do not promote window/pane ids as primary information. A `+N` badge is
+shown only when the group can unfold, and `N` is the number of child
+notification rows that will appear; one-notification group headers omit both
+the count badge and strong fold marker. Right/Left show and hide child rows for
+foldable groups inside the native sidebar only; this fold state is
+session-local and is not persisted. Right on a childless group refreshes
+without adding rows. Enter on a group row, whether folded or expanded, focuses
+the group's representative pane and acknowledges every visible notification in
+that group only after focus succeeds. Inactive means an `ai:` queue entry points
+to a pane that no longer matches live reply+agent state; it is not a time-age
+TTL state, and Enter still focuses the target when it is routable. If the
+representative target is gone/unroutable, Enter treats the selected pane inbox
+as explicit cleanup and acknowledges/prunes the visible group without focusing,
+including critical notifications. If a live- or inactive-looking representative target
+disappears during focus, Enter uses the same gone-group cleanup policy. Other
+focus failures keep the group pending, show a clear message, and refresh/prune
+the list. Expanded child notification rows are compact event rows with age,
+message preview, and severity/state while keeping the existing focus/ack-one
+behavior. The surface actions
+`NotifySidebar:Ack`, `NotifySidebar:AckGroup`,
+`NotifySidebar:ClearNonCritical`, and `NotifySidebar:ClearAll` are internal
+picker actions; direct launch aliases are edited in Settings, while internal
+picker aliases are adjusted in `keymap.toml` when needed.
+`NotifySidebar:AckGroup` defaults to uppercase `A` and explicitly
+acknowledges every visible notification in the selected group, including
+critical notifications. Runtime footer key guides read the merged keymap and
+show the default alias when present, otherwise the first configured alias, so
+custom aliases do not make the UI stale.
+`NotifySidebar:Ack`, `NotifySidebar:AckGroup`, and
 `NotifySidebar:ClearNonCritical` refresh rows, live state, and selection inside
 the same native picker session; `NotifySidebar:ClearAll` still closes the
-popup and prints a summary. Rows are intentionally compact: the visible label keeps
-notification text first, then age, project, window, and pane metadata; hidden
-queue ids remain action values but the sidebar has no search input and
-intentionally does not expose a separate metadata detail view.
+popup and prints a summary. Rows are intentionally compact: hidden queue ids
+remain action values but the sidebar has no search input and intentionally does
+not expose a separate metadata detail view.
 
 When a new pending notification is successfully pushed by any app producer
 (`notify push`, reply-ready, reconcile backfill, or bell fallback), open native
@@ -142,11 +169,20 @@ output becomes `{queue, live, rows, errors}`. Typical states:
   queue entry.
 - `live-ai-reply-missing-queue` — a live AI reply pane lacks the derived
   queue entry; run `projmux notify reconcile` to back-fill it.
-- `queue-stale` — an `ai:` queue entry exists, but the live pane no longer
-  matches reply+agent state; it remains pending until explicit ack. Surfaced
-  in the sidebar/statusbar as `STALE` / `STL`.
-- `queue-gone` — a queue entry has no routable target (empty session); it
-  can only be ack'd. Surfaced as `GONE` / `GON`.
+- `queue-stale` — preserved machine-readable state for an inactive target:
+  an `ai:` queue entry whose pane still EXISTS in the live tmux pane inventory,
+  but no longer matches reply+agent state. It is not TTL/time age. Surfaced in
+  the sidebar/statusbar as `INACTIVE` / `INA`; Enter still focuses and acks if
+  the target is routable.
+- `queue-gone` — the queue entry's target is gone. This is now determined two
+  ways: (a) the entry has no routable target (empty session), or (b) the entry
+  carries a pane target whose pane id is absent from the real tmux live pane
+  inventory (`tmux list-panes -a`). Surfaced as `GONE` / `GON`, and Enter/ack
+  cleans it up without focusing. The inventory check is best-effort: when the
+  pane inventory cannot be read (tmux error, or an empty/unrecognized reply),
+  membership-based GONE is skipped so a missing tmux server never falsely
+  dims/gones every row, and only pane-target rows are eligible (window/session-
+  only rows keep the empty-session check only).
 - `queue-only` — a non-AI/external queue entry is pending and has no live AI
   reply-pane requirement.
 
@@ -176,7 +212,8 @@ path), then:
 - pushes/refreshes one `ai:<session>:<pane>` entry for every pane
   whose attention state is `reply` AND whose agent option is non-empty;
 - reports every existing queue entry whose id starts with `ai:` and whose
-  pane no longer matches that condition as stale, without acking it.
+  pane no longer matches that condition as inactive/`queue-stale`, without
+  acking it.
 
 Successful backfill pushes publish the same best-effort open-sidebar refresh
 event as other pending queue additions.

package/docs/settings-ia.md

@@ -24,16 +24,22 @@ view-first layout:
   commands, `Pane navigation`, `Window navigation`, and `Rename` groups or
   equivalent searchable rows.
 - `Settings > Keybindings > Action` keeps the user-facing edit path small:
-  action, current keybinding/aliases, `Add alias`, and reset. It does not offer
-  replace-primary, disable-default, typed-fallback, terminal mapping preview, or
-  terminal mapping apply rows.
+  action label, state, a flat Keys list, Options, and a collapsed
+  Troubleshooting row. Keys shows only currently active/effective keys plus
+  `+ Add key`. Pressing a key row opens key detail, where Remove key and Test
+  key live. Options offers Unbind and Reset to default/Use default when
+  state-appropriate. Add key opens the default Press a key flow with Cancel and
+  Advanced...; typed key-name entry and raw diagnostics live under Advanced. It
+  does not expose Default key, Apply State, Delivery, Advanced Delivery,
+  key-role replacement, terminal mapping preview, or terminal mapping apply
+  rows as always-visible sections.
 - Terminal delivery remediation lives outside Settings primary flow. The
   supported order is `projmux shell` first, then `projmux setup`, then
   `projmux init` for supported terminal adapters.
 - Rows that cannot safely be edited still stay visible. Mark diagnostic-only
   rows with the delivery path and reason instead of hiding them or turning them
-  into unsupported editable aliases. Transport-dependent rows stay visible with
-  a separate default transport key and additive plain-alias entry; replacing or
+  into unsupported editable keys. Transport-dependent rows stay visible with
+  their default transport key and additive custom-key entry; replacing or
   disabling the transport default is not exposed.
 - `Alt-1..5` are the only guaranteed zero-config launch defaults. `UserN` and
   `CSI-u` are legacy/removal/unsupported targets, not supported fallback
@@ -42,6 +48,13 @@ view-first layout:
   first-class row, action rows use human-readable labels, internal IDs appear
   only in detail/source/keymap contexts, and runtime footers are status hints,
   not key discovery.
+- `Settings > Theme` (Global) is the single theme view. There is no separate
+  `Effective theme` item: the Global theme view shows each color token's value
+  inline. A token set globally (explicit value or via a global preset) shows its
+  set/override/preset summary; an UNSET token shows the resolved fallback value
+  with a dim swatch, a `(fallback)` label, and a `fallback` source. Resolver
+  warnings render as dim info rows after the token rows. Project `.projmux`
+  `[theme]` is never resolved or shown here.
 - `Settings > Notifications` owns notification delivery IA. Desktop notification
   mode, AI desktop notification dedupe duration, delivery source diagnostics,
   AI hook quiet policy, in-app queue status, and
@@ -64,8 +77,7 @@ view-first layout:
   edit catalog `install` values or run agent install/remove commands.
 - `Settings > Session State > Sidebar startup picker` controls the Alt-1
   project-open startup selector. The saved file remains
-  `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`, and the
-  stale `labs:sidebar-startup-picker` action opens this Session State detail.
+  `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`.
 - `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
   visible Labs row. The hidden compatibility action redirects to the
   `Settings > Keybindings` action list, not to a diagnostic default.
@@ -83,10 +95,6 @@ view-first layout:
   and `Notify icon` details. Each detail shows the current mode plus
   immediately selectable off/symbol/emoji preview rows. There is no separate
   `Change` page for icon decoration.
-- `Settings > Appearance` also shows a read-only `Theme font` status row.
-  `font_family` and `font_size` are desired values from the effective
-  project/global theme, and unsupported terminal paths must say `not applied`
-  instead of implying tmux changed the font.
 - `Settings > Appearance > Language / Locale` is the global/user language
   detail. The root row shows the saved `[ui].locale` value and the currently
   effective locale. The detail shows `Current`, `[ui].locale`, optional

package/docs/statusbar.md

@@ -141,13 +141,35 @@ last collect timestamp when present, falls back to the cache file mtime when
 needed, and keeps stale sync metadata muted instead of escalating it to a
 warning color.
 The notification HUD detail surface opens the right-side notification popup
-through the notify sidebar action, with newest-first rows and an
-attention-tinted title. When notification icon decoration is `symbol` or
-`emoji`, the bell appears before the title text.
-Selecting a row still focuses and acknowledges that notification. Internal
-notify commands use `NotifySidebar:*` IDs in `keymap.toml`; runtime footers
-render key guides from the merged keymap and prefer the default alias when it
-is still configured.
+through the notify sidebar action, showing the grouped pane/session inbox with
+collapsed group rows and the same attention-tinted title. When notification
+icon decoration is `symbol` or `emoji`, the bell appears before the title text.
+Foldable group rows show `+N`, where `N` is the number of child notification
+rows shown after Right. One-notification group headers omit the count and do
+not render as strongly foldable. Right/Left show and hide child rows locally
+inside the native sidebar; Right on a childless group refreshes without adding
+rows. Enter on a group row, whether folded or expanded, focuses the group's
+representative pane and acknowledges every visible notification in that group
+only after focus succeeds. Inactive means an `ai:` queue entry no longer
+matches live reply+agent state (its pane still EXISTS in tmux), not that the
+row is old; if the target remains routable, Enter and statusbar clicks still
+focus and then ack. Gone means the target is unroutable (empty session) or the
+row's pane id is absent from the real tmux live pane inventory
+(`tmux list-panes -a`). The inventory check is best-effort: an unreadable or
+empty/unrecognized tmux reply is treated as "unavailable", so a missing tmux
+server never falsely gones routable rows. If the
+representative target is gone/unroutable, Enter cleans up the selected group
+without focusing and acknowledges every visible notification in that group,
+including critical notifications. A
+target-gone focus race follows the same cleanup policy; other focus failures
+keep the group pending and show a clear message before refresh/prune. Enter on
+a child notification preserves the existing focus and ack-one behavior.
+`NotifySidebar:AckGroup` remains the explicit group ack action and acknowledges
+every visible notification in the selected group, including critical
+notifications.
+Internal notify commands use `NotifySidebar:*` IDs in `keymap.toml`; runtime
+footers render key guides from the merged keymap and prefer the default alias
+when it is still configured.
 
 Empty `#{mouse_status_range}` (a click on whitespace) falls through to
 `select-window -t @<mouse_window>` when `--mouse-window` is non-empty,
@@ -180,6 +202,8 @@ them as `display-message` toasts:
 
 - `notify` click whose focus dispatch exits 2 (target unresolved):
   ack the entry, toast `notify target gone; cleared`.
+- `notify` click whose AI target is inactive because it no longer matches live
+  reply+agent state: focus and ack when the target is still routable.
 - Any other focus failure: keep the entry, toast `focus failed:
   <reason>`.
 - `session`, `kube`, or `git` popup launch failure: toast

package/docs/testing.md

@@ -21,6 +21,10 @@ and humans run the same entrypoints.
   `test/e2e/linux-smoke.sh`. It validates a minimal real-tmux workflow:
   sessions, panes, config sourcing, reply-state notify reconciliation, focus
   notify fallback, and status notify rendering.
+- `make deadcode` runs `go tool deadcode` (pinned via the go.mod tool
+  directive) over the module and reports unreachable functions, filtering out
+  the intentional/MUST-KEEP baseline in `.deadcode-allowlist.txt`; it fails
+  only on NEW dead code, and `make fix` runs it after `go fix`.
 
 ## Docker-Covered Checks
 
@@ -90,7 +94,7 @@ Observe:
 
 - `Alt-1` opens the project sidebar.
 - `Alt-2` opens the notification sidebar.
-- `Alt-3` opens the existing-session picker.
+- `Alt-3` opens Recent Windows.
 - `Alt-4` opens the AI split picker.
 - `Alt-5` opens Settings.
 - Pressing the same launch key again closes the popup instead of typing escape