runbook: piege ps-aux host vs namespace PID container (mcp-nas)

common/mcp-nas-container-pid-namespace-blindspot.md

@@ -0,0 +1,19 @@
+# ps aux (host) ne voit pas les process internes aux containers -- piege namespace PID
+
+**Contexte** : diagnostic de l'etat du chantier archive OneDrive->RAG (nyora-notes-tt), 04/08/2026 ~22h.
+
+**Symptome** : `ssh nas-host "ps aux | grep recover_and_complete"` retourne vide -> conclusion (fausse) qu'aucun traitement n'est en cours -> relance d'un second run en doublon sur la meme base, tue immediatement apres detection.
+
+**Cause reelle** : les containers Docker sur ce Synology n'utilisent pas `--pid=host`. `ps aux` execute sur l'hote via SSH ne voit que les process du namespace PID de l'hote, pas ceux a l'interieur des containers. Un process bien vivant dans un container (confirme actif 3h+ via `docker top`) est donc invisible a cette methode.
+
+**Piege annexe decouvert en corrigeant** : les PID affiches par `docker top <container>` sont les PID cote host, alors qu'un `kill <pid>` lance depuis un `docker exec ... sh -c` cible le namespace interne au container (numerotation differente) -> kill: No such process meme si le PID existe bel et bien.
+
+**Methode fiable pour verifier/tuer un process dans un container** :
+1. Existence + age : `docker top <container>` (PID host, juste pour confirmer que ca tourne)
+2. PID interne reel (necessaire pour kill) : depuis un exec dans le container, scanner /proc/[0-9]*/cmdline :
+   `docker exec <container> sh -c for p in /proc/[0-9]*; do grep -qa MOTIF $p/cmdline 2>/dev/null && echo $p; done`
+3. Kill avec le PID interne trouve a l'etape 2, pas celui de `docker top`.
+
+**Application** : avant de relancer un script long (import, embedding, traitement batch) sur nyora-notes-tt/hermes-*/tout container sans ps/procps installe, toujours faire cette verification /proc plutot que de se fier a ps aux cote host.
+
+**Tags** : infra, docker, pid-namespace, mcp-nas, piege