hivecode-mcp 0.12.4 → 0.13.0

package/docs/MCP.md

@@ -1,118 +1,157 @@
-# Hivecode MCP server
-
-Lets any MCP-capable AI agent (Claude Code, Claude Desktop, etc.) join a Hivecode
-room and coordinate through **native tool calls** — no scripts to run, no human
-to set it up.
-
-## Register it
-
-Add Hivecode to your MCP client config. The command runs this repo's server.
-
-**Claude Code** (`.mcp.json` in your project, or user settings):
-```json
-{
-  "mcpServers": {
-    "hivecode": {
-      "command": "node",
-      "args": ["C:/Users/G1/Desktop/N/hive-mcp.js"],
-      "env": { "HIVE_RELAY": "wss://hivecode-relay.onrender.com" }
-    }
-  }
-}
-```
-
-`HIVE_RELAY` is optional (defaults to the hosted relay).
-
-### Setting it up: one command
-
-```bash
-npx -y hivecode-mcp@latest setup
-```
-
-This writes the hivecode entry into every agent app it finds (Claude Code, Antigravity, Cursor,
-Windsurf, Claude Desktop, Gemini CLI), then launches each entry the way that app will and checks it
-answers an MCP handshake. It installs a runtime copy under `~/.hivecode/runtime/<version>`, so the
-agent app starts Hivecode with no download and no network.
-
-Do not put `{"command": "npx", ...}` in an MCP config by hand. Agent apps start servers without a
-shell, and on Windows `npx` is `npx.cmd`, so that entry fails with `spawn npx ENOENT`. Its first
-start also downloads the package, which can outlast an app's start-up limit (Claude Code allows
-30 seconds). If `setup` does not know your app, it prints the exact entry to use instead.
-
-Because agent apps now start that installed copy, nothing updates it on its own. The server asks
-npm once per start (in the background, never blocking) and, when a newer build is out, says so in
-`hive_join` and `hive_status`, with the command to run: `npx -y hivecode-mcp@latest setup`. Mixed
-versions in one room can lose data, so do not ignore it. `HIVE_PRIVATE=1` or
-`HIVE_NO_UPDATE_CHECK=1` turns the check off.
-
-## Tools the agent gets
-
-| Tool | What it does |
-|------|--------------|
-| `hive_join` | Join/host a room for a folder. Auto-joins as an **AI** participant. Returns the room info **and the HIVE_RULES to follow**. With `branch` (and `repo`), joins the room bound to that git branch by `npx -y hivecode-mcp@latest branch <name>`, in a folder of its own. |
-| `hive_say` | Post a coordination message — announce what you're about to work on. |
-| `hive_read_chat` | Read the room conversation (read this to coordinate). |
-| `hive_read_board` | Read recent whole-file rewrites (read before editing a file). |
-| `hive_members` | Who's in the room (humans + agents). |
-| `hive_status` | Current session info. |
-| `hive_leave` | Leave the room. |
-
-## How an agent uses it
-
-1. `hive_join` (with a `link`, a `branch` bound by `npx -y hivecode-mcp@latest branch`, a `dir` containing `.hive.json`, or nothing to host a new room) — pass `owner` so the right human can approve your tasks.
-2. Read the returned **HIVE_RULES**.
-3. `hive_read_chat` + `hive_read_board` before touching files.
-4. `hive_say` to announce intent, then edit files in the synced folder.
-5. Keep editing — changes merge with everyone else's safely; rewrites are auto-logged.
-
-## Reacting to directed work (no polling)
-
-A human can direct a task at you, but you only act once **your owner approves**.
-Don't poll — **block** on `hive_wait`:
-
-```
-loop:
-  result = hive_wait(timeoutSeconds: 60)   # returns the instant your owner approves
-  if result has APPROVED WORK:
-     do it, then hive_complete(id)
-  # else just call hive_wait again
-```
-
-`hive_wait` returns within ~1s of the approval (it reacts to the live update),
-and also wakes on new chat so you stay responsive to teammates.
-
-This is the lowest-friction way for AIs to adopt the protocol in `SPEC.md`:
-the agent never runs a command, it just calls tools.
-
-## The anti-idle gate (Claude Code)
-
-Everything above is still an instruction, and instructions get ignored. The single
-worst failure in a room is an agent that decides it is finished: its process is
-alive and its socket is up, but it has stopped listening, and the agents waiting on
-it just wait. Nothing tells them.
-
-You cannot fix that with wording. Install the gate:
-
-```
-npx -y -p hivecode-mcp@latest hivecode-hook install            # this project
-npx -y -p hivecode-mcp@latest hivecode-hook install --global   # every project
-```
-
-That writes a Claude Code **`Stop` hook**. Claude Code runs it when the agent is
-about to end its turn; the hook checks the room and **refuses the stop** if there is
-unread mail addressed to that agent, or an accepted task still open. The agent does
-not get a vote — same difference as a claim the relay enforces versus a claim it
-merely warns about.
-
-It merges into any existing `Stop` hooks rather than replacing them, and
-`npx -y -p hivecode-mcp@latest hivecode-hook uninstall` removes it. It reads only local mirrored files
-(`HIVE_CHAT.md`, `HIVE_TASKS.md`), so it costs no network round trip and works with
-the relay unreachable.
-
-Three guards stop it becoming a trap: it never blocks a stop that is already the
-result of a block, a given message can cause at most one block, and an open task
-stands down after three consecutive turns so an impossible task cannot pin an agent
-forever. Any failure at all — no room, unreadable file, bad JSON — allows the stop.
-
-Other MCP clients get the same rules in their system prompt (the server returns them
-in `instructions` at handshake), but only Claude Code can enforce them.
+# Hivecode MCP server
+
+Lets any MCP-capable AI agent (Claude Code, Claude Desktop, etc.) join a Hivecode
+room and coordinate through **native tool calls** — no scripts to run, no human
+to set it up.
+
+## Register it
+
+`npx -y hivecode-mcp@latest setup` (below) writes this entry for you. Written by hand, it points at
+the runtime copy that `setup` installs:
+
+**Claude Code** (your user settings, so every project on this machine gets it):
+```json
+{
+  "mcpServers": {
+    "hivecode": {
+      "command": "node",
+      "args": ["<your home>/.hivecode/runtime/<version>/node_modules/hivecode-mcp/hive-mcp.js"],
+      "env": { "HIVE_RELAY": "wss://hivecode-relay.onrender.com" }
+    }
+  }
+}
+```
+
+`HIVE_RELAY` is optional (defaults to the hosted relay).
+
+Do not put this entry in a project's `.mcp.json`. That file is shared through git, but the path in
+it exists only on the machine that wrote it. Inside that project, Claude Code ranks it above the
+entry in a user's settings, so on everyone else's machine Hivecode fails to start ("Connection
+closed").
+
+### Setting it up: one command
+
+```bash
+npx -y hivecode-mcp@latest setup
+```
+
+This writes the hivecode entry into every agent app it finds (Claude Code, Antigravity, Cursor,
+Windsurf, Claude Desktop, Gemini CLI), then launches each entry the way that app will and checks it
+answers an MCP handshake. It installs a runtime copy under `~/.hivecode/runtime/<version>`, so the
+agent app starts Hivecode with no download and no network.
+
+Do not put `{"command": "npx", ...}` in an MCP config by hand. Agent apps start servers without a
+shell, and on Windows `npx` is `npx.cmd`, so that entry fails with `spawn npx ENOENT`. Its first
+start also downloads the package, which can outlast an app's start-up limit (Claude Code allows
+30 seconds). If `setup` does not know your app, it prints the exact entry to use instead.
+
+Because agent apps now start that installed copy, nothing updates it on its own. The server asks
+npm once per start (in the background, never blocking) and, when a newer build is out, says so in
+`hive_join` and `hive_status`, with the command to run: `npx -y hivecode-mcp@latest setup`. Mixed
+versions in one room can lose data, so do not ignore it. `HIVE_PRIVATE=1` or
+`HIVE_NO_UPDATE_CHECK=1` turns the check off.
+
+## Tools the agent gets
+
+| Tool | What it does |
+|------|--------------|
+| `hive_join` | Join/host a room for a folder. Auto-joins as an **AI** participant. Returns the room info **and the HIVE_RULES to follow**. With `branch` (and `repo`), joins the room bound to that git branch by `npx -y hivecode-mcp@latest branch <name>`, in a folder of its own. |
+| `hive_say` | Post a coordination message — announce what you're about to work on. |
+| `hive_read_chat` | Read the room conversation (read this to coordinate). |
+| `hive_read_board` | Read recent whole-file rewrites (read before editing a file). |
+| `hive_members` | Who's in the room (humans + agents). |
+| `hive_status` | Current session info. |
+| `hive_leave` | Leave the room. |
+
+## How an agent uses it
+
+1. `hive_join` (with a `link`, a `branch` bound by `npx -y hivecode-mcp@latest branch`, a `dir` containing `.hive.json`, or nothing to host a new room) — pass `owner` so the right human can approve your tasks.
+2. Read the returned **HIVE_RULES**.
+3. `hive_read_chat` + `hive_read_board` before touching files.
+4. `hive_say` to announce intent, then edit files in the synced folder.
+5. Keep editing — changes merge with everyone else's safely; rewrites are auto-logged.
+
+## Reacting to directed work (no polling)
+
+A human can direct a task at you, but you only act once **your owner approves**.
+Don't poll — **block** on `hive_wait`:
+
+```
+loop:
+  result = hive_wait(timeoutSeconds: 60)   # returns the instant your owner approves
+  if result has APPROVED WORK:
+     do it, then hive_complete(id)
+  # else just call hive_wait again
+```
+
+`hive_wait` returns within ~1s of the approval (it reacts to the live update),
+and also wakes on new chat so you stay responsive to teammates.
+
+This is the lowest-friction way for AIs to adopt the protocol in `SPEC.md`:
+the agent never runs a command, it just calls tools.
+
+## The anti-idle gate (Claude Code)
+
+Everything above is still an instruction, and instructions get ignored. The single
+worst failure in a room is an agent that decides it is finished: its process is
+alive and its socket is up, but it has stopped listening, and the agents waiting on
+it just wait. Nothing tells them.
+
+You cannot fix that with wording. Install the gate:
+
+```
+npx -y -p hivecode-mcp@latest hivecode-hook install            # this project
+npx -y -p hivecode-mcp@latest hivecode-hook install --global   # every project
+```
+
+That writes a Claude Code **`Stop` hook**. Claude Code runs it when the agent is
+about to end its turn; the hook checks the room and **refuses the stop** if there is
+unread mail addressed to that agent, or an accepted task still open. The agent does
+not get a vote — same difference as a claim the relay enforces versus a claim it
+merely warns about.
+
+It merges into any existing `Stop` hooks rather than replacing them, and
+`npx -y -p hivecode-mcp@latest hivecode-hook uninstall` removes it. It reads only local mirrored files
+(`HIVE_CHAT.md`, `HIVE_TASKS.md`), so it costs no network round trip and works with
+the relay unreachable.
+
+Three guards stop it becoming a trap: it never blocks a stop that is already the
+result of a block, a given message can cause at most one block, and an open task
+stands down after three consecutive turns so an impossible task cannot pin an agent
+forever. Any failure at all — no room, unreadable file, bad JSON — allows the stop.
+
+Other MCP clients get the same rules in their system prompt (the server returns them
+in `instructions` at handshake), but only Claude Code can enforce them.
+
+## Running two or more agents in the same app
+
+Host apps handle MCP server processes in one of two ways:
+
+- **Per-session (separate process per chat/terminal):**
+  - **Claude Code**: Each terminal CLI session (`claude`) spawns its own independent Node child process from `~/.claude.json`. Multiple Claude Code sessions never share an MCP server process.
+- **Single shared process across all tabs/windows:**
+  - **Antigravity**: Spawns one singleton stdio MCP process from `mcp_config.json` managed by `language_server.exe` (`--subclient_type hub`), shared by all chats, composer tabs, and agent sessions.
+  - **Cursor**: [not checked] Centralized MCP server lifecycle.
+  - **Windsurf**: [not checked] Centralized MCP server lifecycle.
+  - **Claude Desktop**: [not checked] Centralized MCP server lifecycle.
+
+If two agents in a shared-process app call `hive_join` with different names, the server refuses the second join with **`Q637`** to protect the first agent from being silently replaced.
+
+To run two or more agents concurrently in a shared-process app (e.g. `frontend-bot` and `backend-bot`), register a second MCP server entry in your config pointing to the same runtime copy:
+
+```json
+{
+  "mcpServers": {
+    "hivecode": {
+      "command": "node",
+      "args": ["<your home>/.hivecode/runtime/<version>/node_modules/hivecode-mcp/hive-mcp.js"]
+    },
+    "hivecode-2": {
+      "command": "node",
+      "args": ["<your home>/.hivecode/runtime/<version>/node_modules/hivecode-mcp/hive-mcp.js"]
+    }
+  }
+}
+```
+
+Restart your app. A host that shares MCP servers exposes **all** configured servers to **every** chat — nothing automatically routes `hivecode-2` to Agent 2. You must explicitly prompt each agent which server to use (for example: *"You use only the hivecode-2 tools"*), or both agents will attempt to call `hive_join` on `hivecode`, where `Q637` will refuse the second agent.

package/docs/QUICKSTART.md

@@ -0,0 +1,266 @@
+# Quickstart: Zero to a Pull Request in 10 Minutes
+
+Connect an AI coding agent to your GitHub repository so that adding a `hivecode` label to an issue runs the agent in an isolated workspace and opens a tested pull request.
+
+---
+
+## Step 1: Prerequisites
+
+Ensure you have the following installed on your machine:
+
+1. **Node.js** (`>=18`, per `package.json` engines):
+   ```bash
+   node -v
+   ```
+2. **GitHub CLI** (`gh`):
+   ```bash
+   gh --version
+   ```
+   If missing, install it from [cli.github.com](https://cli.github.com).
+3. **An AI coding agent CLI** (such as Claude Code):
+   ```bash
+   claude --version
+   ```
+
+---
+
+## Step 2: Configure Your Agent (`setup`)
+
+Run `setup` to install the runtime and configure the `hivecode` MCP server into your agent apps:
+
+**Bash & PowerShell:**
+```bash
+npx -y hivecode-mcp@latest setup
+```
+
+### What Success Looks Like
+`setup` verifies each agent by performing an MCP handshake with its configuration:
+```
+  Claude Code     READY   configured in ~/.claude.json  (starts in 0.3s)
+  stop gate       added to ~/.claude/settings.json: in a room, Claude Code is not let end a turn with no listener running
+```
+
+### Likely Failure & Fix
+If an agent configuration file cannot be updated:
+```
+  Claude Code     FAILED  ~/.claude.json
+                  written, but it does not start: <error>
+```
+**Fix:** Add the `hivecode` server entry by hand to your agent's MCP settings:
+```json
+{
+  "mcpServers": {
+    "hivecode": {
+      "command": "node",
+      "args": ["<path-to-runtime>/hive-mcp.js"]
+    }
+  }
+}
+```
+
+---
+
+## Step 3: Authenticate with GitHub (`gh auth login`)
+
+Run this inside your local clone of the repository you want to watch:
+
+```bash
+gh auth login
+```
+
+Follow the interactive prompts to log in via your browser.
+
+### What Success Looks Like
+`gh` confirms you're logged in and displays your active account.
+
+### Likely Failure & Fix
+If `gh` is not logged in, network is down, or you run outside a repository:
+- `Q600 gh is not logged in on this machine. Run: gh auth login (or set GH_TOKEN)`
+  **Fix:** Complete `gh auth login` or set `GH_TOKEN`.
+- `Q601 GitHub has no repository <owner>/<repo> that <login> can see (HTTP 404). Check origin (<url>); a private repo needs an account with access to it (gh auth status shows which one gh uses).`
+  **Fix:** Verify `git remote -v` points to the intended repository, and confirm `gh auth status` shows an account with read access to it.
+- `Q601 <cwd> is not inside a git repository. Run this in your clone of the repo.`
+  **Fix:** `cd` into your git clone before running.
+- `Q601 origin (<url>) is not a github.com repository.`
+  **Fix:** Verify `git remote -v` points to GitHub.
+- `Q601 the GitHub account gh is logged in as cannot push to <owner>/<repo>.`
+  **Fix:** Ensure your GitHub account has write permissions to push branches.
+- `Q603 could not reach GitHub for <endpoint>: <error>`
+  **Fix:** Check your network connection to `github.com`.
+
+---
+
+## Step 4 (Optional): Connect Slack
+
+To receive per-issue progress updates and stop runs directly from Slack:
+
+1. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) by selecting **From a manifest** and pasting [`slack-app-manifest-inbound.json`](../slack-app-manifest-inbound.json).
+2. Install the app to your workspace to generate your **Bot User OAuth Token** (`xoxb-...`).
+3. Under **Basic Information > App-Level Tokens**, create a token with the `connections:write` scope to generate your **App Token** (`xapp-...`).
+4. In Slack, invite the bot to your channel: `/invite @Hivecode`.
+
+> **One Slack app per process:** Each process that reads Slack (e.g. `github start --slack-allow`, `slack start`, or `hive-slack-agent`) needs its own dedicated Slack app and App Token (`xapp-...`). Slack Socket Mode distributes incoming messages across all active connections on the same token without channel routing; sharing an app between the watcher and a room bridge will cause stop commands and thread replies to split between the two processes (`Q635`).
+
+Set the tokens in your shell:
+
+**Bash:**
+```bash
+export SLACK_BOT_TOKEN="xoxb-..."
+export SLACK_APP_TOKEN="xapp-..."
+```
+
+**PowerShell:**
+```powershell
+$env:SLACK_BOT_TOKEN="xoxb-..."
+$env:SLACK_APP_TOKEN="xapp-..."
+```
+
+Verify your Slack setup before starting:
+
+**Bash & PowerShell:**
+```bash
+npx -y hivecode-mcp@latest slack check --channel <channel-id>
+```
+
+### What Success Looks Like
+```
+✓ token: @Hivecode (U0123456789)
+✓ workspace: YourTeam (T0123456789)
+✓ channel: #dev-feed (C0123456789, member)
+✓ scopes (outbound + inbound): chat:write, channels:read, groups:read, channels:history, groups:history, users:read
+✓ Socket Mode: connected
+This posts one message in #dev-feed (and one reply in its thread)
+✓ replies reach Hivecode
+```
+
+### Likely Failure & Fix
+```
+Q631 @Hivecode is not a member of #dev-feed (C0123456789). In Slack, open #dev-feed and run: /invite @Hivecode
+```
+**Fix:** Open the channel in Slack and type `/invite @Hivecode`.
+
+---
+
+## Step 5: Start the GitHub Watcher
+
+To inspect all available watcher options and flags (exits 0):
+```bash
+npx -y hivecode-mcp@latest github --help
+```
+
+### 1. Test with a Dry Run First
+Verify permissions and agent configuration without modifying your repository:
+
+**Bash:**
+```bash
+npx -y hivecode-mcp@latest github start --dry-run \
+  --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode"
+```
+
+**PowerShell:**
+```powershell
+npx -y hivecode-mcp@latest github start --dry-run `
+  --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode'
+```
+
+#### What Success Looks Like
+```
+Dry run: reading GitHub once. Nothing is written anywhere.
+created the label "hivecode"
+claude can use Hivecode (its hivecode MCP server: Connected).
+Dry run done: no open issue is labelled "hivecode". Nothing was written.
+```
+
+### 2. Start the Live Watcher
+Once the dry run succeeds, start the live watcher.
+
+**Bash (standalone):**
+```bash
+npx -y hivecode-mcp@latest github start \
+  --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode"
+```
+
+**PowerShell (standalone):**
+```powershell
+npx -y hivecode-mcp@latest github start `
+  --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode'
+```
+
+**With Slack Integration:**
+
+**Bash:**
+```bash
+npx -y hivecode-mcp@latest github start \
+  --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode" \
+  --slack-channel <channel-id> \
+  --slack-allow <user-id>
+```
+
+**PowerShell:**
+```powershell
+npx -y hivecode-mcp@latest github start `
+  --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode' `
+  --slack-channel <channel-id> `
+  --slack-allow <user-id>
+```
+
+#### What Success Looks Like
+```
+Hivecode is watching <owner>/<repo> for issues labelled "hivecode". Ctrl+C stops it.
+```
+With Slack enabled:
+```
+Slack: `stop` in an issue's thread stops it; `retry` works for <user-id>.
+```
+
+### Likely Failure & Fix
+- If the agent lacks the MCP server:
+  ```
+  Q602 claude has no hivecode MCP server, so it cannot join a room: every run would fail after spending tokens.
+  Run: npx -y hivecode-mcp@latest setup
+  (or --skip-agent-check if it is set up under another name).
+  ```
+  **Fix:** Run `npx -y hivecode-mcp@latest setup` and restart your terminal.
+- If `--allowedTools` is missing `mcp__hivecode`:
+  ```
+  Q602 the agent command passes --allowedTools without mcp__hivecode, so it may not call hive_join and every run would fail after spending tokens. Add mcp__hivecode to its --allowedTools.
+  ```
+  **Fix:** Include `mcp__hivecode` in the `--allowedTools` list.
+
+---
+
+## Step 6: Label an Issue, Observe, and Stop
+
+### 1. Label an Issue
+Open an issue on GitHub and add the `hivecode` label.
+
+### 2. What You See
+- **In your terminal:**
+  ```
+  <HH:MM:SS> #12: queued (labelled by <user>)
+  <HH:MM:SS> #12: run 1 of 6 started (build) in room <room-id>
+  <HH:MM:SS> #12: pull request #13 opened
+  ```
+- **On the GitHub Issue:**
+  Hivecode comments immediately upon claiming:
+  ```
+  Hivecode is working on this. The pull request will be linked here when it is ready.
+
+  To stop, remove the `hivecode` label or comment `/hivecode stop`.
+  ```
+- **On the Pull Request:**
+  Hivecode creates a pull request linked to `#12` containing:
+  - A summary of what the agent changed.
+  - The test command executed and its output.
+  - A table of commits with the agent named as author and a signed trailer.
+- **In Slack (if enabled):**
+  A dedicated thread opens for the issue posting progress milestones and the pull request link.
+
+### 3. How to Stop
+You can cancel an in-progress run or watcher at any time:
+- **On GitHub:** Remove the `hivecode` label from the issue, or post a comment containing `/hivecode stop`.
+- **In Slack:** Reply `stop` in the issue's Slack thread.
+- **In your terminal:** Press `Ctrl+C`. The watcher halts gracefully:
+  ```
+  <HH:MM:SS> stopping: ending the runs in progress
+  ```

package/docs/SELF_HOSTING.md

@@ -183,7 +183,7 @@ A human client shows the same thing in the join banner: `relay: <url>  [VERDICT]
 teammate says they are in the room and your relay's count did not move, they are in
 *a* room — just not on your relay.
 
-You can prove the whole path on your own machine in about a minute:
+You can prove the whole path on your own machine in about a minute, from a clone of the repo:
 
 ```bash
 node tests/self-host-test.mjs
@@ -200,7 +200,7 @@ relay. It is the evidence behind every claim on this page.
 | Env var | Why you want it |
 |---|---|
 | `HIVE_AUTH_MODE=required` + `HIVE_JWT_SECRET=<secret>` | Every connection must present a valid token. This is your invite-only control. `npx hivecode-relay --secret <secret>` sets both. Mint tokens with `npx hivecode-token --room <room> --name <who> --role writer --ttl 7d` on the relay host, which is the only machine that holds the secret. See [RBAC.md](RBAC.md). |
-| `HIVE_PERSIST_DIR=/var/data/hive` | **Important.** Without it a room lives only in connected clients' memory and is **lost the moment everyone disconnects** — the day works perfectly and the folder is empty in the morning. `npx hivecode-relay` turns this on by default; `node server.js` does not. |
+| `HIVE_PERSIST_DIR=/var/data/hive` | **Important.** Without it a room lives only in connected clients' memory and is **lost the moment everyone disconnects** — the day works perfectly and the folder is empty in the morning. `npx hivecode-relay` turns this on by default; running the relay from a clone of the repo (`node server.js`) does not. |
 | `HIVE_SEATS=<n>` | Per-room connection budget (8 per seat). It does **not** raise the whole-relay total — that is `HIVE_MAX_CONNS_TOTAL`. The free-tier ceiling is 8 per room, which is **not** 8 people — see below. |
 | `HIVE_AUDIT_FILE=./audit.log` | One line per admit and reject. This is your evidence of who connected and when. |
 | `HIVE_RELAY_MUX=off` | Turns off one-socket-per-participant mode. It is on by default; this is the kill switch, and clients already connected fall back to one socket per file by themselves. |