metheus-governance-mcp-cli 0.2.100 → 0.2.102

package/README.md

@@ -58,8 +58,11 @@ TELEGRAM_BOT_TOKEN=
 
 ```env
 # ~/.metheus/telegram-bots/ryoai_bot.env
-TELEGRAM_BOT_NAME=ryoai_bot
-TELEGRAM_BOT_SERVER_BOT_ID=
+TELEGRAM_BOT_SERVER_BOT_ID=<server_bot_uuid>
+TELEGRAM_BOT_SERVER_NAME=RyoAI_bot
+TELEGRAM_BOT_SERVER_ROLES=monitor,review,worker,approval
+# Optional fallback only when server bot binding is unavailable
+# TELEGRAM_BOT_USERNAME=ryoai_bot
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_BOT_ROLE_PROFILE=
 TELEGRAM_BOT_AI_CLIENT=
@@ -223,15 +226,15 @@ Direct commands:
 
 ```bash
 metheus-governance-mcp-cli bot list
-metheus-governance-mcp-cli bot show --provider telegram --bot-key ryoai_bot
+metheus-governance-mcp-cli bot show --provider telegram --bot-name RyoAI_bot
 metheus-governance-mcp-cli bot add --provider telegram
 metheus-governance-mcp-cli bot edit
 metheus-governance-mcp-cli bot edit --provider telegram
 metheus-governance-mcp-cli bot remove --provider telegram
-metheus-governance-mcp-cli bot set-default --provider telegram --bot-key ryoai_bot
-metheus-governance-mcp-cli bot migrate --provider telegram --bot-key ryoai_bot
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-name RyoAI_bot
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-name RyoAI_bot
 metheus-governance-mcp-cli bot global --provider telegram
-metheus-governance-mcp-cli bot verify --provider telegram --bot-key ryoai_bot
+metheus-governance-mcp-cli bot verify --provider telegram --bot-name RyoAI_bot
 ```
 
 Behavior:
@@ -259,8 +262,10 @@ Behavior:
 - `bot verify` without flags starts a guided numbered flow: provider -> bot entry -> output format.
 - `bot remove` without flags starts a guided numbered flow: provider -> bot entry -> confirm removal.
 - Telegram stores one bot file per entry under `~/.metheus/telegram-bots/<server-bot-name>.env` with generic fields:
-  - `TELEGRAM_BOT_NAME`
   - `TELEGRAM_BOT_SERVER_BOT_ID`
+  - `TELEGRAM_BOT_SERVER_NAME`
+  - `TELEGRAM_BOT_SERVER_ROLES`
+  - `TELEGRAM_BOT_USERNAME` only as a fallback when server bot binding is unavailable
   - `TELEGRAM_BOT_TOKEN`
   - `TELEGRAM_BOT_ROLE_PROFILE`
   - `TELEGRAM_BOT_AI_CLIENT`
@@ -270,6 +275,7 @@ Behavior:
 - Slack and KakaoTalk currently use a single local token entry per provider in this command flow.
 - `bot verify` checks the configured local token, cross-checks the server bot binding, prints the effective runtime role profile summary that the runner will use, and shows which local runner routes currently point at this bot entry.
 - `bot show` prints one local bot entry in detail, including grouped role summaries when one server bot name expands to multiple roles and any linked local runner routes.
+- In `bot show` and `bot verify`, `stored_*` fields come from the local env file and `live_server_*` fields come from the current server `me/bots` response.
 - `bot global` edits Telegram-wide local settings such as API base URL, allowed updates, and default bot key.
 - `bot set-default` updates `TELEGRAM_DEFAULT_BOT_KEY`.
 - `bot migrate` moves legacy `TELEGRAM_BOT_TOKEN` into a named Telegram bot entry.
@@ -280,16 +286,16 @@ Non-interactive examples:
 metheus-governance-mcp-cli bot global --provider telegram --non-interactive true --api-base-url http://127.0.0.1:8999/telegram --auto-clear-webhook false --allowed-updates message,edited_message,channel_post
 metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --default true
 metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --ai-client gpt --ai-model "gpt-5.4" --ai-permission-mode read_only --ai-reasoning-effort low
-metheus-governance-mcp-cli bot edit --provider telegram --bot-key ryoai_bot --non-interactive true --ai-client claude --ai-model "Sonnet 4.6r" --ai-permission-mode danger_full_access --ai-reasoning-effort high
-metheus-governance-mcp-cli bot set-default --provider telegram --bot-key ryoai_bot --non-interactive true
-metheus-governance-mcp-cli bot migrate --provider telegram --bot-key ryoai_bot --server-bot-id <server_bot_uuid> --bot-name <telegram_username> --role-profile monitor --ai-client gpt --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
-metheus-governance-mcp-cli bot remove --provider telegram --bot-key ryoai_bot --non-interactive true
-metheus-governance-mcp-cli bot verify --provider telegram --bot-key ryoai_bot --json true
+metheus-governance-mcp-cli bot edit --provider telegram --bot-name RyoAI_bot --non-interactive true --ai-client claude --ai-model "Sonnet 4.6r" --ai-permission-mode danger_full_access --ai-reasoning-effort high
+metheus-governance-mcp-cli bot set-default --provider telegram --bot-name RyoAI_bot --non-interactive true
+metheus-governance-mcp-cli bot migrate --provider telegram --bot-name RyoAI_bot --server-bot-id <server_bot_uuid> --role-profile monitor --ai-client gpt --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
+metheus-governance-mcp-cli bot remove --provider telegram --bot-name RyoAI_bot --non-interactive true
+metheus-governance-mcp-cli bot verify --provider telegram --bot-name RyoAI_bot --json true
 ```
 
-For direct Telegram adds, the CLI can derive the local entry key from the matched server bot name. You no longer need `--bot-key` or `--username` in the normal server-bound path. Treat `--bot-key` as an advanced override only when you intentionally want a different local suffix.
+For direct Telegram adds, the CLI derives the local file name from the matched server bot name. You normally do not need `--bot-key` or `--username`. Treat `--bot-key` as an advanced compatibility selector only when you intentionally need a different local file stem.
 
-For direct Telegram edits, `--bot-key` still identifies which saved local entry to update. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
+For direct Telegram edits, prefer `--bot-name` or `--bot-id` because server bot identity is the source of truth. Use `--bot-key` only when you intentionally need the advanced local selector. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
 
 Current support status:
 

package/cli.mjs

@@ -241,13 +241,13 @@ function printUsage() {
       `  ${cmd} setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--workspace-fallback-dir <path>] [--name <server_name>]`,
       `  ${cmd} bot setup [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot list [--provider <telegram|slack|kakaotalk>] [--json <true|false>]`,
-      `  ${cmd} bot show [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>] [--json <true|false>]`,
+      `  ${cmd} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--json <true|false>]`,
       `  ${cmd} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot remove [--provider <telegram|slack|kakaotalk>]`,
-      `  ${cmd} bot set-default --provider telegram [--bot-key <key>]`,
-      `  ${cmd} bot migrate --provider telegram [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>]`,
-      `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--timeout-seconds <n>] [--json <true|false>]`,
+      `  ${cmd} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>]`,
+      `  ${cmd} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>]`,
+      `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--timeout-seconds <n>] [--json <true|false>]`,
       `  ${cmd} bot global --provider telegram [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
       `  ${cmd} doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>] [--strict <true|false>]`,
       `  ${cmd} proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--include-drafts <true|false>] [--auto-pull-on-conflict <true|false>] [--timeout-seconds <n>]`,
@@ -759,7 +759,7 @@ function providerEnvTemplate(provider) {
       "# Keep this file on your machine only. Do not commit it.",
       "# Store Telegram-wide settings here.",
       "# This global file now lives in ~/.metheus/telegram-bots/_global.env.",
-      "# Per-bot secrets and AI settings live in ~/.metheus/telegram-bots/<bot-key>.env.",
+      "# Per-bot secrets and AI settings live in ~/.metheus/telegram-bots/<server-bot-name>.env.",
       "# Project chat destinations must be managed on the Metheus server.",
       "",
       "TELEGRAM_API_BASE_URL=",
@@ -2684,12 +2684,35 @@ function parseTelegramAllowedUpdates(rawValue) {
   return Array.from(new Set(values));
 }
 
+function preferredTelegramServerRoleSort(roles) {
+  const order = ["monitor", "review", "worker", "approval"];
+  return ensureArray(roles).slice().sort((left, right) => {
+    const leftText = String(left || "").trim();
+    const rightText = String(right || "").trim();
+    const leftIndex = order.indexOf(leftText);
+    const rightIndex = order.indexOf(rightText);
+    if (leftIndex >= 0 && rightIndex >= 0) return leftIndex - rightIndex;
+    if (leftIndex >= 0) return -1;
+    if (rightIndex >= 0) return 1;
+    return leftText.localeCompare(rightText);
+  });
+}
+
+function parseTelegramServerRoles(rawValue) {
+  const values = String(rawValue || "")
+    .split(",")
+    .map((value) => String(value || "").trim())
+    .filter(Boolean);
+  if (!values.length) return [];
+  return Array.from(new Set(preferredTelegramServerRoleSort(values)));
+}
+
 function collectTelegramEnvBotEntries(parsedEnv) {
   const parsed = safeObject(parsedEnv);
   const entries = new Map();
   for (const [rawKey, rawValue] of Object.entries(parsed)) {
     const match = String(rawKey || "").trim().match(
-      /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i,
+      /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|SERVER_NAME|SERVER_ROLES|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i,
     );
     if (!match) continue;
     const botKey = normalizeTelegramBotEnvKey(match[1], "");
@@ -2700,6 +2723,8 @@ function collectTelegramEnvBotEntries(parsedEnv) {
       token: "",
       username: "",
       serverBotID: "",
+      serverBotName: "",
+      serverRoles: [],
       roleProfile: "",
       client: "",
       model: "",
@@ -2713,6 +2738,10 @@ function collectTelegramEnvBotEntries(parsedEnv) {
       entry.username = normalizeTelegramBotUsername(textValue);
     } else if (field === "SERVER_BOT_ID") {
       entry.serverBotID = textValue;
+    } else if (field === "SERVER_NAME") {
+      entry.serverBotName = textValue;
+    } else if (field === "SERVER_ROLES") {
+      entry.serverRoles = parseTelegramServerRoles(textValue);
     } else if (field === "ROLE_PROFILE") {
       entry.roleProfile = normalizeRunnerRoleProfileName(textValue);
     } else if (field === "AI_CLIENT") {
@@ -2738,6 +2767,8 @@ function collectTelegramEnvBotEntries(parsedEnv) {
 
 function telegramBotEntryDisplayNameForState(entry) {
   const current = safeObject(entry);
+  const serverBotName = String(current.serverBotName || "").trim();
+  if (serverBotName) return serverBotName;
   const username = normalizeTelegramBotUsername(current.username || "");
   if (username) return username;
   return normalizeTelegramBotEnvKey(current.key || "", "telegram_bot");
@@ -2747,11 +2778,16 @@ function parseTelegramBotEntryFile(filePath) {
   const raw = fs.readFileSync(filePath, "utf8");
   const parsed = parseSimpleEnvText(raw);
   const keyFromFile = normalizeTelegramBotEnvKey(path.basename(filePath, path.extname(filePath)), "telegram_bot");
-  const keyFromName = normalizeTelegramBotEnvKey(parsed.TELEGRAM_BOT_NAME || parsed.TELEGRAM_BOT_USERNAME || "", "");
+  const keyFromName = normalizeTelegramBotEnvKey(
+    parsed.TELEGRAM_BOT_USERNAME || parsed.TELEGRAM_BOT_NAME || parsed.TELEGRAM_BOT_SERVER_NAME || "",
+    "",
+  );
   return {
-    key: keyFromName || keyFromFile,
-    username: normalizeTelegramBotUsername(parsed.TELEGRAM_BOT_NAME || parsed.TELEGRAM_BOT_USERNAME || ""),
+    key: keyFromFile || keyFromName,
+    username: normalizeTelegramBotUsername(parsed.TELEGRAM_BOT_USERNAME || parsed.TELEGRAM_BOT_NAME || ""),
     serverBotID: String(parsed.TELEGRAM_BOT_SERVER_BOT_ID || "").trim(),
+    serverBotName: String(parsed.TELEGRAM_BOT_SERVER_NAME || "").trim(),
+    serverRoles: parseTelegramServerRoles(parsed.TELEGRAM_BOT_SERVER_ROLES || ""),
     token: String(parsed.TELEGRAM_BOT_TOKEN || "").trim(),
     roleProfile: normalizeRunnerRoleProfileName(parsed.TELEGRAM_BOT_ROLE_PROFILE || ""),
     client: normalizeLocalAIClientName(parsed.TELEGRAM_BOT_AI_CLIENT || "", ""),
@@ -2813,6 +2849,8 @@ function buildMergedTelegramEnvParsed(globalParsed, entries) {
     const upper = String(entry.key || "").trim().toUpperCase();
     if (!upper) return;
     merged[`TELEGRAM_BOT_${upper}_SERVER_BOT_ID`] = String(entry.serverBotID || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_SERVER_NAME`] = String(entry.serverBotName || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_SERVER_ROLES`] = ensureArray(entry.serverRoles).join(",");
     merged[`TELEGRAM_BOT_${upper}_USERNAME`] = normalizeTelegramBotUsername(entry.username || "");
     merged[`TELEGRAM_BOT_${upper}_TOKEN`] = String(entry.token || "").trim();
     merged[`TELEGRAM_BOT_${upper}_ROLE_PROFILE`] = String(entry.roleProfile || "").trim();
@@ -2874,12 +2912,14 @@ function readTelegramEnvState() {
 }
 
 function isTelegramEntryEnvKey(rawKey) {
-  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
+  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|SERVER_NAME|SERVER_ROLES|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
     .test(String(rawKey || "").trim());
 }
 
 function telegramEntryCommentNameForEnv(entry) {
   const current = safeObject(entry);
+  const serverBotName = String(current.serverBotName || "").trim();
+  if (serverBotName) return serverBotName;
   const username = normalizeTelegramBotUsername(current.username || "");
   if (username) return username;
   return normalizeTelegramBotEnvKey(current.key || "", "telegram_bot");
@@ -2896,7 +2936,7 @@ function renderNormalizedTelegramEnv(parsedEnv) {
     "# Keep this file on your machine only. Do not commit it.",
     "# Store Telegram-wide settings here.",
     "# This global file lives in ~/.metheus/telegram-bots/_global.env.",
-    "# Per-bot secrets and AI settings live in ~/.metheus/telegram-bots/<bot-key>.env.",
+    "# Per-bot secrets and AI settings live in ~/.metheus/telegram-bots/<server-bot-name>.env.",
     "",
     `TELEGRAM_API_BASE_URL=${formatProviderEnvValue(parsed.TELEGRAM_API_BASE_URL || "")}`,
     `TELEGRAM_AUTO_CLEAR_WEBHOOK=${boolFromRaw(parsed.TELEGRAM_AUTO_CLEAR_WEBHOOK, true) ? "true" : "false"}`,
@@ -2930,12 +2970,22 @@ function renderNormalizedTelegramEnv(parsedEnv) {
 function renderTelegramBotEntryEnv(entryRaw) {
   const entry = safeObject(entryRaw);
   const botName = telegramEntryCommentNameForEnv(entry);
+  const serverRoles = parseTelegramServerRoles(entry.serverRoles || "");
   const lines = [
     "# Metheus local Telegram bot entry",
-    `# Bot: ${botName}`,
+    `# Server bot: ${botName}`,
     "",
-    `TELEGRAM_BOT_NAME=${formatProviderEnvValue(botName)}`,
     `TELEGRAM_BOT_SERVER_BOT_ID=${formatProviderEnvValue(entry.serverBotID || "")}`,
+    `TELEGRAM_BOT_SERVER_NAME=${formatProviderEnvValue(entry.serverBotName || "")}`,
+    `TELEGRAM_BOT_SERVER_ROLES=${formatProviderEnvValue(serverRoles.join(","))}`,
+  ];
+  if (!String(entry.serverBotID || "").trim() && !String(entry.serverBotName || "").trim() && String(entry.username || "").trim()) {
+    lines.push(
+      "# Fallback only when server bot binding is unavailable",
+      `TELEGRAM_BOT_USERNAME=${formatProviderEnvValue(entry.username || "")}`,
+    );
+  }
+  lines.push(
     `TELEGRAM_BOT_TOKEN=${formatProviderEnvValue(entry.token || "")}`,
     `TELEGRAM_BOT_ROLE_PROFILE=${formatProviderEnvValue(entry.roleProfile || "")}`,
     `TELEGRAM_BOT_AI_CLIENT=${formatProviderEnvValue(entry.client || "")}`,
@@ -2943,7 +2993,7 @@ function renderTelegramBotEntryEnv(entryRaw) {
     `TELEGRAM_BOT_AI_PERMISSION_MODE=${formatProviderEnvValue(entry.permissionMode || "")}`,
     `TELEGRAM_BOT_AI_REASONING_EFFORT=${formatProviderEnvValue(entry.reasoningEffort || "")}`,
     "",
-  ];
+  );
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
@@ -2954,6 +3004,8 @@ function writeTelegramEnvState(parsedEnv) {
       entry.token
       || entry.username
       || entry.serverBotID
+      || entry.serverBotName
+      || ensureArray(entry.serverRoles).length
       || entry.roleProfile
       || entry.client
       || entry.model
@@ -3009,7 +3061,13 @@ function normalizeExistingProviderEnvFile(provider, filePath) {
 function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
   const parsed = safeObject(parsedEnv);
   const legacyToken = String(parsed.TELEGRAM_BOT_TOKEN || "").trim();
-  const entries = collectTelegramEnvBotEntries(parsed).filter((entry) => entry.token || entry.username || entry.serverBotID);
+  const entries = collectTelegramEnvBotEntries(parsed).filter((entry) => (
+    entry.token
+    || entry.username
+    || entry.serverBotID
+    || entry.serverBotName
+    || ensureArray(entry.serverRoles).length
+  ));
   const desiredBotID = firstNonEmptyString([
     selectors.serverBotID,
     selectors.botID,
@@ -3037,7 +3095,11 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
   }
   if (!selected && desiredUsername) {
     selected = entries.find(
-      (entry) => entry.username === desiredUsername || normalizeTelegramBotUsername(entry.key) === desiredUsername,
+      (entry) => (
+        entry.username === desiredUsername
+        || normalizeTelegramBotUsername(entry.serverBotName) === desiredUsername
+        || normalizeTelegramBotUsername(entry.key) === desiredUsername
+      ),
     ) || null;
   }
   if (!selected && desiredBotKey) {
@@ -3071,6 +3133,8 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
       botKey: selected.key,
       botUsername: selected.username,
       serverBotID: selected.serverBotID,
+      serverBotName: selected.serverBotName,
+      serverRoles: ensureArray(selected.serverRoles),
       roleProfile: selected.roleProfile,
       client: selected.client,
       model: selected.model,
@@ -3095,6 +3159,8 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
       botKey: "",
       botUsername: "",
       serverBotID: "",
+      serverBotName: "",
+      serverRoles: [],
       roleProfile: "",
       client: "",
       model: "",
@@ -5467,8 +5533,8 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     normalizedGlobalText.includes("TELEGRAM_DEFAULT_BOT_KEY=ryoai_bot")
       && !normalizedGlobalText.includes("TELEGRAM_BOT_RYOAI_BOT_TOKEN")
       && !normalizedGlobalText.includes("TELEGRAM_BOT_RYOAI_TOKEN")
-      && normalizedBotText.includes("TELEGRAM_BOT_NAME=ryoai_bot")
       && normalizedBotText.includes("TELEGRAM_BOT_SERVER_BOT_ID=bot-ryoai")
+      && normalizedBotText.includes("TELEGRAM_BOT_SERVER_NAME=")
       && normalizedBotText.includes("TELEGRAM_BOT_TOKEN=ryoai-token"),
     `${normalizedGlobalText}\n---\n${normalizedBotText}`,
   );

package/lib/bot-commands.mjs

@@ -216,20 +216,21 @@ function printBotUsage(deps) {
       "",
       `  ${cliName} bot setup`,
       `  ${cliName} bot list [--provider <telegram|slack|kakaotalk>] [--json <true|false>]`,
-      `  ${cliName} bot show [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>] [--json <true|false>]`,
+      `  ${cliName} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--json <true|false>]`,
       `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--server-bot-id <uuid>] [--token <token>] [--default <true|false>] [--verify <true|false>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>] [--bot-key <advanced_key>] [--username <fallback_name>] [--role-profile <name>]`,
-      `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-key <key>] [--server-bot-id <uuid>] [--username <name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>]`,
-      `  ${cliName} bot remove [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-key <key>]`,
-      `  ${cliName} bot set-default --provider telegram [--bot-key <key>] [--non-interactive <true|false>]`,
-      `  ${cliName} bot migrate --provider telegram [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>] [--keep-legacy-token <true|false>] [--non-interactive <true|false>]`,
-      `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--timeout-seconds <n>] [--json <true|false>]`,
-      `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
+      `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--username <fallback_name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>]`,
+      `  ${cliName} bot remove [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>]`,
+      `  ${cliName} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--non-interactive <true|false>]`,
+      `  ${cliName} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--keep-legacy-token <true|false>] [--non-interactive <true|false>]`,
+      `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--timeout-seconds <n>] [--json <true|false>]`,
+      `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <advanced_key>]`,
       "",
       `Behavior:`,
       `  - bot setup asks for provider first, then shows a numbered action menu.`,
       `  - bot add without flags uses the shortest practical guided flow: provider -> token -> verify -> optional username fallback -> optional default bot.`,
       `  - in the normal Telegram path, bot add does not ask for a local bot key or a server role/profile choice.`,
-      `  - server bot name/UUID is the source of truth; local key is auto-derived unless you intentionally override it with --bot-key.`,
+      `  - server bot name/UUID is the source of truth; --bot-key is an advanced local selector only.`,
+      `  - runner commands use --route-name, not bot name. Use bot verify/show first, then run the linked route.`,
       `  - bot edit without flags asks for provider, existing entry, then walks field-by-field in a numbered flow.`,
       `  - in the normal Telegram edit path, the CLI keeps or re-resolves the server bot binding automatically instead of asking you to pick a server role/profile UUID first.`,
       `  - bot set-default / bot verify / bot remove also support guided numbered selection when run without flags.`,
@@ -442,6 +443,8 @@ function telegramEntryEnvKeys(botKey) {
   const upper = String(botKey || "").trim().toUpperCase();
   return {
     serverBotID: `TELEGRAM_BOT_${upper}_SERVER_BOT_ID`,
+    serverBotName: `TELEGRAM_BOT_${upper}_SERVER_NAME`,
+    serverRoles: `TELEGRAM_BOT_${upper}_SERVER_ROLES`,
     username: `TELEGRAM_BOT_${upper}_USERNAME`,
     token: `TELEGRAM_BOT_${upper}_TOKEN`,
     roleProfile: `TELEGRAM_BOT_${upper}_ROLE_PROFILE`,
@@ -454,6 +457,8 @@ function telegramEntryEnvKeys(botKey) {
 
 function telegramEntryCommentName(entry) {
   const current = safeObject(entry);
+  const serverBotName = String(current.serverBotName || "").trim();
+  if (serverBotName) return serverBotName;
   const username = String(current.username || "").trim();
   if (username) return username;
   const key = String(current.key || "").trim();
@@ -465,6 +470,8 @@ function persistTelegramUsername(entry) {
   const current = safeObject(entry);
   if (current.__preferServerIdentity) return "";
   if (String(current.serverBotID || "").trim()) return "";
+  if (String(current.serverBotName || "").trim()) return "";
+  if (ensureArray(current.serverRoles).length) return "";
   return normalizeServerBotIdentityText(current.username || "");
 }
 
@@ -486,6 +493,8 @@ function upsertTelegramEntry(parsedEnv, entry) {
   const keys = telegramEntryEnvKeys(entry.key);
   const next = { ...parsed };
   next[keys.serverBotID] = String(entry.serverBotID || "").trim();
+  next[keys.serverBotName] = String(entry.serverBotName || "").trim();
+  next[keys.serverRoles] = ensureArray(entry.serverRoles).join(",");
   next[keys.username] = persistTelegramUsername(entry);
   next[keys.token] = String(entry.token || "").trim();
   next[keys.roleProfile] = String(entry.roleProfile || "").trim();
@@ -512,7 +521,7 @@ function telegramKnownKeys(parsedEnv, deps) {
 }
 
 function isTelegramEntryEnvKey(rawKey) {
-  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
+  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|SERVER_NAME|SERVER_ROLES|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
     .test(String(rawKey || "").trim());
 }
 
@@ -525,6 +534,8 @@ function renderTelegramEnv(parsedEnv, deps) {
       entry.token
       || entry.username
       || entry.serverBotID
+      || entry.serverBotName
+      || ensureArray(entry.serverRoles).length
       || entry.roleProfile
       || entry.client
       || entry.model
@@ -562,6 +573,8 @@ function renderTelegramEnv(parsedEnv, deps) {
       const entryLines = [
         `# Telegram bot entry: ${telegramEntryCommentName(entry)}`,
         `${keys.serverBotID}=${formatEnvValue(entry.serverBotID || "")}`,
+        `${keys.serverBotName}=${formatEnvValue(entry.serverBotName || "")}`,
+        `${keys.serverRoles}=${formatEnvValue(ensureArray(entry.serverRoles).join(","))}`,
       ];
       if (String(entry.username || "").trim()) {
         entryLines.push(`${keys.username}=${formatEnvValue(entry.username || "")}`);
@@ -615,6 +628,46 @@ function renderTokenOnlyProviderEnv(provider, parsedEnv, deps) {
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
+function renderTelegramBotEntryFile(entryRaw) {
+  const entry = safeObject(entryRaw);
+  const botName = telegramEntryCommentName(entry);
+  const serverRoles = ensureArray(entry.serverRoles).join(",");
+  const lines = [
+    "# Metheus local Telegram bot entry",
+    `# Server bot: ${botName}`,
+    "",
+    `TELEGRAM_BOT_SERVER_BOT_ID=${formatEnvValue(entry.serverBotID || "")}`,
+    `TELEGRAM_BOT_SERVER_NAME=${formatEnvValue(entry.serverBotName || "")}`,
+    `TELEGRAM_BOT_SERVER_ROLES=${formatEnvValue(serverRoles)}`,
+  ];
+  if (!String(entry.serverBotID || "").trim() && !String(entry.serverBotName || "").trim() && String(entry.username || "").trim()) {
+    lines.push(
+      "# Fallback only when server bot binding is unavailable",
+      `TELEGRAM_BOT_USERNAME=${formatEnvValue(entry.username || "")}`,
+    );
+  }
+  lines.push(
+    `TELEGRAM_BOT_TOKEN=${formatEnvValue(entry.token || "")}`,
+    `TELEGRAM_BOT_ROLE_PROFILE=${formatEnvValue(entry.roleProfile || "")}`,
+    `TELEGRAM_BOT_AI_CLIENT=${formatEnvValue(entry.client || "")}`,
+    `TELEGRAM_BOT_AI_MODEL=${formatEnvValue(entry.model || "")}`,
+    `TELEGRAM_BOT_AI_PERMISSION_MODE=${formatEnvValue(entry.permissionMode || "")}`,
+    `TELEGRAM_BOT_AI_REASONING_EFFORT=${formatEnvValue(entry.reasoningEffort || "")}`,
+    "",
+  );
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function rewriteTelegramEntryFile(entry, deps) {
+  const entryFilePath = String(requireDependency(deps, "telegramBotEntryFilePath")(entry.key) || "").trim();
+  if (!entryFilePath) return;
+  fs.mkdirSync(path.dirname(entryFilePath), { recursive: true });
+  fs.writeFileSync(entryFilePath, renderTelegramBotEntryFile(entry), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
 function writeProviderEnvState(provider, parsedEnv, deps) {
   if (provider === "telegram" && typeof deps?.writeTelegramEnvState === "function") {
     return deps.writeTelegramEnvState(parsedEnv);
@@ -644,6 +697,8 @@ function telegramEntriesForDisplay(parsedEnv, deps) {
       entry.token
       || entry.username
       || entry.serverBotID
+      || entry.serverBotName
+      || ensureArray(entry.serverRoles).length
       || entry.roleProfile
       || entry.client
       || entry.model
@@ -659,6 +714,8 @@ function telegramEntriesForDisplay(parsedEnv, deps) {
 
 function telegramEntryDisplayName(entry) {
   const current = safeObject(entry);
+  const serverBotName = String(current.serverBotName || "").trim();
+  if (serverBotName) return serverBotName;
   const username = String(current.username || "").trim();
   if (username) return `@${username}`;
   return String(current.key || "").trim() || "(unnamed)";
@@ -694,9 +751,9 @@ function formatRuntimeReasoningField(clientName, reasoningEffort, style = "equal
 function telegramEntryDisplayDescription(entry) {
   const current = safeObject(entry);
   const detail = [
-    current.key ? `key:${current.key}` : "",
-    current.serverBotID ? `server:${current.serverBotID}` : "",
-    current.client ? `AI:${displayLocalAIClientName(current.client)}` : "",
+    current.key ? `local_selector:${current.key}` : "",
+    current.serverBotID ? `stored_server_bot_id:${current.serverBotID}` : "",
+    current.client ? `ai_client:${displayLocalAIClientName(current.client)}` : "",
   ].filter(Boolean);
   return detail.join(" ");
 }
@@ -705,7 +762,9 @@ function findTelegramEntryByFlags(parsedEnv, flags, deps) {
   const entries = telegramEntriesForDisplay(parsedEnv, deps);
   const requestedKey = String(flags["bot-key"] || "").trim();
   const requestedBotID = String(flags["bot-id"] || flags["server-bot-id"] || "").trim();
-  const requestedName = requireDependency(deps, "normalizeTelegramBotUsername")(flags["bot-name"] || flags.username || "");
+  const requestedNameRaw = String(flags["bot-name"] || flags.username || "").trim();
+  const requestedUsername = requireDependency(deps, "normalizeTelegramBotUsername")(requestedNameRaw);
+  const requestedIdentity = normalizeServerBotIdentityText(requestedNameRaw);
   if (requestedKey) {
     const match = entries.find((entry) => entry.key === requestedKey);
     if (!match) {
@@ -720,12 +779,16 @@ function findTelegramEntryByFlags(parsedEnv, flags, deps) {
     }
     return match;
   }
-  if (requestedName) {
+  if (requestedNameRaw) {
     const match = entries.find(
-      (entry) => entry.username === requestedName || normalizeServerBotIdentityText(entry.key) === requestedName,
+      (entry) => (
+        entry.username === requestedUsername
+        || normalizeServerBotIdentityText(entry.serverBotName) === requestedIdentity
+        || normalizeServerBotIdentityText(entry.key) === requestedIdentity
+      ),
     );
     if (!match) {
-      throw new Error(`Telegram bot entry with server bot name "${requestedName}" was not found`);
+      throw new Error(`Telegram bot entry with server bot name "${requestedNameRaw}" was not found`);
     }
     return match;
   }
@@ -783,6 +846,7 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
     const initialBinding = await resolveTelegramServerBindingDetails(
       {
         serverBotID: current.serverBotID,
+        serverBotName: current.serverBotName,
         botUsername: current.username,
         botKey: current.key,
         roleProfile: current.roleProfile,
@@ -795,8 +859,13 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
       current.__preferServerIdentity = true;
       if (initialBinding.mode === "single") {
         current.serverBotID = String(initialBinding.serverBotID || "").trim();
+        current.serverBotName = String(initialBinding.name || "").trim();
+        current.serverRoles = ensureArray(initialBinding.roles);
         current.roleProfile = String(initialBinding.role || current.roleProfile || "").trim();
         applyRoleProfileDefaults(current, resolveRoleProfileDefaults(current.roleProfile, deps));
+      } else if (initialBinding.mode === "group") {
+        current.serverBotName = String(initialBinding.name || "").trim();
+        current.serverRoles = ensureArray(initialBinding.roles);
       }
     }
   }
@@ -847,6 +916,8 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
     const serverBot = await autoResolveTelegramServerBot(current, flags, deps);
     if (serverBot.matchMode === "group") {
       current.serverBotID = "";
+      current.serverBotName = String(serverBot.name || "").trim();
+      current.serverRoles = preferredRoleSort(serverBot.roles);
       current.__preferServerIdentity = true;
       current.roleProfile = "";
       current.client = "";
@@ -861,6 +932,8 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
       );
     } else if (String(serverBot.botID || "").trim()) {
       current.serverBotID = String(serverBot.botID || "").trim();
+      current.serverBotName = String(serverBot.name || "").trim();
+      current.serverRoles = ensureArray(serverBot.roles);
       current.__preferServerIdentity = true;
       current.roleProfile = String(serverBot.role || current.roleProfile || "").trim();
       serverRoleAutoResolved = String(serverBot.role || current.roleProfile || "").trim() || "__server_binding__";
@@ -995,6 +1068,8 @@ function renderBotListPayload(provider, state, deps) {
         key: entry.key,
         isDefault: entry.isDefault,
         serverBotID: entry.serverBotID,
+        serverBotName: entry.serverBotName,
+        serverRoles: ensureArray(entry.serverRoles),
         username: entry.username,
         tokenConfigured: Boolean(entry.token),
         roleProfile: entry.roleProfile,
@@ -1037,6 +1112,8 @@ function buildBotShowPayload(provider, state, entry, deps, extras = {}) {
         key: selectedEntry.key,
         isDefault: selectedEntry.isDefault,
         serverBotID: selectedEntry.serverBotID,
+        serverBotName: selectedEntry.serverBotName,
+        serverRoles: ensureArray(selectedEntry.serverRoles),
         username: selectedEntry.username,
         tokenConfigured: Boolean(selectedEntry.token),
         roleProfile: selectedEntry.roleProfile,
@@ -1133,9 +1210,9 @@ function printBotList(provider, state, deps) {
       process.stdout.write(
         [
           `  - ${telegramEntryDisplayName(entry)}${entry.isDefault ? " [default]" : ""}`,
-          `    key: ${entry.key || "-"}`,
+          `    local_selector: ${entry.key || "-"}${entry.key ? " (advanced)" : ""}`,
           `    server_bot_id: ${entry.serverBotID || "-"}`,
-          `    username: ${entry.username ? `@${entry.username}` : "-"}`,
+          `    fallback_username: ${entry.username ? `@${entry.username}` : "-"}`,
           `    token: ${entry.token ? maskSecret(entry.token) : "-"}`,
           `    role_profile: ${entry.roleProfile || "-"}`,
           `    ai_client: ${entry.client ? displayLocalAIClientName(entry.client) : "-"}`,
@@ -1159,11 +1236,13 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
     const routeLinks = safeObject(extras.routeLinks);
     process.stdout.write(`${providerLabel(provider, deps)} bot\n`);
     process.stdout.write(`  file: ${state.filePath}\n`);
-    process.stdout.write(`  name: ${telegramEntryDisplayName(selectedEntry)}\n`);
-    process.stdout.write(`  key: ${selectedEntry.key || "-"}\n`);
+    process.stdout.write(`  server_name: ${telegramEntryDisplayName(selectedEntry)}\n`);
+    process.stdout.write(`  local_selector: ${selectedEntry.key || "-"}${selectedEntry.key ? " (advanced)" : ""}\n`);
     process.stdout.write(`  default: ${selectedEntry.isDefault ? "yes" : "no"}\n`);
-    process.stdout.write(`  server_bot_id: ${selectedEntry.serverBotID || "-"}\n`);
-    process.stdout.write(`  username: ${selectedEntry.username ? `@${selectedEntry.username}` : "-"}\n`);
+    process.stdout.write(`  stored_server_bot_id: ${selectedEntry.serverBotID || "-"}\n`);
+    process.stdout.write(`  stored_server_name: ${selectedEntry.serverBotName || "-"}\n`);
+    process.stdout.write(`  stored_server_roles: ${ensureArray(selectedEntry.serverRoles).join(", ") || "-" }\n`);
+    process.stdout.write(`  fallback_username: ${selectedEntry.username ? `@${selectedEntry.username}` : "-"}\n`);
     process.stdout.write(`  token: ${selectedEntry.token ? maskSecret(selectedEntry.token) : "(not configured)"}\n`);
     process.stdout.write(`  role_profile: ${selectedEntry.roleProfile || "-"}\n`);
     process.stdout.write(`  ai_client: ${selectedEntry.client ? displayLocalAIClientName(selectedEntry.client) : "-"}\n`);
@@ -1172,17 +1251,17 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
     process.stdout.write(`  reasoning_effort: ${selectedEntry.reasoningEffort || "-"}\n`);
     if (Object.keys(serverBinding).length) {
       process.stdout.write(`  server_binding: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}\n`);
-      process.stdout.write(`  server_binding_mode: ${serverBinding.mode || "-"}\n`);
-      process.stdout.write(`  server_bot_name: ${serverBinding.name || "-"}\n`);
-      process.stdout.write(`  server_bot_id: ${serverBinding.serverBotID || selectedEntry.serverBotID || "-" }\n`);
+      process.stdout.write(`  binding_mode: ${serverBinding.mode || "-"}\n`);
+      process.stdout.write(`  live_server_name: ${serverBinding.name || "-"}\n`);
+      process.stdout.write(`  live_server_bot_id: ${serverBinding.serverBotID || selectedEntry.serverBotID || "-" }\n`);
       if (serverBinding.mode === "group") {
-        process.stdout.write(`  server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}\n`);
+        process.stdout.write(`  live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}\n`);
         const groupedProfiles = safeObject(serverBinding.effectiveRoleProfiles);
         Object.keys(groupedProfiles).forEach((role) => {
           process.stdout.write(`  runtime_role_profile[${role}]: ${formatRoleProfileOutputLine(groupedProfiles[role])}\n`);
         });
       } else if (serverBinding.effectiveRoleProfile) {
-        process.stdout.write(`  server_role: ${serverBinding.role || "-"}\n`);
+        process.stdout.write(`  live_server_role: ${serverBinding.role || "-"}\n`);
         process.stdout.write(`  runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}\n`);
       }
     }
@@ -1877,7 +1956,12 @@ async function maybePromptGroupedServerRoleProfiles(ui, serverBot, deps) {
 
 function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
   const current = safeObject(envConfig);
-  if (!String(current.serverBotID || "").trim() && !String(current.botUsername || "").trim() && !String(current.botKey || "").trim()) {
+  if (
+    !String(current.serverBotID || "").trim()
+    && !String(current.serverBotName || "").trim()
+    && !String(current.botUsername || "").trim()
+    && !String(current.botKey || "").trim()
+  ) {
     return null;
   }
   const resolveGroupedPayload = (matches, matchedBy) => {
@@ -1929,7 +2013,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
       detail: `${String(match.name || "").trim() || "(unnamed)"} [${String(match.role || "").trim() || "-"}]`,
     };
   }
-  const normalizedServerIdentity = normalizeServerBotIdentityText(current.botUsername || current.botKey);
+  const normalizedServerIdentity = normalizeServerBotIdentityText(current.serverBotName || current.botUsername || current.botKey);
   const matches = bots.filter((bot) => normalizeServerBotIdentityText(bot.name) === normalizedServerIdentity);
   if (!matches.length) {
     return {
@@ -2014,6 +2098,7 @@ async function buildTelegramEntrySelectionRows(entries, flags, deps) {
       ? resolveTelegramServerBindingDetailsFromBots(
         {
           serverBotID: current.serverBotID,
+          serverBotName: current.serverBotName,
           botUsername: current.username,
           botKey: current.key,
           roleProfile: current.roleProfile,
@@ -2034,9 +2119,9 @@ async function buildTelegramEntrySelectionRows(entries, flags, deps) {
       label = serverName;
     }
     const descriptionParts = [
-      current.key ? `local:${current.key}` : "",
-      current.serverBotID ? `server:${current.serverBotID}` : "",
-      current.client ? `AI:${displayLocalAIClientName(current.client)}` : "",
+      current.key ? `local_selector:${current.key} (advanced)` : "",
+      current.serverBotID ? `stored_server_bot_id:${current.serverBotID}` : "",
+      current.client ? `ai_client:${displayLocalAIClientName(current.client)}` : "",
     ].filter(Boolean);
     return {
       value: current.key,
@@ -2062,6 +2147,7 @@ async function verifyTelegramTokenCandidate(provider, token, apiBaseURL, timeout
 async function autoResolveTelegramServerBot(current, flags, deps) {
   const existingBotID = String(current?.serverBotID || "").trim();
   const preferredIdentity = firstNonEmptyString([
+    current?.serverBotName,
     current?.username,
     current?.key,
   ]);
@@ -2275,6 +2361,8 @@ async function addTelegramBot(ui, flags, deps) {
   const nextParsed = upsertTelegramEntry(parsed, {
     key: botKey,
     serverBotID: String(getServerBotIDFlag(flags) || serverBot.botID || "").trim(),
+    serverBotName: String(serverBot.name || "").trim(),
+    serverRoles: preferredRoleSort(serverBot.roles),
     username,
     __preferServerIdentity: serverBot.matchMode === "group" || Boolean(String(getServerBotIDFlag(flags) || serverBot.botID || "").trim()),
     token,
@@ -2391,6 +2479,23 @@ async function editTelegramBot(ui, flags, deps) {
     if (boolFromRaw(flags.default, false)) {
       parsed.TELEGRAM_DEFAULT_BOT_KEY = current.key;
     }
+    if (current.serverBotID || current.username || current.serverBotName) {
+      const resolvedServerBot = await autoResolveTelegramServerBot(current, flags, deps);
+      if (resolvedServerBot.matchMode === "group") {
+        current.serverBotID = String(getServerBotIDFlag(flags) || current.serverBotID || "").trim();
+        current.serverBotName = String(resolvedServerBot.name || current.serverBotName || "").trim();
+        current.serverRoles = preferredRoleSort(resolvedServerBot.roles);
+        if (!hasOwnFlag(flags, "role-profile")) current.roleProfile = "";
+        if (!(hasOwnFlag(flags, "client") || hasOwnFlag(flags, "ai-client"))) current.client = "";
+        if (!(hasOwnFlag(flags, "model") || hasOwnFlag(flags, "ai-model"))) current.model = "";
+        if (!(hasOwnFlag(flags, "permission-mode") || hasOwnFlag(flags, "ai-permission-mode"))) current.permissionMode = "";
+        if (!(hasOwnFlag(flags, "reasoning-effort") || hasOwnFlag(flags, "ai-reasoning-effort"))) current.reasoningEffort = "";
+      } else if (String(resolvedServerBot.botID || "").trim()) {
+        current.serverBotID = String(resolvedServerBot.botID || "").trim();
+        current.serverBotName = String(resolvedServerBot.name || "").trim();
+        current.serverRoles = ensureArray(resolvedServerBot.roles);
+      }
+    }
     saveTelegramBotEdit(parsed, selected, current, deps);
     return;
   }
@@ -2462,6 +2567,62 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
     if (serverBinding && !serverBinding.ok) {
       overallOK = false;
     }
+    if (serverBinding?.ok && envConfig.botKey) {
+      const selectedEntry = findTelegramEntryByFlags(
+        state.parsed,
+        { "bot-key": envConfig.botKey },
+        deps,
+      );
+      if (selectedEntry) {
+        const desiredServerBotName = String(serverBinding.name || "").trim();
+        const desiredServerRoles = ensureArray(serverBinding.roles);
+        const currentServerRoles = ensureArray(selectedEntry.serverRoles);
+        const currentServerRolesJoined = currentServerRoles.join(",");
+        const desiredServerRolesJoined = desiredServerRoles.join(",");
+        const desiredServerBotID = (
+          String(selectedEntry.serverBotID || "").trim()
+          || (serverBinding.mode === "single" ? String(serverBinding.serverBotID || "").trim() : "")
+        );
+        const needsMetadataBackfill = (
+          String(selectedEntry.serverBotName || "").trim() !== desiredServerBotName
+          || currentServerRolesJoined !== desiredServerRolesJoined
+          || String(selectedEntry.serverBotID || "").trim() !== desiredServerBotID
+        );
+        if (needsMetadataBackfill) {
+          const nextEntry = {
+            ...selectedEntry,
+            serverBotID: desiredServerBotID,
+            serverBotName: desiredServerBotName,
+            serverRoles: desiredServerRoles,
+          };
+          const nextParsed = upsertTelegramEntry(state.parsed, nextEntry);
+          writeProviderEnvState("telegram", nextParsed, deps);
+          rewriteTelegramEntryFile(nextEntry, deps);
+          envConfig.serverBotID = desiredServerBotID;
+          envConfig.serverBotName = desiredServerBotName;
+          envConfig.serverRoles = desiredServerRoles;
+        }
+        const rewriteEntry = needsMetadataBackfill
+          ? {
+            ...selectedEntry,
+            serverBotID: desiredServerBotID,
+            serverBotName: desiredServerBotName,
+            serverRoles: desiredServerRoles,
+          }
+          : selectedEntry;
+        const currentEntryFilePath = String(
+          rewriteEntry.entryFilePath
+          || requireDependency(deps, "telegramBotEntryFilePath")(rewriteEntry.key),
+        ).trim();
+        const expectedEntryText = renderTelegramBotEntryFile(rewriteEntry);
+        const currentEntryText = currentEntryFilePath && fs.existsSync(currentEntryFilePath)
+          ? fs.readFileSync(currentEntryFilePath, "utf8")
+          : "";
+        if (currentEntryText !== expectedEntryText) {
+          rewriteTelegramEntryFile(rewriteEntry, deps);
+        }
+      }
+    }
     routeLinks = summarizeTelegramRouteLinks(state.parsed, {
       key: envConfig.botKey,
       serverBotID: envConfig.serverBotID,
@@ -2492,6 +2653,8 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
         filePath: envConfig.filePath,
         botKey: envConfig.botKey || "",
         serverBotID: envConfig.serverBotID || "",
+        serverBotName: envConfig.serverBotName || "",
+        serverRoles: ensureArray(envConfig.serverRoles),
         detail: result.detail || "",
         roleProfile: envConfig.roleProfile || "",
         client: envConfig.client || "",
@@ -2506,8 +2669,10 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
     const lines = [
       `${providerLabel(provider, deps)} verify: ${overallOK ? "OK" : "FAIL"}`,
       `file: ${envConfig.filePath}`,
-      provider === "telegram" ? `bot_key: ${envConfig.botKey || "-"}` : "",
-      provider === "telegram" ? `server_bot_id: ${envConfig.serverBotID || "-"}` : "",
+      provider === "telegram" ? `local_selector: ${envConfig.botKey || "-"}${envConfig.botKey ? " (advanced)" : ""}` : "",
+      provider === "telegram" ? `stored_server_bot_id: ${envConfig.serverBotID || "-"}` : "",
+      provider === "telegram" ? `stored_server_name: ${envConfig.serverBotName || "-"}` : "",
+      provider === "telegram" ? `stored_server_roles: ${ensureArray(envConfig.serverRoles).join(", ") || "-"}` : "",
       provider === "telegram" ? `role_profile: ${envConfig.roleProfile || "-"}` : "",
       provider === "telegram" ? `ai_client: ${envConfig.client ? displayLocalAIClientName(envConfig.client) : "-"}` : "",
       provider === "telegram" ? `ai_model: ${envConfig.model || "-"}` : "",
@@ -2518,9 +2683,9 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
       routeLinks ? `route_links: ${intFromRaw(routeLinks.total, 0)}` : "",
     ].filter(Boolean);
     if (provider === "telegram" && serverBinding) {
-      lines.push(`server_binding_mode: ${serverBinding.mode || "-"}`);
-      lines.push(`server_bot_name: ${serverBinding.name || "-"}`);
-      lines.push(`server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`);
+      lines.push(`binding_mode: ${serverBinding.mode || "-"}`);
+      lines.push(`live_server_name: ${serverBinding.name || "-"}`);
+      lines.push(`live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`);
       if (serverBinding.mode === "group") {
         const groupedProfiles = safeObject(serverBinding.effectiveRoleProfiles);
         Object.keys(groupedProfiles).forEach((role) => {

package/lib/selftest-bot-commands.mjs

@@ -352,14 +352,15 @@ export async function runSelftestBotCommands(push, deps) {
     const addGlobals = readTelegramGlobals();
     push(
       "bot_add_guided_creates_named_telegram_entry",
-      String(addState.TELEGRAM_BOT_NAME || "").toLowerCase().includes("monitorselftestbot")
+      String(addState.TELEGRAM_BOT_SERVER_NAME || "") === "MonitorSelftestBot"
+        && String(addState.TELEGRAM_BOT_SERVER_ROLES || "") === "monitor"
         && String(addState.TELEGRAM_BOT_TOKEN || "") === "selftest-main-token"
         && String(addState.TELEGRAM_BOT_ROLE_PROFILE || "") === "monitor"
         && String(addState.TELEGRAM_BOT_AI_CLIENT || "") === "codex"
         && String(addState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "read_only"
         && String(addState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "low"
         && String(addGlobals.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
-      `default=${String(addGlobals.TELEGRAM_DEFAULT_BOT_KEY || "")} token=${String(addState.TELEGRAM_BOT_TOKEN || "")} role=${String(addState.TELEGRAM_BOT_ROLE_PROFILE || "")} client=${String(addState.TELEGRAM_BOT_AI_CLIENT || "")}`,
+      `default=${String(addGlobals.TELEGRAM_DEFAULT_BOT_KEY || "")} token=${String(addState.TELEGRAM_BOT_TOKEN || "")} server_name=${String(addState.TELEGRAM_BOT_SERVER_NAME || "")} roles=${String(addState.TELEGRAM_BOT_SERVER_ROLES || "")} role=${String(addState.TELEGRAM_BOT_ROLE_PROFILE || "")} client=${String(addState.TELEGRAM_BOT_AI_CLIENT || "")}`,
     );
 
     const groupedMock = await createMockServer({
@@ -401,12 +402,13 @@ export async function runSelftestBotCommands(push, deps) {
       const groupedState = readTelegramBotEntry("ryoai_bot");
     push(
       "bot_add_guided_autoresolves_server_bot_group_without_role_prompt",
-        String(groupedState.TELEGRAM_BOT_NAME || "").toLowerCase() === "ryoai_bot"
-          && String(groupedState.TELEGRAM_BOT_SERVER_BOT_ID || "") === ""
+        String(groupedState.TELEGRAM_BOT_SERVER_BOT_ID || "") === ""
+          && String(groupedState.TELEGRAM_BOT_SERVER_NAME || "") === "RyoAI_bot"
+          && String(groupedState.TELEGRAM_BOT_SERVER_ROLES || "") === "monitor,review,worker,approval"
           && String(groupedState.TELEGRAM_BOT_ROLE_PROFILE || "") === ""
           && String(groupedState.TELEGRAM_BOT_AI_CLIENT || "") === ""
           && String(groupedState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "",
-        `name=${String(groupedState.TELEGRAM_BOT_NAME || "")} server_bot_id=${String(groupedState.TELEGRAM_BOT_SERVER_BOT_ID || "")} role=${String(groupedState.TELEGRAM_BOT_ROLE_PROFILE || "")}`,
+        `server_name=${String(groupedState.TELEGRAM_BOT_SERVER_NAME || "")} roles=${String(groupedState.TELEGRAM_BOT_SERVER_ROLES || "")} server_bot_id=${String(groupedState.TELEGRAM_BOT_SERVER_BOT_ID || "")} role=${String(groupedState.TELEGRAM_BOT_ROLE_PROFILE || "")}`,
       );
 
       const groupedEditResult = await runCLI({
@@ -758,11 +760,13 @@ export async function runSelftestBotCommands(push, deps) {
     push(
       "bot_add_accepts_ai_prefixed_option_aliases",
       String(aliasAddState.TELEGRAM_BOT_SERVER_BOT_ID || "") === mock.bots[0].id
+        && String(aliasAddState.TELEGRAM_BOT_SERVER_NAME || "") === "MonitorSelftestBot"
+        && String(aliasAddState.TELEGRAM_BOT_SERVER_ROLES || "") === "monitor"
         && String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "") === "codex"
         && String(aliasAddState.TELEGRAM_BOT_AI_MODEL || "") === "gpt-5.4"
         && String(aliasAddState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "read_only"
         && String(aliasAddState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "low",
-      `client=${String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "")} model=${String(aliasAddState.TELEGRAM_BOT_AI_MODEL || "")}`,
+      `server_name=${String(aliasAddState.TELEGRAM_BOT_SERVER_NAME || "")} roles=${String(aliasAddState.TELEGRAM_BOT_SERVER_ROLES || "")} client=${String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "")} model=${String(aliasAddState.TELEGRAM_BOT_AI_MODEL || "")}`,
     );
 
     const guidedRemoveBeforeList = await runCLI({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metheus-governance-mcp-cli",
-  "version": "0.2.100",
+  "version": "0.2.102",
   "description": "Metheus Governance MCP CLI (setup + stdio proxy)",
   "type": "module",
   "files": [