Function withFileLock

withFileLock<T>(
    resource: string,
    fn: () => Promise<T>,
    timeoutMsOrOptions?:
        | number
        | AbortSignal
        | BackendReadContext
        | FileLockOptions,
): Promise<T>
Executes an asynchronous function within an exclusive file lease lock.

Combines in-process FIFO promise queuing with OS-level .lease file acquisition. Handles stale process detection, atomic reclamation, token-verified cleanup, and safe cancellation of queued waiters (EXEC-001-T09b).
Type Parameters
- T
  Result of the asynchronous critical section.
Parameters
- resource: string
  Canonical path of the resource or directory to lock.
- fn: () => Promise<T>
  Asynchronous critical section callback.
- timeoutMsOrOptions: number | AbortSignal | BackendReadContext | FileLockOptions = 5000
  Lock timeout in milliseconds, cancellation signal, options object, or read context (default: 5000ms).
Returns Promise<T>
Resolves with the result of fn.

Throws
LockTimeoutError if the lock cannot be acquired within the timeout.

Throws
ToolError if the wait is aborted by signal or expired budget.
- Defined in src/storage/lock.ts:281