hivecode-mcp 0.6.0 → 0.8.0

package/README.md

@@ -1,137 +1,68 @@
-<h1>Hivecode</h1>
-
-**Multiplayer for your AI coding agents — with real permissions.**
-
-Run humans and multiple AI agents on one live codebase. Folder-scoped access,
-approval gates, instant revoke. No git push/pull — edits sync in about a second.
-Open source.
-
-[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
-· [**Website**](https://livecode-xoss.onrender.com)
-· [Latest .vsix](https://github.com/GSK7024/livecode/releases)
-
-<!-- Add a demo GIF here once recorded: ![demo](docs/demo.gif) -->
-
----
-
-## Why
-
-The moment you point more than one AI agent at a project, it gets messy: they
-overwrite each other's files, rebuild the same feature twice, and every agent can
-touch every file — secrets, configs, infra included. Today people juggle git
-worktrees and pray at merge time.
-
-Hivecode is a shared **live room** where humans and agents edit one project
-together — but with real access control. You decide what each agent can reach, and
-the relay enforces it; an out-of-scope agent never even receives the bytes.
-
-It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP.
-
----
-
-## Quickstart
-
-1. Install the extension (link above). It works in **VS Code, Cursor, Windsurf,
-   and Antigravity**.
-2. Open the folder you want to share (**File → Open Folder**).
-3. `Ctrl/Cmd+Shift+P` → **Hivecode: Host a Secured Session**. A join link is
-   copied to your clipboard. *(No terminal, no server to run.)*
-4. **Hivecode: Invite to folders…** → pick the folders and a role (edit /
-   read-only) for each person or agent. Send them the link.
-5. They run **Hivecode: Join a Session** and paste the link. You're now editing
-   the same project live.
-
-Use **Manage access** to re-scope or revoke anyone, and **Leave Session** to stop.
-
----
-
-## Add an AI agent
-
-Agents join through the Hivecode MCP server ([`hive-mcp.js`](hive-mcp.js)). Point
-your agent's MCP config at it and hand it the join link; it appears in the room as
-an `ai` member, scoped to exactly the folders you invited it to. The agent gets
-tools to read chat, the task board, and members; to claim and complete tasks; to
-talk; and to wait for work. See [MCP.md](MCP.md) for setup.
-
----
-
-## What you get
-
-**Governance**
-- **Folder-scoped access** — invite an agent to `frontend/` only; it never receives
-  anything else.
-- **Approval gates** — a human's request to *your* agent waits for your OK;
-  agent-to-agent coordination flows automatically.
-- **Read-only roles** — reviewers see everything, change nothing.
-- **Instant revoke** — cut access mid-session, enforced server-side on every
-  reconnect (and it survives a relay restart).
-
-**Coordination**
-- **Built-in chat**, a **shared task board** (assign / complete), and **live
-  presence** so humans and agents stay in sync.
-- **Co-editing heads-up** before two people touch the same file.
-- **Never lose work** — overlapping edits keep both versions with conflict markers;
-  a stale rewrite can't silently delete another's lines.
-- **Mission control** — pause, resume, or reassign any agent; agents honor it
-  mid-task.
-
-**Trust**
-- **Server-enforced auth** — signed tokens, algorithm-pinned, fail-closed.
-  Unauthorized clients never complete the WebSocket handshake.
-- **Self-certifying secured rooms** — the room id embeds a fingerprint of your
-  public key; tokens carry the key and are signed by it; the relay trusts a token
-  only if the fingerprint matches. No account system, no shared secret. Your
-  private key stays in the editor's secure storage.
-- **Dependency-free core** — the access-control layer uses only Node's `crypto`.
-
----
-
-## How the security model works
-
-A secured room's id is `hs_<fp>_<rand>`, where `fp` is a base64url SHA-256
-fingerprint of the owner's public key. Every token for the room carries the owner's
-public key (claim `pk`) and is signed by the matching private key (RS256). The relay
-trusts a token **iff** `fingerprint(token.pk) === fingerprint-in-room-id`, then
-verifies the signature with that key — so trust is anchored in the room id itself
-and the relay stores nothing.
-
-Files use a per-file subdocument model: the room is `<base>`, each file is a
-separate document at `<base>␁<path>`. The relay authorizes per path, so a scoped
-client can only open the files it may load, and out-of-scope content never reaches
-its disk. Paths are guarded against traversal, absolute paths, drive letters, and
-control characters on both the client (before writing) and the relay.
-
-A full threat/edge-case audit is in [EDGE-CASES.md](EDGE-CASES.md); the RBAC design
-is in [RBAC.md](RBAC.md).
-
----
-
-## Self-hosting the relay
-
-The hosted relay is the default (`wss://livecode-xoss.onrender.com`) and needs no
-setup. To run your own, deploy [`server.js`](server.js) anywhere Node runs and set
-`hivecode.relayUrl` in the extension. The relay holds no truth of its own — it just
-passes CRDT updates between clients in the same room, and enforces access at the
-handshake. See [DEPLOY.md](DEPLOY.md).
-
----
-
-## Development
-
-```bash
-npm install
-node test.js          # unit tests
-node hive-edge-test.js # adversarial / edge-case live tests
-```
-
-Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
-`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
-`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
-
-The extension source is in [`extension/`](extension/).
-
----
-
-## License
-
-MIT.
+<h1>Hivecode</h1>
+
+**Oversight and control for your AI coding agents.**
+
+Run AI agents on your codebase and actually stay in control: **watch** every edit
+live, **fence** each agent to the folders it's allowed in, **approve** the risky
+moves, and **undo** any agent instantly. No git push/pull. Open source.
+
+[**Install for VS Code**](https://marketplace.visualstudio.com/items?itemName=hivecode.hivecode)
+· [**Website**](https://livecode-xoss.onrender.com)
+· [Latest .vsix](https://github.com/GSK7024/livecode/releases)
+
+---
+
+## Why
+
+You can't trust an AI agent blindly. The faster it edits, the more you have to
+check — and the moment you run more than one, it gets worse: they touch files they
+shouldn't, overwrite each other, and you lose track of who changed what. Today's
+answer is to isolate each agent in a git worktree and pray at merge time — which
+doesn't help you *trust* the output, it just defers the mess.
+
+Hivecode adds the missing layer: **oversight and control.**
+
+- **See everything** — a live Control Room (browser or phone) shows every agent and every file it touches, in real time.
+- **Fence them in** — folder-scoped access the relay enforces; an out-of-scope agent never even receives the code.
+- **Approve what matters** — gate risky work so nothing lands without your OK.
+- **Undo anything** — instant rollback: restore any file, or revert *everything* one agent did.
+
+It's **agent-neutral**: Claude Code, Cursor, Windsurf, or your own bot over MCP. No
+git push/pull — edits sync in about a second.
+
+---
+
+## Documentation
+
+To keep this README clean, we've modularized the documentation into separate files. Click below to read more about each specific topic:
+
+- **[🔌 Connecting & Hosting Rooms](docs/CONNECTING_ROOMS.md)** - Learn how humans join rooms, how to host your own relay server, and how the self-certifying security model works.
+- **[🤖 AI Agent Manual](docs/AI_AGENT_MANUAL.md)** - A guide written specifically for AI agents on how to download the MCP server, join a room, and behave within the hive.
+- **[🏛️ Hivecode Architecture](docs/HIVECODE_EXPLAINED.md)** - A breakdown of the three core components, the CRDT data model, and how it scales.
+- **[🧠 ICR (Intent-Centric Resolution)](docs/ICR_EXPLAINED.md)** - How our semantic AST-aware merge algorithm guarantees no lines are lost during multi-agent collisions.
+- **[🔐 DCO (Deterministic Context Override)](docs/DCO_EXPLAINED.md)** - The core breakthrough paradigm that physically locks tools based on CRDT state, structurally preventing agent hallucination and drift. Includes our End-to-End Test Report.
+- **[🔗 The Substrate](docs/SUBSTRATE.md)** - A governed *medium* (not a channel) for multi-agent code: every change is a signed `(intent, patch, provenance)` triple, and the medium guarantees it converges, never regresses, and is provenance-verified — enforced by the relay, with no controller. Runnable + testable in one command.
+
+---
+
+## Development
+
+```bash
+npm install
+node test.js          # unit tests
+node hive-edge-test.js # adversarial / edge-case live tests
+
+npm run test:substrate:all   # the substrate: 4 suites (core + live + enforcement + content authority)
+```
+
+Other live suites: `hive-secure-test.js`, `hive-scope-test.js`, `hive-auth-test.js`,
+`hive-readonly-test.js`, `hive-resume-test.js`, `hive-control-test.js`,
+`hive-durable-revoke-test.js`, `hive-relay-robust-test.js`.
+
+The extension source is in [`extension/`](extension/).
+
+---
+
+## License
+
+MIT.

package/hive-coord.js

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

package/hive-mcp.js

@@ -25,6 +25,13 @@ import crypto from 'crypto'
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+// Substrate defaults for MCP agents: signed provenance + the silent-fork gate are ON
+// unless explicitly disabled. Agents register this server with arbitrary (often empty)
+// env, so relying on per-registration env vars left rooms in mixed signed/unsigned mode —
+// which is exactly the condition that disabled fork detection in live testing. sync.js
+// reads these when startSync() runs (not at import), so setting them here covers every join.
+if (!process.env.HIVE_PROVENANCE) process.env.HIVE_PROVENANCE = 'on'
+if (!process.env.HIVE_FORK_GATE) process.env.HIVE_FORK_GATE = 'on'
 import { startSync, parseLink } from './sync.js'
 
 const DEFAULT_RELAY = process.env.HIVE_RELAY || 'wss://livecode-xoss.onrender.com'
@@ -42,6 +49,21 @@ function resolveRoom(link, dir) {
   return { relay: DEFAULT_RELAY, room: 'room-' + crypto.randomBytes(13).toString('base64url'), token: '', mode: 'HOSTED (new room)' }
 }
 
+// Session persistence: keyed to this process's cwd, so each agent runtime (which starts
+// its own MCP process from its own directory) resumes only its own identity. Lets the
+// session survive MCP host restarts, which otherwise silently drop the agent from the room.
+const SESSION_FILE = path.join(process.cwd(), '.hive-mcp-session.json')
+function persistSession({ dir, name, owner }) {
+  try { fs.writeFileSync(SESSION_FILE, JSON.stringify({ dir, name, owner })) } catch { /* best-effort */ }
+}
+async function tryResumeSession() {
+  try {
+    if (!fs.existsSync(SESSION_FILE)) return
+    const s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8'))
+    if (s && s.dir && s.name && fs.existsSync(path.join(path.resolve(s.dir), '.hive.json'))) await joinRoom(s)
+  } catch { /* resume is best-effort; the agent can always hive_join explicitly */ }
+}
+
 async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '' }) {
   if (session) { try { session.hive.stop() } catch {} ; session = null }
   const ROOT = path.resolve(dir)
@@ -54,6 +76,7 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
   fs.writeFileSync(path.join(ROOT, '.hive.json'), JSON.stringify({ relay, room, ...(useToken ? { token: useToken } : {}) }, null, 2))
   const hive = startSync({ relay, room, dir, name, kind: 'ai', owner, token: useToken, log: () => {} })
   session = { hive, room, relay, dir, name }
+  persistSession({ dir, name, owner }) // survive MCP host restarts (see tryResumeSession)
   // wait for the first sync so members/board/rules are ready
   await new Promise((resolve) => {
     let done = false
@@ -61,10 +84,24 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
     hive.provider.on('sync', (s) => s && finish())
     setTimeout(finish, 8000) // don't hang if the relay is cold
   })
-  hive.say(`${name} joined and is ready to work.`)
-  const rules = (() => { try { return fs.readFileSync(path.join(ROOT, 'HIVE_RULES.md'), 'utf8') } catch { return '(rules not yet written)' } })()
   const others = hive.members().filter((m) => m.name !== name).map((m) => `${m.name}(${m.kind})`)
-  return `${mode}\nroom: ${room}\nrelay: ${relay}\nfolder: ${ROOT}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${relay}|${room}\n\n--- FOLLOW THESE RULES ---\n${rules}`
+  
+  // Event-Driven Wakeups: notify the MCP client the millisecond the DCO state changes
+  hive.doc.getMap('swarm_state').observe(() => {
+    try {
+      server.notification({ method: 'notifications/hive_state_changed', params: { state: hive.getState() } })
+    } catch (e) {
+      // client might not support notifications, swallow error
+    }
+  })
+  
+  // The sync engine writes HIVE_RULES.md into the folder on first sync — return it inline
+  // so the agent gets the rules with its join. (Fixes a ReferenceError: `rules` was never
+  // defined, which made every hive_join return "error: rules is not defined".)
+  let rulesText = ''
+  try { rulesText = fs.readFileSync(path.join(ROOT, 'HIVE_RULES.md'), 'utf8') } catch {}
+  if (!rulesText) rulesText = 'Read HIVE_RULES.md in this folder. In short: read chat + board before editing; CLAIM a file with hive_claim before you edit it and hive_release when done; announce intent with hive_say; prefer small patches; act only on accepted tasks; resolve <<<<<<< conflict markers rather than blindly overwriting.'
+  return `${mode}\nroom: ${room}\nrelay: ${relay}\nfolder: ${ROOT}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${relay}|${room}\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
 }
 
 function requireSession() { if (!session) throw new Error('not in a room — call hive_join first'); return session }
@@ -142,22 +179,44 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'how many recent messages (default 30)' } } } },
   { name: 'hive_read_board', description: 'Read recent whole-file rewrites (who rewrote what, which symbols). Read this before editing a file — if it was just rewritten, re-read the file first.',
     inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_claim', description: 'CLAIM a file (or region) BEFORE you edit it, so other agents flow around you instead of colliding. Returns whether you got it — if false, someone else holds it: work on something else. Claims auto-expire, so call hive_release when done (or it frees itself).',
+    inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'the file path (or region id) you want to edit' }, intent: { type: 'string', description: 'short note on what you intend to do' } }, required: ['region'] } },
+  { name: 'hive_release', description: 'Release a file/region you claimed, so other agents can take it. Call this when you finish editing it.',
+    inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'the file path (or region id) to release' } }, required: ['region'] } },
+  { name: 'hive_claims', description: 'See what every agent is currently working on (the live claim board). Read this to pick open work and avoid taken regions.',
+    inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_members', description: 'List who is currently in the room (humans and AI agents).', inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_status', description: 'Show the current session (room, relay, folder, name).', inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_leave', description: 'Leave the room and stop syncing.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_set_state', description: 'PM ONLY: Set a global project state flag (e.g. key="contract", val="READY"). This physically unblocks/blocks other agents. WARNING: ONLY use short enum values. Do NOT use this to store paragraphs of text or code, as it will bloat the context window. Use files for text.', inputSchema: { type: 'object', properties: { key: { type: 'string' }, val: { type: 'string' } }, required: ['key', 'val'] } },
+  { name: 'hive_read_state', description: 'Read the global project state flags.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'hive_set_schema', description: 'PM ONLY: Define strict JSON schema validation for a global state key to prevent agents from hallucinating values (e.g. key="contract", rules={"enum": ["PLANNING", "READY", "APPROVED"]}).', inputSchema: { type: 'object', properties: { key: { type: 'string' }, rules: { type: 'object' } }, required: ['key', 'rules'] } },
 ]
 
-const server = new Server({ name: 'hivecode', version: '0.1.0' }, { capabilities: { tools: {} } })
+function enforceDcoLock() {
+  const state = requireSession().hive.getState()
+  const name = requireSession().name
+  if (state[`${name}_status`] === 'LOCKED' || state[`${name}_locked`] === 'true') {
+    throw new Error(`[DCO Enforced] You are locked by the global state machine. Tool execution denied. Block on hive_wait until your status changes.`)
+  }
+}
+
+const server = new Server({ name: 'hivecode', version: '0.8.0' }, { capabilities: { tools: {} } })
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const { name, arguments: args = {} } = req.params
   try {
+    // AUTO-RESUME: the MCP host may restart this server process at any time, which
+    // wipes the in-memory session and silently kicks the agent out of its room. If a
+    // persisted session exists for this cwd, transparently rejoin before any tool runs —
+    // the agent (and its human) never see a "not in a room" flake again.
+    if (!session && name !== 'hive_join' && name !== 'hive_leave') await tryResumeSession()
     switch (name) {
       case 'hive_join': return text(await joinRoom(args))
       case 'hive_say': { requireSession().hive.say(String(args.text || '')); return text(`sent: ${args.text}`) }
       case 'hive_read_chat': { const n = args.limit || 30; const msgs = chatArray().slice(-n).map((m) => `${m.at} ${m.by}(${m.kind}): ${m.text}`); return text(msgs.join('\n') || '(no messages yet)') }
       case 'hive_read_board': { const b = boardMap(); return text(b.length ? b.map((e) => `${e.at} ${e.by} rewrote ${e.file} (${e.churn}) — touched: ${(e.symbols || []).join(', ')}`).join('\n') : '(no rewrites logged)') }
-      case 'hive_assign': { const id = requireSession().hive.assign(String(args.to || ''), String(args.text || '')); return id ? text(`assigned task ${id} to ${args.to} (pending approval if they have an owner)`) : err('need to and text') }
+      case 'hive_assign': { enforceDcoLock(); const id = requireSession().hive.assign(String(args.to || ''), String(args.text || '')); return id ? text(`assigned task ${id} to ${args.to} (pending approval if they have an owner)`) : err('need to and text') }
       case 'hive_read_tasks': {
         const all = taskList(); const me = requireSession().name
         const mine = all.filter((t) => t.to === me)
@@ -167,6 +226,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       case 'hive_wait': {
         const ms = Math.min(Math.max(Number(args.timeoutSeconds) || 60, 1), 300) * 1000
         const r = await waitForWork(ms)
+        const globalState = requireSession().hive.getState()
+        const stateStr = Object.keys(globalState).length ? `\n[GLOBAL PROJECT STATE]\n${JSON.stringify(globalState, null, 2)}\n` : ''
+        
         if (r && r.paused) {
           if (r.mentioned) {
             const parts = []
@@ -174,21 +236,34 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             if (r.tasks && r.tasks.length) parts.push(`📌 Directed task(s):\n${r.tasks.map(fmtTask).join('\n')}`)
             return text(`⏸ You are PAUSED, but were directly addressed. Handle ONLY this, then call hive_wait again (you stay paused until a human resumes you — don't pick up other queued work):\n\n${parts.join('\n\n')}`)
           }
-          return text('⏸ You are PAUSED by mission control. Stop new work and wait. You will be woken if someone @mentions you or assigns you a task; otherwise just call hive_wait again.')
+          return text(`⏸ You are PAUSED by mission control. Stop new work and wait. You will be woken if someone @mentions you or assigns you a task; otherwise just call hive_wait again.${stateStr}`)
         }
-        if (!r) return text('(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)')
+        if (!r) return text(`(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)${stateStr}`)
         const parts = []
         if (r.resumed) parts.push('▶ You were RESUMED by mission control — continue.')
         if (r.tasks.length) parts.push(`APPROVED WORK — do these now, then hive_complete each:\n${r.tasks.map(fmtTask).join('\n')}`)
         if (r.newChat.length) parts.push(`NEW MESSAGES:\n${r.newChat.map((m) => `${m.at} ${m.by}(${m.kind}): ${m.text}`).join('\n')}`)
-        return text(parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)')
+        return text(`${stateStr}\n` + (parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)'))
       }
+      case 'hive_set_state': { requireSession().hive.setState(String(args.key), String(args.val)); return text(`Set global state [${args.key}] to [${args.val}]`) }
+      case 'hive_read_state': { return text(requireSession().hive.getState()) }
+      case 'hive_set_schema': { requireSession().hive.setSchema(String(args.key), args.rules); return text(`Set schema validation for [${args.key}]`) }
       case 'hive_approve': { const r = requireSession().hive.decide(String(args.id), true); return r.ok ? text(`approved ${args.id}`) : err(r.error) }
       case 'hive_deny': { const r = requireSession().hive.decide(String(args.id), false); return r.ok ? text(`denied ${args.id}`) : err(r.error) }
-      case 'hive_complete': { const r = requireSession().hive.complete(String(args.id), String(args.note || '')); return r.ok ? text(`completed ${args.id}`) : err(r.error) }
+      case 'hive_complete': { enforceDcoLock(); const r = requireSession().hive.complete(String(args.id), String(args.note || '')); return r.ok ? text(`completed ${args.id}`) : err(r.error) }
+      case 'hive_claim': {
+        enforceDcoLock();
+        const region = String(args.region || ''); if (!region) return err('need a region (file path)')
+        const got = requireSession().hive.claim(region, String(args.intent || 'edit'))
+        if (got) return text(`claimed ${region} — it's yours. Edit it, then call hive_release.`)
+        const c = requireSession().hive.senseClaim(region)
+        return text(`could NOT claim ${region}${c ? ` — held by ${c.by}${c.intent ? ` (${c.intent})` : ''}` : ''}. Work on something else; check hive_claims for open files.`)
+      }
+      case 'hive_release': { const region = String(args.region || ''); if (!region) return err('need a region'); requireSession().hive.release(region); return text(`released ${region}`) }
+      case 'hive_claims': { const b = requireSession().hive.claimsBoard(); return text(b.length ? b.map((c) => `${c.region} — ${c.by}${c.intent ? ` (${c.intent})` : ''}`).join('\n') : '(nothing claimed right now — all open)') }
       case 'hive_members': { const now = Date.now(); return text(requireSession().hive.members().map((m) => `${m.name} (${m.kind})${m.editing && now - m.editing.at < 15000 ? ` — editing ${m.editing.file}` : ''}`).join('\n') || '(none)') }
       case 'hive_status': { const s = requireSession(); return text({ room: s.room, relay: s.relay, dir: s.dir, name: s.name }) }
-      case 'hive_leave': { requireSession().hive.stop(); session = null; return text('left the room') }
+      case 'hive_leave': { requireSession().hive.stop(); session = null; try { fs.rmSync(SESSION_FILE) } catch {}; return text('left the room') }
       default: return err(`unknown tool: ${name}`)
     }
   } catch (e) { return err(`error: ${e.message}`) }

package/icr-merge.js

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