hivecode-mcp 0.12.0 → 0.12.2

package/hive-relay-health.js

@@ -132,13 +132,33 @@ export function diagnose(probe, { stuck = 0, what = 'files' } = {}) {
   const seats = h.seats ? ` (${h.seats} seats)` : ''
   const facts = `I asked ${url}: ${conns} of ${total} connections in use, ${h.rooms || 0} rooms, per-room cap ${perRoom}${seats}.`
 
+  // ONE SOCKET PER PARTICIPANT has its own ceiling: the files open across every participant's
+  // shared socket (Q438). Checked first, because at that ceiling the socket count looks healthy.
+  const chanCap = Number(h.limits && h.limits.maxChannelsTotal) || 0
+  const chans = Number(h.channels) || 0
+  if (Number(h.mux) >= 1 && chanCap && chans >= chanCap * NEAR_CAPACITY) {
+    return {
+      verdict: RELAY_FULL,
+      text: [lead, `I asked ${url}: ${chans} of ${chanCap} open files in use across all participants.`,
+        `THE RELAY IS AT ITS OPEN-FILE CAPACITY — this is Q438. Raise HIVE_MAX_CHANNELS_TOTAL on the relay,`,
+        `or narrow what syncs.`].join(' '),
+    }
+  }
+
   if (total && conns >= total * NEAR_CAPACITY) {
+    // Who spends the sockets depends on the transport. A relay offering one-socket mode charges
+    // those clients 2 each; the older transport, still spoken by the VS Code extension, the browser
+    // panel and HIVE_MUX=0, charges one PER FILE -- and that is what exhausts a relay.
+    const who = Number(h.mux) >= 1
+      ? `This relay carries each participant's files on one socket (2 sockets a participant), but clients`
+        + ` on the older transport -- the VS Code extension, the browser panel, HIVE_MUX=0 -- still open one`
+        + ` socket PER FILE, and one large folder on those can exhaust it alone.`
+      : `Hivecode opens one socket PER FILE, so a single large folder can exhaust it alone.`
     return {
       verdict: RELAY_FULL,
       text: [lead, facts,
-        `THE RELAY IS AT OR NEAR CAPACITY — this is Q430. 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(' '),
+        `THE RELAY IS AT OR NEAR CAPACITY — this is Q430.`, who,
+        `Raise HIVE_MAX_CONNS_TOTAL on the relay, or narrow what syncs.`].join(' '),
     }
   }
 
@@ -198,7 +218,7 @@ export function explainStatus(code, relay = '') {
   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 === 503) return 'the relay is not serving this connection. Either the whole relay is at capacity (Q430 sockets, Q438 open files, or Q439 files held by one participant) or it could not check your licence and is failing closed rather than guessing. It may also be restarting -- if this lasts, contact support@getgrm.tech.'
   if (c) return `the relay answered ${c} instead of accepting the connection. Contact support@getgrm.tech.`
   return `the relay at ${relay || 'the relay'} cannot be reached. It may be down, asleep, or blocked by a network. Contact support@getgrm.tech if this continues.`
 }

package/hive-setup.js

@@ -0,0 +1,445 @@
+// hive-setup.js -- `npx -y hivecode-mcp@latest setup ["<join link>"] [--name You-AI]`
+//
+// ONE COMMAND FROM NOTHING TO AN AGENT THAT CAN JOIN. It exists because setup cost a real
+// tester an hour on 24 Sep 2026, and when it was measured the next day on a cold machine the
+// hour had concrete causes, none of them in the relay (hive_join itself took 0.5s):
+//
+//   1. The README's config was {"command":"npx", ...}. Agent apps start MCP servers WITHOUT a
+//      shell, and on Windows npx is npx.cmd, so the launch fails with `spawn npx ENOENT` -- the
+//      agent just never gets the hive_* tools, and nothing on screen says why.
+//   2. The first `npx hivecode-mcp@latest` start took 36.7s, downloading. Claude Code gives an
+//      MCP server 30s, so a new user's FIRST launch fails, and the second one may not.
+//   3. hive_join's default folder was './workspace', relative to whatever directory the agent
+//      app happened to start the server in -- sometimes the user's project, sometimes a
+//      directory nobody can write to.
+//
+// So this does the four things a person was doing by hand, and then CHECKS them:
+//   - installs a runtime copy under ~/.hivecode/runtime/<version>, so launching needs no
+//     download, no network and no npx;
+//   - writes the hivecode entry into every agent config it finds, with the absolute path of
+//     THIS node, which also dodges GUI apps on macOS not seeing an nvm PATH;
+//   - launches each entry exactly the way the agent app will -- read back from the file, no
+//     shell -- and does a real MCP handshake with it;
+//   - prints the one sentence to paste into the agent.
+//
+// THE FAILURE THIS MUST NEVER HAVE is the one every defect in this repo has had: reporting
+// success while the result is wrong. An agent whose config could not be written, or whose entry
+// does not start, is printed as FAILED and makes the exit code non-zero. "Configured" is only
+// ever printed about an entry that was read back from disk and answered a handshake.
+//
+// WHAT IT COSTS WHEN WRONG: these are the user's own config files, holding their other MCP
+// servers. So a file is parsed or refused (JSON with comments is refused, not rewritten), the
+// original is backed up once before the first change, only the `hivecode` key is touched, and
+// every other key survives byte-for-byte as a value.
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import { VERSION } from './hive-version.js'
+import { currentRelayFor, PUBLIC_DEFAULT_RELAY } from './hive-privacy.js'
+import { validateMemberName } from './hive-mailbox.js'
+
+export const SERVER_KEY = 'hivecode'
+const BACKUP_SUFFIX = '.before-hivecode'
+
+/** Every agent app we know how to configure, and where each keeps its MCP servers. */
+export function agentTargets(home = os.homedir(), env = process.env, platform = process.platform) {
+  const claudeDesktopDir = platform === 'win32' ? path.join(env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Claude')
+    : platform === 'darwin' ? path.join(home, 'Library', 'Application Support', 'Claude')
+    : path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'Claude')
+  // `present` is how we decide the app is installed. It is deliberately the app's OWN directory
+  // (or, where the app creates it on first run, its own file) -- never "the file we would write",
+  // which would make every run create configs for apps the user does not have.
+  return [
+    { id: 'claude-code', label: 'Claude Code', file: path.join(home, '.claude.json'), present: path.join(home, '.claude.json'), claudeCode: true,
+      restart: 'start a new Claude Code session (or restart `claude`)' },
+    { id: 'antigravity', label: 'Antigravity', file: path.join(home, '.gemini', 'antigravity', 'mcp_config.json'), present: path.join(home, '.gemini', 'antigravity'),
+      restart: 'Settings > Skills & Customizations > MCP Servers, then click refresh on hivecode (or restart Antigravity)' },
+    // Antigravity also reads this one. It is only touched when it ALREADY has a hivecode entry --
+    // a stale one there could shadow the fresh one above -- and never created.
+    { id: 'antigravity-2', label: 'Antigravity (2nd)', file: path.join(home, '.gemini', 'config', 'mcp_config.json'), present: path.join(home, '.gemini', 'config', 'mcp_config.json'),
+      onlyIfHasEntry: true, restart: 'same refresh as above' },
+    { id: 'cursor', label: 'Cursor', file: path.join(home, '.cursor', 'mcp.json'), present: path.join(home, '.cursor'),
+      restart: 'Cursor Settings > MCP, then turn hivecode off and on (or restart Cursor)' },
+    { id: 'windsurf', label: 'Windsurf', file: path.join(home, '.codeium', 'windsurf', 'mcp_config.json'), present: path.join(home, '.codeium', 'windsurf'),
+      restart: 'Windsurf > MCP servers > Refresh (or restart Windsurf)' },
+    { id: 'claude-desktop', label: 'Claude Desktop', file: path.join(claudeDesktopDir, 'claude_desktop_config.json'), present: claudeDesktopDir,
+      restart: 'quit Claude Desktop fully (tray icon > Quit) and open it again' },
+    // The Gemini CLI shares ~/.gemini with Antigravity, so its directory proves nothing. Its own
+    // settings file does: the CLI writes it on first run.
+    { id: 'gemini-cli', label: 'Gemini CLI', file: path.join(home, '.gemini', 'settings.json'), present: path.join(home, '.gemini', 'settings.json'),
+      restart: 'restart `gemini`' },
+  ]
+}
+
+/**
+ * The node to write into configs: an absolute path (a bare "node" fails with ENOENT in GUI apps
+ * started from the macOS Dock, which do not see an nvm or Homebrew PATH), but the most STABLE
+ * absolute path that is still this same program. process.execPath on Homebrew is the versioned
+ * Cellar path, which `brew upgrade node` deletes; /opt/homebrew/bin/node is a link that follows
+ * the upgrade. A candidate is only taken when its realpath is exactly this node, so the choice
+ * can never change WHICH node runs -- and verifyEntry launches whatever was chosen anyway.
+ */
+export function stableNodePath(execPath = process.execPath, env = process.env) {
+  const real = (p) => { try { return fs.realpathSync(p) } catch { return null } }
+  const target = real(execPath)
+  if (!target) return execPath
+  const exe = process.platform === 'win32' ? 'node.exe' : 'node'
+  const versioned = /[\\/]v?\d+\.\d+\.\d+[\\/]|[\\/]Cellar[\\/]/
+  const fromPath = (env.PATH || env.Path || '').split(path.delimiter).filter(Boolean).map((d) => path.join(d, exe))
+  const cands = ['/opt/homebrew/bin/node', '/usr/local/bin/node', ...fromPath.filter((c) => !versioned.test(c))]
+  for (const c of cands) if (c !== execPath && fs.existsSync(c) && real(c) === target) return c
+  return execPath
+}
+
+/**
+ * Parse the JSON-with-comments that Cursor, VS Code and friends accept: // and /* *\/ comments and
+ * trailing commas, all outside strings. Returns the plain-JSON text.
+ */
+export function stripJsonc(src) {
+  let out = ''
+  for (let i = 0, inStr = false; i < src.length; i++) {
+    const c = src[i]
+    if (inStr) { out += c; if (c === '\\') out += src[++i] ?? ''; else if (c === '"') inStr = false; continue }
+    if (c === '"') { inStr = true; out += c; continue }
+    if (c === '/' && src[i + 1] === '/') { while (i < src.length && src[i] !== '\n') i++; out += '\n'; continue }
+    if (c === '/' && src[i + 1] === '*') { const e = src.indexOf('*/', i + 2); i = e < 0 ? src.length : e + 1; continue }
+    out += c
+  }
+  let res = ''
+  for (let i = 0, inStr = false; i < out.length; i++) {
+    const c = out[i]
+    if (inStr) { res += c; if (c === '\\') res += out[++i] ?? ''; else if (c === '"') inStr = false; continue }
+    if (c === '"') { inStr = true; res += c; continue }
+    if (c === ',') { let j = i + 1; while (j < out.length && /\s/.test(out[j])) j++; if (out[j] === '}' || out[j] === ']') continue }
+    res += c
+  }
+  return res
+}
+
+/** The entry every agent gets: this node, by absolute path, running hive-mcp.js directly. */
+export function serverEntry(runtimeJs, { claudeCode = false, previous = null, node = stableNodePath() } = {}) {
+  const entry = { command: node, args: [runtimeJs] }
+  // What the user added to an existing entry is theirs: a token, a relay, a working directory.
+  // Only the launch itself -- command and args -- is ours to replace.
+  if (previous && typeof previous === 'object') {
+    if (previous.env && typeof previous.env === 'object') entry.env = previous.env
+    if (typeof previous.cwd === 'string') entry.cwd = previous.cwd
+  }
+  if (claudeCode) return { type: 'stdio', ...entry, env: entry.env || {} }
+  return entry
+}
+
+/**
+ * Write the hivecode entry into one config file. Returns { status, detail }, where status is one
+ * of: 'written', 'unchanged', 'refused' (the file exists but is not plain JSON), 'error'.
+ */
+export function writeEntry(target, runtimeJs, { dryRun = false } = {}) {
+  let raw = ''
+  try { raw = fs.readFileSync(target.file, 'utf8') } catch (e) { if (e.code !== 'ENOENT') return { status: 'error', detail: e.message } }
+  let cfg = {}
+  let droppedComments = false
+  if (raw.trim()) {
+    const text = raw.replace(/^/, '')
+    try { cfg = JSON.parse(text) } catch {
+      // JSON with comments is legal in the files Cursor and VS Code write. Refusing it would hand
+      // the user back the hand-editing this command exists to remove; the original is kept.
+      try { cfg = JSON.parse(stripJsonc(text)); droppedComments = true } catch {
+        return { status: 'refused', detail: 'not valid JSON even allowing comments, so it was left exactly as it is' }
+      }
+    }
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) return { status: 'refused', detail: 'the file is not a JSON object' }
+  }
+  const servers = cfg.mcpServers && typeof cfg.mcpServers === 'object' && !Array.isArray(cfg.mcpServers) ? cfg.mcpServers : {}
+  const previous = servers[SERVER_KEY] || null
+  if (target.onlyIfHasEntry && !previous) return { status: 'skipped' }
+  const entry = serverEntry(runtimeJs, { claudeCode: !!target.claudeCode, previous })
+  const next = { ...cfg, mcpServers: { ...servers, [SERVER_KEY]: entry } }
+  // CLAUDE CODE'S OTHER SCOPE. `claude mcp add` stores a server under projects[<folder>] unless
+  // told otherwise, and that entry OVERRIDES the user-wide one inside that folder. Everyone who
+  // followed the old README therefore has a broken npx entry that would silently win over the one
+  // written above -- and this command would have printed READY about it. Those are ours by name.
+  let projectFixes = 0
+  if (target.claudeCode && cfg.projects && typeof cfg.projects === 'object') {
+    for (const [p, v] of Object.entries(cfg.projects)) {
+      const old = v && v.mcpServers && v.mcpServers[SERVER_KEY]
+      if (!old || typeof old !== 'object') continue
+      const fixed = serverEntry(runtimeJs, { claudeCode: true, previous: old })
+      if (JSON.stringify(fixed) === JSON.stringify(old)) continue
+      if (next.projects === cfg.projects) next.projects = { ...cfg.projects }
+      next.projects[p] = { ...v, mcpServers: { ...v.mcpServers, [SERVER_KEY]: fixed } }
+      projectFixes++
+    }
+  }
+  if (previous && !projectFixes && JSON.stringify(previous) === JSON.stringify(entry)) return { status: 'unchanged', detail: 'already set up' }
+  if (dryRun) return { status: 'written', detail: 'dry run: would write', entry }
+  try {
+    fs.mkdirSync(path.dirname(target.file), { recursive: true })
+    // The backup is taken ONCE, of the file as it was before Hivecode ever touched it, so a
+    // second or tenth run can never overwrite the one copy worth going back to.
+    if (raw && !fs.existsSync(target.file + BACKUP_SUFFIX)) fs.writeFileSync(target.file + BACKUP_SUFFIX, raw)
+    const tmp = target.file + '.hivecode-tmp'
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n')
+    try { fs.renameSync(tmp, target.file) } catch {
+      // A locked destination (an app holding it, an antivirus scan) refuses the rename on
+      // Windows. Writing in place is less atomic but still leaves a whole file behind.
+      fs.writeFileSync(target.file, JSON.stringify(next, null, 2) + '\n'); try { fs.rmSync(tmp, { force: true }) } catch {}
+    }
+  } catch (e) { return { status: 'error', detail: e.message } }
+  let detail = previous ? 'replaced the old hivecode entry' : 'added hivecode'
+  if (projectFixes) detail += `, and fixed ${projectFixes} per-folder entr${projectFixes === 1 ? 'y' : 'ies'} that would have overridden it`
+  if (droppedComments) detail += ` (its comments were dropped; the original is ${path.basename(target.file)}${BACKUP_SUFFIX})`
+  return { status: 'written', detail }
+}
+
+/**
+ * Every hivecode entry in a written file must launch the same thing -- including Claude Code's
+ * per-folder ones, which are never verified by launching separately. Returns the first entry
+ * that disagrees with `entry`, or null.
+ */
+export function strayEntry(file, entry) {
+  let cfg
+  try { cfg = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, '')) } catch { return null }
+  for (const [p, v] of Object.entries((cfg && cfg.projects) || {})) {
+    const e = v && v.mcpServers && v.mcpServers[SERVER_KEY]
+    if (e && (e.command !== entry.command || JSON.stringify(e.args) !== JSON.stringify(entry.args))) return p
+  }
+  return null
+}
+
+/** Read the entry back FROM DISK -- the thing the agent app will actually launch. */
+export function readEntry(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, '')).mcpServers[SERVER_KEY] || null } catch { return null }
+}
+
+/**
+ * Launch an entry exactly as an MCP client does -- no shell, the entry's own env and cwd -- and
+ * complete a real `initialize` handshake. Anything short of a hivecode server answering is a
+ * failure with the reason attached.
+ */
+export function verifyEntry(entry, { timeoutMs = 20000 } = {}) {
+  return new Promise((resolve) => {
+    if (!entry || !entry.command) return resolve({ ok: false, error: 'no hivecode entry in the file' })
+    const t0 = Date.now()
+    const cwd = entry.cwd && fs.existsSync(entry.cwd) ? entry.cwd : os.tmpdir()
+    let child
+    try {
+      child = spawn(entry.command, entry.args || [], { cwd, env: { ...process.env, ...(entry.env || {}) }, shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })
+    } catch (e) { return resolve({ ok: false, error: e.message }) }
+    let out = ''
+    let errTail = ''
+    let settled = false
+    const done = (r) => { if (settled) return; settled = true; clearTimeout(timer); try { child.kill() } catch {}; resolve({ ms: Date.now() - t0, ...r }) }
+    const timer = setTimeout(() => done({ ok: false, error: `no answer within ${Math.round(timeoutMs / 1000)}s${errTail ? ': ' + errTail.trim().split('\n').pop() : ''}` }), timeoutMs)
+    child.on('error', (e) => done({ ok: false, error: `${e.code || ''} ${e.message}`.trim() }))
+    child.on('exit', (code) => done({ ok: false, error: `the server exited (code ${code}) before answering${errTail ? ': ' + errTail.trim().split('\n').pop() : ''}` }))
+    child.stderr.on('data', (d) => { errTail = (errTail + d).slice(-400) })
+    child.stdout.on('data', (d) => {
+      out += d
+      let i
+      while ((i = out.indexOf('\n')) >= 0) {
+        const line = out.slice(0, i); out = out.slice(i + 1)
+        let m; try { m = JSON.parse(line) } catch { continue }
+        if (m.id !== 1) continue
+        const info = m.result && m.result.serverInfo
+        if (info && info.name === 'hivecode') done({ ok: true, version: info.version })
+        else done({ ok: false, error: 'something answered, but it is not the hivecode server' })
+      }
+    })
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'hivecode-setup', version: VERSION } } }) + '\n')
+  })
+}
+
+/**
+ * Put a runtime where agent apps can launch it with no download. When this file is running out
+ * of a checkout (development), the checkout IS the runtime. When it is running out of an
+ * installed package (npx), the package and its dependency closure are copied under
+ * ~/.hivecode/runtime/<version> -- the npx cache is not a place to point a config at, because
+ * npm prunes it and the config would break months later with nothing to connect it to setup.
+ */
+export function installRuntime(home = os.homedir(), here = fileURLToPath(import.meta.url)) {
+  const pkgDir = path.dirname(here)
+  const nm = path.dirname(pkgDir)
+  if (path.basename(nm) !== 'node_modules') return { mode: 'checkout', js: path.join(pkgDir, 'hive-mcp.js') }
+  const dest = path.join(home, '.hivecode', 'runtime', VERSION)
+  const js = path.join(dest, 'node_modules', 'hivecode-mcp', 'hive-mcp.js')
+  if (fs.existsSync(js)) return { mode: 'installed', js, dir: dest, reused: true }
+  // ONLY the dependency closure is copied, never the whole node_modules around us: that would
+  // be every global package on a machine where hivecode-mcp was installed with `npm i -g`.
+  const closure = new Set()
+  const seen = new Set()
+  const visit = (name, fromDir) => {
+    // Node's own resolution: <dir>/node_modules/<name> for each directory walking up from the
+    // requiring package, skipping directories that ARE node_modules (Node never looks in
+    // node_modules/node_modules), and stopping at the folder that holds our node_modules.
+    for (let d = fromDir; ;) {
+      if (path.basename(d) !== 'node_modules') {
+        const cand = path.join(d, 'node_modules', name)
+        if (fs.existsSync(path.join(cand, 'package.json'))) {
+          if (seen.has(cand)) return // dependency cycles are real (and legal) in npm trees
+          seen.add(cand)
+          // Nested copies travel inside their parent's directory; only top-level ones are listed.
+          if (path.relative(nm, cand) === path.join(...name.split('/'))) closure.add(name)
+          let pj = {}
+          try { pj = JSON.parse(fs.readFileSync(path.join(cand, 'package.json'), 'utf8')) } catch {}
+          for (const dep of Object.keys({ ...pj.dependencies, ...pj.optionalDependencies, ...pj.peerDependencies })) visit(dep, cand)
+          return
+        }
+      }
+      const up = path.dirname(d)
+      if (up === d || d === path.dirname(nm)) return // a missing optional or peer dependency
+      d = up
+    }
+  }
+  closure.add('hivecode-mcp')
+  let rootPj = {}
+  try { rootPj = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')) } catch {}
+  for (const dep of Object.keys({ ...rootPj.dependencies, ...rootPj.optionalDependencies })) visit(dep, pkgDir)
+  const tmp = `${dest}.tmp-${process.pid}`
+  fs.rmSync(tmp, { recursive: true, force: true })
+  for (const name of closure) {
+    fs.cpSync(path.join(nm, name), path.join(tmp, 'node_modules', name), { recursive: true, dereference: true })
+  }
+  fs.rmSync(dest, { recursive: true, force: true })
+  fs.renameSync(tmp, dest)
+  return { mode: 'installed', js, dir: dest, packages: closure.size }
+}
+
+function defaultName() {
+  let base = 'agent'
+  try { base = os.userInfo().username || base } catch {}
+  const cand = (base.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'agent') + '-AI'
+  const v = validateMemberName(cand)
+  return v.ok ? cand : v.suggested
+}
+
+async function wakeRelay(relay) {
+  const url = relay.replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/+$/, '') + '/health'
+  const t0 = Date.now()
+  try {
+    const r = await fetch(url, { signal: AbortSignal.timeout(75000) })
+    return { ok: r.ok, ms: Date.now() - t0, status: r.status }
+  } catch (e) { return { ok: false, ms: Date.now() - t0, error: e.name === 'TimeoutError' ? 'no answer in 75s' : e.message } }
+}
+
+function parseArgs(argv) {
+  const o = { link: '', name: '', dryRun: false, help: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--name') o.name = argv[++i] || ''
+    else if (a.startsWith('--name=')) o.name = a.slice(7)
+    else if (a === '--dry-run') o.dryRun = true
+    else if (a === '-h' || a === '--help') o.help = true
+    else if (!a.startsWith('-') && !o.link) o.link = a
+  }
+  return o
+}
+
+const pad = (s, n) => (s + ' '.repeat(n)).slice(0, Math.max(n, s.length))
+
+/** Returns the process exit code: 0 only when nothing that exists failed. */
+export async function main(argv = [], { home = os.homedir(), log = console.log } = {}) {
+  const o = parseArgs(argv)
+  if (o.help) {
+    log('Usage: npx -y hivecode-mcp@latest setup ["<join link>"] [--name You-AI] [--dry-run]')
+    return 0
+  }
+  log(`\nHivecode setup  (hivecode-mcp ${VERSION})\n`)
+  const major = Number(process.versions.node.split('.')[0])
+  if (major < 18) { log(`  FAILED  Node ${process.versions.node} is too old. Install Node 18 or newer from https://nodejs.org and run this again.`); return 1 }
+
+  let name = o.name || defaultName()
+  const nv = validateMemberName(name)
+  if (!nv.ok) { log(`  note    "${name}" cannot be a room name (${nv.error.split('.')[0]}); using "${nv.suggested}".`); name = nv.suggested }
+
+  let runtime
+  try { runtime = o.dryRun ? { mode: 'dry-run', js: path.join(home, '.hivecode', 'runtime', VERSION, 'node_modules', 'hivecode-mcp', 'hive-mcp.js') } : installRuntime(home) }
+  catch (e) { log(`  FAILED  could not install the runtime under ${path.join(home, '.hivecode')}: ${e.message}`); return 1 }
+  log(`  runtime   ${runtime.js}`)
+  log(`  node      ${process.execPath}\n`)
+
+  const results = []
+  for (const t of agentTargets(home)) {
+    // A second config path of an app that IS installed is not an app of its own: printing
+    // "Antigravity (2nd) not installed" made a stranger ask what part of Antigravity was missing.
+    if (!fs.existsSync(t.present)) { if (!t.onlyIfHasEntry) results.push({ t, status: 'absent' }); continue }
+    const w = writeEntry(t, runtime.js, { dryRun: o.dryRun })
+    if (w.status !== 'skipped') results.push({ t, ...w })
+  }
+  // Verify what is ON DISK, once per distinct launch -- the entries are normally identical.
+  const cache = new Map()
+  for (const r of results) {
+    if (r.status !== 'written' && r.status !== 'unchanged') continue
+    if (o.dryRun) { r.verify = { ok: true, ms: 0, skipped: true }; continue }
+    const entry = readEntry(r.t.file)
+    const key = JSON.stringify(entry)
+    if (!cache.has(key)) cache.set(key, await verifyEntry(entry))
+    r.verify = cache.get(key)
+    const stray = r.verify.ok && entry && strayEntry(r.t.file, entry)
+    if (stray) r.verify = { ok: false, error: `the entry for the folder ${stray} still launches something else, and it wins inside that folder` }
+  }
+  // A project's own .mcp.json outranks everything written above, inside that project. It is a
+  // shared, committed file, so it is reported rather than rewritten with this machine's paths.
+  const projectMcp = path.join(process.cwd(), '.mcp.json')
+  if (readEntry(projectMcp)) log(`  WARNING   ${projectMcp} defines its own hivecode server, which overrides this setup inside this folder. Remove that entry.\n`)
+
+  let failed = 0
+  const ready = []
+  for (const r of results) {
+    const where = r.t.file
+    if (r.status === 'absent') { log(`  ${pad(r.t.label, 15)} not installed`); continue }
+    if (r.status === 'refused' || r.status === 'error') {
+      failed++
+      log(`  ${pad(r.t.label, 15)} FAILED  ${where}\n  ${' '.repeat(15)}         ${r.detail}. Add the hivecode entry below by hand.`)
+      continue
+    }
+    if (!r.verify.ok) {
+      failed++
+      log(`  ${pad(r.t.label, 15)} FAILED  ${where}\n  ${' '.repeat(15)}         written, but it does not start: ${r.verify.error}`)
+      continue
+    }
+    ready.push(r)
+    const how = r.verify.skipped ? 'dry run, nothing written' : `starts in ${(r.verify.ms / 1000).toFixed(1)}s`
+    log(`  ${pad(r.t.label, 15)} READY   ${r.status === 'unchanged' ? 'already set up' : r.detail}  (${how})`)
+  }
+
+  const manual = { mcpServers: { [SERVER_KEY]: serverEntry(runtime.js) } }
+  if (failed || !ready.length) {
+    log(`\n  ${ready.length ? 'For the agents above that FAILED' : 'No supported agent app was found. For any MCP agent'}, add this to its MCP settings:\n`)
+    log(JSON.stringify(manual, null, 2).split('\n').map((l) => '    ' + l).join('\n'))
+  }
+
+  let link = o.link.trim()
+  if (link) {
+    const [relayPart, ...rest] = link.split('|')
+    const { relay, migratedFrom } = currentRelayFor(relayPart.trim() || PUBLIC_DEFAULT_RELAY)
+    if (migratedFrom) { link = [relay, ...rest].join('|'); log(`\n  note    that link used a retired relay; it now points at ${relay}`) }
+    if (!rest.length || !rest[0].trim()) {
+      // THE PIPE TRAP. Unquoted, `setup wss://relay|room-x` is two commands to every shell: this
+      // one gets `wss://relay`, and our stdout is piped into a program called room-x. So the
+      // explanation also goes to stderr, the one stream still reaching the terminal.
+      const hint = `\n  WARNING  "${o.link}" has no room in it -- the part after | was cut off. Put the whole link in quotes, or leave it out: you give the link to your agent, not to this command.`
+      log(hint)
+      if (!process.stdout.isTTY) console.error(hint)
+    }
+    const w = await wakeRelay(relay)
+    log(w.ok ? `\n  relay     ${relay} is up (answered in ${(w.ms / 1000).toFixed(1)}s)` : `\n  WARNING  ${relay} did not answer (${w.error || 'HTTP ' + w.status}). Joining will fail until it does.`)
+  }
+
+  if (ready.length) {
+    log(`\nNEXT\n`)
+    ready.forEach((r, i) => log(`  ${i + 1}. ${r.t.label}: ${r.t.restart}.`))
+    if (link) {
+      log(`\n  Then paste this to your agent:\n`)
+      log(`    Use your hive_join tool to join the Hivecode room ${link} as ${name}. Then follow the rules it gives you.`)
+    } else {
+      log(`\n  Then paste ONE of these to your agent:\n`)
+      log(`    Use your hive_join tool to join the Hivecode room <the link you were sent> as ${name}. Then follow the rules it gives you.`)
+      log(`    Use your hive_join tool to host a new Hivecode room as ${name}, then give me the join link.`)
+    }
+    log(`\n  Its files go in ${path.join(home, 'hivecode', '<room>', name)} unless you name a folder.`)
+    log(`  People join from a browser, no install: ${PUBLIC_DEFAULT_RELAY.replace(/^wss:/, 'https:')}/control\n`)
+  }
+  return failed ? 1 : 0
+}

package/hive-stdio.js

@@ -0,0 +1,168 @@
+// hive-stdio.js -- the MCP stdio server Hivecode actually needs, without the SDK's web stack.
+//
+// WHY THIS EXISTS. @modelcontextprotocol/sdk is a client AND a server AND three HTTP transports,
+// so installing it installs express, hono, cors, jose, zod, ajv and ~85 other packages -- 25 MB,
+// most of a stranger's first `npx hivecode-mcp` download (36.7s measured cold, 25 Sep 2026). A
+// load trace of a full session (join, claim, write, release, say, wait) showed the client uses
+// exactly one slice of it: newline-delimited JSON-RPC over stdin/stdout, `initialize`, `ping`,
+// `tools/list`, `tools/call`, and two outgoing notifications. That slice is this file.
+//
+// IT MUST BEHAVE EXACTLY LIKE THE SDK WHERE A CLIENT CAN TELL. The SDK is still a devDependency,
+// and tests/mcp-conformance-test.mjs drives this server with the SDK's own CLIENT -- the one
+// Claude Code and the Gemini CLI are built on. Specifically, as in the SDK (1.30):
+//   - protocol version: echo the client's if supported, else answer with the newest we know;
+//   - `ping` -> {}; an unknown method -> error -32601; a handler that throws -> its own numeric
+//     `code` if it has one, else -32603, with the error's message;
+//   - a request the client CANCELLED gets no response (the spec: "SHOULD NOT send a response");
+//   - a line that is not JSON is logged to stderr and otherwise ignored, never answered.
+// And one thing the SDK does not do: when stdin closes, the server says so (onclose), so the
+// process can EXIT. The spec asks exactly that of a stdio server; the SDK left it running, and a
+// Hivecode server that outlives its agent app keeps a seat in the room for a member who is gone.
+
+export const LATEST_PROTOCOL_VERSION = '2025-11-25'
+export const SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07']
+
+// Same shape hive-mcp.js used to import from '@modelcontextprotocol/sdk/types.js': something
+// setRequestHandler can take the method name from.
+export const ListToolsRequestSchema = Object.freeze({ method: 'tools/list' })
+export const CallToolRequestSchema = Object.freeze({ method: 'tools/call' })
+
+const METHOD_NOT_FOUND = -32601
+const INVALID_PARAMS = -32602
+const INTERNAL_ERROR = -32603
+
+export class Server {
+  constructor(serverInfo, { capabilities = {}, instructions } = {}) {
+    this._serverInfo = serverInfo
+    this._capabilities = capabilities
+    this._instructions = instructions
+    // Keyed by method, called as handler(request, extra) -- the SDK's own internal shape, which
+    // the test seam in hive-mcp.js reaches into on purpose.
+    this._requestHandlers = new Map()
+    this._transport = null
+    this._inflight = new Map() // request id -> AbortController, so a cancel can find it
+    this.onclose = null
+    this.oninitialized = null
+    this._requestHandlers.set('initialize', (req) => {
+      const requested = req.params && req.params.protocolVersion
+      return {
+        protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION,
+        capabilities: this._capabilities,
+        serverInfo: this._serverInfo,
+        ...(this._instructions ? { instructions: this._instructions } : {}),
+      }
+    })
+    this._requestHandlers.set('ping', () => ({}))
+  }
+
+  setRequestHandler(schema, handler) {
+    const method = typeof schema === 'string' ? schema : schema && schema.method
+    if (!method) throw new Error('setRequestHandler needs a method')
+    this._requestHandlers.set(method, handler)
+  }
+
+  async connect(transport) {
+    this._transport = transport
+    transport.onmessage = (msg) => this._onmessage(msg)
+    transport.onclose = () => { this._transport = null; if (this.onclose) this.onclose() }
+    await transport.start()
+  }
+
+  /** Send a notification to the client. Rejects when there is nobody to send it to. */
+  notification({ method, params }) {
+    if (!this._transport) return Promise.reject(new Error('Not connected'))
+    return this._transport.send({ jsonrpc: '2.0', method, ...(params !== undefined ? { params } : {}) })
+  }
+
+  _onmessage(msg) {
+    if (Array.isArray(msg)) {
+      // JSON-RPC batches: the 2025-03-26 revision allowed them. Answer each request in the batch;
+      // the replies go back one per line, which every client matches by id.
+      for (const m of msg) this._onmessage(m)
+      return
+    }
+    if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0') return
+    if (msg.method === undefined) return // a response to a request we never send
+    if (msg.id === undefined || msg.id === null) return this._onnotification(msg)
+    this._onrequest(msg)
+  }
+
+  _onnotification(msg) {
+    if (msg.method === 'notifications/initialized') { if (this.oninitialized) this.oninitialized(); return }
+    if (msg.method === 'notifications/cancelled') {
+      const id = msg.params && msg.params.requestId
+      const ac = this._inflight.get(id)
+      if (ac) ac.abort()
+    }
+    // every other notification is ignorable by spec
+  }
+
+  async _onrequest(msg) {
+    const { id, method } = msg
+    const handler = this._requestHandlers.get(method)
+    if (!handler) return this._reply({ jsonrpc: '2.0', id, error: { code: METHOD_NOT_FOUND, message: 'Method not found' } })
+    if (method === 'tools/call' && (!msg.params || typeof msg.params !== 'object' || typeof msg.params.name !== 'string')) {
+      return this._reply({ jsonrpc: '2.0', id, error: { code: INVALID_PARAMS, message: 'tools/call needs params.name' } })
+    }
+    const ac = new AbortController()
+    this._inflight.set(id, ac)
+    let reply
+    try {
+      const result = await handler({ method, params: msg.params }, { signal: ac.signal, requestId: id })
+      reply = { jsonrpc: '2.0', id, result: result === undefined ? {} : result }
+    } catch (e) {
+      const code = e && Number.isSafeInteger(e.code) ? e.code : INTERNAL_ERROR
+      reply = { jsonrpc: '2.0', id, error: { code, message: (e && e.message) || 'Internal error' } }
+    } finally {
+      this._inflight.delete(id)
+    }
+    if (ac.signal.aborted) return // cancelled by the client: it is no longer waiting for this
+    this._reply(reply)
+  }
+
+  _reply(message) {
+    if (!this._transport) return
+    Promise.resolve(this._transport.send(message)).catch((e) => process.stderr.write(`[hive-stdio] could not reply: ${e && e.message}\n`))
+  }
+}
+
+export class StdioServerTransport {
+  constructor(stdin = process.stdin, stdout = process.stdout) {
+    this._stdin = stdin
+    this._stdout = stdout
+    this._buf = ''
+    this._closed = false
+    this.onmessage = null
+    this.onclose = null
+  }
+
+  async start() {
+    this._stdin.setEncoding('utf8') // a multi-byte character split across two chunks stays whole
+    this._stdin.on('data', (chunk) => {
+      this._buf += chunk
+      let i
+      while ((i = this._buf.indexOf('\n')) >= 0) {
+        const line = this._buf.slice(0, i).replace(/\r$/, '')
+        this._buf = this._buf.slice(i + 1)
+        if (!line.trim()) continue
+        let msg
+        try { msg = JSON.parse(line) } catch {
+          process.stderr.write(`[hive-stdio] ignored a line that is not JSON (${line.length} chars)\n`)
+          continue
+        }
+        try { if (this.onmessage) this.onmessage(msg) } catch (e) { process.stderr.write(`[hive-stdio] ${e && e.stack}\n`) }
+      }
+    })
+    const close = () => { if (this._closed) return; this._closed = true; if (this.onclose) this.onclose() }
+    this._stdin.on('end', close)
+    this._stdin.on('close', close)
+    this._stdin.on('error', close)
+  }
+
+  send(message) {
+    return new Promise((resolve, reject) => {
+      if (this._closed && !this._stdout.writable) return reject(new Error('stdout is closed'))
+      this._stdout.write(JSON.stringify(message) + '\n', (err) => (err ? reject(err) : resolve()))
+    })
+  }
+}