hivecode-mcp 0.6.0

package/HIVE_RULES.md

@@ -0,0 +1,41 @@
+# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
+
+You are in a Hivecode room: humans and AI agents edit ONE project together live.
+These rules keep anyone from destroying another's work. The sync layer enforces
+the hard parts automatically; you do the rest.
+
+## Before you touch a file
+1. Read HIVE_CHAT.md — what is everyone doing right now.
+2. Read HIVE_BOARD.md — which files were just rewritten.
+3. If a file you plan to edit appears there, RE-READ it before changing it.
+
+## While you work
+4. ANNOUNCE in chat what you are taking before you start.
+5. PREFER SMALL PATCHES — grep to the spot, edit a few lines (they merge cleanly).
+6. AVOID full-file rewrites; if you must, RE-READ first (rewrites are auto-logged).
+7. STAY IN YOUR LANE — read others' areas, but leave edits to the owner.
+
+## When things collide
+8. <<<<<<< ======= >>>>>>> markers = a real conflict: keep the right code, delete
+   the markers. Never ignore or blindly overwrite.
+9. If your edit was merged/reworked, that is normal — re-read and continue.
+
+## Talking
+10. Coordinate in chat. ASK before anything destructive in another's area.
+
+## Mission control
+- If a human PAUSES you, finish your current step and STOP — start no new work
+  until resumed. A human may reassign your focus anytime; their directive wins.
+
+## When you get a ping mid-task (interruptions)
+11. Another AGENT pinging or assigning you = COORDINATION: auto-accepted and
+    QUEUED. It does NOT interrupt — finish your current atomic step first (never
+    abandon half-done work), THEN handle it. If it's urgent (build broken,
+    blocking others), do it now.
+12. ACKNOWLEDGE the moment you see a ping so the sender isn't left hanging, e.g.
+    "got it — finishing X (~2 min), then on your auth.js fix".
+13. YOU triage: say whether you'll do it now or after your current step. Your
+    OWNER can override anytime — if they say "do it now" or "skip that" in chat,
+    that wins (owner instructions are always honored).
+14. A ping from a HUMAN who is not your owner does NOT auto-run — it waits for
+    your owner's approval. Keep working; your owner decides.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hivecode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MCP.md

@@ -0,0 +1,77 @@
+# Hivecode MCP server
+
+Lets any MCP-capable AI agent (Claude Code, Claude Desktop, etc.) join a Hivecode
+room and coordinate through **native tool calls** — no scripts to run, no human
+to set it up.
+
+## Register it
+
+Add Hivecode to your MCP client config. The command runs this repo's server.
+
+**Claude Code** (`.mcp.json` in your project, or user settings):
+```json
+{
+  "mcpServers": {
+    "hivecode": {
+      "command": "node",
+      "args": ["C:/Users/G1/Desktop/N/hive-mcp.js"],
+      "env": { "HIVE_RELAY": "wss://livecode-xoss.onrender.com" }
+    }
+  }
+}
+```
+
+`HIVE_RELAY` is optional (defaults to the hosted relay).
+
+### Lower-friction join (no file copy)
+
+The package declares a `bin` (`hivecode-mcp` → `hive-mcp.js`), so once it's
+published to npm the other agent needs no local copy/clone — just:
+
+```json
+{ "mcpServers": { "hivecode": { "command": "npx", "args": ["-y", "hivecode-mcp"] } } }
+```
+
+`npx` fetches and runs it. (End state, even simpler: a **remote** MCP server
+hosted on the relay → config is just a `url`, zero install. Tradeoff: a remote
+server can't touch the agent's local disk, so file work goes through tools on
+the shared doc; humans keep the extension for local files.)
+
+## Tools the agent gets
+
+| Tool | What it does |
+|------|--------------|
+| `hive_join` | Join/host a room for a folder. Auto-joins as an **AI** participant. Returns the room info **and the HIVE_RULES to follow**. |
+| `hive_say` | Post a coordination message — announce what you're about to work on. |
+| `hive_read_chat` | Read the room conversation (read this to coordinate). |
+| `hive_read_board` | Read recent whole-file rewrites (read before editing a file). |
+| `hive_members` | Who's in the room (humans + agents). |
+| `hive_status` | Current session info. |
+| `hive_leave` | Leave the room. |
+
+## How an agent uses it
+
+1. `hive_join` (with a `link`, a `dir` containing `.hive.json`, or nothing to host a new room) — pass `owner` so the right human can approve your tasks.
+2. Read the returned **HIVE_RULES**.
+3. `hive_read_chat` + `hive_read_board` before touching files.
+4. `hive_say` to announce intent, then edit files in the synced folder.
+5. Keep editing — changes merge with everyone else's safely; rewrites are auto-logged.
+
+## Reacting to directed work (no polling)
+
+A human can direct a task at you, but you only act once **your owner approves**.
+Don't poll — **block** on `hive_wait`:
+
+```
+loop:
+  result = hive_wait(timeoutSeconds: 60)   # returns the instant your owner approves
+  if result has APPROVED WORK:
+     do it, then hive_complete(id)
+  # else just call hive_wait again
+```
+
+`hive_wait` returns within ~1s of the approval (it reacts to the live update),
+and also wakes on new chat so you stay responsive to teammates.
+
+This is the lowest-friction way for AIs to adopt the protocol in `SPEC.md`:
+the agent never runs a command, it just calls tools.

package/README.md

@@ -0,0 +1,137 @@
+<h1>Hivecode</h1>
+
+**Multiplayer for your AI coding agents — with real permissions.**
+
+Run humans and multiple AI agents on one live codebase. Folder-scoped access,
+approval gates, instant revoke. No git push/pull — edits sync in about a second.
+Open source.
+
+[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
+· [**Website**](https://livecode-xoss.onrender.com)
+· [Latest .vsix](https://github.com/GSK7024/livecode/releases)
+
+<!-- Add a demo GIF here once recorded: ![demo](docs/demo.gif) -->
+
+---
+
+## Why
+
+The moment you point more than one AI agent at a project, it gets messy: they
+overwrite each other's files, rebuild the same feature twice, and every agent can
+touch every file — secrets, configs, infra included. Today people juggle git
+worktrees and pray at merge time.
+
+Hivecode is a shared **live room** where humans and agents edit one project
+together — but with real access control. You decide what each agent can reach, and
+the relay enforces it; an out-of-scope agent never even receives the bytes.
+
+It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP.
+
+---
+
+## Quickstart
+
+1. Install the extension (link above). It works in **VS Code, Cursor, Windsurf,
+   and Antigravity**.
+2. Open the folder you want to share (**File → Open Folder**).
+3. `Ctrl/Cmd+Shift+P` → **Hivecode: Host a Secured Session**. A join link is
+   copied to your clipboard. *(No terminal, no server to run.)*
+4. **Hivecode: Invite to folders…** → pick the folders and a role (edit /
+   read-only) for each person or agent. Send them the link.
+5. They run **Hivecode: Join a Session** and paste the link. You're now editing
+   the same project live.
+
+Use **Manage access** to re-scope or revoke anyone, and **Leave Session** to stop.
+
+---
+
+## Add an AI agent
+
+Agents join through the Hivecode MCP server ([`hive-mcp.js`](hive-mcp.js)). Point
+your agent's MCP config at it and hand it the join link; it appears in the room as
+an `ai` member, scoped to exactly the folders you invited it to. The agent gets
+tools to read chat, the task board, and members; to claim and complete tasks; to
+talk; and to wait for work. See [MCP.md](MCP.md) for setup.
+
+---
+
+## What you get
+
+**Governance**
+- **Folder-scoped access** — invite an agent to `frontend/` only; it never receives
+  anything else.
+- **Approval gates** — a human's request to *your* agent waits for your OK;
+  agent-to-agent coordination flows automatically.
+- **Read-only roles** — reviewers see everything, change nothing.
+- **Instant revoke** — cut access mid-session, enforced server-side on every
+  reconnect (and it survives a relay restart).
+
+**Coordination**
+- **Built-in chat**, a **shared task board** (assign / complete), and **live
+  presence** so humans and agents stay in sync.
+- **Co-editing heads-up** before two people touch the same file.
+- **Never lose work** — overlapping edits keep both versions with conflict markers;
+  a stale rewrite can't silently delete another's lines.
+- **Mission control** — pause, resume, or reassign any agent; agents honor it
+  mid-task.
+
+**Trust**
+- **Server-enforced auth** — signed tokens, algorithm-pinned, fail-closed.
+  Unauthorized clients never complete the WebSocket handshake.
+- **Self-certifying secured rooms** — the room id embeds a fingerprint of your
+  public key; tokens carry the key and are signed by it; the relay trusts a token
+  only if the fingerprint matches. No account system, no shared secret. Your
+  private key stays in the editor's secure storage.
+- **Dependency-free core** — the access-control layer uses only Node's `crypto`.
+
+---
+
+## How the security model works
+
+A secured room's id is `hs_<fp>_<rand>`, where `fp` is a base64url SHA-256
+fingerprint of the owner's public key. Every token for the room carries the owner's
+public key (claim `pk`) and is signed by the matching private key (RS256). The relay
+trusts a token **iff** `fingerprint(token.pk) === fingerprint-in-room-id`, then
+verifies the signature with that key — so trust is anchored in the room id itself
+and the relay stores nothing.
+
+Files use a per-file subdocument model: the room is `<base>`, each file is a
+separate document at `<base>␁<path>`. The relay authorizes per path, so a scoped
+client can only open the files it may load, and out-of-scope content never reaches
+its disk. Paths are guarded against traversal, absolute paths, drive letters, and
+control characters on both the client (before writing) and the relay.
+
+A full threat/edge-case audit is in [EDGE-CASES.md](EDGE-CASES.md); the RBAC design
+is in [RBAC.md](RBAC.md).
+
+---
+
+## Self-hosting the relay
+
+The hosted relay is the default (`wss://livecode-xoss.onrender.com`) and needs no
+setup. To run your own, deploy [`server.js`](server.js) anywhere Node runs and set
+`hivecode.relayUrl` in the extension. The relay holds no truth of its own — it just
+passes CRDT updates between clients in the same room, and enforces access at the
+handshake. See [DEPLOY.md](DEPLOY.md).
+
+---
+
+## Development
+
+```bash
+npm install
+node test.js          # unit tests
+node hive-edge-test.js # adversarial / edge-case live tests
+```
+
+Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
+`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
+`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
+
+The extension source is in [`extension/`](extension/).
+
+---
+
+## License
+
+MIT.

package/core.js

@@ -0,0 +1,174 @@
+// Shared pure logic, used by the sync clients and the agents — and unit-tested
+// in test.js. Keeping these here (instead of copy-pasted) means a fix in one
+// place fixes everywhere, and the tests exercise the REAL code.
+
+// Minimal text diff: replace only the changed middle, preserving the common
+// prefix/suffix. Applied to a Y.Text so edits stay small (good for CRDT churn).
+export function applyDiff(ytext, next) {
+  const cur = ytext.toString()
+  if (cur === next) return false
+  let p = 0
+  while (p < cur.length && p < next.length && cur[p] === next[p]) p++
+  let s = 0
+  while (s < cur.length - p && s < next.length - p && cur[cur.length - 1 - s] === next[next.length - 1 - s]) s++
+  if (cur.length - p - s > 0) ytext.delete(p, cur.length - p - s)
+  const ins = next.slice(p, next.length - s)
+  if (ins) ytext.insert(p, ins)
+  return true
+}
+
+// Optimistic concurrency: is a write based on `expected` still safe to apply?
+// Returns the new version on success, or { stale, current } if the region moved.
+export function safeBump(versions, region, expected) {
+  const current = versions.get(region)
+  if (current !== expected) return { stale: true, current }
+  versions.set(region, (current ?? 0) + 1)
+  return { ok: true, version: (current ?? 0) + 1 }
+}
+
+// Lock helpers (pessimistic concurrency). A lock is "alive" only if unexpired.
+export function lockHeldByOther(locks, file, me, now) {
+  const l = locks.get(file)
+  return l && l.owner !== me && l.exp > now ? l : null
+}
+
+// Deadlock-safe multi-file ordering: always acquire in a stable sorted order so
+// two agents can never form a circular wait (A holds 1 wants 2, B holds 2 wants 1).
+export function lockOrder(files) {
+  return [...files].sort()
+}
+
+// Richer negotiation: when a lock holder gets a request, decide how to respond.
+// Returns one of:
+//   grant   — no conflict, hand over (after finishing)
+//   counter — we both touch the same thing; propose taking turns
+//   deny    — the request is destructive while I'm still mid-edit; refuse for now
+// `holder` = { intent, done }, `request` = { from, summary }.
+export function negotiate(holder, request) {
+  const h = (holder.intent || '').toLowerCase()
+  const r = (request.summary || '').toLowerCase()
+  if (/\b(delete|drop|remove|rewrite|overwrite)\b/.test(r) && !holder.done) {
+    return { decision: 'deny', reason: 'that change is destructive and I am still mid-edit' }
+  }
+  const overlap = sharedWord(h, r)
+  if (overlap && !holder.done) {
+    return { decision: 'counter', reason: `we both touch "${overlap}"`, counter: 'let me finish, then it is yours' }
+  }
+  return { decision: 'grant', reason: 'no conflict' }
+}
+
+// Smallest shared "significant" word (len > 3) between two intent strings.
+function sharedWord(a, b) {
+  const words = (s) => new Set(s.split(/[^a-z0-9]+/i).filter((w) => w.length > 3))
+  const wb = words(b)
+  for (const w of words(a)) if (wb.has(w)) return w
+  return null
+}
+
+// --- Patch-apply-or-rework (for two writers in the SAME file) ---
+// 3-way line merge: given the `base` an agent read, the `mine` it produced, and
+// the `current` on the board now, decide what to write.
+//   - current unchanged  -> take mine
+//   - I changed nothing  -> take current
+//   - changes on disjoint lines -> merge both (no rework)
+//   - changes overlap the same lines -> { conflict } -> agent must re-do on current
+export function mergeEdit(base, mine, current) {
+  if (current === base) return { ok: true, text: mine }
+  if (mine === base) return { ok: true, text: current }
+  if (mine === current) return { ok: true, text: mine }
+  const b = base.split('\n')
+  const mr = changedRange(b, mine.split('\n'))
+  const tr = changedRange(b, current.split('\n'))
+  if (mr.endBase <= tr.startBase || tr.endBase <= mr.startBase) {
+    const out = b.slice()
+    for (const e of [mr, tr].sort((x, y) => y.startBase - x.startBase)) {
+      out.splice(e.startBase, e.endBase - e.startBase, ...e.newLines)
+    }
+    return { ok: true, text: out.join('\n') }
+  }
+  return { conflict: true } // same lines changed two ways -> re-reason on `current`
+}
+
+// --- 3-way merge for the SYNC layer (disk <-> shared doc) ---
+// Same idea as mergeEdit, but instead of bailing with { conflict } it always
+// returns text: disjoint edits merge cleanly; overlapping edits are wrapped in
+// git-style conflict markers so BOTH versions survive and a human/AI resolves.
+//   merge3(base, mine, theirs) -> { text, conflict }
+export function merge3(base, mine, theirs) {
+  if (mine === theirs) return { text: mine, conflict: false }
+  if (base === theirs) return { text: mine, conflict: false }  // only I changed
+  if (base === mine) return { text: theirs, conflict: false }  // only they changed
+  const b = base.split('\n')
+  const mr = changedRange(b, mine.split('\n'))
+  const tr = changedRange(b, theirs.split('\n'))
+  if (mr.endBase <= tr.startBase || tr.endBase <= mr.startBase) {
+    const out = b.slice()
+    for (const e of [mr, tr].sort((x, y) => y.startBase - x.startBase)) {
+      out.splice(e.startBase, e.endBase - e.startBase, ...e.newLines)
+    }
+    return { text: out.join('\n'), conflict: false }
+  }
+  // Overlap: reconstruct each side's lines over the union region [start,end).
+  const start = Math.min(mr.startBase, tr.startBase)
+  const end = Math.max(mr.endBase, tr.endBase)
+  const mineBlock = [...b.slice(start, mr.startBase), ...mr.newLines, ...b.slice(mr.endBase, end)]
+  const theirsBlock = [...b.slice(start, tr.startBase), ...tr.newLines, ...b.slice(tr.endBase, end)]
+  const out = [
+    ...b.slice(0, start),
+    '<<<<<<< local (yours)',
+    ...mineBlock,
+    '=======',
+    ...theirsBlock,
+    '>>>>>>> incoming (theirs)',
+    ...b.slice(end),
+  ]
+  return { text: out.join('\n'), conflict: true }
+}
+
+// Detect REAL git-style conflict markers in a file. Line-anchored on purpose:
+// it requires an opening `<<<<<<< ` AND a closing `>>>>>>> ` each at the start
+// of a line. This is what merge3 emits. A naive `text.includes('<<<<<<<')`
+// false-positives on any file that merely MENTIONS the markers (e.g. a README
+// documenting conflict resolution), which would announce a phantom conflict on
+// every sync. (Found by a live two-agent test, 2026-06-19.)
+export function hasConflictMarkers(text) {
+  return /^<<<<<<< /m.test(text) && /^>>>>>>> /m.test(text)
+}
+
+// --- Rewrite detection for the auto-board ---
+// Classify a change as a small PATCH (grep-and-edit, the common case) vs a
+// wholesale REWRITE, and pull out the symbol names the new version defines in
+// the changed region. The sync layer uses this to AUTO-record what an agent did
+// on a rewrite — so other agents learn of it even when the agent forgets to say.
+//   summarizeChange(base, next) -> { isRewrite, changedLines, totalLines, symbols }
+export function summarizeChange(base, next) {
+  const b = (base || '').split('\n')
+  const n = (next || '').split('\n')
+  if (!base) return { isRewrite: false, changedLines: n.length, totalLines: n.length, symbols: symbolsIn(next || '') }
+  const r = changedRange(b, n)
+  const churn = Math.max(r.endBase - r.startBase, r.newLines.length) // lines replaced or added
+  const total = Math.max(b.length, n.length)
+  // a rewrite = at least half the file churned (and more than a couple of lines)
+  const isRewrite = total > 0 && churn >= 4 && churn / total >= 0.5
+  return { isRewrite, changedLines: churn, totalLines: total, symbols: symbolsIn(r.newLines.join('\n')) }
+}
+
+// Best-effort "what was defined here" across common languages — for the board.
+function symbolsIn(text) {
+  const names = new Set()
+  const add = (re) => { let m; while ((m = re.exec(text)) && names.size < 8) names.add(m[1]) }
+  add(/\bfunction\s+(\w+)/g)        // function foo
+  add(/\bclass\s+(\w+)/g)           // class Foo
+  add(/\bdef\s+(\w+)/g)             // def foo (python)
+  add(/\b(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=/g) // const foo =
+  return [...names].slice(0, 8)
+}
+
+// Which base line-range an edit replaced, and the replacement lines.
+export function changedRange(base, other) {
+  let p = 0
+  while (p < base.length && p < other.length && base[p] === other[p]) p++
+  let s = 0
+  while (s < base.length - p && s < other.length - p && base[base.length - 1 - s] === other[other.length - 1 - s]) s++
+  return { startBase: p, endBase: base.length - s, newLines: other.slice(p, other.length - s) }
+}

package/hive-mcp.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// Hivecode MCP server — lets ANY MCP-capable AI agent join a hive room and
+// coordinate through native tool calls (no script-running, no human setup).
+//
+// Register it with an MCP client (e.g. Claude Code / Claude Desktop):
+//   command: node   args: ["<abs-path>/hive-mcp.js"]
+//   env (optional): HIVE_RELAY = wss://your-relay   (defaults to the hosted relay)
+//
+// Tools exposed:
+//   hive_join         join/host a room for a folder (auto kind:ai) -> returns the rules
+//   hive_say          post a coordination message to the room
+//   hive_read_chat    read the room conversation (read this to coordinate)
+//   hive_read_board   read recent whole-file rewrites (read before editing)
+//   hive_members      who is in the room
+//   hive_status       current session info
+//   hive_leave        leave the room
+//
+// This operationalizes SPEC.md: one server turns the protocol into agent-native
+// actions. The agent's FIRST move after hive_join should be to follow the rules
+// it returns (read chat + board before editing, announce intent, prefer patches).
+
+import fs from 'fs'
+import path from 'path'
+import crypto from 'crypto'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { startSync, parseLink } from './sync.js'
+
+const DEFAULT_RELAY = process.env.HIVE_RELAY || 'wss://livecode-xoss.onrender.com'
+let session = null // { hive, room, relay, dir, name }
+
+const text = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s, null, 2) }] })
+const err = (s) => ({ content: [{ type: 'text', text: s }], isError: true })
+
+function resolveRoom(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)) {
+    try { const c = JSON.parse(fs.readFileSync(cfgPath, 'utf8')); if (c.room) return { relay: c.relay || DEFAULT_RELAY, room: c.room, token: c.token || '', mode: 'joined (.hive.json)' } } catch {}
+  }
+  return { relay: DEFAULT_RELAY, room: 'room-' + crypto.randomBytes(13).toString('base64url'), token: '', mode: 'HOSTED (new room)' }
+}
+
+async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '' }) {
+  if (session) { try { session.hive.stop() } catch {} ; session = null }
+  const ROOT = path.resolve(dir)
+  fs.mkdirSync(ROOT, { recursive: true })
+  const { relay, room, token: linkToken, mode } = resolveRoom(link, dir)
+  // token precedence: explicit arg > token baked into the join link > $HIVE_TOKEN.
+  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))
+  const hive = startSync({ relay, room, dir, name, kind: 'ai', owner, token: useToken, log: () => {} })
+  session = { hive, room, relay, dir, name }
+  // wait for the first sync so members/board/rules are ready
+  await new Promise((resolve) => {
+    let done = false
+    const finish = () => { if (!done) { done = true; resolve() } }
+    hive.provider.on('sync', (s) => s && finish())
+    setTimeout(finish, 8000) // don't hang if the relay is cold
+  })
+  hive.say(`${name} joined and is ready to work.`)
+  const rules = (() => { try { return fs.readFileSync(path.join(ROOT, 'HIVE_RULES.md'), 'utf8') } catch { return '(rules not yet written)' } })()
+  const others = hive.members().filter((m) => m.name !== name).map((m) => `${m.name}(${m.kind})`)
+  return `${mode}\nroom: ${room}\nrelay: ${relay}\nfolder: ${ROOT}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${relay}|${room}\n\n--- FOLLOW THESE RULES ---\n${rules}`
+}
+
+function requireSession() { if (!session) throw new Error('not in a room — call hive_join first'); return session }
+function chatArray() { return requireSession().hive.doc.getArray('chat').toArray() }
+function boardMap() { const b = requireSession().hive.doc.getMap('board'); return [...b.entries()].map(([file, e]) => ({ file, ...e })) }
+function taskList() { return [...requireSession().hive.doc.getMap('tasks').values()] }
+const fmtTask = (t) => `${t.id} [${t.status}] ${t.by} -> ${t.to}: ${t.text}${t.decidedBy ? ` (by ${t.decidedBy})` : ''}`
+
+// Block until there is approved work for me (or a new chat message), then return.
+// This is how the agent reacts the INSTANT the owner approves — no polling loop,
+// no interval to tune. Resolves immediately if approved work already exists.
+function waitForWork(timeoutMs) {
+  const s = requireSession()
+  const tmap = s.hive.doc.getMap('tasks')
+  const chat = s.hive.doc.getArray('chat')
+  const controls = s.hive.doc.getMap('controls')
+  const me = s.name
+  const paused = () => { const c = controls.get(me); return !!(c && c.state === 'paused') }
+  const accepted = () => (paused() ? [] : [...tmap.values()].filter((t) => t.to === me && t.status === 'accepted'))
+  const baseChatLen = chat.length
+  const rx = new RegExp('@' + me.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
+  const mentionsMe = (t) => rx.test(String(t || ''))
+  // PAUSED: stop auto-working, but STAY LISTENING. A paused agent doesn't pull its
+  // queued work — yet it still wakes the moment it's directly addressed: a new
+  // @mention in chat, or a new task assigned to it. It handles that, then calls
+  // hive_wait again (still paused) until a human resumes it.
+  if (paused()) {
+    const baseTaskIds = new Set([...tmap.values()].filter((t) => t.to === me).map((t) => t.id))
+    return new Promise((resolve) => {
+      let done = false
+      const finish = (v) => { if (!done) { done = true; controls.unobserve(onCtl); chat.unobserve(onChat); tmap.unobserve(onTask); resolve(v) } }
+      const mentions = () => chat.toArray().slice(baseChatLen).filter((m) => mentionsMe(m.text))
+      const directTasks = () => [...tmap.values()].filter((t) => t.to === me && t.status === 'accepted' && !baseTaskIds.has(t.id))
+      const check = () => {
+        if (!paused()) return finish({ tasks: accepted(), newChat: [], resumed: true })
+        const dt = directTasks(), mn = mentions()
+        if (dt.length || mn.length) finish({ paused: true, mentioned: true, tasks: dt, newChat: mn })
+      }
+      const onCtl = check, onChat = check, onTask = check
+      controls.observe(onCtl); chat.observe(onChat); tmap.observe(onTask)
+      setTimeout(() => finish({ paused: true }), timeoutMs)
+    })
+  }
+  const ready = accepted()
+  if (ready.length) return Promise.resolve({ tasks: ready, newChat: [] })
+  return new Promise((resolve) => {
+    let done = false
+    const finish = (v) => { if (!done) { done = true; tmap.unobserve(onTask); chat.unobserve(onChat); controls.unobserve(onCtl); resolve(v) } }
+    const onTask = () => { const a = accepted(); if (a.length) finish({ tasks: a, newChat: [] }) }
+    const onChat = () => { const extra = chat.toArray().slice(baseChatLen); if (extra.length) finish({ tasks: accepted(), newChat: extra }) }
+    const onCtl = () => { if (paused()) finish({ paused: true }) } // paused mid-wait -> stop handing out work
+    tmap.observe(onTask); chat.observe(onChat); controls.observe(onCtl)
+    setTimeout(() => finish(null), timeoutMs)
+  })
+}
+
+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.' } } } },
+  { 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.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_wait', description: 'BLOCK until there is approved work for you (or new chat), then return it. Use this as your main loop: call hive_wait; when it returns an accepted task, do the work and call hive_complete; then call hive_wait again. Returns instantly if approved work already exists. Times out after timeoutSeconds (default 60) so you can re-call.',
+    inputSchema: { type: 'object', properties: { timeoutSeconds: { type: 'number', description: 'max seconds to wait (default 60, max 300)' } } } },
+  { name: 'hive_approve', description: 'Approve a pending task (you must be the owner of the target AI). The AI may then act on it.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+  { name: 'hive_deny', description: 'Deny a pending task (you must be the owner of the target AI).',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+  { name: 'hive_complete', description: 'Mark a task you were doing as done (optionally with a note).',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' }, note: { type: 'string' } }, required: ['id'] } },
+  { name: 'hive_say', description: 'Post a coordination message to the room chat. Use this to announce what you are about to work on BEFORE editing (e.g. "taking auth.js: adding login").',
+    inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'the message' } }, required: ['text'] } },
+  { name: 'hive_read_chat', description: 'Read the room conversation. Read this to see what humans and other agents are doing before and while you work.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'how many recent messages (default 30)' } } } },
+  { name: 'hive_read_board', description: 'Read recent whole-file rewrites (who rewrote what, which symbols). Read this before editing a file — if it was just rewritten, re-read the file first.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_members', description: 'List who is currently in the room (humans and AI agents).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_status', description: 'Show the current session (room, relay, folder, name).', inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_leave', description: 'Leave the room and stop syncing.', inputSchema: { type: 'object', properties: {} } },
+]
+
+const server = new Server({ name: 'hivecode', version: '0.1.0' }, { capabilities: { tools: {} } })
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params
+  try {
+    switch (name) {
+      case 'hive_join': return text(await joinRoom(args))
+      case 'hive_say': { requireSession().hive.say(String(args.text || '')); return text(`sent: ${args.text}`) }
+      case 'hive_read_chat': { const n = args.limit || 30; const msgs = chatArray().slice(-n).map((m) => `${m.at} ${m.by}(${m.kind}): ${m.text}`); return text(msgs.join('\n') || '(no messages yet)') }
+      case 'hive_read_board': { const b = boardMap(); return text(b.length ? b.map((e) => `${e.at} ${e.by} rewrote ${e.file} (${e.churn}) — touched: ${(e.symbols || []).join(', ')}`).join('\n') : '(no rewrites logged)') }
+      case 'hive_assign': { const id = requireSession().hive.assign(String(args.to || ''), String(args.text || '')); return id ? text(`assigned task ${id} to ${args.to} (pending approval if they have an owner)`) : err('need to and text') }
+      case 'hive_read_tasks': {
+        const all = taskList(); const me = requireSession().name
+        const mine = all.filter((t) => t.to === me)
+        const pending = all.filter((t) => t.status === 'pending')
+        return text(`TASKS FOR YOU (act only on 'accepted'):\n${mine.map(fmtTask).join('\n') || '(none)'}\n\nPENDING (awaiting approval):\n${pending.map(fmtTask).join('\n') || '(none)'}`)
+      }
+      case 'hive_wait': {
+        const ms = Math.min(Math.max(Number(args.timeoutSeconds) || 60, 1), 300) * 1000
+        const r = await waitForWork(ms)
+        if (r && r.paused) {
+          if (r.mentioned) {
+            const parts = []
+            if (r.newChat && r.newChat.length) parts.push(`💬 Mentioned while paused:\n${r.newChat.map((m) => `${m.by}(${m.kind}): ${m.text}`).join('\n')}`)
+            if (r.tasks && r.tasks.length) parts.push(`📌 Directed task(s):\n${r.tasks.map(fmtTask).join('\n')}`)
+            return text(`⏸ You are PAUSED, but were directly addressed. Handle ONLY this, then call hive_wait again (you stay paused until a human resumes you — don't pick up other queued work):\n\n${parts.join('\n\n')}`)
+          }
+          return text('⏸ You are PAUSED by mission control. Stop new work and wait. You will be woken if someone @mentions you or assigns you a task; otherwise just call hive_wait again.')
+        }
+        if (!r) return text('(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)')
+        const parts = []
+        if (r.resumed) parts.push('▶ You were RESUMED by mission control — continue.')
+        if (r.tasks.length) parts.push(`APPROVED WORK — do these now, then hive_complete each:\n${r.tasks.map(fmtTask).join('\n')}`)
+        if (r.newChat.length) parts.push(`NEW MESSAGES:\n${r.newChat.map((m) => `${m.at} ${m.by}(${m.kind}): ${m.text}`).join('\n')}`)
+        return text(parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)')
+      }
+      case 'hive_approve': { const r = requireSession().hive.decide(String(args.id), true); return r.ok ? text(`approved ${args.id}`) : err(r.error) }
+      case 'hive_deny': { const r = requireSession().hive.decide(String(args.id), false); return r.ok ? text(`denied ${args.id}`) : err(r.error) }
+      case 'hive_complete': { const r = requireSession().hive.complete(String(args.id), String(args.note || '')); return r.ok ? text(`completed ${args.id}`) : err(r.error) }
+      case 'hive_members': { const now = Date.now(); return text(requireSession().hive.members().map((m) => `${m.name} (${m.kind})${m.editing && now - m.editing.at < 15000 ? ` — editing ${m.editing.file}` : ''}`).join('\n') || '(none)') }
+      case 'hive_status': { const s = requireSession(); return text({ room: s.room, relay: s.relay, dir: s.dir, name: s.name }) }
+      case 'hive_leave': { requireSession().hive.stop(); session = null; return text('left the room') }
+      default: return err(`unknown tool: ${name}`)
+    }
+  } catch (e) { return err(`error: ${e.message}`) }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+// 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)