docs: document QR token state locking

GUIDE_DEV_PYTHON.md

@@ -2259,7 +2259,27 @@ d'informations sont non critiques et peuvent retourner une liste vide avec un wa
 Les objets renvoyés par `client.homework(start, end)` couvrent une fenêtre. Le résultat destiné à
 un jour cible est donc filtré explicitement sur `homework.date == target_date`.
 
-#### 5.1.8 Logique de repli (`sources/pronote/fallback.py`)
+#### 5.1.8 Verrou du cycle d'authentification QR/token
+
+En mode `qr_token`, le token Pronote est un état partagé et rotatif. Afin d'éviter que deux
+exécutions ne réutilisent ou n'écrasent cet état simultanément, le client protège chaque cycle
+d'authentification et de récupération par un verrou POSIX local non bloquant, situé dans
+`.pronote_auth_state.json.lock`, à côté de `.pronote_auth_state.json`.
+
+Le verrou couvre l'ensemble du cycle QR/token : chargement de l'état, connexion par token ou
+enrôlement QR initial, opération de données (agenda, devoirs, messages ou informations), puis
+persistance des credentials actualisées. Une tentative concurrente échoue immédiatement avec une
+erreur d'état d'authentification expurgée ; elle ne patiente pas et ne relance pas
+l'authentification. Le contenu du token, le PIN et les autres credentials ne sont jamais inclus
+dans les logs ni dans ce message d'erreur.
+
+Ce mécanisme est un contrat **local** : il coordonne des processus sur le même hôte Linux et un
+filesystem local. Pour des déploiements conteneurisés, les conteneurs qui partagent le même compte
+Pronote doivent également partager le fichier d'état et son fichier de verrou. Le verrou ne fournit
+aucune exclusion fiable entre plusieurs hôtes ou via NFS ; dans ces cas, l'opérateur doit prévoir
+une exclusion externe ou utiliser un token distinct par instance.
+
+#### 5.1.9 Logique de repli (`sources/pronote/fallback.py`)
 
 Le `PronoteFetcher` dépend de `Settings` et d'un protocole de client injecté ; il ne construit pas
 de singleton et ne contient pas d'identifiants dupliqués.