projmux 0.8.0 → 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.
@@ -43,13 +43,14 @@
 - `make test` also covers Codex rollout rate-limit window classification by `window_minutes`: old-schema primary 5-hour plus secondary weekly snapshots, new-schema primary weekly plus null secondary behavior, unknown-window skipping, and golden snapshot output for both rollout schemas.
 - `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, response-complete live badge consume on attention clear without idling action-required/progress badges, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border, Alt-1 sidebar window/preview tabs, and tmux window-status compatibility with dot as the persisted/config fallback.
 - `make test` also covers AI semantic badge Phase 3 theme-role hardening: `@projmux_ai_badge_kind` storage values and aggregate priority stay unchanged, `minimal` remains a read-time alias for the `off` badge style, progress/success/action-required badge roles stay distinct, permission/input status badges do not use critical red, and critical notify queue severity does not drive live AI status badge colors or desktop notification urgency.
-- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Settings delivery diagnostics that split logical key/raw bytes/tmux received key while distinguishing missing, ambiguous, adapter-needed, and delivered states, safe direct key pool and risky/reserved diagnostic-only copy, Projmux-owned Ghostty/Windows Terminal advanced delivery copy, raw escape/CSI-u/xterm modified/UserKey/UserSequence rejection from primary keymap storage, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, capture-unavailable Add key direct recorder routing with Advanced typed entry retained on Action detail, recorder Recording/Staged/Confirmed transitions, empty Enter no-op, Esc cancellation, staged candidate replacement, native byte-stream normalization/confirmation/conflict recovery, and one-reader/no-event-leak lifecycle, collapsed Troubleshooting entry copy, Settings delivery diagnostics that split logical key/raw bytes/tmux received key while distinguishing missing, ambiguous, adapter-needed, and delivered states, safe direct key pool and risky/reserved diagnostic-only copy, Projmux-owned Ghostty/Windows Terminal advanced delivery copy, raw escape/CSI-u/xterm modified/UserKey/UserSequence rejection from primary keymap storage, Labs compatibility redirect to the Keybindings root, existing macOS capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
 - Darwin native-key focused coverage includes portable physical chord parsing for Alt/Option, Control, Control-Option, Shift, letters/digits/navigation/function keys, `darwin && cgo` synthetic event-to-canonical-chord mapping for Option, Control, shifted letters, function keys, and arrows with unmatched/plain event pass-through, shared `keymap.toml` custom-action loading (including `M-a`), focused tmux client discovery, canonical `send-keys -K -c` dispatch through the existing root key table, native Settings Add key capture winning over terminal text encoding, default-on shell startup, `PROJMUX_NATIVE_KEYS=0`/`false` and Settings `[ui].native_keys = false` broker opt-out gates, broker direct no-op behavior, one-time pre-permission consent guidance, and an explicit Linux/Windows/no-CGO shell startup no-op boundary.
 - `make test` covers the default picker key ownership across catalog, generated tmux config, terminal adapters, setup probes, and native popup close hints: `Alt-4` opens AI Resume as a guaranteed launch default, while `Alt-7` opens the AI split picker as its editable default.
 - `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `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,9 +104,10 @@
 - 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, and status notify rendering with contextual project/state/agent badges. Host-only terminal, WSL, macOS, and GUI notification behavior remains outside Docker; see [docs/testing.md](testing.md).
+- `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).
 
 ## When To Update This List
 - A feature moves between unit, integration, and e2e coverage levels.

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/keybindings.md

@@ -102,11 +102,12 @@ and function keys. Command/Super is intentionally not part of this portable
 tier. Picker-local unmodified commands continue through the picker input path;
 the native adapter owns action-level no-prefix bindings only.
 
-Settings > Keybindings > Add key races the native modified-key capture against
-the existing controlling-TTY capture. On Darwin this lets Press a key store a
-new physical Option, Control, Control-Option, or Shift-modified chord before
-the terminal turns it into text; ordinary keys still use the portable TTY
-path. Other operating systems keep the existing TTY capture unchanged.
+On Darwin, Settings > Keybindings > Add key keeps racing native modified-key
+capture against the existing controlling-TTY capture. This lets Press a key
+store a new physical Option, Control, Control-Option, or Shift-modified chord
+before the terminal turns it into text; ordinary keys still use the portable
+TTY path. The Darwin transport lifecycle, Accessibility policy, and event
+mapping are unchanged by the Linux/WSL recorder described below.
 
 ## Discoverable Actions
 
@@ -119,18 +120,27 @@ transport policy toggle followed by the action list with a key summary and
 state. The key summary uses the first key plus `+N`, or `Not bound` when no key
 is active. State vocabulary is limited to Default, Custom, Available, and
 Unbound. Each action detail shows the action label, state, a flat Keys list
-with `+ Add key`, Options, and a collapsed
-Troubleshooting row with Test key delivery and Advanced... entry points. Key
-rows open key detail for Remove key and Test key. Add key opens Press a key by
-default; Enter key name, the safe direct key pool, risky/reserved key copy, and
-raw diagnostics live under Advanced. 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
+with `+ Add key`, Options, and a collapsed Troubleshooting row. Key rows open
+key detail for Remove key and Test key. In a Linux/WSL tmux popup, `+ Add key`
+enters a purpose-built recorder immediately: Recording waits for one chord,
+Staged previews its normalized tmux key name without writing, Enter saves and
+applies, and Esc discards it. Another chord replaces the staged candidate.
+There is no Back row, search prompt, or result count in recorder mode. Plain
+Enter and plain Escape are recorder controls, not candidates; modified Enter or
+Escape are accepted only when the native picker can decode them to a stable
+modified key name. Conflict and invalid-key feedback remains in the recorder so
+the user can choose another chord before any write.
+
+Advanced typed entry remains available from Action detail for literal
+`Enter`/`Escape`, nonstandard tmux key names, the safe direct key pool,
+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
 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.
+Settings tabs; use `projmux setup` and, where the native adapter does not apply,
+`projmux init` from the terminal when key delivery needs remediation.
 
 Optional direct keys can be added for actions such as:
 
@@ -201,8 +211,11 @@ uppercase `A`, distinct from `NotifySidebar:Ack` on lowercase `a`.
 Runtime picker footers render key guides from the merged keymap, using the
 first active key as the representative key.
 
-In Settings > Keybindings, **Add key** appends a key to the selected action's
-`keys = [...]` list. For catalog popup toggle actions, those keys are used both
+In Settings > Keybindings, **Add key** stages one normalized chord and appends
+it to the selected action's `keys = [...]` list only after Enter confirmation.
+The recorder reuses the native picker's single input reader; it does not open a
+second controlling-TTY reader or install a platform input hook. For catalog
+popup toggle actions, confirmed keys are used both
 by generated tmux open bindings and by popup-internal close bindings, so the
 same key can close the corresponding already-open popup. This same-key close
 behavior is only for actions cataloged as popup toggles, such as

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.0",
+  "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.0",
-    "@projmux/linux-arm64": "0.8.0",
-    "@projmux/darwin-x64": "0.8.0",
-    "@projmux/darwin-arm64": "0.8.0"
+    "@projmux/linux-x64": "0.8.2",
+    "@projmux/linux-arm64": "0.8.2",
+    "@projmux/darwin-x64": "0.8.2",
+    "@projmux/darwin-arm64": "0.8.2"
   }
 }