Généré le 14/10/2026 21:47

🛡️ SOP Canonique : Surveillance Obligatoire (Watchdog) & Persistance Système de Tout Processus Automatisé

Statut : Règle Permanente & Directive Système Impérative
Date de promulgation : 14/10/2026
Référence : SOP-INFRA-RESILIENCE-01
Champ d'application : Tout script Python, tâche asynchrone, démon d'arrière-plan, pipeline de données, plugin MCP ou outil automatisé créé dans l'écosystème Jarvis / Antigravity / Claude Code sous Windows.
Fuseau Horaire de Référence : Guadeloupe UTC-4 (AST — Atlantic Standard Time, permanent toute l'année).


🎯 1. Préambule & Philosophie du "Zéro Processus Orphelin"

Dans un écosystème e-commerce et assistant IA autonome opérant 24/7, aucun script ne doit être laissé sans surveillance.
Un script qui crashe en silence sans redémarrer, ou qui s'interrompt définitivement lors d'un redémarrage système ou d'une mise à jour Windows, constitue une rupture critique de service :
- Arrêt des sentinelles de veille et de monitoring ;
- Blocage des pipelines de production publicitaire ou de classement ;
- Interruption de la synchronisation de l'agenda et de l'écoute vocale ;
- Silence radio préjudiciable pour Raphaël.

⚖️ La Règle d'Airain

"Tout nouveau script, outil ou processus automatisé créé doit obligatoirement inclure un mécanisme de surveillance (watchdog) pour assurer son redémarrage automatique en cas de plantage et sa persistance absolue après un reboot du système."

Aucun livrable d'automatisation ne peut être considéré comme "achevé" ou "validé en production" tant que sa boucle de surveillance et ses ancrages de persistance ne sont pas testés et confirmés fonctionnels.


🏛️ 2. Les 5 Piliers Obligatoires d'une Automatisation Résiliente

Chaque nouveau processus long-running ou démon créé dans l'infrastructure de Raphaël doit impérativement respecter les 5 piliers suivants :

flowchart TD
    subgraph "Processus Supervisé"
        SCRIPT["Processus Automatisé (Worker/Démon)"]
        HB[("Fichier Heartbeat (*_heartbeat.json)<br/>Horodatage UTC-4 + PID")]
        SCRIPT -- "Battement de cœur (5-30s)" --> HB
    end

    subgraph "Sentinelle Dédiée (Watchdog)"
        WD["Watchdog Sentinel (watchdog_*.py)"]
        WD -- "1. Scrutation PID & Uptime (< 3s)" --> SCRIPT
        WD -- "2. Détection de Freeze" --> HB
        WD -- "3. Relance automatique immédiate" --> SCRIPT
        WD -- "4. Alerte Telegram Fiable" --> TG["Telegram Raphaël<br/>(telegram_reliable)"]
        CIRCUIT["Disjoncteur Anti-Emballement<br/>(Max 5 crashs / 60s -> Cooldown)"]
        WD --> CIRCUIT
    end

    subgraph "Persistance Système Windows"
        REBOOT{"Reboot PC / Crash Machine"}
        STARTUP["1. Dossier Startup / Registre HKCU Run"]
        SCHED["2. fast_check_daemons.py (Routine Pulse)"]
        VBS["3. Lanceur VBScript Invisible (.vbs)"]

        REBOOT --> STARTUP
        REBOOT --> SCHED
        STARTUP --> VBS
        SCHED --> VBS
        VBS --> WD
    end

💓 Pilier 1 : Télémétrie de Vie & Heartbeat Structuré

Tout processus d'arrière-plan doit écrire périodiquement (toutes les 5 à 30 secondes selon la charge) un fichier de pulsation JSON standardisé :
- Emplacement canonique : C:\ASSISTANT_IA\<nom_processus>_heartbeat.json
- Schéma JSON obligatoire :

{
  "service": "nom_du_processus",
  "pid": 12345,
  "status": "nominal",
  "uptime_seconds": 3600,
  "last_pulse_utc4": "2026-10-14 21:45:00 AST (UTC-4)",
  "timestamp": 1792028700.0,
  "iteration_count": 720,
  "last_action": "Inspection terminée : 0 anomalie",
  "error_count_last_hour": 0
}

👁️ Pilier 2 : Sentinelle Dédiée (Watchdog) & Détection Ultra-Réactive (< 3s)

Chaque service automatisé dispose soit :
1. D'un watchdog dédié : C:\ASSISTANT_IA\watchdog_<nom_outil>.py (Recommandé pour les composants critiques : classement, architecte, IA vocale, proxy).
2. D'un rattachement au superviseur central : Intégration dans task_watchdog.py et la table des démons de tools/fast_check_daemons.py.

Exigences du Watchdog :
- Intervalle de scrutation : 2 à 3 secondes maximum (CHECK_INTERVAL_SECONDS = 3).
- Surveillance bivalente :
- Surveillance de Processus : Vérification active via psutil.pid_exists(pid) et correspondance de la ligne de commande (target_script.name in cmdline).
- Surveillance d'Activité (Heartbeat) : Vérification de la fraîcheur du fichier heartbeat.
- Gestion d'état persistant : Sauvegarde dans <nom>_state.json des métriques de vie : total des redémarrages, date du dernier crash, temps moyen avant panne (MTBF), historique des incidents.


⚡ Pilier 3 : Relance Résiliente avec Sécurité Anti-Emballement (Crash-Loop Protection)

La résurrection d'un script planté ne doit jamais déstabiliser le système hôte.

Mécanisme de Circuit Breaker obligatoire :
- Si un script plante en boucle à cause d'une erreur fatale (faute de syntaxe, ressource disque saturée, dépendance manquante, coupure API), le watchdog ne doit JAMAIS le relancer des centaines de fois par seconde.
- Règle des seuils :
- Fenêtre glissante : MAX_CRASHES_WINDOW_SEC = 60
- Crashs tolérés : MAX_ALLOWED_CRASHES_IN_WINDOW = 5
- En cas de dépassement : Enclenchement d'un Cooldown temporisé de 30 à 60 secondes avec émission d'une alerte Telegram critique ("🚨 ALERTE CRITIQUE : Démon en crash-loop, mise en pause de sauvegarde").


🔄 Pilier 4 : Persistance Totale Après Reboot Windows (Survie Multi-Niveaux)

Un système résilient ne dépend pas d'un lancement manuel dans un terminal interactif. Pour garantir la persistance après un reboot Windows (mise à jour, coupure électrique, redémarrage programmé), 3 couches de protection doivent être impérativement activées :

  1. Lanceur VBScript Invisible Dédié :
    - Fichier : C:\ASSISTANT_IA\lance_<nom_watchdog>_invisible.vbs
    - Code type :
    vbscript Set WshShell = CreateObject("WScript.Shell") WshShell.CurrentDirectory = "C:\ASSISTANT_IA" WshShell.Run "cmd /c python watchdog_<nom>.py run >> logs\watchdog_<nom>.log 2>&1", 0, False
    - Le paramètre 0 garantit l'invisibilité totale (aucune fenêtre CMD noire qui s'ouvre sur le bureau de Raphaël), et False rend l'exécution asynchrone non-bloquante.

  2. Enregistrement dans tools/fast_check_daemons.py :
    - Tout démon et son watchdog doivent être ajoutés dans la liste daemons de tools/fast_check_daemons.py :
    python ("watchdog_<nom>.py", ["wscript", r"C:\ASSISTANT_IA\lance_<nom_watchdog>_invisible.vbs"], "Watchdog <Nom>")
    - Ce script est exécuté automatiquement à chaque réveil de Jarvis, à chaque pulsation proactive, et avant les tâches critiques.

  3. Ancrage Système Windows (Startup / Registre Run / Tâche Planifiée) :
    - Le raccourci vers le lanceur VBS ou la commande Python doit être inscrit dans :

    • Dossier de démarrage : C:\Users\lisa\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup
    • OU clé de registre : HKCU\Software\Microsoft\Windows\CurrentVersion\Run
    • OU tâche planifiée Windows déclenchée à l'ouverture de session (AtLogon).

📢 Pilier 5 : Notification Telegram Immédiate & Journalisation Traçable

Tout incident doit être immédiatement communiqué à Raphaël sans bruit parasite :
- Module obligatoire : Utiliser exclusivement tools/telegram_reliable.py (from telegram_reliable import send_telegram_reliable).
- Format d'alerte en cas de crash :
text ⚠️ [ALERTE SENTINELLE JARVIS] Le démon <Nom_Service> s'est arrêté de façon inattendue. - Horodatage : 14/10/2026 21:45:12 AST (UTC-4) - Dernier PID : 14208 - Code de sortie : 1 - Cause suspectée : Exception non gérée / Crash inopiné 🔄 Résurrection automatique enclenchée immédiatement...
- Confirmation de résurrection :
text ✅ [RÉSURRECTION CONFIRMÉE] Le démon <Nom_Service> a été relancé avec succès. - Nouveau PID : 28416 - Statut : Nominal
- Journalisation Locale : Tous les événements doivent être écrits dans C:\ASSISTANT_IA\logs\watchdog_<nom>.log avec horodatage local strict Guadeloupe UTC-4.


📋 3. Matrice de Classification des Développements

Avant d'écrire la moindre ligne de code, identifie la catégorie du composant selon la matrice suivante :

Catégorie Description Mécanisme de Surveillance Obligatoire Persistance Reboot
Classe A : Démon Résident 24/7 Service permanent d'écoute, watcher de dossiers, serveur web, proxy, scheduler. Watchdog dédié watchdog_*.py avec heartbeat 5s, circuit-breaker, notification Telegram et logs. Lanceur VBS + fast_check_daemons.py + Dossier Startup Windows.
Classe B : Routine Périodique (Pulse/Cron) Tâche programmée (ex: audit toutes les heures, sync toutes les 6h). Déclaration dans tools/scheduler_daemon.py ou pulse_daemon.py avec retry sur échec et rapport Telegram. Géré par le watchdog du planificateur maître.
Classe C : Pipeline DAG / Longue Tâche Chasse produit, génération vidéo, import Shopify, audit de données. Gestion d'état unitaire state.json, reprise sur incident (--resume), timeout de blocage, supervision par mission_watchdog.py. Reprise automatique à l'étape interrompue lors de la relance.
Classe D : Script Utilitaire / CLI One-Shot Script de conversion, calcul ponctuel, requête unitaire. Trap globale des exceptions (try/except/traceback), code de retour explicite (0=succès, 1=erreur), logs d'audit. Aucune persistance requise.

🛠️ 4. Gabarit Standard de Watchdog (Boilerplate Officiel)

Tout développeur ou agent IA concevant un watchdog doit s'appuyer sur la structure de référence éprouvée :

# -*- coding: utf-8 -*-
"""
watchdog_<nom_service>.py
Sentinelle résidente de surveillance 24/7 pour <nom_service>.
Système Jarvis / Antigravity — Conçu pour Raphaël (Guadeloupe UTC-4).
"""

import sys
import os
import time
import json
import psutil
import datetime
import subprocess
from pathlib import Path

WORKDIR = Path(r"C:\ASSISTANT_IA")
TARGET_SCRIPT = WORKDIR / "tools" / "<nom_service>.py"
WATCHDOG_PID_FILE = WORKDIR / "watchdog_<nom_service>.pid"
DAEMON_PID_FILE = WORKDIR / "<nom_service>.pid"
HEARTBEAT_FILE = WORKDIR / "<nom_service>_heartbeat.json"
STATE_FILE = WORKDIR / "watchdog_<nom_service>_state.json"
LOG_FILE = WORKDIR / "logs" / "watchdog_<nom_service>.log"
VBS_LAUNCHER = WORKDIR / "lance_watchdog_<nom_service>_invisible.vbs"

sys.path.insert(0, str(WORKDIR))
try:
    from telegram_reliable import send_telegram_reliable
except ImportError:
    def send_telegram_reliable(msg): return False

CHECK_INTERVAL_SECONDS = 3
MAX_HEARTBEAT_STALE_SEC = 120
MAX_CRASHES_WINDOW_SEC = 60
MAX_ALLOWED_CRASHES_IN_WINDOW = 5
BACKOFF_COOLDOWN_SEC = 30

def get_guadeloupe_time() -> str:
    utc_now = datetime.datetime.now(datetime.timezone.utc)
    guadeloupe_tz = datetime.timezone(datetime.timedelta(hours=-4))
    return utc_now.astimezone(guadeloupe_tz).strftime("%Y-%m-%d %H:%M:%S AST (UTC-4)")

def log(msg: str, level: str = "INFO"):
    ts = get_guadeloupe_time()
    line = f"[{ts}] [{level}] [WATCHDOG] {msg}"
    print(line, flush=True)
    LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
    with open(LOG_FILE, "a", encoding="utf-8") as f:
        f.write(line + "\n")

def is_target_healthy(pid: int) -> bool:
    if not pid or not psutil.pid_exists(pid):
        return False
    try:
        proc = psutil.Process(pid)
        if proc.status() in [psutil.STATUS_ZOMBIE, psutil.STATUS_DEAD]:
            return False
        # Vérification du Heartbeat
        if HEARTBEAT_FILE.exists():
            stale_delta = time.time() - HEARTBEAT_FILE.stat().st_mtime
            if stale_delta > MAX_HEARTBEAT_STALE_SEC:
                log(f"Heartbeat figé depuis {int(stale_delta)}s. Démon présumé gelé.", "WARNING")
                return False
        return True
    except (psutil.NoSuchProcess, psutil.AccessDenied):
        return False

def resurrect_target():
    log("Démarrage du processus managé...", "INFO")
    proc = subprocess.Popen(
        [sys.executable, str(TARGET_SCRIPT)],
        cwd=str(WORKDIR),
        creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0
    )
    DAEMON_PID_FILE.write_text(str(proc.pid), encoding="utf-8")
    send_telegram_reliable(f"✅ Démon {TARGET_SCRIPT.name} relancé avec succès (PID: {proc.pid})")
    return proc.pid

def run_loop():
    log("Sentinelle active. Début de la surveillance 24/7.", "INFO")
    # Boucle de scrutation réactive (<3s) avec gestion de crash-loop
    # ...

☑️ 5. Checklist d'Auto-Validation Avant Clôture de Mission

Avant de déclarer une tâche ou un script terminé, l'agent doit impérativement cocher cette checklist :