projmux 0.6.5 → 0.6.7

package/docs/configuration.md

@@ -87,16 +87,17 @@ language.
 ## Keymap File
 
 Settings > Keybindings is the normal in-app editor for action keys. It lists
-user-configurable direct bindings, opens a detail screen, and offers `Add
-alias`, `Replace primary`, `Disable default`, `Reset`, `Press new key`, and
-`Type key chord`. Saving writes safe tmux plain chords to
+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, or use `projmux init` for
-the supported terminal mappings.
+persisted. Use Settings to save a safe direct alias. 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.
 
 `~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
 absent, generated tmux config stays on the built-in defaults.
@@ -126,21 +127,27 @@ do not break. Settings preserves existing prefix entries when rewriting the
 file, but does not create new prefix keys, and generated tmux config no longer
 binds the old action prefix chords.
 
-Use an empty `keys` list to disable direct plain aliases for the action:
+Settings > Keybindings names `AISplitPickerToggle` as the AI split popup
+picker toggle. That action opens or closes the picker UI and is separate from
+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
+editing the file by hand:
 
 ```toml
 [bindings.ProjectSidebarToggle]
 keys = []
 ```
 
-In Settings, `Disable default` writes `keys = []`. `Reset` removes the saved
-override and returns to the built-in default. Legacy popup IDs such as
+In Settings, reset removes the saved override and returns to the built-in
+default. Legacy popup IDs such as
 `sessionizer-sidebar` still read, but new writes use canonical toggle names
 such as `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
 `AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`. Internal
 popup commands use `Surface:Action` IDs and have surface-local conflict
-domains; those are manual `keymap.toml` entries, not Settings list/edit
-targets.
+domains and remain visible in Settings when catalogued.
 
 The Settings writer is deterministic and rewrites the supported saved subset
 only. If the existing file has parse errors or unknown action IDs, Settings
@@ -149,7 +156,8 @@ shows the keymap error row and refuses to overwrite it until the file is fixed.
 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.
+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.
 Changing terminal-layer mappings still requires rerunning `projmux init` and
 restarting the terminal where that terminal requires it.
 
@@ -176,9 +184,18 @@ field with source labels: `project`, `global`, or `fallback`.
 Renderer adapters can apply an already resolved `EffectiveTheme` to native
 picker frame background/foreground SGR and tmux status/window `colourN`
 background tokens. Settings and native project picker surfaces load global and
-project `[theme]` values through the shared effective-theme source. Fallback
-renderer output intentionally keeps the existing palette constants byte for
-byte.
+project `[theme]` values through the shared effective-theme source. Native
+picker frames also apply the built-in fallback `background`/`foreground` tokens
+so picker-owned padding, empty rows, footer rows, and preview gaps do not
+inherit the terminal default background.
+
+Native picker popups launched through `projmux tmux popup-toggle` also pass a
+per-popup tmux 3.4 `display-popup -s` body style using the effective theme
+`background`/`foreground` tmux tokens. This styles only the tmux popup body
+before the native renderer draws. It does not set global `popup-style` or
+`popup-border-style`, and it does not change shell pane backgrounds,
+`default-style`, `window-style`, OSC terminal backgrounds, or the general
+status/window palette.
 
 Resolver schema shape:
 
@@ -270,11 +287,12 @@ user/global preference in this release.
 | `PROJMUX_FOCUS_DEBUG` | When non-empty, `projmux focus` prints one telemetry line to stderr. |
 | `PROJMUX_PICKER_BACKEND` | Legacy picker backend override. Any value, including old `fzf` settings, now resolves to the native picker. |
 | `PROJMUX_INSTALLER` | Installer source hint used by update flows. npm installs set this automatically; advanced release installs can set `github-release`. |
+| `PROJMUX_SHELL_UPDATE_CHECK_TIMEOUT_MS` | Timeout in milliseconds for the best-effort release check attempted by `projmux shell` when the update cache is missing or stale. Invalid, zero, or negative values use the default. |
 
 ## Welcome State
 
-`projmux shell` stores per-version welcome state under the projmux state
-directory, normally:
+`projmux shell` still reads and rewrites legacy per-version welcome state under
+the projmux state directory for attach-popup compatibility, normally:
 
 ```text
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/welcomed-v<version>.json
@@ -292,11 +310,21 @@ The current schema is:
 }
 ```
 
-`skip_version` is the only field that suppresses the shell welcome. When it
-matches the current projmux version, `projmux shell` skips the welcome. When it
-is absent or names a different version, the welcome is shown again. Older state
-files that contain only `last_welcomed_version` remain readable, but that field
-does not count as a skip.
+This file no longer suppresses the shell-entry welcome. `skip_version` and
+`last_welcomed_version` remain readable for legacy state and pending attach
+popup compatibility, but the automatic shell prompt now uses release skip state
+instead.
+
+Update prompt skips are stored by latest release tag under the update cache
+directory:
+
+```text
+${XDG_CACHE_HOME:-$HOME/.cache}/projmux/update-skip.json
+```
+
+When `tag_name` matches the fresh cached latest release tag, `projmux shell`
+continues without offering the update actions. A newer latest tag makes the
+prompt eligible again.
 
 Example:
 
@@ -398,11 +426,13 @@ only a generic in-app queue/sidebar/statusbar row; it does not fire OS toast,
 The OS-level dispatch carries three modes. The in-app notify queue, the
 statusbar segment, and the attention badge stay live regardless of which
 mode is active — only the toast / notify-send / auto-raise fan-out is
-gated here.
+gated here. The same mode also gates `projmux focus` post-switch osfocus
+dispatch: only `raise` asks the host terminal to come forward after a
+successful tmux focus.
 
 | Mode | On push | On click |
 | --- | --- | --- |
-| `none` | no toast | n/a |
+| `off` / `none` | no toast | n/a |
 | `notify` | toast / notify-send fires | no click action |
 | `raise` | toast / notify-send fires AND the host terminal is auto-raised via the osfocus chain | toast click invokes `projmux focus --uri` via the `projmux://` handler |
 
@@ -410,30 +440,37 @@ Click activation is wired only for `raise`. The `projmux://` URI handler is
 registered on the first `raise` Notify of each tmux server (gated by the
 `@projmux_uri_protocol_registered_v6` marker). The
 mode only controls whether a toast fires at all and whether to follow it
-up with an on-push auto-raise.
+up with an on-push auto-raise. `off` / `none` and `notify` also suppress
+the focus-triggered osfocus raise after `projmux focus`.
 
 Resolution order (highest priority first):
 
-1. `PROJMUX_DESKTOP_NOTIFY_MODE` env (`none` / `notify` / `raise`).
+1. `PROJMUX_DESKTOP_NOTIFY_MODE` env (`off` / `none` / `notify` / `raise`).
 2. `PROJMUX_DESKTOP_NOTIFY` env (legacy `on` / `off`; `on` → `notify`,
    `off` → `none`).
-3. Tmux global option `@projmux_desktop_notify_mode`.
-4. Tmux global option `@projmux_desktop_notify` (legacy `1` / `0`, same
+3. Saved Settings config
+   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/desktop-notify-mode`
+   (`off` / `notify` / `raise`).
+4. Tmux global option `@projmux_desktop_notify_mode`.
+5. Tmux global option `@projmux_desktop_notify` (legacy `1` / `0`, same
    mapping as the env above).
-5. Default = `raise` when running inside WSL with `$WT_SESSION` set
+6. Default = `raise` when running inside WSL with `$WT_SESSION` set
    (Windows Terminal × WSL is the measured-working cell for osfocus
    raise today); otherwise `notify`.
 
 Migration is intentionally read-time. Users with the previous legacy
 toggle set keep their behavior — `@projmux_desktop_notify=0` resolves to
 `none`, `@projmux_desktop_notify=1` resolves to `notify`. The first
-Settings press through the new row writes the new key and the legacy key
-goes unused. No eager rewrite of tmux state.
+Settings press through the new row writes `desktop-notify-mode`, mirrors the
+new value into `@projmux_desktop_notify_mode` when tmux is live, and leaves the
+legacy key unused. No eager rewrite of tmux state.
 
 Toggle from Settings > Notifications > `Desktop notifications`. The
 Settings info row labels the effective source as `env`, `env (legacy)`,
 `setting`, `setting (legacy)`, or `default` so users see which rung of
-the cascade pinned the value.
+the cascade pinned the value. `projmux tmux apply` regenerates the live tmux
+option from the saved Settings file; when that file is missing, apply writes
+only the default for the current host.
 
 Hook details for new-session lifecycle hooks and project-local
 `.projmux/config.toml` live in [Hooks](hooks.md).
@@ -542,8 +579,8 @@ while `on` and `off` take precedence. Auto-save only updates the latest
 snapshot. Named snapshots are manual and are never updated by auto-save.
 
 Project open from the Alt-1 sidebar defaults to opening a closed project as an
-`Empty session`. The optional `Settings > Labs > Sidebar startup picker` toggle
-enables the native sidebar `Start project` step. Rows appear as `Latest
+`Empty session`. The optional `Settings > Session State > Sidebar startup
+picker` toggle enables the native sidebar `Start project` step. Rows appear as `Latest
 snapshot`, named snapshot rows, `Empty session`, and `Back`. `Latest snapshot`
 is the snapshot auto-save that changes as auto-save runs; named snapshots are
 fixed snapshots. Rows include saved-at date/time metadata when projmux can
@@ -562,7 +599,7 @@ Default `projmux shell` no longer opens a startup picker or replays session-stat
 snapshots before attach. It still derives the default app session identity and
 startup directory from the current project context when available; otherwise it
 uses the `home` target and home directory. Session-state restore selection is
-limited to the Labs sidebar startup picker.
+limited to the Session State sidebar startup picker.
 
 Settings > Session State is global settings only: global auto-save, auto-save
 interval, and storage/retention policy. Settings > Project > Session State

package/docs/hooks.md

@@ -206,7 +206,11 @@ desktop sender and receives positional arguments
 `summary body urgency app-name tag group icon-path`. That `urgency` value is
 the OS notification urgency, not the notify-queue severity. AI approval,
 input, selection, and confirmation rows can stay critical in the queue and UI
-while the desktop notification hook receives `normal`.
+while the desktop notification hook receives `normal`. Live AI status badges
+are a third surface: permission/input-required panes use the action-required
+amber-orange status role, response-complete panes use success green, and
+in-progress panes use progress yellow. They do not inherit the critical queue
+severity, and permission/input status badges do not use red.
 
 ## Codex Hooks Engine
 
@@ -602,6 +606,39 @@ Codex and are managed from `Settings > Notifications > Hook quiet policy`.
 They only affect ingest delivery; `projmux ai integrate claude` still uses the
 catalog `install` field for installed hook events.
 
+## Antigravity Hook Ingest
+
+`projmux ai ingest antigravity-hook < payload.json` is available for manual
+Antigravity CLI `agy` hook/statusline payloads. Projmux does not provide
+`projmux ai integrate antigravity`, does not install Antigravity hooks, and
+does not mutate Antigravity user config. The Delivery sources diagnostic
+therefore reports Antigravity as a read-only unsupported/manual row. If users
+wire it by hand, use an absolute `projmux` command path or a known cwd because
+relative command paths failed the Phase 0b smoke.
+
+The default known Antigravity catalog records only observed Phase 0b signals
+and marks them `install: false`:
+
+| Event/signal | Behavior |
+| --- | --- |
+| `PostInvocation` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
+| `Stop` | pushes a completion row, or a critical error row when `error` is present or `terminationReason` is non-normal |
+| `Statusline` with `tool_confirmation_pending=true` | pushes a critical approval row; this is only active when a statusline/manual status payload is wired to ingest |
+| `Statusline` without `tool_confirmation_pending=true` | marks the matched pane hook-active and writes a quiet ingest diagnostic |
+| unknown events | mark the matched pane hook-active and write quiet ingest diagnostics only |
+
+Antigravity notify rows use `agent=antigravity` metadata. Accepted fields
+include `conversationId`/`conversation_id`, `cwd`, `workspace.path`,
+`transcriptPath`, `terminationReason`, `error`, `fullyIdle`, `agent_state`,
+`context_window`, and nested `statusline.tool_confirmation_pending`.
+Antigravity ingest uses `conversationId` as pane thread metadata for matching
+and as session-state resume metadata. Session restore uses
+`agy --conversation <uuid>` only when that id is present and UUID-shaped;
+otherwise preview and doctor render `resume unavailable`. Antigravity usage
+quota HUD support remains unsupported because the stable usage signal is
+`context-window-only` statusline data, not 5-hour/weekly quota data. Raw
+payloads or transcript contents are not stored.
+
 ## Ingest Debug Log
 
 Every `projmux ai ingest ...` path appends compact JSONL diagnostics to

package/docs/install.md

@@ -28,14 +28,14 @@ projmux shell
 ```
 
 Each `projmux shell` launch prints a short welcome with the current version,
-detach/exit keys, core app shortcuts, and cached update status when available.
-Press Enter to continue for this run, or press `s` to skip the welcome for the
-current projmux version. The next projmux version shows the welcome again.
-
-If an installer-supported update is available, the same prompt keeps update
-actions separate from welcome skip: press `u` to run `projmux update apply`,
-`n` to print the manual update command, or `d` to skip daily update prompts for
-that release.
+detach/exit keys, a bootstrap reminder, and cached release status when
+available. Press Enter to continue into the shell.
+
+If an update is available, the same shell-entry prompt uses one action
+vocabulary: Enter continues, `u` upgrades by invoking `projmux update apply`,
+and `s` skips that latest release tag until a newer tag appears. For `source`
+or unknown installer sources, `u` prints installer guidance and then continues
+shell entry.
 
 To revisit the guide later, run `projmux welcome`, or use Settings > About >
 Welcome inside the app to open it in a visible viewer. Set `PROJMUX_WELCOME=off` before

package/docs/keybindings.md

@@ -12,8 +12,7 @@ supported fallback guidance.
 The recommended path when a key does not fire:
 
 1. Try the key inside `projmux shell`.
-2. Open Settings > Keybindings > Diagnostic, or run `projmux setup` outside
-   tmux, to see which bytes reach the process.
+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
@@ -34,7 +33,7 @@ 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-4` | AI split picker |
+| `Alt-4` | AI split popup picker |
 | `Alt-5` | Settings |
 
 The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
@@ -47,14 +46,31 @@ 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:
 
 | Canonical action | Meaning |
 | --- | --- |
 | `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 |
+| `ai-split-down` | Open a new direct AI split below |
 | `new-window` | New tmux window in the current pane directory |
 | `rename-window` | Rename the current tmux window |
 
+`AISplitPickerToggle` is the `Alt-4` popup picker toggle. It opens or closes
+the picker UI where the user chooses the AI split mode. It is separate from
+the direct `ai-split-right` and `ai-split-down` actions.
+
+The direct AI split actions create a new managed AI pane each time they run.
+Existing AI panes are left in place; the requested direction controls where the
+new pane is created.
+
 Pane switching is catalogued as transport-dependent and the generated app tmux
 config binds `M-Left`, `M-Right`, `M-Up`, and `M-Down` to `select-pane`
 movement. Previous/next window remain transport-dependent and the generated app
@@ -67,19 +83,20 @@ 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.
 
-## Roadmap Requirements
+## Product Requirements
 
-Follow-up Phase 2 keeps Settings > Keybindings as a discovery surface. It must
-continue to expose launch toggles, sidebar keymap actions, picker-local actions,
-pane switching, window switching, and rename actions. Transport-dependent rows
-should explain the default transport key and offer only additive safe plain
-aliases; diagnostic-only rows should explain why they are not editable.
+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.
 
-Follow-up Phase 3 removes the `UserN` / `CSI-u` route from the product model.
-Windows Terminal and Ghostty-centered replacements should use plain
-Meta/control chords or xterm modifier sequences where possible. If a key cannot
-be represented that way, leave it as a non-editable unsupported or diagnostic
-row instead of preserving a User-key or CSI-u fallback.
+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
+xterm modifier sequences where possible. If a key cannot be represented that
+way, leave it as a non-editable unsupported or diagnostic row instead of
+preserving a User-key or CSI-u fallback.
 
 ## Picker Actions
 
@@ -126,13 +143,15 @@ Legacy popup IDs such as `sessionizer-sidebar`, `notify-sidebar`,
 `session-popup`, `ai-split-picker-right`, `ai-split-settings`, and
 `sessionizer` still read. Settings and new docs show the canonical toggle
 names: `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
-`AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`.
+`AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`. Direct
+AI split actions keep their command IDs, `ai-split-right` and `ai-split-down`,
+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. The same diagnostic is available in-app at Settings > Keybindings >
-Diagnostic.
+terminal. Settings > Keybindings remains the action/alias editor; setup is the
+terminal delivery diagnostic.
 
 | Status | Meaning |
 | --- | --- |

package/docs/native-picker-parity.md

@@ -32,6 +32,7 @@ native picker engine and is not a public dependency-policy change.
 | close `--bind key:abort` | Esc, Ctrl-C, Alt-N, Ctrl-Alt-S variants | Covered | `CloseActions`; `TestNativeRunnerUsesSharedCloseActions` |
 | terminal modified-key encoding | legacy parser fixtures, Ghostty/kitty-style modified keys | Covered | native handles app-specific parser fixtures, generic modified letters/digits, and non-text keys such as Enter/Esc/Backspace/Tab; this is backend parity, not product fallback guidance; `TestNativeInteractiveSupportsCSIuAppKeyBindings` |
 | `execute-silent(...)+refresh-preview` | switch/session preview cycling | Covered for command execution and rerender loop | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestPickerOptionsMapsCompatBindingsToContractActions`; Docker no-fzf e2e sends `Right` and `Alt-Down` before selection |
+| action-local/event-backed mutable refresh | notify sidebar `a` ack and `x` non-critical clear; notify sidebar queue-write event refresh; switch sidebar `Ctrl-X` kill | Covered for in-session row/live-state refresh without picker restart | `picker.Action.Mutate` returns a `DeferredUpdate`, notify queue-write events trigger the same `DeferredUpdate` path after an event arrives, and both reuse the native frame diff renderer plus value-then-clamp selection preservation; `TestNativeInteractiveCustomActionMutatesItemsAndRefreshes`; `TestNativeInteractiveCustomActionRefreshPreservesSelectedValue`; `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; notify sidebar app tests assert one picker invocation with refreshed rows/live state and event subscription; switch sidebar kill app tests assert one native picker invocation with refreshed rows/preview and previous-live-session guard preservation |
 | `focus:execute-silent(...)` | switch sidebar focus | Covered | native renders the selection frame diff before running sidebar focus commands so movement stays visible before tmux focus side effects; `runNativeFocusAction`; `TestNativeInteractiveRunsFocusActionOnSelectionChange` |
 | `start:pos(N)` | switch sidebar initial row | Covered | `pickercompat.PickerOptions`/`pickercompat.OptionsFromPicker`; `TestPickerOptionsFromCompatPickerMapsStartPosToInitialIndex`; `TestPickerOptionsMapsCompatBindingsToContractActions` |
 | `--preview` | switch, sessions | Covered by command output | `nativePreviewLines`; `TestNativeInteractiveRendersSelectedPreview` |
@@ -46,8 +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` |
-| 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; 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`; `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 with neutral titlebar background, rule fill, and a divider above search/content, 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 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` |
 | 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
@@ -72,9 +74,11 @@ native picker engine and is not a public dependency-policy change.
 ## Frame Chrome ANSI
 
 Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
-Titlebars restore the titlebar style after embedded ANSI resets, 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
+Titlebar text, title dividers, and chip-strip gaps inherit the frame
+background/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
 inherit it. This phase does not add popup modes or change the `popup-toggle`
 contract; native popups still rely on the existing borderless tmux popup path.
 
@@ -107,8 +111,10 @@ contract; native popups still rely on the existing borderless tmux popup path.
   the right-side preview layout instead of inline preview, asserts the stored
   preview cursor, selects `bravo-web`, and asserts tmux reports the selected
   session's active target on the expected window with the expected pane path.
-- `notify sidebar`: native routing is unit-covered; Docker no-fzf e2e pushes a
-  notification, presses printable expect key `a`, and verifies the row is acked.
+- `notify sidebar`: native routing is unit-covered; app tests cover
+  queue-write event subscription and picker tests cover repeated
+  event-triggered deferred refresh. Docker no-fzf e2e pushes a notification,
+  presses printable expect key `a`, and verifies the row is acked.
 
 ## Experimental Boundaries
 

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
 
@@ -100,11 +114,22 @@ pane and acks the row after focus succeeds. The surface actions
 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
+so custom aliases do not make the UI stale. `NotifySidebar:Ack` 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.
 
+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
 does not push, ack, or otherwise repair anything. Human output keeps the
@@ -153,6 +178,9 @@ path), then:
 - reports every existing queue entry whose id starts with `ai:` and whose
   pane no longer matches that condition as 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
 break. Run this as the recovery path when the on-disk queue has drifted
@@ -180,7 +208,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 +231,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 +263,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/npm-distribution.md

@@ -31,13 +31,15 @@ make npm-pack
 or:
 
 ```bash
-scripts/package-npm.sh --version 0.4.0 --out /tmp/projmux-npm --pack
+scripts/package-npm.sh --version 1.2.3 --out /tmp/projmux-npm --pack
 ```
 
 The script stages package directories under `dist/npm` by default. It builds
 the Go binary for each supported platform, copies package metadata and docs,
-updates package versions in the staged copies, then runs `npm pack --dry-run`
-when `--pack` is set.
+updates package versions in the staged copies, generates root
+`optionalDependencies` for the supported platform packages using the same
+version, verifies the staged metadata is internally consistent, then runs
+`npm pack --dry-run` when `--pack` is set.
 
 ## Publish Order
 

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.