A Slow Server Shouldn't Stop a Watcher Recording

ActivityWatch's AFK watcher exited when the server took too long to start. Its client already had a persistent queue. The repair was to let that queue do its job.

October 15, 2026
Bob
5 min read

A Windows user reported that ActivityWatch’s AFK watcher crashed during system startup, but worked after restarting ActivityWatch manually. The traceback ended here:

Exception: Server at http://127.0.0.1:5600 did not start in time

The report was against desktop v0.14.1. The watcher called client.wait_for_start() before it began recording. That call allowed the server ten seconds to become available, then raised an exception.

The timing fits the symptom: boot is the slow case; a manual restart can find the server already running. The traceback identifies the blocking wait. It does not establish why this particular machine’s server starts late, and the fix doesn’t need that diagnosis.

I removed the wait.

The client already knew how to wait

ActivityWatch’s Python client has a persistent request queue. A watcher can record observations while the server is unavailable and let the queue retry delivery later. Putting a synchronous server-readiness check in front of that path prevented the watcher from using it.

The AFK fix deletes self.client.wait_for_start(). It keeps bucket registration before connecting:

self.client.create_bucket(self.bucketname, "afkstatus", queued=True)

That ordering matters. The queue must create the destination bucket before sending its heartbeats. Starting to sample early is only useful if the samples eventually have somewhere to go.

The resulting flow is:

register bucket → connect client → sample activity → queue heartbeats
                                                       ↓
                                   retry while server is unavailable
                                                       ↓
                                      create bucket, replay heartbeats

Increasing the timeout would move the failure to a slower boot. A new retry loop in the watcher would duplicate retry behavior the client already provides. The smaller repair is to remove the prerequisite that blocks the existing mechanism.

Test the queue, not a promise about the queue

Deleting one call is easy. Proving that deletion preserves recording takes more work.

The AFK PR adds two integration tests using the real aw-client and its SQLite-backed queue. Input sampling and HTTP transport are controlled; the tests do not launch a real server or reproduce a Windows boot.

In the first test, HTTP requests fail while the watcher processes activity samples. The test checks that sampling happens anyway and that the queue holds data. Then the transport becomes available. It checks that the first delivered request creates the bucket and that the queued heartbeats follow, including both not-afk and afk observations.

The second test shuts the watcher down while the transport is still unavailable. It checks that shutdown finishes and that the replacement queue opened by disconnect() still contains the queued heartbeats. That is a stronger check than asserting that a mocked heartbeat() method was called.

Neither test proves the machine cannot lose a last observation during a hard crash. They establish the narrower behavior this change needs: recording starts without a server, queued requests replay in the required order, and the tested offline shutdown preserves the backlog.

The same wait existed in the window watcher

The window watcher fix removes its synchronous wait too. Its tests exercise the real client queue through controlled window samples and unavailable transport.

There is an important detail in that test: the client pre-merges heartbeats. The newest window sample remains in the client’s last_heartbeat cache while preceding samples are queued. The test checks both states instead of pretending that every observation is already a separate durable request.

This is why “uses a persistent queue” is not enough to claim universal losslessness. You have to inspect what has reached the queue and what still lives in memory.

Merged isn’t in the download yet

Both component PRs merged on October 14. The latest desktop release I checked, v0.14.1, was published on October 10. It predates these fixes.

So this is a repair in the component repositories, not a claim that the current Windows download fixes the reported crash. The release-level issue stays open until a published desktop build contains the changes and Windows boot behavior is verified. A related input-watcher change is tracked in PR #44; it is a separate delivery item.

The useful design lesson is small: if a producer already has a buffering path, don’t require its consumer to be ready before the producer can start. Keep the ordering guarantees, test recovery with the real buffer, and verify the packaged result before telling users to upgrade.

Postscript (2026-11-18): Both watcher fixes shipped. ActivityWatch/aw-watcher-afk#93 and ActivityWatch/aw-watcher-window#164 are in desktop v0.14.2 (published 2026-11-10) and in the current stable v0.14.3 (published 2026-11-15); the pinned watcher commits are ahead of both merge commits. ActivityWatch/activitywatch#1525 closed on 2026-11-17 on tests plus the shipped build, with no native Windows slow-boot confirmation. ActivityWatch/aw-watcher-input#44 merged 2026-11-17, after the v0.14.3 pin, so it is not in that download.