@imenam/mcp-messenger 1.0.29 → 1.0.31

package/README.md

@@ -1,707 +1,764 @@
-# MCP Messenger
-
-Boîte aux lettres pour agents IA : un **serveur** central reçoit et conserve les messages,
-et un **client MCP** donne à chaque agent — quelle que soit sa plateforme — les outils pour
-écrire, lire, classer et attendre des réponses.
-
-Le même paquet joue les deux rôles :
-
-| | Mode serveur (`--server`) | Mode MCP (sans argument) |
-|---|---|---|
-| Rôle | Boîte aux lettres : stockage, distribution, annuaire | Client stdio branché sur un agent |
-| Exposé sur | HTTP/HTTPS (API + console web) | stdin/stdout (JSON-RPC MCP) |
-| Consommé par | Les MCP des agents, la console web | Claude Code, Cursor, tout client MCP |
-| Variables clés | `MESSENGER_PORT`, `MESSENGER_TOKEN` | `MESSENGER_AGENT_ID`, `MESSENGER_SERVER_URL`, `MESSENGER_TOKEN` |
-| Processus | 1 pour toute la flotte | 1 par agent |
-
-```mermaid
-flowchart LR
-    A["Agent A (Claude Code)"] -- "stdio" --> MA["mcp-messenger (MCP)"]
-    B["Agent B (Cursor)"] -- "stdio" --> MB["mcp-messenger (MCP)"]
-    C["Agent C (autre plateforme)"] -- "stdio" --> MC["mcp-messenger (MCP)"]
-    MA -- "HTTP(S)" --> S
-    MB -- "HTTP(S)" --> S
-    MC -- "HTTP(S)" --> S
-    S["mcp-messenger --server\nSQLite + API + console"] --> U["Console web /ui"]
-```
-
-Les agents n'ont pas besoin d'être sur la même machine ni sur la même plateforme : ils
-partagent seulement l'adresse du serveur. **Chaque session d'agent reçoit sa propre boîte**,
-identifiée par une adresse opaque du type `box_9f2c4a01b3d7e5f8` — voir
-[Adresses et sessions](#adresses-et-sessions).
-
----
-
-## Démarrage rapide
-
-### 1. Lancer la boîte aux lettres
-
-```bash
-# Deux jetons distincts : celui des agents, et celui de la console.
-npx @imenam/mcp-messenger --generate-token   # → jeton client
-npx @imenam/mcp-messenger --generate-token   # → jeton console
-
-MESSENGER_TOKEN=<jeton-client> MESSENGER_ADMIN_TOKEN=<jeton-console> \
-  npx @imenam/mcp-messenger --server
-# → listening on http://127.0.0.1:3600 (loopback only)
-# → auth: shared token — required on every request
-# → WARN shared token: no isolation between mailboxes — any holder can act as any address
-# → WARN set MESSENGER_AGENT_TOKENS (one token per agent) to compartmentalize
-# → web console: http://127.0.0.1:3600/ui/ (asks for MESSENGER_ADMIN_TOKEN once)
-```
-
-Trois invariants, non négociables et vérifiés par les tests :
-
-1. **Le serveur écoute toujours sur `127.0.0.1`.** `MESSENGER_HOST` n'est pas un réglage :
-   toute autre valeur fait échouer le démarrage. Pour joindre la boîte depuis une autre
-   machine, il faut placer un reverse proxy (TLS) devant.
-2. **Un jeton est obligatoire et vérifié sur chaque requête de données** — API, `/health`
-   et données de la console (`/admin`) comprises. Seule la page de la console, qui ne
-   contient aucun secret, est servie librement. Sans `MESSENGER_TOKEN` ni
-   `MESSENGER_AGENT_TOKENS`, le serveur refuse de démarrer.
-3. **Le jeton de la console n'est jamais celui des agents.** `MESSENGER_ADMIN_TOKEN` est
-   exigé dans tous les cas, et le démarrage échoue s'il vaut `MESSENGER_TOKEN`. La console
-   voit toutes les boîtes de tous les projets et sait les supprimer, alors que le jeton
-   client est recopié dans le `.mcp.json` de chaque projet : les confondre donnerait ce
-   pouvoir à tout porteur de ce fichier.
-
-> **Le mode jeton partagé ne cloisonne pas les boîtes.** `MESSENGER_TOKEN` atteste
-> l'appartenance à la flotte, pas une adresse : l'en-tête `X-Agent-Id` qui accompagne chaque
-> appel n'est alors adossé à rien, et tout porteur du jeton peut lire, envoyer et supprimer
-> au nom de n'importe quelle boîte. C'est un mode « cercle de confiance », adapté aux
-> sessions d'une même personne sur une même machine — le serveur le rappelle au démarrage.
-> Dès que les agents ne se font pas mutuellement confiance, passer à
-> [`MESSENGER_AGENT_TOKENS`](#serveur), qui lie chaque adresse à son propre
-> jeton et rejette toute autre combinaison.
-
-### 2. Déclarer le MCP côté agent
-
-Dans le dossier du projet de l'agent :
-
-```bash
-npx -y @imenam/mcp-messenger --claude-setup-mcp
-```
-
-La commande écrit l'entrée `mcp-messenger` dans le `.mcp.json` du répertoire courant (les
-autres serveurs sont préservés ; `--force` pour remplacer une entrée existante), avec un
-`MESSENGER_AGENT_ID` pré-rempli d'après le nom du dossier. Il ne reste qu'à coller le jeton
-du serveur dans `MESSENGER_TOKEN`.
-
-Le bloc généré, à écrire à la main si tu préfères :
-
-```json
-{
-  "mcpServers": {
-    "messenger": {
-      "command": "npx",
-      "args": ["@imenam/mcp-messenger"],
-      "env": {
-        "MESSENGER_AGENT_ID": "planner",
-        "MESSENGER_SERVER_URL": "http://127.0.0.1:3600",
-        "MESSENGER_TOKEN": "le-jeton-du-serveur",
-        "MESSENGER_AGENT_NAME": "Planner",
-        "MESSENGER_AGENT_DESCRIPTION": "Découpe les tâches et répartit le travail"
-      }
-    }
-  }
-}
-```
-
-Chaque agent reçoit le même bloc avec **son propre** `MESSENGER_AGENT_ID`. Au démarrage, le
-MCP s'enregistre dans l'annuaire du serveur ; si le serveur est momentanément injoignable,
-la session MCP démarre quand même et l'enregistrement se fera au premier appel réussi.
-
-### 3. Écrire à un autre agent
-
-L'agent A appelle `send_message` avec `to: ["coder"]`, l'agent B voit le message via
-`list_messages` puis `read_message`, et répond avec `reply_to` pour rester dans le fil.
-Le fil se nomme au passage (`thread_name` sur `send_message`, ou `rename_thread` plus tard).
-`wait_for_message` permet d'attendre une réponse sans faire tourner une boucle d'appels : il ne
-rend la main que sur un message arrivé *après* le début de l'attente, les non-lus déjà en boîte
-ne l'interrompent pas.
-
----
-
-## Être notifié sans attendre
-
-Attendre coûte un tour d'agent. Pour rester joignable **sans rien bloquer**, l'agent active
-les notifications une fois en début de session ; ensuite il travaille normalement, et les
-messages entrants l'interrompent d'eux-mêmes — y compris quand il est à l'arrêt, inactif.
-
-```
-enable_notifications()      → retourne immédiatement, ne bloque rien
-
-  Notifications enabled for mailbox `box_9f2c4a01b3d7e5f8`.
-
-  Last step — call the Monitor tool now, with exactly these arguments:
-    command:     npx -y @imenam/mcp-messenger --watch box_9f2c4a01b3d7e5f8
-    description: Incoming messenger messages
-    timeout_ms:  1800000
-```
-
-L'agent recopie ces trois arguments dans l'outil `Monitor` de son hôte. Le veilleur tourne en fond, tient une attente longue sur `/api/wait`, et écrit **une
-ligne par message** sur sa sortie standard :
-
-```
-[messenger] planner — Refacto prêt (msg_4c1e88a0b2)
-```
-
-Chaque ligne réveille l'agent, qui appelle `read_message` s'il décide de traiter le message.
-
-**Réarmer à l'expiration.** Claude Code arrête tout `Monitor` au bout de 30 minutes au plus,
-quelle que soit la durée demandée, et prévient l'agent. Ce minuteur appartient à l'hôte : le
-veilleur ne peut ni le prolonger ni le remettre à zéro. L'agent relance donc le même appel
-`Monitor` à chaque expiration, sans repasser par `enable_notifications` — la réponse de cet
-outil, les instructions du serveur et le bloc `CLAUDE.md` le lui disent. Le délai de grâce
-décrit plus bas couvre l'intervalle : `whoami` reste à « armed » pendant le réarmement.
-
-**Pourquoi deux appels et pas un.** Armer un réveil, c'est ouvrir un canal vers la boucle de
-la session hôte. Un serveur MCP ne peut pas le faire seul : `Monitor` est un outil de l'hôte,
-seul le modèle peut l'appeler. `enable_notifications` fait donc tout le reste — il connaît
-l'adresse, il prépare le terrain — et rend la commande exacte à recopier. L'agent ne compose
-rien.
-
-**Où passe le jeton.** Le veilleur est lancé par l'hôte dans le shell de la session : il
-n'hérite pas du bloc `env` du `.mcp.json`, donc ni de `MESSENGER_SERVER_URL` ni de
-`MESSENGER_TOKEN`. Les mettre sur la ligne de commande les afficherait dans la conversation.
-`enable_notifications` dépose donc un relais en `0600` sous `~/.mcp-messenger/watch/`
-(`MESSENGER_STATE_DIR` pour le déplacer), que `--watch` retrouve à partir de la seule adresse.
-Le fichier est nommé par hachage de l'adresse, supprimé à la fin de la session, et purgé au
-bout de sept jours si la session s'est arrêtée brutalement.
-
-**Savoir si c'est vraiment armé.** L'armement dépend de l'agent : rien ne peut le déclencher
-à sa place, et un agent qui saute l'étape se croirait joignable sans l'être. Le serveur suit
-donc les attentes tenues par un veilleur, et `whoami` le dit :
-
-```
-Notifications: armed — incoming messages will interrupt you (watcher since 2026-09-07T13:31:00.203Z).
-Notifications: NOT armed — no incoming message will reach you. Call enable_notifications.
-```
-
-C'est une présence de connexion, pas une donnée stockée : elle vit en mémoire du serveur et
-disparaît avec lui. Un `wait_for_message` ordinaire ne compte pas — il s'arrête au premier
-message, un veilleur reste. Entre deux attentes longues, un délai de grâce de deux minutes
-évite que le signalement clignote. `enable_notifications` s'en sert aussi : si un veilleur est
-déjà en place, il le dit et n'en fait pas armer un second, qui doublerait chaque notification.
-
-**Ce que ça ne couvre pas.** Le veilleur n'annonce que les messages arrivés **après** son
-démarrage : `enable_notifications` signale le nombre de non-lus déjà en boîte, à traiter avec
-`list_messages`. Et `--claude-setup-mcp` écrit un rappel d'armement dans le `CLAUDE.md` du
-projet, pour que l'étape ne soit pas oubliée en début de session.
-
-**Sur un autre hôte que Claude Code.** `--watch` est une commande ordinaire : n'importe quel
-superviseur capable de lire les lignes d'un processus peut la brancher. Sans relais, elle lit
-`MESSENGER_SERVER_URL`, `MESSENGER_TOKEN` et `MESSENGER_AGENT_ID` dans son environnement.
-
----
-
-## Outils MCP
-
-**Deux mots, deux choses.** Une **boîte** (`mailbox` dans les outils) est une adresse
-`box_…` : elle désigne une session, et c'est à elle qu'on écrit. Un **nom d'agent** est le
-projet pour lequel une session travaille : c'est une étiquette, jamais une adresse, et
-toutes les sessions du projet la portent. Partout où un outil attend une adresse, sa
-description dit « mailbox address ».
-
-| Outil | Rôle |
-|---|---|
-| `whoami` | Adresse de cette session, serveur connecté, veilleur armé ou non, compteurs par dossier |
-| `attach_to_mailbox` | Se brancher sur une autre boîte via son adresse ; sans argument, retour à la sienne |
-| `rename_mailbox` | Nommer ou renommer sa boîte (de quoi la session s'occupe) ; le nom de l'agent, posé par la configuration, reste |
-| `rename_thread` | Nommer ou renommer un fil (`thread_id`) ; le nom est partagé par tous ses participants |
-| `list_threads` | Carte des conversations : nom, participants, non-lus, dernière activité ; `with_mailbox` ne garde que celles partagées avec une boîte |
-| `list_agents` | Annuaire groupé par agent : un projet, ses sessions ; `agent_name` déplie un groupe. La boîte de l'appelant n'y figure pas |
-| `send_message` | Écrire à un agent — un seul destinataire par message (`to`, `priority`, `reply_to`, `thread_name`) |
-| `list_messages` | Lister la boîte (filtres : dossier, non lus, expéditeur, fil, texte libre) |
-| `read_message` | Lire un message en entier ; le marque lu par défaut |
-| `get_thread` | Relire toute une conversation, du plus ancien au plus récent |
-| `mark_messages` | Marquer lu / non lu, suivi / non suivi |
-| `move_messages` | Classer dans un dossier |
-| `delete_messages` | Corbeille, ou suppression définitive (`permanent: true`) |
-| `list_folders` | Dossiers avec totaux et non-lus |
-| `create_folder` / `delete_folder` | Organiser l'espace comme une messagerie |
-| `enable_notifications` | Prépare la notification passive et rend la commande `Monitor` à armer ; ne bloque rien |
-| `wait_for_message` | Attente longue (jusqu'à 300 s) jusqu'à l'arrivée d'un message *postérieur* à l'appel |
-
-**Noms lisibles** — voir « Nommer les boîtes et les fils » ci-dessous.
-
-**Un message, deux boîtes** — un échange lie exactement deux agents *distincts* : `to` prend
-une seule adresse, il n'y a ni diffusion ni copie, et une boîte ne peut pas s'écrire à
-elle-même. Pour toucher plusieurs agents, on leur envoie un message chacun, dans son propre
-fil. C'est aussi pourquoi `list_agents` ne montre jamais l'appelant : la seule adresse qu'il
-ne peut pas viser n'a pas à figurer dans son annuaire.
-
-**Dossiers système** — toujours présents, non supprimables : `inbox`, `sent`, `archive`,
-`trash`. Les dossiers personnalisés sont propres à chaque boîte.
-
-**Ce que voit un agent** : uniquement les livraisons de la boîte à laquelle il est attaché. Un message adressé à `coder`
-est invisible pour tout autre agent, y compris via son identifiant. Supprimer un message ne
-touche que sa propre copie : l'autre partie garde la sienne.
-
----
-
-## Adresses et sessions
-
-Une adresse n'est pas un rôle, c'est une **boîte**. Au démarrage, chaque processus MCP —
-donc chaque session d'agent — s'en fait allouer une, avec un identifiant opaque et unique :
-
-```
-box_9f2c4a01b3d7e5f8
-```
-
-Conséquence directe : deux sessions ouvertes dans le même projet, avec le même `.mcp.json`,
-ont deux boîtes distinctes et ne se volent pas leur courrier.
-
-### Faire communiquer deux agents
-
-Le plus souvent, il n'y a rien à faire : l'agent B ouvre `list_agents` et y trouve
-l'adresse de A. C'est le chemin normal, et le seul qui ne puisse pas se tromper.
-
-Si tu veux désigner toi-même l'interlocuteur :
-
-1. Demande son adresse à l'agent A (`whoami`) — il te la donne, c'est à toi qu'elle est due.
-2. Transmets-la à l'agent B, qui l'utilise dans `send_message`.
-
-Dans les deux cas, une adresse ne circule jamais **dans** un message : le serveur y attache
-déjà l'expéditeur et le destinataire. Un agent qui recopie une adresse dans un corps de
-message écrit une information que le lecteur a déjà, et qui sera fausse le jour où il se
-trompe de session.
-
-Comme les adresses sont opaques, demande aux agents de nommer leur boîte
-(`rename_mailbox`) : le nom apparaît dans `list_agents` et dans la console web, ce
-qui permet de retrouver une adresse perdue.
-
-### Deux noms par boîte : l'agent et la boîte
-
-Une boîte porte deux identités, qui répondent à deux questions différentes et ne changent
-pas au même rythme :
-
-| | D'où vient-il ? | De quoi s'occupe-t-il ? |
-|---|---|---|
-| Champ | `agent_name`, `agent_description` | `display_name`, `description` |
-| Posé par | la configuration (`MESSENGER_AGENT_NAME`, `MESSENGER_AGENT_DESCRIPTION`) | l'agent lui-même, via `rename_mailbox` |
-| Change | jamais depuis une session | librement, au fil du travail |
-| Exemple | `Ai Corrector Dev` | `Correction du parseur de copies` |
-
-Le nom de l'agent seul ne distingue pas deux sessions ouvertes sur le même projet ; le nom
-de la boîte seul ne dit pas d'où l'agent écrit. `whoami` et la console web montrent donc
-toujours les deux, et l'annuaire (`list_agents`) les met l'un sous l'autre : le nom de
-l'agent en tête de groupe, une ligne par boîte en dessous. Renommer la boîte ne touche
-jamais au nom de l'agent.
-
-**Un nom d'agent ne désigne personne.** C'est le piège de ce modèle : plusieurs boîtes
-portent le même `agent_name`, une par session lancée depuis la même configuration.
-L'annuaire le rend visible en groupant les boîtes sous leur nom d'agent — un groupe à
-plusieurs lignes, ce sont plusieurs sessions vivantes du même projet, chacune à sa propre
-adresse. Un groupe nombreux n'affiche que ses trois sessions les plus récentes ;
-`list_agents` avec `agent_name` donne le reste, sans imposer ce second appel dans le cas
-courant. Un agent
-qui croise son propre nom d'agent dans l'annuaire regarde une *autre* session du même
-projet, jamais la sienne — sa boîte, elle, n'y figure pas du tout. Seule l'adresse identifie
-une session. Ce rappel est servi à trois endroits, du plus tôt au plus tard : les
-instructions du serveur MCP (reçues à la connexion, avant le premier outil), la ligne qui
-suit `Agent:` dans `whoami`, et le pied de l'annuaire dans `list_agents`.
-
-**Les adresses ne se recopient pas à la main.** Le serveur attache l'expéditeur et le
-destinataire à chaque message, et le lecteur les voit dans l'en-tête. Écrire son adresse
-dans le corps n'ajoute rien et se met à mentir dès qu'elle est erronée ou périmée —
-`send_message` le dit dans sa description et dans celle de `body`.
-
-### Nommer les boîtes et les fils
-
-Les identifiants (`box_…`, `thr_…`) ne disent rien de ce qui se passe. Deux noms en langue
-naturelle viennent par-dessus, un outil pour chacun :
-
-```
-rename_mailbox(name: "Développement des tests unitaires du parser")
-    → nomme la boîte de la session (le nom de l'agent reste)
-
-rename_thread(thread_id: "thr_…", name: "Le test échoue sur un bug applicatif")
-    → nomme le fil
-```
-
-Le plus simple reste de nommer un fil au moment où on l'ouvre, via `thread_name` sur
-`send_message` : l'agent qui écrit le premier message sait déjà de quoi il parle.
-
-L'ancien outil `set_label`, qui cumulait les deux rôles, reste accepté sans être publié :
-une session lancée avant la mise à jour peut encore l'appeler.
-
-Un fil n'a **qu'un seul nom, partagé par tous ses participants** — ils discutent du même
-sujet, ils doivent lire le même intitulé. N'importe quel participant peut le renommer, et
-le dernier a le dernier mot ; le serveur retient qui (`named_by`). Un agent extérieur au
-fil ne peut pas le renommer.
-
-Tant qu'un fil n'a pas été nommé, l'affichage retombe sur le sujet de son message
-d'ouverture : rien n'est jamais illisible, mais rien n'est aussi parlant qu'un nom choisi.
-Ces noms apparaissent dans `list_threads`, `list_messages`, `get_thread`, les
-notifications du veilleur et la console web.
-
-### Reprendre le travail d'une session interrompue
-
-Une session relancée est un nouveau processus. Sans mémoire, elle se ferait allouer une
-boîte neuve et laisserait derrière elle ses fils, ses non-lus et **l'adresse que ses
-correspondants connaissent** ; répété, cela multiplie les boîtes pour un travail unique.
-La session retrouve donc la sienne toute seule, par un **registre local**.
-
-Chaque session y inscrit sa boîte, avec l'empreinte de son projet et la preuve qu'elle
-vit : le processus qui la tient et un battement de cœur. **Une boîte tenue par une session
-vivante n'est jamais reprise** — c'est ce qui distingue ce mécanisme d'une adresse
-partagée, et ce qui protège deux sessions ouvertes en parallèle sur le même projet. Une
-boîte n'est reprenable qu'une fois **orpheline** : session close proprement, processus
-mort, ou battement arrêté depuis plusieurs minutes.
-
-Au démarrage, une seule chose est attribuée d'office, et seulement sur certitude :
-
-1. **Le même identifiant de session.** L'hôte en donne un à sa session, et le processus MCP
-   en hérite. Une session reprise sous le même identifiant retrouve exactement sa boîte.
-   Rien n'est à configurer : la variable est lue dans l'environnement
-   (`CLAUDE_CODE_SESSION_ID` et équivalents), et `MESSENGER_SESSION_KEY` permet de la poser
-   soi-même pour des sessions lancées par script. Ni le projet ni cet identifiant ne sont
-   écrits en clair : le registre n'en garde que l'empreinte. Le passage d'une autre session
-   par la boîte n'efface pas ce lien : le registre retient toutes les sessions qui l'ont
-   tenue, et la session d'origine la retrouve dès qu'elle redevient libre.
-2. **Le choix de l'agent, pour tout le reste.** Aucune boîte n'est attribuée sur une
-   ressemblance. Être la seule boîte libre du projet ne prouve rien : le répertoire et le
-   nom d'agent sont communs à toutes les sessions, y compris celles qui n'existaient pas
-   quand cette boîte s'est remplie. Les orphelines qui ont servi sont donc **proposées** :
-   `whoami` les liste avec leur nom, leur nombre de messages et leurs non-lus, et l'agent
-   rattache la bonne avec `attach_to_mailbox`. Les instructions du serveur MCP lui disent
-   aussi de rattacher une adresse `box_…` qu'il reconnaîtrait dans son propre contexte —
-   reconnaître sa propre adresse est une preuve, être la seule boîte libre n'en est pas une.
-
-Quand aucune boîte n'a pu être rattachée, `whoami` le dit en toutes lettres : cette adresse
-est neuve, et si l'agent écrivait d'une autre avant, ses correspondants écrivent toujours à
-celle-là. Sans cette ligne, une conversation reprise croirait garder son adresse d'avant.
-
-Il n'y a rien à régler : la recherche a toujours lieu, et son résultat ne dépend que de ce
-que l'hôte transmet. Le journal du démarrage dit quel chemin a servi et quelle variable a
-fourni l'identifiant de session — c'est là qu'on vérifie ce que l'hôte transmet réellement.
-
-Le rattachement manuel reste disponible en toutes circonstances :
-
-> « Reprends le travail de la session précédente, sa boîte est `box_9f2c4a01b3d7e5f8`. »
-
-L'agent appelle `attach_to_mailbox` avec cette adresse : il lit alors le courrier de cette
-boîte, y compris les messages arrivés pendant l'interruption, et écrit sous cette adresse.
-`attach_to_mailbox` sans argument le ramène à sa propre boîte. Plusieurs sessions peuvent
-être attachées à la même boîte — c'est volontaire, et c'est ce qui permet la reprise. La
-boîte rattachée devient celle que la session travaille : c'est elle que sa prochaine
-reprise retrouvera.
-
-L'adresse est vérifiée avant le basculement : une faute de frappe renvoie
-`mailbox not found` au lieu de créer silencieusement une boîte vide.
-
-Le registre est un fichier par boîte, en 0600, sous `~/.mcp-messenger/mailboxes/`
-(`MESSENGER_STATE_DIR` pour le déplacer). Il est purement local : le serveur n'en sait
-rien, et une entrée qu'aucune session n'a touchée depuis un mois est oubliée.
-
-### Adresse fixe (cas particulier)
-
-Renseigner `MESSENGER_AGENT_ID` fige l'adresse : toutes les sessions utilisant cette
-configuration partagent alors la même boîte. Utile pour un service unique et stable, à
-éviter pour des sessions interactives multiples.
-
----
-
-## Console web
-
-`http://127.0.0.1:3600/ui/` affiche **tous les échanges** de la flotte,
-organisés autour du fil — l'unité d'une correspondance, celle qui porte le sujet, les deux
-correspondants et l'état de lecture :
-
-- **une colonne d'agents à deux niveaux** : un agent tient une boîte par session ouverte,
-  la colonne l'écrit donc ainsi. Une boîte que son agent n'a pas nommée s'affiche à son
-  adresse, la seule chose qui la distingue alors de ses sœurs.
-
-  **Deux gestes, deux effets, sans recouvrement.** Cliquer le nom d'un agent filtre les
-  fils sur **toutes ses sessions**, cliquer une boîte sur **cette seule session** ; le
-  chevron, lui, déplie ou replie les boîtes sans toucher au filtre. Chaque agent est
-  **replié par défaut**, et sélectionner un agent n'ouvre rien. Recliquer ne relâche rien
-  non plus : on revient à la vue générale par « Tous les agents », en tête de colonne. La
-  colonne se replie sur les seuls avatars d'agents quand la place manque, son bouton de
-  repli restant en place : c'est lui qui la rouvre. **Repliée, elle garde deux signes
-  distincts** : l'anneau désigne l'agent sélectionné, la pastille bleue dit qu'il reste du
-  non-lu — la même convention que le point de la liste des fils.
-
-  **Le classement se fait en deux temps : d'abord ce qui a servi, ensuite ce qui est
-  vide ; puis, dans chacun des deux, la dernière activité, la plus récente en tête.** Une
-  boîte est vide tant que rien n'y est passé, ni envoi ni réception — le serveur en alloue
-  une par session ouverte, et beaucoup n'échangeront jamais rien. Ces boîtes-là sont
-  **masquées par défaut**, derrière un bouton en fin de dépli qui dit combien il y en a ;
-  les masquer ne cache jamais de courrier, une boîte sans réception n'ayant par
-  construction aucun non-lu. **Un agent dont aucune session n'a rien échangé est masqué de
-  la même façon**, derrière un bouton en pied de colonne : même geste, un cran plus haut.
-  Chaque boîte affiche la date qui la classe, et deux dates
-  identiques sont départagées par l'adresse pour que l'ordre ne bouge pas d'un
-  rafraîchissement à l'autre ;
-- **la liste des fils**, du plus récemment actif au plus ancien, chacun résumé par son
-  nom, ses correspondants, son dernier message et sa priorité la plus haute. Les deux
-  correspondants y sont d'abord **deux pastilles côte à côte**, séparées et non superposées
-  — leurs initiales doivent rester lisibles. **Ces pastilles sont celles des agents, pas
-  des boîtes** : dans une liste, ce qu'on cherche du regard est le projet, et deux sessions
-  d'un même agent portent donc la même. Ce qui les distingue, le nom de la boîte, se lit au
-  survol, avec le projet, l'adresse et la mention de celle qui a écrit en dernier. Le
-  lecteur du fil suit la même règle, en tête de chaque message ;
-- **un en-tête qui dit sur quoi la liste est filtrée** : sans filtre elle s'intitule
-  « Fils », et dès qu'un agent est choisi c'est lui le sujet — sa pastille en grand, son
-  nom en titre, et en dessous ce que le filtre recouvre, toutes ses sessions ou une seule ;
-- **trois puces** au-dessus de la liste : tous, non lus, priorité haute ;
-- **le lecteur du fil** : la conversation entière dans l'ordre, un bloc par message, avec
-  qui écrit à qui — en clair, pas en adresses — et une pastille disant si le destinataire
-  l'a lu. **Les messages s'ouvrent repliés** : chacun tient alors sur sa ligne d'identité —
-  pastille, qui écrit à qui, heure — et sur **l'objet du message**, qui est ce qui
-  l'identifie. Les deux forment le bandeau qui l'ouvre et le referme, cliquable d'un bout à
-  l'autre et grisé au survol pour se donner à voir comme une cible. Ouvrir un message ne
-  change rien à ce bandeau : le corps vient simplement se poser dessous. Le destinataire
-  n'y figure pas — un fil ne lie que deux boîtes, le répéter à chaque ligne n'apprend
-  rien ;
-  Un fil se parcourt avant de se lire, et le rafraîchissement automatique ne referme pas
-  ce qui est en train d'être lu. **Le corps d'un message est rendu comme du markdown** : titres, listes,
-  citations, tableaux, blocs de code, emphase et liens. C'est la langue dans laquelle les
-  agents s'écrivent, la console la lit donc ainsi plutôt que d'afficher sa syntaxe. Le
-  rendu construit des nœuds un par un et n'insère jamais de HTML : rien de ce qu'un agent
-  écrit ne peut devenir une balise, et seuls les liens `http`, `https` et `mailto` sont
-  suivis. Une image n'est jamais chargée, elle est montrée par son intitulé et son lien.
-  Les aperçus, eux, sont débarrassés de leur syntaxe par le serveur : ils tiennent sur une
-  ligne, où un dièse ou une paire d'astérisques ne serait que du bruit ;
-- **les détails d'un message**, dans une modale ouverte par l'icône d'information au bout
-  de sa ligne : l'objet, le nom et l'identifiant du fil, les identifiants, la date, la
-  priorité, les deux noms et l'adresse de chaque boîte, et le tableau de distribution
-  (rôle, dossier, état). Tout ce qui se recopie a son bouton de copie ;
-- une recherche unique, qui couvre le nom d'un fil, sa description et le texte de ses
-  messages ;
-- **des panneaux redimensionnables** : chaque ligne de séparation se saisit à la souris,
-  se règle aussi aux flèches du clavier une fois qu'elle a le focus, et rend sa largeur
-  d'origine sur un double-clic. Les largeurs choisies sont retenues par le navigateur d'une
-  visite à l'autre ;
-- un rafraîchissement automatique toutes les 5 secondes, débrayable.
-
-**Les adresses ne sont pas de l'information de lecture.** La console résout partout
-`box_9f2c4a01b3d7e5f8` en nom d'agent, et ne montre l'adresse qu'aux endroits où elle sert
-vraiment : les détails d'un message, l'en-tête d'un fil et les boîtes sans nom, chaque fois
-avec un bouton de copie. Quand plusieurs sessions d'un même projet apparaissent, le nom de
-l'agent est suivi de celui de la boîte entre parenthèses — sans quoi un fil se lirait
-« Documentor Dev → Documentor Dev » sans dire de quelles sessions il parle. Une boîte jamais connectée se distingue à son avatar en contour et à la mention
-« jamais connectée » — elle reste listée, puisqu'elle a du courrier en attente.
-
-À l'ouverture, la console demande `MESSENGER_ADMIN_TOKEN` dans un formulaire. Le serveur
-le vérifie (`POST /ui/login`) et ouvre une **session** de 12 heures, portée par un cookie
-`HttpOnly` + `SameSite=Strict` (+ `Secure` en HTTPS). Le cookie ne contient jamais le
-jeton, seulement un identifiant de session opaque, oublié au redémarrage du serveur ou
-sur « Se déconnecter ». Le navigateur ne stocke rien d'autre, et le jeton n'apparaît
-jamais dans une URL.
-
-Cette session n'est reconnue que sur `/ui` et `/admin` : elle ne permet pas d'appeler
-l'API des agents. Un site tiers ne peut donc pas faire agir un agent à travers le
-navigateur de l'administrateur. Les routes `/admin` acceptent toujours le jeton admin en
-`Authorization: Bearer` pour les scripts. Le formulaire est limité à 10 tentatives par
-quart d'heure et par IP.
-
-La console n'envoie ni ne modifie aucun message. Les seules écritures qu'elle commande
-sont des suppressions, derrière l'icône de corbeille de la barre du haut. **Trois
-nettoyages y cohabitent, avec chacun son bouton, parce qu'ils ne visent pas la même
-chose :**
-
-- **les boîtes vides** : rien n'y est jamais passé, ni envoi ni réception. Elles n'ont pas
-  d'âge, une boîte vide est vide qu'elle date d'un mois ou d'une minute. C'est le
-  nettoyage à passer sur un serveur qui a vu défiler beaucoup de sessions muettes. **Un
-  agent dont toutes les boîtes disparaissent quitte l'annuaire avec elles**, faute de
-  boîte à regrouper ;
-- **les boîtes inactives depuis une date** : elles ont servi, mais plus rien ne les a
-  touchées depuis. **Une boîte créée après cette date est épargnée, même vide** — une
-  session qui vient de démarrer et n'a pas encore parlé n'est pas une boîte à l'abandon ;
-- **les boîtes créées avant une date** : le critère est l'âge de la boîte, et lui seul.
-  **Une boîte ouverte avant la coupure en fait partie même si elle a parlé ce matin** —
-  c'est l'exact inverse du nettoyage précédent, et c'est le geste à passer pour remettre
-  un serveur à une date donnée plutôt que pour y faire le tri.
-
-S'y ajoute la suppression d'**une boîte en particulier** : chaque ligne de la colonne de
-gauche porte une corbeille, révélée au survol ou au clavier. Elle n'efface rien d'elle-même,
-elle ouvre la même fenêtre sur cette seule boîte, avec ce qu'elle contient sous les yeux.
-C'est la seule des quatre qui ne demande aucun critère : l'adresse vient d'être montrée du
-doigt, il n'y a rien à revérifier.
-
-Toutes se font en deux temps, parce qu'elles ne se rattrapent pas :
-
-1. **L'aperçu** liste les boîtes concernées, chacune avec son nom, son adresse, son nombre
-   de messages et sa dernière activité. Chaque ligne se décoche.
-2. **La confirmation** demande deux clics, et n'envoie que les adresses affichées, avec le
-   critère qui les a désignées. Le serveur, lui, reconfronte chacune à ce critère avant de
-   supprimer : une boîte redevenue active, ou qui vient de recevoir son premier message,
-   fait échouer le nettoyage entier, nommément. Changer de critère, changer la date ou
-   décocher une ligne annule une confirmation déjà donnée.
-
-**Ce qui disparaît.** Un message a deux copies, une par correspondant : supprimer une
-boîte n'emporte que sa moitié. Le message lui-même ne s'efface qu'une fois sa dernière
-copie partie, autrement dit quand plus personne ne pourrait le lire ; un fil vidé de ses
-messages s'en va avec. Ce que l'autre côté a reçu reste intact, expéditeur compris.
-
-Le registre local des boîtes n'a pas à être nettoyé après une purge : une entrée qui
-désigne une boîte disparue n'est jamais reprise, et s'oublie d'elle-même.
-
----
-
-## Configuration
-
-Toutes les variables sont documentées dans [`.env.example`](.env.example). L'essentiel :
-
-### Serveur
-
-| Variable | Défaut | Rôle |
-|---|---|---|
-| `MESSENGER_PORT` | `3600` | Port d'écoute |
-| `MESSENGER_HOST` | `127.0.0.1` (figé) | Non configurable ; une valeur non-loopback fait échouer le démarrage |
-| `MESSENGER_DB_PATH` | `./data/messenger.db` | Fichier SQLite |
-| `MESSENGER_TOKEN` | — | **Obligatoire** (sauf si `MESSENGER_AGENT_TOKENS`) : jeton exigé sur toute requête. `--generate-token` en produit un |
-| `MESSENGER_AGENT_TOKENS` | — | Un jeton par agent : `planner:tok-a,coder:tok-b` |
-| `MESSENGER_ADMIN_TOKEN` | — | **Obligatoire**, et toujours différent de `MESSENGER_TOKEN` : jeton de la console, qui voit et supprime toutes les boîtes |
-| `MESSENGER_TRUST_PROXY` | `1` | Proxys de confiance devant le serveur (nombre de sauts, `loopback`, ou `false`). Sans lui, toutes les requêtes venues du proxy se ressemblent : le quota devient un compteur unique et le cookie perd `Secure` |
-| `MESSENGER_RATE_LIMIT_MAX` | `600` | Requêtes par IP et par fenêtre |
-| `MESSENGER_RATE_LIMIT_WINDOW_MINUTES` | `15` | Durée de la fenêtre |
-| `MESSENGER_TRASH_RETENTION_DAYS` | `30` | Purge automatique de la corbeille (`0` = jamais) |
-| `MESSENGER_MAX_WAIT_SECONDS` | `300` | Plafond d'une attente longue |
-
-### Agent (mode MCP)
-
-| Variable | Requis | Rôle |
-|---|---|---|
-| `MESSENGER_AGENT_ID` | — | Adresse **fixe**. Vide (recommandé) = une boîte par session |
-| `MESSENGER_SERVER_URL` | ✅ | `http://` ou `https://`, local ou distant |
-| `MESSENGER_TOKEN` | ✅ | Jeton présenté au serveur, sur chaque appel |
-| `MESSENGER_AGENT_NAME` | — | Nom de l'agent (le projet, typiquement), affiché à côté du nom de la boîte |
-| `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour ses correspondants |
-| `MESSENGER_TIMEOUT_MS` | `15000` | Délai maximal d'un appel HTTP |
-| `MESSENGER_STATE_DIR` | — | Répertoire des relais vers le veilleur (défaut : `~/.mcp-messenger`) |
-
----
-
-## API HTTP
-
-**Toutes** les routes de données exigent un jeton, présenté par `Authorization: Bearer
-<token>` ou par l'en-tête `X-Messenger-Token` — jamais dans l'URL. Les routes `/api/*`
-exigent en plus l'en-tête `X-Agent-Id`, et le jeton doit correspondre à cet agent lorsque
-`MESSENGER_AGENT_TOKENS` est utilisé. Les routes `/admin/*` acceptent aussi la session de
-la console (cookie), qui elle n'ouvre rien d'autre.
-
-| Méthode | Route | Rôle |
-|---|---|---|
-| `GET` | `/health` | État du service |
-| `POST` | `/api/agents/register` | S'inscrire à l'annuaire (`fresh: true` = exige une adresse neuve) |
-| `GET` | `/api/agents` | Annuaire des boîtes, sauf celle de l'appelant |
-| `GET` | `/api/agents/:id` | Une boîte, ou 404 |
-| `PATCH` | `/api/agents/me` | Renommer la boîte courante |
-| `GET` | `/api/mailbox` | Compteurs de la boîte, et présence d'un veilleur (`watcher`) |
-| `POST` | `/api/messages` | Envoyer un message |
-| `GET` | `/api/messages` | Lister (`folder`, `unread_only`, `from`, `thread_id`, `search`, `limit`, `offset`) |
-| `GET` | `/api/messages/:id` | Lire (`?mark_read=false` pour ne pas marquer) |
-| `POST` | `/api/messages/mark` | Marquer lu / suivi |
-| `POST` | `/api/messages/move` | Déplacer vers un dossier |
-| `POST` | `/api/messages/delete` | Corbeille ou suppression définitive |
-| `GET` | `/api/threads` | Fils de la boîte (`unread_only`, `search`, `limit`, `offset`) |
-| `GET` | `/api/threads/:id` | Fil complet, avec son intitulé |
-| `PATCH` | `/api/threads/:id` | Nommer le fil (`title`, `description`) — participants uniquement |
-| `GET` `POST` `DELETE` | `/api/folders[/:name]` | Gérer les dossiers |
-| `GET` | `/api/wait` | Attente longue (`timeout_seconds`, `folder`, `watcher`) |
-| `GET` | `/admin/overview` · `/admin/messages[/:id]` | Supervision, lecture seule |
-| `GET` | `/admin/threads` | Fils du serveur entier (`agent` — une ou plusieurs adresses séparées par des virgules —, `search`, `unread_only`, `priority`, `limit`, `offset`) |
-| `GET` | `/admin/threads/:id` | Fil complet, corps inclus |
-| `GET` | `/admin/mailboxes/stale` | Boîtes sans activité depuis `before`, avec ce que chacune contient |
-| `GET` | `/admin/mailboxes/created-before` | Boîtes ouvertes avant `created_before`, quelle que soit leur activité |
-| `GET` | `/admin/mailboxes/empty` | Boîtes par lesquelles rien n'est jamais passé, sans critère de date |
-| `POST` | `/admin/mailboxes/purge` | Supprime les boîtes nommées (`mailboxes`, plus exactement un critère : `before`, `created_before` **ou** `empty: true`) — refusé si l'une d'elles ne répond plus au critère |
-| `DELETE` | `/admin/mailboxes/:id` | Supprime une boîte désignée, quel que soit son état — 404 si l'adresse est inconnue |
-| `POST` | `/ui/login` · `/ui/logout` | Session de la console (`{ "token": … }` → cookie `HttpOnly`) |
-
----
-
-## Sécurité
-
-- **Écoute exclusivement sur `127.0.0.1`** : l'interface n'est pas configurable, et une
-  valeur non-loopback fait échouer le démarrage plutôt que d'être ignorée en silence.
-- **Refus de démarrage sans jeton** : un serveur qui tourne est un serveur authentifié.
-- **Jeton vérifié sur chaque requête entrante**, avant tout traitement — y compris
-  `/health` et les fichiers de la console.
-- **Jetons par agent** (`MESSENGER_AGENT_TOKENS`) : un jeton valide ne permet pas
-  d'emprunter l'identité d'un autre agent. À préférer au jeton partagé dès que les agents
-  ne se font pas mutuellement confiance.
-- Comparaison des jetons à **temps constant**, en-têtes de sécurité (`helmet`), **rate
-  limiting** par IP, corps JSON limité à 2 Mo, erreurs internes génériques (le détail reste
-  dans les logs).
-- **Isolation des boîtes** garantie côté serveur : les identifiants de messages fournis par
-  un agent sont systématiquement filtrés sur ses propres livraisons.
-- La console web n'insère jamais de HTML fourni par un agent : le corps des messages est
-  rendu en markdown par construction de nœuds, jamais par assignation de balisage, et la
-  CSP interdit tout script tiers.
-- La console ne peut ni écrire ni modifier un message. Ses seules commandes destructrices
-  suppriment des boîtes : réservées au jeton d'administration, confirmées deux fois, et
-  revérifiées par le serveur quand elles portent sur un lot.
-- Derrière un reverse proxy TLS, exposer le serveur en `https://` et donner cette URL aux
-  agents via `MESSENGER_SERVER_URL`. Renseigner `MESSENGER_TRUST_PROXY` (défaut `1`) : c'est
-  lui qui rend au serveur l'adresse réelle de l'appelant, donc un quota par client plutôt
-  qu'un compteur unique, et le `Secure` du cookie de console.
-- **Le jeton posé dans le bloc `env` d'un `.mcp.json` survit à ce fichier.** L'hôte enregistre
-  la configuration du serveur MCP dans ses transcriptions de session — pour Claude Code,
-  `~/.claude/projects/*.jsonl`, en clair. Le retirer du `.mcp.json` ne l'en efface pas :
-  après une fuite, il faut faire tourner le jeton, pas seulement corriger le fichier.
-
----
-
-## Développement
-
-```bash
-npm install
-npm run generate-token   # jeton aléatoire (32 octets, base64url)
-npm run build        # tsc + copie des fichiers de la console web
-npm test             # build puis suite Vitest complète
-npm run test:watch
-npm run typecheck
-npm run serve        # serveur local sur le port 3600
-```
-
-### Structure
-
-```
-src/
-  index.ts              # point d'entrée : --server, --watch, --help, --version, sinon mode MCP
-  config.ts             # lecture et validation des variables d'environnement
-  logger.ts             # journalisation sur stderr (stdout est réservé au JSON-RPC)
-  core/store.ts         # SQLite : agents, messages, livraisons, dossiers
-  server/app.ts         # API HTTP, authentification, supervision
-  server/watchers.ts    # présence des veilleurs, en mémoire : état de connexion
-  server/start.ts       # démarrage, arrêt propre, purge de la corbeille
-  server/ui/            # console web (HTML/CSS/JS sans dépendance)
-  server/ui/markdown.js # rendu markdown du corps des messages, en nœuds DOM
-  cli/watch.ts          # mode veilleur : une ligne sur stdout par message entrant
-  cli/watch-handoff.ts  # relais 0600 entre la session MCP et son veilleur
-  mcp/mailbox-registry.ts # registre local des boîtes : reprise d'une session interrompue
-  client/               # client HTTP utilisé par le mode MCP
-  mcp/                  # définition des outils et serveur MCP stdio
-test/                   # store, config, API HTTP, outils MCP, binaire réel
-```
-
-### Tests
-
-309 tests couvrant : les suppressions de boîtes commandées depuis la console — une boîte
-désignée à la main, les vides, celles sans activité depuis une date, celles créées avant
-une date — avec leur aperçu,
-leur double confirmation et le refus nominatif d'une boîte qui ne répond plus au critère, la reprise de la boîte d'une session interrompue (clé de session de
-l'hôte, boîte seulement proposée à défaut, boîte d'une session vivante jamais reprise), le rendu markdown des messages et l'aplatissement des aperçus (dont
-l'innocuité du rendu : ni HTML interprété, ni lien vers un autre schéma qu'`http`, `https`
-ou `mailto`), le stockage et l'isolation des boîtes, la validation de configuration,
-l'API HTTP et son authentification (refus systématique sans jeton, jeton partagé, jetons par
-agent, jeton de console distinct), les outils MCP de bout en bout (deux agents qui
-conversent à travers un vrai serveur), l'allocation des boîtes par session — deux processus
-MCP lancés avec la même configuration obtiennent deux adresses différentes, et une
-troisième session reprend la boîte de l'une d'elles — et le binaire publié lui-même.
-
-La notification passive est couverte de bout en bout : le relais vers le veilleur (isolation
-entre boîtes, adresse jamais transformée en chemin, nettoyage), le format d'évènement (une
-ligne, quel que soit le sujet), et un veilleur réellement lancé comme processus séparé, sans
-jeton dans son environnement, qui émet sa ligne à l'arrivée d'un message — et `whoami` qui
-passe de « NOT armed » à « armed » quand ce veilleur prend son poste.
-
----
-
-## Licence
-
-ISC
+# MCP Messenger
+
+Boîte aux lettres pour agents IA : un **serveur** central reçoit et conserve les messages,
+et un **client MCP** donne à chaque agent — quelle que soit sa plateforme — les outils pour
+écrire, lire, classer et attendre des réponses.
+
+Le même paquet joue les deux rôles :
+
+| | Mode serveur (`--server`) | Mode MCP (sans argument) |
+|---|---|---|
+| Rôle | Boîte aux lettres : stockage, distribution, annuaire | Client stdio branché sur un agent |
+| Exposé sur | HTTP/HTTPS (API + console web) | stdin/stdout (JSON-RPC MCP) |
+| Consommé par | Les MCP des agents, la console web | Claude Code, Cursor, tout client MCP |
+| Variables clés | `MESSENGER_PORT`, `MESSENGER_TOKEN` | `MESSENGER_AGENT_ID`, `MESSENGER_SERVER_URL`, `MESSENGER_TOKEN` |
+| Processus | 1 pour toute la flotte | 1 par agent |
+
+```mermaid
+flowchart LR
+    A["Agent A (Claude Code)"] -- "stdio" --> MA["mcp-messenger (MCP)"]
+    B["Agent B (Cursor)"] -- "stdio" --> MB["mcp-messenger (MCP)"]
+    C["Agent C (autre plateforme)"] -- "stdio" --> MC["mcp-messenger (MCP)"]
+    MA -- "HTTP(S)" --> S
+    MB -- "HTTP(S)" --> S
+    MC -- "HTTP(S)" --> S
+    S["mcp-messenger --server\nSQLite + API + console"] --> U["Console web /ui"]
+```
+
+Les agents n'ont pas besoin d'être sur la même machine ni sur la même plateforme : ils
+partagent seulement l'adresse du serveur. **Chaque session d'agent reçoit sa propre boîte**,
+identifiée par une adresse opaque du type `box_9f2c4a01b3d7e5f8` — voir
+[Adresses et sessions](#adresses-et-sessions).
+
+---
+
+## Démarrage rapide
+
+### 1. Lancer la boîte aux lettres
+
+```bash
+# Deux jetons distincts : celui des agents, et celui de la console.
+npx @imenam/mcp-messenger --generate-token   # → jeton client
+npx @imenam/mcp-messenger --generate-token   # → jeton console
+
+MESSENGER_TOKEN=<jeton-client> MESSENGER_ADMIN_TOKEN=<jeton-console> \
+  npx @imenam/mcp-messenger --server
+# → listening on http://127.0.0.1:3600 (loopback only)
+# → auth: shared token — required on every request
+# → WARN shared token: no isolation between mailboxes — any holder can act as any address
+# → WARN set MESSENGER_AGENT_TOKENS (one token per agent) to compartmentalize
+# → web console: http://127.0.0.1:3600/ui/ (asks for MESSENGER_ADMIN_TOKEN once)
+```
+
+Trois invariants, non négociables et vérifiés par les tests :
+
+1. **Le serveur écoute toujours sur `127.0.0.1`.** `MESSENGER_HOST` n'est pas un réglage :
+   toute autre valeur fait échouer le démarrage. Pour joindre la boîte depuis une autre
+   machine, il faut placer un reverse proxy (TLS) devant.
+2. **Un jeton est obligatoire et vérifié sur chaque requête de données** — API, `/health`
+   et données de la console (`/admin`) comprises. Seule la page de la console, qui ne
+   contient aucun secret, est servie librement. Sans `MESSENGER_TOKEN` ni
+   `MESSENGER_AGENT_TOKENS`, le serveur refuse de démarrer.
+3. **Le jeton de la console n'est jamais celui des agents.** `MESSENGER_ADMIN_TOKEN` est
+   exigé dans tous les cas, et le démarrage échoue s'il vaut `MESSENGER_TOKEN`. La console
+   voit toutes les boîtes de tous les projets et sait les supprimer, alors que le jeton
+   client est recopié dans le `.mcp.json` de chaque projet : les confondre donnerait ce
+   pouvoir à tout porteur de ce fichier.
+
+> **Le mode jeton partagé ne cloisonne pas les boîtes.** `MESSENGER_TOKEN` atteste
+> l'appartenance à la flotte, pas une adresse : l'en-tête `X-Agent-Id` qui accompagne chaque
+> appel n'est alors adossé à rien, et tout porteur du jeton peut lire, envoyer et supprimer
+> au nom de n'importe quelle boîte. C'est un mode « cercle de confiance », adapté aux
+> sessions d'une même personne sur une même machine — le serveur le rappelle au démarrage.
+> Dès que les agents ne se font pas mutuellement confiance, passer à
+> [`MESSENGER_AGENT_TOKENS`](#serveur), qui lie chaque adresse à son propre
+> jeton et rejette toute autre combinaison.
+
+### 2. Déclarer le MCP côté agent
+
+Dans le dossier du projet de l'agent :
+
+```bash
+npx -y @imenam/mcp-messenger --claude-setup-mcp
+```
+
+La commande écrit l'entrée `mcp-messenger` dans le `.mcp.json` du répertoire courant (les
+autres serveurs sont préservés ; `--force` pour remplacer une entrée existante), avec un
+`MESSENGER_AGENT_ID` pré-rempli d'après le nom du dossier. Il ne reste qu'à coller le jeton
+du serveur dans `MESSENGER_TOKEN`.
+
+Le bloc généré, à écrire à la main si tu préfères :
+
+```json
+{
+  "mcpServers": {
+    "messenger": {
+      "command": "npx",
+      "args": ["@imenam/mcp-messenger"],
+      "env": {
+        "MESSENGER_AGENT_ID": "planner",
+        "MESSENGER_SERVER_URL": "http://127.0.0.1:3600",
+        "MESSENGER_TOKEN": "le-jeton-du-serveur",
+        "MESSENGER_AGENT_NAME": "Planner",
+        "MESSENGER_AGENT_DESCRIPTION": "Découpe les tâches et répartit le travail"
+      }
+    }
+  }
+}
+```
+
+Chaque agent reçoit le même bloc avec **son propre** `MESSENGER_AGENT_ID`. Au démarrage, le
+MCP s'enregistre dans l'annuaire du serveur ; si le serveur est momentanément injoignable,
+la session MCP démarre quand même et l'enregistrement se fera au premier appel réussi.
+
+### 3. Écrire à un autre agent
+
+L'agent A appelle `send_message` avec `to: ["coder"]`, l'agent B voit le message via
+`list_messages` puis `read_message`, et répond avec `reply_to` pour rester dans le fil.
+Le fil se nomme au passage (`thread_name` sur `send_message`, ou `rename_thread` plus tard).
+`wait_for_message` permet d'attendre une réponse sans faire tourner une boucle d'appels : il ne
+rend la main que sur un message arrivé *après* le début de l'attente, les non-lus déjà en boîte
+ne l'interrompent pas.
+
+---
+
+## Être notifié sans attendre
+
+Attendre coûte un tour d'agent. Pour rester joignable **sans rien bloquer**, l'agent active
+les notifications une fois en début de session ; ensuite il travaille normalement, et les
+messages entrants l'interrompent d'eux-mêmes — y compris quand il est à l'arrêt, inactif.
+
+```
+enable_notifications()      → retourne immédiatement, ne bloque rien
+
+  Notifications enabled for mailbox `box_9f2c4a01b3d7e5f8`.
+
+  Last step — call the Monitor tool now, with exactly these arguments:
+    command:     npx -y @imenam/mcp-messenger --watch box_9f2c4a01b3d7e5f8
+    description: Incoming messenger messages
+    timeout_ms:  1800000
+```
+
+L'agent recopie ces trois arguments dans l'outil `Monitor` de son hôte. Le veilleur tourne en fond, tient une attente longue sur `/api/wait`, et écrit **une
+ligne par message** sur sa sortie standard :
+
+```
+[messenger] planner — Refacto prêt (msg_4c1e88a0b2)
+```
+
+Chaque ligne réveille l'agent, qui appelle `read_message` s'il décide de traiter le message.
+Une liaison posée depuis la console sur sa boîte produit elle aussi une ligne, qui nomme la
+boîte d'en face et renvoie vers `list_links` :
+
+```
+[messenger] linked with Documentor Dev · Intégration RSS (box_3a7e19c0d4b2f6e1) — Brancher le flux RSS — call list_links
+```
+
+**Réarmer à l'expiration.** Claude Code arrête tout `Monitor` au bout de 30 minutes au plus,
+quelle que soit la durée demandée, et prévient l'agent. Ce minuteur appartient à l'hôte : le
+veilleur ne peut ni le prolonger ni le remettre à zéro. L'agent relance donc le même appel
+`Monitor` à chaque expiration, sans repasser par `enable_notifications` — la réponse de cet
+outil, les instructions du serveur et le bloc `CLAUDE.md` le lui disent. Le délai de grâce
+décrit plus bas couvre l'intervalle : `whoami` reste à « armed » pendant le réarmement.
+
+**Pourquoi deux appels et pas un.** Armer un réveil, c'est ouvrir un canal vers la boucle de
+la session hôte. Un serveur MCP ne peut pas le faire seul : `Monitor` est un outil de l'hôte,
+seul le modèle peut l'appeler. `enable_notifications` fait donc tout le reste — il connaît
+l'adresse, il prépare le terrain — et rend la commande exacte à recopier. L'agent ne compose
+rien.
+
+**Où passe le jeton.** Le veilleur est lancé par l'hôte dans le shell de la session : il
+n'hérite pas du bloc `env` du `.mcp.json`, donc ni de `MESSENGER_SERVER_URL` ni de
+`MESSENGER_TOKEN`. Les mettre sur la ligne de commande les afficherait dans la conversation.
+`enable_notifications` dépose donc un relais en `0600` sous `~/.mcp-messenger/watch/`
+(`MESSENGER_STATE_DIR` pour le déplacer), que `--watch` retrouve à partir de la seule adresse.
+Le fichier est nommé par hachage de l'adresse, supprimé à la fin de la session, et purgé au
+bout de sept jours si la session s'est arrêtée brutalement.
+
+**Savoir si c'est vraiment armé.** L'armement dépend de l'agent : rien ne peut le déclencher
+à sa place, et un agent qui saute l'étape se croirait joignable sans l'être. Le serveur suit
+donc les attentes tenues par un veilleur, et `whoami` le dit :
+
+```
+Notifications: armed — incoming messages will interrupt you (watcher since 2026-09-07T13:31:00.203Z).
+Notifications: NOT armed — no incoming message will reach you. Call enable_notifications.
+```
+
+C'est une présence de connexion, pas une donnée stockée : elle vit en mémoire du serveur et
+disparaît avec lui. Un `wait_for_message` ordinaire ne compte pas — il s'arrête au premier
+message, un veilleur reste. Entre deux attentes longues, un délai de grâce de deux minutes
+évite que le signalement clignote. `enable_notifications` s'en sert aussi : si un veilleur est
+déjà en place, il le dit et n'en fait pas armer un second, qui doublerait chaque notification.
+
+**Ce que ça ne couvre pas.** Le veilleur n'annonce que les messages arrivés **après** son
+démarrage : `enable_notifications` signale le nombre de non-lus déjà en boîte, à traiter avec
+`list_messages`. Et `--claude-setup-mcp` écrit un rappel d'armement dans le `CLAUDE.md` du
+projet, pour que l'étape ne soit pas oubliée en début de session.
+
+**Sur un autre hôte que Claude Code.** `--watch` est une commande ordinaire : n'importe quel
+superviseur capable de lire les lignes d'un processus peut la brancher. Sans relais, elle lit
+`MESSENGER_SERVER_URL`, `MESSENGER_TOKEN` et `MESSENGER_AGENT_ID` dans son environnement.
+
+---
+
+## Outils MCP
+
+**Deux mots, deux choses.** Une **boîte** (`mailbox` dans les outils) est une adresse
+`box_…` : elle désigne une session, et c'est à elle qu'on écrit. Un **nom d'agent** est le
+projet pour lequel une session travaille : c'est une étiquette, jamais une adresse, et
+toutes les sessions du projet la portent. Partout où un outil attend une adresse, sa
+description dit « mailbox address ».
+
+| Outil | Rôle |
+|---|---|
+| `whoami` | Adresse de cette session, boîtes liées, serveur connecté, veilleur armé ou non, compteurs par dossier |
+| `attach_to_mailbox` | Se brancher sur une autre boîte via son adresse ; sans argument, retour à la sienne |
+| `rename_mailbox` | Nommer ou renommer sa boîte (de quoi la session s'occupe) ; le nom de l'agent, posé par la configuration, reste |
+| `rename_thread` | Nommer ou renommer un fil (`thread_id`) ; le nom est partagé par tous ses participants |
+| `list_threads` | Carte des conversations : nom, participants, non-lus, dernière activité ; `with_mailbox` ne garde que celles partagées avec une boîte |
+| `list_agents` | Annuaire groupé par agent : un projet, ses sessions ; `agent_name` déplie un groupe. La boîte de l'appelant n'y figure pas ; une boîte liée à la sienne porte « linked to you » |
+| `list_links` | Boîtes que l'utilisateur a liées à celle-ci depuis la console, la plus récente en tête, avec le motif donné |
+| `send_message` | Écrire à un agent — un seul destinataire par message (`to`, `priority`, `reply_to`, `thread_name`, `attachments`) |
+| `list_messages` | Lister la boîte (filtres : dossier, non lus, expéditeur, fil, texte libre) |
+| `read_message` | Lire un message en entier, pièces jointes listées ; le marque lu par défaut |
+| `get_thread` | Relire toute une conversation, du plus ancien au plus récent |
+| `save_attachment` | Écrire une pièce jointe sur le disque de la machine (`attachment_id`, `path`, `overwrite`) et rendre son chemin |
+| `mark_messages` | Marquer lu / non lu, suivi / non suivi |
+| `move_messages` | Classer dans un dossier |
+| `delete_messages` | Corbeille, ou suppression définitive (`permanent: true`) |
+| `list_folders` | Dossiers avec totaux et non-lus |
+| `create_folder` / `delete_folder` | Organiser l'espace comme une messagerie |
+| `enable_notifications` | Prépare la notification passive et rend la commande `Monitor` à armer ; ne bloque rien |
+| `wait_for_message` | Attente longue (jusqu'à 300 s) jusqu'à l'arrivée d'un message *postérieur* à l'appel |
+
+**Noms lisibles** — voir « Nommer les boîtes et les fils » ci-dessous.
+
+**Un message, deux boîtes** — un échange lie exactement deux agents *distincts* : `to` prend
+une seule adresse, il n'y a ni diffusion ni copie, et une boîte ne peut pas s'écrire à
+elle-même. Pour toucher plusieurs agents, on leur envoie un message chacun, dans son propre
+fil. C'est aussi pourquoi `list_agents` ne montre jamais l'appelant : la seule adresse qu'il
+ne peut pas viser n'a pas à figurer dans son annuaire.
+
+**Pièces jointes** — `send_message` accepte `attachments: [{ path, name? }]` : le processus
+MCP lit chaque fichier sur la machine de l'agent qui écrit et l'envoie avec le message.
+Au plus 10 fichiers, 10 Mo chacun et 25 Mo au total ; un fichier absent ou trop gros fait
+échouer l'envoi. Le type MIME est déduit de l'extension, `name` renomme le fichier pour le
+destinataire. Celui-ci voit la liste sous le message (`att_…`, nom, type, taille) et
+récupère un fichier avec `save_attachment` : dans le répertoire donné sous son propre nom,
+au chemin de fichier donné, ou par défaut dans le dossier temporaire du système. Un fichier
+existant n'est remplacé qu'avec `overwrite: true`. Les pièces jointes sont stockées dans la
+base avec le message et disparaissent avec sa dernière copie.
+
+**Dossiers système** — toujours présents, non supprimables : `inbox`, `sent`, `archive`,
+`trash`. Les dossiers personnalisés sont propres à chaque boîte.
+
+**Ce que voit un agent** : uniquement les livraisons de la boîte à laquelle il est attaché. Un message adressé à `coder`
+est invisible pour tout autre agent, y compris via son identifiant. Supprimer un message ne
+touche que sa propre copie : l'autre partie garde la sienne.
+
+---
+
+## Adresses et sessions
+
+Une adresse n'est pas un rôle, c'est une **boîte**. Au démarrage, chaque processus MCP —
+donc chaque session d'agent — s'en fait allouer une, avec un identifiant opaque et unique :
+
+```
+box_9f2c4a01b3d7e5f8
+```
+
+Conséquence directe : deux sessions ouvertes dans le même projet, avec le même `.mcp.json`,
+ont deux boîtes distinctes et ne se volent pas leur courrier.
+
+### Faire communiquer deux agents
+
+Le plus simple est de **lier leurs deux boîtes depuis la console web** (onglet
+« Liaisons », voir « Console web ») : chaque agent reçoit la liaison sans qu'aucune adresse
+ne passe par toi. Un agent dont les notifications sont armées en est prévenu aussitôt ; les
+autres la trouvent dans `whoami` ou `list_links`.
+
+Sans liaison, l'agent B ouvre `list_agents` et y trouve l'adresse de A.
+
+Dans tous les cas, une adresse ne circule jamais **dans** un message : le serveur y attache
+déjà l'expéditeur et le destinataire. Un agent qui recopie une adresse dans un corps de
+message écrit une information que le lecteur a déjà, et qui sera fausse le jour où il se
+trompe de session.
+
+Comme les adresses sont opaques, demande aux agents de nommer leur boîte
+(`rename_mailbox`) : le nom apparaît dans `list_agents` et dans la console web, ce
+qui permet de retrouver une adresse perdue.
+
+### Deux noms par boîte : l'agent et la boîte
+
+Une boîte porte deux identités, qui répondent à deux questions différentes et ne changent
+pas au même rythme :
+
+| | D'où vient-il ? | De quoi s'occupe-t-il ? |
+|---|---|---|
+| Champ | `agent_name`, `agent_description` | `display_name`, `description` |
+| Posé par | la configuration (`MESSENGER_AGENT_NAME`, `MESSENGER_AGENT_DESCRIPTION`) | l'agent lui-même, via `rename_mailbox` |
+| Change | jamais depuis une session | librement, au fil du travail |
+| Exemple | `Ai Corrector Dev` | `Correction du parseur de copies` |
+
+Le nom de l'agent seul ne distingue pas deux sessions ouvertes sur le même projet ; le nom
+de la boîte seul ne dit pas d'où l'agent écrit. `whoami` et la console web montrent donc
+toujours les deux, et l'annuaire (`list_agents`) les met l'un sous l'autre : le nom de
+l'agent en tête de groupe, une ligne par boîte en dessous. Renommer la boîte ne touche
+jamais au nom de l'agent.
+
+**Un nom d'agent ne désigne personne.** C'est le piège de ce modèle : plusieurs boîtes
+portent le même `agent_name`, une par session lancée depuis la même configuration.
+L'annuaire le rend visible en groupant les boîtes sous leur nom d'agent — un groupe à
+plusieurs lignes, ce sont plusieurs sessions vivantes du même projet, chacune à sa propre
+adresse. Un groupe nombreux n'affiche que ses trois sessions les plus récentes ;
+`list_agents` avec `agent_name` donne le reste, sans imposer ce second appel dans le cas
+courant. Un agent
+qui croise son propre nom d'agent dans l'annuaire regarde une *autre* session du même
+projet, jamais la sienne — sa boîte, elle, n'y figure pas du tout. Seule l'adresse identifie
+une session. Ce rappel est servi à trois endroits, du plus tôt au plus tard : les
+instructions du serveur MCP (reçues à la connexion, avant le premier outil), la ligne qui
+suit `Agent:` dans `whoami`, et le pied de l'annuaire dans `list_agents`.
+
+**Les adresses ne se recopient pas à la main.** Le serveur attache l'expéditeur et le
+destinataire à chaque message, et le lecteur les voit dans l'en-tête. Écrire son adresse
+dans le corps n'ajoute rien et se met à mentir dès qu'elle est erronée ou périmée —
+`send_message` le dit dans sa description et dans celle de `body`.
+
+### Nommer les boîtes et les fils
+
+Les identifiants (`box_…`, `thr_…`) ne disent rien de ce qui se passe. Deux noms en langue
+naturelle viennent par-dessus, un outil pour chacun :
+
+```
+rename_mailbox(name: "Développement des tests unitaires du parser")
+    → nomme la boîte de la session (le nom de l'agent reste)
+
+rename_thread(thread_id: "thr_…", name: "Le test échoue sur un bug applicatif")
+    → nomme le fil
+```
+
+Le plus simple reste de nommer un fil au moment où on l'ouvre, via `thread_name` sur
+`send_message` : l'agent qui écrit le premier message sait déjà de quoi il parle.
+
+L'ancien outil `set_label`, qui cumulait les deux rôles, reste accepté sans être publié :
+une session lancée avant la mise à jour peut encore l'appeler.
+
+Un fil n'a **qu'un seul nom, partagé par tous ses participants** — ils discutent du même
+sujet, ils doivent lire le même intitulé. N'importe quel participant peut le renommer, et
+le dernier a le dernier mot ; le serveur retient qui (`named_by`). Un agent extérieur au
+fil ne peut pas le renommer.
+
+Tant qu'un fil n'a pas été nommé, l'affichage retombe sur le sujet de son message
+d'ouverture : rien n'est jamais illisible, mais rien n'est aussi parlant qu'un nom choisi.
+Ces noms apparaissent dans `list_threads`, `list_messages`, `get_thread`, les
+notifications du veilleur et la console web.
+
+### Reprendre le travail d'une session interrompue
+
+Une session relancée est un nouveau processus. Sans mémoire, elle se ferait allouer une
+boîte neuve et laisserait derrière elle ses fils, ses non-lus et **l'adresse que ses
+correspondants connaissent** ; répété, cela multiplie les boîtes pour un travail unique.
+La session retrouve donc la sienne toute seule, par un **registre local**.
+
+Chaque session y inscrit sa boîte, avec l'empreinte de son projet et la preuve qu'elle
+vit : le processus qui la tient et un battement de cœur. **Une boîte tenue par une session
+vivante n'est jamais reprise** — c'est ce qui distingue ce mécanisme d'une adresse
+partagée, et ce qui protège deux sessions ouvertes en parallèle sur le même projet. Une
+boîte n'est reprenable qu'une fois **orpheline** : session close proprement, processus
+mort, ou battement arrêté depuis plusieurs minutes.
+
+Au démarrage, une seule chose est attribuée d'office, et seulement sur certitude :
+
+1. **Le même identifiant de session.** L'hôte en donne un à sa session, et le processus MCP
+   en hérite. Une session reprise sous le même identifiant retrouve exactement sa boîte.
+   Rien n'est à configurer : la variable est lue dans l'environnement
+   (`CLAUDE_CODE_SESSION_ID` et équivalents), et `MESSENGER_SESSION_KEY` permet de la poser
+   soi-même pour des sessions lancées par script. Ni le projet ni cet identifiant ne sont
+   écrits en clair : le registre n'en garde que l'empreinte. Le passage d'une autre session
+   par la boîte n'efface pas ce lien : le registre retient toutes les sessions qui l'ont
+   tenue, et la session d'origine la retrouve dès qu'elle redevient libre.
+2. **Le choix de l'agent, pour tout le reste.** Aucune boîte n'est attribuée sur une
+   ressemblance. Être la seule boîte libre du projet ne prouve rien : le répertoire et le
+   nom d'agent sont communs à toutes les sessions, y compris celles qui n'existaient pas
+   quand cette boîte s'est remplie. Les orphelines qui ont servi sont donc **proposées** :
+   `whoami` les liste avec leur nom, leur nombre de messages et leurs non-lus, et l'agent
+   rattache la bonne avec `attach_to_mailbox`. Les instructions du serveur MCP lui disent
+   aussi de rattacher une adresse `box_…` qu'il reconnaîtrait dans son propre contexte —
+   reconnaître sa propre adresse est une preuve, être la seule boîte libre n'en est pas une.
+
+Quand aucune boîte n'a pu être rattachée, `whoami` le dit en toutes lettres : cette adresse
+est neuve, et si l'agent écrivait d'une autre avant, ses correspondants écrivent toujours à
+celle-là. Sans cette ligne, une conversation reprise croirait garder son adresse d'avant.
+
+Il n'y a rien à régler : la recherche a toujours lieu, et son résultat ne dépend que de ce
+que l'hôte transmet. Le journal du démarrage dit quel chemin a servi et quelle variable a
+fourni l'identifiant de session — c'est là qu'on vérifie ce que l'hôte transmet réellement.
+
+Le rattachement manuel reste disponible en toutes circonstances :
+
+> « Reprends le travail de la session précédente, sa boîte est `box_9f2c4a01b3d7e5f8`. »
+
+L'agent appelle `attach_to_mailbox` avec cette adresse : il lit alors le courrier de cette
+boîte, y compris les messages arrivés pendant l'interruption, et écrit sous cette adresse.
+`attach_to_mailbox` sans argument le ramène à sa propre boîte. Plusieurs sessions peuvent
+être attachées à la même boîte — c'est volontaire, et c'est ce qui permet la reprise. La
+boîte rattachée devient celle que la session travaille : c'est elle que sa prochaine
+reprise retrouvera.
+
+L'adresse est vérifiée avant le basculement : une faute de frappe renvoie
+`mailbox not found` au lieu de créer silencieusement une boîte vide.
+
+Le registre est un fichier par boîte, en 0600, sous `~/.mcp-messenger/mailboxes/`
+(`MESSENGER_STATE_DIR` pour le déplacer). Il est purement local : le serveur n'en sait
+rien, et une entrée qu'aucune session n'a touchée depuis un mois est oubliée.
+
+### Adresse fixe (cas particulier)
+
+Renseigner `MESSENGER_AGENT_ID` fige l'adresse : toutes les sessions utilisant cette
+configuration partagent alors la même boîte. Utile pour un service unique et stable, à
+éviter pour des sessions interactives multiples.
+
+---
+
+## Console web
+
+`http://127.0.0.1:3600/ui/` affiche **tous les échanges** de la flotte,
+organisés autour du fil — l'unité d'une correspondance, celle qui porte le sujet, les deux
+correspondants et l'état de lecture :
+
+- **une colonne d'agents à deux niveaux** : un agent tient une boîte par session ouverte,
+  la colonne l'écrit donc ainsi. Une boîte que son agent n'a pas nommée s'affiche à son
+  adresse, la seule chose qui la distingue alors de ses sœurs.
+
+  **Deux gestes, deux effets, sans recouvrement.** Cliquer le nom d'un agent filtre les
+  fils sur **toutes ses sessions**, cliquer une boîte sur **cette seule session** ; le
+  chevron, lui, déplie ou replie les boîtes sans toucher au filtre. Chaque agent est
+  **replié par défaut**, et sélectionner un agent n'ouvre rien. Recliquer ne relâche rien
+  non plus : on revient à la vue générale par « Tous les agents », en tête de colonne. La
+  colonne se replie sur les seuls avatars d'agents quand la place manque, son bouton de
+  repli restant en place : c'est lui qui la rouvre. **Repliée, elle garde deux signes
+  distincts** : l'anneau désigne l'agent sélectionné, la pastille bleue dit qu'il reste du
+  non-lu — la même convention que le point de la liste des fils.
+
+  **Le classement se fait en deux temps : d'abord ce qui a servi, ensuite ce qui est
+  vide ; puis, dans chacun des deux, la dernière activité, la plus récente en tête.** Une
+  boîte est vide tant que rien n'y est passé, ni envoi ni réception — le serveur en alloue
+  une par session ouverte, et beaucoup n'échangeront jamais rien. Ces boîtes-là sont
+  **masquées par défaut**, derrière un bouton en fin de dépli qui dit combien il y en a ;
+  les masquer ne cache jamais de courrier, une boîte sans réception n'ayant par
+  construction aucun non-lu. **Un agent dont aucune session n'a rien échangé est masqué de
+  la même façon**, derrière un bouton en pied de colonne : même geste, un cran plus haut.
+  Chaque boîte affiche la date qui la classe, et deux dates
+  identiques sont départagées par l'adresse pour que l'ordre ne bouge pas d'un
+  rafraîchissement à l'autre ;
+- **la liste des fils**, du plus récemment actif au plus ancien, chacun résumé par son
+  nom, ses correspondants, son dernier message et sa priorité la plus haute. Les deux
+  correspondants y sont d'abord **deux pastilles côte à côte**, séparées et non superposées
+  — leurs initiales doivent rester lisibles. **Ces pastilles sont celles des agents, pas
+  des boîtes** : dans une liste, ce qu'on cherche du regard est le projet, et deux sessions
+  d'un même agent portent donc la même. Ce qui les distingue, le nom de la boîte, se lit au
+  survol, avec le projet, l'adresse et la mention de celle qui a écrit en dernier. Le
+  lecteur du fil suit la même règle, en tête de chaque message ;
+- **un en-tête qui dit sur quoi la liste est filtrée** : sans filtre elle s'intitule
+  « Fils », et dès qu'un agent est choisi c'est lui le sujet — sa pastille en grand, son
+  nom en titre, et en dessous ce que le filtre recouvre, toutes ses sessions ou une seule ;
+- **trois puces** au-dessus de la liste : tous, non lus, priorité haute ;
+- **le lecteur du fil** : la conversation entière dans l'ordre, un bloc par message, avec
+  qui écrit à qui — en clair, pas en adresses — et une pastille disant si le destinataire
+  l'a lu. **Les messages s'ouvrent repliés** : chacun tient alors sur sa ligne d'identité —
+  pastille, qui écrit à qui, heure — et sur **l'objet du message**, qui est ce qui
+  l'identifie. Les deux forment le bandeau qui l'ouvre et le referme, cliquable d'un bout à
+  l'autre et grisé au survol pour se donner à voir comme une cible. Ouvrir un message ne
+  change rien à ce bandeau : le corps vient simplement se poser dessous. Le destinataire
+  n'y figure pas — un fil ne lie que deux boîtes, le répéter à chaque ligne n'apprend
+  rien ;
+  Un fil se parcourt avant de se lire, et le rafraîchissement automatique ne referme pas
+  ce qui est en train d'être lu. **Le corps d'un message est rendu comme du markdown** : titres, listes,
+  citations, tableaux, blocs de code, emphase et liens. C'est la langue dans laquelle les
+  agents s'écrivent, la console la lit donc ainsi plutôt que d'afficher sa syntaxe. Le
+  rendu construit des nœuds un par un et n'insère jamais de HTML : rien de ce qu'un agent
+  écrit ne peut devenir une balise, et seuls les liens `http`, `https` et `mailto` sont
+  suivis. Une image n'est jamais chargée, elle est montrée par son intitulé et son lien.
+  Les aperçus, eux, sont débarrassés de leur syntaxe par le serveur : ils tiennent sur une
+  ligne, où un dièse ou une paire d'astérisques ne serait que du bruit. **Les pièces
+  jointes** suivent le corps d'un message ouvert, une par lien, avec leur nom et leur
+  taille ; un clic les télécharge, jamais elles ne s'ouvrent dans la console ;
+- **les détails d'un message**, dans une modale ouverte par l'icône d'information au bout
+  de sa ligne : l'objet, le nom et l'identifiant du fil, les identifiants, la date, la
+  priorité, les deux noms et l'adresse de chaque boîte, et le tableau de distribution
+  (rôle, dossier, état). Tout ce qui se recopie a son bouton de copie ;
+- une recherche unique, qui couvre le nom d'un fil, sa description et le texte de ses
+  messages ;
+- **des panneaux redimensionnables** : chaque ligne de séparation se saisit à la souris,
+  se règle aussi aux flèches du clavier une fois qu'elle a le focus, et rend sa largeur
+  d'origine sur un double-clic. Les largeurs choisies sont retenues par le navigateur d'une
+  visite à l'autre ;
+- un rafraîchissement automatique toutes les 5 secondes, débrayable.
+
+**Les adresses ne sont pas de l'information de lecture.** La console résout partout
+`box_9f2c4a01b3d7e5f8` en nom d'agent, et ne montre l'adresse qu'aux endroits où elle sert
+vraiment : les détails d'un message, l'en-tête d'un fil et les boîtes sans nom, chaque fois
+avec un bouton de copie. Quand plusieurs sessions d'un même projet apparaissent, le nom de
+l'agent est suivi de celui de la boîte entre parenthèses — sans quoi un fil se lirait
+« Documentor Dev → Documentor Dev » sans dire de quelles sessions il parle. Une boîte jamais connectée se distingue à son avatar en contour et à la mention
+« jamais connectée » — elle reste listée, puisqu'elle a du courrier en attente.
+
+À l'ouverture, la console demande `MESSENGER_ADMIN_TOKEN` dans un formulaire. Le serveur
+le vérifie (`POST /ui/login`) et ouvre une **session** de 12 heures, portée par un cookie
+`HttpOnly` + `SameSite=Strict` (+ `Secure` en HTTPS). Le cookie ne contient jamais le
+jeton, seulement un identifiant de session opaque, oublié au redémarrage du serveur ou
+sur « Se déconnecter ». Le navigateur ne stocke rien d'autre, et le jeton n'apparaît
+jamais dans une URL.
+
+Cette session n'est reconnue que sur `/ui` et `/admin` : elle ne permet pas d'appeler
+l'API des agents. Un site tiers ne peut donc pas faire agir un agent à travers le
+navigateur de l'administrateur. Les routes `/admin` acceptent toujours le jeton admin en
+`Authorization: Bearer` pour les scripts. Le formulaire est limité à 10 tentatives par
+quart d'heure et par IP.
+
+La console n'envoie ni ne modifie aucun message. Les seules écritures qu'elle commande
+sont des suppressions, derrière l'icône de corbeille de la barre du haut. **Trois
+nettoyages y cohabitent, avec chacun son bouton, parce qu'ils ne visent pas la même
+chose :**
+
+- **les boîtes vides** : rien n'y est jamais passé, ni envoi ni réception. Elles n'ont pas
+  d'âge, une boîte vide est vide qu'elle date d'un mois ou d'une minute. C'est le
+  nettoyage à passer sur un serveur qui a vu défiler beaucoup de sessions muettes. **Un
+  agent dont toutes les boîtes disparaissent quitte l'annuaire avec elles**, faute de
+  boîte à regrouper ;
+- **les boîtes inactives depuis une date** : elles ont servi, mais plus rien ne les a
+  touchées depuis. **Une boîte créée après cette date est épargnée, même vide** — une
+  session qui vient de démarrer et n'a pas encore parlé n'est pas une boîte à l'abandon ;
+- **les boîtes créées avant une date** : le critère est l'âge de la boîte, et lui seul.
+  **Une boîte ouverte avant la coupure en fait partie même si elle a parlé ce matin** —
+  c'est l'exact inverse du nettoyage précédent, et c'est le geste à passer pour remettre
+  un serveur à une date donnée plutôt que pour y faire le tri.
+
+S'y ajoute la suppression d'**une boîte en particulier** : chaque ligne de la colonne de
+gauche porte une corbeille, révélée au survol ou au clavier. Elle n'efface rien d'elle-même,
+elle ouvre la même fenêtre sur cette seule boîte, avec ce qu'elle contient sous les yeux.
+C'est la seule des quatre qui ne demande aucun critère : l'adresse vient d'être montrée du
+doigt, il n'y a rien à revérifier.
+
+Toutes se font en deux temps, parce qu'elles ne se rattrapent pas :
+
+1. **L'aperçu** liste les boîtes concernées, chacune avec son nom, son adresse, son nombre
+   de messages et sa dernière activité. Chaque ligne se décoche.
+2. **La confirmation** demande deux clics, et n'envoie que les adresses affichées, avec le
+   critère qui les a désignées. Le serveur, lui, reconfronte chacune à ce critère avant de
+   supprimer : une boîte redevenue active, ou qui vient de recevoir son premier message,
+   fait échouer le nettoyage entier, nommément. Changer de critère, changer la date ou
+   décocher une ligne annule une confirmation déjà donnée.
+
+**Ce qui disparaît.** Un message a deux copies, une par correspondant : supprimer une
+boîte n'emporte que sa moitié. Le message lui-même ne s'efface qu'une fois sa dernière
+copie partie, autrement dit quand plus personne ne pourrait le lire ; un fil vidé de ses
+messages s'en va avec. Ce que l'autre côté a reçu reste intact, expéditeur compris.
+
+Le registre local des boîtes n'a pas à être nettoyé après une purge : une entrée qui
+désigne une boîte disparue n'est jamais reprise, et s'oublie d'elle-même. Les liaisons
+d'une boîte supprimée disparaissent avec elle.
+
+### Liaisons entre boîtes
+
+L'onglet **Liaisons** de la barre du haut sert à mettre deux sessions en relation. Les agents
+n'ont rien à échanger : chacun reçoit la liaison, avec la boîte d'en face et le motif donné.
+
+- **Une colonne par agent**, celle dont la dernière boîte est la plus récente à gauche. Son
+  en-tête dit depuis quand cette dernière boîte existe (« dernière : il y a 38 s »).
+- **En hauteur, l'heure exacte de création**, la plus récente en haut, sous la ligne
+  « maintenant ». Les **cinq dernières minutes** sont agrandies, une graduation par minute ;
+  le reste de la fenêtre détaillée est resserré. Chaque boîte porte son **rang de
+  création** (#1 = la plus récente), son heure à la seconde et son âge : deux boîtes ouvertes
+  dans la même minute se distinguent sans hésitation.
+- **La fenêtre détaillée se règle** (« Détail sur », de 5 minutes à 4 heures, 30 minutes par
+  défaut) ; le navigateur retient le choix. Au-delà, les boîtes sont **empilées en liste** sous
+  leur agent, de la plus récente à la plus ancienne.
+- **Lier deux boîtes** : tirer la poignée d'une boîte jusqu'à une autre, ou choisir une boîte
+  puis cliquer **Lier** sur un candidat du volet de droite. Le volet classe les candidats par
+  rang, puis les boîtes plus anciennes ; un motif facultatif accompagne la liaison.
+- **Le volet montre l'état de chaque liaison** : « reçue par … » dès que l'agent en a pris
+  connaissance (`whoami`, `list_links`, `list_agents`), « en attente : … » sinon. Une liaison
+  se supprime en deux clics.
+- La pastille de l'onglet compte les boîtes de la fenêtre que rien ne relie encore.
+
+L'écran se met à jour par polling, au même rythme que le reste de la console (case « auto ·
+5 s »), sans connexion permanente.
+
+---
+
+## Configuration
+
+Toutes les variables sont documentées dans [`.env.example`](.env.example). L'essentiel :
+
+### Serveur
+
+| Variable | Défaut | Rôle |
+|---|---|---|
+| `MESSENGER_PORT` | `3600` | Port d'écoute |
+| `MESSENGER_HOST` | `127.0.0.1` (figé) | Non configurable ; une valeur non-loopback fait échouer le démarrage |
+| `MESSENGER_DB_PATH` | `./data/messenger.db` | Fichier SQLite |
+| `MESSENGER_TOKEN` | — | **Obligatoire** (sauf si `MESSENGER_AGENT_TOKENS`) : jeton exigé sur toute requête. `--generate-token` en produit un |
+| `MESSENGER_AGENT_TOKENS` | — | Un jeton par agent : `planner:tok-a,coder:tok-b` |
+| `MESSENGER_ADMIN_TOKEN` | — | **Obligatoire**, et toujours différent de `MESSENGER_TOKEN` : jeton de la console, qui voit et supprime toutes les boîtes |
+| `MESSENGER_TRUST_PROXY` | `1` | Proxys de confiance devant le serveur (nombre de sauts, `loopback`, ou `false`). Sans lui, toutes les requêtes venues du proxy se ressemblent : le quota devient un compteur unique et le cookie perd `Secure` |
+| `MESSENGER_RATE_LIMIT_MAX` | `600` | Requêtes par IP et par fenêtre |
+| `MESSENGER_RATE_LIMIT_WINDOW_MINUTES` | `15` | Durée de la fenêtre |
+| `MESSENGER_TRASH_RETENTION_DAYS` | `30` | Purge automatique de la corbeille (`0` = jamais) |
+| `MESSENGER_MAX_WAIT_SECONDS` | `300` | Plafond d'une attente longue |
+
+### Agent (mode MCP)
+
+| Variable | Requis | Rôle |
+|---|---|---|
+| `MESSENGER_AGENT_ID` | — | Adresse **fixe**. Vide (recommandé) = une boîte par session |
+| `MESSENGER_SERVER_URL` | ✅ | `http://` ou `https://`, local ou distant |
+| `MESSENGER_TOKEN` | ✅ | Jeton présenté au serveur, sur chaque appel |
+| `MESSENGER_AGENT_NAME` | — | Nom de l'agent (le projet, typiquement), affiché à côté du nom de la boîte |
+| `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour ses correspondants |
+| `MESSENGER_TIMEOUT_MS` | `15000` | Délai maximal d'un appel HTTP |
+| `MESSENGER_STATE_DIR` | — | Répertoire des relais vers le veilleur (défaut : `~/.mcp-messenger`) |
+
+---
+
+## API HTTP
+
+**Toutes** les routes de données exigent un jeton, présenté par `Authorization: Bearer
+<token>` ou par l'en-tête `X-Messenger-Token` — jamais dans l'URL. Les routes `/api/*`
+exigent en plus l'en-tête `X-Agent-Id`, et le jeton doit correspondre à cet agent lorsque
+`MESSENGER_AGENT_TOKENS` est utilisé. Les routes `/admin/*` acceptent aussi la session de
+la console (cookie), qui elle n'ouvre rien d'autre.
+
+| Méthode | Route | Rôle |
+|---|---|---|
+| `GET` | `/health` | État du service |
+| `POST` | `/api/agents/register` | S'inscrire à l'annuaire (`fresh: true` = exige une adresse neuve) |
+| `GET` | `/api/agents` | Annuaire des boîtes, sauf celle de l'appelant |
+| `GET` | `/api/agents/:id` | Une boîte, ou 404 |
+| `PATCH` | `/api/agents/me` | Renommer la boîte courante |
+| `GET` | `/api/mailbox` | Compteurs de la boîte, et présence d'un veilleur (`watcher`) |
+| `GET` | `/api/links` | Boîtes liées à la boîte courante, la plus récente en tête ; les marque reçues par cet agent |
+| `POST` | `/api/messages` | Envoyer un message ; `attachments: [{ filename, mime_type?, content_base64 }]` |
+| `GET` | `/api/messages` | Lister (`folder`, `unread_only`, `from`, `thread_id`, `search`, `limit`, `offset`) |
+| `GET` | `/api/messages/:id` | Lire (`?mark_read=false` pour ne pas marquer) |
+| `POST` | `/api/messages/mark` | Marquer lu / suivi |
+| `POST` | `/api/messages/move` | Déplacer vers un dossier |
+| `POST` | `/api/messages/delete` | Corbeille ou suppression définitive |
+| `GET` | `/api/attachments/:id` | Contenu d'une pièce jointe d'un message de la boîte, en téléchargement |
+| `GET` | `/api/threads` | Fils de la boîte (`unread_only`, `search`, `limit`, `offset`) |
+| `GET` | `/api/threads/:id` | Fil complet, avec son intitulé |
+| `PATCH` | `/api/threads/:id` | Nommer le fil (`title`, `description`) — participants uniquement |
+| `GET` `POST` `DELETE` | `/api/folders[/:name]` | Gérer les dossiers |
+| `GET` | `/api/wait` | Attente longue (`timeout_seconds`, `folder`, `watcher`) ; un veilleur est aussi réveillé par une liaison (`link`) |
+| `GET` | `/admin/overview` · `/admin/messages[/:id]` | Supervision, lecture seule |
+| `GET` | `/admin/threads` | Fils du serveur entier (`agent` — une ou plusieurs adresses séparées par des virgules —, `search`, `unread_only`, `priority`, `limit`, `offset`) |
+| `GET` | `/admin/threads/:id` | Fil complet, corps inclus |
+| `GET` | `/admin/attachments/:id` | Contenu d'une pièce jointe, en téléchargement |
+| `GET` | `/admin/mailboxes/stale` | Boîtes sans activité depuis `before`, avec ce que chacune contient |
+| `GET` | `/admin/mailboxes/created-before` | Boîtes ouvertes avant `created_before`, quelle que soit leur activité |
+| `GET` | `/admin/mailboxes/empty` | Boîtes par lesquelles rien n'est jamais passé, sans critère de date |
+| `POST` | `/admin/mailboxes/purge` | Supprime les boîtes nommées (`mailboxes`, plus exactement un critère : `before`, `created_before` **ou** `empty: true`) — refusé si l'une d'elles ne répond plus au critère |
+| `DELETE` | `/admin/mailboxes/:id` | Supprime une boîte désignée, quel que soit son état — 404 si l'adresse est inconnue |
+| `GET` | `/admin/links` | Toutes les liaisons, la plus récente en tête, avec la date de réception par chaque boîte |
+| `POST` | `/admin/links` | Lie deux boîtes (`mailboxes: [a, b]`, `note?`) — 404 si l'une est inconnue, 409 si elles sont déjà liées |
+| `DELETE` | `/admin/links/:id` | Supprime une liaison |
+| `POST` | `/ui/login` · `/ui/logout` | Session de la console (`{ "token": … }` → cookie `HttpOnly`) |
+
+---
+
+## Sécurité
+
+- **Écoute exclusivement sur `127.0.0.1`** : l'interface n'est pas configurable, et une
+  valeur non-loopback fait échouer le démarrage plutôt que d'être ignorée en silence.
+- **Refus de démarrage sans jeton** : un serveur qui tourne est un serveur authentifié.
+- **Jeton vérifié sur chaque requête entrante**, avant tout traitement — y compris
+  `/health` et les fichiers de la console.
+- **Jetons par agent** (`MESSENGER_AGENT_TOKENS`) : un jeton valide ne permet pas
+  d'emprunter l'identité d'un autre agent. À préférer au jeton partagé dès que les agents
+  ne se font pas mutuellement confiance.
+- Comparaison des jetons à **temps constant**, en-têtes de sécurité (`helmet`), **rate
+  limiting** par IP, corps JSON limité à 2 Mo — sauf l'envoi d'un message, dont la limite
+  couvre ses pièces jointes et ne s'applique qu'une fois l'agent authentifié —, erreurs
+  internes génériques (le détail reste dans les logs).
+- **Pièces jointes** : servies uniquement aux deux boîtes du message (et à la console),
+  toujours en `Content-Disposition: attachment`, jamais affichées en ligne ; leur nom est
+  réduit à sa dernière composante, il ne peut désigner aucun autre répertoire.
+- **Isolation des boîtes** garantie côté serveur : les identifiants de messages fournis par
+  un agent sont systématiquement filtrés sur ses propres livraisons.
+- La console web n'insère jamais de HTML fourni par un agent : le corps des messages est
+  rendu en markdown par construction de nœuds, jamais par assignation de balisage, et la
+  CSP interdit tout script tiers.
+- La console ne peut ni écrire ni modifier un message. Ses seules commandes destructrices
+  suppriment des boîtes : réservées au jeton d'administration, confirmées deux fois, et
+  revérifiées par le serveur quand elles portent sur un lot.
+- Derrière un reverse proxy TLS, exposer le serveur en `https://` et donner cette URL aux
+  agents via `MESSENGER_SERVER_URL`. Renseigner `MESSENGER_TRUST_PROXY` (défaut `1`) : c'est
+  lui qui rend au serveur l'adresse réelle de l'appelant, donc un quota par client plutôt
+  qu'un compteur unique, et le `Secure` du cookie de console.
+- **Le jeton posé dans le bloc `env` d'un `.mcp.json` survit à ce fichier.** L'hôte enregistre
+  la configuration du serveur MCP dans ses transcriptions de session — pour Claude Code,
+  `~/.claude/projects/*.jsonl`, en clair. Le retirer du `.mcp.json` ne l'en efface pas :
+  après une fuite, il faut faire tourner le jeton, pas seulement corriger le fichier.
+
+---
+
+## Développement
+
+```bash
+npm install
+npm run generate-token   # jeton aléatoire (32 octets, base64url)
+npm run build        # tsc + copie des fichiers de la console web
+npm test             # build puis suite Vitest complète
+npm run test:watch
+npm run typecheck
+npm run serve        # serveur local sur le port 3600
+```
+
+### Structure
+
+```
+src/
+  index.ts              # point d'entrée : --server, --watch, --help, --version, sinon mode MCP
+  config.ts             # lecture et validation des variables d'environnement
+  logger.ts             # journalisation sur stderr (stdout est réservé au JSON-RPC)
+  core/store.ts         # SQLite : agents, messages, livraisons, dossiers, pièces jointes
+  core/attachments.ts   # limites des pièces jointes, en-tête de téléchargement
+  server/app.ts         # API HTTP, authentification, supervision
+  server/watchers.ts    # présence des veilleurs, en mémoire : état de connexion
+  server/start.ts       # démarrage, arrêt propre, purge de la corbeille
+  server/ui/            # console web (HTML/CSS/JS sans dépendance)
+  server/ui/markdown.js # rendu markdown du corps des messages, en nœuds DOM
+  cli/watch.ts          # mode veilleur : une ligne sur stdout par message entrant
+  cli/watch-handoff.ts  # relais 0600 entre la session MCP et son veilleur
+  mcp/mailbox-registry.ts # registre local des boîtes : reprise d'une session interrompue
+  client/               # client HTTP utilisé par le mode MCP
+  mcp/                  # définition des outils et serveur MCP stdio
+test/                   # store, config, API HTTP, outils MCP, binaire réel
+```
+
+### Tests
+
+309 tests couvrant : les suppressions de boîtes commandées depuis la console — une boîte
+désignée à la main, les vides, celles sans activité depuis une date, celles créées avant
+une date — avec leur aperçu,
+leur double confirmation et le refus nominatif d'une boîte qui ne répond plus au critère, la reprise de la boîte d'une session interrompue (clé de session de
+l'hôte, boîte seulement proposée à défaut, boîte d'une session vivante jamais reprise), le rendu markdown des messages et l'aplatissement des aperçus (dont
+l'innocuité du rendu : ni HTML interprété, ni lien vers un autre schéma qu'`http`, `https`
+ou `mailto`), le stockage et l'isolation des boîtes, la validation de configuration,
+l'API HTTP et son authentification (refus systématique sans jeton, jeton partagé, jetons par
+agent, jeton de console distinct), les outils MCP de bout en bout (deux agents qui
+conversent à travers un vrai serveur), l'allocation des boîtes par session — deux processus
+MCP lancés avec la même configuration obtiennent deux adresses différentes, et une
+troisième session reprend la boîte de l'une d'elles — et le binaire publié lui-même.
+
+La notification passive est couverte de bout en bout : le relais vers le veilleur (isolation
+entre boîtes, adresse jamais transformée en chemin, nettoyage), le format d'évènement (une
+ligne, quel que soit le sujet), et un veilleur réellement lancé comme processus séparé, sans
+jeton dans son environnement, qui émet sa ligne à l'arrivée d'un message — et `whoami` qui
+passe de « NOT armed » à « armed » quand ce veilleur prend son poste.
+
+---
+
+## Licence
+
+ISC