[hooks_runner] TimeoutException when file locking is unsupported by the filesystem (e.g. SMB shares on macOS) #3651

Problem Description

When running builds (such as flutter build ios or flutter run) on a project hosted on a filesystem where advisory byte-range file locking is unsupported (such as macOS SMB/smbfs network shares), hooks_runner fails after 5 minutes with a TimeoutException:

Could not acquire the lock to /Volumes/APP/.dart_tool/hooks_runner/shared/objective_c/.lock.
Target build_hooks failed: TimeoutException after 0:05:00.000000: Could not acquire the lock to /Volumes/APP/.dart_tool/hooks_runner/shared/objective_c/.lock.
Failed to package /Volumes/APP.
Command PhaseScriptExecution failed with a nonzero exit code

Root Cause

In pkgs/hooks_runner/lib/src/locking/locking.dart, _runUnderFileLock attempts to lock .lock:

while (timeout == null || stopwatch.elapsed < timeout) {
  try {
    await randomAccessFile.lock(FileLock.exclusive);
    ...
  } on FileSystemException {
    if (errorFromCallback) {
      rethrow;
    }
    if (!printed) {
      logger?.finer(
        'Waiting to be able to obtain lock of directory: ${file.path}.',
      );
      printed = true;
    }
    // Don't busy wait, give the CPU some rest.
    // Magic constant taken from flutter_tools for startup lock.
    await Future<void>.delayed(const Duration(milliseconds: 50));
  }
}

final message = 'Could not acquire the lock to ${file.path}.';
logger?.severe(message);
throw TimeoutException(message, timeout);

1. On POSIX systems, randomAccessFile.lock() delegates to fcntl(fd, F_SETLK, &fl).
2. When the underlying filesystem does not support advisory locking (such as macOS SMB mounts, NFS, or special virtual filesystems), fcntl returns an OS error code such as ENOTSUP (45), ENOLCK (77), or EINVAL (22). Dart surfaces this as a native FileSystemException with an OSError.
3. _runUnderFileLock catches all FileSystemException instances and unconditionally treats them as lock contention, sleeping for 50ms and retrying until the 5-minute timeout expires.

Proposed Fix

Inspect e.osError?.errorCode in _runUnderFileLock. If the error code indicates that locking is unsupported rather than genuine contention (e.g., outside Linux EAGAIN 11, POSIX EACCES 13, macOS EAGAIN 35, Windows sharing/lock violations 32/33):

• Log that locking is unsupported on the current filesystem.
• Proceed to execute callback() without holding the lock rather than timing out.

Related Issues

• Originally encountered and reported in flutter/flutter: "Waiting for another flutter command to release the Swift Package Manager lock..." on SMB share on MacOS flutter/flutter#192802.
• Corresponding fix in flutter_tools for Swift Package Manager locking: [flutter_tools] Do not hang when file locking is unsupported by the filesystem flutter/flutter#192821.