metheus-governance-mcp-cli 0.2.92 → 0.2.94

package/README.md

@@ -24,6 +24,7 @@ npm install -g metheus-governance-mcp-cli@latest
 Install creates local provider settings templates here:
 
 - `~/.metheus/telegram.env`
+- `~/.metheus/telegram-bots/`
 - `~/.metheus/slack.env`
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
@@ -31,7 +32,8 @@ 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_BOT_TOKEN` or named Telegram bot mappings such as `TELEGRAM_BOT_RYOAI_TOKEN`
+  - `TELEGRAM_BOT_TOKEN` as a legacy Telegram fallback in `telegram.env`
+  - one Telegram bot file per entry in `~/.metheus/telegram-bots/<bot-key>.env`
   - `SLACK_BOT_TOKEN`
   - `KAKAOTALK_BOT_TOKEN`
 - Server-side Metheus stores project chat destination metadata separately:
@@ -39,7 +41,7 @@ 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 env can also carry per-bot local AI binding fields.
+- Telegram-wide settings stay in `telegram.env`; Telegram per-bot secrets and AI fields live in `telegram-bots/*.env`.
 
 Example templates:
 
@@ -52,18 +54,21 @@ TELEGRAM_DEFAULT_BOT_KEY=ryoai
 
 # Legacy fallback
 TELEGRAM_BOT_TOKEN=
+```
 
-# Preferred named bot mapping
-TELEGRAM_BOT_RYOAI_SERVER_BOT_ID=
-# Optional fallback only when server bot binding is unavailable
-# TELEGRAM_BOT_RYOAI_USERNAME=<bot_username>
-TELEGRAM_BOT_RYOAI_TOKEN=
-TELEGRAM_BOT_RYOAI_ROLE_PROFILE=monitor
-TELEGRAM_BOT_RYOAI_AI_CLIENT=gpt
-TELEGRAM_BOT_RYOAI_AI_MODEL=gpt-5.4
-TELEGRAM_BOT_RYOAI_AI_PERMISSION_MODE=read_only
-TELEGRAM_BOT_RYOAI_AI_REASONING_EFFORT=low
+```env
+# ~/.metheus/telegram-bots/ryoai.env
+TELEGRAM_BOT_NAME=ryoai_bot
+TELEGRAM_BOT_SERVER_BOT_ID=
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_BOT_ROLE_PROFILE=
+TELEGRAM_BOT_AI_CLIENT=
+TELEGRAM_BOT_AI_MODEL=
+TELEGRAM_BOT_AI_PERMISSION_MODE=
+TELEGRAM_BOT_AI_REASONING_EFFORT=
+```
 
+```env
 # ~/.metheus/slack.env
 SLACK_BOT_TOKEN=
 
@@ -160,10 +165,17 @@ metheus-governance-mcp-cli setup --project-id <project_uuid> --ctxpack-key "<ctx
 `setup` also ensures local provider templates exist:
 
 - `~/.metheus/telegram.env`
+- `~/.metheus/telegram-bots/`
 - `~/.metheus/slack.env`
 - `~/.metheus/kakaotalk.env`
 - `~/.metheus/bot-runner.json`
 
+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.env`
+- per-bot secrets move to `~/.metheus/telegram-bots/<bot-key>.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.
 
 `~/.metheus/bot-runner.json` is the local automation profile for:
@@ -228,7 +240,7 @@ Behavior:
 - `bot setup` asks for `Telegram / Slack / KakaoTalk` first, then prompts with numbered actions.
 - `bot add` without flags now uses the shortest practical guided flow: provider -> token -> verify -> optional save-anyway only when verify fails -> optional username fallback only when verify cannot discover it -> optional AI model selection when the resolved defaults leave it blank -> optional default bot.
 - In the normal Telegram path, `bot add` does not ask for a local bot key, a server bot UUID, or an approval / worker / review / monitor choice.
-- For Telegram, the local env key is auto-generated from the matched server bot name or verified username, so you do not have to invent a separate local nickname first.
+- For Telegram, the local bot file stem is auto-generated from the matched server bot name or verified username, so you do not have to invent a separate local nickname first.
 - For Telegram, the CLI tries to match the verified bot identity against the server `me/bots` list first. If the server exposes one logical bot name with multiple roles such as `approval`, `worker`, `review`, and `monitor`, the CLI does not ask you to choose one UUID. It binds by server bot name and keeps the local role/AI fields empty so runtime can use the server bot role for each route.
 - When the Telegram username matches exactly one server bot role, the CLI still auto-fills the local `role_profile` and blank AI defaults from your local `bot-runner.json` `role_profiles` mapping.
 - `bot edit` without flags now uses the same sequential flow every time: provider -> bot entry -> username/token review -> grouped server-role review when needed -> AI field choices -> default choice -> save.
@@ -247,15 +259,15 @@ 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 supports named local bot entries with:
-  - `SERVER_BOT_ID`
-  - `USERNAME` (optional fallback only when server binding is unavailable)
-  - `TOKEN`
-  - `ROLE_PROFILE`
-  - `AI_CLIENT`
-  - `AI_MODEL`
-  - `AI_PERMISSION_MODE`
-  - `AI_REASONING_EFFORT`
+- Telegram stores one bot file per entry under `~/.metheus/telegram-bots/<bot-key>.env` with generic fields:
+  - `TELEGRAM_BOT_NAME`
+  - `TELEGRAM_BOT_SERVER_BOT_ID`
+  - `TELEGRAM_BOT_TOKEN`
+  - `TELEGRAM_BOT_ROLE_PROFILE`
+  - `TELEGRAM_BOT_AI_CLIENT`
+  - `TELEGRAM_BOT_AI_MODEL`
+  - `TELEGRAM_BOT_AI_PERMISSION_MODE`
+  - `TELEGRAM_BOT_AI_REASONING_EFFORT`
 - 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.

package/cli.mjs

@@ -736,46 +736,33 @@ function providerEnvFilePath(provider) {
   return resolveHomeFilePath(providerEnvConfig(provider).relativePath);
 }
 
+function telegramBotEntriesDirPath() {
+  return resolveHomeFilePath(".metheus/telegram-bots");
+}
+
+function telegramBotEntryFilePath(botKey) {
+  const normalizedKey = normalizeTelegramBotEnvKey(botKey || "", "telegram_bot") || "telegram_bot";
+  return path.join(telegramBotEntriesDirPath(), `${normalizedKey}.env`);
+}
+
 function providerEnvTemplate(provider) {
   const config = providerEnvConfig(provider);
   if (normalizeBotProvider(provider) === "telegram") {
     return [
       "# Metheus local Telegram bot settings",
       "# Keep this file on your machine only. Do not commit it.",
-      "# Store Telegram bot secrets and local transport options only.",
+      "# Store only Telegram-wide settings here.",
+      "# Per-bot secrets and AI settings live in ~/.metheus/telegram-bots/<bot-key>.env.",
       "# Project chat destinations must be managed on the Metheus server.",
-      "#",
-      "# Legacy single-bot fallback:",
-      "# TELEGRAM_BOT_TOKEN=<bot token>",
-      "#",
-      "# Preferred v2 multi-bot mapping:",
-      "# TELEGRAM_DEFAULT_BOT_KEY=ryoai",
-      "# TELEGRAM_BOT_RYOAI_SERVER_BOT_ID=<server bot uuid>",
-      "# TELEGRAM_BOT_RYOAI_USERNAME=<optional fallback username when server binding is unavailable>",
-      "# TELEGRAM_BOT_RYOAI_TOKEN=<bot token>",
-      "# TELEGRAM_BOT_RYOAI_ROLE_PROFILE=monitor",
-      "# TELEGRAM_BOT_RYOAI_AI_CLIENT=gpt",
-      "# TELEGRAM_BOT_RYOAI_AI_MODEL=gpt-5.4",
-      "# TELEGRAM_BOT_RYOAI_AI_PERMISSION_MODE=read_only",
-      "# TELEGRAM_BOT_RYOAI_AI_REASONING_EFFORT=low",
       "",
       "TELEGRAM_API_BASE_URL=",
       "TELEGRAM_AUTO_CLEAR_WEBHOOK=true",
       "TELEGRAM_ALLOWED_UPDATES=message,edited_message",
-      "TELEGRAM_DEFAULT_BOT_KEY=ryoai",
+      "TELEGRAM_DEFAULT_BOT_KEY=",
       "",
       "# Legacy fallback (still supported)",
       "TELEGRAM_BOT_TOKEN=",
       "",
-      "# Preferred named bot entry",
-      "TELEGRAM_BOT_RYOAI_SERVER_BOT_ID=",
-      "TELEGRAM_BOT_RYOAI_TOKEN=",
-      "TELEGRAM_BOT_RYOAI_ROLE_PROFILE=",
-      "TELEGRAM_BOT_RYOAI_AI_CLIENT=",
-      "TELEGRAM_BOT_RYOAI_AI_MODEL=",
-      "TELEGRAM_BOT_RYOAI_AI_PERMISSION_MODE=",
-      "TELEGRAM_BOT_RYOAI_AI_REASONING_EFFORT=",
-      "",
     ].join("\n");
   }
   return [
@@ -1053,7 +1040,12 @@ function ensureProviderEnvTemplate(provider) {
   const filePath = providerEnvFilePath(provider);
   try {
     if (fs.existsSync(filePath)) {
-      return { filePath, created: false, existed: true };
+      return {
+        filePath,
+        created: false,
+        existed: true,
+        normalized: normalizeExistingProviderEnvFile(provider, filePath),
+      };
     }
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, providerEnvTemplate(provider), "utf8");
@@ -2636,6 +2628,15 @@ function parseSimpleEnvText(rawText) {
   return out;
 }
 
+function formatProviderEnvValue(rawValue) {
+  const text = String(rawValue ?? "");
+  if (!text) return "";
+  if (/^[A-Za-z0-9_./:@,\-]+$/.test(text)) {
+    return text;
+  }
+  return JSON.stringify(text);
+}
+
 function normalizeTelegramBotEnvKey(rawValue, fallback = "") {
   const normalized = String(rawValue || "")
     .trim()
@@ -2705,6 +2706,240 @@ function collectTelegramEnvBotEntries(parsedEnv) {
   return Array.from(entries.values());
 }
 
+function telegramBotEntryDisplayNameForState(entry) {
+  const current = safeObject(entry);
+  const username = normalizeTelegramBotUsername(current.username || "");
+  if (username) return username;
+  const key = normalizeTelegramBotEnvKey(current.key || "", "telegram_bot");
+  if (!key) return "telegram_bot";
+  return key.endsWith("_bot") ? key : `${key}_bot`;
+}
+
+function parseTelegramBotEntryFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const parsed = parseSimpleEnvText(raw);
+  const keyFromFile = normalizeTelegramBotEnvKey(path.basename(filePath, path.extname(filePath)), "telegram_bot");
+  return {
+    key: keyFromFile,
+    username: normalizeTelegramBotUsername(parsed.TELEGRAM_BOT_NAME || parsed.TELEGRAM_BOT_USERNAME || ""),
+    serverBotID: String(parsed.TELEGRAM_BOT_SERVER_BOT_ID || "").trim(),
+    token: String(parsed.TELEGRAM_BOT_TOKEN || "").trim(),
+    roleProfile: normalizeRunnerRoleProfileName(parsed.TELEGRAM_BOT_ROLE_PROFILE || ""),
+    client: normalizeLocalAIClientName(parsed.TELEGRAM_BOT_AI_CLIENT || "", ""),
+    model: String(parsed.TELEGRAM_BOT_AI_MODEL || "").trim(),
+    permissionMode: normalizeLocalAIPermissionMode(parsed.TELEGRAM_BOT_AI_PERMISSION_MODE || "", ""),
+    reasoningEffort: normalizeLocalAIReasoningEffort(parsed.TELEGRAM_BOT_AI_REASONING_EFFORT || "", ""),
+    entryFilePath: filePath,
+  };
+}
+
+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))
+    .map((item) => path.join(dirPath, item.name))
+    .sort((left, right) => left.localeCompare(right))
+    .map((filePath) => {
+      try {
+        return parseTelegramBotEntryFile(filePath);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function buildMergedTelegramEnvParsed(globalParsed, entries) {
+  const merged = { ...safeObject(globalParsed) };
+  Object.keys(merged).forEach((key) => {
+    if (isTelegramEntryEnvKey(key)) {
+      delete merged[key];
+    }
+  });
+  ensureArray(entries).forEach((entryRaw) => {
+    const entry = safeObject(entryRaw);
+    const upper = String(entry.key || "").trim().toUpperCase();
+    if (!upper) return;
+    merged[`TELEGRAM_BOT_${upper}_SERVER_BOT_ID`] = String(entry.serverBotID || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_USERNAME`] = normalizeTelegramBotUsername(entry.username || "");
+    merged[`TELEGRAM_BOT_${upper}_TOKEN`] = String(entry.token || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_ROLE_PROFILE`] = String(entry.roleProfile || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_AI_CLIENT`] = String(entry.client || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_AI_MODEL`] = String(entry.model || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_AI_PERMISSION_MODE`] = String(entry.permissionMode || "").trim();
+    merged[`TELEGRAM_BOT_${upper}_AI_REASONING_EFFORT`] = String(entry.reasoningEffort || "").trim();
+  });
+  return merged;
+}
+
+function readTelegramEnvState() {
+  const filePath = providerEnvFilePath("telegram");
+  try {
+    if (!fs.existsSync(filePath)) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, providerEnvTemplate("telegram"), "utf8");
+    }
+  } catch (err) {
+    return {
+      filePath,
+      entriesDirPath: telegramBotEntriesDirPath(),
+      parsed: {},
+      globalParsed: {},
+      entries: [],
+      error: String(err?.message || err),
+    };
+  }
+  const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+  const globalParsedRaw = parseSimpleEnvText(raw);
+  const inlineEntries = collectTelegramEnvBotEntries(globalParsedRaw);
+  const fileEntries = loadTelegramBotEntriesFromFiles();
+  const mergedEntries = new Map();
+  inlineEntries.forEach((entry) => mergedEntries.set(entry.key, { ...entry }));
+  fileEntries.forEach((entry) => mergedEntries.set(entry.key, { ...entry }));
+  const globalParsed = { ...globalParsedRaw };
+  Object.keys(globalParsed).forEach((key) => {
+    if (isTelegramEntryEnvKey(key)) {
+      delete globalParsed[key];
+    }
+  });
+  const entries = Array.from(mergedEntries.values());
+  return {
+    filePath,
+    entriesDirPath: telegramBotEntriesDirPath(),
+    parsed: buildMergedTelegramEnvParsed(globalParsed, entries),
+    globalParsed,
+    entries,
+  };
+}
+
+function isTelegramEntryEnvKey(rawKey) {
+  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
+    .test(String(rawKey || "").trim());
+}
+
+function telegramEntryCommentNameForEnv(entry) {
+  const current = safeObject(entry);
+  const username = normalizeTelegramBotUsername(current.username || "");
+  if (username) return username;
+  const key = normalizeTelegramBotEnvKey(current.key || "", "telegram_bot");
+  if (!key) return "telegram_bot";
+  return key.endsWith("_bot") ? key : `${key}_bot`;
+}
+
+function renderNormalizedTelegramEnv(parsedEnv) {
+  const parsed = safeObject(parsedEnv);
+  const defaultBotKey = normalizeTelegramBotEnvKey(parsed.TELEGRAM_DEFAULT_BOT_KEY || "", "");
+  const lines = [
+    "# Metheus local Telegram bot settings",
+    "# Keep this file on your machine only. Do not commit it.",
+    "# Store only Telegram-wide settings here.",
+    "# Per-bot secrets and AI settings live in ~/.metheus/telegram-bots/<bot-key>.env.",
+    "",
+    `TELEGRAM_API_BASE_URL=${formatProviderEnvValue(parsed.TELEGRAM_API_BASE_URL || "")}`,
+    `TELEGRAM_AUTO_CLEAR_WEBHOOK=${boolFromRaw(parsed.TELEGRAM_AUTO_CLEAR_WEBHOOK, true) ? "true" : "false"}`,
+    `TELEGRAM_ALLOWED_UPDATES=${formatProviderEnvValue(String(parsed.TELEGRAM_ALLOWED_UPDATES || "").trim() || "message,edited_message")}`,
+    `TELEGRAM_DEFAULT_BOT_KEY=${formatProviderEnvValue(defaultBotKey || "")}`,
+    "",
+    "# Legacy fallback",
+    `TELEGRAM_BOT_TOKEN=${formatProviderEnvValue(parsed.TELEGRAM_BOT_TOKEN || "")}`,
+    "",
+  ];
+  const knownKeys = new Set([
+    "TELEGRAM_API_BASE_URL",
+    "TELEGRAM_AUTO_CLEAR_WEBHOOK",
+    "TELEGRAM_ALLOWED_UPDATES",
+    "TELEGRAM_DEFAULT_BOT_KEY",
+    "TELEGRAM_BOT_TOKEN",
+  ]);
+  const extras = Object.keys(parsed)
+    .filter((key) => !knownKeys.has(key) && !isTelegramEntryEnvKey(key))
+    .sort((left, right) => left.localeCompare(right));
+  if (extras.length) {
+    lines.push("# Additional preserved keys");
+    extras.forEach((key) => {
+      lines.push(`${key}=${formatProviderEnvValue(parsed[key])}`);
+    });
+    lines.push("");
+  }
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+}
+
+function renderTelegramBotEntryEnv(entryRaw) {
+  const entry = safeObject(entryRaw);
+  const botName = telegramEntryCommentNameForEnv(entry);
+  const lines = [
+    "# Metheus local Telegram bot entry",
+    `# Bot: ${botName}`,
+    "",
+    `TELEGRAM_BOT_NAME=${formatProviderEnvValue(botName)}`,
+    `TELEGRAM_BOT_SERVER_BOT_ID=${formatProviderEnvValue(entry.serverBotID || "")}`,
+    `TELEGRAM_BOT_TOKEN=${formatProviderEnvValue(entry.token || "")}`,
+    `TELEGRAM_BOT_ROLE_PROFILE=${formatProviderEnvValue(entry.roleProfile || "")}`,
+    `TELEGRAM_BOT_AI_CLIENT=${formatProviderEnvValue(entry.client || "")}`,
+    `TELEGRAM_BOT_AI_MODEL=${formatProviderEnvValue(entry.model || "")}`,
+    `TELEGRAM_BOT_AI_PERMISSION_MODE=${formatProviderEnvValue(entry.permissionMode || "")}`,
+    `TELEGRAM_BOT_AI_REASONING_EFFORT=${formatProviderEnvValue(entry.reasoningEffort || "")}`,
+    "",
+  ];
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function writeTelegramEnvState(parsedEnv) {
+  const parsed = safeObject(parsedEnv);
+  const entries = collectTelegramEnvBotEntries(parsed)
+    .filter((entry) => (
+      entry.token
+      || entry.username
+      || entry.serverBotID
+      || entry.roleProfile
+      || entry.client
+      || entry.model
+      || entry.permissionMode
+      || entry.reasoningEffort
+    ))
+    .sort((left, right) => String(left.key || "").localeCompare(String(right.key || "")));
+  const globalParsed = { ...parsed };
+  Object.keys(globalParsed).forEach((key) => {
+    if (isTelegramEntryEnvKey(key)) {
+      delete globalParsed[key];
+    }
+  });
+  const globalFilePath = providerEnvFilePath("telegram");
+  fs.mkdirSync(path.dirname(globalFilePath), { recursive: true });
+  fs.writeFileSync(globalFilePath, renderNormalizedTelegramEnv(globalParsed), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  const entriesDirPath = telegramBotEntriesDirPath();
+  fs.mkdirSync(entriesDirPath, { recursive: true });
+  const activeFiles = new Set();
+  entries.forEach((entry) => {
+    const entryFilePath = telegramBotEntryFilePath(entry.key);
+    activeFiles.add(path.resolve(entryFilePath));
+    fs.writeFileSync(entryFilePath, renderTelegramBotEntryEnv(entry), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  });
+  fs.readdirSync(entriesDirPath, { withFileTypes: true })
+    .filter((item) => item.isFile() && /\.env$/i.test(item.name))
+    .forEach((item) => {
+      const filePath = path.resolve(path.join(entriesDirPath, item.name));
+      if (!activeFiles.has(filePath)) {
+        fs.rmSync(filePath, { force: true });
+      }
+    });
+  return globalFilePath;
+}
+
+function normalizeExistingProviderEnvFile(provider, filePath) {
+  if (normalizeBotProvider(provider) !== "telegram") return false;
+  const state = readTelegramEnvState();
+  writeTelegramEnvState(state.parsed);
+  return true;
+}
+
 function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
   const parsed = safeObject(parsedEnv);
   const legacyToken = String(parsed.TELEGRAM_BOT_TOKEN || "").trim();
@@ -2835,6 +3070,20 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
 function loadProviderEnvConfig(provider, selectors = {}) {
   const normalizedProvider = normalizeBotProvider(provider);
   const config = providerEnvConfig(normalizedProvider);
+  if (normalizedProvider === "telegram") {
+    const state = readTelegramEnvState();
+    if (state.error) {
+      return {
+        ok: false,
+        provider: normalizedProvider,
+        providerLabel: config.label,
+        filePath: state.filePath,
+        error: state.error,
+        token: "",
+      };
+    }
+    return resolveTelegramEnvConfig(state.parsed, state.filePath, config, selectors);
+  }
   const ensured = ensureProviderEnvTemplate(normalizedProvider);
   const filePath = ensured.filePath;
   if (ensured.error) {
@@ -2850,9 +3099,6 @@ function loadProviderEnvConfig(provider, selectors = {}) {
   try {
     const raw = fs.readFileSync(filePath, "utf8");
     const parsed = parseSimpleEnvText(raw);
-    if (normalizedProvider === "telegram") {
-      return resolveTelegramEnvConfig(parsed, filePath, config, selectors);
-    }
     const token = String(parsed[config.tokenKey] || "").trim();
     if (!token) {
       return {
@@ -3352,10 +3598,14 @@ function buildBotCommandDeps() {
     providerEnvOrder: PROVIDER_ENV_ORDER,
     providerEnvConfig,
     providerEnvFilePath,
+    telegramBotEntriesDirPath,
+    telegramBotEntryFilePath,
     ensureProviderEnvTemplate,
     parseCommandAndFlags,
     parseSimpleEnvText,
     collectTelegramEnvBotEntries,
+    readTelegramEnvState,
+    writeTelegramEnvState,
     normalizeBotProvider,
     normalizeTelegramBotEnvKey,
     normalizeTelegramBotUsername,
@@ -5114,6 +5364,45 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
       && telegramEnvV2ByUsername.allowedUpdates.includes("channel_post"),
     `bot=${String(telegramEnvV2ByUsername.botKey || "(none)")} updates=${String((telegramEnvV2ByUsername.allowedUpdates || []).join(","))}`,
   );
+  const telegramEnvNormalizeTempHome = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-telegram-env-normalize-"));
+  const previousUserProfile = process.env.USERPROFILE;
+  const previousHome = process.env.HOME;
+  let normalizedGlobalText = "";
+  let normalizedBotText = "";
+  try {
+    process.env.USERPROFILE = telegramEnvNormalizeTempHome;
+    process.env.HOME = telegramEnvNormalizeTempHome;
+    const normalizeTestEnvPath = providerEnvFilePath("telegram");
+    fs.mkdirSync(path.dirname(normalizeTestEnvPath), { recursive: true });
+    fs.writeFileSync(
+      normalizeTestEnvPath,
+      [
+        "TELEGRAM_DEFAULT_BOT_KEY=ryoai_bot",
+        "TELEGRAM_BOT_RYOAI_BOT_SERVER_BOT_ID=bot-ryoai",
+        "TELEGRAM_BOT_RYOAI_BOT_TOKEN=ryoai-token",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    ensureProviderEnvTemplate("telegram");
+    normalizedGlobalText = fs.readFileSync(normalizeTestEnvPath, "utf8");
+    normalizedBotText = fs.readFileSync(telegramBotEntryFilePath("ryoai"), "utf8");
+  } finally {
+    if (previousUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = previousUserProfile;
+    if (previousHome === undefined) delete process.env.HOME;
+    else process.env.HOME = previousHome;
+  }
+  push(
+    "telegram_env_existing_file_auto_normalizes_named_keys",
+    normalizedGlobalText.includes("TELEGRAM_DEFAULT_BOT_KEY=ryoai")
+      && !normalizedGlobalText.includes("TELEGRAM_BOT_RYOAI_BOT_TOKEN")
+      && !normalizedGlobalText.includes("TELEGRAM_BOT_RYOAI_TOKEN")
+      && normalizedBotText.includes("TELEGRAM_BOT_NAME=ryoai_bot")
+      && normalizedBotText.includes("TELEGRAM_BOT_SERVER_BOT_ID=bot-ryoai")
+      && normalizedBotText.includes("TELEGRAM_BOT_TOKEN=ryoai-token"),
+    `${normalizedGlobalText}\n---\n${normalizedBotText}`,
+  );
   const telegramSupport = getProviderSupport("telegram");
   push(
     "provider_support_telegram_full_runner",

package/lib/bot-commands.mjs

@@ -411,6 +411,17 @@ async function promptKeepChangeClear(ui, title, { allowClear = true, defaultValu
 }
 
 function loadProviderEnvState(provider, deps) {
+  if (provider === "telegram" && typeof deps?.readTelegramEnvState === "function") {
+    const state = deps.readTelegramEnvState();
+    if (state?.error) {
+      throw new Error(String(state.error));
+    }
+    return {
+      provider,
+      filePath: String(state.filePath || "").trim(),
+      parsed: safeObject(state.parsed),
+    };
+  }
   const ensureTemplate = requireDependency(deps, "ensureProviderEnvTemplate");
   const filePathResolver = requireDependency(deps, "providerEnvFilePath");
   const parseEnv = requireDependency(deps, "parseSimpleEnvText");
@@ -441,6 +452,15 @@ function telegramEntryEnvKeys(botKey) {
   };
 }
 
+function telegramEntryCommentName(entry) {
+  const current = safeObject(entry);
+  const username = String(current.username || "").trim();
+  if (username) return username;
+  const key = String(current.key || "").trim();
+  if (!key) return "telegram_bot";
+  return key.endsWith("_bot") ? key : `${key}_bot`;
+}
+
 function persistTelegramUsername(entry) {
   const current = safeObject(entry);
   if (current.__preferServerIdentity) return "";
@@ -491,6 +511,11 @@ function telegramKnownKeys(parsedEnv, deps) {
   return keys;
 }
 
+function isTelegramEntryEnvKey(rawKey) {
+  return /^TELEGRAM_BOT_([A-Z0-9_]+)_(TOKEN|USERNAME|SERVER_BOT_ID|ROLE_PROFILE|AI_CLIENT|AI_MODEL|AI_PERMISSION_MODE|AI_REASONING_EFFORT)$/i
+    .test(String(rawKey || "").trim());
+}
+
 function renderTelegramEnv(parsedEnv, deps) {
   const parsed = safeObject(parsedEnv);
   const collectEntries = requireDependency(deps, "collectTelegramEnvBotEntries");
@@ -535,7 +560,7 @@ function renderTelegramEnv(parsedEnv, deps) {
     entries.forEach((entry) => {
       const keys = telegramEntryEnvKeys(entry.key);
       const entryLines = [
-        `# Telegram bot entry: ${entry.key}`,
+        `# Telegram bot entry: ${telegramEntryCommentName(entry)}`,
         `${keys.serverBotID}=${formatEnvValue(entry.serverBotID || "")}`,
       ];
       if (String(entry.username || "").trim()) {
@@ -555,7 +580,7 @@ function renderTelegramEnv(parsedEnv, deps) {
   }
   const knownKeys = telegramKnownKeys(parsed, deps);
   const extras = Object.keys(parsed)
-    .filter((key) => !knownKeys.has(key))
+    .filter((key) => !knownKeys.has(key) && !isTelegramEntryEnvKey(key))
     .sort((left, right) => left.localeCompare(right));
   if (extras.length) {
     lines.push("# Additional preserved keys");
@@ -591,6 +616,9 @@ function renderTokenOnlyProviderEnv(provider, parsedEnv, deps) {
 }
 
 function writeProviderEnvState(provider, parsedEnv, deps) {
+  if (provider === "telegram" && typeof deps?.writeTelegramEnvState === "function") {
+    return deps.writeTelegramEnvState(parsedEnv);
+  }
   const filePath = String(requireDependency(deps, "providerEnvFilePath")(provider) || "").trim();
   const rendered = provider === "telegram"
     ? renderTelegramEnv(parsedEnv, deps)

package/lib/selftest-bot-commands.mjs

@@ -289,6 +289,15 @@ export async function runSelftestBotCommands(push, deps) {
     const baseURL = `http://127.0.0.1:${mock.port}`;
     const telegramApiBaseURL = `${baseURL}/telegram`;
     const telegramEnvPath = path.join(tempHome, ".metheus", "telegram.env");
+    const telegramBotEntriesDir = path.join(tempHome, ".metheus", "telegram-bots");
+    const readTelegramGlobals = () => parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const readTelegramBotEntry = (botKey) => {
+      const filePath = path.join(telegramBotEntriesDir, `${String(botKey || "").trim()}.env`);
+      if (!fs.existsSync(filePath)) {
+        return {};
+      }
+      return parseSimpleEnvText(fs.readFileSync(filePath, "utf8"));
+    };
 
     const setupResult = await runCLI({
       cliPath,
@@ -314,7 +323,7 @@ export async function runSelftestBotCommands(push, deps) {
       ],
       env,
     });
-    const telegramGlobals = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const telegramGlobals = readTelegramGlobals();
     push(
       "bot_global_updates_telegram_settings",
       String(telegramGlobals.TELEGRAM_API_BASE_URL || "") === telegramApiBaseURL
@@ -339,17 +348,18 @@ export async function runSelftestBotCommands(push, deps) {
         ]),
       },
     });
-    const addState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const addState = readTelegramBotEntry("monitorselftestbot");
+    const addGlobals = readTelegramGlobals();
     push(
       "bot_add_guided_creates_named_telegram_entry",
-      String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_SERVER_BOT_ID || "") === mock.bots[0].id
-        && String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_USERNAME || "").trim() === ""
-        && String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_ROLE_PROFILE || "") === "monitor"
-        && String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "") === "codex"
-        && String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_PERMISSION_MODE || "") === "read_only"
-        && String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_REASONING_EFFORT || "") === "low"
-        && String(addState.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
-      `default=${String(addState.TELEGRAM_DEFAULT_BOT_KEY || "")} role=${String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_ROLE_PROFILE || "")} client=${String(addState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "")}`,
+      String(addState.TELEGRAM_BOT_NAME || "").toLowerCase().includes("monitorselftestbot")
+        && String(addState.TELEGRAM_BOT_TOKEN || "") === "selftest-main-token"
+        && String(addState.TELEGRAM_BOT_ROLE_PROFILE || "") === "monitor"
+        && String(addState.TELEGRAM_BOT_AI_CLIENT || "") === "codex"
+        && String(addState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "read_only"
+        && String(addState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "low"
+        && String(addGlobals.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
+      `default=${String(addGlobals.TELEGRAM_DEFAULT_BOT_KEY || "")} token=${String(addState.TELEGRAM_BOT_TOKEN || "")} role=${String(addState.TELEGRAM_BOT_ROLE_PROFILE || "")} client=${String(addState.TELEGRAM_BOT_AI_CLIENT || "")}`,
     );
 
     const groupedMock = await createMockServer({
@@ -388,15 +398,15 @@ export async function runSelftestBotCommands(push, deps) {
           ]),
         },
       });
-      const groupedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+      const groupedState = readTelegramBotEntry("ryoai");
     push(
       "bot_add_guided_autoresolves_server_bot_group_without_role_prompt",
-        String(groupedState.TELEGRAM_BOT_RYOAI_USERNAME || "").trim() === ""
-          && String(groupedState.TELEGRAM_BOT_RYOAI_SERVER_BOT_ID || "") === ""
-          && String(groupedState.TELEGRAM_BOT_RYOAI_ROLE_PROFILE || "") === ""
-          && String(groupedState.TELEGRAM_BOT_RYOAI_AI_CLIENT || "") === ""
-          && String(groupedState.TELEGRAM_BOT_RYOAI_AI_PERMISSION_MODE || "") === "",
-        `username=${String(groupedState.TELEGRAM_BOT_RYOAI_USERNAME || "")} server_bot_id=${String(groupedState.TELEGRAM_BOT_RYOAI_SERVER_BOT_ID || "")} role=${String(groupedState.TELEGRAM_BOT_RYOAI_ROLE_PROFILE || "")}`,
+        String(groupedState.TELEGRAM_BOT_NAME || "").toLowerCase() === "ryoai_bot"
+          && String(groupedState.TELEGRAM_BOT_SERVER_BOT_ID || "") === ""
+          && String(groupedState.TELEGRAM_BOT_ROLE_PROFILE || "") === ""
+          && String(groupedState.TELEGRAM_BOT_AI_CLIENT || "") === ""
+          && String(groupedState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "",
+        `name=${String(groupedState.TELEGRAM_BOT_NAME || "")} server_bot_id=${String(groupedState.TELEGRAM_BOT_SERVER_BOT_ID || "")} role=${String(groupedState.TELEGRAM_BOT_ROLE_PROFILE || "")}`,
       );
 
       const groupedEditResult = await runCLI({
@@ -571,14 +581,14 @@ export async function runSelftestBotCommands(push, deps) {
       !String(guidedEditResult.stdout || "").includes("Telegram username (without @)"),
       String(guidedEditResult.stdout || "").split(/\r?\n/).filter((line) => line.includes("Telegram username")).join(" | ") || "username prompt skipped",
     );
-    const guidedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const guidedState = readTelegramBotEntry("monitorselftestbot");
     push(
       "bot_edit_guided_prompts_update_ai_binding_fields",
-      String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "") === "gemini"
-        && String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "") === "gemini-3.1-pro"
-        && String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_PERMISSION_MODE || "") === "workspace_write"
-        && String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_REASONING_EFFORT || "") === "medium",
-      `client=${String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "")} model=${String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "")}`,
+      String(guidedState.TELEGRAM_BOT_AI_CLIENT || "") === "gemini"
+        && String(guidedState.TELEGRAM_BOT_AI_MODEL || "") === "gemini-3.1-pro"
+        && String(guidedState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "workspace_write"
+        && String(guidedState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "medium",
+      `client=${String(guidedState.TELEGRAM_BOT_AI_CLIENT || "")} model=${String(guidedState.TELEGRAM_BOT_AI_MODEL || "")}`,
     );
 
     await runCLI({
@@ -596,15 +606,15 @@ export async function runSelftestBotCommands(push, deps) {
       ],
       env,
     });
-    const editedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const editedState = readTelegramBotEntry("monitorselftestbot");
     push(
       "bot_edit_updates_ai_binding_fields",
-      String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_TOKEN || "") === "selftest-edited-token"
-        && String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "") === "claude"
-        && String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "") === "Sonnet 4.6r"
-        && String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_PERMISSION_MODE || "") === "workspace_write"
-        && String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_REASONING_EFFORT || "") === "medium",
-      `client=${String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "")} model=${String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "")}`,
+      String(editedState.TELEGRAM_BOT_TOKEN || "") === "selftest-edited-token"
+        && String(editedState.TELEGRAM_BOT_AI_CLIENT || "") === "claude"
+        && String(editedState.TELEGRAM_BOT_AI_MODEL || "") === "Sonnet 4.6r"
+        && String(editedState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "workspace_write"
+        && String(editedState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "medium",
+      `client=${String(editedState.TELEGRAM_BOT_AI_CLIENT || "")} model=${String(editedState.TELEGRAM_BOT_AI_MODEL || "")}`,
     );
 
     await runCLI({
@@ -619,7 +629,7 @@ export async function runSelftestBotCommands(push, deps) {
         ]),
       },
     });
-    const guidedDefaultState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const guidedDefaultState = readTelegramGlobals();
     push(
       "bot_set_default_guided_selects_entry",
       String(guidedDefaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
@@ -662,7 +672,7 @@ export async function runSelftestBotCommands(push, deps) {
       ],
       env,
     });
-    const defaultState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const defaultState = readTelegramGlobals();
     push(
       "bot_set_default_updates_default_bot_key",
       String(defaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
@@ -744,16 +754,15 @@ export async function runSelftestBotCommands(push, deps) {
       ],
       env,
     });
-    const aliasAddState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const aliasAddState = readTelegramBotEntry("monitorselftestbot");
     push(
       "bot_add_accepts_ai_prefixed_option_aliases",
-      String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_SERVER_BOT_ID || "") === mock.bots[0].id
-        && String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_USERNAME || "") === ""
-        && String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "") === "codex"
-        && String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "") === "gpt-5.4"
-        && String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_PERMISSION_MODE || "") === "read_only"
-        && String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_REASONING_EFFORT || "") === "low",
-      `client=${String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "")} model=${String(aliasAddState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "")}`,
+      String(aliasAddState.TELEGRAM_BOT_SERVER_BOT_ID || "") === mock.bots[0].id
+        && String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "") === "codex"
+        && String(aliasAddState.TELEGRAM_BOT_AI_MODEL || "") === "gpt-5.4"
+        && String(aliasAddState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "read_only"
+        && String(aliasAddState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "low",
+      `client=${String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "")} model=${String(aliasAddState.TELEGRAM_BOT_AI_MODEL || "")}`,
     );
 
     const guidedRemoveBeforeList = await runCLI({
@@ -823,12 +832,13 @@ export async function runSelftestBotCommands(push, deps) {
       ],
       env,
     });
-    const migratedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    const migratedState = readTelegramBotEntry("legacy_main");
+    const migratedGlobals = readTelegramGlobals();
     push(
       "bot_migrate_converts_legacy_token_to_named_entry",
-      String(migratedState.TELEGRAM_BOT_LEGACY_MAIN_TOKEN || "") === "legacy-selftest-token"
-        && String(migratedState.TELEGRAM_BOT_TOKEN || "") === "",
-      `legacy_named=${String(migratedState.TELEGRAM_BOT_LEGACY_MAIN_TOKEN || "")} fallback=${String(migratedState.TELEGRAM_BOT_TOKEN || "")}`,
+      String(migratedState.TELEGRAM_BOT_TOKEN || "") === "legacy-selftest-token"
+        && String(migratedGlobals.TELEGRAM_BOT_TOKEN || "") === "",
+      `legacy_named=${String(migratedState.TELEGRAM_BOT_TOKEN || "")} fallback=${String(migratedGlobals.TELEGRAM_BOT_TOKEN || "")}`,
     );
   } catch (err) {
     push("bot_commands_smoke", false, String(err?.message || err));

package/package.json

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