hivecode-mcp 0.6.0 → 0.7.0

package/sync.js

@@ -21,8 +21,10 @@ import * as Y from 'yjs'
 import { WebsocketProvider } from 'y-websocket'
 import { WebSocket } from 'ws'
 import ignore from 'ignore'
-import { applyDiff, merge3, summarizeChange, changedRange, hasConflictMarkers } from './core.js'
-import { fileRoom, decodeUnsafe, scopeForRoom, pathAllowed, isSafeRelPath } from './token.js'
+import { applyDiff, summarizeChange, changedRange, hasConflictMarkers } from './core.js'
+import { icrMerge3 } from './icr-merge.js' // structure/intent-aware merge; falls back to line merge3
+import { makeCoordinator } from './hive-coord.js' // decentralized claim layer (collision PREVENTION)
+import { fileRoom, decodeUnsafe, scopeForRoom, pathAllowed, writeAllowed, isSafeRelPath } from './token.js'
 
 // Wire-format/protocol version. Bump when a change makes clients incompatible
 // (e.g. the v2 per-file-subdoc model). Broadcast via awareness so peers can warn
@@ -45,9 +47,46 @@ const TASKS_FILE = 'HIVE_TASKS.md' // generated locally from `tasks`; directed w
 const CONFIG_FILE = '.hive.json'   // local rendezvous config (room id); not synced
 const RULES_FILE = 'HIVE_RULES.md' // the law every participant follows; written into every room
 const MEMBERS_FILE = 'HIVE_MEMBERS.md' // live presence: who is in the room right now
+const AGENTS_FILE = 'HIVE_FOR_AGENTS.md' // how an AI agent opening this folder joins (via .hive.json) + behaves
 // Generated/coordination files are rendered locally from CRDT state — never
 // synced as ordinary files (that would cause echo loops / conflicts).
-const SKIP = new Set([BOARD_FILE, CHAT_FILE, TASKS_FILE, CONFIG_FILE, RULES_FILE, MEMBERS_FILE])
+const SKIP = new Set([BOARD_FILE, CHAT_FILE, TASKS_FILE, CONFIG_FILE, RULES_FILE, MEMBERS_FILE, AGENTS_FILE])
+
+// Written into every room folder on sync (like the rules). An AI agent that opens
+// this project reads it to learn it's a Hivecode room and how to JOIN — via the
+// .hive.json already in the folder, so no human has to paste a link.
+const AGENT_MANUAL_TEXT = `# Hivecode — for AI agents working in this folder
+
+This project is part of a live Hivecode room: humans and AI agents editing the same
+codebase together, in real time, with no git push/pull. If you are an AI assistant
+asked to collaborate here, follow this.
+
+## Join the room
+1. If you do NOT have a \`hive_join\` tool and you can run terminal commands, register
+   the Hivecode MCP server, then reload so the tools load:
+     claude mcp add hivecode -- npx -y hivecode-mcp
+2. Call: hive_join({ dir: ".", name: "<your name>", owner: "<the human you work for>" })
+   The room, relay, and token are already saved in .hive.json in this folder, so you
+   do NOT need a link — hive_join reads them automatically.
+3. Read the HIVE_RULES it returns, and follow them.
+
+## Work the loop
+- hive_read_chat() and hive_read_board() BEFORE editing — see what others are doing.
+- hive_claim("path/to/file") BEFORE you edit a file. If you get it, edit then
+  hive_release it. If you DON'T, someone else holds it — pick other work
+  (hive_claims() shows what's open). This is how agents avoid colliding.
+- hive_say("taking X: doing Y") to announce intent before you edit.
+- Edit ONLY inside the folders you were granted. Edits merge live; rewrites are logged.
+- Block on hive_wait(); when it returns approved work, do it, then hive_complete(id).
+- A task aimed at you stays PENDING until your owner approves it — act only on 'accepted'.
+
+## Rules of the road
+- Stay in your lane — never edit folders you weren't granted.
+- Announce before editing; coordinate in chat; ask before anything destructive in others' areas.
+- If a human PAUSES you, finish your current step and stop until resumed.
+- Resolve <<<<<<< conflict markers properly — never blindly overwrite.
+- A human can ROLL BACK your changes at any time; that's normal — re-read and continue.
+`
 
 // The hive's law. Auto-written into every room folder so it is ALWAYS present —
 // no setup, no relying on an agent to remember it. The sync layer enforces the
@@ -70,6 +109,15 @@ another's work. The sync layer enforces the hard parts automatically; you do the
 2. Read HIVE_BOARD.md — which files were just rewritten (and what was touched).
 3. If a file you plan to edit appears there, RE-READ it before changing it.
 
+## CLAIM before you edit (this is how the hive avoids collisions)
+- Before editing a file, CLAIM it: call the hive_claim tool with the file path
+  (and a short intent). This is the most important coordination step.
+  • If you GOT it: edit it, then call hive_release when you finish.
+  • If you could NOT get it: someone else holds it — do NOT edit it. Pick other
+    work; call hive_claims to see what's open.
+- Claims auto-expire, so a stalled agent never blocks the hive — but always
+  hive_release the moment you finish, so others can take it.
+
 ## While you work
 4. ANNOUNCE first: post to chat what you are taking, e.g.
    node hive-say.js <yourName> "taking auth.js: adding login validation"
@@ -146,6 +194,17 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   const tasks = doc.getMap('tasks') // id -> { id, to, by, text, status, decidedBy, at } directed work
   const owners = doc.getMap('owners') // aiName -> ownerHumanName (who may approve its tasks)
   const controls = doc.getMap('controls') // participantName -> { state: 'running'|'paused', by, at } (mission control)
+  // ROLLBACK metadata index: id -> { id, file, by, at, ts, churn, kind, label }. NO
+  // file content here — content is scope-sensitive and lives in each FILE's own doc
+  // (its `snap` map), so it inherits that file's access control. The parent only
+  // holds the timeline (who changed what, when) — same exposure as the manifest,
+  // which already lists every path. Lets a monitor (Control Room) show history.
+  const historyMeta = doc.getMap('history')
+  // The Hive coordination layer: a stigmergic claim map — region(file) -> {by,intent,at,ttl}.
+  // Agents SENSE → FLOW → CLAIM before editing so they don't collide. No central controller;
+  // claims evaporate via TTL so a stalled agent never deadlocks the hive.
+  const claims = doc.getMap('claims')
+  const coordinator = makeCoordinator(claims, name, { ttl: 300000 }) // 5-min claim TTL
   // disableBc: do NOT sync peer-to-peer over BroadcastChannel. The relay must be
   // the ONLY path between clients — otherwise two clients on the same machine would
   // sync directly and bypass the relay's access control (auth, path scope, read-only).
@@ -165,7 +224,13 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     const fdoc = new Y.Doc()
     const fprovider = new WebsocketProvider(relay, fileRoom(room, relPath), fdoc, wsOpts)
     const text = fdoc.getText('content')
-    e = { doc: fdoc, provider: fprovider, text, synced: false }
+    // `snap` (in the FILE's own doc, so it's scope-protected with the file) holds
+    // restore points: id -> { id, file, by, at, ts, content, churn, kind, label }.
+    // `undo` is a per-file UndoManager tracking THIS client's local edits, so a
+    // human/agent can undo their own CRDT changes (Level-0 rollback).
+    const snap = fdoc.getMap('snap')
+    const undo = new Y.UndoManager(text, { captureTimeout: 350 }) // default tracks local-origin txns
+    e = { doc: fdoc, provider: fprovider, text, snap, undo, synced: false }
     fileDocs.set(relPath, e)
     text.observe((_ev, txn) => { if (!txn.local) reconcile(relPath, 'remote') }) // remote content edits
     fprovider.on('sync', (s) => { if (s) { e.synced = true; reconcile(relPath, 'remote') } }) // initial pull settled
@@ -174,6 +239,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   function closeFile(relPath) {
     const e = fileDocs.get(relPath)
     if (!e) return
+    try { e.undo && e.undo.destroy() } catch { }
     try { e.provider.destroy() } catch { }
     try { e.doc.destroy() } catch { }
     fileDocs.delete(relPath)
@@ -184,12 +250,17 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // try to open files I'm not granted — the relay would reject them anyway, but
   // this avoids the churn and keeps out-of-scope files off my disk entirely.
   // undefined = no path restriction (open room or whole-room grant).
-  let myPaths
-  if (token) { const pl = decodeUnsafe(token); const sc = pl && scopeForRoom(pl, room); myPaths = sc ? sc.paths : undefined }
+  let myPaths, myScope = null
+  if (token) { const pl = decodeUnsafe(token); const sc = pl && scopeForRoom(pl, room); myScope = sc || null; myPaths = sc ? sc.paths : undefined }
   // canOpen gates BOTH scope (am I granted this path?) AND safety (is the path
   // safe to write to disk — not a "../" traversal, absolute path, or control-char
   // injection a malicious participant slipped into the shared manifest?).
   const canOpen = (relPath) => isSafeRelPath(relPath) && pathAllowed(myPaths, relPath)
+  // canWrite: of the files I can SEE, which may I PUSH (edit/create in the room)?
+  // A view-only file (in my read scope but not my writePaths) is pull-only — I keep
+  // a local copy synced FROM the room but never publish my changes to it. No token
+  // or a full-write grant => everything I can open is writable (back-compat).
+  const canWrite = (relPath) => !myScope || writeAllowed(myScope, relPath)
 
   const known = new Set()
   const mtimes = new Map()
@@ -231,6 +302,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   }
 
   const conflicted = new Set() // files currently holding unresolved <<<<<<< markers
+  const icrWarned = new Map()  // relPath -> last ICR semantic warning announced (dedupe)
   function reconcile(relPath, origin = 'local') {
     if (SKIP.has(relPath) || isIgnored(relPath)) return // never sync secrets/ignored files
     if (!canOpen(relPath)) return // out-of-scope OR unsafe path (traversal/control char) — never materialize it
@@ -238,6 +310,15 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     const exists = fs.existsSync(full)
     const disk = exists ? readText(full) : null
     if (exists && disk === null) return // present on disk but binary/too-large to represent — leave it untouched (never clobber with stale doc text)
+    // View-only file: never PUSH our local change/creation (the relay would drop it
+    // anyway — it connects this file-room as a reader). Keep disk in sync with the
+    // shared copy if we already have it; a brand-new local-only file just stays local
+    // and is never registered in the manifest. Reads (origin !== 'local') flow on.
+    if (origin === 'local' && !canWrite(relPath)) {
+      const fe2 = fileDocs.get(relPath)
+      if (fe2 && fe2.synced) { const dt = fe2.text.toString(); if (dt && dt !== disk) writeToDisk(relPath, dt) }
+      return
+    }
     // Per-file doc gating: we must know the RELAY's content before touching disk.
     // Until the file-doc has synced, an empty Y.Text means "not pulled yet", not
     // "empty file" — acting now would re-seed from disk and fork the CRDT history
@@ -254,6 +335,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       manifest.set(relPath, 1)
       known.add(relPath); bases.set(relPath, disk); forkBases.set(relPath, disk)
       try { mtimes.set(relPath, fs.statSync(full).mtimeMs) } catch { }
+      captureSnapshot(relPath, disk, name, { force: true, kind: 'base', label: 'created' }); snappedBase.add(relPath)
       return
     }
     const yt = fe.text
@@ -264,6 +346,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       // THIS author's fork on first sight or our own local activity (a remote
       // change landing on disk doesn't mean the local author has seen it).
       if (!forkBases.has(relPath) || origin === 'local') forkBases.set(relPath, disk)
+      if (!snappedBase.has(relPath) && disk) { captureSnapshot(relPath, disk, name, { force: true, kind: 'base', label: 'baseline' }); snappedBase.add(relPath) }
       return
     }
     const base = bases.has(relPath) ? bases.get(relPath) : disk
@@ -288,13 +371,20 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       if (integrated) {
         res = { text: disk, conflict: false } // author built on the latest — trust it
       } else {
-        res = merge3(fork, disk, docText)
+        res = icrMerge3(fork, disk, docText, relPath)
         reAdded = !res.conflict && res.text !== disk // we restored remote lines a stale write had dropped
       }
     } else {
-      res = merge3(base, disk, docText) // incoming remote change merged into our working copy
+      res = icrMerge3(base, disk, docText, relPath) // incoming remote change merged into our working copy
     }
 
+    // Snapshot the state JUST BEFORE this author's edit lands, attributed to them —
+    // captured only on local origin so each change is recorded once, by its author.
+    if (origin === 'local' && res.text !== docText) {
+      const sc = summarizeChange(docText, res.text)
+      captureSnapshot(relPath, docText, name, { force: sc.isRewrite, churn: `${sc.changedLines}/${sc.totalLines} lines` })
+      lastLocalEdit = relPath
+    }
     fileDocs.get(relPath).doc.transact(() => applyDiff(yt, res.text))
     if (res.text !== disk) writeToDisk(relPath, res.text)
     known.add(relPath); bases.set(relPath, res.text)
@@ -313,32 +403,200 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     } else if (reAdded) {
       log(`[${name}] protected ${relPath}: your edit was based on an older version — re-added changes that arrived since (nobody's work lost)`)
       try { say(`↺ ${relPath}: ${name}'s edit was based on an older copy — kept the changes that landed in between (nothing lost).`) } catch { }
+    } else if (!hasMarkers && res.icr === 'rename') {
+      log(`[${name}] ICR merged ${relPath} (detected a rename and updated the call sites)`)
+    } else if (!hasMarkers && res.icr === 'structural') {
+      log(`[${name}] ICR merged ${relPath} structurally (both edits kept, syntax guaranteed)`)
     } else if (!hasMarkers) {
       log(`[${name}] merged ${relPath} (both edits kept)`)
     }
+
+    // ICR semantic warning: the text merged, but ICR saw a meaning-level problem a line
+    // merge can't (e.g. a dangling reference). Surface it once per distinct warning so it
+    // isn't lost — this is exactly the class of bug ICR exists to catch.
+    if (res.icrWarning && icrWarned.get(relPath) !== res.icrWarning) {
+      icrWarned.set(relPath, res.icrWarning)
+      log(`[${name}] ⚠ ICR flag in ${relPath} — ${res.icrWarning}`)
+      try { say(`⚠ ICR flag in ${relPath}: ${res.icrWarning}. It merged, but review — this is a break a plain merge can't see.`) } catch { }
+    } else if (!res.icrWarning && icrWarned.has(relPath)) {
+      icrWarned.delete(relPath)
+    }
   }
 
   const fmtTime = () => new Date().toTimeString().slice(0, 8)
+  // Log file activity to the shared board: EVERY meaningful edit (so the live
+  // activity feed reflects ongoing work), tagged with whether it was a full-file
+  // `rewrite` and a numeric `ts` for ordering. HIVE_BOARD.md stays rewrites-only
+  // (see renderBoard) so the "read before editing" coordination doc isn't noisy.
   function noteIfRewrite(relPath, base, next) {
-    if (!base) return
+    if (base == null || base === next) return
     const s = summarizeChange(base, next)
-    if (!s.isRewrite) return
-    board.set(relPath, { by: name, at: fmtTime(), churn: `${s.changedLines}/${s.totalLines} lines`, symbols: s.symbols })
-    log(`[${name}] board: logged REWRITE of ${relPath} (${s.changedLines}/${s.totalLines} lines; touched ${s.symbols.join(', ') || 'n/a'})`)
+    if (!s.changedLines) return
+    board.set(relPath, { by: name, at: fmtTime(), ts: Date.now(), churn: `${s.changedLines}/${s.totalLines} lines`, symbols: s.symbols, rewrite: s.isRewrite })
+    if (s.isRewrite) log(`[${name}] board: logged REWRITE of ${relPath} (${s.changedLines}/${s.totalLines} lines; touched ${s.symbols.join(', ') || 'n/a'})`)
   }
   function renderBoard() {
+    // HIVE_BOARD.md is the coordination doc: full-file REWRITES only (small edits
+    // live in the activity feed via the board map, but don't clutter this file).
+    const entries = [...board.entries()].map(([file, e]) => ({ file, ...e })).filter((e) => e.rewrite).sort((a, b) => (b.ts || 0) - (a.ts || 0) || (a.at < b.at ? 1 : -1))
+    if (!entries.length) return // no rewrites yet — don't create/clutter the board file
     const out = [
       '# Hive Board — recent full-file rewrites (auto-logged by Hivecode).',
       '# READ THIS before editing a file someone just rewrote, then re-read that file.',
       '',
     ]
-    const entries = [...board.entries()].map(([file, e]) => ({ file, ...e })).sort((a, b) => (a.at < b.at ? 1 : -1))
-    if (!entries.length) out.push('(no rewrites yet — patches and small edits are not listed)')
     for (const e of entries) out.push(`- ${e.at}  ${e.by} rewrote \`${e.file}\` (${e.churn}) — touched: ${(e.symbols || []).join(', ') || 'n/a'}`)
     writeToDisk(BOARD_FILE, out.join('\n') + '\n')
   }
   if (syncFiles) board.observe(() => renderBoard())
 
+  // --- rollback: restore points + per-author revert + undo --------------------
+  // Every meaningful change captures a RESTORE POINT: the file's content from JUST
+  // BEFORE the edit, stored in that file's own doc (scope-safe) and indexed in the
+  // parent `history` (metadata only). Restoring is a normal forward edit (applyDiff
+  // back to the saved content) — so it propagates live to everyone, merges cleanly,
+  // and is itself recoverable. Because each client snapshots only ITS OWN local
+  // edits, every restore point is attributed to its true author exactly once.
+  const SNAP_KEEP = 30          // max AUTO restore points kept per file (manual ones never evicted)
+  const SNAP_MIN_GAP_MS = 4000  // throttle auto-capture per file (fine-grained undo is the editor's job)
+  const META_KEEP = 400         // global cap on the parent timeline index
+  const lastSnapAt = new Map()  // relPath -> ts of last auto-capture
+  const snappedBase = new Set() // files we've already floored with a baseline snapshot
+  const snapId = () => 's' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+
+  function pruneMeta() {
+    if (historyMeta.size <= META_KEEP) return
+    const all = [...historyMeta.values()].filter((e) => e.kind === 'auto').sort((a, b) => (a.ts || 0) - (b.ts || 0))
+    const overflow = historyMeta.size - META_KEEP
+    if (overflow <= 0) return
+    doc.transact(() => { for (let i = 0; i < Math.min(overflow, all.length); i++) historyMeta.delete(all[i].id) })
+  }
+
+  // Capture `content` as a restore point for relPath, attributed to `byWho`.
+  // kind: 'auto' (an ordinary edit), 'base' (a file's floor), 'manual' (a named
+  // checkpoint), 'restore' (the pre-restore state, kept so restore is reversible).
+  function captureSnapshot(relPath, content, byWho, { force = false, churn = '', kind = 'auto', label = '' } = {}) {
+    if (content == null) return null
+    const fe = fileDocs.get(relPath); if (!fe) return null
+    const now = Date.now()
+    if (kind === 'auto' && !force && now - (lastSnapAt.get(relPath) || 0) < SNAP_MIN_GAP_MS) return null
+    const snap = fe.snap
+    let latest = null
+    for (const e of snap.values()) if (!latest || (e.ts || 0) > (latest.ts || 0)) latest = e
+    if (latest && latest.content === content) return null // identical to the most recent point — nothing to keep
+    const id = snapId()
+    const at = fmtTime()
+    const pruned = []
+    fe.doc.transact(() => {
+      snap.set(id, { id, file: relPath, by: byWho, at, ts: now, content, churn, kind, label })
+      const autos = [...snap.values()].filter((e) => e.kind === 'auto').sort((a, b) => (a.ts || 0) - (b.ts || 0))
+      for (let i = 0; i < autos.length - SNAP_KEEP; i++) { snap.delete(autos[i].id); pruned.push(autos[i].id) }
+    })
+    if (kind === 'auto') lastSnapAt.set(relPath, now)
+    doc.transact(() => {
+      historyMeta.set(id, { id, file: relPath, by: byWho, at, ts: now, churn, kind, label }) // metadata only — no content
+      for (const pid of pruned) historyMeta.delete(pid) // keep the index in step with evicted content
+    })
+    pruneMeta()
+    return id
+  }
+
+  // Find which file a restore-point id belongs to (via the index, else by scanning
+  // open file docs as a fallback).
+  function fileOfSnap(id) {
+    const m = historyMeta.get(id)
+    if (m && m.file) return m.file
+    for (const [rp, fe] of fileDocs) if (fe.snap.has(id)) return rp
+    return null
+  }
+
+  // Restore a file to a saved restore point. It first snapshots the CURRENT state
+  // (so the restore can itself be undone), then writes the saved content back as a
+  // normal edit — which syncs to everyone and to disk.
+  function restore(id, by = name) {
+    const relPath = fileOfSnap(id)
+    if (!relPath) return { error: 'restore point not found' }
+    if (!canOpen(relPath)) return { error: `${relPath} is out of your scope` }
+    if (!canWrite(relPath)) return { error: `${relPath} is read-only for you` }
+    let fe = fileDocs.get(relPath)
+    if (!fe) { openFile(relPath); fe = fileDocs.get(relPath) }
+    if (!fe) return { error: 'could not open file' }
+    const entry = fe.snap.get(id)
+    if (!entry || entry.content == null) return { error: 'restore point content unavailable (it may have aged out)' }
+    const current = fe.text.toString()
+    if (current === entry.content) return { ok: true, unchanged: true, file: relPath }
+    captureSnapshot(relPath, current, by, { force: true, kind: 'restore', label: `before restore to ${entry.at}` })
+    fe.doc.transact(() => applyDiff(fe.text, entry.content))
+    writeToDisk(relPath, entry.content)
+    bases.set(relPath, entry.content); forkBases.set(relPath, entry.content)
+    try { say(`↩ ${by} restored ${relPath} to ${entry.at}${entry.by && entry.by !== by ? ` (state before ${entry.by}'s edit)` : ''}.`) } catch { }
+    return { ok: true, file: relPath }
+  }
+
+  // Restore one file to its state as of timestamp `ts` (the newest point at/below ts).
+  function restoreFileTo(relPath, ts, by = name) {
+    const fe = fileDocs.get(relPath)
+    if (!fe) return { error: 'file not open' }
+    let best = null
+    for (const e of fe.snap.values()) if ((e.ts || 0) <= ts && (!best || (e.ts || 0) > (best.ts || 0))) best = e
+    if (!best) return { error: 'no restore point at/before that time' }
+    return restore(best.id, by)
+  }
+
+  // Revert everything an author did since `sinceTs` (default: all of it): for each
+  // file they touched, roll back to the state BEFORE their first edit in the window.
+  // Honest limitation: this is checkpoint-granular, so if SOMEONE ELSE also edited
+  // the same file after that point, their edits in that file are rolled back too.
+  // For the dangerous case — an agent rewriting files — that's exactly right.
+  function revertAuthor(who, sinceTs = 0, by = name) {
+    if (!who) return { error: 'no author given' }
+    const earliest = new Map() // file -> earliest meta authored by `who` in the window
+    for (const m of historyMeta.values()) {
+      if (m.by !== who || (m.ts || 0) < sinceTs) continue
+      const cur = earliest.get(m.file)
+      if (!cur || (m.ts || 0) < (cur.ts || 0)) earliest.set(m.file, m)
+    }
+    const files = []
+    for (const [file, m] of earliest) files.push({ file, ...restore(m.id, by) })
+    const ok = files.filter((f) => f.ok).length
+    if (files.length) { try { say(`⏮ ${by} reverted ${who}'s changes across ${ok}/${files.length} file(s).`) } catch { } }
+    return { ok: true, reverted: ok, files }
+  }
+
+  // The timeline (newest first), read from the parent index. Optional filters.
+  function listHistory({ file = null, by = null, limit = 200 } = {}) {
+    return [...historyMeta.values()]
+      .filter((e) => (!file || e.file === file) && (!by || e.by === by))
+      .sort((a, b) => (b.ts || 0) - (a.ts || 0))
+      .slice(0, limit)
+  }
+
+  // A named manual checkpoint of a file's current state (never auto-evicted).
+  function checkpoint(relPath, label = '', by = name) {
+    const fe = fileDocs.get(relPath); if (!fe) return { error: 'file not open' }
+    const id = captureSnapshot(relPath, fe.text.toString(), by, { force: true, kind: 'manual', label: label || `checkpoint by ${by}` })
+    return id ? { ok: true, id } : { ok: true, unchanged: true }
+  }
+
+  // Level-0 undo/redo: a client undoes its OWN recent CRDT edits to a file. (In an
+  // editor, native Ctrl-Z already covers your own typing; this also covers edits
+  // applied programmatically and keeps the doc, disk, and peers in step.)
+  let lastLocalEdit = null
+  function undoLast() {
+    const rp = lastLocalEdit; const fe = rp && fileDocs.get(rp)
+    if (!fe || !fe.undo || !fe.undo.canUndo()) return { error: 'nothing to undo' }
+    fe.undo.undo()
+    const t = fe.text.toString(); writeToDisk(rp, t); bases.set(rp, t); forkBases.set(rp, t)
+    return { ok: true, file: rp }
+  }
+  function redoLast() {
+    const rp = lastLocalEdit; const fe = rp && fileDocs.get(rp)
+    if (!fe || !fe.undo || !fe.undo.canRedo()) return { error: 'nothing to redo' }
+    fe.undo.redo()
+    const t = fe.text.toString(); writeToDisk(rp, t); bases.set(rp, t); forkBases.set(rp, t)
+    return { ok: true, file: rp }
+  }
+
   // --- coordination channel: the agents (and humans) talk to each other ---
   // say() posts a message into the shared, ordered chat. Everyone renders the
   // whole conversation to HIVE_CHAT.md locally, so an agent just READS that file
@@ -544,6 +802,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   provider.on('sync', (s) => {
     if (!s || !syncFiles) return
     writeToDisk(RULES_FILE, HIVE_RULES_TEXT) // the law is always present in the room
+    writeToDisk(AGENTS_FILE, AGENT_MANUAL_TEXT) // so an agent opening this folder learns how to join + behave
     for (const key of manifest.keys()) if (canOpen(key)) openFile(key) // connect to every file I'm granted; each file-room's sync pulls its content
     if (board.size) renderBoard()
     if (chat.length) renderChat()
@@ -568,6 +827,20 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     control,             // pause/resume an agent (mission control)
     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)),
+    senseClaim: (region) => coordinator.sense(String(region)), // the live claim on a region, or null
+    claimsBoard: () => coordinator.board(),                     // everything currently claimed
+    // --- rollback ---
+    listHistory,         // the restore-point timeline (newest first; filter by file/by)
+    restore,             // restore a file to a restore point by id (reversible)
+    restoreFileTo,       // restore one file to its state as of a timestamp
+    revertAuthor,        // roll back everything an author did since a time
+    checkpoint,          // save a named restore point of a file's current state
+    captureSnapshot,     // (low-level) capture a restore point
+    undoLast,            // undo this client's last local edit
+    redoLast,            // redo it
     // One entry PER NAME, not per connection: the same user open in two windows
     // (e.g. the editor + the browser Control Room) is ONE member. Merge their
     // fields so we keep whichever connection has an active `editing`/`owner`.

package/token.js

@@ -146,6 +146,26 @@ export function pathAllowed(globs, relPath) {
   return inAllow && !matches(neg)
 }
 
+// Phase 5: within a scope, which VISIBLE paths are also WRITABLE. `writePaths` is
+// an optional subset of `paths`: a file the scope can see is read-only unless it
+// ALSO matches writePaths. This is what lets one agent read frontend/ for context
+// but only edit backend/. Semantics, chosen to fail safe:
+//   - role 'reader'        -> never writable (whole grant is view-only)
+//   - no writePaths key     -> every visible path is writable (back-compat: a plain
+//                              writer/agent edits everything it can see)
+//   - writePaths: []        -> nothing writable (explicit view-only everywhere)
+//   - writePaths: [globs]   -> writable IFF the path matches the globs
+// The relay enforces this by connecting an out-of-write-scope file-room as a
+// reader (so makeReadOnly drops its writes); clients use it for read-only UX.
+export function writeAllowed(scope, relPath) {
+  if (!scope) return false
+  if ((scope.role || 'writer') === 'reader') return false
+  const wp = scope.writePaths
+  if (wp == null) return true
+  if (!Array.isArray(wp) || wp.length === 0) return false
+  return pathAllowed(wp, relPath)
+}
+
 // --- self-certifying secured rooms (no server-side key registry, no secret files) ---
 // A secured room's id embeds a fingerprint of the OWNER's public key:
 //     hs_<fp>_<rand>        fp = base64url(sha256(spki-DER)).slice(0, 22)