ciphermesh 2.4.0 → 2.5.0

package/README.md

@@ -212,6 +212,7 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 | `/img [path]` | Render the last received image in **full resolution** (kitty/iTerm2) |
 | `/search <term>` | Search the encrypted local history (on disk, across sessions) |
 | `/find [term]` — **Ctrl+F** | Search **this room's scrollback** and press Enter to **jump to the message**, highlighted |
+| `/doctor [host:port]` | Diagnose why a connection fails: address, DNS, TCP port, TLS (CA vs self-signed) and protocol version — each failure with what to do about it |
 | `/history [n]` | Last n messages from history |
 | `/retention <7d\|24h\|30m>` | Purge local history older than the given age |
 | `/export [path]` | Export history as .txt or .json (plaintext!) |
@@ -226,8 +227,8 @@ A green **✓** next to a name marks a SAS-verified peer; a red **✗** flags a
 | `/away [reason]` / `/back` | Mark yourself away — while away, unreads are counted (`[away · N new]`) and `/back` shows a summary |
 | `/mentions [n]` | Recent mentions of you this session (who, where, when) |
 | `/status <text\|off>` | Free-form status — emojis welcome (`/status :fire: coding`) |
-| `/react <emoji>` | React to the last message |
-| `/edit` `/delete` | Edit/delete your last message |
+| `/react <emoji>` | React to the last message — the emoji lands **on the message**, with a count when several people react |
+| `/edit` `/delete` | Edit or delete your last message — the **original line is rewritten in place** (marked *(edited)*) or replaced by a tombstone, instead of a new line you have to mentally staple to it |
 | `/pin` `/unpin` `/pins` | Pin messages |
 | `/sound` `/notify` | Sound / desktop notifications |
 | `/dnd [on\|off\|mentions\|HH:MM-HH:MM]` | Do-not-disturb, mentions-only, or quiet hours |

package/README.pt-BR.md

@@ -213,6 +213,7 @@ Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗*
 | `/retention <7d\|24h\|30m>` | Purga o histórico local mais antigo que o tempo dado |
 | `/search <termo>` | Busca no histórico local cifrado (em disco, entre sessões) |
 | `/find [termo]` — **Ctrl+F** | Busca **no histórico da sala na tela** e, com Enter, **salta para a mensagem** destacada |
+| `/doctor [host:porta]` | Diagnostica por que a conexão falha: endereço, DNS, porta TCP, TLS (CA ou self-signed) e versão de protocolo — cada falha com o que fazer |
 | `/history [n]` | Últimas n mensagens do histórico |
 | `/export [caminho]` | Exporta o histórico em .txt ou .json (texto plano!) |
 
@@ -226,8 +227,8 @@ Um **✓** verde ao lado de um nome indica um peer verificado por SAS; um **✗*
 | `/away [motivo]` / `/back` | Marca/remove ausência — enquanto ausente, não-lidas são contadas (`[away · N new]`) e o `/back` mostra um resumo |
 | `/mentions [n]` | Menções recentes a você na sessão (quem, onde, quando) |
 | `/status <texto\|off>` | Status livre — emoji à vontade (`/status :fire: codando`) |
-| `/react <emoji>` | Reage à última mensagem |
-| `/edit` `/delete` | Edita/apaga sua última mensagem |
+| `/react <emoji>` | Reage à última mensagem — o emoji aparece **na própria mensagem**, com contagem quando várias pessoas reagem |
+| `/edit` `/delete` | Edita ou apaga sua última mensagem — a **linha original é reescrita no lugar** (marcada *(edited)*) ou vira uma lápide, em vez de uma linha nova que você precisa juntar mentalmente à original |
 | `/pin` `/unpin` `/pins` | Fixa mensagens |
 | `/sound` `/notify` | Notificações sonoras / desktop |
 | `/dnd [on\|off\|mentions\|HH:MM-HH:MM]` | Não perturbe, só menções, ou horário silencioso |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ciphermesh",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Secure terminal chat for the local network (LAN) with real end-to-end encryption (E2EE) using libsodium",
   "type": "module",
   "main": "src/client/index.js",

package/src/client/ChatController.js

@@ -60,6 +60,7 @@ import {
   matchesKeyword,
 } from '../shared/dnd.js';
 import { saveLastSession } from '../shared/lastSession.js';
+import { diagnose, formatDiagnosis } from '../shared/doctor.js';
 import { COMMANDS } from './UI.js';
 
 const TYPING_SEND_INTERVAL = 2000; // debounce: max 1 typing event per 2s
@@ -120,6 +121,9 @@ export class ChatController {
   #watchWords = new Set(); // /watch — keywords that alert like a mention does
   #awayUnread = 0; // messages received while away
   #awayMentions = 0; // …of which mentioned me
+  #messageLines = new Map(); // messageId → { lineIndex, nickname, text, opts, room }
+  #reactions = new Map(); // messageId → Map<emoji, count>
+  #reconnectAttempts = 0; // consecutive reconnects, for the /doctor nudge
   #autoLockMs = 0; // idle screen-lock timeout (0 = off)
   #autoLockTimer = null;
   // Multi-room buffers (IRC style): lines live in the UI; membership, unread
@@ -212,6 +216,7 @@ export class ChatController {
   // the initial JOIN would be lost — the 'connected' event fired before we
   // attached the listener).
   #onConnected() {
+    this.#reconnectAttempts = 0;
     this.#ui.setConnectionState('online');
     this.#connection.send(
       createJoin(this.#nickname, this.#keyManager.publicKeyB64, this.#keyManager.pqPublicKeyB64),
@@ -237,6 +242,12 @@ export class ChatController {
     this.#connection.on('reconnecting', (delay) => {
       this.#ui.setConnectionState('reconnecting');
       this.#ui.addSystemMessage(`Reconnecting in ${delay / 1000}s...`);
+      // After a few failures this is not a blip — point at the tool that can
+      // actually explain it, once, instead of looping silently forever.
+      this.#reconnectAttempts++;
+      if (this.#reconnectAttempts === 3) {
+        this.#ui.addInfoMessage('Still failing? Run /doctor to find out where it breaks.');
+      }
     });
 
     this.#connection.on('cert-ca-valid', ({ issuer }) => {
@@ -1159,9 +1170,17 @@ export class ChatController {
       }
 
       if (data.action === 'reaction') {
-        this.#ui.toBuffer(msgRoom, () => {
-          this.#ui.addSystemMessage(`${data.emoji} ${peer.nickname} reacted to a message`);
-        });
+        // Hang the reaction off the message itself; only fall back to a log
+        // line when the target is not on screen (older or another room).
+        const applied =
+          roomActive && data.targetMessageId
+            ? this.#applyReaction(data.targetMessageId, data.emoji)
+            : false;
+        if (!applied) {
+          this.#ui.toBuffer(msgRoom, () => {
+            this.#ui.addSystemMessage(`${data.emoji} ${peer.nickname} reacted to a message`);
+          });
+        }
         if (roomActive) {
           this.#ui.playNotification();
         }
@@ -1170,7 +1189,14 @@ export class ChatController {
 
       if (data.action === 'edit_message') {
         const author = this.#messageAuthors.get(data.messageId);
-        if (author && author === peer.nickname) {
+        if (!author || author !== peer.nickname) {
+          return; // only the author may rewrite their own message
+        }
+        const entry = this.#editableMessage(data.messageId);
+        if (entry) {
+          entry.text = data.newText;
+          this.#ui.replaceMessageText(entry.lineIndex, entry.nickname, data.newText, entry.opts);
+        } else {
           this.#ui.toBuffer(msgRoom, () => {
             this.#ui.addSystemMessage(`${peer.nickname} edited: ${data.newText} (edited)`);
           });
@@ -1180,7 +1206,14 @@ export class ChatController {
 
       if (data.action === 'delete_message') {
         const author = this.#messageAuthors.get(data.messageId);
-        if (author && author === peer.nickname) {
+        if (!author || author !== peer.nickname) {
+          return;
+        }
+        const entry = this.#editableMessage(data.messageId);
+        if (entry) {
+          this.#ui.tombstoneMessage(entry.lineIndex, peer.nickname);
+          this.#messageLines.delete(data.messageId);
+        } else {
           this.#ui.toBuffer(msgRoom, () => {
             this.#ui.addSystemMessage(`${peer.nickname} deleted a message`);
           });
@@ -1299,11 +1332,12 @@ export class ChatController {
       const trust = trustBadge(this.#trustStore.getPeerRecord(peer.nickname), peer.publicKey);
       // File the message into its buffer (live log when active, stored otherwise).
       let lineIndex = -1;
+      let renderInfo = null;
       this.#ui.toBuffer(msgRoom, () => {
         if (data.replyTo?.nickname && typeof data.replyTo.excerpt === 'string') {
           this.#ui.addQuoteLine(String(data.replyTo.nickname), data.replyTo.excerpt.slice(0, 80));
         }
-        ({ lineIndex } = data.isAction
+        ({ lineIndex, render: renderInfo } = data.isAction
           ? this.#ui.addActionMessage(peer.nickname, data.text)
           : this.#ui.addMessage(
               peer.nickname,
@@ -1315,6 +1349,9 @@ export class ChatController {
               trust,
             ));
       });
+      if (roomActive && data.messageId) {
+        this.#rememberMessage(data.messageId, lineIndex, peer.nickname, data.text, renderInfo);
+      }
       this.#noteBufferUnread(msgRoom, mentioned);
       const notify = shouldNotify(this.#dndMode, this.#dndWindow, nowMinutes(), mentioned);
       if (notify) {
@@ -1440,6 +1477,7 @@ export class ChatController {
         );
         this.#ui.addInfoMessage('  /search <term>       - Search the encrypted local history');
         this.#ui.addInfoMessage('  /find [term]         - Find in this room and jump (Ctrl+F)');
+        this.#ui.addInfoMessage('  /doctor [host:port]  - Diagnose why a connection fails');
         this.#ui.addInfoMessage('  /history [n]         - Last n messages from history');
         this.#ui.addInfoMessage('  /export [path]       - Export the history (.txt or .json)');
         this.#ui.addInfoMessage('  /audit [N]           - Show the last N audit events');
@@ -2171,6 +2209,21 @@ export class ChatController {
         break;
       }
 
+      case '/doctor': {
+        const target = parts.slice(1).join(' ').trim() || this.#connection.url || '';
+        this.#ui.addInfoMessage(`Diagnosing ${target} …`);
+        diagnose(target)
+          .then((steps) => {
+            for (const line of formatDiagnosis(steps)) {
+              this.#ui.addInfoMessage(line);
+            }
+          })
+          .catch((err) => {
+            this.#ui.addErrorMessage(`Diagnostics failed to run: ${err.message}`);
+          });
+        break;
+      }
+
       case '/find': {
         const term = parts.slice(1).join(' ').trim();
         // Opens the same overlay as Ctrl+F, pre-filled when a term is given.
@@ -2283,9 +2336,12 @@ export class ChatController {
           sentAt: Date.now(),
         });
         this.#broadcastPayload(reactionPayload);
-        this.#ui.addSystemMessage(
-          `${emoji} You reacted to ${this.#lastReceivedNickname}'s message`,
-        );
+        // Show it on the message right away instead of announcing it.
+        if (!this.#applyReaction(this.#lastReceivedMessageId, emoji)) {
+          this.#ui.addSystemMessage(
+            `${emoji} You reacted to ${this.#lastReceivedNickname}'s message`,
+          );
+        }
         break;
       }
 
@@ -2306,7 +2362,19 @@ export class ChatController {
           sentAt: Date.now(),
         });
         this.#broadcastPayload(editPayload);
-        this.#ui.addSystemMessage(`You edited: ${editText} (edited)`);
+        // Rewrite our own line in place, like the peers will.
+        const editEntry = this.#editableMessage(this.#lastSentMessageId);
+        if (editEntry) {
+          editEntry.text = editText;
+          this.#ui.replaceMessageText(
+            editEntry.lineIndex,
+            editEntry.nickname,
+            editText,
+            editEntry.opts,
+          );
+        } else {
+          this.#ui.addSystemMessage(`You edited: ${editText} (edited)`);
+        }
         break;
       }
 
@@ -2321,8 +2389,14 @@ export class ChatController {
           sentAt: Date.now(),
         });
         this.#broadcastPayload(deletePayload);
+        const delEntry = this.#editableMessage(this.#lastSentMessageId);
+        if (delEntry) {
+          this.#ui.tombstoneMessage(delEntry.lineIndex, this.#nickname);
+          this.#messageLines.delete(this.#lastSentMessageId);
+        } else {
+          this.#ui.addSystemMessage('You deleted a message');
+        }
         this.#lastSentMessageId = null;
-        this.#ui.addSystemMessage('You deleted a message');
         break;
       }
 
@@ -3019,6 +3093,55 @@ export class ChatController {
     this.#ui.appendBadge(tracked.lineIndex, tracked.baseLine, `{green-fg}${marker}{/green-fg}`);
   }
 
+  // Remember where a message was drawn so reactions/edits/deletes can change
+  // it in place. Bounded like the receipt tracker.
+  #rememberMessage(messageId, lineIndex, nickname, text, render) {
+    if (!messageId || lineIndex === undefined || lineIndex < 0) {
+      return;
+    }
+    this.#messageLines.set(messageId, {
+      lineIndex,
+      nickname,
+      text,
+      opts: render?.opts || {},
+      room: this.#currentRoom,
+    });
+    if (this.#messageLines.size > 200) {
+      const oldest = this.#messageLines.keys().next().value;
+      this.#messageLines.delete(oldest);
+      this.#reactions.delete(oldest);
+    }
+  }
+
+  // A message can only be redrawn while its room is the one on screen.
+  #editableMessage(messageId) {
+    const entry = this.#messageLines.get(messageId);
+    if (!entry || entry.room !== this.#currentRoom) {
+      return null;
+    }
+    return entry;
+  }
+
+  #applyReaction(messageId, emoji) {
+    const entry = this.#editableMessage(messageId);
+    if (!entry) {
+      return false;
+    }
+    const counts = this.#reactions.get(messageId) || new Map();
+    counts.set(emoji, (counts.get(emoji) || 0) + 1);
+    this.#reactions.set(messageId, counts);
+
+    // Re-render the line, then hang the reactions off the end of it.
+    const badge = [...counts.entries()].map(([e, n]) => (n > 1 ? `${e}${n}` : e)).join(' ');
+    this.#ui.replaceMessageText(entry.lineIndex, entry.nickname, entry.text, {
+      ...entry.opts,
+      edited: entry.opts?.edited,
+    });
+    const rebuilt = this.#ui.getLine(entry.lineIndex);
+    this.#ui.appendBadge(entry.lineIndex, rebuilt, badge);
+    return true;
+  }
+
   #trackSentMessage(messageId, lineIndex) {
     const baseLine = this.#ui.getLine(lineIndex);
     if (baseLine === null || baseLine === undefined) {
@@ -3321,9 +3444,10 @@ export class ChatController {
       this.#ui.addQuoteLine(replyTo.nickname, replyTo.excerpt, true);
     }
     const ephLabel = this.#ephemeralMode ? this.#formatDuration(this.#ephemeralDurationMs) : null;
-    const { lineIndex } = isAction
+    const { lineIndex, render } = isAction
       ? this.#ui.addActionMessage(this.#nickname, text)
       : this.#ui.addMessage(this.#nickname, text, false, ephLabel, this.#deniableMode);
+    this.#rememberMessage(messageId, lineIndex, this.#nickname, text, render);
 
     if (this.#ephemeralMode) {
       this.#scheduleEphemeralRemoval(lineIndex, this.#ephemeralDurationMs, this.#nickname);

package/src/client/UI.js

@@ -46,6 +46,7 @@ const COMMAND_INFO = [
   ['/notify', 'Desktop notifications'],
   ['/search', 'Search history (on disk)'],
   ['/find', 'Find in this room and jump to it'],
+  ['/doctor', 'Diagnose why a connection fails'],
   ['/history', 'Recent messages from history'],
   ['/export', 'Export history'],
   ['/backup', 'Back up identity + trust'],
@@ -112,6 +113,7 @@ export const COMMANDS = [
   '/invite',
   '/search',
   '/find',
+  '/doctor',
   '/history',
   '/export',
   '/backup',
@@ -1781,6 +1783,64 @@ export class UI extends EventEmitter {
     trust = 'none',
   ) {
     this.#daySeparator();
+    const isSelfNow = nickname === this.#nickname || nickname.includes('\u2192');
+    const opts = {
+      isDM,
+      ephemeralLabel,
+      deniable,
+      mentioned,
+      trust,
+      grouped: !isSelfNow && !isDM && this.#lastSender === nickname,
+      stamp: time(),
+    };
+    const line = this.#composeMessageLine(nickname, text, opts);
+
+    this.#lines.push(line);
+    this.#chatLog.log(line);
+    this.#screen.render();
+    this.#lastSender = isSelfNow ? 'self' : nickname;
+    if (!isSelfNow) {
+      this.#noteIncoming(mentioned || isDM);
+    }
+    return { lineIndex: this.#lines.length - 1, render: { nickname, opts } };
+  }
+
+  /**
+   * Rewrite an existing message line with new text — used by /edit, so an
+   * edited message changes IN PLACE instead of arriving as a separate line the
+   * reader has to mentally staple to the original.
+   */
+  replaceMessageText(lineIndex, nickname, newText, opts) {
+    this.updateLine(
+      lineIndex,
+      this.#composeMessageLine(nickname, newText, { ...opts, edited: true }),
+    );
+  }
+
+  /** Replace a message with a tombstone (used by /delete). */
+  tombstoneMessage(lineIndex, nickname) {
+    this.updateLine(
+      lineIndex,
+      ` {white-fg}[${time()}]{/white-fg} {#666666-fg}\ud83d\udeab ${blessed.escape(
+        nickname,
+      )} deleted a message{/#666666-fg}`,
+    );
+  }
+
+  // Builds a message line. Shared by addMessage and replaceMessageText so an
+  // edited message keeps exactly the layout it had (alignment, grouping,
+  // badges) instead of drifting into a different shape.
+  #composeMessageLine(nickname, text, opts) {
+    const {
+      isDM = false,
+      ephemeralLabel = null,
+      deniable = false,
+      mentioned = false,
+      trust = 'none',
+      grouped = false,
+      edited = false,
+      stamp = time(),
+    } = opts || {};
 
     const color = nickColor(nickname);
     const isSelf = nickname === this.#nickname || nickname.includes('\u2192');
@@ -1802,24 +1862,15 @@ export class UI extends EventEmitter {
 
     // Consecutive messages from the same peer collapse the avatar/name into a
     // compact continuation bullet (cleaner layout).
-    const grouped = !isSelf && !isDM && this.#lastSender === nickname;
+    const editedMark = edited ? ' {#8888aa-fg}(edited){/#8888aa-fg}' : '';
     const core = grouped
-      ? `{${tag}}\u00b7{/${tag}} ${renderMarkdown(text)}`
-      : `${avatar} {${tag}}${nickname}{/${tag}}${trustGlyph}${dmLabel}: ${renderMarkdown(text)}`;
+      ? `{${tag}}\u00b7{/${tag}} ${renderMarkdown(text)}${editedMark}`
+      : `${avatar} {${tag}}${nickname}{/${tag}}${trustGlyph}${dmLabel}: ${renderMarkdown(text)}${editedMark}`;
 
     // My own messages on the right (timestamp at the end), others on the left
-    const line = isSelf
-      ? this.#alignRight(`${core}${ephLabel}${denLabel} {white-fg}[${time()}]{/white-fg}`)
-      : `${bar}{white-fg}[${time()}]{/white-fg}${ephLabel}${denLabel} ${mentionMark}${core}`;
-
-    this.#lines.push(line);
-    this.#chatLog.log(line);
-    this.#screen.render();
-    this.#lastSender = isSelf ? 'self' : nickname;
-    if (!isSelf) {
-      this.#noteIncoming(mentioned || isDM);
-    }
-    return { lineIndex: this.#lines.length - 1 };
+    return isSelf
+      ? this.#alignRight(`${core}${ephLabel}${denLabel} {white-fg}[${stamp}]{/white-fg}`)
+      : `${bar}{white-fg}[${stamp}]{/white-fg}${ephLabel}${denLabel} ${mentionMark}${core}`;
   }
 
   #daySeparator() {

package/src/p2p/P2PChatController.js

@@ -23,6 +23,7 @@ import { isImageFile, renderImagePreview, loadImageBuffers } from '../client/Ima
 import { detectImageProtocol, encodeInlineImage } from '../shared/terminalGraphics.js';
 import { AuditLog, AuditEvent } from '../shared/AuditLog.js';
 import { applyShortcodes } from '../shared/emoji.js';
+import { diagnose, formatDiagnosis } from '../shared/doctor.js';
 import { deriveSharedKey, encryptDeniable, decryptDeniable } from '../crypto/DeniableEncrypt.js';
 import { GroupSession } from '../crypto/SenderKey.js';
 import { suggestCommand } from '../shared/commandSuggest.js';
@@ -90,6 +91,10 @@ export class P2PChatController {
   #autoLockTimer = null;
   #roomTopics = new Map(); // room → { text, by, at } (E2EE among peers)
   #historyStore; // encrypted local history (opt-in, needs a passphrase)
+  #receiptsEnabled = true; // /receipts — send read confirmations
+  #sentMessageLines = new Map(); // messageId → { lineIndex, baseLine, room }
+  #messageReaders = new Map(); // messageId → Set<nickname>
+  #pendingReceipts = new Map(); // messageId → Set<nickname> acked before we tracked it
   #lastReceivedMessageId;
   #lastReceivedNickname;
   #lastSentMessageId;
@@ -610,6 +615,11 @@ export class P2PChatController {
       return;
     }
 
+    if (data.action === 'read_receipt') {
+      this.#onReadReceipt(fromNickname, data.messageId);
+      return;
+    }
+
     if (data.action === 'set_topic') {
       const room = typeof data.room === 'string' ? data.room : this.#currentRoom;
       if (typeof data.text === 'string') {
@@ -690,6 +700,23 @@ export class P2PChatController {
       this.#ui.playNotification();
     }
 
+    // Confirm the read to the author — an ordinary E2EE payload, sent only to
+    // them. Never for ephemeral or deniable messages: acknowledging those
+    // would defeat the point of not leaving a trace.
+    if (
+      this.#receiptsEnabled &&
+      data.messageId &&
+      !data.ephemeral &&
+      !isDeniable &&
+      !data.deniable
+    ) {
+      this.#broadcastPayload(
+        JSON.stringify({ action: 'read_receipt', messageId: data.messageId, sentAt: Date.now() }),
+        false,
+        fromNickname,
+      );
+    }
+
     if (data.ephemeral && data.ephemeral > 0) {
       this.#scheduleEphemeralRemoval(lineIndex, data.ephemeral, fromNickname);
     }
@@ -906,6 +933,49 @@ export class P2PChatController {
     const cmd = parts[0].toLowerCase();
 
     switch (cmd) {
+      case '/doctor': {
+        const target = parts.slice(1).join(' ').trim();
+        if (!target) {
+          this.#ui.addErrorMessage(
+            'Usage: /doctor <host:port>  — P2P finds peers over mDNS, so give an address to test',
+          );
+          break;
+        }
+        this.#ui.addInfoMessage(`Diagnosing ${target} …`);
+        diagnose(target)
+          .then((steps) => {
+            for (const line of formatDiagnosis(steps)) {
+              this.#ui.addInfoMessage(line);
+            }
+          })
+          .catch((err) => {
+            this.#ui.addErrorMessage(`Diagnostics failed to run: ${err.message}`);
+          });
+        break;
+      }
+
+      case '/find': {
+        // Pure UI: searches the lines on screen, so it works the same here.
+        this.#ui.openFinder(parts.slice(1).join(' ').trim());
+        break;
+      }
+
+      case '/receipts': {
+        const arg = parts[1]?.toLowerCase();
+        if (arg === 'off') {
+          this.#receiptsEnabled = false;
+          this.#ui.addInfoMessage('Read receipts disabled — you no longer send read confirmations');
+        } else if (arg === 'on') {
+          this.#receiptsEnabled = true;
+          this.#ui.addInfoMessage('Read receipts enabled');
+        } else {
+          this.#ui.addInfoMessage(
+            `Read receipts: ${this.#receiptsEnabled ? 'enabled' : 'disabled'}. Use /receipts on or /receipts off`,
+          );
+        }
+        break;
+      }
+
       case '/search': {
         if (!this.#historyStore?.isOpen) {
           this.#ui.addErrorMessage('History disabled — start with a passphrase');
@@ -1263,6 +1333,9 @@ export class P2PChatController {
         this.#ui.addInfoMessage('  /history [n]         - Last n messages from history');
         this.#ui.addInfoMessage('  /export [path]       - Export the history');
         this.#ui.addInfoMessage('  /retention <time>    - Local history retention');
+        this.#ui.addInfoMessage('  /receipts [on|off]   - Read receipts (✓✓)');
+        this.#ui.addInfoMessage('  /find [term]         - Find in this room and jump (Ctrl+F)');
+        this.#ui.addInfoMessage('  /doctor <host:port>  - Diagnose why a connection fails');
         this.#ui.addInfoMessage('  /watch [add|remove|clear] - Alert on a keyword');
         this.#ui.addInfoMessage('  /help                - Show this help');
         this.#ui.addInfoMessage('  /tips                - Show a security/UX tip');
@@ -2363,9 +2436,68 @@ export class P2PChatController {
 
     if (this.#ephemeralMode) {
       this.#scheduleEphemeralRemoval(lineIndex, this.#ephemeralDurationMs, this.#nickname);
+    } else if (!this.#deniableMode) {
+      this.#trackSentMessage(messageId, lineIndex);
+    }
+  }
+
+  // ── Read receipts ────────────────────────────────────────────
+  #trackSentMessage(messageId, lineIndex) {
+    const baseLine = this.#ui.getLine(lineIndex);
+    if (baseLine === null || baseLine === undefined) {
+      return;
+    }
+    this.#sentMessageLines.set(messageId, { lineIndex, baseLine, room: this.#currentRoom });
+
+    // A peer on the same machine (or a very fast link) can acknowledge before
+    // we finish rendering our own echo. Apply anything that arrived early.
+    const early = this.#pendingReceipts.get(messageId);
+    if (early) {
+      this.#pendingReceipts.delete(messageId);
+      for (const nickname of early) {
+        this.#onReadReceipt(nickname, messageId);
+      }
+    }
+
+    // Bound memory: keep only the most recent 200 tracked messages
+    if (this.#sentMessageLines.size > 200) {
+      const oldest = this.#sentMessageLines.keys().next().value;
+      this.#sentMessageLines.delete(oldest);
+      this.#messageReaders.delete(oldest);
     }
   }
 
+  #onReadReceipt(nickname, messageId) {
+    const tracked = this.#sentMessageLines.get(messageId);
+    if (!tracked) {
+      // Arrived before we tracked our own message — remember it (bounded) and
+      // let #trackSentMessage apply it a moment later.
+      if (messageId && this.#pendingReceipts.size < 200) {
+        const set = this.#pendingReceipts.get(messageId) || new Set();
+        set.add(nickname);
+        this.#pendingReceipts.set(messageId, set);
+      }
+      return;
+    }
+    // Line indexes only address the room currently on screen.
+    if (tracked.room && tracked.room !== this.#currentRoom) {
+      return;
+    }
+
+    let readers = this.#messageReaders.get(messageId);
+    if (!readers) {
+      readers = new Set();
+      this.#messageReaders.set(messageId, readers);
+    }
+    if (readers.has(nickname)) {
+      return;
+    }
+    readers.add(nickname);
+
+    const marker = readers.size > 1 ? `✓✓ ${readers.size}` : '✓✓';
+    this.#ui.appendBadge(tracked.lineIndex, tracked.baseLine, `{green-fg}${marker}{/green-fg}`);
+  }
+
   // ── Send encrypted DM to one peer ────────────────────────────
   #sendMessageToPeer(peerNickname, text) {
     const peerPublicKey = this.#handshake.getPeerPublicKey(peerNickname);

package/src/shared/doctor.js

@@ -0,0 +1,225 @@
+// Connection doctor: answers "why can't I connect?" in the order the failures
+// actually happen, so a user without a terminal debugger can fix it alone.
+//
+// Every step reports what was checked, whether it passed, and — when it fails
+// — what to do about it. A failing step stops the run: there is no point
+// testing TLS when the TCP port never opened.
+import { connect as netConnect } from 'node:net';
+import { connect as tlsConnect } from 'node:tls';
+import { lookup as dnsLookup } from 'node:dns';
+import { PROTOCOL_VERSION } from './constants.js';
+
+const DEFAULT_TIMEOUT_MS = 6000;
+
+/** Split "wss://host:3600" (or "host:3600") into its parts. */
+export function parseTarget(raw) {
+  const value = String(raw || '').trim();
+  if (!value) {
+    return null;
+  }
+  const withScheme = /^wss?:\/\//.test(value) ? value : `wss://${value}`;
+  try {
+    const url = new URL(withScheme);
+    const port = Number(url.port) || 3600;
+    if (!url.hostname || !Number.isInteger(port) || port < 1 || port > 65535) {
+      return null;
+    }
+    return { host: url.hostname, port, tls: url.protocol === 'wss:', url: withScheme };
+  } catch {
+    return null;
+  }
+}
+
+const isIpLiteral = (host) => /^[\d.]+$/.test(host) || host.includes(':');
+
+function step(name, ok, detail, hint = null) {
+  return hint ? { name, ok, detail, hint } : { name, ok, detail };
+}
+
+function resolveHost(host, deps) {
+  return new Promise((resolve) => {
+    deps.lookup(host, (err, address) => resolve(err ? null : address));
+  });
+}
+
+function probeTcp(host, port, timeoutMs, deps) {
+  return new Promise((resolve) => {
+    const socket = deps.netConnect({ host, port });
+    const done = (result) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.on('connect', () => done({ ok: true }));
+    socket.on('timeout', () => done({ ok: false, reason: 'timeout' }));
+    socket.on('error', (err) => done({ ok: false, reason: err.code || err.message }));
+  });
+}
+
+function probeTls(host, port, timeoutMs, deps) {
+  return new Promise((resolve) => {
+    // SNI is a hostname field: Node throws outright if given an IP, and on a
+    // LAN the target is almost always an IP. Send it only when we have a name.
+    const sni = isIpLiteral(host) ? {} : { servername: host };
+    // Diagnostic socket only: it completes the handshake, reads the
+    // certificate, reports it and closes — no data is ever sent over it.
+    // rejectUnauthorized is off precisely so a self-signed LAN certificate
+    // still reaches this point and can be DESCRIBED to the user instead of
+    // failing opaquely. The real chat connection does not run this way: it
+    // enforces strict verification for hosts that ever presented a CA-valid
+    // certificate (see crypto/CertPinStore.js).
+    const socket = deps.tlsConnect({ host, port, rejectUnauthorized: false, ...sni });
+    const done = (result) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.on('secureConnect', () => {
+      const cert = socket.getPeerCertificate?.() || {};
+      done({
+        ok: true,
+        authorized: socket.authorized === true,
+        issuer: cert.issuer?.O || cert.issuer?.CN || 'unknown',
+        fingerprint: cert.fingerprint256 || null,
+      });
+    });
+    socket.on('timeout', () => done({ ok: false, reason: 'timeout' }));
+    socket.on('error', (err) => done({ ok: false, reason: err.code || err.message }));
+  });
+}
+
+/**
+ * Run the connection checks against `target`.
+ *
+ * @param {string} target - what the user typed at the Server prompt
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs]
+ * @param {object} [opts.deps] - injectable node primitives (tests)
+ * @returns {Promise<Array<{name, ok, detail, hint?}>>}
+ */
+export async function diagnose(target, opts = {}) {
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const deps = {
+    lookup: dnsLookup,
+    netConnect,
+    tlsConnect,
+    ...(opts.deps || {}),
+  };
+  const steps = [];
+
+  const parsed = parseTarget(target);
+  if (!parsed) {
+    steps.push(
+      step(
+        'Address',
+        false,
+        `cannot parse "${target}"`,
+        'Use host:port — for example 192.168.1.10:3600 — or a ciphermesh:// invite.',
+      ),
+    );
+    return steps;
+  }
+  steps.push(
+    step('Address', true, `${parsed.host}:${parsed.port} (${parsed.tls ? 'TLS' : 'plain'})`),
+  );
+
+  if (/^(localhost|127\.|::1)/.test(parsed.host)) {
+    steps.push(
+      step(
+        'Target',
+        true,
+        'localhost — this points at YOUR machine',
+        'To reach someone else, use THEIR address. localhost never leaves this computer.',
+      ),
+    );
+  }
+
+  if (!isIpLiteral(parsed.host)) {
+    const address = await resolveHost(parsed.host, deps);
+    steps.push(
+      address
+        ? step('DNS', true, `${parsed.host} → ${address}`)
+        : step(
+            'DNS',
+            false,
+            `cannot resolve ${parsed.host}`,
+            'Check the name, or use the IP directly.',
+          ),
+    );
+    if (!address) {
+      return steps;
+    }
+  }
+
+  const tcp = await probeTcp(parsed.host, parsed.port, timeoutMs, deps);
+  if (!tcp.ok) {
+    steps.push(
+      step(
+        'TCP port',
+        false,
+        `port ${parsed.port} unreachable (${tcp.reason})`,
+        tcp.reason === 'timeout'
+          ? 'Something is dropping the packets: a firewall on either side, or client isolation on the Wi-Fi router. If you can ping the host but not open the port, that is the usual cause.'
+          : 'Nothing is listening there. Is the server running, and is the port right?',
+      ),
+    );
+    return steps;
+  }
+  steps.push(step('TCP port', true, `${parsed.host}:${parsed.port} is open`));
+
+  if (parsed.tls) {
+    const tls = await probeTls(parsed.host, parsed.port, timeoutMs, deps);
+    if (!tls.ok) {
+      steps.push(
+        step(
+          'TLS',
+          false,
+          `handshake failed (${tls.reason})`,
+          'The port answered but did not negotiate TLS. Is that really a CipherMesh relay?',
+        ),
+      );
+      return steps;
+    }
+    steps.push(
+      tls.authorized
+        ? step('TLS', true, `verified against a public CA (${tls.issuer})`)
+        : step(
+            'TLS',
+            true,
+            'self-signed certificate (normal on a LAN)',
+            'Trust is pinned on first use — compare fingerprints out-of-band if you want certainty.',
+          ),
+    );
+  }
+
+  steps.push(
+    step(
+      'Protocol',
+      true,
+      `this client speaks v${PROTOCOL_VERSION}`,
+      'If the server refuses with a protocol mismatch, update BOTH sides: npx ciphermesh@latest, or git pull && npm install from source.',
+    ),
+  );
+
+  return steps;
+}
+
+/** Render diagnose() output as lines ready for the chat log. */
+export function formatDiagnosis(steps) {
+  const lines = [];
+  for (const s of steps) {
+    lines.push(`${s.ok ? '✓' : '✗'} ${s.name}: ${s.detail}`);
+    if (s.hint) {
+      lines.push(`    ↳ ${s.hint}`);
+    }
+  }
+  const failed = steps.find((s) => !s.ok);
+  lines.push(
+    failed
+      ? `Blocked at "${failed.name}". Fix that first — the checks after it were skipped.`
+      : 'All checks passed. If the chat still fails, the problem is above the network layer.',
+  );
+  return lines;
+}