claude-slack-channel-bots 0.5.1 → 0.6.1

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.5.5`). 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. v0.5.4 and earlier lack `allow_pending` on `readPane`/`sendKeys`, causing `ErrSpawnNotInteractive` during dev-channels dialog approval on freshly-spawned bots. CSCB pins `^0.5.5` to get past all three.
 
 ---
 
@@ -121,6 +133,7 @@ A skeleton file is created by postinstall. Populate it before running `start`.
 | `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
 
@@ -217,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.
 
@@ -246,17 +260,27 @@ 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 using the stored session IDs in `sessions.json`. When `resume_enabled` is `true` (the default), sessions resume with `--resume`, preserving conversation context. When `resume_enabled` is `false`, sessions always launch fresh without `--resume`.
+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
 
 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.
 
+### Installing from a local worktree
+
+To install the version of CSCB sitting in your working copy (so the globally-linked `claude-slack-channel-bots` binary runs your local sources), use the helper script rather than `bun install -g .`:
+
+```sh
+./scripts/install-local.sh
+```
+
+`bun install -g .` (and the equivalent `bun install -g <local-path>`) is broken on Bun 1.3.13 — it inserts an invalid empty-string dependency key into `~/.bun/install/global/package.json` and then any subsequent global op fails with `error: Package "@" has a dependency loop` (upstream: [oven-sh/bun#24207](https://github.com/oven-sh/bun/issues/24207)). The script uses `bun add -g file:<abs-path>` instead, and pre-emptively strips any empty-string entry a prior `bun install -g .` may have already left behind.
+
 ### Direct invocation for development
 
 Skip the CLI and run the server directly with Bun for development or debugging:
@@ -345,67 +369,23 @@ On success, returns HTTP 200:
 
 ## Permission Relay
 
-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.
-
-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.
+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.
 
-Both hooks are **scope-guarded**: they check the `CLAUDE_MANAGED_CHANNEL` environment variable, which is set as an inline env var (no `export`) on the `claude` command at launch. If the variable is absent, 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. If the variable is present but the server is unreachable, hooks fail closed (deny the tool call) to prevent indefinite hangs in headless sessions.
+Flow:
 
-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 channel ID (from `$CLAUDE_MANAGED_CHANNEL`). 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.
+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".
 
 ### Slack app prerequisites
 
-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.
-
-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`.
-
-### Hook installation
-
-1. Copy the hook scripts from the repo to `~/.claude/hooks/`:
+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`.
 
-   ```sh
-   cp hooks/permission-relay.sh hooks/ask-relay.sh ~/.claude/hooks/
-   chmod +x ~/.claude/hooks/permission-relay.sh ~/.claude/hooks/ask-relay.sh
-   ```
-
-   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
-   ```
-
-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" }]
-     }
-   ]
-   ```
-
-   `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.
+### AskUserQuestion
 
-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.
-
-### Setup skill
-
-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.
 
 ---
 
@@ -427,13 +407,13 @@ 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 check the `CLAUDE_MANAGED_CHANNEL` env var and exit silently if it is not set. Sessions launched manually will not have this variable and 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:
@@ -444,3 +424,99 @@ This is a known regression in certain Claude Code releases (e.g. v2.1.120) where
   "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`.
+
+---
+
+## Release process
+
+CSCB releases are cut with the `/publish` skill from a clean checkout of `main` on a dev box that has `npm login` against the publishing account. The skill bumps the version, packs and smoke-tests the release tarball, commits and tags the release, pushes to GitHub, publishes to npm, polls the registry until the new version is visible, reinstalls the just-published version on the dev box, and prints a final summary.
+
+### Invocation
+
+```
+/publish <patch|minor|major>
+```
+
+The bump kind is **required** — there is no default. The skill exits with a usage line if the argument is missing or not one of `patch`, `minor`, `major`.
+
+### Preflight gates
+
+Before any side-effecting step runs, `/publish` enforces six fail-fast gates. Any failure aborts before the version is bumped, the tarball is packed, or anything is committed:
+
+1. **Clean working tree on `main` in sync with origin/main.** No uncommitted changes; HEAD branch is `main`; `main` is exactly equal to `origin/main` after `git fetch origin`.
+2. **Tests exist and pass.** At least one `*.test.ts` file under `tests/` and `bun test` exits zero.
+3. **Typecheck passes.** `bun run typecheck` exits zero.
+4. **npm authenticated.** `npm whoami` exits zero (run `npm login` first if not).
+5. **Next version not already published.** `npm view claude-slack-channel-bots@<next-version> version` must report nothing.
+6. **`/ci` integration suite passes.** The full Docker-based integration test suite is run via the `/ci` skill and must report PASS. **`/ci` is mandatory and has no opt-out flag** — release without an unbroken integration run is not possible through this skill.
+
+### What happens during a release
+
+After all gates pass, the skill, in this order:
+
+1. Bumps `package.json` and `bun.lock` to `<next-version>` (no commit, no tag yet).
+2. Packs the release tarball with `bun pm pack` and verifies its internal version matches.
+3. Scratch-installs the tarball into a temp `BUN_INSTALL` and runs the bin smoke check (non-zero exit + `Usage:` in stderr). Any failure here rolls back the working tree and aborts — no commit, no push, no publish.
+4. Creates the `Release v<version>` commit and the annotated `v<version>` tag locally.
+5. Pushes the release commit to `origin/main`.
+6. Publishes the smoke-tested tarball with `npm publish <tarball-path>` (the smoke-tested artifact bytes — not a repack from CWD).
+7. Pushes the `v<version>` tag to `origin`, bringing GitHub and npm into agreement.
+8. Polls the npm registry every 5 seconds for up to 60 seconds until the new version is visible.
+9. Sanitizes the bun-1.3.13 empty-string-dependency-key poison from the global `package.json` (see [Installing from a local worktree](#installing-from-a-local-worktree)), removes any pre-existing global install, then runs `bun install -g claude-slack-channel-bots@<version>` — the exact command an end user would run — and verifies the installed bin resolves under `~/.bun/install/global/` at the published version.
+10. Prints a success summary identifying the published version, npm URL, GitHub release tag URL, resolved local install path, and the next-operator-action command.
+
+### After the skill exits
+
+The dev box now has the freshly-published version installed globally as a real copy, but the running CSCB daemon is still on the prior version. Swap the daemon over:
+
+```sh
+claude-slack-channel-bots clean_restart
+```
+
+This gracefully exits the managed Claude Code sessions, stops and restarts the server on the new binary, and brings each session back up. See [`clean_restart`](#claude-slack-channel-bots-clean_restart) above for full behavior.
+
+---
+
+## 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,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {
@@ -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.5"
   },
   "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
+}

package/src/agent-director-errors.ts

@@ -0,0 +1,58 @@
+/**
+ * agent-director-errors.ts — Re-export of typed Err* subclasses CSCB references.
+ *
+ * Per SR-0.2 the integration must not parse error strings or exit codes; every
+ * call site branches on `instanceof` against the typed classes below. This
+ * module gives the rest of CSCB a single import surface and a single place to
+ * keep the subset list in sync with SRD edits.
+ *
+ * Catalog (SR-0.2):
+ *   - ErrUnsupportedPlatform    (Client constructor / platform gate)
+ *   - ErrBunVersionTooOld       (Client constructor / Bun version gate)
+ *   - ErrPlatformPackageMissing (Client constructor / @agent-director/<plat>)
+ *   - ErrCliNotExecutable       (Client constructor / CLI binary lacks +x)
+ *   - ErrInstanceIdCollision    (spawn / SR-1.4 idempotency)
+ *   - ErrSpawnNotFound          (get / status / decide on missing row)
+ *   - ErrNoSessionId            (resume / SR-1.3 fallthrough)
+ *   - ErrJsonlMissing           (resume / SR-1.3 fallthrough)
+ *   - ErrSpawnNotResumable      (resume / SR-1.3 collision-recovery)
+ *   - ErrAlreadyDecided         (decide / SR-2.2 treated-as-success)
+ *   - ErrNoOpenPermissionRequest (decide / poller race)
+ *   - ErrRelayModeOff           (spawn / SR-1.2 abort)
+ *   - ErrRelayModeInvalid       (spawn / SR-1.2 abort)
+ *   - ErrTemplateMalformed      (makeTemplate / SR-3.2 fatal)
+ *   - ErrTemplateExists         (makeTemplate; only relevant pre-overwrite)
+ *   - ErrTemplateNotFound       (defensive — not raised by makeTemplate)
+ *   - ErrTemplateNameUnsafe     (makeTemplate / SR-3.2 fatal)
+ *   - ErrClientClosed           (post-close verb call; TS-only)
+ *   - ErrCallTimeout            (any verb / per-call timeout exceeded)
+ *
+ * ErrPauseTimeout is intentionally omitted (SR-0.2): SR-11 Event 12 owns its
+ * own pause timeout via CSCB-side polling and never relies on the library's
+ * pause budget, so the class never reaches a CSCB handler.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+export {
+  AgentDirectorError,
+  ErrClientClosed,
+  ErrUnsupportedPlatform,
+  ErrPlatformPackageMissing,
+  ErrBunVersionTooOld,
+  ErrCliNotExecutable,
+  ErrCallTimeout,
+  ErrInstanceIdCollision,
+  ErrSpawnNotFound,
+  ErrNoSessionId,
+  ErrJsonlMissing,
+  ErrSpawnNotResumable,
+  ErrAlreadyDecided,
+  ErrNoOpenPermissionRequest,
+  ErrRelayModeOff,
+  ErrRelayModeInvalid,
+  ErrTemplateMalformed,
+  ErrTemplateExists,
+  ErrTemplateNotFound,
+  ErrTemplateNameUnsafe,
+} from 'agent-director'