projmux 0.8.0 → 0.8.1

package/docs/agent-workflow.md

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

package/docs/keybindings.md

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

package/package.json

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