hivecode-mcp 0.6.0 → 0.7.0

package/README.md

@@ -1,10 +1,10 @@
 <h1>Hivecode</h1>
 
-**Multiplayer for your AI coding agents — with real permissions.**
+**Oversight and control for your AI coding agents.**
 
-Run humans and multiple AI agents on one live codebase. Folder-scoped access,
-approval gates, instant revoke. No git push/pull — edits sync in about a second.
-Open source.
+Run AI agents on your codebase and actually stay in control: **watch** every edit
+live, **fence** each agent to the folders it's allowed in, **approve** the risky
+moves, and **undo** any agent instantly. No git push/pull. Open source.
 
 [**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
 · [**Website**](https://livecode-xoss.onrender.com)
@@ -16,16 +16,21 @@ Open source.
 
 ## Why
 
-The moment you point more than one AI agent at a project, it gets messy: they
-overwrite each other's files, rebuild the same feature twice, and every agent can
-touch every file — secrets, configs, infra included. Today people juggle git
-worktrees and pray at merge time.
+You can't trust an AI agent blindly. The faster it edits, the more you have to
+check — and the moment you run more than one, it gets worse: they touch files they
+shouldn't, overwrite each other, and you lose track of who changed what. Today's
+answer is to isolate each agent in a git worktree and pray at merge time — which
+doesn't help you *trust* the output, it just defers the mess.
 
-Hivecode is a shared **live room** where humans and agents edit one project
-together — but with real access control. You decide what each agent can reach, and
-the relay enforces it; an out-of-scope agent never even receives the bytes.
+Hivecode adds the missing layer: **oversight and control.**
 
-It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP.
+- **See everything** — a live Control Room (browser or phone) shows every agent and every file it touches, in real time.
+- **Fence them in** — folder-scoped access the relay enforces; an out-of-scope agent never even receives the code.
+- **Approve what matters** — gate risky work so nothing lands without your OK.
+- **Undo anything** — instant rollback: restore any file, or revert *everything* one agent did.
+
+It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP. No
+git push/pull — edits sync in about a second.
 
 ---
 
@@ -47,24 +52,33 @@ Use **Manage access** to re-scope or revoke anyone, and **Leave Session** to sto
 
 ## Add an AI agent
 
-Agents join through the Hivecode MCP server ([`hive-mcp.js`](hive-mcp.js)). Point
-your agent's MCP config at it and hand it the join link; it appears in the room as
-an `ai` member, scoped to exactly the folders you invited it to. The agent gets
-tools to read chat, the task board, and members; to claim and complete tasks; to
-talk; and to wait for work. See [MCP.md](MCP.md) for setup.
+Agents join through the Hivecode MCP server ([`hive-mcp.js`](hive-mcp.js)). Set it
+up once, then just hand the agent a join link; it appears in the room as an `ai`
+member, scoped to exactly the folders you invited it to.
+
+- **[JOIN_WITH_AGENT.md](JOIN_WITH_AGENT.md)** — step-by-step for a *human*: set up MCP, then bring your agent in.
+- **[AGENT_MANUAL.md](AGENT_MANUAL.md)** — written *for the agent*: how to set itself up and join (drop it in your project as `CLAUDE.md` so the agent reads it automatically).
+- **[MCP.md](MCP.md)** — the full tool reference.
 
 ---
 
 ## What you get
 
-**Governance**
+**Oversight & control** *(the point of the whole thing)*
+- **Live Control Room** — watch every agent and every file it touches in real time,
+  from any browser or your phone. No more "what is it even doing right now?"
 - **Folder-scoped access** — invite an agent to `frontend/` only; it never receives
-  anything else.
-- **Approval gates** — a human's request to *your* agent waits for your OK;
-  agent-to-agent coordination flows automatically.
-- **Read-only roles** — reviewers see everything, change nothing.
+  anything else (relay-enforced, not trust-based).
+- **Approval gates** — risky work waits for your OK; agent-to-agent coordination
+  flows automatically.
+- **Instant rollback** — restore any file to an earlier point, or **revert
+  *everything* one agent did** in a click. Undo a rogue agent without touching the
+  rest of the team's work.
+- **Mission control** — pause, resume, or reassign any agent; agents honor it
+  mid-task.
 - **Instant revoke** — cut access mid-session, enforced server-side on every
   reconnect (and it survives a relay restart).
+- **Read-only roles** — reviewers see everything, change nothing.
 
 **Coordination**
 - **Built-in chat**, a **shared task board** (assign / complete), and **live
@@ -72,8 +86,6 @@ talk; and to wait for work. See [MCP.md](MCP.md) for setup.
 - **Co-editing heads-up** before two people touch the same file.
 - **Never lose work** — overlapping edits keep both versions with conflict markers;
   a stale rewrite can't silently delete another's lines.
-- **Mission control** — pause, resume, or reassign any agent; agents honor it
-  mid-task.
 
 **Trust**
 - **Server-enforced auth** — signed tokens, algorithm-pinned, fail-closed.

package/hive-coord.js

@@ -0,0 +1,72 @@
+// hive-coord.js — the Hive coordination layer (v0 prototype).
+//
+// The bet: AI coding agents work fast and BLIND — they collide because, unlike a human
+// team, they have no way to coordinate BEFORE they edit. Merging (ICR) cleans up after a
+// collision. This prevents the collision in the first place.
+//
+// The design is a real hive: NO central controller, no conductor, no extra agent. Order
+// emerges from each agent following one local rule against a shared medium — exactly how
+// bees coordinate via traces in the environment (stigmergy), and how millions of Ethernet
+// devices share one wire with no master (carrier-sense / collision-detect / backoff).
+//
+// The shared medium is a CRDT map living IN the codebase doc (a Y.Map in Hivecode; a plain
+// Map in tests). Each region of work (a file, or a unit) can hold one CLAIM:
+//     { by: agentId, intent: string, at: time, ttl: ms }
+//
+// An agent's entire protocol — no coordinator anywhere:
+//   1. SENSE   — read the shared map. Is my target region claimed and fresh?
+//   2. FLOW    — if taken, move to open space (pick another free region). This is the
+//                emergent load-balancing: agents spread across the codebase on their own.
+//   3. CLAIM   — write my claim to the free region.
+//   4. VERIFY  — re-read (collision-detect): if a concurrent claim beat mine, BACK OFF and
+//                retry later. (Like Ethernet: listen, send, detect collision, back off.)
+//   5. RELEASE — when done, delete my claim and (optionally) leave a "done" trace.
+//
+// EVAPORATION: claims carry a TTL. A crashed or stalled agent's claim simply expires, and
+// the region frees itself — no central garbage collector, no deadlock. (The pheromone fades.)
+//
+// `shared` is any object with get(key)/set(key,val)/delete(key)/entries() — so the same
+// code runs on a JS Map (tests) and a Yjs Y.Map (production). `now` is injectable so tests
+// can drive a deterministic virtual clock.
+
+export function makeCoordinator(shared, self, opts = {}) {
+  const ttl = opts.ttl != null ? opts.ttl : 5000
+  const now = opts.now || (() => Date.now())
+  const expired = (c) => !c || (now() - c.at) >= c.ttl
+
+  // 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 }
+
+  // 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 }) }
+  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.
+  // The verify step is the collision-detector: if a concurrent writer won the region,
+  // I see their id on re-read and concede.
+  const acquire = (region, intent) => {
+    const c = shared.get(region)
+    if (c && !expired(c) && c.by !== self) return false // sensed an owner → defer
+    claim(region, intent)
+    const after = shared.get(region)
+    return !(after && after.by !== self) // verify: did my claim survive?
+  }
+
+  // FLOW to open space: try my preferred regions in order, take the first I can acquire.
+  // This is what makes the swarm spread out with nobody assigning work.
+  const acquireAny = (candidates, intent) => {
+    for (const r of candidates) if (acquire(r, intent)) return r
+    return null
+  }
+
+  // Everything currently claimed (live), as a snapshot — for awareness / a Control Room.
+  const board = () => {
+    const out = []
+    for (const [region, c] of shared.entries()) if (!expired(c)) out.push({ region, ...c })
+    return out
+  }
+
+  return { sense, free, claim, release, acquire, acquireAny, board }
+}

package/hive-mcp.js

@@ -142,6 +142,12 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'how many recent messages (default 30)' } } } },
   { name: 'hive_read_board', description: 'Read recent whole-file rewrites (who rewrote what, which symbols). Read this before editing a file — if it was just rewritten, re-read the file first.',
     inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_claim', description: 'CLAIM a file (or region) BEFORE you edit it, so other agents flow around you instead of colliding. Returns whether you got it — if false, someone else holds it: work on something else. Claims auto-expire, so call hive_release when done (or it frees itself).',
+    inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'the file path (or region id) you want to edit' }, intent: { type: 'string', description: 'short note on what you intend to do' } }, required: ['region'] } },
+  { name: 'hive_release', description: 'Release a file/region you claimed, so other agents can take it. Call this when you finish editing it.',
+    inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'the file path (or region id) to release' } }, required: ['region'] } },
+  { name: 'hive_claims', description: 'See what every agent is currently working on (the live claim board). Read this to pick open work and avoid taken regions.',
+    inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_members', description: 'List who is currently in the room (humans and AI agents).', inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_status', description: 'Show the current session (room, relay, folder, name).', inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_leave', description: 'Leave the room and stop syncing.', inputSchema: { type: 'object', properties: {} } },
@@ -186,6 +192,15 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'hive_approve': { const r = requireSession().hive.decide(String(args.id), true); return r.ok ? text(`approved ${args.id}`) : err(r.error) }
       case 'hive_deny': { const r = requireSession().hive.decide(String(args.id), false); return r.ok ? text(`denied ${args.id}`) : err(r.error) }
       case 'hive_complete': { const r = requireSession().hive.complete(String(args.id), String(args.note || '')); return r.ok ? text(`completed ${args.id}`) : err(r.error) }
+      case 'hive_claim': {
+        const region = String(args.region || ''); if (!region) return err('need a region (file path)')
+        const got = requireSession().hive.claim(region, String(args.intent || 'edit'))
+        if (got) return text(`claimed ${region} — it's yours. Edit it, then call hive_release.`)
+        const c = requireSession().hive.senseClaim(region)
+        return text(`could NOT claim ${region}${c ? ` — held by ${c.by}${c.intent ? ` (${c.intent})` : ''}` : ''}. Work on something else; check hive_claims for open files.`)
+      }
+      case 'hive_release': { const region = String(args.region || ''); if (!region) return err('need a region'); requireSession().hive.release(region); return text(`released ${region}`) }
+      case 'hive_claims': { const b = requireSession().hive.claimsBoard(); return text(b.length ? b.map((c) => `${c.region} — ${c.by}${c.intent ? ` (${c.intent})` : ''}`).join('\n') : '(nothing claimed right now — all open)') }
       case 'hive_members': { const now = Date.now(); return text(requireSession().hive.members().map((m) => `${m.name} (${m.kind})${m.editing && now - m.editing.at < 15000 ? ` — editing ${m.editing.file}` : ''}`).join('\n') || '(none)') }
       case 'hive_status': { const s = requireSession(); return text({ room: s.room, relay: s.relay, dir: s.dir, name: s.name }) }
       case 'hive_leave': { requireSession().hive.stop(); session = null; return text('left the room') }

package/icr-merge.js

@@ -0,0 +1,58 @@
+// icr-merge.js — the bridge that brings ICR into the live product, SAFELY.
+//
+// Hivecode's reconcile() merges concurrent edits with merge3() (a line-level 3-way
+// merge). merge3 is convergent: across many peers it always settles on one canonical
+// text. ICR's structural merge produces a DIFFERENT canonical form (it may reorder or
+// reformat). Mixing two merge algorithms in a live multi-peer sync means the same logical
+// content has two byte-forms, and peers ping-pong between them — which corrupts files
+// (duplicated/*dropped* lines). So we do NOT change merge bytes with ICR here.
+//
+// Instead ICR runs in ADVISORY mode: merge3 still produces the bytes (full convergence
+// preserved, identical to pre-ICR behavior), and ICR runs alongside purely to DETECT the
+// meaning-level problems a line merge can't see — a dangling reference, a rename, a
+// same-declaration clash — and surface them as a warning on the activity feed. This ships
+// ICR's core value (catching semantic breaks) with zero divergence risk.
+//
+// ICR's full structural/rename AUTO-MERGE lives in the library (icr.js) and is proven by
+// the test suite + fuzzer; turning it on in the product is a later step that needs a
+// format-preserving, single-canonical-form merge so peers can't diverge.
+
+import { structuralMerge, supports } from './icr.js'
+import { merge3 } from './core.js'
+
+// Turn ICR's machine conflict keys into a human sentence for the activity feed / chat.
+function describeConflicts(conflicts) {
+  return (conflicts || []).map((c) => {
+    if (c.startsWith('ref:')) return `'${c.slice(4)}' was removed or renamed but is still used`
+    if (c.startsWith('fn:')) return `both sides changed function ${c.slice(3)}`
+    if (c.startsWith('class:')) return `both sides changed class ${c.slice(6)}`
+    if (c.startsWith('var:')) return `both sides changed ${c.slice(4)}`
+    return `both sides changed ${c}`
+  }).join('; ')
+}
+
+// Same shape as merge3 — { text, conflict } — plus an `icr` tag ('structural'|'rename')
+// and an optional `icrWarning`. ICR's format-preserving merge is convergent (symmetric +
+// fixed-point, verified by icr-converge-test.js), so its 'auto' result is used as the
+// merged bytes for supported files; merge3 covers conflicts, fallbacks, and other languages.
+export function icrMerge3(base, mine, theirs, relPath) {
+  const lm = merge3(base, mine, theirs)
+  if (!supports(relPath)) return lm
+
+  let r
+  try { r = structuralMerge(base, mine, theirs, { filename: relPath }) }
+  catch { return lm } // ICR must never break a sync
+
+  if (r.status === 'auto') {
+    const renamed = r.renames && r.renames.length
+    return {
+      text: r.text, conflict: false, icr: renamed ? 'rename' : 'structural',
+      icrWarning: renamed ? `auto-applied rename ${r.renames.join(', ')} — call sites updated` : undefined,
+    }
+  }
+  // A meaning-level conflict the line merge can't represent (dangling ref / clash): keep
+  // the safe line-merge bytes, but surface what ICR caught so it isn't shipped silently.
+  if (r.status === 'semantic-conflict')
+    return { ...lm, icrWarning: describeConflicts(r.conflicts) }
+  return lm // 'fallback'
+}

package/icr.js

@@ -0,0 +1,267 @@
+// ICR — Intent-aware Code Replication (v1 proof-of-concept).
+//
+// The first real step from Hivecode-the-tool toward a FOUNDATIONAL primitive:
+// merge code by STRUCTURE and INTENT, not characters, with a hard guarantee — never
+// emit code more broken than its inputs.
+//
+// Why this matters: CRDTs (Yjs) merge characters. They will happily fuse two edits
+// into syntactically-valid garbage, because they have no idea what code MEANS. ICR
+// parses the code, merges at the level of declarations (functions / classes / vars),
+// descends INTO a declaration both sides touched (so disjoint edits inside one function
+// still merge), detects when two authors changed the SAME thing (a real conflict), and
+// validates that the merged result still parses — falling back safely if it wouldn't.
+//
+// On top of structure it adds an INTENT layer:
+//   • RENAME DETECTION — a declaration gone from base whose identical-bodied twin appears
+//     under a new name is recognized as a rename; stale call sites are rewritten so the
+//     other agent's fresh calls keep working. Nothing else does this.
+//   • DANGLING REFERENCE — a declaration removed/renamed but still referenced is flagged
+//     as a semantic conflict even though the code parses. CRDTs/git/plain merge miss it.
+//
+// LANGUAGE-AGNOSTIC BY DESIGN: this file is the engine. Everything that knows about a
+// specific language (how to parse, what a declaration is, how to find references) lives
+// behind a provider (see lang-js.js). Adding Python/Go/Rust = writing another provider
+// and registerLanguage()-ing it; the merge logic below never changes. JavaScript via
+// `acorn` is simply the first provider. The production path swaps in tree-sitter
+// providers for every language behind this same interface.
+
+import { javascript } from './lang-js.js'
+
+// --- language registry ----------------------------------------------------------
+const LANGUAGES = [javascript]
+
+// Register an additional language provider. Must expose the provider contract:
+// { id, exts:[...], parses, units, declaredNames, usedIdentifiers, declBody,
+//   renameRefs, fnParts }. Newest wins on extension clashes.
+export function registerLanguage(provider) { LANGUAGES.unshift(provider) }
+
+function extname(p) { const m = /\.[^.\/\\]+$/.exec(p || ''); return m ? m[0].toLowerCase() : '' }
+
+// The provider for a filename, or null if no registered language claims its extension.
+export function languageFor(filename) {
+  const e = extname(filename)
+  return LANGUAGES.find((l) => l.exts.includes(e)) || null
+}
+
+// Can ICR merge this file structurally? (Callers gate on this before trying.)
+export function supports(filename) { return languageFor(filename) != null }
+
+// --- generic merge primitives (language-independent: operate on {key,text}) -----
+const mapOf = (us) => new Map(us.map((u) => [u.key, u.text]))
+function dedupeOrder(keys) { const seen = new Set(), out = []; for (const k of keys) if (!seen.has(k)) { seen.add(k); out.push(k) } return out }
+
+// For a given unit, choose which version survives: whoever CHANGED it wins; if neither
+// changed it, keep the base.
+function pick(k, B, A, Bb) {
+  const base = B.has(k) ? B.get(k) : null
+  const a = A.has(k) ? A.get(k) : null
+  const b = Bb.has(k) ? Bb.get(k) : null
+  if (a != null && a !== base) return a
+  if (b != null && b !== base) return b
+  return base != null ? base : (a != null ? a : b)
+}
+
+// Core 3-way merge over a KEYED list of units (works at file level AND, recursively,
+// inside a single declaration). Returns { conflicts:[...], parts:[...text] }.
+// When both sides change the SAME key into different things, it first tries to descend
+// INTO that unit (finer granularity) — only a clash it can't resolve becomes a conflict.
+function mergeKeyed(lang, baseU, aU, bU) {
+  const B = mapOf(baseU), A = mapOf(aU), Bb = mapOf(bU)
+  const keys = dedupeOrder([...baseU.map((u) => u.key), ...aU.map((u) => u.key), ...bU.map((u) => u.key)])
+
+  const conflicts = [], resolved = new Map()
+  for (const k of keys) {
+    const bs = B.has(k) ? B.get(k) : null
+    const as_ = A.has(k) ? A.get(k) : null
+    const bbs = Bb.has(k) ? Bb.get(k) : null
+    const changedA = as_ !== bs, changedB = bbs !== bs
+    if (changedA && changedB && as_ !== bbs) {
+      // Both touched the same unit, differently. Try finer-grained inner merge first.
+      if (bs != null && as_ != null && bbs != null) {
+        const inner = tryInnerMerge(lang, bs, as_, bbs)
+        if (inner != null) { resolved.set(k, inner); continue }
+      }
+      conflicts.push(k)
+    }
+  }
+  if (conflicts.length) return { conflicts, parts: [] }
+
+  // No unresolved clashes → decide which keys survive, honoring one-sided deletions.
+  const survives = new Set()
+  for (const k of keys) {
+    const inBase = B.has(k), inA = A.has(k), inB2 = Bb.has(k)
+    if (inBase && (!inA || !inB2)) {
+      const deletedByA = !inA, deletedByB = !inB2
+      const otherUnchangedFromBase =
+        (deletedByA && (!inB2 || Bb.get(k) === B.get(k))) ||
+        (deletedByB && (!inA || A.get(k) === B.get(k)))
+      if (otherUnchangedFromBase) continue // accept the deletion
+    }
+    survives.add(k)
+  }
+
+  // CONVERGENCE: the output order must be IDENTICAL no matter which side is `a` vs `b`,
+  // or two peers compute different text and never settle (then re-merging the divergence
+  // corrupts the file). So: surviving base units keep their base order; units added by a
+  // side are appended in a canonical (sorted) order — deterministic and symmetric.
+  const baseOrder = dedupeOrder(baseU.map((u) => u.key))
+  const baseSet = new Set(baseOrder)
+  const final = []
+  for (const k of baseOrder) if (survives.has(k)) final.push(k)
+  for (const k of [...survives].filter((k) => !baseSet.has(k)).sort()) final.push(k)
+
+  // Assemble, recording PROVENANCE per surviving unit: who authored the version we kept
+  // ('a' / 'b' changed it, 'both' if we merged inside it, 'base' if unchanged).
+  const parts = [], provenance = [], order = [], textByKey = new Map()
+  for (const k of final) {
+    let text, from
+    if (resolved.has(k)) { text = resolved.get(k); from = 'both' }
+    else {
+      text = pick(k, B, A, Bb)
+      const bs = B.has(k) ? B.get(k) : null, as_ = A.has(k) ? A.get(k) : null, bbs = Bb.has(k) ? Bb.get(k) : null
+      from = (as_ != null && as_ !== bs) ? 'a' : (bbs != null && bbs !== bs) ? 'b' : 'base'
+    }
+    if (text != null) { parts.push(text); provenance.push({ key: k, from }); order.push(k); textByKey.set(k, text) }
+  }
+  return { conflicts: [], parts, provenance, order, textByKey }
+}
+
+// FINER GRANULARITY: both sides edited the same function OR class. If the signature
+// matches and they edited DIFFERENT inner units (statements / class members), merge those
+// recursively rather than declaring the whole declaration a conflict. Returns merged
+// text, or null meaning "couldn't safely merge inside — treat as a real conflict."
+function tryInnerMerge(lang, baseText, aText, bText) {
+  // Language-specific same-key merges first (e.g. unioning import specifiers).
+  if (lang.mergeUnit) {
+    const t = lang.mergeUnit(baseText, aText, bText)
+    if (t != null && lang.parses(t)) return t
+  }
+  if (!lang.splitUnit) return null
+  const pb = lang.splitUnit(baseText), pa = lang.splitUnit(aText), pbb = lang.splitUnit(bText)
+  if (!pb || !pa || !pbb) return null
+  if (pa.sig.trim() !== pbb.sig.trim()) return null // signature itself changed → real conflict
+  const m = mergeKeyed(lang, pb.units, pa.units, pbb.units)
+  if (m.conflicts.length) return null
+  const text = pa.sig + pa.open + m.parts.join(pa.join) + pa.close
+  const valid = lang.parsesUnit || lang.parses // accept class-member fragments when supported
+  return valid(text) ? text : null
+}
+
+// FORMAT-PRESERVING assembly: rebuild the merged file by splicing the merged units back
+// into the BASE text at their original byte ranges. Unchanged units — and all the
+// whitespace/comments BETWEEN units — survive verbatim; only changed units carry the
+// editing side's bytes, and genuinely new units are appended. This is what stops ICR from
+// reformatting code it merges. Deterministic and symmetric, so peers converge.
+function spliceUnits(baseText, baseUnits, order, textByKey) {
+  const baseKeySet = new Set(baseUnits.map((u) => u.key))
+  const surviving = new Set(order.filter((k) => baseKeySet.has(k)))
+  const emitted = new Set()
+  let out = '', pos = 0
+  for (const u of baseUnits) {
+    out += baseText.slice(pos, u.start) // gap before this unit (comments/blank lines), verbatim
+    if (surviving.has(u.key) && !emitted.has(u.key)) { out += textByKey.get(u.key); emitted.add(u.key) }
+    pos = u.end
+  }
+  const added = order.filter((k) => !baseKeySet.has(k))
+  if (added.length) {
+    const head = out.replace(/\s*$/, '')
+    out = (head ? head + '\n\n' : '') + added.map((k) => textByKey.get(k)).join('\n\n') + '\n'
+  } else {
+    out += baseText.slice(pos) // trailing whitespace (final newline) verbatim
+  }
+  return out.replace(/^\n+/, '') // drop orphan leading blank lines left by a deleted first unit
+}
+
+// --- public API -----------------------------------------------------------------
+
+// Does this source parse under the given (or default JS) language?
+export function parses(src, lang = javascript) { return lang.parses(src) }
+
+// 3-way STRUCTURAL + INTENT merge of `a` and `b` against common ancestor `base`.
+// opts: { lang } a provider, or { filename } to pick one by extension (defaults to JS).
+// Returns { status, text, conflicts, renames? }:
+//   'auto'              — clean merge; `text` is valid, parseable code.
+//   'semantic-conflict' — same declaration changed both sides, or a dangling reference;
+//                         `conflicts` names them (e.g. ['fn:login'] or ['ref:helper']).
+//   'fallback'          — couldn't merge safely (unparseable input, or the merge wouldn't
+//                         parse, or unsupported language); caller keeps both. Never broken.
+export function structuralMerge(base, a, b, opts = {}) {
+  const lang = opts.lang || (opts.filename ? languageFor(opts.filename) : javascript) || javascript
+
+  if (!lang.parses(base) || !lang.parses(a) || !lang.parses(b))
+    return { status: 'fallback', text: null, conflicts: [], reason: 'unparseable input' }
+
+  // FIXED-POINT fast path: once two peers agree on a text T, re-merging must return T
+  // unchanged. This is what makes the live sync settle. Both agree ⇒ nothing to check.
+  if (a === b) return { status: 'auto', text: a, conflicts: [], renames: [], provenance: [] }
+
+  const authors = opts.authors || {}
+  const attribute = (prov) => (prov || []).map((p) => ({ unit: p.key, author: authors[p.from] || p.from }))
+
+  // Determine the structurally-merged text + provenance. A one-sided change takes that
+  // side verbatim (format perfectly preserved); otherwise do the keyed 3-way merge and
+  // splice it back into base. Either way the INTENT layer below still runs, so a deletion
+  // that leaves a dangling reference is caught even when only one side changed.
+  let text, provenance
+  if (a === base) { text = b; provenance = [] }
+  else if (b === base) { text = a; provenance = [] }
+  else {
+    const baseUnits = lang.units(base)
+    const merge = mergeKeyed(lang, baseUnits, lang.units(a), lang.units(b))
+    if (merge.conflicts.length) return { status: 'semantic-conflict', text: null, conflicts: merge.conflicts }
+    // Prefer the format-preserving splice (units carry byte ranges); fall back to a plain
+    // join for languages whose units don't expose ranges.
+    const canSplice = baseUnits.every((u) => typeof u.start === 'number')
+    text = canSplice ? spliceUnits(base, baseUnits, merge.order, merge.textByKey) : merge.parts.join('\n\n') + '\n'
+    provenance = merge.provenance
+  }
+
+  // THE GUARANTEE: the merged result must parse, or we refuse it.
+  if (!lang.parses(text)) return { status: 'fallback', text: null, conflicts: [], reason: 'merge would not parse' }
+
+  // RENAME DETECTION (intent): a declaration gone from base whose identical-bodied twin
+  // appears under a new name is a rename — rewrite stale call sites to the new name.
+  let merged = text
+  const baseNames = lang.declaredNames(base)
+  let mergedNames = lang.declaredNames(merged)
+  let removed = [...baseNames].filter((n) => !mergedNames.has(n))
+  const renames = []
+  const rename = lang.renameFreeRefs || lang.renameRefs // prefer scope-aware rewriting
+  if (removed.length && lang.declBody && rename) {
+    const added = [...mergedNames].filter((n) => !baseNames.has(n))
+    const claimed = new Set()
+    for (const oldName of removed) {
+      const oldBody = lang.declBody(base, oldName)
+      if (oldBody == null) continue
+      const match = added.find((n) => !claimed.has(n) && lang.declBody(merged, n) === oldBody)
+      if (match) { renames.push([oldName, match]); claimed.add(match) }
+    }
+    let rewritten = merged
+    // Rewrite only references that resolve to the renamed binding (scope-aware) — a local
+    // variable that merely shares the old name is left untouched.
+    for (const [oldName, newName] of renames) rewritten = rename(rewritten, oldName, newName)
+    // only accept the rewrite if it still parses — never trade a parse error for intent.
+    if (renames.length && lang.parses(rewritten)) { merged = rewritten; mergedNames = lang.declaredNames(merged) }
+  }
+
+  // DANGLING REFERENCE (intent): a declaration removed (and NOT explained by a rename)
+  // but still referenced is a semantic conflict even though the code parses cleanly.
+  // Uses the SCOPE-AWARE reference set when the language provides one (so a local binding
+  // that merely shares the deleted name is correctly NOT treated as a reference to it),
+  // falling back to the approximate identifier set otherwise.
+  removed = [...baseNames].filter((n) => !mergedNames.has(n))
+  const refs = lang.referencedFreeNames ? lang.referencedFreeNames(merged)
+    : lang.usedIdentifiers ? lang.usedIdentifiers(merged) : null
+  if (removed.length && refs) {
+    const dangling = removed.filter((n) => refs.has(n))
+    if (dangling.length)
+      return { status: 'semantic-conflict', text: null, conflicts: dangling.map((n) => 'ref:' + n), reason: 'dangling reference: a declaration was removed/renamed but is still used' }
+  }
+  // PROVENANCE: attribute each surviving unit to the author whose version we kept. With
+  // opts.authors = { a, b, base } the labels are real names; otherwise they're 'a'/'b'/etc.
+  return {
+    status: 'auto', text: merged, conflicts: [],
+    renames: renames.map(([o, n]) => o + '->' + n),
+    provenance: attribute(provenance),
+  }
+}