feat(process-lock): align with npm npx locking strategy

- Change stale timeout from 10s to 5s (matches npm npx)
- Add periodic lock touching (2s interval) to prevent false stale detection
- Use second-level granularity for mtime comparison (avoids APFS issues)
- Add touch timer management with automatic cleanup on exit
- Prevent timers from keeping process alive with unref()

This aligns Socket's process locking with npm's npx implementation
per npm/cli#8512, providing more robust
inter-process synchronization for long-running operations.

Author: jdalton

src/process-lock.ts

@@ -1,9 +1,10 @@
 /**
  * @fileoverview Process locking utilities with stale detection and exit cleanup.
  * Provides cross-platform inter-process synchronization using file-system based locks.
+ * Aligned with npm's npx locking strategy (5-second stale timeout, periodic touching).
  */
 
-import { existsSync, mkdirSync, statSync } from 'node:fs'
+import { existsSync, mkdirSync, statSync, utimesSync } from 'node:fs'
 
 import { safeDeleteSync } from './fs'
 import { logger } from './logger'
@@ -35,10 +36,17 @@ export interface ProcessLockOptions {
   /**
    * Stale lock timeout in milliseconds.
    * Locks older than this are considered abandoned and can be reclaimed.
-   * Aligned with npm's npx locking strategy (5-10 seconds).
-   * @default 10000 (10 seconds)
+   * Aligned with npm's npx locking strategy (5 seconds).
+   * @default 5000 (5 seconds)
    */
   staleMs?: number | undefined
+
+  /**
+   * Interval for touching lock file to keep it fresh in milliseconds.
+   * Set to 0 to disable periodic touching.
+   * @default 2000 (2 seconds)
+   */
+  touchIntervalMs?: number | undefined
 }
 
 /**
@@ -48,6 +56,7 @@ export interface ProcessLockOptions {
  */
 class ProcessLockManager {
   private activeLocks = new Set<string>()
+  private touchTimers = new Map<string, NodeJS.Timeout>()
   private exitHandlerRegistered = false
 
   /**
@@ -60,24 +69,85 @@ class ProcessLockManager {
     }
 
     onExit(() => {
+      // Clear all touch timers.
+      for (const timer of this.touchTimers.values()) {
+        clearInterval(timer)
+      }
+      this.touchTimers.clear()
+
+      // Clean up all active locks.
       for (const lockPath of this.activeLocks) {
         try {
           if (existsSync(lockPath)) {
             safeDeleteSync(lockPath, { recursive: true })
           }
         } catch {
-          // Ignore cleanup errors during exit
+          // Ignore cleanup errors during exit.
         }
       }
     })
 
     this.exitHandlerRegistered = true
   }
 
+  /**
+   * Touch a lock file to update its mtime.
+   * This prevents the lock from being detected as stale during long operations.
+   *
+   * @param lockPath - Path to the lock directory
+   */
+  private touchLock(lockPath: string): void {
+    try {
+      if (existsSync(lockPath)) {
+        const now = new Date()
+        utimesSync(lockPath, now, now)
+      }
+    } catch (error) {
+      logger.warn(
+        `Failed to touch lock ${lockPath}: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
+  /**
+   * Start periodic touching of a lock file.
+   * Aligned with npm npx strategy to prevent false stale detection.
+   *
+   * @param lockPath - Path to the lock directory
+   * @param intervalMs - Touch interval in milliseconds
+   */
+  private startTouchTimer(lockPath: string, intervalMs: number): void {
+    if (intervalMs <= 0 || this.touchTimers.has(lockPath)) {
+      return
+    }
+
+    const timer = setInterval(() => {
+      this.touchLock(lockPath)
+    }, intervalMs)
+
+    // Prevent timer from keeping process alive.
+    timer.unref()
+
+    this.touchTimers.set(lockPath, timer)
+  }
+
+  /**
+   * Stop periodic touching of a lock file.
+   *
+   * @param lockPath - Path to the lock directory
+   */
+  private stopTouchTimer(lockPath: string): void {
+    const timer = this.touchTimers.get(lockPath)
+    if (timer) {
+      clearInterval(timer)
+      this.touchTimers.delete(lockPath)
+    }
+  }
+
   /**
    * Check if a lock is stale based on mtime.
-   * A lock is considered stale if it's older than the specified timeout,
-   * indicating the holding process likely died abnormally.
+   * Uses second-level granularity to avoid APFS floating-point precision issues.
+   * Aligned with npm's npx locking strategy.
    *
    * @param lockPath - Path to the lock directory
    * @param staleMs - Stale timeout in milliseconds
@@ -90,8 +160,10 @@ class ProcessLockManager {
       }
 
       const stats = statSync(lockPath)
-      const age = Date.now() - stats.mtime.getTime()
-      return age > staleMs
+      // Use second-level granularity to avoid APFS issues.
+      const ageSeconds = Math.floor((Date.now() - stats.mtime.getTime()) / 1000)
+      const staleSeconds = Math.floor(staleMs / 1000)
+      return ageSeconds > staleSeconds
     } catch {
       return false
     }
@@ -128,35 +200,39 @@ class ProcessLockManager {
       baseDelayMs = 100,
       maxDelayMs = 1000,
       retries = 3,
-      staleMs = 10_000,
+      staleMs = 5000,
+      touchIntervalMs = 2000,
     } = options
 
-    // Ensure exit handler is registered before any lock acquisition
+    // Ensure exit handler is registered before any lock acquisition.
     this.ensureExitHandler()
 
     return await pRetry(
       async () => {
         try {
-          // Check for stale lock and remove if necessary
+          // Check for stale lock and remove if necessary.
           if (existsSync(lockPath) && this.isStale(lockPath, staleMs)) {
             logger.log(`Removing stale lock: ${lockPath}`)
             try {
               safeDeleteSync(lockPath, { recursive: true })
             } catch {
-              // Ignore errors removing stale lock - will retry
+              // Ignore errors removing stale lock - will retry.
             }
           }
 
-          // Atomic lock acquisition via mkdir
+          // Atomic lock acquisition via mkdir.
           mkdirSync(lockPath, { recursive: false })
 
-          // Track lock for cleanup
+          // Track lock for cleanup.
           this.activeLocks.add(lockPath)
 
-          // Return release function
+          // Start periodic touching to prevent stale detection.
+          this.startTouchTimer(lockPath, touchIntervalMs)
+
+          // Return release function.
           return () => this.release(lockPath)
         } catch (error) {
-          // Handle lock contention
+          // Handle lock contention.
           if (error instanceof Error && (error as any).code === 'EEXIST') {
             if (this.isStale(lockPath, staleMs)) {
               throw new Error(`Stale lock detected: ${lockPath}`)
@@ -177,7 +253,7 @@ class ProcessLockManager {
 
   /**
    * Release a lock and remove from tracking.
-   * Removes the lock directory and stops tracking it for exit cleanup.
+   * Stops periodic touching and removes the lock directory.
    *
    * @param lockPath - Path to the lock directory
    *
@@ -187,6 +263,9 @@ class ProcessLockManager {
    * ```
    */
   release(lockPath: string): void {
+    // Stop periodic touching.
+    this.stopTouchTimer(lockPath)
+
     try {
       if (existsSync(lockPath)) {
         safeDeleteSync(lockPath, { recursive: true })