hivecode-mcp 0.12.4 → 0.13.0

package/hive-mcp.js

@@ -37,6 +37,8 @@ if (!process.env.HIVE_PROVENANCE) process.env.HIVE_PROVENANCE = 'on'
 if (!process.env.HIVE_FORK_GATE) process.env.HIVE_FORK_GATE = 'on'
 import { startSync, parseLink } from './sync.js'
 import { checkRelay, currentRelayFor, controlUrl, PUBLIC_DEFAULT_RELAY } from './hive-privacy.js'
+import { newPersonalRoom, saveRoomKey, loadRoomKey, hostToken, main as roomKeyMain } from './hive-room-key.js'
+import { isSecuredRoom } from './token.js'
 import { createMailbox, formatMessage, mentionsName, mentionedNames, mentionsAll, unansweredFor, priorityOf, ambientDigest, validateMemberName, collapseRepeats, findClosestKnown, isDirectAddress } from './hive-mailbox.js'
 import { INSTRUCTIONS, JOIN_RULES } from './hive-instructions.js'
 import { makeBusy, isBusy, describeRecipient } from './hive-busy.js'
@@ -48,6 +50,7 @@ import { findSecrets, describeSecret } from './hive-secrets.js' // a key never g
 import { makeThrottle, RULES_NUDGE } from './hive-throttle.js'
 import * as HB from './hive-branch.js' // a room bound to a git branch: hive_join { branch }, and the branch/pr CLI
 import { isArmed, armedFile, listenCommand, listenHow, listenOrder, LISTEN_IDLE_MIN, AWAIT_JS } from './hive-listen.js'
+import { SESSION_FILE_NAME, readAgents, writeAgents, ownRecord, excludeFromGit } from './hive-session.js'
 
 const DEFAULT_RELAY = process.env.HIVE_RELAY || PUBLIC_DEFAULT_RELAY // written once, in hive-privacy.js
 let session = null // { hive, room, relay, dir, name, mailbox }
@@ -86,24 +89,44 @@ function resolveRoomRaw(link, dir) {
   return { relay: DEFAULT_RELAY, room: 'room-' + crypto.randomBytes(13).toString('base64url'), token: '', mode: 'HOSTED (new room)' }
 }
 
-// Session persistence: keyed to this process's cwd, so each agent runtime (which starts
-// its own MCP process from its own directory) resumes only its own identity. Lets the
-// session survive MCP host restarts, which otherwise silently drop the agent from the room.
-const SESSION_FILE = path.join(process.cwd(), '.hive-mcp-session.json')
+// Session persistence: in the folder this server was started in, so a restart of the MCP host
+// rejoins as the same agent instead of silently dropping it from the room. That folder is often
+// shared: two Claude Code sessions in one repo is the obvious way to run a branch room. So the file
+// keeps one record per agent, each with this server's pid, and every read takes only this
+// process's own record (hive-session.js says why it once held one agent, and what that broke).
+const SESSION_FILE = path.join(process.cwd(), SESSION_FILE_NAME)
+const CONV = process.env.CLAUDE_CODE_SESSION_ID || process.env.ANTIGRAVITY_CONVERSATION_ID || ''
+let keptOutOfGit = false
 function persistSession({ dir, name, owner, cursor, authed = false, kind = 'ai', passive = false }) {
   try {
-    const prev = readSessionFile() || {}
-    const chatCursor = cursor === undefined ? prev.chatCursor : cursor
+    const agents = readAgents(SESSION_FILE)
+    const prev = ownRecord(agents, { conv: CONV })
+    const chatCursor = cursor === undefined ? (prev && prev.name === name ? prev.chatCursor : undefined) : cursor
     // `authed`: the Stop hook reads this file, and must not order a listener into a room that checks
     // tokens -- the agent's shell does not hold this server's token, so that listener could not join.
     // `kind` and `passive`: a resume rejoins from this file, and without them a human came back as an
     // AI and a passive participant as one the room waits on; the Stop hook reads `passive` too.
-    fs.writeFileSync(SESSION_FILE, JSON.stringify({ dir, name, owner, chatCursor, ...(authed ? { authed: true } : {}),
-      ...(kind && kind !== 'ai' ? { kind } : {}), ...(passive ? { passive: true } : {}) }))
+    const rec = { dir, name, owner, chatCursor, ...(authed ? { authed: true } : {}),
+      ...(kind && kind !== 'ai' ? { kind } : {}), ...(passive ? { passive: true } : {}),
+      pid: process.pid, ...(CONV ? { conv: CONV } : {}), at: Date.now() }
+    for (const [n, s] of Object.entries(agents)) if (n !== name && s.pid === process.pid) delete agents[n] // this server's earlier identity
+    agents[name] = rec
+    writeAgents(SESSION_FILE, agents, rec)
+    // The launch folder is often the developer's own checkout: keep our files out of their `git status`.
+    if (!keptOutOfGit) { keptOutOfGit = true; excludeFromGit(path.dirname(SESSION_FILE)) }
   } catch { /* best-effort */ }
 }
 function readSessionFile() {
-  try { return JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8')) } catch { return null }
+  try { return ownRecord(readAgents(SESSION_FILE), { conv: CONV }) } catch { return null }
+}
+/** Take this agent off the record (it left, or was refused), and only this agent. */
+function forgetSession() {
+  try {
+    const agents = readAgents(SESSION_FILE)
+    const mine = ownRecord(agents, { conv: CONV })
+    for (const [n, s] of Object.entries(agents)) if (s.pid === process.pid || s === mine) delete agents[n]
+    writeAgents(SESSION_FILE, agents)
+  } catch { /* best-effort */ }
 }
 /** Save the read cursor so a host restart does not reopen the blind window it just closed. */
 function persistCursor() {
@@ -119,7 +142,7 @@ function persistCursor() {
 async function tryResumeSession() {
   try {
     if (!fs.existsSync(SESSION_FILE)) return
-    const s = readSessionFile()
+    const s = readSessionFile() // only this process's own record: never an agent still running beside it
     if (s && s.dir && s.name && fs.existsSync(path.join(path.resolve(s.dir), '.hive.json'))) await joinRoom(s)
   } catch { /* resume is best-effort; the agent can always hive_join explicitly */ }
 }
@@ -166,7 +189,7 @@ function defaultJoinTarget(link, name) {
   return { dir: path.join(HIVE_HOME, safeSegment(room), safeSegment(name)), link, hostedHere: false }
 }
 
-async function joinRoom({ link = '', dir = '', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor, kind = 'ai', passive = false, branch = '', repo = '' }) {
+async function joinRoom({ link = '', dir = '', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor, kind = 'ai', passive = false, branch = '', repo = '', private: personal = false }) {
   // REFUSED BEFORE THE OLD SESSION IS TORN DOWN. joinRoom's first act is to stop whatever session
   // exists, so validating after that point would leave an agent with a bad name holding nothing at
   // all -- it would lose a working room to a refusal it could have been given for free.
@@ -178,9 +201,26 @@ Nothing was joined and your current session is untouched. Re-run hive_join with
 
 This is refused rather than fixed for you because renaming silently is worse: if another member is already called "${nameCheck.suggested}", you would be merged into them -- one awareness entry, one read cursor, one mailbox -- and neither of you would be told. Your own prompt would also still say your name is "${name}", so you would stop recognising messages about yourself.`
   }
+  // A PERSONAL ROOM IS ALWAYS A NEW ONE (8 Oct 2026, hive-room-key.js). Refused here, before the old
+  // session is torn down, for the same reason as the name check above.
+  if (personal && (link || branch)) {
+    return `private: true hosts a NEW personal room, so it cannot be combined with a ${link ? 'link' : 'branch'}.\n\nNothing was joined and your current session is untouched.`
+  }
+  if (personal && dir && roomIn(dir)) {
+    return `${path.resolve(dir)} already belongs to room ${roomIn(dir)}, and a folder holds one room. Pass a new dir, or leave out private to rejoin that room.\n\nNothing was joined and your current session is untouched.`
+  }
   // A BRANCH ROOM (hive-branch.js): the link comes from the repo's git config, and the folder is
   // this participant's own, marked so git refuses to run in it. Resolved and refused BEFORE the old
   // session is torn down, for the same reason as the name check above.
+  // SINGLE IDENTITY PER MCP PROCESS (Q637). Some host apps (Antigravity, Cursor, Claude Desktop)
+  // run ONE shared MCP server process across all their agent windows and tabs. A second join with a
+  // different name while a session is live would silently usurp the first session, breaking chat
+  // identity and authorship attribution. Refused FIRST, before anything below touches the disk: the
+  // branch path marks the folder as not-a-checkout, and a refusal that has already written there is
+  // not "nothing was joined" (antigravity-3, 1 Nov).
+  if (session && session.name !== name) {
+    return `Q637 This Hivecode server is already in use by '${session.name}' in ${session.room} (${session.dir}). If you are a different agent, you are sharing one MCP server with it. Do not leave or rejoin; tell your person: add a second server entry (for example 'hivecode-2') in your app's MCP config and restart the app (docs/JOIN_WITH_AGENT.md). If you ARE '${session.name}' and mean to switch, join again with the name '${session.name}'.\n\nNothing was joined and your current session is untouched.`
+  }
   let branchCtx = null
   if (branch) {
     const untouched = '\n\nNothing was joined and your current session is untouched.'
@@ -195,11 +235,20 @@ This is refused rather than fixed for you because renaming silently is worse: if
   }
   if (session) { try { session.hive.stop() } catch {} ; session = null }
   let hostedHere = false
+  // The new personal room exists only in memory until the privacy gate below has passed: a refused
+  // join must leave nothing behind, and that includes a key for a room nobody ever entered.
+  let fresh = null
+  if (personal) {
+    fresh = newPersonalRoom()
+    link = `${DEFAULT_RELAY}|${fresh.room}`
+    if (!dir) dir = path.join(HIVE_HOME, fresh.room, safeSegment(name))
+    hostedHere = true
+  }
   if (!dir) ({ dir, link, hostedHere } = defaultJoinTarget(link, name))
   const ROOT = path.resolve(dir)
   fs.mkdirSync(ROOT, { recursive: true })
   const { relay, room, token: linkToken, mode: resolvedMode, migratedFrom } = resolveRoom(link, dir)
-  const mode = hostedHere ? 'HOSTED (new room)' : resolvedMode
+  const mode = hostedHere ? (fresh ? 'HOSTED (new personal room)' : 'HOSTED (new room)') : resolvedMode
   // THE PRIVACY GATE, and note where it sits: after the relay is resolved, BEFORE the
   // .hive.json write below and before startSync opens a socket. A refused join must leave
   // nothing behind -- no config pointing at the wrong relay for the next process to find,
@@ -218,8 +267,13 @@ folder: ${ROOT}
 NOTHING WAS JOINED. No socket was opened, no file was published, and ${path.join(ROOT, '.hive.json')}
 was not written. Fix the relay and call hive_join again.`
   }
+  if (fresh) saveRoomKey(fresh, { relay, host: name })
   // token precedence: explicit arg > token baked into the join link > $HIVE_TOKEN.
-  const useToken = token || linkToken || process.env.HIVE_TOKEN || ''
+  let useToken = token || linkToken || process.env.HIVE_TOKEN || ''
+  // A personal room this machine hosts: the host's own token is minted from the key, and renewed
+  // before it runs out, so the host can never be locked out of its own room. Anyone else joining
+  // here keeps the token it came with.
+  if (!token && isSecuredRoom(room)) useToken = hostToken(room, name, useToken, { kind: kind || 'ai', owner })
   // persist the token too, so a re-join from .hive.json keeps the grant (the
   // invitee pastes the link once; subsequent joins just read the folder config).
   // pinnedRelay SURVIVES the rewrite. This line used to write only relay/room/token, so a pin
@@ -333,7 +387,7 @@ was not written. Fix the relay and call hive_join again.`
     const who = [d.kind, d.owner ? `owner ${d.owner}` : '', d.app].filter(Boolean).join(', ')
     try { hive.stop() } catch { }
     session = null
-    try { fs.rmSync(SESSION_FILE) } catch { }
+    forgetSession()
     return [
       `NOT JOINED -- Q581: ${d.name} is already in this room (${who}), and two participants cannot share a name.`,
       'Everything here is keyed by name: you would each be told you hold the other\'s claims, read the',
@@ -444,10 +498,17 @@ was not written. Fix the relay and call hive_join again.`
   // What a person without an agent clicks. Pasting wss:// into a browser's address bar searches for it.
   const browserUrl = controlUrl(inviteLink)
   const ownControl = useToken ? controlUrl(`${relay}|${room}|${useToken}`) : ''
-  const tokenNote = useToken
-    ? `\nthis room checks tokens: each person joins with a token of their own. Mint one per person with npx -y -p hivecode-relay hivecode-token --name <them> --room "${room}" --role agent (add --paths to limit them) and send it to them directly. Never pass on yours: whoever holds it joins as you.` +
-      (ownControl ? `\nyour Control Room (carries YOUR token: open it yourself, never share it): ${ownControl}` : '')
-    : ''
+  // A PERSONAL ROOM (hs_ id) is let into by an invite from its host, and nothing else: the plain
+  // link below gets a stranger nothing, so it is not offered as the way in.
+  const personalRoom = isSecuredRoom(room)
+  const ownControlLine = ownControl ? `\nyour Control Room (carries YOUR token: open it yourself, never share it): ${ownControl}` : ''
+  const tokenNote = personalRoom
+    ? (loadRoomKey(room)
+      ? `\nPERSONAL ROOM: the relay lets in only people you invite, even on the public relay. It still carries the files, so for code that must never leave your machines, run your own relay. Invite one person at a time (each link works only for them): npx -y hivecode-mcp@latest invite <name> --dir "${ROOT}"  (add --reader, or --paths src,docs). Take one back: npx -y hivecode-mcp@latest revoke <name> --dir "${ROOT}"`
+      : `\nPERSONAL ROOM: only people its host invites can join. To bring someone in, ask the host for an invite of their own; never pass on yours.`) + ownControlLine
+    : useToken
+      ? `\nthis room checks tokens: each person joins with a token of their own. Mint one per person with npx -y -p hivecode-relay hivecode-token --name <them> --room "${room}" --role agent (add --paths to limit them) and send it to them directly. Never pass on yours: whoever holds it joins as you.` + ownControlLine
+      : ''
   // THE VERDICT, NOT JUST THE URL. `relay: wss://...` on its own is unreadable to anybody
   // who has not run a relay -- the public one and a company's own look identical. The
   // bracketed verdict is what makes "did my source just leave the building?" answerable
@@ -478,12 +539,13 @@ was not written. Fix the relay and call hive_join again.`
   // One line per thing a person acts on (the stranger walk, 3 Oct: as one line it pasted into chat
   // apps as a wall of links).
   const people = browserUrl ? `\n  No AI agent? Open ${browserUrl}` : ''
-  const invite = /^HOSTED/.test(mode)
-    ? `\nto invite someone, forward this as is:\n  Join my Hivecode room. In a terminal, run this once (needs Node.js 18+), then do what it prints:\n    npx -y hivecode-mcp@latest setup "${inviteLink}"${people}`
-    : (browserUrl ? `\nbrowser (people without an agent): ${browserUrl}` : '')
+  const invite = personalRoom ? ''
+    : /^HOSTED/.test(mode)
+      ? `\nto invite someone, forward this as is:\n  Join my Hivecode room. In a terminal, run this once (needs Node.js 18+), then do what it prints:\n    npx -y hivecode-mcp@latest setup "${inviteLink}"${people}`
+      : (browserUrl ? `\nbrowser (people without an agent): ${browserUrl}` : '')
   // No "announce your version" rule any more: since 29 Sep the room flags a mixed build itself
   // (sync.js checkBuilds), and the joiner is told here, by name, when one is already in the room.
-  return `${branchNote}${mode}\nroom: ${room}\nrelay: ${relay}  [${priv.headline}]\nfolder: ${ROOT}\nhivecode: ${VERSION_LABEL}\nothers here: ${others.join(', ') || 'none yet'}${mixedNote}\ninvite link: ${inviteLink}${tokenNote}${invite}${movedNote}${privNote}${updateNotice() ? '\n\n' + updateNotice() : ''}\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
+  return `${branchNote}${mode}\nroom: ${room}\nrelay: ${relay}  [${priv.headline}]\nfolder: ${ROOT}\nhivecode: ${VERSION_LABEL}\nothers here: ${others.join(', ') || 'none yet'}${mixedNote}\n${personalRoom ? 'room link (lets nobody in without an invite)' : 'invite link'}: ${inviteLink}${tokenNote}${invite}${movedNote}${privNote}${updateNotice() ? '\n\n' + updateNotice() : ''}\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
 }
 
 // A MIXED BUILD, TOLD TO THE ONE WHO CAN ACT ON IT (2 Oct 2026). The room's own warning names
@@ -705,7 +767,7 @@ function withheldNotice(s) {
 
 const TOOLS = [
   { name: 'hive_join', description: 'Join a Hivecode room, or host a new one, for a folder. Uses the join link if given, else <dir>/.hive.json, else hosts. Returns the room details and the rules you must follow.',
-    inputSchema: { type: 'object', properties: { link: { type: 'string', description: 'join link "wss://relay|room"' }, dir: { type: 'string', description: 'folder to sync; default ~/hivecode/<room>/<name>. Never share a folder with another participant.' }, name: { type: 'string', description: 'your display name in the room' }, owner: { type: 'string', description: 'the human who approves tasks aimed at you' }, token: { type: 'string', description: 'token for a secured room (default $HIVE_TOKEN)' }, kind: { type: 'string', description: '"ai" (default) or "human"' }, passive: { type: 'boolean', description: 'true = a listener or bot that never takes turns or answers' }, branch: { type: 'string', description: 'instead of link: the room bound to this git branch (npx -y hivecode-mcp@latest branch <name>)' }, repo: { type: 'string', description: 'the repo for branch (default: your working directory)' } } } },
+    inputSchema: { type: 'object', properties: { link: { type: 'string', description: 'join link "wss://relay|room"' }, dir: { type: 'string', description: 'folder to sync; default ~/hivecode/<room>/<name>. Never share a folder with another participant.' }, name: { type: 'string', description: 'your display name in the room' }, owner: { type: 'string', description: 'the human who approves tasks aimed at you' }, token: { type: 'string', description: 'token for a secured room (default $HIVE_TOKEN)' }, kind: { type: 'string', description: '"ai" (default) or "human"' }, passive: { type: 'boolean', description: 'true = a listener or bot that never takes turns or answers' }, branch: { type: 'string', description: 'instead of link: the room bound to this git branch (npx -y hivecode-mcp@latest branch <name>)' }, repo: { type: 'string', description: 'the repo for branch (default: your working directory)' }, private: { type: 'boolean', description: 'host a NEW room only people you invite can join' } } } },
   { name: 'hive_assign', description: 'Give a task to a participant by name. A task for an AI with an owner stays PENDING until that owner approves.',
     inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'participant name' }, text: { type: 'string', description: 'the task' } }, required: ['to', 'text'] } },
   { name: 'hive_read_tasks', description: 'Tasks aimed at you (act only on accepted ones) and all pending tasks awaiting approval.',
@@ -1674,6 +1736,7 @@ Nothing was written. This tool exists to guarantee the change syncs to every pee
           room: s.room, relay: s.relay, dir: s.dir, name: s.name, hivecode: VERSION, ...(BUILD ? { build: BUILD } : {}), ...(updateNotice() ? { update: updateNotice() } : {}),
           ...(clientName() ? { app: clientName() } : {}), // which agent app this is: support needs it, and so does waitPolicy
           privacy: pv.headline,
+          access: isSecuredRoom(s.room) ? (loadRoomKey(s.room) ? 'personal: invite only, and you host it (npx -y hivecode-mcp@latest invite <name>)' : 'personal: invite only') : 'open: anyone with the link can join',
           ...(pv.warn ? { privacyWarning: pv.warn } : {}),
           ...(pv.pin && pv.pin.pinned ? { relayPin: pv.pin.origins.join(', ') } : {}),
           unread: mailbox().peek(chatArray()).unreadCount,
@@ -1689,7 +1752,7 @@ Nothing was written. This tool exists to guarantee the change syncs to every pee
       // HIV-P11. A deliberate leave is the one departure the room KNOWS about, so the activity
       // row is dropped rather than left to read as GONE. GONE means "stopped without saying so",
       // and diluting it with agents that signed off correctly is how a signal stops being read.
-      case 'hive_leave': { try { ACT.forget(activityMap(), requireSession().name) } catch { }; requireSession().hive.stop(); session = null; try { fs.rmSync(SESSION_FILE) } catch {}; return text('left the room') }
+      case 'hive_leave': { try { ACT.forget(activityMap(), requireSession().name) } catch { }; requireSession().hive.stop(); session = null; forgetSession(); return text('left the room') }
       default: return err(`unknown tool: ${name}`)
     }
   } catch (e) { return err(`error: ${e.message}`) }
@@ -1863,6 +1926,28 @@ if (isEntryPoint && process.argv[2] === 'setup') {
   // `npx -y hivecode-mcp@latest branch <name>` binds a room to a git branch; `pr <name>` lands its work on it.
   // A CLI run like setup: nobody is speaking JSON-RPC to it, so it never opens stdio.
   process.exit(await HB.main(process.argv.slice(2)))
+} else if (isEntryPoint && (process.argv[2] === 'invite' || process.argv[2] === 'revoke')) {
+  // `invite <name>` makes one person's link into a personal room this machine hosts; `revoke <name>`
+  // takes it back. Commands rather than tools: see hive-room-key.js for why.
+  process.exit(await roomKeyMain(process.argv.slice(2)))
+} else if (isEntryPoint && (process.argv[2] === 'github' || process.argv[2] === 'notify' || process.argv[2] === 'slack')) {
+  // `github start|status`: issues labelled hivecode come back as pull requests (hive-github.js).
+  // `notify "<link>"`: a person hears on Slack or Discord when an agent is waiting on them
+  // (hive-notify.js). `slack start "<link>" --channel <id>` or `slack check --channel <id>`:
+  // threads per task in Slack and end-to-end setup check (hive-slack.js).
+  // `slack agent "<link>" --channel <id>`: Slack assistant panel and 1:1 DMs (hive-slack-agent.js).
+  // `slack mcp-server "<link>" --port <port>`: Streamable HTTP MCP server for Slackbot (hive-mcp-http.js).
+  if (process.argv[2] === 'slack' && process.argv[3] === 'agent') {
+    const mod = await import('./hive-slack-agent.js')
+    process.exit(await mod.main(process.argv.slice(4)))
+  } else if (process.argv[2] === 'slack' && process.argv[3] === 'mcp-server') {
+    const mod = await import('./hive-mcp-http.js')
+    process.exit(await mod.main(process.argv.slice(4)))
+  } else {
+    const modPath = process.argv[2] === 'github' ? './hive-github.js' : process.argv[2] === 'slack' ? './hive-slack.js' : './hive-notify.js'
+    const mod = await import(modPath)
+    process.exit(await mod.main(process.argv.slice(3)))
+  }
 } else if (isEntryPoint) {
   const transport = new StdioServerTransport()
   // STDIN CLOSING IS THE AGENT APP SAYING GOODBYE -- the MCP spec's stdio shutdown. Leave the

package/hive-notify.js

@@ -0,0 +1,233 @@
+// hive-notify -- tell a person, on Slack or Discord, when an agent in a room is waiting on them.
+//
+//   npx -y hivecode-mcp@latest notify "<link>" --webhook <url> --for <name>[,<name>] [--every <minutes>] [--title <text>]
+//
+// WHY. On 10 Oct 2026 a two-agent demo stalled for an hour: one agent waited for its person's OK,
+// the other waited for it, and the person was not looking at the chat. The room knew. Nobody was
+// told. An owner who leaves agents working has to hear about the two things only they can unblock:
+//
+//   - a task waiting for their approval        sent at once: an agent is stopped until they answer
+//   - messages from agents naming them          batched, at most one post per --every minutes
+//
+// Neither is sent while that person is in the room (the Control Room counts): they can see it.
+//
+// WHAT IS NEVER SENT: the room's link or full id. On an open relay the id is the key to the room's
+// files, and a Slack channel is not the place for a key. Messages name the room by --title, or by
+// the first characters of its id.
+//
+// IT MUST NOT LOOK ALIVE AND DELIVER NOTHING. It posts once when it starts and refuses to run if
+// that post fails; it says once when it has lost the room and once when it is back.
+//
+// Error codes Q640-Q649 are this module's.
+
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import crypto from 'crypto'
+import { startSync, parseLink } from './sync.js'
+import { makeNotifier, scrub } from './hive-webhook.js'
+
+const oneLine = (s, n = 200) => { const t = String(s || '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t }
+const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const LOST_AFTER = 5 * 60000
+
+/** Does `text` address `name` (@Name, not part of a longer word)? @all counts. */
+export function addresses(text, name) {
+  const t = String(text || '')
+  if (/(^|[^\w@])@all\b/i.test(t)) return true
+  return new RegExp(`(^|[^\\w@])@${esc(name)}(?![\\w-])`, 'i').test(t)
+}
+
+/** What has been sent, kept on disk so a restart does not send it again. */
+export function stateFileFor(room, home = os.homedir()) {
+  const h = crypto.createHash('sha256').update(String(room)).digest('hex').slice(0, 16)
+  return path.join(home, '.hivecode', 'notify', `${h}.json`)
+}
+export function lockFileFor(room, home = os.homedir()) {
+  const h = crypto.createHash('sha256').update(String(room)).digest('hex').slice(0, 16)
+  return path.join(home, '.hivecode', 'notify', `${h}.lock`)
+}
+const alive = (pid) => { try { process.kill(pid, 0); return true } catch (e) { return e.code === 'EPERM' } }
+
+/** One notifier per room. Created exclusively so two starting at the same time cannot double-post. */
+export function takeLock(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  for (let i = 0; i < 2; i++) {
+    try {
+      const fd = fs.openSync(file, 'wx')
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: new Date().toISOString() }))
+      fs.closeSync(fd)
+      return () => { try { if (JSON.parse(fs.readFileSync(file, 'utf8')).pid === process.pid) fs.unlinkSync(file) } catch { } }
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      let held = null
+      try { held = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { held = null }
+      if (held && held.pid && held.pid !== process.pid && alive(held.pid)) {
+        const err = new Error(`Q644 a notifier is already running for this room (process ${held.pid}, since ${held.at}). Use that one, or stop it first.`)
+        err.code = 'Q644'
+        throw err
+      }
+      try { fs.unlinkSync(file) } catch { }
+    }
+  }
+  const err = new Error(`Q644 could not take ${file}`)
+  err.code = 'Q644'
+  throw err
+}
+function loadSent(file) {
+  try { const j = JSON.parse(fs.readFileSync(file, 'utf8')); if (j && j.tasks) return j } catch { }
+  return { tasks: {} }
+}
+function saveSent(file, s) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const ids = Object.keys(s.tasks)
+    if (ids.length > 500) for (const id of ids.slice(0, ids.length - 500)) delete s.tasks[id]
+    fs.writeFileSync(file, JSON.stringify(s))
+  } catch { /* a notifier that cannot remember sends twice; it still sends */ }
+}
+
+/**
+ * The watching itself, on a live sync handle. `check()` is one pass; the CLI calls it on a timer,
+ * and tests call it with a clock of their own.
+ */
+export function makeWatch({ hive, forNames, title, send, now = () => Date.now(), every = 5, stateFile, log = () => {} }) {
+  const people = forNames.map((n) => String(n).trim()).filter(Boolean)
+  const lc = new Set(people.map((n) => n.toLowerCase()))
+  const tasks = hive.doc.getMap('tasks')
+  const owners = hive.doc.getMap('owners')
+  const chat = hive.doc.getArray('chat')
+  const sent = loadSent(stateFile)
+  let seenChat = chat.length // what was said before this started is not news
+  const buffer = []
+  let lastFlush = 0
+  let lostSince = 0
+  let toldLost = false
+
+  const here = (name) => (hive.members ? hive.members() : []).some((m) => String(m.name).toLowerCase() === name.toLowerCase() && m.kind === 'human')
+  const ownerOf = (t) => String(owners.get(t.to) || '')
+
+  function waiting() {
+    return [...tasks.values()].filter((t) => t && t.status === 'pending' && lc.has(ownerOf(t).toLowerCase()))
+  }
+
+  async function check() {
+    const t = now()
+    // THE CONNECTION. Lost for five minutes is said once; back is said once.
+    const connected = !!(hive.connection ? hive.connection().connected : hive.provider && hive.provider.wsconnected)
+    if (!connected) {
+      if (!lostSince) lostSince = t
+      if (!toldLost && t - lostSince >= LOST_AFTER) {
+        toldLost = true
+        await send(`Hivecode lost ${title} ${Math.round((t - lostSince) / 60000)} minutes ago, so nothing from it can reach you here. It keeps trying to reconnect.`)
+      }
+      return
+    }
+    if (lostSince) {
+      if (toldLost) await send(`Hivecode is back in ${title}.`)
+      lostSince = 0
+      toldLost = false
+    }
+
+    // A TASK WAITING FOR APPROVAL: at once, once per task.
+    for (const task of waiting()) {
+      const owner = ownerOf(task)
+      if (sent.tasks[task.id] || here(owner)) continue
+      const ok = await send(`Approval needed in ${title}: ${task.by} asked ${task.to} to "${oneLine(task.text, 300)}". ${task.to} waits until ${owner} approves or denies it in the Control Room.`)
+      if (ok) {
+        sent.tasks[task.id] = t
+        saveSent(stateFile, sent)
+      }
+    }
+
+    // MESSAGES NAMING THEM, from agents, while they are away: batched.
+    const all = chat.toArray()
+    if (all.length < seenChat) seenChat = 0 // the relay restarted and the room's history went with it
+    for (const m of all.slice(seenChat)) {
+      if (!m || m.kind !== 'ai') continue
+      for (const p of people) if (addresses(m.text, p) && !here(p)) { buffer.push({ by: m.by, to: p, text: m.text }); break }
+    }
+    seenChat = all.length
+    if (buffer.length && t - lastFlush >= every * 60000) {
+      const shown = buffer.slice()
+      const to = [...new Set(shown.map((b) => b.to))].join(', ')
+      const lines = shown.slice(0, 5).map((b) => `- ${b.by}: ${oneLine(b.text, 220)}`)
+      if (shown.length > 5) lines.push(`- and ${shown.length - 5} more`)
+      const ok = await send(`${shown.length} message${shown.length === 1 ? '' : 's'} for ${to} in ${title}:\n${lines.join('\n')}`)
+      if (ok) {
+        buffer.splice(0, shown.length)
+        lastFlush = t
+      }
+    }
+  }
+
+  return { check, waiting, buffered: () => buffer.length, sent }
+}
+
+// ---- CLI -------------------------------------------------------------------------------------------
+
+const USAGE = `usage:
+  npx -y hivecode-mcp@latest notify "<link>" --webhook <Slack or Discord webhook URL> --for <name>[,<name>]
+
+  --for <names>     whose approvals and mentions to send (the people, not their agents)
+  --every <min>     at most one post of messages per this many minutes (default 5)
+  --title <text>    what to call the room in posts (default: the first characters of its id)
+  --name <name>     the notifier's own name in the room (default Notifier)`
+
+export async function main(argv, { log = console.log, logErr = console.error, fetchImpl = globalThis.fetch, home = os.homedir(), now = () => Date.now(), once = false } = {}) {
+  if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') { log(USAGE); return 0 }
+  const SWITCHES = new Set(['dry-run', 'once'])
+  const pos = []
+  const f = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      const k = a.slice(2)
+      if (SWITCHES.has(k)) f[k] = true
+      else f[k] = argv[++i] ?? ''
+    } else {
+      pos.push(a)
+    }
+  }
+  const link = pos[0] || ''
+  const { relay, room, token } = parseLink(link)
+  if (!relay || !room) { logErr(`Q640 "${link}" is not a room link (it looks like wss://relay|room-...).\n\n${USAGE}`); return 2 }
+  if (!f.webhook) { logErr(`Q641 say where to post, with --webhook <Slack or Discord incoming-webhook URL>.\n\n${USAGE}`); return 2 }
+  const forNames = String(f.for || '').split(',').map((s) => s.trim()).filter(Boolean)
+  if (!forNames.length) { logErr(`Q642 say whose waits to report, with --for <name> (the person, as they appear in the room).\n\n${USAGE}`); return 2 }
+  const every = Number(f.every || 5)
+  if (!(every > 0)) { logErr('Q642 --every must be a positive number of minutes'); return 2 }
+  const title = f.title ? oneLine(f.title, 60) : `room ${room.slice(0, 8)}…`
+  const send = makeNotifier(f.webhook, { fetchImpl, log })
+
+  // FIRST, PROVE THE WEBHOOK WORKS. A notifier whose posts go nowhere is worse than none: the person
+  // believes they will be told.
+  if (send.kind === 'other' && send.host) log(`posting in Slack format to ${send.host}`)
+  const okSent = await send(`Hivecode will post here when an agent in ${title} is waiting on ${forNames.join(', ')}.`)
+  if (!okSent) { logErr('Q643 the webhook refused the first post (see above). Check the URL, then start again. Nothing is running.'); return 1 }
+
+  const lockFile = lockFileFor(room, home)
+  const releaseLock = (() => { try { return takeLock(lockFile) } catch (e) { logErr(e.message); return null } })()
+  if (!releaseLock) return 2
+
+  const dir = path.join(home, '.hivecode', 'notify', `room-${crypto.createHash('sha256').update(room).digest('hex').slice(0, 12)}`)
+  const hive = startSync({ relay, room, dir, name: f.name || 'Notifier', kind: 'ai', token: token || process.env.HIVE_TOKEN || '', syncFiles: false, passive: true, log: () => { } })
+  const w = makeWatch({ hive, forNames, title, send, now, every, stateFile: stateFileFor(room, home), log })
+  let synced = false
+  await new Promise((res) => { const t = setTimeout(res, 15000); hive.provider.on('sync', (s) => { if (s) { synced = true; clearTimeout(t); res() } }) })
+  if (!synced && !(hive.provider && hive.provider.wsconnected)) {
+    logErr(`NOTE: could not connect to relay at ${relay}. The room may be unreachable or the network down.`)
+  }
+  const members = (hive.members() || []).filter((m) => m.name !== (f.name || 'Notifier')).map((m) => `${m.name} (${m.kind})`)
+  const pending = w.waiting().length
+  log(`watching ${title}: ${members.length ? members.join(', ') : 'nobody here yet'}; ${pending} approval(s) waiting now. Ctrl+C stops it.`)
+  if (!members.length && !hive.doc.getArray('chat').length) log('NOTE: this room is empty -- no members and no chat. Is the link right?')
+  if (once || f['dry-run']) { await w.check(); hive.stop(); releaseLock(); return 0 }
+  const timer = setInterval(() => { w.check().catch((e) => log(`check failed: ${e.message}`)) }, 15000)
+  const quit = () => { clearInterval(timer); try { hive.stop() } catch { } try { releaseLock() } catch { } process.exit(0) }
+  process.on('SIGINT', quit)
+  process.on('SIGTERM', quit)
+  await w.check()
+  return new Promise(() => { }) // runs until stopped
+}
+

package/hive-pr.js

@@ -37,6 +37,7 @@ import { spawnSync } from 'child_process'
 import { fileURLToPath } from 'url'
 import { startSync, parseLink } from './sync.js'
 import { accountFor, verdict, explain, DIVERGED } from './hive-pr-staleness.js'
+import { contentHash } from './substrate.js'
 
 const argv = process.argv.slice(2)
 const [LINK = '', NAME = 'hive-pr'] = argv.filter((a) => !a.startsWith('--'))
@@ -76,12 +77,22 @@ function gitRaw(args, opts = {}) {
 
 /** The authors of a file, newest-landed first, from VERIFIED receipts only.
  *  An unverifiable receipt is not evidence of authorship, so it is dropped rather than trusted. */
-export function authorsOf(receipts, verify) {
+// `roomText`, when given: the author of what the room HOLDS, not of the newest receipt. After a
+// control-room revert the room holds an older version, restored without a receipt, so "newest" named
+// the reverted agent as the author of the code it had just been reverted out of (antigravity-3, 1 Nov).
+export function authorsOf(receipts, verify, roomText) {
   const ok = receipts.filter((r) => r && r.author && (!verify || verify(r)))
   if (!ok.length) return { last: null, contributors: [], first: 0 }
-  const last = ok[ok.length - 1]
+  // Receipts newer than the one the room holds are work that was reverted out: not co-authors either.
+  // Content no receipt matches (a merge, or a revert to a merged state) keeps the old rule, newest
+  // lander, a known limit until merged states are stamped into the ledger (antigravity-3, 1 Nov).
+  const want = typeof roomText === 'string' ? contentHash(roomText) : null
+  let idx = -1
+  if (want) for (let i = ok.length - 1; i >= 0; i--) if (ok[i].contentHash === want) { idx = i; break }
+  const held = idx >= 0 ? ok.slice(0, idx + 1) : ok
+  const last = held[held.length - 1]
   const seen = new Map()
-  for (const r of ok) if (!seen.has(r.author)) seen.set(r.author, { author: r.author, name: r.name || 'agent', at: r.at || 0 })
+  for (const r of held) if (!seen.has(r.author)) seen.set(r.author, { author: r.author, name: r.name || 'agent', at: r.at || 0 })
   return {
     last: { author: last.author, name: last.name || 'agent', at: last.at || 0 },
     contributors: [...seen.values()],
@@ -206,7 +217,9 @@ if (isMain) {
       const receipts = hive.provenanceOf(rel) || []
       const audit = hive.verifyProvenanceOf(rel) || { bad: [] }
       const badIdx = new Set((audit.bad || []).map((b) => b.i))
-      const a = authorsOf(receipts, (r) => !badIdx.has(receipts.indexOf(r)))
+      let roomText = null
+      try { roomText = fs.readFileSync(path.join(dir, rel), 'utf8') } catch { }
+      const a = authorsOf(receipts, (r) => !badIdx.has(receipts.indexOf(r)), roomText)
       files.push({ rel, abs: path.join(dir, rel), ...a })
     }