Serialize cluster image builds with file lock

The `AlreadyExists` fix in #337 handled one symptom of parallel xdist
workers racing to build the same cluster image, but there's a second
failure mode showing up in CI:

https://github.com/chrisguidry/docket/actions/runs/22025132964/job/63640478732

When concurrent builds target the same tag, the Docker SDK's `build()`
completes successfully in the daemon, then tries to inspect the resulting
image by its short ID. If another worker's build re-tagged the image in
the meantime, the first image ID gets orphaned and the inspect 404s.
This knocked out 485 of 686 tests in the cluster job.

Rather than catching yet another exception type, this serializes the
builds with `fcntl.flock` so only one worker builds at a time. The
others wait and find it already built. Eliminates both the
`AlreadyExists` and `ImageNotFound` races structurally.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: chrisguidry

tests/_container.py

@@ -4,8 +4,10 @@
 including single-node Redis, Redis Cluster, and Valkey variants.
 """
 
+import fcntl
 import os
 import socket
+import tempfile
 import time
 from contextlib import contextmanager
 from datetime import datetime, timedelta, timezone
@@ -167,7 +169,13 @@ def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
 
 
 def build_cluster_image(client: DockerClient, base_image: str) -> str:
-    """Build cluster image from base image, return image tag."""
+    """Build cluster image from base image, return image tag.
+
+    Uses a file lock to serialize builds across parallel xdist workers.
+    Without the lock, concurrent builds for the same tag race: one build
+    re-tags the image and the Docker SDK's post-build inspect on the
+    loser's image ID gets a 404.
+    """
     tag = f"docket-cluster:{base_image.replace('/', '-').replace(':', '-')}"
 
     try:
@@ -176,18 +184,23 @@ def build_cluster_image(client: DockerClient, base_image: str) -> str:
     except docker.errors.ImageNotFound:
         pass
 
-    cluster_dir = Path(__file__).parent / "cluster"
-    try:
+    lock_path = Path(tempfile.gettempdir()) / f"docket-{tag.replace(':', '-')}.lock"
+    with open(lock_path, "w") as lock_file:
+        fcntl.flock(lock_file, fcntl.LOCK_EX)
+
+        # Re-check after acquiring lock; another worker may have built it
+        try:
+            client.images.get(tag)
+            return tag
+        except docker.errors.ImageNotFound:
+            pass
+
+        cluster_dir = Path(__file__).parent / "cluster"
         client.images.build(
             path=str(cluster_dir),
             tag=tag,
             buildargs={"BASE_IMAGE": base_image},
         )
-    except docker.errors.BuildError as e:
-        if "AlreadyExists" in str(e):
-            pass
-        else:
-            raise
     return tag