claude-slack-channel-bots 0.6.0 → 0.6.2

package/README.md

@@ -38,7 +38,7 @@ See the sections below for manual configuration details if you prefer not to use
 
 - [Bun](https://bun.sh) `>= 1.0.21` (agent-director minimum)
 - [Claude Code](https://claude.ai/code) installed and authenticated
-- [`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.
+- [`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` — used by JSONL path resolution helpers retained for downstream callers.
 
@@ -54,7 +54,7 @@ See the sections below for manual configuration details if you prefer not to use
 
 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.
+> **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.
 
 ---
 
@@ -271,6 +271,16 @@ Behavior by case:
 
 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:
@@ -436,6 +446,56 @@ Classes you may see:
 
 ---
 
+## 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slack-channel-bots",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Multi-session Slack-to-Claude bridge — run multiple Claude Code bots across Slack channels via Socket Mode",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@slack/socket-mode": "^2.0.0",
     "@slack/web-api": "^7.0.0",
-    "agent-director": "^0.5.1"
+    "agent-director": "^0.5.5"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",

package/src/cli.ts

@@ -112,10 +112,15 @@ export function createCli(deps: CliDeps): CliHandlers {
       const { spawn } = await import('child_process')
       const logPath = join(stateDir, 'server.log')
       const logFd = openSync(logPath, 'a')
+      // b.1m9: propagate --reconcile-instance-ids to the daemon child via env.
+      const childEnv: NodeJS.ProcessEnv = { ...process.env, _CLI_DAEMON_CHILD: '1' }
+      if (process.argv.includes('--reconcile-instance-ids')) {
+        childEnv['CSCB_RECONCILE_INSTANCE_IDS'] = '1'
+      }
       const child = spawn(process.execPath, [import.meta.filename, 'start'], {
         detached: true,
         stdio: ['ignore', logFd, logFd],
-        env: { ...process.env, _CLI_DAEMON_CHILD: '1' },
+        env: childEnv,
       })
       child.unref()
       console.error(`[slack] Server starting in background (PID ${child.pid})`)
@@ -294,14 +299,34 @@ if (import.meta.main) {
   const subcommand = process.argv[2]
 
   if (subcommand !== 'start' && subcommand !== 'stop' && subcommand !== 'clean_restart') {
-    console.error('Usage: cli.ts <start|stop|clean_restart>')
+    console.error('Usage: cli.ts <start|stop|clean_restart> [flags]')
     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('  clean_restart  Exit all managed sessions, then stop and start the server')
+    console.error('')
+    console.error('Flags (b.1m9):')
+    console.error('  --reconcile-instance-ids   Auto-delete stale pre-rename cscb_<id> AD rows on startup')
     process.exit(1)
   }
 
+  // Resolve a channel's actual claude_instance_id by querying agent-director's
+  // label index. Survives the b.1m9 naming change (cscb_<name>_<id>) without
+  // requiring the CLI to know the route's normalizedName. Returns null when
+  // no cscb row exists for the channel; falls back to bare-ID on a list-level
+  // error so legacy behavior is preserved.
+  async function resolveCscbInstanceId(channelId: string): Promise<string | null> {
+    try {
+      const r = await getClient().list({ label: ['service=cscb', `channel=${channelId}`] })
+      if (r.spawns.length === 0) return null
+      // Prefer the new-naming row if both old and new exist mid-migration.
+      const newStyle = r.spawns.find((s) => s.claude_instance_id !== `cscb_${channelId}`)
+      return (newStyle ?? r.spawns[0]).claude_instance_id
+    } catch {
+      return null
+    }
+  }
+
   const realDeps: CliDeps = {
     spawnSync: (cmd, args) => spawnSync(cmd, args, { stdio: 'ignore' }),
     env: process.env,
@@ -315,8 +340,13 @@ if (import.meta.main) {
     exit: (code) => process.exit(code),
     loadConfig: () => configLoadConfig(),
     directorStatus: async (channelId) => {
+      // Resolve the actual claude_instance_id by label (cscb_<name>_<id> after b.1m9,
+      // or cscb_<id> on pre-rename installs). Falls back to bare-ID lookup if
+      // listing isn't possible, preserving compatibility with single-row stubs.
+      const id = await resolveCscbInstanceId(channelId)
+      if (id === null) return null
       try {
-        const r = await getClient().status({ claude_instance_id: instanceIdFor(channelId) })
+        const r = await getClient().status({ claude_instance_id: id })
         return { state: r.state }
       } catch (err) {
         if (err instanceof ErrSpawnNotFound) return null
@@ -324,11 +354,13 @@ if (import.meta.main) {
       }
     },
     directorPause: async (channelId) => {
-      await getClient().pause({ claude_instance_id: instanceIdFor(channelId) })
+      const id = (await resolveCscbInstanceId(channelId)) ?? instanceIdFor(channelId)
+      await getClient().pause({ claude_instance_id: id })
     },
     directorKill: async (channelId) => {
       try {
-        await getClient().kill({ claude_instance_id: instanceIdFor(channelId) })
+        const id = (await resolveCscbInstanceId(channelId)) ?? instanceIdFor(channelId)
+        await getClient().kill({ claude_instance_id: id })
       } catch (err) {
         if (err instanceof ErrSpawnNotFound) return
         throw err

package/src/config.ts

@@ -76,6 +76,30 @@ export interface RouteEntry {
    * if neither is set).
    */
   claude_config_dir?: string
+  /**
+   * Runtime-resolved Slack channel name (e.g. "horde-agent-director").
+   * Populated by the startup `conversations.info` resolver and refreshed
+   * opportunistically by event handlers. Never read from config.json — these
+   * fields exist on the in-memory record only and the validator rejects them
+   * if present in the JSON payload.
+   */
+  name?: string
+  /**
+   * Runtime-resolved normalized channel name suitable for use in tmux
+   * session names and agent-director `claude_instance_id`. Produced by
+   * `normalizeChannelName(name)` whenever `name` is set.
+   */
+  normalizedName?: string
+}
+
+/**
+ * Normalize a Slack channel name into a token safe for tmux session names
+ * and agent-director `claude_instance_id` values: lowercased, all non
+ * `[a-z0-9]` runs collapsed to a single `_`, and any leading or trailing
+ * underscores stripped. Returns `''` when the input contains no alnum chars.
+ */
+export function normalizeChannelName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
 }
 
 /** Raw shape of config.json as parsed from disk. All optional fields may be absent. */

package/src/server.ts

@@ -44,8 +44,11 @@ import {
   flushSpawnFailureQueue,
   instanceIdFor,
   launchSession,
+  reconcileInstanceIds,
   reconcileOrphans,
   reconnectMcp,
+  refreshRouteNameFromEvent,
+  resolveChannelNames,
   startupSessionManager,
 } from './session-manager.ts'
 import { cleanSession, getCozempicAvailable } from './cozempic.ts'
@@ -682,6 +685,7 @@ socket.on('message', async ({ event, ack }) => {
   await ack()
   if (!event) return
   archiveInboundMessage(event)
+  if (routingConfig) refreshRouteNameFromEvent(routingConfig, event)
   try {
     await handleMessage(event)
   } catch (err) {
@@ -694,6 +698,7 @@ socket.on('app_mention', async ({ event, ack }) => {
   await ack()
   if (!event) return
   archiveInboundMessage(event)
+  if (routingConfig) refreshRouteNameFromEvent(routingConfig, event)
   try {
     await handleMessage(event)
   } catch (err) {
@@ -701,6 +706,15 @@ socket.on('app_mention', async ({ event, ack }) => {
   }
 })
 
+// Capture channel renames as a separate event — Slack delivers a channel_name
+// field here that lets us refresh the cached name without waiting for the next
+// message on the channel.
+socket.on('channel_rename', async ({ event, ack }) => {
+  await ack()
+  if (!event) return
+  if (routingConfig) refreshRouteNameFromEvent(routingConfig, event)
+})
+
 socket.on('interactive', async (evt) => {
   const { ack } = evt as { ack: () => Promise<void> }
   const p = ((evt as any).body ?? (evt as any).payload ?? evt) as Record<string, unknown>
@@ -1085,7 +1099,7 @@ export async function main(): Promise<void> {
   // back to "dead" defensively — health-check will retry.
   const isSessionAliveAdapter = async (channelId: string): Promise<boolean> => {
     if (!routingConfig?.routes[channelId]) return false
-    const claude_instance_id = instanceIdFor(channelId)
+    const claude_instance_id = instanceIdFor(channelId, routingConfig.routes[channelId]?.normalizedName)
     try {
       const r = await getClient().status({ claude_instance_id })
       return AGENT_DIRECTOR_LIVE_STATES.has(r.state)
@@ -1106,11 +1120,12 @@ export async function main(): Promise<void> {
       return session?.connected === true
     },
     reconnectSession: async (channelId) => {
-      await reconnectMcp(channelId, isDryRun() ? undefined : web)
+      await reconnectMcp(channelId, isDryRun() ? undefined : web, routingConfig ?? undefined)
     },
     killSession: async (channelId) => {
       try {
-        await getClient().kill({ claude_instance_id: instanceIdFor(channelId) })
+        const normalizedName = routingConfig?.routes[channelId]?.normalizedName
+        await getClient().kill({ claude_instance_id: instanceIdFor(channelId, normalizedName) })
       } catch (err) {
         if (err instanceof ErrSpawnNotFound) return
         console.error(`[slack] killSession (restart adapter): error for channel=${channelId}:`, err)
@@ -1137,6 +1152,30 @@ export async function main(): Promise<void> {
     }
   }
 
+  // b.1m9: resolve channel names from Slack so per-route spawns get the
+  // glanceable `cscb_<name>_<id>` / `slack_bot_<name>_<id>` naming. Failures
+  // are non-fatal: nameless routes fall back to the legacy bare-ID form.
+  if (routingConfig) {
+    try {
+      await resolveChannelNames(routingConfig, isDryRun() ? undefined : web)
+    } catch (err) {
+      console.error('[slack] Warning: channel-name resolution failed:', err)
+    }
+  }
+
+  // b.1m9: warn about (or, with --reconcile-instance-ids, delete) stale
+  // pre-rename rows whose claude_instance_id doesn't match the new naming.
+  // Must run AFTER name resolution so the expected ids are right.
+  if (routingConfig) {
+    const autoDelete = process.argv.includes('--reconcile-instance-ids') ||
+      process.env['CSCB_RECONCILE_INSTANCE_IDS'] === '1'
+    try {
+      await reconcileInstanceIds(routingConfig, autoDelete)
+    } catch (err) {
+      console.error('[slack] Warning: instance-id reconcile failed:', err)
+    }
+  }
+
   // Per-route reconcile via library: spawnForRoute dispatches fresh-spawn or
   // collision-handling per SR-1.4. Failures are surfaced to the affected Slack
   // channel; the server stays up.

package/src/session-manager.ts

@@ -36,7 +36,7 @@ import type { ListRow, SpawnParams } from 'agent-director'
 import type { WebClient } from '@slack/web-api'
 
 import { checkCozempicAvailable } from './cozempic.ts'
-import { type RoutingConfig, MCP_SERVER_NAME } from './config.ts'
+import { type RoutingConfig, MCP_SERVER_NAME, normalizeChannelName } from './config.ts'
 import { getClient } from './agent-director-client.ts'
 import { recordStartupError } from './startup-errors.ts'
 import { isDryRun } from './tokens.ts'
@@ -61,16 +61,48 @@ export const AGENT_DIRECTOR_LIVE_STATES: ReadonlySet<string> = new Set([
 /** The CSCB-shipped template name (mirrors agent-director-client). */
 const TEMPLATE_NAME = 'slack-channel-bot'
 
-/** Build the deterministic claude_instance_id for a channelId. */
-export function instanceIdFor(channelId: string): string {
+/**
+ * Build the deterministic claude_instance_id for a channelId.
+ *
+ * When `normalizedName` is a non-empty string, the id is composed as
+ * `cscb_${normalizedName}_${channelId}` for operator glanceability in
+ * `agent-director list`. When omitted or empty, falls back to the bare
+ * `cscb_${channelId}` form so callers without a resolved name still produce
+ * a stable id. The channelId always suffixes — it is the canonical key
+ * and survives channel renames.
+ */
+export function instanceIdFor(channelId: string, normalizedName?: string): string {
+  if (normalizedName && normalizedName.length > 0) {
+    return `cscb_${normalizedName}_${channelId}`
+  }
   return `cscb_${channelId}`
 }
 
-/** Build the canonical tmux session name for a channelId. */
-export function tmuxSessionNameFor(channelId: string): string {
+/**
+ * Build the canonical tmux session name for a channelId.
+ *
+ * Mirrors `instanceIdFor` composition: with a name, `slack_bot_${name}_${id}`;
+ * without, `slack_bot_${id}`. The id suffix keeps sessions unique across
+ * channel renames or collisions between channels that normalize identically.
+ */
+export function tmuxSessionNameFor(channelId: string, normalizedName?: string): string {
+  if (normalizedName && normalizedName.length > 0) {
+    return `slack_bot_${normalizedName}_${channelId}`
+  }
   return `slack_bot_${channelId}`
 }
 
+/**
+ * Look up the cached normalized channel name on a route. Returns undefined
+ * when the route is missing or the name has not been resolved yet.
+ */
+export function getNormalizedNameForChannel(
+  channelId: string,
+  routingConfig: RoutingConfig,
+): string | undefined {
+  return routingConfig.routes[channelId]?.normalizedName
+}
+
 // ---------------------------------------------------------------------------
 // Spawn-failure queue — Slack-error surface (SR-1.1 channel-post path)
 // ---------------------------------------------------------------------------
@@ -144,8 +176,12 @@ export function flushSpawnFailureQueue(web: WebClient): void {
  * Send `/mcp reconnect <MCP_SERVER_NAME>` to the spawn's pane. Library's
  * sendKeys appends Enter automatically per its contract.
  */
-export async function reconnectMcp(channelId: string, web?: WebClient): Promise<boolean> {
-  const claude_instance_id = instanceIdFor(channelId)
+export async function reconnectMcp(
+  channelId: string,
+  web?: WebClient,
+  routingConfig?: RoutingConfig,
+): Promise<boolean> {
+  const claude_instance_id = instanceIdFor(channelId, routingConfig?.routes[channelId]?.normalizedName)
   console.error(`[slack] reconnecting MCP server "${MCP_SERVER_NAME}": channel=${channelId}`)
   try {
     await getClient().sendKeys({
@@ -161,6 +197,113 @@ export async function reconnectMcp(channelId: string, web?: WebClient): Promise<
   }
 }
 
+// ---------------------------------------------------------------------------
+// approveDevChannelsDialog — auto-approve the dev-channels warning on spawn
+// ---------------------------------------------------------------------------
+
+/**
+ * Verified against Claude Code 2.1.120 (2026-05-27). If this stops matching,
+ * the dev-channels dialog has drifted — see b.yy6. Match the option label
+ * (semantic, stable) rather than the header (cosmetic, drifts).
+ */
+export const DEV_CHANNELS_DIALOG_NEEDLE = 'I am using this for local development'
+
+/** Default poll interval while watching for the dev-channels dialog. */
+export const DIALOG_POLL_INTERVAL_MS = 500
+
+/** Default deadline for both the appearance poll and the still-visible poll. */
+export const DIALOG_POLL_TIMEOUT_MS = 30_000
+
+/** Number of consecutive "needle absent" reads required to confirm approval. */
+export const DIALOG_GONE_CONFIRMS_REQUIRED = 2
+
+let _dialogPollIntervalMs = DIALOG_POLL_INTERVAL_MS
+let _dialogPollTimeoutMs = DIALOG_POLL_TIMEOUT_MS
+
+/** Test-only seam: override the dev-channels poll interval. */
+export function _setDialogPollIntervalMs(ms: number): void {
+  _dialogPollIntervalMs = ms
+}
+
+/** Test-only seam: restore the default poll interval. */
+export function _resetDialogPollIntervalMs(): void {
+  _dialogPollIntervalMs = DIALOG_POLL_INTERVAL_MS
+}
+
+/** Test-only seam: override the dev-channels poll timeout. */
+export function _setDialogPollTimeoutMs(ms: number): void {
+  _dialogPollTimeoutMs = ms
+}
+
+/** Test-only seam: restore the default poll timeout. */
+export function _resetDialogPollTimeoutMs(): void {
+  _dialogPollTimeoutMs = DIALOG_POLL_TIMEOUT_MS
+}
+
+/**
+ * Poll the freshly-spawned bot's tmux pane until the dev-channels approval
+ * dialog appears, send Enter to accept the pre-selected
+ * "I am using this for local development" option, then confirm the dialog
+ * has cleared. All errors caught locally — never throws to the caller.
+ *
+ * readPane/sendKeys use `allow_pending: true` because the bot is still in
+ * `pending` AD state when this runs (b.98w — formerly caused ErrSpawnNotInteractive).
+ *
+ * Two distinct failure modes are recorded via `recordStartupError` so a
+ * future Claude Code release that changes the dialog cannot silently break
+ * fresh-spawn approval:
+ *   - `dev-channels-approve-no-dialog`   — needle never observed
+ *   - `dev-channels-approve-still-visible` — needle persists after Enter
+ */
+export async function approveDevChannelsDialog(
+  channelId: string,
+  web: WebClient | undefined,
+  isStartup: boolean,
+): Promise<void> {
+  void web
+  const claude_instance_id = instanceIdFor(channelId)
+  const client = getClient()
+  const deadline = Date.now() + _dialogPollTimeoutMs
+
+  let approved = false
+  while (Date.now() < deadline) {
+    try {
+      const { pane } = await client.readPane({ claude_instance_id, n_lines: 40, allow_pending: true })
+      if (pane.includes(DEV_CHANNELS_DIALOG_NEEDLE)) {
+        await client.sendKeys({ claude_instance_id, text: '', allow_pending: true })
+        approved = true
+        break
+      }
+    } catch (err) {
+      console.error(`[slack] approveDevChannelsDialog: readPane error channel=${channelId}: ${String(err)}`)
+    }
+    await new Promise((r) => setTimeout(r, _dialogPollIntervalMs))
+  }
+
+  if (!approved) {
+    const msg = `dev-channels dialog never appeared for channel=${channelId} within ${_dialogPollTimeoutMs}ms (dialog text may have drifted — see b.yy6)`
+    console.error(`[slack] approveDevChannelsDialog: ${msg}`)
+    if (isStartup) recordStartupError('dev-channels-approve-no-dialog', msg)
+    return
+  }
+
+  let misses = 0
+  while (Date.now() < deadline && misses < DIALOG_GONE_CONFIRMS_REQUIRED) {
+    await new Promise((r) => setTimeout(r, _dialogPollIntervalMs))
+    try {
+      const { pane } = await client.readPane({ claude_instance_id, n_lines: 40, allow_pending: true })
+      misses = pane.includes(DEV_CHANNELS_DIALOG_NEEDLE) ? 0 : misses + 1
+    } catch {
+      /* tolerate transient readPane failure */
+    }
+  }
+  if (misses < DIALOG_GONE_CONFIRMS_REQUIRED) {
+    const msg = `dev-channels dialog still visible after Enter for channel=${channelId} (sendKeys may not have reached pane)`
+    console.error(`[slack] approveDevChannelsDialog: ${msg}`)
+    if (isStartup) recordStartupError('dev-channels-approve-still-visible', msg)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // waitForWaitingAndReconnect — used when a colliding spawn is in `working`
 // ---------------------------------------------------------------------------
@@ -191,7 +334,7 @@ export async function waitForWaitingAndReconnect(
   routingConfig: RoutingConfig,
   web?: WebClient,
 ): Promise<boolean> {
-  const claude_instance_id = instanceIdFor(channelId)
+  const claude_instance_id = instanceIdFor(channelId, routingConfig.routes[channelId]?.normalizedName)
   const pollIntervalMs = routingConfig.agent_director_poll_interval_ms
   const deadline = Date.now() + _waitForWaitingTimeoutMs
 
@@ -212,7 +355,7 @@ export async function waitForWaitingAndReconnect(
     }
 
     if (state === 'waiting') {
-      return reconnectMcp(channelId, web)
+      return reconnectMcp(channelId, web, routingConfig)
     }
 
     if (state === 'working') {
@@ -247,12 +390,13 @@ function buildSpawnParams(
 ): SpawnParams {
   const effectiveConfigDir =
     routingConfig.routes[channelId]?.claude_config_dir ?? routingConfig.claude_config_dir
+  const normalizedName = routingConfig.routes[channelId]?.normalizedName
   const params: SpawnParams = {
     template: TEMPLATE_NAME,
     cwd: route.cwd,
-    claude_instance_id: instanceIdFor(channelId),
+    claude_instance_id: instanceIdFor(channelId, normalizedName),
     relay_mode: 'on',
-    tmux_session_name: tmuxSessionNameFor(channelId),
+    tmux_session_name: tmuxSessionNameFor(channelId, normalizedName),
     label: ['service=cscb', `channel=${channelId}`],
   }
   if (effectiveConfigDir) {
@@ -262,18 +406,23 @@ function buildSpawnParams(
 }
 
 /** Best-effort kill — never throws. */
-async function tryKill(channelId: string): Promise<void> {
+async function tryKill(channelId: string, normalizedName: string | undefined): Promise<void> {
   try {
-    await getClient().kill({ claude_instance_id: instanceIdFor(channelId) })
+    await getClient().kill({ claude_instance_id: instanceIdFor(channelId, normalizedName) })
   } catch {
     /* ignore */
   }
 }
 
 /** Delete the spawn row; surface failures. Returns whether the delete succeeded. */
-async function tryDelete(channelId: string, web: WebClient | undefined, isStartup: boolean): Promise<boolean> {
+async function tryDelete(
+  channelId: string,
+  normalizedName: string | undefined,
+  web: WebClient | undefined,
+  isStartup: boolean,
+): Promise<boolean> {
   try {
-    await getClient().delete({ claude_instance_id: [instanceIdFor(channelId)] })
+    await getClient().delete({ claude_instance_id: [instanceIdFor(channelId, normalizedName)] })
     return true
   } catch (err) {
     const e = err instanceof AgentDirectorError ? err : new AgentDirectorError('delete', 'UnknownError', String(err))
@@ -311,12 +460,14 @@ export async function spawnForRoute(
   }
 
   const params = buildSpawnParams(channelId, route, routingConfig)
+  const normalizedName = routingConfig.routes[channelId]?.normalizedName
   const client = getClient()
 
   // Attempt fresh spawn ---
   try {
     const r = await client.spawn(params)
     console.error(`[slack] spawnForRoute: spawned channel=${channelId} instanceId=${r.claude_instance_id}`)
+    await approveDevChannelsDialog(channelId, web, isStartup)
     return { channelId, action: 'spawned' }
   } catch (err) {
     if (!(err instanceof ErrInstanceIdCollision)) {
@@ -333,7 +484,7 @@ export async function spawnForRoute(
   // Collision-handling: get-then-act ---
   let state: string
   try {
-    const r = await client.get({ claude_instance_id: instanceIdFor(channelId) })
+    const r = await client.get({ claude_instance_id: instanceIdFor(channelId, normalizedName) })
     state = r.state
   } catch (err) {
     if (err instanceof ErrSpawnNotFound) {
@@ -342,6 +493,7 @@ export async function spawnForRoute(
       try {
         const r = await client.spawn(params)
         console.error(`[slack] spawnForRoute: retry-spawn succeeded for channel=${channelId} instanceId=${r.claude_instance_id}`)
+        await approveDevChannelsDialog(channelId, web, isStartup)
         return { channelId, action: 'spawned' }
       } catch (err2) {
         const e = err2 instanceof AgentDirectorError ? err2 : new AgentDirectorError('spawn', 'UnknownError', String(err2))
@@ -362,11 +514,12 @@ export async function spawnForRoute(
   if (state === 'ended' || state === 'missing') {
     if (routingConfig.resume_enabled === false) {
       console.error(`[slack] spawnForRoute: resume_enabled=false — kill+delete+fresh for channel=${channelId}`)
-      await tryKill(channelId)
-      if (!(await tryDelete(channelId, web, isStartup))) return { channelId, action: 'failed' }
+      await tryKill(channelId, normalizedName)
+      if (!(await tryDelete(channelId, normalizedName, web, isStartup))) return { channelId, action: 'failed' }
       try {
         await client.spawn(params)
         console.error(`[slack] spawnForRoute: fresh-spawned (after kill+delete) for channel=${channelId}`)
+        await approveDevChannelsDialog(channelId, web, isStartup)
         return { channelId, action: 'spawned' }
       } catch (err) {
         const e = err instanceof AgentDirectorError ? err : new AgentDirectorError('spawn', 'UnknownError', String(err))
@@ -380,16 +533,17 @@ export async function spawnForRoute(
     // resume_enabled: attempt resume
     console.error(`[slack] spawnForRoute: attempting resume for channel=${channelId}`)
     try {
-      await client.resume({ claude_instance_id: instanceIdFor(channelId) })
+      await client.resume({ claude_instance_id: instanceIdFor(channelId, normalizedName) })
       console.error(`[slack] spawnForRoute: resumed channel=${channelId}`)
       return { channelId, action: 'resumed' }
     } catch (err) {
       if (err instanceof ErrNoSessionId || err instanceof ErrJsonlMissing) {
         console.error(`[slack] spawnForRoute: ${err.errName} on resume for channel=${channelId} — delete+fresh`)
-        if (!(await tryDelete(channelId, web, isStartup))) return { channelId, action: 'failed' }
+        if (!(await tryDelete(channelId, normalizedName, web, isStartup))) return { channelId, action: 'failed' }
         try {
           await client.spawn(params)
           console.error(`[slack] spawnForRoute: fresh-spawned (after delete) for channel=${channelId}`)
+          await approveDevChannelsDialog(channelId, web, isStartup)
           return { channelId, action: 'spawned' }
         } catch (err2) {
           const e = err2 instanceof AgentDirectorError ? err2 : new AgentDirectorError('spawn', 'UnknownError', String(err2))
@@ -402,10 +556,11 @@ export async function spawnForRoute(
       if (err instanceof ErrSpawnNotResumable) {
         // Row is non-terminal but resume rejected — defensive: kill + delete + spawn
         console.error(`[slack] spawnForRoute: ErrSpawnNotResumable for channel=${channelId} — kill+delete+fresh`)
-        await tryKill(channelId)
-        if (!(await tryDelete(channelId, web, isStartup))) return { channelId, action: 'failed' }
+        await tryKill(channelId, normalizedName)
+        if (!(await tryDelete(channelId, normalizedName, web, isStartup))) return { channelId, action: 'failed' }
         try {
           await client.spawn(params)
+          await approveDevChannelsDialog(channelId, web, isStartup)
           return { channelId, action: 'spawned' }
         } catch (err2) {
           const e = err2 instanceof AgentDirectorError ? err2 : new AgentDirectorError('spawn', 'UnknownError', String(err2))
@@ -422,7 +577,7 @@ export async function spawnForRoute(
   }
 
   if (state === 'waiting') {
-    await reconnectMcp(channelId, web)
+    await reconnectMcp(channelId, web, routingConfig)
     return { channelId, action: 'reconnected' }
   }
 
@@ -525,6 +680,220 @@ export async function reconcileOrphans(
   return { found, killed, failed }
 }
 
+// ---------------------------------------------------------------------------
+// Channel-name resolution (b.1m9)
+// ---------------------------------------------------------------------------
+
+export interface ChannelNameResolveResult {
+  channelId: string
+  name?: string
+  normalizedName?: string
+  /** When set, conversations.info failed; route stays nameless and falls back to bare-ID naming. */
+  error?: string
+}
+
+/** Minimal WebClient surface this module needs — just conversations.info. */
+export type ChannelInfoClient = {
+  conversations: {
+    info: (args: { channel: string }) => Promise<{ channel?: { name?: string } }>
+  }
+}
+
+/**
+ * Resolve and cache Slack channel names for every route at startup.
+ *
+ * For each `routingConfig.routes[channelId]`, call `conversations.info` once
+ * and stash the result on `route.name` + `route.normalizedName`. Sessions
+ * spawned during startup then carry the new `slack_bot_<name>_<id>` /
+ * `cscb_<name>_<id>` naming for operator glanceability.
+ *
+ * Failure is non-fatal: any per-route rejection (network, missing scope,
+ * unknown channel, no `channel.name` field) logs a single line and leaves
+ * the route nameless. `instanceIdFor` / `tmuxSessionNameFor` then fall back
+ * to bare-ID naming, preserving pre-b.1m9 behavior for that one route.
+ *
+ * Mutates `routingConfig.routes` in place. Returns per-route diagnostics for
+ * the operator and for tests.
+ */
+export async function resolveChannelNames(
+  routingConfig: RoutingConfig,
+  web: ChannelInfoClient | undefined,
+): Promise<ChannelNameResolveResult[]> {
+  const results: ChannelNameResolveResult[] = []
+  if (!web) {
+    // Dry-run or otherwise no WebClient — leave every route nameless.
+    console.error('[slack] resolveChannelNames: no WebClient available — skipping')
+    return results
+  }
+  for (const [channelId, route] of Object.entries(routingConfig.routes)) {
+    try {
+      const resp = await web.conversations.info({ channel: channelId })
+      const name = resp.channel?.name
+      if (!name) {
+        const r: ChannelNameResolveResult = { channelId, error: 'no name on conversations.info response' }
+        console.error(`[slack] resolveChannelNames: channel=${channelId} → (no name) — falling back to bare-ID`)
+        results.push(r)
+        continue
+      }
+      const normalizedName = normalizeChannelName(name)
+      route.name = name
+      route.normalizedName = normalizedName.length > 0 ? normalizedName : undefined
+      console.error(
+        `[slack] resolveChannelNames: channel=${channelId} → "${name}" (normalized="${route.normalizedName ?? ''}")`,
+      )
+      results.push({ channelId, name, normalizedName: route.normalizedName })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      console.error(`[slack] resolveChannelNames: channel=${channelId} → error: ${msg} — falling back to bare-ID`)
+      results.push({ channelId, error: msg })
+    }
+  }
+  return results
+}
+
+/**
+ * Opportunistically refresh a route's cached channel name from an incoming
+ * Slack event. Slack only includes `channel.name` on some event types
+ * (channel_rename, channel_archive, etc.); message events typically don't
+ * carry it. When it IS present, refreshing here covers channel renames
+ * without a CSCB restart.
+ *
+ * No-ops when the event has no channel name, no matching route, or the
+ * cached name is already up to date.
+ */
+export function refreshRouteNameFromEvent(
+  routingConfig: RoutingConfig,
+  event: unknown,
+): void {
+  if (!event || typeof event !== 'object') return
+  const ev = event as Record<string, unknown>
+
+  let channelId: string | undefined
+  let channelName: string | undefined
+
+  // Form A: { channel: 'C…', channel_name: 'foo' } — used by channel_rename
+  if (typeof ev['channel'] === 'string') {
+    channelId = ev['channel'] as string
+    if (typeof ev['channel_name'] === 'string') channelName = ev['channel_name'] as string
+  }
+  // Form B: { channel: { id: 'C…', name: 'foo' } } — used by channel_archive, etc.
+  if (channelName === undefined && ev['channel'] && typeof ev['channel'] === 'object') {
+    const ch = ev['channel'] as Record<string, unknown>
+    if (typeof ch['id'] === 'string') channelId = ch['id'] as string
+    if (typeof ch['name'] === 'string') channelName = ch['name'] as string
+  }
+
+  if (!channelId || !channelName) return
+  const route = routingConfig.routes[channelId]
+  if (!route) return
+  if (route.name === channelName) return
+
+  const normalizedName = normalizeChannelName(channelName)
+  route.name = channelName
+  route.normalizedName = normalizedName.length > 0 ? normalizedName : undefined
+  console.error(
+    `[slack] refreshRouteNameFromEvent: channel=${channelId} → "${channelName}" (normalized="${route.normalizedName ?? ''}")`,
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Instance-id migration (b.1m9)
+// ---------------------------------------------------------------------------
+
+export interface InstanceIdMigrationResult {
+  /** Rows whose claude_instance_id doesn't match the route's expected new-naming id. */
+  orphans: Array<{ channelId: string; oldInstanceId: string; expectedInstanceId: string }>
+  /** When auto-delete is on: count of rows we successfully removed. */
+  deleted: number
+  /** When auto-delete is on: count of rows whose delete failed. */
+  failed: number
+}
+
+/**
+ * Detect agent-director rows whose `claude_instance_id` predates the b.1m9
+ * naming change (`cscb_<id>`) for channels we now spawn as
+ * `cscb_<name>_<id>`. The bare-ID rows are orphans the next time the server
+ * starts; the new-naming spawn won't collide with them, so they linger.
+ *
+ * Default behavior: warn only, one line per orphan listing the exact
+ * `agent-director delete --claude-instance-id …` command the operator can
+ * paste. With `autoDelete=true`, this function calls `client.delete` for
+ * each orphan instead.
+ *
+ * Note: a row whose channel label is not in `routingConfig.routes` at all
+ * is handled by `reconcileOrphans` (SR-1.6), not here.
+ */
+export async function reconcileInstanceIds(
+  routingConfig: RoutingConfig,
+  autoDelete: boolean,
+): Promise<InstanceIdMigrationResult> {
+  const empty: InstanceIdMigrationResult = { orphans: [], deleted: 0, failed: 0 }
+  if (isDryRun()) {
+    console.error('[slack] dry-run: skipping instance-id reconcile')
+    return empty
+  }
+
+  const client = getClient()
+  let rows: ListRow[]
+  try {
+    const r = await client.list({ label: ['service=cscb'] })
+    rows = r.spawns
+  } catch (err) {
+    const e = err instanceof AgentDirectorError ? err : new AgentDirectorError('list', 'UnknownError', String(err))
+    console.error(`[slack] reconcileInstanceIds: list failed — skipping: ${e.errName}`)
+    return empty
+  }
+
+  const orphans: InstanceIdMigrationResult['orphans'] = []
+  for (const row of rows) {
+    const channelId = row.labels['channel']
+    if (!channelId) continue
+    const route = routingConfig.routes[channelId]
+    if (!route) continue // covered by reconcileOrphans
+    const expected = instanceIdFor(channelId, route.normalizedName)
+    if (row.claude_instance_id === expected) continue
+    orphans.push({ channelId, oldInstanceId: row.claude_instance_id, expectedInstanceId: expected })
+  }
+
+  if (orphans.length === 0) {
+    return empty
+  }
+
+  if (!autoDelete) {
+    console.error(
+      `[slack] reconcileInstanceIds: found ${orphans.length} row(s) with stale claude_instance_id ` +
+        `(pre-b.1m9 naming). The new spawn(s) will not collide; the old row(s) will linger. ` +
+        `Pass --reconcile-instance-ids to auto-delete, or run the commands below:`,
+    )
+    for (const o of orphans) {
+      console.error(
+        `[slack] reconcileInstanceIds: channel=${o.channelId} stale=${o.oldInstanceId} ` +
+          `expected=${o.expectedInstanceId} — agent-director delete --claude-instance-id ${o.oldInstanceId}`,
+      )
+    }
+    return { orphans, deleted: 0, failed: 0 }
+  }
+
+  let deleted = 0
+  let failed = 0
+  for (const o of orphans) {
+    console.error(
+      `[slack] reconcileInstanceIds: deleting stale row channel=${o.channelId} instanceId=${o.oldInstanceId}`,
+    )
+    try {
+      await client.delete({ claude_instance_id: [o.oldInstanceId] })
+      deleted++
+    } catch (err) {
+      const e = err instanceof AgentDirectorError ? err : new AgentDirectorError('delete', 'UnknownError', String(err))
+      console.error(
+        `[slack] reconcileInstanceIds: delete failed for channel=${o.channelId} instanceId=${o.oldInstanceId}: ${e.errName}`,
+      )
+      failed++
+    }
+  }
+  return { orphans, deleted, failed }
+}
+
 // ---------------------------------------------------------------------------
 // startupSessionManager — iterate routes and dispatch per-channel
 // ---------------------------------------------------------------------------