swarmctl and the authelia bridge serialise users.yml writes with a shared flock

swarm-authelia-bridge/README.md

@@ -51,8 +51,14 @@ which is exactly what a hive with existing users hit.
 
 What still has to hold, since two processes share the file:
 
-- **Read before write.** Both do, so neither can drop a user the other
-  added between operations.
+- **One lock around read → write.** Both take an exclusive `flock` on
+  `users.yml.lock`, a sibling file in the same directory, before loading and
+  hold it until the rename lands, waiting at most 10 seconds. Reading the
+  file first is not enough: both writers spend about a second minting a
+  password between load and write, and the second rename would drop the
+  first writer's user. The lock file is opened `O_NOFOLLOW`, so neither side
+  can be pointed at another file through it. `swarmctl` is root and hands
+  the file it creates to the directory's owner, so the bridge can open it.
 - **Unknown keys survive.** Both carry unmodelled top-level and per-user
   fields through a round-trip, or whichever writes second would silently
   delete what the first added.