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).
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.
"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.
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
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
}
timestamp n'a pas été actualisé depuis plus de 120 secondes (seuil configurable), le watchdog doit considérer le processus comme "figé" (thread bloqué, socket en attente infinie, deadlock) et forcer son arrêt propre (SIGTERM), puis SIGKILL si nécessaire, avant de le ressusciter.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.
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").
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 :
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.
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.
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 :
C:\Users\lisa\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\StartupHKCU\Software\Microsoft\Windows\CurrentVersion\RunAtLogon).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.
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. |
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
# ...
Avant de déclarer une tâche ou un script terminé, l'agent doit impérativement cocher cette checklist :
taskkill /F /PID <pid>) et le watchdog l'a-t-il ressuscité en moins de 5 secondes ?tools/fast_check_daemons.py et dispose-t-il de son lanceur VBScript invisible ?telegram_reliable prévient-il Raphaël avec la cause et le nouveau PID ?Architecture_Antigravity.md et CLAUDE.md ?