Plan M4b: approvals over Mattermost in 15 tasks

Skeletons for new files only; existing files change by exact edits, so no task overwrites an
earlier one's work. Each task's tests were run against a reference built in order from master,
with the gate at each step and mutations checked; each skeleton compiles and fails its tests, and
every todo!() comment was read beside its signature. The reference is kept off this machine.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

docs/plans/M4b/files/runbook-gateway-unreachable.md

@@ -0,0 +1,34 @@
+
+## gateway-unreachable
+
+**What you see.** `brokerd` prints `brokerd: approval <id>: gatewayd is not reachable at <socket>:
+<reason>; bxctl can still answer it`, then this entry, once per approval. No approval post
+appears in Mattermost. `bxctl approvals` lists the approval as usual.
+
+**Why.** `brokerd.toml` has a `[gateway]` section, so each pending approval is carried to
+`gatewayd` to be posted in Mattermost. The courier could not connect to `gateway.sock`, or
+`gatewayd` answered that it could not post (Mattermost unreachable). The approval is not lost: it
+stays pending, `bxctl` can answer it, and the courier tries again every 5 seconds until it is
+posted or answered. When a later try works, `brokerd` prints `brokerd: approval <id> posted in
+Mattermost`.
+
+**Confirm.**
+
+```sh
+ls -l <socket>                        # gatewayd creates it at start; [approvals] socket in gatewayd.toml
+pgrep -x gatewayd                     # is it running?
+```
+
+and `gatewayd`'s own output: `cannot reach …` there means Mattermost is the problem (see
+[mattermost-unreachable](#mattermost-unreachable)).
+
+**Fix.** Start `gatewayd`, or make `[gateway] socket` in `brokerd.toml` and `[approvals] socket`
+in `gatewayd.toml` name the same path (both default to `<home>/run/gateway/gateway.sock`). To turn
+Mattermost approvals off, remove `[gateway]` from `brokerd.toml` and restart `brokerd`.
+
+**Check.** Trigger an `ask` call: its approval is posted in Mattermost, and `!approve <id>` in
+its thread answers it.
+
+Where two Boxmakers share a channel thread, address approval commands to one of them
+(`@<bot> !approve <id>`): a bare `!approve <id>` is taken by every Boxmaker with that id pending
+in that thread.