Module pid 

PID file locking for daemon singleton enforcement

This module provides cross-platform file locking to ensure only one daemon instance runs per project. It addresses these security mitigations:

• TIGER-P1-01: Atomic lock acquisition before PID write (prevents startup race)
• TIGER-P3-02: Acquire lock BEFORE reading existing PID (prevents TOCTOU attacks)

Security Pattern

The lock acquisition follows this secure pattern:

1. Create/open PID file
2. Acquire exclusive non-blocking lock FIRST (before any reads)
3. If lock fails, read PID and check if process is running
4. If lock succeeds, truncate and write our PID
5. Return guard that releases lock on drop

This order is critical - acquiring the lock before reading prevents TOCTOU (time-of-check to time-of-use) vulnerabilities where an attacker could manipulate the PID file between our check and lock acquisition.

Structs

PidGuard

Guard that holds the PID file lock and releases it on drop.

Functions

check_stale_pid

Check if a PID file contains a stale PID (process no longer running).

cleanup_stale_pid

Clean up a stale PID file if it exists.

compute_hash

Compute a deterministic hash for a project path.

compute_pid_path

Compute the PID file path for a project.

compute_socket_path

Compute the socket path for a project (Unix).

is_process_running

Check if a process with the given PID is currently running.

try_acquire_lock

Try to acquire an exclusive lock on the PID file.