projmux 0.6.5 → 0.6.7

package/docs/settings-ia.md

@@ -15,13 +15,21 @@ view-first layout:
   actions live inside that view.
 - `Settings > Project Picker > Project Root` shows effective and saved values
   first, then the edit actions, then the explanatory hints.
-- `Settings > Keybindings` is the single entry point for keybinding work. The
-  page is split into four chips: `Bindings`, `Diagnostic`, `Probe`, and `Init`.
-- `Settings > Keybindings > Bindings` is a keybinding discovery surface, not
-  only a launch-toggle editor. It must show `Toggle Project Sidebar` with the
+- `Settings > Keybindings` is a single action list plus a simple action detail.
+  It does not expose `Bindings`, `Diagnostic`, `Probe`, or `Init` as first-class
+  chips/tabs in the Settings root flow.
+- `Settings > Keybindings` is a keybinding discovery surface, not only a
+  launch-toggle editor. It must show `Toggle Project Sidebar` with the
   guaranteed `Alt-1` / `M-1` default, plus sidebar-local commands, picker-local
   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.
+- 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
@@ -54,9 +62,13 @@ 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`, and the
+  stale `labs:sidebar-startup-picker` action opens this Session State detail.
 - `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
-  visible Labs row. The hidden compatibility action still redirects to the
-  unified Keybindings page.
+  visible Labs row. The hidden compatibility action redirects to the
+  `Settings > Keybindings` action list, not to a diagnostic default.
 - `Settings > Labs > Project Hooks` is overview-first. The Labs root opens the
   overview, and the on/off mutation rows live one level deeper.
 - `Settings > AI Settings` is view-first. The root contains `Default split
@@ -99,5 +111,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

@@ -33,6 +33,28 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   clicks on tmux 3.4+, so a `run-shell` handler can't recover the
   target after the fact — the Go dispatcher's
   `isWindowListRangeToken` fallback is now defense-in-depth only.
+  Each window tab reserves a one-cell live pane attention prefix from
+  `projmux attention window #{window_id}` before the index. AI panes use the
+  semantic `@projmux_ai_badge_kind` first: approval/input-required panes use
+  the action-required amber-orange role, response-complete panes use the
+  non-critical success green role, and in-progress panes use the progress
+  yellow role. Red/critical is reserved for error, failure, and risk chrome;
+  permission or input-required status badges do not use it.
+  Legacy busy/reply title and attention-state markers remain the fallback, and
+  no-state windows render a blank placeholder so title alignment and click range
+  width stay stable. This live window-list badge is independent from the row-0
+  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
+  `⏳` for approval/input-required, `✅` for response-complete, and `🔄` for
+  in-progress. `off` (also accepted as `minimal` when read from disk) preserves
+  the same spacing without drawing a marker.
   The session, pwd, kube, and git segments on this row are wrapped
   in `#[range=user|<id>]` ranges and dispatched through the projmux
   handler. The standalone config also wraps the right-side `projmux`
@@ -95,9 +117,10 @@ When the notify block is wider than its cell budget, clipping shrinks the body
 text first and appends an ellipsis while preserving project, state, agent, age,
 and count metadata. If the segment is still too wide, the age is dropped next
 while badges and the `+N` count stay visible when possible. Very narrow widths
-fall back to the severity-colored dot plus clipped text and count; the final
+fall back to dotless clipped text plus the `+N` count when it fits; the final
 hard-truncate path still closes with `#[default]` so later status segments do
-not inherit notification styling.
+not inherit notification styling. That dotless narrow fallback applies only to
+the queued notify segment, not to the separate window-list live attention badge.
 `usage` opens a native-framed detail HUD for the compact usage bar. It reads
 the cached usage state in-process, keeps the existing `projmux usage` CLI
 output shape unchanged for external consumers, aligns model/window rows with

package/docs/testing.md

@@ -54,3 +54,128 @@ desktop shell, or OS integration:
 
 Keep those checks as manual or host-run smoke validation until a dedicated
 host harness exists.
+
+Use this smoke checklist when a change touches terminal delivery, host desktop
+notifications, or reviewer confidence around those boundaries. If the change
+does not touch those areas, copy the PR-note block below and mark the relevant
+rows `not run`.
+
+### Terminal Key Delivery
+
+Run the raw key probe outside tmux, in the terminal emulator being claimed:
+
+```sh
+projmux setup --timeout 10s
+```
+
+Observe:
+
+- `Alt-1` through `Alt-5` report `OK plain`. These are the guaranteed
+  zero-config launch defaults.
+- If a guaranteed key reports `MISS timeout`, preview a supported terminal
+  mapping with `projmux init ghostty` or `projmux init windows-terminal`,
+  apply it with the same command plus `--apply`, restart that terminal if
+  required, and rerun `projmux setup --timeout 10s`.
+- Optional direct aliases and transport-dependent chords may be reported by
+  the probe, but they are not part of the guaranteed host smoke unless the PR
+  explicitly changes them.
+
+Then run the app in the same terminal:
+
+```sh
+projmux shell
+```
+
+Observe:
+
+- `Alt-1` opens the project sidebar.
+- `Alt-2` opens the notification sidebar.
+- `Alt-3` opens the existing-session picker.
+- `Alt-4` opens the AI split picker.
+- `Alt-5` opens Settings.
+- Pressing the same launch key again closes the popup instead of typing escape
+  bytes into the shell or picker input.
+
+### WSL Toast
+
+Run this from WSL with Windows Terminal available. The detached tmux server is
+intentional: `projmux focus` falls back to the product desktop notification
+path when there is no attached client to switch.
+
+```sh
+sock="${TMPDIR:-/tmp}/projmux-host-smoke.sock"
+tmux -S "$sock" kill-server 2>/dev/null || true
+tmux -S "$sock" new-session -d -s projmux-host-smoke 'sleep 600'
+PROJMUX_DESKTOP_NOTIFY_MODE=notify \
+  projmux focus --socket "$sock" --target projmux-host-smoke --json
+tmux -S "$sock" kill-server
+```
+
+Observe:
+
+- The JSON includes `"ok":true`, `"dispatch":"notify-only"`, and
+  `"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. `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
+
+The built-in desktop sender is Linux/WSL-oriented. On macOS, smoke the
+documented `PROJMUX_NOTIFY_HOOK` escape hatch with an `osascript` sender:
+
+```sh
+hook="${TMPDIR:-/tmp}/projmux-macos-notify.sh"
+cat >"$hook" <<'SH'
+#!/bin/sh
+title=${1:-projmux}
+body=${2:-}
+osascript \
+  -e 'on run argv' \
+  -e 'display notification (item 2 of argv) with title (item 1 of argv)' \
+  -e 'end run' \
+  "$title" "$body"
+SH
+chmod 0755 "$hook"
+
+sock="${TMPDIR:-/tmp}/projmux-host-smoke.sock"
+tmux -S "$sock" kill-server 2>/dev/null || true
+tmux -S "$sock" new-session -d -s projmux-host-smoke 'sleep 600'
+PROJMUX_NOTIFY_HOOK="$hook" \
+  projmux focus --socket "$sock" --target projmux-host-smoke --json
+tmux -S "$sock" kill-server
+```
+
+Observe:
+
+- The JSON includes `"ok":true`, `"dispatch":"notify-only"`, and
+  `"reason":"no-attached-client"`.
+- macOS shows a Notification Center banner with `session ready:
+  projmux-host-smoke`.
+- If macOS prompts for notification permission, record that state in the PR
+  instead of treating the product command as verified.
+
+### PR Note Template
+
+```markdown
+Host-only smoke validation:
+
+- Docker-covered checks: `make test-integration`, `make test-install-smoke`,
+  and `make test-e2e` cover portable Linux tmux/config/notify behavior only.
+- Terminal key delivery: not run / run on <terminal>; `projmux setup --timeout
+  10s` showed <result>; `Alt-1..5` app popup smoke <passed/failed/not run>.
+- WSL toast: not run / run on <Windows + WSL distro>; detached-focus smoke
+  produced `dispatch=notify-only`; observed <toast/no toast/notes>.
+- macOS GUI notification: not run / run on <macOS version>; hook smoke
+  produced `dispatch=notify-only`; observed <banner/permission prompt/notes>.
+- Desktop notification click callbacks: not run unless this PR changes
+  click-to-focus behavior; result <notes>.
+```

package/docs/theme-palette.md

@@ -41,6 +41,14 @@ onto these stable names:
 | `critical` | destructive/error/critical state | settings remove/quit, notify critical badge, statusbar critical usage |
 | `warning` | progress, pending, warning, busy state | AI busy/thinking indicators, notify pending title, usage warning |
 
+AI semantic status badges use renderer-only state roles layered on top of that
+inventory: `progress`, `success`, and `action_required`. The fallback contract
+is progress yellow, success green, action-required amber-orange. These roles are
+separate from notify queue severity and desktop notification urgency; an AI
+approval row can be `critical` in the notify queue while the live status badge
+uses `action_required`, not red. `critical` remains reserved for error, failure,
+destructive, over-limit, or risk states.
+
 Renderer-only role names such as `accent.ai`, `state.progress`, `git.branch`,
 and trust colors remain in `internal/theme/palette.go` until Phase 2+ maps each
 surface to the resolver tokens. The key product contract for this phase is that
@@ -127,10 +135,11 @@ Accents and state:
 | `accent.action` | `141;205;142`, strong `122;199;173` | `colour29` bg / `colour230` fg |
 | `accent.attention` | notify HUD background/project family | `colour53`, project `colour90` |
 | `accent.ai` | notify agent `colour37` family | `colour37` bg / `colour121` fg |
-| `state.progress` | `255;204;102`; switch attention/busy dot and pending notify title/bell/badge `colour220` | `colour220` |
-| `state.warning` | usage/status popup ANSI 256 wrapper | `colour214` |
+| `state.progress` | `255;204;102`; switch attention/busy dot, pane-border in-progress badge, and pending notify title/bell/badge `colour220` | `colour220` |
+| `state.action_required` | AI approval/input-required status badge amber-orange; currently aliases the established warning token | `colour214` |
+| `state.warning` | usage/status popup warning ANSI 256 wrapper; non-AI warning chrome | `colour214` |
 | `state.danger` | `255;107;107` | `colour160` |
-| `state.success` | settings/trust green families | `colour72`, `colour151` |
+| `state.success` | settings/trust green families; pane-border response-complete badge | `colour72`, `colour151` |
 | `state.ahead` | switch/git metadata and notify age ANSI 256 wrapper | `colour153` |
 | `git.branch` | switch/sidebar branch badge uses the statusbar git branch block colors | `colour30` bg / `colour231` fg |
 
@@ -140,6 +149,7 @@ Surface-specific tokens:
 | --- | --- |
 | Native picker | current row, titlebar, rule, pointer, highlight, muted text, chip active/inactive/disabled |
 | Statusbar row 1 | session identity, cwd secondary text, divider, git branch block, git dirty/staged/ahead/behind, settings action chip, clock |
+| App pane borders | semantic AI badge marker style (`dot`, `emoji`, or spacing-preserving `off`) plus action-required/success/progress state color |
 | Notify HUD/sidebar | line bg/fg, project badge, info/warn/crit/stale/gone badges, AI agent badge, count/age text |
 | Usage HUD/popup | OK/warning/critical/over-limit bars and numbers, empty cells, muted sync age |
 | Settings | add/type/open action, destructive remove/quit, back/cancel, info/read-only, dim description, root action/dim rows, trust trusted/stale/untrusted |

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.5",
+  "version": "0.6.7",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -23,14 +23,14 @@
     "README-ko.md",
     "LICENSE"
   ],
-  "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.6.5",
-    "@projmux/darwin-x64": "0.6.5",
-    "@projmux/linux-arm64": "0.6.5",
-    "@projmux/linux-x64": "0.6.5"
-  },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",
     "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"
   }
 }