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.
ADR-0010 — WindowFocusWatcher: MsgWaitForMultipleObjects instead of PumpMessages
Status: Superseded (2026-09-30) — the window-focus watcher left with the awareness layer (ADR-0009). Accepted: 2026-04-25 Phase: A1 — L1 Live Frame Related: ADR-0009 (Awareness-layer architecture)
Context
Plan JARVIS_AWARENESS_PLAN.md §5 describes the WindowFocusWatcher and states verbatim:
The hook runs in a dedicated Win32 message-loop thread (
pythoncom.PumpMessages).
pythoncom.PumpMessages() is the simple, standard solution for Win32 message pumps in Python: it blocks in a C loop, dispatches all messages to the registered hooks, and exits only on WM_QUIT. Shutdown via PostThreadMessage(thread_id, WM_QUIT, 0, 0) from another thread.
Three problems with this pattern for our lifecycle (<2s shutdown guaranteed, idempotent, without hangs):
- Race condition in the startup window:
PostThreadMessagemust fire after the thread is actually insidePumpMessages. IfSetWinEventHookis still running andWM_QUITis posted in between, it is lost — the pump then runs forever. - No deterministic wakeup handle:
thread.join(2.0)is the only validation. If join waits 2s, you don't know why (did WM_QUIT take effect? did Win32 eat it?). WM_QUITis non-specific: aWM_QUITfrom elsewhere (the Windows logoff sequence, another thread in the same process) would terminate our pump — we cannot distinguish between "stop from us" and "WM_QUIT external".
Decision
WindowFocusWatcher._pump_loop uses MsgWaitForMultipleObjects(stop_event, QS_ALLINPUT) instead of pythoncom.PumpMessages():
while True:
rc = win32event.MsgWaitForMultipleObjects(
[stop_event_handle], False, INFINITE, QS_ALLINPUT,
)
if rc == WAIT_OBJECT_0:
break # stop signaled — we wake up immediately
# rc == WAIT_OBJECT_0 + 1 → Win32 messages are pending
while user32.PeekMessageW(byref(msg), 0, 0, 0, PM_REMOVE):
user32.TranslateMessage(byref(msg))
user32.DispatchMessageW(byref(msg))
Shutdown via win32event.SetEvent(stop_event_handle) from the asyncio thread. Wakeup is deterministic and immediate.
Rationale
MsgWaitForMultipleObjects is the Win32 SDK solution for "a GUI thread with additional wait objects". It solves all three PumpMessages problems:
- No race:
SetEvent(stop_event)is explicitly signaling. The pump wakes up immediately, regardless of whether it is currently in the wait or in message dispatch. - Deterministic wakeup:
rc == WAIT_OBJECT_0is unambiguously "our stop". If join still hangs, we know it is due to Win32 hook cleanup in the finally block, not the wait itself. - Source of the wake distinguishable:
rc == WAIT_OBJECT_0is stop,rc == WAIT_OBJECT_0 + 1is a Win32 message. ExternalWM_QUITwould come via the message path and would not kill the loop.
Plan conflict
Plan §5 names pythoncom.PumpMessages verbatim. CLAUDE.md says: "On conflict between plan and code, the plan wins; code deviations must be documented in the plan." This ADR is that documentation.
It is recommended that §5 be updated accordingly at the next plan review (or that the ADR reference be added to the plan). In practice: both patterns would work — PumpMessages with the three risks named above, MsgWaitForMultipleObjects without them.
Consequences
- Deterministic shutdown <2s without a
PostThreadMessagerace. stop_event_handleis a dedicated Win32 resource that we manage explicitly —CloseHandlein the 6-phase stop sequence is clear (seewindow.py:stop()).- No dependency on
pythoncom.CoInitializefor the pump (we make pureuser32message calls +win32eventfor the wait object).
- More code than the
pythoncom.PumpMessages()one-liner. Readability slightly reduced, but offsettable through comments in_pump_loop. - Three additional Win32 constants (
QS_ALLINPUT,WAIT_OBJECT_0,INFINITE,PM_REMOVE) as module constants, because we cannot pull them fromwin32con(lazy-import requirement).
Alternatives Considered
pythoncom.PumpMessages()withPostThreadMessage(WM_QUIT)shutdown (plan wording): race condition, no deterministic wake. Discarded — see above.pythoncom.PumpWaitingMessages()in atime.sleep(0.1)loop: the polling portion runs permanently, eating CPU + latency. Discarded.WaitForSingleObject(hStop, INFINITE)without a message pump: no hook callbacks would ever be dispatched (no pump tick). Discarded.asyncio.rundirectly in the Win32 thread withloop.add_reader: an asyncio loop and a Win32 pump on the same thread mixes two event-loop models — error-prone. Discarded.
References
JARVIS_AWARENESS_PLAN.md§5 (plan wording of the deviation)dodaios/awareness/watchers/window.py:_pump_loop(implementation)- ADR-0009 (Awareness-layer architecture — parent)
- Win32 docs:
MsgWaitForMultipleObjects