@imenam/mcp-messenger 1.0.32 → 1.0.34

package/README.md

@@ -1,772 +1,832 @@
-# 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 ». L'**échelle est régulière** sur toute la fenêtre détaillée, avec six
-  graduations au plus, chacune à son heure. 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. Les boîtes empilées ont aussi leur
-  poignée, au survol, et reçoivent le fil comme les autres ; pendant le glissé, la boîte
-  survolée est mise en avant et « + N autres » se déplie après un court survol. Le volet
-  classe les candidats par rang, puis les boîtes plus anciennes ; un motif facultatif
-  accompagne la liaison.
-- **Renommer une boîte** : le crayon qui apparaît au survol, ou deux clics rapprochés sur la
-  boîte, changent son nom en champ de saisie — récente ou empilée. Entrée ou un clic ailleurs
-  enregistre, Échap annule, un champ vidé efface le nom. Ce nom remplace celui que l'agent a
-  pu poser avec `rename_mailbox`, et l'agent le lit à son prochain `whoami`.
-- **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 |
-| `PATCH` | `/admin/mailboxes/:id` | Renomme une boîte (`display_name` ; vide ou `null` efface le nom) — 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
+# 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_DB_PATH` | `MESSENGER_SERVER_URL`, `MESSENGER_API_KEY` |
+| 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
+npx @imenam/mcp-messenger --server
+# → listening on http://127.0.0.1:3600 (loopback only)
+# → auth: API keys on every agent request, console account on the web console
+# → web console: http://127.0.0.1:3600/ui/
+# → WARN no console account yet — open the web console to create it
+# → WARN setup code: K7QD-4MPX-9TRA
+```
+
+Aucun secret ne passe par l'environnement. Au premier lancement, ouvrir la console
+(`/ui/`) : elle demande le **code d'installation** écrit dans le journal, puis un nom
+d'utilisateur et un mot de passe (12 caractères au moins). Ce compte ouvre la console ; le
+code, qui prouve l'accès à la machine, ne sert qu'une fois et disparaît avec la page.
+
+Ensuite, dans l'onglet **Clés API** de la console, créer une clé par poste ou par agent.
+
+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. **Une clé API active est exigée sur chaque requête d'agent** — API et `/health`
+   comprises. Une clé révoquée ou expirée est refusée dès l'appel suivant.
+3. **La console ne s'ouvre qu'avec son compte.** Aucune clé API n'ouvre `/admin`, et la
+   session de la console (cookie `HttpOnly`) n'ouvre rien d'autre.
+
+> **Migration depuis les jetons.** `MESSENGER_TOKEN`, `MESSENGER_AGENT_TOKENS` et
+> `MESSENGER_ADMIN_TOKEN` ne sont plus lus : le serveur refuse de démarrer tant qu'ils sont
+> posés, et le client refuse `MESSENGER_TOKEN`. Les retirer, créer le compte de la console,
+> puis une clé par client, à poser dans `MESSENGER_API_KEY`. Les boîtes et les messages
+> existants sont conservés.
+
+#### Clés API
+
+Une clé se crée dans la console avec un nom, une portée et une durée :
+
+- **Un seul agent** : la clé porte le nom de l'agent (par exemple `Documentor Dev`) et,
+  si on le souhaite, sa description. Les boîtes ouvertes avec elle prennent ce nom et
+  cette description, et elle n'ouvre que les boîtes de cet agent. `MESSENGER_AGENT_NAME`
+  et `MESSENGER_AGENT_DESCRIPTION` restent vides côté client : une autre valeur y fait
+  refuser l'enregistrement de la boîte. Modifier la description dans la console la
+  reporte sur les boîtes déjà ouvertes avec la clé.
+- **Tous les agents** : la clé ouvre toutes les boîtes ; chaque client donne alors son nom
+  et sa description dans `MESSENGER_AGENT_NAME` et `MESSENGER_AGENT_DESCRIPTION`. C'est
+  un mode « cercle de confiance », pour les sessions d'une même personne.
+- **Durée** : 30 jours, 90 jours, 1 an ou sans échéance. La liste signale une clé qui expire
+  dans les 7 jours ; on la prolonge depuis son détail.
+
+La clé (`mk_…`) n'est affichée qu'une fois, avec le bloc `.mcp.json` et la commande
+d'installation déjà remplis ; le serveur n'en garde qu'une empreinte. Depuis le détail
+d'une clé : renommer, prolonger, voir les boîtes ouvertes avec elle, la **remplacer** (une
+nouvelle clé aux mêmes réglages ; l'ancienne reste acceptée 24 h) ou la **révoquer**.
+
+#### Compte de la console
+
+La page **Mon compte** (menu en haut à droite) change l'identifiant et le mot de passe — ce
+qui ferme toutes les autres sessions — et liste les navigateurs connectés, chacun
+déconnectable. « Rester connecté » à la connexion garde la session 30 jours ; sinon elle
+dure 12 h et meurt avec le navigateur. Le formulaire de connexion est limité à dix essais
+par quart d'heure.
+
+Mot de passe perdu : sur la machine du serveur,
+
+```bash
+npx @imenam/mcp-messenger --reset-password
+```
+
+écrit un mot de passe neuf sur la sortie standard et ferme toutes les sessions. La
+commande lit la base indiquée par `MESSENGER_DB_PATH`.
+
+### 2. Déclarer le MCP côté agent
+
+La fenêtre de création d'une clé donne la commande exacte, à lancer dans le dossier du
+projet de l'agent :
+
+```bash
+npx -y @imenam/mcp-messenger --claude-setup-mcp --server-url https://messenger.exemple.fr --api-key mk_…
+```
+
+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). Sans
+`--api-key`, `MESSENGER_API_KEY` reste vide, à remplir ; sans `--server-url`, l'adresse
+est celle du serveur local.
+
+Le bloc généré, à écrire à la main si tu préfères :
+
+```json
+{
+  "mcpServers": {
+    "messenger": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-messenger"],
+      "env": {
+        "MESSENGER_SERVER_URL": "https://messenger.exemple.fr",
+        "MESSENGER_API_KEY": "mk_…"
+      }
+    }
+  }
+}
+```
+
+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.
+
+Un refus du serveur, lui, arrête le démarrage avec son motif : clé inconnue, révoquée ou
+expirée, nom ou description d'agent qui contredit une clé liée à un agent. Il ne passerait
+pas en réessayant, c'est la configuration qui est à corriger.
+
+### 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 la clé.** 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_API_KEY`. 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_API_KEY` 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 clé API liée à un agent, sinon la configuration du client (`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 le nom d'utilisateur et le mot de passe du compte
+(`POST /ui/login`) et ouvre une **session** — 12 heures, ou 30 jours avec « rester
+connecté » — portée par un cookie `HttpOnly` + `SameSite=Strict` (+ `Secure` en HTTPS).
+Le cookie ne contient qu'un identifiant de session opaque, dont le serveur ne garde que
+l'empreinte en base : la session survit à un redémarrage, et se ferme sur « Se
+déconnecter » ou depuis Mon compte. Le navigateur ne stocke rien d'autre.
+
+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. À l'inverse, aucune clé API n'ouvre `/admin`. Les
+formulaires de connexion, de création du compte et de changement de mot de passe sont
+limités à 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 ». L'**échelle est régulière** sur toute la fenêtre détaillée, avec six
+  graduations au plus, chacune à son heure. 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. Les boîtes empilées ont aussi leur
+  poignée, au survol, et reçoivent le fil comme les autres ; pendant le glissé, la boîte
+  survolée est mise en avant et « + N autres » se déplie après un court survol. Le volet
+  classe les candidats par rang, puis les boîtes plus anciennes ; un motif facultatif
+  accompagne la liaison.
+- **Renommer une boîte** : le crayon qui apparaît au survol, ou deux clics rapprochés sur la
+  boîte, changent son nom en champ de saisie — récente ou empilée. Entrée ou un clic ailleurs
+  enregistre, Échap annule, un champ vidé efface le nom. Ce nom remplace celui que l'agent a
+  pu poser avec `rename_mailbox`, et l'agent le lit à son prochain `whoami`.
+- **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_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 |
+
+Aucun secret n'est à poser côté serveur : le compte de la console et les clés API vivent
+dans la base. `MESSENGER_TOKEN`, `MESSENGER_AGENT_TOKENS` et `MESSENGER_ADMIN_TOKEN` font
+échouer le démarrage tant qu'ils sont posés.
+
+### 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_API_KEY` | ✅ | Clé API créée dans la console, présentée sur chaque appel |
+| `MESSENGER_AGENT_NAME` | — | Nom de l'agent, pour une clé valable pour tous les agents. Une clé liée à un agent donne le sien, et en refuse un autre |
+| `MESSENGER_AGENT_DESCRIPTION` | — | À quoi sert cet agent, pour une clé valable pour tous les agents. Une clé liée à un agent porte la sienne, et en refuse une autre |
+| `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
+
+Les routes des agents exigent une clé API active, présentée par `Authorization: Bearer
+<clé>` 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` ; une clé liée à un agent n'ouvre que les boîtes de
+cet agent (403 sinon). Les routes `/admin/*` n'acceptent que 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 |
+| `PATCH` | `/admin/mailboxes/:id` | Renomme une boîte (`display_name` ; vide ou `null` efface le nom) — 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 |
+| `GET` | `/admin/keys` | Clés API, sans leur secret : début et fin, agent, échéance, dernier usage, état (`active`, `expired`, `revoked`) |
+| `POST` | `/admin/keys` | Crée une clé (`name`, `agent_name` ou `null` pour tous les agents, `agent_description?` pour une clé liée, `lifetime_days` ou `null`) — rend le secret, une seule fois |
+| `GET` `PATCH` | `/admin/keys/:id` | Détail d'une clé et boîtes ouvertes avec elle · renommer (`name`), changer la description de l'agent (`agent_description`, reportée sur ses boîtes) |
+| `POST` | `/admin/keys/:id/extend` | Repousse l'échéance de `days` jours, ou la retire (`days: null`) |
+| `POST` | `/admin/keys/:id/rotate` | Nouvelle clé aux mêmes réglages ; l'ancienne reste acceptée 24 h |
+| `POST` | `/admin/keys/:id/revoke` | Révoque la clé, refusée dès l'appel suivant |
+| `GET` `PATCH` | `/admin/account` | Compte et sessions de la console · changer l'identifiant (`username`) |
+| `POST` | `/admin/account/password` | Change le mot de passe (`current_password`, `new_password`) et ferme les autres sessions |
+| `DELETE` | `/admin/account/sessions/:id` | Ferme une session |
+| `POST` | `/admin/account/sessions/revoke-others` | Ferme toutes les sessions sauf la courante |
+| `GET` | `/ui/session` | Ce que la console affiche en arrivant : `authenticated`, `setup_required`, `user` |
+| `POST` | `/ui/setup` | Crée le compte de la console (`code`, `username`, `password`), tant qu'il n'existe pas |
+| `POST` | `/ui/login` · `/ui/logout` | Session de la console (`username`, `password`, `remember` → cookie `HttpOnly`) ; 429 avec `retry_after_seconds` au-delà de 10 essais |
+
+---
+
+## 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.
+- **Aucun secret stocké en clair** : le mot de passe est haché par scrypt, salé ; une clé
+  API ou une session n'est gardée que sous forme d'empreinte SHA-256. Une clé ne se relit
+  donc pas : perdue, on la révoque et on en crée une autre.
+- **Clé vérifiée sur chaque requête d'agent**, avant tout traitement — y compris `/health`.
+  Une clé révoquée ou expirée est refusée dès l'appel suivant.
+- **Clés liées à un agent** : une clé ne permet pas d'ouvrir les boîtes d'un autre agent. À
+  préférer à une clé valable pour tous les agents dès que les agents ne se font pas
+  mutuellement confiance.
+- **Création du compte gardée** par un code d'installation écrit dans le journal du
+  serveur, à usage unique : le premier visiteur venu ne peut pas s'approprier la console.
+- **Connexion** : un nom inconnu coûte le même calcul qu'un mot de passe faux, la réponse
+  ne dit pas lequel des deux est faux, et les formulaires sont limités à 10 essais par
+  quart d'heure.
+- 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 compte de la console, 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.
+- **La clé posée 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. La retirer du `.mcp.json` ne l'en efface pas :
+  après une fuite, il faut la remplacer ou la révoquer depuis la console.
+
+---
+
+## Développement
+
+```bash
+npm install
+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/access-store.ts  # SQLite : compte de la console, ses sessions, clés API
+  core/credentials.ts   # hachage des mots de passe, empreintes, génération des secrets
+  server/console-session.ts # cookie de session, code d'installation du premier compte
+  cli/reset-password.ts # --reset-password : mot de passe neuf, sessions fermées
+  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
+
+382 tests couvrant : le compte de la console (création gardée par le code d'installation,
+connexion et limitation des essais, changement de mot de passe qui ferme les autres
+sessions, fermeture d'une session), les clés API (montrées une fois, liées à un agent ou
+non, prolongées, remplacées, révoquées, expirées) et leurs écrans dans la console, 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 clé, session de console qui
+n'ouvre pas l'API, clé qui n'ouvre pas la console), 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
+clé 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