hivecode-mcp 0.11.5 → 0.11.6

package/hive-mcp.js

@@ -34,12 +34,30 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 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 { createMailbox, formatMessage, mentionsName, mentionedNames, priorityOf, ambientDigest } from './hive-mailbox.js'
+import { createMailbox, formatMessage, mentionsName, mentionedNames, mentionsAll, unansweredFor, priorityOf, ambientDigest, validateMemberName } from './hive-mailbox.js'
+import { INSTRUCTIONS } from './hive-instructions.js'
+import { makeBusy, isBusy, describeRecipient } from './hive-busy.js'
+import * as OB from './hive-obligations.js'
+import * as RC from './hive-receipts.js'
+import { makeThrottle, RULES_NUDGE } from './hive-throttle.js'
 
 const DEFAULT_RELAY = process.env.HIVE_RELAY || 'wss://livecode-xoss.onrender.com'
 let session = null // { hive, room, relay, dir, name, mailbox }
 
-const text = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s, null, 2) }] })
+// ONE THROTTLE PER SERVER PROCESS, which is one agent. It deliberately does NOT live on the
+// session: a rejoin does not empty the agent's context, so resetting the throttle there would
+// re-send everything the agent can still see -- the exact waste this removes.
+const throttle = makeThrottle()
+
+const text = (s) => {
+  const body = typeof s === 'string' ? s : JSON.stringify(s, null, 2)
+  // THE METER. Every tool result leaves through here, so this count is exact rather than
+  // sampled -- it is the local equivalent of the PTY output bytes Agent Relay's broker measures,
+  // and it is the only evidence available that an agent has done enough since it last saw a
+  // block for that block to have been compacted away.
+  try { throttle.note(body.length) } catch { /* the meter must never break a tool result */ }
+  return { content: [{ type: 'text', text: body }] }
+}
 const err = (s) => ({ content: [{ type: 'text', text: s }], isError: true })
 
 function resolveRoom(link, dir) {
@@ -69,6 +87,12 @@ function readSessionFile() {
 function persistCursor() {
   if (!session || !session.mailbox) return
   persistSession({ dir: session.dir, name: session.name, owner: session.owner, cursor: session.mailbox.cursor })
+  // AND PUBLISH IT INTO THE ROOM. The file above is for resuming THIS session; the room copy is
+  // what makes "did they actually read it" answerable by anybody other than me. The cursor only
+  // advances inside box.take(), which is the call that hands messages to the agent -- so a cursor
+  // past a message is the one honest piece of evidence this system has that the message reached
+  // somebody's context. Before this, that evidence existed and was thrown away on disk.
+  try { RC.publishCursor(session.hive.doc.getMap('cursors'), session.name, session.mailbox.cursor) } catch { /* a room that predates receipts */ }
 }
 async function tryResumeSession() {
   try {
@@ -79,6 +103,17 @@ async function tryResumeSession() {
 }
 
 async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor }) {
+  // 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.
+  const nameCheck = validateMemberName(name)
+  if (!nameCheck.ok) {
+    return `${nameCheck.error}
+
+Nothing was joined and your current session is untouched. Re-run hive_join with name: "${nameCheck.suggested}".
+
+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.`
+  }
   if (session) { try { session.hive.stop() } catch {} ; session = null }
   const ROOT = path.resolve(dir)
   fs.mkdirSync(ROOT, { recursive: true })
@@ -110,13 +145,52 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
   }
   session = { hive, room, relay, dir, name, owner, mailbox: null }
   persistSession({ dir, name, owner }) // survive MCP host restarts (see tryResumeSession)
-  // wait for the first sync so members/board/rules are ready
+  // Wait for the first sync so members/board/rules are ready.
+  //
+  // REPORT THE TRUTH ABOUT THIS. Until 18 Sep 2026 the timeout below simply resolved and the
+  // caller returned a cheerful "joined" banner whether or not the relay had accepted us. On a
+  // relay at capacity that is a false success report: the agent is told it is in a room, reads
+  // the rules, claims files and writes code, and NONE of it reaches anybody. It happened for
+  // real -- a relay answered 38,011 connections with Q430 while three agents believed they were
+  // collaborating. An agent cannot detect this on its own; the only honest place to catch it is
+  // here, at the moment we know whether the socket came up.
+  let synced = false
+  let connErr = ''
   await new Promise((resolve) => {
     let done = false
     const finish = () => { if (!done) { done = true; resolve() } }
-    hive.provider.on('sync', (s) => s && finish())
+    hive.provider.on('sync', (s) => { if (s) { synced = true; finish() } })
+    // A refusal arrives as a failed upgrade: the relay writes an HTTP status line carrying the
+    // Q-code and destroys the socket, so this event is the only place the reason is visible.
+    hive.provider.on('connection-error', (ev) => {
+      const code = ev && (ev.code || ev.status || ev.type)
+      if (!connErr) connErr = `the relay refused the connection${code ? ` (${code})` : ''}`
+    })
     setTimeout(finish, 8000) // don't hang if the relay is cold
   })
+  if (!synced) {
+    const why = connErr || 'no sync within 8s -- the relay did not answer'
+    return [
+      `NOT JOINED -- ${why}.`,
+      `room: ${room}`,
+      `relay: ${relay}`,
+      `folder: ${ROOT}`,
+      '',
+      'DO NOT START WORK. You are not in this room. Nothing you write will reach anyone, no',
+      'claim you make binds anyone else, and the files in this folder are NOT shared. Any work',
+      'you do now is invisible to the team and can be silently overwritten later.',
+      '',
+      'Most likely causes, in the order worth checking:',
+      '  - the relay is at capacity (Q430). Hivecode opens one socket PER FILE, so a large',
+      '    folder can exhaust it by itself. Check <relay-http>/health: connections vs',
+      '    limits.maxConnsTotal. Raise HIVE_MAX_CONNS_TOTAL, or narrow what syncs via .gitignore.',
+      '  - the relay is not running, or the port/room in the link is wrong.',
+      '  - the room is secured and this link carries no token (Q4xx on connect).',
+      '',
+      'Tell whoever is running the relay, then retry hive_join. Call hive_status to re-check:',
+      'it reports `connected` and `filesSynced`, and both are authoritative.',
+    ].join('\n')
+  }
   // The mailbox is created AFTER the first sync, so chat.length is the real room history and
   // not 0 — otherwise a fresh joiner would be handed the entire backlog as unread mail.
   // A resumed session carries its saved cursor forward instead, so anything posted while this
@@ -130,8 +204,18 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
 
   // Event-Driven Wakeups: notify the MCP client the millisecond the DCO state changes
   hive.doc.getMap('swarm_state').observe(() => {
+    // SAME DEFECT AS THE MAIL DOORBELL BELOW, AND FOUND THE SAME WAY -- a test crashed inside a
+    // Yjs observer with the stack pointing at a `try` that looked like it had the case covered.
+    // `notification()` is async: a failure is a REJECTED PROMISE, which sails past this catch,
+    // becomes an unhandled rejection and takes the whole agent down.
+    //
+    // Worth recording that the first fix only repaired the copy in the chat observer. This one
+    // survived untouched for another two tickets and then crashed a second test -- which is the
+    // duplicated-wire-contract lesson arriving in person: repair the CLASS, not the instance.
+    // Both call sites are now the same shape, deliberately.
     try {
-      server.notification({ method: 'notifications/hive_state_changed', params: { state: hive.getState() } })
+      Promise.resolve(server.notification({ method: 'notifications/hive_state_changed', params: { state: hive.getState() } }))
+        .catch(() => { /* no transport, or a client that does not take notifications */ })
     } catch (e) {
       // client might not support notifications, swallow error
     }
@@ -164,7 +248,17 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
       // 0, and a later single mention must still ring. `>` would go permanently silent.
       if (!m.mentioned || m.mentions.length === lastMailSignal) return
       lastMailSignal = m.mentions.length
-      server.notification({
+      // THE CATCH BELOW DOES NOT COVER THIS CALL. `notification()` is async, so a failure inside
+      // it is a REJECTED PROMISE, not a thrown exception -- it sails past the surrounding
+      // try/catch, becomes an unhandled rejection, and takes the whole agent down. Observed
+      // 19 Sep 2026: a second agent posting chat to a server whose transport was not connected
+      // crashed the process from inside this Yjs observer, with the stack pointing at a `try`
+      // that looked like it had the case covered.
+      //
+      // A doorbell that can kill the agent is strictly worse than no doorbell -- and this one is
+      // already optional by design (custom MCP notifications are ignorable by spec), so the right
+      // behaviour on any failure is silence.
+      Promise.resolve(server.notification({
         method: 'notifications/hive_mail',
         params: {
           mentioned: true,
@@ -174,7 +268,7 @@ async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto
           latest: formatMessage(m.mentions[m.mentions.length - 1] || {}),
           hint: 'call hive_wait or hive_check to read it — this notification consumed nothing',
         },
-      })
+      })).catch(() => { /* no transport, or a client that does not take notifications */ })
     } catch (e) {
       // client might not support notifications, swallow error
     }
@@ -196,10 +290,21 @@ function requireSession() { if (!session) throw new Error('not in a room — cal
 /** The read cursor for this participant. Lazily built if a session predates it. */
 function mailbox() {
   const s = requireSession()
+  // hive_join has just handed over the full HIVE_RULES.md, so the nudge would be pure noise on
+  // the next wait. Marking it sent here is what makes the join and the reminder one mechanism
+  // rather than two that disagree.
+  try { throttle.sent('rules', RULES_NUDGE) } catch { }
   if (!s.mailbox) s.mailbox = createMailbox({ me: s.name, startAt: s.hive.doc.getArray('chat').length })
   return s.mailbox
 }
 function chatArray() { return requireSession().hive.doc.getArray('chat').toArray() }
+// Names are matched case-insensitively everywhere else (mentionsName is /i), so a busy lookup
+// keyed on the exact string would silently miss whenever a sender typed @sam for Sam.
+function findBusy(map, name) {
+  const want = String(name || '').toLowerCase()
+  for (const [k, v] of map.entries()) if (String(k).toLowerCase() === want) return v
+  return null
+}
 function boardMap() { const b = requireSession().hive.doc.getMap('board'); return [...b.entries()].map(([file, e]) => ({ file, ...e })) }
 function taskList() { return [...requireSession().hive.doc.getMap('tasks').values()] }
 const fmtTask = (t) => `${t.id} [${t.status}] ${t.by} -> ${t.to}: ${t.text}${t.decidedBy ? ` (by ${t.decidedBy})` : ''}`
@@ -207,6 +312,32 @@ const fmtTask = (t) => `${t.id} [${t.status}] ${t.by} -> ${t.to}: ${t.text}${t.d
 // Block until there is approved work for me (or a new chat message), then return.
 // This is how the agent reacts the INSTANT the owner approves — no polling loop,
 // no interval to tune. Resolves immediately if approved work already exists.
+/** WAKE ON STATE — the predicate that lets a roster run itself.
+ *
+ *  Without this, hive_wait only returns on work assigned TO you or a message naming you, so every
+ *  multi-agent roster silently depends on agents remembering to @ each other after each step. The
+ *  rules ASK them to (sync.js: "block on hive_wait until your specific state flag turns
+ *  APPROVED/READY") and nothing MAKES them, so a night roster stalls with no error: the reviewer
+ *  is asleep, the tests went green an hour ago, and nobody said so.
+ *
+ *  Shapes, all on one state key:
+ *     { key: 'tests', is: 'GREEN' }            exactly this value
+ *     { key: 'tests', in: ['GREEN', 'SKIP'] }  any of these
+ *     { key: 'tests', not: 'RED' }             anything except this (INCLUDING unset)
+ *     { key: 'tests' }                         any value at all, i.e. the key exists
+ *
+ *  `not` deliberately matches an unset key. A reviewer told "wake unless the build is RED" should
+ *  wake on a fresh room where nobody has set `build` yet -- treating absent as RED would hang it
+ *  forever waiting for a flag no one is going to write. */
+export function stateMatches(until, get) {
+  if (!until || !until.key) return false
+  const v = get(until.key)
+  if (Object.prototype.hasOwnProperty.call(until, 'is')) return String(v) === String(until.is)
+  if (Array.isArray(until.in)) return until.in.some((x) => String(x) === String(v))
+  if (Object.prototype.hasOwnProperty.call(until, 'not')) return String(v) !== String(until.not)
+  return v !== undefined && v !== null
+}
+
 function waitForWork(timeoutMs, opts = {}) {
   const s = requireSession()
   const tmap = s.hive.doc.getMap('tasks')
@@ -251,6 +382,13 @@ function waitForWork(timeoutMs, opts = {}) {
   }
   // Queued work no longer hides the mail. This returned `newChat: []` outright, which made
   // the busiest agent in the room the one guaranteed to see no messages at all.
+  // A state the caller is waiting for, checked BEFORE anything blocks: if it is already true the
+  // agent must not sit through a timeout waiting to be told something that happened an hour ago.
+  const state = s.hive.doc.getMap('swarm_state')
+  const until = opts.until && opts.until.key ? opts.until : null
+  const stateHit = () => stateMatches(until, (k) => state.get(k))
+  if (until && stateHit()) return Promise.resolve(deliver({ tasks: accepted(), stateReached: { ...until, value: state.get(until.key) } }))
+
   const ready = accepted()
   if (ready.length) return Promise.resolve(deliver({ tasks: ready }))
   // Anything already unread is handed over immediately rather than waited past — that backlog
@@ -261,7 +399,7 @@ function waitForWork(timeoutMs, opts = {}) {
   }
   return new Promise((resolve) => {
     let done = false
-    const finish = (v) => { if (!done) { done = true; tmap.unobserve(onTask); chat.unobserve(onChat); controls.unobserve(onCtl); resolve(v) } }
+    const finish = (v) => { if (!done) { done = true; tmap.unobserve(onTask); chat.unobserve(onChat); controls.unobserve(onCtl); if (until) { try { state.unobserve(onState) } catch { /* never observed */ } } resolve(v) } }
     const onTask = () => { const a = accepted(); if (a.length) finish(deliver({ tasks: a })) }
     const onChat = () => {
       const seen = box.peek(chat.toArray())
@@ -270,7 +408,11 @@ function waitForWork(timeoutMs, opts = {}) {
       finish(deliver({ tasks: accepted() }))
     }
     const onCtl = () => { if (paused()) finish({ paused: true }) } // paused mid-wait -> stop handing out work
-    tmap.observe(onTask); chat.observe(onChat); controls.observe(onCtl)
+    // A paused agent is NOT woken by state: pausing means stop picking up work, and a state flag
+    // turning green is the room offering it work. It re-checks the predicate on its next wait
+    // after a human resumes it.
+    const onState = () => { if (until && !paused() && stateHit()) finish(deliver({ tasks: accepted(), stateReached: { ...until, value: state.get(until.key) } })) }
+    tmap.observe(onTask); chat.observe(onChat); controls.observe(onCtl); if (until) state.observe(onState)
     // On timeout, flush anything that arrived rather than dropping it: a message must never
     // expire unread just because the wait window closed on it.
     setTimeout(() => finish(box.hasUnread(chat.toArray()) ? deliver({ tasks: accepted() }) : null), timeoutMs)
@@ -284,8 +426,8 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'participant name to assign to' }, text: { type: 'string', description: 'what to do' } }, required: ['to', 'text'] } },
   { name: 'hive_read_tasks', description: 'Read tasks. Shows tasks directed at YOU (act only on accepted ones) and all pending tasks awaiting approval.',
     inputSchema: { type: 'object', properties: {} } },
-  { name: 'hive_wait', description: 'BLOCK until there is approved work for you, or unread mail arrives, then return BOTH. Use this as your main loop: call hive_wait; do the work; hive_complete; call hive_wait again. Returns instantly if approved work or unread mail already exists — nothing addressed to you can be missed while you were busy, because your read position is remembered between calls.',
-    inputSchema: { type: 'object', properties: { timeoutSeconds: { type: 'number', description: 'max seconds to wait (default 60, max 300)' }, wakeOn: { type: 'string', enum: ['any', 'mention'], description: "'any' (default) wakes on any new message; 'mention' only wakes when you are @mentioned or assigned a task — use it in a noisy room. Ambient messages are still delivered on the next wake either way, never dropped." } } } },
+  { name: 'hive_wait', description: 'BLOCK until there is approved work for you, unread mail arrives, or a project-state flag you named reaches the value you are waiting for — then return all of it. Use this as your main loop: call hive_wait; do the work; hive_complete; call hive_wait again. Returns instantly if any of those is ALREADY true, so nothing that happened while you were busy can be missed. Pass `until` to wait on the state machine instead of on somebody remembering to message you — that is how a roster runs itself overnight: the tester sets tests=GREEN, and the reviewer waiting on it wakes by itself.',
+    inputSchema: { type: 'object', properties: { timeoutSeconds: { type: 'number', description: 'max seconds to wait (default 60, max 300)' }, wakeOn: { type: 'string', enum: ['any', 'mention'], description: "'any' (default) wakes on any new message; 'mention' only wakes when you are @mentioned or assigned a task — use it in a noisy room. Ambient messages are still delivered on the next wake either way, never dropped." }, until: { type: 'object', description: 'wake when a GLOBAL PROJECT STATE key reaches a value. { key, is } for one exact value, { key, in: [...] } for any of several, { key, not } for anything else (an unset key counts as "not"), or { key } alone for "as soon as this is set at all". The result carries stateReached with the value that fired.', properties: { key: { type: 'string' }, is: { type: 'string' }, in: { type: 'array', items: { type: 'string' } }, not: { type: 'string' } }, required: ['key'] } } } },
   { name: 'hive_check', description: 'NON-BLOCKING: is anyone calling me? Returns unread messages addressed to you, plus approved work, and returns immediately. Call this between edits during a long task — that is the whole point: hive_wait blocks, so it cannot be used while you are working, and this can. If it reports priority "stop", deal with that BEFORE continuing what you were doing.',
     inputSchema: { type: 'object', properties: { peek: { type: 'boolean', description: 'true = look without marking messages read (default false: reading them here counts as read)' } } } },
   { name: 'hive_approve', description: 'Approve a pending task (you must be the owner of the target AI). The AI may then act on it.',
@@ -294,16 +436,28 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
   { name: 'hive_complete', description: 'Mark a task you were doing as done (optionally with a note).',
     inputSchema: { type: 'object', properties: { id: { type: 'string' }, note: { type: 'string' } }, required: ['id'] } },
-  { name: 'hive_say', description: 'Post a coordination message to the room chat. Use this to announce what you are about to work on BEFORE editing (e.g. "taking auth.js: adding login"). Address someone directly with @Name — that is what makes it land as mail rather than ambient chatter. Set urgent:true when you need them to stop what they are doing.',
-    inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'the message' }, urgent: { type: 'boolean', description: 'true = prefix [!] so the recipient treats it as "handle before continuing", not "read at your next boundary"' } }, required: ['text'] } },
+  { name: 'hive_say', description: 'Post a coordination message to the room chat. Use this to announce what you are about to work on BEFORE editing (e.g. "taking auth.js: adding login"). Address someone directly with @Name — that is what makes it land as mail rather than ambient chatter. Set urgent:true when you need them to stop what they are doing. Set needsReply:true when you are ASKING something — the room then tracks that you are owed an answer, and tells you if you addressed somebody who is not here.',
+    inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'the message' }, urgent: { type: 'boolean', description: 'true = prefix [!] so the recipient treats it as "handle before continuing", not "read at your next boundary"' }, needsReply: { type: 'boolean', description: 'true = this is a QUESTION and you are owed an answer. Records an obligation against everyone you named. It stays open until YOU call hive_answered -- the person you asked cannot close it, and answering is not closing. If you named someone who is not in the room you are told so immediately, instead of waiting forever.' }, replyWithinMinutes: { type: 'number', description: 'how long before you are reminded (default 10). The reminder arrives on a hive_wait you were going to make anyway, so it costs nothing.' } }, required: ['text'] } },
+  { name: 'hive_delivered', description: 'Did anyone actually READ what you said? "sent" only means the message entered your local copy. This reports, per recipient: READ (their read position passed it — real evidence), UNREAD (they are here and behind), UNKNOWN (they publish no read position, e.g. a bridge or a human client — so their silence means NOTHING either way), UNREACHABLE (they left, or you are offline). Read it before concluding an agent is ignoring you, and before believing a handoff landed.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'how many of your recent addressed messages to check (default 10)' } } } },
+  { name: 'hive_answered', description: 'Close a question YOU asked with needsReply — you are saying you got what you needed. Only the asker can call this: the agent you asked cannot mark its own answer sufficient, and a reply alone does not close anything. Pass id for one, or from:"Name" to close everything you asked that agent.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'the obligation id from hive_say or hive_owed' }, from: { type: 'string', description: 'close every open question you asked this agent' } } } },
+  { name: 'hive_owed', description: 'Who owes an answer to whom, and for how long. Read this when the room has gone quiet: an agent that stopped replying looks exactly like an agent that is thinking, and this is the difference. Shows questions aimed at YOU (answer these) and questions you asked (close these with hive_answered). Anything marked STALE has been reminded three times and is now the room\'s problem, not one agent\'s.',
+    inputSchema: { type: 'object', properties: { all: { type: 'boolean', description: 'true = the whole room, not just yours' } } } },
+  { name: 'hive_busy', description: 'Tell the room you are mid-task, so anyone who @mentions you is told to expect a delay AT THE MOMENT THEY SEND, instead of waiting on a reply that is not coming yet. This posts no message and silences nothing — you still receive mail and must still call hive_check between edits. It expires by itself, so a crash cannot leave you permanently "busy". Clear it when you finish.',
+    inputSchema: { type: 'object', properties: { what: { type: 'string', description: 'what you are working on, in a few words — the sender reads this' }, minutes: { type: 'number', description: 'how long to hold it (default 10). It expires on its own either way.' }, clear: { type: 'boolean', description: 'true = I am free again' } } } },
   { name: 'hive_read_chat', description: 'Read the room conversation. Read this to see what humans and other agents are doing before and while you work. Use mentioningMe to recover only what was addressed to you.',
     inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'how many recent messages (default 30)' }, mentioningMe: { type: 'boolean', description: 'true = only messages that @mention you, across the whole room history — use this to recover your own backlog' }, unreadOnly: { type: 'boolean', description: 'true = only what you have not been handed yet (does not mark it read)' } } } },
   { name: 'hive_read_board', description: 'Read recent whole-file rewrites (who rewrote what, which symbols). Read this before editing a file — if it was just rewritten, re-read the file first.',
     inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_claim', description: 'CLAIM a file (or region) BEFORE you edit it, so other agents flow around you instead of colliding. Returns whether you got it — if false, someone else holds it: work on something else. Claims auto-expire, so call hive_release when done (or it frees itself).',
     inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'the file path (or region id) you want to edit' }, intent: { type: 'string', description: 'short note on what you intend to do' } }, required: ['region'] } },
-  { name: 'hive_release', description: 'Release a file/region you claimed, so other agents can take it. Call this when you finish editing it.',
-    inputSchema: { type: 'object', properties: { region: { type: 'string', description: 'the file path (or region id) to release' } }, required: ['region'] } },
+  { name: 'hive_release', description: 'Hand a file back so other agents can take it. If the room has set a gate, this RUNS it in your folder first and a failing check REFUSES the handoff — you keep the file, nobody else can take it, and retrying will not help. Fix what the gate reported, or pass force with a reason if you are abandoning the work (recorded against your name and announced).',
+    inputSchema: { type: 'object', properties: {
+      region: { type: 'string', description: 'the file path (or region id) to release' },
+      force: { type: 'boolean', description: 'release even though the gate failed. Recorded against your name in the room and posted to chat — use it for abandoned work, never to get past a failing check.' },
+      why: { type: 'string', description: 'why the work is being abandoned. Give this whenever force is true; a forced release with no reason is recorded as exactly that.' },
+    }, required: ['region'] } },
   { name: 'hive_claims', description: 'See what every agent is currently working on (the live claim board). Read this to pick open work and avoid taken regions.',
     inputSchema: { type: 'object', properties: {} } },
   { name: 'hive_edit', description: 'Write a file THROUGH the medium (preferred over editing on disk): your intent and exact change are cryptographically stamped into the provenance ledger at the instant of writing — race-free — then merged and synced like any edit. Claim the file first with hive_claim; pass your intent here too so the WHY travels with the change.',
@@ -439,7 +593,15 @@ export const VERSION = (() => {
   } catch { /* fall through */ }
   return '0.0.0-unknown'
 })()
-const server = new Server({ name: 'hivecode', version: VERSION }, { capabilities: { tools: {} } })
+// `instructions` is placed in the agent's SYSTEM PROMPT by the client at connect time, which
+// makes it the only channel that reaches an agent before its first tool call. Everything else we
+// have -- tool descriptions, the HIVE_RULES returned by hive_join -- is read too late or scrolls
+// away, and the rule that matters most (hive_wait is your idle state; ending your turn makes you
+// unreachable) is exactly the one an agent needs up front. See hive-instructions.js.
+const server = new Server(
+  { name: 'hivecode', version: VERSION },
+  { capabilities: { tools: {} }, instructions: INSTRUCTIONS },
+)
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 async function dispatch(req) {
   const { name, arguments: args = {} } = req.params
@@ -452,6 +614,14 @@ async function dispatch(req) {
     switch (name) {
       case 'hive_join': return text(await joinRoom(args))
       case 'hive_say': {
+        // THE CONNECTION IS CHECKED BEFORE ANYTHING ELSE. Until today this tool reported
+        // "sent to @Builder: ..." with the socket down, which is a false success in the most
+        // literal sense: the bytes are in a local Yjs doc, the relay has never seen them, and the
+        // word the agent reads is the same word it reads on success. status().connected was
+        // right there and free the whole time.
+        const sendConn = (() => { try { return requireSession().hive.status() } catch { return null } })()
+        const sendWarn = RC.sendWarning({ connected: !sendConn || !!sendConn.connected })
+        const stamp = (t) => (sendWarn ? `${sendWarn}\n\n${t}` : t)
         const raw = String(args.text || '')
         // The marker is in the text itself so it survives into HIVE_CHAT.md and is visible to
         // a human reading the log, not just to the recipient's tool output.
@@ -463,12 +633,85 @@ async function dispatch(req) {
         // Immediate, per-call feedback, at the moment the mistake is made.
         const named = mentionedNames(body)
         if (!named.length) {
-          return text(`sent: ${body}\n\nNOBODY WAS ADDRESSED. This went to every agent's "room ` +
+          return text(stamp(`sent: ${body}`) + `\n\nNOBODY WAS ADDRESSED. This went to every agent's "room ` +
             `activity", where they are told to skip it — so assume no one acts on it. Name the ` +
             `agents you actually need with @Name (hive_members lists who is here). Use an ` +
             `unaddressed message only for a genuine announcement to the whole room.`)
         }
-        return text(`sent to ${named.map((n) => '@' + n).join(', ')}: ${body}`)
+        // WHO IS ACTUALLY GOING TO READ THIS. The sender is the only participant who can act on
+        // "they left" or "they are mid-task", and it is worth strictly more here than in a
+        // reply: it arrives before the sender starts waiting, and it costs the room no message.
+        // This is the whole reason busy is state rather than an auto-reply (see hive-busy.js).
+        const s = requireSession()
+        const present = new Set(s.hive.members().map((m) => String(m.name).toLowerCase()))
+        const busyMap = s.hive.doc.getMap('busy')
+        const notes = named
+          .filter((n) => n.toLowerCase() !== 'all' && n.toLowerCase() !== s.name.toLowerCase())
+          .map((n) => describeRecipient(n, findBusy(busyMap, n), present.has(n.toLowerCase())))
+          .filter(Boolean)
+        const to = mentionsAll(body) ? 'the whole room (@all)' : named.map((n) => '@' + n).join(', ')
+        // NEEDS REPLY. A question is recorded, not just spoken. One obligation per agent named,
+        // and `absent` is stamped NOW -- because "was anyone even there when I asked" is a fact
+        // about the past, and recomputing it later would let a question asked into an empty room
+        // start looking fine the moment somebody walks in. This is the 19 Sep 2026 failure
+        // exactly: one message to @Reviewer, who had never been in the room, then six hours of
+        // silence that no tool, log or process reported.
+        let obStr = ''
+        if (args.needsReply) {
+          const obMap = s.hive.doc.getMap('obligations')
+          // Floor in MILLISECONDS, not minutes. `Math.max(1, mins)` silently turned a caller's
+          // 0.05 into 1 -- a clamp that changes what was asked for and says nothing, which is the
+          // same shape as every other defect on this project. One second is enough to stop a
+          // zero-or-negative busy loop, and everything above it is honoured as written.
+          const dueMs = Math.max(1000, (Number(args.replyWithinMinutes) || 10) * 60000)
+          const targets = mentionsAll(body)
+            ? s.hive.members().map((m) => String(m.name)).filter((n) => n.toLowerCase() !== s.name.toLowerCase())
+            : named.filter((n) => n.toLowerCase() !== 'all' && n.toLowerCase() !== s.name.toLowerCase())
+          // PRESENCE AND PROVENANCE ARE DIFFERENT FACTS AND THEY DECIDE DIFFERENT THINGS.
+          // `absent` decides the WARNING: nobody by that name is connected right now, so say so
+          // at once. `neverSeen` decides the LIFETIME: nobody by that name has ever joined or
+          // spoken here, so this is noise rather than a teammate who stepped out.
+          // Conflating them would expire a real debt: on 20 Sep an obligation against
+          // @DeepMind-Agent was stamped absent because it had dropped between turns, and it came
+          // back ninety minutes later and answered. A ten-minute timer would have deleted it, and
+          // the ledger would have been at its cleanest exactly while an agent was silent.
+          const everHere = new Set([...present])
+          for (const m of s.hive.doc.getArray('chat').toArray()) {
+            if (m && m.by) everHere.add(String(m.by).toLowerCase())
+          }
+          const opened = targets.map((n) => OB.open(obMap, {
+            from: s.name, to: n, text: body, dueMs,
+            absent: !present.has(n.toLowerCase()),
+            neverSeen: !everHere.has(n.toLowerCase()),
+          }))
+          if (opened.length) {
+            obStr = `\n\nYOU ARE OWED AN ANSWER — ${opened.map((o) => `${o.id} (${o.to})`).join(', ')}\n` +
+              `This stays open until YOU call hive_answered. The agent you asked cannot close it, and ` +
+              `a reply does not close it either — you decide whether you were actually answered. If it ` +
+              `is still open in ${Math.round(dueMs / 60000)} min you will be reminded on your next hive_wait.`
+            const ghosts = opened.filter((o) => o.absent)
+            if (ghosts.length) {
+              obStr += `\n\n⚠ ${ghosts.map((o) => '@' + o.to).join(', ')} — NOT IN THIS ROOM. Nobody by that ` +
+                `name is here, so nobody is going to answer. Call hive_members and re-address it now; ` +
+                `this is the one failure mode that otherwise costs you a whole shift.`
+            }
+          }
+        }
+        return text(stamp(`sent to ${to}: ${body}`) + (notes.length ? '\n\n' + notes.join('\n') : '') + obStr)
+      }
+      case 'hive_busy': {
+        const s = requireSession()
+        const busyMap = s.hive.doc.getMap('busy')
+        if (args.clear) { busyMap.delete(s.name); return text('busy cleared — the room will expect normal replies from you again') }
+        const e = makeBusy(args.what, { ttl: args.minutes ? args.minutes * 60000 : undefined })
+        busyMap.set(s.name, e)
+        // Say what it does NOT do, because an agent that believes this silences its mail will
+        // stop calling hive_check and go deaf on purpose.
+        return text(`marked busy: ${e.what}\n\nThis posts no message and silences nothing — you still ` +
+          `receive mail and must still call hive_check between edits. It only tells anyone who ` +
+          `@mentions you, at the moment they send, that you are mid-task. It expires by itself in ` +
+          `${Math.round(e.ttl / 60000)} minutes, so a crash cannot leave the room believing you are ` +
+          `permanently busy. Call hive_busy with clear:true when you finish.`)
       }
       case 'hive_read_chat': {
         const me = requireSession().name
@@ -496,7 +739,22 @@ async function dispatch(req) {
         const got = args.peek ? box.peek(all) : box.take(all)
         if (!args.peek) persistCursor()
         const tasks = [...s.hive.doc.getMap('tasks').values()].filter((t) => t.to === s.name && t.status === 'accepted')
-        if (!got.unreadCount && !tasks.length) return text('✓ nothing waiting — nobody is calling you and you have no approved work. Carry on.')
+        // WHO IS STILL WAITING ON YOU. Read mail is not answered mail: the cursor advances the
+        // moment a message is handed over, so an agent can absorb a direct question, get busy,
+        // and never notice it left someone hanging -- which is the failure that made a previous
+        // room's PM give up on this channel and tail the chat file with a shell script instead.
+        // Derived from the log, so it needs no state and cannot drift.
+        const owed = unansweredFor(all, s.name)
+        const owedLine = owed.length
+          ? `\n\n⏳ STILL WAITING ON A REPLY FROM YOU: ${owed.map((o) => '@' + o.from).join(', ')}. ` +
+            `Answer with hive_say (name them), even if the answer is "not yet, I am on X" — ` +
+            `silence is the one thing they cannot act on.`
+          : ''
+        if (!got.unreadCount && !tasks.length) {
+          return text(owed.length
+            ? `✓ no new mail and no approved work.${owedLine}`
+            : '✓ nothing waiting — nobody is calling you and you have no approved work. Carry on.')
+        }
         const parts = []
         if (got.priority === 'stop') {
           // HANDLING URGENT MAIL COUNTS AS LIVENESS.
@@ -529,7 +787,7 @@ async function dispatch(req) {
         const dig = ambientDigest(ambient)
         if (dig) parts.push(dig)
         if (tasks.length) parts.push(`approved work queued for you:\n${tasks.map(fmtTask).join('\n')}`)
-        return text(parts.join('\n\n'))
+        return text(parts.join('\n\n') + owedLine)
       }
       case 'hive_read_board': { const b = boardMap(); return text(b.length ? b.map((e) => `${e.at} ${e.by} rewrote ${e.file} (${e.churn}) — touched: ${(e.symbols || []).join(', ')}`).join('\n') : '(no rewrites logged)') }
       case 'hive_assign': { enforceDcoLock(); const id = requireSession().hive.assign(String(args.to || ''), String(args.text || '')); return id ? text(`assigned task ${id} to ${args.to} (pending approval if they have an owner)`) : err('need to and text') }
@@ -541,9 +799,23 @@ async function dispatch(req) {
       }
       case 'hive_wait': {
         const ms = Math.min(Math.max(Number(args.timeoutSeconds) || 60, 1), 300) * 1000
-        const r = await waitForWork(ms, { wakeOn: args.wakeOn })
+        const r = await waitForWork(ms, { wakeOn: args.wakeOn, until: args.until })
         const globalState = requireSession().hive.getState()
-        const stateStr = Object.keys(globalState).length ? `\n[GLOBAL PROJECT STATE]\n${JSON.stringify(globalState, null, 2)}\n` : ''
+        // THE STATE BLOCK WAS RETURNED ON EVERY SINGLE WAIT, unchanged, forever -- an agent
+        // sitting in the night-shift loop was handed the same JSON hundreds of times and paid for
+        // it each time. It is now sent when the agent has not seen it, when it CHANGED (which
+        // always wins: a suppressed state change is a wrong answer, not a saving), or when enough
+        // time AND enough output have passed that it is probably no longer in context.
+        const stateBody = Object.keys(globalState).length ? `\n[GLOBAL PROJECT STATE]\n${JSON.stringify(globalState, null, 2)}\n` : ''
+        const stateStr = stateBody && throttle.send('state', stateBody) ? stateBody : ''
+        // The room rules went the other way: 6 KB handed over ONCE in the hive_join result, where
+        // compaction reaches them first. They are the ROOM-specific half -- lanes, gate command,
+        // ownership -- so the general rules in the system prompt do not cover them. A pointer is
+        // re-sent, never a copy: the file is on this agent's own disk, and a second summary here
+        // would be one more description to drift out of date.
+        const rulesStr = throttle.should('rules', RULES_NUDGE).why === 'likely-compacted'
+          ? (throttle.sent('rules', RULES_NUDGE), `\n${RULES_NUDGE}\n`)
+          : ''
         // Connection state, reported ONLY when it is bad. An agent that cannot tell a
         // quiet room from a dead socket reaches for hive_join -- which calls stop() and
         // tears the session down, turning a blip that would have healed itself into a
@@ -558,6 +830,25 @@ async function dispatch(req) {
           : ''
         
         const me = requireSession().name
+        // THE KNOCK RIDES THE WAIT. hive_wait is the agent's idle state and a blocked wait costs
+        // zero tokens, so a reminder delivered here arrives on a call that was going to happen
+        // anyway. Agent Relay re-injects its boomerang on a broker timer, which spends a turn on
+        // every knock; this spends nothing. The reminder is deliberately NOT sent to a paused
+        // agent -- paused means stop, and nagging a stopped agent is just noise.
+        const obMap = (() => { try { return requireSession().hive.doc.getMap('obligations') } catch { return null } })()
+        let owedStr = ''
+        if (obMap) {
+          const due = OB.overdue(obMap, me)
+          if (due.length) {
+            // Only a DELIVERED knock moves the deadline. If merely NOTICING an overdue record
+            // rescheduled it, an agent that never calls hive_wait would have its deadline pushed
+            // out forever by whoever happened to read the board -- exactly backwards.
+            for (const o of due) OB.knock(obMap, o.id)
+            owedStr = `\n[YOU OWE ${due.length} ANSWER(S)] These were asked of you and are still open. ` +
+              `Answer in chat with @Name — you cannot close them yourself, the asker does that.\n` +
+              due.map((o) => '  ' + OB.describe(o)).join('\n') + '\n'
+          }
+        }
         // Direct address is separated from ambient traffic on every path. It used to be that
         // only a PAUSED agent got this distinction, so a working agent could not tell "stop,
         // wrong file" from two other agents talking to each other.
@@ -577,13 +868,67 @@ async function dispatch(req) {
           }
           return text(`⏸ You are PAUSED by mission control. Stop new work and wait. You will be woken if someone @mentions you or assigns you a task; otherwise just call hive_wait again.${stateStr}`)
         }
-        if (!r) return text(`(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)${connStr}${stateStr}`)
+        if (!r) return text(`(nothing yet — no approved work or new messages in the wait window. Call hive_wait again to keep waiting.)${owedStr}${connStr}${stateStr}${rulesStr}`)
         const parts = []
         if (r.resumed) parts.push('▶ You were RESUMED by mission control — continue.')
         const mb = mentionBlock(r); if (mb) parts.push(mb)
         if (r.tasks.length) parts.push(`APPROVED WORK — do these now, then hive_complete each:\n${r.tasks.map(fmtTask).join('\n')}`)
         const ab = ambientBlock(r); if (ab) parts.push(ab)
-        return text(`${connStr}${stateStr}\n` + (parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)'))
+        return text(`${owedStr}${connStr}${stateStr}${rulesStr}\n` + (parts.join('\n\n') || '(resumed — no queued work yet. Call hive_wait again.)'))
+      }
+      case 'hive_delivered': {
+        const s2 = requireSession()
+        const conn = (() => { try { return s2.hive.status() } catch { return null } })()
+        const connected = !conn || !!conn.connected
+        const here = new Set(s2.hive.members().map((m) => String(m.name).toLowerCase()))
+        const rs = RC.receipts({
+          chat: s2.hive.doc.getArray('chat').toArray(),
+          cursors: s2.hive.doc.getMap('cursors'),
+          me: s2.name,
+          present: (n) => here.has(String(n).toLowerCase()),
+          connected,
+          limit: Math.min(Math.max(Number(args.limit) || 10, 1), 50),
+        })
+        if (!rs.length) return text('You have not addressed anyone recently, so there is nothing to confirm. (Unaddressed and @all messages are not tracked — nobody promised to read those.)')
+        const states = rs.flatMap((r) => r.to)
+        const read = RC.countDelivered(states)
+        const unknown = states.filter((x) => x.state === RC.UNKNOWN).length
+        // The headline deliberately reports READ over TOTAL and names UNKNOWN separately rather
+        // than folding it in. Summing "not proven undelivered" into the good number is how a
+        // receipt system starts reassuring instead of measuring.
+        const head = `${read}/${states.length} confirmed READ` +
+          (unknown ? ` — ${unknown} UNKNOWN (no read position published; that is an absence of evidence, not evidence of delivery)` : '')
+        const worst = states.filter((x) => x.state !== RC.READ)
+        return text(`${head}\n\n` + rs.map((r) => '  ' + RC.describe(r)).join('\n') +
+          (worst.length ? '\n\n' + [...new Set(worst.map((x) => `${x.name}: ${x.why}`))].join('\n') : ''))
+      }
+      case 'hive_answered': {
+        const s2 = requireSession()
+        const obMap = s2.hive.doc.getMap('obligations')
+        if (args.from) {
+          const closed = OB.dischargeFrom(obMap, { by: s2.name, to: String(args.from) })
+          if (!closed.length) return text(`Nothing open that you asked @${args.from}. hive_owed shows what is.`)
+          return text(`Closed ${closed.length} question(s) you asked @${args.from}:\n` + closed.map((o) => '  ' + o.text).join('\n'))
+        }
+        if (!args.id) return err('hive_answered needs either id (one question) or from (everything you asked one agent). hive_owed lists both.')
+        const r2 = OB.discharge(obMap, { id: String(args.id), by: s2.name })
+        if (!r2.ok) return err(r2.reason)
+        return text(r2.already ? `${args.id} was already closed.` : `Closed ${args.id}: "${r2.rec.text}"`)
+      }
+      case 'hive_owed': {
+        const s2 = requireSession()
+        const obMap = s2.hive.doc.getMap('obligations')
+        if (args.all) {
+          const b = OB.board(obMap)
+          if (!b.open) return text('Nothing outstanding in this room.')
+          return text(`${b.open} open, ${b.stale} stale:\n` + b.lines.map((l) => '  ' + l).join('\n'))
+        }
+        const mine = OB.owedBy(obMap, s2.name), theirs = OB.owedTo(obMap, s2.name)
+        if (!mine.length && !theirs.length) return text('You owe nothing and are owed nothing. (Pass all:true for the whole room.)')
+        const parts = []
+        if (mine.length) parts.push(`YOU OWE ${mine.length} ANSWER(S) — answer in chat with @Name; the asker closes it:\n` + mine.map((o) => '  ' + OB.describe(o)).join('\n'))
+        if (theirs.length) parts.push(`YOU ARE OWED ${theirs.length} — close with hive_answered once you actually have what you needed:\n` + theirs.map((o) => '  ' + OB.describe(o)).join('\n'))
+        return text(parts.join('\n\n'))
       }
       case 'hive_set_state': { requireSession().hive.setState(String(args.key), String(args.val)); return text(`Set global state [${args.key}] to [${args.val}]`) }
       case 'hive_read_state': { return text(requireSession().hive.getState()) }
@@ -601,9 +946,29 @@ async function dispatch(req) {
       case 'hive_verified': {
         const f = String(args.file || ''); if (!f) return err('need a file path')
         const r = requireSession().hive.verified(f)
-        if (!r.count) return text(`${f}: NOT attested by anyone. Unverified — measure it and call hive_attest.`)
+        // Attestation and gate verdicts are independent records, so an unattested path must still
+        // report its gate. Returning early here would hide a FAILED check behind "nobody measured
+        // the bytes", which is the opposite of what this tool is for.
+        if (!r.count) {
+          const g0 = requireSession().hive.gateVerdicts(f)
+          const extra = Object.entries(g0).map(([n, v]) => v.forced
+            ? `\n  [!] ${n} FORCE-released it without passing the gate${v.why ? ` — "${v.why}"` : ''}`
+            : `\n  ${v.pass ? '[ok]' : '[!]'} ${n}'s gate ${v.pass ? 'passed' : `FAILED (exit ${v.exit})`}`).join('')
+          return text(`${f}: NOT attested by anyone. Unverified — measure it and call hive_attest.${extra}`)
+        }
         const who = Object.entries(r.peers).map(([n, v]) => `${n}: ${v.bytes} bytes / ${v.lines} lines at ${v.at}`).join('\n  ')
-        return text(`${f}\n  ${who}\n\n${r.diverged ? '[!] DIVERGED — peers hold different bytes. Do not write or build on this path.' : r.quorum ? 'QUORUM: confirmed by 2+ peers at the same size.' : 'Attested by ONE peer only — not yet proof.'}`)
+        // Same bytes in two folders says the file PROPAGATED. It says nothing about whether it
+        // WORKS, which is the actual question an agent is asking here — so the gate verdicts
+        // belong in this answer. A file two peers agree on and whose owner's tests failed is the
+        // exact thing somebody is about to build on.
+        const g = requireSession().hive.gateVerdicts(f)
+        const gLines = Object.entries(g).map(([n, v]) => v.forced
+          ? `  [!] ${n} FORCE-released it without passing the gate${v.why ? ` — "${v.why}"` : ' and gave no reason'}`
+          : `  ${v.pass ? '[ok]' : '[!]'} ${n}'s gate ${v.pass ? 'passed' : `FAILED (exit ${v.exit})`}: ${v.cmd}`)
+        const gate = gLines.length
+          ? `\n\nCHECKS RUN BY THE AGENTS THAT HELD IT:\n${gLines.join('\n')}${Object.values(g).some((v) => !v.pass) ? '\n  Somebody handed this back knowing it did not pass. Read it before you build on it.' : ''}`
+          : '\n\nNo gate verdict recorded for this path — nobody has run a check on it here.'
+        return text(`${f}\n  ${who}\n\n${r.diverged ? '[!] DIVERGED — peers hold different bytes. Do not write or build on this path.' : r.quorum ? 'QUORUM: confirmed by 2+ peers at the same size.' : 'Attested by ONE peer only — not yet proof.'}${gate}`)
       }
       case 'hive_approve': { const r = requireSession().hive.decide(String(args.id), true); return r.ok ? text(`approved ${args.id}`) : err(r.error) }
       case 'hive_deny': { const r = requireSession().hive.decide(String(args.id), false); return r.ok ? text(`denied ${args.id}`) : err(r.error) }
@@ -614,18 +979,52 @@ async function dispatch(req) {
         // always a mistake, and refusing here is far cheaper than refusing after the agent has
         // built the content it intended to write.
         enforceDcoLock({ path: region });
-        const got = requireSession().hive.claim(region, String(args.intent || 'edit'))
+        // HIV-27: A CLAIM YOU CANNOT PUBLISH IS NOT A CLAIM. The claim is a path string in the
+        // shared map; whether that path's BYTES sync is decided separately, per client. Nothing
+        // compared them, so an agent could hold an exclusive claim on a file nobody else can
+        // see, do the work, pass a gate running in its own folder where the file is real, and
+        // hand back something that never existed for anyone else -- every signal green.
+        // Refused HERE rather than at release: by release time the work is already built and
+        // all we could do is tell the agent it was wasted.
+        const unshared = requireSession().hive.whyNotShared(region)
+        if (unshared) {
+          return err(`refusing to claim ${region} — ${unshared}
+
+Nothing was claimed. Put the path inside the room's sync scope, or pick one that is already in it, BEFORE you start work: a claim whose bytes never leave this folder is indistinguishable from one that works.`)
+        }
+        // SETTLED, not optimistic. The synchronous claim answers from this replica alone and
+        // tells three simultaneous callers "it's yours" (measured 5/5). An agent then edits
+        // behind a lock it does not hold. This waits for the relay to serialise it.
+        const got = await requireSession().hive.claimSettled(region, String(args.intent || 'edit'))
         if (got) return text(`claimed ${region} — it's yours. Edit it, then call hive_release.`)
         const c = requireSession().hive.senseClaim(region)
         return text(`could NOT claim ${region}${c ? ` — held by ${c.by}${c.intent ? ` (${c.intent})` : ''}` : ''}. Work on something else; check hive_claims for open files.`)
       }
-      case 'hive_release': { const region = String(args.region || ''); if (!region) return err('need a region'); requireSession().hive.release(region); return text(`released ${region}`) }
+      case 'hive_release': {
+        const region = String(args.region || '')
+        if (!region) return err('need a region')
+        // A gated release can REFUSE, and reporting "released" either way is the worst thing this
+        // could do: the agent moves on believing it handed the file back while it still holds it.
+        const r = requireSession().hive.release(region, { force: !!args.force, why: String(args.why || '') })
+        if (r && r.ok === false) return text(r.message)
+        if (r && r.forced) return text(`released ${region} WITHOUT passing the gate — recorded against your name in the room`)
+        return text(`released ${region}${r && r.gated ? ' (gate passed)' : ''}`)
+      }
       case 'hive_claims': { const b = requireSession().hive.claimsBoard(); return text(b.length ? b.map((c) => `${c.region} — ${c.by}${c.intent ? ` (${c.intent})` : ''}`).join('\n') : '(nothing claimed right now — all open)') }
       case 'hive_edit': {
         const editPath = String(args.file || '')
         // Path gate + lease consumed BEFORE the write, not after: a spent lease that still wrote is
         // indistinguishable from no lease at all.
         enforceDcoLock({ consumes: true, path: editPath })
+        // HIV-27, same reasoning: this tool's entire promise is that the change reaches every
+        // peer. On a path this client never opens a connection for, it would not -- and it
+        // would still report success.
+        const unshared = requireSession().hive.whyNotShared(editPath)
+        if (unshared) {
+          return err(`refusing to write ${editPath} through the medium — ${unshared}
+
+Nothing was written. This tool exists to guarantee the change syncs to every peer; on this path it cannot.`)
+        }
         const r = requireSession().hive.edit(editPath, String(args.content ?? ''), String(args.intent || ''))
         if (r.error) return err(r.error)
         return text(r.conflicted
@@ -741,7 +1140,44 @@ function mailBanner() {
   } catch { return '' }
 }
 
+// A MISSING REQUIRED ARGUMENT MUST BE REFUSED, NOT WRITTEN AS `undefined`.
+//
+// Nothing was validating `inputSchema.required`. The SDK does not enforce it, and every handler
+// read its arguments straight off the object, so a near-miss parameter name sailed through as
+// `undefined` and the tool reported success. Two real cases, both on 18 Sep 2026:
+//   hive_say({ message })    -> posted an EMPTY message and answered "sent: "
+//   hive_set_state({ value }) -> answered "Set global state [gate:cmd] to [undefined]", which
+//                                overwrote the room's gate command with the string "undefined"
+//                                and would have broken the handoff gate for every agent.
+// The failure mode is what makes it serious: the agent is told the action happened. It moves on,
+// and the room is left holding a corrupted value nobody wrote on purpose. Near-miss names are
+// the common case, so the refusal names the unknown argument that was supplied too.
+function missingRequired(req) {
+  const name = req && req.params && req.params.name
+  const tool = TOOLS.find((t) => t.name === name)
+  const schema = tool && tool.inputSchema
+  const required = schema && Array.isArray(schema.required) ? schema.required : []
+  if (!required.length) return ''
+  const args = (req.params && req.params.arguments) || {}
+  // undefined/null only: '' and 0 and false are legitimate values a caller may mean.
+  const missing = required.filter((k) => args[k] === undefined || args[k] === null)
+  if (!missing.length) return ''
+  const known = Object.keys(schema.properties || {})
+  const unknown = Object.keys(args).filter((k) => !known.includes(k))
+  const lines = [
+    `REFUSED -- ${name} needs ${missing.map((m) => `\`${m}\``).join(', ')} and it was not supplied.`,
+    `Nothing was written. This call did NOT happen.`,
+  ]
+  if (unknown.length) {
+    lines.push(`You passed ${unknown.map((u) => `\`${u}\``).join(', ')}, which ${name} does not take -- most likely you meant ${missing.map((m) => `\`${m}\``).join(', ')}.`)
+  }
+  lines.push(`${name} accepts: ${known.map((k) => (required.includes(k) ? `${k} (required)` : k)).join(', ')}.`)
+  return lines.join('\n')
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const bad = missingRequired(req)
+  if (bad) return { content: [{ type: 'text', text: bad }], isError: true }
   const res = await dispatch(req)
   // Never let the banner break a tool: append only to a well-formed text result, and skip the two
   // tools that already deliver mail themselves (appending would double-report the same messages).
@@ -771,6 +1207,10 @@ if (isEntryPoint) {
 export const _test = {
   waitForWork,
   mailbox,
+  // Exposed so the throttle's saving is asserted against the counter itself rather than inferred
+  // from what happened not to appear in a tool result. Counting absences is how you prove a thing
+  // is quiet, not how you prove it is working.
+  throttleStats: () => throttle.stats(),
   setSession(s) { session = s },
   getSession() { return session },
   callTool: (name, args = {}) =>