Diagnostic d'installation (coach-doctor)¶
/coach-doctor (ou python3 scripts/coach_doctor.py directement) vérifie
l'installation en une commande, sans rien écrire — et, par défaut, sans
appeler Garmin Connect (voir --probe-mcp plus bas).
Lancer¶
python3 scripts/coach_doctor.py
coach doctor — /chemin/vers/votre/workspace
❌ garmin_token Tokens Garmin expirés depuis 3 jour(s) (/home/alex/.garminconnect).
→ correctif : uv run garmin-mcp-auth
✅ garmin_mcp MCP garmin : commande « garmin-mcp » présente (/home/alex/.local/bin/garmin-mcp).
✅ config_files Configuration TOML valide (config/workspace.toml, config/workspace.user.toml).
✅ athlete_profile FC max et FC de repos renseignées dans le profil.
✅ index_freshness Index .arc/coach.db à jour.
✅ out_of_contract Aucun fichier hors contrat.
ℹ️ daily_sync_scheduled Aucun LaunchAgent daily-sync — synchronisation Garmin manuelle uniquement.
→ correctif : ./install.sh --daily-sync
⚠️ ntfy_configured ntfy activé mais aucun topic configuré.
→ correctif : scripts/setup-ntfy.sh
Au moins une vérification est en échec (❌) — voir les correctifs ci-dessus.
(Le chemin affiché est toujours le chemin ABSOLU résolu — ~/.garminconnect
n'apparaît jamais littéralement en sortie.)
Ce qui est vérifié¶
| Vérification | Détail | Sévérité |
|---|---|---|
garmin_token |
Âge/échéance des tokens Garmin (~/.garminconnect par défaut) |
⚠️ à moins de 14 jours de l'échéance, ❌ si expirés ou absents |
garmin_token_perms |
(source garmin, sinon ℹ️) Droits de ~/.garminconnect (ou du dossier résolu) et de ~/.garminconnect_base64 : dossier et fichiers de jetons inaccessibles au groupe/autres. Seuls les droits sont lus, jamais le contenu. Corrige : chmod 700 ~/.garminconnect && find ~/.garminconnect -type f -exec chmod 600 {} + (ou relancer ./install.sh) — GHSA-wjhr-76vg-2hvc |
⚠️ si lisibles par d'autres comptes, ℹ️ si aucun dossier de jetons |
garmin_mcp |
Présence/exécutabilité du binaire MCP garmin (aucun process lancé) |
❌ si la commande est introuvable ou non exécutable |
garmin_mcp_pin |
(source garmin, sinon ℹ️) Serveur garmin-mcp installé par uv tool au commit épinglé par install.sh (GARMIN_MCP_REF) ? Lu dans le direct_url.json (dist-info garmin_mcp-*), aucun réseau. La réinstallation au pin met à jour les dépendances transitives (correctifs de sécurité) et conserve les jetons |
⚠️ si le commit diffère du pin, ℹ️ pour une origine personnalisée ou illisible |
strava_connection |
(#164, source strava seulement, sinon ℹ️) Node.js 18+, wrapper, serveur strava déclaré, jetons présents et non lisibles par d'autres — valeurs jamais lues ni affichées, aucun appel réseau |
❌ si Node.js/wrapper/serveur/jeton de rafraîchissement manquent, ⚠️ si identifiants client absents ou fichier lisible par d'autres |
coros_connection |
(--coros seulement, sinon ℹ️) relais déclaré, pas masqué par un serveur coros ajouté à la main, jetons du projet avec jeton de rafraîchissement, droits 700/600 — valeurs jamais lues ni affichées ; --probe-mcp pour un appel réel |
❌ si relais absent ou compte non connecté (arc_coros_auth.py login), ⚠️ si une entrée manuelle masque le relais ou si les jetons sont lisibles par d'autres |
openwearables |
(#220, [health].source = "openwearables" seulement, sinon ℹ️) Fournisseur valide, adresse, fichier de clé d'API présent et en mode 600 (valeur jamais lue ni affichée). Puis, automatiquement, un seul appel à l'instance via arc_openwearables.py check (3 s par requête, sous-processus plafonné à 12 s ; --no-probe-ow pour rester hors ligne) |
❌ configuration incomplète, clé absente ou lisible par d'autres, fournisseur garmin/strava/inconnu, instance injoignable, clé refusée (401) ; ⚠️ fabricant non actif, synchro périmée, version non testée, plusieurs utilisateurs sans user_id |
config_files |
config/workspace.toml et config/workspace.user.toml sont du TOML valide |
❌ si absent ou invalide, ⚠️ si validation stricte indisponible (Python < 3.11) |
athlete_profile |
FC max / FC de repos renseignées dans planning/Runner_Profile.md |
ℹ️ sinon — le coach utilise le RPE à la place |
index_freshness |
.arc/coach.db à jour par rapport aux fichiers du workspace (y compris les fichiers supprimés) |
⚠️ si périmé ou si un fichier supprimé est encore indexé, ℹ️ si jamais construit |
out_of_contract |
Nombre de fichiers sans bloc ```arc conforme |
⚠️ si non nul |
daily_sync_scheduled |
Tâche cron (Linux) ou LaunchAgent (macOS) du daily-sync ; en mode watch, dernier passage de scripts/watch.py |
ℹ️ si non installé (choix valide) ; ⚠️ si le watcher est installé mais muet depuis plus de 3 intervalles |
ntfy_configured |
Notifications push configurées, si activées | ℹ️ si désactivées, ⚠️ si mal configurées |
gear_sync |
Synchronisation du matériel Garmin (#133) : la liste blanche GARMIN_ENABLED_TOOLS de .mcp.json contient get_gear et get_activity_gear, et les paires actives du profil portent un segment garmin: <uuid>. Statique — le doctor n'appelle jamais Garmin ; lister le matériel Garmin sans puce est fait par le coach (get_gear) |
⚠️ si la liste blanche est antérieure à #133 (relancer ./install.sh), ℹ️ si des paires actives ne sont pas associées (ou liste blanche illisible en mode passerelle), ℹ️ sous la source intervals.icu |
weight_sync |
Poids lu dans Garmin Connect (#222) : la liste blanche GARMIN_ENABLED_TOOLS contient get_daily_weigh_ins et get_weigh_ins (lecture seule). Statique — aucun appel Garmin |
ℹ️ si la liste blanche est antérieure à #222 (relancer ./install.sh ; en mode passerelle, éditer leanproxy_servers.yaml), ℹ️ sous une source autre que Garmin — jamais un avertissement : le poids reste déclaratif |
gear_history |
(#145) Historique sans matériel : au moins 5 séances avec garmin_activity_id, dont plus de la moitié sans gear_id (ℹ️, jamais ⚠️) — propose python3 scripts/garmin_gear_backfill.py (simulation). Statique : aucun appel Garmin. |
|
fit_reader |
fitparse présent dans l'environnement MCP de la source (garmin-mcp ou intervals-icu-mcp), pour lire les FIT téléchargés |
⚠️ si absent : zones, GAP, VAM… restent vides — relancer ./install.sh --source <source> |
intervals_mcp_pin |
(#165) Serveur intervals-icu-mcp installé par uv tool au commit épinglé par install.sh ? Lu dans le direct_url.json de son environnement — aucun réseau. Sans objet hors [data].source = "intervals" |
⚠️ si installé depuis l'ancien dépôt eddmann (outils sans préfixe icu_) — ./install.sh --source intervals puis nouvelle session ; ℹ️ si commit différent du pin, origine personnalisée ou illisible |
telegram |
(#174, [telegram].enabled seulement, sinon ℹ️) Liste blanche allowed_chat_ids non vide, fichier du jeton présent en mode 600 avec un TELEGRAM_BOT_TOKEN au bon format (valeur jamais affichée), jeton non exporté dans l'environnement, chat_bridge cohérent avec [chat], service vivant (battement .arc/telegram/heartbeat de moins de 5 min). Aucun appel réseau |
⚠️ au plus (un bot arrêté est une perte de confort), jamais ❌ |
telegram_chat |
(#337, expérimental ; ℹ️ tant que scripts/coach-telegram-chat.sh install n'a pas été lancé) Binaires claude, bun et tmux, plugin Telegram configuré (~/.claude/channels/telegram/.env), politique d'accès allowlist avec au moins un compte autorisé, jeton du plugin différent de celui de [telegram].token_file (deux processus en long polling sur le même bot : erreur 409), session tmux coach-telegram-chat vivante. Aucun jeton affiché, aucun appel réseau |
⚠️ au plus, jamais ❌ |
family_registry, family_tokens, family_ntfy, family_sync |
(#127, seulement si le registre family.toml est donné explicitement — --family ou ARC_FAMILY, jamais découvert tout seul ; jamais avec --check ni sous ARC_LOCK_WORKSPACE=1, pour ne pas décrire les autres membres depuis le chat d'un membre) Registre valide ; aucun dossier de jetons Garmin partagé entre deux membres ; un topic ntfy par membre ; une synchronisation planifiée par membre. Voir Mode famille. Aucun appel réseau |
❌ si le registre est invalide ; ⚠️ si des jetons ou un topic sont partagés ; ℹ️ si la synchronisation d'un membre n'est pas détectée |
Un ❌ fait échouer la commande (code de sortie non nul). Un ⚠️ ou un ℹ️ jamais — ce sont des dégradations connues, pas des pannes.
garmin_mcp : présence par défaut, handshake réel en option¶
Lancer réellement garmin-mcp déclenche une connexion à Garmin Connect avant
même de répondre au protocole MCP (voir la docstring de
check_garmin_mcp_presence dans scripts/coach_doctor.py) : réseau, retries,
et une possible réécriture des tokens. coach doctor s'en tient donc par
défaut à vérifier que le binaire configuré existe et est exécutable.
Le contrôle llm_config reprend python3 scripts/arc_llm.py check (#268) : cohérence runner / backend / modèle / clé, puis jeton d'abonnement ChatGPT / Copilot dans le magasin du coach, OPENCODE_DISABLE_DEFAULT_PLUGINS. Il reste statique (aucun appel réseau) ; --probe-llm ajoute l'appel minimal au fournisseur (clé OpenRouter valide, crédit, quota gratuit du jour, liste des modèles Anthropic / compatible OpenAI) et ne fait jamais plus qu'un avertissement. Détail et actions : Dépannage — La connexion IA.
Un vrai handshake MCP initialize, borné dans le temps, reste disponible :
python3 scripts/coach_doctor.py --probe-mcp # CONTACTE Garmin Connect
Le contrôle openwearables (#220) fait, lui, un appel d'office quand la configuration est complète : à l'instance
Open Wearables de l'athlète, jamais à un tiers (un seul arc_openwearables.py check, 3 s par requête,
sous-processus plafonné à 12 s). --no-probe-ow le garde hors ligne.
Méthode de détection de l'échéance des tokens¶
Le client garminconnect vendored par garmin-mcp ne lit/écrit qu'un seul
fichier : garmin_tokens.json — c'est donc TOUJOURS lui qui fait foi quand il
est présent, même si un oauth2_token.json (format garth, jamais produit
par cette installation) traîne encore d'une ancienne configuration.
garmin_tokens.json(le fichier réel) ne contient aucune échéance longue durée exploitable : sondi_tokenest un JWT dont le claimexpcorrespond à une session courte (régénérée automatiquement, ~1 jour), etdi_refresh_tokenn'est pas un JWT. Repli : date de dernière modification du fichier + une fenêtre de validité d'environ 6 mois — voir Dépannage. Limite connue : ce fichier est réécrit à chaque rafraîchissement automatique du token, ce qui repousse la mtime (donc l'échéance estimée) sans que la session ait réellement été renouvelée pour 6 mois de plus — ne traitez pasmtime_fallbackcomme une garantie, seulement comme la meilleure estimation disponible.oauth2_token.json(formatgarth) n'est utilisé QUE sigarmin_tokens.jsonest absent : son champ expliciterefresh_token_expires_atsert alors de signal.
Aucun contenu de token n'est jamais affiché : seuls des métadonnées (chemin, date d'échéance, nombre de jours restants) apparaissent en sortie.
Sortie machine¶
python3 scripts/coach_doctor.py --json
python3 scripts/coach_doctor.py --json --check garmin_token # une seule vérification (#32)
Un objet par vérification (id, status, message, fix), plus
expires_at/days_left/source pour garmin_token — schéma complet en tête
de scripts/coach_doctor.py. Conçue pour être réutilisée telle quelle par
l'alerte ntfy avant expiration des tokens (#32).
Options utiles¶
python3 scripts/coach_doctor.py --workspace /chemin/vers/le/workspace
python3 scripts/coach_doctor.py --tokens-dir /chemin/de/test # override du répertoire de tokens
python3 scripts/coach_doctor.py --now 2026-09-24T12:00:00+00:00 # horloge figée (tests)
python3 scripts/coach_doctor.py --check garmin_token # une seule vérification, sans MCP
python3 scripts/coach_doctor.py --probe-mcp # handshake MCP réel (contacte Garmin)
python3 scripts/coach_doctor.py --probe-llm # connexion IA : appel réseau minimal vers le fournisseur (#268)
python3 scripts/coach_doctor.py --check openwearables --no-probe-ow # Open Wearables sans appel réseau (#220)
Quand le lancer¶
- Avant toute autre investigation : synchronisation en échec, erreur MCP, agent qui semble se comporter bizarrement.
- Après une réinstallation ou un changement de machine.
- Périodiquement, en curiosité — par défaut, il ne modifie rien et ne contacte personne.