hivecode-mcp 0.11.5 → 0.12.0

package/hive-privacy.js

@@ -0,0 +1,263 @@
+// WHICH RELAY IS THIS, AND DID ANYBODY CHOOSE IT?
+//
+// Every byte of a team's source leaves their machines through one URL: the relay. The
+// client has always printed that URL and stopped there -- a bare `relay: wss://...` line
+// that says nothing about what it MEANS. That is the whole defect this file exists for,
+// and it is the product's highest-stakes false success:
+//
+//   An agent starts with no link and no .hive.json. resolveRoom() falls through to the
+//   shipped default -- a relay the team does not run. The agent joins. hive_status says
+//   connected. filesSynced climbs. Every signal is green, and the company's source code
+//   is now on a stranger's server. Nothing crashed, so nothing reports it.
+//
+// Two separate things are needed and they are NOT the same thing:
+//
+//   1. A VERDICT on every join, so "am I private?" is answered without being asked.
+//      Printing the URL is not a verdict. A person who has never run a relay cannot tell
+//      wss://livecode-xoss.onrender.com from wss://relay.theircompany.com by looking.
+//
+//   2. A PIN that REFUSES. A verdict you have to read is a verdict that gets skimmed, and
+//      an agent does not read banners at all. HIVE_RELAY_PIN says "this machine may only
+//      ever talk to these relays" -- set once in the MCP config, and no stale link, no
+//      typo'd host and no forgotten env var can send a file anywhere else. The refusal
+//      happens BEFORE the socket opens, so a refused join publishes nothing.
+//
+// Comparison is on ORIGIN, never on the raw string. wss://r.co, wss://r.co/ and
+// wss://R.co:443 are one relay; a string compare would refuse a correct configuration,
+// and a guard that fires on the healthy path is a guard people disable.
+
+// The relay this build falls back to when nobody chose one -- THE ONE PLACE IT IS WRITTEN.
+//
+// It used to be written four times: here, hive-mcp.js, hive-agent.js and hive-say.js, each a
+// literal. On 23 Sep 2026 the hosted relay's Render account was suspended and a new one stood
+// up at a new address, and moving meant hunting down every copy -- any one missed would have
+// sent that client to a dead host, or made this module call the live default "YOUR RELAY".
+// Every client now imports it from here. The extension's JSON setting cannot import, so
+// extension-privacy-parity-test pins it equal to this value instead.
+export const PUBLIC_DEFAULT_RELAY = 'wss://hivecode-relay.onrender.com'
+
+// Relays this project has run publicly and retired. A .hive.json written before a move still
+// names the old one, and if that host ever answers again (a reactivated account, a squatter
+// on the name) the verdict must still say PUBLIC -- not "YOUR RELAY", which is what any host
+// outside this list is called.
+export const RETIRED_PUBLIC_RELAYS = ['wss://livecode-xoss.onrender.com']
+
+const DEFAULT_PORT = { 'ws:': '80', 'wss:': '443', 'http:': '80', 'https:': '443' }
+
+/**
+ * Normalise a relay URL to a comparable origin: scheme://host:port, lowercased, with the
+ * scheme's default port made explicit. Returns null for anything that is not a URL --
+ * callers must treat null as "unknown", never as "fine".
+ */
+export function relayOrigin(url) {
+  const s = String(url || '').trim()
+  if (!s) return null
+  let u
+  try { u = new URL(s) } catch { return null }
+  const proto = u.protocol.toLowerCase()
+  if (!DEFAULT_PORT[proto]) return null
+  const port = u.port || DEFAULT_PORT[proto]
+  // ws:// and wss:// to the same host:port are the SAME relay reached two ways, and a pin
+  // written as https:// (which is what a person copies out of a browser) must match the
+  // wss:// the client actually dials. Scheme is reported separately by classifyRelay so
+  // the plaintext warning still fires; it deliberately does not participate in identity.
+  const secureScheme = proto === 'wss:' || proto === 'https:'
+  return `${secureScheme ? 'wss' : 'ws'}://${u.hostname.toLowerCase()}:${port}`
+}
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0', '[::1]'])
+
+function isLoopback(host) {
+  const h = String(host || '').toLowerCase().replace(/^\[|\]$/g, '')
+  if (LOOPBACK.has(h)) return true
+  return /^127\./.test(h)
+}
+
+function isPrivateLan(host) {
+  const h = String(host || '').toLowerCase()
+  if (/^10\./.test(h)) return true
+  if (/^192\.168\./.test(h)) return true
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(h)) return true
+  if (/\.local$/.test(h) || /\.lan$/.test(h) || /\.internal$/.test(h)) return true
+  // A PRIVATE MESH (Tailscale and friends) IS A PRIVATE NETWORK, and the first version of this
+  // file called it "the public internet in plaintext". 100.64.0.0/10 is the shared address space
+  // Tailscale hands out and *.ts.net is its MagicDNS; the transport underneath is WireGuard,
+  // end-to-end encrypted between the two devices, and nothing outside the tailnet can even
+  // route to the relay. Warning a remote team that chose the most private setup available
+  // that their source was travelling in the clear would have taught them to ignore the verdict.
+  if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(h)) return true
+  if (/\.ts\.net$/.test(h)) return true
+  return false
+}
+
+// PUBLIC TUNNELS decrypt at their own edge. A relay on a laptop behind cloudflared or ngrok is
+// the team's relay -- nobody else runs it -- but the tunnel provider terminates TLS and can read
+// every frame, and anyone holding the URL can reach the port. Both facts matter to a team that
+// picked a tunnel *for privacy*, and neither is visible in a URL that starts with wss://.
+const PUBLIC_TUNNEL = /\.(trycloudflare\.com|ngrok-free\.app|ngrok\.app|ngrok\.io|ngrok-free\.dev|loca\.lt|serveo\.net|localhost\.run)$/
+
+function isPublicTunnel(host) {
+  return PUBLIC_TUNNEL.test(String(host || '').toLowerCase())
+}
+
+/**
+ * What kind of relay is this, and does traffic to it leave the machine in the clear?
+ *
+ *   kind: 'public-default' | 'loopback' | 'private-lan' | 'tunnel' | 'own' | 'unknown'
+ *
+ * 'own' does not mean audited -- it means "not the relay we ship". A team that pastes a
+ * link from a blog post lands in 'own' too, which is exactly why the pin exists.
+ */
+export function classifyRelay(url) {
+  const origin = relayOrigin(url)
+  if (!origin) return { kind: 'unknown', origin: null, host: null, encrypted: false, url: String(url || '') }
+  const u = new URL(String(url).trim())
+  const host = u.hostname.toLowerCase()
+  const encrypted = u.protocol === 'wss:' || u.protocol === 'https:'
+  let kind
+  if (origin === relayOrigin(PUBLIC_DEFAULT_RELAY) ||
+    RETIRED_PUBLIC_RELAYS.some((r) => relayOrigin(r) === origin)) kind = 'public-default'
+  else if (isLoopback(host)) kind = 'loopback'
+  else if (isPrivateLan(host)) kind = 'private-lan'
+  else if (isPublicTunnel(host)) kind = 'tunnel'
+  else kind = 'own'
+  return { kind, origin, host, encrypted, url: String(url).trim() }
+}
+
+/**
+ * The pin, from the environment or from <dir>/.hive.json's `pinnedRelay`. Comma-separated,
+ * because a team legitimately has a staging relay and a production one.
+ *
+ * A pin that cannot be parsed is an ERROR, never an empty pin. That distinction is the
+ * whole value of the feature: a typo silently collapsing to "no pin" leaves somebody
+ * believing they are locked to their own relay while the client dials the public one --
+ * the same absence-rendered-as-a-value shape the room has been bitten by before.
+ */
+export function readPin({ env = process.env, dir = null, fs = null } = {}) {
+  let raw = String((env && env.HIVE_RELAY_PIN) || '').trim()
+  let from = 'HIVE_RELAY_PIN'
+  if (!raw && dir && fs) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(`${dir}/.hive.json`, 'utf8'))
+      if (cfg && cfg.pinnedRelay) { raw = String(cfg.pinnedRelay).trim(); from = '.hive.json pinnedRelay' }
+    } catch { /* no config, or not JSON -- that is "no pin", not "bad pin" */ }
+  }
+  if (!raw) return { pinned: false, origins: [], from: null, raw: '' }
+  const parts = raw.split(',').map((s) => s.trim()).filter(Boolean)
+  const origins = []
+  const bad = []
+  for (const p of parts) {
+    const o = relayOrigin(p)
+    if (o) origins.push(o); else bad.push(p)
+  }
+  if (bad.length || !origins.length) {
+    return { pinned: true, origins, from, raw, error: `not a relay URL: ${bad.join(', ') || raw}` }
+  }
+  return { pinned: true, origins, from, raw }
+}
+
+const HEADLINE = {
+  'public-default': 'PUBLIC RELAY — not yours',
+  loopback: 'PRIVATE — relay on this machine',
+  'private-lan': 'PRIVATE — relay on your network',
+  tunnel: 'YOUR RELAY — through a public tunnel',
+  own: 'YOUR RELAY',
+  unknown: 'UNKNOWN RELAY',
+}
+
+/**
+ * The one call a client makes before opening a socket.
+ *
+ * Returns { ok, code, headline, detail, classification, pin }. `ok:false` means DO NOT
+ * CONNECT -- the caller must not open the socket and must not publish anything, because
+ * publishing is the leak this prevents. A warning (ok:true with `warn`) is printed and
+ * proceeds: a team on a plaintext LAN relay has made a choice, and refusing it would be
+ * this guard deciding policy it was not given.
+ *
+ *   Q550  the relay is not one this machine is pinned to
+ *   Q551  HIVE_PRIVATE is set and this is the public relay we ship
+ *   Q552  the pin itself is malformed, so nothing is actually pinned
+ */
+export function checkRelay({ relay, env = process.env, dir = null, fs = null } = {}) {
+  const c = classifyRelay(relay)
+  const pin = readPin({ env, dir, fs })
+  const strict = String((env && env.HIVE_PRIVATE) || '') === '1'
+
+  if (pin.pinned && pin.error) {
+    return {
+      ok: false, code: 'Q552', classification: c, pin,
+      headline: 'Q552 THE RELAY PIN IS MALFORMED — REFUSING TO CONNECT',
+      detail: [
+        `${pin.from} = ${pin.raw}`,
+        `problem: ${pin.error}`,
+        '',
+        'A pin that cannot be parsed is refused rather than ignored. Ignoring it would leave',
+        'you believing this machine is locked to your relay while it dials whatever it likes.',
+        'Write it as a full URL, e.g. HIVE_RELAY_PIN=wss://relay.yourcompany.com',
+      ].join('\n'),
+    }
+  }
+
+  if (pin.pinned && c.origin && !pin.origins.includes(c.origin)) {
+    return {
+      ok: false, code: 'Q550', classification: c, pin,
+      headline: 'Q550 THIS RELAY IS NOT THE ONE THIS MACHINE IS PINNED TO — REFUSING TO CONNECT',
+      detail: [
+        `asked to connect to : ${c.url}   (${c.origin})`,
+        `pinned to           : ${pin.origins.join(', ')}   (via ${pin.from})`,
+        '',
+        'Nothing was opened and nothing was published, so no file has left this machine.',
+        c.kind === 'public-default'
+          ? 'The relay asked for is the PUBLIC one this build ships as a fallback — which is what\nyou get when a link is missing, a .hive.json was not found, or HIVE_RELAY is unset.'
+          : 'Check the join link you were given, and HIVE_RELAY in this process\'s environment.',
+      ].join('\n'),
+    }
+  }
+
+  if (!pin.pinned && strict && c.kind === 'public-default') {
+    return {
+      ok: false, code: 'Q551', classification: c, pin,
+      headline: 'Q551 HIVE_PRIVATE=1 AND THIS IS THE PUBLIC RELAY — REFUSING TO CONNECT',
+      detail: [
+        `relay: ${c.url}`,
+        '',
+        'This is the relay this build falls back to when nobody chose one. Under HIVE_PRIVATE',
+        'that fallback is an error rather than a default, because it is reached by omission —',
+        'a missing link or an unset HIVE_RELAY — and never by anybody deciding on it.',
+        '',
+        'Point HIVE_RELAY at your own relay, or unset HIVE_PRIVATE if you meant to use ours.',
+      ].join('\n'),
+    }
+  }
+
+  // Connecting. Say what that means, in one line, every time.
+  let warn = null
+  if (c.kind === 'public-default') {
+    warn = 'Your files are being sent to a relay run by the Hivecode author, not by you. ' +
+      'Anyone who learns this room id can read them. For private work run your own relay ' +
+      '(npx hivecode-relay) and set HIVE_RELAY.'
+  } else if (c.kind === 'tunnel') {
+    warn = `${c.host} is a public tunnel. The relay is yours, but the tunnel provider decrypts ` +
+      'traffic at its edge and can read it, and anyone with this URL can reach the relay. Fine for ' +
+      'a trial with --secret set; for private remote work use a private network (e.g. Tailscale) ' +
+      'or a server you control.'
+  } else if (c.kind === 'own' && !c.encrypted) {
+    warn = `ws:// to ${c.host} is NOT encrypted — your source travels the public internet in ` +
+      'plaintext. Put TLS in front of the relay and use wss://.'
+  } else if (c.kind === 'unknown') {
+    warn = `"${c.url}" does not parse as a relay URL — the client will almost certainly fail ` +
+      'to connect, and if it does connect you cannot tell where to.'
+  }
+
+  return {
+    ok: true, code: null, classification: c, pin, warn,
+    headline: `${HEADLINE[c.kind]}${c.encrypted ? '' : c.kind === 'loopback' ? '' : ' (UNENCRYPTED)'}`,
+    detail: warn || '',
+  }
+}
+
+/** One line for a join banner / status block: the URL plus what it means. */
+export function privacyLine(relay, opts = {}) {
+  const v = checkRelay({ relay, ...opts })
+  return `relay: ${relay}  [${v.headline}]`
+}

package/hive-receipts.js

@@ -0,0 +1,233 @@
+// hive-receipts.js — did the message actually reach anybody, or did it only look like it did?
+//
+// THE DEFECT THIS EXISTS FOR, from this project's own history:
+//
+//   "29 messages @-mentioned me today. hive_wait has surfaced a handful."
+//   "Those messages land in HIVE_CHAT.md and look delivered -- they just may never reach the
+//    recipient's context. The convention looks like it works, which is the worst property a
+//    coordination protocol can have."
+//
+// `hive_say` returns "sent to @Builder: ..." the instant the message enters the LOCAL Yjs array.
+// It says that while the socket is down. It says that when @Builder crashed ten minutes ago. It
+// says that when @Builder is looping without ever calling hive_wait. Three different failures,
+// one cheerful word, and the sender has no way to tell them apart.
+//
+// WHAT THE EVIDENCE IS, HERE. Agent Relay verifies a delivery by watching the terminal echo the
+// keystrokes back (crates/broker/src/broker/delivery_verification.rs). There is no terminal here,
+// so copying the mechanism would be cargo cult. The equivalent evidence in Hivecode is the one
+// thing that only moves when a message is actually handed into an agent's context:
+//
+//                       THE READ CURSOR IS THE ECHO.
+//
+// A mailbox cursor advances only inside `box.take()`, which is what hands messages to the agent.
+// So "their cursor passed the slot my message sits in" means the message was in the payload that
+// agent received. Today that cursor is written to a LOCAL session file, where nobody else can see
+// it. Publishing it into the room is the whole change.
+//
+// FOUR STATES, AND THE FOURTH IS THE POINT. Agent Relay has three (Success / Unverified /
+// Failed) and the load-bearing one is Unverified -- an unconfirmed delivery must never be counted
+// as a confirmed one. Their comment: "Unverified neither speeds up nor backs off the throttle,
+// but breaks the consecutive-success streak so unverified deliveries never drive the delay down."
+//
+// The same rule here, phrased for this system:
+//
+//   READ         their cursor passed it. Evidence it landed.
+//   UNREAD       they publish cursors, and theirs is behind it. Evidence it did NOT.
+//   UNKNOWN      they publish no cursor at all. NO evidence either way -- and it must never be
+//                counted as READ. A Telegram bridge, a human's browser and an older build all
+//                land here, so silence from this state means nothing at all.
+//   UNREACHABLE  they are not in the room, or WE are offline. It is not going to arrive.
+//
+// UNKNOWN is the honest state that a two-state design (delivered / not) cannot express, and
+// collapsing it into either neighbour is how a receipt system starts lying. `countDelivered`
+// exists precisely so that no caller can accidentally sum UNKNOWN into the good number.
+//
+// NO STORED INDEX. A Yjs array index is not stable: two peers pushing concurrently converge in a
+// deterministic order that need not be the order either one observed, so a message's index can
+// move after it was recorded. Receipts are therefore DERIVED at query time by locating the
+// message in the converged array -- the same choice `unansweredFor` made in hive-mailbox.js, for
+// the same reason: nothing to migrate and nothing that can drift.
+
+// @-parsing is imported, never re-implemented. A second hand-written copy of "who was named in
+// this text" is exactly the shape Agent Relay wrote up in learnings/duplicated-wire-contract.md
+// and exactly the shape that already bit this repo once as a duplicated reconcile(): two
+// descriptions of one thing, only one of which is ever checked against reality.
+import { mentionedNames, mentionsAll } from './hive-mailbox.js'
+
+export const READ = 'READ'
+export const UNREAD = 'UNREAD'
+export const UNKNOWN = 'UNKNOWN'
+export const UNREACHABLE = 'UNREACHABLE'
+
+/** Only these count as delivered. Anything else is an absence of evidence, not evidence. */
+export const DELIVERED_STATES = [READ]
+
+const lc = (x) => String(x == null ? '' : x).toLowerCase()
+
+/**
+ * Publish my read position into the room.
+ *
+ * `at` is a count of messages consumed, so it only ever moves forward. It is clamped against
+ * going BACKWARDS because a rejoin can hand a session a stale persisted cursor, and a receipt
+ * that un-reads a message somebody already answered is worse than no receipt at all.
+ */
+export function publishCursor(cursors, name, at, now = Date.now) {
+  if (!cursors || !name) return null
+  const prev = cursors.get(String(name))
+  const next = Math.max(0, Number(at) || 0)
+  const highest = Math.max(next, (prev && Number(prev.at)) || 0)
+  const rec = { at: highest, ts: now(), ver: 1 }
+  // Writing an identical value would still be a CRDT update, waking every observer in the room
+  // on every tool call for no information. Only a real advance is published.
+  if (prev && prev.at === highest) return prev
+  cursors.set(String(name), rec)
+  return rec
+}
+
+/** Case-insensitive, because @Builder and @builder are one agent everywhere else in this system. */
+export function cursorOf(cursors, name) {
+  if (!cursors) return null
+  const direct = cursors.get(String(name))
+  if (direct) return direct
+  for (const [k, v] of cursors.entries()) if (lc(k) === lc(name)) return v
+  return null
+}
+
+/**
+ * Where a message sits in the converged chat array, or -1.
+ *
+ * Identity is (by, at, text) rather than an index: the triple survives reordering, and the index
+ * does not. Searched from the end because a receipt is almost always asked about something said
+ * recently, and the room's history can be thousands of lines.
+ */
+export function findIndex(chat, msg) {
+  if (!Array.isArray(chat) || !msg) return -1
+  for (let i = chat.length - 1; i >= 0; i--) {
+    const m = chat[i]
+    if (m && m.by === msg.by && m.at === msg.at && m.text === msg.text) return i
+  }
+  return -1
+}
+
+/**
+ * The state of ONE message for ONE recipient.
+ *
+ * Order matters. `connected === false` outranks everything, because if our own socket is down the
+ * message has not left this process and nothing we believe about the other side is worth saying.
+ * Absence outranks a stale cursor for the same reason it does in hive-busy.js: it is the more
+ * actionable of the two.
+ */
+export function stateFor({ cursors, name, index, present = true, connected = true }) {
+  if (!connected) return { name, state: UNREACHABLE, why: 'this client is offline — the message is in your local copy only and has not left this machine' }
+  if (!present) return { name, state: UNREACHABLE, why: `@${name} is not in the room, so nobody is going to read it` }
+  if (index < 0) return { name, state: UNKNOWN, why: 'that message is not in the room log — it may not have synced' }
+  const cur = cursorOf(cursors, name)
+  if (!cur) return { name, state: UNKNOWN, why: `@${name} publishes no read position (an older build, a bridge, or a human client) — silence from them means nothing either way` }
+  // A cursor of N means N messages consumed, i.e. indexes 0..N-1. So the message at `index` has
+  // been handed over exactly when the cursor is strictly greater than it.
+  if (Number(cur.at) > index) return { name, state: READ, at: cur.ts, why: `@${name} has read it` }
+  return { name, state: UNREAD, at: cur.ts, behind: index + 1 - Number(cur.at), why: `@${name} is ${index + 1 - Number(cur.at)} message(s) behind and has NOT been handed this one` }
+}
+
+/**
+ * The state of ONE message for ONE recipient, ASKED AS A DIFFERENT QUESTION.
+ *
+ * `stateFor` above answers "should I wait for a reply from them right now?", so absence outranks
+ * a cursor: an agent that read your message and then left still cannot answer you, and blocking on
+ * them is the failure that function exists to prevent. That is correct, it is deliberate, and
+ * tests/receipts-test.mjs D1 pins it in capital letters.
+ *
+ * This one answers a different question: "did this message ever land?" — and there the cursor
+ * outranks absence, because A READ IS A FACT ABOUT THE PAST AND LOGGING OFF CANNOT UNDO IT.
+ *
+ * WHY TWO FUNCTIONS AND NOT A FLAG. A boolean that silently changes what the returned STRING means
+ * is how this class of bug is born: a caller that forgets it gets a confident answer to a question
+ * it did not ask. Two names cannot be confused by omission.
+ *
+ * WHY THIS ORDER, AND IT IS THE WHOLE DESIGN:
+ *   - `!cur` is checked BEFORE `!present`. A human in a browser, a Telegram bridge and every older
+ *     build publish no cursor at all. Reaching `!present` first would render them UNREACHABLE with
+ *     the claim "they left without reading it" — a claim we cannot support, because we have no
+ *     evidence either way. That is precisely what UNKNOWN exists to express, and folding it into
+ *     UNREACHABLE would make every human in the room read as a delivery failure forever.
+ *   - `!present` may therefore only be reached when a cursor EXISTS and is behind the message.
+ *     Only then is "they left without reading it" a measurement rather than a guess.
+ *   - `connected` is absent on purpose. The cursors map is LOCAL. Our own socket being down right
+ *     now says nothing about whether a three-day-old message was read; that was recorded and is
+ *     already here. Gate this on connectivity and the whole transcript blanks to UNKNOWN during
+ *     every reconnect — exactly when a human is reading it to work out what happened.
+ *
+ * Built by DeepMind-Agent (Gemini, in its own container) in room `night`, 20 Sep 2026, against a
+ * design argued in the room over four rounds. Tests are antigravity1's, written before the code
+ * existed and verified red first: tests/transcript-receipts-test.mjs.
+ */
+export function transcriptStateFor({ cursors, name, index, present = true }) {
+  if (index < 0) return { name, state: UNKNOWN, why: 'that message is not in the room log — it may not have synced' }
+  const cur = cursorOf(cursors, name)
+  if (!cur) return { name, state: UNKNOWN, why: `@${name} publishes no read position (an older build, a bridge, or a human client) — silence from them means nothing either way` }
+  // A cursor of N means N messages consumed, i.e. indexes 0..N-1. So the message at `index` has
+  // been handed over exactly when the cursor is STRICTLY greater than it. A cursor sitting exactly
+  // at `index` means NOT read; an off-by-one here is a receipt that lies quietly.
+  if (Number(cur.at) > index) return { name, state: READ, at: cur.ts, why: `@${name} has read it` }
+  // Only reachable when a cursor exists and is behind the message.
+  if (!present) return { name, state: UNREACHABLE, at: cur.ts, behind: index + 1 - Number(cur.at), why: `@${name} is not in the room, and left with cursor behind this message` }
+  return { name, state: UNREAD, at: cur.ts, behind: index + 1 - Number(cur.at), why: `@${name} is ${index + 1 - Number(cur.at)} message(s) behind and has NOT been handed this one` }
+}
+
+/** Only READ counts. Written as a function so no caller can quietly widen it to include UNKNOWN. */
+export const countDelivered = (states) => states.filter((s) => DELIVERED_STATES.includes(s.state)).length
+
+/**
+ * Every message I addressed to somebody, with per-recipient state.
+ *
+ * Unaddressed messages are skipped on purpose: they land in the ambient digest, where agents are
+ * instructed to skip them, so a receipt for one would be measuring something nobody promised.
+ * `@all` is skipped for the same reason a broadcast creates no reply debt in hive-mailbox.js --
+ * one message obliging eight receipts is the storm, not the signal.
+ */
+export function receipts({ chat, cursors, me, present = () => true, connected = true, limit = 10 }) {
+  const list = Array.isArray(chat) ? chat : []
+  const out = []
+  for (let i = list.length - 1; i >= 0 && out.length < limit; i--) {
+    const m = list[i]
+    if (!m || lc(m.by) !== lc(me)) continue
+    if (mentionsAll(m.text)) continue
+    const named = mentionedNames(m.text).filter((n) => lc(n) !== 'all' && lc(n) !== lc(me))
+    if (!named.length) continue
+    out.push({
+      at: m.at,
+      text: String(m.text || '').slice(0, 120),
+      to: named.map((n) => stateFor({ cursors, name: n, index: i, present: present(n), connected })),
+    })
+  }
+  return out.reverse()
+}
+
+const MARK = { [READ]: '✓', [UNREAD]: '…', [UNKNOWN]: '?', [UNREACHABLE]: '✗' }
+
+/** One line per message. The marks make a column a human can scan; the words carry the meaning. */
+export function describe(r) {
+  return `${r.at}  ${r.to.map((s) => `${MARK[s.state] || '?'} ${s.name}=${s.state}`).join('  ')}  "${r.text}"`
+}
+
+/**
+ * What hive_say should say instead of "sent".
+ *
+ * ONE FAILURE ONLY, AND THAT IS DELIBERATE. At send time delivery is not knowable -- the message
+ * was created a millisecond ago -- so the single thing worth saying is the one that is already
+ * decided and is currently reported as success: our own socket is down.
+ *
+ * It says nothing about an ABSENT recipient even though that is equally decidable, because
+ * `describeRecipient` in hive-busy.js already says it ("@X is NOT in the room — nobody will read
+ * that") and a second hand-written copy of that sentence is precisely the defect class Agent
+ * Relay wrote up in learnings/duplicated-wire-contract.md: two descriptions of one fact, only one
+ * of which anybody keeps current. One producer, one description.
+ *
+ * On success it returns the empty string. A reassuring word at send time IS the defect.
+ */
+export function sendWarning({ connected }) {
+  if (connected) return ''
+  return 'NOT SENT — this client is OFFLINE. The message is in your local copy only; it has not ' +
+    'reached the relay and no one else can see it. It will go out by itself when the connection ' +
+    'heals (do NOT call hive_join, that tears down the session). Until then, treat it as unsent.'
+}