@imenam/mcp-messenger 1.0.16 → 1.0.17

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
@@ -518,6 +559,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 +567,8 @@ 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
+207 tests couvrant : 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/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>;

package/dist/src/mcp/start.js

@@ -7,6 +7,8 @@ import { removeOwnHandoffs } from "../cli/watch-handoff.js";
 import { newId } from "../core/ids.js";
 import { logger } from "../logger.js";
 import { APP_VERSION } from "../version.js";
+import { HEARTBEAT_MS, claim, heartbeat, orphanEntries, projectFingerprint, purge, releaseOwn, sessionKeyDigest, } from "./mailbox-registry.js";
+import { setResumeState } from "./resume-state.js";
 import { TOOLS, callTool } from "./tools.js";
 /**
  * Ce que l'hôte reçoit à la poignée de main, avant le moindre appel d'outil.
@@ -29,6 +31,11 @@ Who you are, and who the others are — read this before writing to anyone:
 - One of those groups may carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — those are other sessions of the same project, each a different agent with its own mailbox. Compare addresses, never names.
 - Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
 
+Resuming earlier work:
+- A resumed session usually keeps the mailbox it had: the address, the threads and the unread messages come back on their own. \`whoami\` says so when it happens.
+- When it cannot be decided automatically, \`whoami\` lists the mailboxes left by a stopped session of this project. If you are continuing that work, call \`attach_to_mailbox\` with the right address.
+- If a \`box_…\` address appears earlier in your own context, from a previous part of this conversation, that is your mailbox from before: attach to it rather than writing from a fresh one, so your correspondents keep reaching you at the address they know.
+
 Writing:
 - One message goes to exactly one mailbox, and never to your own. To reach several correspondents, send each one its own message.
 - Never write a mailbox address in the body of a message. The server attaches the sender and the recipient to every message, and the reader sees them: an address copied by hand adds nothing and misleads as soon as it is stale or mistaken.
@@ -55,17 +62,61 @@ export function createMcpServer(client) {
 /**
  * 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 async function resolveIdentity(client, config) {
+export async function resolveIdentity(client, config, options = {}) {
+    const keySource = config.sessionKey ? config.sessionKeySource : null;
     if (config.agentId) {
         client.setAgentId(config.agentId, { own: true });
         await client.register();
-        return config.agentId;
+        const identity = { mailbox: config.agentId, resumed: null, candidates: [] };
+        setResumeState(client, { resumed: null, candidates: [], keySource });
+        return identity;
+    }
+    const fingerprint = projectFingerprint({
+        cwd: options.cwd ?? process.cwd(),
+        agentName: config.agentName,
+        serverUrl: config.serverUrl,
+    });
+    const sessionKey = config.sessionKey ? sessionKeyDigest(config.sessionKey) : null;
+    purge();
+    const found = config.resume === "off" ? [] : await inspectOrphans(config, orphanEntries(fingerprint));
+    const exact = sessionKey ? found.find((c) => c.entry.session_key === sessionKey) : undefined;
+    // Une seule boîte laissée par une session arrêtée, et elle a servi : l'ambiguïté
+    // n'existe pas. Plusieurs, ou une boîte vide, et c'est à l'agent de choisir.
+    const sole = found.length === 1 && found[0].candidate.messages > 0 ? found[0] : undefined;
+    const taken = config.resume === "auto" ? (exact ?? sole) : exact;
+    if (taken) {
+        client.setAgentId(taken.candidate.mailbox, { own: true });
+        await client.register();
+        claim({ mailbox: taken.candidate.mailbox, fingerprint, sessionKey });
+        const resumed = taken === exact ? "session-key" : "orphan";
+        const candidates = found.filter((c) => c !== taken).map((c) => c.candidate);
+        setResumeState(client, { resumed, candidates, keySource });
+        return { mailbox: taken.candidate.mailbox, resumed, candidates };
     }
+    const mailbox = await allocateMailbox(client);
+    claim({ mailbox, fingerprint, sessionKey });
+    // Une boîte vide n'apprend rien à personne : seules celles qui ont du courrier valent
+    // la peine d'être proposées.
+    const candidates = found.map((c) => c.candidate).filter((c) => c.messages > 0);
+    setResumeState(client, { resumed: null, candidates, keySource });
+    return { mailbox, resumed: null, candidates };
+}
+async function allocateMailbox(client) {
     // `fresh` fait échouer l'enregistrement si l'adresse existe déjà : la collision, même
     // improbable sur 64 bits d'aléa, ne peut pas faire atterrir deux sessions au même endroit.
     for (let attempt = 0; attempt < 5; attempt += 1) {
@@ -83,6 +134,57 @@ export async function resolveIdentity(client, config) {
     }
     throw new Error("could not allocate a mailbox: too many id collisions");
 }
+/**
+ * Ce que le journal dit du démarrage.
+ *
+ * C'est le seul endroit d'où l'on peut vérifier que l'hôte transmet bien un identifiant
+ * de session, et lequel : sans cette ligne, une reprise qui n'a pas lieu ne s'explique pas.
+ */
+function describeIdentity(identity, config) {
+    const key = config.sessionKeySource ? `session key from ${config.sessionKeySource}` : "no host session key";
+    const how = identity.resumed === "session-key"
+        ? "resumed from the previous session (same host session id)"
+        : identity.resumed === "orphan"
+            ? "resumed the only mailbox left by a stopped session of this project"
+            : "new mailbox";
+    const waiting = identity.candidates.length > 0 ? `, ${identity.candidates.length} resumable mailbox(es)` : "";
+    return ` — ${how} (${key})${waiting}`;
+}
+/** Nombre de boîtes orphelines examinées : au-delà, le démarrage coûterait plus qu'il ne rend. */
+const MAX_CANDIDATES = 5;
+/**
+ * Confronte les entrées du registre au serveur : une boîte peut avoir disparu (base
+ * réinitialisée), et une boîte vide n'a rien à reprendre. Un serveur injoignable ne fait
+ * pas échouer le démarrage, il rend simplement la reprise impossible pour cette fois.
+ */
+async function inspectOrphans(config, entries) {
+    // Client jetable : la session n'a pas encore d'adresse, et celle-ci ne doit pas bouger
+    // au gré de l'inspection.
+    const probe = new MessengerClient(config);
+    const found = [];
+    for (const entry of entries.slice(0, MAX_CANDIDATES)) {
+        probe.setAgentId(entry.mailbox);
+        try {
+            const agent = await probe.getAgent(entry.mailbox);
+            const stats = await probe.stats();
+            found.push({
+                entry,
+                candidate: {
+                    mailbox: entry.mailbox,
+                    agent_name: agent.agent_name,
+                    mailbox_name: agent.display_name,
+                    messages: stats.folders.reduce((total, folder) => total + folder.total, 0),
+                    unread: stats.unread_total,
+                    last_activity: agent.last_seen_at,
+                },
+            });
+        }
+        catch (error) {
+            logger.info(`mailbox ${entry.mailbox} cannot be resumed: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    return found;
+}
 /** Point d'entrée du mode MCP (mode par défaut, sans argument). */
 export async function runMcpMode() {
     const config = loadAgentConfig();
@@ -90,18 +192,27 @@ export async function runMcpMode() {
     // Un serveur momentanément injoignable ne doit pas empêcher la session MCP de démarrer :
     // l'agent verra l'erreur au premier outil appelé, et pourra réessayer.
     try {
-        const agentId = await resolveIdentity(client, config);
-        logger.info(`mailbox \`${agentId}\` ready on ${config.serverUrl}`);
+        const identity = await resolveIdentity(client, config);
+        logger.info(`mailbox \`${identity.mailbox}\` ready on ${config.serverUrl}${describeIdentity(identity, config)}`);
     }
     catch (error) {
         logger.warn(`could not reach ${config.serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
     }
+    // Tant que ce battement continue, la boîte de cette session n'est reprise par personne.
+    // `unref` : c'est une trace, pas une raison de garder le processus en vie.
+    setInterval(heartbeat, HEARTBEAT_MS).unref();
     // Le relais vers le veilleur porte le jeton de la session : il ne survit pas à la
     // session. Un arrêt brutal le laisse en place, la purge par ancienneté le rattrape.
-    process.on("exit", removeOwnHandoffs);
+    // L'entrée du registre suit le même sort, à ceci près qu'elle est close et non effacée :
+    // c'est elle qui rendra sa boîte à la session suivante.
+    process.on("exit", () => {
+        removeOwnHandoffs();
+        releaseOwn();
+    });
     for (const signal of ["SIGINT", "SIGTERM"]) {
         process.on(signal, () => {
             removeOwnHandoffs();
+            releaseOwn();
             process.exit(0);
         });
     }

package/dist/src/mcp/tools.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { writeHandoff } from "../cli/watch-handoff.js";
 import { PRIORITIES, SYSTEM_FOLDERS } from "../core/types.js";
+import { rebind } from "./mailbox-registry.js";
+import { forgetCandidate, getResumeState } from "./resume-state.js";
 /** Nom publié : l'agent recopie la commande, il n'a pas à connaître de chemin local. */
 const PACKAGE_NAME = "@imenam/mcp-messenger";
 const FOLDER_HINT = `Folder name. System folders: ${SYSTEM_FOLDERS.join(", ")}. Custom folders come from list_folders.`;
@@ -335,6 +337,7 @@ export async function callTool(client, name, rawArgs) {
             if (client.isAttachedElsewhere) {
                 lines.push(`Attached to another mailbox. This session's own mailbox is ${client.sessionAgentId}.`);
             }
+            lines.push(...resumeLines(client));
             lines.push(`Mailbox server: ${client.serverUrl}${health ? ` (v${health.version}, ${health.agents} mailbox(es))` : " (unreachable health endpoint)"}`, 
             // Sans veilleur, un message arrive en boîte sans que personne n'en soit averti.
             // Le dire ici est le seul moyen pour l'agent de s'en apercevoir.
@@ -350,12 +353,17 @@ export async function callTool(client, name, rawArgs) {
                 if (!own)
                     throw new Error("this session has no mailbox of its own to return to");
                 client.setAgentId(own);
+                rebind(own);
                 return `Back to this session's own mailbox: ${own}`;
             }
             // Vérifie que la boîte existe avant de basculer : une faute de frappe créerait
             // silencieusement une boîte vide, et l'agent croirait avoir repris le travail.
             const target = await client.getAgent(input.mailbox_id);
             client.setAgentId(target.id);
+            // La session travaille désormais cette boîte : c'est elle que sa prochaine reprise
+            // doit retrouver, et elle n'a plus à être proposée.
+            rebind(target.id);
+            forgetCandidate(client, target.id);
             const attachedStats = await client.stats();
             return [
                 `Attached to mailbox ${target.id}${formatAgentNames(target) ? ` (${formatAgentNames(target)})` : ""}.`,
@@ -678,6 +686,35 @@ async function renameThread(client, threadId, name, description) {
         .filter(Boolean)
         .join("\n");
 }
+/**
+ * Ce que `whoami` dit des sessions précédentes.
+ *
+ * Deux choses, et seulement quand elles ont eu lieu : que cette boîte vient d'une session
+ * arrêtée — l'agent doit savoir d'où sortent des fils qu'il n'a pas ouverts — et quelles
+ * boîtes du projet attendent encore quelqu'un.
+ */
+function resumeLines(client) {
+    const state = getResumeState(client);
+    if (!state)
+        return [];
+    const lines = [];
+    if (state.resumed === "session-key") {
+        lines.push("Resumed: this is the mailbox of the session you are continuing (matched on the host session id).");
+    }
+    else if (state.resumed === "orphan") {
+        lines.push("Resumed: this mailbox was left by a stopped session of this project, and no live session held it.", "  ↳ its threads and unread messages are not yours from this conversation; read before you answer.");
+    }
+    if (state.candidates.length > 0) {
+        lines.push("Mailboxes left by a stopped session of this project:");
+        for (const candidate of state.candidates) {
+            const name = candidate.mailbox_name ?? "unnamed mailbox";
+            const seen = candidate.last_activity ? ` · last activity ${candidate.last_activity}` : "";
+            lines.push(`  ${candidate.mailbox} — ${name} · ${candidate.messages} message(s), ${candidate.unread} unread${seen}`);
+        }
+        lines.push("  ↳ if you are resuming that work, call attach_to_mailbox with its address.");
+    }
+    return lines;
+}
 /** `titre (id)`, ou l'id seul tant que le fil n'a pas été nommé. */
 function formatThreadRef(title, threadId) {
     return title ? `${title} (${threadId})` : threadId;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.16";
+export declare const APP_VERSION = "1.0.17";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Généré par scripts/generate-version.js — ne pas modifier à la main.
-export const APP_VERSION = "1.0.16";
+export const APP_VERSION = "1.0.17";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-messenger",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "npm run build && vitest run",