projmux 0.6.7 → 0.7.0

package/README-ko.md

@@ -4,8 +4,9 @@
   <img src="docs/assets/projmux-icon.png" alt="projmux icon" width="112">
 </p>
 
-프로젝트별 tmux workspace를 빠르게 전환하고, preview/status context/AI pane
-attention까지 함께 다루는 터미널 workspace 도구입니다.
+프로젝트별 tmux workspace를 빠르게 전환하고, Claude Code, Codex,
+Antigravity pane의 preview/status context/attention까지 함께 다루는 터미널
+workspace 도구입니다.
 
 [![npm version](https://img.shields.io/npm/v/projmux?logo=npm)](https://www.npmjs.com/package/projmux)
 [![CI](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml/badge.svg)](https://github.com/crevissepartners/projmux/actions/workflows/ci.yml)
@@ -15,7 +16,7 @@ attention까지 함께 다루는 터미널 workspace 도구입니다.
 <p align="center">
   <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
   <br>
-  <em>다른 프로젝트에서 일하는 동안 agent 작업이 끝나면 notification에서 바로 해당 pane으로 돌아갑니다.</em>
+  <em>project를 오가며 AI permission 대기를 상태줄에서 확인하고, notification list에서 해당 pane으로 돌아갑니다.</em>
 </p>
 
 ## 무엇인가
@@ -23,6 +24,8 @@ attention까지 함께 다루는 터미널 workspace 도구입니다.
 `projmux`는 프로젝트 디렉터리를 오래 유지되는 tmux session으로 연결합니다.
 프로젝트 전환, session preview, AI split 실행, tmux 안의 상태 표시를 한
 키보드 중심 workspace 앱으로 묶습니다.
+Claude Code와 Codex hook event를 직접 수집하고, 수동으로 연결한 Antigravity
+hook/statusline event도 같은 notification 흐름으로 다룹니다.
 
 터미널 workspace를 한 명령으로 열고, 한 세트의 키로 project/window/pane,
 notification, settings 사이를 오가고 싶을 때 사용합니다.
@@ -59,7 +62,7 @@ projmux shell
 
 - `Alt-1`: project sidebar.
 - `Alt-2`: notification list.
-- `Alt-3`: existing-session picker.
+- `Alt-3`: Recent Windows.
 - `Alt-4`: AI split picker.
 - `Alt-5`: settings.
 - `Alt-6`: project switcher popup.
@@ -82,17 +85,45 @@ projmux shell
 설정은 [Configuration](docs/configuration.md)을 참고하세요. installer별 update
 동작은 [Upgrading](docs/upgrading.md)에 있습니다.
 
+## 에이전트 스킬
+
+projmux shortcut은 AI 도구의 user-level skill 또는 slash command로도 등록할
+수 있습니다. 스킬은 같은 CLI contract를 감싸는 얇은 wrapper입니다:
+
+```sh
+projmux ai split --agent codex right
+projmux ai split --agent claude down
+projmux ai split --agent antigravity right
+```
+
+`/projmux:codex-right` 같은 Claude slash command를 등록한 뒤 prompt와 함께
+실행시키면, Claude가 projmux command를 호출하고 현재 project에 붙은 managed
+Codex pane이 새로 열립니다. prompt는 새 pane으로 바로 전달되고,
+permission/completion hook event가 tmux 상태줄과 notification list에
+표시됩니다.
+Antigravity도 같은 managed split 경로로 실행되며, 수동 hook ingest와 session
+resume 지원 범위는 CLI reference에 정리되어 있습니다.
+
+설치 template과 naming convention은
+[AI Agent Shortcuts](docs/ai-agent-shortcuts.md)에 정리되어 있습니다.
+
+<p align="center">
+  <img src="docs/assets/projmux-skill-workflow.gif" alt="projmux skill workflow demo" width="820">
+  <br>
+  <em>Claude가 prompt와 함께 등록된 projmux skill을 호출해 managed Codex pane을 열고, Codex가 그 자리에서 응답합니다.</em>
+</p>
+
 ## 추가 문서
 
 - [Install](docs/install.md)
 - [Configuration](docs/configuration.md)
 - [Terminal Keybindings](docs/keybindings.md)
+- [AI Agent Shortcuts](docs/ai-agent-shortcuts.md)
 - [CLI Reference](docs/cli.md)
 - [Statusbar](docs/statusbar.md)
 - [Hooks](docs/hooks.md)
 - [Usage tracking](docs/usage-tracking.md)
 - [Agent Workflow](docs/agent-workflow.md)
-- [README Hero GIF Recording](docs/readme-hero-gif-recording.md)
 
 ## 개발
 

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
   <strong>A tmux-native workspace for multi-agent AI development.</strong>
   <br>
-  <em>First-class Claude Code and Codex integration with hook-driven attention and agent-aware session resume.</em>
+  <em>Managed Claude Code, Codex, and Antigravity panes with hook-driven attention and agent-aware session resume.</em>
 </p>
 
 <p align="center">
@@ -25,20 +25,20 @@ projmux shell
 <p align="center">
   <img src="docs/assets/projmux-ai-attention.gif" alt="projmux AI attention demo" width="820">
   <br>
-  <em>An agent finishes in another project. Open notifications, select it, and jump straight back.</em>
+  <em>Switch between projects while an AI pane waits for permission, then jump back from the tmux notification list.</em>
 </p>
 
 ## Why
 
-Six tmux windows. Each one is running Claude Code or Codex on a different
-repo. Three are idle. One is waiting on a permission prompt. One crashed an
-hour ago and you have no idea which.
+Six tmux windows. Each one is running Claude Code, Codex, or Antigravity on a
+different repo. Three are idle. One is waiting on a permission prompt. One
+crashed an hour ago and you have no idea which.
 
-projmux ingests Claude Code and Codex hook events directly, shows live
-per-pane state in the tmux status bar, and lets one keystroke take you to
-the pane that actually needs you. It also remembers each agent's resume id,
-so after a reboot every pane comes back as the *same* conversation — not a
-fresh one.
+projmux ingests Claude Code and Codex hook events directly, accepts manually
+wired Antigravity hook/statusline events, shows live per-pane state in the tmux
+status bar, and lets one keystroke take you to the pane that actually needs
+you. It also remembers each agent's resume id, so after a reboot every pane
+comes back as the *same* conversation — not a fresh one.
 
 ## Requirements
 
@@ -71,7 +71,7 @@ Inside the app:
 
 - `Alt-1` opens the project sidebar.
 - `Alt-2` opens the notification list.
-- `Alt-3` opens the existing-session picker.
+- `Alt-3` opens Recent Windows.
 - `Alt-4` opens the AI split picker.
 - `Alt-5` opens settings.
 
@@ -94,6 +94,35 @@ For detailed configuration, including `PROJMUX_PROJDIR`, managed roots,
 notifications, and usage tracking, see [Configuration](docs/configuration.md).
 For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 
+## Agent Skills
+
+projmux shortcuts can also live in your AI tool as user-level skills or slash
+commands. A skill is just a thin wrapper around the same CLI contract:
+
+```sh
+projmux ai split --agent codex right
+projmux ai split --agent claude down
+projmux ai split --agent antigravity right
+```
+
+After registering a Claude slash command such as `/projmux:codex-right`, ask
+Claude to use it with a prompt. Claude runs the projmux command, Codex opens in
+a managed pane attached to the current project, and the prompt is delivered
+there immediately.
+projmux tracks hook events from the opened pane and shows permission or
+completion notifications in tmux.
+Antigravity uses the same managed split path, with manual hook ingest and
+session resume support documented in the CLI reference.
+
+Install templates and naming conventions are in
+[AI Agent Shortcuts](docs/ai-agent-shortcuts.md).
+
+<p align="center">
+  <img src="docs/assets/projmux-skill-workflow.gif" alt="projmux skill workflow demo" width="820">
+  <br>
+  <em>Claude invokes a registered projmux skill with a prompt, opens a managed Codex pane, and Codex answers there.</em>
+</p>
+
 ## More Docs
 
 - [Install](docs/install.md)
@@ -105,7 +134,6 @@ For update behavior by installer type, see [Upgrading](docs/upgrading.md).
 - [Hooks](docs/hooks.md)
 - [Usage tracking](docs/usage-tracking.md)
 - [Agent Workflow](docs/agent-workflow.md)
-- [README Hero GIF Recording](docs/readme-hero-gif-recording.md)
 
 ## Development
 

package/docs/agent-workflow.md

@@ -32,11 +32,12 @@
 - `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling and compact dirty/staged/ahead/behind state colors, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, shell-entry welcome release prompt and inline update handling, shell update skip-by-latest-tag behavior plus best-effort stale-cache refresh, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, and no-live-tmux save behavior, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex/Antigravity resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids including Antigravity conversation ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
 - `make test` also covers Settings > AI Settings > Enabled agents Phase 0 config behavior: missing config enables Claude, Codex, and Antigravity, unknown saved provider names are ignored without disabling known providers, Settings toggles persist Claude/Codex/Antigravity only, shell/selective are absent from enabled-agent rows, and a saved default split mode warns when its provider is disabled.
 - `make test` also covers native Alt-1 sidebar `Sidebar:KillSession` mutable refresh: the action kills through the focused-session safety path, keeps the native picker session open, refreshes rows and preview with `picker.Action.Mutate`/`DeferredUpdate`, and preserves the previous-live-session guard.
+- `make test` also covers Notify sidebar pane-grouped read-model rows and interactions: collapsed pane inbox group construction, fixed three-line group cards with stable project/provider, topic/context, aggregate metadata, and latest-preview slots including topic-with-project cases, child-count badges that match expandable child rows without rendering `+0`, childless group headers without strong fold affordance, selected/expanded marker-only row shape changes, duplicate label/preview reduction, worst-severity aggregation, inactive/gone group display and child-count rendering, pane-less fallback grouping, compact newest-first child event rows with warn/critical severity preservation, Right/Left fold mutation plus childless Right no-op refresh, folded and expanded live group Enter focus+ack with mixed-severity critical rows, inactive-but-routable group Enter focus+ack, gone group Enter cleanup without focus including critical rows, target-gone race cleanup, transient focus-failure no-ack refresh, child Enter focus/ack preservation, explicit group acknowledgement including mixed-severity critical rows, and grouped deferred refresh output with expanded-state pruning.
 - `make test` also covers the AI provider metadata registry for Claude/Codex/Antigravity launch providers: registry-derived enabled-agent defaults and ordering, Settings enabled-agent rows, AI picker visibility for disabled providers, ambient usage model scope derivation for quota-supported providers, hook diagnostic provider metadata, Antigravity session-state support metadata, and explicit diagnostics for disabled providers without adding unsupported quota adapters.
 - `make test` also covers usage HUD/all-model filtering from Settings > AI Settings > Enabled agents: ambient `status usage` and `usage --model all` scope collection/rendering to enabled Claude/Codex providers, all-disabled all-model output shows a Settings fallback without refreshing adapters, disabled cached rows/backoff do not leak into ambient output, and explicit `usage --model claude|codex` still collects/renders the requested provider even when disabled.
 - `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, response-complete live badge consume on attention clear without idling action-required/progress badges, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border, Alt-1 sidebar window/preview tabs, and tmux window-status compatibility with dot as the persisted/config fallback.
 - `make test` also covers AI semantic badge Phase 3 theme-role hardening: `@projmux_ai_badge_kind` storage values and aggregate priority stay unchanged, `minimal` remains a read-time alias for the `off` badge style, progress/success/action-required badge roles stay distinct, permission/input status badges do not use critical red, and critical notify queue severity does not drive live AI status badge colors or desktop notification urgency.
-- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, simplified action detail rows, Labs compatibility redirect to the Keybindings root, capture/add-alias flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
 - `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.
 - `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.
@@ -65,11 +66,14 @@
 - `make test` also covers welcome revisit policy: legacy `skip_version` readability without shell suppression, `s` Skip until next vs Enter continue, Settings > About > Welcome native viewer, best-effort shell update cache refresh, and attach-popup no-duplicate/no-op behavior.
 - `make test` also covers `projmux quit` action-picker rows, cancel/close no-op behavior, explicit quit of only app-owned mux runtimes marked by `@projmux_app=1` on the selected `tmux`/`psmux -L projmux` backend, missing/default runtime no-ops, dispatcher wiring, and `Settings > About > Quit projmux` routing through the same picker before any shutdown side effect.
 - `make test` also covers the built-in semantic palette foundation: non-empty fallback truecolor/tmux tokens, distinct action/attention/AI/progress/danger roles, native picker chip/current/titlebar render strings including titlebar frame background/foreground inheritance without separate overlay ANSI, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, settings/trust/destructive row color guards, Theme settings Phase 0/1 resolver behavior for project/global/fallback source labels, preset fill, explicit token override, invalid-layer warnings, and truecolor-to-tmux mapping, Phase 2 fallback render parity and project/global color isolation for native picker and tmux status/window background adapters, native popup-toggle `display-popup -s` body style propagation from the effective theme without touching global popup/shell/status styles, Phase 3 desired font config save/resolve plus unsupported `not applied` status without breaking no-adapter fallback rendering, and Phase 4 Settings theme editing boundaries for project/global resets, project inherit-vs-override labels, effective source labels, and project config theme values feeding the native project popup render path.
+- `make test` also covers Recent Windows Phase 0 state/model behavior: server-scoped file paths, missing/corrupt state policy with corrupt-file backup, MRU newest-first recording, same-window dedupe and promotion, default queue limiting, current-window exclusion, cross-session candidate retention, gone-window pruning against live window inventory, and label fallback rules that keep win/pane ids as debug fallback instead of the primary row label.
+- `make test` also covers Recent Windows Phase 1 native picker behavior: `projmux window recent` empty-state messaging, cross-session candidate picker rows with descriptive project/session/window/pane command age metadata, window-only switching without pane restoration, switch-failure refresh/prune handling, and gone-window pruning before picker selection.
+- `make test` also covers Recent Windows Phase 2/3/4 keybinding, popup, and runtime recorder integration: `RecentWindows:Open` owns the guaranteed `M-3` launch default, generated tmux config uses client-scoped `tmux popup-toggle recent-windows`, the popup body runs `projmux window recent`, generated tmux config installs background `window record` hooks for window and client-session changes plus first-use population without `session-window-changed`, `window record` snapshots current tmux socket/session/window/active-pane metadata into the socket-scoped store with escaped field parsing, repeated same-window record fires dedupe instead of growing entries, the queue remains bounded by `recentwindows.DefaultLimit`, Settings > Keybindings shows Recent Windows with the `M-3` default, setup probe text names Recent Windows, `SessionPopupToggle` no longer owns the guaranteed `M-3` default, and escaped tmux field separators are parsed for current/list window metadata.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,
-  reconcile reports stale rows), `notify list --live` queue/live explanations, notify sidebar
-  two-line card rendering with age/project/window/pane metadata plus focus/ack/non-critical-clear/clear-all
-  actions, notify/statusbar/sidebar attention-vs-AI palette assertions including muted stale/gone rows,
+  reconcile reports inactive `queue-stale` rows), `notify list --live` queue/live explanations, notify sidebar
+  three-line grouped card rendering with child-count/fold semantics plus focus/ack/non-critical-clear/clear-all
+  actions, notify/statusbar/sidebar attention-vs-AI palette assertions including muted inactive/gone rows,
   native picker-session-local `a` ack that refreshes the sidebar without
   focusing or restarting the picker, non-critical `x` bulk clear that preserves critical rows, empty
   state rendering after all visible non-critical rows are cleared, and notify queue-write refresh events

package/docs/architecture.md

@@ -139,13 +139,14 @@ does not own the truth of every live badge.
   TTL is not a removal condition. `projmux notify list --live` adds a
   read-only comparison against live pane state, explaining manual reply
   badges without queue entries, live AI replies with/missing queue entries,
-  and stale `ai:` entries.
+  and inactive (`queue-stale`) `ai:` entries.
 - **Ack** — `projmux notify ack <id>` removes one entry; `--all`
-  flushes everything. Focus/click handlers do not ack rows.
+  flushes everything. Interactive focus/click handlers ack after successful
+  focus, and gone/unroutable targets clean up without focusing.
 - **Reconcile** — `projmux notify reconcile` walks
   `tmux list-panes -a` and back-fills entries for panes whose
   attention state is `reply` AND whose AI agent option is set,
-  reporting stale `ai:` entries that no longer match a live pane without
+  reporting inactive `ai:` entries that no longer match a live reply+agent pane without
   acking them.
   `make install` and `projmux upgrade` invoke it so the queue
   recovers from any drift introduced by a lost daemon.

package/docs/cli.md

@@ -218,11 +218,15 @@ projmux notify reconcile [--json]
   `--live` adds a non-mutating explanation table (or JSON report) that
   compares queued entries with live pane attention. It calls out manual
   reply badges that do not queue because no AI agent is attached, live AI
-  reply panes missing a queue entry, matched AI reply entries, and stale
-  queue entries whose live pane no longer matches. `--ui=sidebar` opens the
-  compact interactive notify list where Enter focuses and acks a target, `a`
-  acks the selected row, `x` clears non-critical rows, and `Ctrl-X` clears all;
-  opening or navigating the sidebar does not ack. While open, the native
+  reply panes missing a queue entry, matched AI reply entries, inactive
+  (`queue-stale`) queue entries whose live pane EXISTS but no longer matches
+  reply+agent state, and gone (`queue-gone`) entries whose pane is absent from
+  the real tmux live pane inventory (or which have no routable target).
+  `--ui=sidebar` opens the compact interactive notify list where Enter
+  focuses and acks live or inactive-routable targets, cleans gone/unroutable
+  targets without focusing, `a` acks the selected row, `x` clears non-critical
+  rows, and `Ctrl-X` clears all; opening or navigating the sidebar does not ack.
+  While open, the native
   sidebar refreshes its row list on successful queue-write events without an
   Alt-2 close/reopen toggle, using the same deferred refresh path as `a` and
   `x`. The sidebar uses two-line cards with notification text first and
@@ -652,8 +656,8 @@ projmux tmux apply
 Helpers tmux's keybindings and the install pipeline call into. Modes
 accepted by `popup-toggle` mirror the historical sessionizer surface:
 `session-popup`, `sessionizer`, `sessionizer-sidebar`,
-`notify-sidebar`, `ai-split-picker-right`, `ai-split-picker-down`,
-`ai-split-settings`.
+`notify-sidebar`, `recent-windows`, `ai-split-picker-right`,
+`ai-split-picker-down`, `ai-split-settings`.
 `apply` reloads the live `-L projmux` server's config without restarting
 it; `make install` and `projmux upgrade` invoke it after replacing the
 binary.

package/docs/configuration.md

@@ -87,14 +87,15 @@ language.
 ## Keymap File
 
 Settings > Keybindings is the normal in-app editor for action keys. It lists
-actions with current keybinding summaries, opens a simple detail screen, and
-offers `Add alias` plus reset. Saving writes safe tmux plain chords to
-`~/.config/projmux/keymap.toml`, rewrites `~/.config/projmux/tmux.conf`, and,
-when Settings is running inside tmux, sources that app config so tmux-level
-chords take effect immediately.
-
-Raw sequences that cannot be safely represented as a tmux plain chord are not
-persisted. Use Settings to save a safe direct alias. When key delivery needs
+actions with the current active keys and one state: Default, Custom, Available,
+or Unbound. Open an action to see the action label, state, a flat Keys list,
+Options, and a collapsed Troubleshooting row. Create flows start from
+`+ Add key`, deletion lives under each key's detail, and action-level state
+changes such as Unbind or Reset live under Options. Successful saves report the
+keybinding as saved; failures identify the stage that failed.
+
+Raw sequences that cannot be safely represented as a direct keybinding are not
+persisted. Use Settings to save a custom key. When key delivery needs
 terminal-layer remediation, first try the key in `projmux shell`, then run
 `projmux setup` from the raw terminal, then use `projmux init` for supported
 terminal adapters.
@@ -133,7 +134,7 @@ the direct AI pane actions, `ai-split-right` and `ai-split-down`. The direct
 actions create a new managed AI pane each time they run, leaving existing AI
 panes in place. `right` and `down` choose where the new pane is created.
 
-Use an empty `keys` list to disable direct plain aliases for the action when
+Use an empty `keys` list to disable direct plain keys for the action when
 editing the file by hand:
 
 ```toml
@@ -157,7 +158,7 @@ The file currently affects generated tmux config from `projmux tmux
 print-config`, `projmux tmux install`, `projmux tmux print-app-config`,
 `projmux tmux install-app`, and `projmux shell`. Terminal init adapters such as
 Ghostty and Windows Terminal install built-in plain-byte mappings where needed;
-they do not read `keymap.toml` or copy saved aliases into terminal configs.
+they do not read `keymap.toml` or copy saved keys into terminal configs.
 Changing terminal-layer mappings still requires rerunning `projmux init` and
 restarting the terminal where that terminal requires it.
 

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,13 @@ 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. Successful saves use simple
+confirmation copy; if saving, runtime config update, or active tmux reload
+fails, the error names the failed stage. Raw escape payloads, Windows Terminal
+`sendInput` strings, and tmux User keys are rejected as action keys.
 
 ## Quick Start
 
@@ -32,10 +31,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 +46,25 @@ 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 and raw diagnostics live under Advanced. 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 +86,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 +119,14 @@ 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 |
+| `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, preferring the
-default alias when it is present and otherwise using the first configured alias.
+Runtime picker footers render key guides from the merged keymap, using the
+first active key as the representative key.
 
 ## Keymap File
 
@@ -150,7 +163,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 |
@@ -184,7 +197,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 +232,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/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
@@ -64,8 +70,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.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.6.7",
-    "@projmux/linux-arm64": "0.6.7",
-    "@projmux/darwin-x64": "0.6.7",
-    "@projmux/darwin-arm64": "0.6.7"
+    "@projmux/linux-x64": "0.7.0",
+    "@projmux/linux-arm64": "0.7.0",
+    "@projmux/darwin-x64": "0.7.0",
+    "@projmux/darwin-arm64": "0.7.0"
   }
 }

package/docs/readme-hero-gif-recording.md

@@ -1,97 +0,0 @@
-# README Hero GIF Recording
-
-This recipe records the README hero GIF:
-
-- `docs/assets/projmux-ai-attention.gif`
-
-The maintained recorder is kept in the local dotfiles checkout at:
-
-```sh
-/home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
-```
-
-## Prerequisites
-
-Install or verify these local tools before recording:
-
-- `python3`
-- `git`
-- `tmux`
-- `ffmpeg` and `ffprobe`
-- `Xvfb`
-- `openbox`
-- `ghostty`
-- `xdotool`
-- `xwininfo`
-- `script` from util-linux
-- authenticated `codex`
-
-Build the local projmux binary first:
-
-```sh
-make build
-```
-
-The script expects `.bin/projmux` by default. Override paths only when needed:
-
-```sh
-PROJMUX_RECORD_REPO=/path/to/projmux \
-PROJMUX_RECORD_BIN=/path/to/projmux \
-PROJMUX_RECORD_DISPLAY=117 \
-PROJMUX_RECORD_SCREEN=2560x1440x24 \
-PROJMUX_RECORD_KEEP_TMP=1 \
-python3 /home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
-```
-
-For the normal checkout, run:
-
-```sh
-python3 /home/es5h/dotfiles/bin/projmux/projmux-record-readme-gifs.py
-```
-
-## Scenario Contract
-
-The recording uses a private demo home, XDG config/state dirs, demo git
-projects, and an isolated `CODEX_HOME`. It copies the local Codex auth/config
-into that isolated home, trusts the demo projects/hooks, and seeds usage cache
-data so the tmux status line shows the Codex HUD during the capture.
-
-The scenario records the AI attention flow:
-
-1. Start in `mobile-client` with no pending notification.
-2. Open the AI picker and launch a real Codex pane.
-3. Ask Codex to do a short task.
-4. Use the projmux sessionizer sidebar to move to `atlas-api`.
-5. Keep working in zsh while Codex finishes in the previous project.
-6. When the Codex completion notification exists, open the notification sidebar.
-7. Select the notification and return focus to the original Codex pane.
-
-## Visual Guardrails
-
-- Keep the native picker UI native. The script runs picker commands through
-  `script(1)` with a fixed PTY size so fzf/terminal UI rendering is captured
-  instead of degraded line-mode output.
-- Keep the terminal in zsh with the demo prompt so the project and git branch
-  are visible.
-- Keep the Codex usage HUD visible in the tmux status line.
-- Use the sessionizer sidebar for project movement in 4a.
-- Capture the Ghostty X11 window geometry with `xwininfo` and feed that exact
-  rectangle to ffmpeg. This prevents the GIF from drifting away from `(0, 0)`.
-
-## Verification
-
-After recording, inspect the resulting streams:
-
-```sh
-ffprobe -v error -select_streams v:0 \
-  -show_entries stream=width,height,nb_frames,duration \
-  -of default=noprint_wrappers=1 \
-  docs/assets/projmux-ai-attention.gif
-```
-
-Expected final shape is roughly 1110px wide and about 16-18 seconds, with the
-native picker, zsh prompt, Codex pane, notification sidebar, and usage HUD
-visible in the relevant frames.
-
-Set `PROJMUX_RECORD_KEEP_TMP=1` when you need to inspect intermediate MP4s,
-Ghostty logs, or palette files under `/tmp/projmux-readme-record-*`.