hivecode-mcp 0.12.4 → 0.13.1

package/docs/SLACK_SETUP.md

@@ -0,0 +1,450 @@
+# Slack Setup (Under 10 Minutes)
+
+Hivecode posts to Slack using **one thread per task** (for a live room) or **one thread per GitHub issue** (for the GitHub watcher). Only the opening message and the final outcome appear in the main channel; intermediate claims, gate checks, CI runs, and untasked room chatter stay inside threads so your channel is never flooded.
+
+---
+
+## 1. Create the Slack App from the Manifest (2 minutes)
+
+1. Open [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** → **From a manifest**.
+2. Pick your Slack workspace and switch the tab to **JSON**.
+3. Paste the contents of [`slack-app-manifest.json`](../slack-app-manifest.json):
+
+```json
+{
+  "display_information": {
+    "name": "Hivecode",
+    "description": "One Slack thread per task or GitHub issue for Hivecode rooms.",
+    "background_color": "#111318"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Hivecode",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "chat:write",
+        "channels:read",
+        "groups:read"
+      ]
+    }
+  },
+  "settings": {
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": false,
+    "token_rotation_enabled": false
+  }
+}
+```
+
+4. Click **Next** → **Create**, then click **Install to Workspace** and **Allow**.
+5. In the left sidebar under **OAuth & Permissions**, copy the **Bot User OAuth Token** (`xoxb-…`). (After inviting `@Hivecode` to your channel in Step 2, run `SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest slack check --channel C0123456789` to verify the app end to end.)
+
+---
+
+## 2. Invite `@Hivecode` to Your Channel & Copy the Channel ID (1 minute)
+
+1. In Slack, open the channel where you want threads posted and invite the bot:
+   ```text
+   /invite @Hivecode
+   ```
+2. Right-click the channel name (or click the channel header at the top) → **View channel details**.
+3. Scroll to the bottom of the dialog and copy the **Channel ID** (looks like `C0123456789`).
+4. Run **`slack check`** to prove your token, workspace, channel membership, scopes, and (when `SLACK_APP_TOKEN` is set) inbound Socket Mode event subscriptions work end to end before starting any workflow:
+   ```bash
+   SLACK_BOT_TOKEN=xoxb-… [SLACK_APP_TOKEN=xapp-…] npx -y hivecode-mcp@latest slack check --channel C0123456789
+   ```
+   *(This posts one message in `#your-channel` — `"Hivecode check: reply anything in this thread"` — and one reply in its thread once your reply arrives.)*
+
+---
+
+## 3. Run `slack check` First, Then Start
+
+Before starting a room bridge or the GitHub watcher, run **`slack check`** once. It verifies each piece of your Slack app in order (`token`, `workspace`, `channel`, `scopes`, `Socket Mode`), then posts `"Hivecode check: reply anything in this thread"` in `#your-channel` and waits up to 2 minutes for your reply so you know outbound posting **and** inbound event subscriptions actually work end to end.
+
+**macOS / Linux (bash, zsh):**
+```bash
+# Outbound only (3-scope manifest):
+SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest slack check --channel C0123456789
+
+# Outbound + inbound stop/retry/replies (Socket Mode manifest):
+SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… npx -y hivecode-mcp@latest slack check --channel C0123456789
+
+# Slack AI Agent surface + native stop button (Paid Slack plan manifest):
+SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… npx -y hivecode-mcp@latest slack check --channel D0123456789 --agent
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:SLACK_BOT_TOKEN="xoxb-…"
+$env:SLACK_APP_TOKEN="xapp-…" # optional: include when using inbound stop/retry/replies or --agent
+npx -y hivecode-mcp@latest slack check --channel C0123456789
+```
+
+**What Each `slack check` Line Means & the One Fix When It Fails:**
+
+| Failing Step / Line | Cause | The One Fix |
+| :--- | :--- | :--- |
+| **`Q630 SLACK_BOT_TOKEN is missing` / `rejected by Slack (invalid_auth)`** | `SLACK_BOT_TOKEN` is unset, pasted from the wrong field, or revoked. | Copy the **Bot User OAuth Token** (`xoxb-…`) from **OAuth & Permissions** in your Slack app settings and export `SLACK_BOT_TOKEN` in the same terminal. |
+| **`Q634 Slack auth.test did not return a workspace team_id`** | Slack did not associate the token with a workspace. | Reinstall the app to your workspace under **OAuth & Permissions → Reinstall to Workspace**. |
+| **`Q631 @Hivecode is not a member of #channel`** | The bot has not been invited to the target channel. | Open `#channel` in Slack and run `/invite @Hivecode`. |
+| **`Q631 Slack channel … could not be accessed (missing_scope: needs groups:read)`** | Target channel is private, or the bot lacks the channel read scope (`needed` scope named in error). | Add the named scope (`groups:read` / `channels:read`) under **OAuth & Permissions → Bot Token Scopes** and click **Reinstall to Workspace**. |
+| **`Q634 SLACK_BOT_TOKEN is missing required inbound scope(s): users:read, channels:history`** | `SLACK_APP_TOKEN` is set for inbound `stop`/`retry`, but the app was created from the outbound-only manifest. | Recreate or update the app's manifest from [`slack-app-manifest-inbound.json`](../slack-app-manifest-inbound.json) (Section 5 below) and click **Reinstall to Workspace**. |
+| **`Q634 SLACK_BOT_TOKEN is missing required agent scope(s): assistant:write, im:history`** | `--agent` (or `hive-slack-agent.js`) was started with a token from the outbound or inbound-only manifest. | Update the app's manifest from [`slack-app-manifest-agent.json`](../slack-app-manifest-agent.json) (Section 5 below) and click **Reinstall to Workspace**. |
+| **`Q634 SLACK_APP_TOKEN was rejected` / `Socket Mode did not open (no hello frame)`** | Socket Mode is disabled in the Slack app, or `SLACK_APP_TOKEN` (`xapp-…`) lacks `connections:write`. | Enable **Socket Mode** in your Slack app settings and generate a new App-Level Token (`xapp-…`) with `connections:write` under **Basic Information → App-Level Tokens**. |
+| **`Q634 Slack agents.sessions.setStatus returned warning missing_agent_session_stopped_event_subscription`** | `--agent` checked `agents.sessions.setStatus`, and Slack reported that `agent_session_stopped` is not subscribed (so the native stop button is not rendered). | Subscribe to `agent_session_stopped` by updating your app's manifest from [`slack-app-manifest-agent.json`](../slack-app-manifest-agent.json) and reinstalling. |
+| **`Q634 Slack agents.sessions.setStatus failed (feature_disabled)`** | The workspace is on a Free Slack plan or Agents & Assistants is disabled for the workspace. | Use [`slack-app-manifest-inbound.json`](../slack-app-manifest-inbound.json) for typed `stop` / `retry` in channel threads (works on all Slack plans), or enable Agents & Assistants on a paid Slack plan. |
+| **`Q634 Slack agents.sessions.setStatus failed (thread_ts_required)`** | Slack rejected `agents.sessions.setStatus` because the DM session requires a valid `thread_ts`. | Run `slack check --channel <D…> --agent` on a DM or channel where `@Hivecode` can post a thread root message first. |
+| **`Q634 replies did not arrive. Event subscriptions are probably missing`** | You replied in the check thread, but Slack never sent the event (`message.channels` / `message.groups` / `message.im` not subscribed). | Update your app's manifest with [`slack-app-manifest-inbound.json`](../slack-app-manifest-inbound.json) (or [`slack-app-manifest-agent.json`](../slack-app-manifest-agent.json) for `--agent`) and reinstall the app. |
+| **`Q635 Another process is already connected to Slack Socket Mode`** | Another running terminal or service is connected with the same `SLACK_APP_TOKEN` (e.g. `slack start`, `github start --slack-allow`, or `hive-slack-agent`). | Use a separate Slack app per process that reads Slack. If you recently stopped a bridge or watcher, wait a minute for Slack to release the socket and retry. |
+
+Once `slack check` passes, you can also run `--dry-run` on `slack start` or `github start` before launching:
+
+### Option A — Bridge a Live Hivecode Room (`slack start`)
+
+> **Where do I get the `"wss://…|room-…"` link?** Running `npx -y hivecode-mcp@latest branch <name>` or `npx -y hivecode-mcp@latest setup` prints your room's `wss://…|room-…` link.
+
+**macOS / Linux (bash, zsh):**
+```bash
+# 1. Verify token and channel membership first
+SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --dry-run
+
+# 2. Start the live bridge
+SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:SLACK_BOT_TOKEN="xoxb-…"
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --dry-run
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789
+```
+
+**Windows (Command Prompt / `cmd.exe`):**
+```cmd
+set SLACK_BOT_TOKEN=xoxb-…
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --dry-run
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789
+```
+
+---
+
+### Option B — One Slack Thread per GitHub Issue (`github start --slack-channel`)
+
+When running the GitHub issue watcher (`docs/GITHUB_WORKFLOW.md`), pass `--slack-channel <id>` with `SLACK_BOT_TOKEN` set in your environment. Each labelled issue opens one Slack thread; PR ready for review, waiting on a person, and merged/closed are posted in the thread and broadcast to the channel (`reply_broadcast`), while run start, CI failures, the tester's verdict, fixes pushed to the PR, resumed, and stopped stay inside the thread only.
+
+If you also set `SLACK_APP_TOKEN=xapp-…` (see Section 5), replying `stop` in an issue's Slack thread stops that issue's run (and posts `/hivecode stop` on GitHub), and replying `retry` re-runs it for Slack user IDs listed in `--slack-allow <U123,U456>`.
+
+**macOS / Linux (bash, zsh):**
+```bash
+# 1. Dry-run first (checks gh auth, repo, and Slack token/channel)
+SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest github start --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode" --slack-channel C0123456789 --dry-run
+
+# 2. Start watching issues
+SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest github start --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode" --slack-channel C0123456789
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:SLACK_BOT_TOKEN="xoxb-…"
+npx -y hivecode-mcp@latest github start --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode' --slack-channel C0123456789 --dry-run
+npx -y hivecode-mcp@latest github start --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode' --slack-channel C0123456789
+```
+
+**Windows (Command Prompt / `cmd.exe`):**
+```cmd
+set SLACK_BOT_TOKEN=xoxb-…
+npx -y hivecode-mcp@latest github start --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode" --slack-channel C0123456789 --dry-run
+npx -y hivecode-mcp@latest github start --agent "claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode" --slack-channel C0123456789
+```
+
+---
+
+## 4. What Gets Posted (and What Is Scrubbed)
+
+| Source | Shown in Channel | Inside the Thread Only |
+| :--- | :--- | :--- |
+| **GitHub Watcher (`--slack-channel`)** | Thread opening post (`#12 — Title`), plus thread replies broadcast to the channel (`reply_broadcast`): PR ready for review, waiting on a person (`hivecode:needs-human`), merged / closed | Run started, CI failed, the tester's verdict, resumed, stopped |
+| **Room Bridge (`slack start`)** | `task-open` and `task-done` | Gate pass/fail (`gate-pass`, `gate-fail`), task chat, and all untasked room chat (grouped inside one shared room thread so chatter never floods the channel) |
+
+- **What `slack start` announces, and when**: it watches the room's task list and gate results as well as its chat. A new task opens its thread (and appears in the channel); when the assignee completes it, the "done" reply is also broadcast to the channel. A gate pass or fail is posted inside the shared room thread. The first time a bridge ever attaches to a room it only records what is already there, so starting it never replays the room's history; what it has announced is kept in room state (`slack_seen`), so a restart does not repeat itself. A forced gate release is not posted as a gate result: it is already in room chat.
+- **Secret & Room Link Scrubbing**: Every message passes through `scrubSlack()` before leaving your machine. API keys, tokens, bearer headers, room capability links (`wss://…|room-…`), and room IDs (`room-…`) are stripped automatically.
+- **Rate Limits & Retries**: Slack's ~1 message/second per-channel pacing is enforced by a single outbound queue. HTTP `429` (`ratelimited`) responses are retried up to 5 times honouring `Retry-After`.
+- **Durable Thread State**: Thread timestamps (`thread_ts`) are stored in room state (`slack_threads` map) for `slack start` and in `.git/hivecode/github.json` for `github start --slack-channel`, so restarting the process continues posting into the existing Slack thread.
+
+---
+
+## 5. Stopping Agents & Replying from Slack (Optional — Socket Mode)
+
+By default, `slack-app-manifest.json` requests only the three outbound scopes (`chat:write`, `channels:read`, `groups:read`). If you also want to **stop/resume agents** or **reply in task threads** from Slack (with zero public webhook URL), enable **Socket Mode**:
+
+### Privacy & Scope Notice
+Inbound Socket Mode requires adding `channels:history`, `groups:history`, and `users:read` to **Bot Token Scopes**, plus an **App-Level Token** (`SLACK_APP_TOKEN=xapp-…`) with `connections:write` and Event Subscriptions for `message.channels` and `message.groups`.
+> **Plain-spoken scope warning:** `channels:history` and `groups:history` let the bot read every message posted in the channels you invite it to. If you only want outbound thread feeds, keep the default 3-scope manifest above.
+
+<details>
+<summary><strong>Optional Inbound Manifest (Socket Mode enabled — <code>slack-app-manifest-inbound.json</code>)</strong></summary>
+
+Paste the contents of [`slack-app-manifest-inbound.json`](../slack-app-manifest-inbound.json):
+
+```json
+{
+  "display_information": {
+    "name": "Hivecode",
+    "description": "One Slack thread per task or GitHub issue, with inbound stop and thread replies.",
+    "background_color": "#111318"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Hivecode",
+      "always_online": true
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "chat:write",
+        "channels:read",
+        "groups:read",
+        "channels:history",
+        "groups:history",
+        "users:read"
+      ]
+    }
+  },
+  "settings": {
+    "event_subscriptions": {
+      "bot_events": [
+        "message.channels",
+        "message.groups"
+      ]
+    },
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": true,
+    "token_rotation_enabled": false
+  }
+}
+```
+</details>
+
+### Generating the App-Level Token (`SLACK_APP_TOKEN`)
+1. In your Slack app settings, go to **Basic Information** and scroll down to **App-Level Tokens**.
+2. Click **Generate Token and Scopes**.
+3. Enter `socket-mode` as the **Token Name** (required by Slack), click **Add Scope**, select `connections:write`, and click **Generate**.
+4. Copy the resulting `xapp-…` token and set it as `SLACK_APP_TOKEN`.
+
+### Who May Act (`--allow` / `--slack-allow`) & No Impersonation
+- **STOP is fail-safe**: Any full member of your Slack workspace may type `stop`, `stop all`, or `stop <AgentName>` in a thread to pause agents (or stop an active GitHub issue run) immediately. If Slack's `users.info` endpoint fails during an outage, `stop` still succeeds and notes `(stopped; I could not confirm who you are)`.
+- **RESUME, RETRY, and thread replies require the allowlist (`--allow U123,U456` on `slack start`, or `--slack-allow U123,U456` on `github start`)**: Only Slack user IDs explicitly listed in the allowlist (find yours in Slack under **Profile → `⋯` → Copy member ID**) may resume agents (`resume`, `resume all`, `resume <AgentName>`), retry a GitHub issue run (`retry`), or send replies into the room. If the allowlist is omitted, inbound is **stop-only**.
+- **Guests & Slack Connect users are refused**: Single-channel/multi-channel guests (`is_restricted` / `is_ultra_restricted`) and external Slack Connect users from other workspaces (`team_id` mismatch via `users.info`) are refused for all actions (including `stop`) and receive a refusal reply in the thread.
+- **One Slack app per process (Socket Mode multi-connection guard)**: Each process that reads Slack (`slack start`, `github start --slack-allow`, or `hive-slack-agent`) requires its own dedicated Slack app and App-Level Token (`xapp-…`). Slack Socket Mode supports up to 10 connections per token and arbitrarily distributes incoming events across them without channel routing. Sharing an app token across two processes causes events (including `stop all` and thread replies) to split between the two processes (`Q635`).
+- **No impersonation (`slack:<handle>`)**: Every message delivered from Slack into the room is attributed as `slack:<handle>` (for example, `slack:ganesh`), never as a bare room member name (`Ganesh`), so a Slack display name cannot impersonate the room owner.
+
+### Free vs Paid Slack Plans & the Slack AI Agent Surface (`hive-slack-agent.js`)
+- **Typed `stop` works on every Slack plan (including Free)**: Replying `stop`, `stop all`, `stop <AgentName>`, `resume <AgentName>`, or `retry` in a channel thread requires only standard channel events (`slack-app-manifest-inbound.json`) and works on **all Slack plans**. We keep `slack-app-manifest-inbound.json` separate from `slack-app-manifest-agent.json` so Free-plan workspaces can install inbound `stop`/`retry` without hitting `feature_disabled`.
+- **Native AI stop button & streamed plan cards (`hive-slack-agent.js`) require a paid Slack plan**: `hive-slack-agent.js` renders live room tasks as a streamed plan (`chat.startStream` / `chat.appendStream` / `chat.stopStream` with `task_display_mode: "plan"`) and enables Slack's native stop button via `agents.sessions.setStatus` (`status: "processing"` / `"active"`) and `agent_session_stopped`.
+- **Who may act on the agent surface (same rules as `slack start`)**: `hive-slack-agent.js` checks every sender with the same `makeSlackActorCheck` rules. Any full workspace member may `stop` / `stop all` (or press Slack's native stop button); if Slack's `users.info` is down it still stops, and says `(stopped; I could not confirm who you are)`. `resume` needs the sender's member ID in `--allow <U123,U456>` (or `SLACK_ALLOW`). Guests and users from other workspaces are refused for everything, `status` included, and are told so in the thread; the room's tasks are never streamed to them. At startup it needs your workspace id from `auth.test` (refused with `Q634` if Slack omits it). A typed message counts only in the configured `--channel` or in a DM with the app (each user's own assistant DM is answered in that DM); messages from any other channel the bot is in are ignored.
+- **Official Slack requirements for `hive-slack-agent.js`**:
+  - **Bot Token Scopes**: `chat:write` ([`chat.startStream`](https://docs.slack.dev/reference/methods/chat.startStream)), `assistant:write` ([`agents.sessions.setStatus`](https://docs.slack.dev/reference/methods/agents.sessions.setStatus) and [`agent_session_stopped`](https://docs.slack.dev/reference/events/agent_session_stopped)), `im:history`, `im:read`, `im:write` ([Developing AI Apps](https://docs.slack.dev/ai/developing-ai-apps)), plus `channels:read`, `groups:read`, `channels:history`, `groups:history`, `users:read`.
+  - **Bot Events**: `agent_session_stopped` ([`agent_session_stopped` event](https://docs.slack.dev/reference/events/agent_session_stopped)), `assistant_thread_started`, `assistant_thread_context_changed`, `message.im`, `message.channels`, `message.groups`.
+  - **App Settings**: `features.assistant_view` (`assistant_description` and `suggested_prompts`) and `settings.socket_mode_enabled: true` ([Agent Sessions](https://docs.slack.dev/ai/agent-sessions)).
+  - **Startup & `slack check --agent` verification**:
+    - At startup, `hive-slack-agent.js` (`preflightSlackAgent`) checks `x-oauth-scopes` from `auth.test` via `checkAgentScopes` and refuses with `Q634` (naming missing scopes such as `assistant:write, im:history` and `slack-app-manifest-agent.json`) before opening Socket Mode.
+    - Running `SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… npx -y hivecode-mcp@latest slack check --channel D0123456789 --agent` verifies those scopes, posts a check message (`checkTs`), and calls `agents.sessions.setStatus({ status: 'processing', channel_id, thread_ts: checkTs })`. Per Slack's [`agent_session_stopped` docs](https://docs.slack.dev/reference/events/agent_session_stopped), if your app is not subscribed to `agent_session_stopped`, Slack returns a `missing_agent_session_stopped_event_subscription` warning (checked in both top-level `warning` and `response_metadata.warnings[]`) and renders a non-interactive spinner instead of the stop button; `slack check --agent` catches that warning (as well as `feature_disabled` and `thread_ts_required`) and refuses with `Q634`. On every exit path (pass, fail, timeout, or `Ctrl+C`), `slack check --agent` clears the session status back to `active` in a `finally` block so the DM is never left spinning.
+    - *(Note: `features.assistant_view` and `suggested_prompts` control the top-bar split-view UI in Slack and cannot be probed via a Web API read call; installing from `slack-app-manifest-agent.json` configures them declaratively.)*
+
+**Starting the Agent Surface (`slack agent`):**
+
+macOS / Linux (bash, zsh):
+```bash
+SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… npx -y hivecode-mcp@latest slack agent "wss://hivecode-relay.onrender.com|room-abc123" --channel D0123456789 --allow U012ABCDEF
+```
+
+Windows (PowerShell):
+```powershell
+$env:SLACK_BOT_TOKEN="xoxb-…"
+$env:SLACK_APP_TOKEN="xapp-…"
+npx -y hivecode-mcp@latest slack agent "wss://hivecode-relay.onrender.com|room-abc123" --channel D0123456789 --allow U012ABCDEF
+```
+
+<details>
+<summary><strong>Optional Paid-Plan AI Agent Surface Manifest (<code>slack-app-manifest-agent.json</code>)</strong></summary>
+
+Paste the contents of [`slack-app-manifest-agent.json`](../slack-app-manifest-agent.json):
+
+```json
+{
+  "display_information": {
+    "name": "Hivecode",
+    "description": "AI agent panel, native stop button, and one Slack thread per task or GitHub issue.",
+    "background_color": "#111318"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Hivecode",
+      "always_online": true
+    },
+    "assistant_view": {
+      "assistant_description": "Inspect live Hivecode rooms, stream task plans, and halt or resume AI agents from Slack.",
+      "suggested_prompts": [
+        {
+          "title": "What is running?",
+          "message": "status"
+        },
+        {
+          "title": "Stop everything",
+          "message": "stop all"
+        },
+        {
+          "title": "What happened overnight?",
+          "message": "what happened overnight"
+        }
+      ]
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "chat:write",
+        "assistant:write",
+        "im:history",
+        "im:read",
+        "im:write",
+        "channels:read",
+        "groups:read",
+        "channels:history",
+        "groups:history",
+        "users:read"
+      ]
+    }
+  },
+  "settings": {
+    "event_subscriptions": {
+      "bot_events": [
+        "agent_session_stopped",
+        "assistant_thread_started",
+        "assistant_thread_context_changed",
+        "message.im",
+        "message.channels",
+        "message.groups"
+      ]
+    },
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": true,
+    "token_rotation_enabled": false
+  }
+}
+```
+</details>
+
+**macOS / Linux (bash, zsh):**
+```bash
+SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF --dry-run
+SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:SLACK_BOT_TOKEN="xoxb-…"
+$env:SLACK_APP_TOKEN="xapp-…"
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF --dry-run
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF
+```
+
+**Windows (Command Prompt / `cmd.exe`):**
+```cmd
+set SLACK_BOT_TOKEN=xoxb-…
+set SLACK_APP_TOKEN=xapp-…
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF --dry-run
+npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF
+```
+
+### Slackbot Remote MCP Server (`hive-mcp-http.js`)
+
+If you connect Slackbot's remote MCP client over Streamable HTTP (`hive-mcp-http.js`), it exposes fast room inspection and control tools (`hive_status`, `hive_members`, `hive_tasks`, `hive_claims`, `hive_recent`, `hive_pause`, `hive_resume`, `hive_say`).
+
+- **Requires both `SLACK_SIGNING_SECRET` and `SLACK_BOT_TOKEN`**: In `--auth slack` mode (the default), `hive-mcp-http.js` refuses to start without `SLACK_SIGNING_SECRET` (`Q510`, copied from **Basic Information → App Credentials → Signing Secret**) **and** `SLACK_BOT_TOKEN` (`Q630`, `xoxb-…` with `users:read` scope so `users.info` can verify callers).
+- **Discovers your workspace (`team_id`) from Slack at startup**: When you start `hive-mcp-http.js` without `--team` (`SLACK_TEAM_ID`), it calls Slack's `auth.test` using `SLACK_BOT_TOKEN` before serving requests. If `auth.test` rejects the token (`Q630`) or does not return a `team_id` (`Q634`), startup is refused immediately so external Slack Connect workspace users can never slip through by default.
+- **Same access rules (`makeSlackActorCheck`)**:
+  - **Every request is HMAC-verified first** (`X-Slack-Signature` + 5-minute replay window, `Q511`–`Q513`) before `_meta.slack.user_id` is read.
+  - **Guests and other workspaces are refused** for all tools (`hive_pause`, `hive_resume`, `hive_say`).
+  - **`hive_pause` (`stop`) is fail-safe** for any full member of your workspace (and fails open with `(stopped; I could not confirm who you are)` if `users.info` is unreachable during a Slack outage).
+  - **`hive_resume` and `hive_say` require `--allow <U123,U456>`** (or `SLACK_ALLOW`). Messages sent via `hive_say` are recorded in room chat as `slack:<handle>`.
+
+**macOS / Linux (bash, zsh):**
+```bash
+SLACK_SIGNING_SECRET=… SLACK_BOT_TOKEN=xoxb-… npx -y hivecode-mcp@latest slack mcp-server "wss://hivecode-relay.onrender.com|room-abc123" --port 8790 --allow U012ABCDEF
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:SLACK_SIGNING_SECRET="…"
+$env:SLACK_BOT_TOKEN="xoxb-…"
+npx -y hivecode-mcp@latest slack mcp-server "wss://hivecode-relay.onrender.com|room-abc123" --port 8790 --allow U012ABCDEF
+```
+
+**What a First-Time User Sees Step by Step (`hive-mcp-http.js`):**
+1. **If `SLACK_SIGNING_SECRET` is missing**: Process exits immediately (`code 2`) with:
+   `Q510 --auth slack needs SLACK_SIGNING_SECRET. Use --auth none only on localhost.`
+2. **If `SLACK_BOT_TOKEN` is missing**: Process exits immediately (`code 2`) with:
+   `Q630 --auth slack needs SLACK_BOT_TOKEN. Set SLACK_BOT_TOKEN=xoxb-… in your environment (docs/SLACK_SETUP.md).`
+3. **When both are set**: `hive-mcp-http.js` calls Slack `auth.test`, locks in your workspace `team_id`, joins the room, and prints:
+   `[hive-mcp-http] room room-abc123 on :8790/  auth=slack`
+4. **When someone asks Slackbot what is happening (`hive_status`)**: Returns the live room name, agent count, paused list, and task counts.
+5. **When a coworker triggers `hive_pause`**: Pauses the named agent (or `all`) on its own client (`paused AgentA — it will finish its current step and then stop picking up work`), while a guest or Slack Connect user from another workspace gets `:no_entry: Refused: guests and external Slack Connect users cannot control or message this room.`
+6. **When someone not in `--allow` triggers `hive_resume` or `hive_say`**: Refused with `:no_entry: Refused: only Slack user IDs listed in --allow may resume/retry agents or send replies into the room (your ID: U…). Any full workspace member may still type stop.` When a user listed in `--allow` calls `hive_say`, it lands in the room attributed as `slack:<handle>`.
+
+---
+
+## 6. How to Show It (Live Demo Walkthrough)
+
+> **Running from a local checkout before npm publish:** Until the latest release is published to npm (`npx -y hivecode-mcp@latest` on npm is `0.12.4` prior to release), replace `npx -y hivecode-mcp@latest` in the commands below with `node C:/Users/G1/Desktop/N-team/hive-mcp.js` (or `node ./hive-mcp.js` from your repo root).
+
+Use these 5 steps to demonstrate either **GitHub-to-Slack issue threads** (`github start --slack-channel --slack-allow`) or a **live room bridge** (`slack start --channel --allow`) end to end:
+
+1. **Install the App & Copy Tokens**:
+   - Create the Slack app from the **Optional Inbound Manifest** in Section 5 above and install it to your workspace.
+   - Copy `SLACK_BOT_TOKEN` (`xoxb-…`) from **OAuth & Permissions**, and generate `SLACK_APP_TOKEN` (`xapp-…`, named `socket-mode` with `connections:write`) under **Basic Information → App-Level Tokens**.
+2. **Invite `@Hivecode` & Copy IDs**:
+   - In your Slack channel, run `/invite @Hivecode` and copy the **Channel ID** (`C…`) from channel details.
+   - Copy your own **Slack Member ID** (`U…`) from your Slack profile (**Profile → `⋯` → Copy member ID**).
+3. **Start the Watcher or Room Bridge**:
+   - **Flow A — GitHub Issue Threads + Slack `stop` / `retry` (PowerShell):**
+     ```powershell
+     $env:SLACK_BOT_TOKEN="xoxb-…"
+     $env:SLACK_APP_TOKEN="xapp-…"
+     npx -y hivecode-mcp@latest github start --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode' --slack-channel C0123456789 --slack-allow U012ABCDEF --dry-run
+     npx -y hivecode-mcp@latest github start --agent 'claude -p --output-format json --allowedTools Bash Edit Write Read Glob Grep mcp__hivecode' --slack-channel C0123456789 --slack-allow U012ABCDEF
+     ```
+   - **Flow B — Live Room Bridge + Slack `stop` / `resume` / Thread Replies (PowerShell):**
+     ```powershell
+     $env:SLACK_BOT_TOKEN="xoxb-…"
+     $env:SLACK_APP_TOKEN="xapp-…"
+     npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF --dry-run
+     npx -y hivecode-mcp@latest slack start "wss://hivecode-relay.onrender.com|room-abc123" --channel C0123456789 --allow U012ABCDEF
+     ```
+4. **Trigger a Thread**:
+   - **In Flow A**: Add the `hivecode` label to a GitHub issue. Watch Slack open a single thread (`#12 — Title`) for that issue and post run progress inside it.
+   - **In Flow B**: Assign a task in the room. Watch Slack open a thread for that task and post gate checks and task chat inside it.
+5. **Control from the Slack Thread**:
+   - **In Flow A (`github start`)**: Reply `stop` inside the issue's Slack thread to stop the active run (posts `/hivecode stop` on GitHub and ends the room). Reply `retry` (permitted because your ID is in `--slack-allow`) to post `/hivecode retry` and start a fresh run.
+   - **In Flow B (`slack start`)**: Reply `stop all` (or `stop <AgentName>`) inside the thread to pause agents on their own clients (`controls` map -> `paused`). Reply `resume all` or reply with instructions (`@AgentName …`, delivered into the room as `slack:<your-handle>`).
+
+---
+
+## 7. Troubleshooting (`Q510` – `Q521`, `Q630` – `Q635`)
+
+| Code | Cause | Fix |
+| :--- | :--- | :--- |
+| **`Q510`** | `hive-mcp-http.js` started in `--auth slack` mode without `SLACK_SIGNING_SECRET`. | Copy your app's **Signing Secret** from **Basic Information → App Credentials** in Slack app settings and set `SLACK_SIGNING_SECRET` (or use `--auth none` on `localhost` only). |
+| **`Q511` – `Q513`** | HTTP request to `hive-mcp-http.js` is unsigned (`Q511`), outside the 5-minute replay window (`Q512`), or its HMAC signature does not match (`Q513`). | Ensure `SLACK_SIGNING_SECRET` matches the Slack app calling the endpoint and that the host clock is synced via NTP. |
+| **`Q514` - `Q521`** | `hive-mcp-http.js` answered a request it could not act on: `Q514` no participant of that name is in the room; `Q515` unknown tool; `Q516` a tool failed; `Q517` JSON-RPC method not supported; `Q518` the endpoint takes `POST` only; `Q519` request body too large; `Q520` body is not JSON; `Q521` refused by the Slack actor check (guest, other workspace, or not in `--allow`). | `Q514`: use a name from the "Here now" list in the same message. `Q515`/`Q517`: call a tool listed above (`hive_status`, `hive_members`, `hive_tasks`, `hive_claims`, `hive_recent`, `hive_pause`, `hive_resume`, `hive_say`). `Q518`/`Q520`: send a JSON-RPC `POST`. `Q519`: send a smaller body. `Q521`: add the Slack member ID to `--allow` (resume / say), or ask a full workspace member. `Q516`: read the message after it; it names the failure. |
+| **`Q630`** | `SLACK_BOT_TOKEN` is missing (required by `slack start` and by `hive-mcp-http.js` in `--auth slack` mode), invalid (`invalid_auth`), or revoked (`token_revoked`) when checked against Slack `auth.test`. | Copy the **Bot User OAuth Token** (`xoxb-…`) from **OAuth & Permissions** in your Slack app settings and set `SLACK_BOT_TOKEN` in the same terminal session. |
+| **`Q631`** | `--channel` is missing, `channel_not_found`, or `@Hivecode` has not been invited to the channel (`is_member: false` / `not_in_channel`). | Open the target channel in Slack and run `/invite @Hivecode`. If it is a private channel, ensure the app has `groups:read` scope and reinstall to workspace. |
+| **`Q632`** | Another `SlackBridge` with the same `--name` is already connected to this room. | Stop the existing `slack start` process before starting a new one so events are not posted twice. |
+| **`Q633`** | `--slack-channel` was passed to `github start`, but `SLACK_BOT_TOKEN` is not set in the environment. | Set `SLACK_BOT_TOKEN=xoxb-…` (or `$env:SLACK_BOT_TOKEN="xoxb-…"` in PowerShell) before running `github start --slack-channel`. |
+| **`Q634`** | Inbound Slack configuration cannot work safely: (1) `SLACK_APP_TOKEN` (`xapp-…`) is missing or rejected by `apps.connections.open`; (2) `--slack-allow` was passed to `github start` without `--slack-channel`, without `SLACK_APP_TOKEN`, or with usernames instead of member IDs (`U…`); or (3) Slack `auth.test` did not return a workspace `team_id` (in `github start` or `hive-mcp-http.js`), so external workspaces could not be refused. | Enable **Socket Mode** and set `SLACK_APP_TOKEN=xapp-…` (`connections:write` scope); pass Slack member IDs (`U…` from **Profile → `⋯` → Copy member ID**) to `--slack-allow` / `--allow`; or pass `--team <T…>` (`SLACK_TEAM_ID`) / reinstall the Slack app if `auth.test` omitted `team_id`. |
+| **`Q635`** | Another process is already connected to Slack Socket Mode with this `SLACK_APP_TOKEN` (Slack distributes incoming events across active connections, so messages or "stop" commands may go to the other process). | Ensure each process reading Slack (`slack start`, `github start --slack-allow`, `hive-slack-agent`) uses its own dedicated Slack app and App-Level Token. Check for another running terminal or service and stop it. If you just stopped a bridge or watcher, wait a minute for Slack to release the connection and start again. |

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,105 @@
+# Hivecode Troubleshooting & Error Code Guide
+
+This guide explains every error code (`Qxxx`) emitted by Hivecode CLI commands, bridges, sync engines, and MCP surfaces.
+
+---
+
+## Error Codes Quick Reference
+
+| Code | Printed by | What was happening | What it means | How to fix it |
+|---|---|---|---|---|
+| `Q430` | `hive-relay-health.js`, `sync.js`, `limits.js` | Connecting to a relay or syncing files | The relay is at or near its total socket connection capacity (`limits.maxConnsTotal`, HTTP 503). | Wait for other participants to disconnect, or if self-hosting, raise `HIVE_MAX_CONNS_TOTAL` in the relay environment. |
+| `Q431` | `hive-relay-health.js`, `sync.js`, `limits.js` | Joining a room (`hive_join`, `branch`, or `sync`) | The room reached its per-room connection ceiling (HTTP 429; 8 connections on the free tier). Note that each concurrently synced file holds a connection. | Close idle files or agents. If self-hosting, raise `HIVE_SEATS` on the relay. |
+| `Q432` | `limits.js` | Sending room events or HTTP MCP requests at high frequency | Message rate limit exceeded (`msgsPerSec` sustained or burst limit). | Back off and pace messages; the rate limiter automatically resets after `retryMs`. |
+| `Q433` | `limits.js` | Sending an oversized frame or message to the relay | Frame payload exceeds the maximum byte limit (`frameCap`). | Reduce message size or split file changes into smaller chunks. |
+| `Q434` | `limits.js` | Transferring large data volume in a short interval | Byte transfer rate limit exceeded (`bytesPerSec` sustained). | The connection is throttled until the byte rate recovers; avoid batching massive binary edits at once. |
+| `Q438` | `hive-relay-health.js`, `sync.js`, `limits.js` | Opening or syncing multiple files across rooms | The relay reached its total open-file capacity across all participants (`maxChannelsTotal`, HTTP 503). | Release claimed files no longer being edited. If self-hosting, raise `HIVE_MAX_CHANNELS_TOTAL` on the relay. |
+| `Q439` | `hive-relay-health.js`, `sync.js` | One participant opening or syncing many files | A single participant exceeded the maximum allowed open files limit on the relay (HTTP 503). | Close or release files that are not actively being modified. |
+| `Q470` | `sync.js`, `hive-pr.js`, `hive-github.js` | Cause 1: Syncing a local folder (`sync.js`). Cause 2: Landing a PR from room files (`hive-pr.js`). | Cause 1: Another local process is already syncing this folder (PID recorded in lock file). Cause 2: Could not reach the relay behind the room link within 20s. | Cause 1: Check running processes (`ps` / Task Manager) and stop the duplicate sync process, or remove the stale lock if crashed. Cause 2: Check internet connection and verify the relay URL is reachable. |
+| `Q490` | `sync.js`, `hive-gate.js` | Releasing a file governed by a verification gate | The verification gate command exited with a non-zero exit code or could not be run. Release is refused; file remains with holder. | Inspect the gate test output, fix the failing test or build error, and re-run. Do not force-release unless intentional. |
+| `Q491` | `sync.js`, `hive-gate.js` | Releasing a file governed by a verification gate | The verification gate command timed out before completing. Release is refused; file remains with holder. | Optimize the test suite to run faster, or adjust `timeoutMs` in the gate configuration. |
+| `Q492` | `hive-gate.js` | An operator force-releasing a file (`--force`) | Notice: a file was force-released without passing its verification gate. | Review the force-release reason posted in room chat to understand why tests were bypassed. |
+| `Q500` | `hive-pr.js` | Running `npx hivecode-mcp pr` | Target directory is not a git repository (missing `.git`). | Run the command from the root of a git repository clone. |
+| `Q501` | `hive-pr.js`, `hive-branch.js` | Running `pr` to land changes from the room | Nothing was attributed to commit (zero changes or no files modified by participants). | Verify that agents have edited files in the room before creating a PR. |
+| `Q502` | `hive-pr.js` | Running `pr` to land changes onto a new branch | Git branch creation failed (`git checkout -b <branch>`). | Check git status, resolve branch conflicts, or verify that the local git repository is in a clean state. |
+| `Q503` | `hive-pr.js` | Running `pr` to land attributed changes | Git commit failed (`git commit`) for an author attribution group. | Ensure `git config user.name` and `user.email` are set, and check for commit hook failures. |
+| `Q504` | `hive-pr.js` | Running `pr` to push changes to remote | Git push failed (`git push origin <branch>`). | Check remote permissions, network connectivity, and ensure authentication to GitHub/git remote is configured. |
+| `Q505` | `hive-pr.js` | Running `pr` to open a pull request | `gh pr create` failed when creating the pull request on GitHub. | Verify `gh auth status` and ensure the repository has a valid upstream remote on GitHub. |
+| `Q506` | `hive-pr-staleness.js` | Running `pr` to land changes | Refusing to write because the git branch moved upstream while agents were working (stale branch base). | Fetch latest changes from the branch (`git pull --ff-only` or merge), reconcile diverged files, and re-run `pr`. |
+| `Q507` | `hive-pr.js`, `hive-github.js` | Landing room work into a pull request | Partial room arrival: not all room files arrived before timeout during landing. Refusing to land incomplete work. | Ensure all agents have completed file synchronization, check network connectivity to relay, and re-run `pr`. |
+| `Q510` | `hive-mcp-http.js` | Starting `slack mcp-server` in `--auth slack` mode | `SLACK_SIGNING_SECRET` environment variable is missing. | Copy your Signing Secret from Slack App Settings (**Basic Information → App Credentials**) and set `SLACK_SIGNING_SECRET`. |
+| `Q511` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | HTTP request is missing the required `X-Slack-Signature` or `X-Slack-Request-Timestamp` headers. | Ensure the client sending requests is an official Slack webhook or computes valid Slack HMAC signatures. |
+| `Q512` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | Request timestamp is outside the 5-minute replay window. | Synchronize system clock with NTP and ensure requests are not delayed or replayed. |
+| `Q513` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | HMAC-SHA256 signature does not match the request payload. | Verify that `SLACK_SIGNING_SECRET` matches the Slack app sending the request. |
+| `Q514` | `hive-mcp-http.js` | Calling `hive_pause` or `hive_resume` via HTTP MCP | Specified participant name does not exist in the room. | Check `hive_members` to see current participants and use an exact name from the "Here now" list. |
+| `Q515` | `hive-mcp-http.js` | Calling a tool on `slack mcp-server` | Unknown tool name requested. | Use only supported tools: `hive_status`, `hive_members`, `hive_tasks`, `hive_claims`, `hive_recent`, `hive_pause`, `hive_resume`, `hive_say`. |
+| `Q516` | `hive-mcp-http.js` | Executing a tool on `slack mcp-server` | Tool execution threw an unhandled error. | Read the error message following `Q516` for specific tool diagnostics. |
+| `Q517` | `hive-mcp-http.js` | Sending JSON-RPC request to `slack mcp-server` | Method is not supported (only `initialize`, `tools/list`, and `tools/call` are supported). | Send valid JSON-RPC 2.0 MCP requests. |
+| `Q518` | `hive-mcp-http.js` | Sending GET or non-POST HTTP request to `slack mcp-server` | The MCP HTTP server endpoint accepts `POST` requests only. | Send HTTP `POST` requests with JSON payload. |
+| `Q519` | `hive-mcp-http.js` | Sending an oversized request body to `slack mcp-server` | Request payload body exceeds the maximum size limit (1 MB). | Reduce request body size or break calls into smaller batches. |
+| `Q520` | `hive-mcp-http.js` | Sending request payload to `slack mcp-server` | Request body is malformed and could not be parsed as JSON. | Validate JSON formatting in request body. |
+| `Q521` | `hive-mcp-http.js` | Calling `hive_pause`, `hive_resume`, or `hive_say` via HTTP MCP | Refused by Slack actor check: caller is a guest, external Slack Connect user, or not in `--allow`. | Full members can pause; add member ID (`U…`) to `--allow` for resume and say actions. |
+| `Q550` | `hive-privacy.js` | Connecting to a relay | Connected relay fingerprint does not match the pinned relay for this machine. | Verify the relay URL. If relay legitimately changed, update the pin file (`~/.hive-pin` or configured pin path). |
+| `Q551` | `hive-privacy.js` | Connecting to the public relay | `HIVE_PRIVATE=1` is set in environment, refusing connections to the public relay. | Pass your private self-hosted relay URL via `--relay <url>` or unset `HIVE_PRIVATE`. |
+| `Q552` | `hive-privacy.js` | Verifying relay pin configuration | The relay pin file or format is malformed or corrupted. | Check the format of the relay pin file or delete and recreate it. |
+| `Q560` | `hive-branch.js` | Running `branch <name>` | Directory is not inside a git repository, or is the user's home directory. | Run the command inside a project git repository clone. |
+| `Q561` | `hive-branch.js` | Running `branch <name>` | Invalid git branch name provided. | Use a valid git branch name conforming to `git check-ref-format`. |
+| `Q562` | `hive-branch.js` | Joining a branch room or running `branch` | Branch has no Hivecode room recorded, or repository has no commits yet. | Commit files to the repository first, or create/record room mapping with `branch <name> --join "<link>"`. |
+| `Q563` | `hive-branch.js` | Running `branch <name>` | Git error: could not read commit tree or branch does not exist locally. | Fetch the branch from remote (`git fetch origin <branch>:<branch>`) or verify branch name. |
+| `Q564` | `hive-mcp.js`, `hive-branch.js` | Checkpointing room branch progress | Checkpoint marker update failed. | Check repository write permissions and verify `.git/config` is writable. |
+| `Q565` | `hive-branch.js`, `hive-github.js` | Seeding a branch room with files | Seed files did not finish publishing within timeout or could not reach relay. | Re-run the branch seed command; check network connection to the relay. |
+| `Q566` | `hive-branch.js` | Seeding a branch room | Fresh joiner did not receive the complete branch tree (missing or divergent files). | Ensure relay has sufficient open-file capacity and re-run branch seeding. |
+| `Q567` | `hive-branch.js` | Running `branch <name> --join "<link>"` | Provided join link is invalid, or branch is already bound to a different room. | Provide a valid `wss://relay|room` link, or remove existing binding with `git config --remove-section "hivecode.<branch>"`. |
+| `Q568` | `hive-branch.js` | Reseeding a branch room (`--reseed`) | Target directory is not a room folder made by Hivecode, or room is not empty. | Reseeding only refills an empty room after relay loss. Move directory aside manually if resetting. |
+| `Q569` | `hive-branch.js` | Binding a branch to a room | Could not write room binding to `.git/config`. | Check file permissions on `.git/config` and verify disk space. |
+| `Q570` | `hive-branch.js` | Landing branch PR | Could not fast-forward branch, or branch moved upstream while landing. | Pull latest upstream commits into local branch and re-run `pr`. |
+| `Q571` | `hive-branch.js` | Landing branch PR | Working tree has uncommitted changes on the checkout branch. | Commit or stash changes (`git stash`) before landing PR. |
+| `Q572` | `hive-branch.js` | Landing branch PR | The room deleted files that were changed on the branch upstream since seeded. | Restore deleted files in the room or delete them upstream on the branch manually. |
+| `Q573` | `hive-branch.js` | Landing branch PR | Local commits landed on branch successfully, but `git push` failed. | Check remote permissions and push manually (`git push origin <branch>`). |
+| `Q574` | `hive-branch.js` | Opening PR from branch | No base branch specified to open PR into, or `gh pr create` failed. | Pass `--base <branch>` or ensure `gh` is authenticated. |
+| `Q580` | `sync.js` | Syncing a room folder | Room directory was deleted or moved while sync was active. | Recreate the folder or re-join the room; files on teammates' clients were protected. |
+| `Q581` | `hive-mcp.js` | Joining a room (`hive_join`) | Participant name is already in use by another connected participant. | Choose a distinct display name via `--name` or in `hive_join`. |
+| `Q600` | `hive-github.js` | Running `github start` or watcher background polling | GitHub CLI (`gh`) not installed, `gh auth login` required, or token expired/HTTP 401. | Install GitHub CLI (`gh`), run `gh auth login`, or set valid `GH_TOKEN`. |
+| `Q601` | `hive-github.js` | Running `github start` | Directory not in git repo, in home directory repo, origin not github.com, repo 404/invisible, or account cannot push. | Run in repository clone, verify `git remote -v`, and ensure `gh auth status` shows account with push access. |
+| `Q602` | `hive-github.js` | Running `github start` | Agent CLI not installed on PATH, invalid `--max-runs`, or missing `mcp__hivecode` in `--allowedTools`. | Install agent CLI, run `npx hivecode-mcp setup`, and ensure `--allowedTools` includes `mcp__hivecode`. |
+| `Q603` | `hive-github.js` | Watcher contacting GitHub API | Network failure reaching api.github.com or non-401 HTTP error. | Check internet connectivity and GitHub status; watcher automatically retries with backoff. |
+| `Q604` | `hive-github.js` | Watcher polling issues or PRs | GitHub secondary API rate limit hit. | Watcher automatically pauses and waits until rate limit resets before resuming. |
+| `Q605` | `hive-github.js` | Running `github start` | A watcher process is already running for this repository clone (lock held). | Stop the existing watcher process (PID named in message), or remove stale `.git/hivecode/watcher.lock`. |
+| `Q606` | `hive-github.js` | Watcher reading state | State file `.git/hivecode/github-watcher.json` is corrupted. | The corrupted state file is moved aside automatically, and watcher rebuilds state from GitHub. |
+| `Q607` | `hive-github.js` | Watcher picking up issue | Branch name collision: exhausted 50 suffix attempts (`hivecode/issue-N-49`). | Delete old merged issue branches on GitHub and locally. |
+| `Q608` | `hive-github.js` | Running `github start` | Repository has more than 5,000 files, exceeding public relay capacity. | Use your own self-hosted relay with `--relay <url>`, or pass `--allow-large`. |
+| `Q609` | `hive-github.js` | Running `github start` with `--notify` or `HIVE_NOTIFY_WEBHOOK` | The webhook given is not a web address (it must start with https:// or http://). | Copy the channel's incoming-webhook URL again from Slack or Discord. |
+| `Q610` | `hive-github.js` | Watcher fetching branches | Git remote error: could not list or fetch branches from origin. | Check network connection, git credentials, and remote repository existence. |
+| `Q611` | `hive-github.js` | Watcher creating issue branch | Branch diverged (commits on GitHub and local that are not in each other) or branch creation failed. | Reconcile branches manually and comment `/hivecode retry` on the issue. |
+| `Q612` | `hive-github.js` | Watcher updating checkpoint | Marker update failed during watcher run. | Check disk space and permissions in `.git/hivecode`. |
+| `Q630` | `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Starting Slack bridge, agent, check, or HTTP MCP | `SLACK_BOT_TOKEN` is missing, rejected (`invalid_auth`), or revoked. | Copy `xoxb-…` Bot Token from Slack App settings (**OAuth & Permissions**) and set `SLACK_BOT_TOKEN`. |
+| `Q631` | `hive-slack.js` | Starting Slack bridge or `slack check` | Missing `--channel`, channel not found, or bot not invited. | Pass `--channel <id>` and run `/invite @Hivecode` in the target Slack channel. |
+| `Q632` | `hive-slack.js` | Starting `slack start` | Another Slack bridge with the same name is already running in the room. | Stop the other bridge before starting a new one, or pass a different `--name`. |
+| `Q633` | `hive-github.js` | Starting `github start --slack-channel` | Slack bridge failed to load, missing `SLACK_BOT_TOKEN`, or missing `makeSlackThreader`. | Ensure `SLACK_BOT_TOKEN` is set and `hivecode-mcp` installation is intact. |
+| `Q634` | `hive-github.js`, `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Cause 1: Missing scopes (`users:read`, `channels:history`, `groups:history`, `assistant:write`). Cause 2: Missing or invalid `SLACK_APP_TOKEN` (`xapp-…`). Cause 3: Invalid allowlist member ID (not `U…`/`W…`). Cause 4: Socket Mode connection failed or timed out after retries. | Reinstall Slack app with appropriate manifest (`slack-app-manifest-inbound.json` or `-agent.json`), set `SLACK_APP_TOKEN`, use valid member IDs from Slack profiles, and verify network connectivity to Slack. |
+| `Q635` | `hive-slack.js` | Starting `slack start`, `slack agent`, or `github start --slack-allow` | Multi-connection collision: another process is already connected to Slack Socket Mode with this `SLACK_APP_TOKEN`. Slack splits events across connections, causing "stop" commands to be dropped. | Stop the other running bridge or watcher process, or use a dedicated Slack app for each bridge. If a bridge was recently stopped, wait 60s for Slack to release the connection and retry. |
+| `Q636` | `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Preflight Slack check, Slack bridge start, or `github start --slack-channel` | Network unreachable: failed to connect to Slack Web API (`fetch failed`, DNS error, or request timeout). The Slack token was not rejected because Slack could not be reached. | Check network connectivity, DNS, and proxy settings, then retry. |
+| `Q637` | `hive-mcp.js` | Running `hive_join` | This MCP server process is already in use by another agent with a different name. Some host apps (Antigravity, Cursor, Claude Desktop) share one MCP server process across all chat tabs. | Do not leave or rejoin. Add a second MCP server entry in your app's MCP config (e.g. `hivecode-2`) and restart the app (`docs/JOIN_WITH_AGENT.md`). If you are the same agent switching rooms, rejoin using the original name. |
+| `Q640` | `hive-notify.js` | Running `notify` | Provided link is not a valid room link (must be `wss://relay|room-…`). | Pass a valid room join link. |
+| `Q641` | `hive-notify.js` | Running `notify` | Missing `--webhook <url>` argument. | Provide incoming webhook URL from Slack or Discord. |
+| `Q642` | `hive-notify.js` | Running `notify` | Missing `--for <name>` argument or non-positive `--every` interval. | Specify who to notify with `--for <name>` and positive minutes with `--every <minutes>`. |
+| `Q643` | `hive-notify.js` | Running `notify` | The webhook endpoint refused the initial test post. | Check the webhook URL and ensure the receiving service is accessible. |
+| `Q644` | `hive-notify.js` | Running `notify` | A notifier is already running for this room (lock file held by another process). | Stop the other running notifier process or let it run. |
+| `Q575` | `hive-land.js` | Landing branch changes into a pull request (`hive_land` / `landIssue`) | A file claim is still held by a participant (or appeared during landing). All files must be released before landing. | Release all held files using `hive_release`, or wait for the holder to finish and release their claims. |
+| `Q576` | `hive-land.js` | Running project tests during landing verification (`--test "<command>"`) | The verification tests failed, timed out, or test checkout was not at the exact commit being landed. | Inspect test error output in room task or log. If tests require uncommitted files or dependencies, pass `--test-copy <files>` or `--test-setup <cmd>`, or fix failing test code. |
+| `Q577` | `hive-land.js` | Landing branch changes into a pull request | The room holds no files or landing would delete most branch files (>50% mass deletion). Indicates relay restarted or room was wiped. | Reconnect agents to reseed the room, reseed from branch (`branch <name> --reseed`), or pass `--allow-mass-delete` if intentional. |
+| `Q578` | `hive-land.js` | Pushing landed commits to remote origin (`git push origin <branch>`) | Pre-push checks failed: `origin` remote missing or unreachable, remote branch ahead, workflow files modified without `--allow-workflow-changes`, or secrets detected. | Ensure `origin` is configured and accessible, pull latest branch commits, or remove secrets/workflow changes from landed files. |
+| `Q579` | `hive-land.js` | Starting a landing run for a branch | Another landing run for this branch is currently active (landing lock held). | Wait for the concurrent landing to finish, or remove stale landing lock if the prior process crashed. |
+| `Q582` | `hive-repos.js` | Running `pr` from within a room | The room's repository folder is not located on this local machine. | Run `pr` from the machine where the repository clone resides, or register the repository with `hive-repos`. |
+| `Q583` | `hive-repos.js`, `hive-branch.js` | Running `pr` to land changes from a room | No local git repository is registered or bound to this room on this machine. | In your repository checkout, run `npx hivecode-mcp branch <branch>` to bind the room to your repository. |
+| `Q584` | `hive-repos.js` | Looking up registered repository for room | Repository registration is stale (folder moved/deleted) or multiple local clones are registered for the same room. | Re-bind the correct repository clone using `npx hivecode-mcp branch <branch>`, or remove obsolete entries in `~/.hivecode/repos.json`. |
+| `Q585` | `hive-repos.js` | Calling `hive_pr` | Not currently connected to a room (`hive_join` has not been called). | Join a room first using `hive_join` before calling `hive_pr`. |
+| `Q586` | `hive-repos.js` | Calling `hive_pr` | Room connection is currently offline or disconnected from relay. | Wait for the room connection to reconnect to the relay before running `hive_pr`. |
+| `Q650` | `hive-room-mode.js` | Starting room-mode watcher (`github start --room "<link>"`) | Missing, empty, or malformed room join link. | Provide a valid room join link (`wss://<relay>|room-<id>`) or use `github start --branch <name>`. |
+| `Q651` | `hive-room-mode.js` | Starting room-mode watcher | Target directory is not a git repository root (or is the user's home directory). | Run the watcher from inside a valid git repository checkout. |
+| `Q652` | `hive-room-mode.js` | Starting room-mode watcher | The specified room is not bound to a git branch in this repository, or multiple branches match. | Run `npx hivecode-mcp branch <branch>` to bind the branch, or launch with `github start --branch <branch>`. |
+| `Q653` | `hive-room-mode.js` | Preflight check for room-mode watcher | GitHub CLI (`gh`) is not installed, not in `PATH`, or not authenticated. | Install `gh` and run `gh auth login` with write permissions to the repository. |
+| `Q654` | `hive-room-mode.js` | Preflight member version check for room mode | An active AI agent in the room is running a Hivecode version older than 0.13.0, or has no version declared. | Update all participating AI agent packages to `hivecode-mcp@latest` (>= 0.13.0) and reconnect. |
+| `Q655` | `hive-room-mode.js` | Starting room-mode watcher | Another room-mode watcher is already active for this room (watcher lock held). | Stop the other running watcher process, or remove the stale lock file in `.git/hive-room-watcher.lock` if crashed. |
+| `Q656` | `hive-room-mode.js` | Room-mode watcher connecting to relay | Could not connect to relay at specified URL, or connection timed out. | Verify internet connectivity, check relay status, and ensure the relay URL is correct. |
+| `Q657` | `hive-room-mode.js` | Dispatching an issue task or chat into room | Delivery verification failed: task assignment or chat message was not confirmed in room within timeout. | Check relay stability, ensure room has reachable participants, and retry with `/hivecode retry`. |