agent tried to reproduce a CI-only failure on a Mac and the bug was a Linux-only file locking issue

TL;DR

macOS and Linux do not implement file locks the same way, so a Mac reproduction of a Linux locking bug proves nothing. Reproduce in a Linux container, find the lock call that behaves differently (flock vs fcntl, mandatory vs advisory, lock inheritance across fork), and fix it with portable locking or a platform branch. Stop debugging Linux bugs on a Mac.

The exact query

agent tried to reproduce a CI-only failure on a Mac and the bug was a Linux-only file locking issue

Steps

1. Confirm the platform gap: check what OS CI runs (almost always Linux) and what the agent reproduced on (a Mac). If file locking is anywhere in the failure (lock files, PID files, SQLite, log rotation), the platform difference is the lead suspect.

Expected: You can state "CI is Linux, reproduction was macOS, and the failure involves file locks." The invalid reproduction is identified.

1. Reproduce on Linux properly: run the failing test in a Linux container (docker with the CI base image) or on a Linux CI runner with debug access. Do not approximate; run the real test on the real platform.

Expected: The failure reproduces on Linux. The Mac's clean runs are now explained as platform behavior, not evidence.

1. Isolate the locking call: find the exact lock operation (flock, lockf, fcntl, or a library wrapping them) and check how it behaves on each platform. Common divergences: BSD flock vs POSIX fcntl semantics, locks not inherited across fork on one platform, NFS or overlay filesystems ignoring locks.

Expected: A named call and a named divergence, for example "the code uses flock, which on this Linux container on overlayfs does not block a second flock the way it does on macOS APFS".

1. Fix portably: use a locking primitive that behaves the same on both platforms (a well-tested library rather than raw syscalls), or branch explicitly per platform with a comment citing the divergence. Add a test that exercises the lock contention path on Linux in CI.

Expected: The locking behavior is correct on Linux (the platform that matters) and does not regress macOS.

1. Record the platform rule: document that file-locking bugs reproduce on Linux only, and require the agent to check the CI platform before choosing a reproduction environment. A one-line platform check at the start of triage prevents the whole wasted cycle.

Expected: The next locking failure goes straight to a Linux container instead of three Mac reruns.

Use this when

• A CI-only failure involves file locks and CI runs Linux
• An agent reproduced (or failed to reproduce) on macOS
• The bug involves flock, fcntl, lock files, PID files, or SQLite locking
• Tests pass on Mac and fail on Linux with no code difference

Not for this skill when

• The bug reproduces on macOS too (then it is not a platform locking issue)
• The file issue is not about locking (path separators, case sensitivity, permissions behave differently but are separate problems)
• CI and the reproduction environment are the same OS already (then look elsewhere)

Variant phrasings

test passes on mac but fails on linux CI with file lock error

Platform locking divergence. Reproduce on Linux, fix portably.

flock behaves differently on macOS and linux

It does. Use a portable locking library or an explicit platform branch with the divergence documented.

agent can't reproduce a linux-only bug on its mac

The agent needs a Linux container for reproduction. Platform parity is step zero of triage.

Why it happens

File locking is one of the least portable parts of POSIX: flock and fcntl have different semantics, BSD-derived macOS and Linux disagree on edge cases, and container filesystems (overlayfs) add their own quirks. Code that locks files correctly on a Mac can deadlock, silently not lock, or throw on Linux. The agent, running on a Mac, sees no bug because on its platform there is none. The bug is real; the reproduction platform was wrong.

Edge cases

• SQLite locking on network or container filesystems is notoriously platform-sensitive. If SQLite is in the mix, the fix may be "do not put the SQLite file on that filesystem" rather than a locking change.
• NFS-mounted CI workspaces can make locks behave differently than local disk even on Linux-to-Linux. If the container reproduces but CI still differs, check the filesystem type.
• Some libraries paper over the differences but change semantics subtly (blocking vs non-blocking defaults). Read the library's platform notes, not just its API docs.
• If the lock is only needed for test isolation (not production correctness), consider replacing the file lock with a test-level mutex or serialized test execution instead of fixing cross-platform locking.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstVFW0ulOP1otQmUdM9eUHQ