hivecode-mcp 0.12.0 → 0.12.2

package/hive-update.js

@@ -0,0 +1,58 @@
+// hive-update.js -- tells an agent, and through it its human, that a newer hivecode is out.
+//
+// WHY THIS EXISTS. `npx -y hivecode-mcp@latest setup` points agent apps at a runtime COPY
+// (~/.hivecode/runtime/<version>), which is what made starting fast, offline and free of npx.
+// It also means nothing updates any more: every start used to fetch @latest, and now an agent
+// stays on the version it was set up with until someone runs setup again. A room with mixed
+// builds is the one condition hive_join itself warns can lose data, so the gap must be visible.
+//
+// IT NEVER GETS IN THE WAY. The check starts with the server, carries a short timeout, and
+// hive_join and hive_status use whatever answer has arrived by then. A failed check says
+// nothing -- no network is not news. HIVE_PRIVATE=1 and HIVE_NO_UPDATE_CHECK=1 both switch it
+// off: a user who asked for privacy did not ask for a request to npm on every start.
+import { VERSION } from './hive-version.js'
+
+const REGISTRY_LATEST = 'https://registry.npmjs.org/hivecode-mcp/latest'
+
+/** True when version `a` is newer than `b` (x.y.z; anything unparseable is never "newer"). */
+export function newer(a, b) {
+  const parse = (v) => String(v).split('-')[0].split('.').map((n) => Number(n))
+  const pa = parse(a)
+  const pb = parse(b)
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return false
+    if (x !== y) return x > y
+  }
+  return false
+}
+
+let latest = null
+let started = false
+
+export function startUpdateCheck({ fetchImpl = globalThis.fetch, timeoutMs = 4000, env = process.env } = {}) {
+  if (started) return
+  started = true
+  if (env.HIVE_NO_UPDATE_CHECK === '1' || env.HIVE_PRIVATE === '1' || typeof fetchImpl !== 'function') return
+  Promise.resolve()
+    // HIVE_UPDATE_URL exists for tests/update-notice-test.mjs, which serves a fake registry so the
+    // wiring is proven end to end through a real server process.
+    .then(() => fetchImpl(env.HIVE_UPDATE_URL || REGISTRY_LATEST, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } }))
+    .then((r) => (r && r.ok ? r.json() : null))
+    .then((j) => { if (j && typeof j.version === 'string') latest = j.version })
+    .catch(() => { /* offline, blocked, or slow: say nothing */ })
+}
+
+/** The line to show, or '' when this agent is current (or nobody knows yet). */
+export function updateNotice(current = VERSION, known = latest) {
+  if (!known || !newer(known, current)) return ''
+  return `UPDATE AVAILABLE: hivecode ${known} is out; this agent runs ${current}. Tell your human to run ` +
+    '`npx -y hivecode-mcp@latest setup` and reload this agent. Mixed versions in one room can lose data.'
+}
+
+export const _test = {
+  reset() { latest = null; started = false },
+  setLatest(v) { latest = v; started = true },
+  latest: () => latest,
+}

package/limits.js

@@ -127,7 +127,27 @@ export const LIMITS = {
   // Retained CRDT size for one doc. A doc is one file in this design.
   maxDocBytes: num('HIVE_MAX_DOC_BYTES', 64 * 1024 * 1024),
   maxConnsPerRoom: num('HIVE_MAX_CONNS_PER_ROOM', 64),
-  maxConnsTotal: num('HIVE_MAX_CONNS_TOTAL', 512),
+  // The only cap that spans a whole project: a client holds one socket per open file (up to
+  // HIVE_MAX_OPEN_FILES=128) plus its base room, and each file is its own room as far as the
+  // per-room ceiling is concerned -- so a real team is bounded by THIS number and nothing else.
+  // It was 512: three participants on a 150-file room measured 409 connections, so a fourth
+  // was refused, on a relay already carrying other rooms. Measured cost 25 Sep 2026: ~56 KB of
+  // relay memory per connection (400 extra sockets to the same 400 docs: +22 MB), so 2048 is
+  // ~115 MB -- comfortable on a 512 MB free instance.
+  maxConnsTotal: num('HIVE_MAX_CONNS_TOTAL', 2048),
+  // ONE SOCKET PER PARTICIPANT (hive-mux-proto.js). A mux socket counts ONCE against
+  // maxConnsTotal above; each file it opens is a CHANNEL, counted against the file's per-room
+  // ceiling exactly as a per-file socket is, and against these two caps instead of the socket
+  // total -- which is the whole point: a participant stops costing 129 sockets.
+  //
+  // Sized by MEMORY, measured 25 Sep 2026: ~25.8 KB per channel whose doc no one else holds (the
+  // doc is most of it), ~2.4 KB for each further participant on the same doc. The socket cap
+  // used to bound open docs as a side effect; this is what bounds them now. 8192 lone small docs
+  // is ~211 MB on the 512 MB hosted instance -- raise it with the instance, not before. The per-
+  // participant cap matches the client's own bound in one-socket mode, so no single participant
+  // can take more than half the relay.
+  maxChannelsTotal: num('HIVE_MAX_CHANNELS_TOTAL', 8192),
+  maxChannelsPerSocket: num('HIVE_MUX_MAX_DOCS', 4096),
   // How long a client stays refused after tripping a rate limit. Long enough that a tight
   // loop actually yields, short enough that a human does not notice a one-off burst.
   cooloffMs: num('HIVE_RATE_COOLOFF_MS', 5000),
@@ -183,6 +203,32 @@ export function noteConnectionOpened(room) {
   roomConns.set(room, (roomConns.get(room) || 0) + 1)
 }
 
+// Channels share roomConns with sockets on purpose: the per-room ceiling means "how many
+// participants hold this file", and it must mean that whichever transport each one uses.
+let totalChannels = 0
+export function admitChannel(room, tier = null) {
+  if (totalChannels >= LIMITS.maxChannelsTotal) {
+    return { code: 503, reason: `Q438 relay at capacity (${LIMITS.maxChannelsTotal} open files across all participants)` }
+  }
+  const cap = (tier && tier.maxConnsPerRoom) || LIMITS.maxConnsPerRoom
+  const n = roomConns.get(room) || 0
+  if (n >= cap) {
+    const which = tier ? `${tier.tier} tier` : 'this relay'
+    return { code: 429, reason: `Q431 room at capacity (${cap} connections on ${which})` }
+  }
+  return null
+}
+export function noteChannelOpened(room) {
+  totalChannels++
+  roomConns.set(room, (roomConns.get(room) || 0) + 1)
+}
+export function noteChannelClosed(room) {
+  totalChannels = Math.max(0, totalChannels - 1)
+  const n = (roomConns.get(room) || 1) - 1
+  if (n <= 0) roomConns.delete(room)
+  else roomConns.set(room, n)
+}
+
 export function noteConnectionClosed(room) {
   totalConns = Math.max(0, totalConns - 1)
   const n = (roomConns.get(room) || 1) - 1
@@ -330,6 +376,7 @@ export function usageFor(room = null) {
 export function stats() {
   return {
     connections: totalConns,
+    channels: totalChannels,
     rooms: roomConns.size,
     largestDocBytes: docBytes.size ? Math.max(...docBytes.values()) : 0,
     docsTracked: docBytes.size,
@@ -340,6 +387,7 @@ export function stats() {
 /** Test-only: reset module state between cases. */
 export function _reset() {
   totalConns = 0
+  totalChannels = 0
   roomConns.clear()
   docBytes.clear()
   usage.clear()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hivecode-mcp",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "MCP server that lets any AI coding agent join a Hivecode room — humans and multiple AI agents edit one live codebase with folder-scoped permissions and approval gates.",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,8 @@
   },
   "files": [
     "hive-mcp.js",
+    "hive-mux.js",
+    "hive-mux-proto.js",
     "hive-version.js",
     "hive-pr-staleness.js",
     "hive-mailbox.js",
@@ -38,6 +40,9 @@
     "hive-activity.js",
     "hive-relay-health.js",
     "hive-privacy.js",
+    "hive-setup.js",
+    "hive-stdio.js",
+    "hive-update.js",
     "docs/SELF_HOSTING.md",
     "reconcile.cjs",
     "hive-busy.js",
@@ -80,13 +85,17 @@
     "test:features:shape": "node tests/features-test.mjs --shape",
     "test:learnings": "node tests/learnings-test.mjs",
     "test:docs": "node tests/readme-promises-test.mjs",
+    "test:setup": "node tests/setup-test.mjs --package",
+    "test:mcp": "node tests/mcp-conformance-test.mjs",
     "test:recreate": "node tests/blind-recreate-test.mjs",
     "test:liveness": "node tests/agent-liveness-test.mjs && node tests/unreachable-recipient-test.mjs",
     "build:ext": "node scripts/build-icr-cjs.cjs && node scripts/build-privacy-cjs.cjs",
     "test:selfhost": "node tests/relay-pin-test.mjs && node tests/self-host-test.mjs && node tests/extension-privacy-parity-test.mjs",
-    "test:hardening": "node tests/genesis-claim-test.mjs && node tests/bare-root-write-test.mjs && node tests/version-truth-test.mjs && node tests/room-repo-drift-test.mjs && node tests/first-contact-refusal-test.mjs && node tests/open-file-cap-test.mjs && node tests/learnings-test.mjs && node tests/agent-liveness-test.mjs && node tests/unreachable-recipient-test.mjs && node tests/join-honesty-test.mjs && node tests/relay-diagnosis-test.mjs && node tests/blind-recreate-test.mjs && node tests/genesis-collision-test.mjs && node tests/relay-pin-test.mjs && node tests/self-host-test.mjs && node tests/extension-privacy-parity-test.mjs && node tests/readme-promises-test.mjs",
+    "test:hardening": "node tests/genesis-claim-test.mjs && node tests/bare-root-write-test.mjs && node tests/version-truth-test.mjs && node tests/room-repo-drift-test.mjs && node tests/first-contact-refusal-test.mjs && node tests/open-file-cap-test.mjs && node tests/learnings-test.mjs && node tests/agent-liveness-test.mjs && node tests/unreachable-recipient-test.mjs && node tests/join-honesty-test.mjs && node tests/relay-diagnosis-test.mjs && node tests/blind-recreate-test.mjs && node tests/genesis-collision-test.mjs && node tests/relay-pin-test.mjs && node tests/self-host-test.mjs && node tests/extension-privacy-parity-test.mjs && node tests/readme-promises-test.mjs && node tests/setup-test.mjs && node tests/mcp-conformance-test.mjs && node tests/update-notice-test.mjs && node tests/mux-test.mjs && node tests/own-files-quiet-test.mjs",
     "test:extension": "node tests/extension-parity-test.mjs && node tests/extension-privacy-parity-test.mjs",
     "test:ceiling": "node tests/refused-visible-test.mjs && node tests/ceiling-no-data-loss-test.mjs",
+    "test:mux": "node tests/mux-test.mjs",
+    "test:live": "node scripts/live-stranger.mjs",
     "test:identity": "node tests/identity-audit-test.mjs",
     "test:billing": "node tests/billing-test.mjs",
     "test:license": "node tests/hive-license-test.js",
@@ -130,17 +139,18 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.104.2",
-    "@modelcontextprotocol/sdk": "^1.30.0",
     "acorn": "^8.17.0",
     "ignore": "^7.0.5",
     "lib0": "^0.2.117",
+    "lodash.debounce": "^4.0.8",
     "ws": "^8.18.0",
-    "y-websocket": "^2.0.4",
-    "yjs": "^13.6.18",
-    "zod": "^4.4.3"
+    "y-protocols": "^1.0.6",
+    "y-websocket": "^3.1.0",
+    "yjs": "^13.6.18"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.104.2",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@types/node": "^26.1.2",
     "esbuild": "^0.28.1",
     "typescript": "^7.0.2"

package/sync.js

@@ -20,6 +20,7 @@ import os from 'os'
 import path from 'path'
 import * as Y from 'yjs'
 import { WebsocketProvider } from 'y-websocket'
+import { createFileTransport } from './hive-mux.js' // ONE SOCKET PER PARTICIPANT: every file doc on one physical socket when the relay offers it
 import { WebSocket } from 'ws'
 import ignore from 'ignore'
 import { applyDiff, summarizeChange, changedRange, hasConflictMarkers, merge3 } from './core.js'
@@ -41,7 +42,7 @@ import { accountFor, sameText, DESCENDS, IDENTICAL, DIVERGED, UNPROVEN } from '.
 // a debt written anywhere else would be invisible to hive_owed: a warning nobody can see, which is
 // the defect this ticket is about, one level down.
 import * as RH from './hive-relay-health.js' // HIV-P13; the ONLY producer of the not-syncing diagnosis
-import { checkRelay } from './hive-privacy.js' // HIV-P20; which relay is this, and did anybody choose it
+import { checkRelay, currentRelayFor } from './hive-privacy.js' // HIV-P20; which relay is this, and did anybody choose it
 import * as OB from './hive-obligations.js'
 
 // Wire-format/protocol version. Bump when a change makes clients incompatible
@@ -63,6 +64,8 @@ const ALWAYS_IGNORE = [
   // to tell an authored edit from its own write after a restart (see SHADOW_FILE). It is
   // per-client by definition: syncing it would hand every peer a false ancestor.
   '.hive-shadow.json',
+  // ...and its write-then-rename temp, which exists for an instant but is the same file.
+  '.hive-shadow.json.tmp',
   // Names a PID on THIS machine. Syncing it would tell every peer their folder is locked by
   // a process that does not exist for them.
   '.hive-lock.json',
@@ -153,6 +156,10 @@ const AGENTS_FILE = 'HIVE_FOR_AGENTS.md' // how an AI agent opening this folder
 // Generated/coordination files are rendered locally from CRDT state — never
 // synced as ordinary files (that would cause echo loops / conflicts).
 const SKIP = new Set([BOARD_FILE, CHAT_FILE, TASKS_FILE, CONFIG_FILE, ID_FILE, RULES_FILE, MEMBERS_FILE, CLAIMS_FILE, AGENTS_FILE])
+// Files a client writes into its folder for ITSELF. They are ignored on purpose, so the "created
+// here but is ignored" notice must never name them: on 27 Sep 2026 every agent joining a live room
+// told the whole team about .hive-shadow.json, a file none of them had made.
+const OWN_LOCAL = new Set([SHADOW_FILE, SHADOW_FILE + '.tmp', LOCK_FILE, '.hive-mcp-session.json', '.hive-id.json'])
 
 // Written into every room folder on sync (like the rules). An AI agent that opens
 // this project reads it to learn it's a Hivecode room and how to JOIN — via the
@@ -166,7 +173,7 @@ asked to collaborate here, follow this.
 ## Join the room
 1. If you do NOT have a \`hive_join\` tool and you can run terminal commands, register
    the Hivecode MCP server, then reload so the tools load:
-     claude mcp add hivecode -- npx -y hivecode-mcp
+     claude mcp add hivecode -- npx -y hivecode-mcp@latest
 2. Call: hive_join({ dir: ".", name: "<your name>", owner: "<the human you work for>" })
    The room, relay, and token are already saved in .hive.json in this folder, so you
    do NOT need a link — hive_join reads them automatically.
@@ -437,6 +444,15 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // It throws for the reason the name check above throws: startSync has no failure channel,
   // and a client that half-connects to a relay nobody authorised is the failure this exists
   // to prevent. Refusing here means no socket was opened and no file was published.
+  // A retired public relay is followed to its replacement here too, because every node client
+  // (hive-agent.js, hive-say.js, the demos) reaches the network through this function and not
+  // through hive-mcp.js's resolveRoom. The privacy check below then judges the relay actually
+  // dialled, not the one that was asked for.
+  const moved = currentRelayFor(relay)
+  if (moved.migratedFrom) {
+    relay = moved.relay
+    try { log(`relay ${moved.migratedFrom} has been retired; using ${relay}`) } catch { /* log is optional */ }
+  }
   const priv = checkRelay({ relay, env: process.env, dir: path.resolve(dir), fs })
   if (!priv.ok) {
     const e = new Error(`${priv.headline}\n\n${priv.detail}`)
@@ -968,6 +984,15 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   if (kind) wsParams.kind = kind
   if (passive) wsParams.passive = 'true'
   const wsOpts = { WebSocketPolyfill: WebSocket, disableBc: true, params: Object.keys(wsParams).length ? wsParams : undefined }
+  // ONE SOCKET PER PARTICIPANT. When the relay offers it (it says so in /health), file docs stop
+  // costing a socket each: they ride one physical socket as channels, and the relay admits each
+  // one through the same gates a per-file socket passes. Against a relay that does not offer it,
+  // or with HIVE_MUX=0, every file gets its own WebsocketProvider exactly as before. Decided once,
+  // before the first file opens, so a session never straddles the two transports.
+  // onFallback: the relay stopped offering it mid-session, so trim to the per-file bound before
+  // each remaining file gets a socket of its own (trimForSockets, below).
+  const fileTransport = createFileTransport({ relay, room, wsOpts, log, onFallback: () => trimForSockets() })
+  let stopped = false
   const provider = new WebsocketProvider(relay, room, doc, wsOpts)
   provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, v: PROTOCOL_VERSION, passive: !!passive }) // identity is implicit in the client
 
@@ -1010,7 +1035,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       `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}.`
     if (code === 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 ` +
+      `(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}.`
     if (code) return `the relay answered ${code} instead of accepting the connection. Contact ${SUPPORT}.`
     return `the relay at ${relay} cannot be reached. It may be down, asleep, or blocked by a network. ` +
@@ -1079,6 +1104,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // count is the useful shape -- one per file would be 800 lines of chat.
   const refusedFiles = new Map() // relPath -> consecutive connection errors, cleared on sync
   const refusedCodes = new Map() // relPath -> the HTTP status the relay refused with, when it gave one
+  const refusedReasons = new Map() // relPath -> the relay's own words (a mux refusal carries its Q-code line)
   let refusalSaidAt = 0
   let refusalTimer = null
 
@@ -1125,7 +1151,11 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       const code = coded.length ? coded.sort((a, b) => coded.filter((c) => c === b).length - coded.filter((c) => c === a).length)[0] : null
       const msg = code
         ? `${stuck.length} file(s) are not synced and will READ AS EMPTY until this clears. ` +
-          `The relay refused ${coded.length} of them with ${code}: ${explain(code)} ` +
+          `The relay refused ${coded.length} of them with ${code}` +
+          // The relay's own reason outranks any mapping of the bare number: one code covers
+          // several ceilings, and only the relay knows which one it hit.
+          (() => { const why = stuck.map((r) => refusedCodes.get(r) === code && refusedReasons.get(r)).find(Boolean); return why ? ` ("${String(why).slice(0, 160)}")` : '' })() +
+          `: ${explain(code)} ` +
           `Do not trust this folder's contents meanwhile.`
         : (await RH.explainNotSyncing(relay, {
             stuck: stuck.length, what: 'files',
@@ -1213,7 +1243,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     let e = fileDocs.get(relPath)
     if (e) return e
     const fdoc = new Y.Doc()
-    const fprovider = new WebsocketProvider(relay, fileRoom(room, relPath), fdoc, wsOpts)
+    const fprovider = fileTransport.provide(fileRoom(room, relPath), fdoc)
     const text = fdoc.getText('content')
     // `snap` (in the FILE's own doc, so it's scope-protected with the file) holds
     // restore points: id -> { id, file, by, at, ts, content, churn, kind, label }.
@@ -1263,8 +1293,11 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       // handler took no argument at all, so noteRefusals had nothing but "N files are quiet" and
       // had to INFER a cause -- which is how it came to announce Q430 on 21 Sep while the relay
       // sat at 56 of 512. explain() above maps these codes correctly and has done since 5 Sep.
-      const code = ev && (ev.code || ev.status)
+      // A mux refusal carries the code; a per-file socket's ErrorEvent carries it only in its
+      // message, which is why this read nothing at all on the socket path.
+      const code = RH.statusFromError(ev)
       if (code) refusedCodes.set(relPath, code)
+      if (ev && typeof ev.reason === 'string' && ev.reason) refusedReasons.set(relPath, ev.reason)
       noteRefusals()
     })
     // Newly opened counts as used, and opening is the moment the working set can go over
@@ -1308,7 +1341,14 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   //   - a file in an unresolved conflict (its fork record is live and local-only)
   //   - a file anyone currently holds a claim on (they are mid-edit)
   //   - anything used within the grace window
-  const MAX_OPEN = Math.max(8, Number(process.env.HIVE_MAX_OPEN_FILES) || 128)
+  //
+  // THE BOUND DEPENDS ON THE TRANSPORT. With a socket per file it is what keeps one client from
+  // filling the relay, and the rule above applies. In one-socket mode a file costs a channel, not
+  // a socket, so the bound only caps memory -- set high enough that an ordinary repo is held
+  // whole, which is what ends "this folder is incomplete on purpose". HIVE_MAX_OPEN_FILES wins
+  // either way. A function, not a constant: the transport is known only once /health answers.
+  const MAX_OPEN_SET = Number(process.env.HIVE_MAX_OPEN_FILES) || 0
+  const maxOpen = () => Math.max(8, MAX_OPEN_SET || (fileTransport.mode === 'mux' ? 4096 : 128))
   // Configurable because the grace window is what makes eviction untestable otherwise: in a
   // short run every file was touched seconds ago, so nothing is ever eligible.
   const EVICT_GRACE_MS = Number(process.env.HIVE_EVICT_GRACE_MS) || 30000
@@ -1316,7 +1356,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   const touchFile = (relPath) => { if (fileDocs.has(relPath)) touched.set(relPath, Date.now()) }
   let evicted = 0
   function evictIfOverCap(keep) {
-    if (fileDocs.size <= MAX_OPEN) return
+    if (fileDocs.size <= maxOpen()) return
     const now = Date.now()
     const isClaimed = (r) => { try { return claims.has(r) } catch { return false } }
     const cand = []
@@ -1330,7 +1370,32 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       cand.push([r, t])
     }
     cand.sort((a, b) => a[1] - b[1]) // least recently used first
-    let over = fileDocs.size - MAX_OPEN
+    let over = fileDocs.size - maxOpen()
+    for (const [r] of cand) {
+      if (over-- <= 0) break
+      closeFile(r); touched.delete(r); evicted++
+    }
+  }
+
+  // THE FALLBACK TRIM. The relay stopped offering one-socket mode mid-session, and every file still
+  // open is about to cost a socket of its own. Keep the most recently used up to the per-file bound
+  // and close the rest -- UNSYNCED ones too, unlike evictIfOverCap: on this path "unsynced" means
+  // "was waiting on the socket that just went away", and its bytes are on disk or still in the
+  // room, so closing it costs latency, not work. Conflicted and claimed files are kept whatever
+  // the count, because closing those could. Without this, a joiner mid-way through fetching 900
+  // files would open 900 sockets at once -- the storm the per-file bound exists to prevent.
+  function trimForSockets() {
+    const cap = maxOpen()
+    if (fileDocs.size <= cap) return
+    const isClaimed = (r) => { try { return claims.has(r) } catch { return false } }
+    const cand = []
+    for (const [r, e] of fileDocs) {
+      if (conflicted.has(r) || isClaimed(r)) continue
+      try { if (e.conflict && e.conflict.size) continue } catch { }
+      cand.push([r, touched.get(r) || 0])
+    }
+    cand.sort((a, b) => a[1] - b[1]) // least recently used first
+    let over = fileDocs.size - cap
     for (const [r] of cand) {
       if (over-- <= 0) break
       closeFile(r); touched.delete(r); evicted++
@@ -2417,7 +2482,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       invisibleWarned.delete(r)
     }
     for (const r of ignoredRel) {
-      if (SKIP.has(r)) continue           // control files are ours and are supposed to be invisible
+      if (SKIP.has(r) || OWN_LOCAL.has(r)) continue // control files are ours and are supposed to be invisible
       if (preexisting.has(r)) continue    // it was already here; nobody did this during the session
       if (invisibleWarned.has(r)) continue // once per path, not once per scan tick
       const holder = coordinator.sense(r)
@@ -2510,7 +2575,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         // the sweep achieved nothing: the first measurement of this cap showed a client with
         // cap 8 holding 30 file docs, every one of them opened right here. A path we decline
         // to open now is not lost; it opens when something touches it.
-        if (fileDocs.size < MAX_OPEN) openFile(key)
+        if (fileDocs.size < maxOpen()) openFile(key)
       }
     })
   })
@@ -2559,16 +2624,26 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     //
     // Files that exist on THIS client's disk come first: they are the ones that need
     // reconciling, and a path we have no local copy of can wait until something asks for it.
-    const openable = [...manifest.keys()].filter((k) => canOpen(k) && !SKIP.has(k) && !isIgnored(k))
-    const localFirst = openable.sort((a, b) => {
-      const la = fs.existsSync(path.join(ROOT, a)) ? 0 : 1
-      const lb = fs.existsSync(path.join(ROOT, b)) ? 0 : 1
-      return la - lb
-    })
-    for (const key of localFirst.slice(0, MAX_OPEN)) openFile(key)
-    if (localFirst.length > MAX_OPEN) {
-      log(`[${name}] ${localFirst.length} files in this room, holding ${MAX_OPEN} open (HIVE_MAX_OPEN_FILES). The rest sync when touched.`)
+    //
+    // If /health has not said yet which transport this relay speaks, the sweep opens what is safe
+    // on either (the per-file bound) now and the rest the moment it answers -- holding every file
+    // back on one HTTP round trip would delay the join for nothing.
+    const sweep = (final) => {
+      const openable = [...manifest.keys()].filter((k) => canOpen(k) && !SKIP.has(k) && !isIgnored(k))
+      const localFirst = openable.sort((a, b) => {
+        const la = fs.existsSync(path.join(ROOT, a)) ? 0 : 1
+        const lb = fs.existsSync(path.join(ROOT, b)) ? 0 : 1
+        return la - lb
+      })
+      const cap = maxOpen()
+      for (const key of localFirst.slice(0, cap)) openFile(key)
+      if (final && localFirst.length > cap) {
+        log(`[${name}] ${localFirst.length} files in this room, holding ${cap} open (HIVE_MAX_OPEN_FILES). The rest sync when touched.`)
+      }
     }
+    const decided = fileTransport.mode !== 'detecting'
+    sweep(decided)
+    if (!decided) fileTransport.ready.then(() => { if (!stopped) sweep(true) })
     if (board.size) renderBoard()
     if (chat.length) renderChat()
     if (tasks.size) renderTasks()
@@ -2587,20 +2662,26 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     //
     // Nothing here changes the cap. It tells the agent the number it needs in order to ASK,
     // which is the one thing that makes "until something touches it" true.
-    setTimeout(() => {
+    //
+    // Said only when the bound really leaves files out. Below it a missing file is in flight (or
+    // refused, which noteRefusals reports with the relay's reason) -- not missing on purpose -- and
+    // one-socket mode holds 4096 files, so an ordinary room never hears this. Timed from the
+    // moment the transport is known, because the bound is not known before that.
+    fileTransport.ready.then(() => setTimeout(() => {
       try {
         const want = [...manifest.keys()].filter((r) => canOpen(r) && !SKIP.has(r))
         const have = want.filter((r) => fs.existsSync(path.join(ROOT, r)))
         const short = want.length - have.length
-        if (short <= 0) return
+        if (short <= 0 || want.length <= maxOpen() || stopped) return
         log(`[${name}] !! THIS FOLDER IS INCOMPLETE ON PURPOSE. The room has ${want.length} files; ` +
           `${have.length} are on disk here and ${short} are NOT. The working set is bounded to ` +
-          `${MAX_OPEN} open files (HIVE_MAX_OPEN_FILES), because one socket is opened per file and a ` +
-          `relay admits a limited number. A missing file EXISTS — it simply has not been fetched. ` +
+          `${maxOpen()} open files (HIVE_MAX_OPEN_FILES), because ` +
+          (fileTransport.mode === 'mux' ? `every open file costs relay memory. ` : `one socket is opened per file and a relay admits a limited number. `) +
+          `A missing file EXISTS — it simply has not been fetched. ` +
           `Do not treat it as absent and do not create it: reading or claiming the path fetches it. ` +
           `hive_status reports filesHeld of roomFiles, and hive_read_board lists what the room holds.`)
       } catch { }
-    }, 4000).unref?.()
+    }, 4000).unref?.())
     if (!scanTimer) {
       startWatch()
       scanTimer = setInterval(scan, watcher ? 2000 : 400) // watch handles fast path; scan is the net
@@ -2886,7 +2967,9 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         // maxConnsTotal, and `evicted` climbing steadily means the cap is too small for
         // how this room actually works — both are things an operator can only act on if
         // they can see them.
-        openCap: MAX_OPEN,
+        openCap: maxOpen(),
+        // 'mux' = every file on this client's one socket; 'socket' = a socket per file.
+        transport: fileTransport.mode,
         evicted,
       }
     },
@@ -2895,6 +2978,10 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       if (debounce) clearTimeout(debounce)
       if (editingClearTimer) clearTimeout(editingClearTimer)
       try { watcher && watcher.close() } catch { }
+      stopped = true
+      // The shared socket first: closing it ends every channel at once on the relay, instead of
+      // one CLOSE frame per file down a socket that is about to go anyway.
+      try { fileTransport.stop() } catch { }
       for (const r of [...fileDocs.keys()]) closeFile(r) // tear down every per-file provider
       try { provider.awareness.setLocalState(null) } catch { } // announce departure now (don't wait for timeout)
       try { provider.destroy() } catch { }