brokerd: courier, carrying pending approvals to gatewayd and answers back

Implemented-By: OpenCode session (model recorded in docs/implementer-log.md)

docs/runbook.md

@@ -558,3 +558,37 @@ again would run it twice.
 Then send the message again in the thread.
 
 **Check.** A direct message to Boxmaker is answered.
+
+## 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.