hivecode-mcp 0.11.1 → 0.11.2

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-mailbox.js

@@ -0,0 +1,143 @@
+// 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}`
+}

package/hive-mcp.js

@@ -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) {
@@ -456,7 +488,27 @@ 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:`)

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 {

package/lang-brace.js

@@ -31,6 +31,10 @@ function scannerAt(src, strings) {
 
 const isWS = (c) => c === ' ' || c === '\t' || c === '\r' || c === '\n'
 
+// Tokens that CONTINUE a declaration onto the next line and can never begin a new top-level
+// one. Used by topUnits to avoid cutting a declaration in half at a newline.
+const CONT = /^(?:__attribute__|__asm__|__asm|__declspec|noexcept|throw\s*\(|->)/
+
 // Extract top-level units [{start,end}] from src[from..to]. A unit is a maximal
 // declaration/statement at bracket depth 0: either a block (signature + balanced
 // {…}) or a statement ending at ';' or end-of-line.
@@ -52,7 +56,36 @@ function topUnits(src, strings, from = 0, to = src.length) {
       if (CLOSE[c]) { depth--; i++; if (depth <= 0 && sawBrace) { while (i < to && (src[i] === ' ' || src[i] === '\t')) i++; if (src[i] === ';') i++; break } continue }
       if (depth === 0) {
         if (c === ';') { i++; break }
-        if (c === '\n' && !sawBrace) break
+        if (c === '\n' && !sawBrace) {
+          // K&R / Allman / kernel style: the body's opening brace sits on the NEXT line, so
+          // this newline is INSIDE a declaration, not the end of one. Breaking here split
+          // every such function into two units — `stmt:<signature>` and `stmt:{` — with
+          // POSITIONAL keys, so any insertion elsewhere shifted the indices and re-paired
+          // body #N with signature #N+1. That silently produced code whose function bodies
+          // belonged to other functions, while braces stayed balanced so the parse gate
+          // passed. Measured at ~34% of real C merges before this fix.
+          // Look ahead past whitespace and comments: if a block follows, it belongs to us.
+          let k = i + 1
+          for (;;) {
+            while (k < to && isWS(src[k])) k++
+            const s2 = at(k)
+            if (s2 > k && (src[k] === '/' || src[k] === '#')) { k = s2; continue } // comment
+            break
+          }
+          if (k < to && src[k] === '{') { i++; continue } // keep scanning; the block joins this unit
+          // A declaration can also continue onto the next line WITHOUT a brace, e.g.
+          //     void addReplyErrorFormat(client *c, const char *fmt, ...)
+          //         __attribute__((format(printf, 2, 3)));
+          // Splitting there produced an orphan `__attribute__…;` unit whose text is IDENTICAL
+          // across many prototypes in a header, so the keys became positional (#2, #3, …) and
+          // shifted exactly like the signature/body case — orphaning attributes onto the wrong
+          // prototypes. Only tokens that can never BEGIN a new top-level declaration are listed
+          // here: `const`/`override`/`final` are deliberately excluded because in TS/Rust they
+          // legitimately start the next statement (the C++ uses of those end in `{`, which the
+          // brace lookahead above already handles).
+          if (k < to && CONT.test(src.slice(k, k + 16))) { i++; continue }
+          break
+        }
       }
       i++
     }
@@ -67,15 +100,33 @@ const VARD = /\b(const|let|var|val|static|final)\s+([A-Za-z_$][\w$]*)/
 // void main(String[] a)`, `std::string name()`): optional decorators + any number of
 // modifiers + an optional return-type token, then NAME(args){. The captured name is
 // the identifier directly before `(`.
-const METH = /^(?:@[\w.()]+\s+)*(?:(?:public|private|protected|internal|static|async|final|override|open|pub|suspend|inline|virtual|export|default|abstract|sealed|unsafe|extern|synchronized|native|constexpr)\s+)*(?:(?:function|fn|func|fun)\s+)?(?:[A-Za-z_$][\w$<>\[\].,:&*\s]*?\s+)?([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\s*\([^;{]*\)\s*(?:->[^{]+|:[^={]+)?\s*\{/
+// The return-type group ends with `[\s*&]+` rather than `\s+` so a pointer return type whose
+// star is attached to the NAME still parses: `struct sk_buff *alloc_skb(int n)` must key as
+// `alloc_skb`, not fall through to DECL and key as the return type `sk_buff`.
+// The `Class::` group makes C++ out-of-line member definitions keyable — `int Widget::render(…)`
+// keys as `render`. Without it every C++ method definition fell through to an unkeyed `stmt:`.
+const METH = /^(?:@[\w.()]+\s+)*(?:(?:public|private|protected|internal|static|async|final|override|open|pub|suspend|inline|virtual|export|default|abstract|sealed|unsafe|extern|synchronized|native|constexpr)\s+)*(?:(?:function|fn|func|fun)\s+)?(?:[A-Za-z_$][\w$<>\[\].,:&*\s]*?[\s*&]+)?(?:[A-Za-z_$][\w$]*\s*::\s*)*([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\s*\([^;{]*\)(?:\s*(?:const|noexcept|override|final|volatile|mutable|&&?|throw\s*\([^){]*\)))*\s*(?:->[^{]+|:[^={]+)?\s*\{/
 // control-flow headers also look like `name (…) {` — never key them as methods
 const CTRL = new Set(['if', 'for', 'while', 'switch', 'catch', 'do', 'else', 'try', 'return', 'new', 'throw', 'match', 'select', 'when', 'until', 'lock', 'using', 'foreach', 'with'])
 
 function keyOf(text) {
   const head = text.replace(/^\s+/, '')
-  let m = head.match(DECL); if (m) return m[1] + ':' + m[2]
-  m = head.match(METH); if (m && !CTRL.has(m[1])) return 'method:' + m[1]
-  m = head.match(VARD); if (m) return 'var:' + m[2]
+  // DECL and METH can both match one declaration, and which is RIGHT depends on whether they
+  // agree on the name:
+  //   `function a() {`              -> both say "a"        -> keep DECL's richer `function:a`
+  //   `struct sk_buff *alloc_skb(`  -> DECL says "sk_buff",
+  //                                    METH says "alloc_skb" -> DECL matched the RETURN TYPE,
+  //                                    so METH wins and the key names the function.
+  // Preferring DECL unconditionally (the original order) meant every pointer-returning C
+  // function was keyed by its return type, feeding the rename/dangling logic wrong names.
+  const meth = head.match(METH)
+  const decl = head.match(DECL)
+  if (meth && !CTRL.has(meth[1])) {
+    if (decl && decl[2] === meth[1]) return decl[1] + ':' + decl[2]
+    return 'method:' + meth[1]
+  }
+  if (decl) return decl[1] + ':' + decl[2]
+  const m = head.match(VARD); if (m) return 'var:' + m[2]
   return 'stmt:' + head.split('\n')[0].trim().replace(/\s+/g, ' ')
 }
 
@@ -130,16 +181,30 @@ function isRefToken(src, t) {
 function balanced(src, strings) {
   const at = scannerAt(src, strings)
   const stack = []
+  let cpp = 0            // #if/#ifdef/#ifndef nesting depth
+  let lineStart = true   // only whitespace seen so far on this line
   let i = 0
   while (i < src.length) {
     const s = at(i)
-    if (s > i) { if (s > src.length) return false; i = s; continue }
+    if (s > i) { if (s > src.length) return false; i = s; lineStart = false; continue }
     const c = src[i]
     if (OPEN[c]) stack.push(c)
     else if (CLOSE[c]) { if (stack.pop() !== CLOSE[c]) return false }
+    // PREPROCESSOR NESTING. Brace balance alone cannot see a dropped `#endif`: the merged
+    // text stays perfectly brace-balanced while the conditional structure is broken, so the
+    // gate passed and invalid C shipped as clean. Directives are matched only at the start
+    // of a line, so `#[derive]`, `#region` and `#` inside strings/comments are unaffected
+    // (strings and comments are skipped by the scanner above).
+    else if (c === '#' && lineStart) {
+      const rest = src.slice(i + 1, i + 12).replace(/^\s+/, '')
+      if (/^(ifdef|ifndef|if)\b/.test(rest)) cpp++
+      else if (/^endif\b/.test(rest)) { cpp--; if (cpp < 0) return false }
+    }
+    if (c === '\n') lineStart = true
+    else if (c !== ' ' && c !== '\t' && c !== '\r') lineStart = false
     i++
   }
-  return stack.length === 0
+  return stack.length === 0 && cpp === 0
 }
 
 export function makeBraceLanguage({ id, exts, strings = ['"', "'", '`'] }) {