feat(chat): Slack bidirectional driver with attested approvals (#1804)

Replaces the NotImplementedError stub in
``src/bernstein/core/chat/drivers/slack.py`` with a Socket Mode driver
that conforms to ``BridgeProtocol`` end to end: slash dispatch, button
decode, edit debounce, signed outbound messages, worktree-pinned
approvals, and chained audit-log entries.

* Outbound messages carry an Ed25519 detached signature over
  ``(install_id, session_id, content_hash)``; ``verify_chat_signature``
  lets a recipient with the install's public key confirm authenticity
  and reject foreign-install forgeries.
* Each Slack approval resolution lands as a ``chat.slack.approval``
  event in the existing HMAC-chained ``AuditLog``; replay over the
  exported chain reproduces the post-approval scheduler state
  byte-identically (covered by the new integration test).
* Cross-worktree approvals raise ``CrossWorktreeApprovalError`` and
  log a ``chat.slack.approval_rejected`` entry so the bypass attempt is
  visible to the operator.
* ``edit_message`` debounces ``chat.update`` to one call per channel
  per second, comfortably below Slack's per-channel rate limit.
* Optional ``bernstein[slack]`` extra pulls in ``slack-sdk``; the
  ``start()`` path raises ``SlackDependencyError`` with a pointer to
  the extra when the SDK is absent.

CLI integration: ``bernstein chat serve --platform=slack`` reads the
bot token from ``BERNSTEIN_SLACK_TOKEN`` and the Socket Mode app token
from ``BERNSTEIN_SLACK_APP_TOKEN``. Docs added at
``docs/operations/chat-bridges.md``.

Closes #1794

Co-authored-by: auto-heal-fixup <auto-heal-fixup@bernstein.local>

Author: chernistry

CHANGELOG.md

@@ -9,11 +9,13 @@ All notable project changes are tracked here (code + docs).
 - `bernstein desktop-register --host <name>` covers the remaining priority hosts: Cursor, Continue, Cline, Zed, and Aider, alongside the existing Claude Desktop and Claude Code adapters. JSON hosts merge into their canonical `mcpServers` map (or `context_servers` for Zed); Aider records the entry in its YAML config under `mcp-servers` for community-wrapper consumption (#1676).
 - `bernstein doctor --substrate` reports which detected hosts have Bernstein registered, which do not, and which are stale (canonical command/args differ from the recorded entry) (#1676).
 - Operator docs at `docs/substrate/{cursor,continue,cline,zed,aider}.md` cover install, verification, and uninstall per host (#1676).
+- Slack bidirectional driver with attested approvals: `bernstein chat serve --platform=slack` connects via Socket Mode, dispatches `/bernstein` slash subcommands, decodes Approve/Reject block actions, debounces `chat.update` per channel, signs every outbound message with an Ed25519 detached signature over `(install_id, session_id, content_hash)`, and appends each approval resolution to the HMAC-chained audit log as a `chat.slack.approval` event covering `(approver, message_ts, decision, tool_call_hash, worktree_id)`. Approvals are worktree-pinned: cross-worktree resolutions raise `CrossWorktreeApprovalError` and emit a `chat.slack.approval_rejected` audit entry. Optional `bernstein[slack]` extra pulls in `slack-sdk` (#1794).
+- `docs/operations/chat-bridges.md` documents the Telegram and Slack drivers, the env-var contract, the signed metadata envelope, and how to verify an outbound Slack message offline (#1794).
 
 ### Changed
 
 - `bernstein audit export --standard` no longer accepts `dora` or `finos-aigf`; the click choice list is `ai-act` only. The previous control maps for those two standards contained only placeholder rows (`status: "todo"`, `selector: "TODO"`) and have been removed from `SUPPORTED_STANDARDS` until their clause mappings are reviewed by subject-matter experts. Operators who pass either value now receive a clean usage error rather than a TODO-only zip (#1316).
-- `DiscordBridge.on_command` / `on_button` and `SlackBridge.on_command` / `on_button` now raise `NotImplementedError` at registration time instead of silently dropping the handler. Callers that wire handlers up front against the unimplemented drivers will see the failure immediately rather than at the first network call.
+- `DiscordBridge.on_command` / `on_button` now raise `NotImplementedError` at registration time instead of silently dropping the handler. Callers that wire handlers up front against the unimplemented drivers will see the failure immediately rather than at the first network call.
 
 ## [2.5.0] - Interoperability surfaces, host portability, deterministic replay
 

docs/operations/chat-bridges.md

@@ -0,0 +1,86 @@
+# Chat bridges
+
+Bernstein ships bidirectional chat drivers so operators can drive a session,
+approve tool calls, and watch streamed agent output from a messaging app
+without keeping a terminal open. Bridges are configured per-platform via
+`bernstein chat serve --platform=<name>`.
+
+## Supported platforms
+
+| Platform | Status | Optional extra | Tokens |
+|----------|--------|---------------|--------|
+| Telegram | Production | `pip install 'bernstein[telegram]'` | `BERNSTEIN_TELEGRAM_TOKEN` |
+| Slack    | Production | `pip install 'bernstein[slack]'`    | `BERNSTEIN_SLACK_TOKEN` (bot) + `BERNSTEIN_SLACK_APP_TOKEN` (Socket Mode app) |
+| Discord  | Stub only  | n/a                                 | n/a |
+
+## Slack setup
+
+1. Create a Slack app and enable Socket Mode.
+2. Add the scopes `chat:write`, `commands`, `app_mentions:read`, plus any
+   scopes your slash command surface needs.
+3. Generate an app-level token (`xapp-...`) with the `connections:write`
+   scope. Install the app to your workspace and copy the bot token
+   (`xoxb-...`).
+4. Map a `/bernstein` slash command in your Slack app configuration. The
+   driver routes subcommands (`run`, `approve`, `reject`, `status`,
+   `switch`, `stop`, `handoff`) from the text body of the slash payload.
+5. Set the two env vars:
+
+   ```sh
+   export BERNSTEIN_SLACK_TOKEN=xoxb-...
+   export BERNSTEIN_SLACK_APP_TOKEN=xapp-...
+   ```
+
+6. Start the bridge:
+
+   ```sh
+   bernstein chat serve --platform=slack
+   ```
+
+## What the driver guarantees
+
+- **Slash dispatch and button decode.** `/bernstein run "..."` and the
+  inline `Approve` / `Reject` buttons are routed through the same handler
+  surface as the Telegram driver.
+- **Edit debounce.** Streaming agent output collapses into one
+  `chat.update` per channel per second so Slack's per-channel rate limit
+  on `chat.update` stays comfortably out of reach.
+- **Attested approvals.** Every approval resolution is appended to the
+  HMAC-chained audit log as a `chat.slack.approval` event whose details
+  cover `(approver, message_ts, decision, tool_call_hash, worktree_id)`.
+  Replaying the chain reproduces the post-approval scheduler state
+  byte-identically.
+- **Worktree pinning.** An `/approve` for a worker bound to worktree
+  `wt-a` cannot resolve a pending approval registered against a
+  different worktree. Cross-worktree attempts log a
+  `chat.slack.approval_rejected` audit entry and raise
+  `CrossWorktreeApprovalError` so the bypass is visible to the operator.
+- **Outbound message signing.** Every outbound chat message carries an
+  Ed25519 detached signature over `(install_id, session_id,
+  content_hash)`. A recipient with the install's public key can verify
+  the message was not injected by another bernstein install
+  impersonating the workspace.
+
+## Verifying a Slack message
+
+```python
+from bernstein.core.chat.drivers.slack import verify_chat_signature
+
+ok = verify_chat_signature(
+    install_id="<the install id that posted>",
+    session_id="<session id from the metadata envelope>",
+    content="<text content of the message>",
+    signature="<base64 signature from metadata.event_payload>",
+    public_key_pem=open(".bernstein/keys/slack/slack-bridge.ed25519.pub", "rb").read(),
+)
+```
+
+Returns `True` on cryptographic match, `False` on tampered content or a
+foreign install public key.
+
+## Missing SDK behaviour
+
+`bernstein chat serve --platform=slack` raises a structured
+`SlackDependencyError` when `slack-sdk` is not installed, with a
+pointer to `pip install 'bernstein[slack]'`. Install the extra, or
+switch to a platform whose SDK is already on the host.

pyproject.toml

@@ -192,6 +192,13 @@ r2 = ["boto3>=1.43.6"]
 # Standard Telegram bot integration via long-poll: configure the bot
 # token (from @BotFather) and the chat id, no external services.
 telegram = ["python-telegram-bot>=22.7"]
+# Slack bidirectional driver over Socket Mode. Enable with:
+#   pip install 'bernstein[slack]'
+# Configure a Slack app with bot scopes (``chat:write``, ``commands``),
+# enable Socket Mode, and set ``BERNSTEIN_SLACK_TOKEN`` (xoxb-...) plus
+# ``BERNSTEIN_SLACK_APP_TOKEN`` (xapp-...) before invoking ``bernstein
+# chat serve --platform=slack``.
+slack = ["slack-sdk>=3.27", "aiohttp>=3.9"]
 # Contamination-resistant eval harness (SWE-bench Pro / Terminal-Bench 2.0 /
 # SWE-rebench). Kept optional so production installs don't pull HuggingFace
 # datasets unless the operator opts into the nightly leaderboard path.

src/bernstein/cli/commands/chat_cmd.py

@@ -50,6 +50,11 @@
     "slack": "BERNSTEIN_SLACK_TOKEN",
 }
 
+#: Slack Socket Mode app-level token env var. Bot token (``xoxb-...``) goes
+#: in ``BERNSTEIN_SLACK_TOKEN``; the Socket Mode app token (``xapp-...``)
+#: lives separately so operators can rotate the two independently.
+_SLACK_APP_TOKEN_ENV = "BERNSTEIN_SLACK_APP_TOKEN"
+
 
 @click.group("chat")
 def chat_group() -> None:
@@ -86,7 +91,7 @@ def chat_serve(platform: str, token: str | None, allow: str | None) -> None:
     allow_list = load_allow_list(workdir / "bernstein.yaml", cli_override=overrides)
     bindings = BindingStore(workdir)
     driver_cls: Any = load_driver(platform)
-    bridge: BridgeProtocol = driver_cls(resolved_token)
+    bridge: BridgeProtocol = _instantiate_bridge(driver_cls, platform, resolved_token)
     session = ChatSession(bridge, bindings, allow_list, workdir)
     session.install_handlers()
 
@@ -608,6 +613,25 @@ def _resolve_chat_token(platform: str) -> str:
     return os.environ.get(_ENV_TOKEN_MAP[platform], "")
 
 
+def _instantiate_bridge(driver_cls: Any, platform: str, token: str) -> BridgeProtocol:
+    """Construct the driver with platform-appropriate kwargs.
+
+    Telegram and Discord take a single ``token`` positional; Slack
+    additionally needs the Socket Mode app token from
+    ``BERNSTEIN_SLACK_APP_TOKEN``. Surface a clear error rather than
+    instantiating with an empty app token (the driver itself rejects it,
+    but the CLI's message is more actionable).
+    """
+    if platform == "slack":
+        app_token = os.environ.get(_SLACK_APP_TOKEN_ENV, "")
+        if not app_token:
+            raise click.UsageError(
+                f"Slack requires the Socket Mode app token in ${_SLACK_APP_TOKEN_ENV} (in addition to the bot token).",
+            )
+        return driver_cls(token=token, app_token=app_token)
+    return driver_cls(token)
+
+
 def _extract_quoted_goal(msg: ChatMessage) -> str:
     """Parse the goal from ``/run "..."`` style commands.