From c57e8fde8422e4803dc972f50e2df06dc780e246 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Mon, 17 Aug 2026 09:03:23 +0300
Subject: [PATCH] Add a meowlnir-whoami diagnostic script to
 matrix-bot-meowlnir

Asks the homeserver who Meowlnir's appservice token belongs to.
A 401 (M_UNKNOWN_TOKEN) response means the homeserver is running
without Meowlnir's appservice registration, which is the usual cause
of Meowlnir's "Failed to connect to homeserver" log messages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/configuring-playbook-bot-meowlnir.md     |  4 +++
 .../tasks/setup_install.yml                   |  1 +
 .../templates/bin/meowlnir-whoami.j2          | 31 +++++++++++++++++++
 .../templates/bin/meowlnir-whoami.j2.license  |  3 ++
 4 files changed, 39 insertions(+)
 create mode 100755 roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2
 create mode 100644 roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2.license

diff --git a/docs/configuring-playbook-bot-meowlnir.md b/docs/configuring-playbook-bot-meowlnir.md
index c99dd52f3..1ea52b1ba 100644
--- a/docs/configuring-playbook-bot-meowlnir.md
+++ b/docs/configuring-playbook-bot-meowlnir.md
@@ -296,6 +296,10 @@ The playbook drives Meowlnir's management API for you based on `matrix_bot_meowl
 
 # Create another management room for an existing bot, with the given users able to command it there
 /matrix/meowlnir/bin/meowlnir-create-management-room meowlnir_bot @alice:example.com
+
+# Ask the homeserver who Meowlnir's appservice token belongs to.
+# A 401 response means the homeserver is running without Meowlnir's appservice registration, which is also what Meowlnir's own "Failed to connect to homeserver" log messages usually mean.
+/matrix/meowlnir/bin/meowlnir-whoami
 ```
 
 `meowlnir-create-management-room` prints the new room's ID, which you then register with `meowlnir-api PUT /_meowlnir/v1/management_room/<room ID>`.
diff --git a/roles/custom/matrix-bot-meowlnir/tasks/setup_install.yml b/roles/custom/matrix-bot-meowlnir/tasks/setup_install.yml
index 6b5d8d13a..5fd071b5c 100644
--- a/roles/custom/matrix-bot-meowlnir/tasks/setup_install.yml
+++ b/roles/custom/matrix-bot-meowlnir/tasks/setup_install.yml
@@ -89,6 +89,7 @@
     - meowlnir-api
     - meowlnir-bots
     - meowlnir-create-management-room
+    - meowlnir-whoami
 
 - name: Ensure matrix-bot-meowlnir container network is created
   when: matrix_bot_meowlnir_container_network != 'host'
diff --git a/roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2 b/roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2
new file mode 100755
index 000000000..c0ac9d19e
--- /dev/null
+++ b/roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2
@@ -0,0 +1,31 @@
+#!/bin/sh
+# Asks the homeserver who Meowlnir's appservice token belongs to.
+#
+# A `200` response proves the homeserver has Meowlnir's appservice registration loaded.
+# A `401` (`M_UNKNOWN_TOKEN`) response means it is running without it — the condition that otherwise surfaces as Meowlnir endlessly logging "Failed to connect to homeserver".
+#
+# Usage: meowlnir-whoami
+#
+# Prints the response body, followed by the HTTP status code on its own final line.
+
+set -eu
+
+CONFIG_FILE='{{ matrix_bot_meowlnir_config_path }}/config.yaml'
+CONTAINER_NAME='matrix-bot-meowlnir'
+HOMESERVER_ADDRESS='{{ matrix_bot_meowlnir_config_homeserver_address }}'
+REQUEST_TIMEOUT='{{ matrix_bot_meowlnir_api_request_timeout_seconds }}'
+
+# The configuration file is generated by Ansible, so its layout is predictable.
+as_token="$(awk '$1 == "as_token:" { print $2; exit }' "$CONFIG_FILE" | sed 's/^"//; s/"$//')"
+
+if [ -z "$as_token" ]; then
+	echo "Could not read as_token from $CONFIG_FILE" >&2
+	exit 1
+fi
+
+# Runs curl inside the container, because the homeserver is only reachable over the container network.
+exec {{ devture_systemd_docker_base_host_command_docker }} exec "$CONTAINER_NAME" \
+	curl -sS --max-time "$REQUEST_TIMEOUT" \
+	-H "Authorization: Bearer $as_token" \
+	-w '\n%{http_code}' \
+	"$HOMESERVER_ADDRESS/_matrix/client/v3/account/whoami"
diff --git a/roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2.license b/roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2.license
new file mode 100644
index 000000000..dbb307901
--- /dev/null
+++ b/roles/custom/matrix-bot-meowlnir/templates/bin/meowlnir-whoami.j2.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later