@imenam/mcp-messenger 1.0.16 → 1.0.18

package/.env.example

@@ -60,3 +60,19 @@ MESSENGER_TOKEN=change-me
 
 # Délai maximal d'un appel HTTP vers le serveur (ms).
 MESSENGER_TIMEOUT_MS=15000
+
+# Reprise de la boîte d'une session interrompue puis relancée.
+# auto (défaut) : la session retrouve sa boîte quand c'est certain (l'hôte a redonné le
+#   même identifiant de session) ou sans ambiguïté (une seule boîte du projet n'est plus
+#   tenue par personne, et elle a servi).
+# ask : rien n'est repris tout seul ; `whoami` présente les boîtes en attente, l'agent en
+#   rattache une avec `attach_to_mailbox`.
+# off : chaque session repart d'une boîte neuve.
+# Une boîte tenue par une session vivante n'est jamais reprise, quel que soit le réglage.
+# MESSENGER_RESUME=auto
+
+# Identifiant de la session hôte, celui qui relie une session reprise à celle qu'elle
+# continue. Inutile à renseigner : il est lu dans l'environnement hérité de l'hôte
+# (CLAUDE_CODE_SESSION_ID et équivalents). À poser soi-même pour des sessions lancées par
+# script. Il n'est jamais écrit sur le disque en clair, seule son empreinte l'est.
+# MESSENGER_SESSION_KEY=

package/README.md

@@ -312,20 +312,61 @@ d'ouverture : rien n'est jamais illisible, mais rien n'est aussi parlant qu'un n
 Ces noms apparaissent dans `list_threads`, `list_messages`, `get_thread`, les
 notifications du veilleur et la console web.
 
-### Reprendre le travail d'une session terminée
-
-Les boîtes survivent aux sessions. Après un redémarrage :
+### Reprendre le travail d'une session interrompue
+
+Une session relancée est un nouveau processus. Sans mémoire, elle se ferait allouer une
+boîte neuve et laisserait derrière elle ses fils, ses non-lus et **l'adresse que ses
+correspondants connaissent** ; répété, cela multiplie les boîtes pour un travail unique.
+La session retrouve donc la sienne toute seule, par un **registre local**.
+
+Chaque session y inscrit sa boîte, avec l'empreinte de son projet et la preuve qu'elle
+vit : le processus qui la tient et un battement de cœur. **Une boîte tenue par une session
+vivante n'est jamais reprise** — c'est ce qui distingue ce mécanisme d'une adresse
+partagée, et ce qui protège deux sessions ouvertes en parallèle sur le même projet. Une
+boîte n'est reprenable qu'une fois **orpheline** : session close proprement, processus
+mort, ou battement arrêté depuis plusieurs minutes.
+
+Au démarrage, trois chemins, du plus certain au plus approximatif :
+
+1. **Le même identifiant de session.** L'hôte en donne un à sa session, et le processus MCP
+   en hérite. Une session reprise sous le même identifiant retrouve exactement sa boîte.
+   Rien n'est à configurer : la variable est lue dans l'environnement
+   (`CLAUDE_CODE_SESSION_ID` et équivalents), et `MESSENGER_SESSION_KEY` permet de la poser
+   soi-même pour des sessions lancées par script. Ni le projet ni cet identifiant ne sont
+   écrits en clair : le registre n'en garde que l'empreinte.
+2. **La seule boîte orpheline du projet, si elle a servi.** Sans identifiant, ou s'il a
+   changé, une boîte du même projet que plus personne ne tient est reprise quand elle est
+   la seule à l'être. Une boîte vide ne l'est jamais : il n'y a rien à y reprendre.
+3. **Le choix de l'agent.** Plusieurs orphelines, ou une reprise incertaine : rien n'est
+   pris en silence. `whoami` les liste avec leur nom, leur nombre de messages et leurs
+   non-lus, et l'agent rattache la bonne avec `attach_to_mailbox`. Les instructions du
+   serveur MCP lui disent aussi de rattacher une adresse `box_…` qu'il reconnaîtrait dans
+   son propre contexte : une session reprise le reçoit en entier.
+
+`MESSENGER_RESUME` tranche pour ceux que la reprise automatique gêne : `auto` par défaut,
+`ask` pour que tout passe par l'agent, `off` pour repartir chaque fois d'une boîte neuve.
+
+Le journal du démarrage dit lequel des trois chemins a servi, et quelle variable a fourni
+l'identifiant de session — c'est là qu'on vérifie ce que l'hôte transmet réellement.
+
+Le rattachement manuel reste disponible en toutes circonstances :
 
 > « Reprends le travail de la session précédente, sa boîte est `box_9f2c4a01b3d7e5f8`. »
 
 L'agent appelle `attach_to_mailbox` avec cette adresse : il lit alors le courrier de cette
 boîte, y compris les messages arrivés pendant l'interruption, et écrit sous cette adresse.
 `attach_to_mailbox` sans argument le ramène à sa propre boîte. Plusieurs sessions peuvent
-être attachées à la même boîte — c'est volontaire, et c'est ce qui permet la reprise.
+ê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
@@ -336,7 +377,7 @@ configuration partagent alors la même boîte. Utile pour un service unique et s
 
 ## Console web
 
-`http://127.0.0.1:3600/ui/` affiche, en lecture seule, **tous les échanges** de la flotte,
+`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 :
 
@@ -345,7 +386,8 @@ correspondants et l'état de lecture :
   chevron sur ses boîtes ; 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. Cliquer l'agent filtre les fils sur
   **toutes ses sessions**, cliquer une boîte sur **cette seule session**. La colonne se
-  replie sur les seuls avatars d'agents quand la place manque.
+  replie sur les seuls avatars d'agents quand la place manque, son bouton de repli restant
+  en place : c'est lui qui la rouvre.
 
   **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
@@ -398,7 +440,31 @@ navigateur de l'administrateur. Les routes `/admin` acceptent toujours le jeton
 `Authorization: Bearer` pour les scripts. Le formulaire est limité à 10 tentatives par
 quart d'heure et par IP.
 
-La console n'écrit jamais : elle ne peut ni envoyer, ni supprimer, ni modifier.
+La console n'envoie ni ne modifie aucun message. Elle ne commande qu'une seule écriture,
+et c'est une suppression : la **purge des boîtes inactives**, derrière l'icône de corbeille
+de la barre du haut.
+
+Une boîte est inactive quand plus rien ne l'a touchée depuis la date choisie : ni
+connexion, ni message reçu ou envoyé. **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.
+
+La purge se fait en deux temps, parce qu'elle ne se rattrape 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. Le
+   serveur, lui, reconfronte chacune à la date avant de supprimer : une boîte redevenue
+   active entre l'aperçu et la confirmation fait échouer la purge entière, nommément.
+   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.
 
 ---
 
@@ -465,6 +531,8 @@ la console (cookie), qui elle n'ouvre rien d'autre.
 | `GET` | `/admin/overview` · `/admin/messages[/:id]` | Supervision, lecture seule |
 | `GET` | `/admin/threads` | Fils du serveur entier (`agent` — une ou plusieurs adresses séparées par des virgules —, `search`, `unread_only`, `priority`, `limit`, `offset`) |
 | `GET` | `/admin/threads/:id` | Fil complet, corps inclus |
+| `GET` | `/admin/mailboxes/stale` | Boîtes sans activité depuis `before`, avec ce que chacune contient |
+| `POST` | `/admin/mailboxes/purge` | Supprime les boîtes nommées (`before`, `mailboxes`) — refusé si l'une d'elles est redevenue active |
 | `POST` | `/ui/login` · `/ui/logout` | Session de la console (`{ "token": … }` → cookie `HttpOnly`) |
 
 ---
@@ -484,8 +552,12 @@ la console (cookie), qui elle n'ouvre rien d'autre.
   dans les logs).
 - **Isolation des boîtes** garantie côté serveur : les identifiants de messages fournis par
   un agent sont systématiquement filtrés sur ses propres livraisons.
-- La console web n'insère jamais de HTML fourni par un agent (`textContent` uniquement) et
-  la CSP interdit tout script tiers.
+- 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. Sa seule commande destructrice est
+  la purge des boîtes inactives, réservée au jeton d'administration, confirmée deux fois et
+  revérifiée par le serveur avant exécution.
 - Derrière un reverse proxy TLS, exposer le serveur en `https://` et donner cette URL aux
   agents via `MESSENGER_SERVER_URL`.
 
@@ -518,6 +590,7 @@ src/
   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
@@ -525,7 +598,9 @@ test/                   # store, config, API HTTP, outils MCP, binaire réel
 
 ### Tests
 
-187 tests couvrant : le rendu markdown des messages et l'aplatissement des aperçus (dont
+231 tests couvrant : la purge des boîtes inactives commandée depuis la console (aperçu,
+double confirmation, refus nominatif d'une boîte redevenue active), la reprise de la boîte d'une session interrompue (clé de session de
+l'hôte, boîte orpheline, boîte d'une session vivante jamais reprise), le rendu markdown des messages et l'aplatissement des aperçus (dont
 l'innocuité du rendu : ni HTML interprété, ni lien vers un autre schéma qu'`http`, `https`
 ou `mailto`), le stockage et l'isolation des boîtes, la validation de configuration,
 l'API HTTP et son authentification (refus systématique sans jeton, jeton partagé, jetons par

package/dist/src/cli/setup-mcp.js

@@ -47,6 +47,7 @@ const OPTIONAL_VARS = [
     ["MESSENGER_AGENT_NAME", "nom de l'agent (le projet, typiquement) ; distinct du nom de la boîte, que l'agent pose lui-même"],
     ["MESSENGER_AGENT_DESCRIPTION", "à quoi sert cet agent, pour ses correspondants"],
     ["MESSENGER_TIMEOUT_MS", "délai maximal d'un appel HTTP (défaut : 15000)"],
+    ["MESSENGER_RESUME", "reprise de la boîte d'une session interrompue : auto (défaut), ask, off"],
 ];
 const CLAUDE_MD_MARKER = "<!-- mcp-messenger -->";
 const CLAUDE_MD_BLOCK = `${CLAUDE_MD_MARKER}

package/dist/src/cli/watch.js

@@ -47,6 +47,11 @@ export function resolveWatchConfig(mailbox, env = process.env) {
             agentName: null,
             agentDescription: null,
             timeoutMs: Number(env.MESSENGER_TIMEOUT_MS) || 15_000,
+            // Le veilleur écoute une adresse qu'on lui donne : il n'alloue rien et n'a donc
+            // aucune boîte à reprendre.
+            sessionKey: null,
+            sessionKeySource: null,
+            resume: "off",
         },
     };
 }

package/dist/src/config.d.ts

@@ -22,6 +22,16 @@ export interface ServerConfig {
     /** Plafond d'attente d'un `wait_for_message` (secondes). */
     maxWaitSeconds: number;
 }
+/**
+ * Ce qu'une session fait des boîtes laissées par une session précédente du même projet.
+ *
+ * `auto` : reprise sans rien demander quand elle est certaine (clé de session identique)
+ * ou sans ambiguïté (une seule boîte orpheline, et elle a servi).
+ * `ask` : rien n'est repris tout seul, les candidates sont présentées à l'agent.
+ * `off` : aucune recherche, chaque session repart d'une boîte neuve.
+ */
+export declare const RESUME_MODES: readonly ["auto", "ask", "off"];
+export type ResumeMode = (typeof RESUME_MODES)[number];
 export interface AgentConfig {
     /** null = une boîte propre à cette session est allouée au démarrage. */
     agentId: string | null;
@@ -31,7 +41,28 @@ export interface AgentConfig {
     agentName: string | null;
     agentDescription: string | null;
     timeoutMs: number;
+    /**
+     * Identifiant de la session hôte, s'il est lisible. C'est lui qui relie une session
+     * reprise à celle qu'elle continue ; il n'est jamais écrit sur le disque en clair.
+     */
+    sessionKey: string | null;
+    /** D'où vient cette clé, pour que le journal puisse le dire. */
+    sessionKeySource: string | null;
+    resume: ResumeMode;
 }
+/**
+ * Variables où chercher l'identifiant de la session hôte, dans l'ordre.
+ *
+ * Rien n'a besoin d'être configuré : le processus MCP est un enfant de l'hôte et hérite
+ * de son environnement. `MESSENGER_SESSION_KEY` vient en tête pour qui lance ses sessions
+ * autrement et veut poser la clé lui-même.
+ */
+export declare const SESSION_KEY_VARS: readonly ["MESSENGER_SESSION_KEY", "CLAUDE_CODE_SESSION_ID", "CLAUDE_SESSION_ID", "CURSOR_SESSION_ID", "MCP_SESSION_ID"];
+/** Première clé de session lisible dans l'environnement, avec la variable qui l'a donnée. */
+export declare function readSessionKey(env?: NodeJS.ProcessEnv): {
+    key: string;
+    source: string;
+} | null;
 export declare function isLoopbackHost(host: string): boolean;
 export declare function loadServerConfig(env?: NodeJS.ProcessEnv): ServerConfig;
 export declare function loadAgentConfig(env?: NodeJS.ProcessEnv): AgentConfig;

package/dist/src/config.js

@@ -9,6 +9,38 @@ export class ConfigError extends Error {
 }
 /** Le serveur n'écoute jamais ailleurs : la boîte aux lettres reste locale à la machine. */
 export const SERVER_HOST = "127.0.0.1";
+/**
+ * Ce qu'une session fait des boîtes laissées par une session précédente du même projet.
+ *
+ * `auto` : reprise sans rien demander quand elle est certaine (clé de session identique)
+ * ou sans ambiguïté (une seule boîte orpheline, et elle a servi).
+ * `ask` : rien n'est repris tout seul, les candidates sont présentées à l'agent.
+ * `off` : aucune recherche, chaque session repart d'une boîte neuve.
+ */
+export const RESUME_MODES = ["auto", "ask", "off"];
+/**
+ * Variables où chercher l'identifiant de la session hôte, dans l'ordre.
+ *
+ * Rien n'a besoin d'être configuré : le processus MCP est un enfant de l'hôte et hérite
+ * de son environnement. `MESSENGER_SESSION_KEY` vient en tête pour qui lance ses sessions
+ * autrement et veut poser la clé lui-même.
+ */
+export const SESSION_KEY_VARS = [
+    "MESSENGER_SESSION_KEY",
+    "CLAUDE_CODE_SESSION_ID",
+    "CLAUDE_SESSION_ID",
+    "CURSOR_SESSION_ID",
+    "MCP_SESSION_ID",
+];
+/** Première clé de session lisible dans l'environnement, avec la variable qui l'a donnée. */
+export function readSessionKey(env = process.env) {
+    for (const name of SESSION_KEY_VARS) {
+        const value = nonEmpty(env[name]);
+        if (value)
+            return { key: value, source: name };
+    }
+    return null;
+}
 export function isLoopbackHost(host) {
     return LOOPBACK_HOSTS.has(host.trim().toLowerCase().replace(/^\[|\]$/g, ""));
 }
@@ -70,6 +102,11 @@ export function loadAgentConfig(env = process.env) {
     if (url.protocol !== "http:" && url.protocol !== "https:") {
         throw new ConfigError(`MESSENGER_SERVER_URL must use http or https (got ${url.protocol}).`);
     }
+    const resume = nonEmpty(env.MESSENGER_RESUME)?.toLowerCase() ?? "auto";
+    if (!RESUME_MODES.includes(resume)) {
+        throw new ConfigError(`MESSENGER_RESUME must be one of ${RESUME_MODES.join(", ")} (got "${resume}").`);
+    }
+    const session = readSessionKey(env);
     return {
         agentId,
         serverUrl: rawUrl.replace(/\/+$/, ""),
@@ -77,6 +114,9 @@ export function loadAgentConfig(env = process.env) {
         agentName: nonEmpty(env.MESSENGER_AGENT_NAME),
         agentDescription: nonEmpty(env.MESSENGER_AGENT_DESCRIPTION),
         timeoutMs: parseIntEnv(env.MESSENGER_TIMEOUT_MS, 15_000, "MESSENGER_TIMEOUT_MS"),
+        sessionKey: session?.key ?? null,
+        sessionKeySource: session?.source ?? null,
+        resume: resume,
     };
 }
 function parseAgentTokens(raw) {

package/dist/src/core/store.d.ts

@@ -87,6 +87,31 @@ export declare class MessageStore extends EventEmitter<StoreEvents> {
     stats(agentId: string): MailboxStats;
     /** Purge les livraisons restées en corbeille au-delà de `days`. Renvoie le nombre supprimé. */
     purgeTrash(days: number): number;
+    /**
+     * Boîtes dont plus rien ne bouge depuis `before`, avec ce que leur suppression coûterait.
+     *
+     * L'inactivité se mesure au plus récent de trois moments : la dernière connexion, la
+     * dernière livraison, et la création. Le dernier compte autant que les autres — une
+     * boîte allouée il y a une minute et qui n'a rien fait n'est pas une boîte à l'abandon,
+     * c'est une session qui n'a pas encore parlé.
+     */
+    staleMailboxes(before: string): (AgentDirectoryEntry & {
+        messages: number;
+    })[];
+    /**
+     * Supprime ces boîtes et tout ce qui n'appartenait qu'à elles.
+     *
+     * Un message a deux copies, une par correspondant : effacer une boîte n'efface donc que
+     * sa moitié. Le message lui-même ne disparaît qu'une fois sa dernière copie partie —
+     * autrement dit quand plus personne ne peut le lire. Ce que l'autre côté a reçu reste
+     * intact, avec l'adresse de l'expéditeur telle qu'elle a été livrée.
+     */
+    deleteMailboxes(ids: string[]): {
+        mailboxes: number;
+        deliveries: number;
+        messages: number;
+        threads: number;
+    };
     /** Vue globale : tous les messages du serveur, indépendamment des boîtes. */
     listAllMessages(opts?: {
         search?: string;

package/dist/src/core/store.js

@@ -581,7 +581,64 @@ export class MessageStore extends EventEmitter {
         this.dropOrphanMessages();
         return removed;
     }
-    // --- Supervision (interface web, lecture seule) --------------------------
+    /**
+     * Boîtes dont plus rien ne bouge depuis `before`, avec ce que leur suppression coûterait.
+     *
+     * L'inactivité se mesure au plus récent de trois moments : la dernière connexion, la
+     * dernière livraison, et la création. Le dernier compte autant que les autres — une
+     * boîte allouée il y a une minute et qui n'a rien fait n'est pas une boîte à l'abandon,
+     * c'est une session qui n'a pas encore parlé.
+     */
+    staleMailboxes(before) {
+        const rows = this.db
+            .prepare(`SELECT a.*, ${LAST_ACTIVITY} AS last_activity_at,
+                (SELECT COUNT(*) FROM deliveries d WHERE d.agent_id = a.id) AS messages
+           FROM agents a
+          WHERE MAX(${LAST_ACTIVITY}, a.created_at) < ?
+          ORDER BY MAX(${LAST_ACTIVITY}, a.created_at) ASC`)
+            .all(before);
+        return rows.map((row) => ({
+            ...row,
+            registered: Boolean(row.registered),
+            last_activity_at: row.last_activity_at || null,
+        }));
+    }
+    /**
+     * Supprime ces boîtes et tout ce qui n'appartenait qu'à elles.
+     *
+     * Un message a deux copies, une par correspondant : effacer une boîte n'efface donc que
+     * sa moitié. Le message lui-même ne disparaît qu'une fois sa dernière copie partie —
+     * autrement dit quand plus personne ne peut le lire. Ce que l'autre côté a reçu reste
+     * intact, avec l'adresse de l'expéditeur telle qu'elle a été livrée.
+     */
+    deleteMailboxes(ids) {
+        if (ids.length === 0)
+            return { mailboxes: 0, deliveries: 0, messages: 0, threads: 0 };
+        return this.db.transaction(() => {
+            const messagesBefore = this.db.prepare("SELECT COUNT(*) AS n FROM messages").get().n;
+            const threadsBefore = this.db.prepare("SELECT COUNT(*) AS n FROM threads").get().n;
+            let mailboxes = 0;
+            let deliveries = 0;
+            const dropDeliveries = this.db.prepare("DELETE FROM deliveries WHERE agent_id = ?");
+            const dropFolders = this.db.prepare("DELETE FROM folders WHERE agent_id = ?");
+            const dropAgent = this.db.prepare("DELETE FROM agents WHERE id = ?");
+            for (const id of ids) {
+                deliveries += dropDeliveries.run(id).changes;
+                dropFolders.run(id);
+                mailboxes += dropAgent.run(id).changes;
+            }
+            this.dropOrphanMessages();
+            const messagesAfter = this.db.prepare("SELECT COUNT(*) AS n FROM messages").get().n;
+            const threadsAfter = this.db.prepare("SELECT COUNT(*) AS n FROM threads").get().n;
+            return {
+                mailboxes,
+                deliveries,
+                messages: messagesBefore - messagesAfter,
+                threads: threadsBefore - threadsAfter,
+            };
+        })();
+    }
+    // --- Supervision (interface web, lecture seule sauf purge) ---------------
     /** Vue globale : tous les messages du serveur, indépendamment des boîtes. */
     listAllMessages(opts = {}) {
         const limit = clamp(opts.limit ?? 50, 1, MAX_LIMIT);

package/dist/src/mcp/mailbox-registry.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Registre local des boîtes tenues par les sessions MCP de cette machine.
+ *
+ * Une session reprise est un nouveau processus : sans mémoire, elle se ferait allouer une
+ * boîte neuve et perdrait ses fils, ses non-lus et son adresse — celle que ses
+ * correspondants connaissent. Le registre est cette mémoire, et il est purement local :
+ * le serveur n'en sait rien, rien ne part sur le réseau.
+ *
+ * Une entrée dit trois choses : quelle boîte, pour quel projet, et **tenue par qui**. Ce
+ * dernier point est ce qui rend la reprise sûre : tant que le processus inscrit vit et
+ * bat, sa boîte lui appartient et aucune autre session ne la prendra. Une boîte n'est
+ * reprenable qu'une fois **orpheline** : session close proprement, processus mort, ou
+ * battement arrêté depuis assez longtemps pour qu'un numéro de processus recyclé ne
+ * puisse pas faire illusion.
+ *
+ * Rien de lisible n'est écrit : le projet et la clé de session ne figurent que par leur
+ * empreinte, et les fichiers sont en 0600 comme les relais de veilleurs.
+ *
+ * Un processus ne tient qu'une entrée à la fois, celle de sa session : c'est vrai du mode
+ * MCP, où un processus est une session. Les tests qui simulent plusieurs sessions dans un
+ * même processus en tiennent compte.
+ */
+export interface RegistryEntry {
+    mailbox: string;
+    /** Empreinte du projet : même répertoire, même agent, même serveur. */
+    fingerprint: string;
+    /** Empreinte de l'identifiant de session de l'hôte, ou null s'il n'y en avait pas. */
+    session_key: string | null;
+    /** Processus MCP qui tient la boîte. Sa mort rend l'entrée orpheline. */
+    pid: number;
+    started_at: string;
+    heartbeat_at: string;
+    /** Posé à l'arrêt propre de la session : la boîte est libre sans attendre. */
+    closed_at: string | null;
+}
+/** Rythme du battement de cœur d'une session vivante. */
+export declare const HEARTBEAT_MS = 60000;
+/** Répertoire du registre. `MESSENGER_STATE_DIR` le déplace, comme pour les relais. */
+export declare function registryDir(): string;
+/**
+ * Ce qui fait qu'une boîte appartient au même travail : le répertoire d'où la session est
+ * lancée, le nom d'agent de sa configuration et le serveur qu'elle utilise. Deux sessions
+ * du même projet partagent cette empreinte ; deux projets ne la partagent jamais.
+ */
+export declare function projectFingerprint(input: {
+    cwd: string;
+    agentName: string | null;
+    serverUrl: string;
+}): string;
+/** L'identifiant de session de l'hôte n'est jamais écrit en clair : seule son empreinte l'est. */
+export declare function sessionKeyDigest(key: string): string;
+/** Toutes les entrées d'un projet, la plus récemment vivante en tête. */
+export declare function listEntries(fingerprint: string): RegistryEntry[];
+/** Vrai tant que le processus existe, même s'il appartient à un autre utilisateur. */
+export declare function isProcessAlive(pid: number): boolean;
+/** Une entrée est orpheline quand plus aucune session vivante ne la tient. */
+export declare function isOrphan(entry: RegistryEntry, now?: number): boolean;
+/** Boîtes du projet qu'aucune session vivante ne tient, la plus récente en tête. */
+export declare function orphanEntries(fingerprint: string, now?: number): RegistryEntry[];
+/** Inscrit la boîte de cette session, et se souvient de l'entrée pour la tenir à jour. */
+export declare function claim(input: {
+    mailbox: string;
+    fingerprint: string;
+    sessionKey: string | null;
+}): RegistryEntry;
+/**
+ * Suit la session quand elle se rattache ailleurs (`attach_to_mailbox`) : c'est cette
+ * boîte-là qu'elle travaille, donc c'est elle que la prochaine reprise doit retrouver.
+ * L'entrée précédente est close, pas supprimée : la boîte qu'elle désigne reste reprenable.
+ */
+export declare function rebind(mailbox: string): void;
+/** Dit que la session est toujours là. Sans ce battement, sa boîte finit par être reprenable. */
+export declare function heartbeat(): void;
+/** Libère la boîte à l'arrêt de la session : la reprise n'a pas à attendre l'expiration. */
+export declare function releaseOwn(): void;
+/** Entrée tenue par ce processus, pour les tests et le journal. */
+export declare function ownEntry(): RegistryEntry | null;
+/** Oublie les entrées qu'aucune session n'a touchées depuis longtemps. */
+export declare function purge(now?: number): number;
+/** Remet le module à zéro entre deux tests : le processus, lui, ne tient qu'une entrée. */
+export declare function resetOwnEntry(): void;

package/dist/src/mcp/resume-state.d.ts

@@ -0,0 +1,34 @@
+import type { MessengerClient } from "../client/messenger-client.js";
+/**
+ * Ce que le démarrage a trouvé des sessions précédentes, gardé pour `whoami`.
+ *
+ * La reprise se décide avant que l'agent ne parle : il faut donc pouvoir la lui dire
+ * plus tard, au premier outil qui parle d'identité. L'état est attaché au client plutôt
+ * qu'au module — deux sessions cohabitent dans un même processus pendant les tests.
+ */
+export interface ResumeCandidate {
+    mailbox: string;
+    agent_name: string | null;
+    mailbox_name: string | null;
+    /** Messages présents dans la boîte, corbeille comprise : de quoi juger si elle a servi. */
+    messages: number;
+    unread: number;
+    last_activity: string | null;
+}
+export interface ResumeState {
+    /**
+     * Comment la boîte de cette session a été retrouvée :
+     * `session-key`, l'hôte a redonné le même identifiant de session — c'est une certitude ;
+     * `orphan`, une seule boîte du projet restait sans session pour la tenir ;
+     * null, la boîte est neuve.
+     */
+    resumed: "session-key" | "orphan" | null;
+    /** Boîtes laissées par une session arrêtée, que l'agent peut rattacher lui-même. */
+    candidates: ResumeCandidate[];
+    /** Variable d'environnement qui a fourni l'identifiant de session, s'il y en avait une. */
+    keySource: string | null;
+}
+export declare function setResumeState(client: MessengerClient, state: ResumeState): void;
+export declare function getResumeState(client: MessengerClient): ResumeState | null;
+/** Une boîte reprise n'est plus une boîte à proposer : l'agent y est déjà. */
+export declare function forgetCandidate(client: MessengerClient, mailbox: string): void;

package/dist/src/mcp/resume-state.js

@@ -0,0 +1,14 @@
+const states = new WeakMap();
+export function setResumeState(client, state) {
+    states.set(client, state);
+}
+export function getResumeState(client) {
+    return states.get(client) ?? null;
+}
+/** Une boîte reprise n'est plus une boîte à proposer : l'agent y est déjà. */
+export function forgetCandidate(client, mailbox) {
+    const state = states.get(client);
+    if (!state)
+        return;
+    states.set(client, { ...state, candidates: state.candidates.filter((c) => c.mailbox !== mailbox) });
+}

package/dist/src/mcp/start.d.ts

@@ -1,16 +1,36 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { type AgentConfig } from "../config.js";
 import { MessengerClient } from "../client/messenger-client.js";
+import { type ResumeCandidate } from "./resume-state.js";
 /** Serveur MCP prêt à être branché sur n'importe quel transport (stdio en production, mémoire en test). */
 export declare function createMcpServer(client: MessengerClient): Server;
+export interface Identity {
+    mailbox: string;
+    /** Non nul quand la boîte vient d'une session précédente. Voir `ResumeState`. */
+    resumed: "session-key" | "orphan" | null;
+    /** Boîtes orphelines du même projet qui n'ont pas été reprises d'office. */
+    candidates: ResumeCandidate[];
+}
 /**
  * Donne son adresse à la session.
  *
- * Avec `MESSENGER_AGENT_ID`, l'adresse est fixe et partagée par toutes les sessions qui
- * utilisent cette configuration. Sans elle — le cas normal — une boîte neuve est allouée
- * pour cette session : deux agents lancés dans le même projet ne se marchent pas dessus.
- * L'identifiant est opaque : c'est une adresse à transmettre, pas un rôle à deviner.
+ * Trois chemins, du plus certain au plus approximatif :
+ *
+ * 1. `MESSENGER_AGENT_ID` fixe l'adresse, partagée par toutes les sessions de cette
+ *    configuration. Rien à chercher.
+ * 2. Le registre local rend à une session reprise la boîte qu'elle tenait : identique si
+ *    l'hôte a redonné le même identifiant de session, sinon la seule boîte du projet
+ *    qu'aucune session vivante ne tient plus et qui a réellement servi.
+ * 3. À défaut, une boîte neuve, comme avant. Les boîtes orphelines non reprises sont
+ *    gardées de côté : `whoami` les propose, l'agent en rattache une s'il reconnaît la
+ *    sienne dans son contexte.
+ *
+ * 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.
  */
-export declare function resolveIdentity(client: MessengerClient, config: AgentConfig): Promise<string>;
+export declare function resolveIdentity(client: MessengerClient, config: AgentConfig, options?: {
+    cwd?: string;
+}): Promise<Identity>;
 /** Point d'entrée du mode MCP (mode par défaut, sans argument). */
 export declare function runMcpMode(): Promise<void>;