# Linux-Tray & Settings-Dialog Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Tray-Icon mit Einstellungs-Dialog für Linux/KDE/Wayland auf Basis des bestehenden Windows-Codes aktivieren.

**Architecture:** Wiederverwendung von `pystray` + `tkinter` + `sv-ttk` (plattformunabhängiger Stack). Plattformspezifisch bleibt nur das Hotkey-Aufzeichnen (Linux: evdev, Windows: pynput) und der Konflikt-Check (nur Windows).

**Tech Stack:** Python 3.13, pystray, tkinter, sv-ttk, darkdetect, Pillow, evdev, sounddevice

**Spec:** [docs/superpowers/specs/2026-04-11-linux-tray-design.md](../specs/2026-04-11-linux-tray-design.md)

---

## Dateistruktur

| Datei | Rolle |
|---|---|
| `whisper_local/tray/__init__.py` | `create_tray()` dispatch (win32 + linux → PystrayApp) |
| `whisper_local/tray/_tray.py` | `AppState`, `PystrayApp` (umbenannt von Win32TrayApp), `NoOpTray` |
| `whisper_local/tray/_settings.py` | `SettingsDialog` + plattformübergreifende Helfer |
| `whisper_local/tray/_hotkey_record_pynput.py` | **Neu** — Windows-Record + Konflikt-Check (Extraktion) |
| `whisper_local/tray/_hotkey_record_evdev.py` | **Neu** — Linux-Record via evdev |
| `whisper_local/hotkey/_evdev.py` | `stop()`-Bugfix (Tasks canceln + Devices schließen) |
| `pyproject.toml` | `sys_platform == 'win32'`-Marker entfernen bei gemeinsamen Deps |
| `tests/test_tray.py` | Neue Tests für Linux-Record + Dispatch |
| `tests/test_hotkey.py` | Neuer Test für `stop()`-Fix |

---

## Task 1: `Win32TrayApp` → `PystrayApp` umbenennen

Struktureller Refactor ohne Verhaltensänderung. Macht den Klassennamen plattformneutral, damit Task 6 den Dispatch erweitern kann.

**Files:**
- Modify: `whisper_local/tray/_tray.py`
- Modify: `whisper_local/tray/__init__.py`
- Modify: `tests/test_tray.py`

- [ ] **Step 1: Rename Klasse in `_tray.py`**

Ändere die Klasse in [whisper_local/tray/_tray.py:14](whisper_local/tray/_tray.py#L14):

```python
class PystrayApp:
    """Tray-Icon via pystray — cross-platform (Windows + Linux)."""

    def __init__(self, on_settings: Callable[[], None], on_quit: Callable[[], None]):
        self._on_settings = on_settings
        self._on_quit = on_quit
        self._icon = None

    def start(self) -> None:
        """Startet pystray in einem Daemon-Thread."""
        import pystray
        from whisper_local.tray._icon import create_icon

        menu = pystray.Menu(
            pystray.MenuItem("Einstellungen", self._menu_settings),
            pystray.MenuItem("Beenden", self._menu_quit),
        )
        self._icon = pystray.Icon(
            "whisper-local",
            create_icon(AppState.WAITING),
            "whisper-local",
            menu,
        )
        thread = threading.Thread(target=self._icon.run, daemon=True)
        thread.start()

    def set_state(self, state: AppState) -> None:
        """Tauscht das Icon aus (thread-sicher)."""
        if self._icon is not None:
            from whisper_local.tray._icon import create_icon
            self._icon.icon = create_icon(state)

    def _menu_settings(self, icon, item) -> None:
        self._on_settings()

    def _menu_quit(self, icon, item) -> None:
        if self._icon is not None:
            self._icon.stop()
        self._on_quit()
```

- [ ] **Step 2: `__init__.py` anpassen**

Ersetze in [whisper_local/tray/__init__.py](whisper_local/tray/__init__.py) die Referenzen:

```python
"""Tray-Package — plattformspezifische Tray-App."""

import sys
from typing import Callable

from whisper_local.tray._tray import AppState, NoOpTray


def create_tray(
    on_settings: Callable[[], None],
    on_quit: Callable[[], None],
) -> "PystrayApp | NoOpTray":
    """Gibt den plattformspezifischen Tray zurück."""
    if sys.platform == "win32":
        from whisper_local.tray._tray import PystrayApp
        return PystrayApp(on_settings=on_settings, on_quit=on_quit)
    return NoOpTray()


__all__ = ["create_tray", "AppState"]
```

(Linux-Dispatch kommt in Task 6 — jetzt erstmal nur umbenennen.)

- [ ] **Step 3: Tests anpassen**

In `tests/test_tray.py` alle Vorkommen von `Win32TrayApp` durch `PystrayApp` ersetzen:

- Zeile 28: `class TestWin32TrayApp:` → `class TestPystrayApp:`
- Zeile 31: `from whisper_local.tray._tray import AppState, Win32TrayApp` → `... PystrayApp`
- Zeile 33: `Win32TrayApp(...)` → `PystrayApp(...)`
- Zeile 44: dito
- Zeile 46: `Win32TrayApp(...)` → `PystrayApp(...)`
- Zeile 248-255 (`test_returns_win32_tray_on_windows`): Import und Assertion auf `PystrayApp` anpassen. Testname umbenennen zu `test_returns_pystray_on_windows`.

- [ ] **Step 4: Tests laufen lassen**

Run: `uv run pytest tests/test_tray.py -v`
Expected: Alle bisher grünen Tests bleiben grün.

- [ ] **Step 5: Commit**

```bash
git add whisper_local/tray/_tray.py whisper_local/tray/__init__.py tests/test_tray.py
git commit -m "refactor: rename Win32TrayApp to PystrayApp"
```

---

## Task 2: Windows-Hotkey-Record in eigenes Modul extrahieren

Bewegt die Windows-spezifischen Record-/Konflikt-Funktionen aus `_settings.py` in ein neues Modul `_hotkey_record_pynput.py`. Verhaltenserhaltend, macht Platz für die Linux-Variante.

**Files:**
- Create: `whisper_local/tray/_hotkey_record_pynput.py`
- Modify: `whisper_local/tray/_settings.py`
- Modify: `tests/test_tray.py`

- [ ] **Step 1: Neues Modul anlegen**

Erstelle `whisper_local/tray/_hotkey_record_pynput.py`:

```python
"""Hotkey-Aufzeichnung und Konflikt-Erkennung für Windows (pynput + Win32)."""

import ctypes
import threading
from typing import Callable


def pynput_to_evdev_key(key) -> str:
    """Konvertiert pynput-Key zu evdev-Key-Namen (z.B. Key.f12 → 'KEY_F12')."""
    from pynput.keyboard import Key, KeyCode

    if isinstance(key, Key):
        return f"KEY_{key.name.upper()}"
    if isinstance(key, KeyCode) and key.char:
        return f"KEY_{key.char.upper()}"
    return ""


def check_hotkey_conflict(evdev_name: str) -> bool:
    """Gibt True zurück wenn die Taste per Win32-RegisterHotKey belegt ist."""
    from whisper_local.hotkey._pynput import _evdev_to_pynput_key
    from pynput.keyboard import Key

    try:
        pynput_key = _evdev_to_pynput_key(evdev_name)
    except ValueError:
        return False

    if not isinstance(pynput_key, Key):
        return False

    vk = getattr(pynput_key.value, "vk", None)
    if vk is None:
        return False

    HOTKEY_ID = 0x7FFF
    user32 = ctypes.windll.user32
    if user32.RegisterHotKey(None, HOTKEY_ID, 0, vk):
        user32.UnregisterHotKey(None, HOTKEY_ID)
        return False
    return True


def record_hotkey(
    on_result: Callable[[str, bool], None],
    cancel_event: threading.Event,
) -> None:
    """Blockiert bis der nächste Keydown kommt oder cancel_event gesetzt wird.

    Ruft on_result(evdev_key_name, has_conflict) auf.
    """
    from pynput.keyboard import Listener

    captured: list[str] = []

    def on_press(key):
        evdev = pynput_to_evdev_key(key)
        if evdev:
            captured.append(evdev)
        return False  # Listener stoppen

    with Listener(on_press=on_press) as lst:
        # Poll cancel_event while listener runs in separate thread
        while lst.running and not cancel_event.is_set():
            lst.join(timeout=0.1)
        if lst.running:
            lst.stop()

    if captured and not cancel_event.is_set():
        evdev = captured[0]
        on_result(evdev, check_hotkey_conflict(evdev))
```

- [ ] **Step 2: `_settings.py` anpassen — Helper entfernen, Record-Logik per Dispatch**

Ersetze [whisper_local/tray/_settings.py](whisper_local/tray/_settings.py) komplett mit:

```python
"""Einstellungs-Dialog für whisper-local (cross-platform)."""

from __future__ import annotations

import sys
import threading
from typing import Callable

import sounddevice as sd

from whisper_local.config import Config, save_config
from whisper_local.tray._theme import apply_system_theme


def list_microphones() -> list[tuple[str, int]]:
    """Gibt Liste aller Eingabegeräte als (name, index) zurück."""
    devices = sd.query_devices()
    return [
        (dev["name"], idx)
        for idx, dev in enumerate(devices)
        if dev["max_input_channels"] > 0
    ]


def _get_record_hotkey():
    """Wählt das plattformspezifische record_hotkey-Callable."""
    if sys.platform == "win32":
        from whisper_local.tray._hotkey_record_pynput import record_hotkey
        return record_hotkey
    from whisper_local.tray._hotkey_record_evdev import record_hotkey
    return record_hotkey


class SettingsDialog:
    """Einstellungs-Dialog (läuft in eigenem Thread)."""

    def __init__(self, config: Config, on_save: Callable[[Config], None]):
        self._config = config
        self._on_save = on_save
        self._cancel_event = threading.Event()

    def open(self) -> None:
        """Öffnet den Dialog in einem Daemon-Thread."""
        thread = threading.Thread(target=self._run, daemon=True)
        thread.start()

    def _run(self) -> None:
        import tkinter as tk
        from tkinter import ttk

        root = tk.Tk()
        root.title("whisper-local – Einstellungen")
        root.resizable(False, False)
        apply_system_theme(root)

        frame = ttk.Frame(root, padding=16)
        frame.pack(fill=tk.BOTH, expand=True)

        # --- Hotkey ---
        ttk.Label(frame, text="Hotkey").grid(row=0, column=0, sticky=tk.W, pady=4)
        hotkey_var = tk.StringVar(value=self._config.hotkey)
        ttk.Label(frame, textvariable=hotkey_var, width=14, relief="sunken").grid(
            row=0, column=1, padx=8
        )

        conflict_var = tk.StringVar()
        ttk.Label(frame, textvariable=conflict_var, foreground="orange").grid(
            row=1, column=0, columnspan=3, sticky=tk.W
        )

        record_hotkey = _get_record_hotkey()

        def do_record():
            hotkey_var.set("...")
            conflict_var.set("")

            def on_result(evdev_key: str, has_conflict: bool):
                root.after(0, lambda: hotkey_var.set(evdev_key))
                if has_conflict:
                    root.after(
                        0,
                        lambda: conflict_var.set(
                            "⚠ Taste ist von einer anderen App belegt (Win32-Hotkeys)"
                        ),
                    )

            def worker():
                record_hotkey(on_result, self._cancel_event)

            threading.Thread(target=worker, daemon=True).start()

        ttk.Button(frame, text="Aufzeichnen", command=do_record).grid(
            row=0, column=2, padx=4
        )

        # --- Mikrofon ---
        ttk.Label(frame, text="Mikrofon").grid(row=2, column=0, sticky=tk.W, pady=4)
        mics = list_microphones()
        mic_names = ["Standard"] + [name for name, _ in mics]
        current_mic = self._config.microphone or "Standard"
        mic_var = tk.StringVar(value=current_mic)
        ttk.Combobox(
            frame, textvariable=mic_var, values=mic_names, state="readonly", width=32
        ).grid(row=2, column=1, columnspan=2, sticky=tk.W, padx=4)

        # --- Buttons ---
        btn_frame = ttk.Frame(frame)
        btn_frame.grid(row=3, column=0, columnspan=3, pady=12, sticky=tk.E)

        def save():
            new_config = Config(
                hotkey=hotkey_var.get(),
                whisper_model=self._config.whisper_model,
                language=self._config.language,
                compute_type=self._config.compute_type,
                sample_rate=self._config.sample_rate,
                channels=self._config.channels,
                min_duration=self._config.min_duration,
                microphone="" if mic_var.get() == "Standard" else mic_var.get(),
            )
            save_config(new_config)
            self._on_save(new_config)
            self._cancel_event.set()
            root.destroy()

        def cancel():
            self._cancel_event.set()
            root.destroy()

        ttk.Button(btn_frame, text="Speichern", command=save).pack(side=tk.RIGHT, padx=4)
        ttk.Button(btn_frame, text="Abbrechen", command=cancel).pack(side=tk.RIGHT)

        root.protocol("WM_DELETE_WINDOW", cancel)
        root.mainloop()
```

- [ ] **Step 3: Tests umbiegen**

In `tests/test_tray.py`:

1. `TestCheckHotkeyConflict`: Import ändern von `whisper_local.tray._settings` auf `whisper_local.tray._hotkey_record_pynput`.
2. `TestPynputToEvdevKey`: Import ändern von `whisper_local.tray._settings` auf `whisper_local.tray._hotkey_record_pynput`.
3. `TestListMicrophones`: bleibt (liegt noch in `_settings`).
4. `TestSettingsDialog.test_on_save_callback_called_when_save_invoked`: Der Patch `patch("whisper_local.tray._settings.apply_system_theme")` bleibt, aber die Referenz auf `pynput_to_evdev_key` etc. existiert nicht mehr in `_settings`. Prüfe, dass dieser Test noch läuft ohne Referenzen auf ausgelagerte Funktionen.

- [ ] **Step 4: Tests laufen lassen**

Run: `uv run pytest tests/test_tray.py -v`
Expected: Alle bisher grünen Tests bleiben grün.

- [ ] **Step 5: Commit**

```bash
git add whisper_local/tray/_hotkey_record_pynput.py whisper_local/tray/_settings.py tests/test_tray.py
git commit -m "refactor: Windows-Hotkey-Record in eigenes Modul auslagern"
```

---

## Task 3: Linux-Hotkey-Record implementieren (TDD)

Neue Funktion `record_hotkey()` auf Basis von `evdev` + `selectors`. Blockiert bis zum ersten Keydown oder Cancel.

**Files:**
- Create: `whisper_local/tray/_hotkey_record_evdev.py`
- Modify: `tests/test_tray.py`

- [ ] **Step 1: Failing Test schreiben**

Füge in `tests/test_tray.py` am Ende ein:

```python
@pytest.mark.skipif(sys.platform != "linux", reason="evdev-Record nur auf Linux")
class TestRecordHotkeyEvdev:
    def test_first_keydown_triggers_on_result(self):
        import threading
        from unittest.mock import MagicMock, patch

        # Fake evdev-Device mit einem Keydown-Event
        fake_event = MagicMock()
        fake_event.type = 1  # EV_KEY
        fake_event.code = 88  # KEY_F12 (ecodes.KEY_F12 == 88)
        fake_event.value = 1  # Keydown

        fake_device = MagicMock()
        fake_device.fd = 42
        fake_device.read.return_value = iter([fake_event])
        fake_device.close = MagicMock()

        cancel = threading.Event()
        results: list[tuple[str, bool]] = []

        def on_result(name, conflict):
            results.append((name, conflict))

        with patch(
            "whisper_local.tray._hotkey_record_evdev.find_all_keyboards",
            return_value=[fake_device],
        ):
            from whisper_local.tray._hotkey_record_evdev import record_hotkey
            record_hotkey(on_result, cancel)

        assert results == [("KEY_F12", False)]
        fake_device.close.assert_called_once()

    def test_cancel_event_stops_recording(self):
        import threading
        from unittest.mock import MagicMock, patch

        fake_device = MagicMock()
        fake_device.fd = 42
        fake_device.read.return_value = iter([])  # keine Events
        fake_device.close = MagicMock()

        cancel = threading.Event()
        cancel.set()  # sofort abbrechen

        results: list[tuple[str, bool]] = []

        with patch(
            "whisper_local.tray._hotkey_record_evdev.find_all_keyboards",
            return_value=[fake_device],
        ):
            from whisper_local.tray._hotkey_record_evdev import record_hotkey
            record_hotkey(lambda n, c: results.append((n, c)), cancel)

        assert results == []
        fake_device.close.assert_called_once()

    def test_ignores_key_up_events(self):
        import threading
        from unittest.mock import MagicMock, patch

        key_up = MagicMock()
        key_up.type = 1  # EV_KEY
        key_up.code = 88
        key_up.value = 0  # Key-Up

        key_down = MagicMock()
        key_down.type = 1
        key_down.code = 88
        key_down.value = 1

        fake_device = MagicMock()
        fake_device.fd = 42
        fake_device.read.return_value = iter([key_up, key_down])
        fake_device.close = MagicMock()

        cancel = threading.Event()
        results: list[tuple[str, bool]] = []

        with patch(
            "whisper_local.tray._hotkey_record_evdev.find_all_keyboards",
            return_value=[fake_device],
        ):
            from whisper_local.tray._hotkey_record_evdev import record_hotkey
            record_hotkey(lambda n, c: results.append((n, c)), cancel)

        assert results == [("KEY_F12", False)]
```

- [ ] **Step 2: Test ausführen — erwartet FAIL**

Run: `uv run pytest tests/test_tray.py::TestRecordHotkeyEvdev -v`
Expected: `ModuleNotFoundError: No module named 'whisper_local.tray._hotkey_record_evdev'`

- [ ] **Step 3: Modul `_hotkey_record_evdev.py` implementieren**

Erstelle `whisper_local/tray/_hotkey_record_evdev.py`:

```python
"""Hotkey-Aufzeichnung via evdev (Linux)."""

import selectors
import threading
from typing import Callable

import evdev
from evdev import InputDevice, ecodes


def find_all_keyboards() -> list[InputDevice]:
    """Gibt alle Input-Devices zurück, die EV_KEY-Events liefern können."""
    keyboards: list[InputDevice] = []
    for path in evdev.list_devices():
        try:
            device = InputDevice(path)
        except (PermissionError, OSError):
            continue
        capabilities = device.capabilities()
        if ecodes.EV_KEY in capabilities:
            keyboards.append(device)
        else:
            device.close()
    return keyboards


def _keycode_to_name(code: int) -> str:
    """Übersetzt evdev-Keycode zu Key-Namen. Gibt '' bei unbekanntem Code."""
    name = ecodes.KEY.get(code)
    if isinstance(name, list):
        return name[0]
    if isinstance(name, str):
        return name
    return ""


def record_hotkey(
    on_result: Callable[[str, bool], None],
    cancel_event: threading.Event,
) -> None:
    """Blockiert bis zum ersten Keydown oder bis cancel_event gesetzt wird.

    Ruft on_result(evdev_key_name, has_conflict) auf. has_conflict ist auf
    Linux immer False — es gibt kein Äquivalent zum Win32-RegisterHotKey-Check.
    """
    devices = find_all_keyboards()
    if not devices:
        return

    selector = selectors.DefaultSelector()
    try:
        for dev in devices:
            selector.register(dev.fd, selectors.EVENT_READ, dev)

        captured: str | None = None
        while captured is None and not cancel_event.is_set():
            for key, _mask in selector.select(timeout=0.1):
                dev: InputDevice = key.data
                for event in dev.read():
                    if event.type == ecodes.EV_KEY and event.value == 1:
                        captured = _keycode_to_name(event.code)
                        break
                if captured:
                    break

        if captured and not cancel_event.is_set():
            on_result(captured, False)
    finally:
        selector.close()
        for dev in devices:
            dev.close()
```

- [ ] **Step 4: Tests ausführen — erwartet PASS**

Run: `uv run pytest tests/test_tray.py::TestRecordHotkeyEvdev -v`
Expected: Alle drei Tests grün.

Falls `fake_device.read()` nicht wie erwartet funktioniert, weil der Selector `selector.select()` blockt: Die Test-Strategie muss den Selector mocken. Alternative:

```python
with patch(
    "whisper_local.tray._hotkey_record_evdev.find_all_keyboards",
    return_value=[fake_device],
), patch(
    "whisper_local.tray._hotkey_record_evdev.selectors.DefaultSelector"
) as mock_sel_cls:
    mock_sel = MagicMock()
    mock_sel_cls.return_value = mock_sel
    # select() liefert den Device-Key zurück
    sel_key = MagicMock()
    sel_key.data = fake_device
    mock_sel.select.return_value = [(sel_key, None)]
    ...
```

Falls der erste Testlauf scheitert, ziehe den Selector-Mock nach.

- [ ] **Step 5: Commit**

```bash
git add whisper_local/tray/_hotkey_record_evdev.py tests/test_tray.py
git commit -m "feat: Linux-Hotkey-Record via evdev"
```

---

## Task 4: `EvdevHotkeyListener.stop()` reparieren (TDD)

Bestehender Bug: `stop()` cancelt die Read-Tasks nicht und schließt die Devices nicht. Das macht den Config-Reload nach Einstellungsänderung kaputt.

**Files:**
- Modify: `whisper_local/hotkey/_evdev.py`
- Modify: `tests/test_hotkey.py`

- [ ] **Step 1: Failing Test schreiben**

Füge in `tests/test_hotkey.py` am Ende ein:

```python
@pytest.mark.skipif(sys.platform != "linux", reason="evdev nur auf Linux")
class TestEvdevListenerStop:
    @pytest.mark.asyncio
    async def test_stop_cancels_tasks_and_closes_devices(self):
        from unittest.mock import MagicMock, patch
        from whisper_local.hotkey._evdev import EvdevHotkeyListener

        listener = EvdevHotkeyListener("KEY_F12")

        async def never_ending(device):
            while True:
                await asyncio.sleep(1)

        fake_device = MagicMock()
        fake_device.close = MagicMock()

        with patch(
            "whisper_local.hotkey._evdev.find_keyboard_devices",
            return_value=[fake_device],
        ), patch.object(listener, "_read_device", side_effect=never_ending):
            listen_task = asyncio.create_task(listener.listen())
            await asyncio.sleep(0.05)  # Loop-Schritt, damit listen() startet

            assert len(listener._tasks) == 1
            listener.stop()
            await asyncio.sleep(0.05)

            assert listener._tasks == []
            fake_device.close.assert_called_once()

        # listen() sollte sauber zurückkehren
        await asyncio.wait_for(listen_task, timeout=1.0)
```

- [ ] **Step 2: Test ausführen — erwartet FAIL**

Run: `uv run pytest tests/test_hotkey.py::TestEvdevListenerStop -v`
Expected: FAIL — `listener._tasks` existiert nicht.

- [ ] **Step 3: Listener patchen**

Ersetze [whisper_local/hotkey/_evdev.py](whisper_local/hotkey/_evdev.py) komplett mit:

```python
"""Hotkey-Listener via evdev für Push-to-Talk (Linux)."""

import asyncio
import logging

import evdev
from evdev import InputDevice, categorize, ecodes

from whisper_local.hotkey import AsyncCallback

logger = logging.getLogger(__name__)


def find_keyboard_devices(key_name: str) -> list[InputDevice]:
    """Findet alle Devices die den angegebenen Key unterstützen."""
    matches = []
    for path in evdev.list_devices():
        device = InputDevice(path)
        capabilities = device.capabilities(verbose=True)
        for (etype_name, _etype_code), events in capabilities.items():
            if etype_name == "EV_KEY":
                key_names = [name for name, _code in events]
                if key_name in key_names:
                    logger.info("Device mit %s gefunden: %s (%s)", key_name, device.name, device.path)
                    matches.append(device)
                    break
    if not matches:
        raise RuntimeError(f"Kein Device mit {key_name} gefunden in /dev/input/")
    return matches


class EvdevHotkeyListener:
    def __init__(self, key_name: str = "KEY_F12"):
        self.key_name = key_name
        self.key_code = ecodes.ecodes.get(key_name)
        if self.key_code is None:
            raise ValueError(f"Unbekannter Key-Name: {key_name}")
        self.on_press: AsyncCallback | None = None
        self.on_release: AsyncCallback | None = None
        self._tasks: list[asyncio.Task] = []
        self._devices: list[InputDevice] = []

    async def _handle_key_event(self, key_down: bool) -> None:
        """Ruft den passenden Callback auf."""
        if key_down and self.on_press:
            await self.on_press()
        elif not key_down and self.on_release:
            await self.on_release()

    async def _read_device(self, device: InputDevice) -> None:
        """Liest Events von einem einzelnen Device."""
        async for event in device.async_read_loop():
            if event.type == ecodes.EV_KEY and event.code == self.key_code:
                if event.value == 1:
                    logger.debug("%s gedrückt (via %s)", self.key_name, device.path)
                    await self._handle_key_event(key_down=True)
                elif event.value == 0:
                    logger.debug("%s losgelassen (via %s)", self.key_name, device.path)
                    await self._handle_key_event(key_down=False)

    def stop(self) -> None:
        """Cancelt laufende Read-Tasks und schließt Devices."""
        for task in self._tasks:
            task.cancel()
        for dev in self._devices:
            try:
                dev.close()
            except Exception:
                pass
        self._tasks = []
        self._devices = []

    async def listen(self) -> None:
        """Lauscht auf evdev-Events der konfigurierten Taste auf allen passenden Devices."""
        self._devices = find_keyboard_devices(self.key_name)
        for dev in self._devices:
            logger.info("Lausche auf %s auf %s (%s)", self.key_name, dev.name, dev.path)
        self._tasks = [asyncio.create_task(self._read_device(dev)) for dev in self._devices]
        await asyncio.gather(*self._tasks, return_exceptions=True)
```

- [ ] **Step 4: Tests ausführen — erwartet PASS**

Run: `uv run pytest tests/test_hotkey.py -v`
Expected: Alle Linux-Tests grün. Die bestehenden Tests (`test_init_stores_key_name`, `test_key_down_calls_callback`, ...) bleiben unverändert grün.

- [ ] **Step 5: Commit**

```bash
git add whisper_local/hotkey/_evdev.py tests/test_hotkey.py
git commit -m "fix: EvdevHotkeyListener.stop() cancelt Tasks und schließt Devices"
```

---

## Task 5: `create_tray()`-Dispatch für Linux erweitern

**Files:**
- Modify: `whisper_local/tray/__init__.py`
- Modify: `tests/test_tray.py`

- [ ] **Step 1: Failing Test schreiben**

Ersetze in `tests/test_tray.py` den bisherigen `test_returns_noop_tray_on_non_windows` (Zeile 257-264) und füge einen Linux-Test hinzu:

```python
class TestCreateTray:
    @pytest.mark.skipif(sys.platform != "win32", reason="Win32 nur auf Windows")
    def test_returns_pystray_on_windows(self):
        from unittest.mock import MagicMock
        from whisper_local.tray import create_tray
        from whisper_local.tray._tray import PystrayApp

        tray = create_tray(on_settings=MagicMock(), on_quit=MagicMock())
        assert isinstance(tray, PystrayApp)

    @pytest.mark.skipif(sys.platform != "linux", reason="Linux-Tray nur auf Linux")
    def test_returns_pystray_on_linux(self):
        from unittest.mock import MagicMock
        from whisper_local.tray import create_tray
        from whisper_local.tray._tray import PystrayApp

        tray = create_tray(on_settings=MagicMock(), on_quit=MagicMock())
        assert isinstance(tray, PystrayApp)

    def test_appstate_exported_from_package(self):
        from whisper_local.tray import AppState
        assert AppState.WAITING is not None
        assert AppState.RECORDING is not None
        assert AppState.TRANSCRIBING is not None
```

- [ ] **Step 2: Test ausführen — erwartet FAIL**

Run: `uv run pytest tests/test_tray.py::TestCreateTray::test_returns_pystray_on_linux -v`
Expected: FAIL — `create_tray()` liefert auf Linux noch `NoOpTray`.

- [ ] **Step 3: Dispatch erweitern**

Ersetze [whisper_local/tray/__init__.py](whisper_local/tray/__init__.py):

```python
"""Tray-Package — plattformspezifische Tray-App."""

import sys
from typing import Callable

from whisper_local.tray._tray import AppState, NoOpTray


def create_tray(
    on_settings: Callable[[], None],
    on_quit: Callable[[], None],
) -> "PystrayApp | NoOpTray":
    """Gibt den plattformspezifischen Tray zurück."""
    if sys.platform in ("win32", "linux"):
        from whisper_local.tray._tray import PystrayApp
        return PystrayApp(on_settings=on_settings, on_quit=on_quit)
    return NoOpTray()


__all__ = ["create_tray", "AppState"]
```

- [ ] **Step 4: Tests ausführen — erwartet PASS**

Run: `uv run pytest tests/test_tray.py -v`
Expected: Alle Tests grün.

- [ ] **Step 5: Commit**

```bash
git add whisper_local/tray/__init__.py tests/test_tray.py
git commit -m "feat: create_tray() dispatcht auf Linux zu PystrayApp"
```

---

## Task 6: `pyproject.toml` — Dependencies für Linux freigeben

**Files:**
- Modify: `pyproject.toml`

- [ ] **Step 1: Marker entfernen**

Ersetze die Dependencies-Liste in [pyproject.toml:5-16](pyproject.toml#L5-L16):

```toml
dependencies = [
    "faster-whisper>=1.1.0",
    "sounddevice>=0.5.0",
    "numpy>=2.0.0",
    "evdev>=1.7.0; sys_platform == 'linux'",
    "pynput>=1.7.0; sys_platform == 'win32'",
    "pywin32>=306; sys_platform == 'win32'",
    "pystray>=0.19.0",
    "Pillow>=10.0.0",
    "sv-ttk>=2.6.0",
    "darkdetect>=0.8.0",
]
```

- [ ] **Step 2: `uv sync` ausführen**

Run: `uv sync`
Expected: Lock-File wird aktualisiert, alle Pakete installieren sauber.

- [ ] **Step 3: Smoke-Import**

Run: `uv run python -c "import pystray, PIL, sv_ttk, darkdetect; print('ok')"`
Expected: `ok` ohne Traceback.

Hinweis: Falls `pystray` auf dem System einen Backend-Fehler wirft (fehlendes `libayatana-appindicator`), installiere `libayatana-appindicator` via Paketmanager. Der Import selbst sollte aber funktionieren — der AppIndicator wird erst zur Laufzeit beim `icon.run()` benötigt.

- [ ] **Step 4: Gesamte Test-Suite**

Run: `uv run pytest -v`
Expected: Alle Tests grün.

- [ ] **Step 5: Commit**

```bash
git add pyproject.toml uv.lock
git commit -m "build: pystray/Pillow/sv-ttk/darkdetect für Linux freigeben"
```

---

## Task 7: Manueller Smoke-Test

Kein Code-Change — verifiziert, dass App unter Linux tatsächlich startet, Tray sichtbar ist und Settings-Dialog funktioniert.

- [ ] **Step 1: App starten**

Run: `uv run whisper-local`
Expected: App startet, Log zeigt `whisper-local gestartet, warte auf Hotkey...`, Tray-Icon (graues Mikrofon) erscheint in der KDE-Taskleiste.

- [ ] **Step 2: Hotkey-Roundtrip**

Drücke `F12` (oder den konfigurierten Hotkey) kurz und sprich etwas. Lasse los.
Expected: Tray-Icon wird rot (Recording), dann gelb (Transcribing), dann wieder grau. Transkribierter Text wird eingefügt.

- [ ] **Step 3: Settings-Dialog**

Rechtsklick auf Tray → „Einstellungen". Klicke „Aufzeichnen" und drücke eine beliebige Taste.
Expected: Der neue Key erscheint im Label. Klicke „Speichern". Dialog schließt, App läuft weiter, neuer Hotkey funktioniert.

- [ ] **Step 4: Beenden**

Rechtsklick auf Tray → „Beenden".
Expected: App beendet sich sauber, kein Zombie-Prozess (`pgrep -af whisper-local` liefert nichts).

- [ ] **Step 5: Ergebnis dokumentieren**

Falls alle Schritte funktionieren: Feature ist fertig. Falls nicht, Befund notieren und als neuen Task aufnehmen.

---

## Selbst-Review-Hinweise für den ausführenden Agent

- **Backend-Check auf CachyOS:** Falls pystray beim `icon.run()` einen Fehler wie `ValueError: Unable to find a tray icon backend` wirft, fehlt AppIndicator. Installiere: `sudo pacman -S libayatana-appindicator`
- **evdev-Permissions:** Wenn `find_all_keyboards()` keine Devices zurückliefert, prüfe Gruppenmitgliedschaft: `groups | grep input`. Nutzer muss in Gruppe `input` sein.
- **Task 3 Test-Strategie:** Wenn der naive Mock-Ansatz für `selectors.DefaultSelector` nicht reicht, nutze den Selector-Patch aus Task 3 Step 4.
- **Keine Änderung an `__main__.py` nötig** — die `create_tray()`-API bleibt gleich, und der bestehende `_restart_hotkey()` funktioniert mit dem `stop()`-Fix aus Task 4 korrekt auf Linux.