hivecode-mcp 0.11.6 → 0.12.0

package/sync.js

@@ -36,6 +36,13 @@ import { genIdentity, authorChange, verifyReceipt, contentHash } from './substra
 // whole file is the most common thing an agent does, so this fired constantly.
 import grmLink from './grm-link.cjs' // hands this room's history to GRM, so the ROOM has a memory
 import { structuralMerge, supports, languageFor } from './icr.js' // validates a judged fork resolution before it may land (parse + dangling refs)
+import { accountFor, sameText, DESCENDS, IDENTICAL, DIVERGED, UNPROVEN } from './hive-pr-staleness.js' // room-versus-branch provenance staleness checks (HIV-P9)
+// HIV-P8. The map key MUST be the string 'obligations' — hive-mcp.js:656 reads that exact key, and
+// a debt written anywhere else would be invisible to hive_owed: a warning nobody can see, which is
+// the defect this ticket is about, one level down.
+import * as RH from './hive-relay-health.js' // HIV-P13; the ONLY producer of the not-syncing diagnosis
+import { checkRelay } from './hive-privacy.js' // HIV-P20; which relay is this, and did anybody choose it
+import * as OB from './hive-obligations.js'
 
 // Wire-format/protocol version. Bump when a change makes clients incompatible
 // (e.g. the v2 per-file-subdoc model). Broadcast via awareness so peers can warn
@@ -405,7 +412,7 @@ export function acquireFolderLock(root, room, log = console.log) {
   return release
 }
 
-export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir = '.', name = 'anon', kind = 'human', owner = '', token = '', license = '', log = console.log, syncFiles = true }) {
+export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir = '.', name = 'anon', kind = 'human', owner = '', token = '', license = '', log = console.log, syncFiles = true, passive = false }) {
   // 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
@@ -420,6 +427,23 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     e.suggested = nameCheck.suggested
     throw e
   }
+  // THE SAME PRIVACY GATE hive-mcp.js applies at join, repeated here because this is the
+  // real choke point. Every client in the product -- the MCP server, hive-agent.js, the
+  // CLIs, every demo script -- reaches the network through this one function, and a guard
+  // that lives only in the MCP layer protects only agents that went through the MCP layer.
+  // An operator who sets HIVE_RELAY_PIN is entitled to expect it means "this machine",
+  // not "this machine, except for the seven scripts that call startSync directly".
+  //
+  // It throws for the reason the name check above throws: startSync has no failure channel,
+  // and a client that half-connects to a relay nobody authorised is the failure this exists
+  // to prevent. Refusing here means no socket was opened and no file was published.
+  const priv = checkRelay({ relay, env: process.env, dir: path.resolve(dir), fs })
+  if (!priv.ok) {
+    const e = new Error(`${priv.headline}\n\n${priv.detail}`)
+    e.code = 'EHIVERELAYPIN'
+    e.qcode = priv.code
+    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,
@@ -942,9 +966,10 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   if (lic) wsParams.license = lic
   if (name) wsParams.name = String(name).slice(0, 48)
   if (kind) wsParams.kind = kind
+  if (passive) wsParams.passive = 'true'
   const wsOpts = { WebSocketPolyfill: WebSocket, disableBc: true, params: Object.keys(wsParams).length ? wsParams : undefined }
   const provider = new WebsocketProvider(relay, room, doc, wsOpts)
-  provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, v: PROTOCOL_VERSION }) // identity is implicit in the client
+  provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, v: PROTOCOL_VERSION, passive: !!passive }) // identity is implicit in the client
 
   // ---- relay reachability, said out loud exactly once -------------------------------
   // y-websocket retries forever and silently. That is the right RECOVERY behaviour and
@@ -1053,12 +1078,14 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // 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
+  const refusedCodes = new Map() // relPath -> the HTTP status the relay refused with, when it gave one
   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 = setTimeout(async () => {
       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
@@ -1068,17 +1095,120 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       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.`
+      // HIV-P13. THIS MESSAGE USED TO NAME A CAUSE IT HAD NOT MEASURED.
+      //
+      // It said "the usual cause is the relay being full (Q430)" on the strength of having
+      // observed only that N file docs have synced=false. Measured 21 Sep 2026, at the moment a
+      // third agent printed it for 49 files: the relay reported 56 connections of 512, and
+      // limits.js keys its per-room count on the FILE-room, so any one file held three
+      // connections against a cap of 64. Q430 needed 512 and had 56; Q431 needed 64 and had 3.
+      // Neither refusal could have fired. The real event was the relay dropping its room state
+      // -- /health went rooms 44 -> 0 -> 29 -> 44 over a few minutes -- and every client
+      // reconnecting one socket per file.
+      //
+      // "The relay is full" and "the relay just dropped everyone and we are all reconnecting"
+      // produce an identical symptom and need OPPOSITE responses: a config change, or thirty
+      // seconds of patience. Telling an operator to raise a limit that is 89% free is worse
+      // than saying nothing, because they will do it, see no change, and conclude the product
+      // is broken -- correctly, on the evidence they were given.
+      //
+      // So the client asks the relay instead of guessing, and reports what came back. It also
+      // stops printing the literal string "<relay-http>", which it did for three weeks while
+      // holding the relay URL in scope.
+      // EVIDENCE BEFORE INFERENCE. If the relay actually refused us it said so with a status,
+      // and explain() maps those to the right cause and the right knob -- Q431 to HIVE_SEATS,
+      // Q430 to capacity, 401/403 to the token, 402 to the plan. That is a fact from the relay.
+      // Only when nothing refused us -- the sockets simply never came up, which is what a
+      // dropped-and-reconnecting relay looks like -- is there anything left to infer, and then
+      // we go and ASK rather than assert.
+      const coded = stuck.map((r) => refusedCodes.get(r)).filter(Boolean)
+      const code = coded.length ? coded.sort((a, b) => coded.filter((c) => c === b).length - coded.filter((c) => c === a).length)[0] : null
+      const msg = code
+        ? `${stuck.length} file(s) are not synced and will READ AS EMPTY until this clears. ` +
+          `The relay refused ${coded.length} of them with ${code}: ${explain(code)} ` +
+          `Do not trust this folder's contents meanwhile.`
+        : (await RH.explainNotSyncing(relay, {
+            stuck: stuck.length, what: 'files',
+            trailer: `Nothing refused these connections with a status code, so the cause above is ` +
+              `inferred from the relay's own counters rather than reported by it. ` +
+              `Do not trust this folder's contents meanwhile.`,
+          })).text
       log(`[${name}] !! ${msg}`)
       try { say(`[!] @all ${msg}`) } catch { /* chat may itself be unreachable — the log still carries it */ }
     }, 4000)
     if (refusalTimer.unref) refusalTimer.unref()
   }
+  // HIV-P18. THE DOCUMENTED REMEDY DID NOT EXIST.
+  //
+  // The README told every user: "A file outside the working set is not on your disk yet. It
+  // exists in the room. Reading or claiming the path fetches it." Measured 21 Sep 2026 against
+  // a client holding 8 of a room's 41 files, on a path that WAS in the manifest:
+  //
+  //   whyNotShared(mod024.js) -> ""      (in scope; edits would reach the room)
+  //   claim(mod024.js)        -> true    ("it's yours")
+  //   after claim + 9s        -> on disk = false
+  //   after release + 9s      -> on disk = false
+  //   provenanceOf            -> 0 receipts,  headOf -> null   (doc never opened)
+  //   public fetch/read/open  -> undefined
+  //
+  // Nothing brought the bytes down. The cause is one line in reconcile: `if (disk === null)
+  // return` before openFile, plus a warm-up that only opens files already on local disk. A
+  // manifest entry with no local copy was never opened, so it could never arrive.
+  //
+  // The only thing that DID work was writing to the path -- which is precisely the blind
+  // recreate HIV-P14b guards. So the sole recovery route was the one dangerous action, reached
+  // by an agent that had been told "it's yours" and then saw an empty directory. That is
+  // HIV-P3's class arriving inbound: a claim granted over bytes that cannot move.
+  //
+  // This makes the sentence true. `fetch` opens the doc and RESOLVES WHEN THE CONTENT HAS
+  // LANDED, because an un-awaited open is the same false success one layer down: the caller
+  // reads the directory, sees nothing, and concludes the file is absent.
+  function fetchFile(relPath, { timeoutMs = 15000 } = {}) {
+    const r = String(relPath)
+    if (!canOpen(r)) return Promise.resolve({ ok: false, reason: `${r} is out of your scope` })
+    const full = path.join(ROOT, r)
+    // Already here: report it, and say so rather than implying we went and got it.
+    if (fs.existsSync(full)) return Promise.resolve({ ok: true, alreadyLocal: true, file: r })
+    // Not in the room either. This is the case @Hermes hit, and it is NOT the working-set
+    // case: nothing will ever arrive, so saying "fetching" would be a lie. The two look
+    // identical from an empty directory and have opposite remedies, so they get different
+    // answers here.
+    if (!manifest.has(r)) {
+      return Promise.resolve({
+        ok: false, notInRoom: true, file: r,
+        reason: `${r} is not in this room at all — no client has ever published it, so nothing ` +
+          `can fetch it. This is not a working-set miss. Check the room's .gitignore allow-list ` +
+          `covers the path, then have whoever holds the file write it into their synced folder.`,
+      })
+    }
+    const e = openFile(r)
+    if (!e) return Promise.resolve({ ok: false, reason: `could not open ${r}` })
+    return new Promise((resolve) => {
+      let done = false
+      const finish = (res) => { if (done) return; done = true; clearInterval(iv); clearTimeout(to); resolve(res) }
+      const check = () => {
+        if (!e.synced) return
+        // reconcile() runs on the provider's own sync event and writes to disk. Wait for the
+        // BYTES, not for the flag -- the flag says the socket settled, which is not the claim
+        // being made to the caller.
+        if (fs.existsSync(full)) return finish({ ok: true, file: r, bytes: fs.statSync(full).size })
+        // Synced and still nothing: the room holds this path with empty content. Real, and a
+        // different answer from "not fetched yet".
+        if (e.text.toString() === '') return finish({ ok: true, file: r, empty: true, bytes: 0 })
+      }
+      const iv = setInterval(check, 250)
+      if (iv.unref) iv.unref()
+      const to = setTimeout(() => finish({
+        ok: false, file: r, timedOut: true,
+        reason: `${r} is in the room but did not arrive within ${timeoutMs}ms. The file's own ` +
+          `socket may be refused — hive_status reports filesHeld of roomFiles, and a refused ` +
+          `file doc is indistinguishable from an empty file.`,
+      }), timeoutMs)
+      if (to.unref) to.unref()
+      check()
+    })
+  }
+
   function openFile(relPath) {
     let e = fileDocs.get(relPath)
     if (e) return e
@@ -1125,9 +1255,16 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     // 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', () => {
+    fprovider.on('connection-error', (ev) => {
       if (e.synced) return // already have the content; a later blip is the provider's business
       refusedFiles.set(relPath, (refusedFiles.get(relPath) || 0) + 1)
+      // HIV-P13. THE STATUS CODE WAS THROWN AWAY HERE, and it is the only authoritative evidence
+      // in the whole path. joinRoom in hive-mcp.js already captured it from this same event; this
+      // handler took no argument at all, so noteRefusals had nothing but "N files are quiet" and
+      // had to INFER a cause -- which is how it came to announce Q430 on 21 Sep while the relay
+      // sat at 56 of 512. explain() above maps these codes correctly and has done since 5 Sep.
+      const code = ev && (ev.code || ev.status)
+      if (code) refusedCodes.set(relPath, code)
       noteRefusals()
     })
     // Newly opened counts as used, and opening is the moment the working set can go over
@@ -1237,6 +1374,46 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // 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.
+  // HIV-P3, 20 Sep 2026. THE GENESIS CASE: the five tests above are all false for a root-level
+  // file that DOES NOT EXIST YET, which is the most common reason anyone claims at all -- you
+  // claim `config.env` precisely because you are about to create it. Found by DeepMind-Agent.
+  // So HIV-27's guard had a hole in exactly the case it was written for: claim succeeds, write
+  // succeeds, the local gate passes because in YOUR folder the file is real, and the bytes never
+  // leave. Born invisible, every signal green.
+  //
+  // THE ONLY QUESTION IS: is this bare string a FILE-TO-BE or a LOGICAL LABEL? Nothing on disk
+  // and nothing in the room can answer it, so this is a guess, and the direction of the guess is
+  // what matters. Guessing "file" too eagerly refuses legitimate region claims -- and under an
+  // allow-list .gitignore that means refusing ALMOST ALL of them, which gets the guard switched
+  // off within a day and costs more than the hole. So every rule here must be one a LABEL would
+  // essentially never satisfy.
+  //
+  // THE DIGIT RULE IS THE LOAD-BEARING ONE and it is not obvious. A trailing dot-segment
+  // containing a LETTER is an extension: .js .env .secret. One that is ALL DIGITS is a version
+  // number: v1.2, release-0.11.6, HIV-P3.5. Without that distinction every ticket id and release
+  // label in this room's own vocabulary gets refused as a file.
+  //
+  // WHAT THIS DOES NOT CLOSE, stated rather than discovered later. Extensionless root files that
+  // are neither conventional nor `*file` shaped -- a bare `config`, `staging`, `hosts` -- are
+  // still read as labels and still go invisible. The hole narrows; it does not close. It cannot
+  // close here, because at claim time the string is all we have. The rest belongs at WRITE time,
+  // where a path that appears on disk inside the room folder is a fact and needs no heuristic.
+  // That is HIV-P8, and it is filed rather than quietly assumed.
+  const EXTENSIONLESS_ROOT_FILES = new Set([
+    'LICENSE', 'LICENCE', 'README', 'CHANGELOG', 'CHANGES', 'NOTICE', 'AUTHORS', 'CONTRIBUTORS',
+    'CODEOWNERS', 'COPYING', 'INSTALL', 'CONTRIBUTING', 'VERSION', 'MAINTAINERS', 'TODO',
+  ])
+  const looksLikeFilename = (p) => {
+    if (/\s/.test(p)) return false                       // "the parser rewrite", "P3 lane"
+    if (/\.[^.]*[A-Za-z][^.]*$/.test(p)) return true     // .js .env .secret -- but NOT .2 .5 .6
+    if (EXTENSIONLESS_ROOT_FILES.has(p.toUpperCase())) return true
+    // Makefile, Dockerfile, Rakefile, Gemfile, Procfile, Vagrantfile, Justfile, Caddyfile.
+    // Capital-initial and case-SENSITIVE on purpose: lowercase "profile" and "logfile" are
+    // perfectly ordinary region names and must stay claimable.
+    if (/^[A-Z][A-Za-z]+file$/.test(p)) return true
+    return false
+  }
+
   const whyNotShared = (relPath) => {
     const p = String(relPath || '')
     if (!p) return ''
@@ -1245,6 +1422,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     // 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('/')
+      || looksLikeFilename(p)                    // HIV-P3: the genesis case -- see above
     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`
@@ -1260,6 +1438,12 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // files" (adopt the room's copy) and "this file was created during the session"
   // (a creation race -- merge, never adopt). Populated once, on the first scan.
   const preexisting = new Set()
+  // HIV-P14b. Manifest keys as of our first sync: what the ROOM held before we arrived.
+  // `preexisting` records our DISK, which structurally cannot distinguish "nobody had this file"
+  // from "the room had it all along and we never fetched it". null until the first sync, and null
+  // must never be read as "the room was empty" -- that would classify every joiner's first
+  // creation as a race, which is the bug this exists to fix.
+  let roomAtJoin = null
   let firstScanDone = false
   const shadow = new Map()     // relPath -> exact bytes THIS ENGINE last wrote/captured (source-level edit capture)
   // THE SAME THING, FROM THE PREVIOUS SESSION, and the reason it exists:
@@ -1283,15 +1467,28 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // work (it would look like a deliberate deletion against an up-to-date base).
 
   const rel = (full) => path.relative(ROOT, full).split(path.sep).join('/')
-  function walk(d, acc = []) {
+  // HIV-P8: `skipped` collects the files this walk DECLINES to sync, and that second list is the
+  // whole ticket. Everything in this engine is derived from "the files we sync", so every natural
+  // place to notice a born-invisible file is definitionally blind to it: walk() dropped ignored
+  // paths, so scan() never saw them, so reconcile() was never called for them, so the guard at the
+  // top of reconcile() was unreachable for exactly the class of file it names. Hooking there would
+  // have passed a unit test that called reconcile() directly and done nothing in a real session.
+  //
+  // DIRECTORY PRUNING IS UNCHANGED, deliberately. Descending into ignored directories to find
+  // ignored files would walk vendor and build trees on every tick. Measured on a real checkout with
+  // pruning kept: 7934 synced, 256 ignored files visible, 280 directories descended, 191ms for the
+  // whole traversal — and that traversal already happens. We are keeping an answer isIgnored()
+  // already computed instead of discarding it. An ignored file inside an ignored directory stays
+  // unseen, which is the correct trade at that price.
+  function walk(d, acc = [], skipped = []) {
     let entries = []
     try { entries = fs.readdirSync(d, { withFileTypes: true }) } catch { return acc }
     for (const e of entries) {
       if (IGNORE.has(e.name)) continue
       const full = path.join(d, e.name)
       const r = rel(full)
-      if (e.isDirectory()) { if (!isIgnored(r + '/')) walk(full, acc) }      // prune ignored dirs
-      else if (e.isFile()) { if (!isIgnored(r)) acc.push(full) }             // skip ignored/secret files
+      if (e.isDirectory()) { if (!isIgnored(r + '/')) walk(full, acc, skipped) }   // prune ignored dirs
+      else if (e.isFile()) { if (isIgnored(r)) skipped.push(full); else acc.push(full) }
     }
     return acc
   }
@@ -1441,10 +1638,19 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     // 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)
+    // HIV-P14b tracing, env-gated. Which branch a blind recreate actually takes was guessed
+    // wrong twice from reading the code; this answers it from the running product.
+    if (process.env.HIVE_P14_DEBUG && new RegExp(process.env.HIVE_P14_DEBUG).test(relPath)) {
+      log(`[P14] ${relPath} origin=${origin} synced=${fe.synced} docLen=${docText.length} ` +
+        `diskLen=${disk === null ? 'null' : disk.length} hasBase=${bases.has(relPath)} ` +
+        `priorShadow=${priorShadow.has(relPath)} inManifest=${manifest.has(relPath)} ` +
+        `preexisting=${preexisting.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
+      if (process.env.HIVE_P14_DEBUG) log(`[P14] BRANCH=genesis-publish ${relPath}`)
       fe.doc.transact(() => applyDiff(fe.text, disk))
       stampProvenance(relPath, '', disk) // genesis: sign the file's first content (base = empty)
       manifest.set(relPath, 1)
@@ -1492,6 +1698,72 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       // disjoint additions union (the normal case -- each author added their own
       // block), and a real overlap raises conflict markers for a human to settle
       // instead of the engine quietly picking a winner on arrival order.
+      // HIV-P14b, OPEN AND DELIBERATELY NOT IMPLEMENTED HERE YET.
+      //
+      // There is a third case this dichotomy misses: the path appeared on OUR disk after we
+      // started AND the room already had it before we joined. That is not a race -- the agent
+      // could not see the file (bounded working set, nothing touched it), believed it did not
+      // exist, and wrote one. Measured 21 Sep 2026: agent B recreated mod039.js and agent A's
+      // copy ended up with two const declarations of the same name.
+      //
+      // `preexisting` records our DISK, so it structurally cannot tell those apart; the manifest
+      // as of first sync can. A guard on that was written and REMOVED before shipping, because
+      // the probe showed it never firing -- most likely the manifest is not yet populated at the
+      // instant the base provider reports sync, so the snapshot came back empty. A refusal path
+      // that silently never runs is worse than none: it reads as protection in review and does
+      // nothing in production, which is the defect class this repo keeps hitting.
+      //
+      // What ships instead is the reporting half, which is verified: status() now exposes
+      // filesHeld/roomFiles/filesMissing instead of a full house, and the join announces the gap
+      // with the count and the remedy. An agent told "33 files exist here that you do not have,
+      // reading the path fetches it" will not recreate them. That removes the cause; the guard
+      // is the belt for when it happens anyway, and it lands when it is proven to fire.
+      if (process.env.HIVE_P14_DEBUG) log(`[P14] BRANCH=no-base-block ${relPath} preexisting=${preexisting.has(relPath)}`)
+      // HIV-P14b. A BLIND RECREATE IS NOT A RACE, and the empty-base merge below corrupts it.
+      //
+      // The dichotomy above has a third case: the path appeared on OUR disk after we started AND
+      // the room already had it before we joined. The working set is bounded, nothing touched
+      // that file, so the agent could not see it, concluded it did not exist, and wrote one.
+      //
+      // Measured 21 Sep 2026, traced through the running product. Agent B, holding 8 of a room's
+      // 41 files, wrote mod039.js:
+      //   mod039.js origin=remote synced=true docLen=22 diskLen=39 hasBase=false
+      //             inManifest=true preexisting=false   -> BRANCH=no-base-block
+      // It lands exactly here, `preexisting` is false, and the empty-base merge unions two whole
+      // files into agent A's copy:
+      //   export const v39 = 39
+      //   export const v39 = "FROM SCRATCH BY B"
+      // Two const declarations of the same name. Invalid code, in someone else's folder, from B
+      // doing the only thing available to it.
+      //
+      // The union is right for what the comment above describes -- two authors adding DIFFERENT
+      // blocks to a file they both just created. It is wrong for two independent whole-file
+      // creations of the same module, which is what a blind recreate always is.
+      //
+      // `roomAtJoin` is the discriminator `preexisting` cannot be: a path in it existed in the
+      // ROOM before we did, however new it is on our disk. The `roomAtJoin &&` guard is
+      // load-bearing -- before first sync it is null, and treating null as an empty room would
+      // classify every joiner's first creation as a race.
+      //
+      // Adopt the room's copy, because it is the real file and the agent needs it to work from,
+      // and snapshot the local draft so nothing the agent wrote is lost. Then say so loudly: the
+      // entire failure was the agent not knowing the file was already there.
+      if (roomAtJoin && roomAtJoin.has(relPath) && !preexisting.has(relPath)) {
+        captureSnapshot(relPath, disk, name, {
+          force: true, kind: 'manual',
+          label: `local draft preserved — ${relPath} already existed in the room before this client joined`,
+        })
+        bases.set(relPath, docText); forkBases.set(relPath, docText); shadow.set(relPath, docText)
+        if (docText !== disk) writeToDisk(relPath, docText)
+        try {
+          say(`⚠ ${relPath} ALREADY EXISTED IN THE ROOM before I joined — I had not fetched it, so it was ` +
+            `written here from scratch. The room's copy is now on disk and my draft was snapshotted. ` +
+            `This folder holds a bounded working set: a file you cannot see may still exist, so read or ` +
+            `claim the path before creating it. hive_status reports filesHeld of roomFiles.`)
+        } catch { }
+        if (process.env.HIVE_P14_DEBUG) log(`[P14] BRANCH=blind-recreate-refused ${relPath}`)
+        return
+      }
       if (!preexisting.has(relPath)) {
         // Terminate both sides before merging. With an empty base there is no shared
         // trailing context, so a side whose last line lacks a newline gets its final
@@ -1499,6 +1771,33 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         // which is worse than failing -- it reads as corruption to whoever opens it.
         const nl = (s) => (s === '' || s.endsWith('\n') ? s : s + '\n')
         const r0 = icrMerge3('', nl(disk), nl(docText), relPath)
+        // HIV-P17: SILENT COLLISION DETECTION on genesis-publish creation race.
+        // The normal merge path (below, ~line 1880) runs fusionReason() to catch merges
+        // that broke valid code or duplicated structure. This creation-race path skipped
+        // that check entirely — a dead-heat race could silently fuse two whole-file
+        // rewrites of the same module and nobody was told. Now we run the same check:
+        // if both inputs parsed but the merged result does not, or if the merge duplicated
+        // structure, refuse it — keep both sides intact and announce loudly.
+        if (!r0.conflict) {
+          const why = fusionReason(r0.text, nl(disk), nl(docText), supports(relPath) ? languageFor(relPath) : null)
+          if (why) {
+            conflicted.add(relPath)
+            // Do NOT write the fused result to doc or disk. The doc already holds docText
+            // (the room's copy) and disk holds the local draft — both are intact. Setting
+            // bases to docText means the next normal edit will merge against the room's copy,
+            // which is the same recovery path the normal-merge refusal uses.
+            bases.set(relPath, docText); forkBases.set(relPath, docText); shadow.set(relPath, docText)
+            if (!manifest.has(relPath)) manifest.set(relPath, 1)
+            if (icrWarned.get(relPath) !== why) {
+              icrWarned.set(relPath, why)
+              log(`[${name}] !! HIV-P17 REFUSED a fused creation-race merge of ${relPath}: ${why}`)
+              try {
+                say(`[!] @all ${relPath}: a creation-race 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. 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
+          }
+        }
         if (r0.text !== docText) fe.doc.transact(() => applyDiff(yt, r0.text))
         if (r0.text !== disk) writeToDisk(relPath, r0.text)
         if (r0.conflict) conflicted.add(relPath)
@@ -1533,14 +1832,31 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         try { say(`⚠ ${relPath} changed locally while ${name} was disconnected — the local edit and the room copy were merged${rj.conflict ? ', and CONFLICT markers need resolving' : ''}. Pre-merge local copy is in the file's history.`) } catch { }
         return
       }
-      // Genuinely no ancestor (a clone-then-join). Adopt the room's copy, keep ours as a
-      // restore point — and SAY SO. This branch used to be the only silent one on this
-      // path, which is why the data loss went unnoticed rather than merely being rare.
-      captureSnapshot(relPath, disk, name, { force: true, kind: 'manual', label: 'local copy at join (room copy adopted)' })
-      writeToDisk(relPath, docText)
-      bases.set(relPath, docText); forkBases.set(relPath, docText)
-      if (!snappedBase.has(relPath)) { captureSnapshot(relPath, docText, name, { force: true, kind: 'base', label: 'adopted from room at join' }); snappedBase.add(relPath) }
-      try { say(`↓ ${relPath} already existed in this room — ${name} adopted the room's copy. The local version before joining is saved in the file's history.`) } catch { }
+      // Genuinely no ancestor (a clone-then-join, or joining with an existing checkout).
+      // HIV-P9: Do NOT adopt the room's copy blindly. Check provenance!
+      // Has the room ever seen what is currently on disk?
+      const receipts = fe && fe.ledger ? fe.ledger.toArray() : []
+      const st = accountFor({ rel: relPath, branchText: disk, roomText: docText, receipts })
+
+      if (st.state === DESCENDS || st.state === IDENTICAL) {
+        // Safe: The room has passed through our disk content, so the room's copy is a true descendant.
+        captureSnapshot(relPath, disk, name, { force: true, kind: 'manual', label: 'local copy at join (room copy adopted)' })
+        writeToDisk(relPath, docText)
+        bases.set(relPath, docText); forkBases.set(relPath, docText)
+        if (!snappedBase.has(relPath)) { captureSnapshot(relPath, docText, name, { force: true, kind: 'base', label: 'adopted from room at join' }); snappedBase.add(relPath) }
+        try { say(`↓ ${relPath} already existed in this room — ${name} adopted the room's copy. The local version before joining is saved in the file's history.`) } catch { }
+        return
+      }
+
+      // DIVERGED or UNPROVEN: The room has NEVER seen local disk's content, or has no proof.
+      // Overwriting disk with docText would cause silent data loss (e.g. wiping out local fixes).
+      // Merging from an empty base would concatenate both copies, creating invalid syntax.
+      // Refuse adoption: keep local disk untouched, keep room doc untouched, snapshot local, and announce loudly.
+      captureSnapshot(relPath, disk, name, { force: true, kind: 'manual', label: `local copy preserved at join (${st.state}: room copy refused)` })
+      bases.set(relPath, disk); forkBases.set(relPath, disk)
+      try {
+        say(`⚠ ${relPath} already existed in room with different content (${st.state}) — room copy was NOT adopted. Local disk was preserved. Resolve deliberately.`)
+      } catch { }
       return
     }
     const base = bases.has(relPath) ? bases.get(relPath) : disk
@@ -1956,7 +2272,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   let myEditing = null, myLastEdit = null
   let editingClearTimer = null
   const warnedAt = new Map() // file -> last time we warned about co-editing it
-  const setUserState = () => provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, editing: myEditing || undefined, lastEdit: myLastEdit || undefined, v: PROTOCOL_VERSION })
+  const setUserState = () => provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, editing: myEditing || undefined, lastEdit: myLastEdit || undefined, v: PROTOCOL_VERSION, passive: !!passive })
   function markEditing(relPath) {
     myEditing = { file: relPath, at: Date.now() }
     myLastEdit = myEditing
@@ -2058,16 +2374,106 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   }
   if (syncFiles) provider.awareness.on('change', () => { renderMembers(); renderClaims(); checkVersions() })
 
+  // HIV-P8: A FILE THAT WILL NEVER LEAVE THIS FOLDER, SAID OUT LOUD.
+  //
+  // HIV-P3 closed the genesis-claim hole at CLAIM time by classifying the claim string, and it
+  // could only ever be a classifier: at claim time a bare string is all there is, and `config`,
+  // `hosts` and `staging` are indistinguishable from ticket labels. At WRITE time there is no
+  // ambiguity left — the file is on disk and isIgnored() is exact. So this is the backstop for
+  // everything the classifier could not decide.
+  //
+  // IT CANNOT REFUSE. The bytes are already written by the time anyone knows, so this is
+  // structurally a warning — and a warning is exactly what every born-invisible incident has
+  // already scrolled past. That is why the claimed case opens an OBLIGATION instead of logging:
+  // an obligation rides hive_wait, backs off, escalates to STALE and shows on the board. It is
+  // un-ignorable by construction and costs nothing while nobody is idle.
+  //
+  // THE TWO GATES ARE THE WHOLE DESIGN, and the numbers are why. On a real checkout there are 256
+  // ignored files. Warning about all of them would open 256 debts on join, each closable only by
+  // its author, and the ledger would be unusable inside one join — the same flooding we spent this
+  // morning clearing forty entries of. So:
+  //   CLAIMED     the author declared they were working on this path. That is their own stated
+  //               intent, already in the CRDT — not a guess about the filename.
+  //   NOT PREEXISTING   it appeared during this session, rather than having sat there for a week.
+  // Neither alone is sufficient: without the claim gate, 256; without the other, every long-lived
+  // ignored file re-fires on every join.
+  //
+  // THE UNCLAIMED CASE GETS ONE LINE AND NO LEDGER ENTRY. The room rule is CLAIM BEFORE YOU WRITE,
+  // so an unclaimed write is outside the protocol and does not get to consume the ledger. I am not
+  // confident this tier earns its place — a chat line is precisely the signal these incidents
+  // scroll past — but deleting the case entirely is worse than announcing it cheaply.
+  const ENGINE_ID = 'hivecode'
+  const invisibleWarned = new Map()  // relPath -> obligation id, or null for the ambient case
+
+  function noticeBornInvisible(ignoredRel) {
+    // DISCHARGE FIRST. A file that has gone away takes its debt with it: the question "this will
+    // never sync" stops being a question when there is nothing left to sync. Left open, the ledger
+    // fills with debts about paths that no longer exist, which is the noise the three-state
+    // lifecycle exists to prevent. Its expiry cannot help here — that only covers names never seen
+    // in the room, and this path was seen, on disk, by us.
+    for (const [r, id] of [...invisibleWarned]) {
+      if (ignoredRel.has(r)) continue
+      if (id) { try { OB.discharge(doc.getMap('obligations'), { id, by: ENGINE_ID }) } catch { } }
+      invisibleWarned.delete(r)
+    }
+    for (const r of ignoredRel) {
+      if (SKIP.has(r)) continue           // control files are ours and are supposed to be invisible
+      if (preexisting.has(r)) continue    // it was already here; nobody did this during the session
+      if (invisibleWarned.has(r)) continue // once per path, not once per scan tick
+      const holder = coordinator.sense(r)
+      if (holder && holder.by) {
+        let id = null
+        try {
+          const rec = OB.open(doc.getMap('obligations'), {
+            from: ENGINE_ID,
+            to: holder.by,
+            text: `${r} is on disk and claimed by you, but it is ignored by a .gitignore here — ` +
+              `no sync connection is opened for it, so nothing written to it will ever reach the room. ` +
+              `Add it to the allow-list, or confirm the work is deliberately local.`,
+            absent: false,
+            neverSeen: false,
+          })
+          id = rec && rec.id
+        } catch { }
+        invisibleWarned.set(r, id)
+        try {
+          say(`⛔ ${r} is claimed and on disk, but it is ignored by a .gitignore here — its bytes will never leave this folder.`)
+        } catch { }
+      } else {
+        invisibleWarned.set(r, null)
+        try {
+          say(`· ${r} was created here but is ignored by a .gitignore — it stays local, and no other agent will see it.`)
+        } catch { }
+      }
+    }
+  }
+
   function scan() {
-    const diskFulls = walk(ROOT)
+    const skippedFulls = []
+    const diskFulls = walk(ROOT, [], skippedFulls)
     const diskRel = new Set(diskFulls.map(rel))
+    const ignoredRel = new Set(skippedFulls.map(rel))
     // Snapshot the starting file set BEFORE the first reconcile pass touches anything.
     // Everything here pre-dates our participation; anything that shows up later was
     // authored while we were connected. See `preexisting`.
     // The ancestor must be loaded BEFORE any path can reach reconcile(), and this is the
     // one place guaranteed to run first exactly once. Loading it later would mean the first
     // scan's reconciles see no ancestor — precisely the bug this is here to close.
-    if (!firstScanDone) { loadPriorShadow(); for (const r of diskRel) preexisting.add(r); firstScanDone = true }
+    //
+    // HIV-P8: THE UNION IS NOT A DETAIL. `preexisting` used to be seeded from diskRel alone, and
+    // diskRel comes from walk(), which dropped ignored files — so `preexisting.has(r)` was
+    // permanently FALSE for every ignored path, whether it was created a second ago or had been
+    // sitting there for a week. Any check phrased as "ignored AND not preexisting" therefore
+    // reduced to "ignored", and a client joining a real checkout would have opened an obligation
+    // for each of its 256 ignored files, about files nobody touched. Seeding the union is what
+    // makes "not preexisting" mean what it says: authored during this session.
+    if (!firstScanDone) {
+      loadPriorShadow()
+      for (const r of diskRel) preexisting.add(r)
+      for (const r of ignoredRel) preexisting.add(r)
+      firstScanDone = true
+    }
+    noticeBornInvisible(ignoredRel)
     for (const full of diskFulls) {
       const r = rel(full)
       if (SKIP.has(r)) continue
@@ -2127,6 +2533,14 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
 
   provider.on('sync', (s) => {
     if (!s || !syncFiles) return
+    // HIV-P14b. Snapshot what the room already had, once. Measured: the manifest IS populated at
+    // this point -- a fresh joiner's observer fires with 13 of 13 entries before the sync event,
+    // so reading it here is sound. (That was checked because the first version of this guard was
+    // wrongly assumed to be failing for this reason.)
+    if (!roomAtJoin) {
+      roomAtJoin = new Set()
+      try { for (const k of manifest.keys()) roomAtJoin.add(k) } catch { }
+    }
     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
     // Connect to every file I'm granted AND have not excluded; each file-room's sync pulls
@@ -2162,6 +2576,31 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     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.`)
+    // HIV-P14. SAY THE GAP OUT LOUD, ONCE, AT JOIN.
+    //
+    // The working set is bounded on purpose, and the documented trade is that "a file outside it
+    // does not arrive until something touches it". For a human reading a folder that is fine. For
+    // an AI agent it is not, because an agent decides what exists by listing its directory: a
+    // file it cannot see is a file it believes does not exist, and it writes one. Measured 21 Sep
+    // 2026, a 40-file room and MAX_OPEN=8: the joiner held 7 files, reported "filesSynced 8/8",
+    // said nothing, and its agent recreated a file the room already had.
+    //
+    // Nothing here changes the cap. It tells the agent the number it needs in order to ASK,
+    // which is the one thing that makes "until something touches it" true.
+    setTimeout(() => {
+      try {
+        const want = [...manifest.keys()].filter((r) => canOpen(r) && !SKIP.has(r))
+        const have = want.filter((r) => fs.existsSync(path.join(ROOT, r)))
+        const short = want.length - have.length
+        if (short <= 0) return
+        log(`[${name}] !! THIS FOLDER IS INCOMPLETE ON PURPOSE. The room has ${want.length} files; ` +
+          `${have.length} are on disk here and ${short} are NOT. The working set is bounded to ` +
+          `${MAX_OPEN} open files (HIVE_MAX_OPEN_FILES), because one socket is opened per file and a ` +
+          `relay admits a limited number. A missing file EXISTS — it simply has not been fetched. ` +
+          `Do not treat it as absent and do not create it: reading or claiming the path fetches it. ` +
+          `hive_status reports filesHeld of roomFiles, and hive_read_board lists what the room holds.`)
+      } catch { }
+    }, 4000).unref?.()
     if (!scanTimer) {
       startWatch()
       scanTimer = setInterval(scan, watcher ? 2000 : 400) // watch handles fast path; scan is the net
@@ -2265,7 +2704,26 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     isPaused,            // is a participant currently paused?
     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)
+    // HIV-P18: a claim is a promise about BYTES, so granting one over bytes the claimer cannot
+    // see is the same false success we shut in the outbound direction (HIV-27: a claim whose
+    // writes could never leave). The claim itself is unchanged -- callers and every existing
+    // suite still get the same boolean -- but it now also starts the fetch the README has been
+    // promising, so an agent that claims a path it does not hold actually receives it instead of
+    // finding an empty directory and creating the file from scratch.
+    claim: (region, intent) => {
+      const r = String(region), i = String(intent || 'edit')
+      myIntents.set(r, i)
+      const held = coordinator.acquire(r, i)
+      // Fire-and-forget on purpose: claim's contract is synchronous and changing that would
+      // break every caller. Use fetch(path) directly when you need to WAIT for the bytes.
+      if (held) { try { fetchFile(r).catch(() => {}) } catch { } }
+      return held
+    }, // true iff you hold it (my intent recorded either way — it's what my receipts sign)
+    // HIV-P18: bring a file the room has but this folder does not. Resolves when the BYTES have
+    // landed, and distinguishes "outside the working set" (fetchable) from "not in the room at
+    // all" (nothing will ever arrive) -- two states that look identical from an empty directory
+    // and have opposite remedies.
+    fetch: fetchFile,
     // 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
@@ -2367,7 +2825,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         const u = s.user
         if (!u || !u.name) continue
         const prev = seen.get(u.name) || {}
-        seen.set(u.name, { ...prev, ...u, editing: u.editing || prev.editing, owner: u.owner || prev.owner })
+        seen.set(u.name, { ...prev, ...u, editing: u.editing || prev.editing, owner: u.owner || prev.owner, passive: !!(u.passive || prev.passive) })
       }
       return [...seen.values()]
     },
@@ -2386,11 +2844,42 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       // 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 })
+      // HIV-P14. THE FULL-HOUSE LIE.
+      //
+      // `files` and `filesSynced` both counted OPEN docs, so a client holding eight of the
+      // room's forty files reported "filesSynced 8/8" -- a complete set. Measured 21 Sep 2026:
+      // a second agent joined a 40-file room, received 7, stayed at 7 for a full minute, and
+      // reported 8/8. Its manifest listed all forty the whole time.
+      //
+      // The bounded working set is deliberate and correct -- one socket per file against a 512
+      // ceiling is the wall, and tests/open-file-cap-test.mjs documents the trade rather than
+      // hiding it: "a file outside the working set does not arrive until something touches it."
+      // What that header does not cover is that FOR AN AGENT, NOTHING EVER TOUCHES IT. An agent
+      // decides what exists by reading its folder; a file it cannot see is a file it believes
+      // does not exist, so it writes one from scratch. Measured consequence, same probe: agent B
+      // created mod039.js, and agent A's copy ended up holding two const declarations of the
+      // same name -- invalid code, in someone else's folder, from B doing the only reasonable
+      // thing available to it.
+      //
+      // So the trade stays and the reporting changes. `files` keeps meaning open docs, because
+      // tests/open-file-cap-test.mjs:71 pins it as the proof the cap is respected. What is added
+      // is the pair that was missing: what the ROOM has, and what this client actually HOLDS.
+      const roomFiles = (() => { try { return [...manifest.keys()].filter((r) => canOpen(r)).length } catch { return 0 } })()
+      const held = (() => {
+        let n = 0
+        try { for (const r of manifest.keys()) { if (canOpen(r) && fs.existsSync(path.join(ROOT, r))) n++ } } catch { }
+        return n
+      })()
       return {
         connected: !!provider.wsconnected,
         connecting: !!provider.wsconnecting,
         files: fileDocs.size,
         filesSynced: synced,
+        // The honest pair. `filesHeld` of `roomFiles` is the number a joiner needs, and the one
+        // that says 7 of 40 where filesSynced said 8 of 8.
+        roomFiles,
+        filesHeld: held,
+        filesMissing: Math.max(0, roomFiles - held),
         notSyncing: notSyncing.length,
         notSyncingFiles: notSyncing.slice(0, 20),
         // The working set and its bound. `openCap` x agents must stay under the relay's