usage-cli 0.29.32__py3-none-any.whl

window_keeper.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Auto-open the next Claude 5-hour window.
+
+When the user's Claude quota window has expired (``current_reset_at < now``) and
+no window is currently running, this fires a single ``claude -p ok --model haiku``
+message in the background to start a fresh window. The ping is the cheapest
+possible Claude call; it does NOT touch any Anthropic quota API — it only shells
+out to the user's local ``claude`` CLI.
+
+Known-unreliable, cause unidentified: on 2026-08-12 two pings ran with
+indistinguishable requests (same version, entrypoint, model, token shape) and
+only one opened a window. The 06:33 ping lines up with an 11:30 reset; the 17:00
+one did not open anything — the next window began only when the user typed into
+Claude Code at 18:30. The user confirmed no claude.ai/mobile activity that
+morning, so the 06:33 window is not explained away by another device. Not a
+model issue (the docs say plan windows are shared across all models).
+
+That ping runs headless, so Claude Code's statusLine hook never fires and
+``usage-status.json`` keeps reporting the boundary we already handled. A
+cooldown clock therefore re-arms the keeper independently of the payload, so a
+machine that never opens Claude Code interactively still gets a fresh window
+every cycle instead of wedging after the first ping.
+
+Defaults OFF. All judgement and side effects live here; ``menubar.py`` only
+dispatches a one-line call into :func:`maybe_ping`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from contextlib import suppress
+from pathlib import Path
+
+from menubar_prefs import _window_keeper_enabled
+
+logger = logging.getLogger(__name__)
+
+# State file holding the last handled reset boundary and dispatch time. Module
+# constant so tests can monkeypatch it instead of touching the real
+# ``~/.usage/`` dir.
+WINDOW_KEEPER_STATE_PATH = Path(os.path.expanduser("~/.usage/window_keeper.json"))
+
+PING_TIMEOUT_SECONDS = 180
+
+# One full window plus five minutes, so a re-arm can never land inside the
+# window the previous ping opened.
+PING_COOLDOWN_SECONDS = 5 * 3600 + 300
+
+# usage_client defaults a missing ``resets_at`` to parse-time "now", which one
+# refresh later reads as "expired seconds ago". Requiring the expiry to be at
+# least this old filters those synthetic timestamps without delaying a real
+# expired-while-away ping by more than two minutes.
+PING_EXPIRY_GRACE_SECONDS = 120
+
+# ``claude`` binary resolution order: PATH first, then the well-known install
+# spots the Claude Code installer/Node/Homebrew lay down. The .app bundle runs
+# with a minimal PATH, so the native installer's ~/.local/bin must be listed.
+_CLAUDE_BIN_FALLBACKS = (
+    "~/.local/bin/claude",
+    "~/.local/bin/claude.exe",
+    "~/.claude/local/claude",
+    "/opt/homebrew/bin/claude",
+    "/usr/local/bin/claude",
+)
+
+_lock = threading.Lock()
+_ping_in_flight = False
+
+
+def should_ping(
+    now: float,
+    current_reset_at: float | None,
+    enabled: bool,
+    last_pinged_reset_at: float | None,
+    last_ping_at: float | None,
+    current_percent: float | None,
+    data_source: str,
+) -> bool:
+    """Pure gate — no I/O. See module docstring for the rules."""
+    if not enabled:
+        return False
+    # Only the statusLine hook carries trustworthy reset timestamps; fallback
+    # sources (tt-fallback / claude-json) may default a missing resets_at to
+    # parse time, which would read as "expired" and fire a spurious ping.
+    if data_source != "hook":
+        return False
+    # No five-hour block in the payload at all — we can't tell whether a window
+    # is running, so stay quiet rather than risk a false start.
+    if current_percent is None:
+        return False
+    if current_reset_at is None or now - current_reset_at < PING_EXPIRY_GRACE_SECONDS:
+        return False
+    # Two independent re-arm paths, because the two cases run on different
+    # clocks. A different real boundary means the user was active and the
+    # window genuinely rolled over — fire regardless of how recent the last
+    # ping was. The same boundary reported over and over means the payload has
+    # gone stale (see module docstring), and only the dispatch clock can tell
+    # us another window's worth of time has passed.
+    if current_reset_at != last_pinged_reset_at:
+        return True
+    return last_ping_at is None or now - last_ping_at >= PING_COOLDOWN_SECONDS
+
+
+def _load_ping_state(
+    path: Path | None = None,
+) -> tuple[float | None, float | None]:
+    state_path = WINDOW_KEEPER_STATE_PATH if path is None else path
+    if not state_path.exists():
+        return None, None
+    try:
+        data = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None, None
+    if not isinstance(data, dict):
+        return None, None
+
+    def numeric_value(key: str) -> float | None:
+        value = data.get(key)
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            return None
+        return float(value)
+
+    return numeric_value("last_pinged_reset_at"), numeric_value("last_ping_at")
+
+
+def _save_ping_state(
+    reset_at: float,
+    ping_at: float,
+    path: Path | None = None,
+) -> None:
+    state_path = WINDOW_KEEPER_STATE_PATH if path is None else path
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = json.dumps(
+        {"last_pinged_reset_at": reset_at, "last_ping_at": ping_at}
+    ) + "\n"
+    tmp_path: str | None = None
+    try:
+        fd, tmp_path = tempfile.mkstemp(dir=state_path.parent, suffix=".tmp")
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(payload)
+        os.replace(tmp_path, state_path)
+        tmp_path = None
+    except OSError:
+        _debug_log("window-keeper state write failed", exc_info=True)
+    finally:
+        if tmp_path and os.path.exists(tmp_path):
+            with suppress(OSError):
+                os.unlink(tmp_path)
+
+
+def _resolve_claude_bin() -> str | None:
+    found = shutil.which("claude")
+    if found:
+        return found
+    for candidate in _CLAUDE_BIN_FALLBACKS:
+        resolved = os.path.expanduser(candidate)
+        if os.path.isfile(resolved) and os.access(resolved, os.X_OK):
+            return resolved
+    return None
+
+
+def _try_acquire() -> bool:
+    global _ping_in_flight
+    with _lock:
+        if _ping_in_flight:
+            return False
+        _ping_in_flight = True
+        return True
+
+
+def _release() -> None:
+    global _ping_in_flight
+    with _lock:
+        _ping_in_flight = False
+
+
+def _run_claude_ping(claude_bin: str) -> None:
+    # encoding="utf-8" is mandatory inside the .app bundle (project invariant).
+    subprocess.run(  # noqa: S603 - shelling out to the user's own claude CLI by resolved path
+        [claude_bin, "-p", "ok", "--model", "haiku"],
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=PING_TIMEOUT_SECONDS,
+        cwd=os.path.expanduser("~"),
+        check=False,
+    )
+
+
+def _ping_worker(started_at: float) -> None:
+    try:
+        claude_bin = _resolve_claude_bin()
+        if claude_bin is None:
+            _debug_log("window-keeper: claude binary not found, skipping ping")
+            return
+        _run_claude_ping(claude_bin)
+        _debug_log(f"window-keeper: ping completed (started_at={started_at})")
+    except subprocess.TimeoutExpired:
+        _debug_log(f"window-keeper: ping timed out after {PING_TIMEOUT_SECONDS}s")
+    except Exception:
+        # Never let a ping failure escape into the app — this runs on a daemon
+        # thread whose exception would otherwise be silently swallowed anyway,
+        # but be explicit so a future refactor can't crash the main loop.
+        _debug_log("window-keeper: ping failed", exc_info=True)
+    finally:
+        _release()
+
+
+def maybe_ping(
+    current_reset_at: float | None,
+    current_percent: float | None,
+    data_source: str,
+    mock: bool,
+) -> None:
+    """High-level entry: read prefs + state, gate, and fire a background ping.
+
+    Returns immediately — the subprocess runs on a daemon thread. Safe to call
+    on every UI refresh; boundary deduplication + the in-flight guard make it a
+    no-op when busy.
+    """
+    if mock:
+        return
+    enabled = _window_keeper_enabled()
+    if not enabled:
+        # Switch off → zero side effects: don't read or write state, don't spawn.
+        return
+    now = time.time()
+    last_pinged_reset_at, last_ping_at = _load_ping_state()
+    if not should_ping(
+        now,
+        current_reset_at,
+        enabled,
+        last_pinged_reset_at,
+        last_ping_at,
+        current_percent,
+        data_source,
+    ):
+        return
+    if not _try_acquire():
+        return
+    # Mark this boundary handled at dispatch time regardless of subprocess
+    # outcome, so a failed ping doesn't retry on every refresh.
+    assert current_reset_at is not None  # guaranteed by should_ping
+    _save_ping_state(current_reset_at, now)
+    worker = threading.Thread(target=_ping_worker, args=(now,), daemon=True)
+    worker.start()
+
+
+def _debug_log(message: str, *, exc_info: bool = False) -> None:
+    if os.environ.get("USAGE_DEBUG") == "1":
+        logger.warning(message, exc_info=exc_info)

windows_watch.py

@@ -0,0 +1,443 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Native Windows file notifications for tray usage refreshes."""
+
+from __future__ import annotations
+
+import ctypes
+import logging
+import os
+import struct
+import sys
+import threading
+import time
+from collections.abc import Callable
+from ctypes import wintypes
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import codex_loader
+import history_loader
+from adapters import rate_limits
+
+logger = logging.getLogger(__name__)
+
+# Values verified against the Windows SDK documentation for CreateFileW,
+# ReadDirectoryChangesW, WaitForMultipleObjects, and GetOverlappedResult.
+_FILE_LIST_DIRECTORY = 0x0001
+_FILE_SHARE_READ = 0x00000001
+_FILE_SHARE_WRITE = 0x00000002
+_FILE_SHARE_DELETE = 0x00000004
+_OPEN_EXISTING = 3
+_FILE_FLAG_BACKUP_SEMANTICS = 0x02000000
+_FILE_FLAG_OVERLAPPED = 0x40000000
+_FILE_NOTIFY_CHANGE_FILE_NAME = 0x00000001
+_FILE_NOTIFY_CHANGE_DIR_NAME = 0x00000002
+_FILE_NOTIFY_CHANGE_SIZE = 0x00000008
+_FILE_NOTIFY_CHANGE_LAST_WRITE = 0x00000010
+_FILE_NOTIFY_CHANGE_CREATION = 0x00000040
+_NOTIFY_FILTER = (
+    _FILE_NOTIFY_CHANGE_FILE_NAME
+    | _FILE_NOTIFY_CHANGE_DIR_NAME
+    | _FILE_NOTIFY_CHANGE_SIZE
+    | _FILE_NOTIFY_CHANGE_LAST_WRITE
+    | _FILE_NOTIFY_CHANGE_CREATION
+)
+_ERROR_OPERATION_ABORTED = 995
+_ERROR_IO_PENDING = 997
+_ERROR_NOTIFY_ENUM_DIR = 1022
+_WAIT_OBJECT_0 = 0
+_WAIT_FAILED = 0xFFFFFFFF
+_INFINITE = 0xFFFFFFFF
+_WATCH_BUFFER_BYTES = 64 * 1024
+
+_FILE_ACTION_ADDED = 1
+_FILE_ACTION_REMOVED = 2
+_FILE_ACTION_MODIFIED = 3
+_FILE_ACTION_RENAMED_OLD_NAME = 4
+_FILE_ACTION_RENAMED_NEW_NAME = 5
+_REMOVAL_ACTIONS = frozenset({_FILE_ACTION_REMOVED, _FILE_ACTION_RENAMED_OLD_NAME})
+
+
+class _Overlapped(ctypes.Structure):
+    _fields_ = [
+        ("Internal", ctypes.c_size_t),
+        ("InternalHigh", ctypes.c_size_t),
+        ("Offset", wintypes.DWORD),
+        ("OffsetHigh", wintypes.DWORD),
+        ("hEvent", wintypes.HANDLE),
+    ]
+
+
+_kernel32: Any = None
+if sys.platform == "win32":
+    try:
+        _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+        _kernel32.CreateFileW.restype = wintypes.HANDLE
+        _kernel32.CreateFileW.argtypes = [
+            wintypes.LPCWSTR,
+            wintypes.DWORD,
+            wintypes.DWORD,
+            wintypes.LPVOID,
+            wintypes.DWORD,
+            wintypes.DWORD,
+            wintypes.HANDLE,
+        ]
+        _kernel32.ReadDirectoryChangesW.restype = wintypes.BOOL
+        _kernel32.ReadDirectoryChangesW.argtypes = [
+            wintypes.HANDLE,
+            wintypes.LPVOID,
+            wintypes.DWORD,
+            wintypes.BOOL,
+            wintypes.DWORD,
+            wintypes.LPVOID,
+            ctypes.POINTER(_Overlapped),
+            wintypes.LPVOID,
+        ]
+        _kernel32.CreateEventW.restype = wintypes.HANDLE
+        _kernel32.CreateEventW.argtypes = [
+            wintypes.LPVOID,
+            wintypes.BOOL,
+            wintypes.BOOL,
+            wintypes.LPCWSTR,
+        ]
+        _kernel32.SetEvent.restype = wintypes.BOOL
+        _kernel32.SetEvent.argtypes = [wintypes.HANDLE]
+        _kernel32.ResetEvent.restype = wintypes.BOOL
+        _kernel32.ResetEvent.argtypes = [wintypes.HANDLE]
+        _kernel32.WaitForMultipleObjects.restype = wintypes.DWORD
+        _kernel32.WaitForMultipleObjects.argtypes = [
+            wintypes.DWORD,
+            ctypes.POINTER(wintypes.HANDLE),
+            wintypes.BOOL,
+            wintypes.DWORD,
+        ]
+        _kernel32.GetOverlappedResult.restype = wintypes.BOOL
+        _kernel32.GetOverlappedResult.argtypes = [
+            wintypes.HANDLE,
+            ctypes.POINTER(_Overlapped),
+            ctypes.POINTER(wintypes.DWORD),
+            wintypes.BOOL,
+        ]
+        _kernel32.CancelIoEx.restype = wintypes.BOOL
+        _kernel32.CancelIoEx.argtypes = [
+            wintypes.HANDLE,
+            ctypes.POINTER(_Overlapped),
+        ]
+        _kernel32.CloseHandle.restype = wintypes.BOOL
+        _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    except (AttributeError, OSError):
+        _kernel32 = None
+
+_INVALID_HANDLE_VALUE = ctypes.c_void_p(-1).value
+
+
+@dataclass(frozen=True, slots=True)
+class WindowsFileEventChanges:
+    paths: frozenset[Path]
+    needs_full_scan: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class WindowsWatchSpec:
+    root: Path
+    recursive: bool
+    filenames: frozenset[str] = frozenset()
+    history_jsonl: bool = False
+
+    def classify(self, path: Path, action: int) -> WindowsFileEventChanges:
+        if self.filenames:
+            if path.name.casefold() in self.filenames:
+                return WindowsFileEventChanges(frozenset({path}))
+            return WindowsFileEventChanges(frozenset())
+
+        if self.history_jsonl and path.suffix.casefold() == ".jsonl":
+            return WindowsFileEventChanges(frozenset({path}))
+        if self.history_jsonl:
+            # FILE_NOTIFY_INFORMATION does not carry a file-vs-directory bit.
+            # Existing directories and removed/old-name entries may represent
+            # a whole subtree, so match FSEvents by requesting a full scan.
+            try:
+                is_directory = path.is_dir()
+            except OSError:
+                is_directory = False
+            if is_directory or action in _REMOVAL_ACTIONS:
+                return WindowsFileEventChanges(frozenset(), needs_full_scan=True)
+        return WindowsFileEventChanges(frozenset())
+
+
+def usage_watch_specs() -> list[WindowsWatchSpec]:
+    """Return only the existing directories that contain tray usage sources."""
+    status_paths = tuple(
+        Path(path)
+        for path in (
+            rate_limits.STATUS_FILE,
+            rate_limits.LEGACY_STATUS_FILE,
+            rate_limits.TT_STATUS_FILE,
+        )
+    )
+    specs: list[WindowsWatchSpec] = []
+    status_root = status_paths[0].parent
+    if status_root.is_dir():
+        specs.append(
+            WindowsWatchSpec(
+                status_root,
+                recursive=False,
+                filenames=frozenset(path.name.casefold() for path in status_paths),
+            )
+        )
+
+    for root in (
+        history_loader.CLAUDE_PROJECTS_DIR,
+        codex_loader.SESSIONS_DIR,
+        codex_loader.ARCHIVED_SESSIONS_DIR,
+    ):
+        if root.is_dir():
+            specs.append(WindowsWatchSpec(root, recursive=True, history_jsonl=True))
+    return specs
+
+
+def _parse_notifications(
+    spec: WindowsWatchSpec,
+    buffer: ctypes.Array[ctypes.c_char],
+    byte_count: int,
+) -> WindowsFileEventChanges:
+    if byte_count == 0:
+        return WindowsFileEventChanges(frozenset(), needs_full_scan=True)
+
+    dirty_paths: set[Path] = set()
+    needs_full_scan = False
+    offset = 0
+    while True:
+        if byte_count - offset < 12:
+            return WindowsFileEventChanges(frozenset(), needs_full_scan=True)
+        next_offset, action, name_bytes = struct.unpack_from("<III", buffer, offset)
+        name_start = offset + 12
+        name_end = name_start + name_bytes
+        if name_bytes % 2 or name_end > byte_count:
+            return WindowsFileEventChanges(frozenset(), needs_full_scan=True)
+        try:
+            relative_name = buffer.raw[name_start:name_end].decode("utf-16-le")
+        except UnicodeDecodeError:
+            return WindowsFileEventChanges(frozenset(), needs_full_scan=True)
+        classified = spec.classify(spec.root / Path(relative_name), action)
+        dirty_paths.update(classified.paths)
+        needs_full_scan = needs_full_scan or classified.needs_full_scan
+
+        if next_offset == 0:
+            break
+        if next_offset < 12 or offset + next_offset >= byte_count:
+            return WindowsFileEventChanges(frozenset(), needs_full_scan=True)
+        offset += next_offset
+    return WindowsFileEventChanges(frozenset(dirty_paths), needs_full_scan)
+
+
+@dataclass(slots=True)
+class _WatchRuntime:
+    spec: WindowsWatchSpec
+    directory_handle: Any
+    io_event: Any
+    ready: threading.Event
+    thread: threading.Thread | None = None
+
+
+class WindowsUsageWatcher:
+    """Own ReadDirectoryChangesW workers and stop them without blocking the tray."""
+
+    def __init__(
+        self,
+        specs: list[WindowsWatchSpec],
+        callback: Callable[[WindowsFileEventChanges], None],
+    ) -> None:
+        self._specs = specs
+        self._callback = callback
+        self._stop_handle: Any = None
+        self._runtimes: list[_WatchRuntime] = []
+        self._stop_lock = threading.Lock()
+        self._stopped = False
+
+    def start(self) -> bool:
+        if _kernel32 is None or not self._specs:
+            return False
+        self._stop_handle = _kernel32.CreateEventW(None, True, False, None)
+        if not self._stop_handle:
+            return False
+
+        for spec in self._specs:
+            directory_handle = _kernel32.CreateFileW(
+                str(spec.root),
+                _FILE_LIST_DIRECTORY,
+                _FILE_SHARE_READ | _FILE_SHARE_WRITE | _FILE_SHARE_DELETE,
+                None,
+                _OPEN_EXISTING,
+                _FILE_FLAG_BACKUP_SEMANTICS | _FILE_FLAG_OVERLAPPED,
+                None,
+            )
+            if directory_handle in (None, _INVALID_HANDLE_VALUE):
+                self._debug_warning("Could not open Windows usage watch path %s", spec.root)
+                continue
+            io_event = _kernel32.CreateEventW(None, True, False, None)
+            if not io_event:
+                _kernel32.CloseHandle(directory_handle)
+                continue
+            runtime = _WatchRuntime(spec, directory_handle, io_event, threading.Event())
+            runtime.thread = threading.Thread(
+                target=self._watch_directory,
+                args=(runtime,),
+                name=f"usage-watch-{spec.root.name}",
+                daemon=True,
+            )
+            self._runtimes.append(runtime)
+            runtime.thread.start()
+
+        for runtime in self._runtimes:
+            runtime.ready.wait(2.0)
+        if any(
+            runtime.thread is not None and runtime.thread.is_alive()
+            for runtime in self._runtimes
+        ):
+            return True
+        self.stop()
+        return False
+
+    def stop(self, timeout: float = 3.0) -> None:
+        with self._stop_lock:
+            if self._stopped:
+                return
+            self._stopped = True
+            stop_handle = self._stop_handle
+            if stop_handle:
+                _kernel32.SetEvent(stop_handle)
+
+        deadline = time.monotonic() + timeout
+        current = threading.current_thread()
+        for runtime in self._runtimes:
+            thread = runtime.thread
+            if thread is not None and thread is not current:
+                thread.join(max(0.0, deadline - time.monotonic()))
+
+        if any(
+            runtime.thread is not None and runtime.thread.is_alive()
+            for runtime in self._runtimes
+        ):
+            self._debug_warning("Windows usage watcher did not stop cleanly")
+            return
+        if stop_handle:
+            _kernel32.CloseHandle(stop_handle)
+            self._stop_handle = None
+
+    def _watch_directory(self, runtime: _WatchRuntime) -> None:
+        buffer = ctypes.create_string_buffer(_WATCH_BUFFER_BYTES)
+        overlapped = _Overlapped()
+        overlapped.hEvent = runtime.io_event
+        wait_handles = (wintypes.HANDLE * 2)(self._stop_handle, runtime.io_event)
+        set_last_error_name = "set_last_error"
+        set_last_error: Any = getattr(ctypes, set_last_error_name)
+        get_last_error_name = "get_last_error"
+        get_last_error: Any = getattr(ctypes, get_last_error_name)
+        try:
+            while True:
+                _kernel32.ResetEvent(runtime.io_event)
+                set_last_error(0)
+                submitted = _kernel32.ReadDirectoryChangesW(
+                    runtime.directory_handle,
+                    buffer,
+                    len(buffer),
+                    runtime.spec.recursive,
+                    _NOTIFY_FILTER,
+                    None,
+                    ctypes.byref(overlapped),
+                    None,
+                )
+                error = get_last_error()
+                if not submitted and error != _ERROR_IO_PENDING:
+                    runtime.ready.set()
+                    if error == _ERROR_NOTIFY_ENUM_DIR:
+                        self._dispatch(WindowsFileEventChanges(frozenset(), True))
+                    else:
+                        self._debug_warning(
+                            "ReadDirectoryChangesW failed for %s (error %s)",
+                            runtime.spec.root,
+                            error,
+                        )
+                    return
+                runtime.ready.set()
+
+                wait_result = _kernel32.WaitForMultipleObjects(
+                    2,
+                    wait_handles,
+                    False,
+                    _INFINITE,
+                )
+                if wait_result == _WAIT_OBJECT_0:
+                    _kernel32.CancelIoEx(runtime.directory_handle, ctypes.byref(overlapped))
+                    transferred = wintypes.DWORD()
+                    _kernel32.GetOverlappedResult(
+                        runtime.directory_handle,
+                        ctypes.byref(overlapped),
+                        ctypes.byref(transferred),
+                        True,
+                    )
+                    return
+                if wait_result != _WAIT_OBJECT_0 + 1:
+                    if wait_result == _WAIT_FAILED:
+                        self._debug_warning(
+                            "WaitForMultipleObjects failed for %s (error %s)",
+                            runtime.spec.root,
+                            get_last_error(),
+                        )
+                    return
+
+                transferred = wintypes.DWORD()
+                set_last_error(0)
+                completed = _kernel32.GetOverlappedResult(
+                    runtime.directory_handle,
+                    ctypes.byref(overlapped),
+                    ctypes.byref(transferred),
+                    False,
+                )
+                if not completed:
+                    error = get_last_error()
+                    if error == _ERROR_OPERATION_ABORTED and self._stopped:
+                        return
+                    self._dispatch(WindowsFileEventChanges(frozenset(), True))
+                    continue
+                changes = _parse_notifications(runtime.spec, buffer, transferred.value)
+                if changes.paths or changes.needs_full_scan:
+                    self._dispatch(changes)
+        finally:
+            runtime.ready.set()
+            _kernel32.CloseHandle(runtime.io_event)
+            _kernel32.CloseHandle(runtime.directory_handle)
+
+    def _dispatch(self, changes: WindowsFileEventChanges) -> None:
+        if self._stopped:
+            return
+        try:
+            self._callback(changes)
+        except Exception:
+            self._debug_warning("Windows usage watcher callback failed", exc_info=True)
+
+    @staticmethod
+    def _debug_warning(
+        message: str,
+        *args: object,
+        exc_info: bool = False,
+    ) -> None:
+        if os.environ.get("USAGE_DEBUG") == "1":
+            logger.warning(message, *args, exc_info=exc_info)
+
+
+def setup_windows_watcher(
+    callback: Callable[[WindowsFileEventChanges], None],
+    *,
+    specs: list[WindowsWatchSpec] | None = None,
+) -> WindowsUsageWatcher | None:
+    """Start native usage-source watchers, returning None when unavailable."""
+    watcher = WindowsUsageWatcher(usage_watch_specs() if specs is None else specs, callback)
+    return watcher if watcher.start() else None