docs: document QR token state locking

.secrets.baseline

@@ -140,7 +140,7 @@
         "filename": "GUIDE_DEV_PYTHON.md",
         "hashed_secret": "90bd1b48e958257948487b90bee080ba5ed00caa",
         "is_verified": true,
-        "line_number": 5064,
+        "line_number": 5084,
         "is_secret": false
       }
     ],
@@ -177,5 +177,5 @@
       }
     ]
   },
-  "generated_at": "2026-09-08T10:45:46Z"
+  "generated_at": "2026-09-10T19:26:08Z"
 }

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.