claude-slack-channel-bots 0.1.2 → 0.1.4

package/README.md

@@ -173,7 +173,7 @@ If you changed `port` or `bind` in `routing.json`, update the `url` here to matc
 
 ## CLI Reference
 
-The `claude-slack-channel-bots` binary exposes two subcommands.
+The `claude-slack-channel-bots` binary exposes three subcommands.
 
 ### `claude-slack-channel-bots start`
 
@@ -202,6 +202,21 @@ Behavior by case:
 - **Stale PID file** (process no longer running): removes the PID file, prints `server is not running (removed stale PID file)`, exits 0.
 - **Live process:** sends `SIGTERM`, polls for exit every 100ms for up to 5 seconds. Prints `[slack] Server stopped.` on clean exit. Prints a warning if the server does not stop within 5 seconds (does not force-kill).
 
+### `claude-slack-channel-bots clean_restart`
+
+Gracefully exits all managed Claude Code sessions, then stops and starts the server.
+
+```sh
+claude-slack-channel-bots clean_restart
+```
+
+For each session in `sessions.json`, sends `/exit` to the tmux session and polls until Claude exits. All sessions are processed in parallel. If a session does not exit within 60 seconds, its tmux session is force-killed. Individual session errors are logged and do not abort the restart. After the server restarts, sessions are relaunched with `--resume` using the stored session IDs in `sessions.json`, preserving conversation context.
+
+Behavior by case:
+
+- **No sessions.json or no sessions:** skips the shutdown phase and proceeds directly to stop/start.
+- **Server already stopped:** `stop` reports `server is not running`; `start` then brings up a fresh server.
+
 ### PID file
 
 The PID file is stored at `STATE_DIR/server.pid` (default: `~/.claude/channels/slack/server.pid`). It is written on startup and removed on clean shutdown. A conflict check at startup prevents running two servers against the same state directory.
@@ -250,6 +265,8 @@ When Claude Code requires tool approval, the permission relay surfaces an intera
 
 The `ask-relay.sh` hook intercepts `AskUserQuestion` tool calls via `PreToolUse`, posts the question and its options to Slack as interactive buttons, and waits for the user's selection. The answer is returned to Claude Code via `updatedInput` without blocking the TUI.
 
+Both hooks are **scope-guarded**: they check for the `SLACK_CHANNEL_BOT_SESSION` environment variable and exit immediately (no-op) if it is not set. The server sets this variable on every Claude session it launches. This means installing the hooks globally in `settings.json` is safe — they will not activate for Claude sessions you run outside the bot.
+
 Both hooks use a **two-phase long-poll protocol**:
 
 1. **Phase 1 — Create request:** The hook POSTs to `/permission` (or `/ask`) with the tool name, input, and CWD. The server posts an interactive Slack message and returns a `requestId`.
@@ -319,11 +336,17 @@ The `update-config` skill can automate hook installation. It copies or symlinks
 **routing.json CWD mismatch**
 If a Claude Code session connects but immediately disconnects, the session's actual CWD does not match any `cwd` in `routing.json`. Confirm the session's working directory matches the entry exactly (after tilde expansion). Duplicate CWDs across multiple routes are rejected at startup.
 
+**Bot not receiving messages in a new channel**
+After inviting the bot to a channel, Slack may not deliver messages until the bot is @mentioned for the first time. This is a Slack Socket Mode behavior — the first @mention activates event delivery for that channel. After that, all messages flow normally regardless of `requireMention` settings.
+
 **Channel not in access.json**
-Messages to channels not listed in `access.json → channels` are silently dropped. Use the `slack-channel-access` skill or edit `access.json` directly to add the channel ID with a `ChannelPolicy` entry.
+Messages to channels not listed in `access.json → channels` and not present in `routing.json → routes` are silently dropped. Use the `claude-slack-channels-config` skill or edit `access.json` directly to add the channel ID with a `ChannelPolicy` entry.
 
 **Permission relay not working**
-Check that the Slack app has interactivity enabled (Interactivity & Shortcuts → toggle on). Verify `curl` and `jq` are on your `PATH`. Confirm the hook scripts are executable (`chmod +x`). If the port was changed in `routing.json`, ensure `SLACK_STATE_DIR` is set correctly so the hooks can read the updated port.
+Check that the Slack app has interactivity enabled (Interactivity & Shortcuts → toggle on). Verify `curl` and `jq` are on your `PATH`. Confirm the hook scripts are executable (`chmod +x`). If the port was changed in `routing.json`, ensure `SLACK_STATE_DIR` is set correctly so the hooks can read the updated port. If the hooks are silently doing nothing, confirm the session was launched by the server — the hooks only activate when `SLACK_CHANNEL_BOT_SESSION=1` is present in the environment. Sessions launched manually will not trigger the relay.
 
 **Session not restarting after crash**
 After 3 consecutive launch failures for a route, auto-restart is suspended until the server is restarted. Restart the server with `claude-slack-channel-bots stop && claude-slack-channel-bots start`. To disable auto-restart entirely, set `session_restart_delay` to `0` in `routing.json`.
+
+**Session stuck during clean_restart**
+If a session does not exit within 60 seconds, `clean_restart` force-kills its tmux session and proceeds. To manually recover, run `tmux kill-session -t <session-name>` for any remaining sessions, then `claude-slack-channel-bots stop && claude-slack-channel-bots start`.

package/hooks/ask-relay.sh

@@ -2,6 +2,11 @@
 # AskUserQuestion relay — intercepts via PreToolUse, posts to Slack, returns answer
 set -euo pipefail
 
+# Guard: only relay for bot-managed sessions
+if [ -z "${SLACK_CHANNEL_BOT_SESSION:-}" ]; then
+  exit 0
+fi
+
 # Only handle AskUserQuestion
 INPUT=$(cat)
 TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || exit 0

package/hooks/permission-relay.sh

@@ -2,6 +2,11 @@
 # permission-relay.sh - Claude Code PermissionRequest hook
 # Implements two-phase long-poll to relay permission decisions via Slack channel server
 
+# Guard: only relay for bot-managed sessions
+if [ -z "${SLACK_CHANNEL_BOT_SESSION:-}" ]; then
+  exit 0
+fi
+
 # Check dependencies
 if ! command -v jq &>/dev/null; then
   exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {

package/skills/setup-slack-channel-bots/SKILL.md

@@ -174,7 +174,9 @@ After collecting at least one route, write the updated `routing.json`.
 **Important:** Remind the user to invite the bot to each channel they configured.
 In Slack, type `/invite @Claude Slack Channel Bots` in each channel (or whatever
 the bot's display name is). The bot cannot receive messages from channels it has
-not been invited to.
+not been invited to. After inviting, send an @mention to the bot in each channel
+— Slack may not deliver messages until the first @mention activates event
+delivery for that channel.
 
 **Optional routing fields** — after required routes are set, offer these with
 their defaults. Prompt only if the user wants to customise:

package/src/cli.ts

@@ -14,6 +14,8 @@ import { join, resolve } from 'path'
 import { existsSync, readFileSync, unlinkSync } from 'fs'
 import { spawnSync } from 'child_process'
 import { isProcessRunning } from './pid.ts'
+import { defaultTmuxClient, isClaudeRunning as tmuxIsClaudeRunning } from './tmux.ts'
+import { readSessions, type SessionsMap } from './sessions.ts'
 
 // ---------------------------------------------------------------------------
 // Injectable dependency interface
@@ -40,6 +42,16 @@ export interface CliDeps {
   startServer: () => Promise<void>
   /** Exit the process. */
   exit: (code: number) => never
+  /** Returns true if a tmux session with the given name exists. */
+  hasSession: (name: string) => Promise<boolean>
+  /** Sends keystrokes to the given tmux session. */
+  sendKeys: (session: string, keys: string) => Promise<void>
+  /** Returns true if a 'claude' process is running in the given tmux session. */
+  isClaudeRunning: (session: string) => Promise<boolean>
+  /** Kills the named tmux session. */
+  killSession: (session: string) => Promise<void>
+  /** Read the sessions registry. */
+  readSessions: () => SessionsMap
 }
 
 // ---------------------------------------------------------------------------
@@ -58,6 +70,7 @@ function defaultStateDir(): string {
 export interface CliHandlers {
   start: () => Promise<void>
   stop: () => Promise<void>
+  clean_restart: () => Promise<void>
 }
 
 /**
@@ -154,7 +167,77 @@ export function createCli(deps: CliDeps): CliHandlers {
     deps.exit(0)
   }
 
-  return { start, stop }
+  async function clean_restart(): Promise<void> {
+    const sessions = deps.readSessions()
+    const entries = Object.entries(sessions)
+
+    if (entries.length > 0) {
+      console.error(`[slack] clean_restart: sending /exit to ${entries.length} session(s)`)
+
+      // Fan out: send /exit + Enter to all sessions in parallel (best-effort)
+      await Promise.all(entries.map(async ([channelId, record]) => {
+        try {
+          const exists = await deps.hasSession(record.tmuxSession)
+          if (!exists) {
+            console.error(`[slack] clean_restart: session not found for channel=${channelId}, skipping`)
+            return
+          }
+          await deps.sendKeys(record.tmuxSession, '/exit')
+          await deps.sendKeys(record.tmuxSession, 'Enter')
+          console.error(`[slack] clean_restart: sent /exit to channel=${channelId} session=${record.tmuxSession}`)
+        } catch (err) {
+          console.error(`[slack] clean_restart: error sending /exit to channel=${channelId}:`, err)
+        }
+      }))
+
+      // Poll each session until Claude exits or 60s timeout (best-effort)
+      await Promise.all(entries.map(async ([channelId, record]) => {
+        try {
+          const exists = await deps.hasSession(record.tmuxSession)
+          if (!exists) return
+
+          const timeout = 60_000
+          const start = Date.now()
+          let delay = 500
+          const maxDelay = 5_000
+
+          while (Date.now() - start < timeout) {
+            const running = await deps.isClaudeRunning(record.tmuxSession)
+            if (!running) {
+              console.error(`[slack] clean_restart: channel=${channelId} exited cleanly`)
+              return
+            }
+            await new Promise<void>((r) => setTimeout(r, delay))
+            delay = Math.min(delay * 2, maxDelay)
+          }
+
+          // Timed out — force kill
+          console.error(`[slack] clean_restart: timeout waiting for channel=${channelId}, force-killing`)
+          try {
+            await deps.killSession(record.tmuxSession)
+          } catch (err) {
+            console.error(`[slack] clean_restart: killSession failed for channel=${channelId}:`, err)
+          }
+        } catch (err) {
+          console.error(`[slack] clean_restart: error polling channel=${channelId}:`, err)
+        }
+      }))
+    }
+
+    // Stop the server
+    console.error('[slack] clean_restart: stopping server')
+    deps.spawnSync(process.execPath, [process.argv[1], 'stop'])
+
+    // Start the server
+    console.error('[slack] clean_restart: starting server')
+    const startResult = deps.spawnSync(process.execPath, [process.argv[1], 'start'])
+    if (startResult.status !== 0) {
+      console.error(`[slack] clean_restart: start failed with exit code ${startResult.status}`)
+      deps.exit(startResult.status ?? 1)
+    }
+  }
+
+  return { start, stop, clean_restart }
 }
 
 // ---------------------------------------------------------------------------
@@ -164,11 +247,12 @@ export function createCli(deps: CliDeps): CliHandlers {
 if (import.meta.main) {
   const subcommand = process.argv[2]
 
-  if (subcommand !== 'start' && subcommand !== 'stop') {
-    console.error('Usage: cli.ts <start|stop>')
+  if (subcommand !== 'start' && subcommand !== 'stop' && subcommand !== 'clean_restart') {
+    console.error('Usage: cli.ts <start|stop|clean_restart>')
     console.error('')
-    console.error('  start  Validate prerequisites and start the server in the background')
-    console.error('  stop   Send SIGTERM to a running server')
+    console.error('  start          Validate prerequisites and start the server in the background')
+    console.error('  stop           Send SIGTERM to a running server')
+    console.error('  clean_restart  Exit all managed sessions, then stop and start the server')
     process.exit(1)
   }
 
@@ -183,6 +267,11 @@ if (import.meta.main) {
     resolveStateDir: defaultStateDir,
     startServer: async () => { const { main } = await import('./server.ts'); return main() },
     exit: (code) => process.exit(code),
+    hasSession: (name) => defaultTmuxClient.hasSession(name),
+    sendKeys: (session, keys) => defaultTmuxClient.sendKeys(session, keys),
+    isClaudeRunning: (session) => tmuxIsClaudeRunning(session, defaultTmuxClient),
+    killSession: (session) => defaultTmuxClient.killSession(session),
+    readSessions: () => readSessions(),
   }
 
   const cli = createCli(realDeps)
@@ -192,10 +281,15 @@ if (import.meta.main) {
       console.error('[slack] Fatal:', err)
       process.exit(1)
     })
-  } else {
+  } else if (subcommand === 'stop') {
     cli.stop().catch((err) => {
       console.error('[slack] Fatal:', err)
       process.exit(1)
     })
+  } else {
+    cli.clean_restart().catch((err) => {
+      console.error('[slack] Fatal:', err)
+      process.exit(1)
+    })
   }
 }

package/src/session-manager.ts

@@ -109,7 +109,7 @@ export async function launchSession(
   const resumeSessionId = options?.sessionId
 
   const escapedConfigPath = routingConfig.mcp_config_path.replace(/'/g, "'\\''")
-  let baseCmd = `claude --mcp-config '${escapedConfigPath}' --dangerously-load-development-channels server:${MCP_SERVER_NAME}`
+  let baseCmd = `SLACK_CHANNEL_BOT_SESSION=1 claude --mcp-config '${escapedConfigPath}' --dangerously-load-development-channels server:${MCP_SERVER_NAME}`
 
   if (routingConfig.append_system_prompt_file !== undefined) {
     try {