hivecode-mcp 0.11.1 → 0.11.3

package/docs/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/docs/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/grm-link.cjs

@@ -0,0 +1,141 @@
+// Gives a Hivecode room a MEMORY, by handing its history to GRM.
+//
+// A room already records everything worth remembering -- HIVE_CHAT.md is the participants'
+// conversation, HIVE_BOARD.md is what was rewritten and by whom, HIVE_TASKS.md is the
+// directed work and its approvals. All of it is written to the room folder as ordinary
+// markdown. And GRM already indexes named files from `code_roots.txt`, re-read on every
+// watcher pass, so a path added here takes effect without restarting anything.
+//
+// So the two halves need no new format, daemon or protocol between them: name those files,
+// and an agent that joins the room tomorrow can ask what was decided in it last week --
+// including in conversations it was never present for. Neither product can do that alone.
+//
+// CommonJS on purpose. sync.js is ESM and the VS Code extension is CJS; a .cjs file is the
+// one shape both can load, so this exists ONCE. The duplicated reconcile()/HIVE_RULES text
+// across those two files has already drifted twice and cost real bugs -- not repeating it.
+
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const crypto = require('crypto')
+
+// The room's own record. NOT the room folder: `code_roots.txt` carries a warning written
+// after adding one directory appended 90,215 blocks in a single pass and had to be cut back
+// out of the journal -- "a root is a whole repository unless you check". Naming four files
+// gives the decision history and nothing else.
+const HISTORY_FILES = ['HIVE_CHAT.md', 'HIVE_BOARD.md', 'HIVE_TASKS.md', 'HIVE_MEMBERS.md']
+
+function grmHome() {
+  const env = (process.env.GRM_HOME || '').trim()
+  return env || path.join(os.homedir(), '.grm')
+}
+
+function rootsPath() {
+  return path.join(grmHome(), 'code_roots.txt')
+}
+
+// Keyed on the resolved directory so the same room in two folders gets two blocks, and the
+// same folder rejoined a hundred times keeps exactly one.
+function tagFor(dir) {
+  return 'hivecode:' + crypto.createHash('sha256').update(path.resolve(dir)).digest('hex').slice(0, 12)
+}
+
+// The file is written by GRM's installer with a UTF-8 BOM. GRM's own reader strips it, but
+// this must not *drop* it on the way through -- the file belongs to GRM, and a tool that
+// silently reformats another tool's config is how you get a bug nobody can find.
+function readRoots(p) {
+  const raw = fs.readFileSync(p, 'utf8')
+  return raw.charCodeAt(0) === 0xfeff ? { bom: '', body: raw.slice(1) } : { bom: '', body: raw }
+}
+
+function writeRootsAtomic(p, bom, body) {
+  const tmp = p + '.hivecode.tmp'
+  fs.writeFileSync(tmp, bom + body, 'utf8')
+  fs.renameSync(tmp, p) // the watcher re-reads on every pass; never let it see a half-written file
+}
+
+// Drop any block previously written for this room. Returns the body without it.
+function stripBlock(body, tag) {
+  const lines = body.split(/\r?\n/)
+  const out = []
+  let inside = false
+  for (const line of lines) {
+    if (!inside && line.startsWith('# >>> ' + tag)) { inside = true; continue }
+    if (inside) { if (line.startsWith('# <<< ' + tag)) inside = false; continue }
+    out.push(line)
+  }
+  return out.join('\n')
+}
+
+function blockFor(dir, tag, files) {
+  const head = `# >>> ${tag}  Hivecode room at ${path.resolve(dir)}`
+  const why = '#     Added by Hivecode so this room\'s decisions are in memory. Safe to delete.'
+  const tail = `# <<< ${tag}`
+  return [head, why, ...files, tail].join('\n')
+}
+
+/**
+ * Point GRM at this room's history. Idempotent and cheap: it rewrites `code_roots.txt`
+ * only when the set of existing history files has actually changed, so it is fine to call
+ * on every join and again whenever one of those files is written.
+ *
+ * Returns { linked, files, reason }. Never throws -- a memory that cannot be wired up is
+ * not a reason to fail somebody's join.
+ */
+function linkRoom(dir, log = () => {}) {
+  try {
+    const p = rootsPath()
+
+    // DO NOT CREATE THIS FILE. GRM's reader has three states, and they are not two:
+    // no file at all -> fall back to the default root; a file naming paths that all fail
+    // to resolve -> watch NOTHING, deliberately, so a typo is visible rather than buried.
+    // Creating one here containing only HIVE_*.md would therefore convert "GRM indexes my
+    // projects" into "GRM indexes this room and nothing else" the moment the paths lag
+    // behind the folder. Only ever append to a file GRM already owns.
+    if (!fs.existsSync(p)) return { linked: false, files: [], reason: 'GRM is not installed on this machine' }
+
+    const files = HISTORY_FILES
+      .map((f) => path.resolve(dir, f))
+      .filter((f) => { try { return fs.statSync(f).isFile() } catch { return false } })
+    if (!files.length) return { linked: false, files: [], reason: 'room has not written its history yet' }
+
+    const tag = tagFor(dir)
+    const { bom, body } = readRoots(p)
+    const stripped = stripBlock(body, tag)
+    const next = stripped.replace(/\s*$/, '') + '\n\n' + blockFor(dir, tag, files) + '\n'
+
+    if (bom + next === bom + body) return { linked: true, files, reason: 'already linked' } // no write, no watcher churn
+    writeRootsAtomic(p, bom, next)
+    log(`[hive] room history handed to GRM (${files.length} file(s)) -- agents here can now recall what this room decided before they joined.`)
+    return { linked: true, files, reason: 'linked' }
+  } catch (e) {
+    log(`[hive] could not hand this room's history to GRM: ${e && e.message}`)
+    return { linked: false, files: [], reason: String((e && e.message) || e) }
+  }
+}
+
+/**
+ * Remove this room from GRM's roots. Called on leave, so a room you are no longer in stops
+ * contributing to what your agents recall.
+ */
+function unlinkRoom(dir, log = () => {}) {
+  try {
+    const p = rootsPath()
+    if (!fs.existsSync(p)) return { unlinked: false, reason: 'GRM is not installed on this machine' }
+    const tag = tagFor(dir)
+    const { bom, body } = readRoots(p)
+    if (!body.includes('# >>> ' + tag)) return { unlinked: false, reason: 'was not linked' }
+    writeRootsAtomic(p, bom, stripBlock(body, tag).replace(/\s*$/, '') + '\n')
+    log('[hive] room history removed from GRM.')
+    return { unlinked: true, reason: 'unlinked' }
+  } catch (e) {
+    return { unlinked: false, reason: String((e && e.message) || e) }
+  }
+}
+
+/** Whether GRM is present at all -- used to decide whether to mention memory in the UI. */
+function grmPresent() {
+  try { return fs.existsSync(rootsPath()) } catch { return false }
+}
+
+module.exports = { linkRoom, unlinkRoom, grmPresent, rootsPath, HISTORY_FILES }

package/hive-coord.js

@@ -31,8 +31,19 @@
 
 export function makeCoordinator(shared, self, opts = {}) {
   const ttl = opts.ttl != null ? opts.ttl : 5000
+  // A holder may RENEW its own claim, because a long edit should not lose the file mid-write.
+  // But renewal cannot be unbounded, or the lease stops being a lease. MEASURED on a 12-agent
+  // run: one agent re-claimed site/pricing.md eight times and legal/terms.md seven times and
+  // released twice, and since `claim` reset `at` on every call the 60s TTL never once elapsed.
+  // Six other agents sensed a live owner for the whole run; sixteen messages asked it to let go.
+  // `since` records the FIRST acquisition and survives renewal, so what caps a claim is total
+  // hold time rather than time since the holder last touched it.
+  const maxHold = opts.maxHold != null ? opts.maxHold : ttl * 3
   const now = opts.now || (() => Date.now())
-  const expired = (c) => !c || (now() - c.at) >= c.ttl
+  const held = (c) => now() - (c.since != null ? c.since : c.at) // total, across renewals
+  const cap = (c) => (c.maxHold != null ? c.maxHold : maxHold)
+  const overheld = (c) => !!c && held(c) >= cap(c)
+  const expired = (c) => !c || (now() - c.at) >= c.ttl || overheld(c)
 
   // SENSE: the live, non-expired claim on a region (or null if open).
   const sense = (region) => { const c = shared.get(region); return expired(c) ? null : c }
@@ -40,7 +51,16 @@ export function makeCoordinator(shared, self, opts = {}) {
   // Is this region open to ME? (free, expired, or already mine)
   const free = (region) => { const c = shared.get(region); return expired(c) || c.by === self }
 
-  const claim = (region, intent) => { shared.set(region, { by: self, intent, at: now(), ttl }) }
+  // A renewal keeps the original `since`; a fresh acquisition starts a new one. Claims written
+  // before `since` existed fall back to `at`, so an older room stays readable.
+  const claim = (region, intent) => {
+    const prev = shared.get(region)
+    const renewing = !!prev && prev.by === self && !expired(prev)
+    shared.set(region, {
+      by: self, intent, at: now(), ttl, maxHold,
+      since: renewing ? (prev.since != null ? prev.since : prev.at) : now(),
+    })
+  }
   const release = (region) => { const c = shared.get(region); if (c && c.by === self) shared.delete(region) }
 
   // ACQUIRE one region: sense → claim → verify. Returns true iff I now hold it.
@@ -49,6 +69,13 @@ export function makeCoordinator(shared, self, opts = {}) {
   const acquire = (region, intent) => {
     const c = shared.get(region)
     if (c && !expired(c) && c.by !== self) return false // sensed an owner → defer
+    // Once total hold is exhausted the region is open to everyone — INCLUDING the outgoing
+    // holder, which could then win the re-claim race indefinitely and starve the waiters that
+    // maxHold exists to admit. So the overrunning holder stands down for a full maxHold, which
+    // is a window every waiter is guaranteed to poll inside. A single-ttl cooldown was tried
+    // first and is NOT enough: the holder just waits it out and opens a fresh `since`.
+    // The bar lapses on its own, so a file nobody else wants returns to its owner.
+    if (c && c.by === self && overheld(c) && held(c) < 2 * cap(c)) return false
     claim(region, intent)
     const after = shared.get(region)
     return !(after && after.by !== self) // verify: did my claim survive?

package/hive-mailbox.js

@@ -0,0 +1,173 @@
+// The room mailbox: what has this participant actually read?
+//
+// WHY THIS EXISTS. `hive_wait` used to capture `baseChatLen = chat.length` at the moment it
+// was CALLED, and only ever returned `chat.slice(baseChatLen)`. So anything posted between one
+// wait returning and the next one starting — which is precisely the window where an agent is
+// doing its work — sat below the cursor and was returned by NO code path. Not delayed:
+// unreachable. Two further holes finished the job: a wait that had queued work returned
+// `newChat: []` hardcoded, so the busiest agent in the room saw no messages at all; and
+// mention detection existed only for PAUSED agents, so a working agent could not tell "stop,
+// you are editing the wrong file" from two other agents chatting.
+//
+// Measured on a real four-agent build (JARVIS, 2026-07-28): 345 @mentions in the room log, 13
+// acknowledgements. The PM agent ended up replacing delivery with a bash script that tails
+// HIVE_CHAT.md, which is the verdict on the old design.
+//
+// So the cursor is now a persistent per-participant position that only advances over messages
+// that were actually handed to the agent. This module is deliberately pure — plain arrays in,
+// plain objects out, no Yjs and no I/O — so the delivery rules are unit-testable without a
+// relay, a room, or a network.
+
+/** A chat message as stored in the room: { by, kind, at, text }. */
+
+/**
+ * Does this text address `me`? Matches `@Name`, case-insensitively, at a word boundary so
+ * `@PM` does not swallow `@PM-Claude` and `@Hermes` does not match `@Hermes-2`.
+ * @param {string} text
+ * @param {string} me
+ */
+export function mentionsName(text, me) {
+  if (!text || !me) return false
+  const escaped = String(me).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  // Trailing boundary: end of string, or anything that cannot continue a name.
+  return new RegExp(`@${escaped}(?![\\w-])`, 'i').test(String(text))
+}
+
+/** Everyone addressed in a message, so a broadcast can be told from a direct call. */
+export function mentionedNames(text) {
+  return [...new Set([...String(text || '').matchAll(/@([\w-]+)/g)].map((m) => m[1]))]
+}
+
+/**
+ * How urgently does this message want attention?
+ *
+ *   'stop'   — act on it before finishing what you are doing
+ *   'normal' — read it at your next boundary
+ *
+ * A marker is an explicit prefix so it is unambiguous, plus a small set of words that mean
+ * stop in every room whether or not the sender knew about markers. An agent about to
+ * overwrite someone's work is not going to be helped by correct syntax.
+ */
+export function priorityOf(text) {
+  const s = String(text || '')
+  if (/^\s*\[!\]|^\s*\[stop\]/i.test(s)) return 'stop'
+  if (/\b(stop|halt|abort|don'?t\s+(?:edit|touch|write)|revert)\b/i.test(s)) return 'stop'
+  return 'normal'
+}
+
+/**
+ * Collapse runs of the identical message into one entry with a count.
+ *
+ * Not cosmetic. A conflict-notification feedback loop in the same live build put 56 copies of
+ * one "⚠ MERGE CONFLICT in Shell.jsx" line into the room in seconds, and 306 of the room's
+ * 2,314 chat lines were that loop. Handing an agent 56 identical lines costs it the context it
+ * needs to fix the actual problem, and buries the one message that mattered.
+ * @param {Array<{text?: string, by?: string}>} messages
+ */
+export function collapseRepeats(messages) {
+  const out = []
+  for (const m of messages || []) {
+    const last = out[out.length - 1]
+    if (last && last.by === m.by && last.text === m.text) {
+      last.repeated = (last.repeated || 1) + 1
+      last.at = m.at ?? last.at // keep the most recent timestamp
+      continue
+    }
+    out.push({ ...m })
+  }
+  return out
+}
+
+/**
+ * A read cursor over the room chat.
+ *
+ * @param {{me: string, startAt?: number}} options
+ *   me      this participant's display name
+ *   startAt where to begin. On a first join this is the current chat length, so an agent is
+ *           not handed the room's entire history; on a resume it is the persisted cursor, so
+ *           nothing posted while the process was down is lost.
+ */
+export function createMailbox({ me, startAt = 0 }) {
+  let cursor = Math.max(0, Number(startAt) || 0)
+
+  /** Read without consuming. `advance` is what `take` does; kept separate so a peek is safe. */
+  function collect(all, { advance }) {
+    const list = Array.isArray(all) ? all : []
+    // A cursor past the end means this position belongs to a different document — a room
+    // rebuilt from scratch, which the recovery procedure for a poisoned room requires. Reset
+    // to the beginning rather than clamping to the end: clamping would deliver nothing, for
+    // ever, silently. Re-reading a short fresh chat costs an agent a few lines; going
+    // permanently deaf costs it the room.
+    if (cursor > list.length) cursor = 0
+
+    const fresh = list.slice(cursor)
+    const end = list.length
+
+    // An agent's own messages are not mail. It used to be woken by its own hive_say, and in a
+    // notification storm most of the flood was self-authored — an agent filling its own inbox.
+    const incoming = fresh.filter((m) => m && m.by !== me)
+    const messages = collapseRepeats(incoming)
+    const mentions = messages.filter((m) => mentionsName(m.text, me))
+    const urgent = mentions.filter((m) => priorityOf(m.text) === 'stop')
+
+    if (advance) cursor = end
+
+    return {
+      messages,
+      mentions,
+      mentioned: mentions.length > 0,
+      priority: urgent.length ? 'stop' : 'normal',
+      unreadCount: incoming.length,
+      cursor,
+    }
+  }
+
+  return {
+    /** Current position, for persisting across process restarts. */
+    get cursor() { return cursor },
+    /** Move the cursor without delivering anything (used at join). */
+    seek(n) { cursor = Math.max(0, Number(n) || 0); return cursor },
+    /** Deliver everything unread and mark it read. Every return path must go through this. */
+    take(all) { return collect(all, { advance: true }) },
+    /** Look at what is unread without marking it read. */
+    peek(all) { return collect(all, { advance: false }) },
+    /** Is there anything at all? Cheap enough to call in a wake predicate. */
+    hasUnread(all) { return collect(all, { advance: false }).unreadCount > 0 },
+  }
+}
+
+/** One-line rendering used in tool output, with the repeat count when a run was collapsed. */
+export function formatMessage(m) {
+  const times = m.repeated > 1 ? `  (×${m.repeated})` : ''
+  return `${m.at || ''} ${m.by}(${m.kind || 'ai'}): ${m.text}${times}`
+}
+
+/**
+ * AMBIENT DIGEST -- what to do with room chatter nobody addressed to you.
+ *
+ * Un-addressed messages were handed to every agent in full, on every wake. In a room of N
+ * agents that means each one pays for the other N-1's conversation every single turn: O(N^2)
+ * context, so TOKEN COST -- not the relay -- becomes the real ceiling on room size. Measured:
+ * the relay holds 8 clients per room, converging in 1.0s on 45 MB. What actually stops a big
+ * room is this block of text.
+ *
+ * The COUNT stays exact and the newest messages still arrive in full. Only the older bodies
+ * are withheld, and the agent is told the number and how to read them, so nothing is hidden --
+ * it just stops being paid for unasked. An agent that wants the whole log calls hive_read_chat.
+ *
+ * Returns '' when there is nothing, so a caller can drop it with a falsy check.
+ */
+export function ambientDigest(messages, { keep = 4 } = {}) {
+  const list = Array.isArray(messages) ? messages : []
+  if (!list.length) return ''
+  const shown = keep > 0 ? list.slice(-keep) : []
+  const hidden = list.length - shown.length
+  const head = 'room activity (' + list.length +
+    (hidden ? ', newest ' + shown.length + ' shown' : '') + '):'
+  const tail = hidden
+    ? '\n... ' + hidden + ' earlier message(s) withheld to keep your context small'
+      + ' -- hive_read_chat for the full log'
+    : ''
+  if (!shown.length) return head + tail
+  return head + '\n' + shown.map(formatMessage).join('\n') + tail
+}

package/hive-mcp.js

@@ -34,7 +34,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 if (!process.env.HIVE_PROVENANCE) process.env.HIVE_PROVENANCE = 'on'
 if (!process.env.HIVE_FORK_GATE) process.env.HIVE_FORK_GATE = 'on'
 import { startSync, parseLink } from './sync.js'
-import { createMailbox, formatMessage, mentionsName, priorityOf } from './hive-mailbox.js'
+import { createMailbox, formatMessage, mentionsName, mentionedNames, priorityOf, ambientDigest } from './hive-mailbox.js'
 
 const DEFAULT_RELAY = process.env.HIVE_RELAY || 'wss://livecode-xoss.onrender.com'
 let session = null // { hive, room, relay, dir, name, mailbox }
@@ -88,7 +88,26 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
   // 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: () => {} })
+  // The ACCOUNT licence is passed through but NOT persisted to .hive.json above, and that
+  // asymmetry is deliberate. `.hive.json` sits in the project folder, so it gets committed
+  // and it gets shared -- fine for a room invite, which is what it is for, and wrong for a
+  // billing credential. startSync resolves the licence from $HIVE_LICENSE (this server's env
+  // block) or ~/.hivecode/config.json instead, both of which are per-machine.
+  // A refused folder lock must reach the AGENT as a readable instruction, not as a stack
+  // trace. An agent that gets an opaque failure retries, and two of them retrying on one
+  // folder is precisely the situation the lock exists to prevent.
+  let hive
+  try {
+    hive = startSync({ relay, room, dir, name, kind: 'ai', owner, token: useToken, log: () => {} })
+  } catch (e) {
+    if (e && e.code === 'EHIVELOCKED') {
+      return text(
+        `${e.message}\n\n` +
+        `Do NOT retry this folder. Either join with a different \`dir\`, or stop process ${e.pid} first.`,
+      )
+    }
+    throw e
+  }
   session = { hive, room, relay, dir, name, owner, mailbox: null }
   persistSession({ dir, name, owner }) // survive MCP host restarts (see tryResumeSession)
   // wait for the first sync so members/board/rules are ready
@@ -406,7 +425,20 @@ function enforceDcoLock(opts = {}) {
 // matters most here: an 0.10.0 client in a room with an 0.11.1 one is invisible in the audit
 // log while its roommate is named, so the room's own membership record disagrees with itself.
 // Also carries the ICR fix that stopped a whole-file rewrite duplicating every declaration.
-export const VERSION = '0.11.1'
+// VERSION is load-bearing, not cosmetic: the join message (see buildJoinReply) instructs every
+// arriving agent to announce it in chat, because a MIXED BUILD in one room causes data loss and
+// this is the only way anyone finds out. Hardcoding it meant that the moment package.json was
+// bumped the two disagreed silently -- so the one mechanism for detecting a mixed build was
+// itself reporting the wrong build. Read the truth instead; package.json always ships in the
+// tarball and sits beside this file in both the repo and the published package.
+// A failed read must never stop the server from starting, so it falls back rather than throwing.
+export const VERSION = (() => {
+  try {
+    const v = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version
+    if (typeof v === 'string' && v) return v
+  } catch { /* fall through */ }
+  return '0.0.0-unknown'
+})()
 const server = new Server({ name: 'hivecode', version: VERSION }, { capabilities: { tools: {} } })
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 async function dispatch(req) {
@@ -425,7 +457,18 @@ async function dispatch(req) {
         // a human reading the log, not just to the recipient's tool output.
         const body = args.urgent && !/^\s*\[!\]/.test(raw) ? `[!] ${raw}` : raw
         requireSession().hive.say(body)
-        return text(`sent: ${body}`)
+        // ADDRESSING IS THE PROTOCOL, and a rule an agent merely read is a rule it forgets once
+        // its context fills. So the tool itself answers back: a message that named nobody is
+        // reported as landing in everyone's ambient digest, where it is meant to be skipped.
+        // Immediate, per-call feedback, at the moment the mistake is made.
+        const named = mentionedNames(body)
+        if (!named.length) {
+          return text(`sent: ${body}\n\nNOBODY WAS ADDRESSED. This went to every agent's "room ` +
+            `activity", where they are told to skip it — so assume no one acts on it. Name the ` +
+            `agents you actually need with @Name (hive_members lists who is here). Use an ` +
+            `unaddressed message only for a genuine announcement to the whole room.`)
+        }
+        return text(`sent to ${named.map((n) => '@' + n).join(', ')}: ${body}`)
       }
       case 'hive_read_chat': {
         const me = requireSession().name
@@ -456,14 +499,35 @@ async function dispatch(req) {
         if (!got.unreadCount && !tasks.length) return text('✓ nothing waiting — nobody is calling you and you have no approved work. Carry on.')
         const parts = []
         if (got.priority === 'stop') {
+          // HANDLING URGENT MAIL COUNTS AS LIVENESS.
+          //
+          // Claims evaporate after 5 minutes so a crashed agent never deadlocks the room.
+          // But an agent that is preempted -- told to stop and deal with something else --
+          // is not crashed, it is obeying. Without this refresh it loses the file it was
+          // halfway through editing WHILE DOING WHAT IT WAS ASKED, another agent takes the
+          // claim, and it resumes writing into a region it no longer owns. The agent gets
+          // punished for complying, and the resulting clobber looks like a merge bug.
+          //
+          // Re-claiming a region you already hold is safe: acquire() only defers when a
+          // DIFFERENT owner holds it, so this refreshes `at` and never steals.
+          //
+          // One refresh buys another full TTL. A long interruption stays safe because the
+          // rules have the agent calling hive_check between steps of the urgent work too.
+          try {
+            for (const c of s.hive.claimsBoard()) {
+              if (c.by === s.name) s.hive.claim(c.region, c.intent || 'edit')
+            }
+          } catch { /* delivering the urgent message matters more than the refresh */ }
           parts.push('🛑 URGENT — someone needs you to STOP what you are doing and handle this FIRST:')
+          parts.push('(your claims were just refreshed — the files you hold stay yours while you deal with this)')
           parts.push(got.mentions.filter((m) => priorityOf(m.text) === 'stop').map(formatMessage).join('\n'))
         } else if (got.mentioned) {
           parts.push(`📣 ${got.mentions.length} message(s) addressed to YOU — answer at your next safe stopping point:`)
           parts.push(got.mentions.map(formatMessage).join('\n'))
         }
         const ambient = got.messages.filter((m) => !mentionsName(m.text, s.name))
-        if (ambient.length) parts.push(`room activity (${ambient.length}):\n` + ambient.map(formatMessage).join('\n'))
+        const dig = ambientDigest(ambient)
+        if (dig) parts.push(dig)
         if (tasks.length) parts.push(`approved work queued for you:\n${tasks.map(fmtTask).join('\n')}`)
         return text(parts.join('\n\n'))
       }
@@ -500,10 +564,10 @@ async function dispatch(req) {
         const mentionBlock = (r) => (r.mentions && r.mentions.length)
           ? `${r.priority === 'stop' ? '🛑 STOP — handle this BEFORE anything else' : '📣 ADDRESSED TO YOU'}:\n${r.mentions.map(formatMessage).join('\n')}`
           : ''
-        const ambientBlock = (r) => {
-          const rest = (r.messages || []).filter((m) => !mentionsName(m.text, me))
-          return rest.length ? `room activity:\n${rest.map(formatMessage).join('\n')}` : ''
-        }
+        // Both delivery paths go through the SAME digest. They used to format ambient traffic
+        // separately, which is how two copies of a rule drift apart -- the exact hazard that
+        // already bit the duplicated reconcile() and the two HIVE_RULES copies.
+        const ambientBlock = (r) => ambientDigest((r.messages || []).filter((m) => !mentionsName(m.text, me)))
 
         if (r && r.paused) {
           const parts = [mentionBlock(r), ambientBlock(r)].filter(Boolean)

package/icr.js

@@ -546,6 +546,11 @@ function spliceUnits(baseText, baseUnits, order, textByKey, opts = {}) {
     out += baseText.slice(cursor, to)
   }
 
+  // A KEY REPEATED IN `order` USED TO EMIT ITS UNIT AGAIN. `order` is assembled from both
+  // sides' unit lists, so any key present in both can appear twice, and each appearance
+  // wrote the declaration out. On a whole-file rewrite that is every declaration in the
+  // file, which is how a merge silently doubled a source file instead of merging it.
+  // Emit each unit exactly once, at its first ordered position.
   const seenKeys = new Set()
   for (const k of order) {
     if (seenKeys.has(k)) continue
@@ -556,6 +561,7 @@ function spliceUnits(baseText, baseUnits, order, textByKey, opts = {}) {
         emitGap(pos, u.start)
         pos = u.end
       }
+      // A missing key used to concatenate the string "undefined" into the source.
       const val = textByKey.get(k)
       if (val != null) out += val
     } else {