projmux 0.6.5 → 0.6.6

package/docs/agent-workflow.md

@@ -30,12 +30,15 @@
 - `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 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, first-run/version-bump shell welcome state and inline update handling, shell startup update prompt actions for fresh installer-aware cached updates, 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, and no-live-tmux save behavior, 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 resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session 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 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, 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, capture and typed fallback flows, unsafe raw capture, unsafe typed payload, disabled/default reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- `make test` also covers Settings > AI Settings > Enabled agents Phase 0 config behavior: missing config enables Claude and Codex, unknown saved provider names are ignored without disabling known providers, Settings toggles persist Claude/Codex 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 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, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border 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, 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, simplified action detail rows, Labs compatibility redirect to the Keybindings root, capture/add-alias 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 welcome revisit policy: shell welcome is suppressed only by `skip_version` matching the current version, legacy `last_welcomed_version` state does not count as skipped, `s` stores current-version welcome skip, Enter continues without storing skip, 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|shell|selective>` launches, 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, and invalid direct-agent usage errors.
-- `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, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
-- `make test` also covers AI desktop notification dedupe precedence (env override > Settings saved value > default), 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 direct `projmux ai split --agent <claude|codex|shell|selective>` 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, 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, and invalid direct-agent usage errors.
+- `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 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 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 Labs 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.
 - `make test` also covers `projmux shell` usage without startup selector flags, project-context default target lookup from `PROJMUX_CWD` or nearest project marker, explicit `--session` separation from project-derived defaults, and direct empty attach behavior without shell startup picker/replay.
@@ -43,13 +46,14 @@
 - `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 `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, 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 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.
-- `make test` also covers `projmux ai ingest claude-hook` core and extra Claude Code hook ingest for event parsing, transcript fallback, cataloged hook notification body formatting, permission summary formatting, UserPromptSubmit busy/no-queue behavior, Notification severity/text mapping, StopFailure/TeammateIdle text/severity/metadata mapping, SubagentStop quiet/no-notify diagnostics, unknown future-event quiet fallback, hook-active pane marking, topic preservation without hook candidate writes, mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at, and Claude transcript path preservation.
+- `make test` also covers `projmux ai ingest claude-hook` core and extra Claude Code hook ingest for event parsing, transcript fallback, cataloged hook notification body formatting, permission summary formatting, UserPromptSubmit busy/no-queue behavior, Notification severity/text mapping, pane-level semantic badge kind writes for permission, input, response complete, and in-progress states, StopFailure/TeammateIdle text/severity/metadata mapping, SubagentStop quiet/no-notify diagnostics, unknown future-event quiet fallback, hook-active pane marking, topic preservation without hook candidate writes, mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at, and Claude transcript path preservation.
 - `make test` also covers the Globalization Phase 0 English baseline for AI desktop notification summaries/bodies and hook-ingest queue text while preserving agent names, tool names, commands, paths, and provider payload values as literals/data.
 - `make test` also covers the Globalization Phase 1 message catalog foundation: locale resolver priority and normalization, `ko-KR` to `en-US` fallback, missing fallback-key errors, `en-US` completeness for foundation keys, and plain-text versus ANSI/tmux-styled fragment API separation.
 - `make test` also covers the Globalization Phase 2 formatter foundation: compact/full relative age and duration formatting, locale-specific just-now text, notification count plural/count preservation, list joins that preserve payload items, status token and target label localization, terminal cell-width measurement/truncation, and ANSI/tmux style wrappers treated as zero-width.
 - `make test` also covers the Globalization Phase 3 notify runtime migration: AI notify category rendering for `en-US`/`ko-KR`, Codex/Claude hook literal preservation for agent names, tool names, commands, paths, URLs, provider messages, subagent and teammate payloads, desktop notification and in-app queue display parity, notify sidebar/statusbar locale formatter output, and raw queue storage schema preservation.
+- `make test` also covers statusbar notify width fallbacks that preserve normal INFO/WARN/CRIT badges at readable widths, use dotless clipped text/count at very narrow widths, and keep hard truncation closed with `#[default]`.
 - `make test` also covers the Globalization Phase 4 Settings and popup guidance migration: `en-US`/`ko-KR` Settings root title/chips/rows/footer rendering, native picker search/empty/footer rendering without overflow, Settings row padding by terminal cell width, shell welcome guide catalog rendering, and long Korean ANSI/tmux-styled guide truncation safety while preserving key/command/path literals.
 - `make test` also covers the Globalization Phase 5 locale settings surface: `PROJMUX_LOCALE` > global `[ui].locale` > `LC_ALL` > `LC_MESSAGES` > `LANG` > `en-US` priority, Settings > Appearance > Language / Locale row/detail visibility, `auto` current-locale/source display, unsupported locale fallback warnings, global config writes, and preserved command/config/env/path literals.
 - `make test` also covers the Globalization Phase 6 governance guard: Go string-literal audit classification for hardcoded Korean candidates, English user-facing candidates, and ignored literal/data/debug examples; no unapproved runtime Korean literals outside catalog/formatter/test fixtures; `en-US` coverage for every embedded default catalog key; and required `ko-KR` coverage for migrated notify, Settings, picker, welcome, update, and help surfaces.
@@ -57,7 +61,7 @@
 - `make test` also covers `projmux ai ingest log` tail/path rendering and bounded JSONL log trimming for ingest diagnostics.
 - `make test` also covers welcome revisit policy: shell `skip_version` gating, `s` skip vs Enter one-run continue, Settings > About > Welcome native viewer, and attach-popup no-duplicate/no-op behavior.
 - `make test` also covers `projmux quit` action-picker rows, cancel/close no-op behavior, explicit quit of only app-owned mux runtimes marked by `@projmux_app=1` on the selected `tmux`/`psmux -L projmux` backend, missing/default runtime no-ops, dispatcher wiring, and `Settings > About > Quit projmux` routing through the same picker before any shutdown side effect.
-- `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, 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, Theme settings Phase 0/1 resolver behavior for project/global/fallback source labels, preset fill, explicit token override, invalid-layer warnings, and truecolor-to-tmux mapping, Phase 2 fallback render parity and project/global color isolation for native picker and tmux status/window background adapters, Phase 3 desired font config save/resolve plus unsupported `not applied` status without breaking no-adapter fallback rendering, and Phase 4 Settings theme editing boundaries for project/global resets, project inherit-vs-override labels, effective source labels, and project config theme values feeding the native project popup render path.
+- `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 background/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, Theme settings Phase 0/1 resolver behavior for project/global/fallback source labels, preset fill, explicit token override, invalid-layer warnings, and truecolor-to-tmux mapping, Phase 2 fallback render parity and project/global color isolation for native picker and tmux status/window background adapters, Phase 3 desired font config save/resolve plus unsupported `not applied` status without breaking no-adapter fallback rendering, and Phase 4 Settings theme editing boundaries for project/global resets, project inherit-vs-override labels, effective source labels, and project config theme values feeding the native project popup render path.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,
   reconcile reports stale rows), `notify list --live` queue/live explanations, notify sidebar
@@ -68,7 +72,7 @@
   state rendering after all visible non-critical rows are cleared, and `focus` dispatch diagnostics for session fallback, unresolved
   targets, window fallback, pane fallback, explicit id failures as unresolved exits, and
   notify-only fallback.
-- 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 keybinding diagnostic list/detail/probe outcome/init delegation coverage, environment override normalization, compact multi-line metadata gutters with one-column-indented metadata, proportional native scrollbar thumb rendering, 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, preview tab/control normalization before width clipping, optional native frame titlebars without same-line rule fill and with titlebar border reset guards, titled native Alt-1 sidebar chrome, statusbar-preserving sidebar popup height, native-only compact project sidebar popup sizing, and notify sidebar title/popup sizing.
+- 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 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, 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.
 - 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/ai-agent-shortcuts.md

@@ -6,7 +6,7 @@ the same split contract.
 
 ```sh
 projmux ai split --agent <agent> <right|down>
-projmux ai split --agent <agent> <right|down> -- <extra args...>
+projmux ai split --agent <agent> [--force-agent] <right|down> -- <extra args...>
 ```
 
 Use this page for shareable registration patterns. Keep machine-local policy,
@@ -41,6 +41,20 @@ your user-level config. Avoid treating placeholder flags in this guide as
 project defaults or current recommendations. If there are no private extra
 arguments, omit the separator entirely; do not leave a trailing bare `--`.
 
+Settings > AI Settings > Enabled agents is the source of truth for whether
+Claude and Codex may be launched. Disabled agents do not appear in the
+selective picker, and direct shortcut commands such as
+`projmux ai split --agent codex right` fail clearly instead of launching. This
+is intentional: shortcuts are thin direct CLI wrappers and must respect the
+same disabled state as hand-written commands.
+
+`--force-agent` is the only override, and it is explicit CLI policy for direct
+`--agent claude|codex` launches. Do not put it in shared picker, default-mode,
+or general shortcut registrations. Use it only in a private one-shot command
+when you deliberately want to launch a disabled agent without changing
+Settings. If every AI agent is disabled, `--agent selective` still offers a
+plain `shell` split and guidance to re-enable Claude/Codex.
+
 `shell` and `selective` are not targets for extra agent arguments. Use them
 without a tail:
 

package/docs/cli.md

@@ -25,7 +25,7 @@ projmux <command> [args...]
 | `current` | Resolve the active tmux pane path. |
 | `doctor` | Diagnose runtime dependencies. |
 | `focus` | Switch the active client to a session/window/pane target. |
-| `init` | Apply supported terminal keybinding fallbacks. |
+| `init` | Preview or apply supported terminal key delivery mappings. |
 | `kill` | Terminate tagged tmux sessions. |
 | `notify` | Manage the pending AI notify queue (push/list/ack/reconcile). |
 | `pin` | Manage pinned project directories. |
@@ -71,13 +71,15 @@ selection has been retired. The native picker is always used.
 projmux setup [--timeout DURATION] [--non-interactive]
 ```
 
-Probes the guaranteed launch defaults (`Alt-1..5`) plus advanced fallback and
-transport candidates such as `Ctrl-N`, `Ctrl-Shift-{R,L,M}`, `Ctrl-M`, and
-`Alt-Shift-{Left,Right}`. Reports `plain`, `csi-u`, `unknown`, or `timeout`
-for each. `--non-interactive` skips the TTY probe and prints the expected key
-map. Default `--timeout` is `5s`. Run it outside tmux after trying
-`projmux shell`; `Alt-1..5` are the only guaranteed zero-config defaults, while
-other probed keys are diagnostic or optional binding candidates.
+Probes the guaranteed launch defaults (`Alt-1..5`) plus transport candidates
+such as `Ctrl-N`, `Ctrl-Shift-{R,L,M}`, `Ctrl-M`, and
+`Alt-Shift-{Left,Right}`. Reports whether each key arrived as the expected
+plain bytes, an unsupported legacy/app-specific sequence, an unknown sequence,
+or a timeout. `--non-interactive` skips the TTY probe and prints the expected
+key map. Default `--timeout` is `5s`. Run it outside tmux after trying
+`projmux shell`; `Alt-1..5` are the only guaranteed zero-config defaults.
+Settings > Keybindings edits in-app action aliases; terminal delivery
+diagnostics stay in this CLI flow.
 
 ## init
 
@@ -86,9 +88,9 @@ projmux init [terminal] [--apply | --dry-run] [--config <path>]
              [--allow-symlink]
 ```
 
-Applies a terminal-specific fallback for shortcuts that `projmux setup`
-reports as swallowed. When `terminal` is omitted, autodetects from
-`$TERM_PROGRAM`/`$TERMINAL_EMULATOR`.
+Previews or applies terminal-specific key delivery mappings for supported
+terminals when `projmux setup` reports swallowed shortcuts. When `terminal` is
+omitted, autodetects from `$TERM_PROGRAM`/`$TERMINAL_EMULATOR`.
 Known terminals: `ghostty`, `windows-terminal`. Default is dry-run; pass
 `--apply` to write (timestamped `.bak.<timestamp>` is created). Refuses to
 write through a symlink unless `--allow-symlink` is passed (dotfiles repos).
@@ -319,7 +321,7 @@ supplied window.
 ## ai
 
 ```
-projmux ai split    [--agent <claude|codex|shell|selective>] [right|down] [-- <extra-arg>...]
+projmux ai split    [--agent <claude|codex|shell|selective>] [--force-agent] [right|down] [-- <extra-arg>...]
 projmux ai picker   --inside <right|down>
 projmux ai settings
 projmux ai status   set <thinking|waiting|idle> [--pane <id>]
@@ -340,6 +342,13 @@ the `attention` badge, the `notify` queue producer, and the desktop
 notifier. `status set waiting` is the trigger that flips a pane to the
 reply-ready state — that transition pushes an `ai:<session>:<pane>`
 entry into the notify queue.
+The durable semantic status badge is stored separately in
+`@projmux_ai_badge_kind` as `approval_required`, `input_required`,
+`response_complete`, `in_progress`, or unset. The live status surfaces color
+those values with action-required amber-orange, success green, and progress
+yellow respectively. That palette is independent from notify queue
+`--severity` and from OS desktop notification urgency; a critical approval row
+can still render a non-red action-required status badge.
 
 `ai split right|down` uses the configured default split mode. Add
 `--agent claude`, `--agent codex`, `--agent shell`, or `--agent selective` for
@@ -348,6 +357,15 @@ existing picker flow; `--agent shell` opens the existing plain shell split.
 Arguments after `--` are extra arguments appended to the resolved `claude` or
 `codex` executable inside the managed wrapper; projmux still sets the context
 directory, tmux title, AI pane metadata, title watcher, and split layout.
+Settings > AI Settings > Enabled agents controls Claude/Codex launch
+visibility. Disabled agents are hidden from the selective picker and from the
+default-mode picker. A saved default that later becomes disabled fails clearly
+instead of falling back to another agent. Direct `--agent claude|codex` launches
+also fail when disabled, including shortcuts that call the same command. For a
+deliberate one-shot direct CLI launch, pass `--force-agent`; picker and saved
+default paths do not use this override. If all AI agents are disabled, the
+selective picker still offers the plain `shell` split and shows guidance to
+re-enable Claude/Codex.
 For user-level skill, slash-command, editor, or launcher registrations that
 call this contract, see [AI Agent Shortcuts](ai-agent-shortcuts.md).
 
@@ -707,9 +725,11 @@ flags with the top-level `switch` UX:
 - `settings` — interactive configuration UI for the project picker, AI
   splits, Notifications, Appearance mode, Project Root management, the
   switcher's saved workdirs list, Labs (experimental), Settings > Keybindings,
-  and About/Update status. The keybinding flow now lives under
-  `Settings > Keybindings` with `Bindings`, `Diagnostic`, `Probe`, and `Init`
-  chips, and includes the `Welcome` entry in About. In Project
+  and About/Update status. The keybinding flow is a single
+  `Settings > Keybindings` action list with simplified action details for
+  aliases and reset. Terminal diagnostics and terminal mapping application stay
+  in the `projmux shell` -> `projmux setup` -> `projmux init` remediation path.
+  The About section includes the `Welcome` entry. In Project
   Picker, `Project Root` manages the saved
   primary root (`~/.config/projmux/projdir`) and displays whether the effective
   value comes from `PROJMUX_PROJDIR`, tmux `@projmux_projdir`, saved config, or
@@ -725,8 +745,9 @@ flags with the top-level `switch` UX:
   `projmux update apply`, and Welcome opens a Settings-native viewer
   independent of shell skip state. `Settings > About > Quit projmux` routes
   through the same `projmux quit` action picker. The same About section also
-  lists the keybinding diagnostic path: zero-config first, `setup` for swallowed keys,
-  `init` for supported terminal mappings, and `doctor` for dependencies.
+  lists the keybinding diagnostic path: try `projmux shell` first, use `setup`
+  for swallowed keys, use `init` for supported terminal mappings, and use
+  `doctor` for dependencies.
 
 ## See also
 

package/docs/configuration.md

@@ -87,16 +87,17 @@ language.
 ## Keymap File
 
 Settings > Keybindings is the normal in-app editor for action keys. It lists
-user-configurable direct bindings, opens a detail screen, and offers `Add
-alias`, `Replace primary`, `Disable default`, `Reset`, `Press new key`, and
-`Type key chord`. Saving writes safe tmux plain chords to
+actions with current keybinding summaries, opens a simple detail screen, and
+offers `Add alias` plus reset. Saving writes safe tmux plain chords to
 `~/.config/projmux/keymap.toml`, rewrites `~/.config/projmux/tmux.conf`, and,
 when Settings is running inside tmux, sources that app config so tmux-level
 chords take effect immediately.
 
 Raw sequences that cannot be safely represented as a tmux plain chord are not
-persisted. Use Settings to save a safe direct alias, or use `projmux init` for
-the supported terminal mappings.
+persisted. Use Settings to save a safe direct alias. When key delivery needs
+terminal-layer remediation, first try the key in `projmux shell`, then run
+`projmux setup` from the raw terminal, then use `projmux init` for supported
+terminal adapters.
 
 `~/.config/projmux/keymap.toml` can also be edited by hand. When the file is
 absent, generated tmux config stays on the built-in defaults.
@@ -126,21 +127,21 @@ do not break. Settings preserves existing prefix entries when rewriting the
 file, but does not create new prefix keys, and generated tmux config no longer
 binds the old action prefix chords.
 
-Use an empty `keys` list to disable direct plain aliases for the action:
+Use an empty `keys` list to disable direct plain aliases for the action when
+editing the file by hand:
 
 ```toml
 [bindings.ProjectSidebarToggle]
 keys = []
 ```
 
-In Settings, `Disable default` writes `keys = []`. `Reset` removes the saved
-override and returns to the built-in default. Legacy popup IDs such as
+In Settings, reset removes the saved override and returns to the built-in
+default. Legacy popup IDs such as
 `sessionizer-sidebar` still read, but new writes use canonical toggle names
 such as `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
 `AISplitPickerToggle`, `SettingsToggle`, and `ProjectSwitcherToggle`. Internal
 popup commands use `Surface:Action` IDs and have surface-local conflict
-domains; those are manual `keymap.toml` entries, not Settings list/edit
-targets.
+domains and remain visible in Settings when catalogued.
 
 The Settings writer is deterministic and rewrites the supported saved subset
 only. If the existing file has parse errors or unknown action IDs, Settings
@@ -149,7 +150,8 @@ shows the keymap error row and refuses to overwrite it until the file is fixed.
 The file currently affects generated tmux config from `projmux tmux
 print-config`, `projmux tmux install`, `projmux tmux print-app-config`,
 `projmux tmux install-app`, and `projmux shell`. Terminal init adapters such as
-Ghostty and Windows Terminal install built-in plain-byte mappings where needed.
+Ghostty and Windows Terminal install built-in plain-byte mappings where needed;
+they do not read `keymap.toml` or copy saved aliases into terminal configs.
 Changing terminal-layer mappings still requires rerunning `projmux init` and
 restarting the terminal where that terminal requires it.
 
@@ -176,9 +178,10 @@ field with source labels: `project`, `global`, or `fallback`.
 Renderer adapters can apply an already resolved `EffectiveTheme` to native
 picker frame background/foreground SGR and tmux status/window `colourN`
 background tokens. Settings and native project picker surfaces load global and
-project `[theme]` values through the shared effective-theme source. Fallback
-renderer output intentionally keeps the existing palette constants byte for
-byte.
+project `[theme]` values through the shared effective-theme source. Native
+picker frames also apply the built-in fallback `background`/`foreground` tokens
+so picker-owned padding, empty rows, footer rows, and preview gaps do not
+inherit the terminal default background.
 
 Resolver schema shape:
 
@@ -402,7 +405,7 @@ gated here.
 
 | Mode | On push | On click |
 | --- | --- | --- |
-| `none` | no toast | n/a |
+| `off` / `none` | no toast | n/a |
 | `notify` | toast / notify-send fires | no click action |
 | `raise` | toast / notify-send fires AND the host terminal is auto-raised via the osfocus chain | toast click invokes `projmux focus --uri` via the `projmux://` handler |
 
@@ -414,26 +417,32 @@ up with an on-push auto-raise.
 
 Resolution order (highest priority first):
 
-1. `PROJMUX_DESKTOP_NOTIFY_MODE` env (`none` / `notify` / `raise`).
+1. `PROJMUX_DESKTOP_NOTIFY_MODE` env (`off` / `none` / `notify` / `raise`).
 2. `PROJMUX_DESKTOP_NOTIFY` env (legacy `on` / `off`; `on` → `notify`,
    `off` → `none`).
-3. Tmux global option `@projmux_desktop_notify_mode`.
-4. Tmux global option `@projmux_desktop_notify` (legacy `1` / `0`, same
+3. Saved Settings config
+   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/desktop-notify-mode`
+   (`off` / `notify` / `raise`).
+4. Tmux global option `@projmux_desktop_notify_mode`.
+5. Tmux global option `@projmux_desktop_notify` (legacy `1` / `0`, same
    mapping as the env above).
-5. Default = `raise` when running inside WSL with `$WT_SESSION` set
+6. Default = `raise` when running inside WSL with `$WT_SESSION` set
    (Windows Terminal × WSL is the measured-working cell for osfocus
    raise today); otherwise `notify`.
 
 Migration is intentionally read-time. Users with the previous legacy
 toggle set keep their behavior — `@projmux_desktop_notify=0` resolves to
 `none`, `@projmux_desktop_notify=1` resolves to `notify`. The first
-Settings press through the new row writes the new key and the legacy key
-goes unused. No eager rewrite of tmux state.
+Settings press through the new row writes `desktop-notify-mode`, mirrors the
+new value into `@projmux_desktop_notify_mode` when tmux is live, and leaves the
+legacy key unused. No eager rewrite of tmux state.
 
 Toggle from Settings > Notifications > `Desktop notifications`. The
 Settings info row labels the effective source as `env`, `env (legacy)`,
 `setting`, `setting (legacy)`, or `default` so users see which rung of
-the cascade pinned the value.
+the cascade pinned the value. `projmux tmux apply` regenerates the live tmux
+option from the saved Settings file; when that file is missing, apply writes
+only the default for the current host.
 
 Hook details for new-session lifecycle hooks and project-local
 `.projmux/config.toml` live in [Hooks](hooks.md).

package/docs/hooks.md

@@ -206,7 +206,11 @@ desktop sender and receives positional arguments
 `summary body urgency app-name tag group icon-path`. That `urgency` value is
 the OS notification urgency, not the notify-queue severity. AI approval,
 input, selection, and confirmation rows can stay critical in the queue and UI
-while the desktop notification hook receives `normal`.
+while the desktop notification hook receives `normal`. Live AI status badges
+are a third surface: permission/input-required panes use the action-required
+amber-orange status role, response-complete panes use success green, and
+in-progress panes use progress yellow. They do not inherit the critical queue
+severity, and permission/input status badges do not use red.
 
 ## Codex Hooks Engine
 

package/docs/keybindings.md

@@ -12,8 +12,7 @@ supported fallback guidance.
 The recommended path when a key does not fire:
 
 1. Try the key inside `projmux shell`.
-2. Open Settings > Keybindings > Diagnostic, or run `projmux setup` outside
-   tmux, to see which bytes reach the process.
+2. Run `projmux setup` outside tmux to see which bytes reach the process.
 3. For supported terminals, preview `projmux init [terminal]`; add `--apply`
    only after reviewing the merge.
 4. For unsupported terminals, configure plain Meta bytes or add a tmux alias in
@@ -47,6 +46,12 @@ keymap actions, pane switching, window switching, and rename actions remain
 visible. Transport-dependent rows show the default transport key separately
 from editable plain aliases.
 
+The Settings flow is intentionally simple: the root is one action list with
+current key summaries, and each action detail shows the action, current
+keybinding/aliases, `Add alias`, and reset. Diagnostic/probe/init workflows are
+not first-class Settings tabs; use `projmux setup` and `projmux init` from the
+terminal when key delivery needs remediation.
+
 Optional direct aliases can be added for actions such as:
 
 | Canonical action | Meaning |
@@ -67,19 +72,20 @@ without storing or replacing the transport default. Rename actions no longer
 have a built-in terminal fallback; use tmux's prefix rename flow or configure
 an explicit safe alias where the action is editable.
 
-## Roadmap Requirements
+## Product Requirements
 
-Follow-up Phase 2 keeps Settings > Keybindings as a discovery surface. It must
-continue to expose launch toggles, sidebar keymap actions, picker-local actions,
-pane switching, window switching, and rename actions. Transport-dependent rows
-should explain the default transport key and offer only additive safe plain
-aliases; diagnostic-only rows should explain why they are not editable.
+Settings > Keybindings stays a discovery surface. It must continue to expose
+launch toggles, sidebar keymap actions, picker-local actions, pane switching,
+window switching, and rename actions. The primary Settings flow is not the
+terminal remediation surface: replace-primary, disable-default, typed fallback,
+terminal mapping preview/apply, and init execution rows stay out of the action
+detail.
 
-Follow-up Phase 3 removes the `UserN` / `CSI-u` route from the product model.
-Windows Terminal and Ghostty-centered replacements should use plain
-Meta/control chords or xterm modifier sequences where possible. If a key cannot
-be represented that way, leave it as a non-editable unsupported or diagnostic
-row instead of preserving a User-key or CSI-u fallback.
+The product model does not support `UserN` or `CSI-u` as fallback guidance.
+Windows Terminal and Ghostty adapters use built-in plain Meta/control bytes or
+xterm modifier sequences where possible. If a key cannot be represented that
+way, leave it as a non-editable unsupported or diagnostic row instead of
+preserving a User-key or CSI-u fallback.
 
 ## Picker Actions
 
@@ -131,8 +137,8 @@ names: `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
 ## Diagnose: `projmux setup`
 
 Run `projmux setup` outside tmux to find out which projmux keys reach the raw
-terminal. The same diagnostic is available in-app at Settings > Keybindings >
-Diagnostic.
+terminal. Settings > Keybindings remains the action/alias editor; setup is the
+terminal delivery diagnostic.
 
 | Status | Meaning |
 | --- | --- |

package/docs/native-picker-parity.md

@@ -46,8 +46,9 @@ native picker engine and is not a public dependency-policy change.
 | fzf navigation keys | interactive selection in searchable lists | Covered | native maps modified-key `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
 | alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
 | frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
+| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective background/foreground SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
 | tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
-| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border with neutral titlebar background, rule fill, and a divider above search/content, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
+| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame background/foreground instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
 | redraw flicker/top clipping | keyboard navigation in exact-height tmux popup | Partially covered | native redraws use synchronized updates plus coalesced row diffs after the first frame, skip unchanged frames, render frame diffs before sidebar focus commands, frame rendering avoids trailing bottom-border CRLF, and screen exit clears the alternate buffer before restore; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; `TestFrameUpdateRendererSkipsUnchangedFrame`; `TestFrameUpdateRendererCoalescesEachFrameUpdate`; `TestRendererRenderFrameUsesCRLFRowsForRawTTY`; `TestNativeInteractiveUsesAlternateScreen` |
 
 ## Native Surface Architecture
@@ -72,9 +73,11 @@ native picker engine and is not a public dependency-policy change.
 ## Frame Chrome ANSI
 
 Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
-Titlebars restore the titlebar style after embedded ANSI resets, search prompt
-and footer separators fill the available frame width, and header, row, footer,
-and preview lines close any active SGR style before padding or frame borders can
+Titlebar text, title dividers, and chip-strip gaps inherit the frame
+background/foreground instead of applying a second titlebar overlay ANSI layer;
+chip bodies can still carry active/inactive/disabled tones. Search prompt and
+footer separators fill the available frame width, and header, row, footer, and
+preview lines close any active SGR style before padding or frame borders can
 inherit it. This phase does not add popup modes or change the `popup-toggle`
 contract; native popups still rely on the existing borderless tmux popup path.
 

package/docs/npm-distribution.md

@@ -31,13 +31,15 @@ make npm-pack
 or:
 
 ```bash
-scripts/package-npm.sh --version 0.4.0 --out /tmp/projmux-npm --pack
+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, then runs `npm pack --dry-run`
-when `--pack` is set.
+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.
 
 ## Publish Order
 

package/docs/settings-ia.md

@@ -15,13 +15,21 @@ view-first layout:
   actions live inside that view.
 - `Settings > Project Picker > Project Root` shows effective and saved values
   first, then the edit actions, then the explanatory hints.
-- `Settings > Keybindings` is the single entry point for keybinding work. The
-  page is split into four chips: `Bindings`, `Diagnostic`, `Probe`, and `Init`.
-- `Settings > Keybindings > Bindings` is a keybinding discovery surface, not
-  only a launch-toggle editor. It must show `Toggle Project Sidebar` with the
+- `Settings > Keybindings` is a single action list plus a simple action detail.
+  It does not expose `Bindings`, `Diagnostic`, `Probe`, or `Init` as first-class
+  chips/tabs in the Settings root flow.
+- `Settings > Keybindings` is a keybinding discovery surface, not only a
+  launch-toggle editor. It must show `Toggle Project Sidebar` with the
   guaranteed `Alt-1` / `M-1` default, plus sidebar-local commands, picker-local
   commands, `Pane navigation`, `Window navigation`, and `Rename` groups or
   equivalent searchable rows.
+- `Settings > Keybindings > Action` keeps the user-facing edit path small:
+  action, current keybinding/aliases, `Add alias`, and reset. It does not offer
+  replace-primary, disable-default, typed-fallback, terminal mapping preview, or
+  terminal mapping apply rows.
+- Terminal delivery remediation lives outside Settings primary flow. The
+  supported order is `projmux shell` first, then `projmux setup`, then
+  `projmux init` for supported terminal adapters.
 - Rows that cannot safely be edited still stay visible. Mark diagnostic-only
   rows with the delivery path and reason instead of hiding them or turning them
   into unsupported editable aliases. Transport-dependent rows stay visible with
@@ -55,8 +63,8 @@ view-first layout:
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
   edit catalog `install` values or run agent install/remove commands.
 - `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
-  visible Labs row. The hidden compatibility action still redirects to the
-  unified Keybindings page.
+  visible Labs row. The hidden compatibility action redirects to the
+  `Settings > Keybindings` action list, not to a diagnostic default.
 - `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

@@ -33,6 +33,25 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   clicks on tmux 3.4+, so a `run-shell` handler can't recover the
   target after the fact — the Go dispatcher's
   `isWindowListRangeToken` fallback is now defense-in-depth only.
+  Each window tab reserves a one-cell live pane attention prefix from
+  `projmux attention window #{window_id}` before the index. AI panes use the
+  semantic `@projmux_ai_badge_kind` first: approval/input-required panes use
+  the action-required amber-orange role, response-complete panes use the
+  non-critical success green role, and in-progress panes use the progress
+  yellow role. Red/critical is reserved for error, failure, and risk chrome;
+  permission or input-required status badges do not use it.
+  Legacy busy/reply title and attention-state markers remain the fallback, and
+  no-state windows render a blank placeholder so title alignment and click range
+  width stay stable. This live window-list badge is independent from the row-0
+  notify queue segment and from notify queue severity or desktop notification
+  urgency. For example, an approval request may remain a critical queued
+  notification while its live status badge renders action-required amber-orange.
+  Window-list badges and app pane-border badges use the same semantic priority,
+  with display style controlled by Settings > Appearance > AI badge style and persisted in
+  `~/.config/projmux/ai-badge-style`. The default is `dot`; `emoji` renders
+  `⏳` for approval/input-required, `✅` for response-complete, and `🔄` for
+  in-progress. `off` (also accepted as `minimal` when read from disk) preserves
+  the same spacing without drawing a marker.
   The session, pwd, kube, and git segments on this row are wrapped
   in `#[range=user|<id>]` ranges and dispatched through the projmux
   handler. The standalone config also wraps the right-side `projmux`
@@ -95,9 +114,10 @@ When the notify block is wider than its cell budget, clipping shrinks the body
 text first and appends an ellipsis while preserving project, state, agent, age,
 and count metadata. If the segment is still too wide, the age is dropped next
 while badges and the `+N` count stay visible when possible. Very narrow widths
-fall back to the severity-colored dot plus clipped text and count; the final
+fall back to dotless clipped text plus the `+N` count when it fits; the final
 hard-truncate path still closes with `#[default]` so later status segments do
-not inherit notification styling.
+not inherit notification styling. That dotless narrow fallback applies only to
+the queued notify segment, not to the separate window-list live attention badge.
 `usage` opens a native-framed detail HUD for the compact usage bar. It reads
 the cached usage state in-process, keeps the existing `projmux usage` CLI
 output shape unchanged for external consumers, aligns model/window rows with

package/docs/testing.md

@@ -54,3 +54,125 @@ desktop shell, or OS integration:
 
 Keep those checks as manual or host-run smoke validation until a dedicated
 host harness exists.
+
+Use this smoke checklist when a change touches terminal delivery, host desktop
+notifications, or reviewer confidence around those boundaries. If the change
+does not touch those areas, copy the PR-note block below and mark the relevant
+rows `not run`.
+
+### Terminal Key Delivery
+
+Run the raw key probe outside tmux, in the terminal emulator being claimed:
+
+```sh
+projmux setup --timeout 10s
+```
+
+Observe:
+
+- `Alt-1` through `Alt-5` report `OK plain`. These are the guaranteed
+  zero-config launch defaults.
+- If a guaranteed key reports `MISS timeout`, preview a supported terminal
+  mapping with `projmux init ghostty` or `projmux init windows-terminal`,
+  apply it with the same command plus `--apply`, restart that terminal if
+  required, and rerun `projmux setup --timeout 10s`.
+- Optional direct aliases and transport-dependent chords may be reported by
+  the probe, but they are not part of the guaranteed host smoke unless the PR
+  explicitly changes them.
+
+Then run the app in the same terminal:
+
+```sh
+projmux shell
+```
+
+Observe:
+
+- `Alt-1` opens the project sidebar.
+- `Alt-2` opens the notification sidebar.
+- `Alt-3` opens the existing-session picker.
+- `Alt-4` opens the AI split picker.
+- `Alt-5` opens Settings.
+- Pressing the same launch key again closes the popup instead of typing escape
+  bytes into the shell or picker input.
+
+### WSL Toast
+
+Run this from WSL with Windows Terminal available. The detached tmux server is
+intentional: `projmux focus` falls back to the product desktop notification
+path when there is no attached client to switch.
+
+```sh
+sock="${TMPDIR:-/tmp}/projmux-host-smoke.sock"
+tmux -S "$sock" kill-server 2>/dev/null || true
+tmux -S "$sock" new-session -d -s projmux-host-smoke 'sleep 600'
+PROJMUX_DESKTOP_NOTIFY_MODE=notify \
+  projmux focus --socket "$sock" --target projmux-host-smoke --json
+tmux -S "$sock" kill-server
+```
+
+Observe:
+
+- The JSON includes `"ok":true`, `"dispatch":"notify-only"`, and
+  `"reason":"no-attached-client"`.
+- Windows shows a short projmux toast with `session ready:
+  projmux-host-smoke`.
+- No visible PowerShell or console window remains open after the toast.
+
+If the PR changes click-to-focus behavior, repeat with
+`PROJMUX_DESKTOP_NOTIFY_MODE=raise`, click the toast, and record whether the
+host terminal returns to the target. Otherwise leave click callbacks marked as
+manual/not run.
+
+### macOS GUI Notification
+
+The built-in desktop sender is Linux/WSL-oriented. On macOS, smoke the
+documented `PROJMUX_NOTIFY_HOOK` escape hatch with an `osascript` sender:
+
+```sh
+hook="${TMPDIR:-/tmp}/projmux-macos-notify.sh"
+cat >"$hook" <<'SH'
+#!/bin/sh
+title=${1:-projmux}
+body=${2:-}
+osascript \
+  -e 'on run argv' \
+  -e 'display notification (item 2 of argv) with title (item 1 of argv)' \
+  -e 'end run' \
+  "$title" "$body"
+SH
+chmod 0755 "$hook"
+
+sock="${TMPDIR:-/tmp}/projmux-host-smoke.sock"
+tmux -S "$sock" kill-server 2>/dev/null || true
+tmux -S "$sock" new-session -d -s projmux-host-smoke 'sleep 600'
+PROJMUX_NOTIFY_HOOK="$hook" \
+  projmux focus --socket "$sock" --target projmux-host-smoke --json
+tmux -S "$sock" kill-server
+```
+
+Observe:
+
+- The JSON includes `"ok":true`, `"dispatch":"notify-only"`, and
+  `"reason":"no-attached-client"`.
+- macOS shows a Notification Center banner with `session ready:
+  projmux-host-smoke`.
+- If macOS prompts for notification permission, record that state in the PR
+  instead of treating the product command as verified.
+
+### PR Note Template
+
+```markdown
+Host-only smoke validation:
+
+- Docker-covered checks: `make test-integration`, `make test-install-smoke`,
+  and `make test-e2e` cover portable Linux tmux/config/notify behavior only.
+- Terminal key delivery: not run / run on <terminal>; `projmux setup --timeout
+  10s` showed <result>; `Alt-1..5` app popup smoke <passed/failed/not run>.
+- WSL toast: not run / run on <Windows + WSL distro>; detached-focus smoke
+  produced `dispatch=notify-only`; observed <toast/no toast/notes>.
+- macOS GUI notification: not run / run on <macOS version>; hook smoke
+  produced `dispatch=notify-only`; observed <banner/permission prompt/notes>.
+- Desktop notification click callbacks: not run unless this PR changes
+  click-to-focus behavior; result <notes>.
+```

package/docs/theme-palette.md

@@ -41,6 +41,14 @@ onto these stable names:
 | `critical` | destructive/error/critical state | settings remove/quit, notify critical badge, statusbar critical usage |
 | `warning` | progress, pending, warning, busy state | AI busy/thinking indicators, notify pending title, usage warning |
 
+AI semantic status badges use renderer-only state roles layered on top of that
+inventory: `progress`, `success`, and `action_required`. The fallback contract
+is progress yellow, success green, action-required amber-orange. These roles are
+separate from notify queue severity and desktop notification urgency; an AI
+approval row can be `critical` in the notify queue while the live status badge
+uses `action_required`, not red. `critical` remains reserved for error, failure,
+destructive, over-limit, or risk states.
+
 Renderer-only role names such as `accent.ai`, `state.progress`, `git.branch`,
 and trust colors remain in `internal/theme/palette.go` until Phase 2+ maps each
 surface to the resolver tokens. The key product contract for this phase is that
@@ -127,10 +135,11 @@ Accents and state:
 | `accent.action` | `141;205;142`, strong `122;199;173` | `colour29` bg / `colour230` fg |
 | `accent.attention` | notify HUD background/project family | `colour53`, project `colour90` |
 | `accent.ai` | notify agent `colour37` family | `colour37` bg / `colour121` fg |
-| `state.progress` | `255;204;102`; switch attention/busy dot and pending notify title/bell/badge `colour220` | `colour220` |
-| `state.warning` | usage/status popup ANSI 256 wrapper | `colour214` |
+| `state.progress` | `255;204;102`; switch attention/busy dot, pane-border in-progress badge, and pending notify title/bell/badge `colour220` | `colour220` |
+| `state.action_required` | AI approval/input-required status badge amber-orange; currently aliases the established warning token | `colour214` |
+| `state.warning` | usage/status popup warning ANSI 256 wrapper; non-AI warning chrome | `colour214` |
 | `state.danger` | `255;107;107` | `colour160` |
-| `state.success` | settings/trust green families | `colour72`, `colour151` |
+| `state.success` | settings/trust green families; pane-border response-complete badge | `colour72`, `colour151` |
 | `state.ahead` | switch/git metadata and notify age ANSI 256 wrapper | `colour153` |
 | `git.branch` | switch/sidebar branch badge uses the statusbar git branch block colors | `colour30` bg / `colour231` fg |
 
@@ -140,6 +149,7 @@ Surface-specific tokens:
 | --- | --- |
 | Native picker | current row, titlebar, rule, pointer, highlight, muted text, chip active/inactive/disabled |
 | Statusbar row 1 | session identity, cwd secondary text, divider, git branch block, git dirty/staged/ahead/behind, settings action chip, clock |
+| App pane borders | semantic AI badge marker style (`dot`, `emoji`, or spacing-preserving `off`) plus action-required/success/progress state color |
 | Notify HUD/sidebar | line bg/fg, project badge, info/warn/crit/stale/gone badges, AI agent badge, count/age text |
 | Usage HUD/popup | OK/warning/critical/over-limit bars and numbers, empty cells, muted sync age |
 | Settings | add/type/open action, destructive remove/quit, back/cancel, info/read-only, dim description, root action/dim rows, trust trusted/stale/untrusted |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -23,14 +23,14 @@
     "README-ko.md",
     "LICENSE"
   ],
-  "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.6.5",
-    "@projmux/darwin-x64": "0.6.5",
-    "@projmux/linux-arm64": "0.6.5",
-    "@projmux/linux-x64": "0.6.5"
-  },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",
     "package:npm:pack": "scripts/package-npm.sh --pack"
+  },
+  "optionalDependencies": {
+    "@projmux/linux-x64": "0.6.6",
+    "@projmux/linux-arm64": "0.6.6",
+    "@projmux/darwin-x64": "0.6.6",
+    "@projmux/darwin-arm64": "0.6.6"
   }
 }