hivecode-mcp 0.14.3 → 0.14.4

package/sync.js

@@ -27,7 +27,8 @@ import ignore from 'ignore'
 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 { gateConfig, runGate, verdictRecord, refusalMessage, forcedMessage } from './hive-gate.js' // the HANDOFF gate: a claim you cannot give back while your own check fails
+import { RULES_MD, AGENT_MANUAL } from './hive-instructions.js'
+import { gateConfig, runGate, verdictRecord, refusalMessage, forcedMessage, gateApproved, gatesDir, writeApproval, notApprovedMessage, notApprovedLine, GATE_CMD, GATE_NOT_APPROVED } from './hive-gate.js' // the HANDOFF gate: a claim you cannot give back while your own check fails
 import { fileRoom, decodeUnsafe, scopeForRoom, pathAllowed, writeAllowed, isSafeRelPath } from './token.js'
 import { validateMemberName } from './hive-mailbox.js' // a name the mention parser cannot produce is not a name
 import { genIdentity, authorChange, verifyReceipt, contentHash } from './substrate.js' // convergent-substrate: signed provenance for every landed change
@@ -229,149 +230,12 @@ const OWN_LOCAL = new Set([SHADOW_FILE, SHADOW_FILE + '.tmp', LOCK_FILE, '.hive-
 // 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@latest
-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.
-- ADDRESS EVERY MESSAGE. Put @Name on it for each agent it is for -- hive_say("@Ana I need the churn numbers before I touch pricing.md"). Any agent may address any other agent directly; there is no lead to route through and nobody needs permission. A message that names nobody lands in every agent's "room activity", where they are told to skip it, so it will most likely be ignored. Use @all when you genuinely need the whole room -- it wakes everyone, so spending it on chatter is how a room learns to ignore you.
-- ANSWER EVERY QUESTION AIMED AT YOU. "Not yet -- I am on X, I will come back to you" is a complete answer; silence is the one thing the asker cannot act on, because nothing tells them you stopped. hive_check lists anyone still waiting on you.
-- BEFORE A LONG STRETCH OF WORK, call hive_busy("what you are doing"). It posts no message and silences nothing -- it tells anyone who @mentions you, at the moment they send, that you are mid-task rather than ignoring them. hive_busy(clear:true) when you finish.
-- 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.
-
-## If something breaks
-Support is support@getgrm.tech. Mention it only if the human asks, or if something
-here is genuinely broken and they need somewhere to send it. Never volunteer it
-otherwise, and never write it into a file.
-`
+const AGENT_MANUAL_TEXT = AGENT_MANUAL // hive-instructions.js: one source for every agent-facing text (0.14.4)
 
 // 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
 // hard parts (merge, board); this is the rest, in plain imperative language.
-const HIVE_RULES_TEXT = `# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
-
-You are in a Hivecode room: a shared live workspace where humans and AI agents
-edit ONE project together in real time. These rules keep anyone from destroying
-another's work. The sync layer enforces the hard parts automatically; you do the rest.
-
-## Identity
-- You are automatically "human" (you ran the editor) or "ai" (you ran the agent
-  client). Nobody declares it — running the client is the declaration.
-
-## Know who you are working with
-- Read HIVE_MEMBERS.md — who (humans + AIs) is in the room right now, and how many.
-
-## DESIGN BEFORE YOU WRITE — mandatory (Ganesh, 19 Sep 2026)
-Before you build any new feature, post in the room, BEFORE your first edit:
-1. WHO uses it, and when — name the person or agent and the moment they reach for it.
-2. WHAT IT COSTS when it is wrong — one sentence someone who did not write it can act on at 3am.
-3. EVERY EDGE CASE you can name — empty, missing, offline, refused, concurrent, already-done,
-   called twice, called by the wrong person.
-Then build it.
-This is not process for its own sake. Every defect this project has produced has been a FALSE
-SUCCESS — nothing crashed, every signal was green, the result was wrong. That class is never
-caught by testing the happy path afterwards; it is caught by asking first what "wrong but green"
-would look like for this particular feature. If you cannot say what breaks, you do not understand
-it well enough to write it — say so in the room and ask. That is a complete answer.
-
-## Before you touch a file
-1. Read HIVE_CHAT.md — what is everyone doing right now.
-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.
-   call hive_say with "taking auth.js: adding login validation"
-5. PREFER SMALL PATCHES — grep to the spot, edit a few lines. Patches from
-   different agents merge automatically with no conflict.
-6. AVOID full-file rewrites unless necessary. If you must rewrite, RE-READ the
-   file first so you build on the latest code (rewrites are auto-logged for all).
-7. STAY IN YOUR LANE — if someone said "I own X" (e.g. the backend), read X but
-   do not edit it; leave that to the owner.
-
-## When things collide
-8. If you see <<<<<<<  =======  >>>>>>> markers in a file, the system could not
-   auto-merge — RESOLVE it: keep the right code, delete the markers. Never ignore
-   them or blindly overwrite.
-9. If your edit was merged/reworked, that is normal — re-read and continue.
-
-## Talking
-10. Coordinate in chat. ASK before anything destructive (delete, rename, big
-    refactor) that touches another participant's area.
-
-## Directed work + permission (the asymmetric gate)
-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
-    whose status is 'accepted'.
-13. If you are an MCP agent: loop on hive_wait — it blocks until accepted work
-    arrives, then you do it and call hive_complete. No need to poll. A pending
-    human request will NOT wake you until your owner approves it.
-
-## Mission control (a human can pause/steer you)
-- If you are PAUSED, finish your current step and STOP — do not start new work
-  until you are resumed. (MCP agents: hive_wait returns no work while paused.)
-- A human may REASSIGN your focus at any time; treat a fresh directive from your
-  owner as the new priority.
-
-## When a ping arrives while you are mid-task (interruptions)
-14. hive_wait only checks BETWEEN steps, so a ping never interrupts mid-step.
-    Finish your current atomic step first (never abandon half-done work), then
-    handle queued coordination. If it's urgent (build broken, blocking others),
-    do it now.
-15. ACKNOWLEDGE a ping as soon as you see it so the sender isn't left hanging,
-    e.g. say "got it — finishing X (~2 min), then on your fix".
-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.
-
----
-Support: support@getgrm.tech
-`
+const HIVE_RULES_TEXT = RULES_MD // hive-instructions.js (0.14.4); HIVE_RULES.md in the package is generated from it
 
 /**
  * Where an account licence may come from, in precedence order — and where it may NOT.
@@ -461,7 +325,10 @@ export function acquireFolderLock(root, room, log = console.log) {
   return release
 }
 
-export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir = '.', name = 'anon', kind = 'human', owner = '', token = '', license = '', log = console.log, syncFiles = true, passive = false, listener = false, app = '' }) {
+export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir = '.', name = 'anon', kind = 'human', owner = '', token = '', license = '', log = console.log, syncFiles = true, passive = false, listener = false, app = '', gatesDir: gatesDirOpt = '' }) {
+  // Where this machine keeps its gate approvals (0.14.4 S-1): outside the synced folder, so no peer can write one.
+  const GATES_DIR = gatesDirOpt || gatesDir()
+  const gateSkipSaid = new Set() // (agent, command) pairs already announced as unchecked
   // BEFORE ANY DISK OR SOCKET WORK. A name outside the mention grammar joins successfully and is
   // then unreachable: its mail, its obligations and its wake-on-mention are all silently dead,
   // and the only symptom is other people being told "@X is NOT in the room" about someone who is
@@ -960,7 +827,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       // 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 { }
+      try { postOnce(`fork:${relPath}:${contentHash(rec.versions.map((v) => v.hash).sort().join(',')).slice(0, 16)}`, `⚠ 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.`, { observer: true }) } catch { }
     }
   }
   // A resolution landed elsewhere: the shared text is clean again. Adopt it to disk.
@@ -1258,7 +1125,8 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   // to everybody; this is what lets a join tell another agent with the same name (refused, see
   // sameNameElsewhere) from this agent a moment ago, restarting in the same folder (allowed).
   const IID = crypto.createHash('sha256').update(`${os.hostname()}|${ROOT}`).digest('hex').slice(0, 12)
-  provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, v: PROTOCOL_VERSION, hv: VERSION_LABEL, passive: !!passive, listener: listener || undefined, app: app || undefined, iid: IID }) // identity is implicit in the client
+  const joinedAt = Date.now()
+  provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, v: PROTOCOL_VERSION, hv: VERSION_LABEL, passive: !!passive, listener: listener || undefined, app: app || undefined, iid: IID, joined: joinedAt }) // identity is implicit in the client
 
   // ---- relay reachability, said out loud exactly once -------------------------------
   // y-websocket retries forever and silently. That is the right RECOVERY behaviour and
@@ -1440,7 +1308,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
               `Do not trust this folder's contents meanwhile.`,
           })).text
       log(`[${name}] !! ${msg}`)
-      try { say(`[!] @all ${msg}`) } catch { /* chat may itself be unreachable — the log still carries it */ }
+      try { postOnce(`notsyncing:${code || 'stuck'}`, `[!] @all ${msg}`, { observer: true, ttlMs: 10 * 60 * 1000 }) } catch { /* chat may itself be unreachable — the log still carries it */ }
     }, 4000)
     if (refusalTimer.unref) refusalTimer.unref()
   }
@@ -2356,7 +2224,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
           if (keptAs) {
             log(`[${name}] local unshared file ${relPath} overwritten by room write; copy preserved in ${keptAs}`)
             try {
-              say(`· ${relPath} on ${name}'s disk was ${unshared.reason} and was overwritten by a room write — local copy preserved in ${keptAs}.`)
+              note(`· ${relPath} on ${name}'s disk was ${unshared.reason} and was overwritten by a room write — local copy preserved in ${keptAs}.`)
             } catch { }
           }
         }
@@ -2514,10 +2382,13 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     if (kept.length) {
       const one = kept.length === 1
       parts.push(`${one ? '1 holds' : `${kept.length} hold`} content the room has never seen, so neither copy was changed and the room's copy was NOT adopted: ${names(kept)}. ` +
-        `In ${name}'s folder ${one ? 'it still holds' : 'they still hold'} ${name}'s version. To make one the room's version, claim it and hive_edit it with the full file. ` +
+        `In ${name}'s folder ${one ? 'it still holds' : 'they still hold'} ${name}'s version, and nothing syncs for ${one ? 'it' : 'them'} until ${name} saves ${one ? 'it' : 'them'} again. To make one the room's version, claim it and hive_edit it with the full file. ` +
         `Don't delete a local copy to get the room's: a deletion syncs, and removes the file for everyone.`)
     }
-    try { say(parts.join(' ')) } catch { }
+    // What concerns THIS folder only (line endings, older copies it now has) is a note for hive_status; only
+    // content the room has never seen is the room's business, because nobody else has it (0.14.4, C5).
+    note(parts.join(' '))
+    if (kept.length) { try { say([parts[0], parts[parts.length - 1]].join(' ')) } catch { } } // the kept part is pushed last
   }
 
   function reconcileBinary(relPath, origin = 'local') {
@@ -2621,7 +2492,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       if (keptAs) {
         log(`[${name}] local binary ${relPath} overwritten by remote write (winner: ${remoteBy || 'teammate'}); copy preserved in ${keptAs}`)
         try {
-          say(`· ${relPath} updated from room (winner: ${remoteBy || 'teammate'}). Your local copy saved to ${keptAs}.`)
+          note(`· ${relPath} updated from room (winner: ${remoteBy || 'teammate'}). Your local copy saved to ${keptAs}.`)
         } catch { }
       }
     }
@@ -2954,7 +2825,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         if (r0.conflict) conflicted.add(relPath)
         bases.set(relPath, r0.text); forkBases.set(relPath, r0.text); shadow.set(relPath, r0.text)
         if (!inManifest(relPath)) queueManifestSet(relPath)
-        try { say(`⚠ ${relPath} was created by two participants at once — both versions were merged${r0.conflict ? ', and CONFLICT markers need resolving' : ''}.`) } catch { }
+        try { postOnce(`race:${relPath}`, `⚠ ${relPath} was created by two participants at once — both versions were merged${r0.conflict ? ', and CONFLICT markers need resolving' : ''}.`, { ttlMs: 10 * 60 * 1000 }) } catch { }
         return
       }
       // REJOIN, NOT A FIRST JOIN. If a previous session of this client wrote this file in
@@ -3066,11 +2937,9 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       // and said", never "lost".
       let keptAt = 0; try { keptAt = fs.statSync(full).mtimeMs } catch { }
       keptUnsent.set(relPath, keptAt)
-      // Said in the room, not only logged (review R5): the agent has to act on it.
-      try {
-        say(`⚠ ${relPath}: ${name}'s copy differs from the room's, and the room cannot tell which is newer (${st.state}: ${name} changed it before the room's copy had loaded here). ` +
-          `Neither was written over the other: ${name}'s is kept on disk, both are in the file's history, and nothing syncs for this file until ${name} saves it again. That save replaces the room's copy. Claim ${relPath} first.`)
-      } catch { }
+      // Said in the room (review R5: the agent has to act on it), but ONCE PER JOIN, in the first-contact
+      // summary below -- not one line per file in engine words. A teammate rejoining with 40 such files
+      // filled the chat with 40 lines (9 Nov 2026; first-contact-summary-test, red since 0.14.3).
       log(`[${name}] ⚠ ${relPath} already existed in room with different content (${st.state}) — room copy was NOT adopted; local disk preserved and frozen until saved again`)
       noteFirstContact('kept', relPath)
       return
@@ -3254,10 +3123,10 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     if (hasMarkers && !conflicted.has(relPath)) {
       conflicted.add(relPath)
       log(`[${name}] ⚠ merge conflict in ${relPath} — kept BOTH versions with <<<<<<< markers`)
-      try { say(`⚠ MERGE CONFLICT in ${relPath} — it has <<<<<<< markers. Whoever owns it: resolve before continuing, by saving the file without them or by passing the marked block as old to hive_edit old/new.`) } catch { }
+      try { postOnce(`conflict:${relPath}`, `⚠ MERGE CONFLICT in ${relPath} — it has <<<<<<< markers. Whoever owns it: resolve before continuing, by saving the file without them or by passing the marked block as old to hive_edit old/new.`, { observer: !res.conflict, clear: `resolved:${relPath}` }) } catch { }
     } else if (!hasMarkers && conflicted.has(relPath)) {
       conflicted.delete(relPath)
-      try { say(`✓ conflict in ${relPath} resolved.`) } catch { }
+      try { postOnce(`resolved:${relPath}`, `✓ conflict in ${relPath} resolved.`, { observer: origin !== 'local', clear: `conflict:${relPath}` }) } catch { }
     } 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 { }
@@ -3275,7 +3144,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     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 { }
+      try { postOnce(`icr:${relPath}:${contentHash(String(res.icrWarning)).slice(0, 16)}`, `⚠ ICR flag in ${relPath}: ${res.icrWarning}. It merged, but review — this is a break a plain merge can't see.`, { observer: origin !== 'local' }) } catch { }
     } else if (!res.icrWarning && icrWarned.has(relPath)) {
       icrWarned.delete(relPath)
     }
@@ -3511,6 +3380,66 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     if (!text) return
     chat.push([{ by: name, kind, at: fmtTime(), text: String(text) }])
   }
+  // ONE LINE PER EVENT, NOT ONE PER OBSERVER (0.14.4, C5). Most system lines are said by whoever
+  // caused them (a task, a review, a revert): one poster by nature. But an OBSERVED event -- a conflict
+  // in a shared file, a client on another build, a divergence -- is detected by every peer's own code,
+  // and each posted it: one conflict gave four MERGE CONFLICT lines and then four "resolved" lines
+  // (incident I-16, #722-#725); one odd client gave a MIXED BUILDS line from every other (I-8, #822-#823).
+  // postOnce(id, text): `id` names the event the same way on every peer. The peer that caused it posts
+  // at once. An observer waits 1.5 s plus 1 s per rank among present engines (sorted by name) and posts
+  // only if nobody has; the key lives in the room (`sys_events`) and expires. A peer that cannot write
+  // the key still posts: a missed alarm hides a conflict, a duplicate is only noise.
+  const sysEvents = doc.getMap('sys_events')
+  const SYS_TTL_MS = 6 * 3600 * 1000
+  const sysTimers = new Set()
+  // What only THIS folder needs to know (a local copy kept, a file that differed at join) goes here, to
+  // the log and hive_status, and not to the whole room (C5).
+  const notices = []
+  function note(text) {
+    const t = String(text || '')
+    if (!t) return
+    log(`[${name}] ${t}`)
+    notices.push({ at: Date.now(), text: t })
+    if (notices.length > 50) notices.shift()
+  }
+  function sysRank() {
+    const names = new Set([name])
+    try {
+      for (const st of provider.awareness.getStates().values()) {
+        const u = st && st.user
+        if (u && u.name && !u.listener && !u.passive && u.v === PROTOCOL_VERSION) names.add(u.name)
+      }
+    } catch { }
+    return [...names].sort().indexOf(name)
+  }
+  function pruneSysEvents(now) {
+    let n = 0
+    for (const [k, v] of sysEvents.entries()) {
+      if (++n > 500) break
+      if (!v || now - (Number(v.at) || 0) > (Number(v.ttl) || SYS_TTL_MS)) sysEvents.delete(k)
+    }
+  }
+  function postOnce(id, text, { observer = false, ttlMs = SYS_TTL_MS, clear = null } = {}) {
+    if (!text) return null
+    if (observer && (passive || listener)) return null // a client nobody waits on never speaks for the room
+    const fire = () => {
+      try {
+        const prev = sysEvents.get(id)
+        if (prev && Date.now() - (Number(prev.at) || 0) < (Number(prev.ttl) || SYS_TTL_MS)) return false
+        doc.transact(() => {
+          sysEvents.set(id, { by: name, at: Date.now(), ttl: ttlMs })
+          if (clear) for (const c of [].concat(clear)) sysEvents.delete(c)
+          pruneSysEvents(Date.now())
+        })
+      } catch { /* fail open: the line is said even if the key could not be written */ }
+      say(text)
+      return true
+    }
+    if (!observer) return fire()
+    const t = setTimeout(() => { sysTimers.delete(t); if (!stopped) { try { fire() } catch { } } }, 1500 + 1000 * Math.max(0, sysRank()))
+    sysTimers.add(t)
+    return null
+  }
   function renderChat() {
     const out = [
       '# Hive Chat — the live coordination channel for everyone in this room.',
@@ -3830,7 +3759,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   let myEditing = null, myLastEdit = null
   let editingClearTimer = null
   const warnedAt = new Map() // file -> last time we warned about co-editing it
-  const setUserState = () => provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, editing: myEditing || undefined, lastEdit: myLastEdit || undefined, v: PROTOCOL_VERSION, hv: VERSION_LABEL, passive: !!passive, listener: listener || undefined, app: app || undefined, iid: IID })
+  const setUserState = () => provider.awareness.setLocalStateField('user', { name, kind, owner: owner || undefined, editing: myEditing || undefined, lastEdit: myLastEdit || undefined, v: PROTOCOL_VERSION, hv: VERSION_LABEL, passive: !!passive, listener: listener || undefined, app: app || undefined, iid: IID, joined: joinedAt })
   function markEditing(relPath) {
     myEditing = { file: relPath, at: Date.now() }
     myLastEdit = myEditing
@@ -3858,7 +3787,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     const now = Date.now()
     if (others.length && now - (warnedAt.get(relPath) || 0) > 30000) {
       warnedAt.set(relPath, now)
-      try { say(`⚠ heads-up: ${name} is also editing ${relPath} (with ${others.join(', ')}). Small patches auto-merge; coordinate before a full rewrite.`) } catch { }
+      try { postOnce(`coedit:${relPath}:${[name, ...others].sort().join(',')}`, `⚠ heads-up: ${name} is also editing ${relPath} (with ${others.join(', ')}). Small patches auto-merge; coordinate before a full rewrite.`, { ttlMs: 10 * 60 * 1000 }) } catch { } // the one who just started editing is the cause: it says it at once
     }
   }
   function memberList() {
@@ -3927,7 +3856,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       versionWarned.add(u.name)
       const theirs = u.v ? `v${u.v}` : 'an older build'
       log(`[${name}] ⚠ ${u.name} is on ${theirs} (incompatible with v${PROTOCOL_VERSION}) — they won't sync correctly until everyone updates.`)
-      try { say(`⚠ ${u.name} is on an incompatible version — files won't sync with them until everyone updates Hivecode.`) } catch { }
+      try { postOnce(`proto:${u.name}:${u.v || '-'}`, `⚠ ${u.name} is on an incompatible version — files won't sync with them until everyone updates Hivecode.`, { observer: true }) } catch { }
     }
     checkBuilds()
   }
@@ -3941,40 +3870,69 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
   //   - humans are not flagged: the extension and the browser panel carry no engine build
   //   - one side of each pair speaks (the name that sorts first), once per build it sees
   const buildWarned = new Set()
+  // ONE ALARM PER ROOM, AND ONLY FOR ANOTHER RELEASE (0.14.4, C5). The rule used to be "one side of
+  // each pair speaks", which is still one line per PAIR: two clients on 0.14.2 each posted about the one
+  // on 0.14.3 (#822 + #823), and a client on the same release from another commit raised the same alarm
+  // (I-8). Now the event is the set of releases in the room: it is said once, by whoever sees it first,
+  // naming who runs what. The same release from another commit is a note for this folder (hive_status).
   function checkBuilds() {
-    // An old engine cannot speak for itself, so SOMEBODY current must -- but only one: the reporting
-    // client whose name sorts first. Otherwise every current client in the room says the same thing.
-    // Listeners (listener: true, syncFiles: false) do not sync or edit files and do not report builds.
-    const reporters = [name]
-    const currentEngines = new Set()
-    for (const s of provider.awareness.getStates().values()) {
-      const u = s && s.user
-      if (!u || !u.name || u.v !== PROTOCOL_VERSION || u.listener) continue
-      if (u.hv) reporters.push(u.name)
-      if (u.hv === VERSION_LABEL) currentEngines.add(u.name)
-    }
-    const speakForOld = reporters.sort()[0] === name
-
-    for (const s of provider.awareness.getStates().values()) {
-      const u = s && s.user
+    // Per CONNECTION, not per name: one participant with two engines open on different builds is its own
+    // alarm (0.14.3 Q-2: "an older connection is still open"), and a map keyed by name would hide it.
+    const labelsOf = new Map() // name -> Set of what its engines run
+    const add = (n, label) => { if (!labelsOf.has(n)) labelsOf.set(n, new Set()); labelsOf.get(n).add(label) }
+    add(name, VERSION_LABEL)
+    for (const st of provider.awareness.getStates().values()) {
+      const u = st && st.user
       if (!u || !u.name || u.name === name || u.v !== PROTOCOL_VERSION || u.listener) continue
-      const human = String(u.kind || '').toLowerCase() === 'human'
-      let theirs = ''
-      if (u.hv) {
-        if (u.hv === VERSION_LABEL || name > u.name) continue
-        const olderOpen = currentEngines.has(u.name) ? ` (an older connection from ${u.name} is still open)` : ''
-        theirs = `hivecode ${u.hv}${olderOpen}`
-      } else if (!human) {
-        if (!speakForOld) continue
-        const olderOpen = currentEngines.has(u.name) ? ` (an older connection from ${u.name} is still open)` : ''
-        theirs = `a hivecode build older than build reporting (before ${VERSION})${olderOpen}`
-      } else continue
-      const key = `${u.name}|${u.hv || '-'}`
-      if (buildWarned.has(key)) continue
-      buildWarned.add(key)
-      const same = u.hv && u.hv.split('+')[0] === VERSION ? ' (the same release from different commits)' : ''
-      log(`[${name}] ⚠ MIXED BUILDS: ${u.name} runs ${theirs}, this client runs ${VERSION_LABEL}${same}`)
-      try { say(`⚠ MIXED BUILDS: ${u.name} runs ${theirs}, ${name} runs hivecode ${VERSION_LABEL}${same}. Two builds in one room can lose file content with no error on either side -- everyone should run the same build.`) } catch { }
+      if (u.hv) add(u.name, String(u.hv))
+      // An AI on this protocol reporting no build is an engine older than build reporting: the rollout
+      // case, and it cannot warn itself. Humans carry no engine build (the extension, the browser panel).
+      else if (String(u.kind || '').toLowerCase() !== 'human') add(u.name, `a build older than build reporting (before ${VERSION})`)
+    }
+    const older = (label) => /^a build older/.test(label)
+    const releaseOf = (label) => (older(label) ? label : String(label).split('+')[0])
+    const on = (label) => (older(label) ? `on ${label}` : `on hivecode ${label}`)
+    // The same release from another commit: a note for this folder, not a room alarm.
+    for (const [n, labels] of labelsOf) {
+      if (n === name) continue
+      for (const label of labels) {
+        if (label === VERSION_LABEL || releaseOf(label) !== VERSION) continue
+        const key = `note|${n}|${label}`
+        if (buildWarned.has(key)) continue
+        buildWarned.add(key)
+        note(`${n} runs hivecode ${label}: the same release as this client (${VERSION_LABEL}), from another commit.`)
+      }
+    }
+    // One name, two engines on different builds: they write over each other's files.
+    for (const [n, labels] of labelsOf) {
+      if (n === name || labels.size < 2) continue
+      const all = [...labels].sort()
+      const id = `dual:${n}:${all.join('|')}`
+      if (buildWarned.has(id)) continue
+      buildWarned.add(id)
+      log(`[${name}] ⚠ MIXED BUILDS: ${n} has engines ${all.map(on).join(' and ')}`)
+      try { postOnce(id, `⚠ MIXED BUILDS: ${n} has two engines open, ${all.map(on).join(' and ')} (an older connection from ${n} is still open). Two engines under one name can lose file content with no error on either side -- close the older one.`, { observer: true }) } catch { }
+    }
+    // An OLDER RELEASE in the room: one alarm per participant and build, for the whole room. The event
+    // is "X runs B, older than the newest release here": every observer sees the same newest release, so
+    // they name the same event, and presence churn (an agent's state re-published) never re-raises it.
+    const parts = (r) => (older(r) ? [-1] : String(r).split('.').map((x) => parseInt(x, 10) || 0))
+    const cmp = (a, b) => { const x = parts(a), y = parts(b); for (let k = 0; k < Math.max(x.length, y.length); k++) { const d = (x[k] || 0) - (y[k] || 0); if (d) return d } return 0 }
+    const releases = new Set()
+    for (const labels of labelsOf.values()) for (const label of labels) releases.add(releaseOf(label))
+    if (releases.size < 2) return
+    const newest = [...releases].sort(cmp).pop()
+    const current = []
+    for (const [n, labels] of labelsOf) for (const label of labels) if (releaseOf(label) === newest) current.push(`${n} ${on(label)}`)
+    for (const [n, labels] of labelsOf) {
+      for (const label of labels) {
+        if (releaseOf(label) === newest) continue
+        const id = `builds:${n}:${label}`
+        if (buildWarned.has(id)) continue
+        buildWarned.add(id)
+        log(`[${name}] ⚠ MIXED BUILDS: ${n} runs ${older(label) ? label : `hivecode ${label}`}`)
+        try { postOnce(id, `⚠ MIXED BUILDS: ${n} runs ${older(label) ? label : `hivecode ${label}`}, older than the room's newest release (${current.sort().join(', ')}). Two releases in one room can lose file content with no error on either side -- ${n} should update (npx -y hivecode-mcp@latest setup, then restart).`, { observer: true }) } catch { }
+      }
     }
   }
   if (syncFiles) provider.awareness.on('change', () => { renderMembers(); renderClaims(); checkVersions() })
@@ -4861,6 +4819,8 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
     try { flushFirstContact() } catch { } // before `stopped`: a join cut short still says what it kept
     try { settleLocalDeletes() } catch { } // a delete made just before leaving still leaves, judged like any other
     stopped = true
+    for (const t of sysTimers) clearTimeout(t)
+    sysTimers.clear()
     try { flushRoomDoc() } catch { }
     if (openTimer) { clearImmediate(openTimer); clearTimeout(openTimer); openTimer = null }
     if (renderBoardTimer) { clearImmediate(renderBoardTimer); renderBoardTimer = null }
@@ -4945,6 +4905,11 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         }
       }
       swarmState.set(key, val)
+      // The session that sets a gate has chosen to run that command, so its own machine approves it
+      // (0.14.4 S-1). Nobody else's does: a gate set here runs elsewhere only after that person approves.
+      if (key === GATE_CMD && String(val == null ? '' : val).trim()) {
+        try { writeApproval(room, String(val), `set by ${name} on this machine`, GATES_DIR) } catch { /* no approval, so it simply does not run here */ }
+      }
       say(`STATE TRANSITION: [${key}] is now [${val}]`)
     },
     getState: () => {
@@ -5074,7 +5039,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
           if (v.stuckLagging) return `${v.peer}:${v.bytes}b/${v.lines}L[STUCK:${v.stuckReason || 'not catching up'}]`
           return `${v.peer}:${v.bytes}b/${v.lines}L`
         }).join('  ')
-        say(`[!] DIVERGENCE on ${p} — peers hold DIFFERENT content: ${detail}. Nobody may write this path until it is reconciled; mark it path:${p}=POISONED if it cannot be.`)
+        postOnce(`diverge:${p}:${contentHash(detail).slice(0, 16)}`, `[!] DIVERGENCE on ${p} — peers hold DIFFERENT content: ${detail}. Nobody may write this path until it is reconciled; mark it path:${p}=POISONED if it cannot be.`)
       }
 
       return {
@@ -5107,6 +5072,8 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
       }
     },
     say,                 // post a coordination message
+    postOnce,            // a system line said once per event in the room, whoever sees it (0.14.4, C5)
+    notices: () => notices.slice(), // what only this folder needs to know (hive_status shows it)
     assign,              // direct a task at a participant (needs approval if target AI has an owner)
     decide,              // approve/deny a task (owner only, if set)
     complete,            // mark a task done
@@ -5168,6 +5135,17 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         return { ok: true, gated: true, forced: true }
       }
 
+      // A COMMAND FROM THE ROOM IS DATA (0.14.4 S-1). It runs here only if this machine's person
+      // approved this exact command; otherwise the hand-back goes through UNCHECKED -- never refused,
+      // or setting a gate would be a way to stop everyone -- and that is recorded and said once.
+      const approvedBy = gateApproved({ room, cmd: g.cmd, dir: GATES_DIR })
+      if (!approvedBy) {
+        gateResults.set(`${r}|${name}`, { ...verdictRecord({ region: r, by: name, cmd: g.cmd, result: null }), skipped: 'not-approved' })
+        letGo()
+        const said = `${name}|${g.cmd}`
+        if (!gateSkipSaid.has(said)) { gateSkipSaid.add(said); try { say(notApprovedLine(name)) } catch { /* chat is not the point */ } }
+        return { ok: true, gated: false, gateSkipped: 'not-approved', code: GATE_NOT_APPROVED, cmd: g.cmd, message: notApprovedMessage({ region: r, cmd: g.cmd, dir: ROOT }) }
+      }
       const result = runGate({ cmd: g.cmd, cwd: ROOT, timeoutMs: g.timeoutMs })
       gateResults.set(`${r}|${name}`, verdictRecord({ region: r, by: name, cmd: g.cmd, result }))
       if (!result.ok) {
@@ -5281,7 +5259,7 @@ export function startSync({ relay = 'ws://localhost:1234', room = 'default', dir
         if (id === me || !u || !u.name || String(u.name).toLowerCase() !== lc) continue
         if (u.listener || u.iid === IID) continue
         if (kind === 'human' && u.kind === 'human') continue
-        out.push({ name: u.name, kind: u.kind, owner: u.owner, app: u.app })
+        out.push({ name: u.name, kind: u.kind, owner: u.owner, app: u.app, joined: u.joined, clientID: id })
       }
       return out
     },

package/docs/HIVE_RULES.md

@@ -1,41 +0,0 @@
-# HIVE RULES — read this first. Everyone in this room (human or AI) follows these.
-
-You are in a Hivecode room: humans and AI agents edit ONE project together live.
-These rules keep anyone from destroying another's work. The sync layer enforces
-the hard parts automatically; you do the rest.
-
-## Before you touch a file
-1. Read HIVE_CHAT.md — what is everyone doing right now.
-2. Read HIVE_BOARD.md — which files were just rewritten.
-3. If a file you plan to edit appears there, RE-READ it before changing it.
-
-## While you work
-4. ANNOUNCE in chat what you are taking before you start.
-5. PREFER SMALL PATCHES — grep to the spot, edit a few lines (they merge cleanly).
-6. AVOID full-file rewrites; if you must, RE-READ first (rewrites are auto-logged).
-7. STAY IN YOUR LANE — read others' areas, but leave edits to the owner.
-
-## When things collide
-8. <<<<<<< ======= >>>>>>> markers = a real conflict: keep the right code, delete
-   the markers. Never ignore or blindly overwrite.
-9. If your edit was merged/reworked, that is normal — re-read and continue.
-
-## Talking
-10. Coordinate in chat. ASK before anything destructive in another's area.
-
-## Mission control
-- If a human PAUSES you, finish your current step and STOP — start no new work
-  until resumed. A human may reassign your focus anytime; their directive wins.
-
-## When you get a ping mid-task (interruptions)
-11. Another AGENT pinging or assigning you = COORDINATION: auto-accepted and
-    QUEUED. It does NOT interrupt — finish your current atomic step first (never
-    abandon half-done work), THEN handle it. If it's urgent (build broken,
-    blocking others), do it now.
-12. ACKNOWLEDGE the moment you see a ping so the sender isn't left hanging, e.g.
-    "got it — finishing X (~2 min), then on your auth.js fix".
-13. YOU triage: say whether you'll do it now or after your current step. Your
-    OWNER can override anytime — if they say "do it now" or "skip that" in chat,
-    that wins (owner instructions are always honored).
-14. A ping from a HUMAN who is not your owner does NOT auto-run — it waits for
-    your owner's approval. Keep working; your owner decides.