hivecode-mcp 0.11.6 → 0.12.1

package/hive-privacy.js

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

package/hive-relay-health.js

@@ -0,0 +1,225 @@
+// 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}.`
+
+  // ONE SOCKET PER PARTICIPANT has its own ceiling: the files open across every participant's
+  // shared socket (Q438). Checked first, because at that ceiling the socket count looks healthy.
+  const chanCap = Number(h.limits && h.limits.maxChannelsTotal) || 0
+  const chans = Number(h.channels) || 0
+  if (Number(h.mux) >= 1 && chanCap && chans >= chanCap * NEAR_CAPACITY) {
+    return {
+      verdict: RELAY_FULL,
+      text: [lead, `I asked ${url}: ${chans} of ${chanCap} open files in use across all participants.`,
+        `THE RELAY IS AT ITS OPEN-FILE CAPACITY — this is Q438. Raise HIVE_MAX_CHANNELS_TOTAL on the relay,`,
+        `or narrow what syncs.`].join(' '),
+    }
+  }
+
+  if (total && conns >= total * NEAR_CAPACITY) {
+    // Who spends the sockets depends on the transport. A relay offering one-socket mode charges
+    // those clients 2 each; the older transport, still spoken by the VS Code extension, the browser
+    // panel and HIVE_MUX=0, charges one PER FILE -- and that is what exhausts a relay.
+    const who = Number(h.mux) >= 1
+      ? `This relay carries each participant's files on one socket (2 sockets a participant), but clients`
+        + ` on the older transport -- the VS Code extension, the browser panel, HIVE_MUX=0 -- still open one`
+        + ` socket PER FILE, and one large folder on those can exhaust it alone.`
+      : `Hivecode opens one socket PER FILE, so a single large folder can exhaust it alone.`
+    return {
+      verdict: RELAY_FULL,
+      text: [lead, facts,
+        `THE RELAY IS AT OR NEAR CAPACITY — this is Q430.`, who,
+        `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 sockets, Q438 open files, or Q439 files held by one participant) 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.`
+}
+