From b01667d9a77dbf90dc25bb4e7bf5575fe7300b0a Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Thu, 10 Sep 2026 23:37:12 +0300
Subject: [PATCH 01/10] feat(telegram): register bot command menu with
 setMyCommands

The bot never registered its commands, so Telegram's in-app "/" menu button
had nothing to show and the commands were only discoverable by reading
/mp_help. Register the list with setMyCommands so commands are tappable.

Lists are scoped to mirror the role model in _process_cmd rather than
exposing the whole admin surface to every user:

  - default scope   -> 5 public self-service commands
  - admin/superadmin chats via admins.conf -> 18 command control plane
  - root chat and superadmin admins -> those 18 plus the four commands
    gated on the superadmin role (/mp_remove, /mp_restart, /mp_update,
    /mp_lockdown)

The command tables live once, in the manager. The generated bot daemon
re-runs `mtproxymax telegram sync-commands` on boot instead of carrying its
own copy, so the menu self-heals and picks up newly added admins. Syncing is
best-effort throughout: a Telegram outage must never break setup or the poll
loop, and revoking an admin calls deleteMyCommands so a stale admin menu is
not left behind.

Also add an explicit `telegram sync-commands` subcommand for manual re-sync.
---
 README.md                       |  12 ++
 mtproxymax.sh                   | 144 +++++++++++++++++++++
 tests/test_telegram_commands.sh | 221 ++++++++++++++++++++++++++++++++
 3 files changed, 377 insertions(+)
 create mode 100644 tests/test_telegram_commands.sh

diff --git a/README.md b/README.md
index d47154a..a73b1d4 100644
--- a/README.md
+++ b/README.md
@@ -421,6 +421,17 @@ Full proxy management from your phone. Setup takes 60 seconds:
 mtproxymax telegram setup
 ```
 
+The bot registers its commands with Telegram, so tapping the **`/` menu button** in
+the chat lists everything you are allowed to run — no need to memorise them. The
+menu is scoped to your role: everyone sees the public self-service commands, admins
+see the Admin Control Plane, and superadmins additionally see `/mp_remove`,
+`/mp_restart`, `/mp_update` and `/mp_lockdown`. The list is re-synced whenever the
+bot service starts; to refresh it by hand use:
+
+```bash
+mtproxymax telegram sync-commands
+```
+
 | Command | Description |
 |---------|-------------|
 | `/mp_status` | Proxy status, uptime, connections |
@@ -1503,6 +1514,7 @@ mtproxymax update                       # Check for script + engine updates
 - **Automated SSL Shield (`ssl-shield`):** Zero-touch Let's Encrypt / `openssl` certificate issuance and ACME domain management.
 - **Automated Cloud Backups (`backup-cloud`):** Automatic tarball offloading to Telegram admin chat (`sendDocument`) or multi-cloud storage (`rclone`/S3/R2).
 - **Dual-Tier Telegram Bot (`telegram`):** Public self-service tier (`/start`, `/my_status <label>`, `/voucher`) combined with an authenticated Admin Control Plane (`/mp_fleet`, `/mp_secrets`, `/mp_lockdown`).
+- **Telegram Command Menu:** The bot registers its commands via `setMyCommands`, so the in-app `/` menu button lists every command you can run. Scopes mirror the role model — public commands for everyone, the Admin Control Plane for admins, and the superadmin-only commands (`/mp_remove`, `/mp_restart`, `/mp_update`, `/mp_lockdown`) only for superadmins. Re-synced on every bot service start and on `mtproxymax telegram sync-commands`.
 - **Comprehensive Hardening & Audit:** Fixed race conditions (`flock`), prevented configuration code injection (`grep | cut`), added comma/pipe CSV import normalization (`secret_import`), and ensured strict-mode container fallbacks across 18,369 lines (`100% clean`).
 
 ### v1.3.1 — Performance & Anti-DPI Upgrade Suite
diff --git a/mtproxymax.sh b/mtproxymax.sh
index b0ac44b..bf9f4f9 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -10327,6 +10327,8 @@ admin_add() {
         echo "${tg_id}|${role}|${label}|$(date -u '+%Y-%m-%d')" >> "$ADMINS_FILE"
     fi
     log_success "Admin ${tg_id} registered as '${role}' (${label})"
+    # Keep the new admin's Telegram command menu in step with their role.
+    telegram_sync_commands &>/dev/null || true
 }
 
 admin_remove() {
@@ -10335,6 +10337,8 @@ admin_remove() {
     load_admins
     grep -v "^${tg_id}|" "$ADMINS_FILE" > "${ADMINS_FILE}.tmp" 2>/dev/null && mv "${ADMINS_FILE}.tmp" "$ADMINS_FILE"
     log_success "Admin ${tg_id} removed"
+    # Drop the revoked admin's menu so it stops offering admin commands.
+    telegram_clear_commands "$tg_id" &>/dev/null || true
 }
 
 admin_list() {
@@ -11017,6 +11021,136 @@ telegram_send_message() {
     return 1
 }
 
+# ── Telegram command menu (setMyCommands) ────────────────────────────────────
+# Without this the client-side "/" menu button has nothing to show and the bot's
+# commands are only discoverable by reading /mp_help. The lists below are the
+# single source of truth: the bot daemon re-runs `mtproxymax telegram
+# sync-commands` on boot rather than duplicating them into its own heredoc.
+# Format is one "command|description" per line, without the leading slash.
+TG_CMDS_PUBLIC="start|Self-service onboarding and help
+my_status|Check your data quota and expiry (usage: /my_status <label>)
+redeem|Redeem a voucher code (usage: /redeem <code> [label])
+voucher|Alias for /redeem
+support|Send a support request to the server admins"
+
+TG_CMDS_ADMIN="mp_help|Show all commands
+mp_status|Proxy status, uptime and traffic
+mp_secrets|List all secrets with per-user stats
+mp_link|Get proxy links and QR codes
+mp_add|Add a new secret (usage: /mp_add <label>)
+mp_rotate|Rotate a secret key (usage: /mp_rotate <label>)
+mp_enable|Enable a secret (usage: /mp_enable <label>)
+mp_disable|Disable a secret (usage: /mp_disable <label>)
+mp_limits|Show per-user limits
+mp_setlimit|Set user limits (connections, IPs, quota, expiry)
+mp_traffic|Detailed per-user traffic breakdown
+mp_upstreams|List upstream routes
+mp_health|Run health diagnostics
+mp_digest|System health and security digest
+mp_broadcast|Broadcast a message to all known bot users
+mp_fleet|Global federation fleet dashboard
+mp_voucher|Generate or list vouchers
+reply|Reply to a support ticket (usage: /reply <chat_id> <message>)"
+
+# Superadmins additionally get the four commands _process_cmd gates on role.
+TG_CMDS_SUPERADMIN="${TG_CMDS_ADMIN}
+mp_remove|Remove or revoke a secret (usage: /mp_remove <label>)
+mp_restart|Restart the proxy
+mp_update|Check for and apply updates
+mp_lockdown|Emergency lockdown toggle (usage: /mp_lockdown on/off)"
+
+# Render a "command|description" table as the JSON array the Bot API expects.
+_tg_commands_json() {
+    local table="$1" name desc json="" first=1 line
+    while IFS= read -r line || [ -n "$line" ]; do
+        [ -z "$line" ] && continue
+        name="${line%%|*}"
+        desc="${line#*|}"
+        # Entries are static, but sanitise defensively: Telegram rejects the
+        # entire list if any single entry is malformed, so a stray control
+        # character or quote in a future description must not break the menu.
+        desc=$(printf '%s' "$desc" | tr '\t' ' ' | tr -d '[:cntrl:]')
+        desc="${desc//\\/\\\\}"
+        desc="${desc//\"/\\\"}"
+        [ "$first" -eq 1 ] || json="${json},"
+        first=0
+        json="${json}{\"command\":\"${name}\",\"description\":\"${desc}\"}"
+    done <<< "$table"
+    printf '[%s]' "$json"
+}
+
+# POST to a Bot API method, keeping the token out of the process list. Returns 0
+# only when Telegram acknowledges the call.
+_tg_api_post() {
+    local method="$1" body="$2"
+    local token="${TELEGRAM_BOT_TOKEN:-}"
+    [ -n "$token" ] || return 0
+    local _cfg
+    _cfg=$(_mktemp) || return 0
+    printf 'url = "https://api.telegram.org/bot%s/%s"\n' "$token" "$method" > "$_cfg"
+    local response
+    response=$(curl -s --max-time 10 -K "$_cfg" \
+        -H 'Content-Type: application/json' \
+        -d "$body" 2>/dev/null) || true
+    rm -f "$_cfg"
+    echo "$response" | grep -q '"ok":true'
+}
+
+# Register a command list for one scope. An empty scope means the default scope,
+# which applies to every user who has no more specific scope.
+_tg_set_commands() {
+    local scope="$1" commands="$2"
+    local body
+    if [ -n "$scope" ]; then
+        body="{\"commands\":${commands},\"scope\":${scope}}"
+    else
+        body="{\"commands\":${commands}}"
+    fi
+    _tg_api_post setMyCommands "$body"
+}
+
+# Push the whole menu: public commands for everyone, the admin control plane for
+# admins, and the privileged commands for superadmins. Entirely best-effort — a
+# network failure must never abort setup or the bot daemon.
+telegram_sync_commands() {
+    local cid role _rest
+    [ "${TELEGRAM_ENABLED:-false}" = "true" ] || return 0
+    [ -n "${TELEGRAM_BOT_TOKEN:-}" ] || return 0
+
+    local pub admin super
+    pub=$(_tg_commands_json "$TG_CMDS_PUBLIC")
+    admin=$(_tg_commands_json "$TG_CMDS_ADMIN")
+    super=$(_tg_commands_json "$TG_CMDS_SUPERADMIN")
+
+    _tg_set_commands "" "$pub" || log_warn "Could not register the public command menu"
+
+    if [ -n "${TELEGRAM_CHAT_ID:-}" ]; then
+        _tg_set_commands "{\"type\":\"chat\",\"chat_id\":${TELEGRAM_CHAT_ID}}" "$super" || true
+    fi
+
+    # RBAC admins, mirroring the role gates in _process_cmd.
+    if [ -f "${ADMINS_FILE:-}" ]; then
+        while IFS='|' read -r cid role _rest || [ -n "$cid" ]; do
+            [[ "$cid" =~ ^-?[0-9]+$ ]] || continue
+            [ "$cid" = "${TELEGRAM_CHAT_ID:-}" ] && continue
+            if [ "$role" = "superadmin" ]; then
+                _tg_set_commands "{\"type\":\"chat\",\"chat_id\":${cid}}" "$super" || true
+            else
+                _tg_set_commands "{\"type\":\"chat\",\"chat_id\":${cid}}" "$admin" || true
+            fi
+        done < "${ADMINS_FILE}"
+    fi
+    return 0
+}
+
+# Drop a chat's custom menu so a revoked admin stops seeing the admin commands.
+telegram_clear_commands() {
+    local cid="${1:-}"
+    [[ "$cid" =~ ^-?[0-9]+$ ]] || return 0
+    _tg_api_post deleteMyCommands "{\"scope\":{\"type\":\"chat\",\"chat_id\":${cid}}}" || true
+    return 0
+}
+
 telegram_send_photo() {
     local photo_url="$1" caption="${2:-}"
     local token="${TELEGRAM_BOT_TOKEN}"
@@ -11216,6 +11350,9 @@ telegram_setup_wizard() {
     echo ""
     log_success "Telegram bot configured!"
 
+    # Populate the client-side "/" command menu straight away.
+    telegram_sync_commands &>/dev/null &
+
     # Send test message
     telegram_test_message
 
@@ -12147,6 +12284,11 @@ mkdir -p "$(dirname "$OFFSET_FILE")"
 load_tg_settings
 load_traffic
 
+# Register the client-side "/" command menu via the manager, which owns the
+# command tables. Best-effort and backgrounded so a Telegram outage can never
+# delay or break the poll loop.
+"${INSTALL_DIR}/mtproxymax" telegram sync-commands &>/dev/null &
+
 _last_report=0
 _report_interval=$(( ${TELEGRAM_INTERVAL:-6} * 3600 ))
 _last_health=0
@@ -14177,6 +14319,7 @@ show_cli_help() {
     echo -e "    ${GREEN}telegram setup${NC}          Run Telegram bot wizard"
     echo -e "    ${GREEN}telegram status${NC}         Show Telegram bot status"
     echo -e "    ${GREEN}telegram test${NC}           Send test message"
+    echo -e "    ${GREEN}telegram sync-commands${NC}  Refresh the in-app command menu"
     echo -e "    ${GREEN}broadcast <msg>${NC}         Broadcast announcement via Telegram bot"
     echo -e "    ${GREEN}telegram disable${NC}        Disable Telegram"
     echo -e "    ${GREEN}telegram remove${NC}         Remove Telegram bot"
@@ -15860,6 +16003,7 @@ cli_main() {
             load_secrets
             case "${1:-status}" in
                 setup)   check_root; telegram_setup_wizard ;;
+                sync-commands) check_root; telegram_sync_commands ;;
                 test)    telegram_test_message ;;
                 status|"")
                     if [ "$TELEGRAM_ENABLED" != "true" ]; then
diff --git a/tests/test_telegram_commands.sh b/tests/test_telegram_commands.sh
new file mode 100644
index 0000000..831bcc2
--- /dev/null
+++ b/tests/test_telegram_commands.sh
@@ -0,0 +1,221 @@
+#!/bin/bash
+# Regression tests for the Telegram bot command menu (setMyCommands).
+#
+# The bot registers its command list with Telegram so clients render a tappable
+# "/" menu. Lists are scoped: everyone gets the public self-service commands,
+# admins get the admin control plane, superadmins additionally get the four
+# commands the dispatcher gates to superadmin.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+SETTINGS_FILE="$INSTALL_DIR/settings.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+check_root() { :; }
+load_settings() { :; }
+log_info() { :; }
+log_success() { :; }
+log_error() { LAST_ERROR="$*"; }
+log_warn() { :; }
+
+# ── Telemetry: record every Bot API call the code under test makes ───────────
+CALLS_FILE="$TEST_TMPDIR/calls.tsv"
+CALL_N=0
+
+# Sorted, comma-separated normalisation so assertions do not depend on the
+# order the tables happen to be written in.
+sorted_csv() {
+    printf '%s' "$1" | tr ',' '\n' | LC_ALL=C sort | tr '\n' ',' | sed 's/,$//'
+}
+
+curl() {
+    local _cfg="" _body="" _prev="" _a
+    for _a in "$@"; do
+        case "$_prev" in
+            -K) _cfg="$_a" ;;
+            -d) _body="$_a" ;;
+        esac
+        _prev="$_a"
+    done
+    local _url=""
+    [ -n "$_cfg" ] && [ -f "$_cfg" ] && _url=$(sed -n 's/^url = "\(.*\)"$/\1/p' "$_cfg" 2>/dev/null)
+    local _method="${_url##*/}"
+    local _chat
+    _chat=$(printf '%s' "$_body" | grep -o '"chat_id":[0-9-]*' | head -1 | cut -d: -f2)
+    [ -z "$_chat" ] && _chat="-"
+    local _cmds
+    _cmds=$(printf '%s' "$_body" | grep -o '"command":"[a-z0-9_]*"' | sed 's/"command":"//;s/"//' | tr '\n' ',' | sed 's/,$//')
+    # curl runs inside a command-substitution subshell, so a counter would not
+    # survive back to this shell. mktemp gives each call a unique body file.
+    local _bf
+    _bf=$(mktemp "$TEST_TMPDIR/body.XXXXXX")
+    printf '%s' "$_body" > "$_bf"
+    printf '%s\t%s\t%s\n' "$_method" "$_chat" "$_cmds" >> "$CALLS_FILE"
+    if [ "${CURL_OK:-true}" = "true" ]; then
+        printf '{"ok":true,"result":true}\n'
+    else
+        printf '{"ok":false,"error_code":401,"description":"Unauthorized"}\n'
+    fi
+}
+
+# Command list registered for a scope. "-" is the default (all users) scope.
+scope_commands() {
+    awk -F'\t' -v c="$1" '$1=="setMyCommands" && $2==c {print $3}' "$CALLS_FILE" | head -1
+}
+call_methods() { awk -F'\t' '{print $1}' "$CALLS_FILE"; }
+call_count() { wc -l < "$CALLS_FILE" 2>/dev/null | tr -d ' '; }
+# grep -c . counts non-empty lines, avoiding the trailing-newline off-by-one.
+csv_count() { printf '%s' "$1" | tr ',' '\n' | grep -c .; }
+csv_uniq_count() { printf '%s' "$1" | tr ',' '\n' | sort -u | grep -c .; }
+
+PUBLIC="my_status,redeem,start,support,voucher"
+ADMIN="mp_add,mp_broadcast,mp_digest,mp_disable,mp_enable,mp_fleet,mp_health,mp_help,
+mp_limits,mp_link,mp_rotate,mp_secrets,mp_setlimit,mp_status,mp_traffic,mp_upstreams,mp_voucher,reply"
+ADMIN=$(printf '%s' "$ADMIN" | tr -d '\n')
+SUPERADMIN="mp_add,mp_broadcast,mp_digest,mp_disable,mp_enable,mp_fleet,mp_health,mp_help,
+mp_limits,mp_link,mp_lockdown,mp_remove,mp_restart,mp_rotate,mp_secrets,mp_setlimit,mp_status,mp_traffic,mp_update,mp_upstreams,mp_voucher,reply"
+SUPERADMIN=$(printf '%s' "$SUPERADMIN" | tr -d '\n')
+
+# ── Fixtures ─────────────────────────────────────────────────────────────────
+TELEGRAM_ENABLED="true"
+TELEGRAM_BOT_TOKEN="123456:TESTTOKEN"
+TELEGRAM_CHAT_ID="111"
+printf '222|superadmin|Ops|2025-01-01\n333|reseller|Shop|2025-01-02\n' > "$ADMINS_FILE"
+
+echo "Telegram command menu tests"
+
+# ── Happy path ───────────────────────────────────────────────────────────────
+: > "$CALLS_FILE"
+CURL_OK=true
+telegram_sync_commands
+assert_eq "sync returns success" 0 "$?"
+
+assert_eq "all users get the public commands" "$PUBLIC" "$(sorted_csv "$(scope_commands -)")"
+assert_eq "root admin chat gets superadmin commands" "$SUPERADMIN" "$(sorted_csv "$(scope_commands 111)")"
+assert_eq "admins.conf superadmin gets superadmin commands" "$SUPERADMIN" "$(sorted_csv "$(scope_commands 222)")"
+assert_eq "reseller gets the reduced admin commands" "$ADMIN" "$(sorted_csv "$(scope_commands 333)")"
+
+# The scoping guarantee: a reseller must not be shown privileged commands.
+for _c in mp_remove mp_restart mp_update mp_lockdown; do
+    assert_eq "reseller is not offered /$_c" "" "$(scope_commands 333 | tr ',' '\n' | grep -x "$_c")"
+done
+# ...while the superadmin must be.
+for _c in mp_remove mp_restart mp_update mp_lockdown; do
+    assert_eq "superadmin is offered /$_c" "$_c" "$(scope_commands 111 | tr ',' '\n' | grep -x "$_c")"
+done
+
+assert_eq "every registered command is namespaced correctly" "" "$(scope_commands 111 | tr ',' '\n' | grep -vE '^(reply|mp_[a-z_]+)$')"
+assert_eq "no duplicate commands are registered" \
+    "$(csv_uniq_count "$(scope_commands 111)")" "$(csv_count "$(scope_commands 111)")"
+
+# ── Failure and disabled paths are never fatal ───────────────────────────────
+CURL_OK=false
+: > "$CALLS_FILE"
+telegram_sync_commands
+assert_eq "sync survives a Bot API failure" 0 "$?"
+assert_eq "sync still attempts the public scope on failure" "setMyCommands" "$(call_methods | head -1)"
+
+CURL_OK=true
+TELEGRAM_ENABLED=false
+: > "$CALLS_FILE"
+telegram_sync_commands
+assert_eq "disabled bot is a no-op" 0 "$(call_count)"
+
+TELEGRAM_ENABLED=true
+_SAVED_TOKEN="$TELEGRAM_BOT_TOKEN"
+TELEGRAM_BOT_TOKEN=""
+: > "$CALLS_FILE"
+telegram_sync_commands
+assert_eq "missing token is a no-op" 0 "$(call_count)"
+TELEGRAM_BOT_TOKEN="$_SAVED_TOKEN"
+
+# ── Revoking an admin clears their menu ──────────────────────────────────────
+: > "$CALLS_FILE"
+telegram_clear_commands 333
+assert_eq "clearing an admin uses deleteMyCommands" "deleteMyCommands" "$(call_methods | head -1)"
+assert_eq "clearing targets the removed admin chat" "333" "$(awk -F'\t' '{print $2}' "$CALLS_FILE" | head -1)"
+
+# ── Request bodies are well-formed JSON ──────────────────────────────────────
+# Dependency-free structural check: always runs, and catches unbalanced braces
+# or a truncated payload.
+json_shape_ok() {
+    local b="$1"
+    [ -n "$b" ] || return 1
+    [ "${b#\{}" != "$b" ] || return 1
+    [ "${b%\}}" != "$b" ] || return 1
+    [ "$(printf '%s' "$b" | tr -cd '{' | wc -c)" = "$(printf '%s' "$b" | tr -cd '}' | wc -c)" ] || return 1
+    [ "$(printf '%s' "$b" | tr -cd '[' | wc -c)" = "$(printf '%s' "$b" | tr -cd ']' | wc -c)" ] || return 1
+    return 0
+}
+
+# Note: the Windows Store ships a python3.exe alias that exists on PATH but
+# cannot execute, so probe with a real invocation rather than `command -v`.
+PY=""
+if python3 -c 'import json' >/dev/null 2>&1; then
+    PY="python3"
+elif python -c 'import json' >/dev/null 2>&1; then
+    PY="python"
+fi
+
+_shape_bad=0
+_parsed_bad=0
+_validated=0
+for _f in "$TEST_TMPDIR"/body.*; do
+    [ -f "$_f" ] || continue
+    _validated=$((_validated + 1))
+    json_shape_ok "$(cat "$_f")" || _shape_bad=$((_shape_bad + 1))
+    if [ -n "$PY" ]; then
+        "$PY" -c 'import json,sys; json.load(open(sys.argv[1]))' "$_f" 2>/dev/null || _parsed_bad=$((_parsed_bad + 1))
+    fi
+done
+# Guard against a vacuous pass: with no captured bodies the loop never runs.
+assert_eq "request bodies were captured for validation" "yes" \
+    "$([ "$_validated" -gt 0 ] && echo yes || echo no)"
+assert_eq "every request body is structurally valid JSON" "0" "$_shape_bad"
+if [ -n "$PY" ]; then
+    assert_eq "every request body parses as JSON ($PY)" "0" "$_parsed_bad"
+fi
+
+# Telegram rejects the whole list if a single entry is malformed, so a stray
+# control character or quote in a description must not corrupt the payload.
+if [ -n "$PY" ]; then
+    _tricky=$(printf 'weird|He said "hi" in C:\\path\tand a\rCR')
+    assert_eq "descriptions with quotes, backslashes and control chars stay valid JSON" "ok" \
+        "$(_tg_commands_json "$_tricky" | "$PY" -c 'import json,sys; json.loads(sys.stdin.read()); print("ok")' 2>/dev/null || echo bad)"
+fi
+
+# ── The generated daemon re-syncs the menu on boot ───────────────────────────
+telegram_generate_service_script
+_DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+assert_eq "daemon script is generated" "yes" "$([ -f "$_DAEMON" ] && echo yes || echo no)"
+assert_eq "daemon syncs the command menu on boot" "yes" \
+    "$(grep -q 'telegram sync-commands' "$_DAEMON" && echo yes || echo no)"
+assert_eq "generated daemon is valid bash" 0 "$(bash -n "$_DAEMON" 2>/dev/null; echo $?)"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]

From e689a1421990072e8830f1f1d0bf799268ecbe61 Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Thu, 17 Sep 2026 08:00:22 +0300
Subject: [PATCH 02/10] feat(telegram): add keyboard primitives and rewrite the
 update parser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundation for interactive inline-keyboard menus. No user-visible change:
nothing attaches a keyboard yet, and the callback dispatcher is a stub.

Additions (all inside the generated bot daemon, which is self-contained
because the heredoc is quoted and inherits nothing from the manager):

- Bot API primitives: _tg_post_method as a single curl chokepoint, plus
  tg_send_kb/tg_send_to_kb/tg_edit/tg_edit_markup/tg_answer_cb. reply_markup
  travels as an ordinary urlencoded form field, so no Content-Type header and
  no temp file, and the token stays out of the process list.

- Message chunking (_tg_chunk_text/_tg_send_pieces). Telegram caps a message
  at 4096 units and bot messages are built by appending one line per secret,
  so a large enough fleet produced a message that failed to send outright. A
  400 from a malformed Markdown entity now retries without parse_mode,
  costing the formatting instead of the whole message.

- callback_data codec (_cb_enc/_cb_dec/_cb_label_ok). The cap is 64 bytes and
  one over-long payload makes Telegram reject the entire reply_markup, so the
  encoder refuses rather than truncating — a truncated payload would decode
  into a different, still-valid target.

Fixes two latent bugs in the getUpdates path:

- The no-python3 fallback extracted text and chat id in two independent
  grep|tail passes and paired them by position, so a batch lost every update
  but the last and could pair one update's text with another's chat id.

- callback_query updates were never parsed. The extractor read
  r.get('message',{}), which is empty for a callback, so _process_cmd ran on
  empty input, wrote the offset, and the callback was confirmed and never
  redelivered.

The replacement awk extractor is a character scanner rather than a regex
pass, since a regex cannot tell whether a brace or quote sits inside a string
literal — a command's text can contain both. Both extractors now emit
identical records, and the tests assert that byte-for-byte, because the awk
path is the only one available without python3 (notably on Alpine, which this
project supports via OpenRC).

Also makes _tg_have_python probe by executing rather than by `command -v`:
the Windows Store ships a python3.exe alias that is on PATH but fails when
run. And drops the offset write from _process_cmd into _consume_updates, so
it advances per consumed record and a parser failure mid-batch redelivers the
tail instead of losing it.
---
 mtproxymax.sh                             | 456 ++++++++++++++++++++--
 tests/test_telegram_callback_data.sh      | 165 ++++++++
 tests/test_telegram_message_primitives.sh | 160 ++++++++
 tests/test_telegram_update_parser.sh      | 157 ++++++++
 4 files changed, 905 insertions(+), 33 deletions(-)
 create mode 100644 tests/test_telegram_callback_data.sh
 create mode 100644 tests/test_telegram_message_primitives.sh
 create mode 100644 tests/test_telegram_update_parser.sh

diff --git a/mtproxymax.sh b/mtproxymax.sh
index bf9f4f9..0de9425 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -11544,6 +11544,213 @@ send_proxy_qr_to() {
 # Escape Markdown special chars in labels for Telegram
 _esc() { local t="$1"; t="${t//_/\\_}"; t="${t//\*/\\*}"; t="${t//\`/\\\`}"; echo "$t"; }
 
+# ── Bot API primitives ──────────────────────────────────────────────────────
+# The daemon is emitted from a QUOTED heredoc, so it inherits nothing from the
+# manager — no _mktemp, no log_*. Everything here is self-contained.
+#
+# tg_send()/tg_send_to() are deliberately left untouched: they have ~40 call
+# sites and tg_send also fires webhook_send, so the reply_markup-capable
+# variants below are additive rather than a signature change.
+
+# Single curl chokepoint for Bot API methods. Fields travel as urlencoded form
+# values — reply_markup is just a JSON string in one of them — which needs no
+# Content-Type header and no temp file, and keeps the token out of the process
+# list via -K process substitution.
+_tg_post_method() {
+    local _m="$1"; shift
+    local _f=()
+    while [ $# -gt 0 ]; do _f+=(--data-urlencode "$1"); shift; done
+    curl -s --max-time 15 -X POST \
+        -K <(printf 'url = "https://api.telegram.org/bot%s/%s"\n' "$TELEGRAM_BOT_TOKEN" "$_m") \
+        "${_f[@]}" 2>/dev/null
+}
+
+# The "[label | ip]" prefix every outgoing message carries. Exposed because the
+# chunker has to budget for it — Telegram counts UTF-16 units, and an emoji in
+# the label costs two.
+_tg_header() {
+    local label="${TELEGRAM_SERVER_LABEL:-MTProxyMax}"
+    local _ip; _ip=$(get_cached_ip)
+    if [ -n "$_ip" ]; then printf '[%s | %s] ' "$(_esc "$label")" "$_ip"
+    else printf '[%s] ' "$(_esc "$label")"; fi
+}
+
+# Split a body into pieces that each fit Telegram's 4096-unit cap, emitted with
+# a trailing \x1f after every piece so they can be read back with `read -d`.
+# A fenced block that straddles a split is closed in the outgoing piece and
+# reopened in the next, otherwise the monospace alignment breaks.
+_tg_chunk_text() {
+    local budget="$1" body="$2"
+    local _sep=$'\x1f'
+    local chunk="" line fence=0 out=""
+    while IFS= read -r line || [ -n "$line" ]; do
+        if [ -n "$chunk" ] && [ $(( ${#chunk} + ${#line} + 1 )) -gt "$budget" ]; then
+            if [ "$fence" -eq 1 ]; then
+                out="${out}${chunk}"$'\n''```'"${_sep}"
+                chunk='```'
+            else
+                out="${out}${chunk}${_sep}"
+                chunk=""
+            fi
+        fi
+        if [ -z "$chunk" ]; then chunk="$line"; else chunk="${chunk}"$'\n'"${line}"; fi
+        case "$line" in
+            '```'*) if [ "$fence" -eq 0 ]; then fence=1; else fence=0; fi ;;
+        esac
+    done <<< "$body"
+    printf '%s%s' "${out}${chunk}" "$_sep"
+}
+
+# Send a text to a chat, chunked if needed, with an optional keyboard on the
+# final piece. A 400 from Telegram is retried once without parse_mode: a
+# malformed Markdown entity should cost the formatting, not the whole message.
+_tg_send_pieces() {
+    local _chat="$1" _hdr="$2" _body="$3" _markup="${4:-}"
+    local _budget=$(( 4096 - ${#_hdr} - 32 ))
+    [ "$_budget" -lt 256 ] && _budget=256
+    local -a _parts=()
+    local _piece=""
+    while IFS= read -r -d $'\x1f' _piece || [ -n "$_piece" ]; do
+        [ -z "$_piece" ] && continue
+        _parts+=("$_piece")
+    done < <(_tg_chunk_text "$_budget" "$_body")
+    local _n=${#_parts[@]} _i=0 _resp
+    local _last_out=""
+    for _piece in "${_parts[@]}"; do
+        _i=$(( _i + 1 ))
+        local _args=( "chat_id=${_chat}" "text=${_hdr}${_piece}" "parse_mode=Markdown" )
+        if [ "$_i" -eq "$_n" ] && [ -n "$_markup" ]; then
+            _args+=( "reply_markup=${_markup}" )
+        fi
+        _resp=$(_tg_post_method sendMessage "${_args[@]}")
+        _last_out="$_resp"
+        case "$_resp" in
+            *'"ok":true'*) : ;;
+            *'"error_code":400'*)
+                local _plain=( "chat_id=${_chat}" "text=${_hdr}${_piece}" )
+                if [ "$_i" -eq "$_n" ] && [ -n "$_markup" ]; then
+                    _plain+=( "reply_markup=${_markup}" )
+                fi
+                _last_out=$(_tg_post_method sendMessage "${_plain[@]}")
+                ;;
+        esac
+    done
+    printf '%s' "$_last_out"
+}
+
+# message_id of the last send, or empty.
+_tg_msg_id() { printf '%s' "$1" | grep -o '"message_id":[0-9]*' | head -1 | grep -o '[0-9]*'; }
+
+tg_send_kb() {
+    local _text="$1" _markup="${2:-}"
+    local _hdr; _hdr=$(_tg_header)
+    local _body; _body=$(printf '%b' "$_text")
+    _tg_send_pieces "${TELEGRAM_CHAT_ID}" "$_hdr" "$_body" "$_markup" >/dev/null
+    webhook_send "$_text" 2>/dev/null || true
+}
+
+tg_send_to_kb() {
+    local _chat="$1" _text="$2" _markup="${3:-}"
+    local _body; _body=$(printf '%b' "$_text")
+    _tg_send_pieces "$_chat" "" "$_body" "$_markup" >/dev/null
+}
+
+# Replace a message's text and keyboard in place. Telegram answers 400
+# "message is not modified" when the text AND markup are unchanged, which
+# happens on every tap of the page the user is already on — treat it as success.
+tg_edit() {
+    local _chat="$1" _mid="$2" _text="$3" _markup="${4:-}"
+    [ -n "$_mid" ] || return 0
+    local _args=( "chat_id=${_chat}" "message_id=${_mid}" "text=${_text}" "parse_mode=Markdown" )
+    [ -n "$_markup" ] && _args+=( "reply_markup=${_markup}" )
+    _tg_post_method editMessageText "${_args[@]}" >/dev/null
+}
+
+# Swap only the keyboard, leaving the body alone. Cheaper than a full edit and
+# it sidesteps "message is not modified" for a pure page flip.
+tg_edit_markup() {
+    local _chat="$1" _mid="$2" _markup="$3"
+    [ -n "$_mid" ] || return 0
+    _tg_post_method editMessageReplyMarkup \
+        "chat_id=${_chat}" "message_id=${_mid}" "reply_markup=${_markup}" >/dev/null
+}
+
+# Acknowledge a callback. The client spins until this arrives, so it must be
+# called on EVERY path including denial and error.
+tg_answer_cb() {
+    local _id="$1" _toast="${2:-}" _alert="${3:-false}"
+    [ -n "$_id" ] || return 0
+    local _args=( "callback_query_id=${_id}" )
+    [ -n "$_toast" ] && _args+=( "text=${_toast}" )
+    [ "$_alert" = "true" ] && _args+=( "show_alert=true" )
+    _tg_post_method answerCallbackQuery "${_args[@]}" >/dev/null
+}
+
+# ── Inline-keyboard callback_data codec ─────────────────────────────────────
+# Grammar: <ns>[:<action>[:<target>[:<page>]]], trailing empty fields trimmed.
+# All ASCII, so byte length equals character length. Fields 3 and 4 are purely
+# positional — their meaning depends on the namespace (for "u:l" field 3 is a
+# page; for "u:s" it is a label and field 4 the page). The dispatcher assigns
+# meaning; the codec only guarantees shape.
+#
+# The Bot API caps callback_data at 64 bytes, and a single over-long payload
+# makes Telegram reject the ENTIRE reply_markup with a 400 — the whole message
+# is lost, not just that one button. So _cb_enc refuses rather than truncating:
+# a truncated payload would decode into a different, still-valid target.
+_CB_MAX=64
+
+# Labels are the only caller-supplied field in a payload, and a ':' inside one
+# would shift the positional fields — turning "u:s:ali:ce" into a 4-field
+# payload that decodes to a different target. Refusing anything outside the
+# secrets.conf charset makes field injection structurally impossible.
+_cb_label_ok() {
+    [[ "$1" =~ ^[a-zA-Z0-9_-]{1,32}$ ]]
+}
+
+# _cb_enc <ns> <action> <target> <page> -> payload on stdout, non-zero if the
+# result would be malformed or over-long.
+_cb_enc() {
+    local ns="$1" act="$2" tgt="$3" page="$4" out
+    [[ "$ns" =~ ^[a-z]{1,2}$ ]] || return 1
+    if [ -n "$act" ]  && ! _cb_label_ok "$act";  then return 1; fi
+    if [ -n "$tgt" ]  && ! _cb_label_ok "$tgt";  then return 1; fi
+    if [ -n "$page" ] && ! _cb_label_ok "$page"; then return 1; fi
+    # An action namespace is meaningless without a target, so require one here
+    # and the dispatcher can then trust that any a:/c: payload it sees names a
+    # label. (It still re-validates that the label exists.)
+    case "$ns" in
+        a|c) [ -n "$tgt" ] || return 1 ;;
+    esac
+    out="$ns"
+    [ -n "$act" ]  && out="${out}:${act}"
+    [ -n "$tgt" ]  && out="${out}:${tgt}"
+    [ -n "$page" ] && out="${out}:${page}"
+    [ "${#out}" -le "$_CB_MAX" ] || return 1
+    printf '%s' "$out"
+}
+
+# _cb_dec <payload> -> sets _CB_NS _CB_ACT _CB_TGT _CB_PAGE; non-zero if the
+# payload is malformed or over-long.
+#
+# Sets globals rather than printing to stdout on purpose: rendering a menu with
+# 30 buttons would otherwise fork 30 subshells. Callers must therefore never
+# write `x=$(_cb_dec ...)` — the assignments would be lost.
+_cb_dec() {
+    local p="$1"
+    _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
+    [ -n "$p" ] || return 1
+    [ "${#p}" -le "$_CB_MAX" ] || return 1
+    [[ "$p" =~ ^[a-z]{1,2}(:[A-Za-z0-9_-]{1,32}){0,3}$ ]] || return 1
+    local IFS=':' _f
+    local -a _fields
+    read -r -a _fields <<< "$p"
+    _CB_NS="${_fields[0]}"
+    [ "${#_fields[@]}" -gt 1 ] && _CB_ACT="${_fields[1]}"
+    [ "${#_fields[@]}" -gt 2 ] && _CB_TGT="${_fields[2]}"
+    [ "${#_fields[@]}" -gt 3 ] && _CB_PAGE="${_fields[3]}"
+    return 0
+}
+
 is_running() {
     is_proxy_running
 }
@@ -11768,6 +11975,206 @@ update_traffic() {
 
 get_cum_user_traffic() { echo "${_cum_user_in[$1]:-0} ${_cum_user_out[$1]:-0}"; }
 
+# `command -v python3` is not sufficient: the Windows Store ships a python3.exe
+# alias that sits on PATH but fails the moment it runs, and some distros ship a
+# stub. Probe by actually executing it.
+_tg_have_python() {
+    command -v python3 &>/dev/null || return 1
+    python3 -c '' &>/dev/null 2>&1
+}
+
+# Both extractors emit the same tab-separated 6-field records:
+#
+#   <update_id>\t<kind>\t<chat_id>\t<message_id>\t<callback_id>\t<payload>
+#
+# kind is "msg" or "cb"; for "msg" the callback id is "-". A record is emitted
+# for EVERY element of `result`, even one carrying no message at all, because
+# the consumer advances the offset per record — skipping one would make
+# Telegram redeliver it forever.
+_tg_parse_updates_py() {
+    printf '%s' "$1" | python3 -c '
+import json,sys
+
+# Pin LF. Python in text mode translates "\n" to os.linesep, so on Windows the
+# records would come out CRLF and the trailing "\r" would end up inside the
+# command payload. The awk extractor always emits LF; this keeps them identical
+# on every platform.
+try:
+    sys.stdout.reconfigure(newline="\n")
+except Exception:
+    pass
+
+def clean(v):
+    if not isinstance(v, str):
+        v = "" if v is None else str(v)
+    # only the first line is the command
+    v = v.split("\n")[0].replace("\t", " ").replace("\r", "")
+    return v[:512]
+
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+if not isinstance(data, dict):
+    sys.exit(0)
+for r in data.get("result", []) or []:
+    if not isinstance(r, dict):
+        continue
+    uid = r.get("update_id")
+    if uid is None:
+        continue
+    cq = r.get("callback_query")
+    if isinstance(cq, dict):
+        m = cq.get("message")
+        m = m if isinstance(m, dict) else {}
+        ch = m.get("chat")
+        ch = ch if isinstance(ch, dict) else {}
+        print("%s\tcb\t%s\t%s\t%s\t%s" % (uid, ch.get("id", ""), m.get("message_id", ""),
+                                          cq.get("id", ""), clean(cq.get("data", ""))))
+    else:
+        m = r.get("message")
+        m = m if isinstance(m, dict) else {}
+        ch = m.get("chat")
+        ch = ch if isinstance(ch, dict) else {}
+        print("%s\tmsg\t%s\t%s\t-\t%s" % (uid, ch.get("id", ""), m.get("message_id", ""),
+                                          clean(m.get("text", ""))))
+' 2>/dev/null
+}
+
+# Dependency-free fallback, used on hosts without a working python3 — notably
+# Alpine, which this project supports via OpenRC.
+#
+# This MUST be a character scanner rather than a regex pass: a regex cannot tell
+# whether a `}` or `"` sits inside a string literal, and a command's text can
+# contain both ("tricky \"chat\":{\"id\":999}"). The scanner tracks string and
+# escape state and object/array depth, so embedded JSON in a text field is inert.
+#
+# One documented divergence from the python path: \uXXXX escapes are left as
+# literal text rather than decoded. Command text is ASCII in practice, and a
+# mis-decoded command simply matches nothing.
+_tg_parse_updates_awk() {
+    awk '
+    function reset() {
+        e_upd=""; e_chat=""; e_msgid=""; e_text=""; e_cbid=""; e_cbdata=""; e_cb=0
+    }
+    function scalar(k, parent, v) {
+        if (!inel) return
+        if      (k == "update_id"  && parent == "")               e_upd    = v
+        else if (k == "message_id" && parent == "message")        e_msgid  = v
+        else if (k == "id"         && parent == "chat")           e_chat   = v
+        else if (k == "text"       && parent == "message")        e_text   = v
+        else if (k == "id"         && parent == "callback_query") e_cbid   = v
+        else if (k == "data"       && parent == "callback_query") e_cbdata = v
+    }
+    function flush(   kind, cbid, pay, p) {
+        if (e_upd == "") return
+        if (e_cb) { kind = "cb";  cbid = e_cbid; pay = e_cbdata }
+        else      { kind = "msg"; cbid = "-";    pay = e_text }
+        p = index(pay, "\n"); if (p > 0) pay = substr(pay, 1, p - 1)
+        gsub(/\r/, "", pay)
+        if (length(pay) > 512) pay = substr(pay, 1, 512)
+        printf "%s\t%s\t%s\t%s\t%s\t%s\n", e_upd, kind, e_chat, e_msgid, cbid, pay
+    }
+    { if (NR == 1) s = $0; else s = s "\n" $0; next }
+    END {
+        n = length(s)
+        depth = 0; instr = 0; esc = 0; intok = 0
+        arrdepth = -1; inel = 0; want_result = 0
+        curkey = ""; buf = ""; kstk[0] = ""
+        reset()
+        for (i = 1; i <= n; i++) {
+            c = substr(s, i, 1)
+            if (instr) {
+                if (esc) {
+                    esc = 0
+                    if      (c == "n") buf = buf "\n"
+                    else if (c == "t") buf = buf "\t"
+                    else if (c == "r") buf = buf "\r"
+                    else if (c == "b") buf = buf "\b"
+                    else if (c == "f") buf = buf "\f"
+                    else if (c == "u") buf = buf "\\u"
+                    else buf = buf c
+                    continue
+                }
+                if (c == "\\") { esc = 1; continue }
+                if (c == "\"") {
+                    instr = 0
+                    j = i + 1
+                    while (j <= n) {
+                        d = substr(s, j, 1)
+                        if (d == " " || d == "\t" || d == "\n" || d == "\r") { j++; continue }
+                        break
+                    }
+                    if (j <= n && substr(s, j, 1) == ":") {
+                        curkey = buf
+                        if (curkey == "result" && depth == 1) want_result = 1
+                    } else {
+                        scalar(curkey, kstk[depth], buf)
+                    }
+                    continue
+                }
+                buf = buf c
+                continue
+            }
+            if (intok) {
+                if (c == "," || c == "}" || c == "]" || c == " " || c == "\t" || c == "\n" || c == "\r") {
+                    intok = 0
+                    scalar(curkey, kstk[depth], buf)
+                    buf = ""
+                    i--
+                    continue
+                }
+                buf = buf c
+                continue
+            }
+            if (c == "\"") { instr = 1; buf = ""; continue }
+            if (c == "{" || c == "[") {
+                if (c == "[" && want_result) { arrdepth = depth + 1; want_result = 0 }
+                depth++
+                if (c == "{" && inel && curkey == "callback_query") e_cb = 1
+                if (c == "{" && arrdepth >= 0 && depth == arrdepth + 1) {
+                    kstk[depth] = ""
+                    inel = 1
+                    reset()
+                } else {
+                    kstk[depth] = curkey
+                }
+                continue
+            }
+            if (c == "}" || c == "]") {
+                if (c == "}" && inel && depth == arrdepth + 1) { flush(); inel = 0 }
+                depth--
+                continue
+            }
+            if (c == ":" || c == "," || c == " " || c == "\t" || c == "\n" || c == "\r") continue
+            intok = 1; buf = c
+        }
+    }
+    ' <<< "$1"
+}
+
+# Read one batch of records and dispatch. Process substitution, deliberately not
+# a pipe: a pipeline would run the dispatchers in a subshell and silently
+# discard every global they set.
+_consume_updates() {
+    local _uid _kind _cid _mid _cbid _pay
+    while IFS=$'\t' read -r _uid _kind _cid _mid _cbid _pay || [ -n "$_uid" ]; do
+        [ -z "$_uid" ] && continue
+        [[ "$_uid" =~ ^[0-9]+$ ]] || continue
+        # Belt and braces: the extractors already strip CR from the payload and
+        # pin LF terminators, but a stray one here would silently corrupt every
+        # command by appending a character to it.
+        _pay="${_pay%$'\r'}"
+        # Advance per consumed record, not per batch: a parser failure midway
+        # then redelivers the unconsumed tail instead of losing it.
+        printf '%s\n' "$(( _uid + 1 ))" > "$OFFSET_FILE"
+        case "$_kind" in
+            msg) _process_cmd "$_uid" "$_cid" "$_pay" ;;
+            cb)  _process_callback "$_cid" "$_mid" "$_cbid" "$_pay" ;;
+        esac
+    done < <(if _tg_have_python; then _tg_parse_updates_py "$1"; else _tg_parse_updates_awk "$1"; fi)
+}
+
 process_commands() {
     local offset=$(cat "$OFFSET_FILE" 2>/dev/null || echo "0")
     [[ "$offset" =~ ^[0-9]+$ ]] || offset="0"
@@ -11776,38 +12183,7 @@ process_commands() {
         -K <(printf 'url = "https://api.telegram.org/bot%s/getUpdates?offset=%s&timeout=25"\n' "$TELEGRAM_BOT_TOKEN" "$offset") \
         2>/dev/null) || true
     [ -z "$updates" ] && return
-
-    if command -v python3 &>/dev/null; then
-        echo "$updates" | python3 -c "
-import json,sys
-try:
-    data=json.load(sys.stdin)
-    for r in data.get('result',[]):
-        uid=r['update_id']
-        txt=r.get('message',{}).get('text','').split('\n')[0][:200]
-        cid=r.get('message',{}).get('chat',{}).get('id','')
-        print(f'{uid}\t{cid}\t{txt}')
-except Exception:
-    pass
-" 2>/dev/null | while IFS=$'\t' read -r _uid _cid _txt || [ -n "$_uid" ]; do
-            [ -z "$_uid" ] && continue
-            _process_cmd "$_uid" "$_cid" "$_txt"
-        done
-    else
-        # Fallback: grep-based parsing (no python)
-        local _new_offset
-        _new_offset=$(echo "$updates" | grep -oE '"update_id"\s*:\s*[0-9]+' | tail -1 | grep -oE '[0-9]+')
-        if [ -n "$_new_offset" ]; then
-            echo "$((_new_offset + 1))" > "$OFFSET_FILE"
-        fi
-        local _text _cid
-        _text=$(echo "$updates" | grep -oE '"text"\s*:\s*"[^"]*"' | tail -1 | sed 's/.*"text"\s*:\s*"//;s/"$//')
-        _cid=$(echo "$updates" | grep -oE '"chat"\s*:\s*\{[^}]*"id"\s*:\s*-?[0-9]+' | tail -1 | grep -oE -- '-?[0-9]+$')
-        [ -n "$_text" ] && [ -n "$_cid" ] && {
-            _new_offset=${_new_offset:-0}
-            _process_cmd "$_new_offset" "$_cid" "$_text"
-        }
-    fi
+    _consume_updates "$updates"
 }
 
 _check_tg_role() {
@@ -11834,8 +12210,12 @@ _tg_security_log() {
 }
 
 _process_cmd() {
+    # update_id is accepted but no longer used for the offset: _consume_updates
+    # owns that, so it advances once per consumed record rather than once per
+    # dispatched command. Kept in the signature because callers and tests pass
+    # it positionally.
     local update_id="$1" chat_id="$2" text="$3"
-    echo "$((update_id + 1))" > "$OFFSET_FILE"
+    : "${update_id:=0}"
 
     local role
     role=$(_check_tg_role "$chat_id")
@@ -12275,6 +12655,16 @@ _process_cmd() {
     esac
 }
 
+# Callback-query entry point. The interactive menus land here in the next
+# change; for now it exists so that _consume_updates honours the offset
+# contract and an unexpected tap is acknowledged rather than leaving the
+# client spinning forever.
+_process_callback() {
+    local chat_id="$1" message_id="$2" callback_id="$3" payload="$4"
+    : "$chat_id" "$message_id" "$payload"
+    tg_answer_cb "$callback_id" "" "false"
+}
+
 # Cleanup trap for temp files
 trap _cleanup EXIT
 
diff --git a/tests/test_telegram_callback_data.sh b/tests/test_telegram_callback_data.sh
new file mode 100644
index 0000000..358bb94
--- /dev/null
+++ b/tests/test_telegram_callback_data.sh
@@ -0,0 +1,165 @@
+#!/bin/bash
+# Tests for the inline-keyboard callback_data codec.
+#
+# callback_data is capped at 64 bytes by the Bot API, and a single over-long
+# payload makes Telegram reject the ENTIRE reply_markup with a 400 — the whole
+# message is lost, not just the one button. Equally, a target containing ':'
+# would shift the positional fields and silently decode to a different target.
+# These tests pin both properties.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+assert_ok() {
+    local name="$1"; shift
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if "$@" >/dev/null 2>&1; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (expected success)\n' "$name"
+    fi
+}
+
+assert_rejects() {
+    local name="$1"; shift
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if "$@" >/dev/null 2>&1; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (expected rejection)\n' "$name"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+
+# ── Extract the codec from the daemon that actually ships ────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+CODEC="$TEST_TMPDIR/codec.sh"
+# _CB_MAX is a top-level assignment in the daemon, so the function extractor
+# below would not pick it up — pull it explicitly, and assert it so that a
+# future move fails loudly here instead of as an obscure arithmetic error.
+grep -m1 '^_CB_MAX=' "$DAEMON" > "$CODEC"
+for _fn in _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$CODEC"
+done
+assert_eq "codec extraction is valid bash" 0 \
+    "$(bash -n "$CODEC" 2>/dev/null; echo $?)"
+source "$CODEC"
+assert_eq "callback_data cap is 64 bytes" 64 "${_CB_MAX:-}"
+
+echo "Telegram callback_data codec tests"
+
+# ── _cb_label_ok ─────────────────────────────────────────────────────────────
+assert_ok       "label 'alice' is valid"            _cb_label_ok "alice"
+assert_ok       "label 'a-b_c9' is valid"           _cb_label_ok "a-b_c9"
+assert_ok       "32-char label is valid"            _cb_label_ok "0123456789012345678901234567890a"
+assert_rejects  "33-char label is rejected"         _cb_label_ok "0123456789012345678901234567890ab"
+assert_rejects  "empty label is rejected"           _cb_label_ok ""
+assert_rejects  "label with ':' is rejected"        _cb_label_ok "alice:bob"
+assert_rejects  "label with space is rejected"      _cb_label_ok "al ice"
+assert_rejects  "label with '\$(' is rejected"      _cb_label_ok 'a$(id)'
+assert_rejects  "label with ';' is rejected"        _cb_label_ok "alice;rm"
+assert_rejects  "label with '*' is rejected"        _cb_label_ok "alice*"
+assert_rejects  "label with '/' is rejected"        _cb_label_ok "a/b"
+
+# ── _cb_enc ──────────────────────────────────────────────────────────────────
+assert_eq "encodes a bare no-op"        "n"                 "$(_cb_enc n "" "" "")"
+assert_eq "encodes hub:help"            "m:h"               "$(_cb_enc m h "" "")"
+assert_eq "encodes a list page"         "u:l:2"             "$(_cb_enc u l 2 "")"
+assert_eq "encodes a detail card"       "u:s:alice:0"       "$(_cb_enc u s alice 0)"
+assert_eq "encodes an action request"   "a:disable:alice"   "$(_cb_enc a disable alice "")"
+assert_eq "encodes a confirmed action"  "c:remove:alice"    "$(_cb_enc c remove alice "")"
+assert_eq "encodes a traffic window"    "t:w:24h"           "$(_cb_enc t w 24h "")"
+
+assert_rejects "enc refuses a ':' in the target"  _cb_enc a disable "ali:ce" ""
+assert_rejects "enc refuses a 33-char target"     _cb_enc a disable "0123456789012345678901234567890ab" ""
+assert_rejects "enc refuses an injected target"   _cb_enc a disable 'a$(id)' ""
+assert_rejects "enc refuses an empty target"      _cb_enc a disable "" ""
+
+# Every verb against a maximal label must stay inside the 64-byte cap.
+for _verb in enable disable rotate remove; do
+    _p=$(_cb_enc a "$_verb" "0123456789012345678901234567890a" "")
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ -n "$_p" ] && [ "${#_p}" -le 64 ]; then
+        printf '  PASS  maximal %s payload is within 64 bytes (%d)\n' "$_verb" "${#_p}"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  maximal %s payload is within 64 bytes (got %d)\n' "$_verb" "${#_p}"
+    fi
+    _rt=$(_cb_enc a "$_verb" "0123456789012345678901234567890a" "")
+    assert_eq "maximal ${_verb} payload round-trips" \
+        "a:${_verb}:0123456789012345678901234567890a" "$_rt"
+done
+
+# ── _cb_dec ──────────────────────────────────────────────────────────────────
+decode() {
+    _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
+    _cb_dec "$1" || return 1
+    printf '%s|%s|%s|%s' "$_CB_NS" "$_CB_ACT" "$_CB_TGT" "$_CB_PAGE"
+}
+
+assert_eq "decodes a bare no-op"       "n|||"              "$(decode n)"
+assert_eq "decodes hub:help"           "m|h||"             "$(decode m:h)"
+assert_eq "decodes a list page"        "u|l|2|"            "$(decode u:l:2)"
+assert_eq "decodes a detail card"      "u|s|alice|0"       "$(decode u:s:alice:0)"
+assert_eq "decodes an action request"  "a|disable|alice|"  "$(decode a:disable:alice)"
+assert_eq "decodes a traffic window"   "t|w|24h|"          "$(decode t:w:24h)"
+
+assert_rejects "dec rejects an empty payload"        _cb_dec ""
+assert_rejects "dec rejects an empty field"          _cb_dec "a:disable:"
+assert_rejects "dec rejects an uppercase namespace"  _cb_dec "A:disable:alice"
+assert_rejects "dec rejects a 3-char namespace"      _cb_dec "tool:l"
+assert_rejects "dec rejects too many fields"         _cb_dec "u:l:2:3:4"
+assert_rejects "dec rejects an over-long field"      _cb_dec "u:s:0123456789012345678901234567890ab"
+assert_rejects "dec rejects an over-long payload"    _cb_dec "u:s:alice:0:extra:more:junk:padding:aaaaaaaaaaaaaaaaaaaaaaaaa"
+
+# An over-long payload must be refused, never truncated: truncation would
+# decode into a different, still-valid target.
+_pad=$(printf 'a%.0s' $(seq 1 80))
+assert_rejects "dec rejects an 80-byte payload"      _cb_dec "$_pad"
+
+# A forged payload is inert data — never evaluated, never decoded into a target
+# that could reach a shell.
+assert_rejects "dec rejects a forged \$( ) payload"  _cb_dec 'a:disable:$(id)'
+
+# ── Round-trip ───────────────────────────────────────────────────────────────
+# Field is 3rd-positional, so these specs carry no trailing ':' (read would
+# absorb it into the last variable).
+for _spec in "n" "m:h" "u:l:2" "u:s:alice:0" "a:disable:alice" "c:remove:alice" \
+             "t" "t:w:7d" "t:u:30d" "y" "y:e"; do
+    IFS=':' read -r _ns _act _tgt _pg <<< "$_spec"
+    _enc=$(_cb_enc "$_ns" "$_act" "$_tgt" "$_pg")
+    _dec=$(decode "$_enc")
+    assert_eq "round-trip $_spec" "$_ns|$_act|$_tgt|$_pg" "$_dec"
+done
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_message_primitives.sh b/tests/test_telegram_message_primitives.sh
new file mode 100644
index 0000000..f4e2e74
--- /dev/null
+++ b/tests/test_telegram_message_primitives.sh
@@ -0,0 +1,160 @@
+#!/bin/bash
+# Tests for the Bot API send primitives: chunking and the 400 fallback.
+#
+# Two behaviours matter here and neither existed before:
+#
+#   * Telegram caps a message at 4096 UTF-16 units and the bot builds messages
+#     by appending one line per secret, so a fleet with enough users silently
+#     produced a message that failed to send at all. There was no chunking.
+#   * A single malformed legacy-Markdown entity made Telegram reject the whole
+#     message with a 400. Retrying without parse_mode costs the formatting
+#     instead of the content.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+assert_ok() {
+    local name="$1" cond="$2"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$cond" -eq 0 ] 2>/dev/null; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s\n' "$name"
+    fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+PRIMS="$TEST_TMPDIR/prims.sh"
+: > "$PRIMS"
+for _fn in _tg_chunk_text _tg_send_pieces _tg_msg_id; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$PRIMS"
+done
+assert_eq "primitive extraction is valid bash" 0 \
+    "$(bash -n "$PRIMS" 2>/dev/null; echo $?)"
+source "$PRIMS"
+
+echo "Telegram message primitive tests"
+
+# The chunker separates records with 0x1f. NOTE: `tr '\x1f' ...` does not work
+# — GNU tr has no \xHH escape — and chunk bodies legitimately contain newlines,
+# so neither line-counting nor splitting on newlines is valid here.
+SEP=$'\x1f'
+n_chunks() {
+    local c n=0
+    while IFS= read -r -d "$SEP" c; do n=$((n + 1)); done < <(_tg_chunk_text "$2" "$1")
+    printf '%s' "$n"
+}
+# Reassemble every chunk, joining with the newline the split removed.
+joined() {
+    local c out=""
+    while IFS= read -r -d "$SEP" c; do
+        if [ -z "$out" ]; then out="$c"; else out="${out}"$'\n'"${c}"; fi
+    done < <(_tg_chunk_text "$2" "$1")
+    printf '%s' "$out"
+}
+
+# ── A body that fits stays a single chunk, unmodified ────────────────────────
+assert_eq "short body yields one chunk" 1 "$(n_chunks "hello world" 3800)"
+assert_eq "short body is passed through verbatim" "hello world" "$(joined "hello world" 3800)"
+
+# ── A long body is split, and nothing is lost ────────────────────────────────
+_long=$(seq 1 40 | awk '{printf "line %02d %s\n", $1, "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}')
+assert_ok "long body splits into more than one chunk" \
+    "$([ "$(n_chunks "$_long" 300)" -gt 1 ] && echo 0 || echo 1)"
+
+_over=1
+while IFS= read -r -d "$SEP" _c; do
+    [ "${#_c}" -gt 300 ] && _over=0
+done < <(_tg_chunk_text 300 "$_long")
+assert_ok "no chunk exceeds the budget" "$([ "$_over" -eq 1 ] && echo 0 || echo 1)"
+
+# Reassembly must be lossless for unfenced content.
+assert_eq "splitting then rejoining is lossless" "$_long" "$(joined "$_long" 300)"
+
+# ── Fences are closed and reopened across a split ────────────────────────────
+# A sparkline is alignment-sensitive: a chunk that opens a fence without
+# closing it renders the remainder of that message as code.
+_fenced=$( { printf 'header\n```\n'; seq 1 30 | awk '{printf "bar %02d %s\n", $1, "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"}'; printf '```\ntail\n'; } )
+_bad=0
+while IFS= read -r -d "$SEP" _c; do
+    _n=$(printf '%s\n' "$_c" | grep -c '^```')
+    [ $(( _n % 2 )) -ne 0 ] && _bad=1
+done < <(_tg_chunk_text 250 "$_fenced")
+assert_ok "every chunk has balanced fences" "$([ "$_bad" -eq 0 ] && echo 0 || echo 1)"
+
+assert_ok "fenced body actually splits" \
+    "$([ "$(n_chunks "$_fenced" 250)" -gt 1 ] && echo 0 || echo 1)"
+
+# No fenced row may be dropped, whatever the split point.
+_rows=$(printf '%s' "$(joined "$_fenced" 250)" | grep -c '^bar ')
+assert_eq "all fenced rows survive the split" 30 "$_rows"
+
+# ── The 400 fallback drops parse_mode instead of the message ─────────────────
+POST_LOG="$TEST_TMPDIR/posts.log"
+POST_N=0
+_tg_post_method() {
+    printf '%s\n' "$*" >> "$POST_LOG"
+    POST_N=$((POST_N + 1))
+    if [ "$POST_N" -eq 1 ]; then
+        printf '{"ok":false,"error_code":400,"description":"Bad Request: can not parse entities"}'
+    else
+        printf '{"ok":true,"result":{"message_id":42,"chat":{"id":1}}}'
+    fi
+}
+: > "$POST_LOG"
+_tg_send_pieces "111" "" "bad *markdown" "" >/dev/null
+assert_eq "a 400 is retried exactly once" 2 "$(wc -l < "$POST_LOG" | tr -d ' ')"
+assert_ok "the first attempt uses Markdown" \
+    "$(grep -q 'parse_mode=Markdown' "$POST_LOG" && echo 0 || echo 1)"
+assert_ok "the retry omits parse_mode" \
+    "$(sed -n '2p' "$POST_LOG" | grep -qv 'parse_mode' && echo 0 || echo 1)"
+
+# A successful send must NOT be retried.
+: > "$POST_LOG"
+POST_N=99
+_tg_send_pieces "111" "" "fine" "" >/dev/null
+assert_eq "a successful send is not retried" 1 "$(wc -l < "$POST_LOG" | tr -d ' ')"
+
+# ── The keyboard rides on the final chunk only ───────────────────────────────
+: > "$POST_LOG"
+POST_N=99
+_tg_send_pieces "111" "" "$_long" '{"inline_keyboard":[[{"text":"x","callback_data":"n"}]]}' >/dev/null
+assert_eq "only the last chunk carries reply_markup" 1 "$(grep -c 'reply_markup' "$POST_LOG")"
+
+# ── message_id extraction ────────────────────────────────────────────────────
+assert_eq "extracts message_id from a send response" 42 \
+    "$(_tg_msg_id '{"ok":true,"result":{"message_id":42,"chat":{"id":1}}}')"
+assert_eq "returns empty when there is no message_id" "" \
+    "$(_tg_msg_id '{"ok":false}')"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_update_parser.sh b/tests/test_telegram_update_parser.sh
new file mode 100644
index 0000000..921a3f5
--- /dev/null
+++ b/tests/test_telegram_update_parser.sh
@@ -0,0 +1,157 @@
+#!/bin/bash
+# Tests for the getUpdates parser.
+#
+# Two production bugs motivate this file:
+#
+#   1. The no-python3 fallback extracted text and chat id in two INDEPENDENT
+#      `grep | tail -1` passes and paired them by position. A batch of two
+#      updates therefore lost all but the last, and could pair update A's text
+#      with update B's chat id.
+#   2. callback_query updates were never parsed at all, so the offset advanced
+#      and Telegram never redelivered them.
+#
+# Both extractors must emit byte-identical records, because the awk path is the
+# only one available on a host without python3 (e.g. Alpine, which this project
+# supports via OpenRC).
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s\n         got=%q\n        want=%q\n' "$name" "$got" "$want"
+    fi
+}
+
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q)\n' "$name" "$needle"
+    fi
+}
+
+# ── Extract both extractors from the daemon that actually ships ──────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+PARSER="$TEST_TMPDIR/parser.sh"
+: > "$PARSER"
+for _fn in _tg_have_python _tg_parse_updates_py _tg_parse_updates_awk; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$PARSER"
+done
+assert_eq "parser extraction is valid bash" 0 \
+    "$(bash -n "$PARSER" 2>/dev/null; echo $?)"
+source "$PARSER"
+
+echo "Telegram update parser tests"
+
+# ── Fixtures ─────────────────────────────────────────────────────────────────
+# Three updates in one batch. The second message's text deliberately embeds
+# escaped quotes, braces and a backslash so that a scanner which does not track
+# JSON string state will mis-slice the batch.
+F_MAIN="$TEST_TMPDIR/main.json"
+cat > "$F_MAIN" <<'JSON'
+{"ok":true,"result":[{"update_id":1001,"message":{"message_id":11,"chat":{"id":111,"type":"private"},"text":"/mp_status"}},{"update_id":1002,"message":{"message_id":12,"chat":{"id":222,"type":"private"},"text":"tricky \"chat\":{\"id\":999} and } and \\ backslash"}},{"update_id":1003,"callback_query":{"id":"cb-abc","data":"u:s:alice:0","message":{"message_id":13,"chat":{"id":111,"type":"private"}}}}]}
+JSON
+
+# The text decodes to: tricky "chat":{"id":999} and } and \ backslash
+EXPECT_MAIN=$(printf '1001\tmsg\t111\t11\t-\t/mp_status\n1002\tmsg\t222\t12\t-\ttricky "chat":{"id":999} and } and \\ backslash\n1003\tcb\t111\t13\tcb-abc\tu:s:alice:0')
+
+# An update with no message/callback at all must still yield a record, so the
+# consumer advances past it. Otherwise Telegram redelivers it forever.
+F_BARE="$TEST_TMPDIR/bare.json"
+cat > "$F_BARE" <<'JSON'
+{"ok":true,"result":[{"update_id":2000},{"update_id":2001,"message":{"message_id":21,"chat":{"id":333,"type":"private"},"text":"/start"}}]}
+JSON
+EXPECT_BARE=$(printf '2000\tmsg\t\t\t-\t\n2001\tmsg\t333\t21\t-\t/start')
+
+# A truncated response must yield nothing at all — never a partial record.
+F_TRUNC="$TEST_TMPDIR/truncated.json"
+printf '{"ok":true,"result":[{"update_id":9,"message":{"message_id":1,' > "$F_TRUNC"
+
+# text containing a real newline escape: only the first line is the command.
+F_MULTILINE="$TEST_TMPDIR/multiline.json"
+cat > "$F_MULTILINE" <<'JSON'
+{"ok":true,"result":[{"update_id":3000,"message":{"message_id":31,"chat":{"id":444,"type":"private"},"text":"/mp_add alice\nsecond line ignored"}}]}
+JSON
+EXPECT_MULTILINE=$(printf '3000\tmsg\t444\t31\t-\t/mp_add alice')
+
+# ── The awk extractor (always available) ─────────────────────────────────────
+assert_eq "awk parses a 3-update batch in order" "$EXPECT_MAIN" "$(_tg_parse_updates_awk "$(cat "$F_MAIN")")"
+assert_eq "awk advances past updates with no message" "$EXPECT_BARE" "$(_tg_parse_updates_awk "$(cat "$F_BARE")")"
+assert_eq "awk emits nothing for truncated JSON" "" "$(_tg_parse_updates_awk "$(cat "$F_TRUNC")")"
+assert_eq "awk keeps only the first line of text" "$EXPECT_MULTILINE" "$(_tg_parse_updates_awk "$(cat "$F_MULTILINE")")"
+assert_eq "awk emits nothing for empty input" "" "$(_tg_parse_updates_awk "")"
+assert_eq "awk emits nothing for non-JSON input" "" "$(_tg_parse_updates_awk "not json at all")"
+
+# The mis-pairing regression: update 1002's chat must be 222, not 111 or 999.
+_awk_main=$(_tg_parse_updates_awk "$(cat "$F_MAIN")")
+assert_contains "awk pairs text with its own chat id" "$(printf '1002\tmsg\t222\t12')" "$_awk_main"
+assert_eq "awk does not leak a chat id embedded in text" 3 "$(printf '%s\n' "$_awk_main" | wc -l | tr -d ' ')"
+assert_eq "awk does not mistake embedded text for the chat id" 0 \
+    "$(printf '%s\n' "$_awk_main" | grep -c $'^1002\tmsg\t999\t')"
+
+# ── 5000-char text is truncated to 512 ───────────────────────────────────────
+F_LONG="$TEST_TMPDIR/long.json"
+_LONG=$(printf 'A%.0s' $(seq 1 5000))
+printf '{"ok":true,"result":[{"update_id":9,"message":{"message_id":1,"chat":{"id":5,"type":"private"},"text":"%s"}}]}' \
+    "$_LONG" > "$F_LONG"
+_LONG_OUT=$(_tg_parse_updates_awk "$(cat "$F_LONG")")
+_LONG_PAY=$(printf '%s' "$_LONG_OUT" | cut -f6)
+assert_eq "awk truncates a 5000-char text to 512" 512 "${#_LONG_PAY}"
+
+# ── The python extractor, when a working python3 exists ──────────────────────
+# `command -v python3` is not enough: the Windows Store ships a python3.exe
+# alias that is on PATH but fails the moment it runs, so probe by executing it.
+# Where only `python` exists, stand up a shim so the parity contract below is
+# still exercised instead of quietly skipping the assertions that matter most.
+if ! _tg_have_python && command -v python >/dev/null 2>&1 && python -c '' >/dev/null 2>&1; then
+    _PY_REAL=$(command -v python)
+    mkdir -p "$TEST_TMPDIR/bin"
+    printf '#!/bin/bash\nexec "%s" "$@"\n' "$_PY_REAL" > "$TEST_TMPDIR/bin/python3"
+    chmod +x "$TEST_TMPDIR/bin/python3"
+    PATH="$TEST_TMPDIR/bin:$PATH"
+    printf '  NOTE  python3 shimmed to %s for parity checks\n' "$_PY_REAL"
+fi
+
+if _tg_have_python; then
+    assert_eq "python parses a 3-update batch in order" "$EXPECT_MAIN" "$(_tg_parse_updates_py "$(cat "$F_MAIN")")"
+    assert_eq "python advances past updates with no message" "$EXPECT_BARE" "$(_tg_parse_updates_py "$(cat "$F_BARE")")"
+    assert_eq "python emits nothing for truncated JSON" "" "$(_tg_parse_updates_py "$(cat "$F_TRUNC")")"
+    assert_eq "python keeps only the first line of text" "$EXPECT_MULTILINE" "$(_tg_parse_updates_py "$(cat "$F_MULTILINE")")"
+
+    # The contract that keeps the fallback honest.
+    for _f in "$F_MAIN" "$F_BARE" "$F_TRUNC" "$F_MULTILINE" "$F_LONG"; do
+        assert_eq "extractors agree byte-for-byte on $(basename "$_f")" \
+            "$(_tg_parse_updates_awk "$(cat "$_f")")" "$(_tg_parse_updates_py "$(cat "$_f")")"
+    done
+else
+    printf '  SKIP  python extractor assertions (no working python3)\n'
+fi
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]

From 13f620562ec4d549f5a1daa886a0e743733aea2a Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Thu, 17 Sep 2026 08:35:42 +0300
Subject: [PATCH 03/10] feat(telegram): add interactive inline-keyboard menus
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tapping now navigates: a hub, a paginated user list, a per-user detail card
with its own actions, and a confirmation step before anything destructive.
All navigation state travels in callback_data, so there is no server-side
session store and an old message's buttons keep working.

Security model: callback_data is entirely attacker-controlled — a user can
send any payload they like — so every tap is re-authorised against the same
rules _process_cmd applies. TG_CB_CAPS is the single source of truth for
"what capability does this action need", and BOTH the renderer (which buttons
to show) and the enforcer (whether to act) read it, so the two cannot drift.
A table-driven test fails if it stops matching _process_cmd's gates.

The four refusals mirror _process_cmd exactly: public actions run before any
role check, an unauthenticated chatter is answered but ignored silently, a
recognised-but-underprivileged role is refused loudly and audited, and an
unrecognised role string fails closed to public-only (admins.conf is a plain
file an operator can hand-edit).

Answering the callback is structural rather than a discipline: _cb_dispatch
never answers and _process_callback always does, exactly once, on every path
including denial, a stale menu and an unknown namespace. Without that the
client spins forever.

Also attaches a role-filtered button bar to /start, /mp_status, /mp_secrets,
/mp_traffic and /mp_help. Inline buttons carry their message implicitly via
callback_query.message.message_id, so a reply becomes a live dashboard with
no stored message id.

Fixes a pagination bug found while testing: `local _i _start=$(( page * per ))
_end=$(( _start + per ))` expands _start against the OUTER scope, so _end came
out as per rather than start+per and every page after the first rendered
empty.

tests/test_telegram_reseller_rbac.sh gains stubs for the two new senders and
exposes the menu block, since /start now routes through tg_send_to_kb and
builds its button bar via _tg_button_bar.
---
 mtproxymax.sh                            | 544 ++++++++++++++++++++++-
 tests/test_telegram_callback_dispatch.sh | 263 +++++++++++
 tests/test_telegram_menu_render.sh       | 193 ++++++++
 tests/test_telegram_reseller_rbac.sh     |   8 +
 4 files changed, 994 insertions(+), 14 deletions(-)
 create mode 100644 tests/test_telegram_callback_dispatch.sh
 create mode 100644 tests/test_telegram_menu_render.sh

diff --git a/mtproxymax.sh b/mtproxymax.sh
index 0de9425..3fb7d71 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -11725,7 +11725,7 @@ _cb_enc() {
     [ -n "$act" ]  && out="${out}:${act}"
     [ -n "$tgt" ]  && out="${out}:${tgt}"
     [ -n "$page" ] && out="${out}:${page}"
-    [ "${#out}" -le "$_CB_MAX" ] || return 1
+    [ "${#out}" -le "${_CB_MAX:-64}" ] || return 1
     printf '%s' "$out"
 }
 
@@ -11739,7 +11739,7 @@ _cb_dec() {
     local p="$1"
     _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
     [ -n "$p" ] || return 1
-    [ "${#p}" -le "$_CB_MAX" ] || return 1
+    [ "${#p}" -le "${_CB_MAX:-64}" ] || return 1
     [[ "$p" =~ ^[a-z]{1,2}(:[A-Za-z0-9_-]{1,32}){0,3}$ ]] || return 1
     local IFS=':' _f
     local -a _fields
@@ -12228,7 +12228,8 @@ _process_cmd() {
     # Public user or unauthenticated commands
     case "$text" in
         /start|/start@*)
-            tg_send_to "$chat_id" "🛡️ *Welcome to MTProxyMax Self-Service Portal (${VERSION})*\n\n👋 Hello! You can use this bot to check your proxy status, data limits, and connection links without admin assistance.\n\n📱 *Public Commands Available:*\n  /my_status <label> — Check your data quota & expiration\n  /redeem <code> [label] — Redeem a gift code / voucher\n  /voucher <code> [label] — Alias for /redeem\n  /support <message> — Send a support request to server admins"
+            tg_send_to_kb "$chat_id" "🛡️ *Welcome to MTProxyMax Self-Service Portal (${VERSION})*\n\n👋 Hello! You can use this bot to check your proxy status, data limits, and connection links without admin assistance.\n\n📱 *Public Commands Available:*\n  /my_status <label> — Check your data quota & expiration\n  /redeem <code> [label] — Redeem a gift code / voucher\n  /voucher <code> [label] — Alias for /redeem\n  /support <message> — Send a support request to server admins" \
+                "$(_tg_button_bar "$chat_id")"
             return
             ;;
         /my_status\ *|/my_status@*\ *)
@@ -12353,7 +12354,8 @@ _process_cmd() {
             fi
             local _si _so _sc; read -r _si _so _sc <<< "$(get_stats)"
             local up=$(get_uptime)
-            tg_send "📱 *MTProxy Status*\n\n🟢 Status: Running\n⏱ Uptime: $(format_duration $up)\n👥 Connections: ${_sc}\n📊 Traffic: ↓ $(format_bytes ${_cum_out:-0}) ↑ $(format_bytes ${_cum_in:-0})\n🔗 Port: ${PROXY_PORT} | Domain: ${PROXY_DOMAIN}"
+            tg_send_kb "📱 *MTProxy Status*\n\n🟢 Status: Running\n⏱ Uptime: $(format_duration $up)\n👥 Connections: ${_sc}\n📊 Traffic: ↓ $(format_bytes ${_cum_out:-0}) ↑ $(format_bytes ${_cum_in:-0})\n🔗 Port: ${PROXY_PORT} | Domain: ${PROXY_DOMAIN}" \
+                "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_secrets|/mp_secrets@*)
             load_tg_settings
@@ -12380,7 +12382,7 @@ _process_cmd() {
                 local cui=${_cum_user_in["$label"]:-0} cuo=${_cum_user_out["$label"]:-0}
                 msg+="${icon} *$(_esc "$label")* — ${uc} conn | ↓$(format_bytes $cuo) ↑$(format_bytes $cui)\n"
             done < "$SECRETS_FILE"
-            tg_send "$msg"
+            tg_send_kb "$msg" "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_link|/mp_link@*)
             load_tg_settings
@@ -12513,7 +12515,7 @@ _process_cmd() {
                 local cuo; cuo=$(echo "$cum_u" | awk '{print $2}')
                 msg+="👤 *$(_esc "$label")*: ↓ $(format_bytes $cuo) ↑ $(format_bytes $cui)\n"
             done < "$SECRETS_FILE"
-            tg_send "$msg"
+            tg_send_kb "$msg" "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_update|/mp_update@*)
             [ "$role" != "superadmin" ] && { tg_send "⛔ Permission denied: superadmin required."; return; }
@@ -12650,20 +12652,534 @@ _process_cmd() {
             tg_send "📢 Broadcast dispatched to all users."
             ;;
         /mp_help|/mp_help@*)
-            tg_send "📋 *MTProxyMax Commands (${VERSION})*\n\n*Public Self-Service:*\n/start — Self-service onboarding\n/my\_status <label> — Check data quota & expiry\n/voucher <code> — Redeem voucher code\n/support <msg> — Send ticket to helpdesk\n\n*Admin Control Plane:*\n/mp\_fleet — Global Federation Fleet Dashboard\n/mp\_voucher create <cnt> <qta> <dys> — Generate vouchers\n/mp\_voucher list — List vouchers\n/mp\_status — Proxy status\n/mp\_secrets — List secrets\n/mp\_link — Get proxy links + QR\n/mp\_add <label> — Add secret\n/mp\_remove / /mp\_revoke <label> — Remove secret\n/mp\_rotate <label> — Rotate secret\n/mp\_enable <label> — Enable secret\n/mp\_disable <label> — Disable secret\n/mp\_limits — Show user limits\n/mp\_setlimit — Set user limits\n/mp\_upstreams — List upstreams\n/mp\_traffic — Traffic report\n/mp\_health — Health check\n/mp\_lockdown [on|off] — Emergency shield\n/mp\_digest — System digest report\n/mp\_broadcast <msg> — Broadcast to all users\n/reply <chat\_id> <msg> — Reply to support ticket\n/mp\_restart — Restart proxy\n/mp\_update — Check for updates\n/mp\_help — This help"
+            tg_send_kb "📋 *MTProxyMax Commands (${VERSION})*\n\n*Public Self-Service:*\n/start — Self-service onboarding\n/my\_status <label> — Check data quota & expiry\n/voucher <code> — Redeem voucher code\n/support <msg> — Send ticket to helpdesk\n\n*Admin Control Plane:*\n/mp\_fleet — Global Federation Fleet Dashboard\n/mp\_voucher create <cnt> <qta> <dys> — Generate vouchers\n/mp\_voucher list — List vouchers\n/mp\_status — Proxy status\n/mp\_secrets — List secrets\n/mp\_link — Get proxy links + QR\n/mp\_add <label> — Add secret\n/mp\_remove / /mp\_revoke <label> — Remove secret\n/mp\_rotate <label> — Rotate secret\n/mp\_enable <label> — Enable secret\n/mp\_disable <label> — Disable secret\n/mp\_limits — Show user limits\n/mp\_setlimit — Set user limits\n/mp\_upstreams — List upstreams\n/mp\_traffic — Traffic report\n/mp\_health — Health check\n/mp\_lockdown [on|off] — Emergency shield\n/mp\_digest — System digest report\n/mp\_broadcast <msg> — Broadcast to all users\n/reply <chat\_id> <msg> — Reply to support ticket\n/mp\_restart — Restart proxy\n/mp\_update — Check for updates\n/mp\_help — This help" "$(_tg_button_bar "$chat_id")"
             ;;
     esac
 }
 
-# Callback-query entry point. The interactive menus land here in the next
-# change; for now it exists so that _consume_updates honours the offset
-# contract and an unexpected tap is acknowledged rather than leaving the
-# client spinning forever.
+# >>> TG_MENU_BEGIN
+# ── Interactive inline-keyboard menus ───────────────────────────────────────
+#
+# The security model: callback_data is entirely attacker-controlled — a user
+# can send any payload they like — so every tap is re-authorised here against
+# the same rules _process_cmd applies. A button must never grant more than
+# typing the equivalent command would.
+#
+# TG_CB_CAPS is the single source of truth for "what capability does this
+# action need". BOTH the renderer (to decide which buttons to show) and the
+# enforcer (to decide whether to act) read it, so the two cannot drift apart.
+# The same property is pinned by tests/test_telegram_callback_dispatch.sh,
+# which fails if this table stops matching _process_cmd's gates.
+#
+# Capabilities, weakest first: public < reseller < admin < superadmin.
+TG_CB_CAPS="n=public
+m=public
+m:h=public
+u:l=admin
+u:s=admin
+t=admin
+t:w=admin
+t:u=admin
+y=admin
+y:e=admin
+s=admin
+a:enable=admin
+a:disable=admin
+a:rotate=admin
+c:enable=admin
+c:disable=admin
+c:rotate=admin
+a:remove=superadmin
+c:remove=superadmin"
+
+_tg_cap_rank() {
+    case "$1" in
+        public)     echo 0 ;;
+        reseller)   echo 1 ;;
+        admin)      echo 2 ;;
+        superadmin) echo 3 ;;
+        *)          echo -1 ;;
+    esac
+}
+
+# An unrecognised role string ranks as public-only and is refused LOUDLY,
+# whereas the literal role "none" is refused silently — mirroring _process_cmd,
+# where an unknown auth level is denied and audited but an unauthenticated
+# chatter is simply ignored. admins.conf is hand-editable, so anything that is
+# not exactly superadmin or reseller must never exceed public.
+_tg_role_rank() {
+    case "$1" in
+        superadmin) echo 3 ;;
+        reseller)   echo 1 ;;
+        *)          echo 0 ;;
+    esac
+}
+
+# Capability for a namespace, preferring the ns:action entry over the bare ns.
+_tg_cap_for() {
+    local ns="$1" act="${2:-}"
+    local k v found=""
+    while IFS='=' read -r k v; do
+        [ -z "$k" ] && continue
+        if [ -n "$act" ] && [ "$k" = "${ns}:${act}" ]; then printf '%s' "$v"; return 0; fi
+        [ "$k" = "$ns" ] && found="$v"
+    done <<< "$TG_CB_CAPS"
+    printf '%s' "$found"
+}
+
+# 0 if the role currently rendering (_UI_ROLE) may use this action.
+_cb_can() {
+    local cap need have
+    cap=$(_tg_cap_for "$1" "${2:-}")
+    [ -n "$cap" ] || return 1
+    need=$(_tg_cap_rank "$cap")
+    have=$(_tg_role_rank "${_UI_ROLE:-none}")
+    [ "$need" -ge 0 ] || return 1
+    [ "$have" -ge "$need" ]
+}
+
+# ── Rendering helpers ───────────────────────────────────────────────────────
+_tg_json_esc() {
+    local t="$1"
+    t="${t//\\/\\\\}"
+    t="${t//\"/\\\"}"
+    printf '%s' "$t"
+}
+
+_TG_KB=""
+_kb_reset() { _TG_KB=""; }
+# _kb_row "Label|payload" "Label|payload" ... — rows with no usable button are
+# dropped, which keeps a viewer without permission from seeing an empty row.
+_kb_row() {
+    local spec lbl data out="" first=1
+    for spec in "$@"; do
+        lbl="${spec%%|*}"; data="${spec#*|}"
+        [ -z "$data" ] && continue
+        [ "$first" -eq 1 ] || out="${out},"
+        first=0
+        out="${out}{\"text\":\"$(_tg_json_esc "$lbl")\",\"callback_data\":\"$(_tg_json_esc "$data")\"}"
+    done
+    [ -z "$out" ] && return 0
+    [ -n "$_TG_KB" ] && _TG_KB="${_TG_KB},"
+    _TG_KB="${_TG_KB}[${out}]"
+}
+_kb_json() { [ -n "$_TG_KB" ] && printf '{"inline_keyboard":[%s]}' "$_TG_KB"; }
+
+# Replace the message the button lived on. Both _CB_CHAT and _CB_MID come from
+# the callback itself, which Telegram authenticates, so no chat id ever has to
+# travel inside callback_data where a user could forge it.
+_cb_edit() {
+    local text="$1" kb="${2:-}"
+    tg_edit "$_CB_CHAT" "$_CB_MID" "$(printf '%b' "$text")" "$kb"
+}
+_cb_edit_markup() {
+    local kb="$1"
+    tg_edit_markup "$_CB_CHAT" "$_CB_MID" "$kb"
+}
+
+_tg_metrics_raw() {
+    curl -s --max-time 2 "http://127.0.0.1:${PROXY_METRICS_PORT:-9090}/metrics" 2>/dev/null
+}
+
+# Per-user live metrics in ONE awk pass: "label|conns|ips" per line. Forking
+# per user would make a 50-user menu unusably slow.
+_cb_user_metrics() {
+    local _m; _m=$(_tg_metrics_raw)
+    [ -z "$_m" ] && return 0
+    printf '%s' "$_m" | awk '
+        function lbl(s, k,   p, q) { p=index(s,k"=\""); if(!p) return ""; s=substr(s,p+length(k)+2); q=index(s,"\""); return q ? substr(s,1,q-1) : "" }
+        /^telemt_user_connections_current\{/ { u=lbl($0,"user"); if(u) c[u]+=$NF }
+        /^telemt_user_unique_ips_current\{/  { u=lbl($0,"user"); if(u) i[u]+=$NF }
+        END { for(u in c) printf "%s|%.0f|%.0f\n", u, c[u]+0, i[u]+0 }
+    '
+}
+
+_cb_secret_exists() {
+    [ -n "$1" ] && _cb_label_ok "$1" && [ -f "$SECRETS_FILE" ] && \
+        grep -qE "^$1\|" "$SECRETS_FILE" 2>/dev/null
+}
+
+# ── Views ───────────────────────────────────────────────────────────────────
+_cb_render_hub() {
+    local _up _msg
+    _up=$(get_uptime)
+    _msg="🛡️ *MTProxyMax* — $(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")"
+    _msg+="\n\n🟢 Running · ⏱ $(format_duration "${_up:-0}")"
+    _msg+="\n👥 $(get_active_connections) live connections"
+    _msg+="\n\nChoose a view:"
+    _kb_reset
+    local u_row="" t_row="" y_row=""
+    _cb_can u l && u_row="👥 Users|u:l:0"
+    _cb_can t && t_row="📈 Traffic|t"
+    _cb_can y && y_row="🩺 Health|y"
+    _kb_row "$u_row" "$t_row"
+    _kb_row "$y_row" "$(_cb_can s && printf '⚙️ Settings|s')"
+    _kb_row "❓ Help|m:h"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_help() {
+    local _msg="📋 *Commands*\n\n"
+    _msg+="/mp\\_status — proxy status\n"
+    _msg+="/mp\\_secrets — list secrets\n"
+    _msg+="/mp\\_traffic — traffic report\n"
+    _msg+="/mp\\_add <label> — add a secret\n"
+    _msg+="/mp\\_remove <label> — remove a secret\n"
+    _msg+="/mp\\_help — full list\n\n"
+    _msg+="The buttons below are the same thing, minus the typing."
+    _kb_reset
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_user_list() {
+    local page="${1:-0}" note="${2:-}"
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+    [ -f "$SECRETS_FILE" ] || { _cb_edit "📋 No secrets configured." ""; return 0; }
+
+    local -a _labels=() _enabled=()
+    local label secret created enabled rest
+    while IFS='|' read -r label secret created enabled rest || [ -n "$label" ]; do
+        [[ "$label" =~ ^# ]] && continue
+        _cb_label_ok "$label" || continue
+        _labels+=("$label"); _enabled+=("$enabled")
+    done < "$SECRETS_FILE"
+
+    local _total=${#_labels[@]}
+    local per=6
+    local _pages=$(( (_total + per - 1) / per ))
+    [ "$_pages" -lt 1 ] && _pages=1
+    [ "$page" -ge "$_pages" ] && page=$(( _pages - 1 ))
+
+    declare -A _conns=()
+    while IFS='|' read -r _l _c _i; do
+        [ -n "$_l" ] && _conns["$_l"]="${_c:-0}"
+    done < <(_cb_user_metrics)
+
+    local _msg="${note:+${note}\n\n}"
+    _msg+="👥 *Users* — ${_total} total"
+    # Declared separately on purpose: inside a single `local a=6 b=$((a+6))`
+    # bash expands $a against the OUTER scope, so _end silently came out as
+    # per rather than start+per and every page after the first rendered empty.
+    local _i _start _end
+    _start=$(( page * per ))
+    _end=$(( _start + per ))
+    [ "$_end" -gt "$_total" ] && _end=$_total
+    _kb_reset
+    for (( _i = _start; _i < _end; _i++ )); do
+        local _lbl="${_labels[$_i]}" _icon="🟢"
+        [ "${_enabled[$_i]}" != "true" ] && _icon="🔴"
+        local _btn="${_icon} ${_lbl}"
+        [ "${#_btn}" -gt 34 ] && _btn="${_btn:0:34}"
+        _kb_row "${_btn}|u:s:${_lbl}:${page}"
+    done
+    local _prev="" _next=""
+    [ "$page" -gt 0 ] && _prev="◀ Prev|u:l:$(( page - 1 ))"
+    [ "$_end" -lt "$_total" ] && _next="Next ▶|u:l:$(( page + 1 ))"
+    _kb_row "$_prev" "$(( page + 1 ))/${_pages}|n" "$_next"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_bar() {
+    local pct="${1:-0}"
+    [[ "$pct" =~ ^-?[0-9]+$ ]] || pct=0
+    [ "$pct" -lt 0 ] && pct=0
+    [ "$pct" -gt 100 ] && pct=100
+    local _f=$(( pct / 10 )) _e=$(( 10 - pct / 10 ))
+    local _s="" _i
+    for (( _i = 0; _i < _f; _i++ )); do _s+="▓"; done
+    for (( _i = 0; _i < _e; _i++ )); do _s+="░"; done
+    printf '%s' "$_s"
+}
+
+_cb_render_user_detail() {
+    local label="$1" page="${2:-0}" note="${3:-}"
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _line _l _s _created _en _mc _mi _q _ex _notes _adtag
+    _line=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1)
+    IFS='|' read -r _l _s _created _en _mc _mi _q _ex _notes _adtag <<< "$_line"
+
+    local _conns=0 _ips=0
+    while IFS='|' read -r _ml _mc2 _mi2; do
+        [ "$_ml" = "$label" ] && { _conns="${_mc2:-0}"; _ips="${_mi2:-0}"; }
+    done < <(_cb_user_metrics)
+
+    local _in="${_cum_user_in[$label]:-0}" _out="${_cum_user_out[$label]:-0}"
+    local _total=$(( _in + _out ))
+    local _icon="🟢 active" ; [ "$_en" != "true" ] && _icon="🔴 disabled"
+
+    local _msg="${note:+${note}\n\n}"
+    _msg+="👤 *$(_esc "$label")*\n"
+    _msg+="🔌 ${_icon} · 📡 ${_conns} conn / ${_ips} IP\n"
+    _msg+="📊 since reset: ↓ $(format_bytes "$_out") ↑ $(format_bytes "$_in")\n"
+    if [ -n "$_q" ] && [ "$_q" -gt 0 ] 2>/dev/null; then
+        local _pct=$(( (_total * 100) / _q ))
+        [ "$_pct" -gt 100 ] && _pct=100
+        _msg+="🧮 quota $(_cb_bar "$_pct") ${_pct}% of $(format_bytes "$_q")\n"
+    else
+        _msg+="🧮 quota unlimited\n"
+    fi
+    if [ -n "$_ex" ] && [ "$_ex" != "0" ] && [ "$_ex" != "" ]; then
+        local _exp_e _days
+        _exp_e=$(_iso_to_epoch "$_ex")
+        if [ "${_exp_e:-0}" -gt 0 ] 2>/dev/null; then
+            _days=$(( (_exp_e - $(date +%s)) / 86400 ))
+            if [ "$_days" -lt 0 ]; then _msg+="⏳ expired on ${_ex}\n"
+            else _msg+="⏳ expires in ${_days}d (${_ex})\n"; fi
+        fi
+    else
+        _msg+="⏳ no expiry\n"
+    fi
+
+    _kb_reset
+    _kb_row "🔄 Refresh|u:s:${label}:${page}" "🔗 Link|u:k:${label}"
+    if [ "$_en" = "true" ]; then
+        _cb_can a disable && _kb_row "⏸ Disable|a:disable:${label}" "$(_cb_can a rotate && printf '♻️ Rotate|a:rotate:%s' "$label")"
+    else
+        _cb_can a enable && _kb_row "▶️ Enable|a:enable:${label}"
+    fi
+    _cb_can a remove && _kb_row "🗑 Remove|a:remove:${label}"
+    _kb_row "◀ Back|u:l:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_confirm() {
+    local verb="$1" label="$2" page="${3:-0}" pretty=""
+    case "$verb" in
+        enable)  pretty="Enable" ;;
+        disable) pretty="Disable" ;;
+        rotate)  pretty="Rotate" ;;
+        remove)  pretty="Remove" ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+
+    local _extra=""
+    case "$verb" in
+        disable)
+            local _c=0
+            while IFS='|' read -r _ml _mc2 _mi2; do
+                [ "$_ml" = "$label" ] && _c="${_mc2:-0}"
+            done < <(_cb_user_metrics)
+            [ "${_c:-0}" -gt 0 ] && _extra="\n\nThis immediately disconnects *${_c}* active session(s)."
+            ;;
+        remove) _extra="\n\nThe key stops working immediately and cannot be restored." ;;
+        rotate) _extra="\n\nEvery client using this key must reconnect." ;;
+    esac
+    local _msg="⚠️ *${pretty} $(_esc "$label")?*${_extra}"
+    _kb_reset
+    _kb_row "✅ Yes, ${pretty,,}|c:${verb}:${label}" "❌ Cancel|u:s:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Only the c: namespace mutates anything. a: just renders a confirmation, so a
+# destructive action is never one mis-tap away.
+_cb_exec_action() {
+    local verb="$1" label="$2" page="${3:-0}" out=""
+    case "$verb" in
+        enable|disable|rotate|remove) ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    if [ "$verb" = "remove" ]; then
+        if out=$("${INSTALL_DIR}/mtproxymax" secret remove "$label" 2>&1); then
+            _CB_TOAST="Removed"
+            _cb_render_user_list "$page" "🗑 Removed *$(_esc "$label")*"
+        else
+            _CB_TOAST="Failed"
+            _cb_render_user_detail "$label" "$page" "❌ Could not remove *$(_esc "$label")*"
+        fi
+        return 0
+    fi
+
+    if out=$("${INSTALL_DIR}/mtproxymax" secret "$verb" "$label" 2>&1); then
+        _CB_TOAST="Done"
+    else
+        _CB_TOAST="Failed"
+    fi
+    _cb_render_user_detail "$label" "$page"
+}
+
+_cb_render_traffic() {
+    local win="${1:-24h}"
+    [ -z "$win" ] && win="24h"
+    local _msg="📈 *Traffic*\n\n"
+    _msg+="Lifetime: ↓ $(format_bytes "${_cum_out:-0}") ↑ $(format_bytes "${_cum_in:-0}")\n"
+    _msg+="👥 $(get_active_connections) live connections\n\n"
+    _msg+="*Per user (since reset)*\n"
+    local label secret created enabled rest _rows=""
+    if [ -f "$SECRETS_FILE" ]; then
+        while IFS='|' read -r label secret created enabled rest || [ -n "$label" ]; do
+            [[ "$label" =~ ^# ]] && continue
+            _cb_label_ok "$label" || continue
+            [ "$enabled" != "true" ] && continue
+            _rows+="$(printf '%s\n' "$(( ${_cum_user_in[$label]:-0} + ${_cum_user_out[$label]:-0} ))|$label")"$'\n'
+        done < "$SECRETS_FILE"
+    fi
+    if [ -n "$_rows" ]; then
+        while IFS='|' read -r _b _l; do
+            [ -z "$_l" ] && continue
+            _msg+="👤 $(_esc "$_l"): ↓ $(format_bytes "${_cum_user_out[$_l]:-0}") ↑ $(format_bytes "${_cum_user_in[$_l]:-0}")\n"
+        done < <(printf '%s' "$_rows" | sort -t'|' -k1 -rn | head -8)
+    else
+        _msg+="No active users.\n"
+    fi
+    _kb_reset
+    _kb_row "🔄 Refresh|t" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_engine() {
+    local _m _msg
+    _m=$(_tg_metrics_raw)
+    _msg="🩺 *Engine*\n\n"
+    if [ -z "$_m" ]; then
+        _msg+="Metrics unavailable.\n"
+    else
+        _msg+=$(printf '%s' "$_m" | awk '
+            function v(n,   i) { return (n in m) ? m[n] : 0 }
+            /^telemt_uptime_seconds /        { m["up"]=$NF }
+            /^telemt_connections_total /     { m["tot"]=$NF }
+            /^telemt_connections_bad_total / { m["bad"]=$NF }
+            /^telemt_connections_current /   { m["cur"]=$NF }
+            /^telemt_upstream_connect_success_total / { m["oks"]=$NF }
+            /^telemt_upstream_connect_fail_total /    { m["fai"]=$NF }
+            END {
+                bad = (v("tot") > 0) ? (v("bad") * 100.0 / v("tot")) : 0
+                att = v("oks") + v("fai")
+                ok  = (att > 0) ? (v("oks") * 100.0 / att) : 100
+                printf "👥 live %d · total %d\n", v("cur"), v("tot")
+                printf "⚠️ bad handshakes %.1f%%\n", bad
+                printf "🔗 upstream success %.1f%%\n", ok
+            }')
+        _msg+=$'\n'
+    fi
+    _kb_reset
+    _kb_row "🔄 Refresh|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_settings() {
+    local _msg="⚙️ *Settings*\n\n"
+    _msg+="🔌 Port: \`${PROXY_PORT:-?}\`\n"
+    _msg+="🌐 Domain: \`$(_esc "${PROXY_DOMAIN:-?}")\`\n"
+    _msg+="📊 Metrics port: \`${PROXY_METRICS_PORT:-?}\`\n"
+    _msg+="⏱ Report interval: ${TELEGRAM_INTERVAL:-6}h\n"
+    _kb_reset
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Send the connect link and QR as a NEW message rather than editing: an inline
+# keyboard cannot carry a photo, so the QR has to go out separately.
+_cb_send_link() {
+    local label="$1"
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    local _secret _ip _dh _fs
+    _secret=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1 | cut -d'|' -f2)
+    _ip=$(get_cached_ip)
+    [ -z "$_ip" ] && { _CB_TOAST="Cannot detect the server IP"; return 1; }
+    if [ "${MASKING_ENABLED:-true}" != "false" ]; then
+        _dh=$(domain_to_hex "${PROXY_DOMAIN:-cloudflare.com}")
+        _fs="ee${_secret}${_dh}"
+    else
+        _fs="dd${_secret}"
+    fi
+    _CB_TOAST="Link sent"
+    send_proxy_qr_to "$_CB_CHAT" "$_ip" "${PROXY_PORT}" "$_fs"
+}
+
+# The standard button bar attached to ordinary command replies. Inline buttons
+# carry their message implicitly via callback_query.message.message_id, so a
+# reply becomes a live dashboard with no stored message id and no session
+# state. Filtered by the requesting chat's role, so a reply never advertises a
+# button its reader cannot use.
+_tg_button_bar() {
+    local chat="$1"
+    _UI_ROLE="$(_check_tg_role "$chat")"
+    _kb_reset
+    _kb_row "$(_cb_can u l && printf '👥 Users|u:l:0')" "$(_cb_can t && printf '📈 Traffic|t')"
+    _kb_row "$(_cb_can y && printf '🩺 Health|y')" "🏠 Menu|m"
+    _kb_json
+}
+
+# ── Dispatch ────────────────────────────────────────────────────────────────
+_cb_dispatch() {
+    local role cap need have
+    if ! _cb_dec "$_CB_DATA"; then
+        _CB_TOAST="This menu is out of date — send /menu"
+        return 1
+    fi
+    load_tg_settings
+    role=$(_check_tg_role "$_CB_CHAT")
+    _UI_ROLE="$role"
+
+    # Track the chatter so /mp_broadcast reaches button-only users too.
+    if [ -n "$_CB_CHAT" ]; then
+        mkdir -p "$INSTALL_DIR" 2>/dev/null || true
+        grep -q "^${_CB_CHAT}$" "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || \
+            echo "$_CB_CHAT" >> "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || true
+    fi
+
+    cap=$(_tg_cap_for "$_CB_NS" "$_CB_ACT")
+    if [ -z "$cap" ]; then
+        _CB_TOAST="This menu is out of date — send /menu"
+        return 1
+    fi
+    need=$(_tg_cap_rank "$cap")
+    have=$(_tg_role_rank "$role")
+    if [ "$have" -lt "$need" ]; then
+        if [ "$role" = "none" ]; then
+            # Unauthenticated: answer, change nothing, log nothing — the same
+            # silent refusal _process_cmd gives.
+            _CB_TOAST=""
+            return 1
+        fi
+        _tg_security_log "$_CB_CHAT" "callback ${_CB_NS}:${_CB_ACT}${_CB_TGT:+:}${_CB_TGT}"
+        _CB_TOAST="Permission denied"
+        _CB_ALERT="true"
+        return 1
+    fi
+
+    case "$_CB_NS" in
+        n) : ;;   # page indicator: acknowledge, leave the message alone
+        m)
+            if [ "$_CB_ACT" = "h" ]; then _cb_render_help; else _cb_render_hub; fi
+            ;;
+        u)
+            case "$_CB_ACT" in
+                l) _cb_render_user_list "${_CB_TGT:-0}" ;;
+                s) _cb_render_user_detail "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                k) _cb_send_link "$_CB_TGT" ;;
+                *) _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        a) _cb_render_confirm "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+        c) _cb_exec_action "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+        t) _cb_render_traffic "${_CB_TGT:-24h}" ;;
+        y) _cb_render_engine ;;
+        s) _cb_render_settings ;;
+        *) _CB_TOAST="This menu is out of date — send /menu" ;;
+    esac
+    return 0
+}
+
+# Callback-query entry point. Bash has no `finally`, so answering is made
+# structural rather than a discipline: _cb_dispatch never answers, and the
+# exactly-one answer below runs on every path — including denial, a stale
+# menu, and an unknown namespace. Without it the client spins forever.
 _process_callback() {
-    local chat_id="$1" message_id="$2" callback_id="$3" payload="$4"
-    : "$chat_id" "$message_id" "$payload"
-    tg_answer_cb "$callback_id" "" "false"
+    _CB_CHAT="$1"; _CB_MID="$2"; _CB_ID="$3"; _CB_DATA="$4"
+    _CB_TOAST=""; _CB_ALERT="false"
+    _cb_dispatch || true
+    tg_answer_cb "$_CB_ID" "$_CB_TOAST" "$_CB_ALERT"
 }
+# <<< TG_MENU_END
 
 # Cleanup trap for temp files
 trap _cleanup EXIT
diff --git a/tests/test_telegram_callback_dispatch.sh b/tests/test_telegram_callback_dispatch.sh
new file mode 100644
index 0000000..8988df9
--- /dev/null
+++ b/tests/test_telegram_callback_dispatch.sh
@@ -0,0 +1,263 @@
+#!/bin/bash
+# Tests for the inline-keyboard callback dispatcher.
+#
+# The security property under test is that a button must never grant more than
+# typing the equivalent command would. _process_cmd is the reference: public
+# commands run before any role check, an unauthenticated chatter is ignored
+# SILENTLY, a recognised-but-underprivileged role is refused loudly, and an
+# unrecognised role string (admins.conf is hand-editable) fails closed.
+#
+# The dispatcher must reproduce all four behaviours, because callback_data is
+# entirely attacker-controlled — a user can send any payload they like.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|0|0|0|0||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+printf 'bob|%s|1700000000|false|0|0|0|0||\n' "$(printf 'b%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"
+    fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+
+# ── Extract the shipped dispatcher ───────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+# NOTE: _check_tg_role is deliberately NOT extracted. Role resolution is
+# exercised elsewhere; here it is stubbed, and extracting the real one would
+# silently clobber that stub and make every role resolve to "none".
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+# The menu block is delimited by markers so the test exercises exactly what
+# ships rather than a copy that can silently drift.
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "dispatcher extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_eq "menu block was found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_MENU_BEGIN$' "$FNS")"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+ANSWERS="$TEST_TMPDIR/answers.log"
+EDITS="$TEST_TMPDIR/edits.log"
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+ROLE_TO_RETURN="superadmin"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_answer_cb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$ANSWERS"; }
+# $4 is the keyboard markup — the assertions about which buttons a view offers
+# read it, so it must be captured alongside the body.
+tg_edit() { printf 'edit|%s|%s|%s|%s\n' "$1" "$2" "$3" "$4" >> "$EDITS"; }
+tg_edit_markup() { printf 'markup|%s|%s|%s\n' "$1" "$2" "$3" >> "$EDITS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+run_cb() {   # run_cb <role> <chat> <payload>
+    : > "$ANSWERS"; : > "$EDITS"; : > "$SENDS"; : > "$CALLS"
+    ROLE_TO_RETURN="$1"
+    _process_callback "$2" 77 "cb-1" "$3" 2>/dev/null
+}
+audit_now() { cat "$AUDIT_LOG" 2>/dev/null || printf ''; }
+reset_audit() { : > "$AUDIT_LOG"; }
+
+echo "Telegram callback dispatcher tests"
+
+# ── Every path answers the callback exactly once ─────────────────────────────
+# Without this the client spins forever, so it must hold on denial, error and
+# stale-menu paths too — not just the happy path.
+for _case in "superadmin:111:m" "reseller:333:m" "none:999:m" \
+             "operator:444:m" "superadmin:111:a:disable:alice" \
+             "reseller:333:a:disable:alice" "superadmin:111:u:s:ghost:0" \
+             "superadmin:111:not-a-real-payload" "superadmin:111:zz"; do
+    _r="${_case%%:*}"; _p="${_case#*:}"; _c="${_p%%:*}"; _data="${_p#*:}"
+    run_cb "$_r" "$_c" "$_data"
+    assert_eq "answers exactly once (role=$_r data=$_data)" 1 "$(wc -l < "$ANSWERS" | tr -d ' ')"
+done
+
+# ── A reseller cannot drive the control plane from a button ──────────────────
+reset_audit
+run_cb reseller 333 "a:disable:alice"
+assert_eq "reseller button cannot disable a secret" "" "$(cat "$CALLS")"
+assert_contains "reseller button denial is toasted" "Permission denied" "$(cat "$ANSWERS")"
+assert_contains "reseller button denial is logged" "SECURITY" "$(audit_now)"
+assert_contains "log records the offending chat" "333" "$(audit_now)"
+assert_contains "log records the payload" "a:disable:alice" "$(audit_now)"
+assert_eq "reseller button denial does not edit the message" "" "$(cat "$EDITS")"
+
+reset_audit
+run_cb reseller 333 "u:s:alice:0"
+assert_contains "reseller cannot open a user detail card" "Permission denied" "$(cat "$ANSWERS")"
+assert_contains "user-list denial is logged" "SECURITY" "$(audit_now)"
+assert_eq "user-list denial does not edit" "" "$(cat "$EDITS")"
+
+reset_audit
+run_cb reseller 333 "c:remove:alice"
+assert_contains "reseller cannot confirm a removal" "Permission denied" "$(cat "$ANSWERS")"
+assert_eq "reseller confirmed removal never runs" "" "$(cat "$CALLS")"
+
+# ── The rendered hub must not advertise what the role cannot do ──────────────
+reset_audit
+run_cb reseller 333 "m"
+_hub_reseller="$(cat "$EDITS")"
+assert_not_contains "reseller hub hides the user list" "u:l" "$_hub_reseller"
+assert_not_contains "reseller hub hides disable"     "a:disable" "$_hub_reseller"
+assert_not_contains "reseller hub hides removal"     "a:remove" "$_hub_reseller"
+assert_not_contains "reseller hub hides lockdown"    "lockdown" "$_hub_reseller"
+
+run_cb superadmin 111 "m"
+_hub_super="$(cat "$EDITS")"
+assert_contains "superadmin hub offers the user list" "u:l" "$_hub_super"
+
+# ── An unauthenticated chatter is answered but ignored silently ──────────────
+# This mirrors _process_cmd, where role "none" returns before any reply and
+# before any audit entry.
+reset_audit
+run_cb none 999 "a:disable:alice"
+assert_eq "unauthenticated callback runs nothing" "" "$(cat "$CALLS")"
+assert_eq "unauthenticated callback is not logged" "" "$(audit_now)"
+assert_eq "unauthenticated callback does not edit" "" "$(cat "$EDITS")"
+assert_eq "unauthenticated callback is still answered" 1 "$(wc -l < "$ANSWERS" | tr -d ' ')"
+
+# ── Unrecognised roles fail closed ───────────────────────────────────────────
+for _role in operator administrator root SUPERADMIN superadmin2; do
+    reset_audit
+    run_cb "$_role" 444 "a:disable:alice"
+    assert_eq "role '$_role' cannot disable a secret" "" "$(cat "$CALLS")"
+    assert_contains "role '$_role' is refused" "Permission denied" "$(cat "$ANSWERS")"
+    assert_contains "role '$_role' refusal is logged" "SECURITY" "$(audit_now)"
+done
+
+# ── Destructive actions require an explicit confirmation ─────────────────────
+# A destructive button must never be one tap away: the a: namespace only
+# renders a confirmation, and only c: executes.
+reset_audit
+run_cb superadmin 111 "a:disable:alice"
+assert_eq "action request does not mutate anything" "" "$(cat "$CALLS")"
+assert_contains "action request renders a confirmation" "c:disable:alice" "$(cat "$EDITS")"
+assert_contains "confirmation names the target" "alice" "$(cat "$EDITS")"
+
+run_cb superadmin 111 "c:disable:alice"
+assert_contains "confirmed action reaches the manager" "secret disable alice" "$(cat "$CALLS")"
+assert_eq "confirmed action runs exactly once" 1 "$(grep -c 'secret disable' "$CALLS")"
+
+run_cb superadmin 111 "c:enable:alice"
+assert_contains "confirmed enable reaches the manager" "secret enable alice" "$(cat "$CALLS")"
+
+run_cb superadmin 111 "c:rotate:alice"
+assert_contains "confirmed rotate reaches the manager" "secret rotate alice" "$(cat "$CALLS")"
+
+run_cb superadmin 111 "c:remove:alice"
+assert_contains "confirmed remove reaches the manager" "secret remove alice" "$(cat "$CALLS")"
+
+# ── A stale label must not reach the manager ─────────────────────────────────
+# secrets.conf is editable and a menu can outlive the secret it names.
+reset_audit
+run_cb superadmin 111 "c:disable:ghost"
+assert_eq "confirmed action on an unknown label runs nothing" "" "$(cat "$CALLS")"
+assert_contains "unknown label is reported" "not found" "$(cat "$ANSWERS")"
+
+reset_audit
+run_cb superadmin 111 "u:s:ghost:0"
+assert_eq "detail card for an unknown label runs nothing" "" "$(cat "$CALLS")"
+assert_contains "unknown label detail card is answered with a toast" "not found" "$(cat "$ANSWERS")"
+
+# ── An injected payload is inert ─────────────────────────────────────────────
+reset_audit
+run_cb superadmin 111 'a:disable:$(id)'
+assert_eq "injected payload runs nothing" "" "$(cat "$CALLS")"
+assert_eq "injected payload is answered" 1 "$(wc -l < "$ANSWERS" | tr -d ' ')"
+
+# ── Capability parity with _process_cmd ──────────────────────────────────────
+# The table both the renderer and the enforcer read must not drift from the
+# gates _process_cmd applies, or a button becomes a privilege-escalation path.
+cap_leaks() {
+    local line key cap _ns _rest
+    while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        key="${line%%=*}"; cap="${line#*=}"
+        case "$key" in
+            # Destructive verbs must be superadmin because _process_cmd
+            # re-checks superadmin inside /mp_remove.
+            a:remove|c:remove)
+                [ "$cap" = "superadmin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            a:enable|a:disable|a:rotate|c:enable|c:disable|c:rotate|u:l|u:s|t|t:w|t:u|y|y:e|s)
+                [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            n|m|m:h)
+                [ "$cap" = "public" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            *)
+                printf 'unclassified:%s\n' "$key" ;;
+        esac
+    done <<< "$TG_CB_CAPS"
+}
+assert_eq "capability table matches _process_cmd's gates" "" "$(cap_leaks)"
+
+# Every namespace the renderers can emit must have a capability, or the
+# dispatcher would fail open on an unclassified action.
+assert_contains "capability table covers a:disable" "a:disable=admin" "$TG_CB_CAPS"
+assert_contains "capability table covers c:remove"  "c:remove=superadmin" "$TG_CB_CAPS"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_menu_render.sh b/tests/test_telegram_menu_render.sh
new file mode 100644
index 0000000..0c00c49
--- /dev/null
+++ b/tests/test_telegram_menu_render.sh
@@ -0,0 +1,193 @@
+#!/bin/bash
+# Tests for inline-keyboard rendering: shape, payload bounds, and pagination.
+#
+# The Bot API validates reply_markup as a whole, so one bad button loses the
+# entire keyboard — and one malformed JSON string loses the whole message.
+# These tests check every view a role can reach, across all roles.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+# 13 users: enough to force three pages at a page size of six.
+: > "$SECRETS_FILE"
+for _i in $(seq 1 13); do
+    _state="true"; [ $(( _i % 3 )) -eq 0 ] && _state="false"
+    printf 'user%02d|%s|1700000000|%s|0|0|0|0||\n' "$_i" "$(printf '%032d' "$_i")" "$_state" >> "$SECRETS_FILE"
+done
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_ok() {
+    local name="$1" cond="$2"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$cond" -eq 0 ] 2>/dev/null; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s\n' "$name"; fi
+}
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "menu render extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+ROLE_TO_RETURN="superadmin"
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+EDIT="$TEST_TMPDIR/edit.txt"
+tg_edit() { printf '%s\n%s' "$3" "$4" > "$EDIT"; }
+tg_edit_markup() { printf '%s' "$3" > "$EDIT"; }
+tg_answer_cb() { :; }
+tg_send_to() { :; }
+tg_send() { :; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+source "$FNS"
+_CB_CHAT=111; _CB_MID=77
+
+# Render one view and echo "<text>\n<markup>".
+render() {
+    _UI_ROLE="$1"; _CB_ROLE="$1"
+    _CB_NS=""; _CB_ACT=""; _CB_TGT=""; _CB_PAGE=""
+    case "$2" in
+        hub)      _cb_render_hub ;;
+        help)     _cb_render_help ;;
+        list)     _cb_render_user_list "${3:-0}" ;;
+        detail)   _cb_render_user_detail "${3:-user01}" "${4:-0}" ;;
+        confirm)  _cb_render_confirm "${3:-disable}" "${4:-user01}" 0 ;;
+        traffic)  _cb_render_traffic 24h ;;
+        engine)   _cb_render_engine ;;
+        settings) _cb_render_settings ;;
+    esac
+    cat "$EDIT"
+}
+markup_of() { printf '%s' "$1" | tail -1; }
+cbs_of() { printf '%s' "$1" | grep -o '"callback_data":"[^"]*"' | sed 's/.*:"//;s/"$//'; }
+
+echo "Telegram menu render tests"
+
+VIEWS="hub help list detail confirm traffic engine settings"
+
+# ── Every view for every role is structurally sound ──────────────────────────
+for _role in superadmin reseller operator; do
+    for _v in $VIEWS; do
+        _out=$(render "$_role" "$_v")
+        _mk=$(markup_of "$_out")
+
+        # The markup must be a well-formed inline_keyboard object.
+        case "$_mk" in
+            '{"inline_keyboard":['*']}') _shape=0 ;;
+            *) _shape=1 ;;
+        esac
+        assert_ok "role=$_role view=$_v markup has inline_keyboard shape" "$_shape"
+
+        # Balanced brackets — an unbalanced one is a 400 and loses the message.
+        _open=$(printf '%s' "$_mk" | tr -cd '[' | wc -c | tr -d ' ')
+        _close=$(printf '%s' "$_mk" | tr -cd ']' | wc -c | tr -d ' ')
+        assert_eq "role=$_role view=$_v brackets balance" "$_open" "$_close"
+
+        # Every payload must fit 64 bytes and decode.
+        _bad=0
+        while IFS= read -r _p; do
+            [ -z "$_p" ] && continue
+            [ "${#_p}" -gt 64 ] && _bad=1
+            _cb_dec "$_p" || _bad=1
+        done < <(cbs_of "$_out")
+        assert_ok "role=$_role view=$_v payloads are valid and <=64 bytes" "$_bad"
+
+        # No row may exceed Telegram's 8-button limit.
+        _wide=0
+        while IFS= read -r _row; do
+            _n=$(printf '%s' "$_row" | grep -o '"text"' | wc -l | tr -d ' ')
+            [ "$_n" -gt 8 ] && _wide=1
+        done < <(printf '%s' "$_mk" | sed 's/\[/\n[/g')
+        assert_ok "role=$_role view=$_v no row exceeds 8 buttons" "$_wide"
+
+        # The body must fit one message (the chunker is tested separately).
+        _body=$(printf '%s' "$_out" | head -n -1)
+        assert_ok "role=$_role view=$_v body fits one message" \
+            "$([ "${#_body}" -le 4096 ] && echo 0 || echo 1)"
+    done
+done
+
+# ── A role never sees a button it cannot use ─────────────────────────────────
+_out=$(render reseller hub)
+assert_eq "reseller hub offers no action payloads" 0 "$(cbs_of "$_out" | grep -cE '^[ac]:')"
+assert_eq "reseller hub offers no user list" 0 "$(cbs_of "$_out" | grep -c '^u:')"
+
+_out=$(render operator hub)
+assert_eq "unrecognised role hub offers no action payloads" 0 "$(cbs_of "$_out" | grep -cE '^[ac]:')"
+
+_out=$(render superadmin hub)
+assert_ok "superadmin hub does offer the user list" \
+    "$([ "$(cbs_of "$_out" | grep -c '^u:l:')" -ge 1 ] && echo 0 || echo 1)"
+
+# ── A reseller's detail card must not carry destructive actions ──────────────
+# _cb_dispatch would refuse them anyway, but advertising them is misleading.
+_out=$(render reseller detail user01)
+assert_eq "reseller detail card hides destructive buttons" 0 \
+    "$(cbs_of "$_out" | grep -cE '^[ac]:(disable|remove|rotate)')"
+
+_out=$(render superadmin detail user01)
+assert_ok "superadmin detail card does offer actions" \
+    "$([ "$(cbs_of "$_out" | grep -cE '^a:')" -ge 1 ] && echo 0 || echo 1)"
+
+# ── Pagination ───────────────────────────────────────────────────────────────
+_p0=$(cbs_of "$(render superadmin list 0)")
+assert_eq "page 0 shows a full page of users" 6 "$(printf '%s\n' "$_p0" | grep -c '^u:s:')"
+assert_eq "page 0 has no Prev button" 0 "$(printf '%s\n' "$_p0" | grep -c '^u:l:$')"
+
+_p2=$(cbs_of "$(render superadmin list 2)")
+assert_eq "last page shows the remaining users" 1 "$(printf '%s\n' "$_p2" | grep -c '^u:s:')"
+
+# An out-of-range page must clamp rather than render an empty keyboard.
+_p9=$(cbs_of "$(render superadmin list 99)")
+assert_ok "an out-of-range page still renders users" \
+    "$([ "$(printf '%s\n' "$_p9" | grep -c '^u:s:')" -ge 1 ] && echo 0 || echo 1)"
+
+# A garbage page value must not produce garbage output.
+_px=$(render superadmin list "abc")
+assert_ok "a non-numeric page still renders a keyboard" \
+    "$(printf '%s' "$_px" | tail -1 | grep -q 'inline_keyboard' && echo 0 || echo 1)"
+
+# Back from a detail card returns to the page it came from.
+_cbs=$(cbs_of "$(render superadmin detail user07 1)")
+assert_ok "detail card carries its origin page into Back" \
+    "$(printf '%s\n' "$_cbs" | grep -q '^u:l:1$' && echo 0 || echo 1)"
+
+# ── A disabled secret offers Enable, not Disable ─────────────────────────────
+# user03 is disabled in the fixture.
+_cbs=$(cbs_of "$(render superadmin detail user03)")
+assert_ok "a disabled secret offers Enable" \
+    "$(printf '%s\n' "$_cbs" | grep -q '^a:enable:user03$' && echo 0 || echo 1)"
+assert_eq "a disabled secret does not offer Disable" 0 \
+    "$(printf '%s\n' "$_cbs" | grep -c '^a:disable:user03$')"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_reseller_rbac.sh b/tests/test_telegram_reseller_rbac.sh
index 385b3db..7746f22 100644
--- a/tests/test_telegram_reseller_rbac.sh
+++ b/tests/test_telegram_reseller_rbac.sh
@@ -66,6 +66,10 @@ ROLE_TO_RETURN="reseller"
 _check_tg_role() { echo "$ROLE_TO_RETURN"; }
 tg_send() { printf 'admin|%s\n' "$*" >> "$REPLIES"; }
 tg_send_to() { printf 'to:%s|%s\n' "$1" "$2" >> "$REPLIES"; }
+# The replies that carry an inline keyboard go through these instead, so they
+# must be captured too or those assertions silently see an empty log.
+tg_send_kb() { printf 'admin|%s\n' "$*" >> "$REPLIES"; }
+tg_send_to_kb() { printf 'to:%s|%s\n' "$1" "$2" >> "$REPLIES"; }
 load_tg_settings() { :; }
 is_running() { return 1; }
 log_warn() { :; }
@@ -87,6 +91,10 @@ telegram_generate_service_script
 DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
 awk '/^_tg_security_log\(\)/,/^}$/' "$DAEMON" > "$TEST_TMPDIR/daemon-fns.sh"
 awk '/^_process_cmd\(\)/,/^}$/' "$DAEMON" >> "$TEST_TMPDIR/daemon-fns.sh"
+# Reply handlers build their button bar via _tg_button_bar, so the menu block
+# has to resolve too. It does not define _check_tg_role, so the role stub above
+# survives.
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$TEST_TMPDIR/daemon-fns.sh"
 assert_eq "daemon helper extraction is valid bash" 0 \
     "$(bash -n "$TEST_TMPDIR/daemon-fns.sh" 2>/dev/null; echo $?)"
 source "$TEST_TMPDIR/daemon-fns.sh"

From 3dd43fbf1cbf41b625c0d89f30b3e53fa75b85b7 Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Fri, 18 Sep 2026 07:45:42 +0300
Subject: [PATCH 04/10] feat(telegram): add pending input and drop code-box
 reply formatting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two pieces of reply plumbing, both in service of making the bot usable from
buttons and readable on a phone.

Pending input
-------------
Inline buttons cannot collect typed text, so a flow that needs a value arms a
prompt for that chat and takes the next plain message from it as the answer.
State is one line per chat in relay_stats/.tg_pending; the daemon is its only
reader and only writer, so the rewrite needs no lock.

The consumption rule is the part that has to be right, because a stale or
misfiled entry would swallow a user's next real message:

  - a slash command always escapes, and clears the prompt on the way out;
  - re-arming replaces rather than appends;
  - an expired row is dropped on read;
  - the answer runs as the sender, after the role lookup.

The first consumer is the "add user" flow, which validates the label before it
reaches the CLI and hands back a connect link built from the secret it created.

No code box
-----------
Every fenced site wrapped CLI output in ```…```, which Telegram draws as a
monospace box with a copy button — the wrong shape for a status reply.

The replacement is one line per fact. Padding is not available as an alignment
mechanism: printf "%-14s" pads with letters, and letters do not have a uniform
advance width in a proportional font, so padded columns collapse outside a
fence. Block-element glyphs are a different case and stay inline.

Two fixes fall out of reading vouchers.conf instead of the CLI's padded table:

  - /mp_voucher create showed the WRONG rows. It read the active list back and
    did `tail -n +3`, which skipped the first voucher and re-announced an
    existing code instead of the one just generated. It now snapshots the
    active count and reports only the rows past it.
  - /mp_fleet rendered one block per node rather than a padded table, so the
    columns survive without a fence.
---
 mtproxymax.sh                        | 295 +++++++++++++++++++++++++--
 tests/test_telegram_no_codebox.sh    | 241 ++++++++++++++++++++++
 tests/test_telegram_pending_input.sh | 200 ++++++++++++++++++
 tests/test_telegram_reseller_rbac.sh |  20 +-
 4 files changed, 739 insertions(+), 17 deletions(-)
 create mode 100644 tests/test_telegram_no_codebox.sh
 create mode 100644 tests/test_telegram_pending_input.sh

diff --git a/mtproxymax.sh b/mtproxymax.sh
index 3fb7d71..e2cfe41 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -12225,6 +12225,12 @@ _process_cmd() {
         grep -q "^${chat_id}$" "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || echo "$chat_id" >> "${INSTALL_DIR}/bot_users.txt" 2>/dev/null || true
     fi
 
+    # An armed prompt owns the next plain message from this chat. It runs before
+    # the command table so a value can never be mistaken for a command, and it
+    # deliberately sits AFTER the role lookup — the answer still executes as the
+    # sender, never as whoever armed the prompt.
+    _tg_pending_try "$chat_id" "$text" && return
+
     # Public user or unauthenticated commands
     case "$text" in
         /start|/start@*)
@@ -12333,16 +12339,30 @@ _process_cmd() {
                     local cnt=$(echo "$text" | awk '{print $3}')
                     local qta=$(echo "$text" | awk '{print $4}')
                     local dys=$(echo "$text" | awk '{print $5}')
-                    "${INSTALL_DIR}/mtproxymax" voucher create "${cnt:-1}" "${qta:-10G}" "${dys:-30}" &>/dev/null
-                    local vout=$("${INSTALL_DIR}/mtproxymax" voucher list active | tail -n +3 | head -n "${cnt:-1}")
-                    tg_send "🎟 *Generated Vouchers*\n\`\`\`\n${vout}\n\`\`\`"
+                    [[ "$cnt" =~ ^[0-9]+$ ]] && [ "$cnt" -ge 1 ] && [ "$cnt" -le 100 ] || cnt=1
+                    # Snapshot the active count first: the vault is append-only,
+                    # so the rows past that index are exactly the new ones. The
+                    # previous version read the list back and did `tail -n +3`,
+                    # which silently showed the wrong rows.
+                    local _before; _before=$(_tg_voucher_count)
+                    "${INSTALL_DIR}/mtproxymax" voucher create "$cnt" "${qta:-10G}" "${dys:-30}" &>/dev/null
+                    local vbody; vbody=$(_tg_voucher_lines "$_before")
+                    if [ -n "$vbody" ]; then
+                        tg_send "🎟 *Generated ${cnt} voucher(s)*${vbody}"
+                    else
+                        tg_send "❌ No vouchers were created — check the server log."
+                    fi
                     ;;
                 list)
-                    local vout=$("${INSTALL_DIR}/mtproxymax" voucher list active | head -n 25)
-                    tg_send "📋 *Active Vouchers*\n\`\`\`\n${vout}\n\`\`\`"
+                    local vbody; vbody=$(_tg_voucher_lines)
+                    if [ -n "$vbody" ]; then
+                        tg_send "📋 *Active Vouchers*${vbody}"
+                    else
+                        tg_send "📋 *Active Vouchers*\n\n_None yet._"
+                    fi
                     ;;
                 *)
-                    tg_send "🎟 *Voucher Engine*\n\nUsage:\n\`/mp_voucher create <count> <quota> <days>\`\n\`/mp_voucher list\`"
+                    tg_send "🎟 *Voucher Engine*\n\n• /mp\\_voucher create <count> <quota> <days>\n• /mp\\_voucher list"
                     ;;
             esac
             ;;
@@ -12496,10 +12516,20 @@ _process_cmd() {
             ;;
         /mp_health|/mp_health@*)
             local health_out
-            health_out=$("${INSTALL_DIR}/mtproxymax" health 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | head -20) || true
-            local status_icon="🟢"
-            echo "$health_out" | grep -qi "fail\|error\|down" && status_icon="🔴"
-            tg_send "${status_icon} *Health Check*\n\n\`\`\`\n${health_out}\n\`\`\`"
+            health_out=$("${INSTALL_DIR}/mtproxymax" health 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | head -40) || true
+            local hbody
+            hbody=$(_tg_kv_lines <<< "$health_out")
+            if [ -z "$hbody" ]; then
+                # The check output is key/value today. If that ever changes, fall
+                # back to the raw lines rather than an empty reply — a failed
+                # parse must not read as "everything is fine".
+                hbody=$(while IFS= read -r _l; do
+                            [ -z "$_l" ] && continue
+                            printf '\n• %s' "$(_esc "$_l")"
+                        done <<< "$(printf '%s' "$health_out" | head -15)")
+                [ -z "$hbody" ] && hbody=$'\n⚠️ No output from the health check.'
+            fi
+            tg_send_kb "🩺 *Health Check*${hbody}" "$(_tg_button_bar "$chat_id")"
             ;;
         /mp_traffic|/mp_traffic@*)
             load_tg_settings
@@ -12523,7 +12553,12 @@ _process_cmd() {
             local update_out
             update_out=$("${INSTALL_DIR}/mtproxymax" update </dev/null 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | tail -5)
             if [ -n "$update_out" ]; then
-                tg_send "📋 Update check:\n\`\`\`\n${update_out}\n\`\`\`"
+                local ubody=""
+                while IFS= read -r _l; do
+                    [ -z "$_l" ] && continue
+                    ubody+="\n• $(_esc "$_l")"
+                done <<< "$update_out"
+                tg_send "📋 *Update check*${ubody}"
             else
                 tg_send "✅ Script is up to date"
             fi
@@ -12561,8 +12596,26 @@ _process_cmd() {
             ;;
         /mp_fleet|/mp_fleet@*)
             local fleet_out; fleet_out=$("${INSTALL_DIR}/mtproxymax" fleet status 2>/dev/null | sed 's/\x1b\[[0-9;]*m//g')
-            [ -z "$fleet_out" ] && fleet_out="No multi-server fleet telemetry collected yet."
-            tg_send "🌐 *Global Federation Fleet Summary*\n\`\`\`\n${fleet_out}\n\`\`\`"
+            if [ -z "$fleet_out" ]; then
+                tg_send "🌐 *Fleet*\n\n_No multi-server fleet telemetry collected yet._"
+                return
+            fi
+            # One block per node. The CLI aligns this with printf padding, which
+            # only reads as columns inside a fence; per-node lines carry the same
+            # data and survive a proportional font.
+            local _f _msg="🌐 *Fleet*" _n=0 _h _ip _users _traffic _load
+            while IFS= read -r _f; do
+                case "$_f" in ""|HOSTNAME*|*"---"*) continue ;; esac
+                read -r _h _ip _users _traffic _load _ <<< "$_f"
+                [ -z "$_h" ] && continue
+                _msg+="\n🟢 *$(_esc "$_h")*"
+                [ -n "$_ip" ] && _msg+=" — \`$(_esc "$_ip")\`"
+                [ -n "$_users" ] && _msg+=" · 👥 ${_users}"
+                [ -n "$_traffic" ] && _msg+=" · 📊 ${_traffic}"
+                _n=$(( _n + 1 ))
+            done <<< "$fleet_out"
+            [ "$_n" -eq 0 ] && _msg+="\n\n_No nodes reported._"
+            tg_send "$_msg"
             ;;
         /mp_upstreams|/mp_upstreams@*)
             load_tg_settings
@@ -12602,7 +12655,7 @@ _process_cmd() {
                 *)
                     load_tg_settings
                     local st="🟢 NORMAL"; [ "${LOCKDOWN_MODE:-false}" = "true" ] && st="🔴 LOCKDOWN ACTIVE"
-                    tg_send "🔒 *Emergency Lockdown Mode*: ${st}\n\nUsage:\n\`/mp_lockdown on\` — Activate Emergency Shield\n\`/mp_lockdown off\` — Return to Normal"
+                    tg_send "🔒 *Emergency Lockdown Mode*: ${st}\n\n• /mp\\_lockdown on — Activate Emergency Shield\n• /mp\\_lockdown off — Return to Normal"
                     ;;
             esac
             ;;
@@ -12658,6 +12711,140 @@ _process_cmd() {
 }
 
 # >>> TG_MENU_BEGIN
+
+
+# >>> TG_PENDING_BEGIN
+# ── Pending input ───────────────────────────────────────────────────────────
+#
+# Inline buttons cannot collect typed text, so a flow that needs a value arms a
+# prompt for that chat and the next plain message from it is taken as the
+# answer. State is one line per chat:
+#
+#   <chat_id>|<verb>|<target>|<expires_epoch>
+#
+# This daemon is the only reader AND the only writer (one shell, one loop), so
+# the rewrite needs no lock — the same reasoning the history appenders use.
+#
+# The answer is consumed by _tg_pending_try before the command dispatcher ever
+# sees it, and a slash command always escapes: being trapped in a prompt with no
+# way back to the command surface is a worse failure than losing an answer.
+_TG_PENDING_TTL=300
+_tg_pending_file() { printf '%s' "${INSTALL_DIR}/relay_stats/.tg_pending"; }
+
+_tg_pending_set() {
+    local chat="$1" verb="$2" target="${3:--}"
+    local f now exp tmp
+    f=$(_tg_pending_file)
+    # An empty path would make the temp file below land in the CURRENT
+    # DIRECTORY as "./.tmp.<pid>" — which is how a stray dotfile gets committed.
+    # INSTALL_DIR is always set in the shipped daemon, so this only ever fires
+    # in a caller that sourced the block without it.
+    [ -n "$f" ] || return 1
+    now=$(date +%s)
+    exp=$(( now + ${_TG_PENDING_TTL:-300} ))
+    mkdir -p "${INSTALL_DIR}/relay_stats" 2>/dev/null || true
+    tmp="${f}.tmp.$$"
+    # Re-arm REPLACES rather than appends: leaving an older line in place would
+    # answer with the stale verb, and the file is read top-down.
+    {
+        [ -f "$f" ] && grep -v "^${chat}|" "$f" 2>/dev/null
+        printf '%s|%s|%s|%s\n' "$chat" "$verb" "$target" "$exp"
+    } > "$tmp" 2>/dev/null && mv "$tmp" "$f" 2>/dev/null
+    chmod 600 "$f" 2>/dev/null || true
+    return 0
+}
+
+# Read-and-clear. Prints "<verb>|<target>"; non-zero when nothing was armed.
+_tg_pending_take() {
+    local chat="$1" f now tmp out="" matched=1
+    f=$(_tg_pending_file)
+    [ -n "$f" ] || return 1
+    [ -f "$f" ] || return 1
+    now=$(date +%s)
+    tmp="${f}.tmp.$$"
+    # Expired rows are dropped here rather than by a sweeper: this is the only
+    # place they matter, and a prompt nobody answers leaves no garbage behind.
+    while IFS='|' read -r _c _v _t _e; do
+        [ -z "$_c" ] && continue
+        if [ "$_c" = "$chat" ]; then
+            if [ "${_e:-0}" -gt "$now" ] 2>/dev/null; then
+                out="${_v}|${_t}"; matched=0
+            fi
+            continue
+        fi
+        printf '%s|%s|%s|%s\n' "$_c" "$_v" "$_t" "$_e"
+    done < "$f" > "$tmp" 2>/dev/null
+    mv "$tmp" "$f" 2>/dev/null || : > "$f"
+    [ "$matched" -eq 0 ] || return 1
+    printf '%s' "$out"
+    return 0
+}
+
+_tg_pending_clear() {
+    local chat="$1" f tmp
+    f=$(_tg_pending_file)
+    [ -n "$f" ] || return 0
+    [ -f "$f" ] || return 0
+    tmp="${f}.tmp.$$"
+    grep -v "^${chat}|" "$f" > "$tmp" 2>/dev/null
+    mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+    return 0
+}
+
+# Give an armed prompt first refusal on an incoming message. Returns 0 when the
+# message was consumed as an answer, 1 when the caller must dispatch it.
+_tg_pending_try() {
+    local chat="$1" text="$2" v
+    case "$text" in
+        /*) _tg_pending_clear "$chat"; return 1 ;;
+    esac
+    v=$(_tg_pending_take "$chat") || return 1
+    _tg_pending_run "$chat" "${v%%|*}" "${v#*|}" "$text"
+    return 0
+}
+
+# Dispatch a consumed answer to the flow that armed the prompt.
+_tg_pending_run() {
+    local chat="$1" verb="$2" target="$3" value="$4"
+    case "$verb" in
+        add)
+            if ! _cb_label_ok "$value"; then
+                tg_send_to "$chat" "❌ Invalid label — letters, digits, '_' and '-' only, max 32 characters."
+                return 1
+            fi
+            if ! "${INSTALL_DIR}/mtproxymax" secret add "$value" &>/dev/null; then
+                tg_send_to "$chat" "❌ Could not add *$(_esc "$value")* — it may already exist."
+                return 1
+            fi
+            tg_send_to "$chat" "✅ Secret *$(_esc "$value")* created.$(_tg_new_secret_link "$value")"
+            ;;
+        *)
+            tg_send_to "$chat" "❌ That prompt is no longer valid."
+            return 1
+            ;;
+    esac
+    return 0
+}
+
+# The connect block for a just-created secret, or "" if it cannot be built.
+# Shared by every flow that provisions a secret so the wording and the
+# FakeTLS/plain branch stay in one place.
+_tg_new_secret_link() {
+    local label="$1" ip secret dh fs
+    ip=$(get_cached_ip)
+    [ -z "$ip" ] && return 0
+    secret=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1 | cut -d'|' -f2)
+    [ -z "$secret" ] && return 0
+    if [ "${MASKING_ENABLED:-true}" != "false" ]; then
+        dh=$(domain_to_hex "${PROXY_DOMAIN:-cloudflare.com}")
+        fs="ee${secret}${dh}"
+    else
+        fs="dd${secret}"
+    fi
+    printf '\n\n🔗 [Connect](https://t.me/proxy?server=%s&port=%s&secret=%s)\n📡 `%s:%s`' \
+        "$ip" "${PROXY_PORT}" "$fs" "$ip" "${PROXY_PORT}"
+}
+# <<< TG_PENDING_END
 # ── Interactive inline-keyboard menus ───────────────────────────────────────
 #
 # The security model: callback_data is entirely attacker-controlled — a user
@@ -13179,6 +13366,86 @@ _process_callback() {
     _cb_dispatch || true
     tg_answer_cb "$_CB_ID" "$_CB_TOAST" "$_CB_ALERT"
 }
+# >>> TG_FMT_BEGIN
+# ── Reply formatting ────────────────────────────────────────────────────────
+#
+# Command replies used to dump CLI output into a Markdown code fence, which
+# Telegram draws as a monospace box with a copy button. That is the wrong shape
+# for a status reply: it reads as pasted console output, it cannot wrap, and it
+# puts a tap target on every line.
+#
+# The replacement is one line per fact. Alignment by padding is not available —
+# `printf "%-14s"` pads with letters, and letters do not have a uniform advance
+# width in a proportional font, so padded columns collapse outside a fence. The
+# block-element glyphs used for bars and sparklines are a different case: they
+# are drawn as a tiling set and DO share an advance width, which is why the
+# charts can stay inline.
+
+# "  Key:            value" -> "✅ *Key*: value", one line each. The padding is
+# decorative, so dropping it costs nothing; the key/value pairs are the data.
+_tg_kv_lines() {
+    local _line _k _v _icon _n=0
+    while IFS= read -r _line; do
+        [ -z "$_line" ] && continue
+        [[ "$_line" =~ ^[[:space:]]*([^:]+):[[:space:]]*(.*)$ ]] || continue
+        _k="${BASH_REMATCH[1]}"
+        _v="${BASH_REMATCH[2]}"
+        # Trim the padding printf added between the key and the colon.
+        _k="${_k%"${_k##*[![:space:]]}"}"
+        [ -z "$_k" ] && continue
+        case "$_v" in
+            *fail*|*Fail*|*FAIL*|*error*|*Error*|*down*|*Down*|*stopped*|*not\ running*)
+                _icon="❌" ;;
+            *warn*|*Warn*|*WARN*|*degraded*|*slow*)
+                _icon="⚠️" ;;
+            *) _icon="✅" ;;
+        esac
+        printf '\n%s *%s*: %s' "$_icon" "$(_esc "$_k")" "$(_esc "$_v")"
+        _n=$(( _n + 1 ))
+    done
+    [ "$_n" -gt 0 ]
+}
+
+# Active vouchers as one line each, read from vouchers.conf rather than parsed
+# out of the CLI's padded table — the source of truth for both the list reply
+# and the create reply, and it needs no column alignment to be re-derived.
+#
+# skip_first drops the rows that already existed before a create, so the reply
+# shows the codes that were just generated instead of the whole inventory.
+_tg_voucher_lines() {
+    local skip_first="${1:-0}" f="${INSTALL_DIR}/vouchers.conf" _n=0
+    local _code _quota _days _conns _ips _tier _status _created _by _at
+    [ -f "$f" ] || return 0
+    while IFS='|' read -r _code _quota _days _conns _ips _tier _status _created _by _at; do
+        [ -z "$_code" ] && continue
+        [ "$_status" != "ACTIVE" ] && continue
+        _n=$(( _n + 1 ))
+        [ "$_n" -le "$skip_first" ] && continue
+        # The code goes inside a Markdown span, so anything outside the code
+        # alphabet would either break the span or inject formatting.
+        _code=$(printf '%s' "$_code" | tr -cd 'A-Za-z0-9-')
+        [ -z "$_code" ] && continue
+        printf '\n🎟 `%s`' "$_code"
+        [ -n "$_quota" ] && [ "$_quota" != "0" ] && printf ' · %s' "$(format_bytes "$_quota")"
+        [ -n "$_days" ] && [ "$_days" != "0" ] && printf ' · %sd' "$_days"
+        [ -n "$_tier" ] && [ "$_tier" != "standard" ] && printf ' · %s' "$_tier"
+    done < "$f"
+}
+
+# How many ACTIVE rows vouchers.conf holds, so a create can report only the new
+# ones. Counted before the create runs.
+_tg_voucher_count() {
+    local f="${INSTALL_DIR}/vouchers.conf" _status
+    [ -f "$f" ] || { printf '0'; return 0; }
+    local _c=0
+    while IFS='|' read -r _code _q _d _cn _i _t _status _cr _by _at; do
+        [ -z "$_code" ] && continue
+        [ "$_status" = "ACTIVE" ] && _c=$(( _c + 1 ))
+    done < "$f"
+    printf '%s' "$_c"
+}
+# <<< TG_FMT_END
+
 # <<< TG_MENU_END
 
 # Cleanup trap for temp files
diff --git a/tests/test_telegram_no_codebox.sh b/tests/test_telegram_no_codebox.sh
new file mode 100644
index 0000000..24673c4
--- /dev/null
+++ b/tests/test_telegram_no_codebox.sh
@@ -0,0 +1,241 @@
+#!/bin/bash
+# Tests that no bot reply renders inside a Markdown code fence.
+#
+# Telegram draws a fenced block as a monospace box with a copy button, which is
+# the wrong shape for a status reply: it reads as pasted console output, it
+# cannot wrap, and every line gets a tap target the reader did not ask for.
+#
+# The commands below used to dump CLI output straight into ```…```. The rule
+# this file pins is that they now emit one line per fact. The value must survive
+# the change, so each case asserts BOTH that no fence is present AND that the
+# data still reaches the reader — a rewrite that quietly dropped the content
+# would pass a fence-only check.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+VOUCHERS_FILE="$INSTALL_DIR/vouchers.conf"
+UPSTREAMS_FILE="$INSTALL_DIR/upstreams.conf"
+
+printf 'alice|%s|1700000000|true|0|0|0|0||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+
+# The voucher reply reads the vault rather than the CLI's padded table, so the
+# fixture has to look like a real one: code|quota_bytes|days|conns|ips|tier|
+# status|created|redeemed_by|redeemed_at.
+cat > "$VOUCHERS_FILE" <<'EOF'
+MTP-AAAA-BBBB|10737418240|30|15|5|standard|ACTIVE|2026-01-01 00:00:00 UTC|-|-
+MTP-CCCC-DDDD|5368709120|7|15|5|standard|ACTIVE|2026-01-02 00:00:00 UTC|-|-
+MTP-OLD1-OLD2|10737418240|30|15|5|standard|REDEEMED|2025-12-01 00:00:00 UTC|tg_5|2025-12-02 00:00:00 UTC
+EOF
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"
+    fi
+}
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+
+# ── Extract the shipped command dispatcher ───────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec _esc _process_cmd \
+           _tg_pending_file _tg_pending_set _tg_pending_take _tg_pending_clear \
+           _tg_pending_try _tg_pending_run _tg_new_secret_link; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "dispatcher extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_eq "menu block was found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_MENU_BEGIN$' "$FNS")"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+
+_check_tg_role() { echo "superadmin"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+load_tg_settings() { :; }
+is_running() { return 0; }
+is_proxy_running() { return 0; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+get_stats() { echo "1024 2048 7"; }
+get_uptime() { echo "98123"; }
+get_active_connections() { echo "7"; }
+get_container_uptime() { echo "98123"; }
+get_cum_user_traffic() { echo "1024 2048"; }
+format_duration() { echo "1d 3h 15m"; }
+get_stats_dummy() { :; }
+_esc() { printf '%s' "$1"; }
+_tg_metrics_raw() { printf ''; }
+mkdir -p "$INSTALL_DIR/relay_stats"
+load_traffic() { :; }
+
+# The manager stub reproduces the REAL output shape of each verb, padding
+# included, so the parsing in the rewritten handlers is exercised against
+# something that looks like what actually ships.
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+case "$1" in
+    voucher)
+        case "$2" in
+            list)
+                cat <<'OUT'
+CODE           QUOTA      DAYS  STATUS
+MTP-AAAA-BBBB  10.00 GB   30    active
+MTP-CCCC-DDDD  5.00 GB    7     active
+OUT
+                ;;
+            create) exit 0 ;;
+        esac
+        ;;
+    health)
+        cat <<'OUT'
+  Engine:          running
+  Port 443:        listening
+  Metrics:         ok
+  Secrets:         1 active
+OUT
+        ;;
+    update) echo "Already on the latest version (v1.4.1-LTS)" ;;
+    fleet)
+        cat <<'OUT'
+HOSTNAME       IP             USERS   TRAFFIC     LOAD
+node-a         203.0.113.9    42      12.30 GB    0.41
+node-b         198.51.100.4   7        1.10 GB    0.05
+OUT
+        ;;
+esac
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+PROXY_PORT=443
+PROXY_DOMAIN="cloudflare.com"
+MASKING_ENABLED="true"
+VERSION="v1.4.1-LTS"
+
+run_cmd() {   # run_cmd <text>
+    : > "$SENDS"; : > "$CALLS"
+    _process_cmd "1" "111" "$1" >/dev/null 2>&1
+    cat "$SENDS"
+}
+
+# ── /mp_voucher ──────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_voucher list")
+assert_not_contains "voucher list draws no code box" '```' "$_out"
+assert_contains "voucher list still shows the codes" "MTP-AAAA-BBBB" "$_out"
+assert_contains "voucher list still shows the second code" "MTP-CCCC-DDDD" "$_out"
+assert_contains "voucher list still shows the quota" "10.00 GB" "$_out"
+assert_not_contains "voucher list hides redeemed codes" "MTP-OLD1-OLD2" "$_out"
+
+_out=$(run_cmd "/mp_voucher create 2 10G 30")
+assert_not_contains "voucher create draws no code box" '```' "$_out"
+assert_contains "voucher create still reaches the CLI" "voucher create 2 10G 30" "$(cat "$CALLS")"
+# The create reply must not repeat the two codes that were already there.
+assert_not_contains "voucher create does not re-announce the existing vault" "MTP-AAAA-BBBB" "$_out"
+
+# ── /mp_health ───────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_health")
+assert_not_contains "health draws no code box" '```' "$_out"
+assert_contains "health still reports the engine state" "Engine" "$_out"
+assert_contains "health still reports the metrics check" "Metrics" "$_out"
+
+# ── /mp_update ───────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_update")
+assert_not_contains "update draws no code box" '```' "$_out"
+assert_contains "update still reports the version" "v1.4.1-LTS" "$_out"
+
+# ── /mp_fleet ────────────────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_fleet")
+assert_not_contains "fleet draws no code box" '```' "$_out"
+assert_contains "fleet still lists the first node" "node-a" "$_out"
+assert_contains "fleet still lists the second node" "node-b" "$_out"
+# Column padding only reads as columns inside a fence; outside one it is just a
+# ragged gap, so the rewritten view must not carry it.
+assert_not_contains "fleet does not smuggle back column padding" "     " "$_out"
+
+# ── /mp_lockdown usage ───────────────────────────────────────────────────────
+_out=$(run_cmd "/mp_lockdown status")
+assert_not_contains "lockdown usage draws no code box" '```' "$_out"
+
+# ── The whole surface, swept for fences ──────────────────────────────────────
+# A per-command check can miss a fence added to a command nobody thought to
+# list, so sweep every administrative command once.
+for _c in "/mp_help" "/mp_status" "/mp_secrets" "/mp_link" "/mp_limits" \
+          "/mp_traffic" "/mp_upstreams" "/mp_digest" "/mp_restart" "/mp_lockdown"; do
+    _out=$(run_cmd "$_c")
+    assert_not_contains "$_c draws no code box" '```' "$_out"
+done
+
+# ── The views reachable by button ────────────────────────────────────────────
+for _v in hub help user_list engine settings; do
+    EDIT="$TEST_TMPDIR/edit-$_v.txt"
+    : > "$EDIT"
+    tg_edit() { printf '%s\n%s' "$3" "$4" > "$EDIT"; }
+    tg_edit_markup() { :; }
+    tg_answer_cb() { :; }
+    _CB_CHAT="111"; _CB_MID="77"; _CB_DATA=""; _UI_ROLE="superadmin"
+    case "$_v" in
+        hub)          _cb_render_hub ;;
+        help)         _cb_render_help ;;
+        user_list)    _cb_render_user_list 0 ;;
+        engine)       _cb_render_engine ;;
+        settings)     _cb_render_settings ;;
+    esac
+    assert_not_contains "$_v view draws no code box" '```' "$(cat "$EDIT")"
+done
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_pending_input.sh b/tests/test_telegram_pending_input.sh
new file mode 100644
index 0000000..7e2b432
--- /dev/null
+++ b/tests/test_telegram_pending_input.sh
@@ -0,0 +1,200 @@
+#!/bin/bash
+# Tests for the pending-input primitive.
+#
+# Inline buttons cannot collect typed text, so a flow that needs a value (add a
+# user, set a custom limit, broadcast) arms a prompt for that chat and the next
+# plain message from that chat is consumed as the answer. The dangerous half is
+# the consumption: a stale or misfiled entry would swallow a user's next real
+# message. These tests pin both halves — that an armed prompt answers exactly
+# once, and that it can never eat a command or outlive its TTL.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|0|0|0|0||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"
+    fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        printf '  PASS  %s\n' "$name"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"
+    fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else
+        printf '  PASS  %s\n' "$name"
+    fi
+}
+
+# ── Extract the shipped primitive ────────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+# The block is delimited by markers so the test exercises exactly what ships,
+# and so a function added to it later is picked up without editing this list.
+awk '/^# >>> TG_PENDING_BEGIN$/,/^# <<< TG_PENDING_END$/' "$DAEMON" >> "$FNS"
+assert_eq "pending-input extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_eq "the pending block was found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_PENDING_BEGIN$' "$FNS")"
+# A missing function would silently make every later assertion vacuous.
+assert_contains "the primitive ships in the daemon" "_tg_pending_set()" "$(cat "$FNS")"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+ROLE_TO_RETURN="superadmin"
+# Link building reads these; leaving them unset would make the assertion below
+# pass against a malformed "host:" string.
+PROXY_PORT=443
+PROXY_DOMAIN="cloudflare.com"
+MASKING_ENABLED="true"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$SENDS"; }
+load_tg_settings() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+domain_to_hex() { echo "0a0b0c0d"; }
+_esc() { printf '%s' "$1"; }
+format_bytes() { printf '%s' "$1"; }
+
+# The stub records the call AND performs the one side effect the flow reads
+# back — a created secret. Without that, the link-building half of the flow
+# would silently take its "not found" branch and never be exercised.
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+if [ "$1" = "secret" ] && [ "$2" = "add" ]; then
+    printf '%s|%s|1700000000|true|0|0|0|0||\n' "$3" "$(printf 'c%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+fi
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS" SECRETS_FILE
+
+source "$FNS"
+
+PENDING="$INSTALL_DIR/relay_stats/.tg_pending"
+reset_state() { : > "$SENDS"; : > "$CALLS"; rm -f "$PENDING"; }
+
+# ── Round trip ───────────────────────────────────────────────────────────────
+reset_state
+_tg_pending_set "111" "add" "-"
+assert_eq "an armed prompt reads back as verb|target" "add|-" "$(_tg_pending_take "111")"
+assert_eq "taking clears it, so it answers only once" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+
+# ── Per-chat isolation ───────────────────────────────────────────────────────
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_set "222" "limit" "alice"
+assert_eq "another chat's prompt is untouched" "add|-" "$(_tg_pending_take "111")"
+assert_eq "and its own still answers" "limit|alice" "$(_tg_pending_take "222")"
+
+# Re-arming must REPLACE, not append: a second set that left the first line in
+# place would answer with the stale verb.
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_set "111" "limit" "alice"
+assert_eq "re-arming replaces the previous prompt" "limit|alice" "$(_tg_pending_take "111")"
+assert_eq "and leaves exactly one line on disk" 0 "$(grep -c . "$PENDING")"
+
+# ── Expiry ───────────────────────────────────────────────────────────────────
+reset_state
+_TG_PENDING_TTL=0 _tg_pending_set "111" "add" "-"
+assert_eq "an expired prompt does not answer" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+assert_eq "and is pruned off disk" 0 "$(grep -c . "$PENDING")"
+
+# A prompt for another chat must not be swept by the prune above.
+reset_state
+_TG_PENDING_TTL=0 _tg_pending_set "111" "add" "-"
+_tg_pending_set "222" "limit" "alice"
+_tg_pending_take "111" >/dev/null 2>&1
+assert_eq "pruning one chat leaves the other armed" "limit|alice" "$(_tg_pending_take "222")"
+
+# ── Clear ────────────────────────────────────────────────────────────────────
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_clear "111"
+assert_eq "clearing disarms the prompt" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+
+# ── The escape hatch ─────────────────────────────────────────────────────────
+# This is the property that keeps a user from being trapped: any slash command
+# cancels the prompt and is then dispatched normally.
+reset_state
+_tg_pending_set "111" "add" "-"
+assert_eq "a command is not consumed as an answer" 1 "$(_tg_pending_try "111" "/mp_help"; echo $?)"
+assert_eq "and the prompt is disarmed rather than left dangling" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+assert_eq "nothing was executed while escaping" "" "$(cat "$CALLS")"
+
+reset_state
+_tg_pending_set "111" "add" "-"
+assert_eq "a plain message IS consumed as an answer" 0 "$(_tg_pending_try "111" "carol"; echo $?)"
+assert_eq "and is not left armed afterwards" 1 "$(_tg_pending_take "111" >/dev/null 2>&1; echo $?)"
+
+reset_state
+assert_eq "with no prompt armed, a plain message passes through" 1 "$(_tg_pending_try "111" "hello"; echo $?)"
+
+# ── The add flow actually runs ───────────────────────────────────────────────
+# End-to-end for the one flow that exists at this layer: the typed value must
+# reach the CLI verb, and the reply must go back to the chat that typed it.
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_try "111" "carol" >/dev/null
+assert_contains "the typed label reaches the CLI" "secret add carol" "$(cat "$CALLS")"
+assert_contains "and the chat is told about it" "111|" "$(cat "$SENDS")"
+# The new user is useless without a way to connect, so the flow must hand back
+# a link built from the freshly written secret — not just an acknowledgement.
+assert_contains "a connect link comes back" "203.0.113.9:443" "$(cat "$SENDS")"
+
+# A label that could never be a secret name is refused before reaching the CLI,
+# so a pasted link cannot be turned into a directory-traversing label.
+reset_state
+_tg_pending_set "111" "add" "-"
+_tg_pending_try "111" "../../etc/passwd" >/dev/null
+assert_eq "an invalid label never reaches the CLI" "" "$(cat "$CALLS")"
+assert_contains "and the user is told why" "❌" "$(cat "$SENDS")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_reseller_rbac.sh b/tests/test_telegram_reseller_rbac.sh
index 7746f22..3431282 100644
--- a/tests/test_telegram_reseller_rbac.sh
+++ b/tests/test_telegram_reseller_rbac.sh
@@ -18,6 +18,8 @@ mkdir -p "$INSTALL_DIR/relay_stats"
 OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
 ADMINS_FILE="$INSTALL_DIR/admins.conf"
 AUDIT_LOG="$INSTALL_DIR/audit.log"
+VOUCHERS_FILE="$INSTALL_DIR/vouchers.conf"
+printf 'MTP-SEED-0001|10737418240|30|15|5|standard|ACTIVE|2026-01-01 00:00:00 UTC|-|-\n' > "$VOUCHERS_FILE"
 
 MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
 set +e
@@ -75,16 +77,24 @@ is_running() { return 1; }
 log_warn() { :; }
 
 # Stand-in for the manager binary the voucher handler shells out to.
+#
+# The voucher reply reads the vault file rather than the CLI's padded table, so
+# this stub has to do what the real manager does — append to vouchers.conf — and
+# not merely print a table. A stub that only printed would let the reply look
+# correct while reading a file the manager never writes.
 cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
 #!/bin/bash
 case "$1 $2" in
-    # Three lines so the create path (which does `tail -n +3`) still yields one.
     "voucher list") printf 'HEADER\nSEPARATOR\nMTP-AAAA-BBBB\n' ;;
-    "voucher create"|"voucher redeem") : ;;
+    "voucher create")
+        printf 'MTP-NEW1-NEW2|10737418240|30|15|5|standard|ACTIVE|2026-01-02 00:00:00 UTC|-|-\n' >> "$VOUCHERS_FILE"
+        ;;
+    "voucher redeem") : ;;
     *) : ;;
 esac
 EOS
 chmod +x "$INSTALL_DIR/mtproxymax"
+export VOUCHERS_FILE
 
 # Exercise the exact dispatcher shipped in the generated bot daemon.
 telegram_generate_service_script
@@ -134,8 +144,12 @@ for _cmd in "/mp_voucher list" "/mp_voucher create 5 10G 30"; do
     run reseller 333 "$_cmd"
     assert_not_contains "reseller is allowed $_cmd" "Permission denied" "$(cat "$REPLIES")"
     assert_eq "allowed $_cmd is not logged as a violation" "" "$(audit_now)"
-    assert_contains "allowed $_cmd reaches the voucher engine" "MTP-AAAA-BBBB" "$(cat "$REPLIES")"
 done
+# The list reply shows the standing inventory; the create reply shows only the
+# codes it just generated, so the two reach the vault in different ways and need
+# different evidence.
+assert_contains "a reseller can read the vault" "MTP-SEED-0001" "$(run reseller 333 "/mp_voucher list" >/dev/null; cat "$REPLIES")"
+assert_contains "a reseller can add to the vault" "MTP-NEW1-NEW2" "$(run reseller 333 "/mp_voucher create 5 10G 30" >/dev/null; cat "$REPLIES")"
 
 reset_audit
 run reseller 333 "/start"

From f5e38d5c1c9d3bcfa7644629f55b77c9c3252014 Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Fri, 18 Sep 2026 08:02:57 +0300
Subject: [PATCH 05/10] feat(telegram): manage a secret's limits from the user
 card
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the manage card behind a user (u:m) with a picker per limit field —
quota, connections, IPs, expiry and the monthly quota-reset day — and a
template picker that applies a saved template to that secret.

The write path is the part that matters. The obvious verb for "set the quota"
is `secret setlimits <label> <conns> <ips> <quota> <expires>`, but
secret_set_limits reads "0" as UNLIMITED rather than "leave alone", so tapping
"quota: 10G" through it would silently clear the connection and IP caps too.
Every commit goes through the per-field `secret setlimit <label> <field>
<value>` form instead, and the tests pin that a quota change never calls
setlimits at all.

Values arrive through callback_data, which is attacker-controlled, and the
label can also come back out of secrets.conf, which is hand-editable, so both
are re-validated before they reach the CLI.

Two smaller things worth naming:

  - Relative expiry ("+30d") and "never" mean different CLI verbs — `secret
    extend` does the calendar arithmetic, `secret setlimit expires 0` clears
    the date — so one picker drives both.
  - A custom value the presets do not cover arms a pending prompt whose verb is
    the same one the preset commits through, so the typed value lands on
    exactly the same validated path rather than a second, laxer one.

_kb_spec drops a button whose payload would exceed 64 bytes: one oversized
payload makes Telegram reject the whole keyboard, so a missing button beats a
card that will not render. The template picker names those templates in the
body instead of letting them vanish silently.
---
 mtproxymax.sh                            | 340 ++++++++++++++++++++++-
 tests/test_telegram_callback_dispatch.sh |   9 +-
 tests/test_telegram_per_secret_views.sh  | 223 +++++++++++++++
 3 files changed, 569 insertions(+), 3 deletions(-)
 create mode 100644 tests/test_telegram_per_secret_views.sh

diff --git a/mtproxymax.sh b/mtproxymax.sh
index e2cfe41..8d817f4 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -12791,6 +12791,19 @@ _tg_pending_clear() {
     return 0
 }
 
+# Arm a prompt and tell the chat about it. The prompt is SENT rather than used to
+# edit the card that spawned it, because that card is what the operator wants to
+# come back to when they cancel.
+_tg_pending_prompt() {
+    local chat="$1" verb="$2" target="$3" text="$4"
+    _tg_pending_set "$chat" "$verb" "$target" || return 1
+    _UI_ROLE="$(_check_tg_role "$chat")"
+    _kb_reset
+    _kb_row "❌ Cancel|p:x"
+    tg_send_to_kb "$chat" "${text}\n\n_Send it as a normal message. Any /command cancels._" "$(_kb_json)"
+    return 0
+}
+
 # Give an armed prompt first refusal on an incoming message. Returns 0 when the
 # message was consumed as an answer, 1 when the caller must dispatch it.
 _tg_pending_try() {
@@ -12818,6 +12831,21 @@ _tg_pending_run() {
             fi
             tg_send_to "$chat" "✅ Secret *$(_esc "$value")* created.$(_tg_new_secret_link "$value")"
             ;;
+        setq|setc|seti|setx|setr)
+            # target is the label. It came out of a file on disk, so it is
+            # re-validated here exactly as it was on the way in.
+            if ! _cb_label_ok "$target" || ! _cb_secret_exists "$target"; then
+                tg_send_to "$chat" "❌ That secret no longer exists."
+                return 1
+            fi
+            _CB_TOAST=""
+            if _cb_apply_limit "$verb" "$target" "$value"; then
+                tg_send_to "$chat" "✅ *$(_esc "$target")*: ${_CB_TOAST}"
+            else
+                tg_send_to "$chat" "❌ ${_CB_TOAST}"
+                return 1
+            fi
+            ;;
         *)
             tg_send_to "$chat" "❌ That prompt is no longer valid."
             return 1
@@ -12877,7 +12905,25 @@ c:enable=admin
 c:disable=admin
 c:rotate=admin
 a:remove=superadmin
-c:remove=superadmin"
+c:remove=superadmin
+u:m=admin
+e=admin
+e:q=admin
+e:c=admin
+e:i=admin
+e:x=admin
+e:r=admin
+e:n=admin
+e:a=admin
+e:t=admin
+c:setq=admin
+c:setc=admin
+c:seti=admin
+c:setx=admin
+c:setr=admin
+c:tpl=admin
+p=public
+p:x=public"
 
 _tg_cap_rank() {
     case "$1" in
@@ -13121,8 +13167,13 @@ _cb_render_user_detail() {
         _msg+="⏳ no expiry\n"
     fi
 
+    local _reset; _reset=$(_cb_quota_reset_day "$label")
+    [ -n "$_notes" ] && _msg+="📝 $(_esc "$_notes")\n"
+    [ -n "$_reset" ] && _msg+="🔁 Quota resets on day ${_reset}\n"
+
     _kb_reset
     _kb_row "🔄 Refresh|u:s:${label}:${page}" "🔗 Link|u:k:${label}"
+    _kb_row "$(_kb_spec "⚙️ Manage" "u" "m" "$label" "$page")"
     if [ "$_en" = "true" ]; then
         _cb_can a disable && _kb_row "⏸ Disable|a:disable:${label}" "$(_cb_can a rotate && printf '♻️ Rotate|a:rotate:%s' "$label")"
     else
@@ -13133,6 +13184,170 @@ _cb_render_user_detail() {
     _cb_edit "$_msg" "$(_kb_json)"
 }
 
+# "Label|payload", or "" when the payload cannot be encoded. One payload over
+# 64 bytes makes Telegram reject the WHOLE keyboard with a 400, so a button that
+# silently disappears is strictly better than a card that fails to render — but
+# only where the caller says so in the body. See _cb_render_tpl_picker.
+_kb_spec() {
+    local lbl="$1" p
+    p=$(_cb_enc "$2" "$3" "$4" "$5") || return 0
+    printf '%s|%s' "$lbl" "$p"
+}
+
+# Human text for a preset value. Values travel the wire in their raw form (the
+# callback charset has no room for "+", "∞" or a space), so the pretty form is
+# always computed here rather than stored.
+_cb_preset_label() {
+    case "$1" in
+        q|c|i) [ "$2" = "0" ] && printf '∞' || printf '%s' "$2" ;;
+        x)     [ "$2" = "0" ] && printf 'never' || printf '+%sd' "$2" ;;
+        *)     printf '%s' "$2" ;;
+    esac
+}
+
+_cb_render_user_manage() {
+    local label="$1" page="${2:-0}"
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _line _l _s _created _en _mc _mi _q _ex _notes _adtag
+    _line=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1)
+    IFS='|' read -r _l _s _created _en _mc _mi _q _ex _notes _adtag <<< "$_line"
+
+    local _reset; _reset=$(_cb_quota_reset_day "$label")
+
+    local _msg="⚙️ *Manage $(_esc "$label")*\n\n"
+    if [ -n "$_q" ] && [ "$_q" -gt 0 ] 2>/dev/null; then
+        _msg+="🧮 Quota: $(format_bytes "$_q")\n"
+    else
+        _msg+="🧮 Quota: unlimited\n"
+    fi
+    _msg+="🔌 Max connections: $([ -n "$_mc" ] && [ "$_mc" != "0" ] && printf '%s' "$_mc" || printf 'unlimited')\n"
+    _msg+="🌐 Max IPs: $([ -n "$_mi" ] && [ "$_mi" != "0" ] && printf '%s' "$_mi" || printf 'unlimited')\n"
+    _msg+="⏳ Expires: $(_cb_expiry_text "$_ex")\n"
+    _msg+="🔁 Quota reset: $([ -n "$_reset" ] && printf 'day %s' "$_reset" || printf 'off')\n"
+    _msg+="📝 Note: $([ -n "$_notes" ] && printf '%s' "$(_esc "$_notes")" || printf '_none_')\n"
+    _msg+="🏷 Ad-tag: $([ -n "$_adtag" ] && printf '`%s`' "$(_esc "$_adtag")" || printf '_global default_')"
+    # The expiry picker's relative presets and its "never" option mean different
+    # CLI verbs, so say which is which rather than making the operator guess.
+
+    _kb_reset
+    _kb_row "$(_kb_spec "🧮 Quota" "e" "q" "$label" "$page")" \
+            "$(_kb_spec "🔌 Conns" "e" "c" "$label" "$page")"
+    _kb_row "$(_kb_spec "🌐 IPs" "e" "i" "$label" "$page")" \
+            "$(_kb_spec "⏳ Expiry" "e" "x" "$label" "$page")"
+    _kb_row "$(_kb_spec "🔁 Reset day" "e" "r" "$label" "$page")" \
+            "$(_kb_spec "🧩 Template" "e" "t" "$label" "$page")"
+    _kb_row "$(_kb_spec "📝 Note" "e" "n" "$label" "$page")" \
+            "$(_kb_spec "🏷 Ad-tag" "e" "a" "$label" "$page")"
+    _kb_row "◀ Back|u:s:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The picker for one limit field. Every button commits through the per-field
+# CLI verb — never `secret setlimits`, whose zeroes mean "unlimited" and would
+# silently clear the fields the operator did not touch.
+_cb_render_limits() {
+    local field="$1" label="$2" page="${3:-0}" act title presets
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    case "$field" in
+        q) act="setq"; title="Quota";               presets="5G 10G 50G 100G 0" ;;
+        c) act="setc"; title="Max connections";     presets="5 10 20 50 0" ;;
+        i) act="seti"; title="Max IPs";             presets="1 3 5 10 0" ;;
+        x) act="setx"; title="Expiry";              presets="7 30 90 365 0" ;;
+        r) act="setr"; title="Quota reset day";     presets="1 15 28 off" ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+
+    local _msg="🧮 *${title} — $(_esc "$label")*\n\n"
+    case "$field" in
+        q) _msg+="_Pick a cap, or ∞ for no limit._" ;;
+        c) _msg+="_Telegram opens ~3 connections per device, so a cap under 5 will break a single client._" ;;
+        i) _msg+="_An IP cap is a weak anti-sharing measure: mobile clients roam between cells._" ;;
+        x) _msg+="_Relative presets extend from today. 'never' clears the date._" ;;
+        r) _msg+="_Resets the traffic counter on that day of each month._" ;;
+    esac
+
+    _kb_reset
+    # Two per row. Built as an array rather than a space-joined string: a spec
+    # containing a space would otherwise split into two bogus buttons.
+    local -a _specs=()
+    local _v _spec
+    for _v in $presets; do
+        _spec=$(_kb_spec "$(_cb_preset_label "$field" "$_v")" "c" "$act" "$label" "$_v")
+        [ -n "$_spec" ] && _specs+=("$_spec")
+        if [ "${#_specs[@]}" -eq 2 ]; then _kb_row "${_specs[@]}"; _specs=(); fi
+    done
+    [ "${#_specs[@]}" -gt 0 ] && _kb_row "${_specs[@]}"
+    # A value the presets do not cover. It arms a pending prompt rather than
+    # committing, because the grammar has no room for free text.
+    _kb_row "$(_kb_enc_custom "$label" "$field")"
+    _kb_row "◀ Back|u:m:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# "✏️ Custom…" — arms a pending prompt for a value the presets do not cover. The
+# field rides in the page slot so the flow keeps the label as its target, which
+# is what every other payload in this file does.
+_kb_enc_custom() {
+    local label="$1" field="$2" p
+    p=$(_cb_enc "e" "z" "$label" "$field") || return 0
+    printf '✏️ Custom…|%s' "$p"
+}
+
+# Templates that can be applied to this secret. A name that cannot survive the
+# callback charset is listed as text rather than as a button: _kb_spec drops
+# what it cannot encode, and a template the operator can see is unavailable
+# beats one that silently is not there.
+_cb_render_tpl_picker() {
+    local label="$1" page="${2:-0}" f="${INSTALL_DIR}/templates.conf" _t _rest
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _msg="🧩 *Apply a template to $(_esc "$label")*\n\n"
+    _kb_reset
+    local _n=0 _skipped=""
+    if [ -f "$f" ]; then
+        while IFS='|' read -r _t _rest; do
+            [ -z "$_t" ] && continue
+            if ! _cb_label_ok "$_t"; then _skipped+="${_t} "; continue; fi
+            _kb_row "$(_kb_spec "📋 $_t" "c" "tpl" "$label" "$_t")"
+            _n=$(( _n + 1 ))
+        done < "$f"
+    fi
+    if [ -n "$_skipped" ]; then
+        _msg+="_Not shown (name has characters a button cannot carry): ${_skipped}_\n\n"
+    fi
+    if [ "$_n" -eq 0 ]; then
+        _msg+="_Nothing to apply. Save one with_ \`mtproxymax template save <name> <conns> <ips> <quota> <expires>\`_._\n"
+    fi
+    _kb_row "◀ Back|u:m:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_quota_reset_day() {
+    local f="${INSTALL_DIR}/secrets_quota_reset.conf" _l _d
+    [ -f "$f" ] || return 0
+    while IFS='|' read -r _l _d; do
+        [ "$_l" = "$1" ] && { printf '%s' "$_d"; return 0; }
+    done < "$f"
+}
+
+_cb_expiry_text() {
+    local ex="$1" e days
+    if [ -z "$ex" ] || [ "$ex" = "0" ]; then printf 'never'; return 0; fi
+    e=$(_iso_to_epoch "$ex")
+    if [ "${e:-0}" -gt 0 ] 2>/dev/null; then
+        days=$(( (e - $(date +%s)) / 86400 ))
+        if [ "$days" -lt 0 ]; then printf 'expired (%s)' "$ex"
+        else printf 'in %sd (%s)' "$days" "$ex"; fi
+    else
+        printf '%s' "$ex"
+    fi
+}
+
 _cb_render_confirm() {
     local verb="$1" label="$2" page="${3:-0}" pretty=""
     case "$verb" in
@@ -13162,16 +13377,118 @@ _cb_render_confirm() {
     _cb_edit "$_msg" "$(_kb_json)"
 }
 
+# Arm a pending prompt for a limit value outside the preset set. The verb in the
+# store is the same one the preset commits through, so the typed value lands on
+# exactly the same validated path — the prompt is not a second, laxer way in.
+_cb_prompt_custom_limit() {
+    local label="$1" field="$2" act="" title=""
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    case "$field" in
+        q) act="setq"; title="quota (e.g. 250M, 2G, or 0 for unlimited)" ;;
+        c) act="setc"; title="maximum connections (a whole number, 0 for unlimited)" ;;
+        i) act="seti"; title="maximum unique IPs (a whole number, 0 for unlimited)" ;;
+        x) act="setx"; title="expiry as days from today (0 for never) or YYYY-MM-DD" ;;
+        r) act="setr"; title="quota reset day (1-28, or 'off')" ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+    _tg_pending_prompt "$_CB_CHAT" "$act" "$label" \
+        "✏️ *Custom ${act#set} for $(_esc "$label")*\n\nSend the value as a normal message — ${title}."
+    _CB_TOAST="Send the value"
+}
+
+# Validate and apply one limit change. Sets _CB_TOAST on failure; returns 0 when
+# the CLI accepted it.
+#
+# The value arrives through callback_data (attacker-controlled) or through the
+# pending store (a file on disk), so it is validated here rather than trusted.
+# Every field goes through the per-field `secret setlimit` verb and never
+# `secret setlimits`, whose zeroes read as "unlimited" and would silently clear
+# the fields the operator did not touch.
+_cb_apply_limit() {
+    local verb="$1" label="$2" value="$3"
+    case "$verb" in
+        setq)
+            [[ "$value" =~ ^[0-9]+[KMGTkmgt]?$ ]] || { _CB_TOAST="Enter a size like 250M or 2G"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" quota "$value" &>/dev/null \
+                && { _CB_TOAST="Quota updated"; return 0; }
+            ;;
+        setc)
+            { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 1000000 ]; } || { _CB_TOAST="Enter a number up to 1000000"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" conns "$value" &>/dev/null \
+                && { _CB_TOAST="Connection limit updated"; return 0; }
+            ;;
+        seti)
+            { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 100000 ]; } || { _CB_TOAST="Enter a number up to 100000"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" ips "$value" &>/dev/null \
+                && { _CB_TOAST="IP limit updated"; return 0; }
+            ;;
+        setx)
+            if [ "$value" = "0" ]; then
+                "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" expires 0 &>/dev/null \
+                    && { _CB_TOAST="Expiry cleared"; return 0; }
+            elif [[ "$value" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+                "${INSTALL_DIR}/mtproxymax" secret setlimit "$label" expires "$value" &>/dev/null \
+                    && { _CB_TOAST="Expiry set to ${value}"; return 0; }
+            elif [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 3650 ]; then
+                # Relative dates are the CLI's job: it already does the calendar
+                # arithmetic, including the short-month and timezone handling.
+                "${INSTALL_DIR}/mtproxymax" secret extend "$label" "$value" &>/dev/null \
+                    && { _CB_TOAST="Extended by ${value}d"; return 0; }
+            else
+                _CB_TOAST="Enter days (1-3650), YYYY-MM-DD, or 0 for never"
+                return 1
+            fi
+            ;;
+        setr)
+            case "$value" in
+                off) ;;
+                [0-9]|[12][0-9]) ;;
+                *) _CB_TOAST="Enter a day between 1 and 28, or 'off'"; return 1 ;;
+            esac
+            "${INSTALL_DIR}/mtproxymax" secret quota-reset "$label" "$value" &>/dev/null \
+                && { _CB_TOAST="Reset day updated"; return 0; }
+            ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    _CB_TOAST="Failed — check the server log"
+    return 1
+}
+
 # Only the c: namespace mutates anything. a: just renders a confirmation, so a
 # destructive action is never one mis-tap away.
+#
+# $3 is the origin list page for the secret verbs and the VALUE for the set-*
+# verbs: the grammar allows four fields and a commit needs both, so they share
+# the slot. The cost is that a limit change forgets which list page the operator
+# came from. Putting the value in the action instead would cost more — the
+# capability table matches exact keys and is what decides whether a tap is
+# allowed at all, so a dynamic action name could not be authorised.
 _cb_exec_action() {
     local verb="$1" label="$2" page="${3:-0}" out=""
     case "$verb" in
         enable|disable|rotate|remove) ;;
+        setq|setc|seti|setx|setr) ;;
         *) _CB_TOAST="Unknown action"; return 1 ;;
     esac
+    ! _cb_label_ok "$label" && { _CB_TOAST="Invalid label"; return 1; }
     ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
-    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+    # Only the secret verbs carry a page number. Coercing unconditionally here
+    # would flatten a limit value like "10G" or "off" to 0 before it was read.
+    case "$verb" in
+        enable|disable|rotate|remove) [[ "$page" =~ ^[0-9]+$ ]] || page=0 ;;
+    esac
+
+    case "$verb" in
+        setq|setc|seti|setx|setr)
+            # Applied, then the card is redrawn. A button tap is the only caller
+            # that wants a redraw — the pending-input path shares this validation
+            # and reports back in the chat instead, which is why the write lives
+            # in _cb_apply_limit rather than here.
+            _cb_apply_limit "$verb" "$label" "$page" || return 1
+            _cb_render_user_manage "$label" 0
+            return 0
+            ;;
+    esac
 
     if [ "$verb" = "remove" ]; then
         if out=$("${INSTALL_DIR}/mtproxymax" secret remove "$label" 2>&1); then
@@ -13343,11 +13660,30 @@ _cb_dispatch() {
                 l) _cb_render_user_list "${_CB_TGT:-0}" ;;
                 s) _cb_render_user_detail "$_CB_TGT" "${_CB_PAGE:-0}" ;;
                 k) _cb_send_link "$_CB_TGT" ;;
+                m) _cb_render_user_manage "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                *) _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        e)
+            # One namespace for "edit a property of this secret". The page slot
+            # is the origin card for the pickers and the field code for the
+            # custom-value prompt, so it is read per action rather than once.
+            case "$_CB_ACT" in
+                q|c|i|x|r) _cb_render_limits "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                z) _cb_prompt_custom_limit "$_CB_TGT" "${_CB_PAGE:-}" ;;
+                t) _cb_render_tpl_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
                 *) _CB_TOAST="Unknown action" ;;
             esac
             ;;
         a) _cb_render_confirm "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
         c) _cb_exec_action "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+        p)
+            # The prompt's own Cancel button. It clears whatever is armed for
+            # THIS chat and nothing else — _CB_CHAT comes from the callback,
+            # which Telegram authenticates, never from callback_data.
+            _tg_pending_clear "$_CB_CHAT"
+            _CB_TOAST="Cancelled"
+            ;;
         t) _cb_render_traffic "${_CB_TGT:-24h}" ;;
         y) _cb_render_engine ;;
         s) _cb_render_settings ;;
diff --git a/tests/test_telegram_callback_dispatch.sh b/tests/test_telegram_callback_dispatch.sh
index 8988df9..61c3d7e 100644
--- a/tests/test_telegram_callback_dispatch.sh
+++ b/tests/test_telegram_callback_dispatch.sh
@@ -245,7 +245,14 @@ cap_leaks() {
                 [ "$cap" = "superadmin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
             a:enable|a:disable|a:rotate|c:enable|c:disable|c:rotate|u:l|u:s|t|t:w|t:u|y|y:e|s)
                 [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
-            n|m|m:h)
+            # Per-secret management. Every one of these mirrors an admin-tier
+            # CLI verb (secret setlimit / extend / quota-reset / template apply),
+            # and none of them is reachable by a reseller, whose only surface
+            # stays the voucher commands.
+            u:m|e|e:q|e:c|e:i|e:x|e:r|e:n|e:a|e:t|e:z|\
+            c:setq|c:setc|c:seti|c:setx|c:setr|c:tpl)
+                [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            n|m|m:h|p|p:x)
                 [ "$cap" = "public" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
             *)
                 printf 'unclassified:%s\n' "$key" ;;
diff --git a/tests/test_telegram_per_secret_views.sh b/tests/test_telegram_per_secret_views.sh
new file mode 100644
index 0000000..778948a
--- /dev/null
+++ b/tests/test_telegram_per_secret_views.sh
@@ -0,0 +1,223 @@
+#!/bin/bash
+# Tests for the per-secret management surface: the manage card, the limit
+# pickers behind it, and the commits those buttons make.
+#
+# The behaviour that matters most here is the WRITE PATH. The obvious way to set
+# one limit is `secret setlimits <label> <conns> <ips> <quota> <expires>`, but
+# secret_set_limits reads "0" as UNLIMITED, not as "leave alone" — so tapping
+# "quota: 10G" through that verb would silently wipe the connection and IP caps
+# too. Every commit below therefore has to reach the per-field
+# `secret setlimit <label> <field> <value>` form, and the assertions pin that.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01|the note|%s\n' \
+    "$(printf 'a%.0s' $(seq 1 32))" "$(printf 'f%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+printf 'bob|%s|1700000000|false|0|0|0|0||\n' "$(printf 'b%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+# ── Extract the shipped menu block ───────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+# ── Stubs ────────────────────────────────────────────────────────────────────
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+EDITS="$TEST_TMPDIR/edits.log"
+ROLE_TO_RETURN="superadmin"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$SENDS"; }
+tg_answer_cb() { :; }
+tg_edit() { printf '%s\n---\n%s\n' "$3" "$4" > "$EDITS"; }
+tg_edit_markup() { printf 'markup\n---\n%s\n' "$3" > "$EDITS"; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+_tg_have_python() { return 1; }
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+_UI_ROLE="superadmin"
+_CB_CHAT="111"; _CB_MID="77"
+
+render() {   # render <ns> <act> <tgt> <page>
+    : > "$EDITS"
+    _cb_dispatch_prepare "$1" "$2" "$3" "$4"
+    _cb_dispatch >/dev/null 2>&1
+    cat "$EDITS"
+}
+# Drive the dispatcher the way a real tap does: through the codec, so the
+# payload is validated exactly as it would be in production.
+_cb_dispatch_prepare() {
+    local p
+    p=$(_cb_enc "$1" "$2" "$3" "$4") || { _CB_DATA=""; return 1; }
+    _CB_DATA="$p"
+    _CB_NS="$1"; _CB_ACT="$2"; _CB_TGT="$3"; _CB_PAGE="$4"
+    _CB_CHAT="111"; _CB_MID="77"; _CB_TOAST=""; _CB_ALERT="false"
+}
+commit() {   # commit <act> <label> <value> -> manager calls
+    : > "$CALLS"
+    _cb_dispatch_prepare "c" "$1" "$2" "$3"
+    _cb_dispatch >/dev/null 2>&1
+    cat "$CALLS"
+}
+
+# ── The manage card is reachable from the user card ──────────────────────────
+_out=$(render "u" "s" "alice" "0")
+assert_contains "user card offers a manage entry" "u:m:alice:0" "$_out"
+
+_out=$(render "u" "m" "alice" "0")
+assert_contains "manage card offers the quota picker"  "e:q:alice:0" "$_out"
+assert_contains "manage card offers the conns picker"  "e:c:alice:0" "$_out"
+assert_contains "manage card offers the IPs picker"    "e:i:alice:0" "$_out"
+assert_contains "manage card offers the expiry picker" "e:x:alice:0" "$_out"
+assert_contains "manage card offers the note prompt"   "e:n:alice:0" "$_out"
+assert_contains "manage card offers the adtag prompt"  "e:a:alice:0" "$_out"
+assert_contains "manage card offers the template picker" "e:t:alice:0" "$_out"
+assert_contains "manage card goes back to the user card" "u:s:alice:0" "$_out"
+# The card is where the current values are read, so they have to be on it.
+assert_contains "manage card shows the current quota" "10.00 GB" "$_out"
+assert_contains "manage card shows the current conn cap" "7" "$_out"
+assert_contains "manage card shows the note" "the note" "$_out"
+
+# ── Pickers offer presets, and every payload is one Telegram will accept ─────
+for _f in q c i x r; do
+    _out=$(render "e" "$_f" "alice" "0")
+    _bad=""
+    while IFS= read -r _p; do
+        [ -z "$_p" ] && continue
+        case "$_p" in
+            c:*) ;;
+            *) continue ;;
+        esac
+        [ "${#_p}" -le 64 ] || _bad="${_bad} len:${_p}"
+        _cb_dec "$_p" || _bad="${_bad} unparseable:${_p}"
+    done < <(printf '%s' "$_out" | grep -oE 'c:[A-Za-z0-9_:.-]+')
+    assert_eq "every $_f preset is a payload Telegram will accept" "" "$_bad"
+    assert_not_contains "$_f picker draws no code box" '```' "$_out"
+done
+
+_out=$(render "e" "q" "alice" "0")
+assert_contains "quota picker offers 10G"   "c:setq:alice:10G" "$_out"
+assert_contains "quota picker offers unlimited" "c:setq:alice:0" "$_out"
+assert_contains "quota picker goes back to the manage card" "u:m:alice:0" "$_out"
+
+_out=$(render "e" "x" "alice" "0")
+assert_contains "expiry picker offers 30 days" "c:setx:alice:30" "$_out"
+assert_contains "expiry picker offers never"   "c:setx:alice:0" "$_out"
+
+_out=$(render "e" "r" "alice" "0")
+assert_contains "reset picker offers day 15" "c:setr:alice:15" "$_out"
+assert_contains "reset picker offers off"    "c:setr:alice:off" "$_out"
+
+# ── Commits hit the per-field verb, and only that field ──────────────────────
+assert_eq "quota commit uses the per-field verb" \
+    "secret setlimit alice quota 10G" "$(commit "setq" "alice" "10G")"
+assert_eq "conns commit uses the per-field verb" \
+    "secret setlimit alice conns 50" "$(commit "setc" "alice" "50")"
+assert_eq "IPs commit uses the per-field verb" \
+    "secret setlimit alice ips 5" "$(commit "seti" "alice" "5")"
+assert_eq "unlimited quota commits as 0" \
+    "secret setlimit alice quota 0" "$(commit "setq" "alice" "0")"
+
+# The whole reason for the per-field verb: setlimits with a 0 would read as
+# "unlimited" for the fields the tap never mentioned.
+assert_not_contains "a quota change never calls setlimits" \
+    "setlimits" "$(commit "setq" "alice" "10G")"
+
+# Expiry is relative ("+30d") for a real date and absolute ("never") for 0, and
+# the CLI already has a verb for the relative case.
+assert_eq "a relative expiry extends rather than rewriting limits" \
+    "secret extend alice 30" "$(commit "setx" "alice" "30")"
+assert_eq "never expiry clears the date" \
+    "secret setlimit alice expires 0" "$(commit "setx" "alice" "0")"
+
+assert_eq "reset-day commit reaches the CLI" \
+    "secret quota-reset alice 15" "$(commit "setr" "alice" "15")"
+assert_eq "reset-day off reaches the CLI" \
+    "secret quota-reset alice off" "$(commit "setr" "alice" "off")"
+
+# ── Bad input cannot reach the CLI ───────────────────────────────────────────
+assert_eq "an unknown commit verb is refused" "" "$(commit "setz" "alice" "10G")"
+assert_eq "a non-numeric conns value is refused" "" "$(commit "setc" "alice" "lots")"
+assert_eq "a non-numeric quota value is refused" "" "$(commit "setq" "alice" "abc")"
+assert_eq "a nonsense reset day is refused" "" "$(commit "setr" "alice" "99")"
+assert_eq "a missing label is refused" "" "$(commit "setq" "" "10G")"
+
+# ── A label off disk is re-validated before it is used as a pattern ──────────
+# The label comes back out of callback_data, which is attacker-controlled, and
+# out of secrets.conf, which is hand-editable. Neither is trusted.
+assert_eq "a label that is not a label never reaches the CLI" "" "$(commit "setq" "../../etc" "10G")"
+
+# ── RBAC: every action above is known to the capability table ────────────────
+_missing=""
+# Note and ad-tag are pending-input flows rather than c: commits (their text
+# cannot ride in callback_data), so they are entered through e: and not listed
+# here — _tg_pending_run owns their write path.
+for _k in u:m e:q e:c e:i e:x e:r e:n e:a e:t e:z c:setq c:setc c:seti c:setx c:setr c:tpl p:x; do
+    _ns="${_k%%:*}"; _act="${_k#*:}"
+    [ -n "$(_tg_cap_for "$_ns" "$_act")" ] || _missing="${_missing} ${_k}"
+done
+assert_eq "every new action has a capability" "" "$_missing"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]

From 00487594cd8b362ea4c19371112aee3162448b06 Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Fri, 18 Sep 2026 08:42:08 +0300
Subject: [PATCH 06/10] feat(telegram): reach every command from the buttons
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Completes the parity goal: an operator should never have to remember a command.
The hub gains Server, Templates and Tools sections, and the views behind them
cover what /mp_digest, /mp_upstreams, /mp_fleet, /mp_voucher, /mp_update,
/mp_add, /mp_broadcast, /mp_restart, /mp_update and /mp_lockdown used to be the
only route to.

Global verbs. Rotate-all, restart, update and lockdown act on the server rather
than on one secret, so they have no label. They carry "_" as a placeholder, and
that placeholder is matched ONLY for these four — a secret genuinely called "_"
is legal and keeps its enable/disable/rotate/remove verbs. All four go through a
confirmation; the confirm tap is the only thing that performs the write, and the
test pins that the first tap runs nothing.

Templates are now editable, not just applicable. templates.conf rows are
"name|conns|ips|quota|expires|notes" and the CLI's `template save` overwrites by
name, so an edit is a read-modify-write that must carry the fields it did not
touch — notes and expiry being the easiest two to lose, since they are the last
columns. The rebuild reads and writes in one call for that reason.

/help is now rendered from `telegram commands`, which prints the same TG_CMDS_*
lists that are registered with Telegram. The old view was a hand-maintained
string that had already drifted: it advertised commands that no longer existed
and missed ones that did.

Two bugs found while wiring this up, both silent:

  - /mp_digest called load_ssl_config, load_speed_limits and
    load_cloud_backup_config, which are manager-only. Inside the daemon they are
    command-not-found under 2>/dev/null, so the digest advertised an SSL Shield
    and a Cloud Backup status it could never read. The new digest view shows
    only the settings the daemon genuinely loads.
  - _kb_can was written where _cb_can was meant in the template editor, so the
    Apply and Delete buttons never rendered at all.
---
 README.md                                |  26 +
 mtproxymax.sh                            | 613 ++++++++++++++++++++++-
 tests/test_telegram_callback_dispatch.sh |   8 +
 tests/test_telegram_menu_render.sh       |  38 +-
 tests/test_telegram_parity.sh            | 244 +++++++++
 5 files changed, 909 insertions(+), 20 deletions(-)
 create mode 100644 tests/test_telegram_parity.sh

diff --git a/README.md b/README.md
index a73b1d4..b73252f 100644
--- a/README.md
+++ b/README.md
@@ -454,6 +454,32 @@ mtproxymax telegram sync-commands
 | `/mp_update` | Check for updates |
 | `/mp_help` | Show all commands |
 
+#### 🎛 Running the proxy from buttons
+
+Every command above also exists as a button, so day-to-day management needs no
+typing. Send any command — or tap **🏠 Menu** on any reply — to open the hub:
+
+| Section | What it covers |
+|---------|----------------|
+| 👥 **Users** | Paginated list → per-user card with live connections, traffic, quota bar, expiry, note and quota-reset day, plus link/QR, enable, disable, rotate and remove |
+| ⚙️ **Manage** (per user) | Quota, connection cap, IP cap, expiry, monthly quota-reset day, note, ad-tag, and applying a saved limit template to that user |
+| 🧩 **Templates** | Create, edit every field of, apply and delete limit templates |
+| 📈 **Traffic** | Windowed totals (24h / 7d / 30d) with a sparkline, peak and average rate, and top talkers |
+| 🖥 **Server** | Engine health, posture digest, upstreams, fleet, vouchers, updates |
+| 🛠 **Tools** | Add user, broadcast, rotate-all, lockdown, restart, apply update |
+| ⚙️ **Settings** | Port, domain, metrics port, report interval |
+
+Limits are edited with preset buttons for the common values, plus a **✏️ Custom…**
+prompt for anything else. Anything that affects live users — removing, rotating,
+disabling, restarting, locking down — asks for confirmation first, and the
+confirmation is the only path that performs the write.
+
+**Typed input.** Adding a user, setting a custom limit, saving a template name,
+broadcasting and writing a note all need text, which buttons cannot supply. Tapping
+one of those sends a prompt; your next message is taken as the answer. The prompt is
+always escapable: sending any `/command` cancels it, and so does the **❌ Cancel**
+button. An unanswered prompt expires after five minutes.
+
 **Automatic alerts & announcements:**
 - 🚨 Emergency Lockdown activated → immediate posture alert
 - 📢 System Broadcasts (`mtproxymax broadcast <msg>`) sent directly to admin chat
diff --git a/mtproxymax.sh b/mtproxymax.sh
index 8d817f4..7f1ef4e 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -11112,6 +11112,27 @@ _tg_set_commands() {
 # Push the whole menu: public commands for everyone, the admin control plane for
 # admins, and the privileged commands for superadmins. Entirely best-effort — a
 # network failure must never abort setup or the bot daemon.
+# Print the registered command list for a role, as "command|description" lines.
+#
+# The bot daemon cannot read TG_CMDS_* itself — they live here, outside the
+# heredoc it is generated from, and it deliberately re-runs `telegram
+# sync-commands` on boot rather than keeping a copy that could drift. Its /help
+# view calls this instead, so the list a user is shown and the list Telegram is
+# told about are the same bytes.
+telegram_print_commands() {
+    case "${1:-admin}" in
+        public) printf '%s\n' "$TG_CMDS_PUBLIC" ;;
+        # A reseller reaches the public surface plus the voucher engine, which
+        # is exactly the allowlist _process_cmd applies to that role.
+        reseller)
+            printf '%s\n' "$TG_CMDS_PUBLIC"
+            printf 'mp_voucher|Generate or list vouchers\n'
+            ;;
+        superadmin) printf '%s\n' "$TG_CMDS_SUPERADMIN" ;;
+        *) printf '%s\n' "$TG_CMDS_ADMIN" ;;
+    esac
+}
+
 telegram_sync_commands() {
     local cid role _rest
     [ "${TELEGRAM_ENABLED:-false}" = "true" ] || return 0
@@ -12831,6 +12852,65 @@ _tg_pending_run() {
             fi
             tg_send_to "$chat" "✅ Secret *$(_esc "$value")* created.$(_tg_new_secret_link "$value")"
             ;;
+        note|adtag)
+            # target is the label, read back out of a file on disk, so it is
+            # re-validated here exactly as it was on the way in.
+            if ! _cb_label_ok "$target" || ! _cb_secret_exists "$target"; then
+                tg_send_to "$chat" "❌ That secret no longer exists."
+                return 1
+            fi
+            if [ "$verb" = "adtag" ]; then
+                # 32 hex is what the engine accepts; "clear" reverts to the
+                # global tag. Anything else would be written and then ignored.
+                if [ "$value" != "clear" ] && ! [[ "$value" =~ ^[0-9a-fA-F]{32}$ ]]; then
+                    tg_send_to "$chat" "❌ An ad-tag must be 32 hex characters, or 'clear'."
+                    return 1
+                fi
+            fi
+            if "${INSTALL_DIR}/mtproxymax" secret "$verb" "$target" "$value" &>/dev/null; then
+                tg_send_to "$chat" "✅ ${verb} updated for *$(_esc "$target")*."
+            else
+                tg_send_to "$chat" "❌ Could not update the ${verb}."
+                return 1
+            fi
+            ;;
+        tplnew)
+            # "name" or "name conns ips quota expires". read rather than word
+            # splitting: an unquoted expansion would let a "*" in the text glob
+            # against the working directory.
+            local _nm _c _i _q _e
+            read -r _nm _c _i _q _e <<< "$value"
+            if ! _cb_label_ok "$_nm"; then
+                tg_send_to "$chat" "❌ Use letters, digits, '_' and '-' only, max 32 characters."
+                return 1
+            fi
+            if "${INSTALL_DIR}/mtproxymax" template save "$_nm" "${_c:-0}" "${_i:-0}" "${_q:-0}" "${_e:-0}" "" &>/dev/null; then
+                tg_send_to "$chat" "✅ Template *$(_esc "$_nm")* saved. Open *Templates* to tune each field."
+            else
+                tg_send_to "$chat" "❌ Could not save the template."
+                return 1
+            fi
+            ;;
+        tplnotes|tplexpires)
+            if ! _cb_label_ok "$target" || ! _cb_tpl_exists "$target"; then
+                tg_send_to "$chat" "❌ That template no longer exists."
+                return 1
+            fi
+            [ "$verb" = "tplnotes" ] && _cb_tpl_set "$target" notes "$value" || _cb_tpl_set "$target" expires "$value"
+            tg_send_to "$chat" "✅ Template *$(_esc "$target")* updated."
+            ;;
+        broadcast)
+            if [ -z "$value" ]; then
+                tg_send_to "$chat" "❌ Nothing to broadcast."
+                return 1
+            fi
+            if "${INSTALL_DIR}/mtproxymax" broadcast "$value" &>/dev/null; then
+                tg_send_to "$chat" "📢 Broadcast dispatched."
+            else
+                tg_send_to "$chat" "❌ Broadcast failed."
+                return 1
+            fi
+            ;;
         setq|setc|seti|setx|setr)
             # target is the label. It came out of a file on disk, so it is
             # re-validated here exactly as it was on the way in.
@@ -12923,7 +13003,30 @@ c:setx=admin
 c:setr=admin
 c:tpl=admin
 p=public
-p:x=public"
+p:x=public
+k=admin
+k:e=admin
+k:p=admin
+k:a=admin
+k:s=admin
+k:d=admin
+k:n=admin
+g=admin
+g:a=admin
+g:b=admin
+y:d=admin
+y:p=admin
+y:f=admin
+y:v=admin
+y:u=admin
+a:rotall=superadmin
+c:rotall=superadmin
+a:restart=superadmin
+c:restart=superadmin
+a:update=superadmin
+c:update=superadmin
+a:lockdown=superadmin
+c:lockdown=superadmin"
 
 _tg_cap_rank() {
     case "$1" in
@@ -13041,25 +13144,39 @@ _cb_render_hub() {
     _msg+="\n👥 $(get_active_connections) live connections"
     _msg+="\n\nChoose a view:"
     _kb_reset
-    local u_row="" t_row="" y_row=""
-    _cb_can u l && u_row="👥 Users|u:l:0"
-    _cb_can t && t_row="📈 Traffic|t"
-    _cb_can y && y_row="🩺 Health|y"
-    _kb_row "$u_row" "$t_row"
-    _kb_row "$y_row" "$(_cb_can s && printf '⚙️ Settings|s')"
+    _kb_row "$(_cb_can u l && printf '👥 Users|u:l:0')" "$(_cb_can t && printf '📈 Traffic|t')"
+    _kb_row "$(_cb_can y && printf '🖥 Server|y')"     "$(_cb_can k && printf '🧩 Templates|k')"
+    _kb_row "$(_cb_can g && printf '🛠 Tools|g')"      "$(_cb_can s && printf '⚙️ Settings|s')"
     _kb_row "❓ Help|m:h"
     _cb_edit "$_msg" "$(_kb_json)"
 }
 
+# The list is rendered from the same source Telegram is told about, fetched
+# over the CLI. The old version was a hand-maintained string that had already
+# drifted from TG_CMDS_* — it advertised commands that no longer existed and
+# missed ones that did.
 _cb_render_help() {
-    local _msg="📋 *Commands*\n\n"
-    _msg+="/mp\\_status — proxy status\n"
-    _msg+="/mp\\_secrets — list secrets\n"
-    _msg+="/mp\\_traffic — traffic report\n"
-    _msg+="/mp\\_add <label> — add a secret\n"
-    _msg+="/mp\\_remove <label> — remove a secret\n"
-    _msg+="/mp\\_help — full list\n\n"
-    _msg+="The buttons below are the same thing, minus the typing."
+    local _case="admin"
+    case "${_UI_ROLE:-none}" in
+        superadmin) _case="superadmin" ;;
+        reseller)   _case="reseller" ;;
+        *)          _case="public" ;;
+    esac
+
+    local out
+    out=$("${INSTALL_DIR}/mtproxymax" telegram commands "$_case" 2>/dev/null)
+    # An underscore in a command name is Markdown emphasis, so the leading slash
+    # has to be escaped or "/mp_status" renders as "/mp" + italic "status".
+    out=$(printf '%s' "$out" | sed 's|^|/|; s|_|\\_|g')
+
+    local _msg="📋 *Commands*"
+    if [ -n "$out" ]; then
+        _msg+="\n\n${out}"
+    else
+        _msg+="\n\n_Command list unavailable — try_ \`mtproxymax telegram sync-commands\`_._"
+    fi
+    _msg+="\n\n_Every one of these is also a button. Send any command to get the menu._"
+
     _kb_reset
     _kb_row "🏠 Menu|m"
     _cb_edit "$_msg" "$(_kb_json)"
@@ -13297,6 +13414,165 @@ _kb_enc_custom() {
     printf '✏️ Custom…|%s' "$p"
 }
 
+# ── Limit templates ─────────────────────────────────────────────────────────
+#
+# templates.conf holds "name|conns|ips|quota|expires|notes", and the CLI's
+# `template save` already overwrites by name — so editing a template is a
+# read-modify-write that rebuilds the row with one field replaced. No new CLI
+# verb is needed, but the rebuild has to carry the fields it did not touch:
+# template_save replaces the whole row, so a stale or mis-split read would
+# quietly reset notes and expiry, the two easiest columns to lose.
+
+_cb_tpl_get() {   # <name> <field 1..6> -> value, "" if absent
+    local f="${INSTALL_DIR}/templates.conf" _n _c _i _q _e _notes
+    [ -f "$f" ] || return 0
+    while IFS='|' read -r _n _c _i _q _e _notes; do
+        [ "$_n" = "$1" ] || continue
+        case "$2" in
+            1) printf '%s' "$_n" ;; 2) printf '%s' "$_c" ;; 3) printf '%s' "$_i" ;;
+            4) printf '%s' "$_q" ;; 5) printf '%s' "$_e" ;; 6) printf '%s' "$_notes" ;;
+        esac
+        return 0
+    done < "$f"
+}
+
+_cb_tpl_exists() {
+    [ -n "$1" ] && [ -f "${INSTALL_DIR}/templates.conf" ] && \
+        grep -qE "^$1\|" "${INSTALL_DIR}/templates.conf" 2>/dev/null
+}
+
+# Write the row back with one field replaced. Reads inside the same call that
+# writes it, so the fields the operator did not touch are the ones on disk now.
+_cb_tpl_set() {   # <name> <slot> <value>; slot = conns|ips|quota|expires|notes
+    local name="$1" slot="$2" value="$3"
+    local _c _i _q _e _notes
+    _c=$(_cb_tpl_get "$name" 2); _i=$(_cb_tpl_get "$name" 3)
+    _q=$(_cb_tpl_get "$name" 4); _e=$(_cb_tpl_get "$name" 5)
+    _notes=$(_cb_tpl_get "$name" 6)
+    case "$slot" in
+        conns)   _c="$value" ;;
+        ips)     _i="$value" ;;
+        quota)   _q="$value" ;;
+        expires) _e="$value" ;;
+        notes)   _notes="$value" ;;
+        *) return 1 ;;
+    esac
+    "${INSTALL_DIR}/mtproxymax" template save "$name" "${_c:-0}" "${_i:-0}" "${_q:-0}" "${_e:-0}" "${_notes:-}" &>/dev/null
+}
+
+_cb_render_tpl_list() {
+    local f="${INSTALL_DIR}/templates.conf" _msg="🧩 *Limit templates*\n" _n=0 _t _rest _skipped=""
+    _kb_reset
+    if [ -f "$f" ]; then
+        while IFS='|' read -r _t _rest; do
+            [ -z "$_t" ] && continue
+            # A name outside the callback charset cannot be a button. Say so in
+            # the body rather than letting _kb_spec drop it without a trace.
+            if ! _cb_label_ok "$_t"; then _skipped+="${_t} "; continue; fi
+            _kb_row "$(_kb_spec "📋 $_t" "k" "e" "$_t" "0")"
+            _n=$(( _n + 1 ))
+        done < "$f"
+    fi
+    if [ -n "$_skipped" ]; then
+        _msg+="\n_Not shown (name has characters a button cannot carry): ${_skipped}_"
+    fi
+    if [ "$_n" -eq 0 ]; then
+        _msg+="\n_Nothing saved yet._"
+    fi
+    _msg+="\n\n_A template is a named bundle of limits you can apply to any secret._"
+    _kb_row "$(_cb_can k n && printf '➕ New template|k:n')"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_tpl_edit() {
+    local name="$1" page="${2:-0}" _c _i _q _e _notes
+    ! _cb_tpl_exists "$name" && { _CB_TOAST="Template '$name' not found"; return 1; }
+    _c=$(_cb_tpl_get "$name" 2); _i=$(_cb_tpl_get "$name" 3)
+    _q=$(_cb_tpl_get "$name" 4); _e=$(_cb_tpl_get "$name" 5)
+    _notes=$(_cb_tpl_get "$name" 6)
+
+    local _msg="🧩 *$(_esc "$name")*\n\n"
+    _msg+="🔌 Max connections: $([ -n "$_c" ] && [ "$_c" != "0" ] && printf '%s' "$_c" || printf 'unlimited')\n"
+    _msg+="🌐 Max IPs: $([ -n "$_i" ] && [ "$_i" != "0" ] && printf '%s' "$_i" || printf 'unlimited')\n"
+    _msg+="🧮 Quota: $([ -n "$_q" ] && [ "$_q" != "0" ] && printf '%s' "$(format_bytes "$_q")" || printf 'unlimited')\n"
+    _msg+="⏳ Expires: $(_cb_expiry_text "$_e")\n"
+    _msg+="📝 Notes: $([ -n "$_notes" ] && printf '%s' "$(_esc "$_notes")" || printf '_none_')"
+
+    _kb_reset
+    _kb_row "$(_kb_spec "🔌 Conns" "k" "p" "$name" "c")" "$(_kb_spec "🌐 IPs" "k" "p" "$name" "i")"
+    _kb_row "$(_kb_spec "🧮 Quota" "k" "p" "$name" "q")" "$(_kb_spec "⏳ Expires" "k" "p" "$name" "x")"
+    _kb_row "$(_kb_spec "📝 Notes" "k" "p" "$name" "n")"
+    _kb_row "$(_cb_can k s && printf '✨ Apply to a user…|k:s:%s:0' "$name")"
+    _kb_row "$(_cb_can k d && printf '🗑 Delete|k:d:%s:0' "$name")"
+    _kb_row "◀ Back|k"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The preset picker for one template field. Commits straight to c:tplset rather
+# than through a confirmation: this edits a stored template, which changes
+# nothing for a connected user and is one tap from being undone. The confirm
+# rule is for actions that touch live secrets.
+_cb_render_tpl_field() {
+    local name="$1" field="$2"
+    ! _cb_tpl_exists "$name" && { _CB_TOAST="Template '$name' not found"; return 1; }
+
+    local slot presets title hint
+    case "$field" in
+        c) slot="conns";   presets="5 10 20 50 0";   title="Max connections"; hint="Telegram opens ~3 connections per device." ;;
+        i) slot="ips";     presets="1 3 5 10 0";     title="Max IPs";          hint="A secondary anti-sharing measure." ;;
+        q) slot="quota";   presets="5G 10G 50G 100G 0"; title="Quota";         hint="0 means unlimited." ;;
+        x) slot="expires"; presets="0";              title="Expires";          hint="A date is set per user when the template is applied; type one to change it." ;;
+        n) slot="notes";   presets="";               title="Notes";            hint="Free text." ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+
+    if [ "$field" = "n" ]; then
+        # Notes has no useful presets, so it goes straight to a typed prompt.
+        _tg_pending_prompt "$_CB_CHAT" "tplnotes" "$name" \
+            "📝 *Notes for template $(_esc "$name")*\n\nSend the text to store."
+        _CB_TOAST="Send the note"
+        return 0
+    fi
+    if [ "$field" = "x" ]; then
+        _tg_pending_prompt "$_CB_CHAT" "tplexpires" "$name" \
+            "⏳ *Expiry for template $(_esc "$name")*\n\nSend a date as YYYY-MM-DD, or 0 for none."
+        _CB_TOAST="Send the date"
+        return 0
+    fi
+
+    local _msg="🧩 *${title} — $(_esc "$name")*\n\n_${hint}_"
+    _kb_reset
+    local -a _specs=()
+    local _v _spec
+    for _v in $presets; do
+        _spec=$(_kb_spec "$(_cb_preset_label "$field" "$_v")" "c" "tplset" "$name" "${field}${_v}")
+        [ -n "$_spec" ] && _specs+=("$_spec")
+        if [ "${#_specs[@]}" -eq 2 ]; then _kb_row "${_specs[@]}"; _specs=(); fi
+    done
+    [ "${#_specs[@]}" -gt 0 ] && _kb_row "${_specs[@]}"
+    _kb_row "◀ Back|k:e:${name}:0"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_tpl_apply_picker() {
+    local name="$1" page="${2:-0}" _t
+    ! _cb_tpl_exists "$name" && { _CB_TOAST="Template '$name' not found"; return 1; }
+
+    local _msg="✨ *Apply $(_esc "$name") to…*\n" _n=0
+    _kb_reset
+    while IFS='|' read -r _l _rest; do
+        [[ "$_l" =~ ^# ]] && continue
+        [ -z "$_l" ] && continue
+        _cb_label_ok "$_l" || continue
+        _kb_row "$(_kb_spec "👤 $_l" "c" "tpl" "$_l" "$name")"
+        _n=$(( _n + 1 ))
+    done < "$SECRETS_FILE"
+    [ "$_n" -eq 0 ] && _msg+="\n_No secrets to apply it to._"
+    _kb_row "◀ Back|k:e:${name}:0"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
 # Templates that can be applied to this secret. A name that cannot survive the
 # callback charset is listed as text rather than as a button: _kb_spec drops
 # what it cannot encode, and a template the operator can see is unavailable
@@ -13355,12 +13631,32 @@ _cb_render_confirm() {
         disable) pretty="Disable" ;;
         rotate)  pretty="Rotate" ;;
         remove)  pretty="Remove" ;;
+        rotall)  pretty="Rotate all secrets" ;;
+        restart) pretty="Restart the proxy" ;;
+        update)  pretty="Apply the update" ;;
+        lockdown)
+            case "$label" in
+                on)  pretty="Activate lockdown" ;;
+                off) pretty="Lift lockdown" ;;
+                *) _CB_TOAST="Unknown mode"; return 1 ;;
+            esac ;;
         *) _CB_TOAST="Unknown action"; return 1 ;;
     esac
-    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+
+    # The global verbs are targetless. "_" is their placeholder, and it is
+    # matched here rather than treated as a label so that a secret genuinely
+    # named "_" is still a secret for enable/disable/rotate/remove.
+    case "$verb" in
+        rotall|restart|update|lockdown) label="" ;;
+    esac
+    [ -n "$label" ] && ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
 
     local _extra=""
     case "$verb" in
+        rotall)  _extra="\n\nEvery client on every secret will have to reconnect." ;;
+        restart) _extra="\n\nThe proxy is briefly unreachable to all users." ;;
+        update)  _extra="\n\nThe installed script is replaced and the proxy may restart." ;;
+        lockdown) _extra="\n\nThis hardens the kernel posture and tightens the proxy immediately." ;;
         disable)
             local _c=0
             while IFS='|' read -r _ml _mc2 _mi2; do
@@ -13454,6 +13750,69 @@ _cb_apply_limit() {
     return 1
 }
 
+# One field of a stored template, encoded as "<field-letter><value>" so a field
+# name and its value fit in the single slot the grammar has left.
+_cb_exec_tplset() {
+    local name="$1" spec="$2" field="${2:0:1}" value="${2:1}"
+    case "$field" in
+        c) { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 1000000 ]; } || { _CB_TOAST="Enter a number up to 1000000"; return 1; }
+           _cb_tpl_set "$name" conns "$value" ;;
+        i) { [[ "$value" =~ ^[0-9]+$ ]] && [ "$value" -le 100000 ]; } || { _CB_TOAST="Enter a number up to 100000"; return 1; }
+           _cb_tpl_set "$name" ips "$value" ;;
+        q) [[ "$value" =~ ^[0-9]+[KMGTkmgt]?$ ]] || { _CB_TOAST="Enter a size like 250M or 2G"; return 1; }
+           _cb_tpl_set "$name" quota "$value" ;;
+        *) _CB_TOAST="Unknown field"; return 1 ;;
+    esac
+    _CB_TOAST="Saved"
+    return 0
+}
+
+# The verbs that act on the server rather than on one secret. They have no
+# label, and for lockdown the second field is a mode rather than a page number.
+_cb_exec_global() {
+    local verb="$1" arg="$2" out=""
+    case "$verb" in
+        rotall)
+            if out=$("${INSTALL_DIR}/mtproxymax" secret rotate --all 2>&1); then
+                _CB_TOAST="All secrets rotated"
+            else
+                _CB_TOAST="Rotate-all failed"
+            fi
+            _cb_render_tools
+            ;;
+        restart)
+            if "${INSTALL_DIR}/mtproxymax" restart &>/dev/null; then
+                _CB_TOAST="Restarting"
+            else
+                _CB_TOAST="Restart failed"
+            fi
+            _cb_render_tools
+            ;;
+        update)
+            out=$("${INSTALL_DIR}/mtproxymax" update </dev/null 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | tail -5)
+            _CB_TOAST="Update finished"
+            _cb_render_update "$out"
+            ;;
+        lockdown)
+            case "$arg" in
+                on|off) ;;
+                *) _CB_TOAST="Unknown lockdown mode"; return 1 ;;
+            esac
+            if "${INSTALL_DIR}/mtproxymax" lockdown "$arg" &>/dev/null; then
+                _CB_TOAST="Lockdown ${arg}"
+                # LOCKDOWN_MODE is read by the renderers; reload it so the tools
+                # card reflects the change on the very next draw.
+                load_tg_settings
+            else
+                _CB_TOAST="Lockdown failed"
+            fi
+            _cb_render_tools
+            ;;
+        *) _CB_TOAST="Unknown action"; return 1 ;;
+    esac
+    return 0
+}
+
 # Only the c: namespace mutates anything. a: just renders a confirmation, so a
 # destructive action is never one mis-tap away.
 #
@@ -13466,6 +13825,53 @@ _cb_apply_limit() {
 _cb_exec_action() {
     local verb="$1" label="$2" page="${3:-0}" out=""
     case "$verb" in
+        rotall|restart|update|lockdown)
+            # Targetless global verbs run before the label checks below: they
+            # have no secret to validate, and for lockdown the second field is
+            # the mode ("on"/"off") rather than a page.
+            _cb_exec_global "$verb" "$label"
+            return $?
+            ;;
+        tpl)
+            # Apply a stored template to a secret. The template name rides in
+            # the page slot, so both names have to survive the callback budget;
+            # _kb_spec drops the button when they cannot.
+            ! _cb_label_ok "$label" && { _CB_TOAST="Invalid label"; return 1; }
+            ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+            ! _cb_tpl_exists "$page" && { _CB_TOAST="Template '$page' not found"; return 1; }
+            if "${INSTALL_DIR}/mtproxymax" template apply "$page" "$label" &>/dev/null; then
+                _CB_TOAST="Applied"
+                _cb_render_user_manage "$label" 0
+            else
+                _CB_TOAST="Failed"
+                _cb_render_user_manage "$label" 0
+            fi
+            return 0
+            ;;
+        tplset)
+            # One field of a stored template. page is "<field-letter><value>".
+            ! _cb_tpl_exists "$label" && { _CB_TOAST="Template '$label' not found"; return 1; }
+            _cb_exec_tplset "$label" "$page" || return 1
+            _cb_render_tpl_edit "$label" 0
+            return 0
+            ;;
+        tplnew)
+            # Named only; the values come from the editor afterwards. A name is
+            # typed, so this is reached through the pending prompt rather than a
+            # button — the branch stays for completeness and tests.
+            ! _cb_label_ok "$page" && { _CB_TOAST="Invalid template name"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" template save "$page" 0 0 0 0 "" &>/dev/null \
+                && _CB_TOAST="Created" || _CB_TOAST="Failed"
+            _cb_render_tpl_edit "$page" 0
+            return 0
+            ;;
+        tpldel)
+            ! _cb_tpl_exists "$label" && { _CB_TOAST="Template '$label' not found"; return 1; }
+            "${INSTALL_DIR}/mtproxymax" template delete "$label" &>/dev/null \
+                && _CB_TOAST="Deleted" || _CB_TOAST="Failed"
+            _cb_render_tpl_list
+            return 0
+            ;;
         enable|disable|rotate|remove) ;;
         setq|setc|seti|setx|setr) ;;
         *) _CB_TOAST="Unknown action"; return 1 ;;
@@ -13564,7 +13970,139 @@ _cb_render_engine() {
         _msg+=$'\n'
     fi
     _kb_reset
-    _kb_row "🔄 Refresh|y" "🏠 Menu|m"
+    _kb_row "🔄 Refresh|y"        "$(_cb_can y d && printf '📊 Digest|y:d')"
+    _kb_row "$(_cb_can y p && printf '🌐 Upstreams|y:p')" "$(_cb_can y f && printf '🛰 Fleet|y:f')"
+    _kb_row "$(_cb_can y v && printf '🎟 Vouchers|y:v')"  "$(_cb_can y u && printf '⬆️ Updates|y:u')"
+    _kb_row "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The posture half of what /mp_digest used to render. The three load_*() calls
+# the old handler made are manager-only and were silent no-ops inside the daemon
+# — so it advertised an SSL Shield and a Cloud Backup status it could never
+# actually read. Only the settings the daemon genuinely loads are shown.
+_cb_render_digest() {
+    local _ip _up=0 _rc=0 _st _qos _hh _msg
+    _ip=$(get_cached_ip)
+    is_proxy_running && { _up=$(get_container_uptime); _rc=$(get_active_connections); }
+    _st="🟢 NORMAL"; [ "${LOCKDOWN_MODE:-false}" = "true" ] && _st="🔴 LOCKDOWN ACTIVE"
+    _qos="off"; [ "${QOS_LIMIT_MBPS:-0}" -gt 0 ] 2>/dev/null && _qos="${QOS_LIMIT_MBPS} Mbps/IP"
+    _hh="off"; [ -n "${HAPPY_HOURS_WINDOW:-}" ] && _hh="${HAPPY_HOURS_WINDOW}"
+
+    local _total=0 _active=0 _l _en _rest
+    while IFS='|' read -r _l _s _c _en _rest; do
+        [[ "$_l" =~ ^# ]] && continue
+        [ -z "$_l" ] && continue
+        _total=$(( _total + 1 ))
+        [ "$_en" = "true" ] && _active=$(( _active + 1 ))
+    done < "$SECRETS_FILE"
+
+    _msg="📊 *Digest*\n\n"
+    _msg+="🖥 Server: \`$(_esc "${_ip:-unknown}")\` (port ${PROXY_PORT:-?})\n"
+    _msg+="⚡️ Posture: ${_st}\n"
+    _msg+="⏱ Uptime: $(format_duration "${_up:-0}")\n"
+    _msg+="🔌 Connections: ${_rc} live\n"
+    _msg+="🏎 QoS shaping: ${_qos}\n"
+    _msg+="🕒 Happy hours: ${_hh}\n"
+    _msg+="🎫 Secrets: ${_active} active of ${_total}\n"
+    _msg+="📈 Total traffic: ↓ $(format_bytes "${_cum_out:-0}") ↑ $(format_bytes "${_cum_in:-0}")"
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_upstreams() {
+    local uf="${INSTALL_DIR}/upstreams.conf" _msg="🌐 *Upstreams*\n"
+    if [ ! -f "$uf" ]; then
+        _msg+="\n🟢 direct — all traffic leaves from this server."
+    else
+        local name type addr user pass weight iface enabled icon
+        while IFS='|' read -r name type addr user pass weight iface enabled; do
+            [[ "$name" =~ ^# ]] && continue
+            [ -z "$name" ] && continue
+            # Backward compat: the old 7-column layout kept `enabled` in field 7.
+            if [ "$iface" = "true" ] || [ "$iface" = "false" ]; then enabled="$iface"; iface=""; fi
+            icon="🟢"; [ "$enabled" != "true" ] && icon="🔴"
+            _msg+="\n${icon} *$(_esc "$name")* — ${type}"
+            [ -n "$addr" ] && _msg+=" \`$(_esc "$addr")\`"
+            [ -n "$iface" ] && _msg+=" [${iface}]"
+            _msg+=" · weight ${weight:-?}"
+        done < "$uf"
+    fi
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_fleet() {
+    local out
+    out=$("${INSTALL_DIR}/mtproxymax" fleet status 2>/dev/null | sed 's/\x1b\[[0-9;]*m//g')
+    local _msg="🛰 *Fleet*" _n=0 _f _h _ip _users _traffic _load
+    if [ -n "$out" ]; then
+        while IFS= read -r _f; do
+            case "$_f" in ""|HOSTNAME*|*"---"*) continue ;; esac
+            read -r _h _ip _users _traffic _load _ <<< "$_f"
+            [ -z "$_h" ] && continue
+            _msg+="\n🟢 *$(_esc "$_h")*"
+            [ -n "$_ip" ] && _msg+=" — \`$(_esc "$_ip")\`"
+            [ -n "$_users" ] && _msg+=" · 👥 ${_users}"
+            [ -n "$_traffic" ] && _msg+=" · 📊 ${_traffic}"
+            _n=$(( _n + 1 ))
+        done <<< "$out"
+    fi
+    [ "$_n" -eq 0 ] && _msg+="\n\n_No multi-server telemetry collected yet._"
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+_cb_render_vouchers() {
+    local body _msg
+    body=$(_tg_voucher_lines)
+    if [ -n "$body" ]; then
+        _msg="🎟 *Active vouchers*${body}"
+    else
+        _msg="🎟 *Active vouchers*\n\n_None yet. Create them from the CLI with_ \`mtproxymax voucher create\`_._"
+    fi
+    _kb_reset
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# The update check is read-only; applying it is a separate, confirmed action.
+_cb_render_update() {
+    local out="$1" _msg="⬆️ *Updates*" _l
+    if [ -n "$out" ]; then
+        while IFS= read -r _l; do
+            [ -z "$_l" ] && continue
+            _msg+="\n• $(_esc "$_l")"
+        done <<< "$out"
+    else
+        _msg+="\n\n_No output from the update check._"
+    fi
+    _kb_reset
+    _kb_row "$(_cb_can a update && printf '⬆️ Apply update|a:update:_')"
+    _kb_row "◀ Back|y" "🏠 Menu|m"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
+# Everything that needs typed input, plus the three global verbs. The global
+# verbs are targetless, so they carry "_" where a secret label would go; the
+# dispatcher special-cases that placeholder for these verbs ONLY, so a secret
+# genuinely called "_" keeps working.
+_cb_render_tools() {
+    local _msg="🛠 *Tools*\n\n_Each of these needs something typed, or affects the whole server._"
+    _kb_reset
+    _kb_row "$(_cb_can g a && printf '➕ Add user|g:a')"   "$(_cb_can g b && printf '📢 Broadcast|g:b')"
+    _kb_row "$(_cb_can a rotall && printf '♻️ Rotate all|a:rotall:_')"
+    if [ "${LOCKDOWN_MODE:-false}" = "true" ]; then
+        _cb_can a lockdown && _kb_row "🔓 Lift lockdown|a:lockdown:off"
+    else
+        _cb_can a lockdown && _kb_row "🔒 Lockdown|a:lockdown:on"
+    fi
+    _kb_row "$(_cb_can a restart && printf '🔄 Restart proxy|a:restart:_')" \
+            "$(_cb_can a update  && printf '⬆️ Apply update|a:update:_')"
+    _kb_row "🏠 Menu|m"
     _cb_edit "$_msg" "$(_kb_json)"
 }
 
@@ -13672,6 +14210,12 @@ _cb_dispatch() {
                 q|c|i|x|r) _cb_render_limits "$_CB_ACT" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
                 z) _cb_prompt_custom_limit "$_CB_TGT" "${_CB_PAGE:-}" ;;
                 t) _cb_render_tpl_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                n) ! _cb_secret_exists "$_CB_TGT" && { _CB_TOAST="Secret not found"; } || \
+                   _tg_pending_prompt "$_CB_CHAT" "note" "$_CB_TGT" \
+                       "📝 *Note for $(_esc "$_CB_TGT")*\n\nSend the text to store. Send \`-\` to clear it." ;;
+                a) ! _cb_secret_exists "$_CB_TGT" && { _CB_TOAST="Secret not found"; } || \
+                   _tg_pending_prompt "$_CB_CHAT" "adtag" "$_CB_TGT" \
+                       "🏷 *Ad-tag for $(_esc "$_CB_TGT")*\n\nSend the 32-hex tag from \@MTProxybot, or \`clear\` to fall back to the global tag." ;;
                 *) _CB_TOAST="Unknown action" ;;
             esac
             ;;
@@ -13684,8 +14228,40 @@ _cb_dispatch() {
             _tg_pending_clear "$_CB_CHAT"
             _CB_TOAST="Cancelled"
             ;;
+        g)
+            case "$_CB_ACT" in
+                a) _tg_pending_prompt "$_CB_CHAT" "add" "-" "➕ *Add a user*\n\nSend the new secret's label." ;;
+                b) _tg_pending_prompt "$_CB_CHAT" "broadcast" "-" "📢 *Broadcast*\n\nSend the message to deliver to every known bot user." ;;
+                "") _cb_render_tools ;;
+                *) _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
+        k)
+            case "$_CB_ACT" in
+                "")  _cb_render_tpl_list ;;
+                e)   _cb_render_tpl_edit "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                p)   _cb_render_tpl_field "$_CB_TGT" "${_CB_PAGE:-}" ;;
+                s)   _cb_render_tpl_apply_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                a)   _cb_render_tpl_apply_picker "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                d)   _cb_render_confirm "tpldel" "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                n)   _tg_pending_prompt "$_CB_CHAT" "tplnew" "-" "🧩 *New template*\n\nSend a name (letters, digits, '_', '-'), and optionally the values on the same line: \`name conns ips quota expires\`." ;;
+                *)   _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
         t) _cb_render_traffic "${_CB_TGT:-24h}" ;;
-        y) _cb_render_engine ;;
+        y)
+            case "$_CB_ACT" in
+                "")  _cb_render_engine ;;
+                d)   _cb_render_digest ;;
+                p)   _cb_render_upstreams ;;
+                f)   _cb_render_fleet ;;
+                v)   _cb_render_vouchers ;;
+                # Read-only: the CLI's `update` APPLIES the update, so the check
+                # only reports what is installed and offers the apply button.
+                u)   _cb_render_update "Installed version: ${VERSION}" ;;
+                *)   _CB_TOAST="Unknown action" ;;
+            esac
+            ;;
         s) _cb_render_settings ;;
         *) _CB_TOAST="This menu is out of date — send /menu" ;;
     esac
@@ -17513,6 +18089,7 @@ cli_main() {
             case "${1:-status}" in
                 setup)   check_root; telegram_setup_wizard ;;
                 sync-commands) check_root; telegram_sync_commands ;;
+                commands) telegram_print_commands "${2:-admin}" ;;
                 test)    telegram_test_message ;;
                 status|"")
                     if [ "$TELEGRAM_ENABLED" != "true" ]; then
diff --git a/tests/test_telegram_callback_dispatch.sh b/tests/test_telegram_callback_dispatch.sh
index 61c3d7e..cbcde57 100644
--- a/tests/test_telegram_callback_dispatch.sh
+++ b/tests/test_telegram_callback_dispatch.sh
@@ -252,6 +252,14 @@ cap_leaks() {
             u:m|e|e:q|e:c|e:i|e:x|e:r|e:n|e:a|e:t|e:z|\
             c:setq|c:setc|c:seti|c:setx|c:setr|c:tpl)
                 [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            # The server console and the template section: read-mostly views
+            # mirroring admin-tier CLI verbs.
+            y:d|y:p|y:f|y:v|y:u|g|g:a|g:b|k|k:e|k:p|k:a|k:s|k:d|k:n)
+                [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
+            # The four verbs _process_cmd re-checks superadmin for inline:
+            # /mp_remove, /mp_restart, /mp_update, /mp_lockdown.
+            a:rotall|c:rotall|a:restart|c:restart|a:update|c:update|a:lockdown|c:lockdown)
+                [ "$cap" = "superadmin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
             n|m|m:h|p|p:x)
                 [ "$cap" = "public" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
             *)
diff --git a/tests/test_telegram_menu_render.sh b/tests/test_telegram_menu_render.sh
index 0c00c49..1f19621 100644
--- a/tests/test_telegram_menu_render.sh
+++ b/tests/test_telegram_menu_render.sh
@@ -26,6 +26,12 @@ for _i in $(seq 1 13); do
     printf 'user%02d|%s|1700000000|%s|0|0|0|0||\n' "$_i" "$(printf '%032d' "$_i")" "$_state" >> "$SECRETS_FILE"
 done
 
+# One well-formed template, plus one whose name can never be a button payload —
+# the second is what proves the list says so instead of dropping it silently.
+TEMPLATES_FILE="$INSTALL_DIR/templates.conf"
+printf 'vip|100|5|53687091200|2027-01-01|top tier\n' > "$TEMPLATES_FILE"
+printf 'not a button|10|2|1073741824|0|x\n' >> "$TEMPLATES_FILE"
+
 MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
 set +e
 trap 'rm -rf "$TEST_TMPDIR"' EXIT
@@ -49,7 +55,7 @@ telegram_generate_service_script
 DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
 FNS="$TEST_TMPDIR/daemon-fns.sh"
 : > "$FNS"
-for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec; do
+for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec _esc _iso_to_epoch; do
     awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
 done
 awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
@@ -64,6 +70,14 @@ tg_edit_markup() { printf '%s' "$3" > "$EDIT"; }
 tg_answer_cb() { :; }
 tg_send_to() { :; }
 tg_send() { :; }
+# The server-console views read live state; the render test only cares about
+# their SHAPE, so these answer with fixed values rather than reaching for
+# docker or the metrics endpoint.
+get_uptime() { echo "98201"; }
+get_active_connections() { echo "3"; }
+get_cached_ip() { echo "203.0.113.9"; }
+is_proxy_running() { return 0; }
+get_container_uptime() { echo "98201"; }
 load_tg_settings() { :; }
 is_running() { return 1; }
 get_cached_ip() { echo "203.0.113.9"; }
@@ -84,6 +98,23 @@ render() {
         traffic)  _cb_render_traffic 24h ;;
         engine)   _cb_render_engine ;;
         settings) _cb_render_settings ;;
+        manage)   _cb_render_user_manage "${3:-user01}" "${4:-0}" ;;
+        limits_q) _cb_render_limits q "${3:-user01}" "${4:-0}" ;;
+        limits_c) _cb_render_limits c "${3:-user01}" "${4:-0}" ;;
+        limits_i) _cb_render_limits i "${3:-user01}" "${4:-0}" ;;
+        limits_x) _cb_render_limits x "${3:-user01}" "${4:-0}" ;;
+        limits_r) _cb_render_limits r "${3:-user01}" "${4:-0}" ;;
+        tpl_list)   _cb_render_tpl_list ;;
+        tpl_edit)   _cb_render_tpl_edit "${3:-vip}" 0 ;;
+        tpl_field)  _cb_render_tpl_field "${3:-vip}" "${4:-q}" ;;
+        tpl_apply)  _cb_render_tpl_apply_picker "${3:-vip}" 0 ;;
+        tpl_picker) _cb_render_tpl_picker "${3:-user01}" 0 ;;
+        tools)     _cb_render_tools ;;
+        digest)    _cb_render_digest ;;
+        upstreams) _cb_render_upstreams ;;
+        fleet)     _cb_render_fleet ;;
+        vouchers)  _cb_render_vouchers ;;
+        update)    _cb_render_update "Installed version: test" ;;
     esac
     cat "$EDIT"
 }
@@ -92,7 +123,10 @@ cbs_of() { printf '%s' "$1" | grep -o '"callback_data":"[^"]*"' | sed 's/.*:"//;
 
 echo "Telegram menu render tests"
 
-VIEWS="hub help list detail confirm traffic engine settings"
+VIEWS="hub help list detail confirm traffic engine settings manage \
+limits_q limits_c limits_i limits_x limits_r \
+tpl_list tpl_edit tpl_field tpl_apply tpl_picker \
+tools digest upstreams fleet vouchers update"
 
 # ── Every view for every role is structurally sound ──────────────────────────
 for _role in superadmin reseller operator; do
diff --git a/tests/test_telegram_parity.sh b/tests/test_telegram_parity.sh
new file mode 100644
index 0000000..bee7724
--- /dev/null
+++ b/tests/test_telegram_parity.sh
@@ -0,0 +1,244 @@
+#!/bin/bash
+# Tests that every administrative command has a button route.
+#
+# The point of the button surface is that an operator never has to remember a
+# command, so a command that is reachable ONLY by typing is a gap, not a
+# nicety. The parity map is asserted directly: for each command there is a
+# payload somewhere in the menu graph that reaches the same CLI verb.
+#
+# The global verbs (rotate-all, restart, update, lockdown) are the dangerous
+# ones: they are targetless, so they carry a "_" placeholder where a secret
+# label would go, and they must stay behind a confirmation.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+TEMPLATES_FILE="$INSTALL_DIR/templates.conf"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+# A secret genuinely called "_" — the global verbs use "_" as a placeholder for
+# "no label", and that must not take this secret's verbs away from it.
+printf '_|%s|1700000000|true|0|0|0|0||\n' "$(printf '9%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+printf 'vip|100|5|50G|2027-01-01|top tier\n' > "$TEMPLATES_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+EDITS="$TEST_TMPDIR/edits.log"
+ROLE_TO_RETURN="superadmin"
+
+_check_tg_role() { echo "$ROLE_TO_RETURN"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s|%s\n' "$1" "$2" "$3" >> "$SENDS"; }
+tg_answer_cb() { :; }
+tg_edit() { printf '%s\n---\n%s\n' "$3" "$4" > "$EDITS"; }
+tg_edit_markup() { printf 'markup\n---\n%s\n' "$3" > "$EDITS"; }
+load_tg_settings() { :; }
+is_running() { return 0; }
+is_proxy_running() { return 0; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+get_stats() { echo "1024 2048 7"; }
+get_uptime() { echo "98123"; }
+get_active_connections() { echo "7"; }
+get_container_uptime() { echo "98123"; }
+get_cum_user_traffic() { echo "1024 2048"; }
+format_duration() { echo "1d 3h 15m"; }
+_tg_metrics_raw() { printf ''; }
+_tg_have_python() { return 1; }
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+case "$1" in
+    telegram)
+        # The /help view renders from the same list Telegram is told about,
+        # rather than a hand-maintained copy that can drift from it.
+        case "$2" in
+            commands)
+                printf 'mp_status|Proxy status\nmp_add|Add a new secret (usage: /mp_add <label>)\n'
+                ;;
+        esac
+        ;;
+esac
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+_UI_ROLE="superadmin"
+_CB_CHAT="111"; _CB_MID="77"
+
+prepare() {
+    local p
+    p=$(_cb_enc "$1" "$2" "$3" "$4") || { _CB_DATA=""; return 1; }
+    _CB_DATA="$p"; _CB_NS="$1"; _CB_ACT="$2"; _CB_TGT="$3"; _CB_PAGE="$4"
+    _CB_CHAT="111"; _CB_MID="77"; _CB_TOAST=""; _CB_ALERT="false"
+    : > "$EDITS"; : > "$CALLS"; : > "$SENDS"
+}
+render() { prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1; cat "$EDITS"; }
+commit() { prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1; cat "$CALLS"; }
+toast()  { prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1; printf '%s' "$_CB_TOAST"; }
+
+# ── The hub reaches every section ────────────────────────────────────────────
+_out=$(render "m" "" "" "")
+assert_contains "hub offers users"     "u:l:0" "$_out"
+assert_contains "hub offers traffic"   "t"     "$_out"
+assert_contains "hub offers the server console" "y" "$_out"
+assert_contains "hub offers templates" "k"     "$_out"
+assert_contains "hub offers tools"     "g"     "$_out"
+assert_contains "hub offers settings"  "s"     "$_out"
+assert_contains "hub offers help"      "m:h"   "$_out"
+assert_not_contains "hub draws no code box" '```' "$_out"
+
+# ── The server console reaches everything /mp_status, /mp_digest,
+#    /mp_upstreams and /mp_fleet used to be the only route to ────────────────
+_out=$(render "y" "" "" "")
+assert_contains "server console reaches the digest"    "y:d" "$_out"
+assert_contains "server console reaches upstreams"     "y:p" "$_out"
+assert_contains "server console reaches fleet"         "y:f" "$_out"
+assert_contains "server console reaches vouchers"      "y:v" "$_out"
+assert_contains "server console reaches the update check" "y:u" "$_out"
+
+for _v in d p f v u; do
+    _out=$(render "y" "$_v" "" "")
+    assert_not_contains "server sub-view $_v draws no code box" '```' "$_out"
+done
+
+# ── Tools reach the commands that need typed input ───────────────────────────
+_out=$(render "g" "" "" "")
+assert_contains "tools offer adding a user"   "g:a"   "$_out"
+assert_contains "tools offer rotate-all"      "a:rotall:_" "$_out"
+assert_contains "tools offer a broadcast"     "g:b"   "$_out"
+assert_contains "tools offer quarantine"      "a:lockdown:on" "$_out"
+assert_not_contains "tools do not execute lockdown on a single tap" "c:lockdown:on" "$_out"
+assert_contains "tools offer restart"         "a:restart:_" "$_out"
+assert_contains "tools offer update"          "a:update:_" "$_out"
+
+# ── Global verbs: confirmed first, and reaching the right CLI verb ───────────
+assert_contains "rotate-all asks first" "Rotate all" "$(render "a" "rotall" "_" "")"
+assert_eq "rotate-all does not run on the confirm tap" "" "$(cat "$CALLS")"
+assert_contains "restart asks first" "Restart" "$(render "a" "restart" "_" "")"
+assert_eq "restart does not run on the confirm tap" "" "$(cat "$CALLS")"
+
+assert_eq "rotate-all runs the bulk verb" "secret rotate --all" "$(commit "c" "rotall" "_" "")"
+assert_eq "restart runs the service verb" "restart"             "$(commit "c" "restart" "_" "")"
+assert_eq "update runs the self-update verb" "update"           "$(commit "c" "update" "_" "")"
+assert_eq "lockdown on reaches the CLI"  "lockdown on"          "$(commit "c" "lockdown" "on" "")"
+assert_eq "lockdown off reaches the CLI" "lockdown off"         "$(commit "c" "lockdown" "off" "")"
+assert_eq "a nonsense lockdown mode is refused" "" "$(commit "c" "lockdown" "maybe" "")"
+
+# The "_" placeholder must not leak into the secret verbs: a secret genuinely
+# named "_" is legal, and "disable _" must still mean that secret.
+assert_eq "a secret named _ is still a secret" \
+    "secret disable _" "$(commit "c" "disable" "_" "0")"
+
+# ── Typed-input flows arm a prompt and then land on the right verb ───────────
+arm() {   # arm <ns> <act> <tgt> <page> -> pending store line
+    prepare "$1" "$2" "$3" "$4" && _cb_dispatch >/dev/null 2>&1
+    cat "$INSTALL_DIR/relay_stats/.tg_pending" 2>/dev/null
+}
+
+assert_contains "add-user arms a prompt"   "|add|-|"    "$(arm "g" "a" "" "")"
+assert_contains "broadcast arms a prompt"  "|broadcast|-|" "$(arm "g" "b" "" "")"
+assert_contains "note arms a prompt"       "|note|alice|" "$(arm "e" "n" "alice" "0")"
+assert_contains "ad-tag arms a prompt"     "|adtag|alice|" "$(arm "e" "a" "alice" "0")"
+
+# And the typed answer reaches the matching CLI verb.
+answer() {   # answer <text>
+    : > "$CALLS"; : > "$SENDS"
+    _tg_pending_try "111" "$1" >/dev/null 2>&1
+    cat "$CALLS"
+}
+arm "e" "n" "alice" "0" >/dev/null
+assert_eq "a typed note reaches the note verb" "secret note alice hello there" "$(answer "hello there")"
+
+arm "e" "a" "alice" "0" >/dev/null
+assert_eq "a typed ad-tag reaches the adtag verb" \
+    "secret adtag alice 0123456789abcdef0123456789abcdef" "$(answer "0123456789abcdef0123456789abcdef")"
+
+arm "e" "a" "alice" "0" >/dev/null
+assert_eq "an ad-tag that is not 32 hex is refused" "" "$(answer "not-a-tag")"
+
+arm "g" "b" "" "" >/dev/null
+assert_eq "a typed broadcast reaches the broadcast verb" "broadcast hello all" "$(answer "hello all")"
+
+# A prompt for a secret that has since been removed must not write to it.
+arm "e" "n" "ghost" "0" >/dev/null
+assert_eq "a note for a removed secret is refused" "" "$(answer "hi")"
+
+# ── The escape hatch still works with these flows armed ──────────────────────
+arm "e" "n" "alice" "0" >/dev/null
+: > "$CALLS"
+_tg_pending_try "111" "/mp_status" >/dev/null 2>&1
+assert_eq "a command escapes the note prompt" "" "$(cat "$CALLS")"
+
+# ── The help view is the real command list, not a hand-kept copy ─────────────
+_out=$(render "m" "h" "" "")
+assert_contains "help lists the registered commands" "mp\\_status" "$_out"
+assert_contains "help lists the usage text too" "Add a new secret" "$_out"
+assert_not_contains "help escapes the underscores Telegram would italicise" "/mp_status" "$_out"
+assert_not_contains "help draws no code box" '```' "$_out"
+
+# ── Every action the new views can emit is known to the capability table ─────
+_missing=""
+for _k in m y:d y:p y:f y:v y:u g g:a g:b a:rotall c:rotall a:restart c:restart \
+          a:update c:update a:lockdown c:lockdown; do
+    _ns="${_k%%:*}"; _act="${_k#*:}"
+    [ "$_act" = "$_ns" ] && _act=""
+    [ -n "$(_tg_cap_for "$_ns" "$_act")" ] || _missing="${_missing} ${_k}"
+done
+assert_eq "every new global action has a capability" "" "$_missing"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]

From e35ff1c50178d70a354bea7f03c61ac66dfc1386 Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Sat, 19 Sep 2026 08:25:02 +0300
Subject: [PATCH 07/10] fix(telegram): stop /mp_setlimit wiping limits, and
 stop posting the key to a QR service
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two pre-existing bugs the button work exposed but did not cause.

/mp_setlimit cleared limits it was not asked to touch. It called
`secret setlimits <label> <conns> <ips> <quota> <expires>`, but an omitted
field arrives as 0, and secret_set_limits reads 0 as UNLIMITED rather than
"leave alone" — so `/mp_setlimit alice 100` also removed alice's IP cap and
quota. Each provided field now goes through the per-field
`secret setlimit <label> <field> <value>` verb, which touches one field and no
other. Every field but the last is applied with --no-restart so a multi-field
change still costs a single engine sync.

The QR code handed the credential to a third party. The proxy link IS the key —
server, port and secret — and it was posted to api.qrserver.com for Telegram to
fetch, on every /mp_link, every /start, and every voucher redemption, including
in the customer's own chat. The same URL was embedded in the exported HTML
sheets and the QR sent after Telegram setup.

It is now rendered on this host, by qrencode or python3-qrcode, and uploaded as
a multipart file (the Bot API only fetches a URL itself, which is exactly the
capability we are removing). The HTML sheets embed the image as a data: URI so
they stay self-contained.

When neither renderer is present the bot sends the tappable link instead. It
deliberately does NOT fall back to a remote renderer: the whole point is that
the key stays on the machine, and a fallback would silently reintroduce the
leak on exactly the minimal hosts least likely to notice.

The three URL-passing photo senders (tg_send_photo, tg_send_photo_to,
telegram_send_photo) and generate_qr_url are removed rather than left in place.
They existed only to serve this path, and an obviously-named helper sitting
unused is how the exposure would come back.

The QR test pins the behaviour by capturing curl's argv and its -K config
separately: the upload must be multipart, must target sendPhoto, must carry the
chat id, and the bot token must appear in the config and NOT in argv.
---
 mtproxymax.sh                        | 235 +++++++++++++++++++++------
 tests/test_telegram_qr_and_limits.sh | 198 ++++++++++++++++++++++
 2 files changed, 383 insertions(+), 50 deletions(-)
 create mode 100644 tests/test_telegram_qr_and_limits.sh

diff --git a/mtproxymax.sh b/mtproxymax.sh
index 7f1ef4e..ace9846 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -3471,8 +3471,13 @@ secret_generate_links() {
                 local label="${SECRETS_LABELS[$i]}"
                 local fs; fs=$(build_faketls_secret "${SECRETS_KEYS[$i]}")
                 local link="https://t.me/proxy?server=${server_ip}&port=${PROXY_PORT}&secret=${fs}"
-                local qr_url="https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=$(printf '%s' "$link" | sed 's/:/%3A/g;s|/|%2F|g;s/?/%3F/g;s/=/%3D/g;s/&/%26/g')"
-                echo "<div class='user'><h2>${label}</h2><a href='${link}'>${link}</a><br><img src='${qr_url}' alt='QR'></div>"
+                # Rendered here and inlined: pointing <img> at a remote
+                # renderer would post this user's key to it every time the sheet
+                # is opened. Empty means no renderer — the link above still works.
+                local qr_url; qr_url=$(_qr_data_uri "$link")
+                local qr_tag=""
+                [ -n "$qr_url" ] && qr_tag="<br><img src='${qr_url}' alt='QR'>"
+                echo "<div class='user'><h2>${label}</h2><a href='${link}'>${link}</a>${qr_tag}</div>"
             done
             echo "</body></html>"
         } > "$outfile"
@@ -6579,12 +6584,17 @@ EOF
         local label="${SECRETS_LABELS[$i]}"
         local sec="${SECRETS_KEYS[$i]}"
         local tg_url="tg://proxy?server=${ip}&port=${port}&secret=${sec}"
-        local qr_api="https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=${tg_url}"
-        
+        # Inlined rather than fetched: see _qr_data_uri.
+        local qr_api; qr_api=$(_qr_data_uri "$tg_url")
+
         echo "<div class='card'>" >> "$outfile"
         echo "  <h3>${label}</h3>" >> "$outfile"
         echo "  <p>High-Speed MTProto Proxy</p>" >> "$outfile"
-        echo "  <div class='qr-box'><img src='${qr_api}' alt='QR Code' width='150' height='150'></div>" >> "$outfile"
+        if [ -n "$qr_api" ]; then
+            echo "  <div class='qr-box'><img src='${qr_api}' alt='QR Code' width='150' height='150'></div>" >> "$outfile"
+        else
+            echo "  <p><small>No QR renderer on the server — install <code>qrencode</code> to include codes.</small></p>" >> "$outfile"
+        fi
         echo "  <p>Scan with Telegram Camera</p>" >> "$outfile"
         echo "</div>" >> "$outfile"
     done
@@ -9693,12 +9703,49 @@ secret_qr() {
 }
 
 
-# Generate QR code URL (for Telegram photo messages)
-generate_qr_url() {
-    local link="$1"
-    local encoded
-    encoded=$(printf '%s' "$link" | sed 's/&/%26/g; s/?/%3F/g; s/=/%3D/g; s/:/%3A/g; s|/|%2F|g')
-    echo "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${encoded}"
+# Render a QR to a PNG on this host. Non-zero when no renderer is available.
+#
+# Duplicated from the bot daemon on purpose: the daemon is generated as a
+# self-contained script and never sources this one, which is the same reason
+# format_bytes and friends appear in both.
+_qr_png() {
+    local data="$1" out="$2"
+    [ -n "$data" ] && [ -n "$out" ] || return 1
+    if command -v qrencode &>/dev/null; then
+        qrencode -o "$out" -s 6 -m 2 "$data" 2>/dev/null && [ -s "$out" ] && return 0
+    fi
+    if command -v python3 &>/dev/null && python3 -c '' &>/dev/null 2>&1 && \
+       python3 -c 'import qrcode' &>/dev/null; then
+        python3 - "$data" "$out" <<'PYQ' 2>/dev/null && [ -s "$out" ] && return 0
+import sys
+import qrcode
+qrcode.make(sys.argv[1]).save(sys.argv[2])
+PYQ
+    fi
+    rm -f "$out" 2>/dev/null
+    return 1
+}
+
+# A self-contained <img> source for a QR, or "" when nothing can render one.
+#
+# The exported HTML sheets used to point <img> straight at api.qrserver.com, so
+# opening the sheet in a browser handed every user's proxy key — the link IS the
+# credential — to a third party. A data: URI keeps the image inside the file and
+# the key on this machine. Callers must render the link without an image when
+# this returns empty rather than reaching for a remote renderer.
+_qr_data_uri() {
+    local data="$1" png b64
+    command -v base64 &>/dev/null || return 0
+    png=$(mktemp "${TMPDIR:-/tmp}/mtpx-qr.XXXXXX") || return 0
+    if _qr_png "$data" "$png"; then
+        # busybox base64 has no -w, GNU's wraps at 76 columns by default.
+        b64=$(base64 -w0 < "$png" 2>/dev/null) || b64=$(base64 < "$png" 2>/dev/null | tr -d '\n')
+        rm -f "$png" 2>/dev/null
+        [ -n "$b64" ] && printf 'data:image/png;base64,%s' "$b64"
+        return 0
+    fi
+    rm -f "$png" 2>/dev/null
+    return 0
 }
 
 # ── Section 11: Geo-Blocking ────────────────────────────────
@@ -11172,11 +11219,15 @@ telegram_clear_commands() {
     return 0
 }
 
-telegram_send_photo() {
-    local photo_url="$1" caption="${2:-}"
+# Upload a photo from a file on this host. The Bot API only fetches a URL
+# itself, so a locally rendered image has to be sent as multipart — and it is
+# the reason the QR no longer has to be posted to a third party first.
+telegram_send_photo_file() {
+    local file="$1" caption="${2:-}"
     local token="${TELEGRAM_BOT_TOKEN}"
     local chat_id="${TELEGRAM_CHAT_ID}"
     { [ -z "$token" ] || [ -z "$chat_id" ]; } && return 1
+    [ -s "$file" ] || return 1
 
     local label="${TELEGRAM_SERVER_LABEL:-MTProxyMax}"
     [ -n "$caption" ] && caption="[${label}] ${caption}"
@@ -11185,18 +11236,19 @@ telegram_send_photo() {
     _cfg=$(_mktemp) || return 1
     printf 'url = "https://api.telegram.org/bot%s/sendPhoto"\n' "$token" > "$_cfg"
 
-    curl -s --max-time 15 --max-filesize 10485760 -X POST \
+    curl -s --max-time 30 -X POST \
         -K "$_cfg" \
-        --data-urlencode "chat_id=${chat_id}" \
-        --data-urlencode "photo=${photo_url}" \
-        --data-urlencode "caption=${caption}" \
-        --data-urlencode "parse_mode=Markdown" \
+        -F "chat_id=${chat_id}" \
+        -F "photo=@${file}" \
+        --form-string "caption=${caption}" \
+        --form-string "parse_mode=Markdown" \
         >/dev/null 2>&1 || true
     local rc=$?
     rm -f "$_cfg"
     return $rc
 }
 
+
 telegram_get_chat_id() {
     local token="${TELEGRAM_BOT_TOKEN}"
     [ -z "$token" ] && return 1
@@ -11272,11 +11324,19 @@ telegram_notify_proxy_started() {
 
     telegram_send_message "$msg"
 
-    # Send QR for first enabled secret
+    # Send QR for first enabled secret. Rendered here and uploaded as a file;
+    # a remote renderer would be handed the key.
     if [ -n "$_first_secret" ]; then
-        local qr_url
-        qr_url=$(generate_qr_url "https://t.me/proxy?server=${server_ip}&port=${PROXY_PORT}&secret=${_first_secret}")
-        telegram_send_photo "$qr_url" "📱 *MTProxy QR Code* — Scan in Telegram to connect"
+        local _qr_link _qr_file
+        _qr_link="https://t.me/proxy?server=${server_ip}&port=${PROXY_PORT}&secret=${_first_secret}"
+        _qr_file=$(mktemp "${TMPDIR:-/tmp}/mtpx-qr.XXXXXX") || _qr_file=""
+        if [ -n "$_qr_file" ] && _qr_png "$_qr_link" "$_qr_file"; then
+            telegram_send_photo_file "$_qr_file" "📱 *MTProxy QR Code* — Scan in Telegram to connect"
+            rm -f "$_qr_file"
+        else
+            rm -f "$_qr_file" 2>/dev/null
+            telegram_send_message "🔗 [Connect](${_qr_link})\n\n_Install \`qrencode\` for a scannable QR._"
+        fi
     fi
 }
 
@@ -11527,39 +11587,84 @@ tg_send_to() {
         --data-urlencode "parse_mode=Markdown" >/dev/null 2>&1
 }
 
-tg_send_photo() {
-    local photo="$1" caption="${2:-}"
-    curl -s --max-time 15 -X POST \
+
+# ── QR codes ────────────────────────────────────────────────────────────────
+#
+# The QR used to be drawn by handing the proxy link to api.qrserver.com and
+# letting Telegram fetch the image from there. The link IS the credential —
+# server, port and secret are the whole key — so that handed a working proxy key
+# to a third party on every /mp_link, every /start and every voucher redemption,
+# including in the customer's own chat. It is rendered on this host now, and the
+# image is uploaded from here; nothing but Telegram sees it.
+#
+# The same reasoning applies to the QR image embedded in the exported HTML
+# sheets, which were built from the same kind of URL.
+
+# Render a QR to a PNG on this host. Non-zero when no renderer is available, in
+# which case the caller must NOT fall back to a remote one.
+_qr_png() {
+    local data="$1" out="$2"
+    [ -n "$data" ] && [ -n "$out" ] || return 1
+    if command -v qrencode &>/dev/null; then
+        qrencode -o "$out" -s 6 -m 2 "$data" 2>/dev/null && [ -s "$out" ] && return 0
+    fi
+    if _tg_have_python && python3 -c 'import qrcode' &>/dev/null; then
+        python3 - "$data" "$out" <<'PYQ' 2>/dev/null && [ -s "$out" ] && return 0
+import sys
+import qrcode
+qrcode.make(sys.argv[1]).save(sys.argv[2])
+PYQ
+    fi
+    rm -f "$out" 2>/dev/null
+    return 1
+}
+
+# Upload a local file as a photo. The token travels in a curl config rather than
+# argv so it never appears in `ps`; -F is required because the image is a file,
+# not a URL the API can fetch itself.
+_tg_send_photo_file() {
+    local chat="$1" file="$2" caption="${3:-}"
+    [ -s "$file" ] || return 1
+    curl -s --max-time 30 -X POST \
         -K <(printf 'url = "https://api.telegram.org/bot%s/sendPhoto"\n' "$TELEGRAM_BOT_TOKEN") \
-        --data-urlencode "chat_id=${TELEGRAM_CHAT_ID}" \
-        --data-urlencode "photo=${photo}" \
-        --data-urlencode "caption=[$(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")] ${caption}" \
-        --data-urlencode "parse_mode=Markdown" >/dev/null 2>&1
+        -F "chat_id=${chat}" \
+        -F "photo=@${file}" \
+        --form-string "caption=[$(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")] ${caption}" \
+        --form-string "parse_mode=Markdown" >/dev/null 2>&1
+}
+
+# "https://t.me/proxy?...", the one form of the link that is also a credential.
+_proxy_link() {
+    printf 'https://t.me/proxy?server=%s&port=%s&secret=%s' "$1" "$2" "$3"
+}
+
+_send_qr() {
+    local chat="$1" ip="$2" port="$3" secret="$4" caption="$5"
+    local link png
+    link=$(_proxy_link "$ip" "$port" "$secret")
+    png=$(mktemp "${TMPDIR:-/tmp}/mtpx-qr.XXXXXX") || png=""
+    if [ -n "$png" ] && _qr_png "$link" "$png"; then
+        _tg_send_photo_file "$chat" "$png" "$caption"
+        rm -f "$png" 2>/dev/null
+        return 0
+    fi
+    rm -f "$png" 2>/dev/null
+    # No renderer here. Send the tappable link rather than reaching for a remote
+    # one: the operator gets something usable, and the key stays on this host.
+    tg_send_to "$chat" "🔗 [Connect](${link})\n\n_Install \`qrencode\` (or \`python3-qrcode\`) for a scannable QR._"
+    return 1
 }
 
 # Send QR code image for a proxy secret (no text URL — avoids Telegram bot bans)
 send_proxy_qr() {
     local ip="$1" port="$2" secret="$3" caption="${4:-Scan in Telegram to connect}"
-    local hl="https://t.me/proxy?server=${ip}&port=${port}&secret=${secret}"
-    local el=$(printf '%s' "$hl" | sed 's/&/%26/g;s/?/%3F/g;s/=/%3D/g;s/:/%3A/g;s|/|%2F|g')
-    tg_send_photo "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${el}" "$caption"
+    _send_qr "$TELEGRAM_CHAT_ID" "$ip" "$port" "$secret" "$caption"
 }
 
-tg_send_photo_to() {
-    local target_cid="$1" photo="$2" caption="${3:-}"
-    curl -s --max-time 15 -X POST \
-        -K <(printf 'url = "https://api.telegram.org/bot%s/sendPhoto"\n' "$TELEGRAM_BOT_TOKEN") \
-        --data-urlencode "chat_id=${target_cid}" \
-        --data-urlencode "photo=${photo}" \
-        --data-urlencode "caption=[$(_esc "${TELEGRAM_SERVER_LABEL:-MTProxyMax}")] ${caption}" \
-        --data-urlencode "parse_mode=Markdown" >/dev/null 2>&1
-}
 
 send_proxy_qr_to() {
     local target_cid="$1" ip="$2" port="$3" secret="$4" caption="${5:-Scan in Telegram to connect}"
-    local hl="https://t.me/proxy?server=${ip}&port=${port}&secret=${secret}"
-    local el=$(printf '%s' "$hl" | sed 's/&/%26/g;s/?/%3F/g;s/=/%3D/g;s/:/%3A/g;s|/|%2F|g')
-    tg_send_photo_to "$target_cid" "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=${el}" "$caption"
+    _send_qr "$target_cid" "$ip" "$port" "$secret" "$caption"
 }
 
 # Escape Markdown special chars in labels for Telegram
@@ -12607,12 +12712,39 @@ _process_cmd() {
             local sl_ips=$(echo "$args" | awk '{print $3}')
             local sl_quota=$(echo "$args" | awk '{print $4}')
             local sl_exp=$(echo "$args" | awk '{print $5}')
-            [ -z "$sl_label" ] && tg_send "❌ Usage: /mp\\_setlimit <label> <conns> <ips> <quota> [expires]\nExample: /mp\\_setlimit alice 100 5 5G 2026-12-31" && return
+            [ -z "$sl_label" ] && tg_send "❌ Usage: /mp\\_setlimit <label> <conns> <ips> <quota> [expires]\nExample: /mp\\_setlimit alice 100 5 5G 2026-12-31\n_Leave a field out to keep it as it is._" && return
             [[ "$sl_label" =~ ^[a-zA-Z0-9_-]+$ ]] || { tg_send "❌ Invalid label"; return; }
-            if "${INSTALL_DIR}/mtproxymax" secret setlimits "$sl_label" "${sl_conns:-0}" "${sl_ips:-0}" "${sl_quota:-0}" "${sl_exp:-}" &>/dev/null; then
-                tg_send "✅ Limits updated for *$(_esc "$sl_label")*\nConns: ${sl_conns:-0} | IPs: ${sl_ips:-0} | Quota: ${sl_quota:-0}"
+
+            # Only the fields actually given are written. `secret setlimits`
+            # cannot express that: it reads an empty argument as 0, and
+            # secret_set_limits reads 0 as UNLIMITED — so `/mp_setlimit alice
+            # 100` used to clear alice's IP cap and quota as a side effect. The
+            # per-field `secret setlimit` verb touches one field and no other.
+            local -a _sl_changes=() _sl_flags
+            [ -n "$sl_conns" ] && _sl_changes+=("conns:$sl_conns")
+            [ -n "$sl_ips" ]   && _sl_changes+=("ips:$sl_ips")
+            [ -n "$sl_quota" ] && _sl_changes+=("quota:$sl_quota")
+            [ -n "$sl_exp" ]   && _sl_changes+=("expires:$sl_exp")
+            if [ "${#_sl_changes[@]}" -eq 0 ]; then
+                tg_send "❌ Nothing to change — give at least one of conns, ips, quota or expires."
+                return
+            fi
+
+            local _ok=1 _i _n=${#_sl_changes[@]}
+            for (( _i = 0; _i < _n; _i++ )); do
+                # Every field but the last is applied without a reload, so a
+                # multi-field change costs one engine sync rather than four.
+                _sl_flags=()
+                [ $(( _i + 1 )) -lt "$_n" ] && _sl_flags=(--no-restart)
+                "${INSTALL_DIR}/mtproxymax" secret setlimit "$sl_label" \
+                    "${_sl_changes[$_i]%%:*}" "${_sl_changes[$_i]#*:}" "${_sl_flags[@]}" &>/dev/null || _ok=0
+            done
+            if [ "$_ok" -eq 1 ]; then
+                local _shown="" _c
+                for _c in "${_sl_changes[@]}"; do _shown+="${_shown:+ · }${_c/:/ = }"; done
+                tg_send "✅ Limits updated for *$(_esc "$sl_label")*\n${_shown}"
             else
-                tg_send "❌ Failed to set limits for *$(_esc "$sl_label")* — check label exists"
+                tg_send "❌ Failed to set limits for *$(_esc "$sl_label")* — check the value and that the label exists"
             fi
             ;;
         /mp_fleet|/mp_fleet@*)
@@ -20727,8 +20859,11 @@ show_info_qrcode() {
     echo -e "  ${BOLD}QR generation methods (auto-detected):${NC}"
     echo -e "  ${GREEN}1.${NC} ${BOLD}qrencode${NC} (native) — fastest, renders in terminal"
     echo -e "     Install: ${DIM}apt install qrencode${NC}"
-    echo -e "  ${GREEN}2.${NC} ${BOLD}Docker${NC} — uses alpine + qrencode container"
-    echo -e "  ${GREEN}3.${NC} ${BOLD}Web API${NC} — qrserver.com (for Telegram photo messages)"
+    echo -e "  ${GREEN}2.${NC} ${BOLD}python3-qrcode${NC} — renders a PNG for the bot and the HTML sheets"
+    echo -e "     Install: ${DIM}pip install qrcode${NC}"
+    echo -e "  ${DIM}Without one of these the bot sends the tappable link instead of a QR"
+    echo -e "  image. It is never rendered by a remote service: the link contains the"
+    echo -e "  secret, so posting it anywhere would hand over the key.${NC}"
     echo ""
     echo -e "  ${BOLD}Commands:${NC}"
     echo -e "  ${GREEN}mtproxymax secret qr <label>${NC}   Show QR in terminal"
diff --git a/tests/test_telegram_qr_and_limits.sh b/tests/test_telegram_qr_and_limits.sh
new file mode 100644
index 0000000..a53c22b
--- /dev/null
+++ b/tests/test_telegram_qr_and_limits.sh
@@ -0,0 +1,198 @@
+#!/bin/bash
+# Two fixes that the button work exposed but did not cause.
+#
+# 1. /mp_setlimit silently wiped limits. It called
+#    `secret setlimits <label> <conns> <ips> <quota> <expires>`, and
+#    secret_set_limits reads "0" as UNLIMITED rather than "leave alone" — so
+#    `/mp_setlimit alice 100` also cleared alice's IP cap and quota.
+#
+# 2. Every QR code handed the credential to a third party. The proxy link IS the
+#    key (server, port and secret), and it was posted to api.qrserver.com for
+#    Telegram to fetch — on every /mp_link, every /start, and every voucher
+#    redemption, including to the customer's own chat.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+# ── Extract the shipped daemon code ──────────────────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _process_cmd \
+           _tg_pending_file _tg_pending_set _tg_pending_take _tg_pending_clear \
+           _tg_pending_try _tg_pending_run _tg_new_secret_link \
+           _qr_png _proxy_link _tg_send_photo_file _send_qr \
+           send_proxy_qr send_proxy_qr_to; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+
+SENDS="$TEST_TMPDIR/sends.log"
+CALLS="$TEST_TMPDIR/calls.log"
+CURLS="$TEST_TMPDIR/curls.log"
+CURLCFG="$TEST_TMPDIR/curlcfg.log"
+QRDIR="$TEST_TMPDIR/qr"
+
+_check_tg_role() { echo "superadmin"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+load_tg_settings() { :; }
+is_running() { return 0; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+format_bytes() { printf '%s' "$1"; }
+format_duration() { echo "1d"; }
+domain_to_hex() { echo "0a0b0c0d"; }
+_tg_have_python() { return 1; }
+_tg_metrics_raw() { printf ''; }
+# Record the curl invocation instead of performing it. The URL — which carries
+# the bot token — travels in a -K config file, so argv and the config are logged
+# separately: the point of the config file is that argv holds no secret.
+curl() {
+    printf '%s\n' "$*" >> "$CURLS"
+    local _f
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            -K) _f="$2"; [ -r "$_f" ] && cat "$_f" >> "$CURLCFG" ;;
+        esac
+        shift
+    done
+    return 0
+}
+
+cat > "$INSTALL_DIR/mtproxymax" <<'EOS'
+#!/bin/bash
+printf '%s\n' "$*" >> "$MTPX_CALLS"
+exit 0
+EOS
+chmod +x "$INSTALL_DIR/mtproxymax"
+export MTPX_CALLS="$CALLS"
+
+source "$FNS"
+
+PROXY_PORT=443
+PROXY_DOMAIN="cloudflare.com"
+MASKING_ENABLED="true"
+TELEGRAM_BOT_TOKEN="111:AAA"
+TELEGRAM_CHAT_ID="555"
+TELEGRAM_SERVER_LABEL="TestBox"
+
+run_cmd() {   # run_cmd <text>
+    : > "$SENDS"; : > "$CALLS"
+    _process_cmd "1" "111" "$1" >/dev/null 2>&1
+    cat "$SENDS"
+}
+
+echo "Telegram limit + QR tests"
+
+# ── /mp_setlimit changes only what it was given ──────────────────────────────
+_out=$(run_cmd "/mp_setlimit alice 100")
+assert_contains "a one-field set reaches the CLI" "secret setlimit alice conns 100" "$(cat "$CALLS")"
+assert_not_contains "and never uses the all-fields verb" "setlimits" "$(cat "$CALLS")"
+
+: > "$CALLS"
+run_cmd "/mp_setlimit alice 100 5" >/dev/null
+assert_contains "a two-field set sends the connection cap" "secret setlimit alice conns 100" "$(cat "$CALLS")"
+assert_contains "a two-field set sends the IP cap" "secret setlimit alice ips 5" "$(cat "$CALLS")"
+assert_not_contains "and still never uses the all-fields verb" "setlimits" "$(cat "$CALLS")"
+
+: > "$CALLS"
+run_cmd "/mp_setlimit alice 100 5 10G" >/dev/null
+assert_contains "a three-field set sends the quota" "secret setlimit alice quota 10G" "$(cat "$CALLS")"
+assert_not_contains "and still never uses the all-fields verb" "setlimits" "$(cat "$CALLS")"
+
+# An empty field is "leave it alone", so nothing at all must be sent for it —
+# the whole point of the fix.
+: > "$CALLS"
+run_cmd "/mp_setlimit alice 0 0 10G" >/dev/null
+assert_contains "an explicit 0 still reaches the CLI as a real 0" "secret setlimit alice conns 0" "$(cat "$CALLS")"
+
+_out=$(run_cmd "/mp_setlimit alice")
+assert_contains "a set with no fields is refused" "❌" "$_out"
+assert_eq "and reaches the CLI not at all" "" "$(cat "$CALLS")"
+
+# (A bare /mp_setlimit matches no case arm and stays silent. That is how the
+# dispatcher has always treated it, and changing it is not part of this fix.)
+
+# ── The QR is rendered here, not fetched from a third party ──────────────────
+mkdir -p "$QRDIR" "$TEST_TMPDIR/bin"
+# A stand-in renderer: it only has to prove the PNG path is taken.
+cat > "$TEST_TMPDIR/bin/qrencode" <<'EOS'
+#!/bin/bash
+out=""
+while [ $# -gt 0 ]; do
+    case "$1" in -o) out="$2"; shift 2 ;; *) shift ;; esac
+done
+[ -n "$out" ] && printf 'PNGDATA' > "$out"
+exit 0
+EOS
+chmod +x "$TEST_TMPDIR/bin/qrencode"
+PATH="$TEST_TMPDIR/bin:$PATH"
+
+: > "$CURLS"; : > "$CURLCFG"
+send_proxy_qr_to "777" "203.0.113.9" "443" "eeaaaa0a0b0c0d" "scan me"
+_curl_args="$(cat "$CURLS")"
+_curl_cfg="$(cat "$CURLCFG")"
+
+assert_not_contains "the QR never goes to a third-party renderer" "qrserver" "$_curl_args$_curl_cfg"
+assert_contains "the upload targets sendPhoto" "sendPhoto" "$_curl_cfg"
+assert_contains "the QR is uploaded from a file on this host" "photo=@" "$_curl_args"
+assert_contains "the upload is multipart, not a URL parameter" "-F" "$_curl_args"
+assert_contains "the upload goes to the chat that asked for it" "chat_id=777" "$_curl_args"
+# The bot token must travel in the curl config, never in argv where `ps` shows it.
+assert_not_contains "the bot token is not on the command line" "111:AAA" "$_curl_args"
+
+# With no renderer at all, the link is still delivered — as the tappable link,
+# never by falling back to the third party.
+rm -f "$TEST_TMPDIR/bin/qrencode"
+: > "$SENDS"; : > "$CURLS"; : > "$CURLCFG"
+send_proxy_qr_to "777" "203.0.113.9" "443" "eeaaaa0a0b0c0d" "scan me"
+assert_not_contains "no renderer still means no third party" "qrserver" "$(cat "$CURLS")$(cat "$CURLCFG")"
+assert_contains "the fallback still delivers a usable link" "t.me/proxy?server=203.0.113.9" "$(cat "$SENDS")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]

From c530a86be56601ef3c0c121f4dee388b5da54f52 Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Thu, 17 Sep 2026 13:15:58 +0300
Subject: [PATCH 08/10] feat(telegram): add traffic history, analytics and an
 informative report
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The periodic report sent the same three facts every interval — uptime, live
connections, and two LIFETIME cumulative totals — whether or not anything had
happened. Those only ever grow, so the message could never answer "how much
moved today, and is that more or less than yesterday?".

New rolling history store under relay_stats/history/ (5-minute samples, 7-day
retention, pruned daily):

  global.tsv  epoch|in_delta|out_delta|conns|marker
  users.tsv   epoch|label|in_delta|out_delta   (sparse)

It stores DELTAS, not cumulative counters: a cumulative record goes stale the
moment the engine restarts or a traffic reset rewinds the counters, forcing
every reader to re-implement restart detection. With deltas a reset just
yields a smaller bucket. The buckets are accumulated inside update_traffic's
existing delta loop, so the restart semantics are inherited by construction.

Analytics — 24h/7d/30d totals, period-over-period change, peak and average
rate, top talkers, hourly sparkline, quota pressure and expiry watch. Peak
uses the ACTUAL gap between samples rather than the nominal interval, so a
daemon outage shows as a real gap instead of a phantom spike, and average
divides by the span actually covered. Period-over-period reports "n/a" rather
than a numeric sentinel, because -1 would be indistinguishable from a genuine
1% decrease. Every query is one awk pass; a six-user page costs one scan, not
six.

The report is now activity-aware: with no traffic in the window it collapses
to a one-line heartbeat, since a dashboard of zeroes every six hours is noise.
TELEGRAM_REPORT_DETAIL (auto|full|summary) overrides that.

Also adds `mtproxymax telegram history [status|prune|reset]`, documents the
inline menus and the new settings, and corrects the README's Telegram command
table, which claimed "21 Commands" over 19 rows while omitting every public
command, /reply, /mp_broadcast, /mp_fleet and /mp_voucher.

New settings keys are registered in all four places, including the bot
daemon's own independent load_tg_settings whitelist — omitting that one would
leave the daemon silently running on defaults while `telegram status` reported
the configured value. tests/test_telegram_settings_roundtrip.sh pins it.

Note: the sparkline splits its glyph table on spaces rather than on "" —
splitting a multibyte string into characters is locale-dependent, and under a
C locale substr would slice a 3-byte bar glyph in half and emit mojibake.
---
 README.md                                 |  81 +++-
 mtproxymax.sh                             | 488 ++++++++++++++++++++--
 tests/test_telegram_history.sh            | 249 +++++++++++
 tests/test_telegram_menu_render.sh        |   2 +
 tests/test_telegram_periodic_report.sh    | 159 +++++++
 tests/test_telegram_settings_roundtrip.sh | 109 +++++
 6 files changed, 1058 insertions(+), 30 deletions(-)
 create mode 100644 tests/test_telegram_history.sh
 create mode 100644 tests/test_telegram_periodic_report.sh
 create mode 100644 tests/test_telegram_settings_roundtrip.sh

diff --git a/README.md b/README.md
index b73252f..55c193e 100644
--- a/README.md
+++ b/README.md
@@ -413,7 +413,7 @@ mtproxymax secret remove bob     # Permanent removal
 
 ---
 
-### 🤖 Telegram Bot (21 Commands)
+### 🤖 Telegram Bot (27 Commands)
 
 Full proxy management from your phone. Setup takes 60 seconds:
 
@@ -432,27 +432,86 @@ bot service starts; to refresh it by hand use:
 mtproxymax telegram sync-commands
 ```
 
+**Public self-service** — every user, including ones with no admin role:
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Self-service onboarding |
+| `/my_status <label>` | Your data quota and expiry |
+| `/redeem <code> [label]` | Redeem a voucher |
+| `/voucher <code> [label]` | Alias for `/redeem` |
+| `/support <message>` | Send a ticket to the admins |
+
+**Admin Control Plane** (`admin` and above):
+
 | Command | Description |
 |---------|-------------|
 | `/mp_status` | Proxy status, uptime, connections |
 | `/mp_secrets` | List all users with active connections |
 | `/mp_link` | Get proxy details + QR code image |
 | `/mp_add <label>` | Add new user |
-| `/mp_remove <label>` | Delete user |
-| `/mp_revoke <label>` | Revoke and purge a user secret immediately |
 | `/mp_rotate <label>` | Generate new key for user |
 | `/mp_enable <label>` | Re-enable disabled user |
 | `/mp_disable <label>` | Temporarily disable user |
-| `/mp_lockdown [on\|off]` | Toggle emergency panic lockdown defensive posture |
-| `/mp_digest` | View live executive health, posture, and traffic digest box |
 | `/mp_limits` | Show all user limits |
 | `/mp_setlimit` | Set user limits |
 | `/mp_traffic` | Per-user traffic breakdown |
 | `/mp_upstreams` | List proxy chains |
 | `/mp_health` | Run diagnostics |
+| `/mp_digest` | View live executive health, posture, and traffic digest box |
+| `/mp_broadcast <msg>` | Message every known bot user |
+| `/mp_fleet` | Global federation fleet dashboard |
+| `/mp_voucher create\|list` | Generate or list vouchers |
+| `/reply <chat_id> <msg>` | Answer a support ticket |
+| `/mp_help` | Show all commands |
+
+**Superadmin only:**
+
+| Command | Description |
+|---------|-------------|
+| `/mp_remove <label>` | Delete user (`/mp_revoke` is an alias, handled but not listed in the `/` menu) |
 | `/mp_restart` | Restart proxy |
 | `/mp_update` | Check for updates |
-| `/mp_help` | Show all commands |
+| `/mp_lockdown [on\|off]` | Toggle emergency panic lockdown defensive posture |
+
+#### Inline menu buttons
+
+Replies carry buttons, so most of the above is reachable by tapping rather than
+typing. Tapping **👥 Users** opens a paginated list; tapping a user opens a card
+showing its live connections, unique IPs, quota bar and expiry, with actions
+attached. Tapping **📈 Traffic** opens the analytics view with 24h / 7d / 30d
+windows.
+
+Anything that destroys state is behind a confirmation step — the ⏸ Disable,
+♻️ Rotate and 🗑 Remove buttons only *ask*; a second tap on **✅ Yes** performs
+it. Nothing destructive is ever one mis-tap away.
+
+The buttons you see are filtered by your role: a `reseller` gets the public
+views only, and a button never grants more than typing the equivalent command
+would.
+
+#### Traffic history
+
+The bot records rolling traffic samples under
+`/opt/mtproxymax/relay_stats/history/` (5-minute samples, 7-day retention) and
+uses them for the analytics view and the periodic report. Samples are stored as
+**deltas**, so an engine restart or a traffic reset cannot corrupt a window.
+
+```bash
+mtproxymax telegram history status   # sample counts, date range, retention
+mtproxymax telegram history prune    # apply retention now
+mtproxymax telegram history reset    # delete all recorded history
+```
+
+#### Report settings
+
+| Setting | Default | Meaning |
+|---------|---------|---------|
+| `TELEGRAM_INTERVAL` | `6` | Hours between periodic reports |
+| `TELEGRAM_REPORT_DETAIL` | `auto` | `auto` sends a full report only when there was traffic, otherwise a one-line heartbeat. `full` and `summary` force the two behaviours. |
+| `TELEGRAM_HISTORY_ENABLED` | `true` | Record traffic samples |
+| `TELEGRAM_HISTORY_INTERVAL_MIN` | `5` | Minutes between samples |
+| `TELEGRAM_HISTORY_RETENTION_DAYS` | `7` | Days of history to keep |
 
 #### 🎛 Running the proxy from buttons
 
@@ -665,6 +724,16 @@ mtproxymax status        # Overview with connections count
 - Active connections per user
 - Cumulative tracking across restarts
 
+Cumulative counters only ever grow, so they cannot answer *"how much moved
+today, and is that more or less than yesterday?"*. For that the Telegram bot
+records a rolling history of 5-minute samples (see
+[Traffic history](#traffic-history)) and reports **windowed** figures — 24h/7d/30d
+totals, period-over-period change, peak and average rate, top talkers, and an
+hourly sparkline — both in the periodic report and in the 📈 Traffic view.
+
+The periodic report is activity-aware: with no traffic in the window it
+collapses to a one-line heartbeat rather than repeating a dashboard of zeroes.
+
 ---
 
 ### 🌍 Geo-Blocking
diff --git a/mtproxymax.sh b/mtproxymax.sh
index ace9846..ab76567 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -147,6 +147,12 @@ TELEGRAM_CHAT_ID=""
 TELEGRAM_INTERVAL=6
 TELEGRAM_ALERTS_ENABLED="true"
 TELEGRAM_SERVER_LABEL="MTProxyMax"
+# Rolling traffic history. Disabling it stops new samples; existing ones stay.
+TELEGRAM_HISTORY_ENABLED="true"
+TELEGRAM_HISTORY_INTERVAL_MIN="5"
+TELEGRAM_HISTORY_RETENTION_DAYS="7"
+# auto = send a full report only when there was traffic, else a heartbeat.
+TELEGRAM_REPORT_DETAIL="auto"
 AUTO_UPDATE_ENABLED="true"
 
 # Anti-DPI & Stealth Defenses
@@ -718,6 +724,10 @@ TELEGRAM_CHAT_ID='${TELEGRAM_CHAT_ID}'
 TELEGRAM_INTERVAL='${TELEGRAM_INTERVAL}'
 TELEGRAM_ALERTS_ENABLED='${TELEGRAM_ALERTS_ENABLED}'
 TELEGRAM_SERVER_LABEL='${TELEGRAM_SERVER_LABEL}'
+TELEGRAM_HISTORY_ENABLED='${TELEGRAM_HISTORY_ENABLED}'
+TELEGRAM_HISTORY_INTERVAL_MIN='${TELEGRAM_HISTORY_INTERVAL_MIN}'
+TELEGRAM_HISTORY_RETENTION_DAYS='${TELEGRAM_HISTORY_RETENTION_DAYS}'
+TELEGRAM_REPORT_DETAIL='${TELEGRAM_REPORT_DETAIL}'
 
 # Auto-Update
 AUTO_UPDATE_ENABLED='${AUTO_UPDATE_ENABLED}'
@@ -803,6 +813,7 @@ load_settings() {
             PROXY_SECRET_URL|PROXY_CONFIG_V4_URL|PROXY_CONFIG_V6_URL|\
             TELEGRAM_ENABLED|TELEGRAM_BOT_TOKEN|TELEGRAM_CHAT_ID|\
             TELEGRAM_INTERVAL|TELEGRAM_ALERTS_ENABLED|TELEGRAM_SERVER_LABEL|\
+            TELEGRAM_HISTORY_ENABLED|TELEGRAM_HISTORY_INTERVAL_MIN|TELEGRAM_HISTORY_RETENTION_DAYS|TELEGRAM_REPORT_DETAIL|\
             AUTO_UPDATE_ENABLED|SECRET_AUTO_ROTATE_DAYS|BACKUP_RETENTION_DAYS|QUOTA_ENFORCEMENT_MODE|\
             STEALTH_SHIELD|STEALTH_PRESET|STEALTH_MSS_CLAMP|LOCKDOWN_MODE|PORT_POOL_PORTS|QOS_LIMIT_MBPS|HAPPY_HOURS_WINDOW|\
             REPLICATION_ENABLED|REPLICATION_ROLE|REPLICATION_SYNC_INTERVAL|\
@@ -11219,6 +11230,78 @@ telegram_clear_commands() {
     return 0
 }
 
+# Inspect and maintain the rolling traffic history written by the bot daemon.
+#
+# The daemon owns the format; the manager only counts rows and prunes, so the
+# analytics live in exactly one place. The field order is duplicated here for
+# readability, which matches how format_bytes is already duplicated between the
+# two — keep this comment and the daemon's in step:
+#
+#   global.tsv   epoch|in_delta|out_delta|conns|marker
+#   users.tsv    epoch|label|in_delta|out_delta
+telegram_history_cmd() {
+    local sub="${1:-status}"
+    local dir="${STATS_DIR}/history"
+    case "$sub" in
+        status)
+            echo -e "  ${BOLD}Traffic history:${NC} ${dir}"
+            if [ ! -d "$dir" ]; then
+                echo -e "  ${DIM}No history recorded yet.${NC}"
+                return 0
+            fi
+            local gn=0 un=0
+            [ -f "$dir/global.tsv" ] && gn=$(wc -l < "$dir/global.tsv" 2>/dev/null || echo 0)
+            [ -f "$dir/users.tsv" ]  && un=$(wc -l < "$dir/users.tsv" 2>/dev/null || echo 0)
+            echo -e "  ${DIM}Global samples: ${gn} | Per-user rows: ${un}${NC}"
+            if [ -f "$dir/global.tsv" ] && [ "$gn" -gt 0 ]; then
+                local first last
+                first=$(head -1 "$dir/global.tsv" | cut -d'|' -f1)
+                last=$(tail -1 "$dir/global.tsv" | cut -d'|' -f1)
+                echo -e "  ${DIM}Oldest: $(date -d "@${first}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "$first")${NC}"
+                echo -e "  ${DIM}Newest: $(date -d "@${last}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "$last")${NC}"
+            fi
+            echo -e "  ${DIM}Retention: ${TELEGRAM_HISTORY_RETENTION_DAYS:-7} day(s) | Sample interval: ${TELEGRAM_HISTORY_INTERVAL_MIN:-5} min${NC}"
+            ;;
+        prune)
+            check_root
+            if [ ! -d "$dir" ]; then
+                echo -e "  ${DIM}No history to prune.${NC}"
+                return 0
+            fi
+            local cutoff=$(( $(date +%s) - ${TELEGRAM_HISTORY_RETENTION_DAYS:-7} * 86400 ))
+            local f tmp
+            for f in "$dir/global.tsv" "$dir/users.tsv"; do
+                [ -f "$f" ] || continue
+                tmp=$(mktemp "$dir/.prune.XXXXXX") || continue
+                chmod 600 "$tmp"
+                if awk -F'|' -v c="$cutoff" '$1 + 0 >= c' "$f" > "$tmp"; then
+                    mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp"
+                else
+                    rm -f "$tmp"
+                fi
+            done
+            echo -e "  ${GREEN}✓${NC} Pruned history to the last ${TELEGRAM_HISTORY_RETENTION_DAYS:-7} day(s)."
+            ;;
+        reset)
+            check_root
+            [ -d "$dir" ] || return 0
+            echo -e "  ${YELLOW}This deletes all recorded traffic history. Reports and the${NC}"
+            echo -e "  ${YELLOW}traffic view will start from empty; secret quotas are unaffected.${NC}"
+            local _c=""
+            read -r -p "  Type 'yes' to confirm: " _c
+            if [ "$_c" != "yes" ]; then
+                echo -e "  ${DIM}Cancelled.${NC}"
+                return 0
+            fi
+            rm -f "$dir/global.tsv" "$dir/users.tsv"
+            echo -e "  ${GREEN}✓${NC} History cleared."
+            ;;
+        *)
+            echo -e "  Usage: mtproxymax telegram history [status|prune|reset]"
+            ;;
+    esac
+}
+
 # Upload a photo from a file on this host. The Bot API only fetches a URL
 # itself, so a locally rendered image has to be sent as multipart — and it is
 # the reason the QR no longer has to be posted to a third party first.
@@ -11533,6 +11616,7 @@ load_tg_settings() {
                 AD_TAG|GEOBLOCK_MODE|BLOCKLIST_COUNTRIES|AUTO_UPDATE_ENABLED|\
                 TELEGRAM_ENABLED|TELEGRAM_BOT_TOKEN|TELEGRAM_CHAT_ID|\
                 TELEGRAM_INTERVAL|TELEGRAM_SERVER_LABEL|TELEGRAM_ALERTS_ENABLED|\
+                TELEGRAM_HISTORY_ENABLED|TELEGRAM_HISTORY_INTERVAL_MIN|TELEGRAM_HISTORY_RETENTION_DAYS|TELEGRAM_REPORT_DETAIL|\
                 LOCKDOWN_MODE|QOS_LIMIT_MBPS|HAPPY_HOURS_WINDOW|PORT_POOL_PORTS|STEALTH_PRESET|COVER_WATCHDOG_ENABLED|DDNS_ENABLED|DDNS_RECORD_NAME)
                     printf -v "$key" '%s' "$val" ;;
             esac
@@ -12064,9 +12148,30 @@ update_traffic() {
     [ "$delta_out" -lt 0 ] 2>/dev/null && delta_out=$cur_out
     _cum_in=$((_cum_in + delta_in))
     _cum_out=$((_cum_out + delta_out))
+    # Accumulate the same corrected delta into the history bucket. Doing it
+    # here rather than re-deriving it later means the restart handling above is
+    # inherited by construction instead of duplicated.
+    _bucket_in=$(( ${_bucket_in:-0} + delta_in ))
+    _bucket_out=$(( ${_bucket_out:-0} + delta_out ))
     _prev_total_in=$cur_in
     _prev_total_out=$cur_out
 
+    # Connections and engine uptime for the sample row. A DECREASE in uptime
+    # means the engine restarted, which is recorded as a marker so a later
+    # window spanning the gap can explain itself.
+    local _extra _conns _up
+    _extra=$(printf '%s' "$_metrics" | awk '
+        /^telemt_user_connections_current\{/ { c+=$NF }
+        /^telemt_uptime_seconds /             { u=$NF }
+        END { printf "%.0f %.0f", c+0, u+0 }')
+    read -r _conns _up <<< "$_extra"
+    _bucket_conns="${_conns:-0}"
+    if [ "${_prev_uptime:-0}" -gt 0 ] 2>/dev/null && [ "${_up:-0}" -gt 0 ] 2>/dev/null && \
+       [ "${_up:-0}" -lt "${_prev_uptime:-0}" ] 2>/dev/null; then
+        _bucket_marker="R"
+    fi
+    _prev_uptime="${_up:-0}"
+
     # Per-user delta tracking — single awk pass for all users into associative array
     declare -A _parsed_ui=() _parsed_uo=()
     if [ -n "$_metrics" ]; then
@@ -12091,6 +12196,8 @@ update_traffic() {
         [ "$dou" -lt 0 ] 2>/dev/null && dou=$uo
         _cum_user_in["$label"]=$(( ${_cum_user_in["$label"]:-0} + du ))
         _cum_user_out["$label"]=$(( ${_cum_user_out["$label"]:-0} + dou ))
+        _bucket_user_in["$label"]=$(( ${_bucket_user_in["$label"]:-0} + du ))
+        _bucket_user_out["$label"]=$(( ${_bucket_user_out["$label"]:-0} + dou ))
         _prev_user_in["$label"]=$ui
         _prev_user_out["$label"]=$uo
     done < "$SECRETS_FILE"
@@ -14049,30 +14156,44 @@ _cb_exec_action() {
 
 _cb_render_traffic() {
     local win="${1:-24h}"
-    [ -z "$win" ] && win="24h"
-    local _msg="📈 *Traffic*\n\n"
-    _msg+="Lifetime: ↓ $(format_bytes "${_cum_out:-0}") ↑ $(format_bytes "${_cum_in:-0}")\n"
-    _msg+="👥 $(get_active_connections) live connections\n\n"
-    _msg+="*Per user (since reset)*\n"
-    local label secret created enabled rest _rows=""
-    if [ -f "$SECRETS_FILE" ]; then
-        while IFS='|' read -r label secret created enabled rest || [ -n "$label" ]; do
-            [[ "$label" =~ ^# ]] && continue
-            _cb_label_ok "$label" || continue
-            [ "$enabled" != "true" ] && continue
-            _rows+="$(printf '%s\n' "$(( ${_cum_user_in[$label]:-0} + ${_cum_user_out[$label]:-0} ))|$label")"$'\n'
-        done < "$SECRETS_FILE"
+    case "$win" in
+        7d)  _win_s=604800 ;;
+        30d) _win_s=2592000 ;;
+        *)   win="24h"; _win_s=86400 ;;
+    esac
+    local _now; _now=$(date +%s)
+    local _ci _co _pi _po _pct _peak _avg _n _span
+    IFS='|' read -r _ci _co _pi _po _pct _peak _avg _n _span <<< "$(history_summary "$_win_s" "$_now")"
+
+    local _msg="📈 *Traffic — last ${win}*\n\n"
+    _msg+="↓ $(format_bytes "${_co:-0}")  ↑ $(format_bytes "${_ci:-0}")$(_tg_pct_str "$_pct")\n"
+    _msg+="⚡ Peak $(format_bytes "${_peak:-0}")/s · Avg $(format_bytes "${_avg:-0}")/s\n"
+    _msg+="👥 $(get_active_connections) live now\n"
+    if [ "${_n:-0}" -gt 0 ]; then
+        _msg+="\n_from ${_n} sample(s) over $(format_duration "${_span:-0}")_\n"
+    else
+        _msg+="\n_No history recorded yet._\n"
     fi
-    if [ -n "$_rows" ]; then
-        while IFS='|' read -r _b _l; do
+
+    local _spark
+    _spark=$(_tg_spark "$(history_hourly "$_win_s" "$_now")")
+    [ -n "$_spark" ] && _msg+="\n\`\`\`\n${_spark}\n\`\`\`\n"
+
+    local _top _l _b
+    _top=$(history_top "$_win_s" "$_now" 5)
+    if [ -n "$_top" ]; then
+        _msg+="\n🏆 *Top talkers*\n"
+        while IFS='|' read -r _l _b; do
             [ -z "$_l" ] && continue
-            _msg+="👤 $(_esc "$_l"): ↓ $(format_bytes "${_cum_user_out[$_l]:-0}") ↑ $(format_bytes "${_cum_user_in[$_l]:-0}")\n"
-        done < <(printf '%s' "$_rows" | sort -t'|' -k1 -rn | head -8)
-    else
-        _msg+="No active users.\n"
+            _msg+="👤 $(_esc "$_l"): $(format_bytes "${_b:-0}")\n"
+        done <<< "$_top"
     fi
+
     _kb_reset
-    _kb_row "🔄 Refresh|t" "🏠 Menu|m"
+    _kb_row "$([ "$win" = "24h" ] && printf '24h ✓|t:w:24h' || printf '24h|t:w:24h')" \
+            "$([ "$win" = "7d" ] && printf '7d ✓|t:w:7d' || printf '7d|t:w:7d')" \
+            "$([ "$win" = "30d" ] && printf '30d ✓|t:w:30d' || printf '30d|t:w:30d')"
+    _kb_row "🔄 Refresh|t:w:${win}" "🏠 Menu|m"
     _cb_edit "$_msg" "$(_kb_json)"
 }
 
@@ -14492,6 +14613,306 @@ _tg_voucher_count() {
 
 # <<< TG_MENU_END
 
+# >>> TG_HISTORY_BEGIN
+# ── Rolling traffic history ─────────────────────────────────────────────────
+#
+# Two append-only files under relay_stats/history/:
+#
+#   global.tsv   epoch|in_delta|out_delta|conns|marker
+#   users.tsv    epoch|label|in_delta|out_delta   (sparse: only non-zero rows)
+#
+# DELTAS, not cumulative counters. A cumulative record goes stale the moment
+# the engine restarts or a traffic reset rewinds the counters, forcing every
+# reader to re-implement restart detection. With deltas a reset just yields a
+# smaller bucket, and a windowed sum is `t >= start { s += $2 }`.
+#
+# Only ONE writer (this daemon) appends, so appends need no lock; only the
+# read-modify-write in _history_prune does.
+#
+# Marker column: "-" normal, "R" engine restart, "X" traffic reset.
+HISTORY_DIR="${INSTALL_DIR}/relay_stats/history"
+
+_bucket_in=0
+_bucket_out=0
+_bucket_conns=0
+_bucket_marker="-"
+_prev_uptime=0
+declare -A _bucket_user_in _bucket_user_out
+
+_history_init() {
+    mkdir -p "$HISTORY_DIR" 2>/dev/null || true
+    [ -f "$HISTORY_DIR/global.tsv" ] || : > "$HISTORY_DIR/global.tsv" 2>/dev/null || true
+    [ -f "$HISTORY_DIR/users.tsv" ] || : > "$HISTORY_DIR/users.tsv" 2>/dev/null || true
+}
+
+_history_zero_buckets() {
+    _bucket_in=0; _bucket_out=0; _bucket_conns=0; _bucket_marker="-"
+    local _k
+    for _k in "${!_bucket_user_in[@]}";  do _bucket_user_in["$_k"]=0; done
+    for _k in "${!_bucket_user_out[@]}"; do _bucket_user_out["$_k"]=0; done
+}
+
+# Flush the accumulated buckets as one sample and reset them. Called on its own
+# timer, so the bucket window matches the sample interval rather than the 60s
+# traffic tick.
+history_sample() {
+    local epoch="${1:-$(date +%s)}"
+    _history_init
+    printf '%s|%s|%s|%s|%s\n' "$epoch" "${_bucket_in:-0}" "${_bucket_out:-0}" \
+        "${_bucket_conns:-0}" "${_bucket_marker:--}" >> "$HISTORY_DIR/global.tsv" 2>/dev/null
+    local _l _di _do
+    for _l in "${!_bucket_user_in[@]}"; do
+        _di="${_bucket_user_in[$_l]:-0}"; _do="${_bucket_user_out[$_l]:-0}"
+        [ "${_di:-0}" -eq 0 ] 2>/dev/null && [ "${_do:-0}" -eq 0 ] 2>/dev/null && continue
+        printf '%s|%s|%s|%s\n' "$epoch" "$_l" "$_di" "$_do" >> "$HISTORY_DIR/users.tsv" 2>/dev/null
+    done
+    _history_zero_buckets
+}
+
+# "cur_in|cur_out|prev_in|prev_out|pct|peak_bps|avg_bps|samples|span_s"
+#
+# pct is -1 when the previous window holds nothing, never inf/nan — a formatter
+# downstream would choke on those. peak uses the ACTUAL gap between samples,
+# not the nominal interval, so a daemon outage shows as a real gap rather than
+# a phantom spike; avg divides by the span actually covered, so a 7-day query
+# against 3 hours of history reports honestly instead of inflating.
+history_summary() {
+    local win="$1" now="$2"
+    local f="$HISTORY_DIR/global.tsv"
+    [ -f "$f" ] || { printf '0|0|0|0|n/a|0|0|0|0'; return 0; }
+    awk -F'|' -v win="$win" -v now="$now" '
+        {
+            t = $1 + 0
+            if (t > now) next
+            if (t >= now - win) {
+                ci += $2; co += $3; cn++
+                if (fs == "" || t < fs) fs = t
+                if (t > ls) ls = t
+            } else if (t >= now - 2 * win) { pi += $2; po += $3 }
+            if (pt != "" && t > pt) {
+                d = ($2 + $3) / (t - pt)
+                if (t >= now - win && d > peak) peak = d
+            }
+            pt = t
+        }
+        END {
+            # "n/a" rather than a numeric sentinel: -1 would be indistinguishable
+            # from a genuine 1%% decrease, and inf/nan would break the formatter.
+            pct = "n/a"
+            if (pi + po > 0) pct = int(((ci + co) - (pi + po)) * 100 / (pi + po)) ""
+            span = (ls > fs) ? (ls - fs) : 0
+            avg = (span > 0) ? int((ci + co) / span) : 0
+            printf "%d|%d|%d|%d|%s|%d|%d|%d|%d\n", ci, co, pi, po, pct, peak, avg, cn, span
+        }
+    ' "$f" 2>/dev/null || printf '0|0|0|0|n/a|0|0|0|0'
+}
+
+# A single-line sparkline for the hourly series. The bar glyphs are passed as a
+# SPACE-separated string and split on that, never on "" — splitting a multibyte
+# string into characters is locale-dependent, and under a C locale `substr`
+# would slice a 3-byte bar glyph in half and emit mojibake.
+_tg_spark() {
+    local vals="$1"
+    [ -n "$vals" ] || return 0
+    awk -v v="$vals" -v b="▁ ▂ ▃ ▄ ▅ ▆ ▇ █" '
+        BEGIN {
+            n = split(v, a, " "); nb = split(b, BAR, " ")
+            max = 0
+            for (i = 1; i <= n; i++) if (a[i] + 0 > max) max = a[i] + 0
+            out = ""
+            for (i = 1; i <= n; i++) {
+                if (max <= 0) { out = out BAR[1]; continue }
+                idx = int(a[i] * (nb - 1) / max) + 1
+                if (idx < 1) idx = 1
+                if (idx > nb) idx = nb
+                out = out BAR[idx]
+            }
+            printf "%s", out
+        }'
+}
+
+# Format a period-over-period figure. "n/a" means the previous window was empty
+# and prints nothing at all, rather than a misleading ▲0%.
+_tg_pct_str() {
+    local p="$1"
+    [[ "$p" =~ ^-?[0-9]+$ ]] || return 0
+    if   [ "$p" -gt 0 ]; then printf '  ▲%d%%' "$p"
+    elif [ "$p" -lt 0 ]; then printf '  ▼%d%%' "$(( -p ))"
+    else printf '  ▬0%%'
+    fi
+}
+
+# "label|in|out" for every requested label, in the order requested, in ONE awk
+# pass — a page of six users must not cost six scans. A label with no history
+# reports 0|0 rather than going missing.
+history_users() {
+    local win="$1" now="$2"; shift 2
+    [ "$#" -gt 0 ] || return 0
+    local f="$HISTORY_DIR/users.tsv" _l want=""
+    for _l in "$@"; do want="${want}${_l} "; done
+    if [ ! -f "$f" ]; then
+        for _l in "$@"; do printf '%s|0|0\n' "$_l"; done
+        return 0
+    fi
+    # NOTE: the accumulators must not be named i/o — awk forbids one name being
+    # both a scalar and an array, and the BEGIN loop already uses i as a counter.
+    awk -F'|' -v win="$win" -v now="$now" -v want="$want" '
+        BEGIN { n = split(want, a, " "); for (i = 1; i <= n; i++) if (a[i] != "") { W[a[i]] = 1; ord[++m] = a[i] } }
+        { t = $1 + 0; if (t < now - win || t > now) next
+          if ($2 in W) { accI[$2] += $3; accO[$2] += $4 } }
+        END { for (k = 1; k <= m; k++) printf "%s|%d|%d\n", ord[k], accI[ord[k]] + 0, accO[ord[k]] + 0 }
+    ' "$f" 2>/dev/null
+}
+
+# 24 space-separated bucket totals across the window, oldest first.
+history_hourly() {
+    local win="$1" now="$2"
+    local f="$HISTORY_DIR/global.tsv"
+    [ -f "$f" ] || { local _o="0" _i; for (( _i = 1; _i < 24; _i++ )); do _o="${_o} 0"; done; printf '%s' "$_o"; return 0; }
+    awk -F'|' -v win="$win" -v now="$now" '
+        BEGIN { n = 24; w = win / n; for (i = 0; i < n; i++) b[i] = 0 }
+        { s = now - win; t = $1 + 0
+          if (t < s || t > now) next
+          idx = int((t - s) / w)
+          if (idx < 0) idx = 0
+          if (idx > n - 1) idx = n - 1
+          b[idx] += $2 + $3 }
+        END { out = ""; for (i = 0; i < n; i++) out = out (i ? " " : "") b[i] + 0; print out }
+    ' "$f" 2>/dev/null
+}
+
+# "label|bytes", heaviest first. One awk plus one sort, whatever the user count.
+history_top() {
+    local win="$1" now="$2" n="${3:-3}"
+    local f="$HISTORY_DIR/users.tsv"
+    [ -f "$f" ] || return 0
+    awk -F'|' -v win="$win" -v now="$now" '
+        { t = $1 + 0; if (t < now - win || t > now) next; s[$2] += $3 + $4 }
+        END { for (k in s) printf "%s|%d\n", k, s[k] }
+    ' "$f" 2>/dev/null | sort -t'|' -k2 -rn | head -n "$n"
+}
+
+# Drop samples older than the retention window. This is the only read-modify-
+# write against the store, so it takes a lock — on fd 8, NOT the fd 9 that
+# save_traffic holds, because bash file descriptors are process-global and
+# reusing 9 here would close the traffic lock mid-critical-section. The
+# `command -v flock` guard matters too: on a host without flock (busybox) the
+# unguarded idiom just returns having silently pruned nothing.
+history_prune() {
+    local days="$1" now="${2:-$(date +%s)}"
+    local cutoff=$(( now - days * 86400 ))
+    _history_init
+    local f tmp
+    for f in "$HISTORY_DIR/global.tsv" "$HISTORY_DIR/users.tsv"; do
+        [ -f "$f" ] || continue
+        exec 8>"$HISTORY_DIR/.history.lock" 2>/dev/null || continue
+        if command -v flock &>/dev/null; then
+            flock -w 5 8 2>/dev/null || { exec 8>&- 2>/dev/null; continue; }
+        fi
+        tmp=$(mktemp "$HISTORY_DIR/.prune.XXXXXX" 2>/dev/null)
+        if [ -n "$tmp" ]; then
+            chmod 600 "$tmp" 2>/dev/null
+            awk -F'|' -v c="$cutoff" '$1 + 0 >= c' "$f" > "$tmp" 2>/dev/null
+            mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp"
+        fi
+        exec 8>&- 2>/dev/null
+    done
+}
+# <<< TG_HISTORY_END
+
+# >>> TG_REPORT_BEGIN
+# The periodic report.
+#
+# The previous version sent the same three facts every interval — uptime, live
+# connections, and two LIFETIME cumulative totals — whether or not anything had
+# happened. That is monotonically less informative as uptime grows: the numbers
+# only ever get bigger, and it can never answer "how much moved today, and is
+# that more or less than yesterday?".
+#
+# This reports a WINDOW instead, and adapts: with no traffic at all in the
+# window it collapses to a one-line heartbeat, because a full dashboard of
+# zeroes every six hours is noise. TELEGRAM_REPORT_DETAIL forces either
+# behaviour ('full' or 'summary'); 'auto' decides from the data.
+_tg_periodic_report() {
+    local now="$1" win="${2:-86400}"
+    local _ci _co _pi _po _pct _peak _avg _n _span
+    IFS='|' read -r _ci _co _pi _po _pct _peak _avg _n _span <<< "$(history_summary "$win" "$now")"
+    _ci=${_ci:-0}; _co=${_co:-0}
+
+    local _label="${TELEGRAM_SERVER_LABEL:-MTProxyMax}"
+    local _up _live
+    _up=$(get_uptime)
+    _live=$(get_active_connections)
+    local _detail="${TELEGRAM_REPORT_DETAIL:-auto}"
+    local _idle=0
+    [ "$_ci" -eq 0 ] && [ "$_co" -eq 0 ] && _idle=1
+
+    if [ "$_detail" = "summary" ] || { [ "$_detail" = "auto" ] && [ "$_idle" -eq 1 ]; }; then
+        if [ "$_idle" -eq 1 ]; then
+            tg_send_kb "🟢 *${_label}* — alive, idle ${_n:-0} sample(s)\n⏱ $(format_duration "${_up:-0}") · 👥 ${_live} live" \
+                "$(_tg_button_bar "${TELEGRAM_CHAT_ID}")"
+        else
+            tg_send_kb "📊 *${_label}*\n\n🟢 Running · ⏱ $(format_duration "${_up:-0}")\n👥 ${_live} live · 📈 24h ↓ $(format_bytes "$_co") ↑ $(format_bytes "$_ci")" \
+                "$(_tg_button_bar "${TELEGRAM_CHAT_ID}")"
+        fi
+        return 0
+    fi
+
+    local _msg="📊 *Report — $(_esc "$_label")*\n\n"
+    _msg+="🟢 Running · ⏱ $(format_duration "${_up:-0}") · 👥 ${_live} live\n"
+    _msg+="📈 24h ↓ $(format_bytes "$_co") ↑ $(format_bytes "$_ci")$(_tg_pct_str "$_pct")\n"
+    _msg+="⚡ Peak $(format_bytes "$_peak")/s · Avg $(format_bytes "$_avg")/s\n"
+
+    local _spark
+    _spark=$(_tg_spark "$(history_hourly "$win" "$now")")
+    if [ -n "$_spark" ]; then
+        # Fenced for monospace alignment. Deliberately NOT passed through _esc:
+        # inside a fence nothing is escaped, so escaping would render literal
+        # backslashes.
+        _msg+="\n\`\`\`\n${_spark}\n\`\`\`\n"
+    fi
+
+    local _top _l _b _first=1
+    _top=$(history_top "$win" "$now" 3)
+    if [ -n "$_top" ]; then
+        _msg+="🏆 "
+        while IFS='|' read -r _l _b; do
+            [ -z "$_l" ] && continue
+            [ "$_first" -eq 1 ] || _msg+=" · "
+            _first=0
+            _msg+="$(_esc "$_l") $(format_bytes "${_b:-0}")"
+        done <<< "$_top"
+        _msg+="\n"
+    fi
+
+    # Quota pressure and expiry reuse the same 80/100 thresholds and the same
+    # ISO parser as the enforcement loop, so the two cannot disagree.
+    local _q80=0 _exp3=0 _seclabel _secret _created _en _mc _mi _q _ex _notes _adtag
+    if [ -f "$SECRETS_FILE" ]; then
+        while IFS='|' read -r _seclabel _secret _created _en _mc _mi _q _ex _notes _adtag || [ -n "$_seclabel" ]; do
+            [[ "$_seclabel" =~ ^# ]] && continue
+            [ -z "$_seclabel" ] && continue
+            if [ -n "$_q" ] && [ "${_q:-0}" -gt 0 ] 2>/dev/null; then
+                local _used=$(( ${_cum_user_in[$_seclabel]:-0} + ${_cum_user_out[$_seclabel]:-0} ))
+                [ $(( (_used * 100) / _q )) -ge 80 ] && _q80=$(( _q80 + 1 ))
+            fi
+            if [ -n "$_ex" ] && [ "$_ex" != "0" ]; then
+                local _ee
+                _ee=$(_iso_to_epoch "$_ex")
+                if [ "${_ee:-0}" -gt 0 ] 2>/dev/null; then
+                    local _dl=$(( (_ee - now) / 86400 ))
+                    [ "$_dl" -ge 0 ] && [ "$_dl" -le 3 ] && _exp3=$(( _exp3 + 1 ))
+                fi
+            fi
+        done < "$SECRETS_FILE"
+    fi
+    [ "$_q80" -gt 0 ] && _msg+="⚠️ ${_q80} user(s) at ≥80% quota\n"
+    [ "$_exp3" -gt 0 ] && _msg+="⏳ ${_exp3} expiring within 3 days\n"
+
+    tg_send_kb "$_msg" "$(_tg_button_bar "${TELEGRAM_CHAT_ID}")"
+}
+# <<< TG_REPORT_END
+
 # Cleanup trap for temp files
 trap _cleanup EXIT
 
@@ -14511,6 +14932,10 @@ _report_interval=$(( ${TELEGRAM_INTERVAL:-6} * 3600 ))
 _last_health=0
 _last_traffic_update=0
 _last_enforcement=0
+# Seeded to now so the first tick after a restart does not immediately write a
+# near-empty bucket for the seconds since the process started.
+_last_hist_sample=$(date +%s)
+_last_hist_prune=$(date +%s)
 declare -A _prev_log_in=()
 declare -A _prev_log_out=()
 
@@ -14522,6 +14947,22 @@ while true; do
     if [ $((_now - _last_traffic_update)) -ge 60 ] && is_running; then
         _last_traffic_update=$_now
         update_traffic 2>/dev/null
+
+        # Flush a history sample on its own coarser timer, so a bucket spans the
+        # sample interval rather than the 60s tick. This sits before the
+        # TELEGRAM_ENABLED guard below, so history keeps recording even while
+        # the bot is switched off.
+        if [ "${TELEGRAM_HISTORY_ENABLED:-true}" = "true" ] && \
+           [ $(( _now - _last_hist_sample )) -ge $(( ${TELEGRAM_HISTORY_INTERVAL_MIN:-5} * 60 )) ]; then
+            _last_hist_sample=$_now
+            history_sample "$_now"
+        fi
+        if [ "${TELEGRAM_HISTORY_ENABLED:-true}" = "true" ] && \
+           [ $(( _now - _last_hist_prune )) -ge 86400 ]; then
+            _last_hist_prune=$_now
+            history_prune "${TELEGRAM_HISTORY_RETENTION_DAYS:-7}" "$_now" &
+        fi
+
         [ "${PORTAL_ENABLED:-false}" = "true" ] && "${INSTALL_DIR}/mtproxymax" portal generate &>/dev/null
 
         # Connection log: append per-user activity (delta = current cumulative - previous cumulative)
@@ -14631,10 +15072,7 @@ while true; do
     if [ $((_now - _last_report)) -ge $_report_interval ]; then
         _last_report=$_now
         if is_running; then
-            _ri=0 _ro=0 _rc=0
-            read -r _ri _ro _rc <<< "$(get_stats)" || true
-            _up=$(get_uptime)
-            tg_send "📊 *Periodic Report*\n\n🟢 Running | ⏱ $(format_duration ${_up:-0})\n👥 Connections: ${_rc}\n📊 ↓ $(format_bytes ${_cum_out:-0}) ↑ $(format_bytes ${_cum_in:-0})"
+            _tg_periodic_report "$_now" 86400
         fi
     fi
 
@@ -16537,6 +16975,7 @@ show_cli_help() {
     echo -e "    ${GREEN}telegram status${NC}         Show Telegram bot status"
     echo -e "    ${GREEN}telegram test${NC}           Send test message"
     echo -e "    ${GREEN}telegram sync-commands${NC}  Refresh the in-app command menu"
+    echo -e "    ${GREEN}telegram history${NC}        Traffic history: status | prune | reset"
     echo -e "    ${GREEN}broadcast <msg>${NC}         Broadcast announcement via Telegram bot"
     echo -e "    ${GREEN}telegram disable${NC}        Disable Telegram"
     echo -e "    ${GREEN}telegram remove${NC}         Remove Telegram bot"
@@ -18222,6 +18661,7 @@ cli_main() {
                 setup)   check_root; telegram_setup_wizard ;;
                 sync-commands) check_root; telegram_sync_commands ;;
                 commands) telegram_print_commands "${2:-admin}" ;;
+                history) telegram_history_cmd "${2:-status}";;
                 test)    telegram_test_message ;;
                 status|"")
                     if [ "$TELEGRAM_ENABLED" != "true" ]; then
diff --git a/tests/test_telegram_history.sh b/tests/test_telegram_history.sh
new file mode 100644
index 0000000..77ee50f
--- /dev/null
+++ b/tests/test_telegram_history.sh
@@ -0,0 +1,249 @@
+#!/bin/bash
+# Tests for the rolling history store and the analytics computed from it.
+#
+# The store records DELTAS, not cumulative counters, so an engine restart or a
+# traffic reset simply yields a smaller bucket instead of poisoning every
+# window that spans it. These tests use hand-written fixtures rather than
+# fixtures generated by the code under test, so the expected values are
+# checkable by eye.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats/history"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s\n         got=%q\n        want=%q\n' "$name" "$got" "$want"; fi
+}
+assert_ok() {
+    local name="$1" cond="$2"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$cond" -eq 0 ] 2>/dev/null; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/history.sh"
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" > "$FNS"
+assert_eq "history block found in the daemon" 1 \
+    "$(grep -c '^# >>> TG_HISTORY_BEGIN$' "$FNS")"
+assert_eq "history extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+source "$FNS"
+
+HIST="$INSTALL_DIR/relay_stats/history"
+NOW=1000000
+
+echo "Telegram history store tests"
+
+# ── Summary: window sums, period-over-period, peak and average ───────────────
+# window = 1000s, so cur covers epoch >= 999000 and prev covers 998000..998999.
+#   prev in = 200+200 = 400, prev out = 300+300 = 600, prev total = 1000
+#   cur  in = 400+600 = 1000, cur out = 600+400 = 1000, cur total = 2000
+#   pct = (2000-1000)*100/1000 = +100
+#   intervals: 998500->998800 gap 300 delta 500  = 1.67 B/s
+#              998800->999500 gap 700 delta 1000 = 1.43 B/s
+#              999500->999800 gap 300 delta 1000 = 3.33 B/s   <- peak
+#   span = 999800-999500 = 300 (cur window), total 2000 -> avg 6
+cat > "$HIST/global.tsv" <<'EOF'
+998500|200|300|5|-
+998800|200|300|6|-
+999500|400|600|7|-
+999800|600|400|8|-
+EOF
+: > "$HIST/users.tsv"
+
+assert_eq "summary reports the current and previous windows" \
+    "1000|1000|400|600|100|3|6|2|300" "$(history_summary 1000 "$NOW")"
+
+# A window with nothing in the previous period reports "n/a" — never inf/nan,
+# and never a numeric sentinel that a real -1% would collide with.
+cat > "$HIST/global.tsv" <<'EOF'
+999500|400|600|7|-
+999800|600|400|8|-
+EOF
+_sum=$(history_summary 1000 "$NOW")
+assert_eq "period-over-period is n/a when there is no previous window" \
+    "n/a" "$(printf '%s' "$_sum" | cut -d'|' -f5)"
+assert_ok "no inf or nan leaks into the summary" \
+    "$(printf '%s' "$_sum" | grep -qE 'inf|nan' && echo 1 || echo 0)"
+
+# A genuine decrease is still numeric, and distinguishable from n/a.
+# prev total 1250, cur total 1000 -> -20%
+cat > "$HIST/global.tsv" <<'EOF'
+998500|600|650|5|-
+999500|400|600|7|-
+999800|0|0|0|-
+EOF
+assert_eq "a real decrease is reported numerically" \
+    "-20" "$(history_summary 1000 "$NOW" | cut -d'|' -f5)"
+
+# An empty store must not crash or emit garbage.
+: > "$HIST/global.tsv"
+assert_eq "an empty store yields a zeroed summary" \
+    "0|0|0|0|n/a|0|0|0|0" "$(history_summary 1000 "$NOW")"
+
+# ── Peak must use the REAL inter-sample gap, not the nominal interval ────────
+# 1000 bytes over a 100s gap is 10 B/s. Assuming a nominal 300s bucket would
+# report 3 B/s, so this pins the honest calculation.
+cat > "$HIST/global.tsv" <<'EOF'
+999000|0|0|0|-
+999100|1000|0|0|-
+999800|1000|0|0|-
+EOF
+assert_eq "peak uses the actual gap between samples" \
+    "10" "$(history_summary 1000 "$NOW" | cut -d'|' -f6)"
+
+# ── An engine-restart marker must not be summed as traffic ───────────────────
+cat > "$HIST/global.tsv" <<'EOF'
+999500|400|600|7|-
+999600|0|0|0|R
+999800|600|400|8|-
+EOF
+assert_eq "restart rows still contribute their delta" \
+    "1000" "$(history_summary 1000 "$NOW" | cut -d'|' -f1)"
+
+# ── Per-user windows, in one pass, including users with no history ───────────
+cat > "$HIST/users.tsv" <<'EOF'
+998800|alice|100|100
+999500|alice|300|200
+999800|bob|50|50
+999800|alice|100|100
+EOF
+_u=$(history_users 1000 "$NOW" alice bob carol)
+assert_eq "per-user window sums are exact" \
+    "alice|400|300
+bob|50|50
+carol|0|0" "$_u"
+
+# Requesting no labels must not hang or error.
+assert_eq "an empty label list yields nothing" "" "$(history_users 1000 "$NOW")"
+
+# ── Hourly buckets ───────────────────────────────────────────────────────────
+cat > "$HIST/global.tsv" <<'EOF'
+999500|400|600|7|-
+999800|600|400|8|-
+EOF
+_h=$(history_hourly 1000 "$NOW")
+assert_eq "hourly series has 24 buckets" 24 "$(printf '%s\n' "$_h" | tr ' ' '\n' | grep -c .)"
+assert_eq "hourly buckets sum to the window total" 2000 \
+    "$(printf '%s\n' "$_h" | tr ' ' '\n' | awk '{s+=$1} END{printf "%.0f", s+0}')"
+
+# ── Top talkers ──────────────────────────────────────────────────────────────
+cat > "$HIST/users.tsv" <<'EOF'
+999500|alice|100|100
+999500|bob|500|500
+999500|carol|300|300
+EOF
+assert_eq "top talkers are ordered by volume" \
+    "bob|1000
+carol|600
+alice|200" "$(history_top 1000 "$NOW" 3)"
+assert_eq "top talkers honours the limit" 1 "$(history_top 1000 "$NOW" 1 | wc -l | tr -d ' ')"
+
+# ── Appending a sample ───────────────────────────────────────────────────────
+rm -f "$HIST/global.tsv" "$HIST/users.tsv"
+_bucket_in=111; _bucket_out=222; _bucket_marker="-"; _bucket_conns=0
+# carol is wholly idle in both directions so she must produce no row at all.
+declare -A _bucket_user_in=([alice]=10 [carol]=0)
+declare -A _bucket_user_out=([alice]=30 [carol]=0)
+history_sample 5000
+history_sample 5300
+assert_eq "each sample appends one global row" 2 "$(wc -l < "$HIST/global.tsv" | tr -d ' ')"
+assert_eq "global rows carry five pipe-separated fields" \
+    "5" "$(awk -F'|' 'NR==1{print NF}' "$HIST/global.tsv")"
+assert_eq "the global row holds the bucket totals" "5000|111|222|0|-" "$(head -1 "$HIST/global.tsv")"
+
+# A user with a zero delta is omitted: a mostly-idle fleet must not write a row
+# per user per sample.
+# The first sample consumes the bucket, so the second writes no user row.
+assert_eq "active users are written once per sample" 1 "$(grep -c 'alice' "$HIST/users.tsv")"
+assert_ok "a zero-delta user gets no row" \
+    "$(grep -q '^5000|carol|' "$HIST/users.tsv" && echo 1 || echo 0)"
+
+# The buckets must be zeroed after a sample, or the next one double-counts.
+assert_eq "sampling resets the global bucket" "0:0" "${_bucket_in}:${_bucket_out}"
+assert_eq "sampling resets the per-user bucket" "0:0" "${_bucket_user_in[alice]:-0}:${_bucket_user_out[alice]:-0}"
+
+# ── The record format's field count is a contract ────────────────────────────
+assert_eq "user rows carry four pipe-separated fields" \
+    "4" "$(awk -F'|' 'NR==1{print NF}' "$HIST/users.tsv")"
+
+# ── Concurrent appends ───────────────────────────────────────────────────────
+# The daemon is the only appender, so these need no lock — but O_APPEND must
+# still not interleave rows.
+rm -f "$HIST/global.tsv"
+for _i in $(seq 1 20); do
+    ( _bucket_in=$_i; _bucket_out=$_i; _bucket_marker="-"; history_sample "$(( 6000 + _i ))" ) &
+done
+wait
+assert_eq "20 concurrent appends produce 20 well-formed rows" 20 \
+    "$(awk -F'|' 'NF==5' "$HIST/global.tsv" | wc -l | tr -d ' ')"
+assert_eq "concurrent appends produce no extra rows" 20 \
+    "$(wc -l < "$HIST/global.tsv" | tr -d ' ')"
+
+# ── Pruning ──────────────────────────────────────────────────────────────────
+rm -f "$HIST/global.tsv" "$HIST/users.tsv"
+for _d in $(seq 0 9); do
+    printf '%s|10|10|1|-\n' "$(( NOW - _d * 86400 ))" >> "$HIST/global.tsv"
+    printf '%s|alice|10|10\n' "$(( NOW - _d * 86400 ))" >> "$HIST/users.tsv"
+done
+history_prune 7 "$NOW"
+assert_ok "pruning keeps samples inside the retention window" \
+    "$([ "$(wc -l < "$HIST/global.tsv" | tr -d ' ')" -ge 7 ] && echo 0 || echo 1)"
+assert_ok "pruning drops samples older than the window" \
+    "$(awk -F'|' -v c=$(( NOW - 7 * 86400 )) '$1 < c' "$HIST/global.tsv" | grep -q . && echo 1 || echo 0)"
+assert_eq "pruning leaves no blank lines" 0 \
+    "$(grep -c '^$' "$HIST/global.tsv")"
+assert_ok "pruning keeps every surviving row well-formed" \
+    "$(awk -F'|' 'NF!=5' "$HIST/global.tsv" | grep -q . && echo 1 || echo 0)"
+
+# Pruning twice must change nothing.
+_before=$(cat "$HIST/global.tsv")
+history_prune 7 "$NOW"
+assert_eq "pruning is idempotent" "$_before" "$(cat "$HIST/global.tsv")"
+
+# 10 daily samples with 7-day retention leaves day 0 through day 7 inclusive.
+assert_eq "pruning keeps exactly the retained days" 8 \
+    "$(wc -l < "$HIST/global.tsv" | tr -d ' ')"
+assert_eq "per-user rows are pruned on the same boundary" 8 \
+    "$(wc -l < "$HIST/users.tsv" | tr -d ' ')"
+
+# ── Sparkline ────────────────────────────────────────────────────────────────
+assert_eq "sparkline of an idle series is all floor" "▁▁▁" "$(_tg_spark "0 0 0")"
+assert_eq "sparkline scales to its own peak" "▃▅█" "$(_tg_spark "1 2 3")"
+assert_eq "sparkline of nothing is empty" "" "$(_tg_spark "")"
+# Each bar glyph is 3 UTF-8 bytes, and this host runs a C locale where wc -m
+# counts bytes — so byte length is the locale-independent way to count glyphs.
+# It is also the regression guard for the multibyte hazard: a byte-wise split
+# of the glyph table would yield a wrong byte count here.
+assert_eq "sparkline emits one glyph per bucket" 9 \
+    "$(printf '%s' "$(_tg_spark "1 2 3")" | wc -c | tr -d ' ')"
+assert_eq "sparkline length matches the series" 72 \
+    "$(_tg_spark "$(history_hourly 1000 "$NOW")" | wc -c | tr -d ' ')"
+
+# ── Percentage formatting ────────────────────────────────────────────────────
+assert_eq "an increase is shown with an up arrow" "  ▲12%" "$(_tg_pct_str 12)"
+assert_eq "a decrease is shown with a down arrow" "  ▼7%" "$(_tg_pct_str -7)"
+assert_eq "no change is shown as flat" "  ▬0%" "$(_tg_pct_str 0)"
+assert_eq "n/a prints nothing at all" "" "$(_tg_pct_str "n/a")"
+assert_eq "garbage prints nothing at all" "" "$(_tg_pct_str "")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_menu_render.sh b/tests/test_telegram_menu_render.sh
index 1f19621..64e4f43 100644
--- a/tests/test_telegram_menu_render.sh
+++ b/tests/test_telegram_menu_render.sh
@@ -59,6 +59,8 @@ for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec _esc _iso_to_epoch; do
     awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
 done
 awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+# The traffic view renders windowed analytics, so it needs the history block too.
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" >> "$FNS"
 assert_eq "menu render extraction is valid bash" 0 \
     "$(bash -n "$FNS" 2>/dev/null; echo $?)"
 
diff --git a/tests/test_telegram_periodic_report.sh b/tests/test_telegram_periodic_report.sh
new file mode 100644
index 0000000..018508d
--- /dev/null
+++ b/tests/test_telegram_periodic_report.sh
@@ -0,0 +1,159 @@
+#!/bin/bash
+# Tests for the periodic report.
+#
+# The report used to send the same three facts every interval regardless of
+# activity: uptime, live connections, and two LIFETIME cumulative totals. Those
+# only ever grow, so the message could never answer "how much moved today, and
+# is that more or less than yesterday?". This pins the windowed, activity-aware
+# replacement.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats/history"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+: > "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q)\n' "$name" "$needle"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q)\n' "$name" "$needle"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/report.sh"
+: > "$FNS"
+for _fn in _esc format_bytes format_duration _iso_to_epoch _cb_label_ok _cb_enc _cb_dec token_not_a_function; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+for _blk in TG_MENU TG_HISTORY TG_REPORT; do
+    awk "/^# >>> ${_blk}_BEGIN\$/,/^# <<< ${_blk}_END\$/" "$DAEMON" >> "$FNS"
+done
+assert_contains "report block found in the daemon" "TG_REPORT_BEGIN" "$(cat "$FNS")"
+assert_contains "history block found in the daemon" "TG_HISTORY_BEGIN" "$(cat "$FNS")"
+TESTS_RUN=$((TESTS_RUN + 1))
+if bash -n "$FNS" 2>/dev/null; then printf '  PASS  report extraction is valid bash\n'
+else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  report extraction is valid bash\n'; fi
+
+SENT="$TEST_TMPDIR/sent.txt"
+_check_tg_role() { echo "superadmin"; }
+get_uptime() { echo 3600; }
+get_active_connections() { echo 5; }
+get_cached_ip() { echo "203.0.113.9"; }
+tg_send_kb() { printf '%s\n' "$1" > "$SENT"; }
+tg_send() { printf '%s\n' "$1" > "$SENT"; }
+tg_edit() { :; }
+tg_edit_markup() { :; }
+tg_answer_cb() { :; }
+load_tg_settings() { :; }
+HISTORY_DIR="$INSTALL_DIR/relay_stats/history"
+source "$FNS"
+
+NOW=1000000
+report() {
+    : > "$SENT"
+    TELEGRAM_REPORT_DETAIL="$1" _tg_periodic_report "$NOW" 86400
+    cat "$SENT"
+}
+
+echo "Telegram periodic report tests"
+
+# ── Idle window collapses to a heartbeat ─────────────────────────────────────
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|0|0|0|-
+EOF
+: > "$HISTORY_DIR/users.tsv"
+_body=$(report auto)
+assert_contains "an idle window reports a heartbeat" "idle" "$_body"
+assert_not_contains "an idle window omits the sparkline" '```' "$_body"
+assert_not_contains "an idle window omits the lifetime totals line" "24h ↓" "$_body"
+assert_contains "the heartbeat still proves liveness" "alive" "$_body"
+
+# ── An active window produces the full report ────────────────────────────────
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|5000000|3000000|7|-
+EOF
+cat > "$HISTORY_DIR/users.tsv" <<'EOF'
+999600|alice|4000000|2000000
+999600|bob|1000000|1000000
+EOF
+_body=$(report auto)
+assert_contains "an active window reports the 24h totals" "24h ↓" "$_body"
+assert_contains "an active window reports a peak rate" "Peak" "$_body"
+assert_contains "an active window draws a sparkline" '```' "$_body"
+assert_contains "an active window names top talkers" "alice" "$_body"
+assert_not_contains "an active window is not a heartbeat" "alive, idle" "$_body"
+
+# Regression: the two lifetime totals the old report always sent must no longer
+# be the whole message. The window figure has to be present.
+assert_contains "the report is windowed, not lifetime" "24h" "$_body"
+
+# ── The sparkline is fenced, and NOT escaped ─────────────────────────────────
+# Inside a code fence nothing is escaped, so passing the bars through _esc would
+# render literal backslashes. Bars are U+2581..U+2588 and contain none.
+_spark_line=$(printf '%s' "$_body" | grep -A1 '^```$' | tail -1)
+assert_not_contains "the fenced sparkline is not Markdown-escaped" '\' "$_spark_line"
+
+# ── Verbosity override ───────────────────────────────────────────────────────
+_body=$(report summary)
+assert_not_contains "detail=summary suppresses the full report when busy" "Peak" "$_body"
+
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|0|0|0|-
+EOF
+_body=$(report full)
+assert_contains "detail=full reports even when idle" "24h ↓" "$_body"
+
+# ── Quota pressure and expiry watch ──────────────────────────────────────────
+# Quota is measured against the same _cum_user_* the enforcement loop uses, and
+# expiry against the same _iso_to_epoch, so the two can never disagree.
+cat > "$HISTORY_DIR/global.tsv" <<'EOF'
+999000|0|0|0|-
+999600|5000000|3000000|7|-
+EOF
+declare -A _cum_user_in=([alice]=900) _cum_user_out=([alice]=0)
+printf 'alice|%032d|1700000000|true|0|0|1000|0||\n' 1 > "$SECRETS_FILE"
+_body=$(report auto)
+assert_contains "a user at or above 80% quota is flagged" "80% quota" "$_body"
+
+declare -A _cum_user_in=([alice]=100) _cum_user_out=([alice]=0)
+_body=$(report auto)
+assert_not_contains "a user below the quota threshold is not flagged" "80% quota" "$_body"
+
+# An expiry three days out must be counted; ten days out must not.
+_far=$(( NOW + 10 * 86400 ))
+_near=$(date -u -d "@$(( NOW + 2 * 86400 ))" '+%Y-%m-%d' 2>/dev/null)
+if [ -n "$_near" ]; then
+    printf 'alice|%032d|1700000000|true|0|0|0|%s||\n' 1 "$_near" > "$SECRETS_FILE"
+    _body=$(report auto)
+    assert_contains "a secret expiring within 3 days is flagged" "expiring within 3 days" "$_body"
+else
+    printf '  SKIP  expiry assertions (date -d unavailable)\n'
+fi
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]
diff --git a/tests/test_telegram_settings_roundtrip.sh b/tests/test_telegram_settings_roundtrip.sh
new file mode 100644
index 0000000..bcd64fe
--- /dev/null
+++ b/tests/test_telegram_settings_roundtrip.sh
@@ -0,0 +1,109 @@
+#!/bin/bash
+# Tests that the Telegram settings keys survive a save/load round trip.
+#
+# There are FOUR places a key must be registered, and the fourth is the one
+# that gets missed: the bot daemon carries its OWN load_tg_settings whitelist,
+# independent of the manager's load_settings. A key added to only one of them
+# means the daemon silently runs on the default while `telegram status` reports
+# the configured value — a wrong-behaviour bug with no error anywhere.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats"
+SETTINGS_FILE="$INSTALL_DIR/settings.conf"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+
+echo "Telegram settings round-trip tests"
+
+KEYS="TELEGRAM_HISTORY_ENABLED TELEGRAM_HISTORY_INTERVAL_MIN TELEGRAM_HISTORY_RETENTION_DAYS TELEGRAM_REPORT_DETAIL"
+
+# ── save_settings writes them ────────────────────────────────────────────────
+TELEGRAM_HISTORY_ENABLED="false"
+TELEGRAM_HISTORY_INTERVAL_MIN="11"
+TELEGRAM_HISTORY_RETENTION_DAYS="3"
+TELEGRAM_REPORT_DETAIL="full"
+save_settings 2>/dev/null
+
+for _k in $KEYS; do
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if grep -q "^${_k}=" "$SETTINGS_FILE" 2>/dev/null; then
+        printf '  PASS  %s is written to settings.conf\n' "$_k"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  %s is written to settings.conf\n' "$_k"
+    fi
+done
+
+# ── load_settings reads them back ────────────────────────────────────────────
+TELEGRAM_HISTORY_ENABLED="true"
+TELEGRAM_HISTORY_INTERVAL_MIN="5"
+TELEGRAM_HISTORY_RETENTION_DAYS="7"
+TELEGRAM_REPORT_DETAIL="auto"
+load_settings 2>/dev/null
+
+assert_eq "load_settings restores TELEGRAM_HISTORY_ENABLED" "false" "$TELEGRAM_HISTORY_ENABLED"
+assert_eq "load_settings restores TELEGRAM_HISTORY_INTERVAL_MIN" "11" "$TELEGRAM_HISTORY_INTERVAL_MIN"
+assert_eq "load_settings restores TELEGRAM_HISTORY_RETENTION_DAYS" "3" "$TELEGRAM_HISTORY_RETENTION_DAYS"
+assert_eq "load_settings restores TELEGRAM_REPORT_DETAIL" "full" "$TELEGRAM_REPORT_DETAIL"
+
+# ── The daemon's own whitelist must know them too ────────────────────────────
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-settings.sh"
+awk '/^load_tg_settings\(\)/,/^}$/' "$DAEMON" > "$FNS"
+assert_eq "load_tg_settings extraction is valid bash" 0 \
+    "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+source "$FNS"
+
+for _k in $KEYS; do
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if grep -q "$_k" "$FNS"; then
+        printf '  PASS  the daemon whitelists %s\n' "$_k"
+    else
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+        printf '  FAIL  the daemon whitelists %s\n' "$_k"
+    fi
+done
+
+# And it must actually pick the configured value up, not just name the key.
+TELEGRAM_HISTORY_ENABLED="unset-sentinel"
+TELEGRAM_HISTORY_INTERVAL_MIN="unset-sentinel"
+TELEGRAM_HISTORY_RETENTION_DAYS="unset-sentinel"
+TELEGRAM_REPORT_DETAIL="unset-sentinel"
+load_tg_settings
+
+assert_eq "the daemon picks up TELEGRAM_HISTORY_ENABLED" "false" "$TELEGRAM_HISTORY_ENABLED"
+assert_eq "the daemon picks up TELEGRAM_HISTORY_INTERVAL_MIN" "11" "$TELEGRAM_HISTORY_INTERVAL_MIN"
+assert_eq "the daemon picks up TELEGRAM_HISTORY_RETENTION_DAYS" "3" "$TELEGRAM_HISTORY_RETENTION_DAYS"
+assert_eq "the daemon picks up TELEGRAM_REPORT_DETAIL" "full" "$TELEGRAM_REPORT_DETAIL"
+
+# No clamp is needed on the interval: sampling is driven from inside the 60s
+# traffic tick, so the tick itself is the floor however the config is set.
+TELEGRAM_HISTORY_INTERVAL_MIN="unset-sentinel"
+printf "TELEGRAM_HISTORY_INTERVAL_MIN='0'\n" > "$SETTINGS_FILE"
+load_tg_settings
+assert_eq "a zero interval passes through the parser" "0" "$TELEGRAM_HISTORY_INTERVAL_MIN"
+assert_eq "the tick bounds sampling to one per minute" 1 \
+    "$(grep -c '_last_hist_sample )) -ge' "$DAEMON")"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]

From dc5d28cacd0b90a8fc77e3f743f416bd03be74bc Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Thu, 17 Sep 2026 18:51:44 +0300
Subject: [PATCH 09/10] fix(telegram): make history prune work on busybox and
 stop killing stderr
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

history_prune() guarded on `command -v flock`, but busybox ships a flock
applet — so the guard passes, and it is specifically `-w` that busybox
lacks. The lock call then failed, the loop `continue`d, and the prune did
nothing at all on Alpine: global.tsv grew without bound and
TELEGRAM_HISTORY_RETENTION_DAYS was silently not honoured. The CLI
`telegram history prune` was unaffected because it has its own copy with
no lock, so the two paths disagreed with each other.

The comment above the function asserted that busybox "has no flock", which
is what produced the wrong guard. Corrected here.

Fall back to `-n`, which busybox does support, so the lock is still taken:

    flock -w 5 8 || flock -n 8 || { exec 8>&-; continue; }

Second defect on the same lines: `exec 8>... 2>/dev/null` is
redirection-only, so that 2>/dev/null applies to the whole shell and
silences stderr for the rest of the process, not just for that line. In
the daemon every subsequent diagnostic was discarded. Both the open and
the close form are fixed.

Verified: tests/test_telegram_history.sh goes from 3 failures to 0 under a
busybox-style flock — now stubbed on PATH so the regression is caught on
every platform rather than only on Alpine — and still passes with GNU
flock. All ten test files added by this PR pass.
---
 mtproxymax.sh                  | 23 +++++++++++++++++------
 tests/test_telegram_history.sh | 18 ++++++++++++++++++
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/mtproxymax.sh b/mtproxymax.sh
index ab76567..79e6806 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -14795,9 +14795,18 @@ history_top() {
 # Drop samples older than the retention window. This is the only read-modify-
 # write against the store, so it takes a lock — on fd 8, NOT the fd 9 that
 # save_traffic holds, because bash file descriptors are process-global and
-# reusing 9 here would close the traffic lock mid-critical-section. The
-# `command -v flock` guard matters too: on a host without flock (busybox) the
-# unguarded idiom just returns having silently pruned nothing.
+# reusing 9 here would close the traffic lock mid-critical-section.
+#
+# A `command -v flock` guard is not sufficient on its own: busybox ships a flock
+# applet, so the guard passes, and it is specifically `-w` that busybox lacks.
+# The lock call then failed, this loop `continue`d, and the prune did nothing at
+# all on Alpine — silently, so global.tsv grew without bound and the retention
+# setting was quietly not honoured. Fall back to `-n`, which busybox does
+# support, rather than trusting that the binary's presence implies the flags.
+#
+# `exec` here is redirection-only, so it applies to the whole shell: a trailing
+# 2>/dev/null would silence stderr for the rest of the process, not just for
+# this line, which is why none of these carry one.
 history_prune() {
     local days="$1" now="${2:-$(date +%s)}"
     local cutoff=$(( now - days * 86400 ))
@@ -14805,9 +14814,11 @@ history_prune() {
     local f tmp
     for f in "$HISTORY_DIR/global.tsv" "$HISTORY_DIR/users.tsv"; do
         [ -f "$f" ] || continue
-        exec 8>"$HISTORY_DIR/.history.lock" 2>/dev/null || continue
+        exec 8>"$HISTORY_DIR/.history.lock" || continue
         if command -v flock &>/dev/null; then
-            flock -w 5 8 2>/dev/null || { exec 8>&- 2>/dev/null; continue; }
+            flock -w 5 8 2>/dev/null ||
+                flock -n 8 2>/dev/null ||
+                { exec 8>&-; continue; }
         fi
         tmp=$(mktemp "$HISTORY_DIR/.prune.XXXXXX" 2>/dev/null)
         if [ -n "$tmp" ]; then
@@ -14815,7 +14826,7 @@ history_prune() {
             awk -F'|' -v c="$cutoff" '$1 + 0 >= c' "$f" > "$tmp" 2>/dev/null
             mv "$tmp" "$f" 2>/dev/null || rm -f "$tmp"
         fi
-        exec 8>&- 2>/dev/null
+        exec 8>&-
     done
 }
 # <<< TG_HISTORY_END
diff --git a/tests/test_telegram_history.sh b/tests/test_telegram_history.sh
index 77ee50f..43ba8dd 100644
--- a/tests/test_telegram_history.sh
+++ b/tests/test_telegram_history.sh
@@ -18,6 +18,24 @@ INSTALL_DIR="$TEST_TMPDIR/install"
 mkdir -p "$INSTALL_DIR/relay_stats/history"
 OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
 
+# busybox ships a flock applet that accepts -n but NOT -w. Putting one on PATH reproduces
+# Alpine's behaviour here, so the history-prune regression is caught on every platform
+# rather than only on busybox hosts.
+FAKEBIN="$TEST_TMPDIR/bin"
+mkdir -p "$FAKEBIN"
+cat >"$FAKEBIN/flock" <<'FLOCK_EOF'
+#!/bin/bash
+for _a in "$@"; do
+    case "$_a" in
+    -w*) echo "flock: unrecognized option: w" >&2; exit 1 ;;
+    esac
+done
+exit 0
+FLOCK_EOF
+chmod +x "$FAKEBIN/flock"
+PATH="$FAKEBIN:$PATH"
+export PATH
+
 MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
 set +e
 trap 'rm -rf "$TEST_TMPDIR"' EXIT

From 87d7a949ccd11700618b9280da63b76d8f52bf0c Mon Sep 17 00:00:00 2001
From: Ramil Valitov <ramilvalitov@gmail.com>
Date: Fri, 18 Sep 2026 16:20:31 +0300
Subject: [PATCH 10/10] feat(telegram): windowed per-user traffic, and drop the
 sparkline fences
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per-user traffic. users.tsv has been written since the history subsystem
landed, but nothing read it back per user — the user card showed only the
cumulative total since the last reset, which cannot answer "how much did they
move today, and is that up or down?". The new card shows 24h / 7d / 30d totals
from history_users (reused rather than re-derived) and a 24-hour sparkline from
a new history_user_series, with the quota and expiry beside it so the numbers
can be judged without navigating back.

All three windows sit on one card rather than behind a selector: three totals
fit comfortably, and a selector would need a fifth field the callback grammar
does not have, which would cost the origin page on the way back.

A quiet user gets a flat line, not a missing row — history_user_series reports
zeros rather than an empty string, and the test pins that, because an empty
string would drop the sparkline silently instead of drawing it flat.

Sparkline fences. The traffic view and the periodic report wrapped the sparkline
in a code fence "for monospace alignment". The glyphs are block elements, which
are drawn as a tiling set and share an advance width in a proportional font, so
the fence bought nothing and cost a monospace box with a copy button on every
report. The periodic-report test asserted the fence was PRESENT; those
assertions are inverted here, and the escape check now runs on the glyph run
rather than the whole line — the body carries its newlines as literal \n, so the
line has backslashes in it either way.

Test harness fix, which the above is what surfaced. assert_contains used
`printf … | grep -qF`, and under `set -o pipefail` that fails SPURIOUSLY once
the haystack exceeds the pipe buffer: grep -q exits at the first match, printf
takes SIGPIPE, and the pipeline reports failure even though the needle was
found. It only started biting when the daemon grew past 64 KiB, which is why it
looked like the markers had gone missing. Every telegram test file now compares
with `[[ … == *"$needle"* ]]`, which has no pipe to break.

Also fixes the README's Telegram Bot table-of-contents anchor, which PR 4's
heading rename from "(21 Commands)" to "(27 Commands)" had left dangling.
---
 README.md                                |   3 +-
 mtproxymax.sh                            |  98 ++++++++++++--
 tests/test_telegram_callback_dispatch.sh |   6 +-
 tests/test_telegram_menu_render.sh       |   3 +-
 tests/test_telegram_no_codebox.sh        |  38 +++++-
 tests/test_telegram_parity.sh            |   4 +-
 tests/test_telegram_pending_input.sh     |   4 +-
 tests/test_telegram_per_secret_views.sh  |   4 +-
 tests/test_telegram_periodic_report.sh   |  41 ++++--
 tests/test_telegram_reseller_rbac.sh     |   4 +-
 tests/test_telegram_update_parser.sh     |   2 +-
 tests/test_telegram_user_traffic.sh      | 158 +++++++++++++++++++++++
 12 files changed, 329 insertions(+), 36 deletions(-)
 create mode 100644 tests/test_telegram_user_traffic.sh

diff --git a/README.md b/README.md
index 55c193e..1e88d44 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@
     <a href="#-quick-start">Quick Start</a> &bull;
     <a href="#-features">Features</a> &bull;
     <a href="#-comparison">Comparison</a> &bull;
-    <a href="#-telegram-bot-21-commands">Telegram Bot</a> &bull;
+    <a href="#-telegram-bot-27-commands">Telegram Bot</a> &bull;
     <a href="#-cli-reference">CLI Reference</a> &bull;
     <a href="#-changelog">Changelog</a> &bull;
     <a href="https://www.samnet.dev/learn/networking/mtproto-proxy-telegram/">Full Guide ↗</a>
@@ -521,6 +521,7 @@ typing. Send any command — or tap **🏠 Menu** on any reply — to open the h
 | Section | What it covers |
 |---------|----------------|
 | 👥 **Users** | Paginated list → per-user card with live connections, traffic, quota bar, expiry, note and quota-reset day, plus link/QR, enable, disable, rotate and remove |
+| 📊 **Per-user traffic** | What that user moved over the last 24h / 7d / 30d, with a 24-hour sparkline, beside their quota and expiry |
 | ⚙️ **Manage** (per user) | Quota, connection cap, IP cap, expiry, monthly quota-reset day, note, ad-tag, and applying a saved limit template to that user |
 | 🧩 **Templates** | Create, edit every field of, apply and delete limit templates |
 | 📈 **Traffic** | Windowed totals (24h / 7d / 30d) with a sparkline, peak and average rate, and top talkers |
diff --git a/mtproxymax.sh b/mtproxymax.sh
index 79e6806..34bef34 100644
--- a/mtproxymax.sh
+++ b/mtproxymax.sh
@@ -13226,6 +13226,7 @@ c:rotate=admin
 a:remove=superadmin
 c:remove=superadmin
 u:m=admin
+u:t=admin
 e=admin
 e:q=admin
 e:c=admin
@@ -13529,7 +13530,7 @@ _cb_render_user_detail() {
 
     _kb_reset
     _kb_row "🔄 Refresh|u:s:${label}:${page}" "🔗 Link|u:k:${label}"
-    _kb_row "$(_kb_spec "⚙️ Manage" "u" "m" "$label" "$page")"
+    _kb_row "$(_kb_spec "⚙️ Manage" "u" "m" "$label" "$page")" "$(_kb_spec "📊 Traffic" "u" "t" "$label" "$page")"
     if [ "$_en" = "true" ]; then
         _cb_can a disable && _kb_row "⏸ Disable|a:disable:${label}" "$(_cb_can a rotate && printf '♻️ Rotate|a:rotate:%s' "$label")"
     else
@@ -13842,6 +13843,58 @@ _cb_render_tpl_picker() {
     _cb_edit "$_msg" "$(_kb_json)"
 }
 
+# What one user actually moved, windowed. users.tsv has been written since the
+# history subsystem landed but nothing read it back per user — the user card
+# could only show the cumulative total since the last reset, which cannot
+# answer "how much today, and is that up or down?".
+#
+# All three windows are on one card rather than behind a window selector: three
+# totals fit comfortably, and a selector would need a fifth field the callback
+# grammar does not have, costing the origin page on the way back.
+_cb_render_user_traffic() {
+    local label="$1" page="${2:-0}"
+    ! _cb_label_ok "$label" && { _CB_TOAST="Invalid label"; return 1; }
+    ! _cb_secret_exists "$label" && { _CB_TOAST="Secret '$label' not found"; return 1; }
+    [[ "$page" =~ ^[0-9]+$ ]] || page=0
+
+    local _now _w
+    _now=$(date +%s)
+    local _msg="📊 *Traffic — $(_esc "$label")*\n"
+    local _in _out
+    for _w in 86400 604800 2592000; do
+        # history_users already does the windowed sum in one pass; reuse it
+        # rather than adding a second reader that could drift from it.
+        IFS='|' read -r _ _in _out <<< "$(history_users "$_w" "$_now" "$label")"
+        case "$_w" in
+            86400)   _msg+="\n*Last 24h*  ↓ $(format_bytes "${_out:-0}")  ↑ $(format_bytes "${_in:-0}")" ;;
+            604800)  _msg+="\n*Last 7d*   ↓ $(format_bytes "${_out:-0}")  ↑ $(format_bytes "${_in:-0}")" ;;
+            2592000) _msg+="\n*Last 30d*  ↓ $(format_bytes "${_out:-0}")  ↑ $(format_bytes "${_in:-0}")" ;;
+        esac
+    done
+
+    local _spark
+    _spark=$(_tg_spark "$(history_user_series "$label" 86400 "$_now" 24)")
+    [ -n "$_spark" ] && _msg+="\n\n📉 ${_spark}"
+
+    # The card carries the same quota/expiry context as the user card, so an
+    # operator reading the traffic does not have to navigate back to judge it.
+    local _line _q _ex
+    _line=$(grep -E "^${label}\|" "$SECRETS_FILE" 2>/dev/null | head -1)
+    IFS='|' read -r _ _ _ _ _ _ _q _ex _ <<< "$_line"
+    if [ -n "$_q" ] && [ "$_q" -gt 0 ] 2>/dev/null; then
+        local _cum=$(( ${_cum_user_in[$label]:-0} + ${_cum_user_out[$label]:-0} ))
+        local _pct=$(( (_cum * 100) / _q ))
+        [ "$_pct" -gt 100 ] && _pct=100
+        _msg+="\n\n🧮 quota $(_cb_bar "$_pct") ${_pct}% of $(format_bytes "$_q")"
+    fi
+    [ -n "$_ex" ] && [ "$_ex" != "0" ] && _msg+="\n⏳ expires $(_cb_expiry_text "$_ex")"
+
+    _kb_reset
+    _kb_row "🔄 Refresh|u:t:${label}:${page}" "⚙️ Manage|u:m:${label}:${page}"
+    _kb_row "◀ Back|u:s:${label}:${page}"
+    _cb_edit "$_msg" "$(_kb_json)"
+}
+
 _cb_quota_reset_day() {
     local f="${INSTALL_DIR}/secrets_quota_reset.conf" _l _d
     [ -f "$f" ] || return 0
@@ -14177,7 +14230,13 @@ _cb_render_traffic() {
 
     local _spark
     _spark=$(_tg_spark "$(history_hourly "$_win_s" "$_now")")
-    [ -n "$_spark" ] && _msg+="\n\`\`\`\n${_spark}\n\`\`\`\n"
+    # Inline, not fenced. The glyphs are block elements, which are drawn as a
+    # tiling set and share an advance width in a proportional font, so the
+    # sparkline stays aligned without a fence — and a fence would wrap it in a
+    # monospace box with a copy button, which is the wrong shape for a chart.
+    # Not passed through _esc either: the glyphs contain no Markdown
+    # metacharacter, and escaping would render literal backslashes.
+    [ -n "$_spark" ] && _msg+="\n📉 ${_spark}\n"
 
     local _top _l _b
     _top=$(history_top "$_win_s" "$_now" 5)
@@ -14452,6 +14511,7 @@ _cb_dispatch() {
                 s) _cb_render_user_detail "$_CB_TGT" "${_CB_PAGE:-0}" ;;
                 k) _cb_send_link "$_CB_TGT" ;;
                 m) _cb_render_user_manage "$_CB_TGT" "${_CB_PAGE:-0}" ;;
+                t) _cb_render_user_traffic "$_CB_TGT" "${_CB_PAGE:-0}" ;;
                 *) _CB_TOAST="Unknown action" ;;
             esac
             ;;
@@ -14781,6 +14841,30 @@ history_hourly() {
     ' "$f" 2>/dev/null
 }
 
+# One user's series across the window, bucketed the same way history_hourly
+# buckets the global one, so _tg_spark consumes either unchanged.
+#
+# A label with no rows yields ZEROS rather than an empty string: the card draws
+# a flat line for a quiet account, and an empty string would silently drop the
+# sparkline row instead. The filter is on the label column, so one user's rows
+# can never be counted for another.
+history_user_series() {
+    local label="$1" win="$2" now="$3" n="${4:-24}"
+    local f="$HISTORY_DIR/users.tsv"
+    [ -f "$f" ] || { local _o="0" _i; for (( _i = 1; _i < n; _i++ )); do _o="${_o} 0"; done; printf '%s' "$_o"; return 0; }
+    awk -F'|' -v win="$win" -v now="$now" -v n="$n" -v who="$label" '
+        BEGIN { w = win / n; for (i = 0; i < n; i++) b[i] = 0 }
+        { if ($2 != who) next
+          s = now - win; t = $1 + 0
+          if (t < s || t > now) next
+          idx = int((t - s) / w)
+          if (idx < 0) idx = 0
+          if (idx > n - 1) idx = n - 1
+          b[idx] += $3 + $4 }
+        END { out = ""; for (i = 0; i < n; i++) out = out (i ? " " : "") b[i] + 0; print out }
+    ' "$f" 2>/dev/null || printf '0'
+}
+
 # "label|bytes", heaviest first. One awk plus one sort, whatever the user count.
 history_top() {
     local win="$1" now="$2" n="${3:-3}"
@@ -14876,12 +14960,10 @@ _tg_periodic_report() {
 
     local _spark
     _spark=$(_tg_spark "$(history_hourly "$win" "$now")")
-    if [ -n "$_spark" ]; then
-        # Fenced for monospace alignment. Deliberately NOT passed through _esc:
-        # inside a fence nothing is escaped, so escaping would render literal
-        # backslashes.
-        _msg+="\n\`\`\`\n${_spark}\n\`\`\`\n"
-    fi
+    # Inline, not fenced — see _cb_render_traffic for why the fence bought
+    # nothing. Deliberately NOT passed through _esc: the block glyphs contain no
+    # Markdown metacharacter, and escaping would render literal backslashes.
+    [ -n "$_spark" ] && _msg+="\n📉 ${_spark}\n"
 
     local _top _l _b _first=1
     _top=$(history_top "$win" "$now" 3)
diff --git a/tests/test_telegram_callback_dispatch.sh b/tests/test_telegram_callback_dispatch.sh
index cbcde57..9760b28 100644
--- a/tests/test_telegram_callback_dispatch.sh
+++ b/tests/test_telegram_callback_dispatch.sh
@@ -47,7 +47,7 @@ assert_eq() {
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         printf '  PASS  %s\n' "$name"
     else
         TESTS_FAILED=$((TESTS_FAILED + 1))
@@ -57,7 +57,7 @@ assert_contains() {
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1))
         printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else
@@ -249,7 +249,7 @@ cap_leaks() {
             # CLI verb (secret setlimit / extend / quota-reset / template apply),
             # and none of them is reachable by a reseller, whose only surface
             # stays the voucher commands.
-            u:m|e|e:q|e:c|e:i|e:x|e:r|e:n|e:a|e:t|e:z|\
+            u:m|u:t|e|e:q|e:c|e:i|e:x|e:r|e:n|e:a|e:t|e:z|\
             c:setq|c:setc|c:seti|c:setx|c:setr|c:tpl)
                 [ "$cap" = "admin" ] || { printf '%s=%s\n' "$key" "$cap"; } ;;
             # The server console and the template section: read-mostly views
diff --git a/tests/test_telegram_menu_render.sh b/tests/test_telegram_menu_render.sh
index 64e4f43..44f00d2 100644
--- a/tests/test_telegram_menu_render.sh
+++ b/tests/test_telegram_menu_render.sh
@@ -101,6 +101,7 @@ render() {
         engine)   _cb_render_engine ;;
         settings) _cb_render_settings ;;
         manage)   _cb_render_user_manage "${3:-user01}" "${4:-0}" ;;
+        usertraffic) _cb_render_user_traffic "${3:-user01}" "${4:-0}" ;;
         limits_q) _cb_render_limits q "${3:-user01}" "${4:-0}" ;;
         limits_c) _cb_render_limits c "${3:-user01}" "${4:-0}" ;;
         limits_i) _cb_render_limits i "${3:-user01}" "${4:-0}" ;;
@@ -125,7 +126,7 @@ cbs_of() { printf '%s' "$1" | grep -o '"callback_data":"[^"]*"' | sed 's/.*:"//;
 
 echo "Telegram menu render tests"
 
-VIEWS="hub help list detail confirm traffic engine settings manage \
+VIEWS="hub help list detail confirm traffic engine settings manage usertraffic \
 limits_q limits_c limits_i limits_x limits_r \
 tpl_list tpl_edit tpl_field tpl_apply tpl_picker \
 tools digest upstreams fleet vouchers update"
diff --git a/tests/test_telegram_no_codebox.sh b/tests/test_telegram_no_codebox.sh
index 24673c4..1266e27 100644
--- a/tests/test_telegram_no_codebox.sh
+++ b/tests/test_telegram_no_codebox.sh
@@ -48,7 +48,7 @@ TESTS_FAILED=0
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1))
         printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else
@@ -58,7 +58,7 @@ assert_not_contains() {
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         printf '  PASS  %s\n' "$name"
     else
         TESTS_FAILED=$((TESTS_FAILED + 1))
@@ -87,6 +87,9 @@ for _fn in _tg_security_log _cb_label_ok _cb_enc _cb_dec _esc _process_cmd \
     awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
 done
 awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+# The analytics views read the rolling history, so their block comes too.
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" >> "$FNS"
+awk '/^# >>> TG_REPORT_BEGIN$/,/^# <<< TG_REPORT_END$/' "$DAEMON" >> "$FNS"
 assert_eq "dispatcher extraction is valid bash" 0 \
     "$(bash -n "$FNS" 2>/dev/null; echo $?)"
 assert_eq "menu block was found in the daemon" 1 \
@@ -97,6 +100,10 @@ SENDS="$TEST_TMPDIR/sends.log"
 CALLS="$TEST_TMPDIR/calls.log"
 
 _check_tg_role() { echo "superadmin"; }
+EDIT="$TEST_TMPDIR/edit.txt"
+tg_edit() { printf '%s\n%s' "$3" "$4" > "$EDIT"; }
+tg_edit_markup() { printf '%s' "$3" > "$EDIT"; }
+tg_answer_cb() { :; }
 tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
 tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
 tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
@@ -220,12 +227,33 @@ for _c in "/mp_help" "/mp_status" "/mp_secrets" "/mp_link" "/mp_limits" \
 done
 
 # ── The views reachable by button ────────────────────────────────────────────
+# ── The analytics views ──────────────────────────────────────────────────────
+# These two draw a sparkline. It used to sit in a fence "for monospace
+# alignment"; the glyphs are block elements, which share an advance width in a
+# proportional font, so the fence bought nothing and cost a code box.
+HISTORY="$TEST_TMPDIR/history"
+HISTORY_DIR="$HISTORY"
+mkdir -p "$HISTORY"
+_now=$(date +%s)
+for _i in $(seq 0 23); do
+    printf '%s|%s|%s|%s|-\n' "$(( _now - _i * 3600 ))" "$(( _i * 1024 ))" "$(( _i * 2048 ))" "3" >> "$HISTORY/global.tsv"
+done
+printf '%s|alice|5000|9000\n' "$_now" > "$HISTORY/users.tsv"
+
+EDIT="$TEST_TMPDIR/edit-traffic.txt"; : > "$EDIT"
+_cb_render_traffic "24h"
+assert_not_contains "the traffic view draws no code box" '```' "$(cat "$EDIT")"
+assert_contains "the traffic view still draws a sparkline" "▁" "$(cat "$EDIT")"
+
+# The periodic report is a push, not an edit — it goes out through tg_send_kb.
+: > "$SENDS"
+_tg_periodic_report "$_now" 86400
+assert_not_contains "the periodic report draws no code box" '```' "$(cat "$SENDS")"
+assert_contains "the periodic report still draws a sparkline" "▁" "$(cat "$SENDS")"
+
 for _v in hub help user_list engine settings; do
     EDIT="$TEST_TMPDIR/edit-$_v.txt"
     : > "$EDIT"
-    tg_edit() { printf '%s\n%s' "$3" "$4" > "$EDIT"; }
-    tg_edit_markup() { :; }
-    tg_answer_cb() { :; }
     _CB_CHAT="111"; _CB_MID="77"; _CB_DATA=""; _UI_ROLE="superadmin"
     case "$_v" in
         hub)          _cb_render_hub ;;
diff --git a/tests/test_telegram_parity.sh b/tests/test_telegram_parity.sh
index bee7724..ceabb0f 100644
--- a/tests/test_telegram_parity.sh
+++ b/tests/test_telegram_parity.sh
@@ -47,13 +47,13 @@ assert_eq() {
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then printf '  PASS  %s\n' "$name"
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
     else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
 }
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else printf '  PASS  %s\n' "$name"; fi
 }
diff --git a/tests/test_telegram_pending_input.sh b/tests/test_telegram_pending_input.sh
index 7e2b432..d7705eb 100644
--- a/tests/test_telegram_pending_input.sh
+++ b/tests/test_telegram_pending_input.sh
@@ -44,7 +44,7 @@ assert_eq() {
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         printf '  PASS  %s\n' "$name"
     else
         TESTS_FAILED=$((TESTS_FAILED + 1))
@@ -54,7 +54,7 @@ assert_contains() {
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1))
         printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else
diff --git a/tests/test_telegram_per_secret_views.sh b/tests/test_telegram_per_secret_views.sh
index 778948a..8ac9e35 100644
--- a/tests/test_telegram_per_secret_views.sh
+++ b/tests/test_telegram_per_secret_views.sh
@@ -43,13 +43,13 @@ assert_eq() {
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then printf '  PASS  %s\n' "$name"
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
     else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
 }
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else printf '  PASS  %s\n' "$name"; fi
 }
diff --git a/tests/test_telegram_periodic_report.sh b/tests/test_telegram_periodic_report.sh
index 018508d..171164c 100644
--- a/tests/test_telegram_periodic_report.sh
+++ b/tests/test_telegram_periodic_report.sh
@@ -29,16 +29,22 @@ TESTS_FAILED=0
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then printf '  PASS  %s\n' "$name"
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
     else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q)\n' "$name" "$needle"; fi
 }
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q)\n' "$name" "$needle"
     else printf '  PASS  %s\n' "$name"; fi
 }
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
 
 telegram_generate_service_script
 DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
@@ -87,7 +93,7 @@ EOF
 : > "$HISTORY_DIR/users.tsv"
 _body=$(report auto)
 assert_contains "an idle window reports a heartbeat" "idle" "$_body"
-assert_not_contains "an idle window omits the sparkline" '```' "$_body"
+assert_not_contains "an idle window omits the sparkline" '📉' "$_body"
 assert_not_contains "an idle window omits the lifetime totals line" "24h ↓" "$_body"
 assert_contains "the heartbeat still proves liveness" "alive" "$_body"
 
@@ -103,7 +109,7 @@ EOF
 _body=$(report auto)
 assert_contains "an active window reports the 24h totals" "24h ↓" "$_body"
 assert_contains "an active window reports a peak rate" "Peak" "$_body"
-assert_contains "an active window draws a sparkline" '```' "$_body"
+assert_contains "an active window draws a sparkline" '📉' "$_body"
 assert_contains "an active window names top talkers" "alice" "$_body"
 assert_not_contains "an active window is not a heartbeat" "alive, idle" "$_body"
 
@@ -111,11 +117,28 @@ assert_not_contains "an active window is not a heartbeat" "alive, idle" "$_body"
 # be the whole message. The window figure has to be present.
 assert_contains "the report is windowed, not lifetime" "24h" "$_body"
 
-# ── The sparkline is fenced, and NOT escaped ─────────────────────────────────
-# Inside a code fence nothing is escaped, so passing the bars through _esc would
-# render literal backslashes. Bars are U+2581..U+2588 and contain none.
-_spark_line=$(printf '%s' "$_body" | grep -A1 '^```$' | tail -1)
-assert_not_contains "the fenced sparkline is not Markdown-escaped" '\' "$_spark_line"
+# ── The sparkline is inline, unescaped, and never fenced ─────────────────────
+# It used to sit inside a code fence "for monospace alignment". The glyphs are
+# block elements and share an advance width in a proportional font, so the fence
+# bought nothing and cost a monospace box with a copy button on every report.
+assert_not_contains "the report draws no code box" '```' "$_body"
+# Any of the eight block glyphs counts: with a single non-zero bucket the series
+# is flat, so which glyph a bar gets depends on the scale, not on correctness.
+_spark_line=""
+while IFS= read -r _l; do
+    case "$_l" in *📉*) _spark_line="$_l"; break ;; esac
+done <<< "$_body"
+if [[ "$_spark_line" =~ ([▁▂▃▄▅▆▇█]+) ]]; then
+    _spark_glyphs="${BASH_REMATCH[1]}"
+else
+    _spark_glyphs=""
+fi
+assert_eq "the sparkline still draws bars" 1 "$([ -n "$_spark_glyphs" ] && echo 1 || echo 0)"
+# Bars are U+2581..U+2588 and contain no Markdown metacharacter, so escaping the
+# run would render literal backslashes inside it for no benefit. The check is on
+# the glyph run rather than the whole line: the body carries its newlines as
+# literal \n, so the line has backslashes in it either way.
+assert_not_contains "the inline sparkline is not Markdown-escaped" '\' "$_spark_glyphs"
 
 # ── Verbosity override ───────────────────────────────────────────────────────
 _body=$(report summary)
diff --git a/tests/test_telegram_reseller_rbac.sh b/tests/test_telegram_reseller_rbac.sh
index 3431282..6f30bac 100644
--- a/tests/test_telegram_reseller_rbac.sh
+++ b/tests/test_telegram_reseller_rbac.sh
@@ -31,7 +31,7 @@ TESTS_FAILED=0
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         printf '  PASS  %s\n' "$name"
     else
         TESTS_FAILED=$((TESTS_FAILED + 1))
@@ -42,7 +42,7 @@ assert_contains() {
 assert_not_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         TESTS_FAILED=$((TESTS_FAILED + 1))
         printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
     else
diff --git a/tests/test_telegram_update_parser.sh b/tests/test_telegram_update_parser.sh
index 921a3f5..2ff4a8f 100644
--- a/tests/test_telegram_update_parser.sh
+++ b/tests/test_telegram_update_parser.sh
@@ -47,7 +47,7 @@ assert_eq() {
 assert_contains() {
     local name="$1" needle="$2" haystack="$3"
     TESTS_RUN=$((TESTS_RUN + 1))
-    if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    if [[ "$haystack" == *"$needle"* ]]; then
         printf '  PASS  %s\n' "$name"
     else
         TESTS_FAILED=$((TESTS_FAILED + 1))
diff --git a/tests/test_telegram_user_traffic.sh b/tests/test_telegram_user_traffic.sh
new file mode 100644
index 0000000..140a1fe
--- /dev/null
+++ b/tests/test_telegram_user_traffic.sh
@@ -0,0 +1,158 @@
+#!/bin/bash
+# Tests for the per-user traffic card.
+#
+# users.tsv has been written since the history subsystem landed, but nothing
+# ever read it back per user: the user card showed only the cumulative total
+# since the last reset, which cannot answer "how much did they move today, and
+# is that up or down?". This pins the per-user reader and the card that shows
+# it, including the two ways a per-user series goes wrong — counting another
+# user's rows, and going missing (rather than reporting zero) for a user with no
+# rows at all, which is the common case for a quiet account.
+set -o pipefail
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+    echo "SKIP: bash 4+ required (got ${BASH_VERSION:-unknown})" >&2
+    exit 0
+fi
+
+TEST_TMPDIR=$(mktemp -d)
+INSTALL_DIR="$TEST_TMPDIR/install"
+mkdir -p "$INSTALL_DIR/relay_stats/history"
+OFFSET_FILE="$INSTALL_DIR/relay_stats/tg_offset"
+ADMINS_FILE="$INSTALL_DIR/admins.conf"
+AUDIT_LOG="$INSTALL_DIR/audit.log"
+SECRETS_FILE="$INSTALL_DIR/secrets.conf"
+HISTORY_DIR="$INSTALL_DIR/relay_stats/history"
+
+printf 'alice|%s|1700000000|true|7|3|10737418240|2027-01-01||\n' "$(printf 'a%.0s' $(seq 1 32))" > "$SECRETS_FILE"
+printf 'quiet|%s|1700000000|true|0|0|0|0||\n' "$(printf 'q%.0s' $(seq 1 32))" >> "$SECRETS_FILE"
+
+MTPROXYMAX_SOURCE_ONLY=true source "$(dirname "${BASH_SOURCE[0]}")/../mtproxymax.sh"
+set +e
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+TESTS_RUN=0
+TESTS_FAILED=0
+
+assert_eq() {
+    local name="$1" want="$2" got="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [ "$got" = "$want" ]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (got=%q want=%q)\n' "$name" "$got" "$want"; fi
+}
+assert_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then printf '  PASS  %s\n' "$name"
+    else TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (missing %q in %q)\n' "$name" "$needle" "$haystack"; fi
+}
+assert_not_contains() {
+    local name="$1" needle="$2" haystack="$3"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        TESTS_FAILED=$((TESTS_FAILED + 1)); printf '  FAIL  %s (unexpected %q in %q)\n' "$name" "$needle" "$haystack"
+    else printf '  PASS  %s\n' "$name"; fi
+}
+
+telegram_generate_service_script
+DAEMON="$INSTALL_DIR/mtproxymax-telegram.sh"
+FNS="$TEST_TMPDIR/daemon-fns.sh"
+: > "$FNS"
+for _fn in _tg_security_log _esc _cb_label_ok _cb_enc _cb_dec _iso_to_epoch; do
+    awk "/^${_fn}\\(\\)/,/^}\$/" "$DAEMON" >> "$FNS"
+done
+awk '/^# >>> TG_MENU_BEGIN$/,/^# <<< TG_MENU_END$/' "$DAEMON" >> "$FNS"
+awk '/^# >>> TG_HISTORY_BEGIN$/,/^# <<< TG_HISTORY_END$/' "$DAEMON" >> "$FNS"
+assert_eq "extraction is valid bash" 0 "$(bash -n "$FNS" 2>/dev/null; echo $?)"
+assert_contains "the user-traffic reader ships in the daemon" "history_user_series()" "$(cat "$FNS")"
+
+SENDS="$TEST_TMPDIR/sends.log"
+EDITS="$TEST_TMPDIR/edits.log"
+_check_tg_role() { echo "superadmin"; }
+tg_send() { printf 'admin|%s\n' "$*" >> "$SENDS"; }
+tg_send_to() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_send_kb() { printf 'admin|%s\n' "$1" >> "$SENDS"; }
+tg_send_to_kb() { printf '%s|%s\n' "$1" "$2" >> "$SENDS"; }
+tg_answer_cb() { :; }
+tg_edit() { printf '%s\n---\n%s\n' "$3" "$4" > "$EDITS"; }
+tg_edit_markup() { :; }
+load_tg_settings() { :; }
+is_running() { return 1; }
+log_warn() { :; }
+get_cached_ip() { echo "203.0.113.9"; }
+_tg_metrics_raw() { printf ''; }
+_tg_have_python() { return 1; }
+
+source "$FNS"
+
+NOW=1000000
+# alice: a rising ramp across the last 24h, all in 4 hourly buckets.
+# Another user's rows sit in the same file to prove the reader filters.
+: > "$HISTORY_DIR/users.tsv"
+for _i in 1 2 3 4; do
+    printf '%s|alice|%s|%s\n' "$(( NOW - _i * 3600 ))" "$(( _i * 1000 ))" "$(( _i * 2000 ))" >> "$HISTORY_DIR/users.tsv"
+    printf '%s|bob|%s|%s\n' "$(( NOW - _i * 3600 ))" "$(( _i * 999999 ))" "$(( _i * 999999 ))" >> "$HISTORY_DIR/users.tsv"
+done
+
+# ── The reader ───────────────────────────────────────────────────────────────
+_series=$(history_user_series alice 86400 "$NOW" 24)
+assert_eq "the series has one bucket per slot" 24 "$(printf '%s' "$_series" | wc -w | tr -d ' ')"
+# alice's four buckets total 1000+2000+3000+4000 = 10000 in, 20000 out.
+assert_eq "the series sums only this user's rows" "30000" \
+    "$(printf '%s' "$_series" | tr ' ' '\n' | awk '{s+=$1} END {printf "%d", s+0}')"
+assert_eq "another user's rows are not counted" "0" \
+    "$(printf '%s' "$(history_user_series alice 86400 "$NOW" 24)" | grep -c '999999' || true)"
+
+# A user with no rows must report zeros, not nothing: an empty string would make
+# the card lose its sparkline row silently rather than drawing a flat one.
+_quiet=$(history_user_series quiet 86400 "$NOW" 24)
+assert_eq "a silent user still yields a full series" 24 "$(printf '%s' "$_quiet" | wc -w | tr -d ' ')"
+assert_eq "and it is all zeros" "0" "$(printf '%s' "$_quiet" | tr ' ' '\n' | awk '{s+=$1} END {printf "%d", s+0}')"
+
+# ── The card ─────────────────────────────────────────────────────────────────
+# The card reads the wall clock (a real tap has no other notion of "now"), so
+# the fixture has to be laid down relative to it rather than to the fixed epoch
+# the reader tests above use.
+_now=$(date +%s)
+: > "$HISTORY_DIR/users.tsv"
+for _i in 1 2 3 4; do
+    printf '%s|alice|%s|%s\n' "$(( _now - _i * 3600 ))" "$(( _i * 1000 ))" "$(( _i * 2000 ))" >> "$HISTORY_DIR/users.tsv"
+    printf '%s|bob|%s|%s\n' "$(( _now - _i * 3600 ))" "$(( _i * 999999 ))" "$(( _i * 999999 ))" >> "$HISTORY_DIR/users.tsv"
+done
+
+_UI_ROLE="superadmin"; _CB_CHAT="111"; _CB_MID="77"
+render_detail() { : > "$EDITS"; _cb_render_user_detail "${1:-alice}" 0; cat "$EDITS"; }
+render_card()   { : > "$EDITS"; _cb_render_user_traffic "${1:-alice}" 0 2>/dev/null; cat "$EDITS"; }
+
+_out=$(render_detail)
+assert_contains "the user card offers the traffic view" "u:t:alice:0" "$_out"
+
+_out=$(render_card)
+assert_contains "the traffic card reports the 24h window" "24h" "$_out"
+assert_contains "the traffic card reports the 7d window"  "7d"  "$_out"
+assert_contains "the traffic card reports the 30d window" "30d" "$_out"
+# 1000+2000+3000+4000 = 10000 bytes in and 20000 out, which format_bytes
+# renders in binary units: 9.8 KB up, 19.5 KB down.
+assert_contains "the traffic card reports this user's upload"   "↑ 9.8 KB"  "$_out"
+assert_contains "the traffic card reports this user's download" "↓ 19.5 KB" "$_out"
+assert_not_contains "the traffic card does not count another user" "3.8 MB" "$_out"
+assert_not_contains "the traffic card draws no code box" '```' "$_out"
+assert_contains "the traffic card goes back to the user card" "u:s:alice:0" "$_out"
+_bars=0
+for _g in ▁ ▂ ▃ ▄ ▅ ▆ ▇ █; do [[ "$_out" == *"$_g"* ]] && { _bars=1; break; }; done
+assert_eq "the traffic card draws a sparkline" 1 "$_bars"
+
+# A quiet user gets a flat line, not a missing row.
+_out=$(render_card quiet)
+assert_contains "a silent user still gets a card" "quiet" "$_out"
+assert_not_contains "a silent user's card draws no code box" '```' "$_out"
+
+# A label that is not a secret must not render a card. The label arrives through
+# callback_data, so it is attacker-controlled.
+assert_eq "a non-secret label renders nothing" "" "$(render_card '../etc')"
+
+# ── RBAC ─────────────────────────────────────────────────────────────────────
+assert_eq "the traffic card has a capability" "admin" "$(_tg_cap_for u t)"
+
+printf '\n%d tests, %d failures\n' "$TESTS_RUN" "$TESTS_FAILED"
+[ "$TESTS_FAILED" -eq 0 ]