projmux 0.7.6 → 0.8.0

package/docs/agent-workflow.md

@@ -29,7 +29,12 @@
 - `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 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.
+- `make test` also covers GitHub Release updater resource and integrity boundaries: bounded compressed responses, decompressed tar streams, total and per-file regular bytes, entry counts, required SHA-256 asset digests, release-host/redirect allowlisting, scratch cleanup, and no atomic replacement after rejection.
+- `make test` also covers resume-title cleaning at the shared Claude/Codex/Antigravity choke point: known Claude command, local-command, task-notification, and system-reminder scaffolding is discarded so discovery falls through to the first real prompt, while inline `<`, leading HTML, and custom-element prompts remain intact.
+- `make test` also covers the hardcoded usage HUD manual refresh key, full enabled-adapter collection through the existing throttle/backoff policy, cooldown no-op, cached popup rerender, and unchanged click/`u` cache-only behavior.
 - `make test` also covers Settings > AI Settings > Enabled agents Phase 0 config behavior: missing config enables Claude, Codex, and Antigravity, unknown saved provider names are ignored without disabling known providers, Settings toggles persist Claude/Codex/Antigravity only, shell/selective are absent from enabled-agent rows, and a saved default split mode warns when its provider is disabled.
 - `make test` also covers native Alt-1 sidebar `Sidebar:KillSession` mutable refresh: the action kills through the focused-session safety path, keeps the native picker session open, refreshes rows and preview with `picker.Action.Mutate`/`DeferredUpdate`, and preserves the previous-live-session guard.
 - `make test` also covers Notify sidebar pane-grouped read-model rows and interactions: collapsed pane inbox group construction, fixed three-line group cards with stable project/provider, topic/context, aggregate metadata, and latest-preview slots including topic-with-project cases, child-count badges that match expandable child rows without rendering `+0`, childless group headers without strong fold affordance, selected/expanded marker-only row shape changes, duplicate label/preview reduction, worst-severity aggregation, inactive/gone group display and child-count rendering, pane-less fallback grouping, compact newest-first child event rows with warn/critical severity preservation, Right/Left fold mutation plus childless Right no-op refresh, folded and expanded live group Enter focus+ack with mixed-severity critical rows, inactive-but-routable group Enter focus+ack, gone group Enter cleanup without focus including critical rows, target-gone race cleanup, transient focus-failure no-ack refresh, child Enter focus/ack preservation, explicit group acknowledgement including mixed-severity critical rows, and grouped deferred refresh output with expanded-state pruning.
@@ -39,7 +44,7 @@
 - `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.
-- Darwin native-key focused coverage includes portable physical chord parsing for Alt/Option, Control, Control-Option, Shift, letters/digits/navigation/function keys, 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, and an explicit Linux/Windows/no-CGO shell startup no-op boundary.
+- 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.
@@ -52,6 +57,7 @@
 - `make test` also covers app tmux naming metadata policy: pane border and automatic window rename share the visible pane label expression, AI topic panes feed window tab labels through `@projmux_ai_topic`, shell panes prefer the visible shell command label such as `zsh`, and `projmux shell` disables program-driven window renames while keeping automatic rename enabled.
 - `make test` also covers manual Session State Save snapshot and restore dry-run preview actions, title-first pane preview labels with legacy snapshot fallback, missing-snapshot messaging, and the absence of the removed statusbar State shortcut.
 - `make test` also covers legacy named-snapshot storage compatibility for `.projmux/layouts/*.toml`, supported interpolation validation, malformed-file list warnings, portable conversion helpers, dry-run conversion to the session-state restore preview with source labels, missing current-session failure, destructive live replay helper behavior with fresh/internal source marking and fresh saved-snapshot cleanup, and the session-state live replay helper that stages windows, moves them by tmux ID, and removes extra live windows.
+- `make test` also covers the project-local executable artifact trust boundary for named snapshots: one-read exact-byte parse/hash reuse, SHA-256 allow-once/allow-always decisions, changed-byte and rename/replacement reauthorization, final-file and parent-component symlink rejection, config-absent and `PROJMUX_PROJECT_HOOKS=off` independence, non-interactive fail-closed behavior, commandless-layout compatibility, terminal-control escaping for layout names/descriptions/window names/agent topics/command previews, and deny/error paths that stop before restore, session/pane creation, or startup `send-keys`.
 - `make test` also covers `projmux ai integrate codex` default hooks install/idempotence/dry-run/removal, compatibility legacy Codex notify mode install/idempotence, dry-run preview, unmanaged `notify = ...` conflict refusal, managed-block removal, catalog-driven Codex hook event installation with local override merging, nested inline Codex hook schema, `[features]` merge/preservation, preservation of unrelated Codex/Claude config and unmanaged hook entries, Settings Codex `/hooks` review notice and tested-version rows, and remove-all behavior for projmux-managed Codex blocks.
 - `make test` also covers `projmux ai ingest codex-hook` event parsing, PermissionRequest critical queue rows with tool/action metadata, Stop info queue rows, UserPromptSubmit busy/no-queue behavior, pane-level semantic badge kind writes that keep permission, response complete, and in-progress states distinct, quiet/no-notify diagnostics for non-firing Codex hook events including override-added catalog events, cataloged hook notification body formatting, hook-active pane marking, topic preservation without hook candidate writes, and mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at.
 - `make test` also covers `projmux ai integrate claude` user-level Claude Code hook settings install/idempotence, dry-run preview, unmanaged projmux ingest command conflict refusal across all settings events, managed-command removal by marker even for stale events outside the current catalog, preservation of unrelated settings/hooks, catalog-driven Claude hook event installation with local override merging, and managed wiring for the 29 Claude Code 2.1.140 events in the embedded default catalog.
@@ -71,6 +77,8 @@
 - `make test` also covers the built-in semantic palette foundation: non-empty fallback truecolor/tmux tokens, distinct action/attention/AI/progress/danger roles, native picker chip/current/titlebar render strings including titlebar frame `surface` / `chrome_foreground` inheritance without separate overlay ANSI, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, settings/trust/destructive row color guards, global-only theme resolver behavior for `global`/`fallback` source labels (project `[theme]` is not a source), preset fill, explicit token override, unknown-preset/invalid-color warnings that ignore only the global layer, and truecolor-to-tmux mapping with generated `xterm*:RGB` terminal feature support, semantic role map (`RenderRoles`/`ANSIRoles`) fallback byte-identity for non-background historical palette literals plus explicit-theme repaint of Tier A/B chrome/state roles while Tier C renderer-only literals stay fixed, split foreground behavior where legacy `foreground` fills `text_primary` and `chrome_foreground` but `text_primary` does not repaint frame/title/search/border/status chrome, Phase 6 public token (`progress`/`success`/`action_required`/`pane_active_bg`/`focus`) repaint of the tmux and ANSI roles with `action_required` kept independent of `critical`, default `projmux` background tokens pinned to terminal default without separate terminal preset variants, Phase 6b pane-body-vs-popup/status background separation where an explicit `background` repaints the inactive pane body, an explicit `surface` repaints popups/native frames, and an explicit `status_background` repaints only the bottom status bar, native popup-toggle `display-popup -s` body style propagation from the effective theme without touching global popup/shell/status styles, and Settings global theme editing with the merged Global/Effective view, directly selectable prefixed theme token rows, no legacy `foreground` row, no project theme editor, and no font keys.
 - `make test` also covers Recent Windows Phase 0 state/model behavior: server-scoped file paths, missing/corrupt state policy with corrupt-file backup, MRU newest-first recording, same-window dedupe and promotion, default queue limiting, current-window exclusion, cross-session candidate retention, gone-window pruning against live window inventory, and label fallback rules that keep win/pane ids as debug fallback instead of the primary row label.
 - `make test` also covers Recent Windows Phase 1 native picker behavior: `projmux window recent` empty-state messaging, cross-session candidate picker rows with descriptive project/session/window/pane command age metadata, pane summaries mirroring visible pane labels with AI topic and known-shell command precedence, four visible pane cells before compact `+N` overflow, window-only switching without pane restoration, switch-failure refresh/prune handling, and gone-window pruning before picker selection.
+- `make test` also covers notify reconcile eviction policy: expired rows are removed only when their real tmux pane/session target is gone, expired live and unexpired gone rows remain pending, inventory failures skip target-based eviction, hard-cap overflow keeps the newest 256 rows, and ephemeral prune triggers cleanup through the reconcile hook after session kills.
+- `make test` also covers stale state cleanup policy: successful prune, tagged-kill, sessions-picker, and switch/sidebar session kills trigger best-effort preview-row cleanup; notify refresh publishing sweeps dead-PID sockets while preserving live-PID sockets; Session State prune listing distinguishes dead sessions from old live persistent sessions without deleting either, explicit named deletion removes only selected snapshots, malformed snapshots remain preserved with a warning, and doctor documents the manual-only retention policy.
 - `make test` also covers Recent Windows Phase 2/3/4 keybinding, popup, and runtime recorder integration: `RecentWindows:Open` owns the guaranteed `M-3` launch default, generated tmux config uses client-scoped `tmux popup-toggle recent-windows`, the popup body runs `projmux window recent`, generated tmux config installs background `window record` hooks for window and client-session changes plus first-use population without `session-window-changed`, `window record` snapshots current tmux socket/session/window/active-pane metadata into the socket-scoped store with escaped field parsing, repeated same-window record fires dedupe instead of growing entries, the queue remains bounded by `recentwindows.DefaultLimit`, Settings > Keybindings shows Recent Windows with the `M-3` default, setup probe text names Recent Windows, `SessionPopupToggle` no longer owns the guaranteed `M-3` default, and escaped tmux field separators are parsed for current/list window metadata.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,
@@ -83,7 +91,13 @@
   that update an open native sidebar best-effort without failing queue pushes, and `focus` dispatch diagnostics for session fallback, unresolved
   targets, window fallback, pane fallback, explicit id failures as unresolved exits, and
   notify-only fallback.
+- Security hardening coverage includes private `0700` directory and `0600`
+  file creation for sensitive local config/state, idempotent repair of legacy
+  permissions on load/save, best-effort behavior when chmod is unsupported,
+  symlink-safe repair that does not chmod an external target, and race-safe
+  notify/recent-windows lock retry jitter under concurrent store operations.
 - Picker focused unit coverage includes backend-neutral picker item/action mapping, native title-focused filtering, numeric selection, shared close actions including raw native custom actions, deprecated picker backend value normalization, AI picker title chrome and stable search-key ordering, Settings title chrome and root section order, Settings Labs shell without backend choices plus keybindings compatibility redirect, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, native row width clamps that preserve ANSI resets and Korean/wide-cell frame geometry with matched scrollbar/no-scrollbar row budgets including Settings > Appearance AI badge preview rows and parent long emoji preview rows, native app-background and semantic selected/muted/accent/warning/critical role coverage for fallback/effective themes across content padding, empty no-footer rows, footer rows, scrollbars, split-preview gaps, reset-to-padding continuation, and Korean Settings > Appearance AI badge style chips/prompt/emoji rows, multiline partial next/previous item row rendering with rendered-row scrollbar units, fixed split-preview and sidebar list viewports with scrollbar tracks, native up/down-family navigation wrap with empty-list safety and PageUp/PageDown/Home/End clamp regression coverage, native mouse down/follow-drag/release behavior, deferred native row updates that preserve filter/selection state and can repeat from event triggers, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with title/chip gap inheritance guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, cheap Alt-1 first-paint rows with deferred git/window/attention/preview enrichment, fixed three-line Alt-1 sidebar row geometry across cheap/enriched paints, bulk switch existing-session classification with per-candidate fallback, and notify sidebar title/popup sizing.
+- Picker/setup lifecycle coverage includes deferred native key-reader stop and repeated reopen cleanup, plus per-probe controlling-TTY cleanup and timeout-then-next-key reads without stale goroutines stealing input.
 - Doctor focused unit coverage includes native Windows psmux dependency policy, Windows `stty` skip behavior, Linux tmux required/stale behavior, and native Windows tmux bell fallback skip diagnostics.
 - psmux focused unit coverage includes Windows native command rendering policy: PowerShell-generated config callbacks quote `projmux.exe` and argv without POSIX shell quoting, direct CreateProcess/C-runtime command-line rendering remains separate from PowerShell and `cmd.exe /c`, and paths/args containing spaces, quotes, backtick, dollar, ampersand, pipe, redirect characters, semicolon, parentheses, braces, caret, percent, and exclamation are pinned as data.
 - 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.

package/docs/architecture.md

@@ -135,8 +135,8 @@ does not own the truth of every live badge.
   source (`ai|k8s|git|external`), TTL freshness metadata (default 600s), and a
   `Target{Socket, Session, Window, Pane}`. Re-pushing an existing id
   refreshes the entry's text and timestamp.
-- **List** — `projmux notify list` returns newest-first until explicit ack.
-  TTL is not a removal condition. `projmux notify list --live` adds a
+- **List** — `projmux notify list` returns newest-first without mutating the
+  queue. TTL alone is not a removal condition. `projmux notify list --live` adds a
   read-only comparison against live pane state, explaining manual reply
   badges without queue entries, live AI replies with/missing queue entries,
   and inactive (`queue-stale`) `ai:` entries.
@@ -147,7 +147,9 @@ does not own the truth of every live badge.
   `tmux list-panes -a` and back-fills entries for panes whose
   attention state is `reply` AND whose AI agent option is set,
   reporting inactive `ai:` entries that no longer match a live reply+agent pane without
-  acking them.
+  acking them. It then removes rows only when they are both TTL-expired and
+  gone from the real pane/session inventory, and enforces a 256-row hard cap
+  by evicting oldest overflow. Live rows otherwise remain explicit-ack-only.
   `make install` and `projmux upgrade` invoke it so the queue
   recovers from any drift introduced by a lost daemon.
 
@@ -214,6 +216,9 @@ The keyboard chord uses `bind-key s switch-client -T projmux-status` so the
 prefix-then-`s`-then-letter shortcut routes through the same dispatcher as
 the mouse click. Empty `#{mouse_status_range}` (clicks on whitespace) is a
 no-op so the binding never flashes a spurious error.
+The hardcoded `prefix s r` sibling is usage-specific: it runs the existing
+throttled collector and then reopens the same display-only usage popup from
+cache.
 
 ## Non-goals
 

package/docs/cli.md

@@ -30,7 +30,7 @@ projmux <command> [args...]
 | `notify` | Manage the pending AI notify queue (push/list/ack/reconcile). |
 | `pin` | Manage pinned project directories. |
 | `preview` | Manage persisted tmux preview selection. |
-| `prune` | Trim stale tmux lifecycle state. |
+| `prune` | Trim stale tmux lifecycle state and inspect preserved session snapshots. |
 | `quit` | Quit the app-owned projmux tmux runtime. |
 | `sessions` | Pick and open an existing tmux session. |
 | `session-popup` | Read tmux popup preview state. |
@@ -204,8 +204,9 @@ projmux notify reconcile [--json]
 ```
 
 - `push` — append (or refresh, with `--id`) one entry. `--ttl` defaults to
-  `600` seconds as freshness metadata; it does not remove rows from
-  `notify list`. `--text` is hard-capped to 80 runes (longer text is
+  `600` seconds as freshness metadata; expiration does not remove rows from
+  `notify list` and is considered only by reconcile together with a gone
+  target. Reconcile also retains only the newest 256 rows. `--text` is hard-capped to 80 runes (longer text is
   truncated server-side). After a successful queue write, projmux sends a
   best-effort refresh event to open native notify sidebars and fires
   declarative `[hooks.send-noti]` asynchronously if configured. Event delivery
@@ -301,6 +302,7 @@ projmux status notify [--max-width N]
 ```
 projmux statusbar click <range-id> [--socket <s>] [--mouse-window <id>]
                                    [--client <tty>] [--mouse-x N] [--mouse-y N]
+projmux statusbar usage-refresh
 ```
 
 Click/keyboard dispatcher for the two-line status bar. Implemented range ids:
@@ -313,7 +315,9 @@ popup; `pwd` shows the current pane path in a native-framed display-only
 popup; `kube` and `git` open the project switcher popup;
 `settings` toggles the settings popup for the tmux client; `usage` opens the
 detailed `projmux usage` table popup; `notify` focuses and acks the newest
-actionable queue target.
+actionable queue target. The internal `usage-refresh` shortcut entry point
+runs the same throttled, per-adapter collection policy as `status usage` and
+then reopens the display-only usage popup from cache.
 `MouseDown1Status` errors are
 swallowed and surfaced as `display-message` toasts so a transient
 failure does not raise a tmux error popup. See [statusbar.md](statusbar.md).
@@ -767,7 +771,15 @@ flags with the top-level `switch` UX:
 - `kill <session>` / `kill tagged` — terminate sessions; `tagged`
   consumes the active tagged-selection set.
 - `prune ephemeral` — drop ephemeral sessions older than the configured
-  retention window.
+  retention window. Successful session kills also remove the session's
+  persisted preview cursor; saved Session State snapshots are preserved.
+- `prune session-state [--older-than=720h]` — list snapshots whose tmux
+  session is no longer live or whose save time is older than the threshold.
+  Listing is read-only and never deletes snapshots.
+- `prune session-state delete <session>...` — explicitly delete only the
+  named snapshots. Session State snapshots are never automatically pruned,
+  because closed-session restore depends on them. `projmux doctor` repeats
+  this retention policy and points to the read-only listing command.
 - `tag` — manage the tagged-selection set.
 
 ## current / shell / attach / settings / quit

package/docs/configuration.md

@@ -273,7 +273,10 @@ of these is a public token: leave it unset to keep the historical built-in
 color, or set it to repaint the matching chrome.
 
 Supported presets are `projmux`, `high-contrast`, `blue-hour`, `carbon-violet`,
-`ember`, `forest`, and `rose`. A preset fills
+`daylight`, `ember`, `forest`, and `rose`. `daylight` is the fully-light
+preset; the others are dark. Preset colors paint projmux chrome only (status
+bar, popups, pane borders/tint) — pane contents follow the terminal theme, so
+`daylight` pairs best with a light terminal theme. A preset fills
 missing color tokens, and explicit color tokens override preset values. Tokens
 the global theme leaves unset fall through to the built-in fallback preset.
 Terminal-default backgrounds are configured per token with the `default`
@@ -694,10 +697,13 @@ snapshot`, named snapshot rows, `Empty session`, and `Back`. `Latest snapshot`
 is the snapshot auto-save that changes as auto-save runs; named snapshots are
 fixed snapshots. Rows include saved-at date/time metadata when projmux can
 determine it. `Back` returns to the project list without creating, replaying, or
-opening a session. After the startup mode is selected, project hook/config trust
-is evaluated if needed; approval continues the selected path and deny/cancel
-aborts without session create, snapshot replay, or startup command. The Alt-1
-sidebar opens trust as the shared client-scoped `Trust project hooks` popup
+opening a session. After the startup mode is selected, project automation trust
+is evaluated if needed. A named snapshot containing a startup `command` must
+authorize the SHA-256 of the exact layout bytes used for parse/restore, even
+when project hooks are disabled or `.projmux/config.toml` is absent. Approval
+continues the selected path and deny/cancel aborts without session create,
+snapshot replay, or startup command. The Alt-1 sidebar opens trust as the shared
+client-scoped `Trust project automation` popup
 instead of inline sidebar rows. The selected open continuation runs in a
 detached tmux job that can close the sidebar before trust without depending on
 the self-closing sidebar process to keep running. Deny/cancel refreshes the

package/docs/hooks.md

@@ -109,8 +109,11 @@ values.
 
 Global hooks under `$XDG_CONFIG_HOME` are prompt-free.
 
-Project-local `.projmux/config.toml` files are gated by trust-on-first-use
-before projmux runs hooks or applies startup/session environment settings.
+Project-local executable automation is gated by trust-on-first-use. This
+includes `.projmux/config.toml` before projmux runs hooks or applies
+startup/session environment settings, and a selected
+`.projmux/layouts/*.toml` named snapshot before projmux replays any declared
+`command`.
 Approving "always"
 records the file content hash in:
 
@@ -118,16 +121,22 @@ records the file content hash in:
 ${XDG_STATE_HOME:-$HOME/.local/state}/projmux/trusted-projects.json
 ```
 
-The trust key is the absolute repository path and the config path is stored
+The trust key is the absolute repository path and each artifact path is stored
 relative to that repository. Each project entry has a
 `trusted_at` timestamp and a `files` map of relative paths to SHA-256 hashes.
-When file content changes, projmux asks again and shows the old and new SHA-256
-hashes. In non-interactive contexts such as tmux run-shell or CI, untrusted or
-changed project-local files fail closed with a warning.
+When file content changes or the layout path is replaced, projmux asks again
+and shows the old and new SHA-256 hashes. Layout symlinks, including symlinked
+`.projmux` or `layouts` path components, are rejected. The selected layout is
+read once; those exact bytes are both hashed and parsed, and the resulting
+in-memory snapshot is what restore uses. In non-interactive contexts such as
+tmux run-shell or CI, untrusted or changed project-local executable files fail
+closed with a warning.
 
 Set `PROJMUX_PROJECT_HOOKS=off` to disable project-local hook discovery
 entirely. Project-local hooks can also be disabled from `projmux settings`
-under Labs. The global hook still runs either way.
+under Labs. The global hook still runs either way. This setting does not trust
+or bypass executable named-snapshot commands. A layout without a startup
+`command` does not require executable-artifact approval.
 
 ## Startup Commands
 

package/docs/keybindings.md

@@ -73,11 +73,29 @@ delivery path.
 This adapter is terminal-independent, so Ghostty and iTerm2 do not need
 separate projmux mappings for the app socket. It does not rewrite terminal
 configuration and it does not translate Option-produced symbols such as `¡`.
-The first launch requires macOS Accessibility permission because consuming a
-physical chord before the terminal converts it requires a CGEvent event tap.
-The broker waits for the one-time approval and enables the event tap
+The first launch shows a one-time consent hint before macOS asks for
+Accessibility permission. The hint explains that the adapter captures only
+modified chords from the configured keybinding catalog, never plain-text
+typing; physical Option needs the event tap because terminals may convert it
+before tmux can see it; and capture plus tmux injection stay on the local
+machine. The broker then waits for approval and enables the event tap
 automatically; the tmux session does not need to be restarted.
 
+Native macOS delivery remains on by default. To prevent the broker from
+starting—and therefore prevent the Accessibility prompt—turn off **Native
+macOS keybindings** in Settings > Keybindings before the next `projmux shell`
+start, or launch with:
+
+```sh
+PROJMUX_NATIVE_KEYS=0 projmux shell
+```
+
+`PROJMUX_NATIVE_KEYS=false` is equivalent. The environment opt-out takes
+precedence over the saved Settings value. Turning native delivery off leaves
+the ordinary terminal key path in place; Option chords then depend on what the
+terminal sends. Linux, WSL, and Windows never start this Darwin broker and are
+unchanged.
+
 The portable key vocabulary stays shared across operating systems:
 `M-` (Alt/Option), `C-`, `S-`, letters, top-row digits, arrows/navigation,
 and function keys. Command/Super is intentionally not part of this portable
@@ -96,11 +114,12 @@ Settings > Keybindings lists the full action catalogue. In particular, sidebar
 keymap actions, pane switching, window switching, and rename actions remain
 visible.
 
-The Settings flow is intentionally simple: the root is one 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
+The Settings flow is intentionally simple: the root has one native macOS
+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

package/docs/notify-queue.md

@@ -3,7 +3,9 @@
 `projmux` keeps a persistent JSON queue of pending AI notifications.
 `attention` is live tmux pane state; `notify` is the user's pending
 notification source of truth. The queue is derived from live state and user
-pushes, but an entry remains pending until explicit ack. Each entry can route
+pushes. Live entries remain pending until explicit ack unless they are among
+the oldest rows beyond the 256-entry hard cap; reconcile can also collect an
+expired entry after its tmux target disappears. Each entry can route
 the status-bar notify segment or notify sidebar to the originating tmux pane
 via `projmux focus`, and feeds the HUD pill rendered by
 `projmux status notify`.
@@ -23,7 +25,9 @@ queue.
 
 The queue file is a pretty-printed JSON array of `Notification`
 objects, sorted newest-first on read. `expires_at` is freshness metadata;
-expired entries are not filtered or deleted by `list`.
+expired entries are not filtered or deleted by `list`. Reconcile removes an
+expired row only when the real tmux inventory also shows its pane/session is
+gone; if inventory is unavailable, that target-based removal is skipped.
 
 Open native notify sidebars also create per-process Unix datagram sockets for
 queue-write refresh events. If the state-dir socket path would exceed Unix

package/docs/session-restore.md

@@ -86,13 +86,21 @@ keeps changing as auto-save runs. `Named snapshot` is a fixed, user-named
 snapshot and is not updated by auto-save. Rows include saved-at date/time
 metadata when available. `Back` returns to the project list without creating,
 replaying, or opening a session. After the startup mode is selected, project
-hook/config trust is evaluated if needed; approval continues the selected path
-and deny/cancel aborts before session create, snapshot replay, or startup
-command. The Alt-1 sidebar does not render trust approve/deny rows inline:
+automation trust is evaluated if needed. For a named snapshot with a startup
+`command`, projmux rejects symlink artifacts, reads the selected layout once,
+and authorizes the SHA-256 of the exact bytes used to parse the in-memory
+restore plan. The trust prompt names the layout file and shows terminal-safe
+command previews. Config absence and `PROJMUX_PROJECT_HOOKS=off` do not bypass
+this layout gate; commandless layouts keep their existing prompt-free restore
+behavior. Approval continues the selected path, while deny/cancel/error aborts
+before session or pane creation, snapshot replay, or `send-keys`. Project-owned
+layout names, descriptions, window names, agent topics, and command previews
+escape terminal control characters before rendering. The Alt-1 sidebar does
+not render trust approve/deny rows inline:
 before trust is requested, projmux snapshots the sidebar query/selection
 context and hands the selected open continuation to a detached tmux job. That
 job closes the sidebar popup state for the client and opens the shared `Trust
-project hooks` popup as a client-scoped decision surface, so no code relies on
+project automation` popup as a client-scoped decision surface, so no code relies on
 the self-closing sidebar popup process continuing after `display-popup -C`.
 Deny/cancel or trust-popup errors return to the sidebar near the same
 query/selection with a visible status message; only a missing/invalid context

package/docs/statusbar.md

@@ -181,6 +181,7 @@ placeholder surfaces and no-op until a handler is wired into the dispatcher.
 ```tmux
 bind-key s switch-client -T projmux-status
 bind-key -T projmux-status u run-shell '#{q:projmux} statusbar click usage'
+bind-key -T projmux-status r run-shell '#{q:projmux} statusbar usage-refresh'
 bind-key -T projmux-status n run-shell '#{q:projmux} statusbar click notify'
 bind-key -T projmux-status g run-shell '#{q:projmux} statusbar click git'
 bind-key -T projmux-status k run-shell '#{q:projmux} statusbar click kube'
@@ -190,6 +191,10 @@ bind-key -T projmux-status s run-shell '#{q:projmux} statusbar click session'
 
 The chord routes through the same dispatcher as the mouse click, so
 keyboard and mouse paths are functionally identical for keyed ranges.
+The `r` key is the one exception: it asks the usage manager for a throttled
+refresh and then reopens the same display-only usage popup from cache.
+Per-adapter throttle hints and backoff remain in force, so repeated refreshes
+inside the cooldown rerender cached data without another adapter collection.
 There is intentionally no `prefix s s` settings fallback because that chord
 already opens the session/sidebar range.
 

package/docs/theme-palette.md

@@ -159,6 +159,7 @@ Built-in preset config values are:
 - `high-contrast`
 - `blue-hour`
 - `carbon-violet`
+- `daylight`
 - `ember`
 - `forest`
 - `rose`
@@ -167,10 +168,42 @@ Built-in preset config values are:
   and a deep indigo active pane tint.
 - `carbon-violet` — charcoal/violet dark theme with darker popup/status
   surfaces and a black active pane tint.
+- `daylight` — the fully-light preset: warm paper pane/popup surfaces, an
+  explicit light status bar, dark slate text, a teal accent, a strong blue
+  focus border, and darkened saturated state colors (red/amber/blue/green/
+  orange) tuned to stay distinguishable on light chrome after 256-color
+  quantization. The active pane tint sits one tone darker than the pane body
+  (the inverse of the dark presets).
 - `high-contrast` — black surfaces, white text, a dark blue active surface,
   near-black active pane tint, vivid cyan focus, and bright
   cyan/yellow/red/green state colors.
 
+Preset colors paint projmux chrome only — the tmux status bar, picker/popup
+frames, pane borders, and the pane background tint. Pane contents (shell
+prompt, editor, command output) follow the terminal/shell theme, so a fully
+light experience with `daylight` also requires a light terminal theme.
+
+`daylight` palette values:
+
+| Token | Hex | Nearest tmux |
+| --- | --- | --- |
+| `background` | `#f2efe9` | `colour255` |
+| `surface` | `#faf7f1` | `colour255` |
+| `status_background` | `#dfdad0` | `colour188` |
+| `surface_active` | `#cfe0f0` | `colour189` |
+| `chrome_foreground` | `#3a4550` | `colour238` |
+| `text_primary` | `#2c3338` | `colour236` |
+| `foreground` | `#2c3338` | `colour236` |
+| `muted` | `#6b7680` | `colour243` |
+| `accent` | `#0f766e` | `colour6` |
+| `critical` | `#c62828` | `colour160` |
+| `warning` | `#b45309` | `colour130` |
+| `progress` | `#1d4ed8` | `colour26` |
+| `success` | `#15803d` | `colour29` |
+| `action_required` | `#d97706` | `colour172` |
+| `pane_active_bg` | `#e8e4dc` | `colour254` |
+| `focus` | `#2563eb` | `colour26` |
+
 ## Fallback Inventory
 
 Chrome and text:

package/docs/upgrading.md

@@ -88,7 +88,8 @@ should visibly sink. The active-pane border (`focus`) defaults to cyan
 `colour51`. Both apply only to tmux pane chrome.
 
 Built-in presets are intentionally small: `projmux`, `high-contrast`,
-`blue-hour`, `carbon-violet`, `ember`, `forest`, and `rose`. Terminal-default
+`blue-hour`, `carbon-violet`, `daylight`, `ember`, `forest`, and `rose`
+(`daylight` is the fully-light one). Terminal-default
 backgrounds are configured per token with the `default` sentinel rather than
 through separate terminal preset variants.
 

package/package.json

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