hivecode-mcp 0.11.5 → 0.11.6

package/hive-obligations.js

@@ -0,0 +1,247 @@
+// hive-obligations.js — a question you asked stays open until YOU say it was answered.
+//
+// THE PROBLEM THIS EXISTS FOR, observed live on 19 Sep 2026.
+//
+// Tester posted one message at 12:29 addressed to @Reviewer, an agent that was never in the
+// room, and then went silent for six hours. Nothing failed. No tool returned an error, no
+// process died, no log line said anything was wrong. The room simply had a question in it that
+// nobody would ever answer, and the only way to find that out was for a human to read the
+// transcript and notice.
+//
+// Hivecode already carries the RULE -- the MCP instructions say "ANSWER EVERY QUESTION AIMED AT
+// YOU: silence is the one thing the asker cannot act on". A rule an agent read once is a rule it
+// forgets the moment its context fills. So the rule moves here, where it is a data structure
+// instead of a paragraph.
+//
+// THE ONE LOAD-BEARING DECISION: ONLY THE ASKER DISCHARGES.
+//
+// The obvious design lets the answerer mark it answered. That design measures nothing. An agent
+// that replies "I'll look into it" would clear its own obligation, and a question answered wrongly
+// clears just as cleanly as one answered well. Both are exactly the failure -- everything green,
+// the result wrong -- that every defect on this project has turned out to be.
+//
+// So: `from` opened it, and only `from` can close it. The debtor cannot mark its own homework.
+// (Agent Relay reached the same conclusion independently in crates/broker/src/obligation.rs:
+// "only the author can discharge an obligation... the broker checks reactor == author". Their
+// broker re-injects a knock on a timer, which costs tokens on every knock. Ours rides hive_wait,
+// which is already blocked and already free.)
+//
+// ESCALATION IS TO AN AUDIENCE, NOT A FREQUENCY. A knock that repeats every minute forever is
+// noise, and a room learns to ignore noise. So the interval backs OFF (10min, 20min, 40min...)
+// while the visibility goes UP: after `STALE_AFTER` knocks the record is stale, and a stale
+// obligation is the room's problem rather than one agent's.
+//
+// PURE ON PURPOSE. Every function here takes the store and the clock. The store needs only
+// get/set/delete/entries, which a Y.Map and a plain Map both satisfy -- so the tests run against
+// a Map with an injected clock and no relay, and the production path passes the Y.Map. That is
+// the same shape as governor.js, and it is what let the governor's 10x minutes bug be caught by
+// a test instead of by a customer.
+
+/** Default time before the first knock. Ten minutes: long enough that an agent mid-task is not
+ *  nagged for thinking, short enough that a stall is caught inside one working stretch. */
+export const DUE_MS = 10 * 60000
+
+/** Each knock doubles the wait, so a genuinely long job is not pestered... */
+export const BACKOFF = 2
+
+/** ...but never past this, or a forgotten question goes quiet for a whole shift. */
+export const MAX_DUE_MS = 60 * 60000
+
+/** Knocks before the room is told. Three because two is a coincidence and four is too late. */
+export const STALE_AFTER = 3
+
+/** Chat text is a whole message; an obligation is an index entry. Keep it short enough that
+ *  `hive_owed` on a busy room stays readable rather than becoming a second transcript. */
+export const TEXT_MAX = 140
+
+const clip = (s) => {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim()
+  return t.length > TEXT_MAX ? t.slice(0, TEXT_MAX - 1) + '…' : t
+}
+
+/** Ids must not collide across peers. Two agents opening an obligation in the same millisecond is
+ *  not hypothetical in a CRDT room -- every write lands, and a shared key would silently make one
+ *  of the two questions disappear. Name + time + entropy: the name alone makes it readable in a
+ *  log, which the entropy alone would not.
+ *
+ *  THE TAG IS TWO DRAWS, NOT ONE, and that is not belt-and-braces. A single `rand() * 1e6` gives
+ *  about 2^20 of space, and by the birthday bound 500 ids drawn from it collide roughly 12% of the
+ *  time -- which is exactly how this was found: the suite passed, then failed, then passed again on
+ *  unchanged code. A flaky test here is not test flakiness, it is the defect reporting itself. Two
+ *  draws give ~2^40, where the same 500 ids collide about one run in five million. */
+export function obligationId(from, at, rand = Math.random) {
+  const draw = () => Math.floor(rand() * 1e6).toString(36).padStart(4, '0')
+  return `ob_${String(from || '?').toLowerCase().replace(/[^a-z0-9]+/g, '')}_${at.toString(36)}_${draw()}${draw()}`
+}
+
+/**
+ * Open an obligation: `from` asked `to` something and is owed an answer.
+ *
+ * `absent` is recorded at OPEN time and never recomputed. That is deliberate -- it is the answer
+ * to "was anyone even there when this was asked", which is a fact about the past. Recomputing it
+ * later would let a question asked into an empty room look fine the moment someone walks in.
+ */
+/**
+ * PRESENCE AND PROVENANCE ARE DIFFERENT QUESTIONS, AND `absent` ONLY ANSWERS THE FIRST.
+ *
+ * `absent` is stamped at send time and means "nobody by that name was connected at this instant".
+ * That is the right question for the warning — it is how the 19 Sep stall was caught — and it is
+ * the WRONG question for how long the record should live, because an agent mid-reconnect or
+ * mid-ratelimit is absent and is also a real teammate who really owes an answer.
+ *
+ * Measured in room `night`, 20 Sep 2026: an obligation against @DeepMind-Agent was stamped absent
+ * because it had dropped between turns. It came back ninety minutes later and answered. Expiring
+ * that record on a ten-minute timer would have deleted a genuine debt — and worse, it would have
+ * emptied the ledger precisely while an agent was silent, which is the exact inverse of what the
+ * ledger is for.
+ *
+ * So `neverSeen` is the separate fact: nobody by this name has ever joined or spoken here. That is
+ * the noise — @gmail, @modelcontextprotocol, a name quoted out of a test suite. It is safe to
+ * expire and safe for anyone to dismiss, because there is no debtor whose honesty the author-only
+ * rule exists to protect.
+ */
+export function open(store, { from, to, text, dueMs = DUE_MS, absent = false, neverSeen = false }, now = Date.now, rand = Math.random) {
+  const at = now()
+  const rec = {
+    id: obligationId(from, at, rand),
+    from: String(from),
+    to: String(to),
+    text: clip(text),
+    at,
+    due: at + Math.max(1, dueMs),
+    dueMs: Math.max(1, dueMs),
+    knocks: 0,
+    absent: !!absent,
+    neverSeen: !!neverSeen,
+    done: false,
+  }
+  store.set(rec.id, rec)
+  return rec
+}
+
+const all = (store) => [...store.entries()].map(([, v]) => v).filter(Boolean)
+
+/** Everything still open. */
+/**
+ * Everything still owed — with never-seen records aging out on their own.
+ *
+ * EXPIRY IS MATERIALISED, NOT MERELY FILTERED, and that distinction is load-bearing. Filtering
+ * here would leave `done: false` on the record, and `isStale` reads `r.done` directly rather than
+ * going through this function — so an expired ghost would vanish from one view and linger in
+ * another. Two readers disagreeing about whether a thing is finished is the same defect this whole
+ * file exists to prevent, one level down.
+ *
+ * Written lazily on read, which is the pattern the claim layer already uses (`hive-coord.js`
+ * expires a lease the moment somebody looks). There is no timer to miss and nothing to schedule:
+ * the fact becomes true at `due`, and the first reader after that writes it down.
+ *
+ * NO RESURRECTION. `neverSeen` is stamped when the question is asked and never recomputed, so a
+ * name that finally joins hours later does not revive its expired debt. The question was asked
+ * into an empty room; somebody arriving afterwards does not change what was true then.
+ *
+ * Only never-seen records expire. A known teammate's debt survives any amount of silence, because
+ * silence is the thing it is there to make visible.
+ */
+export const openList = (store, now = Date.now) => {
+  const out = []
+  for (const r of all(store)) {
+    if (r.done) continue
+    if (r.neverSeen && now() >= r.due) {
+      store.set(r.id, { ...r, done: true, doneAt: now(), doneBy: 'auto-expired (never seen here)' })
+      continue
+    }
+    out.push(r)
+  }
+  return out
+}
+
+/** What `name` OWES: questions aimed at them that their asker has not signed off. */
+export const owedBy = (store, name) =>
+  openList(store).filter((r) => String(r.to).toLowerCase() === String(name).toLowerCase())
+
+/** What `name` IS OWED: questions they asked that they have not signed off. */
+export const owedTo = (store, name) =>
+  openList(store).filter((r) => String(r.from).toLowerCase() === String(name).toLowerCase())
+
+/**
+ * Discharge. Returns `{ ok, reason }` and NEVER throws, because the interesting cases are all
+ * refusals and a refusal has to be readable by the agent that hit it.
+ *
+ * The `by !== from` refusal is the whole mechanism. It is phrased as instruction rather than
+ * error, because the agent reading it is usually the debtor trying to close its own ticket and
+ * the useful next action is "answer, then ask them to close it".
+ */
+export function discharge(store, { id, by }, now = Date.now) {
+  const rec = store.get(id)
+  if (!rec) return { ok: false, reason: `no obligation ${id} -- it may already be discharged` }
+  if (rec.done) return { ok: true, already: true, rec }
+  // THE AUTHOR-ONLY RULE PROTECTS A DEBTOR FROM GRADING ITS OWN HOMEWORK. A never-seen record has
+  // no debtor: nobody by that name has ever been here, so there is nobody whose self-assessment
+  // the rule is guarding against. Holding the rule there protects nothing and costs the room an
+  // entry only the original asker can clear -- and tonight the original asker cleared forty of
+  // them by hand. Anyone may tidy these; real debts keep the rule untouched.
+  if (!rec.neverSeen && String(rec.by || rec.from).toLowerCase() !== String(by).toLowerCase()) {
+    return {
+      ok: false,
+      reason: `${by} cannot discharge this: ${rec.from} asked it, and only the asker can say it ` +
+        `was answered. If you are ${rec.to}, answer it in chat and ${rec.from} will close it -- ` +
+        `marking your own answer sufficient is exactly the check this exists to make.`,
+    }
+  }
+  const done = { ...rec, done: true, doneAt: now(), doneBy: String(by) }
+  store.set(id, done)
+  return { ok: true, rec: done }
+}
+
+/** Close everything `by` is owed from one agent. An asker who got a long reply covering four
+ *  questions should not have to look up four ids to say so. */
+export function dischargeFrom(store, { by, to }, now = Date.now) {
+  const hit = owedTo(store, by).filter((r) => String(r.to).toLowerCase() === String(to).toLowerCase())
+  for (const r of hit) discharge(store, { id: r.id, by }, now)
+  return hit
+}
+
+/** Open obligations whose knock time has passed. */
+export const overdue = (store, name, now = Date.now) =>
+  owedBy(store, name).filter((r) => now() >= r.due)
+
+/**
+ * Record that a knock was delivered, and push the next one out.
+ *
+ * Called only when the knock actually reached somebody -- if we advanced `due` on merely NOTICING
+ * an overdue record, a debtor that never calls hive_wait would have its deadline extended forever
+ * by an observer, which is precisely backwards.
+ */
+export function knock(store, id, now = Date.now) {
+  const rec = store.get(id)
+  if (!rec || rec.done) return null
+  const nextDueMs = Math.min(MAX_DUE_MS, Math.max(1, rec.dueMs) * BACKOFF)
+  const next = { ...rec, knocks: rec.knocks + 1, dueMs: nextDueMs, due: now() + nextDueMs, lastKnockAt: now() }
+  store.set(id, next)
+  return next
+}
+
+/** Knocked enough times that this is the room's problem now, not one agent's. */
+export const isStale = (r) => !r.done && r.knocks >= STALE_AFTER
+
+/** Every stale obligation in the room, for the board and for the human. */
+export const stale = (store) => openList(store).filter(isStale)
+
+const mins = (ms) => Math.round(ms / 6000) / 10
+
+/** One line, for chat and for tool output. Age is what makes it actionable: "Tester owes Claude
+ *  an answer" is a fact, "for 361 minutes" is a decision. */
+export function describe(r, now = Date.now) {
+  const age = mins(now() - r.at)
+  const flags = [
+    r.absent ? 'NOBODY BY THAT NAME WAS IN THE ROOM' : '',
+    isStale(r) ? `STALE after ${r.knocks} reminders` : '',
+  ].filter(Boolean)
+  return `${r.id}  ${r.to} owes ${r.from}  (${age}m)  "${r.text}"${flags.length ? '  [' + flags.join('; ') + ']' : ''}`
+}
+
+/** The whole board, newest question last so it reads like a conversation. */
+export function board(store, now = Date.now) {
+  const list = openList(store).sort((a, b) => a.at - b.at)
+  return { open: list.length, stale: list.filter(isStale).length, lines: list.map((r) => describe(r, now)) }
+}

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.'
+}