Module lock 

Directory lock helpers for queue/task coordination.

Responsibilities:

• Provide directory-based locks for queue/task operations.
• Record lock ownership metadata (PID, timestamp, command, label).
• Detect supervising processes and stale lock holders.
• Support shared task locks when a supervising process owns the lock.
• Provide tri-state PID liveness checks (Running, NotRunning, Indeterminate).

Not handled here:

• Atomic writes or temp file cleanup (see crate::fsutil).
• Cross-machine locking or distributed coordination.
• Lock timeouts/backoff beyond the current retry/force logic.

Invariants/assumptions:

• Callers hold DirLock for the entire critical section.
• The lock directory path is stable for the resource being protected.
• The “task” label is reserved for shared lock semantics.
• Labels are informational and should be trimmed before evaluation.
• Task lock sidecar files use unique names (owner_task_<pid>_<counter>) to prevent collisions when multiple task locks are acquired from the same process.
• Indeterminate PID liveness is treated conservatively as lock-owned to prevent concurrent supervisors and unsafe state cleanup.

Structs

DirLock

LockOwner

Lock owner metadata parsed from the owner file.

Enums

PidLiveness

Tri-state PID liveness result.

Functions

acquire_dir_lock

is_supervising_process

Check if the queue lock is currently held by a supervising process (run one or run loop), which means the caller is running under ralph’s supervision and should not attempt to acquire the lock.

pid_is_running

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

pid_liveness

Check PID liveness with tri-state result.

queue_lock_dir

read_lock_owner

Read the lock owner metadata from the lock directory.