hivecode-mcp 0.11.6 → 0.12.1

package/hive-mux-proto.js

@@ -0,0 +1,58 @@
+// hive-mux-proto.js -- the wire format for ONE socket per participant, shared by relay and client.
+//
+// WHY: Hivecode opened one WebSocket per FILE. A participant held 1 + min(files, 128) sockets,
+// so an agent in a 1000-file repository saw only 128 files on disk, and a relay's connection cap
+// divided by 129 per person. The mux carries every file doc of one room over one socket.
+//
+// The design rule that makes it safe: the relay does not grow a second enforcement path. Each
+// OPEN runs the SAME per-doc admission a per-file upgrade runs (token scope for that path, the
+// per-room ceiling, the committer limit), and the accepted channel is wrapped in a VirtualConn
+// that looks exactly like a ws connection to installUsageLimits, makeReadOnly, installWriteGate
+// and setupWSConnection. The bytes inside a MSG frame are the same y-protocols message a
+// per-file socket would carry.
+//
+// Frames are binary, lib0-encoded:
+//   client -> relay   OPEN     [0, id, docName]       open this file doc as channel `id`
+//                     CLOSE    [1, id]                the client is done with it
+//                     MSG      [2, id, ...payload]    a y-protocols message for that doc
+//   relay -> client   MSG      [2, id, ...payload]
+//                     OPENED   [3, id]                admitted; the relay's sync step 1 follows
+//                     REFUSED  [4, id, code, reason]  not admitted -- the HTTP status a per-file
+//                                                     upgrade would have answered, and why
+//                     CLOSED   [5, id, reason]        the relay closed that channel
+//                     BEAT     [6, 0]                 liveness, so a dead socket is noticed
+// Channel ids are chosen by the client and are only meaningful on the socket that opened them.
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+
+export const MUX_PREFIX = '_hive_mux/'
+export const MUX_VERSION = 1
+export const F = Object.freeze({ OPEN: 0, CLOSE: 1, MSG: 2, OPENED: 3, REFUSED: 4, CLOSED: 5, BEAT: 6 })
+
+export function encodeFrame(kind, id, a, b) {
+  const e = encoding.createEncoder()
+  encoding.writeVarUint(e, kind)
+  encoding.writeVarUint(e, id >>> 0)
+  if (kind === F.OPEN) encoding.writeVarString(e, String(a))
+  else if (kind === F.MSG) encoding.writeUint8Array(e, a instanceof Uint8Array ? a : new Uint8Array(a))
+  else if (kind === F.REFUSED) { encoding.writeVarUint(e, a >>> 0); encoding.writeVarString(e, String(b || '')) }
+  else if (kind === F.CLOSED) encoding.writeVarString(e, String(a || ''))
+  return encoding.toUint8Array(e)
+}
+
+/** Decode one frame. Throws on garbage, which the caller treats as a protocol violation. */
+export function decodeFrame(buf) {
+  const u8 = buf instanceof Uint8Array ? buf : new Uint8Array(buf)
+  const d = decoding.createDecoder(u8)
+  const kind = decoding.readVarUint(d)
+  const id = decoding.readVarUint(d)
+  if (kind === F.OPEN) return { kind, id, docName: decoding.readVarString(d) }
+  if (kind === F.MSG) return { kind, id, payload: u8.subarray(d.pos) }
+  if (kind === F.REFUSED) return { kind, id, code: decoding.readVarUint(d), reason: decoding.readVarString(d) }
+  if (kind === F.CLOSED) return { kind, id, reason: decoding.readVarString(d) }
+  if (kind === F.CLOSE || kind === F.OPENED || kind === F.BEAT) return { kind, id }
+  throw new Error(`unknown mux frame kind ${kind}`)
+}
+
+/** The mux upgrade path for a base room, as the relay parses it (pathname minus the slash). */
+export function muxPath(room) { return MUX_PREFIX + encodeURIComponent(room) }

package/hive-mux.js

@@ -0,0 +1,350 @@
+// hive-mux.js -- the client half of ONE socket per participant (wire format: hive-mux-proto.js).
+//
+// sync.js asks this module for a provider per file doc and gets back an object with the surface
+// it already used from y-websocket's WebsocketProvider: `synced`, the 'sync' / 'status' /
+// 'connection-error' / 'connection-close' events, and destroy(). Behind it is EITHER a channel
+// on the participant's one mux socket, or -- when the relay does not advertise mux in /health,
+// or HIVE_MUX=0 -- a plain per-file WebsocketProvider exactly as before. An old relay therefore
+// keeps working with a new client, and the choice is made once per session, before any file
+// socket exists, so a room never ends up half on one transport by accident.
+//
+// Inside a channel the y-protocols exchange is the one y-websocket performs: on admission send
+// sync step 1, answer the relay's step 1, count the session synced when step 2 arrives, forward
+// local updates, never echo an update this provider applied. A refused OPEN is reported as a
+// 'connection-error' carrying the same HTTP status a refused per-file upgrade carried, so every
+// piece of refusal reporting in sync.js (Q430/Q431 counts, notSyncing, explain()) works unchanged.
+import * as syncProtocol from 'y-protocols/sync'
+import * as encoding from 'lib0/encoding'
+import * as decoding from 'lib0/decoding'
+import { ObservableV2 } from 'lib0/observable'
+import { WebsocketProvider } from 'y-websocket'
+import { F, encodeFrame, decodeFrame, muxPath, MUX_VERSION } from './hive-mux-proto.js'
+
+const messageSync = 0
+
+export const httpBase = (relay) => String(relay).replace(/^wss:/, 'https:').replace(/^ws:/, 'http:').replace(/\/+$/, '')
+
+/** The provider sync.js holds per file. Delegates to a mux channel or a legacy provider. */
+class FileProvider extends ObservableV2 {
+  constructor(docName, doc) {
+    super()
+    this.docName = docName
+    this.doc = doc
+    this.destroyed = false
+    this._impl = null
+  }
+  get synced() { return !!(this._impl && this._impl.synced) }
+  get wsconnected() { return !!(this._impl && this._impl.wsconnected) }
+  get transport() { return this._impl ? this._impl.transport : 'pending' }
+  _bindLegacy(relay, wsOpts) {
+    const p = new WebsocketProvider(relay, this.docName, this.doc, wsOpts)
+    for (const ev of ['sync', 'status', 'connection-error', 'connection-close']) p.on(ev, (...args) => this.emit(ev, args))
+    this._impl = { transport: 'socket', get synced() { return p.synced }, get wsconnected() { return p.wsconnected }, destroy: () => p.destroy() }
+  }
+  destroy() {
+    if (this.destroyed) return
+    this.destroyed = true
+    try { if (this._impl) this._impl.destroy() } catch { }
+    super.destroy()
+  }
+}
+
+class Channel {
+  constructor(mux, id, docName, doc, facade) {
+    this.mux = mux
+    this.id = id
+    this.docName = docName
+    this.doc = doc
+    this.facade = facade
+    this.transport = 'mux'
+    this.opened = false
+    this.synced = false
+    this.retries = 0
+    this.retryTimer = null
+    this.destroyed = false
+    this._onUpdate = (update, origin) => {
+      if (origin === this.facade || !this.opened) return // gaps are closed by the next step1/step2
+      const e = encoding.createEncoder()
+      encoding.writeVarUint(e, messageSync)
+      syncProtocol.writeUpdate(e, update)
+      this.mux.send(encodeFrame(F.MSG, this.id, encoding.toUint8Array(e)))
+    }
+    doc.on('update', this._onUpdate)
+  }
+  get wsconnected() { return this.opened && this.mux.connected }
+  sendOpen() {
+    if (this.destroyed || !this.mux.connected) return
+    clearTimeout(this.retryTimer); this.retryTimer = null
+    this.mux.send(encodeFrame(F.OPEN, this.id, this.docName))
+  }
+  retryLater() {
+    if (this.destroyed || this.retryTimer) return
+    // Refused or closed by the relay: back off, like the per-file provider did, but further --
+    // an OPEN is cheap to send and a relay at capacity should not be asked 40 times a second.
+    const ms = Math.min(15000, 500 * 2 ** Math.min(this.retries++, 5))
+    this.retryTimer = setTimeout(() => { this.retryTimer = null; this.sendOpen() }, ms)
+    if (this.retryTimer.unref) this.retryTimer.unref()
+  }
+  onFrame(f) {
+    if (this.destroyed) return
+    if (f.kind === F.OPENED) {
+      this.opened = true
+      this.retries = 0
+      const e = encoding.createEncoder()
+      encoding.writeVarUint(e, messageSync)
+      syncProtocol.writeSyncStep1(e, this.doc)
+      this.mux.send(encodeFrame(F.MSG, this.id, encoding.toUint8Array(e)))
+      this.facade.emit('status', [{ status: 'connected' }])
+    } else if (f.kind === F.MSG) {
+      try { this.onMessage(f.payload) } catch (e) {
+        // A message this doc could not apply. Skipping it would leave a gap that every later
+        // update builds on, silently; reopening makes the relay run the sync exchange again,
+        // and that carries whatever was missed.
+        this.mux.log(`[hive] could not apply a relay message for ${JSON.stringify(this.docName)} (${e && e.message}); resyncing it`)
+        this.reopen()
+      }
+    } else if (f.kind === F.REFUSED) {
+      this.opened = false
+      this.facade.emit('connection-error', [{ code: f.code, status: f.code, reason: f.reason, message: `Unexpected server response: ${f.code} ${f.reason}` }])
+      this.retryLater()
+    } else if (f.kind === F.CLOSED) {
+      this.lost({ code: 4000, reason: f.reason })
+      this.retryLater()
+    }
+  }
+  onMessage(payload) {
+    let d
+    try { d = decoding.createDecoder(payload) } catch { return }
+    const type = decoding.readVarUint(d)
+    if (type !== messageSync) return // awareness/auth/query: file docs carry no presence
+    const e = encoding.createEncoder()
+    encoding.writeVarUint(e, messageSync)
+    const t = syncProtocol.readSyncMessage(d, e, this.doc, this.facade)
+    if (t === syncProtocol.messageYjsSyncStep2 && !this.synced) {
+      this.synced = true
+      this.facade.emit('sync', [true])
+    }
+    if (encoding.length(e) > 1) this.mux.send(encodeFrame(F.MSG, this.id, encoding.toUint8Array(e)))
+  }
+  reopen() {
+    if (this.destroyed) return
+    if (this.mux.connected) this.mux.send(encodeFrame(F.CLOSE, this.id))
+    this.lost({ code: 4001, reason: 'resync' })
+    this.retryLater()
+  }
+  /** The channel is gone (socket dropped, or the relay closed it); a reconnect will reopen it. */
+  lost(ev = null) {
+    const wasOpen = this.opened
+    this.opened = false
+    if (this.synced) { this.synced = false; this.facade.emit('sync', [false]) }
+    if (wasOpen) {
+      this.facade.emit('connection-close', [ev])
+      this.facade.emit('status', [{ status: 'disconnected' }])
+    }
+  }
+  destroy() {
+    if (this.destroyed) return
+    this.destroyed = true
+    clearTimeout(this.retryTimer)
+    try { this.doc.off('update', this._onUpdate) } catch { }
+    if (this.mux.connected) this.mux.send(encodeFrame(F.CLOSE, this.id))
+    this.mux.channels.delete(this.id)
+  }
+}
+
+/** The participant's one physical socket, carrying a channel per open file doc. */
+class MuxConnection {
+  constructor({ relay, room, params, WebSocketPolyfill, log, onRefused }) {
+    const q = new URLSearchParams({ ...(params || {}), mux: String(MUX_VERSION) })
+    this.url = `${String(relay).replace(/\/+$/, '')}/${muxPath(room)}?${q}`
+    this.WS = WebSocketPolyfill
+    this.log = log || (() => { })
+    this.onRefused = onRefused || (() => { })
+    this.channels = new Map()
+    this.nextId = 1
+    this.ws = null
+    this.connected = false
+    this.connecting = false
+    this.destroyed = false
+    this.failures = 0
+    this.lastHeard = 0
+    this.reconnectTimer = null
+    // The relay sends a BEAT every 20s; 45s of silence means the socket is dead even if the OS
+    // has not said so, which is exactly the half-open state a laptop lid produces.
+    this.liveness = setInterval(() => {
+      // terminate, not close: a close handshake cannot complete on a dead link, and ws waits 30s more for it
+      if (this.connected && Date.now() - this.lastHeard > 45000) { try { this.ws.terminate ? this.ws.terminate() : this.ws.close() } catch { } }
+    }, 5000)
+    if (this.liveness.unref) this.liveness.unref()
+  }
+  channel(docName, doc, facade) {
+    const ch = new Channel(this, this.nextId++, docName, doc, facade)
+    this.channels.set(ch.id, ch)
+    if (this.connected) ch.sendOpen()
+    else this.connect()
+    return ch
+  }
+  send(bytes) {
+    if (!this.connected || !this.ws) return
+    try { this.ws.send(bytes) } catch { /* the close handler takes it from here */ }
+  }
+  connect() {
+    if (this.destroyed || this.connected || this.connecting) return
+    this.connecting = true
+    let ws
+    try { ws = new this.WS(this.url) } catch (e) { this.connecting = false; this.scheduleReconnect(); return }
+    ws.binaryType = 'arraybuffer'
+    this.ws = ws
+    ws.onopen = () => {
+      if (this.ws !== ws) return
+      this.connecting = false
+      this.connected = true
+      this.failures = 0
+      this.lastHeard = Date.now()
+      for (const ch of this.channels.values()) ch.sendOpen()
+    }
+    ws.onmessage = (ev) => {
+      if (this.ws !== ws) return
+      this.lastHeard = Date.now()
+      let f
+      try { f = decodeFrame(new Uint8Array(ev.data)) } catch { return }
+      if (f.kind === F.BEAT) return
+      const ch = this.channels.get(f.id)
+      if (ch) ch.onFrame(f)
+    }
+    ws.onerror = (ev) => {
+      if (this.ws !== ws) return
+      // A refused UPGRADE of the mux socket itself (401/402/403/429/503) refuses every file on it.
+      // Hand each unsynced channel the same event a refused per-file socket produced.
+      const m = /Unexpected server response:\s*(\d{3})/.exec((ev && (ev.message || (ev.error && ev.error.message))) || '')
+      const code = m ? Number(m[1]) : null
+      for (const ch of this.channels.values()) {
+        if (!ch.synced) ch.facade.emit('connection-error', [{ code, status: code, message: (ev && ev.message) || 'mux socket error' }])
+      }
+      if (code) this.onRefused(code)
+    }
+    ws.onclose = (ev) => {
+      if (this.ws !== ws) return
+      this.ws = null
+      this.connected = false
+      this.connecting = false
+      for (const ch of this.channels.values()) ch.lost(ev)
+      this.scheduleReconnect()
+    }
+  }
+  scheduleReconnect() {
+    if (this.destroyed || this.reconnectTimer || !this.channels.size) return
+    const ms = Math.min(5000, 100 * 2 ** Math.min(this.failures++, 6))
+    this.reconnectTimer = setTimeout(() => { this.reconnectTimer = null; this.connect() }, ms)
+    if (this.reconnectTimer.unref) this.reconnectTimer.unref()
+  }
+  destroy() {
+    this.destroyed = true
+    clearInterval(this.liveness)
+    clearTimeout(this.reconnectTimer)
+    const ws = this.ws
+    this.ws = null
+    // Disconnected FIRST: closing the socket ends every channel on the relay at once, so no
+    // channel sends a CLOSE frame of its own down a socket that is about to go.
+    this.connected = false
+    for (const ch of [...this.channels.values()]) { try { ch.destroy() } catch { } }
+    try { if (ws) ws.close() } catch { }
+  }
+}
+
+/**
+ * One per startSync. provide(docName, doc) returns the provider for a file doc; the transport is
+ * decided once -- HIVE_MUX=1 forces mux, HIVE_MUX=0 forces a socket per file, anything else asks
+ * the relay's /health -- and file providers created before the answer are bound when it comes.
+ */
+export function createFileTransport({ relay, room, wsOpts = {}, log = () => { }, env = process.env, fetchImpl = globalThis.fetch, onFallback = () => { }, retryMs = 1000, detectForMs = 90000 }) {
+  const forced = env.HIVE_MUX === '0' || env.HIVE_MUX === '1'
+  let mode = env.HIVE_MUX === '0' ? 'socket' : env.HIVE_MUX === '1' ? 'mux' : null
+  let mux = null
+  let stopped = false
+  const pending = new Set()
+  const health = () => Promise.resolve()
+    .then(() => fetchImpl(`${httpBase(relay)}/health`, { signal: AbortSignal.timeout(20000) }))
+    .then((r) => (r && r.ok ? r.json() : null))
+  const offersMux = (j) => !!j && Number(j.mux) >= MUX_VERSION
+
+  // THE KILL SWITCH HAS TO REACH CLIENTS THAT ARE ALREADY CONNECTED. A relay that stops serving
+  // mux -- an operator setting HIVE_RELAY_MUX=off, or a rollback to a build that predates it --
+  // refuses the mux socket from then on, and without this every file would stay refused until
+  // the agent restarted. A 404 says so outright. Any other refusal is checked against /health, at
+  // most once a minute, because a relay that predates mux reads the mux path as a room name and
+  // refuses the token -- a 401 that looks exactly like a real one.
+  let lastCheck = 0
+  const onRefused = (code) => {
+    if (forced || stopped || mode !== 'mux') return
+    if (code === 404) return fallBack('the relay no longer serves one-socket mode (404)')
+    const now = Date.now()
+    if (now - lastCheck < 60000) return
+    lastCheck = now
+    health().then((j) => { if (j && !offersMux(j)) fallBack('the relay stopped offering one-socket mode') }, () => { })
+  }
+  const fallBack = (why) => {
+    if (stopped || mode !== 'mux') return
+    mode = 'socket'
+    log(`[hive] ${why}: falling back to a socket per file`)
+    // sync.js lets go of every file beyond the per-file bound FIRST. Without that, a client holding
+    // 900 files on one socket would open 900 sockets at once -- the storm the bound exists to stop.
+    try { onFallback() } catch { }
+    const moving = mux ? [...mux.channels.values()].map((ch) => ch.facade) : []
+    try { if (mux) mux.destroy() } catch { }
+    mux = null
+    for (const fp of moving) { if (!fp.destroyed) fp._bindLegacy(relay, wsOpts) }
+  }
+  const bind = (fp) => {
+    if (fp.destroyed) return
+    if (mode === 'mux') {
+      if (!mux) mux = new MuxConnection({ relay, room, params: wsOpts.params, WebSocketPolyfill: wsOpts.WebSocketPolyfill, log, onRefused })
+      fp._impl = mux.channel(fp.docName, fp.doc, fp)
+    } else {
+      fp._bindLegacy(relay, wsOpts)
+    }
+  }
+  let resolveReady
+  const ready = new Promise((r) => { resolveReady = r })
+  const decide = (m) => {
+    if (!mode) mode = m
+    for (const fp of pending) bind(fp)
+    pending.clear()
+    resolveReady(mode)
+  }
+  // ONLY AN ANSWER DECIDES. A free Render instance takes 30-60s to wake and says nothing at all
+  // meanwhile; reading that silence as "no mux" pinned the whole session to a socket per file.
+  // So silence (a timeout, a refused connection, a 5xx from a proxy fronting a booting service) is
+  // asked again for up to ~90s. Any real answer decides at once -- including an old relay's
+  // plain-text /health, which is a relay that has never heard of mux. Out of time: a socket per
+  // file, the transport every relay has always spoken.
+  const detect = async () => {
+    const deadline = Date.now() + detectForMs
+    for (let wait = retryMs; ; wait = Math.min(wait * 2, 15000)) {
+      try {
+        const r = await fetchImpl(`${httpBase(relay)}/health`, { signal: AbortSignal.timeout(20000) })
+        if (r && r.status < 500) {
+          let j = null
+          try { j = JSON.parse(await r.text()) } catch { /* not JSON: an old relay, or not a relay */ }
+          return r.ok && offersMux(j) ? 'mux' : 'socket'
+        }
+      } catch { /* no answer yet */ }
+      if (stopped || Date.now() + wait > deadline) return 'socket'
+      await new Promise((res) => { const t = setTimeout(res, wait); if (t.unref) t.unref() })
+    }
+  }
+  if (mode) resolveReady(mode)
+  else detect().then(decide, () => decide('socket'))
+  return {
+    ready,
+    get mode() { return mode || 'detecting' },
+    provide(docName, doc) {
+      const fp = new FileProvider(docName, doc)
+      if (mode) bind(fp)
+      else pending.add(fp)
+      return fp
+    },
+    stats() { return { mode: mode || 'detecting', channels: mux ? mux.channels.size : 0, muxConnected: !!(mux && mux.connected) } },
+    stop() { stopped = true; try { if (mux) mux.destroy() } catch { } },
+  }
+}

package/hive-pr-staleness.js

@@ -0,0 +1,189 @@
+// hive-pr-staleness.js — do not write a file over a branch change you cannot account for.
+//
+// THE INCIDENT, MEASURED 19 Sep 2026. hive-pr generated a PR that looked perfect: three commits,
+// one per agent, each agent as the real git author, signed ids in `Hivecode-Author:` trailers,
+// files with no verified receipt refused rather than committed. A reviewer would have had every
+// reason to trust it.
+//
+// Diffed against the branch it was cut from:
+//
+//     hive-linear.js               -77
+//     tests/hive-linear-test.mjs  -114
+//     tests/hive-mcp-http-test.mjs -49
+//     tests/hive-governor-test.mjs -32
+//     sync.js                      -39
+//
+// It deleted the HIV-27 claim guard, deleted the HIV-14 truncation fix, deleted ~200 lines of
+// tests, and restored the 10x dashboard bug -- the one where thirty minutes of runtime displays
+// as 3.0. Filed HIV-28.
+//
+// THE CAUSE IS ONE LINE. hive-pr.js did `fs.copyFileSync(f.abs, dest)` and then `git add`. It
+// treats the room as truth and writes it over the branch. Grepping that file for `ahead`,
+// `behind`, `stale`, `diverged`, `merge-base` or `rev-list` returned nothing: it never asked
+// whether the branch had moved.
+//
+// This is not an exotic case, it is the NORMAL one. Any commit reaching the branch by another
+// route puts it ahead -- a hotfix, a second developer, CI, or a human doing exactly the
+// review-then-push workflow this tool exists to serve. In the measured incident the other route
+// was me, working in the git checkout instead of my room folder.
+//
+// WHY "AHEAD/BEHIND" IS THE WRONG QUESTION. There is no merge-base between a Yjs room and a git
+// branch; they are not two git histories. `git rev-list --count` cannot answer this, and reaching
+// for it would produce a check that looks rigorous and measures nothing.
+//
+// THE QUESTION THAT IS ANSWERABLE, per file:
+//
+//               has the room ever SEEN what is currently on the branch?
+//
+// It can be answered exactly, from state that already exists. Every landed change appends a
+// receipt carrying `parent` (the contentHash the author built on) and `contentHash` (the result),
+// so a file's ledger IS a hash chain of every state the room has passed through. `provenanceOf()`
+// already returns it -- hive-pr reads it for attribution and then ignores it for safety.
+//
+// If the branch's current bytes hash to something in that chain, the room descends from the
+// branch and writing is continuing the line. If they do not, the branch holds a change the room
+// has never seen, and writing would delete it. That is the whole check.
+
+import { contentHash } from './substrate.js'
+
+/** Nothing to write: the branch already holds exactly this. */
+export const IDENTICAL = 'IDENTICAL'
+/** The file is not on the branch at all, so there is nothing to revert. */
+export const NEW = 'NEW'
+/** The branch's bytes are in the room's chain: the room descends from them. Safe. */
+export const DESCENDS = 'DESCENDS'
+/** The branch holds bytes the room has never seen. REFUSE. */
+export const DIVERGED = 'DIVERGED'
+/** The room has no chain for this file, so nothing can be proved either way. REFUSE. */
+export const UNPROVEN = 'UNPROVEN'
+
+/** The only two states that may be written. A list, so widening it is a visible edit. */
+export const WRITABLE = [NEW, DESCENDS]
+
+/**
+ * LINE ENDINGS ARE PRESENTATION, AND ON THIS REPO THEY DIFFER BY DEFAULT.
+ *
+ * Measured here: `hive-mcp.js` and `sync.js` are CRLF in the working tree and LF in the blob,
+ * because `core.autocrlf` is true. So the bytes git stored and the bytes the room holds are not
+ * equal for most files in this project, while the file is by any useful definition the same file.
+ *
+ * A byte comparison would therefore mark nearly everything DIVERGED and refuse every run. That is
+ * worse than no check: a guard that fires on the HEALTHY path is the one that gets a `--force`
+ * alias in somebody's shell history within a week, and then it is not a guard at all.
+ *
+ * So both the equality test and the chain lookup are done modulo line endings. Three variants, not
+ * a normalisation, because the chain's hashes were computed by substrate.js over whatever text the
+ * room actually held at the time -- there is no single canonical form to normalise TO.
+ */
+const variants = (t) => {
+  const lf = String(t).replace(/\r\n/g, '\n')
+  return [String(t), lf, lf.replace(/\n/g, '\r\n')]
+}
+
+/** Same file, ignoring how the lines end. */
+export const sameText = (a, b) =>
+  a != null && b != null && String(a).replace(/\r\n/g, '\n') === String(b).replace(/\r\n/g, '\n')
+
+/**
+ * Every content state this file has passed through in the room.
+ *
+ * Both fields go in. `parent` is the state an author BUILT ON -- which may be a state no receipt
+ * ever produced, because the first write's parent is the hash of the empty string and a rejoin
+ * can land on a state whose own receipt lives on another peer. Taking only `contentHash` would
+ * miss exactly those, and each miss reads as DIVERGED: a refusal on a healthy file, which is the
+ * failure mode that gets a safety check disabled.
+ */
+export function chainOf(receipts) {
+  const seen = new Set()
+  for (const r of receipts || []) {
+    if (!r) continue
+    if (r.parent) seen.add(r.parent)
+    if (r.contentHash) seen.add(r.contentHash)
+  }
+  return seen
+}
+
+/**
+ * Decide whether the room's copy may be written over the branch's.
+ *
+ * `branchText` is null when the path does not exist on the branch. It must be the RAW blob --
+ * read with `git cat-file blob`, never `git show` through a working tree, or a checkout with
+ * `core.autocrlf` hands back bytes git never stored and every hash misses.
+ */
+export function accountFor({ rel, branchText, roomText, receipts }) {
+  if (branchText == null) return { rel, state: NEW, why: 'not on the branch yet — nothing can be reverted' }
+  // Modulo line endings on purpose. A file that differs ONLY in how its lines end must not be
+  // rewritten: it would produce a diff of every line in the file, for no change anybody made.
+  if (sameText(branchText, roomText)) return { rel, state: IDENTICAL, why: 'the branch already holds this (line endings aside)' }
+
+  const chain = chainOf(receipts)
+  if (!chain.size) {
+    return {
+      rel, state: UNPROVEN,
+      why: 'the room has no provenance chain for this file, so there is no way to tell whether its copy is newer than the branch or older',
+    }
+  }
+
+  const hashes = variants(branchText).map(contentHash)
+  if (hashes.some((h) => chain.has(h))) {
+    return { rel, state: DESCENDS, why: 'the room has passed through the branch\'s current content, so its copy is a descendant' }
+  }
+  return {
+    rel, state: DIVERGED, branchHash: hashes[0],
+    why: 'the branch holds content this room has never seen — writing the room\'s copy would delete it',
+  }
+}
+
+/** May this decision be written? Never inline `state !== DIVERGED` — that admits UNPROVEN. */
+export const writable = (d) => WRITABLE.includes(d.state)
+
+/**
+ * The run-level verdict.
+ *
+ * ALL OR NOTHING, and that is the design. Committing the safe files and skipping the rest produces
+ * a PR that looks complete and is not -- the same false success the tool already produced once,
+ * one level up. A refusal a human can read beats a branch they have to audit.
+ */
+export function verdict(decisions) {
+  const blocked = decisions.filter((d) => !writable(d) && d.state !== IDENTICAL)
+  return {
+    ok: blocked.length === 0,
+    blocked,
+    writable: decisions.filter(writable),
+    identical: decisions.filter((d) => d.state === IDENTICAL),
+  }
+}
+
+/**
+ * What the operator reads. `lastTouch` is supplied by the caller (hive-pr runs the git command)
+ * so this module stays pure and testable without a repository.
+ *
+ * It names the commit and the person, because "diverged" alone sends someone to `git log` to work
+ * out whether this is their own forgotten hotfix or somebody else's live work -- and that lookup
+ * is the moment a tired operator reaches for --force.
+ */
+export function explain(blocked, lastTouch = () => '') {
+  // Q506, the next free code in hive-pr's own Q500-Q505 block. Q443 would have read naturally
+  // here -- it is the other "you are being handed an incomplete picture" refusal -- and it is
+  // already the Linear truncation code. Two meanings behind one code is the duplicated-wire
+  // -contract defect wearing a three-digit hat.
+  const lines = ['Q506 REFUSING TO WRITE — the branch has moved under these files:', '']
+  for (const d of blocked) {
+    const touch = lastTouch(d.rel)
+    lines.push(`  ${d.rel}`)
+    lines.push(`      ${d.why}`)
+    if (touch) lines.push(`      last changed on the branch by: ${touch}`)
+  }
+  lines.push('')
+  lines.push('Nothing was written and no branch was created. Writing the room\'s copy over these')
+  lines.push('would silently revert whatever reached the branch another way — a hotfix, a second')
+  lines.push('developer, CI, or your own work done outside the room. That has happened once on this')
+  lines.push('project and the resulting PR looked perfect.')
+  lines.push('')
+  lines.push('Fix it one of two ways:')
+  lines.push('  - bring the branch\'s version INTO the room (edit it there, or hive_edit it), so the')
+  lines.push('    room\'s copy descends from what is on the branch. Then run this again.')
+  lines.push('  - --force "<reason>" if you have decided the room\'s copy should win. The reason is')
+  lines.push('    recorded in the PR body, because somebody will ask.')
+  return lines.join('\n')
+}