metheus-governance-mcp-cli 0.2.102 → 0.2.103

package/README.md

@@ -31,9 +31,9 @@ Install creates local provider settings templates here:
 These files are for local provider bot secrets, local transport options, and optional per-bot local AI binding.
 
 - Store locally:
-  - Telegram-wide settings in `~/.metheus/telegram-bots/_global.env`
-  - `TELEGRAM_BOT_TOKEN` as a legacy Telegram fallback in `_global.env`
-  - one Telegram bot file per entry in `~/.metheus/telegram-bots/<server-bot-name>.env`
+  - Telegram-wide settings in `~/.metheus/telegram-bots/global.env`
+  - `TELEGRAM_BOT_TOKEN` as a legacy Telegram fallback in `global.env`
+  - one Telegram bot file per entry in `~/.metheus/telegram-bots/<ServerBotName>.env`
   - `SLACK_BOT_TOKEN`
   - `KAKAOTALK_BOT_TOKEN`
 - Server-side Metheus stores project chat destination metadata separately:
@@ -41,12 +41,13 @@ These files are for local provider bot secrets, local transport options, and opt
   - `chat_id` / channel / room identifier
   - label / active state
 - Do not put project chat destination identifiers in local env files.
-- Telegram-wide settings now live in `telegram-bots/_global.env`; Telegram per-bot secrets and AI fields live in `telegram-bots/*.env`.
+- Telegram-wide settings now live in `telegram-bots/global.env`; Telegram per-bot secrets and server metadata live in `telegram-bots/*.env`.
+- Grouped server bots also persist `TELEGRAM_BOT_SERVER_ROLE_IDS`, so the local file keeps the exact role-to-server-bot-id mapping instead of pretending that one grouped bot has only one server UUID.
 
 Example templates:
 
 ```env
-# ~/.metheus/telegram-bots/_global.env
+# ~/.metheus/telegram-bots/global.env
 TELEGRAM_API_BASE_URL=
 TELEGRAM_AUTO_CLEAR_WEBHOOK=true
 TELEGRAM_ALLOWED_UPDATES=message,edited_message
@@ -57,10 +58,11 @@ TELEGRAM_BOT_TOKEN=
 ```
 
 ```env
-# ~/.metheus/telegram-bots/ryoai_bot.env
+# ~/.metheus/telegram-bots/RyoAI_bot.env
 TELEGRAM_BOT_SERVER_BOT_ID=<server_bot_uuid>
 TELEGRAM_BOT_SERVER_NAME=RyoAI_bot
 TELEGRAM_BOT_SERVER_ROLES=monitor,review,worker,approval
+TELEGRAM_BOT_SERVER_ROLE_IDS=monitor:<uuid>,review:<uuid>,worker:<uuid>,approval:<uuid>
 # Optional fallback only when server bot binding is unavailable
 # TELEGRAM_BOT_USERNAME=ryoai_bot
 TELEGRAM_BOT_TOKEN=
@@ -172,10 +174,12 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
 
+Bootstrap or setup does not create one file per server bot automatically. Per-bot Telegram files are created later when you run `bot add`, `bot verify`, or `bot edit` against a real server bot identity.
+
 When Telegram local config already exists, bootstrap/setup keeps your secrets but auto-normalizes the layout to the latest split structure:
 
-- Telegram-wide settings stay in `~/.metheus/telegram-bots/_global.env`
-- per-bot secrets move to `~/.metheus/telegram-bots/<server-bot-name>.env`
+- Telegram-wide settings stay in `~/.metheus/telegram-bots/global.env`
+- per-bot secrets move to `~/.metheus/telegram-bots/<ServerBotName>.env`
 - stale inline keys such as `TELEGRAM_BOT_<NAME>_BOT_*` are rewritten into generic per-bot keys
 
 Fill provider bot secrets and provider-local transport options locally. Project chat destination identifiers should be managed on the Metheus server as project chat destinations, not as local env values and not inside legacy Chat Hooks/webhooks.
@@ -185,7 +189,7 @@ Fill provider bot secrets and provider-local transport options locally. Project
 - which provider/role bot profile to use
 - which `project_id -> workspace_dir` mapping to apply locally
 - which role profile maps to which local CLI/model/permission/reasoning policy
-- which server bot maps to which local LLM execution profile via `telegram-bots/_global.env`, `telegram-bots/*.env`, or fallback `bot_bindings`
+- which server bot maps to which local LLM execution profile via `telegram-bots/global.env`, `telegram-bots/*.env`, or fallback `bot_bindings`
 
 Built-in helper command for legacy fallback/testing:
 
@@ -261,10 +265,11 @@ Behavior:
 - `bot set-default` without flags starts a guided numbered flow: provider -> bot entry -> confirm default change.
 - `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 stores one bot file per entry under `~/.metheus/telegram-bots/<ServerBotName>.env` with generic fields:
   - `TELEGRAM_BOT_SERVER_BOT_ID`
   - `TELEGRAM_BOT_SERVER_NAME`
   - `TELEGRAM_BOT_SERVER_ROLES`
+  - `TELEGRAM_BOT_SERVER_ROLE_IDS`
   - `TELEGRAM_BOT_USERNAME` only as a fallback when server bot binding is unavailable
   - `TELEGRAM_BOT_TOKEN`
   - `TELEGRAM_BOT_ROLE_PROFILE`
@@ -293,7 +298,7 @@ metheus-governance-mcp-cli bot remove --provider telegram --bot-name RyoAI_bot -
 metheus-governance-mcp-cli bot verify --provider telegram --bot-name RyoAI_bot --json true
 ```
 
-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 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 to target an older local selector directly.
 
 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.
 
@@ -377,6 +382,7 @@ Execution model:
 Commands:
 
 ```bash
+metheus-governance-mcp-cli runner list
 metheus-governance-mcp-cli runner once --route-name telegram-monitor
 metheus-governance-mcp-cli runner start --route-name telegram-monitor
 ```
@@ -403,7 +409,7 @@ Recommended production path:
 - keep `project_mappings.<project_id>.workspace_dir` aligned to that teammate's actual local project folder
 - let `ctxpack pull` or project connection refresh the mapping automatically
 - keep per-role execution policy under `role_profiles`
-- keep Telegram-wide binding defaults in `~/.metheus/telegram-bots/_global.env`
+- keep Telegram-wide binding defaults in `~/.metheus/telegram-bots/global.env`
 - use `bot_bindings` in `bot-runner.json` only as local fallback/override
 - runner resolution order is: explicit `route.role_profile` -> provider env bot binding -> `bot_bindings` -> server bot role -> `route.role`
 
@@ -476,7 +482,7 @@ Notes:
 - `local-bot-bridge` reads stdin JSON from the runner and can call Codex/Claude/Gemini for you
 - `route.command` fallback is disabled by default; enable it only temporarily with `METHEUS_ALLOW_LEGACY_RUNNER_COMMAND=1`
 - today this automation path is implemented for Telegram end-to-end
-- prefer `TELEGRAM_API_BASE_URL=` inside `~/.metheus/telegram-bots/_global.env` for local Telegram API overrides; `METHEUS_TELEGRAM_API_BASE_URL` remains a process-level fallback mainly for mock/regression testing
+- prefer `TELEGRAM_API_BASE_URL=` inside `~/.metheus/telegram-bots/global.env` for local Telegram API overrides; `METHEUS_TELEGRAM_API_BASE_URL` remains a process-level fallback mainly for mock/regression testing
 - Slack can use direct local send, but automatic inbound runner flow is not completed yet
 - KakaoTalk config can be stored now, but direct send/runner flow is not implemented yet
 - `doctor` now reports provider support for both enabled runner routes and active project chat destinations

package/cli.mjs

@@ -154,8 +154,9 @@ const AUTH_STORE_RELATIVE_PATH = path.join(".metheus", "governance-mcp-auth.json
 const BOT_RUNNER_CONFIG_RELATIVE_PATH = path.join(".metheus", "bot-runner.json");
 const BOT_RUNNER_STATE_RELATIVE_PATH = path.join(".metheus", "bot-runner-state.json");
 const BOT_RUNNER_CONFIG_VERSION = 2;
-const TELEGRAM_LEGACY_ENV_RELATIVE_PATH = path.join(".metheus", "telegram.env");
-const TELEGRAM_GLOBAL_ENV_RELATIVE_PATH = path.join(".metheus", "telegram-bots", "_global.env");
+const TELEGRAM_ROOT_LEGACY_ENV_RELATIVE_PATH = path.join(".metheus", "telegram.env");
+const TELEGRAM_LEGACY_GLOBAL_ENV_RELATIVE_PATH = path.join(".metheus", "telegram-bots", "_global.env");
+const TELEGRAM_GLOBAL_ENV_RELATIVE_PATH = path.join(".metheus", "telegram-bots", "global.env");
 const PROVIDER_ENV_CONFIG = {
   telegram: {
     relativePath: TELEGRAM_GLOBAL_ENV_RELATIVE_PATH,
@@ -253,6 +254,7 @@ function printUsage() {
       `  ${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>]`,
       `  ${cmd} selftest [--json <true|false>]`,
       `  ${cmd} local-bot-bridge [--client <codex|claude|gemini|sample>] [--cwd <path>] [--model <name>] [--permission-mode <read_only|workspace_write|danger_full_access>] [--reasoning-effort <low|medium|high>]`,
+      `  ${cmd} runner list [--json <true|false>]`,
       `  ${cmd} runner once [--route-name <name>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--bot-name <name>] [--bot-id <uuid>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--context-comments <n>] [--archive-replies <true|false>]`,
       `  ${cmd} runner start [--route-name <name>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--bot-name <name>] [--bot-id <uuid>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--poll-interval-ms <n>] [--context-comments <n>] [--archive-replies <true|false>]`,
       `  ${cmd} ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path|auto>] [--paths <csv>] [--timeout-seconds <n>]`,
@@ -739,18 +741,57 @@ function providerEnvFilePath(provider) {
 }
 
 function telegramLegacyEnvFilePath() {
-  return resolveHomeFilePath(TELEGRAM_LEGACY_ENV_RELATIVE_PATH);
+  return resolveHomeFilePath(TELEGRAM_ROOT_LEGACY_ENV_RELATIVE_PATH);
+}
+
+function telegramLegacyGlobalEnvFilePath() {
+  return resolveHomeFilePath(TELEGRAM_LEGACY_GLOBAL_ENV_RELATIVE_PATH);
 }
 
 function telegramBotEntriesDirPath() {
   return resolveHomeFilePath(".metheus/telegram-bots");
 }
 
+function normalizeComparablePath(rawPath) {
+  const resolved = path.resolve(String(rawPath || ""));
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function sanitizeTelegramBotFileStem(rawValue, fallback = "telegram_bot") {
+  const text = String(rawValue || "")
+    .trim()
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, "_")
+    .replace(/\s+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return text || fallback;
+}
+
 function telegramBotEntryFilePath(botKey) {
   const normalizedKey = normalizeTelegramBotEnvKey(botKey || "", "telegram_bot") || "telegram_bot";
   return path.join(telegramBotEntriesDirPath(), `${normalizedKey}.env`);
 }
 
+function telegramBotEntryFilePathForEntry(entryRaw) {
+  const entry = safeObject(entryRaw);
+  const fallbackKey = normalizeTelegramBotEnvKey(entry.key || "", "telegram_bot") || "telegram_bot";
+  const preferredStem = sanitizeTelegramBotFileStem(
+    firstNonEmptyString([entry.serverBotName, entry.username, entry.key]),
+    fallbackKey,
+  );
+  return path.join(telegramBotEntriesDirPath(), `${preferredStem}.env`);
+}
+
+function findTelegramEntryPathVariant(targetPath) {
+  const dirPath = path.dirname(targetPath);
+  if (!fs.existsSync(dirPath)) return "";
+  const targetComparable = normalizeComparablePath(targetPath);
+  const match = fs.readdirSync(dirPath, { withFileTypes: true })
+    .filter((item) => item.isFile() && /\.env$/i.test(item.name))
+    .map((item) => path.join(dirPath, item.name))
+    .find((candidatePath) => normalizeComparablePath(candidatePath) === targetComparable);
+  return String(match || "").trim();
+}
+
 function providerEnvTemplate(provider) {
   const config = providerEnvConfig(provider);
   if (normalizeBotProvider(provider) === "telegram") {
@@ -758,7 +799,7 @@ function providerEnvTemplate(provider) {
       "# Metheus local Telegram bot settings",
       "# 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.",
+      "# This global file now lives in ~/.metheus/telegram-bots/global.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.",
       "",
@@ -2525,6 +2566,57 @@ async function runRunnerOnce(flags) {
   }
 }
 
+function buildRunnerRouteListRows() {
+  const config = loadBotRunnerConfig({ persistIfNeeded: true });
+  return ensureArray(config.routes).map((rawRoute, index) => {
+    const route = normalizeRunnerRoute(rawRoute);
+    return {
+      index: index + 1,
+      name: route.name || runnerRouteKey(route),
+      enabled: route.enabled !== false,
+      provider: route.provider || "-",
+      projectID: route.projectID || "-",
+      botName: route.botName || "-",
+      botID: route.botID || "-",
+      role: route.role || "-",
+      roleProfile: route.roleProfile || "-",
+      destinationLabel: route.destinationLabel || "-",
+      pollIntervalMs: route.pollIntervalMs || 0,
+      configFilePath: config.filePath,
+    };
+  });
+}
+
+async function runRunnerList(flags) {
+  const rows = buildRunnerRouteListRows();
+  if (boolFromRaw(flags.json, false)) {
+    process.stdout.write(`${JSON.stringify({ ok: true, routes: rows }, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write("Runner routes\n");
+  if (!rows.length) {
+    process.stdout.write("  none configured\n");
+    return;
+  }
+  process.stdout.write(`  file: ${rows[0].configFilePath}\n`);
+  rows.forEach((row) => {
+    process.stdout.write(
+      [
+        `  - ${row.name}${row.enabled ? "" : " [disabled]"}`,
+        `    provider: ${row.provider}`,
+        `    project_id: ${row.projectID}`,
+        `    bot_name: ${row.botName}`,
+        `    bot_id: ${row.botID}`,
+        `    role: ${row.role}`,
+        `    role_profile: ${row.roleProfile}`,
+        `    destination_label: ${row.destinationLabel}`,
+        `    poll_interval_ms: ${row.pollIntervalMs}`,
+        `    run_once: ${CLI_NAME} runner once --route-name ${row.name}`,
+      ].join("\n") + "\n",
+    );
+  });
+}
+
 async function runRunnerStart(flags) {
   const jsonMode = boolFromRaw(flags.json, false);
   const routes = resolveRunnerRoutes(flags, "start");
@@ -2585,6 +2677,10 @@ async function runRunner(argv) {
   const [subcommandRaw = "", ...rest] = argv;
   const subcommand = String(subcommandRaw || "").trim().toLowerCase();
   const flags = parseArgs(rest);
+  if (subcommand === "list") {
+    await runRunnerList(flags);
+    return;
+  }
   if (subcommand === "once") {
     await runRunnerOnce(flags);
     return;
@@ -2593,7 +2689,7 @@ async function runRunner(argv) {
     await runRunnerStart(flags);
     return;
   }
-  throw new Error("runner requires a subcommand: once | start");
+  throw new Error("runner requires a subcommand: list | once | start");
 }
 
 async function runLocalBotBridge(argv) {
@@ -2707,12 +2803,39 @@ function parseTelegramServerRoles(rawValue) {
   return Array.from(new Set(preferredTelegramServerRoleSort(values)));
 }
 
+function parseTelegramServerRoleIDs(rawValue) {
+  const output = {};
+  String(rawValue || "")
+    .split(",")
+    .map((value) => String(value || "").trim())
+    .filter(Boolean)
+    .forEach((pair) => {
+      const separatorIndex = pair.indexOf(":");
+      if (separatorIndex <= 0) return;
+      const role = String(pair.slice(0, separatorIndex) || "").trim();
+      const id = String(pair.slice(separatorIndex + 1) || "").trim();
+      if (!role || !id) return;
+      output[role] = id;
+    });
+  return preferredTelegramServerRoleSort(Object.keys(output)).reduce((acc, role) => {
+    acc[role] = output[role];
+    return acc;
+  }, {});
+}
+
+function formatTelegramServerRoleIDs(roleIDs) {
+  return preferredTelegramServerRoleSort(Object.keys(safeObject(roleIDs)))
+    .map((role) => `${role}:${String(safeObject(roleIDs)[role] || "").trim()}`)
+    .filter((item) => !item.endsWith(":"))
+    .join(",");
+}
+
 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|SERVER_NAME|SERVER_ROLES|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|SERVER_ROLE_IDS|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i,
     );
     if (!match) continue;
     const botKey = normalizeTelegramBotEnvKey(match[1], "");
@@ -2725,6 +2848,7 @@ function collectTelegramEnvBotEntries(parsedEnv) {
       serverBotID: "",
       serverBotName: "",
       serverRoles: [],
+      serverRoleIDs: {},
       roleProfile: "",
       client: "",
       model: "",
@@ -2742,6 +2866,8 @@ function collectTelegramEnvBotEntries(parsedEnv) {
       entry.serverBotName = textValue;
     } else if (field === "SERVER_ROLES") {
       entry.serverRoles = parseTelegramServerRoles(textValue);
+    } else if (field === "SERVER_ROLE_IDS") {
+      entry.serverRoleIDs = parseTelegramServerRoleIDs(textValue);
     } else if (field === "ROLE_PROFILE") {
       entry.roleProfile = normalizeRunnerRoleProfileName(textValue);
     } else if (field === "AI_CLIENT") {
@@ -2788,6 +2914,7 @@ function parseTelegramBotEntryFile(filePath) {
     serverBotID: String(parsed.TELEGRAM_BOT_SERVER_BOT_ID || "").trim(),
     serverBotName: String(parsed.TELEGRAM_BOT_SERVER_NAME || "").trim(),
     serverRoles: parseTelegramServerRoles(parsed.TELEGRAM_BOT_SERVER_ROLES || ""),
+    serverRoleIDs: parseTelegramServerRoleIDs(parsed.TELEGRAM_BOT_SERVER_ROLE_IDS || ""),
     token: String(parsed.TELEGRAM_BOT_TOKEN || "").trim(),
     roleProfile: normalizeRunnerRoleProfileName(parsed.TELEGRAM_BOT_ROLE_PROFILE || ""),
     client: normalizeLocalAIClientName(parsed.TELEGRAM_BOT_AI_CLIENT || "", ""),
@@ -2824,7 +2951,11 @@ function loadTelegramBotEntriesFromFiles() {
   const dirPath = telegramBotEntriesDirPath();
   if (!fs.existsSync(dirPath)) return [];
   return fs.readdirSync(dirPath, { withFileTypes: true })
-    .filter((item) => item.isFile() && /\.env$/i.test(item.name) && item.name.toLowerCase() !== "_global.env")
+    .filter((item) => item.isFile() && /\.env$/i.test(item.name))
+    .filter((item) => {
+      const lowered = item.name.toLowerCase();
+      return lowered !== "_global.env" && lowered !== "global.env";
+    })
     .map((item) => path.join(dirPath, item.name))
     .sort((left, right) => left.localeCompare(right))
     .map((filePath) => {
@@ -2851,6 +2982,7 @@ function buildMergedTelegramEnvParsed(globalParsed, entries) {
     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}_SERVER_ROLE_IDS`] = formatTelegramServerRoleIDs(entry.serverRoleIDs);
     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();
@@ -2865,9 +2997,12 @@ function buildMergedTelegramEnvParsed(globalParsed, entries) {
 function readTelegramEnvState() {
   const filePath = providerEnvFilePath("telegram");
   const legacyFilePath = telegramLegacyEnvFilePath();
+  const legacyGlobalFilePath = telegramLegacyGlobalEnvFilePath();
   let sourceFilePath = filePath;
   try {
-    if (!fs.existsSync(filePath) && fs.existsSync(legacyFilePath)) {
+    if (!fs.existsSync(filePath) && fs.existsSync(legacyGlobalFilePath)) {
+      sourceFilePath = legacyGlobalFilePath;
+    } else if (!fs.existsSync(filePath) && fs.existsSync(legacyFilePath)) {
       sourceFilePath = legacyFilePath;
     } else if (!fs.existsSync(filePath)) {
       fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -2877,6 +3012,7 @@ function readTelegramEnvState() {
     return {
       filePath,
       legacyFilePath,
+      legacyGlobalFilePath,
       sourceFilePath,
       entriesDirPath: telegramBotEntriesDirPath(),
       parsed: {},
@@ -2903,6 +3039,7 @@ function readTelegramEnvState() {
   return {
     filePath,
     legacyFilePath,
+    legacyGlobalFilePath,
     sourceFilePath,
     entriesDirPath: telegramBotEntriesDirPath(),
     parsed: buildMergedTelegramEnvParsed(globalParsed, entries),
@@ -2912,7 +3049,7 @@ function readTelegramEnvState() {
 }
 
 function isTelegramEntryEnvKey(rawKey) {
-  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
+  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|SERVER_NAME|SERVER_ROLES|SERVER_ROLE_IDS|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
     .test(String(rawKey || "").trim());
 }
 
@@ -2935,7 +3072,7 @@ function renderNormalizedTelegramEnv(parsedEnv) {
     "# Metheus local Telegram bot settings",
     "# 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.",
+    "# This global file lives in ~/.metheus/telegram-bots/global.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 || "")}`,
@@ -2971,6 +3108,7 @@ function renderTelegramBotEntryEnv(entryRaw) {
   const entry = safeObject(entryRaw);
   const botName = telegramEntryCommentNameForEnv(entry);
   const serverRoles = parseTelegramServerRoles(entry.serverRoles || "");
+  const serverRoleIDs = formatTelegramServerRoleIDs(entry.serverRoleIDs);
   const lines = [
     "# Metheus local Telegram bot entry",
     `# Server bot: ${botName}`,
@@ -2978,6 +3116,7 @@ function renderTelegramBotEntryEnv(entryRaw) {
     `TELEGRAM_BOT_SERVER_BOT_ID=${formatProviderEnvValue(entry.serverBotID || "")}`,
     `TELEGRAM_BOT_SERVER_NAME=${formatProviderEnvValue(entry.serverBotName || "")}`,
     `TELEGRAM_BOT_SERVER_ROLES=${formatProviderEnvValue(serverRoles.join(","))}`,
+    `TELEGRAM_BOT_SERVER_ROLE_IDS=${formatProviderEnvValue(serverRoleIDs)}`,
   ];
   if (!String(entry.serverBotID || "").trim() && !String(entry.serverBotName || "").trim() && String(entry.username || "").trim()) {
     lines.push(
@@ -3006,6 +3145,7 @@ function writeTelegramEnvState(parsedEnv) {
       || entry.serverBotID
       || entry.serverBotName
       || ensureArray(entry.serverRoles).length
+      || Object.keys(safeObject(entry.serverRoleIDs)).length
       || entry.roleProfile
       || entry.client
       || entry.model
@@ -3021,6 +3161,7 @@ function writeTelegramEnvState(parsedEnv) {
   });
   const globalFilePath = providerEnvFilePath("telegram");
   const legacyFilePath = telegramLegacyEnvFilePath();
+  const legacyGlobalFilePath = telegramLegacyGlobalEnvFilePath();
   fs.mkdirSync(path.dirname(globalFilePath), { recursive: true });
   fs.writeFileSync(globalFilePath, renderNormalizedTelegramEnv(globalParsed), {
     encoding: "utf8",
@@ -3030,24 +3171,46 @@ function writeTelegramEnvState(parsedEnv) {
   fs.mkdirSync(entriesDirPath, { recursive: true });
   const activeFiles = new Set();
   entries.forEach((entry) => {
-    const entryFilePath = telegramBotEntryFilePath(entry.key);
-    activeFiles.add(path.resolve(entryFilePath));
+    const entryFilePath = telegramBotEntryFilePathForEntry(entry);
+    const previousEntryFilePath = String(entry.entryFilePath || "").trim();
+    const discoveredEntryFilePath = previousEntryFilePath || findTelegramEntryPathVariant(entryFilePath);
+    const sourceEntryFilePath = discoveredEntryFilePath || previousEntryFilePath;
+    if (sourceEntryFilePath && sourceEntryFilePath !== entryFilePath && fs.existsSync(sourceEntryFilePath)) {
+      const previousComparable = normalizeComparablePath(sourceEntryFilePath);
+      const nextComparable = normalizeComparablePath(entryFilePath);
+      if (previousComparable === nextComparable) {
+        const tempRenamePath = path.join(
+          path.dirname(entryFilePath),
+          `.__rename__.${Date.now()}-${Math.random().toString(16).slice(2)}.env`,
+        );
+        fs.renameSync(sourceEntryFilePath, tempRenamePath);
+        fs.renameSync(tempRenamePath, entryFilePath);
+      }
+    }
+    activeFiles.add(normalizeComparablePath(entryFilePath));
     fs.writeFileSync(entryFilePath, renderTelegramBotEntryEnv(entry), {
       encoding: "utf8",
       mode: 0o600,
     });
   });
   fs.readdirSync(entriesDirPath, { withFileTypes: true })
-    .filter((item) => item.isFile() && /\.env$/i.test(item.name) && item.name.toLowerCase() !== "_global.env")
+    .filter((item) => item.isFile() && /\.env$/i.test(item.name))
+    .filter((item) => {
+      const lowered = item.name.toLowerCase();
+      return lowered !== "_global.env" && lowered !== "global.env";
+    })
     .forEach((item) => {
-      const filePath = path.resolve(path.join(entriesDirPath, item.name));
+      const filePath = normalizeComparablePath(path.join(entriesDirPath, item.name));
       if (!activeFiles.has(filePath)) {
-        fs.rmSync(filePath, { force: true });
+        fs.rmSync(path.join(entriesDirPath, item.name), { force: true });
       }
     });
   if (legacyFilePath !== globalFilePath && fs.existsSync(legacyFilePath)) {
     fs.rmSync(legacyFilePath, { force: true });
   }
+  if (legacyGlobalFilePath !== globalFilePath && fs.existsSync(legacyGlobalFilePath)) {
+    fs.rmSync(legacyGlobalFilePath, { force: true });
+  }
   return globalFilePath;
 }
 
@@ -3067,6 +3230,7 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
     || entry.serverBotID
     || entry.serverBotName
     || ensureArray(entry.serverRoles).length
+    || Object.keys(safeObject(entry.serverRoleIDs)).length
   ));
   const desiredBotID = firstNonEmptyString([
     selectors.serverBotID,
@@ -3118,7 +3282,8 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
         provider: "telegram",
         providerLabel: config.label,
         filePath,
-        error: `TELEGRAM_BOT_${selected.key.toUpperCase()}_TOKEN is missing in ${filePath}`,
+        entryFilePath: telegramBotEntryFilePathForEntry(selected),
+        error: `TELEGRAM_BOT_TOKEN is missing in ${telegramBotEntryFilePathForEntry(selected) || filePath}`,
         token: "",
       };
     }
@@ -3127,14 +3292,16 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
       provider: "telegram",
       providerLabel: config.label,
       filePath,
+      entryFilePath: telegramBotEntryFilePathForEntry(selected),
       token: selected.token,
       source: "telegram_env_v2",
-      tokenKey: `TELEGRAM_BOT_${selected.key.toUpperCase()}_TOKEN`,
+      tokenKey: "TELEGRAM_BOT_TOKEN",
       botKey: selected.key,
       botUsername: selected.username,
       serverBotID: selected.serverBotID,
       serverBotName: selected.serverBotName,
       serverRoles: ensureArray(selected.serverRoles),
+      serverRoleIDs: safeObject(selected.serverRoleIDs),
       roleProfile: selected.roleProfile,
       client: selected.client,
       model: selected.model,
@@ -3161,6 +3328,7 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
       serverBotID: "",
       serverBotName: "",
       serverRoles: [],
+      serverRoleIDs: {},
       roleProfile: "",
       client: "",
       model: "",
@@ -3732,6 +3900,7 @@ function buildBotCommandDeps() {
     providerEnvFilePath,
     telegramBotEntriesDirPath,
     telegramBotEntryFilePath,
+    telegramBotEntryFilePathForEntry,
     ensureProviderEnvTemplate,
     parseCommandAndFlags,
     parseSimpleEnvText,
@@ -5521,7 +5690,7 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     const normalizedState = readTelegramEnvState();
     writeTelegramEnvState(normalizedState.parsed);
     normalizedGlobalText = fs.readFileSync(providerEnvFilePath("telegram"), "utf8");
-    normalizedBotText = fs.readFileSync(telegramBotEntryFilePath("ryoai_bot"), "utf8");
+    normalizedBotText = fs.readFileSync(telegramBotEntryFilePathForEntry({ serverBotName: "RyoAI_bot", key: "ryoai_bot" }), "utf8");
   } finally {
     if (previousUserProfile === undefined) delete process.env.USERPROFILE;
     else process.env.USERPROFILE = previousUserProfile;

package/lib/bot-commands.mjs

@@ -230,7 +230,7 @@ function printBotUsage(deps) {
       `  - 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; --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.`,
+      `  - runner commands use route names. Use runner list first, then run runner once/start with --route-name.`,
       `  - 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.`,
@@ -445,6 +445,7 @@ function telegramEntryEnvKeys(botKey) {
     serverBotID: `TELEGRAM_BOT_${upper}_SERVER_BOT_ID`,
     serverBotName: `TELEGRAM_BOT_${upper}_SERVER_NAME`,
     serverRoles: `TELEGRAM_BOT_${upper}_SERVER_ROLES`,
+    serverRoleIDs: `TELEGRAM_BOT_${upper}_SERVER_ROLE_IDS`,
     username: `TELEGRAM_BOT_${upper}_USERNAME`,
     token: `TELEGRAM_BOT_${upper}_TOKEN`,
     roleProfile: `TELEGRAM_BOT_${upper}_ROLE_PROFILE`,
@@ -455,6 +456,52 @@ function telegramEntryEnvKeys(botKey) {
   };
 }
 
+function parseTelegramServerRoleIDs(rawText) {
+  const output = {};
+  String(rawText || "")
+    .split(",")
+    .map((value) => String(value || "").trim())
+    .filter(Boolean)
+    .forEach((pair) => {
+      const separatorIndex = pair.indexOf(":");
+      if (separatorIndex <= 0) return;
+      const role = String(pair.slice(0, separatorIndex) || "").trim();
+      const id = String(pair.slice(separatorIndex + 1) || "").trim();
+      if (!role || !id) return;
+      output[role] = id;
+    });
+  return preferredRoleSort(Object.keys(output)).reduce((acc, role) => {
+    acc[role] = output[role];
+    return acc;
+  }, {});
+}
+
+function formatTelegramServerRoleIDs(roleIDs) {
+  return preferredRoleSort(Object.keys(safeObject(roleIDs)))
+    .map((role) => `${role}:${String(safeObject(roleIDs)[role] || "").trim()}`)
+    .filter((item) => !item.endsWith(":"))
+    .join(",");
+}
+
+function summarizeServerRoleIDs(bots) {
+  const output = {};
+  ensureArray(bots).forEach((bot) => {
+    const role = String(bot?.role || "").trim();
+    const id = String(bot?.id || "").trim();
+    if (!role || !id || output[role]) return;
+    output[role] = id;
+  });
+  return preferredRoleSort(Object.keys(output)).reduce((acc, role) => {
+    acc[role] = output[role];
+    return acc;
+  }, {});
+}
+
+function normalizeComparablePath(rawPath) {
+  const resolved = path.resolve(String(rawPath || ""));
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
 function telegramEntryCommentName(entry) {
   const current = safeObject(entry);
   const serverBotName = String(current.serverBotName || "").trim();
@@ -495,6 +542,7 @@ function upsertTelegramEntry(parsedEnv, entry) {
   next[keys.serverBotID] = String(entry.serverBotID || "").trim();
   next[keys.serverBotName] = String(entry.serverBotName || "").trim();
   next[keys.serverRoles] = ensureArray(entry.serverRoles).join(",");
+  next[keys.serverRoleIDs] = formatTelegramServerRoleIDs(entry.serverRoleIDs);
   next[keys.username] = persistTelegramUsername(entry);
   next[keys.token] = String(entry.token || "").trim();
   next[keys.roleProfile] = String(entry.roleProfile || "").trim();
@@ -521,7 +569,7 @@ function telegramKnownKeys(parsedEnv, deps) {
 }
 
 function isTelegramEntryEnvKey(rawKey) {
-  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
+  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|SERVER_NAME|SERVER_ROLES|SERVER_ROLE_IDS|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
     .test(String(rawKey || "").trim());
 }
 
@@ -536,6 +584,7 @@ function renderTelegramEnv(parsedEnv, deps) {
       || entry.serverBotID
       || entry.serverBotName
       || ensureArray(entry.serverRoles).length
+      || Object.keys(safeObject(entry.serverRoleIDs)).length
       || entry.roleProfile
       || entry.client
       || entry.model
@@ -575,6 +624,7 @@ function renderTelegramEnv(parsedEnv, deps) {
         `${keys.serverBotID}=${formatEnvValue(entry.serverBotID || "")}`,
         `${keys.serverBotName}=${formatEnvValue(entry.serverBotName || "")}`,
         `${keys.serverRoles}=${formatEnvValue(ensureArray(entry.serverRoles).join(","))}`,
+        `${keys.serverRoleIDs}=${formatEnvValue(formatTelegramServerRoleIDs(entry.serverRoleIDs))}`,
       ];
       if (String(entry.username || "").trim()) {
         entryLines.push(`${keys.username}=${formatEnvValue(entry.username || "")}`);
@@ -632,6 +682,7 @@ function renderTelegramBotEntryFile(entryRaw) {
   const entry = safeObject(entryRaw);
   const botName = telegramEntryCommentName(entry);
   const serverRoles = ensureArray(entry.serverRoles).join(",");
+  const serverRoleIDs = formatTelegramServerRoleIDs(entry.serverRoleIDs);
   const lines = [
     "# Metheus local Telegram bot entry",
     `# Server bot: ${botName}`,
@@ -639,6 +690,7 @@ function renderTelegramBotEntryFile(entryRaw) {
     `TELEGRAM_BOT_SERVER_BOT_ID=${formatEnvValue(entry.serverBotID || "")}`,
     `TELEGRAM_BOT_SERVER_NAME=${formatEnvValue(entry.serverBotName || "")}`,
     `TELEGRAM_BOT_SERVER_ROLES=${formatEnvValue(serverRoles)}`,
+    `TELEGRAM_BOT_SERVER_ROLE_IDS=${formatEnvValue(serverRoleIDs)}`,
   ];
   if (!String(entry.serverBotID || "").trim() && !String(entry.serverBotName || "").trim() && String(entry.username || "").trim()) {
     lines.push(
@@ -658,11 +710,47 @@ function renderTelegramBotEntryFile(entryRaw) {
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
+function appendTextSection(lines, title, sectionLines) {
+  const rows = ensureArray(sectionLines).filter(Boolean);
+  if (!rows.length) return;
+  lines.push(`${title}:`);
+  rows.forEach((row) => {
+    lines.push(`  ${row}`);
+  });
+}
+
+function resolveTelegramEntryFilePath(entry, deps) {
+  const current = safeObject(entry);
+  if (!firstNonEmptyString([current.serverBotName, current.username, current.key])) {
+    return "";
+  }
+  if (typeof deps?.telegramBotEntryFilePathForEntry === "function") {
+    return String(deps.telegramBotEntryFilePathForEntry(entry) || "").trim();
+  }
+  return String(requireDependency(deps, "telegramBotEntryFilePath")(current.key) || "").trim();
+}
+
 function rewriteTelegramEntryFile(entry, deps) {
-  const entryFilePath = String(requireDependency(deps, "telegramBotEntryFilePath")(entry.key) || "").trim();
+  const entryFilePath = resolveTelegramEntryFilePath(entry, deps);
   if (!entryFilePath) return;
+  let rewritePath = entryFilePath;
+  if (fs.existsSync(path.dirname(entryFilePath))) {
+    const currentComparable = normalizeComparablePath(entryFilePath);
+    const existingVariant = fs.readdirSync(path.dirname(entryFilePath), { withFileTypes: true })
+      .filter((item) => item.isFile() && /\.env$/i.test(item.name))
+      .map((item) => path.join(path.dirname(entryFilePath), item.name))
+      .find((candidatePath) => normalizeComparablePath(candidatePath) === currentComparable);
+    if (existingVariant && existingVariant !== entryFilePath) {
+      const tempRenamePath = path.join(
+        path.dirname(entryFilePath),
+        `.__rename__.${Date.now()}-${Math.random().toString(16).slice(2)}.env`,
+      );
+      fs.renameSync(existingVariant, tempRenamePath);
+      fs.renameSync(tempRenamePath, entryFilePath);
+    }
+  }
   fs.mkdirSync(path.dirname(entryFilePath), { recursive: true });
-  fs.writeFileSync(entryFilePath, renderTelegramBotEntryFile(entry), {
+  fs.writeFileSync(rewritePath, renderTelegramBotEntryFile(entry), {
     encoding: "utf8",
     mode: 0o600,
   });
@@ -699,6 +787,7 @@ function telegramEntriesForDisplay(parsedEnv, deps) {
       || entry.serverBotID
       || entry.serverBotName
       || ensureArray(entry.serverRoles).length
+      || Object.keys(safeObject(entry.serverRoleIDs)).length
       || entry.roleProfile
       || entry.client
       || entry.model
@@ -861,11 +950,13 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
         current.serverBotID = String(initialBinding.serverBotID || "").trim();
         current.serverBotName = String(initialBinding.name || "").trim();
         current.serverRoles = ensureArray(initialBinding.roles);
+        current.serverRoleIDs = safeObject(initialBinding.serverRoleIDs);
         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);
+        current.serverRoleIDs = safeObject(initialBinding.serverRoleIDs);
       }
     }
   }
@@ -918,6 +1009,7 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
       current.serverBotID = "";
       current.serverBotName = String(serverBot.name || "").trim();
       current.serverRoles = preferredRoleSort(serverBot.roles);
+      current.serverRoleIDs = safeObject(serverBot.roleIDs);
       current.__preferServerIdentity = true;
       current.roleProfile = "";
       current.client = "";
@@ -934,6 +1026,7 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
       current.serverBotID = String(serverBot.botID || "").trim();
       current.serverBotName = String(serverBot.name || "").trim();
       current.serverRoles = ensureArray(serverBot.roles);
+      current.serverRoleIDs = safeObject(serverBot.roleIDs);
       current.__preferServerIdentity = true;
       current.roleProfile = String(serverBot.role || current.roleProfile || "").trim();
       serverRoleAutoResolved = String(serverBot.role || current.roleProfile || "").trim() || "__server_binding__";
@@ -1062,14 +1155,17 @@ function renderBotListPayload(provider, state, deps) {
     return {
       provider,
       filePath: state.filePath,
+      globalFilePath: state.filePath,
       support: requireDependency(deps, "summarizeProviderSupport")(provider),
       defaultBotKey: String(state.parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim(),
       entries: telegramEntriesForDisplay(state.parsed, deps).map((entry) => ({
         key: entry.key,
         isDefault: entry.isDefault,
+        entryFilePath: resolveTelegramEntryFilePath(entry, deps),
         serverBotID: entry.serverBotID,
         serverBotName: entry.serverBotName,
         serverRoles: ensureArray(entry.serverRoles),
+        serverRoleIDs: safeObject(entry.serverRoleIDs),
         username: entry.username,
         tokenConfigured: Boolean(entry.token),
         roleProfile: entry.roleProfile,
@@ -1106,14 +1202,18 @@ function buildBotShowPayload(provider, state, entry, deps, extras = {}) {
     return {
       provider,
       filePath: state.filePath,
+      globalFilePath: state.filePath,
+      entryFilePath: selectedEntry ? resolveTelegramEntryFilePath(selectedEntry, deps) : "",
       support: requireDependency(deps, "summarizeProviderSupport")(provider),
       defaultBotKey: String(state.parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim(),
       entry: selectedEntry ? {
         key: selectedEntry.key,
         isDefault: selectedEntry.isDefault,
+        entryFilePath: resolveTelegramEntryFilePath(selectedEntry, deps),
         serverBotID: selectedEntry.serverBotID,
         serverBotName: selectedEntry.serverBotName,
         serverRoles: ensureArray(selectedEntry.serverRoles),
+        serverRoleIDs: safeObject(selectedEntry.serverRoleIDs),
         username: selectedEntry.username,
         tokenConfigured: Boolean(selectedEntry.token),
         roleProfile: selectedEntry.roleProfile,
@@ -1210,8 +1310,10 @@ function printBotList(provider, state, deps) {
       process.stdout.write(
         [
           `  - ${telegramEntryDisplayName(entry)}${entry.isDefault ? " [default]" : ""}`,
+          `    entry_file: ${resolveTelegramEntryFilePath(entry, deps) || "-"}`,
           `    local_selector: ${entry.key || "-"}${entry.key ? " (advanced)" : ""}`,
           `    server_bot_id: ${entry.serverBotID || "-"}`,
+          `    server_role_ids: ${formatTelegramServerRoleIDs(entry.serverRoleIDs) || "-"}`,
           `    fallback_username: ${entry.username ? `@${entry.username}` : "-"}`,
           `    token: ${entry.token ? maskSecret(entry.token) : "-"}`,
           `    role_profile: ${entry.roleProfile || "-"}`,
@@ -1234,38 +1336,49 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
     const selectedEntry = entry || {};
     const serverBinding = safeObject(extras.serverBinding);
     const routeLinks = safeObject(extras.routeLinks);
-    process.stdout.write(`${providerLabel(provider, deps)} bot\n`);
-    process.stdout.write(`  file: ${state.filePath}\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(`  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`);
-    process.stdout.write(`  ai_model: ${selectedEntry.model || "-"}\n`);
-    process.stdout.write(`  permission_mode: ${selectedEntry.permissionMode || "-"}\n`);
-    process.stdout.write(`  reasoning_effort: ${selectedEntry.reasoningEffort || "-"}\n`);
+    const lines = [
+      `${providerLabel(provider, deps)} bot`,
+      `global_file: ${state.filePath}`,
+      `entry_file: ${resolveTelegramEntryFilePath(selectedEntry, deps) || "-"}`,
+      `server_name: ${telegramEntryDisplayName(selectedEntry)}`,
+    ];
+    appendTextSection(lines, "stored_local_entry", [
+      `local_selector: ${selectedEntry.key || "-"}${selectedEntry.key ? " (advanced)" : ""}`,
+      `default: ${selectedEntry.isDefault ? "yes" : "no"}`,
+      `stored_server_bot_id: ${selectedEntry.serverBotID || "-"}`,
+      `stored_server_name: ${selectedEntry.serverBotName || "-"}`,
+      `stored_server_roles: ${ensureArray(selectedEntry.serverRoles).join(", ") || "-"}`,
+      `stored_server_role_ids: ${formatTelegramServerRoleIDs(selectedEntry.serverRoleIDs) || "-"}`,
+      `fallback_username: ${selectedEntry.username ? `@${selectedEntry.username}` : "-"}`,
+      `token: ${selectedEntry.token ? maskSecret(selectedEntry.token) : "(not configured)"}`,
+      `role_profile: ${selectedEntry.roleProfile || "-"}`,
+      `ai_client: ${selectedEntry.client ? displayLocalAIClientName(selectedEntry.client) : "-"}`,
+      `ai_model: ${selectedEntry.model || "-"}`,
+      `permission_mode: ${selectedEntry.permissionMode || "-"}`,
+      `reasoning_effort: ${selectedEntry.reasoningEffort || "-"}`,
+    ]);
     if (Object.keys(serverBinding).length) {
-      process.stdout.write(`  server_binding: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}\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`);
+      const liveLines = [
+        `status: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}`,
+        `binding_mode: ${serverBinding.mode || "-"}`,
+        `live_server_name: ${serverBinding.name || "-"}`,
+        `live_server_bot_id: ${serverBinding.serverBotID || selectedEntry.serverBotID || "-"}`,
+      ];
       if (serverBinding.mode === "group") {
-        process.stdout.write(`  live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}\n`);
+        liveLines.push(`live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`);
+        liveLines.push(`live_server_role_ids: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`);
         const groupedProfiles = safeObject(serverBinding.effectiveRoleProfiles);
         Object.keys(groupedProfiles).forEach((role) => {
-          process.stdout.write(`  runtime_role_profile[${role}]: ${formatRoleProfileOutputLine(groupedProfiles[role])}\n`);
+          liveLines.push(`runtime_role_profile[${role}]: ${formatRoleProfileOutputLine(groupedProfiles[role])}`);
         });
       } else if (serverBinding.effectiveRoleProfile) {
-        process.stdout.write(`  live_server_role: ${serverBinding.role || "-"}\n`);
-        process.stdout.write(`  runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}\n`);
+        liveLines.push(`live_server_role: ${serverBinding.role || "-"}`);
+        liveLines.push(`live_server_role_ids: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`);
+        liveLines.push(`runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}`);
       }
+      appendTextSection(lines, "live_server_binding", liveLines);
     }
-    process.stdout.write(`  route_links: ${intFromRaw(routeLinks.total, 0)}\n`);
+    const routeLines = [`count: ${intFromRaw(routeLinks.total, 0)}`];
     ensureArray(routeLinks.routes).forEach((route) => {
       const routeRuntime = safeObject(route.runtimeRoleProfile);
       const routeDetail = [
@@ -1273,8 +1386,10 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
         route.routeRole ? `route_role=${String(route.routeRole || "").trim()}` : "",
         Object.keys(routeRuntime).length ? `runtime=${formatRoleProfileOutputLine(routeRuntime)}` : "",
       ].filter(Boolean).join(" ");
-      process.stdout.write(`  linked_route[${String(route.routeName || "-")}]: ${routeDetail || "-"}\n`);
+      routeLines.push(`${String(route.routeName || "-")}: ${routeDetail || "-"}`);
     });
+    appendTextSection(lines, "linked_runner_routes", routeLines);
+    process.stdout.write(`${lines.join("\n")}\n`);
     return;
   }
   const tokenKey = providerTokenKey(provider, deps);
@@ -1343,6 +1458,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
         role: "",
         name: "",
         roles: [],
+        roleIDs: {},
         matchMode: manualID ? "manual" : "blank",
       };
     }
@@ -1360,6 +1476,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
         role: String(match.role || "").trim(),
         name: String(match.name || "").trim(),
         roles: summarizeServerBotRoles([match]),
+        roleIDs: summarizeServerRoleIDs([match]),
         matchMode: "exact",
       };
     }
@@ -1369,6 +1486,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
         role: "",
         name: String(matchedByName[0]?.name || "").trim(),
         roles: summarizeServerBotRoles(matchedByName),
+        roleIDs: summarizeServerRoleIDs(matchedByName),
         matchMode: "group",
       };
     }
@@ -1380,6 +1498,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
       role: String(match.role || "").trim(),
       name: String(match.name || "").trim(),
       roles: summarizeServerBotRoles([match]),
+      roleIDs: summarizeServerRoleIDs([match]),
       matchMode: "exact",
     };
   }
@@ -1399,6 +1518,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
         role: "",
         name: String(groupedBots[0]?.name || "").trim(),
         roles: summarizeServerBotRoles(groupedBots),
+        roleIDs: summarizeServerRoleIDs(groupedBots),
         matchMode: "group",
       };
     }
@@ -1453,7 +1573,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
     { defaultIndex: 0 },
   );
   if (!roleChoice || roleChoice.value === "__blank__") {
-    return { botID: "", role: "", name: "", roles: [], matchMode: "blank" };
+    return { botID: "", role: "", name: "", roles: [], roleIDs: {}, matchMode: "blank" };
   }
   if (roleChoice.value === "__manual__") {
     const manualID = await promptLine(ui, "Server bot UUID", "");
@@ -1462,6 +1582,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
       role: "",
       name: "",
       roles: [],
+      roleIDs: {},
       matchMode: manualID ? "manual" : "blank",
     };
   }
@@ -1473,6 +1594,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
       role: String(match.role || "").trim(),
       name: String(match.name || "").trim(),
       roles: summarizeServerBotRoles([match]),
+      roleIDs: summarizeServerRoleIDs([match]),
       matchMode: "exact",
     };
   }
@@ -1501,7 +1623,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
     { defaultIndex: 0 },
   );
   if (!choice || choice.value === "__blank__") {
-    return { botID: "", role: "", name: "", roles: [], matchMode: "blank" };
+    return { botID: "", role: "", name: "", roles: [], roleIDs: {}, matchMode: "blank" };
   }
   if (choice.value === "__manual__") {
     const manualID = await promptLine(ui, "Server bot UUID", "");
@@ -1510,6 +1632,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
       role: selectedRole,
       name: "",
       roles: selectedRole ? [selectedRole] : [],
+      roleIDs: {},
       matchMode: manualID ? "manual" : "blank",
     };
   }
@@ -1519,6 +1642,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, opti
     role: String(match.role || "").trim(),
     name: String(match.name || "").trim(),
     roles: summarizeServerBotRoles([match]),
+    roleIDs: summarizeServerRoleIDs([match]),
     matchMode: "exact",
   };
 }
@@ -1534,7 +1658,7 @@ async function resolveServerBotForNonInteractive(provider, flags, deps, options
     ]),
   );
   if (!requestedBotID && !requestedName) {
-    return { botID: "", role: "", name: "", roles: [], matchMode: "blank" };
+    return { botID: "", role: "", name: "", roles: [], roleIDs: {}, matchMode: "blank" };
   }
   const lookup = await requireDependency(deps, "listServerBots")({
     provider,
@@ -1563,6 +1687,7 @@ async function resolveServerBotForNonInteractive(provider, flags, deps, options
         role: "",
         name: match.name,
         roles: summarizeServerBotRoles(sameNameMatches),
+        roleIDs: summarizeServerRoleIDs(sameNameMatches),
         matchMode: "group",
       };
     }
@@ -1571,6 +1696,7 @@ async function resolveServerBotForNonInteractive(provider, flags, deps, options
       role: match.role,
       name: match.name,
       roles: summarizeServerBotRoles([match]),
+      roleIDs: summarizeServerRoleIDs([match]),
       matchMode: "exact",
     };
   }
@@ -1587,6 +1713,7 @@ async function resolveServerBotForNonInteractive(provider, flags, deps, options
       role: String(match.role || "").trim(),
       name: String(match.name || "").trim(),
       roles: summarizeServerBotRoles([match]),
+      roleIDs: summarizeServerRoleIDs([match]),
       matchMode: "exact",
     };
   }
@@ -1595,6 +1722,7 @@ async function resolveServerBotForNonInteractive(provider, flags, deps, options
     role: "",
     name: String(matchedByName[0]?.name || "").trim(),
     roles: summarizeServerBotRoles(matchedByName),
+    roleIDs: summarizeServerRoleIDs(matchedByName),
     matchMode: "group",
   };
 }
@@ -1966,6 +2094,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
   }
   const resolveGroupedPayload = (matches, matchedBy) => {
     const roles = preferredRoleSort(summarizeServerBotRoles(matches));
+    const serverRoleIDs = summarizeServerRoleIDs(matches);
     return {
       ok: true,
       mode: "group",
@@ -1973,6 +2102,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
       name: String(matches[0]?.name || "").trim(),
       role: "",
       roles,
+      serverRoleIDs,
       serverBotID: String(current.serverBotID || "").trim(),
       effectiveRoleProfile: null,
       effectiveRoleProfiles: buildGroupedRoleProfileOutput(roles, deps),
@@ -1989,6 +2119,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
         name: "",
         role: "",
         roles: [],
+        serverRoleIDs: {},
         serverBotID: String(current.serverBotID || "").trim(),
         effectiveRoleProfile: null,
         effectiveRoleProfiles: {},
@@ -2007,6 +2138,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
       name: match.name,
       role: match.role,
       roles: summarizeServerBotRoles([match]),
+      serverRoleIDs: summarizeServerRoleIDs([match]),
       serverBotID: match.id,
       effectiveRoleProfile,
       effectiveRoleProfiles: {},
@@ -2023,6 +2155,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
       name: "",
       role: "",
       roles: [],
+      serverRoleIDs: {},
       serverBotID: "",
       effectiveRoleProfile: null,
       effectiveRoleProfiles: {},
@@ -2041,6 +2174,7 @@ function resolveTelegramServerBindingDetailsFromBots(envConfig, bots, deps) {
     name: String(match.name || "").trim(),
     role: String(match.role || "").trim(),
     roles: summarizeServerBotRoles([match]),
+    serverRoleIDs: summarizeServerRoleIDs([match]),
     serverBotID: String(match.id || "").trim(),
     effectiveRoleProfile,
     effectiveRoleProfiles: {},
@@ -2062,6 +2196,7 @@ async function resolveTelegramServerBindingDetails(envConfig, flags, deps) {
       name: "",
       role: "",
       roles: [],
+      serverRoleIDs: {},
       effectiveRoleProfile: null,
       effectiveRoleProfiles: {},
       detail: `server bot lookup unavailable: ${lookup?.error || "unknown error"}`,
@@ -2157,6 +2292,7 @@ async function autoResolveTelegramServerBot(current, flags, deps) {
       role: String(current?.roleProfile || "").trim(),
       name: "",
       roles: [],
+      roleIDs: {},
       matchMode: existingBotID ? "existing" : "blank",
     };
   }
@@ -2180,6 +2316,7 @@ async function autoResolveTelegramServerBot(current, flags, deps) {
       role: String(current?.roleProfile || "").trim(),
       name: "",
       roles: [],
+      roleIDs: {},
       matchMode: existingBotID ? "existing" : "blank",
     };
   }
@@ -2363,6 +2500,7 @@ async function addTelegramBot(ui, flags, deps) {
     serverBotID: String(getServerBotIDFlag(flags) || serverBot.botID || "").trim(),
     serverBotName: String(serverBot.name || "").trim(),
     serverRoles: preferredRoleSort(serverBot.roles),
+    serverRoleIDs: safeObject(serverBot.roleIDs),
     username,
     __preferServerIdentity: serverBot.matchMode === "group" || Boolean(String(getServerBotIDFlag(flags) || serverBot.botID || "").trim()),
     token,
@@ -2485,6 +2623,7 @@ async function editTelegramBot(ui, flags, deps) {
         current.serverBotID = String(getServerBotIDFlag(flags) || current.serverBotID || "").trim();
         current.serverBotName = String(resolvedServerBot.name || current.serverBotName || "").trim();
         current.serverRoles = preferredRoleSort(resolvedServerBot.roles);
+        current.serverRoleIDs = safeObject(resolvedServerBot.roleIDs);
         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 = "";
@@ -2494,6 +2633,7 @@ async function editTelegramBot(ui, flags, deps) {
         current.serverBotID = String(resolvedServerBot.botID || "").trim();
         current.serverBotName = String(resolvedServerBot.name || "").trim();
         current.serverRoles = ensureArray(resolvedServerBot.roles);
+        current.serverRoleIDs = safeObject(resolvedServerBot.roleIDs);
       }
     }
     saveTelegramBotEdit(parsed, selected, current, deps);
@@ -2576,9 +2716,12 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
       if (selectedEntry) {
         const desiredServerBotName = String(serverBinding.name || "").trim();
         const desiredServerRoles = ensureArray(serverBinding.roles);
+        const desiredServerRoleIDs = safeObject(serverBinding.serverRoleIDs);
         const currentServerRoles = ensureArray(selectedEntry.serverRoles);
         const currentServerRolesJoined = currentServerRoles.join(",");
         const desiredServerRolesJoined = desiredServerRoles.join(",");
+        const currentServerRoleIDs = formatTelegramServerRoleIDs(selectedEntry.serverRoleIDs);
+        const desiredServerRoleIDsText = formatTelegramServerRoleIDs(desiredServerRoleIDs);
         const desiredServerBotID = (
           String(selectedEntry.serverBotID || "").trim()
           || (serverBinding.mode === "single" ? String(serverBinding.serverBotID || "").trim() : "")
@@ -2586,6 +2729,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
         const needsMetadataBackfill = (
           String(selectedEntry.serverBotName || "").trim() !== desiredServerBotName
           || currentServerRolesJoined !== desiredServerRolesJoined
+          || currentServerRoleIDs !== desiredServerRoleIDsText
           || String(selectedEntry.serverBotID || "").trim() !== desiredServerBotID
         );
         if (needsMetadataBackfill) {
@@ -2594,6 +2738,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
             serverBotID: desiredServerBotID,
             serverBotName: desiredServerBotName,
             serverRoles: desiredServerRoles,
+            serverRoleIDs: desiredServerRoleIDs,
           };
           const nextParsed = upsertTelegramEntry(state.parsed, nextEntry);
           writeProviderEnvState("telegram", nextParsed, deps);
@@ -2601,6 +2746,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
           envConfig.serverBotID = desiredServerBotID;
           envConfig.serverBotName = desiredServerBotName;
           envConfig.serverRoles = desiredServerRoles;
+          envConfig.serverRoleIDs = desiredServerRoleIDs;
         }
         const rewriteEntry = needsMetadataBackfill
           ? {
@@ -2608,6 +2754,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
             serverBotID: desiredServerBotID,
             serverBotName: desiredServerBotName,
             serverRoles: desiredServerRoles,
+            serverRoleIDs: desiredServerRoleIDs,
           }
           : selectedEntry;
         const currentEntryFilePath = String(
@@ -2651,10 +2798,13 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
         ok: overallOK,
         provider,
         filePath: envConfig.filePath,
+        globalFilePath: envConfig.filePath,
+        entryFilePath: provider === "telegram" ? resolveTelegramEntryFilePath(envConfig, deps) : "",
         botKey: envConfig.botKey || "",
         serverBotID: envConfig.serverBotID || "",
         serverBotName: envConfig.serverBotName || "",
         serverRoles: ensureArray(envConfig.serverRoles),
+        serverRoleIDs: safeObject(envConfig.serverRoleIDs),
         detail: result.detail || "",
         roleProfile: envConfig.roleProfile || "",
         client: envConfig.client || "",
@@ -2668,34 +2818,44 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
   } else {
     const lines = [
       `${providerLabel(provider, deps)} verify: ${overallOK ? "OK" : "FAIL"}`,
-      `file: ${envConfig.filePath}`,
-      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 || "-"}` : "",
-      provider === "telegram" ? `permission_mode: ${envConfig.permissionMode || "-"}` : "",
-      provider === "telegram" ? `reasoning_effort: ${envConfig.reasoningEffort || "-"}` : "",
+      `global_file: ${envConfig.filePath}`,
+      provider === "telegram" ? `entry_file: ${resolveTelegramEntryFilePath(envConfig, deps) || "-"}` : "",
       `detail: ${result.detail || "-"}`,
-      serverBinding ? `server_binding: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}` : "",
-      routeLinks ? `route_links: ${intFromRaw(routeLinks.total, 0)}` : "",
-    ].filter(Boolean);
+    ];
+    if (provider === "telegram") {
+      appendTextSection(lines, "stored_local_entry", [
+        `local_selector: ${envConfig.botKey || "-"}${envConfig.botKey ? " (advanced)" : ""}`,
+        `stored_server_bot_id: ${envConfig.serverBotID || "-"}`,
+        `stored_server_name: ${envConfig.serverBotName || "-"}`,
+        `stored_server_roles: ${ensureArray(envConfig.serverRoles).join(", ") || "-"}`,
+        `stored_server_role_ids: ${formatTelegramServerRoleIDs(envConfig.serverRoleIDs) || "-"}`,
+        `role_profile: ${envConfig.roleProfile || "-"}`,
+        `ai_client: ${envConfig.client ? displayLocalAIClientName(envConfig.client) : "-"}`,
+        `ai_model: ${envConfig.model || "-"}`,
+        `permission_mode: ${envConfig.permissionMode || "-"}`,
+        `reasoning_effort: ${envConfig.reasoningEffort || "-"}`,
+      ]);
+    }
     if (provider === "telegram" && serverBinding) {
-      lines.push(`binding_mode: ${serverBinding.mode || "-"}`);
-      lines.push(`live_server_name: ${serverBinding.name || "-"}`);
-      lines.push(`live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`);
+      const liveLines = [
+        `status: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}`,
+        `binding_mode: ${serverBinding.mode || "-"}`,
+        `live_server_name: ${serverBinding.name || "-"}`,
+        `live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`,
+        `live_server_role_ids: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`,
+      ];
       if (serverBinding.mode === "group") {
         const groupedProfiles = safeObject(serverBinding.effectiveRoleProfiles);
         Object.keys(groupedProfiles).forEach((role) => {
-          lines.push(`runtime_role_profile[${role}]: ${formatRoleProfileOutputLine(groupedProfiles[role])}`);
+          liveLines.push(`runtime_role_profile[${role}]: ${formatRoleProfileOutputLine(groupedProfiles[role])}`);
         });
       } else if (serverBinding.effectiveRoleProfile) {
-        lines.push(`runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}`);
+        liveLines.push(`runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}`);
       }
+      appendTextSection(lines, "live_server_binding", liveLines);
     }
     if (provider === "telegram" && routeLinks) {
+      const routeSection = [`count: ${intFromRaw(routeLinks.total, 0)}`];
       ensureArray(routeLinks.routes).forEach((route) => {
         const routeRuntime = safeObject(route.runtimeRoleProfile);
         const routeDetail = [
@@ -2703,8 +2863,9 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
           route.routeRole ? `route_role=${String(route.routeRole || "").trim()}` : "",
           Object.keys(routeRuntime).length ? `runtime=${formatRoleProfileOutputLine(routeRuntime)}` : "",
         ].filter(Boolean).join(" ");
-        lines.push(`linked_route[${String(route.routeName || "-")}]: ${routeDetail || "-"}`);
+        routeSection.push(`${String(route.routeName || "-")}: ${routeDetail || "-"}`);
       });
+      appendTextSection(lines, "linked_runner_routes", routeSection);
     }
     process.stdout.write(`${lines.join("\n")}\n`);
   }

package/lib/selftest-bot-commands.mjs

@@ -289,11 +289,22 @@ export async function runSelftestBotCommands(push, deps) {
     const baseURL = `http://127.0.0.1:${mock.port}`;
     const telegramApiBaseURL = `${baseURL}/telegram`;
     const telegramBotEntriesDir = path.join(tempHome, ".metheus", "telegram-bots");
-    const telegramEnvPath = path.join(telegramBotEntriesDir, "_global.env");
+    const telegramEnvPath = path.join(telegramBotEntriesDir, "global.env");
     const readTelegramGlobals = () => parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
-    const readTelegramBotEntry = (botKey) => {
-      const filePath = path.join(telegramBotEntriesDir, `${String(botKey || "").trim()}.env`);
-      if (!fs.existsSync(filePath)) {
+    const readTelegramBotEntry = (selector) => {
+      const requested = String(selector || "").trim().toLowerCase();
+      const fileCandidates = fs.readdirSync(telegramBotEntriesDir, { withFileTypes: true })
+        .filter((item) => item.isFile() && /\.env$/i.test(item.name) && item.name.toLowerCase() !== "global.env")
+        .map((item) => path.join(telegramBotEntriesDir, item.name));
+      const filePath = fileCandidates.find((candidatePath) => {
+        const stem = path.basename(candidatePath, path.extname(candidatePath)).toLowerCase();
+        if (stem === requested) return true;
+        const parsedCandidate = parseSimpleEnvText(fs.readFileSync(candidatePath, "utf8"));
+        const serverName = String(parsedCandidate.TELEGRAM_BOT_SERVER_NAME || "").trim().toLowerCase();
+        const username = String(parsedCandidate.TELEGRAM_BOT_USERNAME || "").trim().toLowerCase();
+        return serverName === requested || username === requested;
+      });
+      if (!filePath || !fs.existsSync(filePath)) {
         return {};
       }
       return parseSimpleEnvText(fs.readFileSync(filePath, "utf8"));

package/lib/setup-registration.mjs

@@ -38,6 +38,7 @@ export function buildSetupOutputLines(summary, deps) {
       );
     }
   }
+  lines.push("Telegram bots: per-bot files are created later by bot add / bot verify after server bot identity is known.");
   if (runnerTemplate?.error) {
     lines.push(`Runner:    template unavailable (${runnerTemplate.error})`);
   } else {

package/package.json

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