Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
fix(keybinds): record macOS modifiers even when the WebView swallows keyup
rubenluetke10-beep9fa22047eee4
diff --git a/docs/os-parity.md b/docs/os-parity.mdindex e28eecde75..2ab299904f 100644--- a/docs/os-parity.md+++ b/docs/os-parity.md@@ -289,6 +289,7 @@ experiences today.| P-22 | Low | Coding-CLI panes | Kimi Code uses the bundled Git Bash as its shell environment on Windows, so without Git for Windows installed the binary answers `--version` correctly and the agent then cannot run a single shell command | Kimi vendor docs; `jarvis/workspace/agents.py` (the `kimi` entry) | Windows without Git for Windows: the pane opens, the CLI reports a healthy version, and shell commands fail inside it. macOS/Linux unaffected. `KIMI_SHELL_PATH` points at a non-standard `bash.exe`. An install check that only runs `--version` cannot see this || P-23 | Info | Coding-CLI panes | Kimi Code's alternate screen cannot be disabled (an open upstream request notes it is the outlier versus Claude Code, Codex and the Gemini CLI), so it may conflict with the pane's own scrollback the way a Claude Code pane once did | Upstream issue; `jarvis/agentic_ide/screen.py` | All OSes equally — not an OS gap, recorded here because it is the same class of pane defect and is expected to need the same kind of fix || P-27 | Low | Mouse-button shortcuts | A shortcut may now be a MOUSE BUTTON (middle, and the two side buttons — `mouse_middle` / `mouse_x1` / `mouse_x2`). All three OSes are implemented in the same change and share one token vocabulary, but the delivery is not uniform: Windows needs nothing extra (the backend polls `GetAsyncKeyState`, which reports mouse buttons); macOS needs pyobjc `Quartz` plus the Accessibility + Input Monitoring grants the hotkey tap already requires; Linux/X11 needs `pynput`, which is the opt-in `[desktop-linux]` extra for the reason recorded in P-24 (`evdev` is source-only). Wayland cannot do it at all — no global button grab exists, the same design reason keyboard shortcuts degrade there. The left and right buttons are deliberately not bindable on any OS: their meaning follows the system "swap mouse buttons" setting, so a shortcut recorded as "left" would fire on the physical right button for a left-handed user | `jarvis/trigger/hotkey.py::mouse_hotkeys_available`, `backends/global_hotkeys.py::_MOUSE_TOKEN_TO_VK`, `backends/pynput.py::_start_mouse_listener`, `backends/quartz.py::_MOUSE_BUTTON_TO_TOKEN` | Every host answers the capability question BEFORE offering the control: `mouse_hotkeys_available()` returns an English sentence naming what is missing and what still works, and a backend that cannot start its mouse hook logs the same thing and keeps the KEYBOARD shortcuts alive rather than failing the whole binding. macOS/Linux desktop with the extras: full parity with Windows. Wayland and headless: key combinations only |+| P-43 | Low | Keybind recorder modifiers | The settings recorder used to trust only DOM keydown/keyup. On macOS WKWebView a lone Option/Command/Control can arrive as `flagsChanged` (not a DOM event) or as a keydown whose keyup never comes, so the recorder previewed the key and then hung (GitHub #98). The recorder now (a) syncs the modifier flag word from every keyboard and mouse event, and (b) while capturing, polls `GET /api/settings/keybinds/held`, which is a capability probe (`modifier_snapshot`): Windows `GetAsyncKeyState` for Shift/Ctrl/Alt/Win; macOS `CGEventSourceFlagsState` (no event tap and no Accessibility grant); Linux/X11 falls back to the running pynput held-set when the listener is up; Wayland/headless/missing extras answer `available: false` and the on-screen picker still works. A lagging first poll that says "nothing held" does not commit a chord the user just pressed — the snapshot may only DROP a modifier it has already seen down | `jarvis/trigger/hotkey.py::modifier_snapshot`, `jarvis/ui/web/settings_routes.py::get_keybind_held`, `jarvis/ui/web/frontend/src/views/settings/KeybindRow.tsx` | Windows: live modifier snapshot, no extra packages. macOS with pyobjc Quartz: live snapshot even when the hotkey tap is not running. macOS without Quartz / Wayland / headless: honest `available: false`, click-to-assign and letter+modifier chords still record. Linux/X11 with pynput running: snapshot from the listener held-set. Fn is still not a portable key (the OS often swallows it) and is not offered || P-28 | Low | Local realtime | The one-click managed install AND the 2026-08-08 supervisor (prewarm, pidfile ownership, start/stop routes, Ollama keep-alive warm ping) are built cross-platform — pathlib, `os.name` venv layout with a POSIX `lib/python*/site-packages` glob, per-hardware torch flavor, `start_new_session` + `killpg` SIGTERM→SIGKILL escalation on POSIX, `HF_HUB_DISABLE_SYMLINKS` Windows-only — but have only been RUN on the Windows dev box. The preflight narrows the SHARED accelerator probe to the two sources this stack can drive -- NVIDIA VRAM (nvidia-smi) and Apple-Silicon unified memory (total RAM), which the derived launch command maps to `cuda`/`mps`. The shared probe itself also reads AMD and Intel cards now (BUG-206), for the local-model fit verdicts; the preflight deliberately drops those to `(0.0, "none")` via `_DRIVEABLE_SOURCES`, because clearing the memory floor and then launching with a torch device the box does not have is worse than the refusal. An AMD/Intel/no-nvidia-smi host therefore still gets the honest "no supported accelerator" blocker (unit-tested) | `jarvis/realtime/local_server/{preflight,install,supervisor}.py` | Any host under 12 GB usable accelerator memory (including every GPU-less/headless box) gets the honest blocker with a cloud pointer instead of an install — verified by unit tests. macOS Apple-Silicon: preflight and install should work but the smoke boot (`--qwen3_tts_device mps`) is UNVERIFIED on real hardware; a failure is honest (install ends in an error state naming the smoke log, readiness stays fail-closed). Linux+NVIDIA: expected to work via the same cu130 wheel index, unverified; the supervisor's POSIX kill/spawn branches are unit-tested but not live-run. The bring-your-own-server URL socket keeps full parity everywhere || P-30 | Medium | Local STT on the GPU | The on-device CTranslate2 recognizer (faster-whisper) needs the cuBLAS 12 / cuDNN 9 runtime wheels, which the `[full]` profile deliberately does not carry. Without them the engine self-heals onto the CPU and, until 2026-08-22, nothing but a log line said so (36 silent fallbacks in one live log; the cloud fallback then ran at ~1× realtime). The wheels are now the opt-in `[cuda]` extra, the provider card reports the accelerator truth (`accelerator_status`: requested device, effective device, reason code) and offers the install from inside the app (`POST /api/local-gpu/libraries`), and the library probe is a pure on-disk look — the out-of-process inference probe (AP-25) remains the only verdict on whether the GPU WORKS | `jarvis/plugins/stt/fwhisper.py::cuda_runtime_libraries_present`, `GPU_LIBRARY_PACKAGES`, `jarvis/speech/local_models.py::accelerator_status`, `jarvis/speech/local_install.py::start_gpu_libraries_install` | Windows: verified live on the dev box (install → `ctranslate2.get_cuda_device_count() == 1`, base/cuda decode). Linux: the same wheels land in `nvidia/cublas/lib`; the probe also accepts a system-wide CUDA via `ctypes.util.find_library("cublas")` — expected to work, UNVERIFIED on real hardware. macOS: no CUDA exists; the card says `unsupported_os` and the recognizer runs on the CPU with no install offered. Headless/GPU-less Linux: libraries absent → honest `cuda_libraries_missing` when the config asks for `cuda`, silent when it asks for `cpu` |@@ -335,6 +336,7 @@ shortcuts it never created. Covered by| # | Impact | Area | Gap | Evidence | Behavior off-Windows ||---|---|---|---|---|---|| P-38 | Medium | Native installer / desktop window | The Linux AppImage and `.deb` have **no native desktop window**. Windows (WebView2) and macOS (WKWebView) get one from the frozen bundle; Linux does not, because pywebview's GTK backend needs PyGObject and a frozen interpreter can never import the distribution's `python3-gi` (it is compiled against the system CPython), while bundling GTK 3 + WebKit2GTK portably means shipping its helper processes, GIO modules, pixbuf loaders, GSettings schemas and typelibs. The Qt route is also closed today: the `[desktop]` extra installs `pyside6-essentials`, which has no QtWebEngine, and `jarvis.spec` excludes PySide6 outright. Adding `pyside6-addons` and dropping that exclusion is the realistic fix, at roughly +400 MB | `packaging/linux/README.md` ("The window question"), `jarvis/ui/desktop_app.py::_degrade_to_browser_ui`, `jarvis.spec` `excludes`, `pyproject.toml` `[desktop]` | Linux: honest degradation, verified against a real build — the app catches pywebview's `WebViewException`, keeps the backend serving, and `AppRun` waits for `/api/health` and opens the interface with `xdg-open`. Everything except the window frame works, including the whole CLI. A source/pipx install on a Linux desktop with `python3-gi` + `gir1.2-webkit2-4.1` still gets the native window; only the frozen build does not. Sub-gap: the app's fallback message advises installing those system packages, which does not help a frozen build |+| P-39 | Medium | Dictation hold-key watchdog | A HOLD-started dictation is owed a release edge, and that edge can be lost between the OS hotkey listener and the pipeline (a checker restart mid-hold, a re-arm, a handler that raised). The recording then ran to its 30-minute cap with the bar's X dead and every key press refused (BUG-191). The repair asks the keyboard instead of trusting edges: `HotkeyBackend.chord_is_down(combo)` is a three-way capability — `True`/`False` when the backend can see the keyboard, `None` when it cannot — and the recording finishes itself once the chord has read "up" for one second. The three OS backends can see different amounts: Windows reads `GetAsyncKeyState` (ground truth, the poller's own source); macOS answers from the event tap's held-set, whose modifier half is re-synced from every event's flags word; Linux/X11 answers from pynput's held-set, which is edge-fed like the matcher itself | `jarvis/trigger/backends/__init__.py::HotkeyBackend.chord_is_down`, `backends/global_hotkeys.py::chord_is_down`, `backends/quartz.py::chord_is_down`, `backends/pynput.py::chord_is_down`, `backends/noop.py`, `jarvis/speech/pipeline.py::_watch_dictation_hold_key`, `tests/contract/test_hotkey_backend_protocol.py` | Windows: the watchdog sees the physical key and ends a lost-release recording within ~1 s. macOS / Linux-X11: the watchdog runs on the listener's own bookkeeping — it catches a release the pipeline missed, not one the listener itself missed. Wayland / no listener: the backend answers `None`, the watchdog stands down, and the other stop gestures carry alone — the key (a press during a running dictation is its stop), the bar's X, the Dictation view, `jarvis api dictation stop`. On no host does `None` ever read as "up": a phantom release is the one failure this must never produce || P-40 | Low | JarvisBar | The Prompt Mode switch (`[dictation].prompt_mode`, every dictation comes out as a written prompt) is a control on the native bar since 2026-08-28: a sparkle in the resting pill's left slot, drawn ONLY while the SETTING is on (visible without a hover — the pill opens as it does for mute). A click PAUSES the rewriting rather than changing the setting: the mark goes red with a slash through it, jarvis.toml is untouched, and the same click brings it back. The pause is runtime-only and clears on restart or on any write of the setting. With the setting off nothing is drawn there and the spot starts a session as before. The glyph mirrors the mic's inset rather than the close-X's, which is left untouched on a live bar. The switch has ONE writer (`jarvis/dictation/prompt_mode_switch.py`) and one broadcast (`DictationPromptModeChanged`) that the bar, the front-page pill and the settings card all redraw from | `jarvis/ui/jarvisbar/renderer.py::_draw_sparkle`, `interaction.py::resolve_click` (`prompt_mode_toggle`), `overlay.py` / `qt_overlay.py` / `subprocess_overlay.py` (`set_prompt_mode`, `set_on_prompt_mode_toggle`), `host.py` (op `set_prompt_mode`, event `prompt_mode_toggle`), `ui/orb/bus_bridge.py` | Windows/Linux (Tk bar, in-process) and macOS (Qt bar in the companion host, over the existing IPC protocol): the same sparkle, the same click, the same event. Headless / `orb_style = none`: the NullOverlay accepts both methods as no-ops; the pill on the front page and the settings card remain the switch. Guards: `tests/unit/ui/jarvisbar/test_prompt_mode_button.py`, `test_prompt_mode_bridge.py`, `test_surface_contract.py`, `test_host_protocol.py` || P-41 | Medium | Dictation final pass | The dictation lane reads its final pass on the machine, in front of any configured cloud provider, through the same out-of-process worker the live preview uses (`jarvis.dictation.preview_worker`) with a stronger checkpoint (`[dictation].local_model`, default `large-v3-turbo`, `int8_float16`, beam 5). 2026-09-02 forensics: 220 of 220 dictations had run on a cloud recognizer the settings did not name, because the VOICE lane had been moved there to keep CUDA out of the desktop process, and the dictation lane inherited the move — round-trips as lag, near-empty answers on 25 s windows as "truncated window" repairs. The provider declines itself with a CROSSABLE failure (HTTP-503-shaped, `LocalEngineUnavailable`) so the configured provider is one step behind on every press and never a restart away: too little free accelerator memory (`[dictation].local_min_free_gb`, default 1.5; an UNKNOWN reading never blocks), a worker that only comes up on the CPU, a missing local runtime, a worker that died. A call abandoned at its ceiling leaves its answer in the pipe, so the next call kills that worker instead of reading it (AP-24) | `jarvis/dictation/local_final.py::LocalFinalSTT`, `jarvis/speech/pipeline.py::_dictation_local_final`, `_dictation_stt`, `jarvis/dictation/local_preview.py::_spawn_worker_model` (`compute`), `preview_worker.py` (`beam_size`, `segments`), `jarvis/hardware/detection.py::free_accelerator_gb` | Windows/Linux with an NVIDIA card and the local runtime: the final pass runs locally when ≥ 1.5 GB is free, else the cloud chain. macOS: no NVIDIA reading → the memory gate passes as unknown, and the worker's own device ladder decides; a CPU-only worker is declined for the final pass (a beam decode of a 25 s window on a CPU is slower than the cloud it would replace), so Apple Silicon stays on the configured provider until a Metal-backed runtime exists. Headless `python:3.11-slim` (no `faster-whisper`): the provider is never built and the chain is exactly what it was. Switch: `[dictation].local_engine = false`. Guards: `tests/unit/dictation/test_local_final.py`, `test_preview_worker.py` |diff --git a/jarvis/trigger/backends/global_hotkeys.py b/jarvis/trigger/backends/global_hotkeys.pyindex e802361158..b4ff274cb7 100644--- a/jarvis/trigger/backends/global_hotkeys.py+++ b/jarvis/trigger/backends/global_hotkeys.py@@ -533,6 +533,10 @@ class GlobalHotkeysBackend:return Falsereturn True+ def held_tokens(self) -> frozenset[str] | None:+ """Windows has no edge-fed held-set; the recorder reads GetAsyncKeyState instead."""+ return None+# Virtual-key codes for the two Win keys (``VK_LWIN`` / ``VK_RWIN``), spelled# out so the probe below needs no ``win32con`` import to name them.diff --git a/jarvis/trigger/backends/noop.py b/jarvis/trigger/backends/noop.pyindex d3007d0ed4..1589d6f706 100644--- a/jarvis/trigger/backends/noop.py+++ b/jarvis/trigger/backends/noop.py@@ -132,5 +132,9 @@ class NoopBackend:"""No listener, no keyboard state to report — honestly unknown."""return None+ def held_tokens(self) -> frozenset[str] | None:+ """No listener, no held-set — honestly unknown."""+ return None+__all__ = ["NoopBackend", "_reset_noop_log_flag_for_tests", "explain_unavailable"]diff --git a/jarvis/trigger/backends/pynput.py b/jarvis/trigger/backends/pynput.pyindex ca33eba2df..a5378268c6 100644--- a/jarvis/trigger/backends/pynput.py+++ b/jarvis/trigger/backends/pynput.py@@ -217,6 +217,12 @@ class PynputBackend:return Nonereturn _combo_is_down(tokens, self._held)+ def held_tokens(self) -> frozenset[str] | None:+ """Copy of the listener's held-set. ``None`` while it is not running."""+ if not self._started or self._listener is None:+ return None+ return frozenset(self._held)+def _token_for(self, key) -> str | None:"""Map a pynput key event to our canonical token, or ``None``."""# ``KeyCode`` for character keys exposes ``.char``; ``Key`` enum membersdiff --git a/jarvis/trigger/backends/quartz.py b/jarvis/trigger/backends/quartz.pyindex ce728b02ca..37b3e0f953 100644--- a/jarvis/trigger/backends/quartz.py+++ b/jarvis/trigger/backends/quartz.py@@ -204,6 +204,12 @@ class QuartzHotkeyBackend:return Nonereturn tokens.issubset(self._held)+ def held_tokens(self) -> frozenset[str] | None:+ """Copy of the tap's held-set. ``None`` while the tap is not running."""+ if not self._started or self._tap is None:+ return None+ return frozenset(self._held)+def _permitted(self) -> bool:"""The grant verdict, re-probed at most every ``_PERMISSION_TTL_S``.diff --git a/jarvis/trigger/hotkey.py b/jarvis/trigger/hotkey.pyindex 0c7343d3e8..4c7ec97014 100644--- a/jarvis/trigger/hotkey.py+++ b/jarvis/trigger/hotkey.py@@ -43,6 +43,7 @@ permanently now live inside ``GlobalHotkeysBackend`` (relocated verbatim):``validate_hotkey`` and ``_normalize_combo`` stay importable from this modulefor backwards compatibility (the wizard / settings UI import them here)."""+from __future__ import annotationsimport asyncio@@ -105,7 +106,7 @@ SELF_INPUT_SUPPRESSED_EVENTS: frozenset[str] = frozenset({"ptt_press","dictate_press",- "dictate", # legacy [dictation].mode = "toggle"+ "dictate", # legacy [dictation].mode = "toggle""dictate_toggle","paste_last",}@@ -115,9 +116,17 @@ SELF_INPUT_SUPPRESSED_EVENTS: frozenset[str] = frozenset(# is not a usable trigger; a usable combo needs at least one real key._MODIFIER_TOKENS = frozenset({- "ctrl", "control", "right_ctrl", "right_control",- "alt", "right_alt", "left_alt", "altgr",- "shift", "win", "window",+ "ctrl",+ "control",+ "right_ctrl",+ "right_control",+ "alt",+ "right_alt",+ "left_alt",+ "altgr",+ "shift",+ "win",+ "window",# macOS Command. The Quartz backend has always decoded it# (``_FLAG_MASK_TO_TOKEN`` maps ``kCGEventFlagMaskCommand`` -> ``cmd``),# but it was missing here, so the validator treated Command as an@@ -125,7 +134,10 @@ _MODIFIER_TOKENS = frozenset(# ``cmd+q``, ``cmd+w``, ``cmd+c``, ``cmd+space`` were all accepted while# their Windows equivalents were refused, and a user could bind "quit# the focused app" as their dictation key.- "cmd", "command", "meta", "super",+ "cmd",+ "command",+ "meta",+ "super",})@@ -136,9 +148,16 @@ _MODIFIER_TOKENS = frozenset(# keystroke of normal typing and would make the assistant trigger constantly._SOLO_SAFE_KEYS = frozenset({f"f{i}" for i in range(1, 25)}) | frozenset({- "up", "down", "left", "right",- "home", "end", "page_up", "page_down",- "insert", "delete",+ "up",+ "down",+ "left",+ "right",+ "home",+ "end",+ "page_up",+ "page_down",+ "insert",+ "delete",})@@ -299,8 +318,7 @@ def validate_hotkey(combo: str, *, platform: str | None = None) -> HotkeyVerdictcautions.append(_os_shortcut_caution(f"Command+{non_modifiers[0].upper()}",- "is a system shortcut on macOS (copy, quit, close, Spotlight "- "and friends)",+ "is a system shortcut on macOS (copy, quit, close, Spotlight and friends)",))@@ -354,9 +372,7 @@ def normalized_combo_tokens(combo: str) -> frozenset[str]:all fold onto ``window``. Any comparison of two shortcuts has to happen onTHIS set — comparing the raw tokens accepts two combos the OS sees as one."""- return frozenset(- p.strip() for p in _normalize_combo(combo).split("+") if p.strip()- )+ return frozenset(p.strip() for p in _normalize_combo(combo).split("+") if p.strip())def combos_collide(a: str, b: str) -> bool:@@ -453,6 +469,179 @@ def _module_present(name: str) -> bool:return False+# Virtual-key codes for the three named modifiers. The two Win keys already+# live next to GetAsyncKeyState in the Windows backend; these three are the+# rest of the chord the in-app recorder has to see even when the WebView+# swallowed the DOM keyup (GitHub #98).+_VK_SHIFT = 0x10+_VK_CONTROL = 0x11+_VK_MENU = 0x12 # Alt / Option++# pynput / Quartz held-set spellings -> the four snapshot tokens the recorder+# understands (ctrl, alt, shift, and win-or-cmd). Side-specific names fold+# because the snapshot cannot tell left from right on every OS.+_HELD_MODIFIER_TO_SNAPSHOT: dict[str, str] = {+ "ctrl": "ctrl",+ "ctrl_l": "ctrl",+ "ctrl_r": "ctrl",+ "control": "ctrl",+ "right_control": "ctrl",+ "alt": "alt",+ "alt_l": "alt",+ "alt_r": "alt",+ "alt_gr": "alt",+ "right_alt": "alt",+ "left_alt": "alt",+ "shift": "shift",+ "shift_l": "shift",+ "shift_r": "shift",+ "cmd": "win",+ "cmd_l": "win",+ "cmd_r": "win",+ "command": "win",+ "win": "win",+ "window": "win",+ "super": "win",+ "meta": "win",+}+++def modifier_snapshot(+ platform: str | None = None,+ *,+ backend_held: frozenset[str] | set[str] | None = None,+) -> tuple[frozenset[str] | None, str]:+ """Currently held modifier keys, or ``(None, reason)`` if this host cannot tell.++ A capability probe, never a platform-name test at the call site (AP-21).+ The in-app keybind recorder uses this when the WebView's DOM events lie:+ macOS WKWebView often delivers a modifier ``keydown`` and then never the+ matching ``keyup`` (the OS sent ``flagsChanged``, which is not a DOM+ event), so a recorder that only trusts keyup hangs with Option/Command+ still marked as held. Asking the OS is the one answer that cannot go+ stale. Empty ``frozenset`` means "we can tell, and nothing is down".++ Tokens are the recorder vocabulary: ``ctrl``, ``alt``, ``shift``, plus+ ``cmd`` on macOS and ``win`` everywhere else.++ * Windows — ``GetAsyncKeyState`` for Shift/Ctrl/Alt/Win (same primitive+ the hotkey poller already uses).+ * macOS — ``CGEventSourceFlagsState`` (no event tap, no Accessibility+ grant). Needs pyobjc Quartz.+ * Linux/X11 — no cheap OS-wide read in the base install. When the live+ pynput listener is running its held-set is accepted as a fallback;+ Wayland and a not-yet-started listener return ``None`` with an English+ reason. The on-screen picker still works there.+ """+ host = platform if platform is not None else _detect_platform()+ if host == "win32":+ snap = _win32_modifier_snapshot()+ if snap is not None:+ return snap, ""+ return None, (+ "This Windows session cannot read the modifier keys right now. "+ "Click the keys on the on-screen keyboard, or type a letter with "+ "the modifiers held."+ )+ if host == "darwin":+ snap = _darwin_modifier_snapshot()+ if snap is not None:+ return snap, ""+ return None, (+ "Reading the modifier keys needs the pyobjc Quartz package, which "+ "is not installed — install the [full] profile. Click the keys on "+ "the on-screen keyboard in the meantime."+ )+ if host == "linux":+ if backend_held is not None:+ return _snapshot_from_held(backend_held, meta_spelling="win"), ""+ try:+ from jarvis.platform.probes import is_wayland++ wayland = is_wayland()+ except Exception: # noqa: BLE001 — a probe failure must never hard-fail+ wayland = False+ if wayland:+ return None, (+ "Wayland does not let an application read the modifier keys "+ "globally. Click the keys on the on-screen keyboard, or bind "+ "a compositor shortcut to the Jarvis CLI."+ )+ return None, (+ "This Linux session cannot read the modifier keys until global "+ "hotkeys are running. Click the keys on the on-screen keyboard, "+ "or type a letter with the modifiers held."+ )+ return None, (+ "This system has no way to read the modifier keys globally — click "+ "the keys on the on-screen keyboard instead."+ )+++def _snapshot_from_held(held: frozenset[str] | set[str], *, meta_spelling: str) -> frozenset[str]:+ """Fold a backend held-set down to the four snapshot tokens."""+ out: set[str] = set()+ for token in held:+ folded = _HELD_MODIFIER_TO_SNAPSHOT.get(token)+ if folded is None:+ continue+ out.add(meta_spelling if folded == "win" else folded)+ return frozenset(out)+++def _win32_modifier_snapshot() -> frozenset[str] | None:+ """Shift/Ctrl/Alt/Win via GetAsyncKeyState. ``None`` if the probe cannot run."""+ from jarvis.trigger.backends.global_hotkeys import (+ _VK_LWIN,+ _VK_RWIN,+ _async_key_is_down,+ )++ tokens: set[str] = set()+ for vk, name in (+ (_VK_SHIFT, "shift"),+ (_VK_CONTROL, "ctrl"),+ (_VK_MENU, "alt"),+ ):+ down = _async_key_is_down(vk)+ if down is None:+ return None+ if down:+ tokens.add(name)+ left = _async_key_is_down(_VK_LWIN)+ right = _async_key_is_down(_VK_RWIN)+ if left is None or right is None:+ return None+ if left or right:+ tokens.add("win")+ return frozenset(tokens)+++def _darwin_modifier_snapshot() -> frozenset[str] | None:+ """Shift/Ctrl/Option/Command via CGEventSourceFlagsState. ``None`` if Quartz is missing."""+ try:+ import Quartz # type: ignore[import-not-found,import-untyped] # lazy (HN-7)+ except Exception: # noqa: BLE001 — optional [desktop-macos] extra+ return None+ try:+ state = Quartz.kCGEventSourceStateCombinedSessionState+ flags = int(Quartz.CGEventSourceFlagsState(state))+ except Exception: # noqa: BLE001 — a failed probe is "unknown", never a crash+ log.debug("CGEventSourceFlagsState failed", exc_info=True)+ return None+ tokens: set[str] = set()+ # Same masks as QuartzHotkeyBackend._FLAG_MASK_TO_TOKEN.+ if flags & (1 << 17):+ tokens.add("shift")+ if flags & (1 << 18):+ tokens.add("ctrl")+ if flags & (1 << 19):+ tokens.add("alt")+ if flags & (1 << 20):+ tokens.add("cmd")+ return frozenset(tokens)++class HotkeyTrigger:"""Manages several named hotkey bindings at once.@@ -537,6 +726,7 @@ class HotkeyTrigger:log.debug("Hotkey %r dropped: the event loop is closing.", event_name)except Exception: # noqa: BLE001 — a dead poller is worse than any lost edgelog.exception("Hotkey %r handler failed (edge dropped).", event_name)+return _on_pressdef chord_is_down(self, event_name: str) -> bool | None:@@ -569,6 +759,31 @@ class HotkeyTrigger:answered = Truereturn False if answered else None+ def held_tokens(self) -> frozenset[str] | None:+ """Every token the live backend currently has in its held-set.++ ``None`` when there is no backend or it cannot see the keyboard (not+ started, Noop, Windows poller which has no held-set). The in-app+ recorder uses this as a Linux fallback for :func:`modifier_snapshot`.+ """+ backend = self._backend+ if backend is None:+ return None+ probe = getattr(backend, "held_tokens", None)+ if callable(probe):+ try:+ answer = probe()+ except Exception: # noqa: BLE001 — a failed probe is "unknown"+ log.debug("held_tokens() failed", exc_info=True)+ return None+ if answer is None:+ return None+ return frozenset(answer)+ held = getattr(backend, "_held", None)+ if isinstance(held, set):+ return frozenset(held)+ return None+def _push_nowait(self, event_name: str) -> None:try:self._queue.put_nowait(event_name)@@ -650,8 +865,9 @@ class HotkeyTrigger:log.info("Hotkey-Trigger armed (%s): %s",type(backend).__name__,- ", ".join(f"{name}=[{', '.join(combos)}]"- for name, combos in self._bindings_cfg.items()),+ ", ".join(+ f"{name}=[{', '.join(combos)}]" for name, combos in self._bindings_cfg.items()+ ),)return self@@ -715,8 +931,7 @@ class HotkeyTrigger:log.info("🔁 Hotkey-Live-Reload — re-armed: %s",", ".join(- f"{name}=[{', '.join(combos)}]"- for name, combos in self._bindings_cfg.items()+ f"{name}=[{', '.join(combos)}]" for name, combos in self._bindings_cfg.items()),)except Exception: # noqa: BLE001 — never crash voice on a re-arm hiccup@@ -739,6 +954,7 @@ __all__ = ["HotkeyTrigger","HotkeyVerdict","combos_collide",+ "modifier_snapshot","mouse_hotkeys_available","normalized_combo_tokens","validate_hotkey",diff --git a/jarvis/ui/web/frontend/src/views/KeybindsPanel.test.tsx b/jarvis/ui/web/frontend/src/views/KeybindsPanel.test.tsxindex 2a67e225f6..1ba1cdd004 100644--- a/jarvis/ui/web/frontend/src/views/KeybindsPanel.test.tsx+++ b/jarvis/ui/web/frontend/src/views/KeybindsPanel.test.tsx@@ -279,6 +279,82 @@ describe("KeybindsPanel", () => {);});+ it("commits when a letter's keyup says the modifier is already up", async () => {+ // GitHub #98: WKWebView often delivers Control's keydown and then never+ // the matching keyup. The letter's keyup still carries ctrlKey=false, so+ // the recorder must not wait for a mouse move (or hang forever).+ const calls = stubFetch();+ render(<KeybindsPanel />);++ await waitFor(() => expect(comboText("call")).toBe("F3+F4"));+ fireEvent.click(screen.getByTestId("combo-field-call"));++ fireEvent.keyDown(window, {+ code: "ControlLeft",+ key: "Control",+ ctrlKey: true,+ });+ fireEvent.keyDown(window, { code: "KeyJ", key: "j", ctrlKey: true });+ fireEvent.keyUp(window, { code: "KeyJ", key: "j", ctrlKey: false });++ await waitFor(() =>+ expect(+ calls.some(+ (c) =>+ c.method === "PUT" &&+ (c.body as { hotkey: string }).hotkey === "ctrl+j",+ ),+ ).toBe(true),+ );+ });++ it("records a lone Command from the OS snapshot when the WebView is silent", async () => {+ const calls: RecordedCall[] = [];+ let held: string[] = ["cmd"];+ vi.stubGlobal(+ "fetch",+ vi.fn(async (url: unknown, init?: { method?: string; body?: unknown }) => {+ const href = String(url);+ calls.push({+ url: href,+ method: init?.method ?? "GET",+ body: init?.body ? JSON.parse(String(init.body)) : undefined,+ });+ if (href.includes("/keybinds/held")) {+ return {+ ok: true,+ json: async () => ({ available: true, tokens: held, reason: "" }),+ };+ }+ return { ok: true, json: async () => FULL };+ }),+ );+ render(<KeybindsPanel />);++ await waitFor(() => expect(comboText("call")).toBe("F3+F4"));+ fireEvent.click(screen.getByTestId("combo-field-call"));++ await waitFor(() => {+ const text = comboText("call");+ // jsdom reports a PC keyboard, so Command folds onto Win; a Mac host+ // emits the ⌘ chip. Either spelling is the same physical key.+ expect(text === "⌘" || text === "Win").toBe(true);+ });+ held = [];++ await waitFor(+ () =>+ expect(+ calls.some((c) => {+ if (c.method !== "PUT") return false;+ const hotkey = (c.body as { hotkey: string }).hotkey;+ return hotkey === "cmd" || hotkey === "win";+ }),+ ).toBe(true),+ { timeout: 4000 },+ );+ });+it("recovers from a swallowed modifier keyup on the next mouse move", async () => {// A mouse event carries the TRUE modifier state, so it is a free, continuous// repair for a phantom held modifier — the one state no timer may resolve.diff --git a/jarvis/ui/web/frontend/src/views/settings/KeybindRow.tsx b/jarvis/ui/web/frontend/src/views/settings/KeybindRow.tsxindex c1afb156a2..22768b01c5 100644--- a/jarvis/ui/web/frontend/src/views/settings/KeybindRow.tsx+++ b/jarvis/ui/web/frontend/src/views/settings/KeybindRow.tsx@@ -48,11 +48,25 @@ const _CLICK_SETTLE_MS = 1200;* indefinitely: holding Ctrl+Alt while deciding on the third key is how a human* actually builds a chord, and committing "ctrl+alt" out from under them (the* reported "it saves before I can think") is precisely what this guard exists- * to prevent. The gesture ends when the user lets go of everything — or when- * the window loses focus, which ends it whether the keys came up or not.+ * to prevent. Modifier releases are recovered a different way: every keyboard+ * and mouse event carries the true flag word, and while capturing we also poll+ * the OS snapshot at ``GET /api/settings/keybinds/held``. The gesture ends when+ * the user lets go of everything — or when the window loses focus, which ends+ * it whether the keys came up or not.*/const _LOST_KEYUP_MS = 900;+/**+ * How often the recorder asks the OS which modifiers are actually down.+ *+ * Short enough that a lone Option/Command whose DOM keyup never arrives still+ * commits as part of the same gesture; long enough that a Settings panel with+ * the recorder closed does not poll at all (the interval only runs while+ * capturing). A host that answers ``available: false`` is asked once and then+ * left alone.+ */+const _NATIVE_HELD_MS = 80;+/** Pretty-print a combo string ("ctrl+right_alt+j" → "Ctrl + AltGr + J"). */export function formatCombo(combo: string): string {const labels: Record<string, string> = {@@ -453,6 +467,149 @@ export function KeybindRow({return true;}+ function familyOfCode(code: string): "ctrl" | "alt" | "shift" | "meta" | null {+ if (code.startsWith("Control")) return "ctrl";+ if (code.startsWith("Alt")) return "alt";+ if (code.startsWith("Shift")) return "shift";+ if (code.startsWith("Meta")) return "meta";+ return null;+ }++ function codesForFamily(family: "ctrl" | "alt" | "shift" | "meta"): string[] {+ switch (family) {+ case "ctrl":+ return ["ControlLeft", "ControlRight"];+ case "alt":+ return ["AltLeft", "AltRight", "AltGraph"];+ case "shift":+ return ["ShiftLeft", "ShiftRight"];+ case "meta":+ return ["MetaLeft", "MetaRight"];+ }+ }++ function canonicalCode(family: "ctrl" | "alt" | "shift" | "meta"): string {+ switch (family) {+ case "ctrl":+ return "ControlLeft";+ case "alt":+ return "AltLeft";+ case "shift":+ return "ShiftLeft";+ case "meta":+ return "MetaLeft";+ }+ }++ type FlagWord = { ctrl: boolean; alt: boolean; shift: boolean; meta: boolean };++ function flagsFromEvent(e: {+ ctrlKey: boolean;+ altKey: boolean;+ shiftKey: boolean;+ metaKey: boolean;+ }): FlagWord {+ return {+ ctrl: e.ctrlKey,+ alt: e.altKey,+ shift: e.shiftKey,+ meta: e.metaKey,+ };+ }++ function dropReleasedModifiers(flags: FlagWord): boolean {+ let changed = false;+ for (const code of [...pressed]) {+ const family = familyOfCode(code);+ if (family === null) continue;+ if (!flags[family]) {+ pressed.delete(code);+ changed = true;+ }+ }+ return changed;+ }++ function ensureFlaggedModifiers(flags: FlagWord): boolean {+ let changed = false;+ for (const family of ["ctrl", "alt", "shift", "meta"] as const) {+ if (!flags[family]) continue;+ if (codesForFamily(family).some((c) => pressed.has(c))) continue;+ pressed.add(canonicalCode(family));+ changed = true;+ }+ return changed;+ }++ function previewFromPressed() {+ const next = chordToCombo(+ {+ code: "",+ ctrlKey: codesForFamily("ctrl").some((c) => pressed.has(c)),+ altKey: codesForFamily("alt").some((c) => pressed.has(c)),+ shiftKey: codesForFamily("shift").some((c) => pressed.has(c)),+ metaKey: codesForFamily("meta").some((c) => pressed.has(c)),+ },+ held,+ );+ if (next) {+ pending = next;+ setCombo(next);+ setSaved(false);+ }+ }++ function finishIfReleased(): boolean {+ if (pressed.size === 0 && pending) {+ if (idle) clearTimeout(idle);+ commit();+ return true;+ }+ return false;+ }++ // Families the OS snapshot has reported as down at least once this+ // gesture. We only DROP a modifier from that snapshot after it has been+ // seen down: a lagging first poll that says "nothing held" must not+ // commit Ctrl+Alt out from under someone who just pressed them.+ const nativeSeen = new Set<"ctrl" | "alt" | "shift" | "meta">();+ let nativeUnavailable = false;++ function applyNativeTokens(tokens: string[]) {+ const set = new Set(tokens);+ const nativeFlags: FlagWord = {+ ctrl: set.has("ctrl"),+ alt: set.has("alt"),+ shift: set.has("shift"),+ meta:+ set.has("cmd") ||+ set.has("win") ||+ set.has("command") ||+ set.has("window") ||+ set.has("meta") ||+ set.has("super"),+ };+ let changed = false;+ for (const family of ["ctrl", "alt", "shift", "meta"] as const) {+ if (nativeFlags[family]) {+ nativeSeen.add(family);+ if (!codesForFamily(family).some((c) => pressed.has(c))) {+ pressed.add(canonicalCode(family));+ changed = true;+ }+ } else if (nativeSeen.has(family)) {+ nativeSeen.delete(family);+ for (const code of codesForFamily(family)) {+ if (pressed.delete(code)) changed = true;+ }+ }+ }+ if (!changed) return;+ setPressedCodes(new Set(pressed));+ previewFromPressed();+ finishIfReleased();+ }+// Rescue timer for keys that never deliver a keyup — function keys// especially, and anything released while the window is losing focus.// Without it the "commit on full release" path below would hang forever@@ -486,6 +643,9 @@ export function KeybindRow({return;}pressed.add(e.code);+ const flags = flagsFromEvent(e);+ ensureFlaggedModifiers(flags);+ dropReleasedModifiers(flags);setPressedCodes(new Set(pressed)); // live keyboard highlightconst tok = codeToKeyToken(e.code);if (tok) held.add(tok);@@ -502,15 +662,15 @@ export function KeybindRow({e.preventDefault();e.stopPropagation();pressed.delete(e.code);+ // A letter's keyup carries the TRUE modifier flags. If Option/Command+ // was released and its own keyup was swallowed, this is the moment we+ // find out — without waiting for a mouse move.+ dropReleasedModifiers(flagsFromEvent(e));setPressedCodes(new Set(pressed)); // live keyboard highlight// Fast path: commit the instant EVERY key is released. `pending` holds// the fullest chord seen during the gesture, so the release order never// matters and early-lifted keys are not lost.- if (pressed.size === 0 && pending) {- if (idle) clearTimeout(idle);- commit();- return;- }+ if (finishIfReleased()) return;armRescue();}@@ -535,28 +695,9 @@ export function KeybindRow({* could sit armed with a phantom Ctrl and no way out but Esc.*/function syncModifiers(e: MouseEvent) {- let changed = false;- for (const code of [...pressed]) {- const stillDown = code.startsWith("Control")- ? e.ctrlKey- : code.startsWith("Alt")- ? e.altKey- : code.startsWith("Shift")- ? e.shiftKey- : code.startsWith("Meta")- ? e.metaKey- : true; // not a modifier — a mouse event says nothing about it- if (!stillDown) {- pressed.delete(code);- changed = true;- }- }- if (!changed) return;+ if (!dropReleasedModifiers(flagsFromEvent(e))) return;setPressedCodes(new Set(pressed));- if (pressed.size === 0 && pending) {- if (idle) clearTimeout(idle);- commit();- }+ finishIfReleased();}// A MouseEvent carries the same modifier flags a KeyboardEvent does, but no@@ -628,8 +769,36 @@ export function KeybindRow({window.addEventListener("auxclick", onAuxClick, true);window.addEventListener("mousemove", syncModifiers, true);window.addEventListener("blur", onWindowBlur);++ // OS snapshot of the modifier keys. Covers the case WKWebView never+ // delivers a modifier event at all (lone Command on macOS): the probe+ // sees the flags word, the recorder lights the key, and the matching+ // "up" snapshot commits. A host that cannot tell is asked once.+ async function tickNative() {+ if (nativeUnavailable) return;+ try {+ const res = await fetch("/api/settings/keybinds/held");+ if (!res.ok) return;+ const data: { available?: boolean; tokens?: string[] } = await res.json();+ if (nativeUnavailable) return;+ if (data.available !== true) {+ nativeUnavailable = true;+ return;+ }+ applyNativeTokens(Array.isArray(data.tokens) ? data.tokens : []);+ } catch {+ // A single failed probe is not "unavailable"; the next tick retries.+ }+ }+ const nativeTimer = setInterval(() => {+ void tickNative();+ }, _NATIVE_HELD_MS);+ void tickNative();+return () => {if (idle) clearTimeout(idle);+ clearInterval(nativeTimer);+ nativeUnavailable = true;window.removeEventListener("keydown", onKeyDown, true);window.removeEventListener("keyup", onKeyUp, true);window.removeEventListener("mousedown", onMouseDown, true);diff --git a/jarvis/ui/web/settings_routes.py b/jarvis/ui/web/settings_routes.pyindex 8c2bac3a49..18b7e6ef55 100644--- a/jarvis/ui/web/settings_routes.py+++ b/jarvis/ui/web/settings_routes.py@@ -11,6 +11,8 @@ Endpoints:instant_phrases, local_whisper_available}PUT /api/settings/wake-word → persist to jarvis.toml [trigger.wake_word](+ resolved-plan preview); restart required+ GET /api/settings/keybinds/held → live modifier keys currently held+ ({available, tokens, reason})Why a dedicated route (not localStorage): the reply language has to reach theBrainManager so ``_build_system_prompt`` can emit the language directive — the@@ -1817,6 +1819,37 @@ def get_keybinds(request: Request) -> dict[str, object]:}[email protected]("/keybinds/held")+def get_keybind_held(request: Request) -> dict[str, object]:+ """Live modifier keys currently held, for the in-app recorder.++ ``available`` is the capability probe: False on hosts that cannot read+ modifier state (Wayland, headless, missing Quartz). The recorder then+ keeps using DOM events and the on-screen picker instead of hanging.+ """+ from jarvis.trigger.hotkey import modifier_snapshot++ backend_held: set[str] | None = None+ pipeline = getattr(request.app.state, "speech_pipeline", None)+ trigger = getattr(pipeline, "_hotkey_trigger", None) if pipeline is not None else None+ probe = getattr(trigger, "held_tokens", None) if trigger is not None else None+ if callable(probe):+ try:+ raw = probe()+ except Exception: # noqa: BLE001 — a failed probe is "unknown"+ log.debug("held_tokens() failed", exc_info=True)+ raw = None+ if raw is not None:+ backend_held = set(raw)++ tokens, reason = modifier_snapshot(backend_held=backend_held)+ return {+ "available": tokens is not None,+ "tokens": sorted(tokens) if tokens is not None else [],+ "reason": reason,+ }++@router.put("/keybinds")def put_keybind(body: KeybindBody, request: Request) -> dict[str, object]:from jarvis.core.config_writer import KEYBIND_ACTIONS, KEYBIND_TOML_KEYdiff --git a/tests/contract/test_hotkey_backend_protocol.py b/tests/contract/test_hotkey_backend_protocol.pyindex b00b2811a1..9e410e9048 100644--- a/tests/contract/test_hotkey_backend_protocol.py+++ b/tests/contract/test_hotkey_backend_protocol.py@@ -51,3 +51,13 @@ def test_a_backend_that_is_not_listening_answers_unknown_never_up(factory):def test_an_empty_combo_is_unknown_not_down(factory):backend = factory()assert backend.chord_is_down("") is None++[email protected]("factory", _backend_factories())+def test_held_tokens_is_unknown_before_the_backend_listens(factory):+ """The recorder snapshot must not invent a held modifier on a host that+ is not listening yet — same three-way contract as ``chord_is_down``."""+ backend = factory()+ probe = getattr(backend, "held_tokens", None)+ assert callable(probe)+ assert probe() is Nonediff --git a/tests/fakes/fake_hotkey_backend.py b/tests/fakes/fake_hotkey_backend.pyindex 420be8055b..0f9300f02c 100644--- a/tests/fakes/fake_hotkey_backend.py+++ b/tests/fakes/fake_hotkey_backend.py@@ -39,6 +39,9 @@ class FakeHotkeyBackend:self.key_state: dict[str, bool | None] = {}self.key_state_default: bool | None = Noneself.key_state_queries: list[str] = []+ # Test knob for ``held_tokens``: ``None`` (default) = cannot see the+ # keyboard; a set is the live held-set while started.+ self.held: frozenset[str] | None = None# ------------------------------------------------------------------# HotkeyBackend protocol surface@@ -71,6 +74,11 @@ class FakeHotkeyBackend:self.key_state_queries.append(key)return self.key_state.get(key, self.key_state_default)+ def held_tokens(self) -> frozenset[str] | None:+ if not self._started:+ return None+ return self.held+# ------------------------------------------------------------------# Test helpers (not part of the protocol)# ------------------------------------------------------------------diff --git a/tests/unit/trigger/test_modifier_snapshot.py b/tests/unit/trigger/test_modifier_snapshot.pynew file mode 100644index 0000000000..0e76328783--- /dev/null+++ b/tests/unit/trigger/test_modifier_snapshot.py@@ -0,0 +1,96 @@+"""``modifier_snapshot`` — the live modifier probe the in-app recorder polls.++GitHub #98: macOS WKWebView often delivers a modifier keydown and then never+the matching keyup, so a recorder that only trusts DOM events hangs with+Option/Command still marked as held. The probe asks the OS instead. Empty+frozenset = "we can tell, and nothing is down"; None = "this host cannot tell".+"""++from __future__ import annotations++import sys+from types import SimpleNamespace++from jarvis.trigger.hotkey import modifier_snapshot+++def test_win32_snapshot_reports_each_held_modifier(monkeypatch) -> None:+ from jarvis.trigger.backends import global_hotkeys as ghb++ down = {0x11, 0x5B} # VK_CONTROL + VK_LWIN+ monkeypatch.setattr(ghb, "_async_key_is_down", lambda vk: int(vk) in down)++ tokens, reason = modifier_snapshot(platform="win32")+ assert tokens == frozenset({"ctrl", "win"})+ assert reason == ""+++def test_win32_snapshot_empty_set_means_nothing_held(monkeypatch) -> None:+ from jarvis.trigger.backends import global_hotkeys as ghb++ monkeypatch.setattr(ghb, "_async_key_is_down", lambda vk: False)++ tokens, reason = modifier_snapshot(platform="win32")+ assert tokens == frozenset()+ assert reason == ""+++def test_win32_snapshot_is_unknown_when_the_probe_cannot_run(monkeypatch) -> None:+ from jarvis.trigger.backends import global_hotkeys as ghb++ monkeypatch.setattr(ghb, "_async_key_is_down", lambda vk: None)++ tokens, reason = modifier_snapshot(platform="win32")+ assert tokens is None+ assert reason+ assert "on-screen" in reason.lower()+++def test_darwin_snapshot_reads_the_flags_word(monkeypatch) -> None:+ fake = SimpleNamespace(+ kCGEventSourceStateCombinedSessionState=0,+ CGEventSourceFlagsState=lambda _state: (1 << 19) | (1 << 20), # alt + cmd+ )+ monkeypatch.setitem(sys.modules, "Quartz", fake)++ tokens, reason = modifier_snapshot(platform="darwin")+ assert tokens == frozenset({"alt", "cmd"})+ assert reason == ""+++def test_darwin_snapshot_is_unknown_without_quartz(monkeypatch) -> None:+ monkeypatch.setitem(sys.modules, "Quartz", None)++ tokens, reason = modifier_snapshot(platform="darwin")+ assert tokens is None+ assert "Quartz" in reason+++def test_linux_uses_the_live_listener_held_set() -> None:+ tokens, reason = modifier_snapshot(platform="linux", backend_held={"ctrl", "j", "alt_r", "cmd"})+ assert tokens == frozenset({"ctrl", "alt", "win"})+ assert reason == ""+++def test_linux_without_a_listener_is_unknown(monkeypatch) -> None:+ import jarvis.platform.probes as probes++ monkeypatch.setattr(probes, "is_wayland", lambda: False)+ tokens, reason = modifier_snapshot(platform="linux")+ assert tokens is None+ assert reason+++def test_wayland_names_the_compositor_instead_of_pretending(monkeypatch) -> None:+ import jarvis.platform.probes as probes++ monkeypatch.setattr(probes, "is_wayland", lambda: True)+ tokens, reason = modifier_snapshot(platform="linux")+ assert tokens is None+ assert "Wayland" in reason+++def test_unknown_host_is_honest() -> None:+ tokens, reason = modifier_snapshot(platform="haiku")+ assert tokens is None+ assert reasondiff --git a/tests/unit/ui/test_keybinds_route.py b/tests/unit/ui/test_keybinds_route.pyindex 00cb5bae21..e864e65437 100644--- a/tests/unit/ui/test_keybinds_route.py+++ b/tests/unit/ui/test_keybinds_route.py@@ -614,3 +614,36 @@ def test_get_reflects_cleared_keybind() -> None:)body = client.get("/api/settings/keybinds").json()assert body["keybinds"]["call"] == ""+++def test_held_route_serves_the_capability_probe(monkeypatch) -> None:+ """The recorder polls this; a missing ``available`` field would hang a+ Mac user whose WebView swallowed the modifier keyup (GitHub #98)."""+ from jarvis.trigger import hotkey as hotkey_mod++ monkeypatch.setattr(+ hotkey_mod,+ "modifier_snapshot",+ lambda **k: (frozenset({"alt", "cmd"}), ""),+ )+ body = _client().get("/api/settings/keybinds/held").json()+ assert body["available"] is True+ assert body["tokens"] == ["alt", "cmd"]+ assert body["reason"] == ""+++def test_held_route_is_honest_when_the_host_cannot_tell(monkeypatch) -> None:+ from jarvis.trigger import hotkey as hotkey_mod++ monkeypatch.setattr(+ hotkey_mod,+ "modifier_snapshot",+ lambda **k: (+ None,+ "Wayland does not let an application read the modifier keys globally.",+ ),+ )+ body = _client().get("/api/settings/keybinds/held").json()+ assert body["available"] is False+ assert body["tokens"] == []+ assert "Wayland" in body["reason"]