projmux 0.8.4 → 0.10.0

package/docs/upgrading.md

@@ -40,6 +40,27 @@ still requires an explicit `PROJMUX_INSTALLER=github-release`.
 
 ## Behavior Changes
 
+### Terminal init command removed
+
+The deprecated top-level `projmux init` command and its legacy-only
+`--dry-run` flag have been removed. Use the exact replacement
+`projmux setup terminal`; it previews by default, and accepts `--apply`,
+`--config <path>`, and `--allow-symlink` when those behaviors are needed.
+
+### Pane rename keymap action ID removed
+
+The deprecated `rename-pane-topic` keybinding action ID has been removed. If
+`~/.config/projmux/keymap.toml` still contains
+`[bindings.rename-pane-topic]`, rename that table to
+`[bindings.rename-pane-label]` before running Settings or
+`projmux tmux apply`. Projmux now rejects the stale table with that exact
+replacement instead of silently applying its keys to the user-label action.
+
+This removal does not change `projmux ai topic set/clear`: those advanced CLI
+commands continue to write only AI topic and manual-ownership state. User pane
+rename continues to write only the pane label, and raw pane title remains an
+independent fallback.
+
 ### Theme is now global-only
 
 Theme is a global user preference. The effective theme resolves from the global

package/docs/usage-tracking.md

@@ -1,26 +1,28 @@
 # Usage tracking
 
-`projmux usage` and `projmux status usage` report authoritative 5-hour
-and weekly utilisation for enabled AI agents. `--model all`, the tmux
+`projmux usage` and `projmux status usage` report authoritative fixed-window
+utilisation for Claude/Codex and official named quota buckets for Antigravity.
+`--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
+agents as the source of truth, so disabled Claude/Codex/Antigravity providers are
 not refreshed or rendered on ambient/all surfaces. Explicit read-only
-requests such as `projmux usage --model claude` or `--model codex`
+requests such as `projmux usage --model claude`, `--model codex`, or
+`--model antigravity`
 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,
+Claude and Codex adapters read the upstream's own account view. Antigravity
+reads only the official managed statusline payload: `context_window` remains
+private conversation-local diagnostic metadata, while each valid `quota` map
+entry is a separate account row. Projmux preserves the upstream bucket ID and
+never guesses that an undocumented ID means `5h` or `weekly`. It does not infer
+quota, cadence, reset timestamps, or account limits from screen scraping,
 tokens, history, OAuth/cache files, or binary strings.
 
+Claude keeps the canonical aggregate `five_hour` and `seven_day` rows and also
+preserves structurally valid typed `limits[]` rows as named account quotas for
+inspection surfaces. These named rows never participate in the ambient status
+projection.
+
 ## Adapters
 
 ### Claude (`internal/core/usage/adapters/claude`)
@@ -48,6 +50,23 @@ floor.
 - A clean 200 resets the consecutive counter.
 - `--force` (BackoffResetter) clears the persisted state and attempts
   the call regardless of streak.
+- Canonical `five_hour` and `seven_day` blocks remain `5h` and `weekly`.
+  Each valid typed `limits[]` row becomes `window=quota` with the exact opaque
+  `group` copied to `bucket`. The snapshot also preserves `kind`, `severity`,
+  `is_active`, and nullable `scope`, model ID, and surface metadata; percent and
+  reset remain the authoritative common snapshot fields.
+- A model-scoped quota renders as `quota/<group> · <model display name>` in
+  text and popup inspection. Control characters and tmux format introducers are
+  escaped and the display label is bounded, while the stored identity remains
+  byte-for-byte unchanged. No model-family inference, aliasing, aggregation, or
+  percentage-to-count derivation is performed.
+- `limits[]` is capped at 64 rows and required field presence/types are checked
+  explicitly. A malformed container or row fails that adapter collection so the
+  manager retains the complete last-known-good Claude slice. A valid
+  aggregate-only response succeeds and therefore removes obsolete named rows.
+- Null legacy top-level model hints and unknown experiment keys are ignored.
+  Billing/credit blocks such as `extra_usage` and `spend` are not ingested or
+  rendered.
 
 ### Codex (`internal/core/usage/adapters/codex`)
 
@@ -73,6 +92,28 @@ Codex shares the manager's default `30s` throttle (no
 `ThrottleHinter`). It does not implement `BackoffStater` — local-only
 read.
 
+### Antigravity (`internal/core/usage/adapters/antigravity`)
+
+Local managed-statusline sidecars. No network or credential reads.
+
+- `context_window.used_percentage` and its conversation ID remain in the
+  private context sidecar for hook/notify diagnostics. They do not become
+  Usage snapshots. The legacy string percentage remains a writer fallback.
+- The official `quota` map is sorted by its exact bucket ID. Each valid bucket
+  becomes `window=quota`, `bucket=<upstream ID>` and renders as
+  `quota/<upstream ID>` on account-inspection surfaces.
+- Used percent is `100 * (1 - remaining_fraction)`. Non-finite or values
+  outside `[0,1]`, empty IDs, null/disabled entries, and negative relative
+  resets are ignored safely.
+- `reset_time` and optional `reset_in_seconds` are stored independently. An
+  absent relative reset differs from explicit zero; no value is derived from
+  the other.
+- Context and quota use independent private sidecars. A context-only payload
+  does not erase the last quota observation. An explicit empty/null quota map
+  records no buckets; the manager's existing rule still preserves prior model
+  rows when an adapter returns zero total rows. Context never participates in
+  that account-row replacement decision.
+
 ## Snapshot store
 
 ```
@@ -81,7 +122,10 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 
 JSON document keyed by adapter, recording:
 
-- per-window `Snapshot{Model, Window, Pct, Limit, ResetsAt, UpdatedAt}`
+- per-window `Snapshot{Model, Window, Bucket, Pct, Limit, ResetsAt,
+  ResetInSeconds, UpdatedAt, NamedQuota}`; `Bucket` is populated only for
+  `window=quota`, and `NamedQuota` is populated only when an upstream typed
+  named-quota contract supplies the metadata
 - per-adapter `last_collect` timestamp (drives the throttle)
 - per-adapter `Backoff{Until, Consecutive}` (drives the cooldown)
 
@@ -95,7 +139,7 @@ across machines (Dropbox, iCloud Drive).
 ### `projmux usage`
 
 ```
-projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|all]
+projmux usage [--model codex|claude|antigravity|all] [--window 5h|weekly|context|quota|all]
               [--json] [--force|-f]
 ```
 
@@ -104,11 +148,10 @@ For `--model all`, calls `Manager.Collect` (or `ForceCollect` with
 Enabled agents, filters by window, and renders the tab-aligned table:
 
 ```
-MODEL   WINDOW  PCT   RESETS_AT                STALE
-claude  5h      80%   2026-05-07T14:00:00+09:00
-claude  weekly  35%   2026-05-09T00:00:00+09:00
-codex   5h      8%    2026-05-07T11:30:00+09:00
-codex   weekly  4%    2026-05-09T00:00:00+09:00
+MODEL        WINDOW                 PCT  RESETS_AT                 RESET_IN  STALE
+claude       5h                     80%  2026-05-07T14:00:00+09:00 -
+antigravity  quota/gemini-weekly    6%   2026-07-06T16:50:32+09:00 560580s
+claude       quota/group-redacted · Model Redacted Alpha  38%  2031-02-03T15:05:06+09:00  -  *
 ```
 
 `STALE` is `*` when `now - UpdatedAt > 10m`. A `--json` payload returns
@@ -124,10 +167,12 @@ 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`, `--model codex` and
 `--model antigravity` bypass the enabled-agent filter for read-only
-inspection and collect/render only the requested adapter. Antigravity
-exposes no 5h/weekly quota, so its adapter reports a single `context`
-window row (context-window fullness, no `RESETS_AT`) sourced from the
-latest statusline `context_window` observed via hook ingest.
+inspection and collect/render only the requested adapter. Antigravity reports
+zero or more account `quota/<bucket-id>` rows. Legacy cached `window=context`
+rows are suppressed in text and JSON output. `--window quota` selects only
+account buckets; `--window weekly` never matches an opaque quota bucket named
+`weekly`. `--window context` remains an accepted compatibility filter and
+returns no Usage rows.
 
 ### `projmux status usage`
 
@@ -143,12 +188,19 @@ 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.
 
+The HUD first derives an ambient projection separate from lossless account
+snapshots. Canonical `5h`/`weekly` rows are eligible for every provider;
+Antigravity's exact `quota/gemini-weekly` identity is projected as `weekly`
+without rewriting the cache. Context, `3p-weekly`, and unknown quota buckets
+do not participate in status width. Claude `limits[]` named/model rows are also
+excluded; only its aggregate official `5h` and `weekly` rows reach the HUD.
+
 Output degrades through six tiers as `--max-width` shrinks:
 
 1. Long form with last-sync age + bars: `Claude (3m) 5h [████████░░]
-   80% · weekly [...]   Codex 5h [...] 20% · weekly [...]`
+   80% · weekly [...]   Antigravity weekly [...]`
 2. Drop the age indicator (legacy long form).
-3. Drop the weekly bar.
+3. Keep one primary bar per provider (`5h`, or `weekly` when 5h is absent).
 4. Drop bars entirely (`Claude 5h:80% weekly:30%`).
 5. Single-letter labels (`C 5h:80% weekly:30%`).
 6. Hard rune-truncate with trailing `…`.
@@ -167,6 +219,17 @@ sync metadata to the same enabled-agent scope as the ambient HUD. This keeps
 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 suppresses legacy cached context rows while preserving every valid
+named quota ID, reset, and freshness value. Its columns are data-driven: when
+no displayed row has authoritative absolute token counts, `USED`, `LIMIT`, and
+`LEFT` are omitted together. If any row has real counts, all three columns are
+shown; percent-only rows use unavailable cells. Counts are never derived from
+percentages.
+
+Named Claude rows use the same bounded, injection-safe label as text output and
+include their reset plus per-row `AGE`. JSON retains exact opaque group/model
+identity, nullable scope fields, `updated_at`, and the derived `stale` flag.
+
 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
 mtime. The sync line turns amber when the timestamp is more than 60 seconds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.8.4",
+  "version": "0.10.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.8.4",
-    "@projmux/linux-arm64": "0.8.4",
-    "@projmux/darwin-x64": "0.8.4",
-    "@projmux/darwin-arm64": "0.8.4"
+    "@projmux/linux-x64": "0.10.0",
+    "@projmux/linux-arm64": "0.10.0",
+    "@projmux/darwin-x64": "0.10.0",
+    "@projmux/darwin-arm64": "0.10.0"
   }
 }

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

@@ -1,227 +0,0 @@
-# Native Picker Engine
-
-This note tracks the native picker engine. Native is the only picker backend.
-
-The fzf compatibility surface for the native engine is tracked in
-[native-picker-parity.md](native-picker-parity.md).
-
-## What This Covers
-
-- `internal/ui/picker` is the backend-neutral contract for native picker rows,
-  actions, filtering, and typed-query prompts.
-- `internal/ui/projmuxpicker` is the projmux-specific native picker surface for
-  frame, redraw updates, theme tokens, ANSI width/truncation,
-  prompt/footer/list rendering, and preview pane layout. The POC keeps `picker`
-  responsible for backend routing, keyboard input, filtering, preview command
-  execution, and result contracts, while moving visual composition into
-  `projmuxpicker` so projmux can evolve a native picker design without coupling
-  every visual tweak to the compatibility option/result shape.
-  Built-in fallback colors are centralized as semantic tokens in
-  `internal/theme/palette.go`; see [theme-palette.md](theme-palette.md) for the
-  current inventory and truecolor to tmux 256-color mapping policy.
-- `internal/ui/pickercompat` remains an internal compatibility mapper between
-  the old option/result shape and the backend-neutral `picker.Options`
-  contract. It is not a runtime backend. App code should
-  describe picker intent as rows, actions, preview commands, and initial focus,
-  then route through the native picker.
-- Settings > Labs remains available for experimental settings, but picker
-  backend selection has been retired.
-- Picker flows covered by the native path include AI picker/settings, shell
-  update prompt, settings hub sections, switch settings/add-pin, the main
-  project switcher list, recent sessions, and notify sidebar.
-- The native picker supports ranked fuzzy search/filter, arrow-key selection in
-  normal CSI and tmux application-cursor modes, Enter, Esc, Ctrl-C, Backspace,
-  Ctrl-U, Ctrl-W, PageUp/PageDown, Home/End, modified CSI keys, custom expect
-  keys such as Ctrl-X/Alt-P, printable expect keys such as notify `a`/`x`, control
-  expect keys such as notify `Ctrl-X`, `start:pos(N)` initial focus, preview
-  command output, preview cycle command bindings, and sidebar focus command
-  bindings.
-- FZF-style movement keys are supported for native selection: `Ctrl-N` and
-  `Ctrl-J` move down, while `Ctrl-P` and `Ctrl-K` move up unless the app claims
-  the key as a custom action. Up/down-family movement wraps at list boundaries;
-  PageUp/PageDown and Home/End remain clamped or explicit jumps.
-- Typed-query prompts support cursor-aware insertion/deletion with a visible
-  prompt cursor, Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U, and Ctrl-W
-  for settings path entry.
-- The native key parser keeps legacy parser-fixture coverage for app-specific
-  modified-key escapes, plus generic modified forms such as `ESC [ 115 ; 7 u`
-  for `Ctrl-Alt-S`. This is backend parser parity, not a product fallback
-  route.
-- Native interactive picker screens use an alternate screen lifecycle to better
-  match fzf fullscreen behavior and restore the tmux pane after exit. Frame
-  updates and screen exit both return to column 0 before emitting terminal
-  control sequences, and screen exit resets styles plus clears the alternate
-  buffer from the home cursor before restore. This keeps restore/update escapes
-  and selected-session handoff output from visually trailing the bottom border
-  in tmux/script captures. Native also gives real TTY screen restore a short
-  settle window before returning to callers that may immediately draw a tmux
-  session.
-- Native interactive picker screens render inside a full-screen border frame to
-  match the app's fzf `--height 100% --border` surface more closely.
-- Popup-toggle commands use tmux `display-popup -B` when the native backend is
-  active so the native picker owns the visible frame and does not double-draw
-  with tmux's outer popup border.
-- Native Alt-1 sidebar popups use the same responsive width calculation as fzf
-  with a smaller native-only minimum, so the borderless native frame is not
-  wider than the existing fzf sidebar surface on normal terminals.
-- Native Alt-2 notify sidebar popups keep the fzf baseline width contract
-  (`24%`, minimum `64`) while still letting the native picker own the frame.
-- Native sidebar popups reserve two rows at the bottom for the tmux statusbar
-  area instead of using the full client height.
-- Simple native lists use the available terminal height after header, prompt,
-  footer, and preview reservations instead of a fixed page-sized viewport.
-- Navigation-only native lists mirror fzf `--disabled --no-input`: the input
-  prompt is hidden, printable non-action keys do not alter the query, and
-  expect/action keys still work.
-- Native frame content now uses the full inner border width so prompt/list/footer
-  separators reach the right border like fzf.
-- Native frames can render an optional picker-owned titlebar row below the top
-  border when `picker.Options.Title` is set; empty titles keep the default frame
-  unchanged. Non-empty titles use a distinct neutral titlebar surface with rule
-  fill and a divider row separating the title section from the search/content
-  section. The native Alt-1 project sidebar uses this for a
-  `Projects` titlebar.
-- Native width/truncation uses terminal cell width for Korean/CJK text, emoji,
-  and combining marks instead of raw rune count, so localized project names and
-  decorated notify headers do not push the right frame border out of alignment.
-- Searchable native pickers draw an explicit `Search` label and a muted
-  separator under the prompt/count line so the query area reads as distinct
-  chrome rather than the first row of the list. Footer, down-preview, and
-  multi-line card gaps share the same `projmuxpicker` separator primitive for a
-  more consistent native surface.
-- Native interactive mode enables SGR mouse reporting while the alternate screen
-  is active. Primary mouse down focuses the row under the cursor, primary mouse
-  up applies it, mouse wheel moves selection up/down, and reporting is disabled
-  again during screen restore.
-- When terminal size detection is unavailable, native picker falls back to a
-  conservative 80x24 terminal instead of assuming a wider surface. Interactive
-  tmux popups still use the detected popup size when `stty size` is available.
-- Simple and multi-line native rows share the same projmux current-row style and
-  pointer marker rather than falling back to terminal inverse video for simple
-  pickers.
-- Selected multi-line rows use the same pointer-width `▌` continuation marker
-  as the first selected project line, so switch/session/notify cards read as one
-  focused block.
-- Pointer and continuation markers render inside the current-row gutter style so
-  selected cards do not visually break between the marker and row content.
-- Native redraws use terminal synchronized-update wrappers and coalesced
-  row-diff updates after the first frame. The frame/redraw renderer lives in
-  `projmuxpicker` rather than the backend loop, skips unchanged frames, and
-  avoids a trailing newline after the bottom border. This reduces visible
-  keyboard-navigation flicker and prevents exact-height popups from scrolling
-  the top border off screen.
-- Native preview panes normalize tabs and control bytes before horizontal
-  clipping, preventing long preview rows from wrapping and consuming extra
-  vertical viewport rows in session popups.
-- Native sidebar list scrollbars use the fixed list viewport as their track and
-  measure multi-line cards in rendered rows, so the thumb does not shrink or
-  jump when card heights vary.
-- Switch picker git branch badges are capped more tightly for the native card
-  surface, so inactive branch backgrounds do not dominate narrow Alt-1 sidebar
-  rows.
-- Native selection changes render their frame diff before running sidebar focus
-  commands, so tmux focus/switch side effects do not delay the visible picker
-  movement.
-- In app TTY contexts, the native picker opens the controlling terminal
-  (`/dev/tty`) before entering raw mode. This avoids stdin/stdout mismatch and
-  line-mode escape leakage such as arrow keys appearing as `^[[`.
-- Raw TTY reads keep polling briefly across empty reads while decoding
-  escape-key sequences, so split arrow/Alt key bytes are consumed by the picker
-  instead of leaking into the query or parent shell.
-
-## Experimental Boundaries
-
-- The `projmuxpicker` package is intended as a foundation that can be carried
-  forward, along with the compatibility option/result mapping in
-  `internal/ui/pickercompat`.
-  Its frame, row, preview, theme, ANSI, and redraw modules are foundation code;
-  Docker sandbox scripts and dependency-policy notes remain support
-  scaffolding.
-- Switch and sessions preview panes are native previews for the concrete
-  projmux option shapes. Wide right-side preview windows render beside the
-  list, and sidebar-style `down,25%,border-top` previews render below the list
-  without a synthetic preview title row, using fzf-measured percent sizing.
-  Preview rows are padded by `projmuxpicker` to the full preview surface width
-  before the outer frame is applied, which keeps split/down preview columns
-  visually stable during redraws.
-  The full fzf preview-window grammar remains outside this POC surface.
-- Preview cycle state is covered in Docker e2e against real tmux sessions: the
-  switch and sessions popup flows type a filtered query, send `Right` and
-  `Alt-Down`, and assert the stored preview window/pane cursor for the selected
-  session.
-- Public doctor dependency policy no longer includes an external picker binary.
-
-## Interactive No-fzf Sandbox
-
-Use this when you want to enter a Docker container and experience this build
-directly without `fzf`. It builds the no-fzf dependency image, mounts this
-worktree, builds `projmux` inside the container, creates sample projects under
-`/workspace/projects`, stores the native picker backend in the sandbox config,
-writes a tmux config with the same backend in the tmux server environment, and
-launches `projmux shell`. It also forces UTF-8 locale inside the container. This
-uses `wt path` instead of `wt run` because `docker run -it` needs the current
-terminal TTY:
-
-```sh
-bash "$(wt path poc/native-picker-no-fzf)/scripts/poc-native-picker-no-fzf-sandbox.sh"
-```
-
-Inside the tmux shell, try:
-
-```sh
-projmux switch
-projmux settings
-projmux doctor --json
-```
-
-Manual UX checks for the Docker sandbox:
-
-- Alt-1 opens with the top border/title visible, not clipped.
-- Vertical borders stay continuous while moving Up/Down.
-- Alt-1 closes the sidebar immediately when pressed again.
-- Alt-2, Alt-4, Alt-5, and Alt-7 open their matching native popups and close
-  on the same Alt key immediately.
-- Alt-3 opens Recent Windows.
-- Arrow keys move selection without leaking `^[[` text into the query.
-
-`fzf` is intentionally not installed in the image.
-
-## Automated No-fzf Docker E2E Command
-
-Run this from the repository root. It builds a Go 1.24 Trixie no-fzf
-dependency image from `test/docker/no-fzf-poc.Dockerfile`, including Go module
-cache, then mounts the repository into an isolated `--network none` container,
-builds `projmux`, asserts `fzf` is not on `PATH`, runs the focused native-picker
-tests, stores the native backend through Settings > Labs, verifies the saved
-backend works without an env override, exercises `projmux switch --ui=sidebar`
-search/selection under a container PTY,
-exercises `projmux switch --ui=popup` and `projmux sessions --ui=popup` against
-existing tmux sessions under a wide 150x30 PTY, sends `Right` and `Alt-Down`
-once to smoke the preview-cycle bindings, asserts those popup flows stay on the
-right-side preview layout instead of falling back to inline preview, asserts the
-explicit `Search` chrome across the searchable native picker surfaces, launches
-`projmux shell` under a container PTY, verifies
-that it creates a tmux session, verifies immediate launch-key close behavior for
-Alt-1 through Alt-5 native popup surfaces, exercises `notify list --ui=sidebar`
-with the printable `x` expect key, and exercises the settings picker under a PTY
-using Enter and arrow-key navigation through the native backend. Settings flows
-must keep stderr clean in the no-tmux-server container; tmux no-server noise is
-treated as an e2e failure.
-
-Short tmux-friendly form:
-
-```sh
-wt run poc/native-picker-no-fzf -- scripts/poc-native-picker-no-fzf-e2e.sh
-```
-
-The script contains the Docker image build and isolated `docker run` command:
-
-```sh
-scripts/poc-native-picker-no-fzf-e2e.sh
-```
-
-To compare another base image without editing the repo, override the build arg:
-
-```sh
-PROJMUX_POC_NO_FZF_BASE_IMAGE=golang:1.24-bookworm bash "$(wt path poc/native-picker-no-fzf)/scripts/poc-native-picker-no-fzf-sandbox.sh"
-```

package/docs/native-picker-parity.md

@@ -1,153 +0,0 @@
-# Native Picker fzf Parity Map
-
-This audit note reverse-engineers the subset of fzf behavior that projmux
-currently uses and maps it to native picker evidence. It supports the default
-native picker engine and is not a public dependency-policy change.
-
-## App fzf Surface
-
-| fzf surface | projmux usage | Native status | Evidence |
-| --- | --- | --- | --- |
-| `--prompt` | AI, settings, shell update, switch, sessions, notify | Covered | `renderNativeInteractive`, `renderNative`; `TestNativePromptLineIncludesInlineMatchCount` |
-| prompt/list separation | native searchable picker chrome | Covered | native renders an explicit `Search` header label plus a separator under searchable prompt/count lines; `TestNativeInteractiveSeparatesSearchHeaderFromList`; Docker no-fzf e2e asserts the `Search` header in Settings, AI settings, mouse-click, switch sidebar, switch popup, sessions popup, and shell Alt-1 PTY logs |
-| `--height 100%` / `--border` | all interactive picker screens | Covered for fullscreen rounded border frame | `renderNativeFrame`; screen-height list budgeting; conservative 80x24 fallback only when terminal size detection is unavailable; `TestNativeInteractiveRendersBorderFrame`; `TestNativeInteractiveUsesAvailableHeightForSimpleLists` |
-| `--header` | AI, settings, shell update, notify | Covered | `renderNativeInteractive`, `renderNative`; settings native tests |
-| `--footer` / `--footer-border line` | AI, settings, shell update, switch, sessions, notify | Covered for interactive native screens | `renderNativeInteractive` reserves bottom footer space and renders a separator line; `TestNativeInteractiveRendersFooterAtBottom` |
-| `--ansi` | colored row labels from render package | Covered | native writes row labels directly, strips ANSI escapes from default search text, restores selected-row styling after embedded ANSI resets, and measures rendered cell width for Korean/CJK text, emoji, and combining marks; `TestFilterItemsIgnoresANSIEscapeSequences`; `TestNativeInteractiveUsesCurrentStyleForSimpleSelection`; `TestVisibleLenUsesTerminalCellWidth`; Docker e2e shows ANSI rows |
-| hidden value after tab delimiter | all picker selections and default fzf matching | Covered by `picker.Item.Value` and default search text | `pickercompat.PickerOptions`; `TestNativeRunnerFiltersAndSelectsByNumber`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey` |
-| plain fzf candidates without structured entries | compat option call shape | Covered | `pickercompat.PickerOptions`; `TestPickerOptionsFromCompatPickerMapsCandidatesWhenEntriesAreEmpty` |
-| search key filtering (`--nth`/reload filter file) | switch/sessions/notify entries | Covered by `Item.SearchText` with fzf reload order preservation | `FilterItems`; `TestFilterItemsUsesSearchTextNotMetadata`; `TestFilterItemsPreservesSearchKeyOrder` |
-| default `--smart-case` matching | all searchable picker rows | Covered | native filter keeps lower-case queries case-insensitive and uppercase queries case-sensitive; `TestFilterItemsUsesFZFSmartCase` |
-| fzf match highlighting | searchable simple picker rows | Covered for non-search-key simple rows | native highlights matched visible label runes while preserving embedded ANSI style; search-key reload lists intentionally keep fzf disabled-filter rendering without match highlights; `TestNativeInteractiveHighlightsSimpleQueryMatches`; `TestNativeInteractiveDoesNotHighlightSearchKeyReloadLists` |
-| `--disabled --no-input` | navigation-only notify sidebar | Covered | native suppresses prompt/query editing and ignores printable non-action input; `TestNativeInteractiveDisableSearchIgnoresPrintableInput`; Docker no-fzf e2e asserts notify prompt is hidden |
-| fuzzy result ranking | simple non-search-key picker UX | Covered with fzf V2 dynamic scoring for normal app rows | `fuzzyScore`; `TestFilterItemsRanksBetterMatchesFirst`; `TestFilterItemsPrefersFZFBoundaryAndCamelCaseMatches`; `TestFuzzyScoreMatchesFZFV2ReferenceScores` |
-| `--scrollbar █` | long switch/session/settings lists | Covered for app lists | `nativeListLinesWithScrollbarRows`; proportional multi-row thumb rendering in `projmuxpicker`; split-preview and sidebar list viewports keep a fixed row budget and scrollbar track; multi-line cards use rendered-row scroll units; `TestNativeInteractiveUsesScrollbarForLongLists`; `TestListLinesWithScrollbarUsesProportionalThumb`; `TestListLinesWithScrollbarMovesThumbGradually`; `TestListLinesWithScrollbarRowsKeepsViewportTrack`; `TestRenderSplitPreviewRowsKeepsRequestedViewport`; `TestNativeListScrollbarUnitsUseRenderedRowsForMultiline`; `TestNativeInteractiveKeepsMultilineScrollbarOnViewportTrack` |
-| `--read0` multi-line rows | switch, sessions, notify | Covered | `Options.MultiLine`; `TestNativeInteractiveRendersFZFLikeMultilineSelection` |
-| `--gap --gap-line ─` | switch, sessions, notify multi-line rows | Covered for app multiline rows | `nativeGapLine`, row-budgeted range; `TestNativeInteractiveRendersMultilineGapLine`, `TestNativeVisibleRangeCountsMultilineRenderedRows` |
-| selected multi-line marker | selected switch/session/notify cards | Covered for app multiline rows | native uses the same compact pointer-width red `▌` gutter as the first selected project line, and metadata lines align to the project-name column without the old deeper indent; `nativeContinuation`; `TestNativeInteractiveRendersSelectedMultilineContinuationMarker`; `TestInteractiveRowLinesUsesCompactSelectedMetaIndent`; `TestInteractiveRowLinesAlignsUnselectedMetaWithProjectName` |
-| fzf current row colors | simple and multi-line rows | Covered for app rows | `nativeCurrentStart`, `nativePointer`; pointer/continuation gutter tokens carry the current-row background; `TestNativeSelectedContentKeepsCurrentStyleAfterReset`; `TestNativeInteractiveUsesCurrentStyleForSimpleSelection` |
-| `--expect` keys | Enter/Ctrl-X/Alt-P/notify keys | Covered | `pickercompat.PickerOptions`; `TestNativeInteractiveSupportsCustomExpectKeys` |
-| printable expect keys | notify sidebar `a` ack and `x` non-critical clear | Covered | `TestNativeInteractiveSupportsPrintableExpectKeys`; Docker no-fzf e2e |
-| control expect keys | notify sidebar `Ctrl-X`, settings `Ctrl-Alt-S` close | Covered | `TestNativeInteractiveSupportsControlExpectKeys`; `TestNativeInteractiveSupportsControlAltCloseKeys` |
-| 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` |
-| `--preview-window right,60%,border-left` | switch popup, sessions popup | Covered for projmux option shape | `renderNativeSplitPreview` renders a single-column left border without a synthetic title row, uses fzf-measured percent sizing, normalizes preview tabs/control bytes before clipping, and pads both panes to fixed row widths so long preview rows do not wrap into extra vertical rows; `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativePreviewWidthUsesPreviewWindowPercent`; `TestRenderSplitPreviewRowsPadsBothPanes`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating` |
-| `--preview-window down,25%,border-top` | switch sidebar | Covered for projmux option shape | `renderNativeDownPreview` renders an immediate top border without a synthetic title row, uses fzf-measured percent sizing, and pads preview rows to the surface width; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestNativePreviewHeightUsesPreviewWindowPercent`; `TestRenderDownPreviewPadsPreviewRows` |
-| preview scrolling | long switch/session preview output | Covered for keyboard preview scroll | `previewOffset`; `TestNativeInteractiveRendersPreviewOffset` |
-| `--query` | typed settings path defaults | Covered | `Options.InitialQuery`; settings tests |
-| `--print-query` accept-query mode | typed settings path prompts | Covered | `Options.AcceptQuery`; `TestNativeRunnerAcceptsTypedQuery` |
-| query cursor editing | typed settings path prompts | Covered | Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U/W query editing plus visible prompt cursor; `TestNativeInteractiveEditsTypedQueryAtCursor`; `TestNativeInteractiveSupportsQueryLineEditingKeys`; `TestNativeInteractiveCtrlUDeletesBeforeCursor`; `TestNativePromptLineRendersQueryCursor` |
-| terminal arrow key variants | interactive selection in tmux/docker | Covered | CSI, SS3/application cursor, modified CSI tests; up/down movement wraps at list boundaries while PageUp/PageDown and Home/End remain clamped or explicit jumps; app TTY `/dev/tty` fallback; raw TTY EOF polling keeps split ESC sequences from leaking into the query; `TestNativeInteractiveWrapsPreviousNavigationKeys`; `TestNativeInteractiveWrapsNextNavigationKeys`; `TestNativeInteractiveJumpNavigationRemainsClamped` |
-| mouse support | optional fzf mouse picker interaction | Partially covered | native enables SGR mouse reporting in interactive alternate-screen mode, primary mouse down focuses the clicked row, primary mouse up applies it, and wheel input moves selection; drag gestures remain outside this POC; `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDownOnlyFocuses`; `TestNativeInteractiveIgnoresMouseReleaseBeforeDown`; `TestNativeInteractiveSupportsMouseWheelSelection`; Docker no-fzf e2e clicks the AI settings row under a PTY |
-| fzf navigation keys | interactive selection in searchable lists | Covered | native maps modified-key `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
-| alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
-| frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
-| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective `surface` / `chrome_foreground` SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
-| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg` from `surface` and `fg` from `chrome_foreground` so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
-| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame `surface` / `chrome_foreground` instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
-| redraw flicker/top clipping | keyboard navigation in exact-height tmux popup | Partially covered | native redraws use synchronized updates plus coalesced row diffs after the first frame, skip unchanged frames, render frame diffs before sidebar focus commands, frame rendering avoids trailing bottom-border CRLF, and screen exit clears the alternate buffer before restore; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; `TestFrameUpdateRendererSkipsUnchangedFrame`; `TestFrameUpdateRendererCoalescesEachFrameUpdate`; `TestRendererRenderFrameUsesCRLFRowsForRawTTY`; `TestNativeInteractiveUsesAlternateScreen` |
-
-## Native Surface Architecture
-
-- `internal/ui/picker` remains the backend-neutral contract and owns native
-  routing, keyboard input, fuzzy filtering, action dispatch, preview command
-  execution, and result handling.
-- `internal/ui/projmuxpicker` owns projmux-native visual composition: frame,
-  redraw updates, ANSI width/truncation, theme tokens, prompt/footer/list
-  rendering, selected row styling, scrollbars/gap rows, and preview pane
-  geometry/rendering.
-- `internal/ui/pickercompat` remains as the internal compatibility option/result
-  mapper from older app option shapes to `picker.Options` for the native
-  backend. It is not a runtime backend. This keeps app code closer to a
-  DI-style picker contract instead of embedding binding strings at each call
-  site.
-- Settings > Labs remains available, but picker backend selection has been
-  retired. Deprecated saved/env backend values normalize to native.
-- The split lets projmux grow a first-party picker design independently from
-  the compatibility option/result mapper.
-
-## Frame Chrome ANSI
-
-Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
-Titlebar text, title dividers, and chip-strip gaps inherit the frame
-`surface` / `chrome_foreground` instead of applying a second titlebar overlay ANSI layer;
-chip bodies can still carry active/inactive/disabled tones. Search prompt and
-footer separators fill the available frame width, and header, row, footer, and
-preview lines close any active SGR style before padding or frame borders can
-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.
-
-## Verified Flows
-
-- `ai` picker/settings: native backend routing covered by app tests. Docker
-  no-fzf e2e also types `Codex` into `projmux ai settings` and verifies the
-  native simple picker writes the `codex` mode without fzf.
-- `shell` update prompt: native backend routing covered by shared compat-to-native
-  bridge and settings-style typed prompt tests.
-- `settings`: native backend exercised in unit tests and Docker no-fzf e2e
-  using Enter plus arrow-key navigation under a PTY. The Docker e2e also fails
-  if the Settings flows write tmux no-server noise to stderr while running
-  outside tmux.
-- `settings > Labs`: unit-covered backend toggle writes
-  `~/.config/projmux/picker-backend`, updates the tmux global
-  `PROJMUX_PICKER_BACKEND`, and lets env override saved config.
-- `switch --ui=sidebar`: Docker no-fzf e2e creates sample projects, types
-  `bravo`, selects `bravo-web`, and confirms the opened tmux shell path.
-- `switch --ui=popup`: Docker no-fzf e2e creates existing tmux sessions using
-  the app's session naming convention, runs the picker under a 150x30 PTY,
-  types `bravo`, sends `Right` and `Alt-Down` to exercise preview window/pane
-  cycle, asserts the popup stays on 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.
-- `sessions --ui=popup`: Docker no-fzf e2e creates existing tmux sessions,
-  runs the picker under a 150x30 PTY, types `bravo`, sends `Right` and
-  `Alt-Down` to exercise preview window/pane cycle, asserts the popup stays on
-  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; 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
-
-- Preview-window parity is covered for the concrete projmux option shapes
-  (`right,60%,border-left` and `down,25%,border-top`) with fzf-measured percent
-  sizing. The full fzf preview-window grammar, threshold alternatives, sticky
-  headers, and offset expressions are intentionally outside this POC surface.
-- fzf V2 dynamic scoring is covered for normal app-length non-search-key
-  rows, including reference scores for boundary, delimiter, camelCase/number,
-  gap, and consecutive bonuses. Very large `query * row` matrices intentionally
-  fall back to the greedy scorer to avoid pathological memory use. Search-keyed
-  app pickers preserve fzf's `--disabled` reload order instead of score-sorting.
-- Mouse support is intentionally narrow in this POC: primary mouse down focuses
-  the clicked row, primary mouse up applies it, and wheel input moves selection.
-  Drag gestures and the full fzf mouse grammar are follow-up work.
-- The public doctor/docs dependency policy no longer includes an external
-  picker binary.
-- Draft PR: https://github.com/crevissepartners/projmux/pull/98.
-
-## Commands
-
-Automated no-fzf e2e:
-
-```sh
-wt run poc/native-picker-no-fzf -- scripts/poc-native-picker-no-fzf-e2e.sh
-```
-
-Interactive no-fzf sandbox:
-
-```sh
-bash "$(wt path poc/native-picker-no-fzf)/scripts/poc-native-picker-no-fzf-sandbox.sh"
-```
-
-Do not run the interactive sandbox through `wt run`: current `wt run` captures
-child stdio instead of forwarding the caller's TTY, so Docker cannot attach
-`-it` and terminal picker input will not behave like a real session.