npm - @imenam/mcp-messenger - Versions diffs - 1.0.25 → 1.0.27 - Mend

@imenam/mcp-messenger 1.0.25 → 1.0.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md +670 -666
package/dist/src/cli/setup-mcp.js +13 -14
package/dist/src/cli/watch.js +0 -1
package/dist/src/config.d.ts +0 -11
package/dist/src/config.js +0 -14
package/dist/src/mcp/mailbox-registry.d.ts +15 -1
package/dist/src/mcp/mailbox-registry.js +0 -0
package/dist/src/mcp/resume-state.d.ts +11 -5
package/dist/src/mcp/start.d.ts +9 -8
package/dist/src/mcp/start.js +41 -45
package/dist/src/mcp/tools.js +10 -5
package/dist/src/server/ui/app.js +18 -5
package/dist/src/version.d.ts +1 -1
package/dist/src/version.js +1 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,666 +1,670 @@
-# 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
-# Un jeton, à conserver : il sera demandé au serveur, aux agents et à la console.
-npx @imenam/mcp-messenger --generate-token
-MESSENGER_TOKEN=<le-jeton> npx @imenam/mcp-messenger --server
-# → listening on http://127.0.0.1:3600 (loopback only)
-# → auth: shared token — required on every request
-# → web console: http://127.0.0.1:3600/ui/ (asks for MESSENGER_ADMIN_TOKEN once)
-```
-Deux 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.
-### 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
-    persistent:  true
-```
-L'agent recopie ces trois arguments dans l'outil `Monitor` de son hôte, et c'est fini pour la
-session. 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.
-**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, trois chemins, du plus certain au plus approximatif :
-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.
-2. **La seule boîte orpheline du projet, si elle a servi.** Sans identifiant, ou s'il a
-   changé, une boîte du même projet que plus personne ne tient est reprise quand elle est
-   la seule à l'être. Une boîte vide ne l'est jamais : il n'y a rien à y reprendre.
-3. **Le choix de l'agent.** Plusieurs orphelines, ou une reprise incertaine : rien n'est
-   pris en silence. `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 : une session reprise le reçoit en entier.
-`MESSENGER_RESUME` tranche pour ceux que la reprise automatique gêne : `auto` par défaut,
-`ask` pour que tout passe par l'agent, `off` pour repartir chaque fois d'une boîte neuve.
-Le journal du démarrage dit lequel des trois chemins 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. **Deux
-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.
-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 trois 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` | `MESSENGER_TOKEN` | Jeton de la console ; obligatoire si seul `MESSENGER_AGENT_TOKENS` est défini |
-| `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/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 `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`.
----
-## 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
-287 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 — 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 orpheline, 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
+# Un jeton, à conserver : il sera demandé au serveur, aux agents et à la console.
+npx @imenam/mcp-messenger --generate-token
+MESSENGER_TOKEN=<le-jeton> npx @imenam/mcp-messenger --server
+# → listening on http://127.0.0.1:3600 (loopback only)
+# → auth: shared token — required on every request
+# → web console: http://127.0.0.1:3600/ui/ (asks for MESSENGER_ADMIN_TOKEN once)
+```
+Deux 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.
+### 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
+    persistent:  true
+```
+L'agent recopie ces trois arguments dans l'outil `Monitor` de son hôte, et c'est fini pour la
+session. 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.
+**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. **Deux
+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.
+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 trois 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` | `MESSENGER_TOKEN` | Jeton de la console ; obligatoire si seul `MESSENGER_AGENT_TOKENS` est défini |
+| `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/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 `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`.
+---
+## 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
+287 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 — 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