hivecode-mcp 0.11.5 → 0.11.6

package/sync.js

@@ -25,7 +25,9 @@ import ignore from 'ignore'
 import { applyDiff, summarizeChange, changedRange, hasConflictMarkers, merge3 } from './core.js'
 import { icrMerge3 } from './icr-merge.js' // structure/intent-aware merge; falls back to line merge3
 import { makeCoordinator } from './hive-coord.js' // decentralized claim layer (collision PREVENTION)
+import { gateConfig, runGate, verdictRecord, refusalMessage, forcedMessage } from './hive-gate.js' // the HANDOFF gate: a claim you cannot give back while your own check fails
 import { fileRoom, decodeUnsafe, scopeForRoom, pathAllowed, writeAllowed, isSafeRelPath } from './token.js'
+import { validateMemberName } from './hive-mailbox.js' // a name the mention parser cannot produce is not a name
 import { genIdentity, authorChange, verifyReceipt, contentHash } from './substrate.js' // convergent-substrate: signed provenance for every landed change
 // `languageFor` belongs in this list and was missing: reconcile() calls it on the
 // clean-rewrite path, so a local whole-file rewrite of a supported file threw
@@ -78,6 +80,52 @@ const ALWAYS_IGNORE = [
   '__pycache__/', '*.pyc', '.pytest_cache/', '.mypy_cache/', '.venv/',
 ]
 
+// Is this "merge" actually a FUSION — output neither author wrote? Returns the reason, or ''.
+//
+// Exported and pure so it can be tested against crafted inputs. Forcing a real fusion is
+// timing-dependent (it needs concurrent writes landing inside the sync window), and a guard
+// this important should not be covered only by a test that is inherently flaky.
+//
+// The two signals, and why each is here:
+//   - BROKE IT: both versions parsed and the merged output does not. There is no reading of
+//     that which is correct — whatever it produced, neither author wrote it.
+//   - DUPLICATION: distinctive lines appear MORE often in the output than in the side they
+//     came from. That is content copied rather than merged, and it is what a union of two
+//     near-identical versions looks like — the live corruption had `const MAX_OPEN` and
+//     `function evictIfOverCap` three times each.
+//
+// LENGTH IS DELIBERATELY NOT A SIGNAL, and the first version of this got that wrong. "The
+// output is about as long as both inputs combined" describes a fusion, but it equally
+// describes two authors who each added two hundred lines in different places — a perfectly
+// good merge. The test caught it firing on exactly that. Duplication separates them: a
+// genuine disjoint merge repeats nothing.
+export function fusionReason(merged, mine, theirs, lang) {
+  if (!merged || !mine || !theirs || mine === theirs) return ''
+  // If a side was ALREADY broken, the merge did not break it — blaming the merge would make
+  // every merge on a half-written file look like corruption.
+  if (lang && lang.parses(mine) && lang.parses(theirs) && !lang.parses(merged)) {
+    return 'the merged result does not parse, although BOTH versions did'
+  }
+  // Only distinctive lines: a closing brace or a blank line legitimately repeats, and
+  // counting those would make every file look duplicated.
+  const sig = (s) => s.split('\n').map((l) => l.trim()).filter((l) => l.length > 24)
+  const tally = (arr) => { const m = new Map(); for (const l of arr) m.set(l, (m.get(l) || 0) + 1); return m }
+  const M = tally(sig(merged)), A = tally(sig(mine)), B = tally(sig(theirs))
+  let dup = 0, seen = 0
+  for (const [line, n] of M) {
+    const expected = Math.max(A.get(line) || 0, B.get(line) || 0)
+    if (expected === 0) continue // content in neither side — new, and not our business here
+    seen++
+    if (n > expected) dup++
+  }
+  // Needs enough lines to mean anything, and enough of them repeated to be structural rather
+  // than one unlucky duplicated statement.
+  if (seen >= 10 && dup / seen >= 0.25) {
+    return `${dup} of ${seen} distinctive lines appear more often in the result than in either version — that is content duplicated, not merged`
+  }
+  return ''
+}
+
 const IGNORE = new Set(['node_modules', '.git'])
 const MAX_BYTES = 1_000_000
 const BOARD_FILE = 'HIVE_BOARD.md' // generated locally from `board`; never synced as a file
@@ -89,10 +137,15 @@ const LOCK_FILE = '.hive-lock.json'     // one sync client per folder; see acqui
 const ID_FILE = '.hive-id.json'    // this client's substrate signing identity (private); never synced
 const RULES_FILE = 'HIVE_RULES.md' // the law every participant follows; written into every room
 const MEMBERS_FILE = 'HIVE_MEMBERS.md' // live presence: who is in the room right now
+// The claim map is the stigmergic trace agents SENSE before editing (see `claims` below), but it
+// was the one part of the room that never reached disk — so an agent could only learn it by
+// remembering to call a tool, and a trace nobody can see coordinates nothing. Rendered here for
+// the same reason HIVE_CHAT.md is: a file in the working folder needs no tool call and no memory.
+const CLAIMS_FILE = 'HIVE_CLAIMS.md'
 const AGENTS_FILE = 'HIVE_FOR_AGENTS.md' // how an AI agent opening this folder joins (via .hive.json) + behaves
 // Generated/coordination files are rendered locally from CRDT state — never
 // synced as ordinary files (that would cause echo loops / conflicts).
-const SKIP = new Set([BOARD_FILE, CHAT_FILE, TASKS_FILE, CONFIG_FILE, ID_FILE, RULES_FILE, MEMBERS_FILE, AGENTS_FILE])
+const SKIP = new Set([BOARD_FILE, CHAT_FILE, TASKS_FILE, CONFIG_FILE, ID_FILE, RULES_FILE, MEMBERS_FILE, CLAIMS_FILE, AGENTS_FILE])
 
 // Written into every room folder on sync (like the rules). An AI agent that opens
 // this project reads it to learn it's a Hivecode room and how to JOIN — via the
@@ -118,7 +171,9 @@ asked to collaborate here, follow this.
   hive_release it. If you DON'T, someone else holds it — pick other work
   (hive_claims() shows what's open). This is how agents avoid colliding.
 - hive_say("taking X: doing Y") to announce intent before you edit.
-- ADDRESS EVERY MESSAGE. Put @Name on it for each agent it is for -- hive_say("@Ana I need the churn numbers before I touch pricing.md"). Any agent may address any other agent directly; there is no lead to route through and nobody needs permission. A message that names nobody lands in every agent's "room activity", where they are told to skip it, so it will most likely be ignored -- use it only for a real announcement to the whole room.
+- ADDRESS EVERY MESSAGE. Put @Name on it for each agent it is for -- hive_say("@Ana I need the churn numbers before I touch pricing.md"). Any agent may address any other agent directly; there is no lead to route through and nobody needs permission. A message that names nobody lands in every agent's "room activity", where they are told to skip it, so it will most likely be ignored. Use @all when you genuinely need the whole room -- it wakes everyone, so spending it on chatter is how a room learns to ignore you.
+- ANSWER EVERY QUESTION AIMED AT YOU. "Not yet -- I am on X, I will come back to you" is a complete answer; silence is the one thing the asker cannot act on, because nothing tells them you stopped. hive_check lists anyone still waiting on you.
+- BEFORE A LONG STRETCH OF WORK, call hive_busy("what you are doing"). It posts no message and silences nothing -- it tells anyone who @mentions you, at the moment they send, that you are mid-task rather than ignoring them. hive_busy(clear:true) when you finish.
 - Edit ONLY inside the folders you were granted. Edits merge live; rewrites are logged.
 - Block on hive_wait(); when it returns approved work, do it, then hive_complete(id).
 - A task aimed at you stays PENDING until your owner approves it — act only on 'accepted'.
@@ -152,6 +207,19 @@ another's work. The sync layer enforces the hard parts automatically; you do the
 ## Know who you are working with
 - Read HIVE_MEMBERS.md — who (humans + AIs) is in the room right now, and how many.
 
+## DESIGN BEFORE YOU WRITE — mandatory (Ganesh, 19 Sep 2026)
+Before you build any new feature, post in the room, BEFORE your first edit:
+1. WHO uses it, and when — name the person or agent and the moment they reach for it.
+2. WHAT IT COSTS when it is wrong — one sentence someone who did not write it can act on at 3am.
+3. EVERY EDGE CASE you can name — empty, missing, offline, refused, concurrent, already-done,
+   called twice, called by the wrong person.
+Then build it.
+This is not process for its own sake. Every defect this project has produced has been a FALSE
+SUCCESS — nothing crashed, every signal was green, the result was wrong. That class is never
+caught by testing the happy path afterwards; it is caught by asking first what "wrong but green"
+would look like for this particular feature. If you cannot say what breaks, you do not understand
+it well enough to write it — say so in the room and ask. That is a complete answer.
+
 ## 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 (and what was touched).
@@ -338,11 +406,24 @@ export function acquireFolderLock(root, room, log = console.log) {
 }
 
 export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir = '.', name = 'anon', kind = 'human', owner = '', token = '', license = '', log = console.log, syncFiles = true }) {
+  // BEFORE ANY DISK OR SOCKET WORK. A name outside the mention grammar joins successfully and is
+  // then unreachable: its mail, its obligations and its wake-on-mention are all silently dead,
+  // and the only symptom is other people being told "@X is NOT in the room" about someone who is
+  // sitting right there. Refusing here costs the caller one clear error; allowing it cost an hour
+  // on 20 Sep 2026 and was only found because a human noticed the routing failures by eye.
+  // This throws rather than returning, because startSync has no failure channel and a half-joined
+  // client is worse than no client.
+  const nameCheck = validateMemberName(name)
+  if (!nameCheck.ok) {
+    const e = new Error(`${nameCheck.error} Try "${nameCheck.suggested}".`)
+    e.code = 'EHIVEINVALIDNAME'
+    e.suggested = nameCheck.suggested
+    throw e
+  }
   const ROOT = path.resolve(dir)
   fs.mkdirSync(ROOT, { recursive: true })
   // FIRST, before any socket or file work: if another client already holds this folder,
-  // nothing below should happen at all.
-  const releaseLock = acquireFolderLock(ROOT, room, log)
+  const releaseLock = syncFiles ? acquireFolderLock(ROOT, room, log) : () => {}
 
   // Respect .gitignore (+ always-ignore secrets/junk) so we never sync a
   // teammate's .env, keys, or build output. Reloaded by reloadIgnores().
@@ -431,6 +512,12 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // DISAGREEMENT becomes the signal. One shared "size" field would have silently converged on
   // whichever peer wrote last, which is precisely the failure it exists to catch.
   const swarmAttest = doc.getMap('swarm_attest')
+  // GATE VERDICTS — `<region>|<peerName>` -> the result of that peer running the room's check in
+  // ITS OWN folder before handing the file back. Keyed per peer for the same reason swarmAttest
+  // is: "the tests pass" is a fact about one folder's bytes, and storing it as a single shared
+  // value would converge on whoever released last, silently erasing the disagreement that is the
+  // entire signal. Two agents reporting different verdicts for one path both survive here.
+  const gateResults = doc.getMap('gate_results')
   // CLAIM LEASE. Expiry is evaluated lazily on read, so the moment a lease passes its TTL the
   // next agent that tries simply gets the file -- that is what stops a stalled agent
   // deadlocking the room.
@@ -955,6 +1042,43 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // "not pulled yet", NOT "new file", so we must not re-seed it from disk (that
   // would create a second CRDT history and duplicate/garble content on rejoin).
   const fileDocs = new Map() // relPath -> { doc, provider, text, synced }
+
+  // REFUSED FILE-ROOMS. y-websocket retries a failed upgrade forever, with backoff and in
+  // silence. That is right for a flaky network and badly wrong for a relay that is full: on
+  // 18 Sep 2026 a relay answered 38,011 connections with Q430 while the agents involved
+  // showed no symptom at all. Their files simply never arrived, and an unsynced file-doc
+  // reads as EMPTY, which is how the same evening ended with 186 files written to 0 bytes.
+  //
+  // So count refusals for docs that have NEVER synced, and say it once. The condition is
+  // usually a whole-relay problem rather than a per-file one, so one message naming the
+  // count is the useful shape -- one per file would be 800 lines of chat.
+  const refusedFiles = new Map() // relPath -> consecutive connection errors, cleared on sync
+  let refusalSaidAt = 0
+  let refusalTimer = null
+  function noteRefusals() {
+    if (refusalTimer) return
+    // Debounced: a full relay refuses every file at once, and we want the total, not the first.
+    refusalTimer = setTimeout(() => {
+      refusalTimer = null
+      const stuck = [...refusedFiles.keys()].filter((r) => { const e = fileDocs.get(r); return e && !e.synced })
+      // One transient error on one file is a blip, not an outage. Two or more files stuck, or
+      // repeated failures on one, is the shape of a relay that will not take us.
+      const repeated = stuck.some((r) => (refusedFiles.get(r) || 0) >= 3)
+      if (stuck.length < 2 && !repeated) return
+      const now = Date.now()
+      if (now - refusalSaidAt < 300000) return // at most once every 5 minutes
+      refusalSaidAt = now
+      const msg =
+        `${stuck.length} file(s) cannot connect to the relay and are NOT syncing. ` +
+        `They will read as empty until this clears. The usual cause is the relay being full ` +
+        `(Q430): Hivecode opens one socket PER FILE, so a large folder can exhaust it alone. ` +
+        `Check <relay-http>/health -- connections against limits.maxConnsTotal -- then raise ` +
+        `HIVE_MAX_CONNS_TOTAL or narrow what syncs. Do not trust this folder's contents meanwhile.`
+      log(`[${name}] !! ${msg}`)
+      try { say(`[!] @all ${msg}`) } catch { /* chat may itself be unreachable — the log still carries it */ }
+    }, 4000)
+    if (refusalTimer.unref) refusalTimer.unref()
+  }
   function openFile(relPath) {
     let e = fileDocs.get(relPath)
     if (e) return e
@@ -997,7 +1121,19 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     // The fork record arrived/changed from a peer: render it locally, or — if it was
     // cleared (resolved elsewhere) — adopt the now-clean shared text to disk.
     conflict.observe((_ev, txn) => { if (txn.local) return; if (e.conflict.has('meta')) renderConflict(relPath); else adoptResolved(relPath) })
-    fprovider.on('sync', (s) => { if (s) { e.synced = true; reconcile(relPath, 'remote'); detectFork(relPath) } }) // initial pull settled
+    fprovider.on('sync', (s) => { if (s) { e.synced = true; refusedFiles.delete(relPath); reconcile(relPath, 'remote'); detectFork(relPath) } }) // initial pull settled
+    // A refused upgrade lands here. The provider will keep retrying by itself, which is the
+    // right behaviour and exactly why nothing surfaces it — so count it and let noteRefusals
+    // decide whether this is a blip or a relay that will not take us.
+    fprovider.on('connection-error', () => {
+      if (e.synced) return // already have the content; a later blip is the provider's business
+      refusedFiles.set(relPath, (refusedFiles.get(relPath) || 0) + 1)
+      noteRefusals()
+    })
+    // Newly opened counts as used, and opening is the moment the working set can go over
+    // its bound — so this is where the least-recently-used ones are let go.
+    touched.set(relPath, Date.now())
+    evictIfOverCap(relPath)
     return e
   }
   function closeFile(relPath) {
@@ -1010,6 +1146,60 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   }
   const fileText = (relPath) => { const e = fileDocs.get(relPath); return e ? e.text : null }
 
+  // HIV-18: BOUND HOW MANY FILE SOCKETS THIS CLIENT HOLDS.
+  //
+  // Hivecode opens one WebSocket per FILE. A relay allows 512 connections in total by
+  // default, and a normal project has more files than that, so a single client could
+  // exhaust the whole relay by itself. Measured 18 Sep 2026: 889 files, 38,011 Q430
+  // refusals in one evening, three agents locked out — and because a file-doc that never
+  // syncs reads as EMPTY, 186 files per folder were written to 0 bytes.
+  //
+  // Holding every file open forever is what made that possible. A client now keeps a
+  // BOUNDED working set: the most recently used MAX_OPEN files stay connected, the rest
+  // are closed and reopened on demand. Closing a file doc costs nothing on disk — the
+  // bytes stay where they are, the room keeps the content, and touching the file reopens
+  // it and pulls the current copy.
+  //
+  // THE TRADE, stated plainly: a file outside the working set does not receive remote
+  // edits until something touches it. That is a real semantic change, and it is strictly
+  // better than the alternative it replaces, which was not receiving them either AND
+  // believing the file was empty. The default is high enough that ordinary projects never
+  // notice; size it as MAX_OPEN x agents < the relay's maxConnsTotal.
+  //
+  // NEVER EVICT, because these lose work rather than merely adding latency:
+  //   - a doc that has not synced (its content has not reached the relay yet)
+  //   - a file in an unresolved conflict (its fork record is live and local-only)
+  //   - a file anyone currently holds a claim on (they are mid-edit)
+  //   - anything used within the grace window
+  const MAX_OPEN = Math.max(8, Number(process.env.HIVE_MAX_OPEN_FILES) || 128)
+  // Configurable because the grace window is what makes eviction untestable otherwise: in a
+  // short run every file was touched seconds ago, so nothing is ever eligible.
+  const EVICT_GRACE_MS = Number(process.env.HIVE_EVICT_GRACE_MS) || 30000
+  const touched = new Map() // relPath -> last use (ms)
+  const touchFile = (relPath) => { if (fileDocs.has(relPath)) touched.set(relPath, Date.now()) }
+  let evicted = 0
+  function evictIfOverCap(keep) {
+    if (fileDocs.size <= MAX_OPEN) return
+    const now = Date.now()
+    const isClaimed = (r) => { try { return claims.has(r) } catch { return false } }
+    const cand = []
+    for (const [r, e] of fileDocs) {
+      if (r === keep || !e.synced) continue
+      if (conflicted.has(r)) continue
+      try { if (e.conflict && e.conflict.size) continue } catch { }
+      if (isClaimed(r)) continue
+      const t = touched.get(r) || 0
+      if (now - t < EVICT_GRACE_MS) continue
+      cand.push([r, t])
+    }
+    cand.sort((a, b) => a[1] - b[1]) // least recently used first
+    let over = fileDocs.size - MAX_OPEN
+    for (const [r] of cand) {
+      if (over-- <= 0) break
+      closeFile(r); touched.delete(r); evicted++
+    }
+  }
+
   // My own path scope, read from my token (for THIS room). Used so I don't even
   // try to open files I'm not granted — the relay would reject them anyway, but
   // this avoids the churn and keeps out-of-scope files off my disk entirely.
@@ -1026,6 +1216,43 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // or a full-write grant => everything I can open is writable (back-compat).
   const canWrite = (relPath) => !myScope || writeAllowed(myScope, relPath)
 
+  // WOULD AN EDIT TO THIS PATH ACTUALLY REACH ANYONE? '' if yes, else the reason. (HIV-27)
+  //
+  // A claim is a path STRING in the shared `claims` map. Whether that path's BYTES sync is
+  // decided somewhere else entirely, per client, by canOpen/isIgnored. Nothing compared the
+  // two, so an agent could hold an exclusive claim on a file nobody else can see, do the work,
+  // pass a gate that runs in its OWN folder where the file is real, and hand back something
+  // that never existed for anyone else. Every signal green, the work genuinely done, and
+  // invisible. Observed live: an agent edited scripts/check-deploy.mjs, claimed it, released it
+  // through the gate, and the other two folders still held the old bytes.
+  //
+  // This is checked at CLAIM time on purpose. Release is too late -- by then the agent has
+  // built the thing it intended to write, and all we could do is tell it the work was wasted.
+  //
+  // THE FALSE-POSITIVE DIRECTION IS WHAT MAKES THIS USABLE, and it is easy to get wrong.
+  // A claim may name a logical region rather than a file ("auth-refactor", "the parser"), and
+  // under an ALLOW-LIST .gitignore -- `/*` followed by negations, which is how a room bounds
+  // itself against the one-socket-per-file limit -- isIgnored() returns true for every string
+  // that is not an explicitly allowed path. A naive isIgnored() check would therefore refuse
+  // almost every legitimate claim in exactly the rooms that need this guard most, and it would
+  // be switched off within a day. So we only judge things we have positive reason to believe
+  // are FILES: known to the room, present on disk, or carrying a directory separator.
+  const whyNotShared = (relPath) => {
+    const p = String(relPath || '')
+    if (!p) return ''
+    let onDisk = false
+    try { onDisk = fs.existsSync(path.join(ROOT, p)) } catch { onDisk = false }
+    // SKIP counts as positive evidence: those names ARE files by definition, and a control
+    // file sits in the room root with no separator in its name, so the heuristics below miss it.
+    const isFile = manifest.has(p) || fileDocs.has(p) || SKIP.has(p) || onDisk || p.includes('/')
+    if (!isFile) return ''                       // a label, not a path -- not ours to judge
+    if (!isSafeRelPath(p)) return `"${p}" is not a safe relative path, so it can never be synced`
+    if (SKIP.has(p)) return `${p} is a Hivecode control file, not shared source`
+    if (!canOpen(p)) return `your access token's scope does not cover ${p}, so its bytes stay in this folder`
+    if (isIgnored(p)) return `${p} is ignored by a .gitignore here, so this client never opens a sync connection for it -- anything you write stays in this folder and no other agent will ever see it`
+    return ''
+  }
+
   const known = new Set()
   const mtimes = new Map()
   // Paths that already existed on disk when this client STARTED. This is the
@@ -1153,6 +1380,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     let fe = fileDocs.get(relPath)
     if (!fe) { if (disk === null) return; openFile(relPath); return }
     if (!fe.synced) return
+    touchFile(relPath) // reconciling a file IS using it — keep it in the working set
     // SOURCE CAPTURE (fork gate): before ANYTHING in this pass can merge over or render into
     // this file, record any authored edit sitting on disk. The edit enters the provenance
     // DAG first; whatever happens to the disk afterwards can no longer lose it.
@@ -1203,8 +1431,19 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       if (disk !== null && hasConflictMarkers(disk) && !hasConflictMarkers(fe.text.toString())) { adoptResolved(relPath); return }
     }
     const docText = fe.text.toString()
-    if (docText === '' && !manifest.has(relPath)) {
-      // the relay has no copy of this path -> publish ours (a genuinely new file)
+    // An empty shared doc is authoritative ONLY if we have history for this path.
+    // A file's NAME lives in the parent doc and its CONTENT in the file's own doc, on two
+    // different connections — there is no atomicity across them. A client that joins a large
+    // project and dies mid-join gets every manifest key up and only some file bodies, leaving
+    // the room asserting that paths exist with nothing behind them. With no ancestor and real
+    // bytes on disk, "" means the publisher never finished, not that the file is empty, and
+    // adopting it deletes real work (measured: 186 files zeroed across three folders).
+    // A genuine emptying of a file we HAVE synced still has an ancestor, so it falls through
+    // to the merge below and still lands.
+    const noHistory = !bases.has(relPath) && !priorShadow.has(relPath)
+    if (docText === '' && (!manifest.has(relPath) || (disk && noHistory))) {
+      // the relay has no usable copy of this path -> publish ours (a genuinely new file,
+      // or one whose registration outlived the join that promised it)
       if (disk === null) return
       fe.doc.transact(() => applyDiff(fe.text, disk))
       stampProvenance(relPath, '', disk) // genesis: sign the file's first content (base = empty)
@@ -1337,6 +1576,41 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       res = icrMerge3(base, disk, docText, relPath) // incoming remote change merged into our working copy
     }
 
+    // FUSION GUARD (HIV-26). A merge must never produce something NEITHER author wrote.
+    //
+    // On 18 Sep 2026 three peers wrote the same file within about a second of each other and
+    // the character-CRDT UNIONED the versions instead of converging: sync.js went 144,144 ->
+    // 291,750 bytes, `const MAX_OPEN` appeared three times, and the splice landed mid-token
+    // (`evicted// Newly opened...`). There were NO conflict markers, every peer converged on
+    // the corruption — so agreement proved nothing — and the only thing that caught it was a
+    // parse failure at the handoff gate, by which point it had already reached every folder.
+    //
+    // Two cheap signals, each catching what the other misses:
+    //   - the merge BROKE a file both sides could parse. Definitionally wrong: whatever that
+    //     output is, neither author wrote it.
+    //   - the result is about as long as both sides put together. That is concatenation in a
+    //     merge's clothing, and it catches a fusion that happens to still parse.
+    //
+    // We land NOTHING. Not a conflict block either: this engine deliberately keeps markers
+    // out of the shared text, because writing them into the very layer that fuses is what
+    // produced marker-fusion before. So the doc keeps its version, disk keeps its version,
+    // both are still intact and recoverable, and the room is TOLD. A file left visibly
+    // divergent is a bad day; a file silently fused is an unrecoverable one.
+    if (res && !res.conflict) {
+      const why = fusionReason(res.text, disk, docText, supports(relPath) ? languageFor(relPath) : null)
+      if (why) {
+        conflicted.add(relPath)
+        if (icrWarned.get(relPath) !== why) {
+          icrWarned.set(relPath, why)
+          log(`[${name}] !! REFUSED a fused merge of ${relPath}: ${why}`)
+          try {
+            say(`[!] @all ${relPath}: a merge was REFUSED because it fused rather than merged — ${why}. Nothing was written: the room's copy and ${name}'s local copy are both intact and unchanged. Someone must reconcile them deliberately; a plain file write will merge against the other version again, hive_edit replaces it outright.`)
+          } catch { /* the log still carries it */ }
+        }
+        return
+      }
+    }
+
     // Snapshot the state JUST BEFORE this author's edit lands, attributed to them —
     // captured only on local origin so each change is recorded once, by its author.
     if (origin === 'local' && res.text !== docText) {
@@ -1730,6 +2004,44 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     }
     writeToDisk(MEMBERS_FILE, out.join('\n') + '\n')
   }
+  /** The claim map as a file. Same contract as renderMembers: generated locally, never synced.
+   *
+   *  EXPIRY IS SHOWN, NOT HIDDEN. A claim whose TTL has run out is not a lock any more — the
+   *  region is free — so rendering it as "held" would make agents queue behind a crashed peer,
+   *  which is the deadlock TTLs exist to prevent. Expired rows stay visible but labelled, because
+   *  "AgentX died holding this" is information, and silently dropping the row loses it. */
+  function renderClaims() {
+    const now = Date.now()
+    const rows = []
+    claims.forEach((c, region) => {
+      if (!c || !c.by) return
+      const ttl = Number(c.ttl) || 0
+      const age = now - (Number(c.at) || 0)
+      const left = ttl - age
+      rows.push({ region, by: c.by, intent: c.intent || 'edit', age, left, dead: left <= 0 })
+    })
+    rows.sort((a, b) => a.region.localeCompare(b.region))
+
+    const secs = (ms) => `${Math.max(0, Math.round(ms / 1000))}s`
+    const live = rows.filter((r) => !r.dead)
+    const out = [
+      '# Hive Claims — who holds which file right now (live).',
+      '# SENSE this before you edit. A region held by someone else is not yours to write:',
+      '# flow to open work instead of waiting. Claims expire on their own, so nothing deadlocks.',
+      '',
+      `held: ${live.length}`,
+      '',
+    ]
+    for (const r of rows) {
+      out.push(r.dead
+        ? `- ${r.region} — EXPIRED (was ${r.by}, ${r.intent}, ${secs(r.age)} ago) — free to take`
+        : `- ${r.region} — ${r.by} (${r.intent}) — held ${secs(r.age)}, ${secs(r.left)} left`)
+    }
+    if (!rows.length) out.push('- nothing claimed; every region is open')
+    writeToDisk(CLAIMS_FILE, out.join('\n') + '\n')
+  }
+  if (syncFiles) claims.observe(() => renderClaims())
+
   // Warn (once per peer) when someone joins on an incompatible protocol version —
   // otherwise they'd silently fail to sync and look like a "broken room".
   const versionWarned = new Set()
@@ -1744,7 +2056,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       try { say(`⚠ ${u.name} is on an incompatible version — files won't sync with them until everyone updates Hivecode.`) } catch { }
     }
   }
-  if (syncFiles) provider.awareness.on('change', () => { renderMembers(); checkVersions() })
+  if (syncFiles) provider.awareness.on('change', () => { renderMembers(); renderClaims(); checkVersions() })
 
   function scan() {
     const diskFulls = walk(ROOT)
@@ -1783,8 +2095,16 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         try { fs.rmSync(path.join(ROOT, key)) } catch { }
         known.delete(key); bases.delete(key); forkBases.delete(key); mtimes.delete(key)
         log(`[${name}] <- deleted ${key}`)
-      } else if (canOpen(key)) {
-        openFile(key)
+      } else if (canOpen(key) && !SKIP.has(key) && !isIgnored(key)) {
+        // Same rule as the initial sweep: a path this client ignores must not cost it a
+        // socket just because somebody else registered it.
+        //
+        // AND the same BOUND. This observer is how a joining client learns the room's whole
+        // manifest — every existing path arrives here as a remote change — so capping only
+        // the sweep achieved nothing: the first measurement of this cap showed a client with
+        // cap 8 holding 30 file docs, every one of them opened right here. A path we decline
+        // to open now is not lost; it opens when something touches it.
+        if (fileDocs.size < MAX_OPEN) openFile(key)
       }
     })
   })
@@ -1809,11 +2129,37 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     if (!s || !syncFiles) return
     writeToDisk(RULES_FILE, HIVE_RULES_TEXT) // the law is always present in the room
     writeToDisk(AGENTS_FILE, AGENT_MANUAL_TEXT) // so an agent opening this folder learns how to join + behave
-    for (const key of manifest.keys()) if (canOpen(key)) openFile(key) // connect to every file I'm granted; each file-room's sync pulls its content
+    // Connect to every file I'm granted AND have not excluded; each file-room's sync pulls
+    // its content. `canOpen` is the TOKEN's scope -- what the relay would let me see. It is
+    // not the same question as "do I want this file", and using it alone meant a participant
+    // could not bound its own footprint: on 18 Sep 2026 two agents kept opening demo/** file
+    // rooms after their .gitignore had been narrowed to 35 paths, and between them consumed
+    // the relay's entire 512-connection budget. Since one socket is opened PER FILE, an
+    // ignore rule that does not stop the connection is not a containment tool at all.
+    // Same predicate reconcile() uses, so a file is never open but unreconcilable.
+    // BOUND THE INITIAL SWEEP, not just the steady state. This burst is precisely when the
+    // budget blows: a client with 889 files used to try to open 889 sockets at once against
+    // a 512-connection relay. LRU eviction cannot help here — during a burst every file was
+    // touched seconds ago, so nothing is eligible to evict. The only thing that works is to
+    // not open them all.
+    //
+    // Files that exist on THIS client's disk come first: they are the ones that need
+    // reconciling, and a path we have no local copy of can wait until something asks for it.
+    const openable = [...manifest.keys()].filter((k) => canOpen(k) && !SKIP.has(k) && !isIgnored(k))
+    const localFirst = openable.sort((a, b) => {
+      const la = fs.existsSync(path.join(ROOT, a)) ? 0 : 1
+      const lb = fs.existsSync(path.join(ROOT, b)) ? 0 : 1
+      return la - lb
+    })
+    for (const key of localFirst.slice(0, MAX_OPEN)) openFile(key)
+    if (localFirst.length > MAX_OPEN) {
+      log(`[${name}] ${localFirst.length} files in this room, holding ${MAX_OPEN} open (HIVE_MAX_OPEN_FILES). The rest sync when touched.`)
+    }
     if (board.size) renderBoard()
     if (chat.length) renderChat()
     if (tasks.size) renderTasks()
     renderMembers()
+    renderClaims() // unconditional: "nothing is claimed" is the answer an arriving agent needs most
     scan()
     log(`[${name}] folder sync active on ${ROOT} (room "${room}") as ${kind}. ${manifest.size} files.`)
     if (!scanTimer) {
@@ -1920,8 +2266,71 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     controls,            // the live control map
     // --- hive coordination: claim a region BEFORE editing (collision prevention) ---
     claim: (region, intent) => { const r = String(region), i = String(intent || 'edit'); myIntents.set(r, i); return coordinator.acquire(r, i) }, // true iff you hold it (my intent recorded either way — it's what my receipts sign)
-    release: (region) => { const r = String(region); myIntents.delete(r); return coordinator.release(r) },
+    // RELEASE IS A HANDOFF, AND A HANDOFF CAN BE REFUSED.
+    //
+    // Until the room sets `gate:cmd`, this behaves exactly as it always did and returns
+    // {ok:true} — no configured gate means no new failure mode for existing rooms.
+    //
+    // With a gate set, the check runs in THIS agent's folder and a non-zero exit keeps the claim.
+    // That is the whole idea: the file stays visibly yours, so the next agent cannot quietly
+    // inherit something that looked finished. It does NOT unsend the bytes — the CRDT syncs
+    // continuously and they are already everywhere — it refuses the "I am done, it is yours".
+    //
+    // `force` exists because abandoning work is legitimate, and it is never silent: it releases,
+    // records that it was forced, and says so in the room.
+    release: (region, opts = {}) => {
+      const r = String(region)
+      const g = gateConfig((k) => swarmState.get(k))
+      const letGo = () => { myIntents.delete(r); coordinator.release(r) }
+      if (!g) { letGo(); return { ok: true, gated: false } }
+
+      if (opts.force) {
+        const rec = verdictRecord({ region: r, by: name, cmd: g.cmd, result: null, forced: true, why: opts.why })
+        gateResults.set(`${r}|${name}`, rec)
+        letGo()
+        try { say(forcedMessage({ region: r, by: name, why: opts.why })) } catch { /* chat is not the point */ }
+        return { ok: true, gated: true, forced: true }
+      }
+
+      const result = runGate({ cmd: g.cmd, cwd: ROOT, timeoutMs: g.timeoutMs })
+      gateResults.set(`${r}|${name}`, verdictRecord({ region: r, by: name, cmd: g.cmd, result }))
+      if (!result.ok) {
+        // The claim is NOT dropped. Saying so in the room is what makes the refusal visible to
+        // everyone rather than a private error the holder can ignore.
+        try { say(`@all ${name} could not hand back ${r}: the gate failed (exit ${result.code}). Still held.`) } catch { /* ignore */ }
+        return { ok: false, gated: true, code: result.timedOut ? 'Q491' : 'Q490', result, message: refusalMessage({ region: r, cmd: g.cmd, result }) }
+      }
+      letGo()
+      return { ok: true, gated: true, result }
+    },
+    /** The verdicts recorded for a path, by peer. Read this before building on someone's file. */
+    gateVerdicts: (region) => {
+      const out = {}
+      const pre = String(region) + '|'
+      gateResults.forEach((v, k) => { if (k.startsWith(pre)) out[k.slice(pre.length)] = v })
+      return out
+    },
+    /** The room's gate, or null. Exposed so a client can say what it is about to be judged by. */
+    gate: () => gateConfig((k) => swarmState.get(k)),
+    // THE LOCK YOU MAY WRITE BEHIND. `claim()` answers from this replica alone, so under real
+    // concurrency it says yes to everyone (see hive-coord.js). This waits for the claim to
+    // round-trip through the relay -- the only place the room is actually serialised -- and then
+    // asks who the converged map says holds it. Exactly one caller gets true.
+    //
+    // The loser has nothing to release: the winner's entry replaced its own under last-writer-
+    // wins on the same key, so conceding is just returning false.
+    claimSettled: async (region, intent, waitMs = 900) => {
+      const r = String(region), i = String(intent || 'edit')
+      myIntents.set(r, i)
+      if (!coordinator.acquire(r, i)) return false          // someone already visibly holds it
+      await new Promise((res) => setTimeout(res, Math.max(200, waitMs)))
+      const holder = coordinator.sense(r)
+      if (holder && holder.by === name) return true
+      myIntents.delete(r)
+      return false
+    },
     senseClaim: (region) => coordinator.sense(String(region)), // the live claim on a region, or null
+    whyNotShared,        // '' if edits to this path reach the room, else why they would not (HIV-27)
     claimsBoard: () => coordinator.board(),                     // everything currently claimed
     // --- intent-aware fork resolution: any agent may judge; the medium validates ---
     forkInfo,            // the active fork on a file as a resolvable object (base + versions + signed intents), or null
@@ -1973,11 +2382,23 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     status: () => {
       let synced = 0
       for (const e of fileDocs.values()) if (e.synced) synced++
+      // `notSyncing` is the number the caller actually needs when something is wrong: files
+      // whose own socket the relay refused. They are not slow, they are not arriving, and
+      // until they do they read as empty. filesSynced alone shows a shortfall but not a cause.
+      const notSyncing = [...refusedFiles.keys()].filter((r) => { const e = fileDocs.get(r); return e && !e.synced })
       return {
         connected: !!provider.wsconnected,
         connecting: !!provider.wsconnecting,
         files: fileDocs.size,
         filesSynced: synced,
+        notSyncing: notSyncing.length,
+        notSyncingFiles: notSyncing.slice(0, 20),
+        // The working set and its bound. `openCap` x agents must stay under the relay's
+        // maxConnsTotal, and `evicted` climbing steadily means the cap is too small for
+        // how this room actually works — both are things an operator can only act on if
+        // they can see them.
+        openCap: MAX_OPEN,
+        evicted,
       }
     },
     stop: () => {