fix: enforce single-instance using QLockFile

[TimeToBuildBob]

Summary

Prevents multiple instances of aw-qt from running simultaneously by using Qt's built-in QLockFile.

• On startup, aw-qt acquires a lock file in the aw-qt data directory
• If a lock is already held, the new instance logs a warning (with the running PID) and exits with code 1
• Testing mode uses a separate lock file (aw-qt-testing.lock) to avoid conflicts with a production instance

Implementation

QLockFile from PyQt6.QtCore was chosen because:

• Cross-platform (Windows, macOS, Linux) without additional dependencies
• Already available since PyQt6 is an existing dependency
• Designed exactly for this use case — includes PID/hostname/process name in the lock file for diagnostics
• Handles stale lock cleanup automatically

The lock is acquired after logging is set up (so the warning lands in the log file) but before modules are started (so no partial startup occurs).

Related

Fixes ActivityWatch/activitywatch#1176

cc @ErikBjare

---

Important

Prevents multiple aw-qt instances using QLockFile, logging a warning and exiting if another instance is running.

• Behavior:
  • Prevents multiple aw-qt instances using QLockFile in main.py.
  • Logs a warning and exits with code 1 if another instance is running.
  • Uses aw-qt-testing.lock for testing mode to avoid conflicts.
• Implementation:
  • Adds _acquire_single_instance_lock() function in main.py to handle lock acquisition.
  • Lock acquired after logging setup but before module startup.
• Misc:
  • Fixes App allows to execute multiple instances activitywatch#1176.

^{This description was created by for 827d660. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 827d660 in 6 seconds. Click for details.

• Reviewed 58 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 0 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

Workflow ID: wflow_WSmqMFjeCPyzsfIo

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ErikBjare]

Data dir? Why not cache dir?

[greptile-apps]

Greptile Summary

Adds single-instance enforcement to aw-qt using Qt's QLockFile, preventing multiple instances from running simultaneously.

• Uses QLockFile from PyQt6.QtCore for cross-platform compatibility without additional dependencies
• Lock is acquired after logging setup but before module startup, ensuring proper error reporting and preventing partial initialization
• Testing mode uses a separate lock file (aw-qt-testing.lock) to avoid conflicts with production instances
• When a second instance is attempted, it logs the PID of the running instance and exits cleanly with code 1
• Lock is held for the entire process lifetime and automatically handles stale lock cleanup when processes crash

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation uses Qt's well-tested QLockFile API with appropriate error handling and doesn't modify any existing functionality—it only adds single-instance enforcement at the appropriate point in the startup sequence
• No files require special attention

Important Files Changed

Filename	Overview
aw_qt/main.py	Added single-instance enforcement using QLockFile to prevent multiple aw-qt processes from running simultaneously

_{Last reviewed commit: 827d660}

[greptile-apps]

_{1 file reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}