hivecode-mcp 0.12.0 → 0.12.2

package/hive-mcp.js

@@ -20,12 +20,14 @@
 // it returns (read chat + board before editing, announce intent, prefer patches).
 
 import fs from 'fs'
+import os from 'os'
 import path from 'path'
 import crypto from 'crypto'
 import { fileURLToPath } from 'url'
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+// The stdio server is our own, not @modelcontextprotocol/sdk's: the SDK drags express, hono, zod
+// and ~85 more packages into every install for a slice this small. See hive-stdio.js.
+import { Server, StdioServerTransport, ListToolsRequestSchema, CallToolRequestSchema } from './hive-stdio.js'
+import { startUpdateCheck, updateNotice } from './hive-update.js'
 // Substrate defaults for MCP agents: signed provenance + the silent-fork gate are ON
 // unless explicitly disabled. Agents register this server with arbitrary (often empty)
 // env, so relying on per-registration env vars left rooms in mixed signed/unsigned mode —
@@ -34,7 +36,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 if (!process.env.HIVE_PROVENANCE) process.env.HIVE_PROVENANCE = 'on'
 if (!process.env.HIVE_FORK_GATE) process.env.HIVE_FORK_GATE = 'on'
 import { startSync, parseLink } from './sync.js'
-import { checkRelay, PUBLIC_DEFAULT_RELAY } from './hive-privacy.js'
+import { checkRelay, currentRelayFor, PUBLIC_DEFAULT_RELAY } from './hive-privacy.js'
 import { createMailbox, formatMessage, mentionsName, mentionedNames, mentionsAll, unansweredFor, priorityOf, ambientDigest, validateMemberName } from './hive-mailbox.js'
 import { INSTRUCTIONS } from './hive-instructions.js'
 import { makeBusy, isBusy, describeRecipient } from './hive-busy.js'
@@ -63,7 +65,16 @@ const text = (s) => {
 }
 const err = (s) => ({ content: [{ type: 'text', text: s }], isError: true })
 
+// Every route to a relay passes through here, so a retired public relay is followed to its
+// replacement in one place -- whether it arrived in a pasted link, a .hive.json written before
+// the move, or a HIVE_RELAY our own docs once told people to set. See currentRelayFor().
 function resolveRoom(link, dir) {
+  const r = resolveRoomRaw(link, dir)
+  const { relay, migratedFrom } = currentRelayFor(r.relay)
+  return { ...r, relay, migratedFrom }
+}
+
+function resolveRoomRaw(link, dir) {
   if (link) { const { relay, room, token } = parseLink(link); return { relay: relay || DEFAULT_RELAY, room, token, mode: 'joined (link)' } }
   const cfgPath = path.join(path.resolve(dir), '.hive.json')
   if (fs.existsSync(cfgPath)) {
@@ -105,7 +116,49 @@ async function tryResumeSession() {
   } catch { /* resume is best-effort; the agent can always hive_join explicitly */ }
 }
 
-async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor, kind = 'ai', passive = false }) {
+// WHERE AN AGENT'S FILES GO WHEN NOBODY SAID. This was './workspace', resolved against the
+// directory the agent app happened to start this server in: the user's project for Claude Code,
+// something unwritable or unguessable for others -- and the SAME folder for two agents started
+// alike, which is the one thing a room must never have (one folder per participant). Now it is
+// ~/hivecode/<room>/<name>: absolute, writable, and different for every name.
+//
+// One exception keeps returning users whole: an agent that joined the old way and now calls
+// hive_join with nothing, expecting its room back from ./workspace/.hive.json, still gets it.
+// Sending it to a new folder instead would host a brand-new room and report success -- the agent
+// would be alone, told it was joined.
+const HIVE_HOME = process.env.HIVE_HOME || path.join(os.homedir(), 'hivecode')
+const LEGACY_DIR = './workspace'
+function safeSegment(s) {
+  const t = String(s || '').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[.]+/, '_').slice(0, 64) || '_'
+  return /^(con|prn|aux|nul|com\d|lpt\d)$/i.test(t) ? '_' + t : t
+}
+function roomIn(dir) {
+  try { return JSON.parse(fs.readFileSync(path.join(path.resolve(dir), '.hive.json'), 'utf8')).room || null } catch { return null }
+}
+function defaultJoinTarget(link, name) {
+  // The folders this agent already has a room in: the one its last session used (hive_leave
+  // deletes that record, so it only survives a disconnect or a restart), then the old default.
+  const prev = readSessionFile()
+  const prevDir = prev && prev.dir && roomIn(prev.dir) ? prev.dir : null
+  const legacy = roomIn(LEGACY_DIR) ? LEGACY_DIR : null
+  if (!link) {
+    // "No link, no folder" has always meant "my room, if I have one". Hosting a new one instead
+    // would leave an agent that meant to rejoin alone in an empty room, told it had joined.
+    const back = prevDir || legacy
+    if (back) return { dir: back, link, hostedHere: false }
+    const room = 'room-' + crypto.randomBytes(13).toString('base64url')
+    return { dir: path.join(HIVE_HOME, room, safeSegment(name)), link: `${DEFAULT_RELAY}|${room}`, hostedHere: true }
+  }
+  const room = parseLink(link).room
+  if (!room) return { dir: LEGACY_DIR, link, hostedHere: false }
+  // Rejoining a room this agent was already in lands in the folder it used, files and all. The
+  // session record must be under THIS name: two runtimes started in one directory share it.
+  if (prevDir && prev.name === name && roomIn(prevDir) === room) return { dir: prevDir, link, hostedHere: false }
+  if (legacy && roomIn(legacy) === room) return { dir: legacy, link, hostedHere: false }
+  return { dir: path.join(HIVE_HOME, safeSegment(room), safeSegment(name)), link, hostedHere: false }
+}
+
+async function joinRoom({ link = '', dir = '', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor, kind = 'ai', passive = false }) {
   // REFUSED BEFORE THE OLD SESSION IS TORN DOWN. joinRoom's first act is to stop whatever session
   // exists, so validating after that point would leave an agent with a bad name holding nothing at
   // all -- it would lose a working room to a refusal it could have been given for free.
@@ -118,9 +171,12 @@ Nothing was joined and your current session is untouched. Re-run hive_join with
 This is refused rather than fixed for you because renaming silently is worse: if another member is already called "${nameCheck.suggested}", you would be merged into them -- one awareness entry, one read cursor, one mailbox -- and neither of you would be told. Your own prompt would also still say your name is "${name}", so you would stop recognising messages about yourself.`
   }
   if (session) { try { session.hive.stop() } catch {} ; session = null }
+  let hostedHere = false
+  if (!dir) ({ dir, link, hostedHere } = defaultJoinTarget(link, name))
   const ROOT = path.resolve(dir)
   fs.mkdirSync(ROOT, { recursive: true })
-  const { relay, room, token: linkToken, mode } = resolveRoom(link, dir)
+  const { relay, room, token: linkToken, mode: resolvedMode, migratedFrom } = resolveRoom(link, dir)
+  const mode = hostedHere ? 'HOSTED (new room)' : resolvedMode
   // THE PRIVACY GATE, and note where it sits: after the relay is resolved, BEFORE the
   // .hive.json write below and before startSync opens a socket. A refused join must leave
   // nothing behind -- no config pointing at the wrong relay for the next process to find,
@@ -143,7 +199,13 @@ was not written. Fix the relay and call hive_join again.`
   const useToken = token || linkToken || process.env.HIVE_TOKEN || ''
   // persist the token too, so a re-join from .hive.json keeps the grant (the
   // invitee pastes the link once; subsequent joins just read the folder config).
-  fs.writeFileSync(path.join(ROOT, '.hive.json'), JSON.stringify({ relay, room, ...(useToken ? { token: useToken } : {}) }, null, 2))
+  // pinnedRelay SURVIVES the rewrite. This line used to write only relay/room/token, so a pin
+  // kept in .hive.json -- one of the two places readPin() looks -- was erased by the very first
+  // join that honoured it. Only the pin is carried over: an old token must not follow the
+  // folder into a different room.
+  let keep = {}
+  try { const old = JSON.parse(fs.readFileSync(path.join(ROOT, '.hive.json'), 'utf8')); if (old && old.pinnedRelay) keep = { pinnedRelay: old.pinnedRelay } } catch { /* none yet */ }
+  fs.writeFileSync(path.join(ROOT, '.hive.json'), JSON.stringify({ relay, room, ...(useToken ? { token: useToken } : {}), ...keep }, null, 2))
   // The ACCOUNT licence is passed through but NOT persisted to .hive.json above, and that
   // asymmetry is deliberate. `.hive.json` sits in the project folder, so it gets committed
   // and it gets shared -- fine for a room invite, which is what it is for, and wrong for a
@@ -331,7 +393,13 @@ was not written. Fix the relay and call hive_join again.`
   // bracketed verdict is what makes "did my source just leave the building?" answerable
   // without asking, and the warning line below is what makes it actionable.
   const privNote = priv.warn ? `\n\n!! ${priv.warn}` : ''
-  return `${mode}\nroom: ${room}\nrelay: ${relay}  [${priv.headline}]\nfolder: ${ROOT}\nhivecode: ${VERSION}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${inviteLink}${privNote}\n\nANNOUNCE YOUR VERSION: say "joined on hivecode ${VERSION}" in chat. Mixed builds in one room cause data loss, and this is the only way anyone finds out.\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
+  // Said out loud, because changing where someone's files go without telling them is the thing
+  // this whole module exists to prevent -- even when the move is to where they meant to be.
+  const movedNote = migratedFrom
+    ? `\n\nMOVED: this folder pointed at ${migratedFrom}, a Hivecode relay that has been retired. ` +
+      `It now uses ${relay}, and .hive.json has been updated, so this happens once.`
+    : ''
+  return `${mode}\nroom: ${room}\nrelay: ${relay}  [${priv.headline}]\nfolder: ${ROOT}\nhivecode: ${VERSION}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${inviteLink}${movedNote}${privNote}\n\nANNOUNCE YOUR VERSION: say "joined on hivecode ${VERSION}" in chat. Mixed builds in one room cause data loss, and this is the only way anyone finds out.${updateNotice() ? '\n' + updateNotice() : ''}\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
 }
 
 function requireSession() { if (!session) throw new Error('not in a room — call hive_join first'); return session }
@@ -473,7 +541,7 @@ function waitForWork(timeoutMs, opts = {}) {
 
 const TOOLS = [
   { name: 'hive_join', description: 'Join (or host) a Hivecode room for a project folder. Joins automatically as an AI participant. If a join link is given, uses it; else reads <dir>/.hive.json; else hosts a new room. Returns the room info and the HIVE_RULES you must follow.',
-    inputSchema: { type: 'object', properties: { link: { type: 'string', description: 'optional join link "wss://relay|room"' }, dir: { type: 'string', description: 'project folder to sync (default ./workspace)' }, name: { type: 'string', description: 'your display name in the room' }, owner: { type: 'string', description: 'the human responsible for you — only they may approve tasks directed at you' }, token: { type: 'string', description: 'access token for a secured room (else uses $HIVE_TOKEN). Required only if the relay runs in auth-required mode.' }, kind: { type: 'string', description: 'participant kind (ai or human)' }, passive: { type: 'boolean', description: 'true = this participant is a passive listener or bot daemon and does not take turns or answer questions' } } } },
+    inputSchema: { type: 'object', properties: { link: { type: 'string', description: 'optional join link "wss://relay|room"' }, dir: { type: 'string', description: 'folder to sync. Leave it out and Hivecode uses ~/hivecode/<room>/<your name>, a folder of your own. Never share a folder with another participant.' }, name: { type: 'string', description: 'your display name in the room' }, owner: { type: 'string', description: 'the human responsible for you — only they may approve tasks directed at you' }, token: { type: 'string', description: 'access token for a secured room (else uses $HIVE_TOKEN). Required only if the relay runs in auth-required mode.' }, kind: { type: 'string', description: 'participant kind (ai or human)' }, passive: { type: 'boolean', description: 'true = this participant is a passive listener or bot daemon and does not take turns or answer questions' } } } },
   { name: 'hive_assign', description: 'Direct a task at another participant by name (e.g. ask another agent to work on a file). If the target is an AI with an owner, it stays PENDING until that owner approves.',
     inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'participant name to assign to' }, text: { type: 'string', description: 'what to do' } }, required: ['to', 'text'] } },
   { name: 'hive_read_tasks', description: 'Read tasks. Shows tasks directed at YOU (act only on accepted ones) and all pending tasks awaiting approval.',
@@ -1318,7 +1386,7 @@ Nothing was written. This tool exists to guarantee the change syncs to every pee
         // answer to the second -- the public relay and a company's own are the same shape.
         const pv = checkRelay({ relay: s.relay, env: process.env, dir: s.dir, fs })
         return text({
-          room: s.room, relay: s.relay, dir: s.dir, name: s.name, hivecode: VERSION,
+          room: s.room, relay: s.relay, dir: s.dir, name: s.name, hivecode: VERSION, ...(updateNotice() ? { update: updateNotice() } : {}),
           privacy: pv.headline,
           ...(pv.warn ? { privacyWarning: pv.warn } : {}),
           ...(pv.pin && pv.pin.pinned ? { relayPin: pv.pin.origins.join(', ') } : {}),
@@ -1470,10 +1538,37 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
 
 // Only claim stdio when this file IS the program. Importing it (a test, a tool) must not
 // hijack the JSON-RPC channel — that is what made the wait/mailbox logic untestable before.
-const isEntryPoint = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))
-if (isEntryPoint) {
+//
+// COMPARED AS REAL PATHS. On macOS and Linux, npx starts a package's bin through the symlink in
+// node_modules/.bin. Node resolves that symlink for import.meta.url and NOT for argv[1], so the
+// plain comparison this used to make was false there: the server never started, the process
+// exited 0 with no output, and the agent app showed nothing but "failed to start". Reproduced on
+// 25 Sep 2026 through a Windows junction, which Node treats the same way.
+function isMainModule() {
+  if (!process.argv[1]) return false
+  const me = fileURLToPath(import.meta.url)
+  try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(me) } catch { return path.resolve(process.argv[1]) === path.resolve(me) }
+}
+const isEntryPoint = isMainModule()
+if (isEntryPoint && process.argv[2] === 'setup') {
+  // `npx -y hivecode-mcp@latest setup` -- configures every agent app on this machine and checks
+  // each one starts. It never opens stdio: nobody is speaking JSON-RPC to a setup run.
+  const { main } = await import('./hive-setup.js')
+  process.exit(await main(process.argv.slice(3)))
+} else if (isEntryPoint && (process.argv[2] === '--version' || process.argv[2] === '-v')) {
+  console.log(VERSION)
+  process.exit(0)
+} else if (isEntryPoint) {
   const transport = new StdioServerTransport()
+  // STDIN CLOSING IS THE AGENT APP SAYING GOODBYE -- the MCP spec's stdio shutdown. Leave the
+  // room and exit. The SDK kept this process alive on its open sockets instead, holding a seat
+  // and a presence entry for a member that was gone, until something killed it.
+  server.onclose = () => {
+    try { if (session) session.hive.stop() } catch { /* leaving is best-effort; exiting is not */ }
+    setTimeout(() => process.exit(0), 500)
+  }
   await server.connect(transport)
+  startUpdateCheck() // background, short timeout; hive_join and hive_status show what it finds
   // stderr is fine for logs; stdout is the JSON-RPC channel and must stay clean.
   console.error('[hive-mcp] Hivecode MCP server ready (stdio). Default relay:', DEFAULT_RELAY)
 }
@@ -1481,6 +1576,7 @@ if (isEntryPoint) {
 /** Test seam: drive the real wait/delivery logic against a doc, with no relay and no stdio. */
 export const _test = {
   waitForWork,
+  defaultJoinTarget,
   mailbox,
   // Exposed so the throttle's saving is asserted against the counter itself rather than inferred
   // from what happened not to appear in a tool result. Counting absences is how you prove a thing

package/hive-mux-proto.js

@@ -0,0 +1,58 @@
+// hive-mux-proto.js -- the wire format for ONE socket per participant, shared by relay and client.
+//
+// WHY: Hivecode opened one WebSocket per FILE. A participant held 1 + min(files, 128) sockets,
+// so an agent in a 1000-file repository saw only 128 files on disk, and a relay's connection cap
+// divided by 129 per person. The mux carries every file doc of one room over one socket.
+//
+// The design rule that makes it safe: the relay does not grow a second enforcement path. Each
+// OPEN runs the SAME per-doc admission a per-file upgrade runs (token scope for that path, the
+// per-room ceiling, the committer limit), and the accepted channel is wrapped in a VirtualConn
+// that looks exactly like a ws connection to installUsageLimits, makeReadOnly, installWriteGate
+// and setupWSConnection. The bytes inside a MSG frame are the same y-protocols message a
+// per-file socket would carry.
+//
+// Frames are binary, lib0-encoded:
+//   client -> relay   OPEN     [0, id, docName]       open this file doc as channel `id`
+//                     CLOSE    [1, id]                the client is done with it
+//                     MSG      [2, id, ...payload]    a y-protocols message for that doc
+//   relay -> client   MSG      [2, id, ...payload]
+//                     OPENED   [3, id]                admitted; the relay's sync step 1 follows
+//                     REFUSED  [4, id, code, reason]  not admitted -- the HTTP status a per-file
+//                                                     upgrade would have answered, and why
+//                     CLOSED   [5, id, reason]        the relay closed that channel
+//                     BEAT     [6, 0]                 liveness, so a dead socket is noticed
+// Channel ids are chosen by the client and are only meaningful on the socket that opened them.
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+
+export const MUX_PREFIX = '_hive_mux/'
+export const MUX_VERSION = 1
+export const F = Object.freeze({ OPEN: 0, CLOSE: 1, MSG: 2, OPENED: 3, REFUSED: 4, CLOSED: 5, BEAT: 6 })
+
+export function encodeFrame(kind, id, a, b) {
+  const e = encoding.createEncoder()
+  encoding.writeVarUint(e, kind)
+  encoding.writeVarUint(e, id >>> 0)
+  if (kind === F.OPEN) encoding.writeVarString(e, String(a))
+  else if (kind === F.MSG) encoding.writeUint8Array(e, a instanceof Uint8Array ? a : new Uint8Array(a))
+  else if (kind === F.REFUSED) { encoding.writeVarUint(e, a >>> 0); encoding.writeVarString(e, String(b || '')) }
+  else if (kind === F.CLOSED) encoding.writeVarString(e, String(a || ''))
+  return encoding.toUint8Array(e)
+}
+
+/** Decode one frame. Throws on garbage, which the caller treats as a protocol violation. */
+export function decodeFrame(buf) {
+  const u8 = buf instanceof Uint8Array ? buf : new Uint8Array(buf)
+  const d = decoding.createDecoder(u8)
+  const kind = decoding.readVarUint(d)
+  const id = decoding.readVarUint(d)
+  if (kind === F.OPEN) return { kind, id, docName: decoding.readVarString(d) }
+  if (kind === F.MSG) return { kind, id, payload: u8.subarray(d.pos) }
+  if (kind === F.REFUSED) return { kind, id, code: decoding.readVarUint(d), reason: decoding.readVarString(d) }
+  if (kind === F.CLOSED) return { kind, id, reason: decoding.readVarString(d) }
+  if (kind === F.CLOSE || kind === F.OPENED || kind === F.BEAT) return { kind, id }
+  throw new Error(`unknown mux frame kind ${kind}`)
+}
+
+/** The mux upgrade path for a base room, as the relay parses it (pathname minus the slash). */
+export function muxPath(room) { return MUX_PREFIX + encodeURIComponent(room) }

package/hive-mux.js

@@ -0,0 +1,350 @@
+// hive-mux.js -- the client half of ONE socket per participant (wire format: hive-mux-proto.js).
+//
+// sync.js asks this module for a provider per file doc and gets back an object with the surface
+// it already used from y-websocket's WebsocketProvider: `synced`, the 'sync' / 'status' /
+// 'connection-error' / 'connection-close' events, and destroy(). Behind it is EITHER a channel
+// on the participant's one mux socket, or -- when the relay does not advertise mux in /health,
+// or HIVE_MUX=0 -- a plain per-file WebsocketProvider exactly as before. An old relay therefore
+// keeps working with a new client, and the choice is made once per session, before any file
+// socket exists, so a room never ends up half on one transport by accident.
+//
+// Inside a channel the y-protocols exchange is the one y-websocket performs: on admission send
+// sync step 1, answer the relay's step 1, count the session synced when step 2 arrives, forward
+// local updates, never echo an update this provider applied. A refused OPEN is reported as a
+// 'connection-error' carrying the same HTTP status a refused per-file upgrade carried, so every
+// piece of refusal reporting in sync.js (Q430/Q431 counts, notSyncing, explain()) works unchanged.
+import * as syncProtocol from 'y-protocols/sync'
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+import { ObservableV2 } from 'lib0/observable'
+import { WebsocketProvider } from 'y-websocket'
+import { F, encodeFrame, decodeFrame, muxPath, MUX_VERSION } from './hive-mux-proto.js'
+
+const messageSync = 0
+
+export const httpBase = (relay) => String(relay).replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/+$/, '')
+
+/** The provider sync.js holds per file. Delegates to a mux channel or a legacy provider. */
+class FileProvider extends ObservableV2 {
+  constructor(docName, doc) {
+    super()
+    this.docName = docName
+    this.doc = doc
+    this.destroyed = false
+    this._impl = null
+  }
+  get synced() { return !!(this._impl && this._impl.synced) }
+  get wsconnected() { return !!(this._impl && this._impl.wsconnected) }
+  get transport() { return this._impl ? this._impl.transport : 'pending' }
+  _bindLegacy(relay, wsOpts) {
+    const p = new WebsocketProvider(relay, this.docName, this.doc, wsOpts)
+    for (const ev of ['sync', 'status', 'connection-error', 'connection-close']) p.on(ev, (...args) => this.emit(ev, args))
+    this._impl = { transport: 'socket', get synced() { return p.synced }, get wsconnected() { return p.wsconnected }, destroy: () => p.destroy() }
+  }
+  destroy() {
+    if (this.destroyed) return
+    this.destroyed = true
+    try { if (this._impl) this._impl.destroy() } catch { }
+    super.destroy()
+  }
+}
+
+class Channel {
+  constructor(mux, id, docName, doc, facade) {
+    this.mux = mux
+    this.id = id
+    this.docName = docName
+    this.doc = doc
+    this.facade = facade
+    this.transport = 'mux'
+    this.opened = false
+    this.synced = false
+    this.retries = 0
+    this.retryTimer = null
+    this.destroyed = false
+    this._onUpdate = (update, origin) => {
+      if (origin === this.facade || !this.opened) return // gaps are closed by the next step1/step2
+      const e = encoding.createEncoder()
+      encoding.writeVarUint(e, messageSync)
+      syncProtocol.writeUpdate(e, update)
+      this.mux.send(encodeFrame(F.MSG, this.id, encoding.toUint8Array(e)))
+    }
+    doc.on('update', this._onUpdate)
+  }
+  get wsconnected() { return this.opened && this.mux.connected }
+  sendOpen() {
+    if (this.destroyed || !this.mux.connected) return
+    clearTimeout(this.retryTimer); this.retryTimer = null
+    this.mux.send(encodeFrame(F.OPEN, this.id, this.docName))
+  }
+  retryLater() {
+    if (this.destroyed || this.retryTimer) return
+    // Refused or closed by the relay: back off, like the per-file provider did, but further --
+    // an OPEN is cheap to send and a relay at capacity should not be asked 40 times a second.
+    const ms = Math.min(15000, 500 * 2 ** Math.min(this.retries++, 5))
+    this.retryTimer = setTimeout(() => { this.retryTimer = null; this.sendOpen() }, ms)
+    if (this.retryTimer.unref) this.retryTimer.unref()
+  }
+  onFrame(f) {
+    if (this.destroyed) return
+    if (f.kind === F.OPENED) {
+      this.opened = true
+      this.retries = 0
+      const e = encoding.createEncoder()
+      encoding.writeVarUint(e, messageSync)
+      syncProtocol.writeSyncStep1(e, this.doc)
+      this.mux.send(encodeFrame(F.MSG, this.id, encoding.toUint8Array(e)))
+      this.facade.emit('status', [{ status: 'connected' }])
+    } else if (f.kind === F.MSG) {
+      try { this.onMessage(f.payload) } catch (e) {
+        // A message this doc could not apply. Skipping it would leave a gap that every later
+        // update builds on, silently; reopening makes the relay run the sync exchange again,
+        // and that carries whatever was missed.
+        this.mux.log(`[hive] could not apply a relay message for ${JSON.stringify(this.docName)} (${e && e.message}); resyncing it`)
+        this.reopen()
+      }
+    } else if (f.kind === F.REFUSED) {
+      this.opened = false
+      this.facade.emit('connection-error', [{ code: f.code, status: f.code, reason: f.reason, message: `Unexpected server response: ${f.code} ${f.reason}` }])
+      this.retryLater()
+    } else if (f.kind === F.CLOSED) {
+      this.lost({ code: 4000, reason: f.reason })
+      this.retryLater()
+    }
+  }
+  onMessage(payload) {
+    let d
+    try { d = decoding.createDecoder(payload) } catch { return }
+    const type = decoding.readVarUint(d)
+    if (type !== messageSync) return // awareness/auth/query: file docs carry no presence
+    const e = encoding.createEncoder()
+    encoding.writeVarUint(e, messageSync)
+    const t = syncProtocol.readSyncMessage(d, e, this.doc, this.facade)
+    if (t === syncProtocol.messageYjsSyncStep2 && !this.synced) {
+      this.synced = true
+      this.facade.emit('sync', [true])
+    }
+    if (encoding.length(e) > 1) this.mux.send(encodeFrame(F.MSG, this.id, encoding.toUint8Array(e)))
+  }
+  reopen() {
+    if (this.destroyed) return
+    if (this.mux.connected) this.mux.send(encodeFrame(F.CLOSE, this.id))
+    this.lost({ code: 4001, reason: 'resync' })
+    this.retryLater()
+  }
+  /** The channel is gone (socket dropped, or the relay closed it); a reconnect will reopen it. */
+  lost(ev = null) {
+    const wasOpen = this.opened
+    this.opened = false
+    if (this.synced) { this.synced = false; this.facade.emit('sync', [false]) }
+    if (wasOpen) {
+      this.facade.emit('connection-close', [ev])
+      this.facade.emit('status', [{ status: 'disconnected' }])
+    }
+  }
+  destroy() {
+    if (this.destroyed) return
+    this.destroyed = true
+    clearTimeout(this.retryTimer)
+    try { this.doc.off('update', this._onUpdate) } catch { }
+    if (this.mux.connected) this.mux.send(encodeFrame(F.CLOSE, this.id))
+    this.mux.channels.delete(this.id)
+  }
+}
+
+/** The participant's one physical socket, carrying a channel per open file doc. */
+class MuxConnection {
+  constructor({ relay, room, params, WebSocketPolyfill, log, onRefused }) {
+    const q = new URLSearchParams({ ...(params || {}), mux: String(MUX_VERSION) })
+    this.url = `${String(relay).replace(/\/+$/, '')}/${muxPath(room)}?${q}`
+    this.WS = WebSocketPolyfill
+    this.log = log || (() => { })
+    this.onRefused = onRefused || (() => { })
+    this.channels = new Map()
+    this.nextId = 1
+    this.ws = null
+    this.connected = false
+    this.connecting = false
+    this.destroyed = false
+    this.failures = 0
+    this.lastHeard = 0
+    this.reconnectTimer = null
+    // The relay sends a BEAT every 20s; 45s of silence means the socket is dead even if the OS
+    // has not said so, which is exactly the half-open state a laptop lid produces.
+    this.liveness = setInterval(() => {
+      // terminate, not close: a close handshake cannot complete on a dead link, and ws waits 30s more for it
+      if (this.connected && Date.now() - this.lastHeard > 45000) { try { this.ws.terminate ? this.ws.terminate() : this.ws.close() } catch { } }
+    }, 5000)
+    if (this.liveness.unref) this.liveness.unref()
+  }
+  channel(docName, doc, facade) {
+    const ch = new Channel(this, this.nextId++, docName, doc, facade)
+    this.channels.set(ch.id, ch)
+    if (this.connected) ch.sendOpen()
+    else this.connect()
+    return ch
+  }
+  send(bytes) {
+    if (!this.connected || !this.ws) return
+    try { this.ws.send(bytes) } catch { /* the close handler takes it from here */ }
+  }
+  connect() {
+    if (this.destroyed || this.connected || this.connecting) return
+    this.connecting = true
+    let ws
+    try { ws = new this.WS(this.url) } catch (e) { this.connecting = false; this.scheduleReconnect(); return }
+    ws.binaryType = 'arraybuffer'
+    this.ws = ws
+    ws.onopen = () => {
+      if (this.ws !== ws) return
+      this.connecting = false
+      this.connected = true
+      this.failures = 0
+      this.lastHeard = Date.now()
+      for (const ch of this.channels.values()) ch.sendOpen()
+    }
+    ws.onmessage = (ev) => {
+      if (this.ws !== ws) return
+      this.lastHeard = Date.now()
+      let f
+      try { f = decodeFrame(new Uint8Array(ev.data)) } catch { return }
+      if (f.kind === F.BEAT) return
+      const ch = this.channels.get(f.id)
+      if (ch) ch.onFrame(f)
+    }
+    ws.onerror = (ev) => {
+      if (this.ws !== ws) return
+      // A refused UPGRADE of the mux socket itself (401/402/403/429/503) refuses every file on it.
+      // Hand each unsynced channel the same event a refused per-file socket produced.
+      const m = /Unexpected server response:\s*(\d{3})/.exec((ev && (ev.message || (ev.error && ev.error.message))) || '')
+      const code = m ? Number(m[1]) : null
+      for (const ch of this.channels.values()) {
+        if (!ch.synced) ch.facade.emit('connection-error', [{ code, status: code, message: (ev && ev.message) || 'mux socket error' }])
+      }
+      if (code) this.onRefused(code)
+    }
+    ws.onclose = (ev) => {
+      if (this.ws !== ws) return
+      this.ws = null
+      this.connected = false
+      this.connecting = false
+      for (const ch of this.channels.values()) ch.lost(ev)
+      this.scheduleReconnect()
+    }
+  }
+  scheduleReconnect() {
+    if (this.destroyed || this.reconnectTimer || !this.channels.size) return
+    const ms = Math.min(5000, 100 * 2 ** Math.min(this.failures++, 6))
+    this.reconnectTimer = setTimeout(() => { this.reconnectTimer = null; this.connect() }, ms)
+    if (this.reconnectTimer.unref) this.reconnectTimer.unref()
+  }
+  destroy() {
+    this.destroyed = true
+    clearInterval(this.liveness)
+    clearTimeout(this.reconnectTimer)
+    const ws = this.ws
+    this.ws = null
+    // Disconnected FIRST: closing the socket ends every channel on the relay at once, so no
+    // channel sends a CLOSE frame of its own down a socket that is about to go.
+    this.connected = false
+    for (const ch of [...this.channels.values()]) { try { ch.destroy() } catch { } }
+    try { if (ws) ws.close() } catch { }
+  }
+}
+
+/**
+ * One per startSync. provide(docName, doc) returns the provider for a file doc; the transport is
+ * decided once -- HIVE_MUX=1 forces mux, HIVE_MUX=0 forces a socket per file, anything else asks
+ * the relay's /health -- and file providers created before the answer are bound when it comes.
+ */
+export function createFileTransport({ relay, room, wsOpts = {}, log = () => { }, env = process.env, fetchImpl = globalThis.fetch, onFallback = () => { }, retryMs = 1000, detectForMs = 90000 }) {
+  const forced = env.HIVE_MUX === '0' || env.HIVE_MUX === '1'
+  let mode = env.HIVE_MUX === '0' ? 'socket' : env.HIVE_MUX === '1' ? 'mux' : null
+  let mux = null
+  let stopped = false
+  const pending = new Set()
+  const health = () => Promise.resolve()
+    .then(() => fetchImpl(`${httpBase(relay)}/health`, { signal: AbortSignal.timeout(20000) }))
+    .then((r) => (r && r.ok ? r.json() : null))
+  const offersMux = (j) => !!j && Number(j.mux) >= MUX_VERSION
+
+  // THE KILL SWITCH HAS TO REACH CLIENTS THAT ARE ALREADY CONNECTED. A relay that stops serving
+  // mux -- an operator setting HIVE_RELAY_MUX=off, or a rollback to a build that predates it --
+  // refuses the mux socket from then on, and without this every file would stay refused until
+  // the agent restarted. A 404 says so outright. Any other refusal is checked against /health, at
+  // most once a minute, because a relay that predates mux reads the mux path as a room name and
+  // refuses the token -- a 401 that looks exactly like a real one.
+  let lastCheck = 0
+  const onRefused = (code) => {
+    if (forced || stopped || mode !== 'mux') return
+    if (code === 404) return fallBack('the relay no longer serves one-socket mode (404)')
+    const now = Date.now()
+    if (now - lastCheck < 60000) return
+    lastCheck = now
+    health().then((j) => { if (j && !offersMux(j)) fallBack('the relay stopped offering one-socket mode') }, () => { })
+  }
+  const fallBack = (why) => {
+    if (stopped || mode !== 'mux') return
+    mode = 'socket'
+    log(`[hive] ${why}: falling back to a socket per file`)
+    // sync.js lets go of every file beyond the per-file bound FIRST. Without that, a client holding
+    // 900 files on one socket would open 900 sockets at once -- the storm the bound exists to stop.
+    try { onFallback() } catch { }
+    const moving = mux ? [...mux.channels.values()].map((ch) => ch.facade) : []
+    try { if (mux) mux.destroy() } catch { }
+    mux = null
+    for (const fp of moving) { if (!fp.destroyed) fp._bindLegacy(relay, wsOpts) }
+  }
+  const bind = (fp) => {
+    if (fp.destroyed) return
+    if (mode === 'mux') {
+      if (!mux) mux = new MuxConnection({ relay, room, params: wsOpts.params, WebSocketPolyfill: wsOpts.WebSocketPolyfill, log, onRefused })
+      fp._impl = mux.channel(fp.docName, fp.doc, fp)
+    } else {
+      fp._bindLegacy(relay, wsOpts)
+    }
+  }
+  let resolveReady
+  const ready = new Promise((r) => { resolveReady = r })
+  const decide = (m) => {
+    if (!mode) mode = m
+    for (const fp of pending) bind(fp)
+    pending.clear()
+    resolveReady(mode)
+  }
+  // ONLY AN ANSWER DECIDES. A free Render instance takes 30-60s to wake and says nothing at all
+  // meanwhile; reading that silence as "no mux" pinned the whole session to a socket per file.
+  // So silence (a timeout, a refused connection, a 5xx from a proxy fronting a booting service) is
+  // asked again for up to ~90s. Any real answer decides at once -- including an old relay's
+  // plain-text /health, which is a relay that has never heard of mux. Out of time: a socket per
+  // file, the transport every relay has always spoken.
+  const detect = async () => {
+    const deadline = Date.now() + detectForMs
+    for (let wait = retryMs; ; wait = Math.min(wait * 2, 15000)) {
+      try {
+        const r = await fetchImpl(`${httpBase(relay)}/health`, { signal: AbortSignal.timeout(20000) })
+        if (r && r.status < 500) {
+          let j = null
+          try { j = JSON.parse(await r.text()) } catch { /* not JSON: an old relay, or not a relay */ }
+          return r.ok && offersMux(j) ? 'mux' : 'socket'
+        }
+      } catch { /* no answer yet */ }
+      if (stopped || Date.now() + wait > deadline) return 'socket'
+      await new Promise((res) => { const t = setTimeout(res, wait); if (t.unref) t.unref() })
+    }
+  }
+  if (mode) resolveReady(mode)
+  else detect().then(decide, () => decide('socket'))
+  return {
+    ready,
+    get mode() { return mode || 'detecting' },
+    provide(docName, doc) {
+      const fp = new FileProvider(docName, doc)
+      if (mode) bind(fp)
+      else pending.add(fp)
+      return fp
+    },
+    stats() { return { mode: mode || 'detecting', channels: mux ? mux.channels.size : 0, muxConnected: !!(mux && mux.connected) } },
+    stop() { stopped = true; try { if (mux) mux.destroy() } catch { } },
+  }
+}

package/hive-privacy.js

@@ -42,6 +42,31 @@ export const PUBLIC_DEFAULT_RELAY = 'wss://hivecode-relay.onrender.com'
 // 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' }
 
 /**