projmux 0.8.1 → 0.8.2

package/docs/agent-workflow.md

@@ -28,7 +28,7 @@
 ## Maintained Test List
 - `make fmt`: repository formatting for Go, shell snippets, and generated docs where applicable.
 - `make fix`: safe automatic fixes such as `go fix` and repository-approved cleanup steps.
-- `make npm-pack`: local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages.
+- `make npm-pack`: macOS-hosted local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages, including native-key-adapter checks for both Darwin architectures; release staging reuses the release matrix archives.
 - `make security`: pinned govulncheck, gosec, staticcheck, gitleaks history/current-tree, actionlint, and shellcheck gates. Reviewed gosec/staticcheck findings use checked-in fingerprint/count baselines so only new findings fail.
 - `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling, compact dirty/staged/ahead/behind state colors, and bounded git/kube child execution, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, shell-entry welcome release prompt and inline update handling, shell update skip-by-latest-tag behavior plus best-effort stale-cache refresh, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, no-live-tmux save behavior, and stage-by-stage apply recovery copy, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling and bounded slow-repository branch enrichment, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex/Antigravity resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids including Antigravity conversation ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
 - `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling and compact dirty/staged/ahead/behind state colors, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, shell-entry welcome release prompt and inline update handling, shell update skip-by-latest-tag behavior plus best-effort stale-cache refresh, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, no-live-tmux save behavior, and stage-by-stage apply recovery copy, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex/Antigravity resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids including Antigravity conversation ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
@@ -50,6 +50,7 @@
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.
 - `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective|resume>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, resume picker routing/New delegation/zero-session fallback/Phase 1 fresh fallback contract, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.
 - `make test` also covers Settings IA regression guards for `send-noti` visibility in Hooks, no nested Project recipe inside Hooks, Project recipe/AI/Labs view-first detail rows, Appearance Path/Git/Notify icon direct off/symbol/emoji preview selection with no Change page, Notifications root/Desktop notifications/Delivery sources relocation, localized Korean Desktop notifications root/detail chrome without visible English residue, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
+- `make test` also covers the Linux/WSL live resource status Lab: default-off and atomic saved-value persistence, direct Labs on/off mutation plus live tmux option update, generated app/standalone conditional placement between git and clock, `/proc/stat` first/delta/reset/malformed/overflow and stale-reference handling, `/proc/meminfo` `MemAvailable` semantics, 0–100 clamping, atomic private sample-cache writes, and compact unavailable rendering.
 - `make test` also covers AI desktop notification dedupe precedence (env override > Settings saved value > default), Desktop notifications mode persistence through `desktop-notify-mode`, saved-config precedence over live tmux options, `projmux tmux apply` regeneration of `@projmux_desktop_notify_mode`, configured dedupe-window collapse/send behavior, Settings > Notifications AI dedupe preset/custom rows, explicit notify focus consume rules for selected critical rows and older same-pane non-critical AI cleanup, preservation of critical/permission/stop-failure/external/git/k8s rows during bulk cleanup, OS Toast click-to-focus queue consume, WSL Toast protocol handler hidden-launcher registration with `wsl.exe --exec` URI forwarding, and attention clear paths that do not ack the queue.
 - `make test` also covers AI hook runtime action precedence over catalog defaults, runtime quiet for known Codex notify events, runtime notify for known Claude quiet events, generic in-app-only notify rows for known Codex hook events without specialized handlers, suppression of desktop notification and `send-noti` dispatch on that generic path, separation of runtime hook action from catalog install events, Settings > Notifications hook quiet policy display/write behavior without external install/remove execution, hook desktop notification payload parity with the in-app queue text across the shared OS notification payload, normal/transient OS urgency and expiration for critical AI queue rows, and dormant title/capture fallback gating once a pane is hook-active.
 - `make test` also covers Settings > Session State as global settings-only UI with default-off auto-save, Sidebar startup picker relocation/compatibility, and no window/pane tree, Settings > Project > Session State project-derived identity plus project auto-save override/effective source rows and distinct Save latest snapshot / Save named snapshot labels, closed-project save disabled reasons, named snapshot portable path conversion, project/global auto-save precedence, Projects > Sessions > State read-only latest/named snapshot overview with window/pane cwd/recipe/agent-resume health, user-facing `projmux session-state` status/save/delete/restore dry-run actions including explicit manual save bypass of disabled autosave and agent resume status/confidence preview, and Project open sidebar startup coverage for Session State opt-in `Start project`, default-off empty creation, Latest snapshot, Named snapshot, Empty session, Back, saved-at row metadata, existing-session skip, startup-before-trust ordering, detached sidebar open continuation before client-scoped separate trust popup handoff without sidebar inline trust UI, trust approve continuation, and trust deny/cancel no-session sidebar refresh behavior.
@@ -103,7 +104,8 @@
 - psmux app/session foundation focused unit coverage includes `PROJMUX_MUX_BACKEND` and platform-default backend selection, psmux `-L projmux` session create/attach/switch/ephemeral marker command args, list-sessions/list-windows/list-panes minimal inventory parsing, selected-backend app command wiring, and the explicit absence of pane-scoped metadata in psmux inventory rows.
 - psmux AI split MVP focused unit coverage includes right/down `psmux -L projmux split-window` command shapes with `-P -F "#{pane_id}"`, PowerShell-rendered plain shell and Codex/Claude command tails, psmux-scoped Windows runner lookup for Codex `.cmd`/`.ps1`/`.exe`/extensionless shims, Claude native-installer PATH guidance, unchanged tmux split behavior, and explicit psmux degradation for tmux-only pane metadata, watch-title, and split-layout follow-up calls.
 - Shell focused unit coverage includes native Windows and explicit `PROJMUX_MUX_BACKEND=psmux` `projmux.exe shell` routing to `psmux -L projmux -f <generated config> new-session -A -s <session> [-c <cwd>]`, separate minimal psmux config generation with PowerShell-rendered callbacks, minimal psmux project-switch keybinding generation with psmux/native-picker env forcing, native line-mode fallback, explicit PowerShell `display-popup -E powershell -NoProfile -Command <script>` command tail, left-anchored sidebar-like popup geometry, explicit tmux override on Windows, and unchanged tmux/POSIX shell routing.
-- `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, and notify queue CRUD against isolated HOME/XDG paths.
+- `make test` also covers npm retire/staging path canonicalization for the resolved projmux executable so generated tmux config and hooks never embed a `node_modules/.projmux-<hash>` directory, plus error-suppressed attention and rebalance-panes hooks.
+- `make test-integration`: Docker-backed Linux integration smoke with real `tmux`, `git`, and `stty`; covers `doctor`, tmux config print/install/apply, default-off/on live resource config plus two-sample procfs status rendering, and notify queue CRUD against isolated HOME/XDG paths.
 - `make test-install-smoke`: Docker-backed source install smoke; covers `make install`, atomic binary replacement, `tmux apply` against a live `projmux` socket, and post-install notify queue initialization.
 - `make test-e2e`: Docker-backed real-tmux workflow smoke for session/pane setup, app config sourcing, reply-state notify reconciliation, focus notify fallback, status notify rendering with contextual project/state/agent badges, and an isolated attached-client `display-popup` Settings recorder flow that verifies staged-before-write Enter confirmation plus Esc cancellation against a temporary HOME/keymap. Host-only terminal, WSL, macOS, and GUI notification behavior remains outside Docker; see [docs/testing.md](testing.md).
 

package/docs/cli.md

@@ -269,7 +269,7 @@ alongside the Claude/Codex quota bars.
 
 ## status
 
-Per-segment status-bar renderers. All four are silent on failure — the
+Per-segment status-bar renderers. All five are silent on failure — the
 tmux status interval polls them and must never produce a stack trace.
 
 ```
@@ -277,6 +277,7 @@ projmux status git    [path]
 projmux status kube   [session]
 projmux status usage  [--max-width N] [--force|-f]
 projmux status notify [--max-width N]
+projmux status resources
 ```
 
 - `git` — `#[bold,fg=colour16,bg=colour45] <branch> <state> #[default]` for
@@ -296,6 +297,10 @@ projmux status notify [--max-width N]
   age, and `+<extras>`. Window/pane ids remain routable metadata but are not
   displayed in the compact HUD. Degrades through width tiers; default
   `--max-width` is `200` runes.
+- `resources` — Linux/WSL aggregate `CPU N%  MEM N%` from `/proc/stat` and
+  `/proc/meminfo`. CPU needs two invocations to establish a delta and renders
+  `--` for the first sample. WSL reports the Linux guest/VM view. Unsupported
+  platforms and unreadable procfs data produce no error output.
 
 ## statusbar
 

package/docs/configuration.md

@@ -770,6 +770,24 @@ The per-surface saved values live at:
 The legacy `~/.config/projmux/statusbar-decoration` value is still read as the
 fallback default when a per-surface file is absent.
 
+## Live System Resources Lab
+
+`Settings > Labs > Live system resources` controls the experimental compact
+CPU/memory segment on the lower status row. The saved global value is:
+
+```text
+~/.config/projmux/live-resources
+```
+
+Accepted values are `off` (default) and `on`. The feature is available on
+native Linux and WSL. It reads Linux procfs directly without launching `top`,
+`free`, PowerShell, or another metrics process. In WSL the values describe the
+Linux guest/VM view, not total Windows host utilization. The CPU delta cache is
+internal state at
+`${XDG_STATE_HOME:-~/.local/state}/projmux/live-resources-sample.json`.
+CPU reference samples older than 30 seconds are ignored and replaced on the
+next refresh.
+
 ## Rare Tunables
 
 These are intended for debugging or local policy, not routine setup:

package/docs/npm-distribution.md

@@ -34,12 +34,26 @@ or:
 scripts/package-npm.sh --version 1.2.3 --out /tmp/projmux-npm --pack
 ```
 
-The script stages package directories under `dist/npm` by default. It builds
-the Go binary for each supported platform, copies package metadata and docs,
-updates package versions in the staged copies, generates root
+The script stages package directories under `dist/npm` by default. Local
+all-platform packaging runs on macOS so both Darwin packages include the CGO
+native key adapter; attempting to build them on another host fails instead of
+silently producing a no-CGO Darwin package. The script builds the Go binary for
+each supported platform, copies package metadata and docs, updates package
+versions in the staged copies, generates root
 `optionalDependencies` for the supported platform packages using the same
-version, verifies the staged metadata is internally consistent, then runs
-`npm pack --dry-run` when `--pack` is set.
+version, verifies the staged metadata is internally consistent, checks both
+Darwin binaries for the native adapter, then runs `npm pack --dry-run` when
+`--pack` is set.
+
+Release packaging reuses the already-tested platform archives rather than
+cross-compiling a second set of npm-only binaries:
+
+```bash
+scripts/package-npm.sh \
+  --version 1.2.3 \
+  --release-dir /path/to/release-archives \
+  --out /tmp/projmux-npm
+```
 
 ## Publish Order
 
@@ -69,17 +83,35 @@ Leave the npm trusted publisher environment field empty unless the workflow is
 later moved behind a GitHub deployment environment.
 
 Tag releases publish npm packages from GitHub Actions after release archives
-are uploaded. The workflow runs:
+are uploaded. The npm job downloads the same linux/darwin × amd64/arm64
+archives built by the release matrix and runs:
 
 ```bash
-scripts/package-npm.sh --version "${GITHUB_REF_NAME#v}" --out dist/npm
+scripts/package-npm.sh \
+  --version "${GITHUB_REF_NAME#v}" \
+  --out dist/npm \
+  --release-dir dist/release
 ```
 
-then publishes each staged package with `npm publish --access public`.
+This keeps the npm platform binaries byte-for-byte aligned with the GitHub
+Release binaries, including the `darwin && cgo` native key adapter, then
+publishes each staged package with `npm publish --access public`.
 The npm publish job uses GitHub Actions OIDC (`id-token: write`) instead of a
 long-lived `NPM_TOKEN` secret. PR CI runs `make npm-pack` so package staging and
 dry-run packing fail before release.
 
+## Executable Path Canonicalization
+
+`npm update -g` retires the existing package directory by renaming it to
+`node_modules/.<pkg>-<hash>` before installing the replacement and deleting
+the retired directory. `os.Executable()` follows that rename, so a projmux
+process running across the update window can resolve its own path into the
+doomed staging directory. projmux canonicalizes any `node_modules/.<pkg>-<hash>`
+(or scoped `node_modules/@scope/.<pkg>-<hash>`) segment back to `<pkg>` before
+writing the resolved path into generated tmux config or live hooks, so a
+completed update never leaves stale-path `run-shell` commands failing with
+`... returned 127`.
+
 ## Non-Goals
 
 The npm installer must not install system dependencies, edit shell startup

package/docs/settings-ia.md

@@ -81,6 +81,10 @@ view-first layout:
 - `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 > Live system resources` is a direct global on/off toggle
+  for the 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 copy identifies the values as 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

package/docs/statusbar.md

@@ -14,7 +14,7 @@ truecolor to tmux 256-color mapping policy and palette inventory.
 ```
 row 0  #[range=user|notify] <notify HUD pill> #[norange]
                                       #[range=user|usage] <usage HUD bar> #[norange]
-row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
+row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>  CPU 12%  MEM 41%   %H:%M
        └────────── native tmux window list (one entry per window) ──────────┘
 ```
 
@@ -68,6 +68,18 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   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%`
+  segment between git and the clock on Linux and WSL. It is global, default
+  off, and updates with tmux's existing five-second status interval. CPU is the
+  aggregate delta from `/proc/stat`; memory is
+  `(MemTotal - MemAvailable) / MemTotal` from `/proc/meminfo`. The first CPU
+  sample renders `CPU --%` until a second counter sample exists. WSL values are
+  the Linux guest/VM view, not whole-Windows host utilization. The generated
+  tmux condition prevents the status subprocess from running while the Lab is
+  off. CPU reference samples older than 30 seconds are discarded, so
+  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 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
@@ -247,6 +259,12 @@ Appearance also shows the effective desired theme font. This is a status row,
 not a font editor: tmux status strings and ANSI output cannot force terminal
 font family or size, so unsupported environments report `not applied`.
 
+Settings > Labs controls the experimental live resource segment. Its saved
+value is `~/.config/projmux/live-resources`; changing it inside tmux updates
+`@projmux_live_resources` immediately. CPU sampling state is an internal,
+atomically replaced file under `${XDG_STATE_HOME:-~/.local/state}/projmux/`
+and is not a user-edited setting.
+
 To add a new clickable segment:
 
 1. Add a `statusbarRangeID` constant in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.8.1",
-    "@projmux/linux-arm64": "0.8.1",
-    "@projmux/darwin-x64": "0.8.1",
-    "@projmux/darwin-arm64": "0.8.1"
+    "@projmux/linux-x64": "0.8.2",
+    "@projmux/linux-arm64": "0.8.2",
+    "@projmux/darwin-x64": "0.8.2",
+    "@projmux/darwin-arm64": "0.8.2"
   }
 }