claude-slack-channel-bots 0.5.0 → 0.6.0

package/README.md

@@ -36,13 +36,25 @@ See the sections below for manual configuration details if you prefer not to use
 
 ## Prerequisites
 
-- [Bun](https://bun.sh) v1.0+
-- [tmux](https://github.com/tmux/tmux) (required for server-managed sessions)
+- [Bun](https://bun.sh) `>= 1.0.21` (agent-director minimum)
 - [Claude Code](https://claude.ai/code) installed and authenticated
-- `ss` from [iproute2](https://github.com/iproute2/iproute2) on your `PATH` (required for session ID discovery; pre-installed on most Linux distributions)
-- `curl` and `jq` on your `PATH` (required for the permission relay hooks)
+- [`agent-director`](https://github.com/gabemahoney/agent-director) **runtime dependency** — pulled in transitively when you install this package. Hard required at server boot: CSCB refuses to start if the library is missing, the host platform is unsupported, Bun is too old, or the installed version is below `MIN_AD_VERSION` (`^0.4.3`). agent-director itself requires [tmux](https://github.com/tmux/tmux) on the operator's PATH; CSCB no longer probes for it directly.
 - Slack workspace admin access (to create and configure the Slack app)
-- **cozempic** (optional) — Python 3.10+ and `pip install cozempic` — enables session file cleaning before `--resume` for faster load times
+- **cozempic** (optional) — Python 3.10+ and `pip install cozempic` — used by JSONL path resolution helpers retained for downstream callers.
+
+### Supported platforms (inherited from agent-director)
+
+| Platform | Status |
+|---|---|
+| `linux-x64` | Supported |
+| `darwin-arm64` (Apple Silicon Mac) | Supported |
+| `linux-arm64` | **Not supported** by agent-director |
+| `darwin-x64` (Intel Mac) | **Not supported** by agent-director |
+| Windows | **Not supported** by agent-director |
+
+If the host is unsupported, the SR-5.1 startup gate exits non-zero at server boot with a typed error from agent-director (`ErrPlatformPackageMissing` or `ErrUnsupportedPlatform`) and writes the failure to `~/.claude/channels/slack/startup-errors.log` and stderr. See [Startup errors](#startup-errors) below.
+
+> **Note on agent-director versions.** v0.4.1 is a zombie release (the published tarball is missing `dist/` and cannot be imported). v0.4.2 lacks the `MakeTemplateParams.overwrite` field CSCB needs for the boot-time template refresh. CSCB pins `^0.4.3` to get past both.
 
 ---
 
@@ -105,7 +117,7 @@ A skeleton file is created by postinstall. Populate it before running `start`.
 
 | Field | Type | Default | Description |
 |---|---|---|---|
-| `routes` | object | required | Map of Slack channel ID → route entry. Each entry requires a `cwd` field: the working directory for that session. Used to identify sessions via `roots/list` after MCP handshake. `~` is expanded. Each `cwd` must be unique across all routes. |
+| `routes` | object | required | Map of Slack channel ID → route entry. Each entry requires a `cwd` field: the working directory for that session. Used to identify sessions via `roots/list` after MCP handshake. `~` is expanded. Each `cwd` must be unique across all routes. May also include an optional `claude_config_dir` string (see below). |
 | `default_route` | string | — | CWD path to use when a message arrives on a channel with no explicit entry in `routes`. Must match an existing route `cwd`. Channels that are in `routes` but whose session is not yet registered have their messages dropped — they do not fall back to `default_route`. |
 | `default_dm_session` | string | — | CWD path of the session that handles direct messages. Must match an existing route `cwd`. |
 | `bind` | string | `"127.0.0.1"` | Interface the HTTP server binds to. Use `"0.0.0.0"` to expose on all interfaces. |
@@ -118,6 +130,31 @@ A skeleton file is created by postinstall. Populate it before running `start`.
 | `append_system_prompt_file` | string | — | Path to a file appended to every managed session's system prompt via `--append-system-prompt-file`. Missing file silently skipped. See `skills/EXAMPLE_CLAUDE.md` for a template. |
 | `system_prompt_mode` | string | `"append"` | Controls how `append_system_prompt_file` is applied. `"append"`: the custom prompt file is appended on top of `CLAUDE.md` (default, current behavior). `"none"`: only `CLAUDE.md` is used; `append_system_prompt_file` is ignored even if set. Use `"none"` when the project's `CLAUDE.md` already contains everything the bot needs. |
 | `cozempic_prescription` | string | `"standard"` | Cozempic cleaning intensity before resume. Valid values: `gentle`, `standard`, `aggressive`. Has no effect if cozempic is not installed. |
+| `message_archive_db` | string | — | Path to a SQLite DB where every inbound Slack message is archived in real time. Parent directories are created if missing; schema is initialized on first open. Compatible with the `archive-messages.py` backfill script — both can write concurrently. Feature is disabled when absent. |
+| `claude_config_dir` | string | — | Path to a Claude on-disk config directory. When set, managed sessions launch with `CLAUDE_CONFIG_DIR='<resolved-path>'` so the bot authenticates against a specific account. `~` is expanded and the path is resolved to absolute. Per-route `routes[id].claude_config_dir` overrides this top-level value for individual channels. When neither is set, Claude's own default applies. Must be non-empty when set. |
+| `resume_enabled` | boolean | `true` | When `false`, the session manager always performs a fresh Claude session launch instead of resuming, both on startup and on runtime auto-restart, even when a stored session ID exists. Disabling this skips the `--resume` flag entirely. Use this as a workaround if your Claude Code version crashes with "sandbox required but unavailable" on `--resume` (a known regression in v2.1.120). |
+| `agent_director_poll_interval_ms` | number | `1000` | Poll interval (ms) for the agent-director permission relay tick. Must be a positive integer in `[200, 3_600_000]`. Replaces the pre-rename `claude_director_poll_interval_ms` — the old name is rejected at startup. Unknown top-level config fields are also rejected to surface stale configs after the rename. |
+
+#### Per-route `claude_config_dir` override
+
+When you want different bot sessions to authenticate as different Claude accounts (e.g. one channel runs as a personal Max account, another as a corporate account), set `claude_config_dir` on the individual route. Per-route values take priority over the top-level `claude_config_dir`; routes without their own override fall back to the top-level value.
+
+```json
+{
+  "routes": {
+    "C_PERSONAL": {
+      "cwd": "~/projects/alpha",
+      "claude_config_dir": "~/.claude-maxauth"
+    },
+    "C_CORPORATE": {
+      "cwd": "~/projects/beta"
+    }
+  },
+  "claude_config_dir": "~/.claude-corp"
+}
+```
+
+`C_PERSONAL` launches with the Max account; `C_CORPORATE` falls through to the top-level value and uses the corporate account. Use `claude auth login --claudeai` (or `--console`) with `CLAUDE_CONFIG_DIR` set to the same directory to populate each config dir before starting the server.
 
 ---
 
@@ -193,10 +230,11 @@ Checks prerequisites, then daemonizes the server.
 
 **Prerequisite checks (in order):**
 
-1. `tmux` is on `PATH` — fails with `missing prerequisite: tmux` if not found.
-2. `SLACK_BOT_TOKEN` is set — fails with `missing prerequisite: SLACK_BOT_TOKEN environment variable` if absent.
-3. `SLACK_APP_TOKEN` is set — fails with `missing prerequisite: SLACK_APP_TOKEN environment variable` if absent.
-4. `config.json` exists at `STATE_DIR/config.json` — fails with the full path if not found.
+1. `SLACK_BOT_TOKEN` is set — fails with `missing prerequisite: SLACK_BOT_TOKEN environment variable` if absent.
+2. `SLACK_APP_TOKEN` is set — fails with `missing prerequisite: SLACK_APP_TOKEN environment variable` if absent.
+3. `config.json` exists at `STATE_DIR/config.json` — fails with the full path if not found.
+
+Once the server daemonizes, the SR-5.1 startup gate runs inside the child process: it imports `agent-director`, constructs the singleton Client, runs `client.version()`, and verifies `~/.agent-director/state.db` is owned by the current user. Failures land in `startup-errors.log` (see [Startup errors](#startup-errors)). The previous `tmux -V` probe at the CLI level has been removed — agent-director enforces tmux availability at spawn time.
 
 If all checks pass, the parent process spawns a detached child process and exits immediately, printing the child PID. The child starts the server and writes its PID to `STATE_DIR/server.pid`. Conversation context is preserved across server restarts when possible.
 
@@ -222,11 +260,11 @@ Gracefully exits all managed Claude Code sessions, then stops and starts the ser
 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 `exit_timeout` seconds (default 120s), 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.
+For each configured route, calls `client.pause({claude_instance_id})` via agent-director and polls `client.status(...)` until the spawn transitions to `ended` / `missing` (or `client.list(...)` returns no row). If the spawn does not exit within `exit_timeout` seconds (default 120s), the spawn is force-killed via `client.kill(...)`. All routes are processed in parallel. Individual session errors are logged and do not abort the restart. After the server restarts, the SR-1.4 collision-then-act dispatcher decides resume-vs-fresh per route — agent-director owns Claude session-id state, not CSCB.
 
 Behavior by case:
 
-- **No sessions.json or no sessions:** skips the shutdown phase and proceeds directly to stop/start.
+- **No configured routes:** 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
@@ -271,69 +309,73 @@ Each MCP endpoint exposes the following tools to the connected Claude Code sessi
 
 ---
 
-## Permission Relay
+## Interject
 
-When Claude Code requires tool approval, the permission relay surfaces an interactive Slack message with **Allow** and **Deny** buttons instead of blocking the TUI. The Claude Code hook POSTs the pending request to the server, then long-polls for the user's response. Once the user clicks a button, the result is returned to Claude Code and execution continues.
+POST to `/interject` to inject a message into an active Claude session from localhost. Only requests from `127.0.0.1` or `::1` are accepted — external callers are rejected with 403.
 
-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.
+### Request
 
-Both hooks are **scope-guarded**: on each invocation they call the server's `GET /is-managed?pid=$PPID` endpoint to verify that the calling process belongs to a server-managed Claude session. If the server is not running or does not recognize the PID, the hooks exit silently (no-op). This means installing the hooks globally in `settings.json` is safe — they will not activate for Claude sessions you run outside the bot.
+```sh
+curl -X POST http://localhost:<port>/interject \
+  -H "Content-Type: application/json" \
+  -d '{"channel": "C1234567890", "message": "Hello from a script", "sender": "my-cron-job"}'
+```
 
-Both hooks use a **two-phase long-poll protocol**:
+| Field | Required | Description |
+|---|---|---|
+| `channel` | yes | Slack channel ID matching an entry in `config.json → routes`. |
+| `message` | yes | Text to inject into the session. |
+| `sender` | no | Label attached to the injected message. Defaults to `"interject"`. |
 
-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`.
-2. **Phase 2 — Long-poll:** The hook GETs `/permission/{requestId}` (or `/ask/{requestId}`) in a loop with a 90-second `curl` timeout. The server holds the connection for up to 60 seconds waiting for a button click, then returns `{"status":"pending"}` if no decision has arrived. The hook retries immediately. Once the user clicks, the server returns `{"status":"decided","decision":"allow"|"deny"}` and the hook exits.
+### Response
 
-### Slack app prerequisites
+On success, returns HTTP 200:
 
-The Slack app must have **interactivity enabled** with **Socket Mode** as the delivery method. Without this, button-click payloads are never delivered and the relay will not work.
+```json
+{ "ok": true, "channel": "C1234567890", "cwd": "/path/to/session" }
+```
 
-To enable it: open your Slack app config → **Interactivity & Shortcuts** → toggle **Interactivity** on. No Request URL is needed — Socket Mode delivers interaction payloads over the existing socket connection. This is included automatically if you created the app from `slack-app-manifest.yml`.
+### Error conditions
 
-### Hook installation
+| Status | Meaning |
+|---|---|
+| 400 | Invalid JSON or missing required field (`channel` or `message`). |
+| 403 | Request did not originate from localhost. |
+| 404 | Channel not found in `config.json → routes`. |
+| 405 | Must use POST method. |
+| 413 | Request body exceeds 32KB. |
+| 503 | Channel is routed but no active session is connected. |
 
-1. Copy the hook scripts from the repo to `~/.claude/hooks/`:
+### Example: crontab reminder
 
-   ```sh
-   cp hooks/permission-relay.sh hooks/ask-relay.sh ~/.claude/hooks/
-   chmod +x ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
-   ```
+```sh
+# crontab -e
+0 9 * * 1 curl -s -X POST http://localhost:3100/interject \
+  -H "Content-Type: application/json" \
+  -d '{"channel": "C1234567890", "message": "Weekly reminder: update the changelog before standup.", "sender": "cron"}'
+```
 
-   Alternatively, symlink them so updates to the repo are reflected automatically:
+---
 
-   ```sh
-   ln -sf /path/to/repo/hooks/permission-relay.sh ~/.claude/hooks/permission-relay.sh
-   ln -sf /path/to/repo/hooks/ask-relay.sh ~/.claude/hooks/ask-relay.sh
-   ```
+## Permission Relay
 
-2. Ensure `curl` and `jq` are on your `PATH`.
-
-3. Add the following to your Claude Code `settings.json`:
-
-   ```jsonc
-   "PermissionRequest": [
-     {
-       "matcher": ".*",
-       "timeout": 2000000,
-       "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-relay.sh" }]
-     }
-   ],
-   "PreToolUse": [
-     {
-       "matcher": "AskUserQuestion",
-       "timeout": 2000000,
-       "hooks": [{ "type": "command", "command": "~/.claude/hooks/ask-relay.sh" }]
-     }
-   ]
-   ```
+When Claude Code requires tool approval, the permission relay surfaces an interactive Slack message with **Allow** and **Deny** buttons instead of blocking the TUI. Architecture is polling-based on the `agent-director` library — there are **no hook scripts to install** and no HTTP long-poll loops.
+
+Flow:
 
-   `permission-relay.sh` relays tool permission requests (Allow/Deny) to Slack via `PermissionRequest`. `ask-relay.sh` relays `AskUserQuestion` calls to Slack via `PreToolUse`, returning the user's selection without blocking the TUI.
+1. agent-director moves the spawn into `check_permission` state when Claude requests a tool permission.
+2. CSCB's poller (`src/permission-poller.ts`) runs `client.list({ state: ['check_permission'], label: ['service=cscb'] })` at the `agent_director_poll_interval_ms` cadence (default 1000 ms).
+3. For each new spawn, `client.get(...)` returns the open `permission_request` (tool name + tool input + integer `request_id`). CSCB `chat.postMessage`s the Block Kit prompt to the spawn's `channel` label.
+4. The operator clicks Allow / Deny in Slack. CSCB's interactive handler calls `client.decide({ claude_instance_id, decision })` and `chat.update`s the message to "Allowed/Denied by <user>".
+5. If a tracked prompt drops out of `check_permission` for any reason other than a Slack click (timeout, external `decide`, crash), the next poller tick replaces the buttons with "expired".
 
-Both hooks auto-detect the server port from `config.json`. They read `${SLACK_STATE_DIR:-$HOME/.claude/channels/slack}/config.json` and use the `port` field (defaulting to `3100`), so they stay in sync if you change the port in routing config.
+### Slack app prerequisites
+
+The Slack app must have **interactivity enabled** with **Socket Mode** as the delivery method. Open your Slack app config → **Interactivity & Shortcuts** → toggle **Interactivity** on. No Request URL is needed; Socket Mode delivers interaction payloads over the existing socket. This is included automatically if you created the app from `slack-app-manifest.yml`.
 
-### Setup skill
+### AskUserQuestion
 
-The `update-config` skill can automate hook installation. It copies or symlinks the hooks and writes the `settings.json` entries in one step — use it if you prefer not to configure hooks manually.
+The `AskUserQuestion` tool is denied for every CSCB-spawned bot via the agent-director template (`deny: ['AskUserQuestion']`). Bots respond to operator questions via the Slack `reply` MCP tool instead. There is no `ask-relay.sh` hook and no `/ask` HTTP route.
 
 ---
 
@@ -355,10 +397,66 @@ After inviting the bot to a channel, Slack may not deliver messages until the bo
 Messages to channels not listed in `access.json → channels` and not present in `config.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 `config.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 call `GET /is-managed?pid=$PPID` and exit silently if the server is unreachable or the PID is not recognized. Sessions launched manually will not trigger the relay.
+Check that the Slack app has interactivity enabled (Interactivity & Shortcuts → toggle on). Verify the bot is in `check_permission` state via `agent-director list --state check_permission --label service=cscb` (operator CLI). Inspect `server.log` for `permission-poller:` lines — skipped-tick WARNs at 5+ consecutive skips signal that the poll interval is too tight; increase `agent_director_poll_interval_ms` in `config.json`.
 
 **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 `config.json`.
 
 **Session stuck during clean_restart**
-If a session does not exit within `exit_timeout` seconds (default 120s), `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`.
+If a session does not exit within `exit_timeout` seconds (default 120s), `clean_restart` force-kills the spawn via `agent-director kill` and proceeds. To manually recover, run `agent-director list --label service=cscb` to find lingering spawns and `agent-director kill <claude_instance_id>` to clear them, then `claude-slack-channel-bots stop && claude-slack-channel-bots start`.
+
+**Session crashes on resume with "sandbox required but unavailable"**
+This is a known regression in certain Claude Code releases (e.g. v2.1.120) where `--resume` triggers a sandbox check that fails in headless environments. Set `resume_enabled: false` in `config.json` to disable `--resume` entirely — the bot will always start a fresh Claude session instead of resuming a prior conversation, both on startup and on runtime auto-restart:
+
+```json
+{
+  "routes": { ... },
+  "resume_enabled": false
+}
+```
+
+---
+
+## Startup errors
+
+CSCB writes fatal startup errors to `~/.claude/channels/slack/startup-errors.log` (override the directory with `SLACK_STATE_DIR`) in addition to stderr. Each entry is a single timestamped line. The file is append-only and never rotated by CSCB — copy `docs/logrotate-startup-errors.conf` into `/etc/logrotate.d/` if you want host-level rotation.
+
+Classes you may see:
+
+- `ad-platform-package-missing` — agent-director's platform-native peer dependency is absent. The host is unsupported by agent-director.
+- `ad-unsupported-platform` — agent-director's runtime check rejected the host's `process.platform`/`process.arch` tuple.
+- `ad-bun-version-too-old` — agent-director needs Bun `>= 1.0.21`. Upgrade Bun.
+- `ad-cli-not-executable` — the resolved agent-director CLI binary exists but is not executable. Run `chmod +x` on the binary referenced in the log line.
+- `ad-version-probe` — `agent-director` was loaded but the `version()` probe failed (subprocess invocation, platform binary, etc.).
+- `ad-version-stale` — installed `agent-director` is below the minimum version this CSCB requires. Run `bun add agent-director@^<minimum>`.
+- `ad-call-timeout` — an agent-director verb call exceeded the configured `callTimeoutMs` (default 30 s). Investigate the subprocess or increase the timeout.
+- `ad-same-user` — `~/.agent-director/state.db` is owned by a different UID than the CSCB process. Reinstall agent-director as the correct user or remove the mismatched file.
+- `ad-same-user-stat` — Non-ENOENT stat error on the state DB (permissions, I/O). Investigate the file before re-launching.
+- `ad-template-install` — `client.makeTemplate(...)` rejected the boot-time refresh of the `slack-channel-bot` template. The line includes the agent-director `errName`.
+
+---
+
+## Migration
+
+For operators upgrading from a pre-`agent-director` install:
+
+1. **Install the new CSCB**: `bun remove claude-director` (if present) and `bun install -g claude-slack-channel-bots@^<new>`. The `agent-director` library is pulled in transitively — no separate install step.
+2. **Delete any old relay hooks** (CSCB no longer ships them — agent-director's relay machinery owns the tool-permission flow):
+   ```sh
+   rm -f ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
+   ```
+   Also remove their entries from `~/.claude/settings.json` if you wired them in by hand previously.
+3. **Configure agent-director's `find-missing` sweep**. CSCB does NOT call `client.findMissing(...)`; reconciling stuck rows is the operator's responsibility. Add a cron entry (or systemd timer) that runs `agent-director find-missing` on a cadence that matches your tolerance — e.g. every minute on a busy host:
+   ```cron
+   * * * * * /usr/local/bin/agent-director find-missing --timeout 30s
+   ```
+4. **Install the startup-errors logrotate snippet** so `~/.claude/channels/slack/startup-errors.log` doesn't grow unboundedly. Edit `USER` in the file to match the OS account running CSCB:
+   ```sh
+   sudo cp docs/logrotate-startup-errors.conf /etc/logrotate.d/claude-slack-channel-bots
+   ```
+5. **Rename your config field**. Pre-Epic-2 configs used `claude_director_poll_interval_ms`; CSCB now expects `agent_director_poll_interval_ms` and rejects the old name (no silent alias). Edit `~/.claude/channels/slack/config.json` accordingly. Unknown top-level fields are also rejected — clear any other deprecated keys.
+6. **Optional cleanup**: `~/.claude/channels/slack/sessions.json` and `sessions.json.last` are no longer read or written. CSCB ignores them; you can safely `rm` them after a successful boot.
+7. **`tmux` is no longer a CSCB-direct prereq** but is still required transitively via agent-director — keep it installed.
+
+After step 1, every CSCB bot is spawned through `client.spawn(...)` with `relay_mode='on'`. The green/red Slack button UX is byte-identical to the pre-migration behavior; the action_id shape changes from `perm_(allow|deny)_<uuid>` to `perm_(allow|deny)_cscb_<channelId>_<request_id>` but this is invisible to end users.
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.5.0",
-  "description": "Multi-session Slack-to-Claude bridge \u2014 run multiple Claude Code bots across Slack channels via Socket Mode",
+  "version": "0.6.0",
+  "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {
     "claude-slack-channel-bots": "src/cli.ts"
@@ -10,6 +10,7 @@
     "src/*.ts",
     "!src/*.test.ts",
     "hooks/",
+    "scripts/fixup-bun-cache.ts",
     "slack-app-manifest.yml",
     "README.md",
     "skills/"
@@ -18,15 +19,18 @@
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "postinstall": "bun src/postinstall.ts",
+    "postinstall": "bun src/postinstall.ts && bun scripts/fixup-bun-cache.ts",
     "start": "bun install --no-summary && bun src/server.ts",
+    "pretest": "bun scripts/fixup-bun-cache.ts && bun scripts/check-no-toplevel-mock-module.ts",
+    "check:mocks": "bun scripts/check-no-toplevel-mock-module.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@slack/socket-mode": "^2.0.0",
-    "@slack/web-api": "^7.0.0"
+    "@slack/web-api": "^7.0.0",
+    "agent-director": "^0.5.1"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",

package/scripts/fixup-bun-cache.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * fixup-bun-cache.ts — Workaround for bun's tarball-extraction bug.
+ *
+ * bun (observed in 1.3.13) sometimes drops files during tarball extraction when
+ * a directory and a file share a name prefix in the same parent — e.g.
+ *   node_modules/ajv/dist/core.js   (file, dropped)
+ *   node_modules/ajv/dist/compile/  (sibling directory)
+ * or
+ *   node_modules/zod/v4/core/core.js  (file, dropped)
+ *   node_modules/zod/v4/core/        (parent directory of itself)
+ *
+ * The cache entry under ~/.bun/install/cache/<name>@<version>@@@N contains the
+ * complete tarball contents. Once a broken extraction has been hardlinked into
+ * node_modules, subsequent `bun install` invocations reuse the broken state.
+ *
+ * This script walks every installed package, finds its cache directory, and
+ * hardlinks (or copies) any file present in the cache but missing in node_modules.
+ * Safe to re-run.
+ */
+
+import {
+  readdirSync,
+  readFileSync,
+  existsSync,
+  mkdirSync,
+  linkSync,
+  copyFileSync,
+} from 'fs'
+import { join, dirname } from 'path'
+import { homedir } from 'os'
+
+const ROOT = process.cwd()
+const NM = join(ROOT, 'node_modules')
+const CACHE = join(homedir(), '.bun', 'install', 'cache')
+
+function* walkPackages(dir: string): Generator<string> {
+  if (!existsSync(dir)) return
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    if (entry.name === '.bin' || entry.name === '.cache') continue
+    const child = join(dir, entry.name)
+    if (entry.name.startsWith('@')) {
+      for (const inner of readdirSync(child, { withFileTypes: true })) {
+        if (inner.isDirectory()) {
+          const innerPath = join(child, inner.name)
+          yield innerPath
+          const nested = join(innerPath, 'node_modules')
+          if (existsSync(nested)) yield* walkPackages(nested)
+        }
+      }
+    } else {
+      yield child
+      const nested = join(child, 'node_modules')
+      if (existsSync(nested)) yield* walkPackages(nested)
+    }
+  }
+}
+
+function readVersion(pkgDir: string): string | null {
+  const pj = join(pkgDir, 'package.json')
+  if (!existsSync(pj)) return null
+  try {
+    return JSON.parse(readFileSync(pj, 'utf-8')).version ?? null
+  } catch {
+    return null
+  }
+}
+
+function* walkFiles(dir: string, base = dir): Generator<string> {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const child = join(dir, entry.name)
+    if (entry.isDirectory()) yield* walkFiles(child, base)
+    else yield child.slice(base.length + 1)
+  }
+}
+
+function findCacheDir(scope: string, name: string, version: string): string | null {
+  const base = scope ? join(CACHE, `@${scope}`) : CACHE
+  const prefix = `${name}@${version}@@@`
+  if (!existsSync(base)) return null
+  for (const entry of readdirSync(base)) {
+    if (entry.startsWith(prefix)) return join(base, entry)
+  }
+  return null
+}
+
+function pkgIdentity(pkgDir: string): { scope: string; name: string } {
+  const tail = pkgDir.split('/node_modules/').pop()!
+  const parts = tail.split('/')
+  if (parts[0].startsWith('@')) return { scope: parts[0].slice(1), name: parts[1] }
+  return { scope: '', name: parts[0] }
+}
+
+let scanned = 0
+let restored = 0
+const restoredPaths: string[] = []
+
+for (const pkgDir of walkPackages(NM)) {
+  scanned++
+  const version = readVersion(pkgDir)
+  if (!version) continue
+  const { scope, name } = pkgIdentity(pkgDir)
+  const cacheDir = findCacheDir(scope, name, version)
+  if (!cacheDir) continue
+
+  for (const relFile of walkFiles(cacheDir)) {
+    const installedPath = join(pkgDir, relFile)
+    if (existsSync(installedPath)) continue
+    const cachePath = join(cacheDir, relFile)
+    mkdirSync(dirname(installedPath), { recursive: true })
+    try {
+      linkSync(cachePath, installedPath)
+    } catch {
+      copyFileSync(cachePath, installedPath)
+    }
+    restored++
+    restoredPaths.push(installedPath.slice(NM.length + 1))
+  }
+}
+
+if (restored > 0) {
+  for (const p of restoredPaths) console.log(`fixup-bun-cache: restored ${p}`)
+}
+console.log(`fixup-bun-cache: scanned ${scanned} packages, restored ${restored} file(s)`)

package/src/agent-director-client.ts

@@ -0,0 +1,133 @@
+/**
+ * agent-director-client.ts — Module-level singleton wrapper for the
+ * `agent-director` library Client (SR-0.1).
+ *
+ * Public API:
+ *   - getClient(): Client                          — lazy-construct + return the singleton
+ *   - closeClient(): void                           — idempotent shutdown for SR-11 Event 11
+ *   - MIN_AD_VERSION: string                        — semver string derived from package.json
+ *   - DEFAULT_STORE_PATH / DEFAULT_TEMPLATE_NAME    — paths CSCB pins
+ *   - resetClientForTests(): void                   — test-only handle reset
+ *
+ * MIN_AD_VERSION is read once at module init from this package.json's
+ * `dependencies['agent-director']` range, stripping leading semver operators
+ * (`^`, `~`, `>=`, etc.) so a single source of truth covers both the install-
+ * time dep declaration (SR-5.3) and the runtime version gate (SR-5.1 step 3).
+ *
+ * Construction uses `{ storePath, createIfMissing: true, logger: console }`
+ * per SR-0.1; tilde expansion is the library's responsibility.
+ *
+ * Concurrency: AD's Client is internally safe for concurrent verb calls
+ * (the subprocess-CLI transport serializes its own dispatch) per SR-0.1,
+ * so CSCB does NOT add its own mutex.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Client } from 'agent-director'
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default AD store path; tilde-expanded library-side. */
+export const DEFAULT_STORE_PATH = '~/.agent-director/state.db'
+
+/** Name of the CSCB-shipped template (SR-3.1). */
+export const DEFAULT_TEMPLATE_NAME = 'slack-channel-bot'
+
+/**
+ * Resolve the package.json that ships with this module, then extract and
+ * normalize `dependencies['agent-director']` into a bare semver string.
+ *
+ * Throws at module init if the dep is missing or shaped wrong — that's a
+ * packaging bug worth failing loudly on, not a runtime condition.
+ */
+function readMinAdVersion(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url))
+  // src/agent-director-client.ts → package.json lives one level up
+  const pkgPath = join(moduleDir, '..', 'package.json')
+  const raw = readFileSync(pkgPath, 'utf-8')
+  const pkg = JSON.parse(raw) as { dependencies?: Record<string, string> }
+  const range = pkg.dependencies?.['agent-director']
+  if (typeof range !== 'string' || range.length === 0) {
+    throw new Error(
+      `agent-director-client: package.json dependencies['agent-director'] is missing or empty — cannot derive MIN_AD_VERSION`,
+    )
+  }
+  // Strip leading semver operators: ^, ~, >=, >, =, v. Anything left should
+  // parse as semver; we don't validate further here — the SR-5.1 version gate
+  // does the actual comparison.
+  const stripped = range.replace(/^[\^~]|^>=|^>|^=/, '').replace(/^v/, '').trim()
+  if (stripped.length === 0) {
+    throw new Error(
+      `agent-director-client: dependencies['agent-director']=${range} reduced to empty string after stripping operators`,
+    )
+  }
+  return stripped
+}
+
+/** Minimum agent-director version CSCB requires at runtime (SR-5.3). */
+export const MIN_AD_VERSION: string = readMinAdVersion()
+
+// ---------------------------------------------------------------------------
+// Singleton state
+// ---------------------------------------------------------------------------
+
+let singleton: Client | null = null
+
+/**
+ * Return the singleton Client, lazy-constructing it on first call.
+ *
+ * Construction is synchronous: all platform / Bun / subprocess-resolution
+ * errors fire eagerly here per SR-0.1, not at first verb call. Typed `Err*`
+ * subclasses propagate; the SR-5.1 startup gate is the only intended
+ * caller-of-record that branches them.
+ */
+export function getClient(): Client {
+  if (singleton === null) {
+    singleton = new Client({
+      storePath: DEFAULT_STORE_PATH,
+      createIfMissing: true,
+      logger: console,
+    })
+  }
+  return singleton
+}
+
+/**
+ * Release the Client handle if open. Idempotent: a second call is a no-op.
+ * `client.close()` itself never throws per the library contract.
+ *
+ * Called from SR-11 Event 11 (graceful shutdown) inside a try/finally.
+ */
+export function closeClient(): void {
+  if (singleton !== null) {
+    singleton.close()
+    singleton = null
+  }
+}
+
+/**
+ * Test-only helper: drop the cached singleton WITHOUT closing it. Use when
+ * tests construct fake Clients via the agent-director-stub and want a clean
+ * slate per test. Production code must use closeClient() instead.
+ *
+ * @internal
+ */
+export function resetClientForTests(): void {
+  singleton = null
+}
+
+/**
+ * Test-only helper: install a pre-built Client (typically a stub) as the
+ * singleton. Skip the Client construction path entirely.
+ *
+ * @internal
+ */
+export function setClientForTests(client: Client): void {
+  singleton = client
+}