projmux 0.8.4 → 0.10.0

package/docs/operational-diagnostics.md

@@ -0,0 +1,121 @@
+# Operational Diagnostics and Privacy
+
+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, 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. 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
+characters removed, whitespace normalized, the current home path abbreviated
+to `~`, and length capped at 512 Unicode code points. Top-level outcomes never
+copy `error.Error()` into the journal: their message is one of three stable,
+lossy phrases (`command failed`, `invalid command usage`, or a classified
+non-success status). Error `kind` is stored separately from that phrase.
+
+The journal must never contain raw argv, stdin, prompts, notification bodies,
+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
+`${XDG_STATE_HOME:-$HOME/.local/state}/projmux/logs/operations.jsonl`.
+On POSIX systems the `projmux` state and `logs` directories are private
+(`0700`) and the journal is private (`0600`); accesses make a best-effort
+repair of older permissive modes.
+
+Append and trim share an OS-owned advisory inter-process lock. The kernel
+releases ownership when a process exits, so an orphaned lock path needs no
+path deletion or stale-owner reclamation and cannot race a successor owner.
+Lock acquisition has an explicit 200 ms total budget so this side channel
+cannot materially delay the original command result. When the file exceeds
+5 MiB, a platform-specific atomic replacement retains approximately the
+newest 2 MiB, beginning at a complete valid record; Windows uses replace-
+existing semantics rather than plain rename. A trailing partial record is
+discarded before the next append, and the reader skips malformed or truncated
+records.
+
+Classification is intentionally conservative for mutation-capable interactive
+commands: opening session/project/settings/popup flows is treated as changing
+even when a user cancels. Explicit read variants (`status`, `list`, `get`,
+`preview`, config printing, plain welcome, and the diagnostics viewer) remain
+read-only. The successful automatic hook/poll paths `ai ingest`, `attention
+arm`, `attention clear`, `attention window`, `tmux autosave-session-state`, and
+`window record` are also read-only so high-frequency operation does not append
+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`, 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
+after the direct command position stay conservatively mutation-capable because
+they may be values rather than help intent.
+
+Failures to resolve the path, create/repair permissions, lock, append, or trim
+are ignored by the top-level command boundary. They do not change the original
+command's stdout, stderr, exit code, or success/failure meaning, and journal
+failures are never recursively journaled.
+
+## Inspecting records
+
+Use `projmux diagnostics log`; see [cli.md](cli.md#diagnostics). All text,
+JSONL, tail, and filter views consume the same tolerant reader. A successful
+viewer read is excluded from success logging, so inspection does not create a
+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

@@ -0,0 +1,189 @@
+# Linux resource attribution core
+
+Phase 0 provides the read-only attribution contract consumed by the Resource
+Inspector shipped in Phase 1. `projmux resources`, the client-scoped
+`resource-inspector` popup, the statusbar range, and `Resources:Open` all keep
+the snapshot in memory only for the interactive process lifetime; it remains
+outside Session State.
+
+## Identity and inventory
+
+`tmux.Client.ListResourcePanes` reads a resource-specific inventory containing
+socket path, session id/name, window id, pane id, pane PID/TTY, and the session
+`@projmux_project_path` anchor. This is deliberately separate from the general
+`tmux.Pane` inventory so the resource contract requires PID, TTY, and project
+anchor data without weakening other pane consumers.
+
+The ownership key is `(socket, pane_id)`. Process identity is `(PID,
+/proc/<pid>/stat starttime)` and a process is attributed only when its POSIX
+SID maps to exactly one unique pane PID. Pane labels, AI topics, raw titles,
+current commands, and cwd-derived names are not ownership inputs.
+
+Linked appearances of one pane are deduplicated. Multiple non-empty project
+anchors become `Shared / ambiguous`; no anchor becomes `Unassigned`. Processes
+that use `setsid` or otherwise leave the pane SID remain host-only and are
+counted at the escaped boundary instead of guessed back onto a pane.
+
+## Sampling and read model
+
+The Linux collector enumerates `/proc` once per sample, then reads only
+`/proc/stat`, `/proc/meminfo`, and numeric `/proc/<pid>/stat` files. It never
+reads command lines, environment, prompts, pane content, transcripts, memory
+maps, SQLite, protobuf, or remote telemetry.
+
+- CPU needs two samples with the same positive logical CPU count. Primary CPU
+  is process tick delta divided by aggregate host tick delta (host capacity
+  share, normally comparable on a 0–100% scale); secondary CPU is that share
+  multiplied by logical CPUs (core-equivalent). First sample, invalid/reset
+  deltas, PID reuse, and logical CPU changes remain unknown/partial, never zero
+  or silently clamped.
+- Memory is summed RSS bytes plus `RSS / MemTotal`. RSS is a per-process sum;
+  shared pages may therefore be counted more than once.
+- Pane values are aggregated into unique window and project rows. Tests enforce
+  that window/project totals equal the same set of unique pane totals.
+- `Attributed` is not host total. `Other / unattributed` is a separate host
+  remainder. When process-delta timing or RSS sharing makes attributed values
+  exceed the host comparison sample, the model exposes an overage and leaves
+  remainder unknown instead of clamping it to zero.
+- Snapshot state is `warming`, `ready`, `partial`, or `unavailable`. Bounded
+  diagnostics contain scan duration and sampled/skipped/race/permission counts,
+  plus identity/delta quality counts; they contain no user payload.
+
+## Measurements
+
+Measured 2026-08-12 on Linux amd64, Intel Core Ultra 5 125U. Collector cases
+used generated procfs directory fixtures and `-benchtime=20x`; aggregation used
+`-benchtime=100x`. Commands:
+
+```text
+go test -run '^$' -bench BenchmarkCollectorScan -benchtime=20x -count=1 ./internal/integrations/procfsresources
+go test -run '^$' -bench BenchmarkBuildSnapshot -benchtime=100x -count=1 ./internal/core/resources
+```
+
+| Panes | Processes | Procfs scan | Scan allocation | Aggregation | Aggregation allocation |
+|---:|---:|---:|---:|---:|---:|
+| 10 | 50 | 0.407 ms | 80.6 KB | 0.026 ms | 32.1 KB |
+| 10 | 200 | 0.927 ms | 313.0 KB | 0.074 ms | 75.0 KB |
+| 10 | 1000 | 6.332 ms | 1.56 MB | 0.230 ms | 481.6 KB |
+| 50 | 50 | 0.407 ms | 80.6 KB | 0.084 ms | 90.4 KB |
+| 50 | 200 | 0.927 ms | 313.0 KB | 0.111 ms | 133.2 KB |
+| 50 | 1000 | 6.332 ms | 1.56 MB | 0.261 ms | 539.9 KB |
+
+The scan is process-count-bound and does not multiply by pane count. This
+supports the planned 2-second popup cadence without a daemon or persistent
+history. A separate count-only live cost probe (`PROJMUX_RESOURCE_PSS_MEASURE=1
+go test -run TestPSSReadCostMeasurement -v
+./internal/integrations/procfsresources`) attempted 200 host processes: 53
+`smaps_rollup` reads succeeded and 147 were skipped because of access
+restrictions. Those reads took 92.865058 ms, versus 7.323994 ms for the matching
+one-pass RSS/stat scan. This is not a universal cost multiplier: accessibility,
+process shape, kernel state, and cache effects differ by host. It does show the
+structural cost of a separate `smaps_rollup` read and kernel page accounting per
+accessible process, whereas RSS comes from the stat file already needed for
+CPU/identity. PSS is therefore **deferred**. It may be reconsidered only as an
+on-demand pane-detail measurement with a concrete consumer; it is not part of
+continuous refresh.
+
+## Sanitized real tmux smoke
+
+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 \
+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
+showed four shell panes, three direct agent panes, and one launcher pane. The
+zero escaped count is a valid observed boundary; the setsid fixture test pins
+the non-attribution behavior deterministically. Race and permission states are
+also deterministic fixtures: the collector test injects `fs.ErrNotExist` and
+`fs.ErrPermission` for numeric proc entries and checks the separate counts.
+
+A positive real-kernel setsid boundary is covered by an isolated transient
+smoke. It creates and removes its own tmux socket/server and never touches the
+existing production socket:
+
+```text
+PROJMUX_RESOURCE_TRANSIENT_SMOKE=1 go test \
+  -run TestResourceAttributionTransientSetsidSmoke -v \
+  ./internal/integrations/tmux
+```
+
+2026-08-12 result: `panes=1`, `attributed_processes=1`,
+`escaped_boundary=1`, `sampled=480`, `skipped=0`, `race=0`, `permission=0`.
+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
+explicitly as a sum, keeps `Other / unattributed` non-drillable, and discards
+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. 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/session-restore.md

@@ -11,9 +11,10 @@ projmux session-state restore --dry-run [--session <name>]
 projmux session-state delete [--session <name>]
 ```
 
-Snapshots preserve source metadata, not a final display label. Window records
-keep `window_name`; pane records keep `pane_title`, recipe fields, AI topic
-metadata (`@projmux_ai_topic`), and resume metadata when available. There is no
+Snapshots preserve source metadata, not a resolved display label. Window records
+keep `window_name`; pane records keep the user label, raw `pane_title`, recipe
+fields, AI topic and manual-ownership metadata (`@projmux_ai_topic` and
+`@projmux_ai_topic_manual`), and resume metadata when available. There is no
 `display_label` field in the snapshot schema. After restore, pane borders and
 app window tabs are display-time tmux policy: the app config derives both from
 the active pane's visible label expression, while raw shell or terminal titles
@@ -48,11 +49,21 @@ unknown sources are low or none. The old statusbar Session State shortcut has
 been removed; use `Projects > Sessions > State` or the `projmux session-state`
 CLI for inspection/actions.
 
+Session snapshots capture each pane's user-owned `label` separately from its
+raw `title` and agent recipe `topic`. Older snapshots decode with an empty
+label and no manual topic ownership; no title/topic equality heuristic is
+applied. Replay explicitly sets or clears the label, startup recipe fields, AI
+agent/topic/ownership/resume fields, and finally the raw title on the pane id
+returned by tmux creation. It does not derive a target or identity from pane
+order, a visible title, or equality between saved fields.
+
 Agent restore direct-starts supported resume commands when creating fresh tmux
 panes, matching the `projmux ai split` wrapper shape: the wrapper prepends the
-agent binary directory to `PATH`, changes to the saved cwd, sets the terminal
-and tmux pane title from the saved agent topic, then execs `codex resume <id>`,
-`claude --resume <id>`, or `agy --conversation <uuid>`. Antigravity restore
+agent binary directory to `PATH`, changes to the saved cwd, then execs
+`codex resume <id>`, `claude --resume <id>`, or
+`agy --conversation <uuid>`. It does not copy the saved topic into OSC or raw
+tmux title state; replay restores the final raw title only from `Pane.Title`.
+Antigravity restore
 uses only the stable statusline `conversation_id` or hook `conversationId`
 metadata captured as the pane resume id; missing or non-UUID Antigravity ids
 render as `resume unavailable` rather than falling back silently to a shell
@@ -63,6 +74,20 @@ environment, shell functions, aliases, or live process state. Startup recipes
 continue to use their saved `send-keys` command replay, and shell recipes only
 restore cwd/layout.
 
+This live capture lane remains distinct from resume-picker disk discovery and
+has high confidence (`hook`/`session-id`). When an Antigravity picker row starts
+a pane, its source is captured too: a UUID verified by an exact regular
+`conversations/<uuid>.db` through `last_conversations` or workspace-bearing
+summarized metadata has medium confidence, while a legacy `history.jsonl` row
+has low confidence. Preview and doctor report that source/confidence as stored;
+they do not claim that the upstream cache exposes complete history. Disk
+discovery does not replace an existing live hook source, and it never opens a
+conversation database or reads prompt/transcript content.
+Bounded Session State agent-pane previews place resume health before the full
+resume id, topic, and title so status, confidence, and source remain visible;
+the underlying snapshot and unbounded preview model retain those identity and
+context fields unchanged. Non-agent pane preview ordering is unchanged.
+
 Settings > Session State is global settings only: global auto-save, auto-save
 interval, and storage/retention policy. It does not show the current
 snapshot tree. Delete for current-session snapshots and destructive restore

package/docs/settings-ia.md

@@ -11,6 +11,10 @@ view-first layout:
   current state, source, and expected rendered result before offering mutation
   rows. If a detail opens a dedicated `Change` page, that page is mutation-only
   and does not repeat the same read-only view rows.
+- Every rendered non-empty row value is classified as navigation, actionable,
+  or passive information/disabled state and is mapped to a closed owner-loop
+  contract before rendering. An unowned value is a Settings error; Enter on a
+  passive row is consumed as a no-op.
 - `Settings > Project Picker > Workdirs` is the list/overview entry. Add/remove
   actions live inside that view.
 - `Settings > Project Picker > Project Root` shows effective and saved values
@@ -35,7 +39,7 @@ view-first layout:
   rows as always-visible sections.
 - Terminal delivery remediation lives outside Settings primary flow. The
   supported order is `projmux shell` first, then `projmux setup`, then
-  `projmux init` for supported terminal adapters.
+  `projmux setup terminal` 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 keys. Transport-dependent rows stay visible with
@@ -57,9 +61,10 @@ view-first layout:
   `[theme]` is never resolved or shown here.
 - `Settings > Notifications` owns notification delivery IA. Desktop notification
   mode, AI desktop notification dedupe duration, delivery source diagnostics,
-  AI hook quiet policy, in-app queue status, and
-  `PROJMUX_NOTIFY_HOOK` visibility live together without mixing mutation
-  boundaries.
+  and AI hook quiet policy live together without mixing mutation boundaries.
+  The in-app queue is consumed from the statusbar/sidebar, not from a standalone
+  Settings row. `PROJMUX_NOTIFY_HOOK` override presence is folded into Delivery
+  sources summary/detail instead of appearing as a separate root row.
 - `Settings > Notifications > Desktop notifications` owns the desktop
   notification mode. The detail choices are `none`, `notify`, and `raise`.
 - `Settings > Notifications > AI notification dedupe` owns the duplicate
@@ -67,10 +72,10 @@ view-first layout:
   the effective source; `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` remains the top
   override. The tmux bell fallback keeps its fixed 5 second window.
 - `Settings > Notifications > Delivery sources` shows Codex hooks, Claude, and
-  tmux producer diagnostics plus copyable install/remove/dry-run commands.
-  Settings copies command text only; it does not install or remove external
-  notify wiring. The legacy Codex notify source is intentionally omitted from
-  Settings.
+  tmux producer diagnostics, the effective desktop sender override state, and
+  copyable install/remove/dry-run commands. Settings copies command text only;
+  it does not install or remove external notify wiring. The legacy Codex notify
+  source is intentionally omitted from Settings.
 - `Settings > Notifications > Hook quiet policy` shows Codex/Claude hook
   runtime action values and writes only
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
@@ -78,13 +83,17 @@ view-first layout:
 - `Settings > Session State > Sidebar startup picker` controls the Alt-1
   project-open startup selector. The saved file remains
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`.
-- `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
-  visible Labs row. The hidden compatibility action redirects to the
-  `Settings > Keybindings` action list, not to a diagnostic default.
+- `Settings > Labs` contains only Live system resources and Project Hooks.
+  Keybindings live at `Settings > Keybindings`; Labs has no visible or hidden
+  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
-  unsupported platforms. WSL values describe the Linux guest/VM view.
+  unsupported platforms. CPU and memory use fixed independent semantic
+  thresholds (CPU warning/critical at 70/90; memory at 75/90); the toggle does
+  not expose threshold customization. WSL values describe the Linux guest/VM
+  view.
 - `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
@@ -106,6 +115,37 @@ view-first layout:
   `ko-KR`. When `auto` is active it must show the detected source (`LC_ALL`,
   `LC_MESSAGES`, `LANG`, or fallback). Unsupported locale tags must remain
   visible as warnings and fall back to `en-US`.
+- Global root descriptions keep ownership explicit: Appearance owns language,
+  AI badge style, and status/notification icon decoration; Theme owns presets,
+  color tokens, and font hints. About describes only the surface it retains.
+- `Settings > About` is intentionally compact: Version, Source, update
+  status/actions (including Latest, Update state, Installer, and Release notes
+  when available), Welcome, and Quit. It does not reproduce static key,
+  terminal, dependency, terminal-emulator, or documentation guides. Key
+  delivery discovery lives in `projmux setup`, supported terminal remediation
+  in `projmux setup terminal`, read-only dependency/runtime diagnostics in
+  `projmux doctor`, and broader orientation in Welcome and maintained docs.
+- Without an actionable project context, the Project surface renders one
+  passive context-guidance row instead of repeating the same disabled reason
+  for Trust, Hooks, Project recipe, and Effective merge view. With project
+  context, those four rows and Session State retain their existing actions.
+
+Settings mutation feedback follows one transient contract. The next picker
+frame inserts one passive `Feedback` row after Back; the row uses the catalogued
+`settingsNoopValue`, so Enter cannot create an unknown action. Selecting another
+navigation/action clears the old row before that operation runs, and a handled
+result replaces it. The inventory includes AI defaults/enabled agents/resume
+limits, notification modes/dedupe/hook policy, Appearance and locale choices,
+Labs toggles, project roots/workdirs/pins, project hooks/recipe/trust, Theme,
+Session State, direct keybinding reset/remove/toggle operations, and About
+update apply/check. Typed validation and staged apply failures stay in the
+popup instead of being visible only on stdout/stderr.
+
+The generic feedback inventory deliberately excludes Welcome, Quit,
+read-only hook/effective/notification diagnostics, Session State preview, and
+key capture/probe/diagnostic bodies. Those flows own a viewer, confirmation, or
+multi-step output surface; only an actual Settings write at their boundary is
+eligible for transient mutation feedback.
 
 Hooks remain the reference pattern for this IA:
 

package/docs/statusbar.md

@@ -68,9 +68,22 @@ 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
+  session attribution. Each value has an independent semantic style: CPU is
+  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. 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
@@ -82,6 +95,10 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>  CPU 12%  MEM 41%  
   re-enabling after a pause starts at `CPU --%` instead of showing a long-term
   average. Missing or malformed procfs data degrades to `--` or an empty segment
   without producing a tmux error popup.
+  The complete live segment is wrapped in `#[range=user|resources]...#[norange]`.
+  Clicking it opens the same canonical client-scoped `resource-inspector`
+  popup as the `Resources:Open` keybinding action. Disabling the Lab hides only
+  the segment; it does not disable a custom action or `projmux resources`.
 - The settings chip keeps its label padding inside the `settings` range
   and inside the chip background. The compact app chip renders `` with
   the extra right-side icon padding painted by the same background, while
@@ -112,6 +129,7 @@ bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
 | `kube`    | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s k`  |
 | `git`     | 0 | `projmux tmux popup-toggle sessionizer`   | `prefix s g`  |
 | `settings` | 0 | `projmux tmux popup-toggle --client <tty> ai-split-settings` | mouse only; `prefix s s` remains `session` |
+| `resources` | 0 | `projmux tmux popup-toggle --client <tty> resource-inspector` | mouse or custom `Resources:Open`; no default key |
 | `usage`   | 1 | show a native-framed usage HUD popup from cached usage state | `prefix s u`  |
 | `notify`  | 1 | `projmux focus --target <newest> --source status-bar --kind segment-click [--client <tty>]`, then ack on focus success | `prefix s n`  |
 
@@ -136,10 +154,18 @@ hard-truncate path still closes with `#[default]` so later status segments do
 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
+the cached usage state in-process and aligns model/window rows with
 right-aligned numeric values, dims unavailable values, keeps stale sync/age
 metadata muted, and colors only threshold values: amber at 80% and red at 95%.
+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. 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.
@@ -153,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/testing.md

@@ -77,7 +77,7 @@ 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`,
+  mapping with `projmux setup terminal ghostty` or `projmux setup terminal 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