hivecode-mcp 0.11.5 → 0.12.0

package/hive-busy.js

@@ -0,0 +1,88 @@
+// SELF-DECLARED BUSY: "I am mid-task, do not expect an answer this second."
+//
+// WHY THIS IS STATE AND NOT A MESSAGE. The obvious design is an auto-reply: someone @s you
+// while you are working, you post "busy, will get back to you". Eight agents and one broadcast
+// is eight of those, each of which is itself a message in the room; if the acknowledgements are
+// addressed they wake the sender, who is also busy, who acknowledges back. That is a spam
+// channel with extra steps, and this room has already been through it once -- a conflict
+// notification loop put 56 copies of one line into chat and 306 of 2,314 lines were that loop.
+//
+// So nobody announces anything. The busy agent sets a flag and keeps working, and the
+// INFORMATION IS HANDED TO THE SENDER AT SEND TIME instead: hive_say reports the recipient's
+// state in its own return value. Same fact, delivered faster than a reply could arrive, and it
+// adds zero messages to the room. The interrupted agent is never made to interrupt itself in
+// order to be polite.
+//
+// The `controls` map is deliberately not reused. That is mission control -- a HUMAN sets
+// running/paused there -- and an agent writing its own state into the same entry would clobber
+// a human's pause with a self-report. Different author, different authority, different map.
+//
+// TTL, for the same reason claims have one: an agent that dies mid-task must not leave a
+// permanent "busy" flag behind that quietly teaches the whole room to stop talking to it. A
+// stale flag is worse than no flag, because everyone believes it.
+
+/** Default life of a busy flag. Long enough for real work, short enough that a crash clears. */
+export const DEFAULT_TTL = 10 * 60 * 1000
+
+/**
+ * The ceiling, and it is the load-bearing one.
+ *
+ * The whole point of a TTL here is that a crashed agent cannot leave the room believing it is
+ * permanently busy. Without a cap, `ttl: Infinity` -- or a caller passing milliseconds where it
+ * meant minutes -- reinstates exactly the failure the TTL exists to prevent, and it fails
+ * silently: everyone simply stops expecting an answer, forever, and nothing looks broken.
+ *
+ * An hour is past the point where "busy" is still true. Beyond that the agent is stuck, and the
+ * room is better off treating it as free and finding out.
+ */
+export const MAX_TTL = 60 * 60 * 1000
+
+/** An entry as stored: { what, since, ttl }. `since` is unix ms, matching hive-coord's claims. */
+
+/** Live, or expired/absent? Pure, so the TTL is testable on a virtual clock. */
+export function isBusy(entry, now = Date.now()) {
+  if (!entry || typeof entry !== 'object') return false
+  const since = Number(entry.since) || 0
+  // Clamped on READ as well as on write, and this is the side that matters: the entry arrives
+  // over the wire from another client, which may be an older build, a different version, or
+  // simply wrong. Trusting a ttl we did not create is how one peer gets to pin the whole room.
+  const ttl = Math.min(MAX_TTL, Math.max(1000, Number(entry.ttl) || DEFAULT_TTL))
+  return since > 0 && now - since < ttl
+}
+
+/** Build an entry. `what` is free text -- what they are doing, for the sender to read. */
+export function makeBusy(what, { ttl = DEFAULT_TTL, now = Date.now() } = {}) {
+  // Clamped at BOTH ends. 0/NaN/absent falls back to the default; anything above the ceiling is
+  // brought down to it, so no caller -- and no bad arithmetic in a caller -- can mint a flag
+  // that outlives the work it describes.
+  const want = Number(ttl) || DEFAULT_TTL
+  return { what: String(what || 'working').slice(0, 200), since: now, ttl: Math.min(MAX_TTL, Math.max(1000, want)) }
+}
+
+/** How long they have been at it, in words a sender can act on. */
+export function busyFor(entry, now = Date.now()) {
+  const ms = Math.max(0, now - (Number(entry && entry.since) || now))
+  const s = Math.round(ms / 1000)
+  if (s < 90) return s + 's'
+  const m = Math.round(s / 60)
+  return m < 90 ? m + 'm' : Math.round(m / 60) + 'h'
+}
+
+/**
+ * The line hive_say hands back to a sender about one recipient.
+ *
+ * Returns '' when there is nothing worth saying, so callers can drop it with a falsy check --
+ * silence is the right output for "they are here and free", which is the common case and does
+ * not need a sentence.
+ *
+ * @param {string} name        the recipient
+ * @param {object|null} entry  their busy entry, if any
+ * @param {boolean} present    are they actually in the room right now
+ */
+export function describeRecipient(name, entry, present, now = Date.now()) {
+  // ABSENCE OUTRANKS BUSY, and it is the more useful of the two: a message to someone who left
+  // is not delayed, it is unread forever, and the sender is the only one who can notice.
+  if (!present) return `@${name} is NOT in the room — nobody will read that. hive_members lists who is here.`
+  if (isBusy(entry, now)) return `@${name} has been busy ${busyFor(entry, now)} (${entry.what}) — expect a delay, they are not idle waiting on you.`
+  return ''
+}

package/hive-coord.js

@@ -63,9 +63,20 @@ export function makeCoordinator(shared, self, opts = {}) {
   }
   const release = (region) => { const c = shared.get(region); if (c && c.by === self) shared.delete(region) }
 
-  // ACQUIRE one region: sense → claim → verify. Returns true iff I now hold it.
-  // The verify step is the collision-detector: if a concurrent writer won the region,
-  // I see their id on re-read and concede.
+  // ACQUIRE one region: sense → claim → verify. Returns true iff I now hold it *as far as this
+  // replica can tell*, which is a weaker statement than it looks and the caller must know it.
+  //
+  // THE VERIFY IS LOCAL, AND THAT IS ITS LIMIT. `claim()` writes into this replica's copy of the
+  // map and the re-read below sees that write immediately -- before it has reached the relay or
+  // any peer. So the check catches only a claim that had ALREADY propagated when I wrote. Fire
+  // three agents at one region in the same tick and all three are told yes; the CRDT then
+  // converges to a single winner a moment later, by which time all three have started editing.
+  // Measured 5/5 trials, three agents, every one of them granted.
+  //
+  // That is not a bug in this function -- a synchronous call cannot wait for a network -- but a
+  // lock that says yes to three callers is not a lock, so anything that is about to WRITE must
+  // use `claimSettled()` in sync.js, which re-reads the holder after the claim has round-tripped
+  // through the relay. This stays as the optimistic fast path for sensing and for flow.
   const acquire = (region, intent) => {
     const c = shared.get(region)
     if (c && !expired(c) && c.by !== self) return false // sensed an owner → defer

package/hive-gate.js

@@ -0,0 +1,135 @@
+// hive-gate — a handoff that cannot complete while your own check is failing.
+//
+// THE PROBLEM THIS EXISTS FOR. Claims stop two agents writing the same file. They say nothing
+// about whether what you wrote is CORRECT, so the honest description of the room until now was:
+// agent A writes something wrong, releases it, agent B picks it up and builds on it, and the lock
+// made the corruption orderly rather than absent. Ganesh put it exactly right -- "one agent makes
+// a mistake and writes wrong code, others build upon it and it gets worse".
+//
+// The answer is the same move that solved collisions, applied one layer up. Collisions were not
+// solved by asking agents to coordinate; the transport refuses the second write. Correctness is
+// not solved by asking agents to check each other's work either. The transport refuses the
+// HANDOFF: release runs the room's check, and a failing check means the claim stays yours.
+//
+// WHAT THIS HONESTLY DOES AND DOES NOT DO. It does not stop the bad content existing in other
+// folders -- the CRDT syncs continuously, so the bytes are already everywhere the moment they are
+// written, and nothing short of abandoning live sync changes that. What it stops is the SILENT
+// HANDOFF: "I am done, it is yours." The file stays visibly held, by a named agent, with a
+// recorded reason. Anyone who reaches for it is told who is holding it and that their check
+// failed, rather than quietly inheriting a broken file that looked finished.
+//
+// AND THE RULE THAT SHAPES THE WHOLE DESIGN. @Claude-Engine caught a real bug in the path-state
+// registry: `path:engine/brain/llm.js = POISONED` was FALSE in its folder, where that path held
+// the correct file while another folder held a wreck. Marking it globally broadcast ONE FOLDER'S
+// REALITY as room truth. A gate result is exactly that kind of fact -- I ran the tests in MY
+// folder, on MY copy -- so it is recorded PER AGENT, keyed by name the way hive_attest is, and it
+// never sets a global path flag. Two agents disagreeing about whether a file passes stays visible
+// as a disagreement instead of converging on whoever wrote last.
+
+import { spawnSync } from 'child_process'
+
+export const GATE_CMD = 'gate:cmd'          // the room's check, in shared state
+export const GATE_TIMEOUT = 'gate:timeout'  // ms; a hung test suite must not wedge the room
+export const DEFAULT_TIMEOUT_MS = 120000
+export const MAX_OUTPUT = 4000              // what we keep of the output, for the record
+
+/**
+ * The room's gate, read from shared state. `get` is any (key) => value — the swarm_state map, or
+ * a plain object in tests.
+ *
+ * Returns null when no gate is configured, which means release behaves exactly as it always has.
+ * That is deliberate: a room that has not opted in is not silently given a new failure mode.
+ */
+export function gateConfig(get) {
+  const read = typeof get === 'function' ? get : (k) => get[k]
+  const cmd = read(GATE_CMD)
+  if (cmd == null || String(cmd).trim() === '') return null
+  const raw = Number(read(GATE_TIMEOUT))
+  const timeoutMs = Number.isFinite(raw) && raw > 0 ? Math.min(raw, 600000) : DEFAULT_TIMEOUT_MS
+  return { cmd: String(cmd), timeoutMs }
+}
+
+/** Trim command output to something that belongs in a CRDT, keeping the END — that is where a
+ *  test runner puts the failures. Keeping the head would record the banner and drop the reason. */
+export function trimOutput(s, max = MAX_OUTPUT) {
+  const t = String(s == null ? '' : s).replace(/\r\n/g, '\n').trim()
+  if (t.length <= max) return t
+  return '…(' + (t.length - max) + ' chars trimmed)\n' + t.slice(-max)
+}
+
+/**
+ * Run the check in a folder. Exit code 0 is a pass; anything else, including the command not
+ * existing, is a fail.
+ *
+ * A command that cannot be RUN is a failure and not a pass. Treating "spawn failed" as success
+ * would mean a typo in the gate silently disables it for the whole room, which is the worst
+ * outcome available here: everyone would believe they were gated and nobody would be.
+ */
+export function runGate({ cmd, cwd, timeoutMs = DEFAULT_TIMEOUT_MS, run = spawnSync, env = {} }) {
+  const started = Date.now()
+  let r
+  // Isolated test port per gate run so concurrent gates on the same machine never collide over fixed ports (HIV-24).
+  const isolatedPort = Number(process.env.HIVE_TEST_PORT) || (20000 + (process.pid % 10000) + Math.floor(Math.random() * 10000))
+  const gateEnv = {
+    ...process.env,
+    HIVE_TEST_PORT: String(isolatedPort),
+    ...env,
+  }
+  try {
+    r = run(cmd, {
+      cwd, shell: true, encoding: 'utf8', timeout: timeoutMs,
+      maxBuffer: 8 * 1024 * 1024, windowsHide: true,
+      env: gateEnv,
+    })
+  } catch (e) {
+    return { ok: false, code: null, timedOut: false, ms: Date.now() - started, out: trimOutput('could not run the gate: ' + e.message) }
+  }
+  const timedOut = r.error && (r.error.code === 'ETIMEDOUT' || /timed? ?out/i.test(r.error.message || ''))
+  const out = trimOutput([r.stdout, r.stderr].filter(Boolean).join('\n') || (r.error ? r.error.message : ''))
+  return {
+    ok: !r.error && r.status === 0,
+    code: r.status == null ? null : r.status,
+    timedOut: !!timedOut,
+    ms: Date.now() - started,
+    out,
+  }
+}
+
+/** The record stored under this agent's name. Timestamps are unix MICROseconds, per project rule. */
+export function verdictRecord({ region, by, cmd, result, forced = false, why = '' }) {
+  return {
+    region, by, cmd,
+    pass: !!(result && result.ok),
+    exit: result ? result.code : null,
+    timedOut: !!(result && result.timedOut),
+    ms: result ? result.ms : 0,
+    out: result ? result.out : '',
+    forced: !!forced,
+    why: String(why || ''),
+    at: Date.now() * 1000,
+  }
+}
+
+/**
+ * What the releasing agent is told. It has to say the three things an agent needs to act, because
+ * a refusal that does not say what to do next just gets retried: what failed, that the claim is
+ * still theirs (so this is not a collision to back off from), and the one honest way out.
+ */
+export function refusalMessage({ region, cmd, result }) {
+  const why = result.timedOut
+    ? `Q491 the gate timed out after ${Math.round(result.ms / 1000)}s`
+    : result.code == null
+      ? 'Q490 the gate could not be run'
+      : `Q490 the gate failed (exit ${result.code})`
+  return [
+    `${why}: \`${cmd}\``,
+    `${region} is STILL YOURS — nobody else can take it, so this is not a collision and retrying the release will not help.`,
+    'Fix what the gate is reporting and release again, or release with force and a reason if you are abandoning the work.',
+    result.out ? '\n' + result.out : '',
+  ].join('\n')
+}
+
+/** A forced release is legitimate — abandoning work is real — but it is never silent. */
+export function forcedMessage({ region, by, why }) {
+  return `Q492 ${by} force-released ${region} without passing the gate${why ? `: ${why}` : ' (no reason given)'}`
+}

package/hive-hook-install.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * INSTALL THE ANTI-IDLE GATE.
+ *
+ *   npx hivecode-hook install            # this project  (.claude/settings.json)
+ *   npx hivecode-hook install --global   # every project (~/.claude/settings.json)
+ *   npx hivecode-hook status
+ *   npx hivecode-hook uninstall
+ *
+ * Writes a Claude Code `Stop` hook entry pointing at hive-stop-hook.js. See that file for what
+ * the gate does and why prompt text alone cannot do it.
+ *
+ * MERGES, NEVER CLOBBERS. Settings files are shared: this machine already runs a Stop hook for
+ * something else entirely, and a writer that assumed it owned `hooks.Stop` would silently delete
+ * it. So we read what is there, append one entry to the existing array, and key it by command so
+ * re-running is idempotent rather than additive.
+ *
+ * Project-local by default. A global install would arm the gate inside every repo the user opens,
+ * including ones with no room in them -- harmless (the hook exits immediately without a session
+ * file) but it is still their machine, so it takes an explicit flag.
+ */
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+// Forward slashes: this string is written into JSON and handed to a shell. Windows accepts them
+// and it avoids a backslash-escaping round trip through the settings file.
+const HOOK = path.join(HERE, 'hive-stop-hook.js').split(path.sep).join('/')
+const COMMAND = `node "${HOOK}"`
+const TIMEOUT = 10
+
+const cmd = (process.argv[2] || 'status').toLowerCase()
+const GLOBAL = process.argv.includes('--global')
+const settingsPath = GLOBAL
+  ? path.join(os.homedir(), '.claude', 'settings.json')
+  : path.join(process.cwd(), '.claude', 'settings.json')
+
+const read = () => {
+  try { return JSON.parse(fs.readFileSync(settingsPath, 'utf8')) } catch { return null }
+}
+// A settings file we cannot parse is not ours to overwrite -- it is more likely hand-edited and
+// briefly invalid than genuinely empty, and clobbering it would lose the user's own config.
+const load = () => {
+  if (!fs.existsSync(settingsPath)) return {}
+  const j = read()
+  if (j && typeof j === 'object') return j
+  console.error(`refusing to touch ${settingsPath}: it exists but is not valid JSON.`)
+  console.error('fix or move it, then run this again.')
+  process.exit(1)
+}
+
+// Ours is any Stop entry whose command mentions hive-stop-hook, so an install from a previous
+// version (a different absolute path) is recognised and replaced rather than duplicated.
+const isOurs = (entry) =>
+  (entry?.hooks || []).some((h) => typeof h?.command === 'string' && h.command.includes('hive-stop-hook'))
+
+function install() {
+  const s = load()
+  s.hooks = s.hooks || {}
+  const stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
+  const kept = stop.filter((e) => !isOurs(e))
+  const dropped = stop.length - kept.length
+  kept.push({
+    hooks: [{ type: 'command', command: COMMAND, timeout: TIMEOUT, statusMessage: 'Checking the room (Hivecode)...' }],
+  })
+  s.hooks.Stop = kept
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
+  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
+
+  console.log(`\n  ${dropped ? 'updated' : 'installed'}  ${settingsPath}`)
+  console.log(`  command    ${COMMAND}`)
+  if (kept.length > 1) console.log(`  alongside  ${kept.length - 1} other Stop hook(s), left untouched`)
+  console.log('\n  An agent in a room can no longer end its turn while it has unread mail')
+  console.log('  addressed to it, or an accepted task still open.\n')
+  console.log('  Restart Claude Code for it to pick this up.\n')
+}
+
+function uninstall() {
+  const s = load()
+  const stop = Array.isArray(s.hooks?.Stop) ? s.hooks.Stop : []
+  const kept = stop.filter((e) => !isOurs(e))
+  if (kept.length === stop.length) { console.log(`\n  not installed in ${settingsPath}\n`); return }
+  if (kept.length) s.hooks.Stop = kept; else delete s.hooks.Stop
+  if (s.hooks && !Object.keys(s.hooks).length) delete s.hooks
+  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
+  console.log(`\n  removed from ${settingsPath}\n`)
+}
+
+function status() {
+  const s = read() || {}
+  const mine = (s.hooks?.Stop || []).filter(isOurs)
+  const others = (s.hooks?.Stop || []).length - mine.length
+  console.log(`\n  settings   ${settingsPath}${fs.existsSync(settingsPath) ? '' : '  (does not exist)'}`)
+  console.log(`  hivecode   ${mine.length ? 'INSTALLED' : 'not installed'}`)
+  if (others) console.log(`  other      ${others} unrelated Stop hook(s)`)
+  console.log(`\n  install with:  npx hivecode-hook install${GLOBAL ? ' --global' : ''}\n`)
+}
+
+if (cmd === 'install') install()
+else if (cmd === 'uninstall' || cmd === 'remove') uninstall()
+else status()

package/hive-instructions.js

@@ -0,0 +1,66 @@
+// THE RULES, DELIVERED BEFORE THE AGENT DOES ANYTHING.
+//
+// MCP servers may return an `instructions` string from the initialize handshake, and clients
+// place it in the model's system prompt at connect time (MCP spec; SDK support is at
+// @modelcontextprotocol/sdk server/index.js, which spreads `instructions` into InitializeResult).
+// That makes it the only channel we have that reaches an agent BEFORE it has decided what to do.
+//
+// WHY THIS FILE EXISTS AT ALL. Until now the only place the room's protocol was taught was the
+// tool descriptions and the HIVE_RULES the join call returns. Both are read too late: a tool
+// description is read when the agent is already considering that tool, and the join result is
+// one message that scrolls away. The single most important rule -- that hive_wait is your idle
+// state and ending your turn makes you unreachable -- is the one an agent needs before its first
+// tool call, and it was the one nothing said up front.
+//
+// BUDGET. This text is re-sent in the system prompt on every single turn of every agent that
+// installs Hivecode, so length here is a recurring cost paid by the user, forever. It is kept
+// to the rules that change behaviour and that an agent gets WRONG by default. Anything that is
+// merely useful belongs in a tool description, where it is read once and only when relevant.
+//
+// Keep it imperative and addressed to the agent. It is not documentation for a human.
+
+export const INSTRUCTIONS = `You are connected to Hivecode: a folder shared live with other AI
+agents and with humans who are editing at the same moment you are. Nothing here is advice about
+being tidy -- each rule exists because breaking it destroys someone else's work or strands them.
+
+THE LOOP. hive_wait is your idle state, not the end of your turn:
+  hive_wait -> do the work -> hive_complete -> hive_wait
+Ending your turn in a room makes you unreachable, and the agents waiting on you cannot learn that
+you stopped -- they just wait. If you think you have nothing left to do, that is exactly when to
+call hive_wait. It returns the moment anyone needs you.
+
+ADDRESS PEOPLE BY NAME. Put @Name on every message meant for someone; hive_members lists who is
+here. A message naming nobody lands in every agent's ambient digest, where they are instructed to
+skip it -- so assume no one acts on it. @all wakes the whole room: use it when you genuinely need
+everyone, never for chatter. Any agent may address any other directly -- no lead to
+route through, no permission needed.
+
+ANSWER EVERY QUESTION AIMED AT YOU. "Not yet -- I am on X, I will come back to you" is a complete
+answer. Silence is the one thing the asker cannot act on, because nothing tells them you stopped.
+Before a long stretch of work call hive_busy("what you are doing"): it silences nothing, it just
+tells anyone who @mentions you, as they send, that you are mid-task. Clear it when you finish.
+
+DESIGN BEFORE YOU WRITE -- MANDATORY. Before any new feature, post in the room BEFORE your first
+edit: who uses it and how, what it costs when it is wrong, and the edge cases. Every defect here
+has been a FALSE SUCCESS -- green, and wrong. You do not catch those by testing the happy path
+afterwards; you catch them by asking first what "wrong but green" would look like. If you cannot
+say what breaks, you do not understand it well enough to write it.
+
+CLAIM BEFORE YOU WRITE. hive_claim the file, write it, hive_release it. If the relay refuses your
+write because someone else holds that file, that is not an error and not something to retry --
+it is the lock doing its job. Go do something else, or @ the holder. hive_claims is authoritative
+about who holds what: read it instead of asking the room.
+
+A REFUSED RELEASE IS NOT A COLLISION: a failing gate keeps the file YOURS -- fix it, or
+force-release with a reason. hive_verified says whose check passed; "released" is not "works".
+
+WHILE YOU ARE WORKING. hive_wait blocks, so it cannot be used mid-task -- call hive_check between
+edits instead. If it reports priority "stop", deal with that before continuing what you were doing.
+
+NEVER STATE A NUMBER YOU DID NOT MEASURE. Other agents will build on what you say without
+re-deriving it. If you have not read the file or run the command, say so plainly instead of
+supplying a plausible value.`
+
+// One line, for surfaces too small for the full text (a hook's block reason, a CLI banner).
+export const ONE_LINER =
+  'In a Hivecode room, hive_wait is your idle state -- never end your turn, call hive_wait.'

package/hive-mailbox.js

@@ -28,14 +28,227 @@
  */
 export function mentionsName(text, me) {
   if (!text || !me) return false
+  if (mentionsAll(text)) return true // @all reaches everyone by definition
   const escaped = String(me).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  // Trailing boundary: end of string, or anything that cannot continue a name.
-  return new RegExp(`@${escaped}(?![\\w-])`, 'i').test(String(text))
+  // Both boundaries, and the same ones the extractor uses. If these two ever disagree, a message
+  // can be extracted as addressing someone who does not match it, or match someone it was never
+  // extracted for -- which is how a mailbox and a transcript come to tell different stories.
+  return new RegExp(`${MENTION_START}@${escaped}${MENTION_END}`, 'i').test(String(text))
 }
 
+/**
+ * `@all` — the deliberate broadcast.
+ *
+ * Before this there was no way to reach the whole room on purpose. An unaddressed message goes
+ * into every agent's ambient digest, where the rules tell them to skip it -- correct for
+ * chatter, useless for "everyone stop, the suite is red". So the only two options were name
+ * eight agents by hand or be ignored.
+ *
+ * It wakes everyone. It deliberately does NOT create a reply debt (see unansweredFor): one
+ * broadcast obliging eight replies is how a coordination channel becomes a spam channel, and
+ * that is the exact failure this room already had once.
+ */
+export function mentionsAll(text) {
+  // CODE SPANS ARE STRIPPED FIRST, AND ONLY HERE. Every other false mention is handled by the
+  // boundary rules below plus `obligationTargets`, which refuses to open a debt against somebody
+  // who is not in the room. `@all` is the one case neither can save: it is not a member, so the
+  // membership gate does not apply to it, and it wakes EVERYONE. So writing `@all` inside
+  // backticks -- which is how anybody documents this feature -- paged the entire room, every time.
+  //
+  // This is deliberately NOT a Markdown parser. Nested spans, unclosed fences and indented blocks
+  // are all out of scope, because the question is not "what is code here" but the much smaller
+  // "is this one token wrapped in backticks". A tokenizer would be the wrong tool and a permanent
+  // source of edge cases; one replace is the whole fix.
+  return /@all(?![\w-])/i.test(stripCodeSpans(text))
+}
+
+/** Inline code spans blanked out, so a token quoted as code is not read as an address. */
+const stripCodeSpans = (text) => String(text || '').replace(/`[^`]*`/g, ' ')
+
+/**
+ * WHERE A MENTION MAY BEGIN, AND WHERE IT MAY NOT.
+ *
+ * Measured in room `night` on 20 Sep 2026, against the old bare /@([\w-]+)/g:
+ *
+ *   "email me at ganesh@gmail.com"      -> ["gmail"]                 every email address
+ *   "blame line: author@example.org"    -> ["example"]               every commit trailer
+ *   "npm i @modelcontextprotocol/sdk"   -> ["modelcontextprotocol"]  every scoped package
+ *   "see `@all` in the docs"            -> broadcast to everyone     every doc about this feature
+ *
+ * After three hours the obligation ledger held 44 entries of which 32% were debts against members
+ * who had never existed, and a debt can only be discharged by the asker, so nothing in the system
+ * could ever have closed them. The ledger is what catches an agent going silent; it was becoming
+ * unreadable through ordinary use.
+ *
+ * LEADING: start of string, whitespace, an opening bracket, a quote, a dash, or a colon. Quotes
+ * are INCLUDED on purpose. A quoted example ("the parser reads "@antigravity"") is then extracted
+ * for the transcript and creates no debt, because `obligationTargets` gates on membership. The
+ * opposite choice would silently drop a real mention that opens a quoted sentence, and a dropped
+ * mention is the worse failure: the sender believes it was delivered.
+ *
+ * TRAILING: not a word character, a hyphen, or a SLASH. The slash is what distinguishes
+ * `@scope/package` from `@person`. It is written as one lookahead rather than a separate check so
+ * the regex cannot backtrack into a shorter name to satisfy it -- `[\w-]+` followed by `(?!\/)`
+ * alone would happily match "modelcontextprotoco" and declare victory.
+ */
+const MENTION_START = '(?:^|[\\s(\\[{<"\'—–:])'
+const MENTION_END = '(?![\\w\\-/])'
+
 /** Everyone addressed in a message, so a broadcast can be told from a direct call. */
 export function mentionedNames(text) {
-  return [...new Set([...String(text || '').matchAll(/@([\w-]+)/g)].map((m) => m[1]))]
+  const re = new RegExp(`${MENTION_START}@([\\w-]+)${MENTION_END}`, 'g')
+  return [...new Set([...String(text || '').matchAll(re)].map((m) => m[1]))]
+}
+
+/**
+ * WHO ACTUALLY OWES AN ANSWER — which is not the same question as who was named.
+ *
+ * Extraction and obligation were one decision and they are two. A transcript should show what the
+ * text said, including a name that is merely quoted; a DEBT is a claim about the present, and
+ * opening one against somebody who is not here produces an entry nobody can ever discharge, since
+ * only the asker may close it and the debtor does not exist.
+ *
+ * The distinction that makes this safe is which way time points. Resolving a HISTORICAL mention
+ * against who is present now would be the Historical Transcript Fallacy -- the past decided by the
+ * present -- and that is why extraction deliberately does NOT do it. An obligation is not history:
+ * it is live state about who owes me an answer right now, so checking present membership is
+ * exactly the right question for it.
+ *
+ * @param {string} text
+ * @param {{ me?: string, present?: Iterable<string> }} ctx  `present` is lowercased names
+ */
+export function obligationTargets(text, { me = '', present = [] } = {}) {
+  const here = new Set([...present].map((n) => String(n).toLowerCase()))
+  const self = String(me).toLowerCase()
+  return mentionedNames(text).filter((n) => {
+    const low = n.toLowerCase()
+    // @all wakes the room and obliges nobody -- one broadcast owing eight replies is how a
+    // coordination channel becomes a spam channel. Unchanged from the original behaviour.
+    if (low === 'all' || low === self) return false
+    return here.has(low)
+  })
+}
+
+/**
+ * A NAME THAT CANNOT BE ADDRESSED IS NOT A NAME. Refuse it at the door.
+ *
+ * On 20 Sep 2026 an agent joined room `night` as "antigravity 1". `mentionedNames` above splits
+ * on /@([\w-]+)/g, so "@antigravity 1" reads as "@antigravity", and no such member existed. Its
+ * mail, its obligations and its wake-on-mention were all silently dead for an hour. It saw
+ * messages only because it happened to be tailing the chat log. Nothing errored; the room said
+ * "@antigravity is NOT in the room", which was true and useless, because the member WAS present
+ * under a name this parser cannot produce.
+ *
+ * WHY REFUSE RATHER THAN NORMALISE. Silently rewriting "coder 1" to "coder-1" collides with a
+ * real "coder-1" and merges two processes into one participant — one awareness entry, one cursor,
+ * one mailbox — with neither told. And the agent's own prompt still says its name is the original,
+ * so it stops recognising messages about itself.
+ *
+ * WHY REFUSE RATHER THAN RESOLVE @mentions AGAINST THE MEMBER LIST. That would make a departed
+ * member break the historical record: a fact about the past decided by who happens to be present
+ * now. Same defect as the receipts work in HIV-P2.
+ *
+ * WHY THIS CHARSET AND NOT A NICER ONE. It is not taste, it is arithmetic. The extractor above
+ * only recognises [\w-]. A name outside that set CANNOT be produced by it, however carefully the
+ * sender types. Constraining names to the charset the parser already uses makes the two
+ * consistent by construction instead of by coincidence.
+ *
+ * KNOWN LIMIT, stated because it is a product decision and not an oversight: `\w` is ASCII, so a
+ * name in Devanagari, Han or Cyrillic is refused. That is honest rather than good — those names
+ * are equally unaddressable today, and refusing at least says so out loud. Widening it means
+ * widening the extractor first; the two move together or not at all.
+ *
+ * @param {any} name
+ * @returns {{ ok: boolean, error?: string, suggested?: string }}
+ */
+export function validateMemberName(name) {
+  if (name == null || typeof name !== 'string' || name.length === 0) {
+    return {
+      ok: false,
+      error: 'Member name must be a non-empty string so that the participant can be addressed via @mentions.',
+      suggested: 'agent-1',
+    }
+  }
+  // Whitespace is checked BEFORE the charset so the message names the actual problem. "contains
+  // whitespace" tells you what to do; "contains invalid characters" makes you hunt for which one.
+  if (/\s/.test(name)) {
+    return {
+      ok: false,
+      error: `Member name "${name}" contains whitespace. Names with spaces cannot be addressed via @mentions, breaking message routing, mailboxes, and delivery receipts.`,
+      suggested: suggestMemberName(name),
+    }
+  }
+  if (!/^[\w-]+$/.test(name)) {
+    return {
+      ok: false,
+      error: `Member name "${name}" contains invalid characters. Names must contain only letters, numbers, underscores, and hyphens so that @mentions can route mail to you.`,
+      suggested: suggestMemberName(name),
+    }
+  }
+  return { ok: true }
+}
+
+/**
+ * A refusal nobody can act on gets worked around, so every refusal above carries one of these.
+ *
+ * It deliberately validates its own output before returning it: a suggestion that is itself
+ * invalid is worse than no suggestion, because the caller retries, fails again, and now distrusts
+ * the error message. Whitespace-only and non-ASCII names both collapse to nothing here, which is
+ * why the fallback exists rather than being defensive padding.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function suggestMemberName(name) {
+  if (!name || typeof name !== 'string') return 'agent-1'
+  let s = name.replace(/[\s]+/g, '-').replace(/[^\w-]+/g, '-')
+  s = s.replace(/-+/g, '-').replace(/^[-_]+|[-_]+$/g, '')
+  return /^[\w-]+$/.test(s) ? s : 'agent-1'
+}
+
+/**
+ * Who has directly addressed `me` and not been answered since?
+ *
+ * "Answered" is deliberately cheap to satisfy: any later message from me that names them. It is
+ * not trying to judge whether the reply was any good -- only that the room never goes silent on
+ * someone who asked a direct question, which is the failure that makes agents give up on the
+ * channel and start tailing files instead.
+ *
+ * Derived from the chat log rather than stored, so it cannot drift out of sync with what was
+ * actually said, and needs no new state to persist or migrate.
+ *
+ * THREE THINGS DO NOT COUNT AS A DEBT, all for the same reason -- an obligation that fires on
+ * traffic nobody chose to send is noise wearing a rule's clothes:
+ *   - `@all` broadcasts (see mentionsAll)
+ *   - system messages, and the client's own auto-posted conflict/adopt notices
+ *   - my own messages, however many times I say my own name
+ *
+ * @param {Array<{by?: string, kind?: string, text?: string, at?: string}>} messages
+ * @param {string} me
+ * @returns {Array<{from: string, at: string, text: string}>} oldest first
+ */
+export function unansweredFor(messages, me) {
+  const list = Array.isArray(messages) ? messages : []
+  if (!me) return []
+  const low = (s) => String(s || '').toLowerCase()
+  const mine = low(me)
+  const AUTO = /^(⚠ MERGE CONFLICT|✓ conflict|↓ )/ // posted by the sync client, not by a person
+
+  const owed = new Map()   // sender (lowercased) -> the message I owe a reply to
+  for (const m of list) {
+    if (!m || m.kind === 'system' || AUTO.test(String(m.text || ''))) continue
+    if (low(m.by) === mine) {
+      // Anything I name is discharged. A broadcast from me discharges everything: I have
+      // spoken to the room, and holding a debt open after that is pedantry, not coordination.
+      if (mentionsAll(m.text)) { owed.clear(); continue }
+      for (const n of mentionedNames(m.text)) owed.delete(low(n))
+      continue
+    }
+    // Directly addressed, not merely broadcast to.
+    if (mentionsAll(m.text)) continue
+    if (mentionsName(m.text, me)) owed.set(low(m.by), { from: m.by, at: m.at || '', text: m.text || '' })
+  }
+  return [...owed.values()]
 }
 
 /**