projmux 0.9.0 → 0.10.0

package/docs/globalization.md

@@ -87,7 +87,7 @@ Files:
 
 - `internal/ui/projmuxpicker/*`
 - `internal/ui/render/*`
-- `docs/native-picker-no-fzf-poc.md`
+- `docs/native-picker.md`
 
 Classification:
 

package/docs/keybindings.md

@@ -194,7 +194,7 @@ 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 basic Settings flow is not the
 terminal remediation surface: key-role replacement, disable-default, typed
-fallback, terminal mapping preview/apply, and init execution rows stay out of
+fallback and terminal mapping preview/apply rows stay out of
 the action detail.
 
 The product model does not support `UserN` or `CSI-u` as fallback guidance.
@@ -242,7 +242,10 @@ Settings is the default apply path for key edits: it writes the key list,
 refreshes the generated config, and reloads the running tmux session when
 possible. Use `projmux tmux apply` as a CLI recovery/sync command after editing
 the keymap file by hand, after an outside-tmux Settings save, or after resolving
-a reported generated-config or live-reload failure.
+a reported generated-config or live-reload failure. Generated config first
+unbinds the known retired `C-t` pane-label chord, then installs the current
+keymap; an explicit current `C-t` assignment therefore wins without retaining
+the retired command body. Apply does not rewrite `keymap.toml`.
 
 ## Keymap File
 

package/docs/native-picker.md

@@ -0,0 +1,103 @@
+# Native Picker
+
+The native picker is the product picker for every interactive selection flow.
+There is no runtime backend selection, saved picker selector, or external
+picker process. `internal/ui/picker` owns the interaction contract and
+`internal/ui/projmuxpicker` owns its visual composition.
+
+## Product Contract
+
+| Area | Behavior | Primary evidence |
+| --- | --- | --- |
+| Items and results | Structured items keep display labels, stable values, optional search text, multi-line metadata, and action results separate. `internal/ui/pickercompat` maps older internal option/result shapes into this contract; it is not a runtime backend. | `TestPickerOptionsFromCompatPickerMapsCandidatesWhenEntriesAreEmpty`; `TestPickerOptionsFromCompatPickerPreservesTheme` |
+| Search | Lower-case queries are case-insensitive, uppercase queries are case-sensitive, hidden values remain searchable when no explicit search key exists, explicit search-key lists preserve caller order, and simple rows receive fuzzy ranking and match highlighting. | `TestFilterItemsUsesSmartCase`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey`; `TestFilterItemsPreservesSearchKeyOrder`; `TestFilterItemsRanksBetterMatchesFirst` |
+| Navigation | Up/Down, Ctrl-J/Ctrl-N, and Ctrl-K/Ctrl-P wrap selection; PageUp/PageDown and Home/End clamp or jump; empty lists remain safe. Ctrl-N and Ctrl-P remain real navigation keys unless a caller claims the key as a custom action. | `TestNativeInteractiveSupportsControlNavigationKeys`; `TestNativeInteractiveWrapsPreviousNavigationKeys`; `TestNativeInteractiveWrapsNextNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList`; `TestNativeInteractiveJumpNavigationRemainsClamped` |
+| Editing | Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U/W, printable input, accept-query mode, and a visible query cursor are supported. | `TestNativeInteractiveEditsTypedQueryAtCursor`; `TestNativeInteractiveSupportsQueryLineEditingKeys`; `TestNativeInteractiveCtrlUDeletesBeforeCursor`; `TestNativeRunnerAcceptsTypedQuery` |
+| Actions | Enter accepts, shared close actions abort, printable/control expect keys return stable action keys, command actions can refresh previews, and mutable actions can update items without restarting the picker. | `TestNativeRunnerUsesSharedCloseActions`; `TestNativeInteractiveSupportsPrintableExpectKeys`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestNativeInteractiveCustomActionMutatesItemsAndRefreshes` |
+| Deferred state | Deferred and event-triggered updates preserve query and selection by value, can repeat, and may explicitly choose a new focus value. | `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; switch and notify sidebar mutable-refresh app tests |
+| Preview | Popup previews use a right split, sidebar previews use a bottom split, control bytes and tabs are normalized before clipping, and preview scrolling/cycling rerenders in place. | `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating`; `TestNativeInteractiveRendersPreviewOffset` |
+| Mouse | SGR mouse input focuses on primary down, follows drag, accepts on matching release, and scrolls with the wheel. | `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDragFollowsSelection`; `TestNativeInteractiveSupportsMouseWheelSelection` |
+| Lifecycle | Interactive runs use the alternate screen, synchronized/coalesced frame updates, controlling-TTY fallback, and deterministic reader cleanup. | `TestNativeInteractiveUsesAlternateScreen`; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; picker/setup lifecycle tests in `docs/agent-workflow.md` |
+
+## Rendering And Popup Chrome
+
+The renderer owns rounded frames, optional titlebars and chips, search/header
+separators, footer placement, selected-row styling, proportional scrollbars,
+multi-line gaps, preview geometry, ANSI restoration, and terminal-cell width for
+CJK text, emoji, and combining marks. Frame-owned cells inherit the effective
+theme's `surface` and `chrome_foreground` values, including padding after
+embedded resets.
+
+Picker popups are always borderless tmux popups (`display-popup -B`) so the
+native renderer owns the visible frame. The popup body receives a per-command
+style derived from the effective theme; no global popup, pane, window, shell,
+or status style is mutated. Project sidebars use a `20%` width with a `40`
+column minimum, notification sidebars use `24%` with a `64` column minimum,
+and both reserve the two statusbar rows when client height is known.
+
+Primary evidence includes `TestAppRunTmuxPopupToggleUsesBorderlessNativePopup`,
+`TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromGlobalTheme`,
+`TestBuildPopupToggleAppliesNativeBodyStyle`,
+`TestSessionizerSidebarWidthUsesCompactMinimum`,
+`TestNotifySidebarWidthUsesProductContract`, and
+`TestSidebarPopupHeightLeavesStatusbarRows`.
+
+## Fuzzy Scoring Provenance
+
+The native fuzzy scorer intentionally follows the fzf V2 dynamic-scoring
+algorithm for the maintained reference cases in `internal/ui/picker/backend_test.go`.
+`TestFuzzyScoreMatchesFZFV2ReferenceScores` and
+`TestFuzzyScoreRejectsFZFV2ReferenceNonMatches` are provenance fixtures; keep
+their expected scores stable when changing filtering internals.
+
+## Retired Artifact Contract
+
+The retired picker selector environment variable and saved selector filename
+are not runtime inputs. Their presence must not cause lookup, file reads,
+warnings, deletion, rewriting, propagation to child popups, or any change to
+the native path. There is deliberately no alias, migration, or stale-value
+cleanup behavior.
+
+Coverage is split by boundary:
+
+- `TestRunNativePickerOptionDoesNotObserveRetiredBackendArtifacts` guards the
+  direct picker path, fails if the retired env name is queried, and verifies a
+  stale file is neither deleted nor replaced.
+- `TestAppRunSwitchUsesNativePickerWithoutBackendLookup` guards the ordinary
+  switch flow.
+- `TestAppRunTmuxPopupToggleIgnoresRetiredBackendArtifacts` and
+  `TestBuildPopupTogglePropagatesNativePickerEnvironmentWithoutRetiredBackend`
+  guard popup chrome and child-environment construction.
+- `test/e2e/linux-smoke.sh` launches the ordinary attached-client Settings
+  popup with stale env/file values, completes the recorder flow, verifies the
+  file inode/content are unchanged, and rejects visible compatibility output.
+
+## Removed PoC Coverage Mapping
+
+The retired standalone dependency sandbox and focused smoke duplicated product
+coverage or tested a dependency policy that no longer exists. Its valid
+behavior assertions remain covered as follows:
+
+| Removed focused assertion | Maintained coverage |
+| --- | --- |
+| Settings and Labs render through the native picker | `TestSettingsUsesNativePicker`; `TestSettingsHubKeepsLabsSectionWithoutRetiredPickerChoices`; ordinary attached-client Settings recorder in `test/e2e/linux-smoke.sh` |
+| Search chrome, smart-case filtering, native frame ownership, and full-height rendering | `TestNativeInteractiveSeparatesSearchHeaderFromList`; `TestFilterItemsUsesSmartCase`; `TestNativeInteractiveRendersBorderFrame`; `TestNativeInteractiveUsesAvailableHeightForSimpleLists` |
+| AI Settings maps a typed selection to the saved mode | `TestAISettingsPickerSetsSelectedMode`; native picker option/result mapping tests |
+| Switch popup/sidebar filtering, selection, preview cycling, and initial focus | `TestAppRunSwitchDefaultsToPopupAndOpensSelectedSession`; `TestSwitchCommandSupportsSidebarUI`; preview cycle and initial-position tests in `internal/app/switch_test.go` |
+| Sessions popup filtering, selection, and preview cycling | `TestAppRunSessionsDefaultsToPopupAndOpensSelectedSession`; session popup preview/cycle tests in `internal/app/session_popup_test.go` |
+| Notification sidebar navigation and mutable actions | `TestNotifySidebarUsesNativePicker`; notify sidebar ack/clear/deferred-refresh app tests |
+| Launch-key close behavior and Ctrl-N/Ctrl-P navigation | `TestNativeInteractiveClosesOnMatchingLaunchCloseKey`; `TestNativeInteractiveSupportsControlNavigationKeys`; empty-list and wrap tests |
+| Mouse selection and alternate-screen restoration | native mouse and lifecycle tests listed above |
+| Generated shell config and the Alt-1 project-sidebar popup path | `TestShellWritesAppConfigAndRunsIsolatedTmux`; `TestAppRunTmuxPopupToggleOpensStandaloneSidebar`; popup frame/body-style tests listed above |
+| Stale selector values do not affect the product | retained and strengthened in the unit/app/e2e negative coverage listed in the previous section |
+
+The dependency-absence assertion is now a source-residue property rather than
+a separate container scenario: production code contains no selector, resolver,
+saved-selector access, propagation, or external picker launch path.
+
+## Maintenance
+
+Update this document and the maintained list in
+[`docs/agent-workflow.md`](agent-workflow.md) whenever picker behavior changes
+coverage level, gains a new product flow, or changes input/render/action
+semantics.

package/docs/operational-diagnostics.md

@@ -2,15 +2,19 @@
 
 Projmux records a small local-only operational journal so command failures and
 state changes can be inspected after the originating process exits. It does
-not upload the journal, create support archives, contact an issue tracker, or
-provide a background telemetry service.
+not upload the journal, contact an issue tracker, or provide a background
+telemetry service. A support archive is created only by an explicit
+`projmux diagnostics report` invocation and is never transmitted.
 
 ## Safe event contract
 
 Each JSONL record has a closed schema: `at`, `level`, `component`, `event`,
 `result`, `duration_ms`, `run_id`, `version`, `mux_backend`, and optional
 allowlisted `command`, `subcommand`, `kind`, and sanitized `message`. There is
-no generic metadata map.
+no generic metadata map. Runtime lifecycle records add only closed
+`operation` and `code` enums. The allowed operations are session create,
+attach, switch, kill, and tmux apply; codes are stable failure/health
+classifications and never carry routing identity or subprocess details.
 
 Command and subcommand names come from static allowlists. Unknown argv values,
 paths, flags, and arguments are dropped. Messages have control/format
@@ -25,6 +29,28 @@ pane captures/output/title/topic/content, transcripts, raw hook payloads,
 configuration secrets, or arbitrary environment values. Phase 0 also does not
 add session/window/pane or other routing identifiers.
 
+One explicit state-changing command owns at most one lifecycle pair. Its
+`lifecycle.start` and `lifecycle.outcome` share the process `run_id`, and a
+composite create-then-attach/switch flow keeps the first real mutation as its
+operation instead of recording nested outcomes. Lifecycle ownership replaces
+the generic top-level `command.outcome`; it never duplicates it. Start/outcome
+append failures are ignored and do not change the command result.
+
+The diagnostics package exposes a typed `ReadRuntimeHealth` projection for
+read-only Doctor consumers. It reports the fixed `tmux` backend, latest
+socket/apply state, and a bounded tail/count of safe failures using only
+`Store.ReadOnly`; it does not create, chmod, lock, truncate, apply, restart, or
+repair anything. Doctor schema 2 consumes that seam for its `logs` findings
+and adds one fixed-argv, one-second `tmux -L projmux show-options` probe for
+actual socket/config health. The probe neither generates nor applies config.
+Its captured output is capped at 4 KiB. Doctor reads only a pre-existing
+regular generated config (at most 1 MiB) without following symlinks, and the
+shared read-only journal seam rejects non-regular inputs and files above 5 MiB.
+These conditions degrade to typed findings rather than blocking or repairing
+the source. Windows ACL privacy is reported as unverified because `os.FileMode`
+cannot prove it; a separate finding preserves the metadata-only writability
+result, and Doctor does not modify ACLs.
+
 ## Storage and retention
 
 The path is
@@ -54,9 +80,13 @@ arm`, `attention clear`, `attention window`, `tmux autosave-session-state`, and
 to the journal; an error from any of them still records exactly one safe error
 outcome. Explicit user mutations such as `attention toggle` retain their
 state-changing success record. Direct top-level help and explicit preview-only intents (`upgrade
---dry-run`, `update apply --dry-run`, `doctor --install-missing --dry-run`, AI
-integration dry-runs, and the currently preview-only session restore) are also
-read-only. Multi-mode commands such as AI status/topic, doctor install,
+--dry-run`, `update apply --dry-run`, AI integration dry-runs, and the
+currently preview-only session restore) are also read-only. Doctor is a stricter
+boundary: successes and errors never append to this journal, so diagnostics do
+not make its filesystem contract self-defeating. Support report success and
+errors likewise never append; its strict reader shares the viewer's tolerant
+decoder but never creates/locks/chmods/repairs/truncates the source journal.
+Multi-mode commands such as AI status/topic,
 terminal apply, snapshot delete, update check, and welcome popup inspect only
 allowlisted mode/flag names; boolean `=false` values retain mutation-capable
 classification, and no flag values are ever recorded. Help-looking tokens
@@ -78,3 +108,14 @@ recursion loop.
 The older bounded `ai-ingest.log` and subsystem-specific `PROJMUX_*_DEBUG`
 surfaces retain their current paths, formats, and behavior. They are not
 migrated by this foundation.
+
+## Explicit support report
+
+`projmux diagnostics report [--output <path>]` previews and then atomically
+publishes a private local `tar.gz`; see [cli.md](cli.md#diagnostics). The
+manifest records report schema version 2, `default-hash-v1` redaction, every
+included entry, and stable missing/corrupt/permission omission reasons. Doctor
+JSON schema version 2 and the bounded operations decoder are reused rather than
+duplicated. AI ingest contributes count-only allowlisted source/result rows,
+never raw legacy lines. Existing output files survive collisions and partial
+temporary archives are removed.

package/docs/pr-guideline.md

@@ -24,7 +24,7 @@ feat(ai): add codex split picker keybinding
 fix(ai): prepend agent bin dir to PATH so node-managed CLIs find node
 docs(readme): drop Releases and Configuration sections
 chore: bump release-please manifest to 0.3.0
-refactor(picker): collapse duplicate fzf bootstrap code
+refactor(picker): simplify native picker bootstrap code
 ```
 
 Rules:

package/docs/resource-attribution.md

@@ -90,11 +90,18 @@ The opt-in read-only test below observes an existing socket and emits counts
 only. It neither captures pane content nor reads process command lines.
 
 ```text
-PROJMUX_RESOURCE_TMUX_SOCKET=projmux go test \
+PROJMUX_RESOURCE_TMUX_SOCKET=projmux \
+PROJMUX_RESOURCE_EXPECT_PROJECT_ROOT=/path/to/project go test \
   -run TestResourceAttributionRealTmuxReadOnlySmoke -v \
   ./internal/integrations/tmux
 ```
 
+When `PROJMUX_RESOURCE_EXPECT_PROJECT_ROOT` is set, the smoke additionally
+requires at least one blank explicit anchor to resolve from its pane current
+path and requires the resulting project bucket to contain a pane. Output stays
+bounded to the expected project path and aggregate counts; it does not emit
+session names, pane content, prompts, transcripts, or process command lines.
+
 2026-08-12 result: `panes=8`, `pane_pid_eq_sid=8`, `missing_pids=0`,
 `attributed_processes=13`, `escaped_boundary=0`, `sampled=474`, `skipped=0`,
 `race=0`, `permission=0`, `status=ready`. A separate tmux format-only count
@@ -119,6 +126,18 @@ PROJMUX_RESOURCE_TRANSIENT_SMOKE=1 go test \
 The pane shell remained attributed while its real `setsid` child was counted
 at the escaped/Other boundary, without reading the child command line.
 
+The current-path fallback itself has a separate isolated real-tmux smoke. It
+starts with inherited `TMUX`/`TMUX_PANE` removed, uses a dedicated
+`TMUX_TMPDIR` plus `-L` socket, verifies the actual socket path is below that
+temporary root before exact cleanup, and confirms the blank tmux project
+option remains blank after in-memory attribution:
+
+```text
+PROJMUX_RESOURCE_PROJECT_FALLBACK_SMOKE=1 go test \
+  -run TestResourceProjectFallbackTransientSmoke -v \
+  ./internal/integrations/tmux
+```
+
 ## Phase 1 inspector
 
 The popup retains warming/partial/unavailable and overage states, renders RSS
@@ -127,6 +146,44 @@ samples when it closes. Its non-overlapping default cadence is two seconds;
 Ctrl-R shares the same scan gate. Selection and query survive refresh by stable
 row identity, while a vanished row clamps to the nearest valid neighbor.
 Display labels use label → agent topic → known interactive shell → raw title,
-but those values never become ownership keys. Unsupported platforms show an
-unavailable reason, not zero metrics. PSS, non-Linux collectors, process-list
-drill-down, history, and resource mutation remain outside this contract.
+but those values never become ownership keys. Pane rows and detail reuse that
+identity plus the tmux current command, PID/SID, pane id, and TTY; pane rows
+show attributed process counts while project/window rows retain pane counts.
+Right/Enter move forward, Left moves back (and is a root no-op), and Esc closes
+at every depth. Unsupported platforms show an unavailable reason, not zero
+metrics. PSS, non-Linux collectors, process-list drill-down, history, and
+resource mutation remain outside this contract.
+
+Host and attributed CPU/memory use the same semantic classifier as the live
+statusbar: CPU is normal below 70%, warning at 70–89.9%, and critical at 90%
+or above; memory is normal below 75%, warning at 75–89.9%, and critical at 90%
+or above. Values retain the resolved semantic role but omit visible severity
+words. Unknown is rendered as `--`, never as zero; Sample lifecycle and
+freshness remain explicit text.
+
+The first paint is a non-actionable warming surface. Completed samples report
+age and fresh/stale state; partial and overage callouts stay bounded to counts
+and aggregate values. Empty and gone scopes are read-only and explain what the
+latest complete sample can no longer open. Automatic refresh runs every two
+seconds; Ctrl-R reports in-progress state while retaining the last complete
+sample. Both paths preserve scope, breadcrumb, query, selection, and the row
+order last computed by Tab. The default order is Name; Tab computes CPU,
+Memory, or Name once from the current sample, while later refreshes update row
+values without silently moving focus. Native synchronized frame diffs repaint
+only changed rows and update state/footer chrome together.
+
+The live summary is a fixed five-row bottom dock below the search/list surface:
+one renderer-owned theme-aware divider, then Host, Attributed, Coverage, and
+Sample. It does not scroll or filter with rows. Coverage owns the non-drillable
+Other or current-scope empty/gone explanation; bounded partial/overage details
+stay on Sample. The action footer remains below the dock with its own chrome
+boundary, so diagnostic values and key hints never share a role. The 80x24
+layout retains a navigable list viewport without clipping, border bleed, or a
+second dock divider.
+
+Project rows label project paths explicitly. The two attribution buckets keep
+their stable core keys but display `No project match` and `Multiple project
+matches` with bounded explanations. Pane primary identity follows the shared
+label → agent-only AI topic → interactive shell → raw title resolver; pane id,
+process id, and TTY remain labeled secondary details and stable keys are
+unchanged.

package/docs/settings-ia.md

@@ -85,8 +85,8 @@ view-first layout:
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`.
 - `Settings > Labs` contains only Live system resources and Project Hooks.
   Keybindings live at `Settings > Keybindings`; Labs has no visible or hidden
-  keybindings redirect. Native is the only picker backend, so Labs does not
-  render picker source/backend information.
+  keybindings redirect. The native picker is the product picker, so Labs does
+  not render picker source information.
 - `Settings > Labs > Live system resources` is a direct global on/off toggle
   for the macOS/Linux/WSL lower-status-row `CPU N%  MEM N%` segment. It defaults
   off, updates live tmux state when toggled, and renders unavailable on

package/docs/statusbar.md

@@ -68,7 +68,8 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>  CPU 12%  MEM 41%  
   without dominating the status row. Window tab indexes stay left of each tab,
   and tab titles are centered in a fixed-width trim so long active pane names
   do not resize the status row.
-- `Settings > Labs > Live system resources` adds the compact `CPU N%  MEM N%`
+- `Settings > Labs > Live system resources` adds the compact
+  `CPU N%  MEM N%`
   segment between git and the clock on macOS, Linux, and WSL. It is global,
   default off, and updates with tmux's existing five-second status interval.
   CPU and memory are host-scoped telemetry, not pane, window, project, or
@@ -76,8 +77,13 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>  CPU 12%  MEM 41%  
   normal below 70%, warning at 70–89%, and critical at 90% or above; memory is
   normal below 75%, warning at 75–89%, and critical at 90% or above. Normal and
   unavailable (`--`) values use the secondary status-text role, warnings use
-  the warning role, and critical values use the bold critical role. Styling one
-  value never promotes the other value.
+  the warning role, and critical values use the bold critical role. Severity
+  words are omitted. Each percent value, including `%`, occupies one fixed
+  four-column slot (`  9%`, ` 15%`, `100%`, or ` --%`), so styling or changing
+  either metric cannot move the following segment. Styling one value never
+  promotes the other value. The Resource Inspector uses this same classifier
+  and semantic roles for host and attributed CPU/memory while rendering
+  unavailable metrics as `--` without severity suffixes.
   Linux CPU is the aggregate delta from `/proc/stat`; memory is
   `(MemTotal - MemAvailable) / MemTotal` from `/proc/meminfo`. macOS CPU uses
   the aggregate Mach host tick delta; memory is total physical memory minus
@@ -155,7 +161,11 @@ Antigravity rows keep conversation-local `context` separate from account
 `quota/<exact upstream bucket ID>` rows; the popup displays an absolute reset
 when provided and otherwise the exact optional relative reset seconds. Opaque
 bucket IDs are escaped for terminal/tmux safety and are never assigned a
-`5h`/`weekly` cadence.
+`5h`/`weekly` cadence. Claude retains aggregate `5h`/`weekly` rows alongside
+typed named/model `limits[]` rows in this popup: model-scoped rows display the
+exact upstream group plus model display identity with a bounded terminal-safe
+label, reset, and per-row age. The compact status line excludes every Claude
+named/model row and continues to use only the aggregate official windows.
 Session State inspection lives under `Projects > Sessions > State`; global
 Settings > Session State is settings-only and the statusbar no longer exposes a
 duplicate State button.
@@ -169,7 +179,8 @@ does not leave terminal key state behind. The usage popup uses the same
 single-payload print and plain Enter-close pattern. It shows the authoritative
 last collect timestamp when present, falls back to the cache file mtime when
 needed, and keeps stale sync metadata muted instead of escalating it to a
-warning color.
+warning color. Percent-only named rows do not synthesize `USED`, `LIMIT`, or
+`LEFT` counts.
 The notification HUD detail surface opens the right-side notification popup
 through the notify sidebar action, showing the grouped pane/session inbox with
 collapsed group rows and the same attention-tinted title. When notification

package/docs/tmux-surface-inventory.md

@@ -18,7 +18,6 @@ Primary production sources:
 Support and fixture sources:
 
 - `test/`
-- `scripts/poc-native-picker-no-fzf-*.sh`
 - current docs that describe generated tmux snippets
 
 Useful inventory searches:

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

@@ -11,12 +11,17 @@ requests such as `projmux usage --model claude`, `--model codex`, or
 still collect and render that provider even when it is disabled.
 
 Claude and Codex adapters read the upstream's own account view. Antigravity
-reads only the official managed statusline payload: `context_window` remains a
-conversation-local fullness gauge, while each `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.
+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
 
@@ -45,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`)
 
@@ -74,12 +96,12 @@ read.
 
 Local managed-statusline sidecars. No network or credential reads.
 
-- `context_window.used_percentage` becomes the conversation-local `context`
-  row and retains the conversation ID in its sidecar. The legacy string
-  percentage remains a compatibility fallback.
+- `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>` beside, never instead of, `ctx`.
+  `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.
@@ -89,8 +111,8 @@ Local managed-statusline sidecars. No network or credential reads.
 - 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, while any returned context row
-  causes the normal full-model replacement.
+  rows when an adapter returns zero total rows. Context never participates in
+  that account-row replacement decision.
 
 ## Snapshot store
 
@@ -101,7 +123,9 @@ ${PROJMUX_USAGE_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/projmux/usage}/
 JSON document keyed by adapter, recording:
 
 - per-window `Snapshot{Model, Window, Bucket, Pct, Limit, ResetsAt,
-  ResetInSeconds, UpdatedAt}`; `Bucket` is populated only for `window=quota`
+  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)
 
@@ -126,8 +150,8 @@ Enabled agents, filters by window, and renders the tab-aligned table:
 ```
 MODEL        WINDOW                 PCT  RESETS_AT                 RESET_IN  STALE
 claude       5h                     80%  2026-05-07T14:00:00+09:00 -
-antigravity  context                14%  -                         -
 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
@@ -144,9 +168,11 @@ 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 reports
-its conversation-local `context` row separately from zero or more account
-`quota/<bucket-id>` rows. `--window quota` selects only account buckets;
-`--window weekly` never matches an opaque quota bucket named `weekly`.
+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`
 
@@ -162,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 [...]   Antigravity ctx [...] · quota/gemini-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 `…`.
@@ -186,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.9.0",
+  "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.9.0",
-    "@projmux/linux-arm64": "0.9.0",
-    "@projmux/darwin-x64": "0.9.0",
-    "@projmux/darwin-arm64": "0.9.0"
+    "@projmux/linux-x64": "0.10.0",
+    "@projmux/linux-arm64": "0.10.0",
+    "@projmux/darwin-x64": "0.10.0",
+    "@projmux/darwin-arm64": "0.10.0"
   }
 }