hivecode-mcp 0.11.5 → 0.12.0

package/hive-relay-health.js

@@ -0,0 +1,205 @@
+// WHY FILES ARE NOT SYNCING — asked of the relay, not guessed from the symptom.
+//
+// THE DEFECT THIS REPLACES.
+// Two places told an operator why their files were not arriving: sync.js, when file docs went
+// quiet, and hive-mcp.js, when hive_join failed to sync. Both carried the same three faults.
+//
+//   1. Both printed the literal string "<relay-http>/health" -- a placeholder, never
+//      substituted, while the relay URL sat in scope a few lines away.
+//   2. Both named only Q430 and only limits.maxConnsTotal. limits.js:176 ALSO refuses with
+//      Q431 on a PER-ROOM cap, and the two need different fixes: HIVE_MAX_CONNS_TOTAL for the
+//      first, HIVE_SEATS for the second. An operator hitting Q431 and following that advice
+//      raises a limit that was never the constraint, sees no change, and is entitled to
+//      conclude the product is broken.
+//   3. Both told a HUMAN to go read /health. The client can read it itself, in the same
+//      breath, and say which cause it actually is.
+//
+// MEASURED, 21 Sep 2026. A third agent joined room `night` and announced that 49 files could
+// not connect, "the usual cause is the relay being full (Q430)". At that moment the relay
+// reported 56 connections of 512. limits.js keys its per-room counter on the FILE-room, and
+// each file held three connections against a cap of 64. Q430 needed 512 and had 56. Q431 needed
+// 64 and had 3. NEITHER REFUSAL COULD HAVE FIRED.
+//
+// What had actually happened: /health went rooms 44 -> 0 -> 29 -> 31 -> 44 over a few minutes.
+// The relay dropped its room state and every client began reconnecting, one socket per file.
+//
+// "The relay is full" and "the relay just dropped everyone and we are all reconnecting" produce
+// an IDENTICAL local symptom -- N file docs with synced=false -- and need opposite responses: a
+// config change, or thirty seconds of patience. The difference is a number only the relay has.
+// So ask it.
+//
+// ONE PRODUCER, ON PURPOSE. learnings/repair-the-class-not-the-copy.md exists in this repo
+// because a fix landed on one instance and the class survived into two more tickets. Two
+// hand-written copies of a diagnosis is that state exactly: they had already drifted (the
+// hive-mcp.js copy listed three candidate causes, the sync.js copy asserted one). This module is
+// the only place the wording lives, and tests/relay-diagnosis-test.mjs COUNTS the producers so a
+// third copy fails a test rather than shipping.
+
+/** A free-tier per-room cap. At or below this, Q431 is the likely refusal and seats are the fix. */
+export const FREE_TIER_ROOM_CAP = 8
+
+/** Fraction of maxConnsTotal at which "the relay is effectively full" is the right reading. */
+export const NEAR_CAPACITY = 0.9
+
+/**
+ * Turn a websocket relay URL into its /health URL.
+ * Exported because a caller that cannot fetch still wants to NAME the URL correctly, which is
+ * the whole of defect (1) above.
+ */
+export function healthUrlFor(relay) {
+  const base = String(relay || '')
+    .replace(/^wss:/i, 'https:')
+    .replace(/^ws:/i, 'http:')
+    .replace(/\/+$/, '')
+  return /^https?:/i.test(base) ? `${base}/health` : null
+}
+
+/**
+ * Ask the relay for its own numbers.
+ *
+ * NEVER THROWS, AND NEVER BLOCKS FOR LONG. This runs inside a diagnostic, and a diagnostic that
+ * can hang is a diagnostic that withholds the warning it exists to deliver. The warning matters
+ * more than the detail: a failed probe still produces a message, with the failure named.
+ *
+ * `ok` means "the probe worked", NOT "the relay is healthy". Conflating those is how a monitor
+ * reports the absence of an answer as a clean bill of health.
+ */
+export async function probeRelayHealth(relay, { timeoutMs = 2500, fetchImpl } = {}) {
+  const url = healthUrlFor(relay)
+  if (!url) return { ok: false, url: null, error: 'no usable relay URL' }
+  const f = fetchImpl || (typeof fetch === 'function' ? fetch : null)
+  if (!f) return { ok: false, url, error: 'no fetch available in this runtime' }
+  try {
+    const ac = new AbortController()
+    const t = setTimeout(() => ac.abort(), timeoutMs)
+    if (t && t.unref) t.unref()
+    let res
+    try { res = await f(url, { signal: ac.signal }) } finally { clearTimeout(t) }
+    if (!res || !res.ok) return { ok: false, url, error: `HTTP ${res ? res.status : 'no response'}` }
+    const j = await res.json()
+    return { ok: true, url, health: j }
+  } catch (e) {
+    const name = e && e.name
+    const why = name === 'AbortError' ? `no response in ${timeoutMs}ms` : ((e && e.message) || 'unreachable')
+    return { ok: false, url, error: why }
+  }
+}
+
+/** The four readings this can produce. Named so a test can assert on the verdict, not the prose. */
+export const RELAY_FULL = 'RELAY_FULL'
+export const ROOM_CAP = 'ROOM_CAP'
+export const NOT_CAPACITY = 'NOT_CAPACITY'
+export const UNREACHABLE = 'UNREACHABLE'
+
+/**
+ * Decide what the numbers mean, and say it in a way an operator can act on.
+ *
+ * Returns { verdict, text }. The verdict is for tests and for callers that want to branch; the
+ * text is what a human reads. Keeping them separate is what lets the test pin the DECISION
+ * rather than the wording, so rephrasing the advice does not break the suite and changing the
+ * advice does.
+ *
+ * @param {object} probe   the result of probeRelayHealth()
+ * @param {object} opts
+ * @param {number} opts.stuck   how many files are not synced
+ * @param {string} opts.what    'files' (sync.js) or 'join' (hive-mcp.js) -- changes the lead only
+ */
+export function diagnose(probe, { stuck = 0, what = 'files' } = {}) {
+  const h = (probe && probe.ok && probe.health) || null
+  const url = (probe && probe.url) || 'the relay'
+
+  const lead = what === 'join'
+    ? 'The relay did not sync this folder.'
+    : `${stuck} file(s) are not synced and will READ AS EMPTY until this clears.`
+
+  if (!h) {
+    // A probe that failed is MORE specific than any guess, not less: the relay is unreachable
+    // over HTTP from this machine, so capacity is not the question and no limit needs changing.
+    return {
+      verdict: UNREACHABLE,
+      text: [
+        lead,
+        `I could not reach ${url}${probe && probe.error ? ` (${probe.error})` : ''}, so the relay may be down,`,
+        `restarting, or blocked from this machine. THAT IS NOT A CAPACITY PROBLEM and no limit needs raising.`,
+        `Check that the relay is running and that this host can reach it.`,
+      ].join(' '),
+    }
+  }
+
+  const total = Number(h.limits && h.limits.maxConnsTotal) || 0
+  const conns = Number(h.connections) || 0
+  const perRoom = Number(h.connsPerRoom) || Number(h.limits && h.limits.maxConnsPerRoom) || 0
+  const seats = h.seats ? ` (${h.seats} seats)` : ''
+  const facts = `I asked ${url}: ${conns} of ${total} connections in use, ${h.rooms || 0} rooms, per-room cap ${perRoom}${seats}.`
+
+  if (total && conns >= total * NEAR_CAPACITY) {
+    return {
+      verdict: RELAY_FULL,
+      text: [lead, facts,
+        `THE RELAY IS AT OR NEAR CAPACITY — this is Q430. Hivecode opens one socket PER FILE, so a`,
+        `single large folder can exhaust it alone. Raise HIVE_MAX_CONNS_TOTAL on the relay, or narrow`,
+        `what syncs.`].join(' '),
+    }
+  }
+
+  if (perRoom && perRoom <= FREE_TIER_ROOM_CAP) {
+    // The case the old message could not express at all, and the one where its advice was
+    // actively harmful: total headroom is fine, so raising the total changes nothing.
+    return {
+      verdict: ROOM_CAP,
+      text: [lead, facts,
+        `The relay has total headroom, but its PER-ROOM cap is ${perRoom} and it refuses past that with Q431.`,
+        `That is a free-tier default. Set HIVE_SEATS on the relay — raising HIVE_MAX_CONNS_TOTAL will NOT help,`,
+        `because the total is not the constraint.`].join(' '),
+    }
+  }
+
+  return {
+    verdict: NOT_CAPACITY,
+    text: [lead, facts,
+      `CAPACITY IS NOT THE CAUSE: ${Math.max(0, total - conns)} of ${total} connections are free and the per-room`,
+      `cap is ${perRoom}. These sockets are most likely still reconnecting — the relay drops room state on`,
+      `restart and every file reconnects separately, which looks exactly like this for a minute or two.`,
+      `Wait and re-check before changing any limit. If it persists, the room may be secured and this client`,
+      `may carry no token, or the relay may be failing its licence check closed.`].join(' '),
+  }
+}
+
+/**
+ * The whole diagnosis in one call, for the two callers that want it.
+ * `trailer` is appended verbatim -- sync.js needs "do not trust this folder's contents", a
+ * failed join needs its own instructions, and neither belongs in the capacity reasoning.
+ */
+export async function explainNotSyncing(relay, { stuck = 0, what = 'files', trailer = '', timeoutMs = 2500, fetchImpl } = {}) {
+  const probe = await probeRelayHealth(relay, { timeoutMs, fetchImpl })
+  const d = diagnose(probe, { stuck, what })
+  return { ...d, probe, text: trailer ? `${d.text} ${trailer}` : d.text }
+}
+
+/**
+ * Extract HTTP status code from a WebSocket or upgrade error, if present.
+ */
+export function statusFromError(e) {
+  if (!e) return null
+  if (typeof e === 'number') return e
+  if (e.status && typeof e.status === 'number') return e.status
+  if (e.code && typeof e.code === 'number') return e.code
+  if (e.statusCode && typeof e.statusCode === 'number') return e.statusCode
+  const m = /Unexpected server response:\s*(\d{3})/.exec((e.message || e.reason || String(e)))
+  return m ? Number(m[1]) : null
+}
+
+/**
+ * Authoritative explanations for HTTP status codes returned by the relay on connection upgrade.
+ */
+export function explainStatus(code, relay = '') {
+  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 === 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.'
+  if (c === 503) return 'the relay is not serving this connection. Either the whole relay is at capacity (Q430) or it could not check your licence and is failing closed rather than guessing. It may also be restarting -- if this lasts, contact support@getgrm.tech.'
+  if (c) return `the relay answered ${c} instead of accepting the connection. Contact support@getgrm.tech.`
+  return `the relay at ${relay || 'the relay'} cannot be reached. It may be down, asleep, or blocked by a network. Contact support@getgrm.tech if this continues.`
+}
+

package/hive-stop-hook.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * THE ANTI-IDLE GATE.
+ *
+ * A rule an agent is told to follow is advice. This is the same rule as a lock.
+ *
+ * THE PROBLEM. hive_wait exists so an agent never goes unreachable: block until someone needs
+ * you, do the work, block again. It is in the tool description and it is now in the system
+ * prompt (hive-instructions.js). Both are still instructions, and an agent that decides it is
+ * finished simply emits a final answer instead of another tool call. Its process is alive, its
+ * socket is up, and it is deaf. Everyone waiting on it waits forever, and nothing tells them.
+ *
+ * You cannot fix that with better wording, for the same reason a claim board that only warns
+ * does not stop a write: it is enforcement or it is a suggestion.
+ *
+ * WHAT THIS IS. A Claude Code `Stop` hook. Claude Code runs it when the main agent is about to
+ * end its turn. Returning {"decision":"block","reason":...} makes Claude Code refuse to stop and
+ * feed `reason` back as the next input. The agent does not get a vote. So an agent that tries to
+ * go idle while it has unread mail or unfinished accepted work is simply not allowed to.
+ *
+ * WHY IT READS DISK AND NOT THE RELAY. This runs on every turn boundary and has a hard timeout.
+ * A network round trip inside that budget would make the hook the least reliable thing in the
+ * session. It does not need one: the sync client already mirrors the room to HIVE_CHAT.md and
+ * HIVE_TASKS.md on local disk. Reading those is microseconds, works with the relay unreachable,
+ * and cannot itself desync the room because it only ever reads.
+ *
+ * IT BLOCKS ON THREE THINGS, and the middle one is the subtle one:
+ *
+ *   - unread mail addressed to you
+ *   - a question you DID read and never answered ("read" is not "answered": the cursor advances
+ *     the moment a message is handed over, so an agent can absorb a direct question mid-work and
+ *     end its turn having left someone hanging, with nothing unread to block on)
+ *   - an accepted task still open
+ *
+ * FOUR GUARDS AGAINST TRAPPING THE AGENT IN A LOOP. A hook that blocks forever is worse than
+ * no hook -- it burns the user's tokens and they cannot get their agent back:
+ *
+ *   1. stop_hook_active. Claude Code sets this when the stop it is asking about is ALREADY the
+ *      result of a previous block. We always allow then, so a block is never immediately
+ *      re-applied on top of itself.
+ *   2. The watermark advances even when we block. A given message can cause exactly one block,
+ *      ever. If the agent ignores it, that is the human's problem to see, not ours to enforce.
+ *   3. `nudged` -- the same one-block-per-message rule extended across BOTH reasons, so a
+ *      message cannot charge once as unread mail and again as an unanswered question. Keyed on
+ *      sender+timestamp, so a genuinely new question still gets its own single nudge.
+ *   4. MAX_TASK_BLOCKS. Unlike a message, an open task stays open, so it would re-block on every
+ *      turn until completed -- including when it CANNOT be completed. After a few consecutive
+ *      task-only blocks we stand down and let the agent stop.
+ *
+ * Any failure at all -- no session, unreadable file, malformed JSON, unexpected shape -- exits 0
+ * and allows the stop. The hook may make an agent more reliable; it must never make a session
+ * unusable.
+ *
+ * Install with:  npx hivecode-hook install
+ */
+import fs from 'fs'
+import path from 'path'
+import { mentionsName, unansweredFor } from './hive-mailbox.js'
+
+// Consecutive turns we will block purely because a task is still open, before standing down.
+// Messages are not subject to this: the watermark already makes each one block at most once.
+const MAX_TASK_BLOCKS = 3
+
+const SESSION_FILE = '.hive-mcp-session.json'  // written by hive-mcp.js on join
+const STATE_FILE = '.hive-stop-hook.json'      // ours: watermark, task blocks, questions already nudged
+
+// A chat line: "- 19:07:27  Eve (ai): text". Anything else is a continuation of the message
+// above it (messages may contain newlines) or a header comment.
+const CHAT_LINE = /^- (\d{2}:\d{2}:\d{2})\s+(.+?) \((human|ai|system)\): ([\s\S]*)$/
+// A task line: "- [accepted] tmtofacav4mf  Ganesh -> PM: do the thing  (by Ganesh)"
+const TASK_LINE = /^- \[(\w+)\]\s+(\S+)\s+(.+?) -> (.+?): ([\s\S]*)$/
+
+const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')) } catch { return null } }
+
+/** Fold continuation lines into their message so a multi-line post counts once. */
+export function parseChat(src) {
+  const out = []
+  for (const line of String(src || '').split(/\r?\n/)) {
+    const m = CHAT_LINE.exec(line)
+    if (m) out.push({ at: m[1], by: m[2], kind: m[3], text: m[4] })
+    else if (out.length && line.trim() && !line.startsWith('#')) out[out.length - 1].text += '\n' + line
+  }
+  return out
+}
+
+/** Accepted tasks pointed at `me` that nobody has marked done. */
+export function openTasksFor(src, me) {
+  const out = []
+  for (const line of String(src || '').split(/\r?\n/)) {
+    const m = TASK_LINE.exec(line)
+    // `done` and `completed` both appear in the wild depending on how the task was closed;
+    // anything that is not explicitly accepted-and-open is not work we should block on.
+    if (m && m[1] === 'accepted' && m[4].trim().toLowerCase() === String(me).toLowerCase()) {
+      out.push({ id: m[2], from: m[3], text: m[5] })
+    }
+  }
+  return out
+}
+
+/**
+ * The whole decision, as a pure function of what is on disk, so the test can drive it without a
+ * Claude Code session, a relay, or a room.
+ *
+ * Returns { block: boolean, reason?: string, seen: number, taskBlocks: number }.
+ */
+export function decide({ chat, tasks, me, seen, taskBlocks, nudged = [] }) {
+  const msgs = parseChat(chat)
+  const nowSeen = msgs.length
+  // A cursor past the end means this is a different (rebuilt or switched) room -- start over
+  // rather than treating the whole history as unread and blocking on all of it.
+  const from = seen > nowSeen ? 0 : seen
+  const fresh = msgs.slice(from)
+
+  const mail = fresh.filter((m) =>
+    m.kind !== 'system' &&
+    String(m.by).toLowerCase() !== String(me).toLowerCase() &&  // never block on our own post
+    mentionsName(m.text, me))
+
+  if (mail.length) {
+    const quoted = mail.slice(0, 5).map((m) => `  ${m.by}: ${m.text.replace(/\s+/g, ' ').slice(0, 220)}`)
+    const more = mail.length > 5 ? `\n  ... and ${mail.length - 5} more` : ''
+    return {
+      block: true, seen: nowSeen, taskBlocks: 0,
+      // Blocking here also spends this message's ONE nudge, so the debt branch below cannot
+      // charge for the same message a second time. One block per message, whatever the reason.
+      nudged: [...nudged, ...mail.map((m) => m.by + '|' + m.at)].slice(-200),
+      reason: `You are in a Hivecode room and ${mail.length} message${mail.length > 1 ? 's' : ''} ` +
+        `addressed to you arrived while you were working:\n\n${quoted.join('\n')}${more}\n\n` +
+        `Do not stop -- they are waiting on a reply from you. Answer with hive_say (put @Name on ` +
+        `it), then go back to hive_wait. hive_wait is your idle state; ending your turn makes you ` +
+        `unreachable and nobody in the room finds out.`,
+    }
+  }
+
+  // A DEBT IS NOT THE SAME AS UNREAD MAIL, and this is the gap the watermark alone leaves. The
+  // cursor advances the instant a message is handed over, so an agent can read a direct
+  // question, get absorbed in the work, and end its turn having left someone hanging -- with
+  // nothing unread and nothing to block on. The person waiting has no way to find that out.
+  //
+  // ONE NUDGE PER QUESTION, EVER -- the same rule mail already follows, and it has to be the
+  // same rule. A debt survives until it is answered, so anything weaker than remembering which
+  // ones we already raised means the identical question blocks turn after turn, and a gate that
+  // nags is a gate the user switches off. Keyed on sender+timestamp rather than on sender, so a
+  // NEW question from someone we have already nudged about still gets its own one nudge.
+  const owed = unansweredFor(msgs, me)
+  const unnudged = owed.filter((o) => !nudged.includes(o.from + '|' + o.at))
+  if (unnudged.length) {
+    const quoted = unnudged.slice(0, 3).map((o) => `  ${o.from}: ${o.text.replace(/\s+/g, ' ').slice(0, 200)}`)
+    return {
+      block: true, seen: nowSeen, taskBlocks,
+      // Recorded BEFORE returning, exactly as the watermark is, so a question cannot block a
+      // second time even if whatever happens next goes wrong. Capped so the state file cannot
+      // grow without bound in a long-lived room.
+      nudged: [...nudged, ...unnudged.map((o) => o.from + '|' + o.at)].slice(-200),
+      reason: `You are in a Hivecode room and ${unnudged.length} participant${unnudged.length > 1 ? 's are' : ' is'} ` +
+        `still waiting on a reply from you:\n\n${quoted.join('\n')}\n\n` +
+        `Answer with hive_say and name them. "Not yet — I am on X, I will come back to you" is a ` +
+        `complete answer; silence is the one thing they cannot act on, and nothing tells them you ` +
+        `stopped. Then call hive_wait.`,
+    }
+  }
+
+  const open = openTasksFor(tasks, me)
+  if (open.length && taskBlocks < MAX_TASK_BLOCKS) {
+    const quoted = open.slice(0, 3).map((t) => `  [${t.id}] from ${t.from}: ${t.text.replace(/\s+/g, ' ').slice(0, 220)}`)
+    return {
+      block: true, seen: nowSeen, taskBlocks: taskBlocks + 1, nudged,
+      reason: `You are in a Hivecode room with ${open.length} accepted task${open.length > 1 ? 's' : ''} ` +
+        `still open:\n\n${quoted.join('\n')}\n\n` +
+        `Finish the work and call hive_complete with the task id, or say why you are blocked with ` +
+        `hive_say (@ the person who assigned it). Then call hive_wait. If you genuinely cannot ` +
+        `proceed, say so in the room first -- do not just stop, nobody would learn that you had.`,
+    }
+  }
+
+  // Standing down on something we have already blocked on MAX_TASK_BLOCKS times is not the same
+  // as it being resolved, so hold the counter rather than resetting it while it is still there.
+  // Debts and tasks share the counter deliberately: they are the same kind of obligation, and
+  // two separate counters would let an agent be pinned for 2x MAX_TASK_BLOCKS turns.
+  return { block: false, seen: nowSeen, taskBlocks: open.length ? taskBlocks : 0, nudged }
+}
+
+/** Walk up from `start` looking for the session file; the hook's cwd is usually but not always
+ *  the folder the MCP server was launched in. */
+function findSession(start) {
+  let dir = path.resolve(start)
+  for (let i = 0; i < 4; i++) {
+    const p = path.join(dir, SESSION_FILE)
+    if (fs.existsSync(p)) return { root: dir, session: readJson(p) }
+    const up = path.dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+  return null
+}
+
+async function main() {
+  let input = ''
+  for await (const chunk of process.stdin) input += chunk
+  const hook = (() => { try { return JSON.parse(input) } catch { return {} } })()
+
+  // GUARD 1: this stop is already the product of a block. Never stack another on it.
+  if (hook.stop_hook_active) return
+
+  const found = findSession(hook.cwd || process.cwd())
+  if (!found || !found.session || !found.session.dir || !found.session.name) return // not in a room
+
+  const { root, session } = found
+  const dir = path.isAbsolute(session.dir) ? session.dir : path.join(root, session.dir)
+  const read = (f) => { try { return fs.readFileSync(path.join(dir, f), 'utf8') } catch { return '' } }
+
+  const chat = read('HIVE_CHAT.md')
+  if (!chat) return // room folder not mirrored yet; nothing to be sure about, so allow
+
+  const statePath = path.join(root, STATE_FILE)
+  const prev = readJson(statePath) || {}
+  // Keyed by room: a folder rejoined against a different room must not inherit a watermark from
+  // unrelated history -- the same reasoning as the persisted sync ancestor being room-keyed.
+  const key = String(session.room || session.dir)
+  const st = prev[key] || { seen: 0, taskBlocks: 0, nudged: [] }
+
+  const d = decide({
+    chat, tasks: read('HIVE_TASKS.md'), me: session.name,
+    seen: Number(st.seen) || 0, taskBlocks: Number(st.taskBlocks) || 0,
+    nudged: Array.isArray(st.nudged) ? st.nudged : [],
+  })
+
+  // GUARD 2: write the watermark BEFORE returning the block, so this message can never block a
+  // second time even if what happens next goes wrong.
+  try {
+    prev[key] = { seen: d.seen, taskBlocks: d.taskBlocks, nudged: d.nudged || [], at: Date.now() }
+    fs.writeFileSync(statePath, JSON.stringify(prev, null, 2))
+  } catch { /* a watermark we cannot persist is a reason to allow, never to fail */ }
+
+  if (d.block) process.stdout.write(JSON.stringify({ decision: 'block', reason: d.reason }))
+}
+
+// Only run when executed as the hook, so the test can import decide()/parseChat() cleanly.
+if (process.argv[1] && /hive-stop-hook\.js$/.test(process.argv[1])) {
+  main().catch(() => { }).finally(() => process.exit(0))
+}

package/hive-throttle.js

@@ -0,0 +1,118 @@
+// hive-throttle.js — say it again only if they can no longer see it.
+//
+// TWO OPPOSITE WASTES, ONE CAUSE. Hivecode repeats some blocks to an agent that still has them
+// verbatim, and never repeats others to an agent that lost them hours ago. Both are the same
+// missing question: *is this still in their context?*
+//
+//   [GLOBAL PROJECT STATE]   rebuilt and returned on EVERY hive_wait, unchanged, forever.
+//                            An agent waiting in a loop is handed the same JSON hundreds of
+//                            times, and pays for it hundreds of times.
+//
+//   HIVE_RULES.md            6,288 bytes handed over ONCE, in the hive_join tool result. It sits
+//                            in the transcript, so it is exactly what compaction throws away
+//                            first -- and it is the ROOM-specific half of the rules: lanes, gate
+//                            commands, who owns what. Six hours in, it is simply gone.
+//
+// WHAT IS *NOT* IN SCOPE, AND THIS WAS WORTH CHECKING BEFORE WRITING ANYTHING. `INSTRUCTIONS`
+// (2,477 chars) is passed to `new Server(..., { instructions })`, which puts it in the agent's
+// SYSTEM PROMPT. A system prompt is not part of the compactable transcript, so those rules are
+// present on every single turn and re-sending them would be the precise waste this file exists
+// to remove. Half of an earlier draft of this module did exactly that.
+//
+// THE PROXY, AND ITS HONEST LIMIT. There is no way to ask an agent what is still in its context.
+// Agent Relay's broker faces the same wall and answers it with a measurement it *does* have --
+// bytes of PTY output since the last reminder:
+//
+//     "Output volume is the proxy for 'the agent actually worked and may have compacted the
+//      earlier reminder out of its context'. An agent that only sat at the prompt receiving
+//      messages still has the previous reminder verbatim in context, so repeating it only
+//      burns tokens."                     -- crates/broker/src/broker/injection_format.rs
+//
+// There is no PTY here. The equivalent measurement is the one thing this server controls exactly:
+// BYTES IT HAS HANDED THE AGENT since the last send. Every tool result goes out through one
+// `text()`, so the count is precise rather than sampled.
+//
+// This is a proxy and nothing more. It does not detect compaction; it estimates that enough has
+// happened for compaction to be plausible. It will sometimes repeat something still in context,
+// and sometimes stay quiet about something already gone. Both failures are cheap. Pretending the
+// number means more than it does would not be.
+//
+// THREE RULES, IN PRIORITY ORDER, AND THE ORDER IS THE DESIGN:
+//
+//   1. never sent      -> SEND. They have not seen it.
+//   2. content changed -> SEND. Correctness outranks economy: a suppressed state change is a
+//                         wrong answer, while a repeated one is only a cost.
+//   3. otherwise       -> send only if BOTH the cooldown has elapsed AND enough bytes have gone
+//                         out. Either gate alone is wrong. Time alone nags an idle agent that
+//                         still has the text. Bytes alone fires mid-burst on an agent that read
+//                         it ninety seconds ago.
+
+/** Long enough that a burst of work does not trigger a repeat, short enough to catch a stall. */
+export const COOLDOWN_MS = 5 * 60000
+
+/** Agent Relay's number, and a reasonable one: ~16k tokens of traffic since they last saw it. */
+export const OUTPUT_BYTES = 64 * 1024
+
+/** Cheap, order-insensitive change detection. Not a hash -- a hash would be more code for a
+ *  comparison that is already exact on the strings these callers pass. */
+const norm = (c) => (typeof c === 'string' ? c : JSON.stringify(c === undefined ? null : c))
+
+export function makeThrottle({ now = Date.now, cooldownMs = COOLDOWN_MS, bytes = OUTPUT_BYTES } = {}) {
+  // key -> { at, content, bytesSince, sends }
+  const seen = new Map()
+  let noted = 0        // total bytes handed to the agent, for reporting only
+
+  /**
+   * Record output handed to the agent.
+   *
+   * Counting for a key starts only once that key has been sent at least once -- the volume only
+   * means anything relative to "since you last saw this". Agent Relay makes the same choice and
+   * for the same reason; a counter running before the first send would make the first repeat fire
+   * immediately on a busy agent.
+   */
+  function note(n) {
+    const add = Math.max(0, Number(n) || 0)
+    noted += add
+    for (const e of seen.values()) e.bytesSince += add
+  }
+
+  function should(key, content) {
+    const e = seen.get(key)
+    if (!e) return { send: true, why: 'first' }
+    if (norm(content) !== e.content) return { send: true, why: 'changed' }
+    const waited = now() - e.at
+    if (waited < cooldownMs) return { send: false, why: 'recent', waited }
+    if (e.bytesSince < bytes) return { send: false, why: 'quiet', bytesSince: e.bytesSince }
+    return { send: true, why: 'likely-compacted', waited, bytesSince: e.bytesSince }
+  }
+
+  function sent(key, content) {
+    const prev = seen.get(key)
+    seen.set(key, { at: now(), content: norm(content), bytesSince: 0, sends: (prev ? prev.sends : 0) + 1 })
+  }
+
+  /** should() and sent() in one call, for the common site: `if (send(k, c)) include(c)`. */
+  function send(key, content) {
+    const d = should(key, content)
+    if (d.send) sent(key, content)
+    return d.send
+  }
+
+  /** What was actually saved, so the claim is measured rather than asserted. */
+  function stats() {
+    const out = { keys: {}, bytesHandled: noted }
+    for (const [k, e] of seen.entries()) out.keys[k] = { sends: e.sends, bytesSince: e.bytesSince }
+    return out
+  }
+
+  return { note, should, sent, send, stats }
+}
+
+/** Cheap enough to be worth repeating; says nothing an agent's system prompt already carries.
+ *  Deliberately a POINTER, not a copy: the file is on the agent's own disk, and a second
+ *  hand-written summary of it here would be one more description to drift. */
+export const RULES_NUDGE =
+  '[ROOM RULES] You have been working a while — the room rules you were handed when you joined ' +
+  'are probably out of your context by now. They are ROOM-specific (lanes, gate command, who ' +
+  'owns what), so the general rules you still have do not cover them. Re-read HIVE_RULES.md in ' +
+  'your own folder before your next claim.'

package/hive-version.js

@@ -0,0 +1,59 @@
+// hive-version.js — one place that knows what build this is.
+//
+// WHY THIS FILE EXISTS, and it is not tidiness.
+//
+// VERSION is load-bearing, not cosmetic. hive_join instructs every arriving agent to announce its
+// version in chat, because two clients running different builds in one room corrupt each other's
+// files with no error on either side — both writes succeed, both are green, and the disagreement
+// surfaces only as lost bytes. That announcement is the ONLY channel that makes a mixed build
+// visible from inside the room. So a version string is not a label; it is the input to the one
+// detector we have.
+//
+// On 20 Sep 2026 three entry points were found reporting a version package.json does not contain:
+// remote-mcp.js said '0.11.5' while live on the hosted relay, hive-mcp-http.js and hive-linear.js
+// both said '1.0.0'. hive-mcp.js had already been fixed months earlier, with a comment explaining
+// exactly why hardcoding it is dangerous — and that fix was never carried to the other three.
+// A detector that lies is strictly worse than no detector, because it is trusted.
+//
+// HIV-P7 closed that by giving each of the four files its own runtime read. Which produced the
+// next defect, and it was measured rather than predicted: with the reader duplicated four times,
+// corrupting ONE copy's fallback string to '9.9.9-DRIFTED' left tests/version-truth-test.mjs at
+// 16 passed, 0 failed. The property guards the version that gets REPORTED and says nothing about
+// the mechanism that produces it, so three of four copies could rot in silence.
+//
+// This codebase has watched that happen before. The extension's reconcile() and the engine's were
+// the same function once; they now share 34 lines and behave differently. Eight lines is not too
+// small to drift — it is exactly small enough that nobody feels the need to check.
+//
+// So the fix is DELETION, not another assertion. One definition, imported by all four. The
+// property becomes true by construction instead of by policing, and a fifth entry point written
+// next year gets it right by importing rather than by remembering.
+//
+// TWO DECISIONS WORTH KEEPING:
+//
+// It READS package.json rather than being told. package.json always ships beside these files —
+// in the repo and in the published tarball — so `new URL('./package.json', import.meta.url)`
+// resolves in both. Anything else (a constant, a build step, a generated file) can disagree with
+// the package the moment `npm version` runs, which is precisely the failure being fixed.
+//
+// IT NEVER THROWS. A version read is not worth a server that will not boot, and a server that
+// refuses to start is a worse outcome than one that says it does not know which build it is. So
+// an unreadable or malformed package.json yields '0.0.0-unknown' — a value that is obviously
+// wrong to a human, will never match a real release, and cannot be mistaken for a true answer.
+// Silence or an empty string could be read as "no mixed build here"; this cannot.
+
+import fs from 'fs'
+
+/** Recomputed never: a running process cannot change which build it is. */
+export const VERSION = (() => {
+  try {
+    const v = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version
+    if (typeof v === 'string' && v) return v
+  } catch { /* fall through — see IT NEVER THROWS above */ }
+  return '0.0.0-unknown'
+})()
+
+/** The sentinel, exported so callers and tests can name it instead of retyping the literal. */
+export const UNKNOWN_VERSION = '0.0.0-unknown'
+
+export default VERSION

package/lang-js.js

@@ -128,11 +128,20 @@ function bareName(node) {
 function declaredNames(src) {
   const s = new Set()
   for (const node of parse(src).body) {
-    const nm = bareName(node); if (nm) s.add(nm)
-    // Import locals count as declared names too — so if an import is ever dropped and its
+    let n = node
+    if (n.type === 'ExportNamedDeclaration' && n.declaration) n = n.declaration
+    if (n.type === 'VariableDeclaration') {
+      for (const d of n.declarations) bindingNames(d.id, s)
+    } else {
+      const nm = bareName(node); if (nm) s.add(nm)
+    }
+    // Import locals count as declared names too — so if an import is ever dropped and its
     // binding is still used, the dangling-reference check catches it (safety net for the
     // import merge). Keeps the never-emit-broken-code guarantee honest for imports.
     if (node.type === 'ImportDeclaration') for (const sp of node.specifiers) s.add(sp.local.name)
+    if (node.type === 'ExportNamedDeclaration' && !node.declaration && node.specifiers) {
+      for (const sp of node.specifiers) s.add(sp.exported.name || sp.exported.value || sp.local.name)
+    }
   }
   return s
 }