fix(processes): fix multiple clawx processes running concurently

[hazeone]

Summary

This PR addresses the issue of multiple ClawX processes running concurrently and causing port conflicts, particularly after abnormal application termination. It hardens the application's process lifecycle management to ensure reliable single-instance operation and proper cleanup of child processes.

Key changes include:

• Deterministic Quit Lifecycle: Ensures the gateway process is properly stopped and cleaned up during application exit, with a bounded timeout.
• Robust Single-Instance Lock: Implements a file-based fallback lock mechanism in addition to Electron's requestSingleInstanceLock() to prevent multiple instances from starting, even if the lock file is malformed or stale.
• Improved Gateway Termination: Enhances the supervisor to use process-tree termination on Windows (taskkill /F /T) for owned gateway processes and adds a post-cleanup port release wait.
• Enhanced Observability: Adds clearer logging for process ownership, instance outcomes, and updates documentation regarding Electron's multi-process nature and troubleshooting port conflicts.
• New Unit Tests: Adds tests for quit lifecycle, gateway supervisor termination, and process instance lock robustness.

Related Issue(s)

Addresses the root cause of multiple ClawX processes and port conflicts described in the initial task.

Type of Change

• Bug fix
• Refactor
• New feature
• Documentation
• Other

Validation

The following checks were performed:

• Unit Tests: New and existing unit tests for process-instance-lock, main-quit-lifecycle, and gateway-supervisor were run and passed.
• Type Checking: pnpm run typecheck passed.
• Manual Validation:
  • Confirmed only one listener on 127.0.0.1:18789 after startup.
  • Verified immediate exit of duplicate instances on second launch.
  • Validated correct creation, recovery from stale/malformed lock files, and release of the clawx.instance.lock file.
  • Tested SIGINT/SIGTERM handling to ensure proper lock release and gateway shutdown.

Checklist

• I ran relevant checks/tests locally.
• I updated docs if behavior or interfaces changed.
• I verified there are no unrelated changes in this PR.

  

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}