hivecode-mcp 0.12.1 → 0.12.4

package/hive-receipts.js

@@ -1,233 +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.'
-}
+// 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.'
+}

package/hive-relay-health.js

@@ -212,9 +212,14 @@ export function statusFromError(e) {
 /**
  * Authoritative explanations for HTTP status codes returned by the relay on connection upgrade.
  */
-export function explainStatus(code, relay = '') {
+export function explainStatus(code, relay = '', opts = {}) {
   const c = Number(code)
-  if (c === 401) return 'the relay rejected your token. It may have expired -- ask the room owner for a new invite.'
+  if (c === 401) {
+    if (opts && opts.hasToken === false) {
+      return 'this room needs a token of your own. Ask the room owner to mint you one.'
+    }
+    return 'the relay rejected your token. It may have expired -- ask the room owner for a new invite.'
+  }
   if (c === 402) return 'this room is over its plan limit. Contact support@getgrm.tech and we will sort it out.'
   if (c === 403) return 'the relay refused this room or path for your token. You are outside the folders you were given.'
   if (c === 429) return 'this room is FULL, so you were not let in (Q431). A relay admits a limited number of connections per room -- 8 on the free tier -- and this room is at that ceiling. Note it counts CONNECTIONS, not people: one agent holding several files holds several. If you run the relay, raise it with HIVE_SEATS; otherwise ask whoever does, or contact support@getgrm.tech.'

package/hive-secrets.js

@@ -0,0 +1,89 @@
+// LIVE CREDENTIALS ARE NOT SENT TO THE ROOM (3 Oct 2026).
+//
+// A file in a room goes to the relay and to every participant's disk. ALWAYS_IGNORE keeps the
+// files that are secrets by NAME at home (.env, *.pem, id_rsa, ...), but a secret inside an
+// ordinary file went out with it: an agent that pastes an API key into config.js to try
+// something shares that key with everyone in the room, and with whoever runs the relay.
+//
+// So a file whose content holds a credential the room does not already have is held on this
+// machine (see sync.js, withheld) until the credential is moved out. Only formats a provider
+// stamps on its keys are matched -- a fixed prefix plus enough random characters -- and private
+// key blocks. Nothing here guesses from entropy alone: a false match holds back real work, and
+// the people who hit it would be right to switch this off.
+//
+// The matched value never leaves this module's callers in any form: not in a log line, not in
+// the room, not in status. Only its kind and its line number do.
+
+const PATTERNS = [
+  { kind: 'private key', re: /-----BEGIN (?:[A-Z0-9]+ ){0,3}PRIVATE KEY(?: BLOCK)?-----/g },
+  { kind: 'AWS access key', re: /\b(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g },
+  { kind: 'GitHub token', re: /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{60,100})\b/g },
+  { kind: 'GitLab token', re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
+  { kind: 'Slack token', re: /\bxox[abposr]-[0-9]{6,}-[0-9A-Za-z-]{10,}/g },
+  { kind: 'Slack webhook', re: /hooks\.slack\.com\/services\/T[A-Z0-9]{6,}\/B[A-Z0-9]{6,}\/[A-Za-z0-9]{20,}/g },
+  { kind: 'Stripe live key', re: /\b[rs]k_live_[A-Za-z0-9]{20,}\b/g },
+  { kind: 'OpenAI API key', re: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{16,}T3BlbkFJ[A-Za-z0-9_-]{16,}/g },
+  { kind: 'Anthropic API key', re: /\bsk-ant-(?:api|admin|oat)\d{2}-[A-Za-z0-9_-]{60,}/g },
+  { kind: 'npm token', re: /\bnpm_[A-Za-z0-9]{36}\b/g },
+  { kind: 'Hugging Face token', re: /\bhf_[A-Za-z0-9]{30,40}\b/g },
+  { kind: 'Groq API key', re: /\bgsk_[A-Za-z0-9]{40,60}\b/g },
+  { kind: 'SendGrid API key', re: /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/g },
+  { kind: 'DigitalOcean token', re: /\bdo[opr]_v1_[a-f0-9]{64}\b/g },
+  // .npmrc and friends: a registry password or token written out literally. `${NPM_TOKEN}` is the
+  // documented way to keep one out of the file, so a reference to the environment is not a secret.
+  { kind: 'registry credential', re: /(?:^|\n)[ \t]*(?:\/\/[^\s=]+:)?_(?:authToken|auth|password)[ \t]*=[ \t]*(?!\$\{)[^\s'"]{8,}/g },
+]
+
+// Documentation and tests are full of keys that look real and are not: AWS's own example id,
+// and placeholders like sk_live_XXXXXXXXXXXXXXXXXXXXXXXX. A provider's key is random, so a match
+// with few distinct characters, or that says it is an example, is a placeholder.
+const PLACEHOLDER = /EXAMPLE|example|XXXX|xxxx|0{8}|1234567890|your[_-]?(?:key|token|secret)/i
+function placeholder(value, kind) {
+  if (kind === 'private key' || kind === 'registry credential') return false
+  if (PLACEHOLDER.test(value)) return true
+  return new Set(value).size < 10
+}
+
+// A SIGNED ACCESS TOKEN -- a JWT, which is what Hivecode's own room tokens are -- is a person: whoever
+// holds it joins as them, with their access. It is kept out of the room's chat and tasks
+// ({ tokens: true }). It is NOT a reason to hold a FILE back: auth code and its tests are full of
+// sample tokens, most of them expired or fake, and holding each such file would stop real work.
+export const TOKEN_PATTERNS = [
+  { kind: 'access token', re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{16,}/g },
+]
+
+/** Every credential in `text`: [{ kind, line, value }]. `value` is for comparing, never for showing.
+ *  `tokens: true` adds signed access tokens, for what goes into the room's chat and tasks. */
+export function findSecrets(text, { tokens = false } = {}) {
+  const s = String(text || '')
+  if (!s) return []
+  const out = []
+  for (const { kind, re } of tokens ? [...PATTERNS, ...TOKEN_PATTERNS] : PATTERNS) {
+    re.lastIndex = 0
+    let m
+    while ((m = re.exec(s)) !== null) {
+      const value = m[0].replace(/^\s+/, '')
+      if (!placeholder(value, kind)) {
+        const at = m.index + (m[0].length - m[0].replace(/^\s+/, '').length)
+        out.push({ kind, line: s.slice(0, at).split('\n').length, value })
+      }
+      if (m[0].length === 0) re.lastIndex++
+    }
+  }
+  return out.sort((a, b) => a.line - b.line)
+}
+
+/** Credentials in `local` that `shared` does not already contain: what sharing `local` would leak. */
+export function newSecrets(local, shared) {
+  const found = findSecrets(local)
+  if (!found.length) return []
+  const room = String(shared || '')
+  return found.filter((f) => !room.includes(f.value))
+}
+
+/** "an OpenAI API key (line 12)" -- the only form a finding is ever shown in. */
+export function describeSecret(f) {
+  if (!f) return ''
+  const a = /^(?:[aeiou]|npm\b)/i.test(f.kind) ? 'an' : 'a'
+  return `${a} ${f.kind} (line ${f.line})`
+}