projmux 0.6.6 → 0.7.0

package/docs/notify-queue.md

@@ -13,6 +13,7 @@ via `projmux focus`, and feeds the HUD pill rendered by
 ```
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify.json.lock
+${XDG_STATE_HOME:-$HOME/.local/state}/projmux/notify-queue-events/refresh-*.sock
 ```
 
 The lock file is acquired via `O_CREATE|O_EXCL` with bounded retry
@@ -24,6 +25,13 @@ The queue file is a pretty-printed JSON array of `Notification`
 objects, sorted newest-first on read. `expires_at` is freshness metadata;
 expired entries are not filtered or deleted by `list`.
 
+Open native notify sidebars also create per-process Unix datagram sockets for
+queue-write refresh events. If the state-dir socket path would exceed Unix
+socket path limits, projmux uses a short per-state-dir temp runtime path for
+the socket directory. These sockets are transient UI delivery endpoints only:
+they are not queue state, do not change the JSON schema, and are removed when
+the sidebar exits.
+
 ## Data model
 
 `internal/core/notify`:
@@ -58,11 +66,17 @@ exit code 2.
 routing/debug context such as `agent`, `thread_id`, `turn_id`, `cwd`,
 `model`, and `client`; Claude hook rows also carry event-specific keys such as
 `tool_name`, `tool_input.command`, `error_type`, `subagent_type`, and
-`teammate_name`. Tmux bell fallback rows carry `agent=bell`, `event=bell`,
-and tmux target context such as pane title, command, session, window, pane, and
-socket. `notify list --json` includes this metadata as the structured data
-channel while human table/sidebar output keeps the compact text body. Existing
-entries without metadata remain valid.
+`teammate_name`. Antigravity manual hook rows carry `agent=antigravity`,
+`conversation_id`, `termination_reason`, `fully_idle`,
+`tool_confirmation_pending`, `agent_state`, and `context_window` when present.
+The same `conversation_id` can seed session-state restore via
+`agy --conversation <uuid>` when it is UUID-shaped; Antigravity quota usage
+remains unsupported because `context_window` is not 5-hour/weekly quota data.
+Tmux bell fallback rows carry `agent=bell`, `event=bell`, and tmux target
+context such as pane title, command, session, window, pane, and socket.
+`notify list --json` includes this metadata as the structured data channel
+while human table/sidebar output keeps the compact text body. Existing entries
+without metadata remain valid.
 
 ## CLI surface
 
@@ -92,18 +106,56 @@ 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. 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.
+`--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: 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
+notify sidebars receive a best-effort queue-write event and rerun the same
+`DeferredUpdate` row/live-state refresh path used by `a` ack and `x`
+non-critical clear. Event delivery errors are ignored after the queue write:
+the push still succeeds, and reopening the sidebar remains the recovery path
+for seeing the latest queue.
 
 `--live` adds a non-mutating explanation view that reads
 `tmux list-panes -a` and compares the queue with live reply-state panes. It
@@ -117,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.
 
@@ -151,7 +212,11 @@ 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.
 
 Soft-fails when tmux is not running (returns a populated `errors`
 field rather than a non-zero exit) so the post-install hook does not
@@ -180,7 +245,10 @@ an entry with:
 When the pane leaves the reply state (manual `attention clear`,
 `status set idle`, or a window close), `AckReplyReady` intentionally does not
 remove the entry. The user consumes it through explicit ack. Store errors are
-swallowed so the live tmux UI never blocks on disk IO.
+swallowed so the live tmux UI never blocks on disk IO. After a successful
+queue write and same-pane non-critical compaction, the producer publishes the
+same best-effort notify-sidebar queue-write refresh event used by
+`projmux notify push`.
 
 Manual `projmux attention toggle` on a pane without an agent option
 does NOT push — the queue is intentionally AI-driven; reconcile honours
@@ -200,7 +268,9 @@ tmux and writes an info/source-ai row with:
 Unlike reply-ready reconcile, bell ingest does not require AI pane metadata.
 It is intentionally available for arbitrary CLIs that only signal attention
 through BEL or OSC 9. Repeated bells from the same pane are suppressed for 5
-seconds before a later bell refreshes the stable queue id.
+seconds before a later bell refreshes the stable queue id. Successful
+non-deduped bell queue writes publish the same best-effort open-sidebar
+refresh event as other pending queue additions.
 
 ## Consumer (status-bar click)
 
@@ -230,8 +300,11 @@ Outcomes:
 
 The same consume policy is shared by notify-sidebar Enter and OS
 click-to-focus Toast callbacks after a real tmux focus dispatch succeeds.
+OS Toast click-to-focus is only registered when Desktop notification mode is
+`raise`; the in-app sidebar/statusbar consume path works in every mode.
 Pane focus hooks and attention clear paths remain live-attention-only and do
-not ack the notify queue. Non-critical AI completion producers also compact
+not ack the notify queue; their response-complete badge consume is limited to
+live tmux pane badge/state options. Non-critical AI completion producers also compact
 older same-pane non-critical AI rows after replacing/pushing their latest row,
 so reply-ready/stop/bell-style completion rows stay latest-state centered
 without changing the queue schema or TTL contract.

package/docs/session-restore.md

@@ -51,8 +51,12 @@ CLI for inspection/actions.
 Agent restore direct-starts supported resume commands when creating fresh tmux
 panes, matching the `projmux ai split` wrapper shape: the wrapper prepends the
 agent binary directory to `PATH`, changes to the saved cwd, sets the terminal
-and tmux pane title from the saved agent topic, then execs `codex resume <id>`
-or `claude --resume <id>`. This avoids typing agent resumes with
+and tmux pane title from the saved agent topic, then execs `codex resume <id>`,
+`claude --resume <id>`, or `agy --conversation <uuid>`. Antigravity restore
+uses only the stable statusline `conversation_id` or hook `conversationId`
+metadata captured as the pane resume id; missing or non-UUID Antigravity ids
+render as `resume unavailable` rather than falling back silently to a shell
+recipe. This avoids typing agent resumes with
 `tmux send-keys`. The restore wrapper is still a non-interactive shell command
 tail, so it does not replay the original pane's interactive shell startup,
 environment, shell functions, aliases, or live process state. Startup recipes
@@ -74,7 +78,7 @@ when building `Named snapshot` candidates; new primary surfaces should describe
 the restore unit as a snapshot, not as a separate layout or preset feature.
 
 Project open from the Alt-1 sidebar defaults to opening a closed project as an
-`Empty session`. `Settings > Labs > Sidebar startup picker` is an opt-in toggle;
+`Empty session`. `Settings > Session State > Sidebar startup picker` is an opt-in toggle;
 when it is on, closed project open advances inside the sidebar to the native
 `Start project` step. Rows are ordered `Latest snapshot`, named snapshot rows,
 `Empty session`, then `Back`. `Latest snapshot` is the auto-saved snapshot that
@@ -98,5 +102,5 @@ directly without a startup picker or trust gate.
 Default `projmux shell` no longer opens a compatibility startup picker and no
 longer accepts startup selector flags for session-state restore. It always
 follows the normal empty attach path after resolving the target app session name
-and startup directory. Use `Settings > Labs > Sidebar startup picker` for
+and startup directory. Use `Settings > Session State > Sidebar startup picker` for
 interactive Latest snapshot / Named snapshot / Empty session selection.

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
@@ -62,6 +68,9 @@ view-first layout:
   runtime action values and writes only
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
   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`.
 - `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.
@@ -107,5 +116,6 @@ Shell bootstrap UX is phase-split:
 - `projmux welcome` remains the stdout revisit command.
 - `Settings > About > Welcome` opens a visible native viewer independent of
   shell skip state.
-- Shell `skip_version` state applies only to the automatic `projmux shell`
-  prompt; it does not hide manual revisit surfaces.
+- Legacy shell `skip_version` state remains readable for compatibility but no
+  longer suppresses the automatic `projmux shell` prompt; release skips live in
+  `update-skip.json` and do not hide manual revisit surfaces.

package/docs/statusbar.md

@@ -46,6 +46,9 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   notify queue segment and from notify queue severity or desktop notification
   urgency. For example, an approval request may remain a critical queued
   notification while its live status badge renders action-required amber-orange.
+  Pane focus hooks and `projmux attention clear` consume only the
+  response-complete live badge, including stale `@projmux_ai_state=waiting`
+  fallback state; action-required and in-progress live badges remain visible.
   Window-list badges and app pane-border badges use the same semantic priority,
   with display style controlled by Settings > Appearance > AI badge style and persisted in
   `~/.config/projmux/ai-badge-style`. The default is `dot`; `emoji` renders
@@ -138,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,
@@ -177,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
@@ -117,12 +121,15 @@ Observe:
   `"reason":"no-attached-client"`.
 - Windows shows a short projmux toast with `session ready:
   projmux-host-smoke`.
+- In `notify` mode, the toast has no click-to-focus action and should not
+  auto-raise the host terminal.
 - No visible PowerShell or console window remains open after the toast.
 
 If the PR changes click-to-focus behavior, repeat with
 `PROJMUX_DESKTOP_NOTIFY_MODE=raise`, click the toast, and record whether the
-host terminal returns to the target. Otherwise leave click callbacks marked as
-manual/not run.
+host terminal returns to the target. `raise` should also be the only mode where
+`projmux focus` performs post-switch osfocus. Otherwise leave click callbacks
+marked as manual/not run.
 
 ### macOS GUI Notification
 

package/docs/upgrading.md

@@ -3,13 +3,14 @@
 projmux has two update surfaces:
 
 - `projmux shell` reads the cached release status before opening the app. When
-  the cache is fresh and a newer release is available, startup shows a picker
-  with Update Now, Later, and Skip This Version actions.
+  the cache is missing or stale, startup attempts a short best-effort refresh
+  and continues if it fails. When a newer release is available, the shell
+  welcome offers Continue, Upgrade, and Skip until next actions.
 - Settings > About > Update shows the current version, detected installer,
   cached latest version, Check Updates, and Update Now actions.
 
-Startup never reaches the network. Refresh the cache explicitly when you want
-projmux to check GitHub Releases:
+Refresh the cache explicitly when you want a full foreground GitHub Releases
+check:
 
 ```sh
 projmux update check
@@ -24,6 +25,11 @@ projmux update apply
 Use `--dry-run` to see the planned action and `--no-apply` to skip reloading
 the live tmux config after the binary changes.
 
+Shell Upgrade invokes only `projmux update apply`. Shell Skip until next stores
+the current latest release tag in `update-skip.json`; the prompt appears again
+when the cached latest tag changes. For `source` and unknown installer sources,
+Upgrade prints guidance and continues shell entry without applying anything.
+
 ## npm Installs
 
 The recommended install path is:

package/docs/usage-tracking.md

@@ -1,10 +1,26 @@
 # Usage tracking
 
 `projmux usage` and `projmux status usage` report authoritative 5-hour
-and weekly utilisation for both Claude Code and the Codex CLI. Both
-adapters read from the upstream's own view of the account so the
+and weekly utilisation for enabled AI agents. `--model all`, the tmux
+HUD, and the statusbar usage popup use Settings > AI Settings > Enabled
+agents as the source of truth, so disabled Claude/Codex providers are
+not refreshed or rendered on ambient/all surfaces. Explicit read-only
+requests such as `projmux usage --model claude` or `--model codex`
+still collect and render that provider even when it is disabled.
+
+Both adapters read from the upstream's own view of the account so the
 percentages match what `claude /usage` and `codex` show natively.
 
+Antigravity is intentionally not registered as a 5-hour/weekly quota adapter.
+The only stable Phase 0b usage signal is statusline `context_window`, which is
+conversation context-window usage, not account quota usage. `projmux usage
+--model antigravity` and ambient all-model table output therefore render an
+explicit unsupported note when Antigravity is enabled. The statusbar usage
+popup shows an `Antigravity ctx ... unsupported` row, while the compact tmux
+status segment stays silent unless Claude/Codex quota rows exist. Projmux does
+not infer quota, reset timestamps, or account limits from screen scraping,
+tokens, history, OAuth/cache files, or binary strings.
+
 ## Adapters
 
 ### Claude (`internal/core/usage/adapters/claude`)
@@ -79,12 +95,13 @@ across machines (Dropbox, iCloud Drive).
 ### `projmux usage`
 
 ```
-projmux usage [--model codex|claude|all] [--window 5h|weekly|all]
+projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|all]
               [--json] [--force|-f]
 ```
 
-Calls `Manager.Collect` (or `ForceCollect` with `--force`), filters by
-model/window, and renders the tab-aligned table:
+For `--model all`, calls `Manager.Collect` (or `ForceCollect` with
+`--force`) only for providers enabled in Settings > AI Settings >
+Enabled agents, filters by window, and renders the tab-aligned table:
 
 ```
 MODEL   WINDOW  PCT   RESETS_AT                STALE
@@ -103,16 +120,27 @@ instead. A backoff note is appended to the human table:
 claude is in backoff, try again in 30m (use --force to bypass)
 ```
 
+When no AI agents are enabled, all-model table output contains no
+provider rows and prints a short Settings hint. `--json` returns an
+empty array. Explicit `--model claude` and `--model codex` bypass the
+enabled-agent filter for read-only inspection and collect/render only
+the requested adapter. Explicit `--model antigravity` renders the same
+unsupported/context-window-only note even when Antigravity is disabled, because
+there is no supported Antigravity quota adapter to collect.
+
 ### `projmux status usage`
 
 ```
 projmux status usage [--max-width N] [--force|-f]
 ```
 
-The HUD bar wired to the tmux status interval. Triggers an
-opportunistic refresh: `MaybeCollect(throttle=30s)` (subject to
-per-adapter throttle and active backoff). Errors are swallowed unless
-`PROJMUX_USAGE_DEBUG` is set. Then loads the cache and renders.
+The HUD bar wired to the tmux status interval. It scopes the registry to
+enabled AI agents, then triggers an opportunistic refresh:
+`MaybeCollect(throttle=30s)` (subject to per-adapter throttle and active
+backoff). Disabled providers are not refreshed just to be hidden. Errors
+are swallowed unless `PROJMUX_USAGE_DEBUG` is set. Then it loads the
+cache, filters to the same enabled-agent scope, and renders. If no AI
+agents are enabled, the status segment emits nothing.
 
 Output degrades through six tiers as `--max-width` shrinks:
 
@@ -132,10 +160,11 @@ because the rollout file is always near-current (no throttle gap to report).
 ### Statusbar usage popup
 
 `projmux statusbar click usage` renders a native-framed popup from the same
-cache instead of shelling out to `projmux usage`. This keeps `projmux usage
---json` backwards-compatible for CLI consumers while giving the tmux click path
-a structured table with aligned rows, right-aligned numeric values, dim
-unavailable cells, amber usage at 80%, and red usage at 95%.
+cache instead of shelling out to `projmux usage`. The popup filters rows and
+sync metadata to the same enabled-agent scope as the ambient HUD. This keeps
+`projmux usage --json` backwards-compatible for CLI consumers while giving the
+tmux click path a structured table with aligned rows, right-aligned numeric
+values, dim unavailable cells, amber usage at 80%, and red usage at 95%.
 
 The popup sync line uses the maximum authoritative `LastCollect` timestamp from
 the cache. If that field is unavailable, it falls back to the snapshots file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.6",
+  "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.6",
-    "@projmux/linux-arm64": "0.6.6",
-    "@projmux/darwin-x64": "0.6.6",
-    "@projmux/darwin-arm64": "0.6.6"
+    "@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-*`.