hivecode-mcp 0.8.0 → 0.11.0

package/package.json

@@ -1,70 +1,97 @@
-{
-  "name": "hivecode-mcp",
-  "version": "0.8.0",
-  "description": "MCP server that lets any AI coding agent join a Hivecode room — humans and multiple AI agents edit one live codebase with folder-scoped permissions and approval gates.",
-  "type": "module",
-  "license": "MIT",
-  "homepage": "https://github.com/Ganesh-Kute/HiveCode",
-  "bugs": {
-    "url": "https://github.com/Ganesh-Kute/HiveCode/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Ganesh-Kute/HiveCode"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "ai-agents",
-    "multi-agent",
-    "claude",
-    "collaboration",
-    "realtime",
-    "yjs"
-  ],
-  "bin": {
-    "hivecode-mcp": "./hive-mcp.js"
-  },
-  "files": [
-    "hive-mcp.js",
-    "sync.js",
-    "core.js",
-    "token.js",
-    "icr.js",
-    "lang-js.js",
-    "lang-brace.js",
-    "lang-python.js",
-    "icr-merge.js",
-    "hive-coord.js",
-    "substrate.js",
-    "HIVE_RULES.md",
-    "MCP.md",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "start": "node server.js",
-    "relay": "node server.js",
-    "test": "node test.js",
-    "test:substrate": "node substrate-test.js",
-    "test:substrate:live": "node substrate-live-test.js",
-    "test:substrate:enforce": "node substrate-enforce-test.js",
-    "test:substrate:authority": "node substrate-authority-test.js",
-    "test:substrate:all": "node substrate-test.js && node substrate-live-test.js && node substrate-enforce-test.js && node substrate-authority-test.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.104.2",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "acorn": "^8.17.0",
-    "ignore": "^7.0.5",
-    "ws": "^8.18.0",
-    "y-websocket": "^2.0.4",
-    "yjs": "^13.6.18"
-  }
-}
+{
+  "name": "hivecode-mcp",
+  "version": "0.11.0",
+  "description": "MCP server that lets any AI coding agent join a Hivecode room — humans and multiple AI agents edit one live codebase with folder-scoped permissions and approval gates.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/Ganesh-Kute/HiveCode",
+  "bugs": {
+    "url": "https://github.com/Ganesh-Kute/HiveCode/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ganesh-Kute/HiveCode.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "multi-agent",
+    "claude",
+    "collaboration",
+    "realtime",
+    "yjs"
+  ],
+  "bin": {
+    "hivecode-mcp": "hive-mcp.js"
+  },
+  "files": [
+    "hive-mcp.js",
+    "sync.js",
+    "core.js",
+    "token.js",
+    "icr.js",
+    "lang-js.js",
+    "lang-brace.js",
+    "lang-python.js",
+    "lang-ruby.js",
+    "lang-json.js",
+    "lang-yaml.js",
+    "lang-toml.js",
+    "icr-merge.js",
+    "hive-coord.js",
+    "substrate.js",
+    "HIVE_RULES.md",
+    "MCP.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "node scripts/install-hooks.mjs || exit 0",
+    "start": "node server.js",
+    "relay": "node server.js",
+    "sync:engine": "node sync-engine.mjs",
+    "check:engine": "node sync-engine.mjs --check",
+    "pretest": "node scripts/sync-engine.mjs --check",
+    "test": "node tests/test.js",
+    "test:billing": "node tests/billing-test.mjs",
+    "test:license": "node tests/hive-license-test.js",
+    "test:money": "node tests/billing-test.mjs && node tests/hive-license-test.js && node tests/recover-test.mjs",
+    "check:web": "tsc --noEmit",
+    "build:web": "esbuild web/src/main.ts --bundle --minify --format=iife --target=es2019 --outfile=public/app.js",
+    "test:substrate": "node substrate-test.js",
+    "test:substrate:live": "node substrate-live-test.js",
+    "test:substrate:enforce": "node substrate-enforce-test.js",
+    "test:substrate:authority": "node substrate-authority-test.js",
+    "test:substrate:all": "node substrate-test.js && node substrate-live-test.js && node substrate-enforce-test.js && node substrate-authority-test.js",
+    "test:recover": "node tests/recover-test.mjs",
+    "test:mailbox": "node tests/mailbox-test.mjs && node tests/mcp-wait-test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.104.2",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "acorn": "^8.17.0",
+    "ignore": "^7.0.5",
+    "ws": "^8.18.0",
+    "y-websocket": "^2.0.4",
+    "yjs": "^13.6.18",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "esbuild": "^0.28.1",
+    "typescript": "^7.0.2"
+  },
+  "main": "core.js",
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "author": "Ganesh Shivlal Kute <support@getgrm.tech>"
+}

package/sync.js

@@ -26,6 +26,7 @@ import { icrMerge3 } from './icr-merge.js' // structure/intent-aware merge; fall
 import { makeCoordinator } from './hive-coord.js' // decentralized claim layer (collision PREVENTION)
 import { fileRoom, decodeUnsafe, scopeForRoom, pathAllowed, writeAllowed, isSafeRelPath } from './token.js'
 import { genIdentity, authorChange, verifyReceipt, contentHash } from './substrate.js' // convergent-substrate: signed provenance for every landed change
+import { structuralMerge, supports } from './icr.js' // validates a judged fork resolution before it may land (parse + dangling refs)
 
 // 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
@@ -38,6 +39,10 @@ const ALWAYS_IGNORE = [
   '.git/', 'node_modules/',
   '.env', '.env.*', '*.pem', '*.key', '*.pfx', '*.p12', 'id_rsa', 'id_ed25519', '*.keystore',
   '.hive-id.json', // this client's substrate signing identity (holds a PRIVATE key) — never sync it
+  // This client's own session + chat read cursor. Syncing it would push one agent's identity
+  // and read position into every other agent's folder, and a shared cursor means one agent
+  // consuming another's unread mail.
+  '.hive-mcp-session.json',
   '*.log', '.DS_Store', 'Thumbs.db', '*.vsix',
 ]
 
@@ -216,7 +221,25 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   const claims = doc.getMap('claims')
   const swarmState = doc.getMap('swarm_state')
   const swarmSchema = doc.getMap('swarm_schema')
+  // ATTESTATION LEDGER — path -> { <peerName>: { bytes, lines, at } }.
+  //
+  // The one thing a four-agent build could not do without a human relaying numbers by hand: tell
+  // whether two folders actually hold the same file. Measured on the JARVIS run (2026-07-29):
+  // engine/brain/llm.js was 178 lines and parsing in one folder and 22,312 lines with 73 conflict
+  // markers in two others, and the agent with the clean copy reported a green suite in good faith
+  // for hours. Nothing in the product could have told any of them.
+  //
+  // Why bytes per PEER rather than a single value: a CRDT map keyed by peer name MERGES instead of
+  // last-writer-wins, so two peers attesting different byte counts both survive and the
+  // 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')
   const coordinator = makeCoordinator(claims, name, { ttl: 300000 }) // 5-min claim TTL
+  // MY declared intent per region — recorded on every claim ATTEMPT, kept locally.
+  // The provenance stamp reads this (not the shared claim map) so an agent always signs
+  // ITS OWN intent: under a true concurrent collision the shared claim converges to ONE
+  // winner, and reading it would misattribute the loser's receipt with the winner's WHY.
+  const myIntents = new Map()
 
   // --- convergent substrate: signed provenance (opt-in via HIVE_PROVENANCE) ------
   // When on, this client loads (or mints) a persistent Ed25519 identity and SIGNS
@@ -260,7 +283,8 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     if (fe.ledger.toArray().some((r) => r && r.author === identity.id && r.parent === pHash && r.contentHash === cHash0)) return
     try {
       const c = coordinator.sense(relPath)
-      const ch = authorChange({ identity, filename: relPath, base: base == null ? '' : base, text: next, intent: (c && c.intent) || 'edit', at: Date.now() })
+      const intent = myIntents.get(relPath) || (c && c.by === name && c.intent) || 'edit'
+      const ch = authorChange({ identity, filename: relPath, base: base == null ? '' : base, text: next, intent, at: Date.now() })
       // `name` is display-only (NOT signed) — the verified identity is `author` (the key
       // fingerprint). A UI shows both: the friendly name, and the cryptographic author it
       // must match. Signature covers everything else, so tampering `name` can't fake trust.
@@ -282,7 +306,8 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       if (cur && cur.hash === contentHash(landed)) return // head already attests this content
       const c = coordinator.sense(relPath)
       const at = Date.now()
-      const ch = authorChange({ identity, filename: relPath, base: base == null ? '' : base, text: landed, intent: (c && c.intent) || 'edit', at })
+      const intent = myIntents.get(relPath) || (c && c.by === name && c.intent) || 'edit'
+      const ch = authorChange({ identity, filename: relPath, base: base == null ? '' : base, text: landed, intent, at })
       fe.doc.transact(() => {
         fe.head.set('cur', { text: landed, hash: ch.prov.contentHash, at, by: name, receipt: { ...ch.prov, name } })
         storeVersion(fe, landed)
@@ -445,7 +470,10 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       conflicted.add(relPath)
       const who = rec.versions.map((v) => v.name).join(', ')
       log(`[${name}] ⚠ SILENT FORK in ${relPath} — ${who} changed the same region at once; provenance caught it. Surfaced ALL ${rec.versions.length} versions with <<<<<<< markers (rendered locally, not into the shared text).`)
-      try { say(`⚠ SILENT FORK in ${relPath}: ${who} changed the same region concurrently. Surfaced ALL ${rec.versions.length} versions with <<<<<<< markers. Resolve before continuing.`) } catch { }
+      // Carry each side's SIGNED intent into the announcement: the WHY is what lets any
+      // agent in the room reconcile the fork (via hive_resolve) instead of picking a winner.
+      const why = rec.versions.map((v) => `${v.name}: "${versionIntent(fe, rec, v.hash) || 'no stated intent'}"`).join(' | ')
+      try { say(`⚠ SILENT FORK in ${relPath}: ${who} changed the same region concurrently. Signed intents — ${why}. Surfaced ALL ${rec.versions.length} versions with <<<<<<< markers. ANY agent may reconcile BOTH intents: call hive_resolve with the full resolved file — it is validated (parses, no dangling refs) before it lands.`) } catch { }
     }
   }
   // A resolution landed elsewhere: the shared text is clean again. Adopt it to disk.
@@ -458,6 +486,112 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     bases.set(relPath, dt); forkBases.set(relPath, dt)
     conflicted.delete(relPath)
   }
+  // The VERIFIED signed intent behind one fork version: the receipt that produced this
+  // content from the fork's parent, signature-checked — so the WHY a judge reconciles is
+  // cryptographically the author's own declaration, not something another peer typed.
+  function versionIntent(fe, rec, hash) {
+    const r = fe.ledger.toArray().find((r) => r && r.contentHash === hash && r.parent === rec.parent && verifyReceipt(r).ok)
+    return (r && r.intent) || ''
+  }
+  // The active fork as a machine-RESOLVABLE object: the common base plus every divergent
+  // version with its author and verified intent. This is what an agent judge reads before
+  // proposing a reconciliation — the conflict is data, not just markers on a disk.
+  function forkInfo(relPath) {
+    const fe = fileDocs.get(relPath); if (!fe) return null
+    const rec = forkRecord(fe); if (!rec) return null
+    return {
+      file: relPath,
+      base: rec.base,
+      versions: rec.versions.map((v) => ({ name: v.name, author: v.author, intent: versionIntent(fe, rec, v.hash), text: fe.versions.get(v.hash) })),
+    }
+  }
+  // INTENT-AWARE FORK RESOLUTION — the judged path out of a surfaced silent fork.
+  // Any participant (typically an AI agent that has read both sides' signed intents via
+  // forkInfo / the chat announcement) proposes the FULL reconciled file; the MEDIUM
+  // validates it before it may land:
+  //   - no conflict markers left behind,
+  //   - (supported language) judged as a one-sided change from the fork's base through
+  //     ICR structuralMerge: it must PARSE and must not leave a DANGLING reference —
+  //     the same guarantee the icr-merge library's resolveMerge gives a judge, so broken
+  //     judge output physically cannot ship. (A rename in the proposal even gets its
+  //     stale call sites rewritten, same as any merge.)
+  // A landed resolution takes the exact convergent path a human resolution takes: it is
+  // signed by the resolver, folds the fork versions, clears the record on every peer,
+  // and is announced. A refused proposal changes NOTHING — the fork stays surfaced.
+  function resolveFork(relPath, proposal) {
+    const fe = fileDocs.get(relPath)
+    if (!fe || !fe.synced || !fe.conflict) return { ok: false, reason: `no active fork on ${relPath}` }
+    const rec = forkRecord(fe)
+    if (!rec) return { ok: false, reason: `no active fork on ${relPath}` }
+    if (!canWrite(relPath)) return { ok: false, reason: `${relPath} is read-only for you` }
+    if (typeof proposal !== 'string' || !proposal.trim()) return { ok: false, reason: 'empty resolution' }
+    if (hasConflictMarkers(proposal)) return { ok: false, reason: 'resolution still contains <<<<<<< conflict markers — send the final clean file' }
+    let landed = proposal
+    if (supports(relPath) && rec.base != null) {
+      const v = structuralMerge(rec.base, proposal, rec.base, { filename: relPath })
+      if (v.status !== 'auto') return { ok: false, reason: `resolution refused by ICR validation: ${v.reason || (v.conflicts || []).join(', ') || v.status}` }
+      landed = v.text
+    }
+    // INTENT COVERAGE (informational, deterministic): did each side's TOKEN-level
+    // changes survive into the landed text? Token granularity is what makes a genuine
+    // reconciliation count for both sides (a merged ternary contains both sides' new
+    // tokens) while a lazy single-winner judgment shows one side's tokens dropped.
+    // A resolution may legitimately pick one side — but that becomes VISIBLE to the
+    // room instead of silently passing as a reconciliation. Never refuses.
+    const tokSet = (s) => new Set(String(s).match(/[A-Za-z_$]\w*|\d[\w.]*/g) || [])
+    const baseToks = tokSet(rec.base || ''), landedToks = tokSet(landed)
+    const coverage = rec.versions.map((v) => {
+      const vt = fe.versions.get(v.hash)
+      const changed = vt == null ? [] : [...tokSet(vt)].filter((t) => !baseToks.has(t))
+      const missing = changed.filter((t) => !landedToks.has(t))
+      return { name: v.name, covered: missing.length === 0, missing }
+    })
+    const dropped = coverage.filter((c) => !c.covered)
+    const block = forkBlock(fe, rec)
+    fe.doc.transact(() => {
+      applyDiff(fe.text, landed)
+      for (const vv of rec.versions) fe.forkmark.set(vv.hash, 1)
+      for (const key of [...fe.conflict.keys()]) fe.conflict.delete(key)
+    })
+    stampProvenance(relPath, block || rec.base || '', landed)
+    writeToDisk(relPath, landed)
+    conflicted.delete(relPath)
+    known.add(relPath); bases.set(relPath, landed); forkBases.set(relPath, landed)
+    const covNote = dropped.length
+      ? ` ⚠ Coverage: ${dropped.map((c) => `${c.name}'s changes (${c.missing.slice(0, 5).join(', ')}) did NOT survive`).join('; ')} — the room should sanity-check this judgment.`
+      : ' Full intent coverage: every side\'s changes survived token-level.'
+    try { say(`⚖ FORK RESOLVED by ${name} (intent-aware): reconciled ${rec.versions.map((v) => v.name).join(' + ')} in ${relPath}. Validated by ICR (parses, no dangling refs) before landing.${covNote}`) } catch { }
+    return { ok: true, file: relPath, text: landed, coverage }
+  }
+  // FIRST-CLASS AUTHORED WRITE — an agent writes THROUGH the medium instead of via
+  // disk + a debounced watcher. This closes the capture race COMPLETELY for the write:
+  // the author's declared intent is recorded and the (base -> text) transition is
+  // stamped into the provenance ledger synchronously, before any concurrent merge or
+  // conflict render could contaminate the disk (the fs.watch model's residual window
+  // does not exist on this path). The content then lands through the SAME reconcile
+  // pipeline as any local edit — merging, fork detection, and conflicts behave
+  // identically; only the capture is race-free.
+  function editFile(relPath, content, intent) {
+    relPath = String(relPath || '').replace(/\\/g, '/')
+    if (!relPath || typeof content !== 'string') return { error: 'need a file path and string content' }
+    if (!isSafeRelPath(relPath)) return { error: 'unsafe path' }
+    if (SKIP.has(relPath) || isIgnored(relPath)) return { error: `${relPath} is not a syncable file` }
+    if (!canOpen(relPath)) return { error: `${relPath} is out of your scope` }
+    if (!canWrite(relPath)) return { error: `${relPath} is read-only for you` }
+    if (intent) myIntents.set(relPath, String(intent)) // my declared WHY — what my receipt will sign
+    const full = path.join(ROOT, relPath)
+    try { fs.mkdirSync(path.dirname(full), { recursive: true }); fs.writeFileSync(full, content) }
+    catch (e) { return { error: 'write failed: ' + e.message } }
+    // Deliberately NOT via writeToDisk (which records engine writes in `shadow`):
+    // this write is AUTHORED, so disk-vs-shadow divergence is exactly what captureLocal
+    // stamps. Run the pass NOW — no debounce window at all.
+    if (FORK_GATE) captureLocal(relPath)
+    reconcile(relPath, 'local')
+    const fe = fileDocs.get(relPath)
+    const landed = fe && fe.synced ? fe.text.toString() : content
+    let disk = content; try { disk = fs.readFileSync(full, 'utf8') } catch { }
+    return { ok: true, file: relPath, landed, conflicted: hasConflictMarkers(disk) }
+  }
   // Detect a live fork and record it. The version set is a CRDT UNION (per-hash keys), so
   // this is monotonic + convergent: every peer contributes what it sees and the set grows
   // to the full fork on all peers regardless of arrival order. Does NOT touch Y.Text.
@@ -731,7 +865,11 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       res = { text: disk, conflict: false }
     } else if (origin === 'local') {
       noteIfRewrite(relPath, fork, disk)
-      // THE FIX. Merge a local edit against the FORK POINT (what this author
+      // Check if this write is an intentional clean rewrite
+      const sc = summarizeChange(fork, disk)
+      const isCleanRewrite = sc.isRewrite && supports(relPath) && languageFor(relPath).parses(disk)
+
+      // Merge a local edit against the FORK POINT (what this author
       // last saw), not the latest doc. If the doc gained lines since the fork
       // that this write does NOT contain, the author was working from a stale
       // copy — merging against the fork re-adds those lines (disjoint) or raises
@@ -739,8 +877,8 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       const theirsNew = changedRange(fork.split('\n'), docText.split('\n')).newLines.filter((l) => l.length)
       const mineLines = new Set(disk.split('\n'))
       const integrated = theirsNew.every((l) => mineLines.has(l)) // this write already contains the remote change
-      if (integrated) {
-        res = { text: disk, conflict: false } // author built on the latest — trust it
+      if (integrated || (isCleanRewrite && !hasConflictMarkers(docText))) {
+        res = { text: disk, conflict: false } // author built on the latest or cleanly rewrote — trust it
       } else {
         res = icrMerge3(fork, disk, docText, relPath)
         reAdded = !res.conflict && res.text !== disk // we restored remote lines a stale write had dropped
@@ -1208,10 +1346,54 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   return {
     doc,
     provider,
+    // A STATE MACHINE, not a validated variable.
+    //
+    // `enum` alone makes this a notepad with spellcheck: it stops a typo and permits any value at any
+    // time, so APPROVED can slide back to LOCKED and a release gate can be opened by an agent that
+    // simply set the flag. Two additions turn it into a machine, and both exist because a live
+    // four-agent build (JARVIS, 2026-07-29) was governed entirely by rules written in prose that four
+    // capable agents read and then broke:
+    //
+    //   transitions: { FROM: [TO, ...] }   which moves are legal AT ALL
+    //   requires:    { TO: { key: val } }  what must already be true to arrive at TO
+    //
+    // `requires` is the important one. It makes a contract EXECUTABLE. "Nobody sends email until the
+    // suppression UI exists and the unsubscribe URL is real" held for nine hours only because a PM
+    // kept repeating it; expressed as
+    //   requires: { LIVE: { suppression_ui: 'APPROVED', unsubscribe_url: 'SET' } }
+    // it holds because the transition cannot be made. That is the whole point of this layer: the
+    // place where a rule stops being advice.
     setState: (key, val) => {
       const rules = swarmSchema.get(key)
-      if (rules && rules.enum && !rules.enum.includes(val)) {
-        throw new Error(`[Schema Error] Invalid state for [${key}]. Allowed values: ${rules.enum.join(', ')}`);
+      const cur = swarmState.get(key)
+      // PARAMETERISED VALUES. `PUBLISH:2` must satisfy an enum containing `PUBLISH` — otherwise the
+      // two features collide: a leased grant is a PUBLISH carrying a count, and schema-ing the status
+      // key would make every lease illegal. So a value of the form BASE:arg validates on BASE.
+      // Found by trying to use both at once on a live room, which is the only way this surfaces.
+      const base = String(val).includes(':') ? String(val).slice(0, String(val).indexOf(':')) : val
+      if (rules && rules.enum && !rules.enum.includes(val) && !rules.enum.includes(base)) {
+        throw new Error(`[Schema Error] Invalid state for [${key}]. Allowed values: ${rules.enum.join(', ')}${base !== val ? ` (parameterised values like ${base}:<n> are allowed when ${base} is listed)` : ''}`);
+      }
+      // Transitions are checked only when the key ALREADY has a value — the first write to a key is
+      // initialisation, not a move, and demanding a `from` entry for it would make every schema
+      // carry a synthetic start state.
+      // Transitions compare on the BASE too, for the same reason as the enum above: a lease counting
+      // down PUBLISH:2 -> PUBLISH:1 is one state decrementing its own parameter, not a move between
+      // states, and demanding a transition entry per count would be absurd.
+      const curBase = cur !== undefined && String(cur).includes(':') ? String(cur).slice(0, String(cur).indexOf(':')) : cur
+      if (rules && rules.transitions && cur !== undefined && curBase !== base) {
+        const allowed = rules.transitions[curBase] || rules.transitions[cur]
+        if (!Array.isArray(allowed) || !(allowed.includes(val) || allowed.includes(base))) {
+          throw new Error(`[Transition Error] [${key}] cannot go ${cur} -> ${val}. Legal from ${curBase}: ${Array.isArray(allowed) && allowed.length ? allowed.join(', ') : '(nothing — terminal state)'}`)
+        }
+      }
+      if (rules && rules.requires && rules.requires[val]) {
+        const unmet = Object.entries(rules.requires[val])
+          .filter(([k, want]) => String(swarmState.get(k)) !== String(want))
+          .map(([k, want]) => `${k}=${want} (is ${swarmState.get(k) === undefined ? 'unset' : swarmState.get(k)})`)
+        if (unmet.length) {
+          throw new Error(`[Guard Error] [${key}] cannot become ${val} until: ${unmet.join('; ')}`)
+        }
       }
       swarmState.set(key, val)
       say(`STATE TRANSITION: [${key}] is now [${val}]`)
@@ -1225,6 +1407,30 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       swarmSchema.set(key, rules)
       say(`SCHEMA UPDATED: [${key}] rules set to ${JSON.stringify(rules)}`)
     },
+    // --- attestation: does another folder actually hold the same bytes? ---
+    // Records THIS peer's measurement of a path. Returns the merged picture including, crucially,
+    // whether the peers DISAGREE — see the swarm_attest declaration for why it is keyed per peer.
+    attest: (relPath, bytes, lines) => {
+      const p = String(relPath)
+      const prev = swarmAttest.get(p) || {}
+      const next = { ...prev, [name]: { bytes: Number(bytes), lines: Number(lines), at: new Date().toISOString() } }
+      swarmAttest.set(p, next)
+      const sizes = [...new Set(Object.values(next).map((v) => v && v.bytes))]
+      const split = sizes.length > 1
+      if (split) {
+        // Announce, do not throw. The measuring agent did nothing wrong and its report is valid; the
+        // ROOM is what is broken. Throwing here would punish whoever happened to measure second.
+        const detail = Object.entries(next).map(([who, v]) => `${who}:${v.bytes}b/${v.lines}L`).join('  ')
+        say(`[!] DIVERGENCE on ${p} — peers hold DIFFERENT bytes: ${detail}. Nobody may write this path until it is reconciled; mark it path:${p}=POISONED if it cannot be.`)
+      }
+      return { path: p, peers: next, count: Object.keys(next).length, sizes, diverged: split }
+    },
+    verified: (relPath) => {
+      const p = String(relPath)
+      const rec = swarmAttest.get(p) || {}
+      const sizes = [...new Set(Object.values(rec).map((v) => v && v.bytes))]
+      return { path: p, peers: rec, count: Object.keys(rec).length, sizes, diverged: sizes.length > 1, quorum: Object.keys(rec).length >= 2 && sizes.length === 1 }
+    },
     say,                 // post a coordination message
     assign,              // direct a task at a participant (needs approval if target AI has an owner)
     decide,              // approve/deny a task (owner only, if set)
@@ -1234,10 +1440,14 @@ 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) => coordinator.acquire(String(region), String(intent || 'edit')), // true iff you hold it
-    release: (region) => coordinator.release(String(region)),
+    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) },
     senseClaim: (region) => coordinator.sense(String(region)), // the live claim on a region, or null
     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
+    resolveFork,         // propose the reconciled file; ICR-validated (parse + dangling) before it lands, refused otherwise
+    edit: editFile,      // first-class authored write: intent + transition stamped race-free, then normal reconcile
     // --- convergent substrate: provenance (I1) ---
     identity: () => identity ? { id: identity.id, name: identity.name, pk: identity.pk } : null, // never exposes the private key
     provenanceOf: (relPath) => { const e = fileDocs.get(relPath); return e && e.ledger ? e.ledger.toArray() : [] }, // signed receipts for a file

package/MCP.md

@@ -1,77 +0,0 @@
-# Hivecode MCP server
-
-Lets any MCP-capable AI agent (Claude Code, Claude Desktop, etc.) join a Hivecode
-room and coordinate through **native tool calls** — no scripts to run, no human
-to set it up.
-
-## Register it
-
-Add Hivecode to your MCP client config. The command runs this repo's server.
-
-**Claude Code** (`.mcp.json` in your project, or user settings):
-```json
-{
-  "mcpServers": {
-    "hivecode": {
-      "command": "node",
-      "args": ["C:/Users/G1/Desktop/N/hive-mcp.js"],
-      "env": { "HIVE_RELAY": "wss://livecode-xoss.onrender.com" }
-    }
-  }
-}
-```
-
-`HIVE_RELAY` is optional (defaults to the hosted relay).
-
-### Lower-friction join (no file copy)
-
-The package declares a `bin` (`hivecode-mcp` → `hive-mcp.js`), so once it's
-published to npm the other agent needs no local copy/clone — just:
-
-```json
-{ "mcpServers": { "hivecode": { "command": "npx", "args": ["-y", "hivecode-mcp"] } } }
-```
-
-`npx` fetches and runs it. (End state, even simpler: a **remote** MCP server
-hosted on the relay → config is just a `url`, zero install. Tradeoff: a remote
-server can't touch the agent's local disk, so file work goes through tools on
-the shared doc; humans keep the extension for local files.)
-
-## Tools the agent gets
-
-| Tool | What it does |
-|------|--------------|
-| `hive_join` | Join/host a room for a folder. Auto-joins as an **AI** participant. Returns the room info **and the HIVE_RULES to follow**. |
-| `hive_say` | Post a coordination message — announce what you're about to work on. |
-| `hive_read_chat` | Read the room conversation (read this to coordinate). |
-| `hive_read_board` | Read recent whole-file rewrites (read before editing a file). |
-| `hive_members` | Who's in the room (humans + agents). |
-| `hive_status` | Current session info. |
-| `hive_leave` | Leave the room. |
-
-## How an agent uses it
-
-1. `hive_join` (with a `link`, a `dir` containing `.hive.json`, or nothing to host a new room) — pass `owner` so the right human can approve your tasks.
-2. Read the returned **HIVE_RULES**.
-3. `hive_read_chat` + `hive_read_board` before touching files.
-4. `hive_say` to announce intent, then edit files in the synced folder.
-5. Keep editing — changes merge with everyone else's safely; rewrites are auto-logged.
-
-## Reacting to directed work (no polling)
-
-A human can direct a task at you, but you only act once **your owner approves**.
-Don't poll — **block** on `hive_wait`:
-
-```
-loop:
-  result = hive_wait(timeoutSeconds: 60)   # returns the instant your owner approves
-  if result has APPROVED WORK:
-     do it, then hive_complete(id)
-  # else just call hive_wait again
-```
-
-`hive_wait` returns within ~1s of the approval (it reacts to the live update),
-and also wakes on new chat so you stay responsive to teammates.
-
-This is the lowest-friction way for AIs to adopt the protocol in `SPEC.md`:
-the agent never runs a command, it just calls tools.