hivecode-mcp 0.11.6 → 0.12.0

package/hive-pr-staleness.js

@@ -0,0 +1,189 @@
+// hive-pr-staleness.js — do not write a file over a branch change you cannot account for.
+//
+// THE INCIDENT, MEASURED 19 Sep 2026. hive-pr generated a PR that looked perfect: three commits,
+// one per agent, each agent as the real git author, signed ids in `Hivecode-Author:` trailers,
+// files with no verified receipt refused rather than committed. A reviewer would have had every
+// reason to trust it.
+//
+// Diffed against the branch it was cut from:
+//
+//     hive-linear.js               -77
+//     tests/hive-linear-test.mjs  -114
+//     tests/hive-mcp-http-test.mjs -49
+//     tests/hive-governor-test.mjs -32
+//     sync.js                      -39
+//
+// It deleted the HIV-27 claim guard, deleted the HIV-14 truncation fix, deleted ~200 lines of
+// tests, and restored the 10x dashboard bug -- the one where thirty minutes of runtime displays
+// as 3.0. Filed HIV-28.
+//
+// THE CAUSE IS ONE LINE. hive-pr.js did `fs.copyFileSync(f.abs, dest)` and then `git add`. It
+// treats the room as truth and writes it over the branch. Grepping that file for `ahead`,
+// `behind`, `stale`, `diverged`, `merge-base` or `rev-list` returned nothing: it never asked
+// whether the branch had moved.
+//
+// This is not an exotic case, it is the NORMAL one. Any commit reaching the branch by another
+// route puts it ahead -- a hotfix, a second developer, CI, or a human doing exactly the
+// review-then-push workflow this tool exists to serve. In the measured incident the other route
+// was me, working in the git checkout instead of my room folder.
+//
+// WHY "AHEAD/BEHIND" IS THE WRONG QUESTION. There is no merge-base between a Yjs room and a git
+// branch; they are not two git histories. `git rev-list --count` cannot answer this, and reaching
+// for it would produce a check that looks rigorous and measures nothing.
+//
+// THE QUESTION THAT IS ANSWERABLE, per file:
+//
+//               has the room ever SEEN what is currently on the branch?
+//
+// It can be answered exactly, from state that already exists. Every landed change appends a
+// receipt carrying `parent` (the contentHash the author built on) and `contentHash` (the result),
+// so a file's ledger IS a hash chain of every state the room has passed through. `provenanceOf()`
+// already returns it -- hive-pr reads it for attribution and then ignores it for safety.
+//
+// If the branch's current bytes hash to something in that chain, the room descends from the
+// branch and writing is continuing the line. If they do not, the branch holds a change the room
+// has never seen, and writing would delete it. That is the whole check.
+
+import { contentHash } from './substrate.js'
+
+/** Nothing to write: the branch already holds exactly this. */
+export const IDENTICAL = 'IDENTICAL'
+/** The file is not on the branch at all, so there is nothing to revert. */
+export const NEW = 'NEW'
+/** The branch's bytes are in the room's chain: the room descends from them. Safe. */
+export const DESCENDS = 'DESCENDS'
+/** The branch holds bytes the room has never seen. REFUSE. */
+export const DIVERGED = 'DIVERGED'
+/** The room has no chain for this file, so nothing can be proved either way. REFUSE. */
+export const UNPROVEN = 'UNPROVEN'
+
+/** The only two states that may be written. A list, so widening it is a visible edit. */
+export const WRITABLE = [NEW, DESCENDS]
+
+/**
+ * LINE ENDINGS ARE PRESENTATION, AND ON THIS REPO THEY DIFFER BY DEFAULT.
+ *
+ * Measured here: `hive-mcp.js` and `sync.js` are CRLF in the working tree and LF in the blob,
+ * because `core.autocrlf` is true. So the bytes git stored and the bytes the room holds are not
+ * equal for most files in this project, while the file is by any useful definition the same file.
+ *
+ * A byte comparison would therefore mark nearly everything DIVERGED and refuse every run. That is
+ * worse than no check: a guard that fires on the HEALTHY path is the one that gets a `--force`
+ * alias in somebody's shell history within a week, and then it is not a guard at all.
+ *
+ * So both the equality test and the chain lookup are done modulo line endings. Three variants, not
+ * a normalisation, because the chain's hashes were computed by substrate.js over whatever text the
+ * room actually held at the time -- there is no single canonical form to normalise TO.
+ */
+const variants = (t) => {
+  const lf = String(t).replace(/\r\n/g, '\n')
+  return [String(t), lf, lf.replace(/\n/g, '\r\n')]
+}
+
+/** Same file, ignoring how the lines end. */
+export const sameText = (a, b) =>
+  a != null && b != null && String(a).replace(/\r\n/g, '\n') === String(b).replace(/\r\n/g, '\n')
+
+/**
+ * Every content state this file has passed through in the room.
+ *
+ * Both fields go in. `parent` is the state an author BUILT ON -- which may be a state no receipt
+ * ever produced, because the first write's parent is the hash of the empty string and a rejoin
+ * can land on a state whose own receipt lives on another peer. Taking only `contentHash` would
+ * miss exactly those, and each miss reads as DIVERGED: a refusal on a healthy file, which is the
+ * failure mode that gets a safety check disabled.
+ */
+export function chainOf(receipts) {
+  const seen = new Set()
+  for (const r of receipts || []) {
+    if (!r) continue
+    if (r.parent) seen.add(r.parent)
+    if (r.contentHash) seen.add(r.contentHash)
+  }
+  return seen
+}
+
+/**
+ * Decide whether the room's copy may be written over the branch's.
+ *
+ * `branchText` is null when the path does not exist on the branch. It must be the RAW blob --
+ * read with `git cat-file blob`, never `git show` through a working tree, or a checkout with
+ * `core.autocrlf` hands back bytes git never stored and every hash misses.
+ */
+export function accountFor({ rel, branchText, roomText, receipts }) {
+  if (branchText == null) return { rel, state: NEW, why: 'not on the branch yet — nothing can be reverted' }
+  // Modulo line endings on purpose. A file that differs ONLY in how its lines end must not be
+  // rewritten: it would produce a diff of every line in the file, for no change anybody made.
+  if (sameText(branchText, roomText)) return { rel, state: IDENTICAL, why: 'the branch already holds this (line endings aside)' }
+
+  const chain = chainOf(receipts)
+  if (!chain.size) {
+    return {
+      rel, state: UNPROVEN,
+      why: 'the room has no provenance chain for this file, so there is no way to tell whether its copy is newer than the branch or older',
+    }
+  }
+
+  const hashes = variants(branchText).map(contentHash)
+  if (hashes.some((h) => chain.has(h))) {
+    return { rel, state: DESCENDS, why: 'the room has passed through the branch\'s current content, so its copy is a descendant' }
+  }
+  return {
+    rel, state: DIVERGED, branchHash: hashes[0],
+    why: 'the branch holds content this room has never seen — writing the room\'s copy would delete it',
+  }
+}
+
+/** May this decision be written? Never inline `state !== DIVERGED` — that admits UNPROVEN. */
+export const writable = (d) => WRITABLE.includes(d.state)
+
+/**
+ * The run-level verdict.
+ *
+ * ALL OR NOTHING, and that is the design. Committing the safe files and skipping the rest produces
+ * a PR that looks complete and is not -- the same false success the tool already produced once,
+ * one level up. A refusal a human can read beats a branch they have to audit.
+ */
+export function verdict(decisions) {
+  const blocked = decisions.filter((d) => !writable(d) && d.state !== IDENTICAL)
+  return {
+    ok: blocked.length === 0,
+    blocked,
+    writable: decisions.filter(writable),
+    identical: decisions.filter((d) => d.state === IDENTICAL),
+  }
+}
+
+/**
+ * What the operator reads. `lastTouch` is supplied by the caller (hive-pr runs the git command)
+ * so this module stays pure and testable without a repository.
+ *
+ * It names the commit and the person, because "diverged" alone sends someone to `git log` to work
+ * out whether this is their own forgotten hotfix or somebody else's live work -- and that lookup
+ * is the moment a tired operator reaches for --force.
+ */
+export function explain(blocked, lastTouch = () => '') {
+  // Q506, the next free code in hive-pr's own Q500-Q505 block. Q443 would have read naturally
+  // here -- it is the other "you are being handed an incomplete picture" refusal -- and it is
+  // already the Linear truncation code. Two meanings behind one code is the duplicated-wire
+  // -contract defect wearing a three-digit hat.
+  const lines = ['Q506 REFUSING TO WRITE — the branch has moved under these files:', '']
+  for (const d of blocked) {
+    const touch = lastTouch(d.rel)
+    lines.push(`  ${d.rel}`)
+    lines.push(`      ${d.why}`)
+    if (touch) lines.push(`      last changed on the branch by: ${touch}`)
+  }
+  lines.push('')
+  lines.push('Nothing was written and no branch was created. Writing the room\'s copy over these')
+  lines.push('would silently revert whatever reached the branch another way — a hotfix, a second')
+  lines.push('developer, CI, or your own work done outside the room. That has happened once on this')
+  lines.push('project and the resulting PR looked perfect.')
+  lines.push('')
+  lines.push('Fix it one of two ways:')
+  lines.push('  - bring the branch\'s version INTO the room (edit it there, or hive_edit it), so the')
+  lines.push('    room\'s copy descends from what is on the branch. Then run this again.')
+  lines.push('  - --force "<reason>" if you have decided the room\'s copy should win. The reason is')
+  lines.push('    recorded in the PR body, because somebody will ask.')
+  return lines.join('\n')
+}

package/hive-privacy.js

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

package/hive-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.`
+}
+