feat(api,mcp): explain account_id mixed up with a telegram user id

backend/src/utils/read/accounts.py

@@ -45,6 +45,35 @@ async def self_user_id(pool: asyncpg.Pool, account_id: int) -> int | None:
     return tg_user_id
 
 
+_known_ids: set[int] = set()
+
+
+def _account_label(row: asyncpg.Record) -> str:
+    named = f", {row['label']}" if row["label"] else ""
+    return f"account_id={row['account_id']} (Telegram id {row['tg_user_id']}{named})"
+
+
+async def unknown_account_hint(pool: asyncpg.Pool, account_id: int) -> str | None:
+    """Explain an account_id that matches no account, or None if it is valid."""
+    if account_id in _known_ids:
+        return None
+    rows = await pool.fetch(
+        "SELECT account_id, tg_user_id, label FROM accounts ORDER BY account_id"
+    )
+    _known_ids.update(row["account_id"] for row in rows)
+    if account_id in _known_ids:
+        return None
+    known = "; ".join(_account_label(row) for row in rows) or "none"
+    mistaken = next((row for row in rows if row["tg_user_id"] == account_id), None)
+    if mistaken is not None:
+        return (
+            f"{account_id} is a Telegram user id, not an account_id. In beavergram "
+            f"that account is account_id={mistaken['account_id']}. "
+            f"Retry with account_id={mistaken['account_id']}."
+        )
+    return f"No account with account_id={account_id}. Archived accounts: {known}."
+
+
 async def list_accounts(pool: asyncpg.Pool) -> list[AccountView]:
     rows = await pool.fetch(
         f"SELECT {_ACCOUNT_COLS} FROM accounts ORDER BY account_id"  # noqa: S608