projmux 0.5.1 → 0.5.3

package/docs/cli.md

@@ -116,8 +116,10 @@ does not diagnose terminal key delivery; use `projmux setup` for that.
 
 ```
 projmux focus --target SESSION[:WINDOW[.PANE]] [--socket <path>]
-              [--source ai|status-bar|external|os-notification]
-              [--kind reply-ready|busy-cleared|segment-click|custom]
+              [--source ai|status-bar|external|os-notification|toast]
+              [--kind reply-ready|busy-cleared|segment-click|toast-click|custom]
+              [--json]
+projmux focus --uri "projmux://focus?pane_id=%N&socket=<path>&source=toast"
               [--json]
 ```
 
@@ -128,6 +130,13 @@ client is attached on that socket, it emits the configured desktop
 notification instead. `--socket` is explicit; when omitted, the socket is
 derived from `$TMUX`.
 
+`--uri` is the entry point used by the WSL Toast click handler (see
+[configuration.md](configuration.md#toast-click-handler-wsl--windows-terminal)).
+The pane id from the URI is resolved to a `SESSION:WINDOW.%paneID` target
+via `tmux display-message`, and the URI's `socket` overrides any
+`--socket` flag so the click round-trips back to the right tmux server.
+`--uri` and `--target` are mutually exclusive.
+
 Exit codes:
 
 - `0` — focused (or the notify-only fallback fired).

package/docs/configuration.md

@@ -108,6 +108,8 @@ configured key opens and closes the popup.
 | `PROJMUX_MANAGED_ROOTS` | Search-root override. Uses the OS-native path-list separator and takes priority over the saved workdirs file and default weak probes. |
 | `TMUX_SESSIONIZER_ROOTS` | Legacy alias still honored at runtime for managed roots. |
 | `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in Linux/WSL sender. |
+| `PROJMUX_DESKTOP_NOTIFY_MODE` | OS desktop notification mode override. `none` / `notify` / `raise` (case insensitive). When set, this takes priority over every other resolution rung. The in-app notify queue is not affected. |
+| `PROJMUX_DESKTOP_NOTIFY` | Legacy on/off override kept for backward compatibility. `on` maps to `notify`, `off` maps to `none`. Honored only when `PROJMUX_DESKTOP_NOTIFY_MODE` is unset. |
 | `PROJMUX_WSL_TOAST_ICON_DIR` | Directory used when copying the WSL toast icon into a Windows-readable path. |
 | `PROJMUX_USAGE_STATE_DIR` | Override directory for AI usage snapshots. Defaults to `<state>/projmux/usage`. Point this at a synced directory to share authoritative usage across machines. |
 | `PROJMUX_USAGE_DEBUG` | When non-empty, prints adapter errors from `projmux status usage` to stderr. |
@@ -149,9 +151,119 @@ When the hook is set, projmux invokes it with positional arguments:
 summary body urgency app-name tag group icon-path
 ```
 
+The app-name argument is `com.crevisse.projmux` (reverse-domain id used as
+the Linux `--app-name`, the macOS sender label, and the Windows
+`AppUserModelID`). Earlier releases used `projmux.TmuxCodex`; the new id
+ships with a one-shot Windows cleanup that removes the legacy Start Menu
+shortcut and registry entry the first time projmux runs.
+
+### Desktop notification mode
+
+The OS-level dispatch carries three modes. The in-app notify queue, the
+statusbar segment, and the attention badge stay live regardless of which
+mode is active — only the toast / notify-send / auto-raise fan-out is
+gated here.
+
+| Mode | On push | On click |
+| --- | --- | --- |
+| `none` | no toast | n/a |
+| `notify` | toast / notify-send fires | toast click invokes `projmux focus --uri` via the `projmux://` handler |
+| `raise` | toast / notify-send fires AND the host terminal is auto-raised via the osfocus chain | same as `notify` — click is always available |
+
+Click activation is always wired. The `projmux://` URI handler is
+registered on the first Notify of each tmux server (gated by the
+`@projmux_uri_protocol_registered_v2` marker) regardless of mode. The
+mode only controls whether a toast fires at all and whether to follow it
+up with an on-push auto-raise.
+
+Resolution order (highest priority first):
+
+1. `PROJMUX_DESKTOP_NOTIFY_MODE` env (`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
+   mapping as the env above).
+5. 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.
+
+Toggle from Settings > AI Settings > `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.
+
 Hook details for new-session lifecycle hooks and project-local
 `.projmux/config.toml` live in [Hooks](hooks.md).
 
+### Toast click handler (WSL + Windows Terminal)
+
+On WSL, projmux registers a `projmux://` URL scheme on the Windows side
+the first time a Toast is dispatched on each tmux server. Clicking the
+toast hands control back to projmux inside WSL via the registered command:
+
+```text
+wsl.exe -d $WSL_DISTRO_NAME --exec <absolute-path-to-projmux> focus --uri "%1"
+```
+
+For click activation to work in our unpackaged Win32 setup, four
+conditions must hold simultaneously — all of them are arranged by the
+notify path so users do not configure anything:
+
+1. No COM Toast Activator is registered. The shortcut writes only
+   `PKEY_AppUserModel_ID` (pid=5) and intentionally omits
+   `PKEY_AppUserModel_ToastActivatorCLSID` (pid=26). When a COM activator
+   is registered alongside the AppID, Windows tries COM first, silently
+   fails for unpackaged exes, and does *not* fall through to the launch
+   URI. Stripping the COM side makes Windows ShellExecute the launch URI
+   on click.
+2. The Start Menu shortcut exists with the AppID set. The shortcut is
+   never launched — it is a property bag so the toast can route under
+   the right DisplayName + icon.
+3. The shortcut target is `cmd.exe /c exit`. Earlier code used
+   `powershell.exe -WindowStyle Hidden -Command exit`; Windows Defender
+   silently quarantines such shortcuts moments after creation, which
+   leaves no AppID-tagged shortcut and breaks both the routing and the
+   click path. `cmd.exe /c exit` is treated as benign and survives.
+4. The WSL handler command uses `--exec`, not `--`. `wsl.exe -- <cmd>`
+   routes its tail through the user's login shell, which parses `&`
+   query-string separators as background-job operators (zsh emits
+   `parse error near '&'`). `--exec` skips the shell and invokes the
+   binary directly. The absolute WSL filesystem path to the binary is
+   captured at registration so PATH does not need to be populated under
+   `--exec`.
+
+The URI carries the originating pane id and tmux socket so the click
+round-trips back to the exact pane that fired the notification, which
+the `projmux focus` path then redirects via `tmux switch-client`.
+
+Registration markers and the writes involved:
+
+- Registry keys (HKCU): `SOFTWARE\Classes\projmux\(Default)`,
+  `SOFTWARE\Classes\projmux\URL Protocol`, and
+  `SOFTWARE\Classes\projmux\shell\open\command\(Default)`.
+- tmux user-option marker `@projmux_uri_protocol_registered_v2` records that
+  registration has been attempted on this server so the script runs at most
+  once per server boot. (The v1 marker `@projmux_uri_protocol_registered`
+  was bumped when the registry command switched to `--exec`; existing v1
+  users re-register transparently on the next Notify after upgrade and the
+  orphaned v1 key requires no cleanup.)
+
+Limitations:
+
+- The handler captures the user's current `WSL_DISTRO_NAME` at registration
+  time. Users running multiple WSL distros get one handler bound to the
+  first distro that fired a toast — clicks from a different distro's toast
+  will route back through the first distro. Tier-2 follow-up.
+- WSL2 cold-start latency: the first click after a long idle goes through
+  WSL boot and typically takes 2-3s to surface the focus on the pane.
+
 ## Usage Tracking
 
 `projmux usage` and the status-bar usage segment store snapshots under:

package/docs/notify-os-focus-poc.md

@@ -0,0 +1,318 @@
+# Notify OS Focus Spike
+
+This document is the on-floor matrix for the "Notify 시 터미널 OS 포커스"
+roadmap item. The first step of that roadmap is explicitly a **spike with no
+code** — fill in the tables below with real measurements, then make the
+follow-on decisions before any adapter code lands.
+
+The full design lives in the project notes (`로드맵 디테일 - Notify 시 터미널 OS
+포커스`). This file is the in-tree, fill-in-the-blanks transcription so the
+spike trail lives next to the code it informs.
+
+## Background and scope
+
+`projmux focus` (see [`internal/app/focus.go`](../internal/app/focus.go))
+currently handles tmux pane focus only. Once a tmux client is already attached
+and on screen, it can resolve a target session/window/pane, redirect an
+existing client if one is attached, or emit a desktop notification as a last
+resort. The notify path that produces the entries this focuses on lives in
+[`internal/app/notify.go`](../internal/app/notify.go),
+[`internal/app/notify_producer.go`](../internal/app/notify_producer.go), and
+[`internal/app/notify_reconcile.go`](../internal/app/notify_reconcile.go).
+
+The realistic stack for "go to the pane that fired this notification" has four
+layers:
+
+1. **tmux pane** — already solved by `projmux focus`.
+2. **tmux session / client switch** — partially solved
+   (`tmux switch-client -c <tty>`).
+3. **Terminal app window / tab** — terminal-specific IPC, requires an adapter
+   per terminal.
+4. **OS-level window focus** — raise the app itself to foreground; platform
+   policy varies and the result is best-effort.
+
+Layers 3 and 4 are the unresolved area and the scope of this spike.
+
+## Trigger mode question
+
+Two entry points are possible:
+
+- **(a) on-push (automatic)**: `projmux notify push` fires OS-level focus
+  immediately when the notification is enqueued.
+- **(b) on-click / keypress (user-initiated)**: extend the existing
+  `projmux focus` path so a statusbar / sidebar click goes
+  tmux pane focus → terminal tab focus → OS window focus.
+
+**Recommendation: (b) is primary, (a) is opt-in only.**
+
+- (a) steals the screen while the user is doing something else and is hostile
+  UX by default.
+- (b) only runs at the moment the user explicitly says "I want this now," so a
+  larger focus action is acceptable.
+- A system notification daemon (libnotify, macOS UserNotificationCenter,
+  Windows Toast) is the (a) substitute: the OS shows the notification, the
+  user clicks it, and that click drops into the (b) path.
+
+Lock the decision once the matrix below is filled in:
+
+- [x] Primary trigger mode confirmed as (b).
+- [x] (a) shipped as opt-in only, or deferred entirely. — **deferred**.
+- [x] System notification daemon path adopted in place of (a), or deferred. —
+  **deferred**; the WSL toast path already in place covers the (a) substitute
+  role for tier-1.
+
+## Terminal × OS matrix
+
+Fill the **Result** column with one of `OK`, `Partial`, `No`, plus a one-line
+note. Tick **Tested?** once measured. Candidate commands are pre-filled from
+the roadmap and are starting points, not prescriptions — note in **Result** if
+a different command worked better.
+
+| Terminal | OS | Candidate command(s) for window/tab focus | Result | Tested? |
+|---|---|---|---|---|
+| Ghostty | macOS | `osascript -e 'tell application "Ghostty" to activate'` + window-id match | | [ ] |
+| Ghostty | Linux X11 | `wmctrl -ia <wid>` | | [ ] |
+| Ghostty | Linux Wayland | Compositor-specific: gnome `dbus` (`org.gnome.Shell.Eval`), KDE `kdotool`, sway `swaymsg` | | [ ] |
+| Kitty | Any | `kitty @ focus-window --match <expr>` | | [ ] |
+| WezTerm | Any | `wezterm cli activate-pane --pane-id <id>` | | [ ] |
+| Windows Terminal | Windows | `wt -w <id> focus-tab -t <n>` (same instance only) | | [ ] |
+| Windows Terminal | WSL → Windows | WSL interop + `wt.exe -w <id> focus-tab` | OK — `wt.exe -w 0 focus-tab -t 0` raises the WT window (verified WSL2 Ubuntu-24.04, WT host) | [x] |
+| iTerm2 | macOS | AppleScript (`tell application "iTerm" ...`) or Python API | | [ ] |
+| Alacritty | Any | No remote IPC. OS-window focus only — fall back to the table below. | | [ ] |
+| Foot | Linux | `footclient` is limited. OS-window focus only — fall back to the table below. | | [ ] |
+| VS Code embedded | Any | Best-effort via `vscode://` URL handler or `code --command` | | [ ] |
+
+## OS-level window activation matrix
+
+Independent of the terminal: "raise this app to the foreground." Fill the
+**Result** column the same way.
+
+| OS | Candidate command(s) | Notes | Result | Tested? |
+|---|---|---|---|---|
+| macOS | `osascript -e 'tell application "<AppName>" to activate'` | Stable; no special permission. | | [ ] |
+| Linux X11 | `wmctrl -a <window-name>` or `xdotool windowactivate <wid>` | Requires `wmctrl` / `xdotool` installed; standard. | | [ ] |
+| Linux Wayland (GNOME) | `gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell --method org.gnome.Shell.Eval ...` | Depends on shell version; recent GNOME locks `Eval` outside dev mode. | | [ ] |
+| Linux Wayland (KDE) | `kdotool windowactivate <wid>` | KWin script bridge; requires `kdotool`. | | [ ] |
+| Linux Wayland (sway) | `swaymsg '[con_id=<id>] focus'` | Works for sway / wlroots compositors. | | [ ] |
+| Windows | `SetForegroundWindow` via PowerShell + P/Invoke | Foreground-lock policy: if the target hasn't recently been active, the OS will only flash the taskbar entry. | | [ ] |
+| WSL → Windows | Same as Windows, invoked through `powershell.exe` interop | Inherits Windows foreground-lock. | Partial — raw `SetForegroundWindow` returns `False` under foreground-lock; the `AttachThreadInput` + `BringWindowToTop` + `SetForegroundWindow` workaround does bypass the lock (verified WSL2 Ubuntu-24.04, WT host). Caveat: pairing it with `ShowWindow(SW_RESTORE)` unconditionally restores **maximized** windows to normal size — adapter must `IsIconic`-guard `ShowWindow` so only minimized windows are restored. | [x] |
+
+## Detection signals
+
+Each terminal adapter has to detect that it's the right one to run before
+touching IPC. These are the env vars / files we can rely on. The precedent for
+this style of detection is
+[`internal/app/init_ghostty.go`](../internal/app/init_ghostty.go) and
+[`internal/app/init_windows_terminal.go`](../internal/app/init_windows_terminal.go) —
+the new `osfocus` adapters should reuse the same detect-then-dispatch pattern.
+
+| Terminal | Signal(s) |
+|---|---|
+| iTerm2 | `TERM_PROGRAM=iTerm.app` (plus `ITERM_SESSION_ID`) |
+| Apple Terminal | `TERM_PROGRAM=Apple_Terminal` |
+| VS Code (embedded) | `TERM_PROGRAM=vscode` (plus `VSCODE_INJECTION`, `VSCODE_PID`) |
+| Windows Terminal | `WT_SESSION`, `WT_PROFILE_ID` |
+| Ghostty | `GHOSTTY_RESOURCES_DIR`, `GHOSTTY_BIN_DIR` |
+| Kitty | `KITTY_PID`, `KITTY_LISTEN_ON`, `KITTY_WINDOW_ID` |
+| WezTerm | `WEZTERM_PANE`, `WEZTERM_EXECUTABLE`, `WEZTERM_UNIX_SOCKET` |
+| Alacritty | `ALACRITTY_LOG`, `ALACRITTY_WINDOW_ID`, `ALACRITTY_SOCKET` |
+| Foot | `FOOT_SOCK_*`, `FOOTCLIENT` (varies by build) |
+
+Notes for adapter authors (from Test 1, WSL2 Ubuntu-24.04 inside Windows
+Terminal):
+
+- Inside tmux, `TERM_PROGRAM` is rewritten to `tmux` and masks the host
+  terminal. Detect Windows Terminal via `WT_SESSION` / `WT_PROFILE_ID`
+  (forwarded into WSL via `WSLENV`), not `TERM_PROGRAM`.
+- `WAYLAND_DISPLAY=wayland-0` is present in WSL2 via WSLg. Do **not** treat it
+  as a "running on native Wayland" signal — gate Wayland adapters on a real
+  Wayland session (e.g. absence of `WSL_INTEROP`).
+- `WSL_INTEROP` + `WSL_DISTRO_NAME` reliably identify WSL2; use them to gate
+  the WSL → Windows adapter branch.
+
+Notes from Test 2 (WSL → Windows OS-level activation):
+
+- Raw `SetForegroundWindow` is unreliable under Windows foreground-lock; it
+  returns `False` whenever the calling process isn't already foreground (the
+  common case for a background-triggered focus).
+- The `AttachThreadInput(fgThread, thisThread, true)` + `BringWindowToTop` +
+  `SetForegroundWindow` + detach combo bypasses the lock and does raise the
+  target window in this configuration.
+- `ShowWindow(handle, SW_RESTORE)` un-maximizes maximized windows as a side
+  effect. The adapter must `IsIconic`-guard the call so it only restores
+  minimized windows; do not call `ShowWindow` unconditionally.
+- For Windows Terminal specifically, prefer the Test 1 path
+  (`wt.exe -w 0 focus-tab`) — it raises WT without any of the above
+  ceremony and has no side effect on window state. The `SetForegroundWindow`
+  combo is the fallback for non-WT Windows apps.
+
+Notes from Test 3 (`wt.exe -w 0` bare, no subcommand):
+
+- Raises the WT window OK and preserves maximization, **but adds a new tab
+  as a side effect** (the bare invocation defaults to "new tab in window
+  0"). Unsuitable as a raise-only call.
+- Always pair `wt.exe -w 0` with a no-op subcommand such as `focus-tab -t 0`
+  (Test 1) to raise without creating a tab. Treat the bare form as
+  reserved for the "open new tab" case only.
+
+If multiple signals are present (e.g. tmux inside VS Code's embedded
+terminal), the adapter chain picks the innermost match the IPC can actually
+talk to and falls through to the next on detect failure.
+
+## Decisions to lock after measurement
+
+- [x] Tier-1 support matrix — which terminal × OS cells ship in the first
+  adapter PR. → **Windows Terminal × WSL → Windows only** (the single
+  combination measured this session). Other matrix rows stay pending tier-2
+  measurements.
+- [x] Trigger mode — confirm (a), (b), or both (b primary + (a) opt-in). →
+  **(b) on-click/keypress is primary; (a) on-push is deferred** (the WSL
+  toast already serves as the (a) substitute).
+- [x] System notification daemon integration — in scope for tier-1, or
+  deferred to a follow-on PR. → **shipped (Windows scope only)**. The WSL
+  toast now carries a `projmux://focus?pane_id=…&socket=…&source=toast`
+  launch URI; a one-shot HKCU registration on first dispatch wires
+  `wsl.exe -d <distro> -- projmux focus --uri "%1"` so the click
+  round-trips back into the (b) focus path. Tier-2 covers
+  non-WSL/non-Windows daemons (libnotify, UNUserNotificationCenter) and
+  the multi-distro handler.
+- [x] Adapter module path — proposed `internal/integrations/osfocus/`. Confirm
+  or pick alternative. → confirmed `internal/integrations/osfocus/`.
+- [x] Adapter call style — synchronous from `projmux focus`, or background
+  (`tmux run-shell -b`-style) so the click → toast path stays responsive. →
+  **background goroutine, non-blocking** inside the adapter; the chain
+  itself returns immediately to the caller.
+- [x] Failure policy — silent fallback (keep entry in queue, no error
+  surfaced) confirmed as the default. → confirmed; the chain returns nil
+  even when an adapter's Focus errors.
+
+Locked 2026-05-11.
+
+### Tier-1 status
+
+Tier-1 adapter shipped: `internal/integrations/osfocus/` with
+`WindowsTerminalWSLAdapter`. Other matrix rows remain pending tier-2
+measurements.
+
+### Tier-1.5 shipped — Toast click handler (WSL + Windows Terminal)
+
+The toast notification produced by `aiDesktopNotifier.Notify` on WSL
+carries a `launch="projmux://focus?..." activationType="protocol"`
+attribute, and the first dispatch of a tmux server boot registers the
+`projmux://` scheme in `HKCU\SOFTWARE\Classes\projmux\…` so Windows
+routes the click to
+`wsl.exe -d <distro> --exec <abs-path> focus --uri "%1"`. Inside WSL,
+`projmux focus --uri` parses the URI, resolves the pane id to its
+`session:window.%paneID` target via `tmux display-message`, and reuses
+the existing focus dispatch. This closes the previously-deferred (a)
+on-push trigger mode in the Windows-only scope: the toast becomes the
+(a) surface and its click drops into the (b) `projmux focus` path.
+
+Trigger mode is a 3-way selector now (Settings > AI Settings > Desktop
+notifications, tmux option `@projmux_desktop_notify_mode`):
+
+| Mode | On push | On click |
+|---|---|---|
+| `none` | no toast | n/a |
+| `notify` | show toast | toast click → `projmux focus` via URI handler |
+| `raise` | show toast + raise host terminal via osfocus chain | toast click → `projmux focus` via URI handler |
+
+Click handling is always wired regardless of mode — the URI handler
+registration is gated on its own one-shot marker, not on the mode.
+
+#### Retrospective — what the working configuration is
+
+An earlier Tier-1.5 spike explored a COM Toast Activator path (PR-H
+tree: the `feat/toast-com-activator` branch and tooling under
+`tools/win-toast-activator`). That path is **abandoned**: an unpackaged
+Win32 binary running under WSL cannot reliably take a
+`INotificationActivationCallback` dispatch even with a fully-wired
+registry chain. The configuration that works in live testing on this
+machine is:
+
+1. **No COM activator** at all. The shortcut writes only
+   `PKEY_AppUserModel_ID` (pid=5) and intentionally omits
+   `PKEY_AppUserModel_ToastActivatorCLSID` (pid=26). When a COM activator
+   is registered, Windows tries COM first and silently fails — it does
+   not fall through to the launch URI. Stripping the COM side makes
+   Windows ShellExecute the URI on click.
+2. **AppID-tagged shortcut present** (`projmux.lnk` in the Start Menu's
+   Programs folder, target `cmd.exe /c exit`). The toast platform
+   requires an AppID-tagged shortcut to be discoverable for the toast to
+   route under the right DisplayName + icon. The target is never
+   launched — it is a property bag.
+3. **Shortcut target = `cmd.exe /c exit`**. Earlier code used
+   `powershell.exe -WindowStyle Hidden -Command exit`. Windows Defender
+   silently quarantines such shortcuts within seconds of creation, which
+   leaves no AppID-tagged shortcut at all and breaks both the toast
+   routing and (since the AppID has to be live when the toast fires) the
+   click path. `cmd.exe /c exit` is benign and survives.
+4. **WSL handler command uses `--exec` not `--`**. `wsl.exe -- <cmd>`
+   routes its tail through the user's default login shell, which parses
+   `&` query-string separators as background-job operators (zsh emits
+   `parse error near '&'`). `--exec` skips the shell and invokes the
+   binary directly. PATH is empty under `--exec`, so the registry
+   command uses the absolute WSL filesystem path captured at registration
+   time.
+
+#### Lessons (so future readers don't repeat them)
+
+- Do not "fix" the shortcut target back to `powershell.exe -WindowStyle
+  Hidden -Command exit`. It triggers Defender quarantine and breaks
+  every routing path that depends on the AppID shortcut existing.
+- Do not add `PKEY_AppUserModel_ToastActivatorCLSID` (pid=26) thinking
+  it would "unlock click activation". For unpackaged binaries it does
+  the opposite — Windows routes through the COM path, the COM call
+  silently fails, and the launch URI is never invoked.
+- Do not use `wsl.exe -- projmux ...` in the registry handler.
+  Re-introducing the login-shell hop will surface as `parse error near
+  '&'` from the user's shell at click time.
+- The `@projmux_uri_protocol_registered_v2` marker exists because the
+  v1 marker came before the `--exec` fix. Re-registration is idempotent
+  so upgrades from v1 transparently install the new handler — the old
+  marker key just goes orphaned.
+
+Multi-distro dispatch (one handler per distro, or a distro-selector
+arg) is a known tier-2 follow-up — current registration captures the
+first distro to fire a toast and pins the handler to it. See
+docs/configuration.md → "Toast click handler" for the limitation
+summary.
+
+## Out of scope
+
+- Guaranteeing identical behavior across every environment. Cells the matrix
+  marks `No` stay fallback-only (notification stays in the queue); we do not
+  try to force-support them.
+- Shipping on-push automatic focus (a) as the default. If (a) ships at all it
+  is opt-in.
+- Bypassing OS foreground-lock policy (Windows in particular). The adapter
+  does what the OS allows and no more.
+
+## Risks and cost
+
+- Adapter calls spawn external processes, which adds latency on the focus
+  path. Tier-1 adapters should be invoked asynchronously (background) so the
+  visible click → focus response stays snappy.
+- `wmctrl`, `xdotool`, `wt.exe`, `osascript`, `kdotool`, etc. are not all
+  installed by default on user systems. Adapter `Detect()` must verify the
+  binary is on `PATH` before claiming the slot.
+- System notification daemon integration drags in OS permission flows (macOS
+  notification permission, Windows Toast registration, libnotify
+  availability). Estimate that cost in the spike before committing.
+
+## Source links
+
+- [`internal/app/focus.go`](../internal/app/focus.go) — current tmux pane
+  focus dispatcher; the planned hook point for the adapter chain.
+- [`internal/app/notify.go`](../internal/app/notify.go) — notify queue API.
+- [`internal/app/notify_producer.go`](../internal/app/notify_producer.go) —
+  pushes notifications from the attention state machine.
+- [`internal/app/notify_reconcile.go`](../internal/app/notify_reconcile.go) —
+  back-fills the queue from live tmux state.
+- [`internal/app/init_ghostty.go`](../internal/app/init_ghostty.go),
+  [`internal/app/init_windows_terminal.go`](../internal/app/init_windows_terminal.go) —
+  precedent for terminal detection and per-terminal adapter dispatch.
+- [`internal/integrations/tmux/`](../internal/integrations/tmux/) — external
+  process helpers; pattern to reuse for the new adapters.
+- Planned: `internal/integrations/osfocus/` — new home for the OS / terminal
+  focus adapters once the matrix above is filled in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -24,10 +24,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.5.1",
-    "@projmux/darwin-x64": "0.5.1",
-    "@projmux/linux-arm64": "0.5.1",
-    "@projmux/linux-x64": "0.5.1"
+    "@projmux/darwin-arm64": "0.5.3",
+    "@projmux/darwin-x64": "0.5.3",
+    "@projmux/linux-arm64": "0.5.3",
+    "@projmux/linux-x64": "0.5.3"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",