hivecode-mcp 0.11.6 → 0.12.0

package/hive-mcp.js

@@ -4,7 +4,7 @@
 //
 // Register it with an MCP client (e.g. Claude Code / Claude Desktop):
 //   command: node   args: ["<abs-path>/hive-mcp.js"]
-//   env (optional): HIVE_RELAY = wss://your-relay   (defaults to the hosted relay)
+//   env (optional): HIVE_RELAY = wss://your-relay   (defaults to PUBLIC_DEFAULT_RELAY in hive-privacy.js)
 //
 // Tools exposed:
 //   hive_join         join/host a room for a folder (auto kind:ai) -> returns the rules
@@ -34,14 +34,17 @@ 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 { checkRelay, PUBLIC_DEFAULT_RELAY } from './hive-privacy.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 ACT from './hive-activity.js'   // HIV-P11; key MUST be 'activity'
+import * as RH from './hive-relay-health.js' // HIV-P13; the ONLY producer of the not-syncing diagnosis
 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'
+const DEFAULT_RELAY = process.env.HIVE_RELAY || PUBLIC_DEFAULT_RELAY // written once, in hive-privacy.js
 let session = null // { hive, room, relay, dir, name, mailbox }
 
 // ONE THROTTLE PER SERVER PROCESS, which is one agent. It deliberately does NOT live on the
@@ -102,7 +105,7 @@ async function tryResumeSession() {
   } catch { /* resume is best-effort; the agent can always hive_join explicitly */ }
 }
 
-async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor }) {
+async function joinRoom({ link = '', dir = './workspace', name = `agent-${crypto.randomBytes(2).toString('hex')}`, owner = '', token = '', chatCursor, kind = 'ai', passive = false }) {
   // REFUSED BEFORE THE OLD SESSION IS TORN DOWN. joinRoom's first act is to stop whatever session
   // exists, so validating after that point would leave an agent with a bad name holding nothing at
   // all -- it would lose a working room to a refusal it could have been given for free.
@@ -118,6 +121,24 @@ This is refused rather than fixed for you because renaming silently is worse: if
   const ROOT = path.resolve(dir)
   fs.mkdirSync(ROOT, { recursive: true })
   const { relay, room, token: linkToken, mode } = resolveRoom(link, dir)
+  // THE PRIVACY GATE, and note where it sits: after the relay is resolved, BEFORE the
+  // .hive.json write below and before startSync opens a socket. A refused join must leave
+  // nothing behind -- no config pointing at the wrong relay for the next process to find,
+  // and above all no published file. Checking after connecting would report a leak instead
+  // of preventing one, which is the difference between a guard and a log line.
+  const priv = checkRelay({ relay, env: process.env, dir: ROOT, fs })
+  if (!priv.ok) {
+    return `${priv.headline}
+
+${priv.detail}
+
+room: ${room}
+mode: ${mode}
+folder: ${ROOT}
+
+NOTHING WAS JOINED. No socket was opened, no file was published, and ${path.join(ROOT, '.hive.json')}
+was not written. Fix the relay and call hive_join again.`
+  }
   // token precedence: explicit arg > token baked into the join link > $HIVE_TOKEN.
   const useToken = token || linkToken || process.env.HIVE_TOKEN || ''
   // persist the token too, so a re-join from .hive.json keeps the grant (the
@@ -133,7 +154,7 @@ This is refused rather than fixed for you because renaming silently is worse: if
   // folder is precisely the situation the lock exists to prevent.
   let hive
   try {
-    hive = startSync({ relay, room, dir, name, kind: 'ai', owner, token: useToken, log: () => {} })
+    hive = startSync({ relay, room, dir, name, kind: kind || 'ai', owner, token: useToken, log: () => {}, passive: !!passive })
   } catch (e) {
     if (e && e.code === 'EHIVELOCKED') {
       return text(
@@ -143,7 +164,7 @@ This is refused rather than fixed for you because renaming silently is worse: if
     }
     throw e
   }
-  session = { hive, room, relay, dir, name, owner, mailbox: null }
+  session = { hive, room, relay, dir, name, owner, kind: kind || 'ai', passive: !!passive, mailbox: null }
   persistSession({ dir, name, owner }) // survive MCP host restarts (see tryResumeSession)
   // Wait for the first sync so members/board/rules are ready.
   //
@@ -156,6 +177,7 @@ This is refused rather than fixed for you because renaming silently is worse: if
   // here, at the moment we know whether the socket came up.
   let synced = false
   let connErr = ''
+  let refusedCode = null
   await new Promise((resolve) => {
     let done = false
     const finish = () => { if (!done) { done = true; resolve() } }
@@ -163,13 +185,35 @@ This is refused rather than fixed for you because renaming silently is worse: if
     // 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)
+      const code = RH.statusFromError(ev) || (ev && (ev.code || ev.status || ev.type))
+      if (code && typeof code === 'number') refusedCode = code
       if (!connErr) connErr = `the relay refused the connection${code ? ` (${code})` : ''}`
     })
     setTimeout(finish, 8000) // don't hang if the relay is cold
   })
   if (!synced) {
+    // HIV-P12. EVIDENCE BEFORE INFERENCE.
+    // If the relay actually refused us with an HTTP status, explainStatus() maps it to the
+    // authoritative cause (Q430 -> capacity, Q431 -> HIVE_SEATS, 401/403 -> token).
+    // Only when nothing refused us with a code do we query /health to infer whether it was capacity.
+    if (refusedCode) {
+      const explanation = RH.explainStatus(refusedCode, relay)
+      return [
+        `NOT JOINED -- the relay refused the connection (${refusedCode}): ${explanation}`,
+        `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.',
+        '',
+        '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')
+    }
     const why = connErr || 'no sync within 8s -- the relay did not answer'
+    const diag = await RH.explainNotSyncing(relay, { what: 'join' })
     return [
       `NOT JOINED -- ${why}.`,
       `room: ${room}`,
@@ -180,10 +224,9 @@ This is refused rather than fixed for you because renaming silently is worse: if
       '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.',
+      diag.text,
+      '',
+      'Two causes the relay cannot tell you about, worth checking if the above says capacity is fine:',
       '  - 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).',
       '',
@@ -283,7 +326,12 @@ This is refused rather than fixed for you because renaming silently is worse: if
   // The invite link carries the token when there is one — without it a secured room rejects
   // whoever you hand it to, and the Control Room says the link is missing its token.
   const inviteLink = `${relay}|${room}${useToken ? `|${useToken}` : ''}`
-  return `${mode}\nroom: ${room}\nrelay: ${relay}\nfolder: ${ROOT}\nhivecode: ${VERSION}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${inviteLink}\n\nANNOUNCE YOUR VERSION: say "joined on hivecode ${VERSION}" in chat. Mixed builds in one room cause data loss, and this is the only way anyone finds out.\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
+  // THE VERDICT, NOT JUST THE URL. `relay: wss://...` on its own is unreadable to anybody
+  // who has not run a relay -- the public one and a company's own look identical. The
+  // bracketed verdict is what makes "did my source just leave the building?" answerable
+  // without asking, and the warning line below is what makes it actionable.
+  const privNote = priv.warn ? `\n\n!! ${priv.warn}` : ''
+  return `${mode}\nroom: ${room}\nrelay: ${relay}  [${priv.headline}]\nfolder: ${ROOT}\nhivecode: ${VERSION}\nothers here: ${others.join(', ') || 'none yet'}\ninvite link: ${inviteLink}${privNote}\n\nANNOUNCE YOUR VERSION: say "joined on hivecode ${VERSION}" in chat. Mixed builds in one room cause data loss, and this is the only way anyone finds out.\n\n--- FOLLOW THESE RULES ---\n${rulesText}`
 }
 
 function requireSession() { if (!session) throw new Error('not in a room — call hive_join first'); return session }
@@ -298,6 +346,10 @@ function mailbox() {
   return s.mailbox
 }
 function chatArray() { return requireSession().hive.doc.getArray('chat').toArray() }
+
+// HIV-P11. Returns null rather than throwing when there is no session: a liveness stamp is an
+// observation about a tool call, not part of it, and it must never be the reason a tool fails.
+function activityMap() { try { return requireSession().hive.doc.getMap('activity') } catch { return null } }
 // 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) {
@@ -421,7 +473,7 @@ function waitForWork(timeoutMs, opts = {}) {
 
 const TOOLS = [
   { name: 'hive_join', description: 'Join (or host) a Hivecode room for a project folder. Joins automatically as an AI participant. If a join link is given, uses it; else reads <dir>/.hive.json; else hosts a new room. Returns the room info and the HIVE_RULES you must follow.',
-    inputSchema: { type: 'object', properties: { link: { type: 'string', description: 'optional join link "wss://relay|room"' }, dir: { type: 'string', description: 'project folder to sync (default ./workspace)' }, name: { type: 'string', description: 'your display name in the room' }, owner: { type: 'string', description: 'the human responsible for you — only they may approve tasks directed at you' }, token: { type: 'string', description: 'access token for a secured room (else uses $HIVE_TOKEN). Required only if the relay runs in auth-required mode.' } } } },
+    inputSchema: { type: 'object', properties: { link: { type: 'string', description: 'optional join link "wss://relay|room"' }, dir: { type: 'string', description: 'project folder to sync (default ./workspace)' }, name: { type: 'string', description: 'your display name in the room' }, owner: { type: 'string', description: 'the human responsible for you — only they may approve tasks directed at you' }, token: { type: 'string', description: 'access token for a secured room (else uses $HIVE_TOKEN). Required only if the relay runs in auth-required mode.' }, kind: { type: 'string', description: 'participant kind (ai or human)' }, passive: { type: 'boolean', description: 'true = this participant is a passive listener or bot daemon and does not take turns or answer questions' } } } },
   { name: 'hive_assign', description: 'Direct a task at another participant by name (e.g. ask another agent to work on a file). If the target is an AI with an owner, it stays PENDING until that owner approves.',
     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.',
@@ -586,13 +638,8 @@ function enforceDcoLock(opts = {}) {
 // itself reporting the wrong build. Read the truth instead; package.json always ships in the
 // tarball and sits beside this file in both the repo and the published package.
 // A failed read must never stop the server from starting, so it falls back rather than throwing.
-export const VERSION = (() => {
-  try {
-    const v = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version
-    if (typeof v === 'string' && v) return v
-  } catch { /* fall through */ }
-  return '0.0.0-unknown'
-})()
+import { VERSION } from "./hive-version.js"
+export { VERSION }
 // `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
@@ -611,6 +658,21 @@ async function dispatch(req) {
     // persisted session exists for this cwd, transparently rejoin before any tool runs —
     // the agent (and its human) never see a "not in a room" flake again.
     if (!session && name !== 'hive_join' && name !== 'hive_leave') await tryResumeSession()
+    // HIV-P11. STAMPED BEFORE THE TOOL RUNS, not after it returns.
+    //
+    // The first version stamped in a `finally` -- which is wrong by exactly one call, and the
+    // suite caught it: an agent that called hive_members saw ITSELF reported PARKED, because the
+    // record it read still held the timestamp of its previous call. The activity is the call
+    // BEGINNING; a tool that takes four minutes is working for all four of them, and a tool that
+    // throws was still an agent doing something. Stamping first covers both, and covers every
+    // tool anyone adds later, because there is no path into the switch that skips this line.
+    //
+    // hive_wait stamps its own entry and exit (waitingSince must mean "inside the call RIGHT
+    // NOW"). hive_leave drops the row instead of refreshing it. hive_join has no session yet, so
+    // it is stamped in the finally below -- the one case where after is the only option.
+    if (session && name !== 'hive_wait' && name !== 'hive_leave') {
+      try { ACT.noteAction(activityMap(), { name: session.name, tool: name }) } catch { }
+    }
     switch (name) {
       case 'hive_join': return text(await joinRoom(args))
       case 'hive_say': {
@@ -643,58 +705,137 @@ async function dispatch(req) {
         // 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 members = s.hive.members()
+        const memberMap = new Map(members.map((m) => [String(m.name).toLowerCase(), m]))
+        const present = new Set(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 act = activityMap()
+        const controls = s.hive.doc.getMap('controls')
+        const parkedAfter = ACT.parkedAfterMs()
+        const now = Date.now()
+
+        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())
+        }
+
+        // HIV-P11b. Send-time inspection of recipient state:
+        // Warns when addressing PARKED, PAUSED, PASSIVE, or GONE/AWAY agents.
+        function describeRecipientLiveness(n) {
+          const lc = n.toLowerCase()
+          const mem = memberMap.get(lc)
+          const isPresent = !!mem
+          const rec = act ? act.get(lc) : null
+          const c = controls.get(mem ? mem.name : n)
+          const isPaused = !!(c && c.state === 'paused')
+          const isPassive = !!(mem && mem.passive)
+          const d = ACT.describe(rec, {
+            present: isPresent,
+            paused: isPaused,
+            passive: isPassive,
+            now,
+            parkedAfter,
+          })
+          const displayName = mem ? mem.name : n
+
+          if (d.state === ACT.PARKED) {
+            const age = d.ageMs == null ? 'its whole session' : `${Math.round(d.ageMs / 60000)} min`
+            const tool = d.lastTool ? ` (${d.lastTool})` : ''
+            return `⚠ @${displayName} — PARKED: connected, but NOT inside hive_wait and silent for ${age}${tool}. ` +
+              `It will not wake on its own — anything you send it now will sit unread until a human prompts it.`
+          }
+          if (d.state === ACT.PAUSED) {
+            return `⚠ @${displayName} — PAUSED by a human. It is obeying a stop, not stalled. Do not reassign its work.`
+          }
+          if (d.state === ACT.PASSIVE) {
+            return `⚠ @${displayName} — PASSIVE LISTENER. This process does not take turns or answer questions; no obligation recorded.`
+          }
+          if (d.state === ACT.GONE) {
+            if (everHere.has(lc)) {
+              return `⚠ @${displayName} — AWAY RIGHT NOW. Not connected at the moment, but has worked here before; obligation recorded for when they return.`
+            } else {
+              return `⚠ @${displayName} — 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.`
+            }
+          }
+          // d.state is WORKING or WAITING
+          const busy = findBusy(busyMap, n)
+          if (busy) {
+            return describeRecipient(displayName, busy, true, now)
+          }
+          return ''
+        }
+
+        const candidateNames = named.filter((n) => n.toLowerCase() !== 'all' && n.toLowerCase() !== s.name.toLowerCase())
+        const seenCandidates = new Set()
+        const uniqueCandidates = []
+        for (const n of candidateNames) {
+          const lc = n.toLowerCase()
+          if (!seenCandidates.has(lc)) {
+            seenCandidates.add(lc)
+            uniqueCandidates.push(n)
+          }
+        }
+        const notes = uniqueCandidates.map(describeRecipientLiveness).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.
+        // NEEDS REPLY. A question is recorded, not just spoken. One obligation per agent named.
+        // HIV-P6: If the room knows nobody will answer, DO NOT record a debt.
+        //   1. Absent names: warned immediately, ZERO obligations opened.
+        //   2. Passive listeners (bot daemons, wake listeners): warned immediately, ZERO obligations opened.
+        //   3. Active participants: real debt opened, dischargeable ONLY by the asker.
+        //   4. @all broadcast: targets only active non-passive AI agents in the room.
         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())
+
+          let activeTargets = []
+          let awayTargets = []
+          let neverSeenNames = []
+          let passiveNames = []
+
+          if (mentionsAll(body)) {
+            activeTargets = members
+              .filter((m) => String(m.name).toLowerCase() !== s.name.toLowerCase() && !m.passive && m.kind === 'ai')
+              .map((m) => String(m.name))
+          } else {
+            for (const n of uniqueCandidates) {
+              const lc = n.toLowerCase()
+              const mem = memberMap.get(lc)
+              if (mem) {
+                if (mem.passive) {
+                  passiveNames.push(mem.name || n)
+                } else {
+                  activeTargets.push(mem.name || n)
+                }
+              } else {
+                if (everHere.has(lc)) {
+                  awayTargets.push(n)
+                } else {
+                  neverSeenNames.push(n)
+                }
+              }
+            }
           }
-          const opened = targets.map((n) => OB.open(obMap, {
+
+          const openedActive = activeTargets.map((n) => OB.open(obMap, {
             from: s.name, to: n, text: body, dueMs,
-            absent: !present.has(n.toLowerCase()),
-            neverSeen: !everHere.has(n.toLowerCase()),
+            absent: false,
+            neverSeen: false,
           }))
+
+          const openedAway = awayTargets.map((n) => OB.open(obMap, {
+            from: s.name, to: n, text: body, dueMs,
+            absent: true,
+            neverSeen: false,
+          }))
+
+          const opened = [...openedActive, ...openedAway]
+
           if (opened.length) {
-            obStr = `\n\nYOU ARE OWED AN ANSWER — ${opened.map((o) => `${o.id} (${o.to})`).join(', ')}\n` +
+            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)
@@ -799,7 +940,21 @@ 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, until: args.until })
+        // HIV-P11. `waitingSince` means "inside this call right now", never "waited at some
+        // point", and the finally is what keeps that true. A wait that returns or throws while
+        // leaving the flag set describes an agent parked in a call it has already left -- and
+        // describes it as WAITING, the single most reassuring state in the taxonomy. stateOf()
+        // gates WAITING on awareness so a process that DIES here cannot fake it, but a live
+        // process that merely threw is still present, so the gate does not cover that and this
+        // does. The name is captured first because the session can be gone by the finally.
+        const waitName = requireSession().name
+        ACT.noteWaitStart(activityMap(), { name: waitName })
+        let r
+        try {
+          r = await waitForWork(ms, { wakeOn: args.wakeOn, until: args.until })
+        } finally {
+          try { ACT.noteWaitEnd(activityMap(), { name: waitName }) } catch { }
+        }
         const globalState = requireSession().hive.getState()
         // 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
@@ -918,16 +1073,52 @@ async function dispatch(req) {
       case 'hive_owed': {
         const s2 = requireSession()
         const obMap = s2.hive.doc.getMap('obligations')
+        const act = activityMap()
+        const parkedAfter = ACT.parkedAfterMs()
+        const members = s2.hive.members()
+        const memberMap = new Map(members.map((m) => [String(m.name).toLowerCase(), m]))
+        const controls = s2.hive.doc.getMap('controls')
+        const now = Date.now()
+
+        // HIV-P11b. Dynamic reachability annotation for debts:
+        // Distinguishes actionable pending debts from debts owed by PARKED, GONE, or PAUSED agents.
+        function describeDebt(o) {
+          const base = OB.describe(o, () => now)
+          const lc = String(o.to || '').toLowerCase()
+          const mem = memberMap.get(lc)
+          const rec = act ? act.get(lc) : null
+          const c = controls.get(mem ? mem.name : o.to)
+          const d = ACT.describe(rec, {
+            present: !!mem,
+            paused: !!(c && c.state === 'paused'),
+            passive: !!(mem && mem.passive),
+            now,
+            parkedAfter,
+          })
+          if (d.state === ACT.PARKED) {
+            const age = d.ageMs == null ? 'its whole session' : `${Math.round(d.ageMs / 60000)} min`
+            return `${base}  [UNREACHABLE — @${mem ? mem.name : o.to} is PARKED: silent for ${age}, will not wake on its own]`
+          }
+          if (d.state === ACT.GONE) {
+            return `${base}  [UNREACHABLE — @${o.to} is GONE: not connected]`
+          }
+          if (d.state === ACT.PAUSED) {
+            return `${base}  [PAUSED by human — do not reassign]`
+          }
+          return base
+        }
+
         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 openList = OB.openList(obMap, () => now)
+          if (!openList.length) return text('Nothing outstanding in this room.')
+          const staleCount = openList.filter(OB.isStale).length
+          return text(`${openList.length} open, ${staleCount} stale:\n` + openList.map((o) => '  ' + describeDebt(o)).join('\n'))
         }
-        const mine = OB.owedBy(obMap, s2.name), theirs = OB.owedTo(obMap, s2.name)
+        const mine = OB.owedBy(obMap, s2.name, () => now), theirs = OB.owedTo(obMap, s2.name, () => now)
         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'))
+        if (mine.length) parts.push(`YOU OWE ${mine.length} ANSWER(S) — answer in chat with @Name; the asker closes it:\n` + mine.map((o) => '  ' + describeDebt(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) => '  ' + describeDebt(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}]`) }
@@ -996,7 +1187,39 @@ Nothing was claimed. Put the path inside the room's sync scope, or pick one that
         // 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.`)
+        if (got) {
+          // HIV-P18. "It's yours" was all this said, and for a file outside the working set that
+          // was the entire defect: the agent reads its directory, sees nothing, concludes the file
+          // does not exist, and CREATES it -- which is the blind recreate. Measured 21 Sep 2026:
+          // claim returned true, the file doc was never opened, no bytes arrived, and the agent
+          // was told it held something it could not see.
+          //
+          // sync.js now fetches on claim. This reports WHICH of three states the agent is in,
+          // because they demand different next actions and an empty directory cannot tell them
+          // apart. Awaited here rather than in claim(), whose contract is synchronous.
+          let fetched = null
+          try { fetched = await requireSession().hive.fetch(region) } catch { }
+          const head = `claimed ${region} — it's yours.`
+          if (fetched && fetched.notInRoom) {
+            return text(`${head}
+
+!! ${region} IS NOT IN THIS ROOM. No client has ever published it, so nothing will fetch it and it is NOT simply outside your working set. If you create it now you are creating a new file, not editing an existing one — which is correct only if that is what you intend. If you expected content here, the path is probably outside the room's sync scope: check that first, then ask whoever holds the file to write it into their synced folder.
+
+Edit it, then call hive_release.`)
+          }
+          if (fetched && fetched.ok === false) {
+            return text(`${head}
+
+!! ${region} IS IN THE ROOM BUT ITS CONTENT HAS NOT ARRIVED. ${fetched.reason || ''}
+DO NOT create it from scratch — the room's copy exists and writing over it unions two whole files. Retry, or check hive_status (filesHeld of roomFiles).
+
+Then call hive_release.`)
+          }
+          const note = fetched && fetched.ok && !fetched.alreadyLocal && !fetched.empty
+            ? ` Its content was not in this folder and has been fetched (${fetched.bytes} bytes) — read it before editing.`
+            : ''
+          return text(`claimed ${region} — it's yours.${note} 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.`)
       }
@@ -1048,7 +1271,40 @@ Nothing was written. This tool exists to guarantee the change syncs to every pee
         const dropped = (r.coverage || []).filter((c) => !c.covered)
         return text(`✓ resolution LANDED in ${file} — validated by ICR (parses, no dangling refs), signed by you, synced to every peer.${dropped.length ? ` ⚠ Intent coverage: ${dropped.map((c) => `${c.name}'s changes (${c.missing.slice(0, 5).join(', ')}) did not survive`).join('; ')} — if that was not deliberate, submit a better reconciliation.` : ' Full intent coverage: every side\'s changes survived.'}`)
       }
-      case 'hive_members': { const now = Date.now(); return text(requireSession().hive.members().map((m) => `${m.name} (${m.kind})${m.editing && now - m.editing.at < 15000 ? ` — editing ${m.editing.file}` : ''}`).join('\n') || '(none)') }
+      case 'hive_members': {
+        const now = Date.now()
+        const s = requireSession()
+        const act = activityMap()
+        const controls = s.hive.doc.getMap('controls')
+        const parkedAfter = ACT.parkedAfterMs()
+        const present = s.hive.members()
+        const presentKeys = new Set(present.map((m) => String(m.name).toLowerCase()))
+
+        const rows = present.map((m) => {
+          const rec = act ? act.get(String(m.name).toLowerCase()) : null
+          const c = controls.get(m.name)
+          const editing = m.editing && now - m.editing.at < 15000 ? `\n    editing ${m.editing.file}` : ''
+          return ACT.line(`${m.name} (${m.kind})`, rec, {
+            present: true, passive: !!m.passive,
+            paused: !!(c && c.state === 'paused'),
+            // HIV-P11c. Without this the room said `Ganesh (human) — PARKED: ... anything you
+            // send it now will sit unread until a human prompts it` about the human.
+            human: String(m.kind || '').toLowerCase() === 'human',
+            now, parkedAfter,
+          }) + editing
+        })
+
+        // HIV-P11. THE ONES THAT ARE NOT HERE ANY MORE, which is the half a human coming back in
+        // the morning actually needs. Awareness is ephemeral: an agent that died at 23:00 simply
+        // vanishes from members(), so the old output could not distinguish "never joined" from
+        // "worked here for three hours and stopped". The activity record is durable, so it can.
+        const goneRows = ACT.all(act)
+          .filter((r) => !presentKeys.has(r.key))
+          .map((r) => ACT.line(r.name || r.key, r, { present: false, now, parkedAfter }))
+
+        const body = [...rows, ...(goneRows.length ? ['', '— not connected —', ...goneRows] : [])]
+        return text(body.join('\n') || '(none)')
+      }
       case 'hive_status': {
         const s = requireSession()
         // Connection state belongs here too, not only in hive_wait: this is the tool an
@@ -1056,17 +1312,36 @@ Nothing was written. This tool exists to guarantee the change syncs to every pee
         // is almost always "you are still connected, do nothing".
         let conn = null
         try { conn = s.hive.status() } catch { }
+        // `privacy` sits next to `connected` on purpose. These are the two questions an
+        // agent asks here, and only one of them had an answer: "am I reaching anyone" was
+        // reportable and "where is my source going" was not. A bare relay URL is not an
+        // answer to the second -- the public relay and a company's own are the same shape.
+        const pv = checkRelay({ relay: s.relay, env: process.env, dir: s.dir, fs })
         return text({
           room: s.room, relay: s.relay, dir: s.dir, name: s.name, hivecode: VERSION,
+          privacy: pv.headline,
+          ...(pv.warn ? { privacyWarning: pv.warn } : {}),
+          ...(pv.pin && pv.pin.pinned ? { relayPin: pv.pin.origins.join(', ') } : {}),
           unread: mailbox().peek(chatArray()).unreadCount,
           connected: conn ? conn.connected : null,
           filesSynced: conn ? `${conn.filesSynced}/${conn.files}` : null,
         })
       }
-      case 'hive_leave': { requireSession().hive.stop(); session = null; try { fs.rmSync(SESSION_FILE) } catch {}; return text('left the room') }
+      // HIV-P11. A deliberate leave is the one departure the room KNOWS about, so the activity
+      // row is dropped rather than left to read as GONE. GONE means "stopped without saying so",
+      // and diluting it with agents that signed off correctly is how a signal stops being read.
+      case 'hive_leave': { try { ACT.forget(activityMap(), requireSession().name) } catch { }; requireSession().hive.stop(); session = null; try { fs.rmSync(SESSION_FILE) } catch {}; return text('left the room') }
       default: return err(`unknown tool: ${name}`)
     }
   } catch (e) { return err(`error: ${e.message}`) }
+  finally {
+    // hive_join only: the session does not exist until the case has run, so this is the single
+    // tool that cannot be stamped on the way in. Everything else is stamped above, before the
+    // switch, so that an agent's own record reflects the call it is currently making.
+    try {
+      if (session && name === 'hive_join') ACT.noteAction(activityMap(), { name: session.name, tool: name })
+    } catch { /* a liveness stamp must never be able to fail a tool call */ }
+  }
 }
 
 // MAIL PIGGYBACK — the delivery channel that cannot be ignored.