@@ -44,6 +44,9 @@ read before it goes live, and a `git revert` if it was wrong.
   shows the meter's day and night readings, and one button sends them through
   YASNO's Telegram bot
   ([`docs/electricity-reading-submission.md`](docs/electricity-reading-submission.md)).
+  Every Monday `packages/meterbots_session.yaml` asks MeterBots whether its
+  Telegram session is still logged in, and notifies if not, so a dead session
+  is found before the month-end ask.
 - **Two air conditioners**: an infrared one through [`../IRBridge`](../IRBridge)
   and a networked one ([`docs/climate-dashboard.md`](docs/climate-dashboard.md)).
 - **Google Home and Gemini**: entities exposed through the Google Assistant
 
@@ -0,0 +1,70 @@
+# ---------------------------------------------------------------------------
+# Is MeterBots' Telegram session still logged in? Asked every Monday at 12:00.
+#
+# Both monthly readings (gas_submit.yaml, electricity_submit.yaml) go out
+# through one logged-in Telegram user in MeterBots (LXC 105). That session
+# can end without anyone noticing: terminated in Telegram -> Settings ->
+# Devices, revoked by Telegram, or ended by Telegram's own "terminate
+# inactive sessions" for a session that is used about once a month. Its file
+# stays behind, so MeterBots' /health keeps saying "session: true".
+#
+# Without this, the first sign is the monthly ask on the 1st, with three or
+# four days of the window left to log in again with a phone code. Asked
+# weekly, it is found days or weeks earlier. The check is also an authorised
+# request, which counts as the session being used.
+#
+#   rest_command.meterbots_session   MeterBots' GET /session (the gas token
+#                                    opens it); one round trip to Telegram,
+#                                    nothing sent to any bot
+#
+# secrets.yaml:  meterbots_session_url   http://<meterbots-ip>:8770/session
+#                gasbot_token            MeterBots' GASBOT_TOKEN (shared with
+#                                        gas_submit.yaml)
+#
+# Logging in again: MeterBots/docs/deployment.md.
+# ---------------------------------------------------------------------------
+
+rest_command:
+  meterbots_session:
+    url: !secret meterbots_session_url
+    method: GET
+    headers:
+      X-Gasbot-Token: !secret gasbot_token
+    # It waits out a running bot walk (one conversation at a time).
+    timeout: 300
+
+automation:
+  - id: meterbots_session_check
+    alias: 'MeterBots: is the Telegram session still logged in'
+    mode: single
+    trigger:
+      - platform: time
+        at: "12:00:00"
+    condition:
+      - condition: time
+        weekday: mon
+    action:
+      - service: rest_command.meterbots_session
+        response_variable: sess
+        continue_on_error: true
+      - variables:
+          ok: >-
+            {{ sess is defined and sess.status == 200 and sess.content is mapping
+               and (sess.content.ok | default(false)) }}
+          why: >-
+            {% if ok %}{% elif sess is not defined %}MeterBots did not answer, or refused (see the HA log)
+            {%- elif sess.content is mapping and sess.content.error is defined %}{{ sess.content.error }}
+            {%- else %}MeterBots answered {{ sess.status }}{% endif %}
+      - if:
+          - condition: template
+            value_template: "{{ not ok }}"
+        then:
+          - service: notify.household
+            data:
+              title: '🤖 MeterBots cannot reach Telegram'
+              message: >-
+                {{ why }}. The monthly gas and electricity readings go out
+                through this session, so log MeterBots in again before the
+                1st (MeterBots/docs/deployment.md).
+              data:
+                channel: MeterBots
@@ -41,6 +41,9 @@ gasbot_submit_url: "http://<meterbots-ip>:8770/gas/bot/submit"
 yasnobot_token: "<same value as YASNOBOT_TOKEN>"
 yasnobot_status_url: "http://<meterbots-ip>:8770/yasno/bot/status"
 yasnobot_submit_url: "http://<meterbots-ip>:8770/yasno/bot/submit"
+# The weekly "still logged in?" check (packages/meterbots_session.yaml);
+# opened with gasbot_token.
+meterbots_session_url: "http://<meterbots-ip>:8770/session"
 # Optional: where gas_submit.py fetches the photo, and the token MeterCam
 # asks for (its METERCAM_TOKEN).
 metercam_url: "http://<metercam-ip>:8770"
 
@@ -14,6 +14,7 @@
   * the two kitchen helpers cannot both drive the relay
   * the IR phone charges below 21% on every path, and is re-checked
   * irbridge_send_candidate honours idx 0
+  * the weekly MeterBots session check says why whenever it fails
 
 Same approach as check_dtek_templates.py: just enough of HA's template
 environment to render these templates, not an HA emulator.
@@ -185,5 +186,31 @@ def walk(node):
 check("no idx -> the input_number", render(tpl, states=held), "47")
 check("empty idx -> the input_number", render(tpl, states=held, idx=""), "47")
 
+# --- MeterBots session -------------------------------------------------------
+print("\n8. MeterBots session: weekly, and every failure says why")
+pkg = yaml.load((CONFIG / "packages" / "meterbots_session.yaml").read_text(encoding="utf-8"),
+                HaLoader)
+auto = pkg["automation"][0]
+check("Mondays at 12:00",
+      (auto["trigger"][0]["at"], auto["condition"][0]["weekday"]), ("12:00:00", "mon"))
+call, var_step, notify_step = auto["action"]
+check("a MeterBots that is down does not stop the run", call.get("continue_on_error"), True)
+ok_tpl, why_tpl = var_step["variables"]["ok"], var_step["variables"]["why"]
+cases = [
+    ("logged in", {"status": 200, "content": {"ok": True, "authorized": True}}, "True", ""),
+    ("logged out", {"status": 200, "content": {"ok": False,
+                                               "error": "Telegram session is not logged in"}},
+     "False", "Telegram session is not logged in"),
+    ("wrong token", {"status": 401, "content": {"error": "unauthorised"}}, "False", "unauthorised"),
+    ("not JSON", {"status": 502, "content": "Bad Gateway"}, "False", "MeterBots answered 502"),
+]
+for label, sess, want_ok, want_why in cases:
+    check("%s -> ok %s" % (label, want_ok), render(ok_tpl, sess=sess), want_ok)
+    check("%s -> why" % label, render(why_tpl, sess=sess, ok=want_ok == "True"), want_why)
+check("no answer at all -> not ok", render(ok_tpl), "False")
+check("no answer at all -> why",
+      render(why_tpl, ok=False), "MeterBots did not answer, or refused (see the HA log)")
+check("only a failure notifies", notify_step["if"][0]["value_template"], "{{ not ok }}")
+
 print("\n%s" % ("FAILED: " + ", ".join(FAILED) if FAILED else "all checks passed"))
 sys.exit(1 if FAILED else 0)
@@ -6,6 +6,7 @@ MeterBots listens on `:8770` in LXC 105. Home Assistant calls it with
 | Endpoint | Who calls it | What |
 | --- | --- | --- |
 | `GET /health` | Docker's healthcheck, `deploy.sh`, a human | `{status, version, bots: {gas, yasno}, session}`. `bots` says which bots have a token; `session` says whether a session file exists, not whether it is still logged in. No secrets |
+| `GET /session` | Home Assistant (`meterbots_session.yaml`), every Monday | `{ok: true, authorized: true}` while the Telegram session is logged in, else `{ok: false, error}`. One round trip to Telegram, nothing sent to any bot. Either bot's token opens it. Waits out a running walk |
 | `GET /gas/bot/status` | Home Assistant (`gas_submit.yaml`) | Dry run of `@mygrmu_bot`: walks to the reading prompt and back, answers `{ok, previous, previous_date, transcript}`. Sends no reading |
 | `POST /gas/bot/submit` | Home Assistant, on a button press | `{"value": 2262}` (> 0, < 100000, at most 2 decimals) sends the monthly gas reading; `{ok, value, reply, transcript}` or `{ok: false, error, transcript}` |
 | `GET /yasno/bot/status` | Home Assistant (`electricity_submit.yaml`) | Dry run of `@Yasnoonlinebot`: walks to the reading prompt and back, answers `{ok, previous: {day, night, date}, transcript}`. Sends no reading |
@@ -21,7 +22,7 @@ Each bot has its own token, sent as its own header:
 | `/yasno/bot/*` | `X-Yasnobot-Token` | `YASNOBOT_TOKEN` | `yasnobot_token` |
 
 A wrong or missing token gets `401`, and one bot's token never opens another's
-routes. **With the token unset, the route refuses
+routes. `/session` is the exception: it walks no bot, so either token opens it. **With the token unset, the route refuses
 everyone**, an empty header included: filing a reading as the household is not
 something a stray script on the LAN may do. `/health` needs no token and
 carries none.
 
@@ -78,3 +78,20 @@ Whoever has `telegram.session` can read and send as the household. So:
 - It shows up in Telegram → Settings → Devices under the API app's name.
   Ending it there logs MeterBots out, and every call answers
   `Telegram session is not logged in` until someone logs in again.
+
+## Keeping it logged in
+
+The session is used about once a month, and Telegram ends sessions that sit
+unused. Two things keep that from surfacing at the monthly ask:
+
+- **Telegram's own timer.** In the household account, Telegram → Settings →
+  Privacy and Security → Devices → *Automatically terminate old sessions*: set
+  it to the longest period (1 year). With 1 month, a quiet session can be
+  ended between two monthly readings.
+- **The weekly check.** Every Monday at 12:00 Home Assistant calls `GET
+  /session` (`HomeAssistant/config/packages/meterbots_session.yaml`). It asks
+  Telegram whether the session is still authorised, which is also a use of the
+  session, and notifies the household if it is not, or if MeterBots does not
+  answer. `/health` cannot tell: a session ended in Telegram leaves its file.
+
+To check by hand: `curl -H "X-Gasbot-Token: <token>" http://<meterbots-ip>:8770/session`.
@@ -6,7 +6,8 @@
 a stray script on the LAN may do.
 
     GET  /health              alive, which bots are configured, the session
-    GET  /gas/bot/status      dry run of @mygrmu_bot, sends nothing
+    GET  /session             is the Telegram session still logged in
+    GET  /gas/bot/status     dry run of @mygrmu_bot, sends nothing
     POST /gas/bot/submit      {"value": 2262}
     GET  /yasno/bot/status    dry run of @Yasnoonlinebot, sends nothing
     POST /yasno/bot/submit    {"day": 38500, "night": 6450}
@@ -19,7 +20,7 @@
 
 from . import gasbot, tgclient, yasnobot
 
-VERSION = "1.1.0"
+VERSION = "1.2.0"
 
 APP = Flask(__name__)
 
@@ -47,6 +48,17 @@ def health():
                     "session": tgclient.session_present()})
 
 
+@APP.route("/session")
+def session():
+    """Whether the Telegram session is still logged in: one round trip to
+    Telegram, nothing sent to any bot. Either bot's token opens it. Home
+    Assistant asks weekly, so a logged-out session is found weeks before the
+    monthly ask instead of at it."""
+    if not (gasbot_authorised() or yasnobot_authorised()):
+        return deny()
+    return jsonify(tgclient.session_check())
+
+
 @APP.route("/gas/bot/status")
 def gas_bot_status():
     """Walk @mygrmu_bot to the value prompt and back; send nothing."""
 
@@ -209,6 +209,30 @@ async def conversation(api, bot_name, watch_edits=False):
         await client.disconnect()
 
 
+async def _session_check():
+    from telethon import TelegramClient
+
+    api = api_settings()
+    client = TelegramClient(str(SESSION), api["api_id"], api["api_hash"])
+    await client.connect()
+    try:
+        if not await client.is_user_authorized():
+            raise BotError("Telegram session is not logged in -- run the login steps")
+        return {"ok": True, "authorized": True}
+    finally:
+        await client.disconnect()
+
+
+def session_check():
+    """Is the session still logged in? A real round trip to Telegram, unlike
+    session_present(): a session ended in Telegram -> Settings -> Devices, or
+    by Telegram's own "terminate inactive sessions", still leaves its file.
+    Takes the lock like any conversation, so it waits out a running walk."""
+    if not session_present():
+        return {"ok": False, "error": "no session file -- run the login steps"}
+    return blocking(_session_check)
+
+
 def blocking(coro_fn, *args):
     """Run one conversation from a Flask route: locked, always JSON back."""
     with LOCK:
 
@@ -44,6 +44,8 @@ def run(*args):
         return run
     gasbot.run = stub("gas")
     yasnobot.run = stub("yasno")
+    appmod.tgclient.session_check = lambda: calls.append(("session",)) or {"ok": True,
+                                                                         "authorized": True}
     return appmod.create_app().test_client(), calls
 
 
@@ -52,7 +54,7 @@ def run(*args):
 r = client.get("/health")
 body = r.get_json()
 check("200 and ok", r.status_code == 200 and body["status"] == "ok")
-check("carries the version", body.get("version") == "1.1.0", body)
+check("carries the version", body.get("version") == "1.2.0", body)
 check("says which bots are configured", body.get("bots") == {"gas": True, "yasno": False}, body)
 check("no secret in it", TOKEN not in r.get_data(as_text=True))
 
@@ -111,6 +113,24 @@ def run(*args):
       client.post("/yasno/bot/submit", json={"day": 1, "night": 1},
                   headers={"X-Yasnobot-Token": ""}).status_code == 401 and calls == [])
 
+print("session")
+client, calls = load(TOKEN, "yasno-token")
+check("no token -> 401", client.get("/session").status_code == 401 and calls == [])
+check("wrong token -> 401",
+      client.get("/session", headers={"X-Gasbot-Token": "nope"}).status_code == 401)
+r = client.get("/session", headers={"X-Gasbot-Token": TOKEN})
+check("the gas token opens it, and it asks Telegram",
+      r.status_code == 200 and r.get_json() == {"ok": True, "authorized": True}
+      and calls == [("session",)], (r.get_json(), calls))
+calls.clear()
+r = client.get("/session", headers={"X-Yasnobot-Token": "yasno-token"})
+check("so does the YASNO token", r.status_code == 200 and calls == [("session",)])
+check("and no bot is ever walked", all(c == ("session",) for c in calls))
+client, calls = load(None, None)
+check("both tokens unset: refused even with empty headers",
+      client.get("/session", headers={"X-Gasbot-Token": "", "X-Yasnobot-Token": ""})
+      .status_code == 401 and calls == [])
+
 print("yasno submit: what reaches the bot")
 client, calls = load(TOKEN, "yasno-token")
 for body, want in [({"day": 38500, "night": 6450}, ("yasno", 38500, 6450)),
 
@@ -215,4 +215,49 @@ async def slow(name):
 check("two bots never talk at once: one conversation ends before the next starts",
       order == ["gas in", "gas out", "yasno in", "yasno out"], order)
 
+print("session_check")
+import tempfile
+import types
+
+events = []
+
+
+class FakeTelegramClient:
+    authorized = True
+
+    def __init__(self, session, api_id, api_hash):
+        events.append(("new", api_id))
+
+    async def connect(self):
+        events.append("connect")
+
+    async def is_user_authorized(self):
+        return FakeTelegramClient.authorized
+
+    async def disconnect(self):
+        events.append("disconnect")
+
+
+sys.modules["telethon"] = types.SimpleNamespace(TelegramClient=FakeTelegramClient)
+os.environ["TELEGRAM_API_ID"], os.environ["TELEGRAM_API_HASH"] = "12345", "hash"
+tmp = pathlib.Path(tempfile.mkdtemp())
+tgclient.SESSION = tmp / "telegram"
+check("no session file: says so, Telegram not asked",
+      tgclient.session_check() == {"ok": False, "error": "no session file -- run the login steps"}
+      and events == [])
+(tmp / "telegram.session").write_bytes(b"x")
+check("logged in: authorized", tgclient.session_check() == {"ok": True, "authorized": True})
+check("connected once and disconnected", events == [("new", 12345), "connect", "disconnect"],
+      events)
+FakeTelegramClient.authorized = False
+events.clear()
+r = tgclient.session_check()
+check("logged out: a failure that says to log in",
+      not r["ok"] and "not logged in" in r["error"], r)
+check("and it still disconnects", events[-1] == "disconnect", events)
+os.environ.pop("TELEGRAM_API_ID")
+r = tgclient.session_check()
+check("no API credentials: a failure, not an exception",
+      not r["ok"] and "TELEGRAM_API_ID" in r["error"], r)
+
 print("%d checks passed" % checks)