metheus-governance-mcp-cli 0.2.102 → 0.2.104

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`
@@ -275,7 +280,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.
+- In `bot show` and `bot verify`, `saved_local_file` means the values already stored on disk under `~/.metheus/telegram-bots/*.env`, while `current_server_protocol` means the fresh `/api/v1/me/bots` response from the server right now.
 - `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.
@@ -293,10 +298,12 @@ 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.
 
+For runner commands, you can still use `--route-name` directly, but normal operator workflows can also use `--bot-name` or `--bot-id` when those identify one enabled route uniquely. Use `runner list` first if you are not sure which route belongs to which server bot.
+
 Current support status:
 
 - Telegram: full local bot entry management, token verification, bot-to-AI binding, inbound runner support
@@ -377,6 +384,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 +411,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 +484,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,
@@ -241,20 +242,21 @@ 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-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--json <true|false>]`,
+      `  ${cmd} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--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-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 set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>]`,
+      `  ${cmd} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>]`,
+      `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--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>]`,
       `  ${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 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} runner list [--json <true|false>]`,
+      `  ${cmd} runner once [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--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> | --bot-name <server_name> | --bot-id <uuid>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--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>]`,
       `  ${cmd} auth status`,
       `  ${cmd} auth login [--base-url <url>] [--flow <auto|device|callback|manual>] [--keycloak-url <url>] [--realm <name>] [--client-id <id>] [--open-browser <true|false>] [--callback-port <n>] [--timeout-seconds <n>] [--manual <true|false>]`,
@@ -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,75 @@ async function runRunnerOnce(flags) {
   }
 }
 
+function buildRunnerRouteListRows() {
+  const config = loadBotRunnerConfig({ persistIfNeeded: true });
+  const telegramState = readTelegramEnvState();
+  const telegramEntries = ensureArray(telegramState.entries);
+  return ensureArray(config.routes).map((rawRoute, index) => {
+    const route = normalizeRunnerRoute(rawRoute);
+    const matchedTelegramEntry = route.provider === "telegram"
+      ? telegramEntries.find((entry) => {
+        const current = safeObject(entry);
+        return (
+          (route.botID && current.serverBotID && current.serverBotID === route.botID)
+          || (route.botName && current.serverBotName && current.serverBotName === route.botName)
+        );
+      })
+      : null;
+    const resolvedBotName = firstNonEmptyString([
+      route.botName,
+      matchedTelegramEntry?.serverBotName,
+      matchedTelegramEntry?.key,
+      "-",
+    ]);
+    return {
+      index: index + 1,
+      name: route.name || runnerRouteKey(route),
+      enabled: route.enabled !== false,
+      provider: route.provider || "-",
+      projectID: route.projectID || "-",
+      botName: resolvedBotName,
+      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}`,
+        `    server_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}`,
+        row.botName ? `    run_once_by_bot_name: ${CLI_NAME} runner once --bot-name "${row.botName}"` : "",
+      ].join("\n") + "\n",
+    );
+  });
+}
+
 async function runRunnerStart(flags) {
   const jsonMode = boolFromRaw(flags.json, false);
   const routes = resolveRunnerRoutes(flags, "start");
@@ -2585,6 +2695,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 +2707,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 +2821,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 +2866,7 @@ function collectTelegramEnvBotEntries(parsedEnv) {
       serverBotID: "",
       serverBotName: "",
       serverRoles: [],
+      serverRoleIDs: {},
       roleProfile: "",
       client: "",
       model: "",
@@ -2742,6 +2884,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 +2932,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 +2969,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 +3000,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 +3015,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 +3030,7 @@ function readTelegramEnvState() {
     return {
       filePath,
       legacyFilePath,
+      legacyGlobalFilePath,
       sourceFilePath,
       entriesDirPath: telegramBotEntriesDirPath(),
       parsed: {},
@@ -2903,6 +3057,7 @@ function readTelegramEnvState() {
   return {
     filePath,
     legacyFilePath,
+    legacyGlobalFilePath,
     sourceFilePath,
     entriesDirPath: telegramBotEntriesDirPath(),
     parsed: buildMergedTelegramEnvParsed(globalParsed, entries),
@@ -2912,7 +3067,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 +3090,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 +3126,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 +3134,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 +3163,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 +3179,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 +3189,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 +3248,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 +3300,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 +3310,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 +3346,7 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
       serverBotID: "",
       serverBotName: "",
       serverRoles: [],
+      serverRoleIDs: {},
       roleProfile: "",
       client: "",
       model: "",
@@ -3732,6 +3918,7 @@ function buildBotCommandDeps() {
     providerEnvFilePath,
     telegramBotEntriesDirPath,
     telegramBotEntryFilePath,
+    telegramBotEntryFilePathForEntry,
     ensureProviderEnvTemplate,
     parseCommandAndFlags,
     parseSimpleEnvText,
@@ -5521,7 +5708,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;