ctrlrelay 0.11.3__tar.gz → 0.12.0__tar.gz

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-06
+
+### Added
+
+- Mattermost transport, and a transport-neutral bridge (#180)
+
+### Fixed
+
+- Write the transport the operator asked for, and document the choice (#184)
+- Resolve the bridge socket for whichever transport is set (#183)
+- Say the real reason instead of "Unknown error" (#182)
+- Refuse a reply whose reply-to names a non-routable session (#178)
+
 ## [0.11.3] - 2026-09-12
 
 ### Fixed
@@ -1658,7 +1671,8 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.3...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.3...v0.12.0
 [0.11.3]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.2...v0.11.3
 [0.11.2]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.1...v0.11.2
 [0.11.1]: https://github.com/AInvirion/ctrlrelay/compare/v0.11.0...v0.11.1

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.11.3
+Version: 0.12.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/
@@ -25,11 +25,13 @@ Classifier: Topic :: Software Development :: Version Control :: Git
 Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.12
 Requires-Dist: apscheduler>=3.10.0
+Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-telegram-bot>=21.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.12.0
+Requires-Dist: websockets>=12.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
@@ -48,7 +50,8 @@ Description-Content-Type: text/markdown
 
 > Local-first orchestrator for headless coding agents across your GitHub
 > repos. Watches for assigned issues, runs a dev pipeline in an isolated
-> git worktree, opens a PR, and asks you on Telegram when it gets stuck.
+> git worktree, opens a PR, and asks you on Telegram or Mattermost when it
+> gets stuck.
 
 ## Table of Contents
 
@@ -78,7 +81,7 @@ Your agent credentials, your GitHub credentials, your repos, your
 machine.
 
 Today `ctrlrelay` ships with a Claude Code (`claude -p`) backend. The
-orchestrator layer — worktrees, state DB, scheduler, Telegram bridge —
+orchestrator layer — worktrees, state DB, scheduler, chat bridge —
 is agent-agnostic, and plug-in backends for other headless coding agents
 are on the roadmap (see [Roadmap](#roadmap)).
 
@@ -90,11 +93,15 @@ are on the roadmap (see [Roadmap](#roadmap)).
   and opens a PR. Label triggers let a teammate without rights on your
   account flag an issue as safe for the bot to pick up —
   see [`include_labels`][docs-config].
-- **Telegram bridge.** When a session hits a blocking question, the
-  bridge relays it to you as a DM and resumes the session once you
-  reply.
+- **Chat bridge.** When a session hits a blocking question, the bridge
+  relays it to you and resumes the session once you reply. Choose
+  **Telegram** (a DM from a bot) or **Mattermost** (a channel on your own
+  server) with one `transport.type` setting. Exactly one is active at a
+  time; running both at once is not supported yet
+  ([#176](https://github.com/AInvirion/ctrlrelay/issues/176)). See
+  [configuration][docs-config].
 - **PR watcher.** Tracks the opened PR to merge and closes the loop
-  with a Telegram notification.
+  with a notification on whichever chat transport is configured.
 - **In-process scheduler** (APScheduler). Runs periodic jobs inside
   the poller daemon. Ships with a `secops` job that reviews Dependabot
   alerts and PRs daily at 6am; cron expressions follow standard Vixie
@@ -153,8 +160,10 @@ a launchd/systemd-supervised daemon.
   independent reviewer for the agent's output; you can disable it by
   setting `code_review.method: "none"` in your config if you prefer to
   skip the review step.
-- *(Optional)* a Telegram bot token if you want the bridge — see
-  [Telegram bridge docs][docs-bridge].
+- *(Optional)* if you want the bridge, credentials for one chat
+  transport: a **Telegram** bot token, or a **Mattermost** server URL,
+  bot token and channel ID — see [bridge docs][docs-bridge] and
+  [configuration][docs-config].
 
 ### Installation
 

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/README.md

@@ -9,7 +9,8 @@
 
 > Local-first orchestrator for headless coding agents across your GitHub
 > repos. Watches for assigned issues, runs a dev pipeline in an isolated
-> git worktree, opens a PR, and asks you on Telegram when it gets stuck.
+> git worktree, opens a PR, and asks you on Telegram or Mattermost when it
+> gets stuck.
 
 ## Table of Contents
 
@@ -39,7 +40,7 @@ Your agent credentials, your GitHub credentials, your repos, your
 machine.
 
 Today `ctrlrelay` ships with a Claude Code (`claude -p`) backend. The
-orchestrator layer — worktrees, state DB, scheduler, Telegram bridge —
+orchestrator layer — worktrees, state DB, scheduler, chat bridge —
 is agent-agnostic, and plug-in backends for other headless coding agents
 are on the roadmap (see [Roadmap](#roadmap)).
 
@@ -51,11 +52,15 @@ are on the roadmap (see [Roadmap](#roadmap)).
   and opens a PR. Label triggers let a teammate without rights on your
   account flag an issue as safe for the bot to pick up —
   see [`include_labels`][docs-config].
-- **Telegram bridge.** When a session hits a blocking question, the
-  bridge relays it to you as a DM and resumes the session once you
-  reply.
+- **Chat bridge.** When a session hits a blocking question, the bridge
+  relays it to you and resumes the session once you reply. Choose
+  **Telegram** (a DM from a bot) or **Mattermost** (a channel on your own
+  server) with one `transport.type` setting. Exactly one is active at a
+  time; running both at once is not supported yet
+  ([#176](https://github.com/AInvirion/ctrlrelay/issues/176)). See
+  [configuration][docs-config].
 - **PR watcher.** Tracks the opened PR to merge and closes the loop
-  with a Telegram notification.
+  with a notification on whichever chat transport is configured.
 - **In-process scheduler** (APScheduler). Runs periodic jobs inside
   the poller daemon. Ships with a `secops` job that reviews Dependabot
   alerts and PRs daily at 6am; cron expressions follow standard Vixie
@@ -114,8 +119,10 @@ a launchd/systemd-supervised daemon.
   independent reviewer for the agent's output; you can disable it by
   setting `code_review.method: "none"` in your config if you prefer to
   skip the review step.
-- *(Optional)* a Telegram bot token if you want the bridge — see
-  [Telegram bridge docs][docs-bridge].
+- *(Optional)* if you want the bridge, credentials for one chat
+  transport: a **Telegram** bot token, or a **Mattermost** server URL,
+  bot token and channel ID — see [bridge docs][docs-bridge] and
+  [configuration][docs-config].
 
 ### Installation
 

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/config/orchestrator.yaml.example

@@ -31,8 +31,22 @@ agent:
   default_timeout_seconds: 1800
   output_format: "json"
 
+# EXACTLY ONE transport is active, and it is the one named by `type`.
+# The other blocks below are inert: they may stay in the file, but nothing
+# reads them. Running Telegram and Mattermost at the same time is NOT
+# supported - that is tracked as issue #176.
+#
+# Choose:
+#   type: "telegram"    production, 1:1 chat with a bot
+#   type: "mattermost"  production, a channel on your own server
+#   type: "file_mock"   no chat at all; questions are written to files.
+#                       Blocked sessions still persist and can be resumed
+#                       later, but nobody is asked anything.
+#
+# Leaving a stale block for the transport you are NOT using is harmless,
+# but delete it if you want the file to say what is true.
 transport:
-  type: "file_mock"  # Use "telegram" for production
+  type: "file_mock"  # "telegram" or "mattermost" for production
   telegram:
     bot_token_env: "CTRLRELAY_TELEGRAM_TOKEN"
     chat_id: 123456789
@@ -44,6 +58,24 @@ transport:
     # to cover being asleep: a sweep runs its repos one at a time and
     # holds each repo's lock and worktree for the whole wait.
     ask_timeout_seconds: 900
+  mattermost:
+    url: "https://chat.example.com"
+    bot_token_env: "CTRLRELAY_MATTERMOST_TOKEN"
+    # The 26-character channel ID, not the channel name: a name is only
+    # unique within a team and can be renamed under you. Channel menu ->
+    # View Info, or GET /api/v4/teams/name/{team}/channels/name/{channel}.
+    #
+    # The bot must be a MEMBER of this channel. A bot without `post:all`
+    # cannot post where it is not a member - and, the part that is easy to
+    # miss, it does not receive that channel's reply events either, so
+    # answers would silently never arrive.
+    channel_id: "abcdefghijklmnopqrstuvwxyz"
+    socket_path: "~/.ctrlrelay/ctrlrelay.sock"
+    ask_timeout_seconds: 900
+    # How long an UNANSWERED question stays routable before it is retired.
+    # Read from whichever transport is active, so a Mattermost deployment
+    # takes this value and not the telegram block's.
+    question_ttl_seconds: 172800
   file_mock:
     inbox: "~/.ctrlrelay/inbox.txt"
     outbox: "~/.ctrlrelay/outbox.txt"

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/docs/bridge.md

@@ -1,19 +1,45 @@
 ---
-title: Telegram bridge
+title: Chat bridge
 layout: default
 nav_order: 4
-description: "Set up the Telegram bridge that delivers BLOCKED questions to a human and routes their answers back to a paused Claude session."
+description: "Set up the chat bridge — Telegram or Mattermost — that delivers BLOCKED questions to a human and routes their answers back to a paused Claude session."
 permalink: /bridge/
 ---
 
-# Telegram bridge
+# Chat bridge
 
 The bridge is a small daemon that:
 
-1. Listens on a Unix socket at `transport.telegram.socket_path`.
-2. Forwards messages from ctrlrelay to a Telegram chat over the Bot API.
-3. Long-polls Telegram for replies in that chat and delivers them back to the
-   socket client that asked.
+1. Listens on a Unix socket at the configured transport's `socket_path`.
+2. Forwards messages from ctrlrelay to a chat channel.
+3. Streams replies back from that channel and delivers them to the socket
+   client that asked.
+
+It speaks **Telegram** or **Mattermost**. Pipelines never know which: they
+talk to the socket, and the chat app is the bridge's business. Switching is a
+one-line config change and no pipeline code moves.
+
+**One at a time.** `transport.type` names the transport that is active, and the
+other block is inert — it may stay in the file, but nothing reads it, including
+its `question_ttl_seconds`. There is no fallback: a question goes to the one
+you named or nowhere. Running both at once is
+[issue #176](https://github.com/AInvirion/ctrlrelay/issues/176) and is not
+built.
+
+| | Telegram | Mattermost |
+|---|---|---|
+| Needs | a bot from BotFather, your chat id | a self-hosted server, a bot account, a channel id |
+| Outbound | Bot API `sendMessage` | `POST /api/v4/posts` |
+| Inbound | `getUpdates` long-poll | WebSocket `posted` events |
+| "answer this one" | the reply gesture | reply **in the question's thread** |
+| Tappable choices | reply keyboard | rendered as a numbered list you type |
+
+**The one operator-facing difference worth knowing.** When several questions
+are outstanding, the bridge can only route your answer if it knows which
+question you mean. On Telegram that is Telegram's reply; on Mattermost it is
+**replying inside the question's thread**. A loose message in the channel is
+only routable when exactly one question is waiting — otherwise the bridge
+refuses and tells you what is outstanding, rather than guessing.
 
 Pipelines use it as the human-in-the-loop channel: when Claude writes a
 `BLOCKED_NEEDS_INPUT` checkpoint, the dev pipeline calls `transport.ask(question)`,
@@ -108,6 +134,91 @@ Stop it:
 ctrlrelay bridge stop
 ```
 
+## Mattermost instead of Telegram
+
+Steps 1–2 above are Telegram-specific. For Mattermost, do this instead and
+then rejoin at step 4.
+
+### M1 — Enable bot accounts
+
+**System Console → Integrations → Bot Accounts → Enable Bot Account Creation
+= true.**
+
+On a self-hosted install this is off by default. Note that editing
+`config.json` on the server may not be enough — if the instance has no config
+watcher the value will not take effect until `systemctl restart mattermost`,
+and the live value is what matters. Read it back before believing it:
+
+```bash
+curl -s "https://<your-server>/api/v4/config/client?format=old" \
+  | jq .EnableBotAccountCreation
+```
+
+`EnableUserAccessTokens` is **not** required. That setting governs *user*
+personal access tokens; bot account tokens are managed separately. Leaving it
+off avoids letting every user mint long-lived full-access tokens.
+
+### M2 — Create the bot and its token
+
+1. **Integrations → Bot Accounts → Add Bot Account.**
+2. Username `ctrlrelay`, role **Member**. Leave `post:all` and `post:channels`
+   **off** — the bot will be added to one channel, and a token with no reach
+   beyond it is a smaller problem if it leaks.
+3. **Create New Token** and copy it immediately. Mattermost shows it once.
+
+### M3 — A channel, and put the bot in it
+
+Create a channel for orchestrator questions, then invite the bot:
+
+```
+/invite @ctrlrelay
+```
+
+**This is not optional, and the reason is easy to miss.** A bot without
+`post:all` cannot post where it is not a member — and it does not receive the
+reply events for such a channel either. Forget this and questions fail to post
+*and* answers would never arrive. `ctrlrelay bridge start` checks membership
+before it binds its socket and refuses to start until the bot is invited.
+
+The bot must also be on the team. If `/invite` complains, add it via the
+team's **Invite People** first.
+
+### M4 — Find the channel id
+
+The id, not the name: a name is only unique within a team and can be renamed
+under you, while the id is stable. From the channel's **View Info**, or:
+
+```bash
+curl -s -H "Authorization: Bearer $CTRLRELAY_MATTERMOST_TOKEN" \
+  "https://<your-server>/api/v4/teams/name/<team>/channels/name/<channel>" \
+  | jq -r .id
+```
+
+### M5 — Configure
+
+```bash
+export CTRLRELAY_MATTERMOST_TOKEN="your-bot-token"
+```
+
+```yaml
+transport:
+  type: "mattermost"
+  mattermost:
+    url: "https://chat.example.com"   # scheme required
+    bot_token_env: "CTRLRELAY_MATTERMOST_TOKEN"
+    channel_id: "emzhur1hwpyc38ehkfm5ppym8y"
+    socket_path: "~/.ctrlrelay/ctrlrelay.sock"
+    ask_timeout_seconds: 900
+```
+
+Then `ctrlrelay config validate`, and continue from step 4 above —
+`ctrlrelay bridge start` is the same command for either transport.
+
+**Editions.** Everything here works on free self-hosted Mattermost. The REST
+API, the WebSocket, bot accounts and bot tokens are core features, not
+licensed ones; the paid tiers cover SSO/SAML/LDAP, compliance export and high
+availability, none of which the bridge touches.
+
 ## 5 — Send a test message
 
 Once the bridge is running and reachable on its socket, send a one-off message
@@ -186,17 +297,23 @@ no running process", remove the orphan socket file (`rm
 ## Sequence: BLOCKED question round-trip
 
 ```
-   pipeline                bridge                Telegram          user
+   pipeline                bridge               chat app          user
       │                      │                      │               │
       │── ask("Which?") ────>│                      │               │
-      │                      │── sendMessage ──────>│               │
+      │                      │─ post question ─────>│               │
       │                      │                      │── push ──────>│
       │                      │                      │               │
       │                      │                      │<── reply ─────│
-      │                      │<── getUpdates ───────│               │
+      │                      │<─ reply + post id ───│               │
       │<── answer("the b") ──│                      │               │
 ```
 
+The bridge remembers the id of every question it posts, so the reply's
+"this is what I am answering" — Telegram's `reply_to_message_id`, Mattermost's
+thread `root_id` — names the session exactly. That is also how an answer
+arriving *after* the pipeline stopped waiting still drives a resume, via the
+`pending_resumes` table.
+
 The pipeline's `transport.ask()` call blocks (with the configured timeout) until
 the bridge returns the answer. The pipeline then resumes the Claude session via
 `claude --resume <session_id>` with a prompt of the form "User answered: …".

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/docs/configuration.md

@@ -91,26 +91,52 @@ intentional — the orchestrator runs unattended.
 ## transport
 
 The transport carries `BLOCKED_NEEDS_INPUT` questions out of ctrlrelay to a
-human and routes the answer back. Pick one of two types.
+human and routes the answer back.
+
+### Choosing one
+
+**Exactly one transport is active: the one named by `type`.** Every other
+block in the file is inert — it may stay there, but nothing reads it.
+
+| You want | Set `type` to | You need |
+|---|---|---|
+| A 1:1 chat with a bot | `"telegram"` | A bot token and your chat ID. |
+| A channel on your own server | `"mattermost"` | A server URL, a bot token, and the channel's 26-character ID. |
+| No chat at all | `"file_mock"` | Nothing. Questions go to a file; **nobody is asked anything.** |
+
+**Running Telegram and Mattermost at the same time is not supported.** Setting
+`type` to one does not fall back to the other, and a question is delivered to
+one place or not at all. That is tracked as
+[issue #176](https://github.com/AInvirion/ctrlrelay/issues/176).
+
+Switching is a two-line change — set `type`, add that transport's block — plus
+a restart of **both** daemons, which share `state.db`.
+
+Every per-transport setting below is read from the **active** transport. A
+Mattermost deployment takes `question_ttl_seconds` from the `mattermost` block,
+not from a leftover `telegram` one.
 
 ```yaml
 transport:
-  type: "telegram"   # or "file_mock"
-  telegram:
-    bot_token_env: "CTRLRELAY_TELEGRAM_TOKEN"
-    chat_id: 123456789
+  type: "mattermost"   # or "telegram", or "file_mock"
+  mattermost:
+    url: "https://chat.example.com"
+    bot_token_env: "CTRLRELAY_MATTERMOST_TOKEN"
+    channel_id: "abcdefghijklmnopqrstuvwxyz"
     socket_path: "~/.ctrlrelay/ctrlrelay.sock"
-  file_mock:
-    inbox:  "~/.ctrlrelay/inbox.txt"
-    outbox: "~/.ctrlrelay/outbox.txt"
 ```
 
 | Key | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `type` | enum | no | `"file_mock"` | One of `"telegram"`, `"file_mock"`. |
+| `type` | enum | no | `"file_mock"` | One of `"telegram"`, `"mattermost"`, `"file_mock"`. |
 | `telegram` | object | required when `type=telegram` | — | Telegram bridge settings — see below. |
+| `mattermost` | object | required when `type=mattermost` | — | Mattermost bridge settings — see below. |
 | `file_mock` | object | required when `type=file_mock` | — | Local-file fake transport, used for tests/dev. |
 
+The block for the selected type is **required**: a config naming a type whose
+block is absent is refused at load, loudly, rather than starting with no way to
+reach anybody.
+
 ### transport.telegram
 
 | Key | Type | Default | Description |
@@ -123,6 +149,27 @@ transport:
 
 See [Telegram bridge]({{ '/bridge/' | relative_url }}) for the full setup walkthrough.
 
+### transport.mattermost
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `url` | string | — | Base URL of your Mattermost server, e.g. `https://chat.example.com`. Required. |
+| `bot_token_env` | string | `"CTRLRELAY_MATTERMOST_TOKEN"` | Name of the environment variable holding the bot token. ctrlrelay never reads the token directly — only the variable name. |
+| `channel_id` | string | `""` | The channel's **26-character ID**, not its name: a name is only unique within a team and can be renamed under you. Find it in the channel menu under *View Info*, or via `GET /api/v4/teams/name/{team}/channels/name/{channel}`. |
+| `socket_path` | path | `"~/.ctrlrelay/ctrlrelay.sock"` | Unix socket path the bridge listens on. Pipelines connect to this socket as clients. |
+| `ask_timeout_seconds` | int | `900` | Same meaning as the Telegram key above: it bounds only the in-session wait, and a later reply still resolves through `pending_resumes`. |
+| `question_ttl_seconds` | int | `172800` (48h) | Same meaning as the Telegram key above. |
+
+**The bot must be a member of that channel.** A bot without `post:all` cannot
+post where it is not a member — and, the part that is easy to miss, it does not
+receive that channel's reply events either, so answers would silently never
+arrive.
+
+Outbound is `POST /api/v4/posts`; inbound is a WebSocket on
+`/api/v4/websocket` filtered to the one channel. A threaded reply's `root_id`
+equals the question's post ID, which is how an answer is matched to its
+question — the same role `reply_to_message_id` plays on Telegram.
+
 ### transport.file_mock
 
 | Key | Type | Required | Description |

{ctrlrelay-0.11.3 → ctrlrelay-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.11.3"
+version = "0.12.0"
 description = "Local-first orchestrator for headless coding agents across multiple GitHub repos"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -32,6 +32,13 @@ dependencies = [
     "rich>=13.0.0",
     "python-telegram-bot>=21.0",
     "apscheduler>=3.10.0",
+    # Mattermost transport: REST out, WebSocket in. Both are permissive
+    # licences (httpx BSD-3-Clause, websockets BSD-3-Clause) and actively
+    # maintained. A Mattermost-specific client library was considered and
+    # skipped: the surface used here is four endpoints and one event type,
+    # which is less code than keeping a wrapper current.
+    "httpx>=0.27.0",
+    "websockets>=12.0",
 ]
 
 [project.optional-dependencies]

ctrlrelay-0.12.0/src/ctrlrelay/bridge/__init__.py

@@ -0,0 +1,34 @@
+"""Bridge process: a Unix socket on one side, a chat app on the other."""
+
+from ctrlrelay.bridge.factory import (
+    HandlerConfigError,
+    make_handler,
+    token_env_var,
+)
+from ctrlrelay.bridge.handler import ChatHandler, IncomingMessageHandler
+from ctrlrelay.bridge.mattermost_handler import MattermostHandler
+from ctrlrelay.bridge.protocol import (
+    BridgeMessage,
+    BridgeOp,
+    ProtocolError,
+    parse_message,
+    serialize_message,
+)
+from ctrlrelay.bridge.server import BridgeServer
+from ctrlrelay.bridge.telegram_handler import TelegramHandler
+
+__all__ = [
+    "BridgeMessage",
+    "BridgeOp",
+    "BridgeServer",
+    "ChatHandler",
+    "HandlerConfigError",
+    "IncomingMessageHandler",
+    "MattermostHandler",
+    "ProtocolError",
+    "TelegramHandler",
+    "make_handler",
+    "parse_message",
+    "serialize_message",
+    "token_env_var",
+]

ctrlrelay-0.12.0/src/ctrlrelay/bridge/__main__.py

@@ -0,0 +1,120 @@
+"""Bridge process entry point for daemon mode.
+
+Takes a config path rather than per-transport flags. The alternative —
+growing a flag per chat app — means every new transport touches this file,
+the CLI that spawns it, and the two of them have to agree. Reading the same
+config the CLI read removes that agreement from the design.
+
+The token is never an argument. It is read from the environment variable
+the config names, which the parent process passes through, because argv is
+world-readable via ``ps`` and ``/proc/*/cmdline``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import signal
+import sys
+from pathlib import Path
+
+from ctrlrelay.bridge import BridgeServer, HandlerConfigError, make_handler
+from ctrlrelay.core.config import ConfigError, load_config, resolve_config_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="ctrlrelay chat bridge")
+    parser.add_argument(
+        "--config",
+        default=None,
+        help="Path to orchestrator.yaml (default: auto-discover).",
+    )
+    parser.add_argument(
+        "--socket-path",
+        default=None,
+        help="Unix socket path. Defaults to the configured transport's.",
+    )
+    parser.add_argument(
+        "--state-db",
+        default=None,
+        help=(
+            "Path to the orchestrator state.db. When provided, orphan "
+            "replies route to persisted BLOCKED sessions in "
+            "pending_resumes. Required for the resume-via-chat flow."
+        ),
+    )
+    args = parser.parse_args()
+
+    try:
+        config = load_config(resolve_config_path(args.config))
+    except ConfigError as e:
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        handler = make_handler(config.transport)
+    except HandlerConfigError as e:
+        # Exit 2, not 1: this is a configuration fault the operator must
+        # fix, not a transient failure worth a supervisor restart loop.
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    socket_path = (
+        Path(args.socket_path).expanduser()
+        if args.socket_path
+        else config.transport.socket_path
+    )
+    if socket_path is None:
+        print("error: no socket path in config or arguments", file=sys.stderr)
+        sys.exit(2)
+
+    state_db = None
+    if args.state_db:
+        from ctrlrelay.core.state import StateDB
+        state_db = StateDB(Path(args.state_db))
+
+    server = BridgeServer(
+        socket_path=Path(socket_path),
+        handler=handler,
+        state_db=state_db,
+    )
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    async def _run_server() -> None:
+        # Wrap start() in a finally that awaits stop() so the loop cannot
+        # close before the handler is closed and the socket unlinked.
+        try:
+            await server.start()
+        finally:
+            await server.stop()
+
+    main_task = loop.create_task(_run_server())
+
+    def handle_signal(sig: int) -> None:
+        main_task.cancel()
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(sig, handle_signal, sig)
+
+    try:
+        loop.run_until_complete(main_task)
+    except asyncio.CancelledError:
+        pass
+    except HandlerConfigError as e:
+        # The server's startup preflight: same class of fault as a bad
+        # token above, reported the same way and with the same exit code.
+        print(f"error: {e}", file=sys.stderr)
+        sys.exit(2)
+    finally:
+        loop.close()
+        if state_db is not None:
+            try:
+                state_db.close()
+            except Exception:
+                pass
+
+
+if __name__ == "__main__":
+    main()