hivecode-mcp 0.12.1 → 0.12.4

package/LICENSE

@@ -1,21 +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.
+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/README.md

@@ -1,12 +1,13 @@
 <h1>Hivecode</h1>
 
-**A live shared workspace for people and their AI agents.**
+**An operating system for AI agents that share a workspace.**
 
-A few people, each with their own AI agent — Claude Code, Cursor, Windsurf, Antigravity, or
-your own bot — work on one project at the same time. Every edit reaches everyone in about a
-second. Agents lock a file before they change it, so they never overwrite each other. They
+A few people, each with their own AI agent — Claude Code, Antigravity, another app that speaks
+MCP, or your own bot — work on one project at the same time. Every edit reaches everyone in about
+a second. Agents lock a file before they change it, so they never overwrite each other. They
 talk to each other by name, and they wait for work instead of wandering off. You watch all of
-it live in your browser, approve what matters, pause any agent, and undo anything.
+it live in your browser, approve what matters, pause any agent, and put any file back to an
+earlier point.
 
 ---
 
@@ -19,12 +20,44 @@ it live in your browser, approve what matters, pause any agent, and undo anythin
 4. An agent **claims** a file before editing it and **releases** it after. While someone
    holds a file, anyone else's write to it is refused — never silently overwritten.
 5. You watch and steer from the **Control Room** in your browser.
+6. A file someone deletes is deleted for everyone, but every other folder keeps a copy in
+   `.hive-deleted/` for 7 days. A folder that disappears, or empties all at once, deletes nothing.
 
 Nothing to host. Rooms run on the Hivecode relay, and anyone who has a link can join that
 room — **treat the link like a password** and share it only with your team.
 
 ---
 
+## Your code: where it goes, and who can see it
+
+Read this before you join from a real project.
+
+- **Your shared files go to the relay and to everyone in the room.** The default relay is run by
+  the Hivecode author, not by you. Files travel over an encrypted connection (`wss://`), and the
+  relay keeps a copy so the room survives everyone going offline. Your agent's `hive_join` says
+  which relay it is using every time, and whose it is.
+- **The link is the key.** Anyone who has it can read and change every file in the room. Share
+  it like a password. If it leaks, start a new room. Let your agent host the room, so its name is
+  random: a name you type yourself, like `myteam`, can be guessed, and on our relay your agent is
+  warned when it joins one.
+- **These never leave your machine:** anything your `.gitignore` files ignore, `.git/`,
+  `node_modules/`, `.env` and `.env.*`, keys and certificates (`*.pem`, `*.key`, `*.p12`, `*.pfx`,
+  `*.p8`, `*.ppk`, `*.jks`, `*.keystore`, `id_rsa`, `id_ed25519`, `id_ecdsa`, `id_dsa`), and login
+  files (`.envrc`, `.netrc`, `.git-credentials`, `.pypirc`).
+- **A key pasted into an ordinary file stays too.** If a file holds an API key or token the room
+  does not already have (OpenAI, Anthropic, GitHub, GitLab, AWS, Stripe, Slack, npm, Hugging Face,
+  Groq, SendGrid, DigitalOcean, or a private key), Hivecode keeps that file on your machine and
+  tells you and your agent which file, and which line. Your agent's `hive_edit` says so too, rather
+  than reporting the file as shared. Move the key into `.env` and the file is shared on its next save.
+- **What the others in the room can do:** change any shared file, which then changes in your
+  folder too (claims stop two agents colliding, not a teammate), and message your agent, which acts
+  on it. Hivecode never runs anything on your machine, but what they write lands on your disk.
+  Invite only people you would let push to your repository.
+- **For code that must never leave your own machines,** run your own relay: `npx hivecode-relay`
+  (see [docs/SELF_HOSTING.md](docs/SELF_HOSTING.md)). Then nothing goes to ours.
+
+---
+
 ## Set up an AI agent (about 2 minutes)
 
 You need [Node.js](https://nodejs.org) 18 or newer. Then run this once, in any terminal:
@@ -52,8 +85,13 @@ Then:
 The agent's files go in `~/hivecode/<room>/<name>`, a folder of its own. To use a particular
 folder instead, add *"using the folder ./hive-alice"*.
 
-**Starting a brand-new room?** Paste: *"Use your hive_join tool to host a new Hivecode room as
-Alice-AI, then give me the join link."* It creates the room and prints the link for you to share.
+**Starting a brand-new room?** Paste: *"Use your hive_join tool to host a new, empty Hivecode
+room as Alice-AI, then give me the join link."* It creates an empty room and prints the link for
+you to share.
+
+**Bringing your project in?** Run `npx -y hivecode-mcp@latest branch fix-login` in the repo
+instead: see [Work on a git branch](#work-on-a-git-branch). Setup prints this line for you when
+you run it inside a repo.
 
 **Another MCP client?** Run the same command. If it doesn't know your app, it prints the exact
 entry to paste into that app's MCP settings, with the right paths for your machine.
@@ -90,12 +128,139 @@ From there you can:
 - **Chat** — start a message with `@Alice-AI` to address an agent directly
 - **Approve or deny** work that is waiting on you
 - **Pause or resume** any agent
-- **Restore or revert** — undo one file, or everything one agent did
+- **Restore or revert** — put one file back to an earlier point, or roll back every file one
+  agent touched. A revert takes each of those files back to before that agent's first edit, so
+  anyone else's later edits in them go too.
 
 To write code yourself, run your own AI agent (above) and join the same room.
 
 ---
 
+## Work on a git branch
+
+In a git repository, one command gives a branch its own room:
+
+```bash
+npx -y hivecode-mcp@latest branch fix-login
+```
+
+It creates the branch `fix-login` if it doesn't exist yet (your checkout is not switched), creates
+a room for it, fills the room with the branch's files, checks that a newcomer receives every one
+of them, and prints three lines: one for your agents, one for teammates, and one for when the
+work is done.
+
+- **Your agents:** *"Use hive_join with branch `fix-login`, repo `<path to the repo>`, as a name
+  of your own (each agent picks a different one)."* Each agent gets its own folder holding the
+  branch. Files a room does not carry (binaries, files over 1 MB, and any committed file that holds
+  a key or token) are filled in from git instead.
+- **A teammate**, in their own clone, after running setup once:
+  `npx -y hivecode-mcp@latest branch fix-login --join "<link>"`, then the same line for their agents.
+- **When the work is done:**
+
+  ```bash
+  npx -y hivecode-mcp@latest pr fix-login
+  ```
+
+  This lands the room's work on `fix-login` as one commit per agent, with each agent as the git
+  author. Files the agents deleted are deleted too. Add `--pr` to push the branch and open the
+  pull request (this needs [`gh`](https://cli.github.com)).
+
+The room's folders are deliberately **not git checkouts**: git refuses to run in them, so no
+`checkout`, `stash` or `clean` can rewrite files your teammates are working on. Work leaves only
+through `pr`, which builds the commits in a temporary worktree and never touches your checkout.
+If someone changed a file on the branch that the room also changed, `pr` refuses and names the
+commit rather than writing over it.
+
+The room's link is random, never the branch name, and like any room link it lets whoever has it
+read the room.
+
+---
+
+## Give an outside agent one folder
+
+When you bring in an outside agent or contractor, you may not want them seeing or editing your
+whole repository. In a token-secured room, the relay enforces path scopes at the network boundary:
+files outside the agent's scope never reach the agent, and attempts to touch them are refused at
+the wire.
+
+In a secured room (`HIVE_AUTH_MODE=required`), nobody joins without a token — including the host.
+You mint an unscoped token for yourself (a maintainer), and a scoped token for the outside agent.
+
+### 1. Run a secured relay
+
+Set the auth mode and secret once in your environment so the secret never appears in command arguments:
+
+**Bash:**
+```bash
+export HIVE_AUTH_MODE=required
+export HIVE_JWT_SECRET="your-secret"
+npx -y -p hivecode-relay hivecode-relay
+```
+
+**PowerShell:**
+```powershell
+$env:HIVE_AUTH_MODE='required'
+$env:HIVE_JWT_SECRET='your-secret'
+npx -y -p hivecode-relay hivecode-relay
+```
+
+> **Note on encryption:** `ws://127.0.0.1` is fine for trying it on your machine. For production
+> or remote use, run behind `wss://` (the privacy gate warns that non-loopback `ws://` connections
+> are unencrypted). `render.yaml` includes ready-to-uncomment `HIVE_AUTH_MODE` and `HIVE_JWT_SECRET`
+> variables.
+
+### 2. Mint tokens for yourself and the agent
+
+The relay is running in the first terminal, so open a second one and set `HIVE_JWT_SECRET` there
+the same way. `hivecode-token` reads it from the environment, so the secret isn't in the commands
+below. `<room>` is any room name you choose, for example `project-alpha`:
+
+**For yourself (the host — full access across the room):**
+```bash
+npx -y -p hivecode-relay hivecode-token --name Alice --room "<room>" --role maintainer
+```
+
+**For the outside agent (scoped only to `src/stripe/**`):**
+```bash
+npx -y -p hivecode-relay hivecode-token --name StripeAgent --room "<room>" --role agent --paths "src/stripe/**" --ttl 24h
+```
+
+The commands are the same in PowerShell.
+
+### 3. Join the room
+
+Join with your own token first, then invite the outside agent:
+
+> Use `hive_join` with link `wss://your-relay|<room>`, token `<token>`, as **StripeAgent**.
+
+### What the agent experiences
+
+The agent's access is verified and enforced directly at the relay boundary:
+
+1. **Unauthenticated access is blocked (401):** An agent trying to join without a token is refused immediately:
+   ```
+   NOT JOINED -- the relay refused the connection (401): this room needs a token of your own.
+   Ask the room owner to mint you one.
+   ```
+   If an expired or invalid token is supplied, the refusal names it directly:
+   ```
+   NOT JOINED -- the relay refused the connection (401): the relay rejected your token.
+   It may have expired -- ask the room owner for a new invite.
+   ```
+2. **In-scope files sync cleanly:** Within `src/stripe/**`, claims and edits work normally:
+   ```
+   claimed src/stripe/charge.js — it's yours.
+   ✓ wrote src/stripe/charge.js through the medium — your intent is signed into its provenance ledger.
+   ```
+3. **Out-of-scope files are refused at the wire:** If the agent attempts to claim or edit a file outside its scope (like `src/core/auth.js`):
+   ```
+   refusing to claim src/core/auth.js — your access token's scope does not cover src/core/auth.js, so its bytes stay in this folder
+   refusing to write src/core/auth.js through the medium — your access token's scope does not cover src/core/auth.js, so its bytes stay in this folder
+   ```
+   Out-of-scope files never touch the agent's disk, and writes never reach the room.
+
+---
+
 ## The rules agents follow
 
 Every agent is handed these when it joins. They are worth knowing as a person too:
@@ -108,6 +273,15 @@ Every agent is handed these when it joins. They are worth knowing as a person to
 | **Answer every question aimed at you.** | Silence looks exactly like "still thinking". |
 | **Wait with `hive_wait`** instead of ending your turn. | An agent that stops is unreachable; `hive_wait` wakes it the moment someone needs it. |
 
+**When an agent's turn ends anyway.** Claude Code and Antigravity agents are handed a listener
+command on their first quiet `hive_wait`. It runs in the background, costs nothing while it waits,
+and wakes the agent when someone addresses it, so it stays reachable after its turn. Every wake
+carries the command to start it again. On Claude Code, `setup` also adds a Stop hook
+(`hive-stop-hook.js`): an agent in a room cannot end its turn with no listener running, and is
+handed the command instead. To remove it: `npx -y -p hivecode-mcp@latest hivecode-hook uninstall --global`. In other apps (Cursor, Windsurf,
+Claude Desktop, Gemini CLI: not checked yet), an agent whose turn has ended hears nothing until
+you prompt it: tell it to check the room.
+
 ---
 
 ## Troubleshooting
@@ -116,6 +290,7 @@ Every agent is handed these when it joins. They are worth knowing as a person to
 |---|---|---|
 | the agent has no `hive_join` tool | Hivecode isn't loaded in that app yet | run `npx -y hivecode-mcp@latest setup` again, check it printed `READY` for your app, then reload the agent |
 | `setup` printed `FAILED` for an app | that app's config could not be written, or what was written does not start | the reason is on the same line, and the entry to add by hand is printed below it |
+| `npx` stops with `ENOENT` and `AppData\Roaming\npm` (Windows) | that folder is missing, which happens on some fresh Node installs, and npm gives up before Hivecode starts | create it with `mkdir "$env:APPDATA\npm"` in PowerShell (`mkdir "%APPDATA%\npm"` in cmd), then run setup again |
 | `'room-…' is not recognized` or `command not found: room-…` | a join link was pasted into a terminal without quotes | give the link to your agent instead; if you pass it to `setup`, quote it |
 | `NOT JOINED` and the address `livecode-xoss.onrender.com` | an old Hivecode version, still cached by `npx` | put `hivecode-mcp@latest` in your agent's config and restart it |
 | `Q430` | the relay is out of sockets | try again shortly; clients on the older one-socket-per-file transport (the VS Code extension, the browser panel) can lower `HIVE_MAX_OPEN_FILES` |
@@ -123,6 +298,11 @@ Every agent is handed these when it joins. They are worth knowing as a person to
 | `Q431` | this room is full | fewer participants in one room, or ask whoever runs the relay to raise `HIVE_SEATS` |
 | an agent says a file doesn't exist | very large rooms (over 4,096 files, or 128 on the older transport) keep only recently used files on disk | `hive_claim` the file, which downloads it. Do not create it again. |
 | `hive_members` doesn't list someone | they are not in the room | check they used the same link, in their own folder |
+| a file you had is gone | a teammate deleted it, and the delete reached your folder | your copy is in `.hive-deleted/<when>/` inside your room folder for 7 days; copy it back and it syncs again |
+| `Q581` | someone in the room already uses that name. Two participants under one name would share claims and mail | join again with the free name it suggests. If that was you a moment ago, wait 30 seconds and join again |
+| `Q580` | your room folder was deleted, moved, or emptied all at once. Nothing was deleted for anyone, and file sync stopped in that folder | call `hive_join` again with the same link: an empty folder is filled from the room |
+| the room says a file `stays on <name>'s machine, because it contains` a key | that file holds an API key or token the room does not have, so it was not shared (nor any change to it since) | move the key into `.env` and read it from the environment. The file is shared on its next save, with every edit made meanwhile |
+| the room says a file `could not be written on <name>'s disk` | that file is read-only or locked in their folder (a Perforce checkout, a generated file, another program holding it), so their copy is older than the room's. Everyone else's copy, and the room's, are fine | make it writable, or close what holds it. It is then written on its own, with no edit needed, and an edit made to the old copy meanwhile is merged, not lost |
 
 **Secured room?** Give the agent its token: pass `token` to `hive_join`, or set `HIVE_TOKEN`.
 

package/core.js

@@ -1,91 +1,91 @@
-// 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.
-
-import reconcilePkg from './reconcile.cjs'
-
-export const {
-  applyDiff,
-  hasConflictMarkers,
-  stripConflictMarkers,
-  merge3,
-  summarizeChange,
-  changedRange,
-  symbolsIn,
-  icrMerge3,
-  createReconciler,
-  reconcile
-} = reconcilePkg
-
-// 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`
-}
-
+// 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.
+
+import reconcilePkg from './reconcile.cjs'
+
+export const {
+  applyDiff,
+  hasConflictMarkers,
+  stripConflictMarkers,
+  merge3,
+  summarizeChange,
+  changedRange,
+  symbolsIn,
+  icrMerge3,
+  createReconciler,
+  reconcile
+} = reconcilePkg
+
+// 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`
+}
+

package/docs/HIVE_RULES.md

@@ -1,41 +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.
+# 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/docs/MCP.md

@@ -49,7 +49,7 @@ versions in one room can lose data, so do not ignore it. `HIVE_PRIVATE=1` or
 
 | 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_join` | Join/host a room for a folder. Auto-joins as an **AI** participant. Returns the room info **and the HIVE_RULES to follow**. With `branch` (and `repo`), joins the room bound to that git branch by `npx -y hivecode-mcp@latest branch <name>`, in a folder of its own. |
 | `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). |
@@ -59,7 +59,7 @@ versions in one room can lose data, so do not ignore it. `HIVE_PRIVATE=1` or
 
 ## 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.
+1. `hive_join` (with a `link`, a `branch` bound by `npx -y hivecode-mcp@latest branch`, 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.
@@ -94,8 +94,8 @@ it just wait. Nothing tells them.
 You cannot fix that with wording. Install the gate:
 
 ```
-npx hivecode-hook install            # this project
-npx hivecode-hook install --global   # every project
+npx -y -p hivecode-mcp@latest hivecode-hook install            # this project
+npx -y -p hivecode-mcp@latest hivecode-hook install --global   # every project
 ```
 
 That writes a Claude Code **`Stop` hook**. Claude Code runs it when the agent is
@@ -105,7 +105,7 @@ not get a vote — same difference as a claim the relay enforces versus a claim
 merely warns about.
 
 It merges into any existing `Stop` hooks rather than replacing them, and
-`npx hivecode-hook uninstall` removes it. It reads only local mirrored files
+`npx -y -p hivecode-mcp@latest hivecode-hook uninstall` removes it. It reads only local mirrored files
 (`HIVE_CHAT.md`, `HIVE_TASKS.md`), so it costs no network round trip and works with
 the relay unreachable.