feat(download-lock): align stale timeout with npm and use in dlxBinary

- Reduce default staleTimeout from 300s to 10s (align with npm's 5-10s range)
- Use downloadWithLock in dlxBinary.downloadBinary() for concurrent protection
- Prevents corruption when multiple processes download same binary
- Preserves checksum verification after download completes
- Sets 2-minute lockTimeout for large binary downloads

Benefits:
- Aligns with npm's battle-tested npx locking strategy
- Prevents TAR_ENTRY_ERROR, ENOTEMPTY, MODULE_NOT_FOUND issues
- Faster stale lock detection (10s vs 5 minutes)
- Better concurrent download handling across processes

Author: jdalton

src/dlx-binary.ts

@@ -7,8 +7,8 @@ import path from 'node:path'
 
 import { WIN32 } from '#constants/platform'
 
+import { downloadWithLock } from './download-lock'
 import { isDir, readJson, safeDelete } from './fs'
-import { httpRequest } from './http-request'
 import { isObjectObject } from './objects'
 import { normalizePath } from './path'
 import { getSocketDlxDir } from './paths'
@@ -88,63 +88,42 @@ async function isCacheValid(
 }
 
 /**
- * Download a file from a URL with integrity checking.
+ * Download a file from a URL with integrity checking and concurrent download protection.
+ * Uses downloadWithLock to prevent multiple processes from downloading the same binary simultaneously.
  */
 async function downloadBinary(
   url: string,
   destPath: string,
   checksum?: string | undefined,
 ): Promise<string> {
-  const response = await httpRequest(url)
-  if (!response.ok) {
+  // Use downloadWithLock to handle concurrent download protection.
+  // This prevents corruption when multiple processes try to download the same binary.
+  await downloadWithLock(url, destPath, {
+    staleTimeout: 10_000, // Align with npm's npx locking strategy
+    lockTimeout: 120_000, // Allow up to 2 minutes for large binary downloads
+  })
+
+  // Compute checksum of downloaded file.
+  const fileBuffer = await fs.readFile(destPath)
+  const hasher = createHash('sha256')
+  hasher.update(fileBuffer)
+  const actualChecksum = hasher.digest('hex')
+
+  // Verify checksum if provided.
+  if (checksum && actualChecksum !== checksum) {
+    // Clean up invalid file.
+    await safeDelete(destPath)
     throw new Error(
-      `Failed to download binary: ${response.status} ${response.statusText}`,
+      `Checksum mismatch: expected ${checksum}, got ${actualChecksum}`,
     )
   }
 
-  // Create a temporary file first.
-  const tempPath = `${destPath}.download`
-  const hasher = createHash('sha256')
-
-  try {
-    // Ensure directory exists.
-    await fs.mkdir(path.dirname(destPath), { recursive: true })
-
-    // Get the response as a buffer and compute hash.
-    const buffer = response.body
-
-    // Compute hash.
-    hasher.update(buffer)
-    const actualChecksum = hasher.digest('hex')
-
-    // Verify checksum if provided.
-    if (checksum && actualChecksum !== checksum) {
-      throw new Error(
-        `Checksum mismatch: expected ${checksum}, got ${actualChecksum}`,
-      )
-    }
-
-    // Write to temp file.
-    await fs.writeFile(tempPath, buffer)
-
-    // Make executable on POSIX systems.
-    if (!WIN32) {
-      await fs.chmod(tempPath, 0o755)
-    }
-
-    // Move temp file to final location.
-    await fs.rename(tempPath, destPath)
-
-    return actualChecksum
-  } catch (e) {
-    // Clean up temp file on error.
-    try {
-      await safeDelete(tempPath)
-    } catch {
-      // Ignore cleanup errors.
-    }
-    throw e
+  // Make executable on POSIX systems.
+  if (!WIN32) {
+    await fs.chmod(destPath, 0o755)
   }
+
+  return actualChecksum
 }
 
 /**

src/download-lock.ts

@@ -30,7 +30,8 @@ export interface DownloadWithLockOptions extends HttpDownloadOptions {
   pollInterval?: number | undefined
   /**
    * Maximum age of a lock before it's considered stale in milliseconds.
-   * @default 300000 (5 minutes)
+   * Aligned with npm's npx locking strategy (5-10 seconds).
+   * @default 10000 (10 seconds)
    */
   staleTimeout?: number | undefined
 }
@@ -191,7 +192,7 @@ export async function downloadWithLock(
     lockTimeout = 60_000,
     locksDir,
     pollInterval = 1000,
-    staleTimeout = 300_000,
+    staleTimeout = 10_000, // Aligned with npm's npx locking (5-10s range)
     ...downloadOptions
   } = { __proto__: null, ...options } as DownloadWithLockOptions