projmux 0.8.3 → 0.9.0

package/docs/hooks.md

@@ -207,8 +207,9 @@ If a `send-noti` hook itself calls `projmux notify push`, projmux sees
 
 `Settings > Notifications > Delivery sources` surfaces the active Codex hooks,
 Claude, and tmux AI notify diagnostics: status, conflicts, config paths, and
-copyable CLI install/remove/dry-run commands. It does not install or remove
-external Codex, Claude, or tmux settings.
+copyable CLI install/remove/dry-run commands. It also shows whether
+`PROJMUX_NOTIFY_HOOK` overrides the built-in desktop sender. It does not install
+or remove external Codex, Claude, or tmux settings.
 
 `PROJMUX_NOTIFY_HOOK` is separate from `[hooks.send-noti]`: it replaces the
 desktop sender and receives positional arguments
@@ -617,37 +618,79 @@ catalog `install` field for installed hook events.
 
 ## Antigravity Hook Ingest
 
-`projmux ai ingest antigravity-hook < payload.json` is available for manual
-Antigravity CLI `agy` hook/statusline payloads. Projmux does not provide
-`projmux ai integrate antigravity`, does not install Antigravity hooks, and
-does not mutate Antigravity user config. The Delivery sources diagnostic
-therefore reports Antigravity as a read-only unsupported/manual row. If users
-wire it by hand, use an absolute `projmux` command path or a known cwd because
-relative command paths failed the Phase 0b smoke.
-
-The default known Antigravity catalog records only observed Phase 0b signals
-and marks them `install: false`:
+`projmux ai ingest antigravity-hook --event <event> < payload.json` accepts
+Antigravity CLI `agy` hook payloads. Antigravity v1.1.12 stdin does
+not include the event name, so the command's `--event` value is authoritative.
+Payload event aliases remain a compatibility fallback when `--event` is
+omitted. `projmux ai integrate antigravity [--dry-run|--remove]` owns exactly
+the named `projmux` entry in `~/.gemini/config/hooks.json` and separately owns
+only `statusLine` in `~/.gemini/antigravity-cli/settings.json`. Other named hooks,
+their fields, and unknown JSON values remain untouched. The generated commands
+use the stable absolute projmux executable because Antigravity runs handlers
+with the config directory as cwd. The command refuses unmanaged name/command
+conflicts, malformed JSON, symlink paths, and permission failures with an
+actionable diagnostic. Doctor/Settings distinguish installed, missing,
+conflicting, and stale managed entries; stale covers executable, event/schema,
+or stdout-fallback drift and is refreshed by the install command.
+The statusline object uses the official v1.1.12 command shape with
+`enabled=true` and `stack_with_default=true`. Its direct explicit `Statusline`
+ingest command emits empty stdout, preserving the built-in line. Existing
+custom statusline commands are conflicts and are never wrapped or chained.
+
+The default Antigravity catalog records the five official v1.1.12 events and
+installs four non-permission events:
 
 | Event/signal | Behavior |
 | --- | --- |
-| `PostInvocation` | marks the matched pane hook-active and writes a quiet ingest diagnostic; no notify queue entry is pushed |
-| `Stop` | pushes a completion row, or a critical error row when `error` is present or `terminationReason` is non-normal |
-| `Statusline` with `tool_confirmation_pending=true` | pushes a critical approval row; this is only active when a statusline/manual status payload is wired to ingest |
-| `Statusline` without `tool_confirmation_pending=true` | marks the matched pane hook-active and writes a quiet ingest diagnostic |
+| `PreToolUse` | known permission-changing event; never installed and no permission decision is synthesized |
+| `PreInvocation` | marks the matched pane hook-active and moves it to thinking/busy; no notify queue entry is pushed |
+| `PostInvocation` | marks the matched pane hook-active and writes a quiet bookkeeping diagnostic; no notify queue entry is pushed |
+| `PostToolUse` | marks the matched pane hook-active, retains tool error metadata in quiet diagnostics, and pushes no notify queue entry |
+| `Stop` | pushes an info completion unless an explicit error signal requires a critical error row |
+| `Statusline` with `tool_confirmation_pending=true` | pushes/replaces a deduped critical approval-required row outside the hook catalog |
+| `Statusline` with `agent_state=thinking|working|tool_use` | moves the matched pane to thinking/busy without notifying, unless a terminal completion/approval state must be preserved from a late refresh; a new `PreInvocation` resets the next generation to busy |
+| `Statusline` with `agent_state=idle` or `tool_confirmation_pending=false` | quiet update; does not clear completion/approval attention and creates no notification |
 | unknown events | mark the matched pane hook-active and write quiet ingest diagnostics only |
 
-Antigravity notify rows use `agent=antigravity` metadata. Accepted fields
-include `conversationId`/`conversation_id`, `cwd`, `workspace.path`,
-`transcriptPath`, `terminationReason`, `error`, `fullyIdle`, `agent_state`,
-`context_window`, and nested `statusline.tool_confirmation_pending`.
+Antigravity notify rows use `agent=antigravity` metadata. The v1.1.12 parser
+retains common camelCase `conversationId`, `workspacePaths`, `transcriptPath`,
+`artifactDirectoryPath`, and `modelName`; invocation `invocationNum` and
+`initialNumSteps`; post-tool `toolCall`, `stepIdx`, and `error`; and Stop
+`executionNum`, `terminationReason`, `error`, and `fullyIdle`. Existing aliases
+such as `conversation_id`, `cwd`, `workspace.path`, `agent_state`, and nested
+`statusline.tool_confirmation_pending` remain accepted. The first non-empty
+`workspacePaths` value is only a cwd fallback candidate; empty/absent arrays do
+not become the process cwd, and inherited `$TMUX_PANE` still wins attribution.
+`NO_TOOL_CALL`, `MODEL_STOP`, and known normal reasons are info completions.
+Non-empty `error`, explicit `ERROR`, and `MAX_STEPS_EXCEEDED` families are
+critical; unknown reasons retain diagnostic metadata but default to info.
+Explicit non-permission hook ingest writes valid hook stdout: `{}` for
+invocation/post-tool events and `{"decision":"stop"}` for Stop. The latter
+allows the requested stop to complete; projmux does not emit `continue` or a
+`PreToolUse` permission decision.
+Each managed command includes its explicit event selector and a valid stdout
+fallback: `{}` for invocation/post-tool events and `{"decision":"stop"}` for
+Stop. The fallback is non-blocking and never returns `continue`,
+`allow`, `deny`, or `ask`.
+
+The named entry in `hooks.json` remains the install source of truth. Use
+`agy -p '/hooks' --output-format json` only as a read-only runtime diagnosis of
+loaded sources/events; its result is never used to generate or rewrite config.
 Antigravity ingest uses `conversationId` as pane thread metadata for matching
 and as session-state resume metadata. Session restore uses
 `agy --conversation <uuid>` only when that id is present and UUID-shaped;
-otherwise preview and doctor render `resume unavailable`. The statusline
-`context_window` percentage is persisted to the usage state dir on ingest so
-the usage HUD can surface it as a `context-window-only` row — Antigravity has
-no 5-hour/weekly quota contract, so no quota bars are emitted. Raw payloads or
-transcript contents are not stored.
+otherwise preview and doctor render `resume unavailable`. Official snake_case
+`cwd`, `conversation_id`, `transcript_path`, `agent_state`,
+`tool_confirmation_pending`, and structured `context_window.used_percentage`
+plus token fields are parsed directly. The structured percentage is persisted
+with conversation identity to the usage state dir; the legacy string percentage
+remains a fallback so the usage HUD can surface it as the conversation-local
+`context` row. The official top-level `quota` map is persisted independently:
+valid `remaining_fraction` values become used percent, exact upstream bucket
+IDs render as separate `quota/<bucket>` account rows, and `reset_time` plus
+optional `reset_in_seconds` retain their independent meanings. Invalid,
+disabled, missing, or empty quota shapes degrade without inventing a cadence or
+reinterpreting context. Raw payloads or transcript contents are not stored.
 
 ## Ingest Debug Log
 

package/docs/install.md

@@ -18,8 +18,8 @@ After installing, run:
 projmux doctor
 ```
 
-`doctor` checks that runtime tools such as `tmux`, `git`, and `stty` are
-available.
+`doctor` performs read-only diagnostics for runtime tools such as `tmux`,
+`git`, and `stty`.
 
 Start the tmux app with:
 

package/docs/keybindings.md

@@ -17,7 +17,7 @@ The recommended path when a key does not fire:
    `projmux shell` key adapter, then retry the physical key.
 3. Run `projmux setup` outside tmux to see which bytes reach the process.
 4. For supported terminals outside the native macOS app socket, preview
-   `projmux init [terminal]`; add `--apply`
+   `projmux setup terminal [terminal]`; add `--apply`
    only after reviewing the merge.
 5. For unsupported terminals, configure plain Meta bytes or add a custom key in
    Settings > Keybindings.
@@ -56,6 +56,13 @@ These shortcuts are the guaranteed launch defaults. They need no tmux prefix.
 to the selected live tmux window using that window's current active pane; it is
 separate from `last-pane` and from the existing-session popup.
 
+`Resources:Open` is listed in Settings > Keybindings without a default key.
+Adding a safe direct chord opens the Linux/tmux Resource Inspector through the
+canonical client-scoped popup-toggle path; pressing the same custom chord again
+closes it without touching another client's popup. The action remains usable
+when Settings > Labs > Live system resources is off—the Lab controls only
+statusbar visibility.
+
 The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
 session, `Ctrl-b ?` lists the live tmux bindings.
 
@@ -142,11 +149,11 @@ Advanced typed entry remains available from Action detail for literal
 risky/reserved key copy, and raw diagnostics. Advanced delivery is still owned
 by the selected Projmux action. The native macOS app-socket adapter reads the
 same safe chords directly; supported Ghostty and Windows Terminal mappings for
-other paths are previewed/applied through `projmux init`, not by storing raw
+other paths are previewed/applied through `projmux setup terminal`, not by storing raw
 sequences in the primary keymap. Options covers unbinding the action and
 reset/use-default flows. Diagnostic/probe/init workflows are not first-class
 Settings tabs; use `projmux setup` and, where the native adapter does not apply,
-`projmux init` from the terminal when key delivery needs remediation.
+`projmux setup terminal` from the terminal when key delivery needs remediation.
 
 Optional direct keys can be added for actions such as:
 
@@ -299,29 +306,29 @@ projmux setup --timeout 10s
 projmux setup --non-interactive
 ```
 
-## Auto-Config: `projmux init`
+## Terminal remediation: `projmux setup terminal`
 
-`projmux init` previews and optionally applies supported terminal mappings.
-Default mode is dry-run; pass `--apply` to write changes with a timestamped
+`projmux setup terminal` previews and optionally applies supported terminal
+mappings. Default mode is a read-only preview; pass `--apply` to write changes with a timestamped
 backup.
 
 ```sh
-projmux init
-projmux init ghostty
-projmux init ghostty --apply
-projmux init windows-terminal --apply
-projmux init --config /path/to/file
-projmux init --allow-symlink
+projmux setup terminal
+projmux setup terminal ghostty
+projmux setup terminal ghostty --apply
+projmux setup terminal windows-terminal --apply
+projmux setup terminal --config /path/to/file
+projmux setup terminal --allow-symlink
 ```
 
 The merge is idempotent: matching bindings are no-ops, missing bindings are
 added, and keys already mapped to a different user action are skipped with a
-warning. `projmux init` does not read `keymap.toml`; direct tmux keys still
+warning. `projmux setup terminal` does not read `keymap.toml`; direct tmux keys still
 belong in Settings > Keybindings or the keymap file.
 
 ### Ghostty
 
-`projmux init ghostty` emits plain Meta bytes for `Alt-1` through `Alt-5` in
+`projmux setup terminal ghostty` emits plain Meta bytes for `Alt-1` through `Alt-5` in
 the managed block:
 
 ```text
@@ -341,7 +348,7 @@ refused by default; pass `--allow-symlink` to write through the link.
 
 ### Windows Terminal
 
-`projmux init windows-terminal` merges `sendInput` actions identified by the
+`projmux setup terminal windows-terminal` merges `sendInput` actions identified by the
 `User.projmux*` ID prefix. The generated inputs use plain Meta bytes, tmux
 prefix sequences for split actions, and xterm modifier-arrow sequences for
 previous/next window:

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

@@ -24,8 +24,8 @@ The fzf compatibility surface for the native engine is tracked in
   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.
+- Settings > Labs remains available for Live system resources and Project
+  Hooks, but picker backend/source information 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.
@@ -188,12 +188,12 @@ Manual UX checks for the Docker sandbox:
 
 ## Automated No-fzf Docker E2E Command
 
-Run this from the repository root. It builds a Go 1.24 Trixie no-fzf
+Run this from the repository root. It builds a Go 1.25 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`
+tests, opens Settings > Labs with legacy `fzf` env/file values, verifies native
+operation without a Labs picker-source row or config rewrite, 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`

package/docs/native-picker-parity.md

@@ -66,8 +66,9 @@ native picker engine and is not a public dependency-policy change.
   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.
+- Settings > Labs remains available for Live system resources and Project
+  Hooks, but no longer exposes picker backend/source information. Deprecated
+  saved/env backend values remain read-compatible and normalize to native.
 - The split lets projmux grow a first-party picker design independently from
   the compatibility option/result mapper.
 
@@ -93,9 +94,10 @@ contract; native popups still rely on the existing borderless tmux popup path.
   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.
+- `settings > Labs`: unit and Docker no-fzf coverage assert only Live system
+  resources and Project Hooks are visible. The Docker smoke starts with legacy
+  `fzf` env/file values, verifies Settings still uses native without fzf, and
+  confirms the compatibility file is read without being rewritten.
 - `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

package/docs/notify-queue.md

@@ -70,12 +70,13 @@ exit code 2.
 routing/debug context such as `agent`, `thread_id`, `turn_id`, `cwd`,
 `model`, and `client`; Claude hook rows also carry event-specific keys such as
 `tool_name`, `tool_input.command`, `error_type`, `subagent_type`, and
-`teammate_name`. Antigravity manual hook rows carry `agent=antigravity`,
+`teammate_name`. Antigravity hook rows carry `agent=antigravity`,
 `conversation_id`, `termination_reason`, `fully_idle`,
 `tool_confirmation_pending`, `agent_state`, and `context_window` when present.
 The same `conversation_id` can seed session-state restore via
-`agy --conversation <uuid>` when it is UUID-shaped; Antigravity quota usage
-remains unsupported because `context_window` is not 5-hour/weekly quota data.
+`agy --conversation <uuid>` when it is UUID-shaped. Antigravity
+account quota remains outside notify attention semantics: `context_window` is a
+separate conversation-local gauge and is never treated as quota data.
 Tmux bell fallback rows carry `agent=bell`, `event=bell`, and tmux target
 context such as pane title, command, session, window, pane, and socket.
 `notify list --json` includes this metadata as the structured data channel

package/docs/npm-distribution.md

@@ -18,7 +18,7 @@ The shim sets `PROJMUX_INSTALLER=npm` before executing the real binary so
 `projmux update status` and the Settings About screen can present
 npm-specific guidance. npm is only an update/install source label here; the
 keybinding flow remains `projmux shell` first, then `projmux setup` and
-`projmux init` only for terminals that swallow shortcuts.
+`projmux setup terminal` only for terminals that swallow shortcuts.
 
 ## Local Packaging
 
@@ -116,5 +116,5 @@ completed update never leaves stale-path `run-shell` commands failing with
 
 The npm installer must not install system dependencies, edit shell startup
 files, or mutate tmux config. Those actions stay behind explicit
-`projmux doctor`, `projmux init`, Settings About update actions, or future
+`projmux doctor`, `projmux setup terminal`, Settings About update actions, or future
 opt-in install commands.

package/docs/operational-diagnostics.md

@@ -0,0 +1,80 @@
+# 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, create support archives, contact an issue tracker, or
+provide a background telemetry service.
+
+## 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.
+
+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.
+
+## 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`, `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,
+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.

package/docs/resource-attribution.md

@@ -0,0 +1,132 @@
+# 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 go test \
+  -run TestResourceAttributionRealTmuxReadOnlySmoke -v \
+  ./internal/integrations/tmux
+```
+
+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.
+
+## 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. 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.

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