hivecode-mcp 0.7.0 → 0.11.0

package/sync.js

@@ -21,10 +21,12 @@ import * as Y from 'yjs'
 import { WebsocketProvider } from 'y-websocket'
 import { WebSocket } from 'ws'
 import ignore from 'ignore'
-import { applyDiff, summarizeChange, changedRange, hasConflictMarkers } from './core.js'
+import { applyDiff, summarizeChange, changedRange, hasConflictMarkers, merge3 } 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'
+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
@@ -36,6 +38,11 @@ const PROTOCOL_VERSION = 2
 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',
 ]
 
@@ -45,12 +52,13 @@ const BOARD_FILE = 'HIVE_BOARD.md' // generated locally from `board`; never sync
 const CHAT_FILE = 'HIVE_CHAT.md'   // generated locally from `chat`; the agents' conversation
 const TASKS_FILE = 'HIVE_TASKS.md' // generated locally from `tasks`; directed work + approvals
 const CONFIG_FILE = '.hive.json'   // local rendezvous config (room id); not synced
+const ID_FILE = '.hive-id.json'    // this client's substrate signing identity (private); never 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, AGENTS_FILE])
+const SKIP = new Set([BOARD_FILE, CHAT_FILE, TASKS_FILE, CONFIG_FILE, ID_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
@@ -139,8 +147,10 @@ another's work. The sync layer enforces the hard parts automatically; you do the
     refactor) that touches another participant's area.
 
 ## Directed work + permission (the asymmetric gate)
-11. AI -> AI is COORDINATION: if another agent hands you work, it is auto-accepted
-    and you may proceed. This is how the hive plans and divides work by itself.
+11. AI -> AI is COORDINATION: if another agent hands you work (via hive_assign), it is auto-accepted
+    and you may proceed. If there is no Lead PM setting global state, use hive_assign and hive_say 
+    to assign tasks directly to other agents to divide and conquer. This is how a leaderless hive 
+    plans and divides work by itself.
 12. A HUMAN directing you is different. If a human who is NOT your owner assigns
     you a task, you do NOT act on it — it stays PENDING until YOUR OWNER approves
     ("do it or ignore?"). Your own owner's requests proceed. Act only on tasks
@@ -165,6 +175,11 @@ another's work. The sync layer enforces the hard parts automatically; you do the
 16. YOU triage: announce do-now vs after-current. Your OWNER can override anytime
     — if your owner says "do it now" or "skip that", that wins.
 
+## State-Machine Prompting (SMP)
+17. The Lead PM controls the [GLOBAL PROJECT STATE] via hive_set_state.
+18. ONLY use short enum flags (e.g. "APPROVED", "LOCKED"). Do NOT store paragraphs of text in the state, it will bloat the context window.
+19. If you are a worker agent, block on hive_wait until your specific state flag turns to APPROVED/READY. Do not write code if you are LOCKED.
+
 Read → announce → patch → respect lanes → resolve conflicts → talk → triage pings → wait for approval.
 `
 
@@ -204,7 +219,404 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // 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 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
+  // every change it lands, appending a verifiable receipt to each file's provenance
+  // ledger. This makes invariant I1 (provenance-verified) real end-to-end: every
+  // state the room ever holds is attributable to a cryptographic author + a declared
+  // intent. Everything here is wrapped so a failure can NEVER break sync — provenance
+  // is an added guarantee, not a new dependency of the live path.
+  const PROVENANCE = (process.env.HIVE_PROVENANCE || 'off').toLowerCase() !== 'off'
+  // The live SILENT-FORK GATE (detect + surface concurrent same-line edits) is EXPERIMENTAL
+  // and OFF by default. It reliably surfaces conflicts for realistic (2-3 agent, non-burst)
+  // concurrency, but robustly detecting forks needs a source-level capture of each authored
+  // edit BEFORE it merges — the fs.watch/disk-diff model contaminates the authored version,
+  // so detection can't be made both complete (catch every clash) and sound (never false-flag
+  // a disjoint edit). Opt in with HIVE_FORK_GATE=on. When off, sync behaves exactly as the
+  // proven core: provenance still signs every change; only the fork surfacing is disabled.
+  const FORK_GATE = PROVENANCE && (process.env.HIVE_FORK_GATE || 'off').toLowerCase() !== 'off'
+  let identity = null
+  if (PROVENANCE) {
+    const idPath = path.join(ROOT, ID_FILE)
+    try { if (fs.existsSync(idPath)) { const j = JSON.parse(fs.readFileSync(idPath, 'utf8')); if (j && j.pk && j.sk && j.id) identity = j } } catch { identity = null }
+    if (!identity) { try { identity = genIdentity(name); fs.writeFileSync(idPath, JSON.stringify(identity, null, 2)) } catch { identity = null } }
+    if (identity) log(`[${name}] substrate provenance ON — signing as ${identity.id.slice(0, 12)}…`)
+  }
+  // Record a signed receipt for a landed local change (base -> next) on a file's
+  // ledger. Intent is taken from this author's live claim on the region, so the
+  // WHY that the coordinator already knows is what gets cryptographically bound.
+  // Two concerns, deliberately decoupled:
+  //   stampIntent -> LEDGER receipt: the author's INTENT — the state they edited FROM (base)
+  //     -> the content they WROTE (next). With the fork gate on this comes from the SOURCE
+  //     capture (captureLocal), so it is anchored to a clean base, not the fusing shared
+  //     text — which is what keeps concurrent same-line edits fork-detectable.
+  //   attestHead -> HEAD: content AUTHORITY — attests the ACTUAL landed (converged) content,
+  //     so the relay's non-regression guard always judges real content, never partial intent.
+  function stampIntent(relPath, base, next) {
+    if (!PROVENANCE || !identity) return
+    const fe = fileDocs.get(relPath); if (!fe || !fe.ledger) return
+    // Idempotent: if THIS author already signed this exact (parent -> content) transition,
+    // don't duplicate it — the source capture and the edit path may both stamp the same change.
+    const pHash = contentHash(base == null ? '' : base), cHash0 = contentHash(next)
+    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 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.
+      const receipt = { ...ch.prov, name }
+      fe.doc.transact(() => {
+        fe.ledger.push([receipt])                 // append INTENT to history (audit + fork detection)
+        // Preserve the FULL TEXT of both states, keyed by content hash — the raw material
+        // fork detection reconstructs pre-fusion versions from after the char-CRDT fuses them.
+        storeVersion(fe, base == null ? '' : base)
+        storeVersion(fe, next)
+      })
+    } catch { /* provenance must never break the sync path */ }
+  }
+  function attestHead(relPath, landed, base) {
+    if (!PROVENANCE || !identity || landed == null) return
+    const fe = fileDocs.get(relPath); if (!fe || !fe.head) return
+    try {
+      const cur = fe.head.get('cur')
+      if (cur && cur.hash === contentHash(landed)) return // head already attests this content
+      const c = coordinator.sense(relPath)
+      const 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: 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)
+      })
+    } catch { /* provenance must never break the sync path */ }
+  }
+  // Compatibility wrapper: record intent AND attest the landed content (defaults to next).
+  function stampProvenance(relPath, base, next, landed) {
+    stampIntent(relPath, base, next)
+    attestHead(relPath, landed == null ? next : landed, base)
+  }
+  // Record text by its content hash, bounded: drop any stored version no longer
+  // referenced by a receipt (as a parent or a result) so the map can't grow forever.
+  function storeVersion(fe, text) {
+    if (!fe || !fe.versions || text == null) return
+    fe.versions.set(contentHash(text), text)
+    if (fe.versions.size > 64) {
+      const live = new Set()
+      for (const r of fe.ledger.toArray()) { if (r && r.parent) live.add(r.parent); if (r && r.contentHash) live.add(r.contentHash) }
+      for (const h of [...fe.versions.keys()]) if (!live.has(h)) fe.versions.delete(h)
+    }
+  }
+  // SOURCE-LEVEL EDIT CAPTURE — the subsystem that makes fork detection sound.
+  // A room folder has exactly TWO writers: this engine (every write it makes is recorded in
+  // `shadow`) and the local author (their editor/agent — everything else). So any divergence
+  // of disk from shadow IS an authored edit, and (shadow -> disk) is its true, uncontaminated
+  // (base -> text) pair — captured and signed BEFORE any merge or conflict render can
+  // overwrite the file. This is what after-the-fact disk-diffing could never provide: the
+  // author's version unpolluted by concurrent merges. It closes the capture race: the old
+  // window was the whole watcher debounce; now capture runs at the entry of every pass that
+  // could clobber, so an authored edit enters the provenance DAG before anything overwrites
+  // it. Gate-on only; the proven default path is untouched.
+  function captureLocal(relPath) {
+    if (!FORK_GATE || !identity) return false
+    const fe = fileDocs.get(relPath); if (!fe || !fe.synced || !fe.ledger) return false
+    if (SKIP.has(relPath) || isIgnored(relPath)) return false
+    let disk = null; try { disk = fs.readFileSync(path.join(ROOT, relPath), 'utf8') } catch { return false }
+    const base = shadow.get(relPath)
+    if (base == null || disk === base) return false // no baseline yet, or nothing new on disk
+    if (hasConflictMarkers(disk)) return false      // half-edited conflict block — not an authored state
+    stampIntent(relPath, base, disk)                // into the provenance DAG NOW — clobber-proof
+    shadow.set(relPath, disk)                       // the captured state is the new baseline
+    return true
+  }
+  // Build ONE clean N-way conflict block from a common parent and N divergent versions:
+  // strip the lines they (and the parent) all share as a prefix/suffix, then stack each
+  // version's differing middle between markers. Deterministic (caller sorts versions), so
+  // every peer produces byte-identical output. Returns null if nothing distinct remains.
+  function nwayConflict(parentText, versions) {
+    const P = parentText.split('\n')
+    const Vs = versions.map((v) => v.text.split('\n'))
+    const minLen = Math.min(P.length, ...Vs.map((v) => v.length))
+    let pre = 0
+    while (pre < minLen && Vs.every((v) => v[pre] === P[pre])) pre++
+    let suf = 0
+    while (suf < minLen - pre && Vs.every((v) => v[v.length - 1 - suf] === P[P.length - 1 - suf])) suf++
+    const out = [...P.slice(0, pre)]
+    let any = false
+    versions.forEach((v, i) => {
+      const mid = Vs[i].slice(pre, Vs[i].length - suf)
+      if (mid.length) any = true
+      out.push(`${i === 0 ? '<<<<<<<' : '======='} ${v.name} (${String(v.hash).slice(0, 7)})`)
+      out.push(...mid)
+    })
+    // Closing marker MUST carry a trailing label — core.js hasConflictMarkers matches
+    // /^>>>>>>> /m (note the space), so a bare ">>>>>>>" would not register as a conflict
+    // and the sync layer would treat the block as clean content.
+    out.push('>>>>>>> (resolve: keep one, delete the markers)')
+    out.push(...P.slice(P.length - suf))
+    return any ? out.join('\n') : null
+  }
+  // SILENT-FORK DETECTION — the health gate, done RIGHT (local-render model).
+  //
+  // The char-CRDT (Y.Text) always converges, even when it shouldn't: two agents editing
+  // the SAME line fuse into valid-but-unauthored code ("return 2" + "return 3" -> "return
+  // 32") that no layer flags. Nobody signs that fused byte-string, yet BOTH real versions
+  // were signed against the SAME parent. So the provenance ledger still holds the truth
+  // the char-merge destroyed.
+  //
+  // The KEY design choice: we do NOT write conflict markers back into the shared Y.Text
+  // (that just makes the markers themselves fuse — the old bug). Instead a fork is recorded
+  // as a deterministic, converged RECORD (a per-file LWW register, computed purely from the
+  // ledger so every peer derives the identical value), and each peer renders the markers to
+  // its OWN disk. Nothing concurrent is written to the shared text, so nothing can tangle.
+  // Y.Text is frozen at the fused value and simply ignored until a human resolves.
+
+  // Compute the live fork purely from the ledger. Same input -> same output on every peer,
+  // so setting the record is idempotent and needs no applier election. Returns
+  // { parent, base, versions:[{hash,name,author}] } or null.
+  function computeFork(fe) {
+    const receipts = fe.ledger.toArray()
+    if (!receipts.length) return null
+    const builtOn = new Set(receipts.map((r) => r && r.parent).filter(Boolean))
+    const byParent = new Map()
+    for (const r of receipts) {
+      if (!r || !r.parent || !r.contentHash) continue
+      if (!byParent.has(r.parent)) byParent.set(r.parent, new Map())
+      byParent.get(r.parent).set(r.contentHash, r) // dedupe divergent children by content
+    }
+    for (const [parent, kids] of byParent) {
+      if (kids.size < 2) continue
+      const base = fe.versions.get(parent)
+      if (base == null) continue
+      let arr = [...kids.values()]
+        .map((r) => ({ r, text: fe.versions.get(r.contentHash) }))
+        .filter((x) => x.text != null && !fe.forkmark.has(x.r.contentHash)) // skip versions already folded into a resolved conflict
+      const tips = arr.filter((x) => !builtOn.has(x.r.contentHash)) // prefer live heads
+      if (tips.length >= 2) arr = tips
+      if (arr.length < 2) continue
+      arr.sort((a, b) => (a.r.contentHash < b.r.contentHash ? -1 : 1)) // deterministic order across peers
+      // Discriminator: a REAL same-region fork, or disjoint edits the char-merge combined
+      // fine? If no pair actually conflicts on a 3-way against the base, leave it.
+      let real = false
+      for (let i = 0; i < arr.length && !real; i++)
+        for (let j = i + 1; j < arr.length && !real; j++) {
+          const m = merge3(base, arr[i].text, arr[j].text)
+          if (m.conflict || hasConflictMarkers(m.text)) real = true
+        }
+      if (!real) continue
+      return { parent, base, versions: arr.map((x) => ({ hash: x.r.contentHash, name: x.r.name, author: x.r.author })) }
+    }
+    return null
+  }
+  // The deterministic conflict block for a record (byte-identical on every peer).
+  function forkBlock(fe, rec) {
+    const versions = rec.versions.map((v) => ({ text: fe.versions.get(v.hash), name: v.name, hash: v.hash })).filter((v) => v.text != null)
+    if (versions.length < 2) return null
+    return nwayConflict(rec.base, versions)
+  }
+  // Read the ACTIVE fork from the conflict map. The version set is stored as a UNION of
+  // per-hash keys ('v:'+hash) that MERGE across peers (not a single LWW register), so a
+  // late-arriving version can never be lost to a last-writer-wins race — the set only grows
+  // and converges to the full set on every peer. Returns { parent, base, versions } or null.
+  function forkRecord(fe) {
+    if (!fe || !fe.conflict) return null
+    const meta = fe.conflict.get('meta'); if (!meta) return null
+    const versions = []
+    for (const key of fe.conflict.keys()) {
+      if (!key.startsWith('v:')) continue
+      const v = fe.conflict.get(key)
+      versions.push({ hash: key.slice(2), name: v.name, author: v.author })
+    }
+    if (versions.length < 2) return null
+    versions.sort((a, b) => (a.hash < b.hash ? -1 : 1)) // deterministic order across peers
+    return { parent: meta.parent, base: meta.base, versions }
+  }
+  // Render the active conflict to THIS peer's disk (local only — never Y.Text).
+  function renderConflict(relPath) {
+    const fe = fileDocs.get(relPath); if (!fe || !fe.conflict) return
+    // Before we overwrite this file with the conflict block, capture any local edit sitting
+    // on disk that hasn't been stamped yet — otherwise rendering would silently destroy it.
+    if (captureLocal(relPath)) { detectFork(relPath); return } // it grew the fork; detectFork re-renders with it included
+    const rec = forkRecord(fe); if (!rec) return
+    const block = forkBlock(fe, rec); if (!block) return
+    let disk = null; try { disk = fs.readFileSync(path.join(ROOT, relPath), 'utf8') } catch { }
+    forkBases.set(relPath, block) // this peer has now SEEN the markers — a later clean edit from here is a resolution
+    if (disk === block) return
+    writeToDisk(relPath, block)
+    if (!conflicted.has(relPath)) {
+      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).`)
+      // 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.
+  function adoptResolved(relPath) {
+    const fe = fileDocs.get(relPath); if (!fe) return
+    const dt = fe.text.toString()
+    if (hasConflictMarkers(dt)) return
+    captureLocal(relPath) // an authored edit may be sitting on disk — record it before adopting over it
+    writeToDisk(relPath, dt)
+    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.
+  function detectFork(relPath) {
+    if (!FORK_GATE) return
+    const fe = fileDocs.get(relPath)
+    if (!fe || !fe.ledger || !fe.versions || !fe.conflict || !fe.synced) return
+    const rec = computeFork(fe)
+    if (fe.conflict.has('meta')) {
+      // Already in conflict — union in any newly-seen versions (never overwrites; only adds).
+      if (rec) fe.doc.transact(() => { for (const v of rec.versions) if (!fe.conflict.has('v:' + v.hash)) fe.conflict.set('v:' + v.hash, { name: v.name, author: v.author }) })
+      renderConflict(relPath)
+      return
+    }
+    const cur = fe.text.toString()
+    // Current content is itself a signed/authored state (one side won cleanly, or a human
+    // already resolved) — not a silent fusion.
+    if (fe.ledger.toArray().some((r) => r && r.contentHash === contentHash(cur))) return
+    if (!rec) return
+    fe.doc.transact(() => {
+      fe.conflict.set('meta', { parent: rec.parent, base: rec.base })
+      for (const v of rec.versions) fe.conflict.set('v:' + v.hash, { name: v.name, author: v.author })
+    })
+    renderConflict(relPath)
+  }
   // 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).
@@ -229,11 +641,38 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     // `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')
+    // The file's provenance LEDGER: an append-only list of signed receipts, one per
+    // landed change. Lives in the file's own doc, so it inherits the file's access
+    // control and travels with it. Any peer can verifyReceipt() every entry.
+    const ledger = fdoc.getArray('ledger')
+    // The authoritative HEAD: a single signed pointer at the file's CURRENT content
+    // (key 'cur' -> { text, hash, at, by, receipt }). Content authority = the relay
+    // guarantees this is always a verified, non-regressing attestation of the content.
+    const head = fdoc.getMap('head')
+    // versions: contentHash -> full text, for every state any author edited from or
+    // produced. The char-CRDT keeps only the fused current bytes; this keeps the
+    // pre-fusion originals so a silent fork can be reconstructed and surfaced.
+    const versions = fdoc.getMap('versions')
+    // forkmark: contentHash -> 1 for every version already folded into a surfaced
+    // conflict. Synced, so once ANY peer surfaces a fork, those versions never trigger
+    // again — the conflict stays put until a human resolves it, and a resolution can't
+    // be re-conflicted by a peer whose ledger lags its content (the re-fork race).
+    const forkmark = fdoc.getMap('forkmark')
+    // conflict: the per-file LWW fork RECORD (key 'cur' -> { parent, base, versions }).
+    // Deterministic (computed from the ledger), converged across peers, and rendered to
+    // each peer's DISK — never into the shared text — so conflict markers can't fuse.
+    const conflict = fdoc.getMap('conflict')
     const undo = new Y.UndoManager(text, { captureTimeout: 350 }) // default tracks local-origin txns
-    e = { doc: fdoc, provider: fprovider, text, snap, undo, synced: false }
+    e = { doc: fdoc, provider: fprovider, text, snap, ledger, head, versions, forkmark, conflict, 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
+    // A divergent receipt can arrive slightly after (or before) the fused content — so
+    // re-run the fork check whenever the provenance ledger changes too, not only on edits.
+    ledger.observe((_ev, txn) => { if (!txn.local) detectFork(relPath) })
+    // The fork record arrived/changed from a peer: render it locally, or — if it was
+    // cleared (resolved elsewhere) — adopt the now-clean shared text to disk.
+    conflict.observe((_ev, txn) => { if (txn.local) return; if (e.conflict.has('meta')) renderConflict(relPath); else adoptResolved(relPath) })
+    fprovider.on('sync', (s) => { if (s) { e.synced = true; reconcile(relPath, 'remote'); detectFork(relPath) } }) // initial pull settled
     return e
   }
   function closeFile(relPath) {
@@ -264,6 +703,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
 
   const known = new Set()
   const mtimes = new Map()
+  const shadow = new Map()     // relPath -> exact bytes THIS ENGINE last wrote/captured (source-level edit capture)
   const bases = new Map()      // last synced content per file (advances on every reconcile)
   const forkBases = new Map()  // FORK POINT: what THIS author last saw/authored per file.
   // forkBases advances only on local authorship / first adoption — NOT when a
@@ -297,6 +737,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     const full = path.join(ROOT, relPath)
     fs.mkdirSync(path.dirname(full), { recursive: true })
     fs.writeFileSync(full, content)
+    shadow.set(relPath, content) // record what THE ENGINE wrote — any later disk divergence is an authored edit
     known.add(relPath)
     try { mtimes.set(relPath, fs.statSync(full).mtimeMs) } catch { }
   }
@@ -327,13 +768,63 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     let fe = fileDocs.get(relPath)
     if (!fe) { if (disk === null) return; openFile(relPath); return }
     if (!fe.synced) return
+    // SOURCE CAPTURE (fork gate): before ANYTHING in this pass can merge over or render into
+    // this file, record any authored edit sitting on disk. The edit enters the provenance
+    // DAG first; whatever happens to the disk afterwards can no longer lose it.
+    if (FORK_GATE) captureLocal(relPath)
+    // --- provenance conflict state machine (local-render model) ---
+    // While a file is in a surfaced fork, its markers live ONLY on disk; the shared
+    // Y.Text is left at the fused value. This is what avoids the marker-fusion the old
+    // in-CRDT approach suffered — nothing conflict-related is ever written to Y.Text.
+    if (FORK_GATE && fe.conflict) {
+      const rec = forkRecord(fe)
+      if (rec) {
+        const block = forkBlock(fe, rec)
+        if (origin === 'local') {
+          if (disk === block) return // our own rendered conflict — ignore
+          const fork0 = forkBases.get(relPath)
+          // Did THIS author edit FROM the conflict block (i.e. they saw the markers)? Only
+          // then is a clean edit a RESOLUTION. A clean edit from a NON-marked base is just a
+          // concurrent authored edit that happened during the fork — it must NOT be mistaken
+          // for a resolution, or that agent's work silently replaces everyone's conflict.
+          const sawMarkers = fork0 === block || hasConflictMarkers(fork0 || '')
+          if (sawMarkers && disk !== null && !hasConflictMarkers(disk)) {
+            // RESOLUTION: a human replaced the markers with clean code. Publish it to the
+            // shared text, fold the fork versions, and clear the record for everyone.
+            fe.doc.transact(() => {
+              applyDiff(fe.text, disk)
+              for (const v of rec.versions) fe.forkmark.set(v.hash, 1)
+              for (const key of [...fe.conflict.keys()]) fe.conflict.delete(key)
+            })
+            stampProvenance(relPath, block || '', disk)
+            conflicted.delete(relPath)
+            known.add(relPath); bases.set(relPath, disk); forkBases.set(relPath, disk)
+            try { say(`✓ conflict in ${relPath} resolved by ${name}.`) } catch { }
+            return
+          }
+          if (!sawMarkers && disk !== null && disk !== fork0) {
+            // A concurrent authored edit landed WHILE the fork was open (this agent never saw
+            // the markers). The source capture at the top of this pass already stamped it, so
+            // it is in the fork's version set — re-detect so the record grows to include it.
+            detectFork(relPath)
+            return
+          }
+          renderConflict(relPath); return // still conflicted (or partially edited) — re-assert canonical block
+        }
+        renderConflict(relPath); return // remote churn while in conflict — keep our local render
+      }
+      // No active record, but our disk still shows stale markers while the shared text is
+      // clean again -> a resolution landed elsewhere; adopt it (order-independent w/ observer).
+      if (disk !== null && hasConflictMarkers(disk) && !hasConflictMarkers(fe.text.toString())) { adoptResolved(relPath); return }
+    }
     const docText = fe.text.toString()
     if (docText === '' && !manifest.has(relPath)) {
       // the relay has no copy of this path -> publish ours (a genuinely new file)
       if (disk === null) return
       fe.doc.transact(() => applyDiff(fe.text, disk))
+      stampProvenance(relPath, '', disk) // genesis: sign the file's first content (base = empty)
       manifest.set(relPath, 1)
-      known.add(relPath); bases.set(relPath, disk); forkBases.set(relPath, disk)
+      known.add(relPath); bases.set(relPath, disk); forkBases.set(relPath, disk); shadow.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
@@ -341,7 +832,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     const yt = fe.text
     if (disk === null) { writeToDisk(relPath, docText); bases.set(relPath, docText); forkBases.set(relPath, docText); return }
     if (disk === docText) {
-      known.add(relPath); bases.set(relPath, disk)
+      known.add(relPath); bases.set(relPath, disk); shadow.set(relPath, disk) // agreed state = capture baseline
       // disk and doc already agree — a safe fork point, but only adopt it as
       // 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).
@@ -349,6 +840,20 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       if (!snappedBase.has(relPath) && disk) { captureSnapshot(relPath, disk, name, { force: true, kind: 'base', label: 'baseline' }); snappedBase.add(relPath) }
       return
     }
+    // FIRST-CONTACT ADOPT (no common ancestor). We have never reconciled this file
+    // this session (no base history), yet it ALREADY exists in the room (non-empty
+    // docText) AND on local disk with DIFFERENT content. There is no shared base, so
+    // a 3-way merge would UNION the two copies — the duplicated-content bug seen when
+    // a client clones a repo and then joins a room that already has those files. A
+    // joining client adopts the ROOM's copy wholesale; its local copy is preserved as
+    // a restore point so nothing is lost and the user can revert if it was the good one.
+    if (!bases.has(relPath) && docText !== '' && disk !== docText) {
+      captureSnapshot(relPath, disk, name, { force: true, kind: 'manual', label: 'local copy at join (room copy adopted)' })
+      writeToDisk(relPath, docText)
+      bases.set(relPath, docText); forkBases.set(relPath, docText)
+      if (!snappedBase.has(relPath)) { captureSnapshot(relPath, docText, name, { force: true, kind: 'base', label: 'adopted from room at join' }); snappedBase.add(relPath) }
+      return
+    }
     const base = bases.has(relPath) ? bases.get(relPath) : disk
     const fork = forkBases.has(relPath) ? forkBases.get(relPath) : base
     if (origin === 'local') { noteCoEditing(relPath); markEditing(relPath) } // broadcast activity + warn if someone else is on this file
@@ -360,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
@@ -368,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
@@ -386,6 +895,18 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       lastLocalEdit = relPath
     }
     fileDocs.get(relPath).doc.transact(() => applyDiff(yt, res.text))
+    // Sign this landed local change into the file's provenance ledger (I1). Stamp the
+    // author's TRUE intent — the state THEY edited from (fork) -> the content THEY wrote
+    // (disk) — NOT the live shared text, which under truly-concurrent edits is already
+    // fusing. Recording (fork, disk) keeps every concurrent same-line edit anchored to the
+    // SAME clean parent, so the fork stays detectable no matter how the char-CRDT fuses.
+    if (origin === 'local') {
+      // Gate ON: the author's INTENT was already captured at the source (captureLocal, top
+      // of this pass) — here we only advance the authority head to the landed content.
+      // Gate OFF (default): the proven landed-transition stamp, unchanged.
+      if (FORK_GATE) { if (res.text !== docText) attestHead(relPath, res.text, docText) }
+      else if (res.text !== docText) stampProvenance(relPath, docText, res.text)
+    }
     if (res.text !== disk) writeToDisk(relPath, res.text)
     known.add(relPath); bases.set(relPath, res.text)
     if (origin === 'local') forkBases.set(relPath, res.text) // we authored this state; it's our new fork
@@ -421,6 +942,11 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     } else if (!res.icrWarning && icrWarned.has(relPath)) {
       icrWarned.delete(relPath)
     }
+
+    // Health gate on the live path: after the char-CRDT has converged, check whether the
+    // current content is a SILENT FORK (a fusion nobody authored). If so, record it (the
+    // record is rendered to disk locally — never written back into the shared text).
+    detectFork(relPath)
   }
 
   const fmtTime = () => new Date().toTimeString().slice(0, 8)
@@ -526,6 +1052,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     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}` })
+    captureLocal(relPath) // record any pending authored edit before the restore overwrites it
     fe.doc.transact(() => applyDiff(fe.text, entry.content))
     writeToDisk(relPath, entry.content)
     bases.set(relPath, entry.content); forkBases.set(relPath, entry.content)
@@ -819,6 +1346,91 @@ 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)
+      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}]`)
+    },
+    getState: () => {
+      const s = {}
+      for (const [k, v] of swarmState.entries()) s[k] = v
+      return s
+    },
+    setSchema: (key, rules) => {
+      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)
@@ -828,10 +1440,27 @@ 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
+    headOf: (relPath) => { const e = fileDocs.get(relPath); return e && e.head ? e.head.get('cur') || null : null }, // the file's authoritative attested current content
+    // Audit a file's ledger: verify EVERY receipt's signature + author identity, and
+    // report which authors contributed. Returns { ok, count, verified, bad, authors }.
+    verifyProvenanceOf: (relPath) => {
+      const e = fileDocs.get(relPath)
+      const rs = e && e.ledger ? e.ledger.toArray() : []
+      let verified = 0; const bad = []; const authors = new Set()
+      for (let i = 0; i < rs.length; i++) { const v = verifyReceipt(rs[i]); if (v.ok) { verified++; authors.add(rs[i].author) } else bad.push({ i, reason: v.reason }) }
+      return { ok: bad.length === 0, count: rs.length, verified, bad, authors: [...authors] }
+    },
     // --- rollback ---
     listHistory,         // the restore-point timeline (newest first; filter by file/by)
     restore,             // restore a file to a restore point by id (reversible)