metheus-governance-mcp-cli 0.2.69 → 0.2.70

package/README.md

@@ -55,7 +55,8 @@ TELEGRAM_BOT_TOKEN=
 
 # Preferred named bot mapping
 TELEGRAM_BOT_MAIN_SERVER_BOT_ID=
-TELEGRAM_BOT_MAIN_USERNAME=<bot_username>
+# Optional fallback only when server bot binding is unavailable
+# TELEGRAM_BOT_MAIN_USERNAME=<bot_username>
 TELEGRAM_BOT_MAIN_TOKEN=
 TELEGRAM_BOT_MAIN_ROLE_PROFILE=monitor
 TELEGRAM_BOT_MAIN_AI_CLIENT=codex
@@ -225,9 +226,11 @@ metheus-governance-mcp-cli bot verify --provider telegram --bot-key main
 Behavior:
 
 - `bot setup` asks for `Telegram / Slack / KakaoTalk` first, then prompts with numbered actions.
-- `bot add` without flags starts a guided question flow: provider -> bot responsibility -> local bot key -> token -> verify.
-- For Telegram, the CLI asks for the server-side bot responsibility first and automatically resolves the matching server bot profile when the role is unique.
-- When you choose a Telegram responsibility such as `monitor`, the CLI automatically uses that server role as the local `role_profile` and fills blank AI defaults from your local `bot-runner.json` `role_profiles` mapping.
+- `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 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 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 starts a guided numbered flow: provider -> bot entry -> guided edit -> step-by-step field choices.
 - In guided `bot edit`, changing the bound Telegram responsibility can also auto-fill blank local AI fields from the selected server role and skip redundant role/AI prompts.
 - `bot set-default` without flags starts a guided numbered flow: provider -> bot entry -> confirm default change.
@@ -235,7 +238,7 @@ Behavior:
 - `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`
+  - `USERNAME` (optional fallback only when server binding is unavailable)
   - `TOKEN`
   - `ROLE_PROFILE`
   - `AI_CLIENT`
@@ -253,7 +256,8 @@ Non-interactive examples:
 
 ```bash
 metheus-governance-mcp-cli bot global --provider telegram --non-interactive true --api-base-url http://127.0.0.1:8999/telegram --auto-clear-webhook false --allowed-updates message,edited_message,channel_post
-metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --bot-key main --server-bot-id <server_bot_uuid> --username <telegram_username> --token <telegram_bot_token> --role-profile monitor --ai-client codex --ai-model gpt-5-codex --ai-permission-mode read_only --ai-reasoning-effort low --default true
+metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --default true
+metheus-governance-mcp-cli bot add --provider telegram --non-interactive true --server-bot-id <server_bot_uuid> --token <telegram_bot_token> --ai-client codex --ai-model gpt-5-codex --ai-permission-mode read_only --ai-reasoning-effort low
 metheus-governance-mcp-cli bot edit --provider telegram --bot-key main --non-interactive true --ai-client claude --ai-model claude-sonnet --ai-permission-mode workspace_write --ai-reasoning-effort medium
 metheus-governance-mcp-cli bot set-default --provider telegram --bot-key main --non-interactive true
 metheus-governance-mcp-cli bot migrate --provider telegram --bot-key main --server-bot-id <server_bot_uuid> --bot-name <telegram_username> --role-profile monitor --ai-client codex --ai-permission-mode read_only --ai-reasoning-effort low --non-interactive true
@@ -261,6 +265,8 @@ metheus-governance-mcp-cli bot remove --provider telegram --bot-key main --non-i
 metheus-governance-mcp-cli bot verify --provider telegram --bot-key main --json true
 ```
 
+For direct Telegram adds, the CLI can derive the local entry key from the matched server bot name. You no longer need `--bot-key` or `--username` in the normal server-bound path. Treat `--bot-key` as an advanced override only when you intentionally want a different local suffix.
+
 Current support status:
 
 - Telegram: full local bot entry management, token verification, bot-to-AI binding, inbound runner support

package/cli.mjs

@@ -748,7 +748,7 @@ function providerEnvTemplate(provider) {
       "# Preferred v2 multi-bot mapping:",
       "# TELEGRAM_DEFAULT_BOT_KEY=main",
       "# TELEGRAM_BOT_MAIN_SERVER_BOT_ID=<server bot uuid>",
-      "# TELEGRAM_BOT_MAIN_USERNAME=<bot username>",
+      "# TELEGRAM_BOT_MAIN_USERNAME=<optional fallback username when server binding is unavailable>",
       "# TELEGRAM_BOT_MAIN_TOKEN=<bot token>",
       "# TELEGRAM_BOT_MAIN_ROLE_PROFILE=monitor",
       "# TELEGRAM_BOT_MAIN_AI_CLIENT=codex",
@@ -766,7 +766,6 @@ function providerEnvTemplate(provider) {
       "",
       "# Preferred named bot entry",
       "TELEGRAM_BOT_MAIN_SERVER_BOT_ID=",
-      "TELEGRAM_BOT_MAIN_USERNAME=",
       "TELEGRAM_BOT_MAIN_TOKEN=",
       "TELEGRAM_BOT_MAIN_ROLE_PROFILE=",
       "TELEGRAM_BOT_MAIN_AI_CLIENT=",
@@ -2730,7 +2729,9 @@ function resolveTelegramEnvConfig(parsedEnv, filePath, config, selectors = {}) {
     selected = entries.find((entry) => entry.serverBotID === desiredBotID) || null;
   }
   if (!selected && desiredUsername) {
-    selected = entries.find((entry) => entry.username === desiredUsername) || null;
+    selected = entries.find(
+      (entry) => entry.username === desiredUsername || normalizeTelegramBotUsername(entry.key) === desiredUsername,
+    ) || null;
   }
   if (!selected && desiredBotKey) {
     selected = entries.find((entry) => entry.key === desiredBotKey) || null;
@@ -3697,8 +3698,9 @@ async function runDoctor(flags) {
         }
         const detailParts = [];
         if (envConfig.botKey) detailParts.push(`bot=${envConfig.botKey}`);
-        if (envConfig.botUsername) detailParts.push(`@${envConfig.botUsername}`);
-        if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
+      if (envConfig.botUsername) detailParts.push(`@${envConfig.botUsername}`);
+      if (envConfig.serverBotID) detailParts.push(`server_bot_id=${envConfig.serverBotID}`);
+        else if (envConfig.botKey) detailParts.push(`server_name=${envConfig.botKey}`);
         if (envConfig.client) detailParts.push(`ai=${envConfig.client}`);
         addDoctorCheck(
           rows,
@@ -3715,12 +3717,28 @@ async function runDoctor(flags) {
           );
         }
         if (route.botID && !envConfig.serverBotID) {
-          addDoctorCheck(
-            rows,
-            strictMode ? "fail" : "warn",
-            `runner route ${routeLabel} server_bot_id`,
-            `route bot_id ${route.botID} is set, but local env entry does not carry SERVER_BOT_ID`,
+          const serverMatch = ensureArray(serverBots).find((bot) => String(bot.id || "").trim() === String(route.botID || "").trim());
+          const routeBotName = normalizeTelegramBotUsername(
+            firstNonEmptyString([route.botName, route.bot_name, serverMatch?.name]),
           );
+          const envBotName = normalizeTelegramBotUsername(envConfig.botUsername || envConfig.botKey);
+          if (routeBotName && envBotName && routeBotName === envBotName) {
+            addDoctorCheck(
+              rows,
+              "ok",
+              `runner route ${routeLabel} server bot`,
+              envConfig.botUsername
+                ? `resolved by bot username @${envConfig.botUsername}`
+                : `resolved by server bot name ${envConfig.botKey}`,
+            );
+          } else {
+            addDoctorCheck(
+              rows,
+              strictMode ? "fail" : "warn",
+              `runner route ${routeLabel} server_bot_id`,
+              `route bot_id ${route.botID} is set, but local env entry does not carry SERVER_BOT_ID`,
+            );
+          }
         }
         if (serverBots && route.botID) {
           const match = ensureArray(serverBots).find((bot) => String(bot.id || "").trim() === String(route.botID || "").trim());

package/lib/bot-commands.mjs

@@ -43,6 +43,35 @@ function firstNonEmptyString(values) {
   return "";
 }
 
+function uniqueNormalizedValues(values, deps, fallback = "") {
+  const normalizeBotKey = requireDependency(deps, "normalizeTelegramBotEnvKey");
+  const seen = new Set();
+  const ordered = [];
+  ensureArray(values).forEach((value) => {
+    const normalized = normalizeBotKey(value || "", "");
+    if (!normalized || seen.has(normalized)) return;
+    seen.add(normalized);
+    ordered.push(normalized);
+  });
+  if (ordered.length) return ordered;
+  const fallbackKey = normalizeBotKey(fallback || "", "");
+  return fallbackKey ? [fallbackKey] : [];
+}
+
+function normalizeServerBotIdentityText(rawValue) {
+  return String(rawValue || "").trim().replace(/^@+/, "").toLowerCase();
+}
+
+function summarizeServerBotRoles(bots) {
+  return Array.from(
+    new Set(
+      ensureArray(bots)
+        .map((bot) => String(bot?.role || "").trim())
+        .filter(Boolean),
+    ),
+  ).sort((left, right) => left.localeCompare(right));
+}
+
 function hasOwnFlag(flags, key) {
   return Object.prototype.hasOwnProperty.call(safeObject(flags), key);
 }
@@ -105,7 +134,7 @@ function printBotUsage(deps) {
       `  ${cliName} bot setup`,
       `  ${cliName} bot list [--provider <telegram|slack|kakaotalk>] [--json <true|false>]`,
       `  ${cliName} bot show [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--bot-id <uuid>] [--bot-name <name>] [--json <true|false>]`,
-      `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-key <key>] [--server-bot-id <uuid>] [--username <name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>] [--default <true|false>] [--verify <true|false>]`,
+      `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--server-bot-id <uuid>] [--token <token>] [--default <true|false>] [--verify <true|false>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>] [--bot-key <advanced_key>] [--username <fallback_name>] [--role-profile <name>]`,
       `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-key <key>] [--server-bot-id <uuid>] [--username <name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>]`,
       `  ${cliName} bot remove [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-key <key>]`,
       `  ${cliName} bot set-default --provider telegram [--bot-key <key>] [--non-interactive <true|false>]`,
@@ -113,6 +142,14 @@ function printBotUsage(deps) {
       `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-key <key>] [--timeout-seconds <n>] [--json <true|false>]`,
       `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
       "",
+      `Behavior:`,
+      `  - bot setup asks for provider first, then shows a numbered action menu.`,
+      `  - bot add without flags uses the shortest practical guided flow: provider -> token -> verify -> optional username fallback -> optional default bot.`,
+      `  - in the normal Telegram path, bot add does not ask for a local bot key or a server role/profile choice.`,
+      `  - server bot name/UUID is the source of truth; local key is auto-derived unless you intentionally override it with --bot-key.`,
+      `  - bot edit without flags asks for provider, existing entry, then a numbered edit flow.`,
+      `  - bot set-default / bot verify / bot remove also support guided numbered selection when run without flags.`,
+      "",
     ].join("\n"),
   );
 }
@@ -277,6 +314,13 @@ function telegramEntryEnvKeys(botKey) {
   };
 }
 
+function persistTelegramUsername(entry) {
+  const current = safeObject(entry);
+  if (current.__preferServerIdentity) return "";
+  if (String(current.serverBotID || "").trim()) return "";
+  return normalizeServerBotIdentityText(current.username || "");
+}
+
 function removeTelegramEntry(parsedEnv, botKey) {
   const parsed = { ...safeObject(parsedEnv) };
   const keys = telegramEntryEnvKeys(botKey);
@@ -295,7 +339,7 @@ function upsertTelegramEntry(parsedEnv, entry) {
   const keys = telegramEntryEnvKeys(entry.key);
   const next = { ...parsed };
   next[keys.serverBotID] = String(entry.serverBotID || "").trim();
-  next[keys.username] = String(entry.username || "").trim();
+  next[keys.username] = persistTelegramUsername(entry);
   next[keys.token] = String(entry.token || "").trim();
   next[keys.roleProfile] = String(entry.roleProfile || "").trim();
   next[keys.client] = String(entry.client || "").trim();
@@ -363,10 +407,14 @@ function renderTelegramEnv(parsedEnv, deps) {
   } else {
     entries.forEach((entry) => {
       const keys = telegramEntryEnvKeys(entry.key);
-      lines.push(
+      const entryLines = [
         `# Telegram bot entry: ${entry.key}`,
         `${keys.serverBotID}=${formatEnvValue(entry.serverBotID || "")}`,
-        `${keys.username}=${formatEnvValue(entry.username || "")}`,
+      ];
+      if (String(entry.username || "").trim()) {
+        entryLines.push(`${keys.username}=${formatEnvValue(entry.username || "")}`);
+      }
+      entryLines.push(
         `${keys.token}=${formatEnvValue(entry.token || "")}`,
         `${keys.roleProfile}=${formatEnvValue(entry.roleProfile || "")}`,
         `${keys.client}=${formatEnvValue(entry.client || "")}`,
@@ -375,6 +423,7 @@ function renderTelegramEnv(parsedEnv, deps) {
         `${keys.reasoningEffort}=${formatEnvValue(entry.reasoningEffort || "")}`,
         "",
       );
+      lines.push(...entryLines);
     });
   }
   const knownKeys = telegramKnownKeys(parsed, deps);
@@ -453,6 +502,23 @@ function telegramEntriesForDisplay(parsedEnv, deps) {
     .sort((left, right) => String(left.key || "").localeCompare(String(right.key || "")));
 }
 
+function telegramEntryDisplayName(entry) {
+  const current = safeObject(entry);
+  const username = String(current.username || "").trim();
+  if (username) return `@${username}`;
+  return String(current.key || "").trim() || "(unnamed)";
+}
+
+function telegramEntryDisplayDescription(entry) {
+  const current = safeObject(entry);
+  const detail = [
+    current.key ? `key:${current.key}` : "",
+    current.serverBotID ? `server:${current.serverBotID}` : "",
+    current.client ? `AI:${current.client}` : "",
+  ].filter(Boolean);
+  return detail.join(" ");
+}
+
 function findTelegramEntryByFlags(parsedEnv, flags, deps) {
   const entries = telegramEntriesForDisplay(parsedEnv, deps);
   const requestedKey = String(flags["bot-key"] || "").trim();
@@ -473,9 +539,11 @@ function findTelegramEntryByFlags(parsedEnv, flags, deps) {
     return match;
   }
   if (requestedName) {
-    const match = entries.find((entry) => entry.username === requestedName);
+    const match = entries.find(
+      (entry) => entry.username === requestedName || normalizeServerBotIdentityText(entry.key) === requestedName,
+    );
     if (!match) {
-      throw new Error(`Telegram bot entry with username "${requestedName}" was not found`);
+      throw new Error(`Telegram bot entry with server bot name "${requestedName}" was not found`);
     }
     return match;
   }
@@ -496,8 +564,44 @@ function saveTelegramBotEdit(parsed, selected, current, deps) {
   return filePath;
 }
 
+function buildDerivedTelegramBotKey(parsedEnv, deps, preferredValues, { excludeKeys = [] } = {}) {
+  const normalizeBotKey = requireDependency(deps, "normalizeTelegramBotEnvKey");
+  const existingKeys = new Set(
+    telegramEntriesForDisplay(parsedEnv, deps)
+      .map((entry) => entry.key)
+      .filter((key) => !ensureArray(excludeKeys).includes(key)),
+  );
+  const candidates = uniqueNormalizedValues(
+    [
+      ...ensureArray(preferredValues),
+      "main",
+    ],
+    deps,
+    "main",
+  );
+  const baseKey = candidates[0] || normalizeBotKey("main", "main") || "main";
+  for (const candidate of candidates) {
+    if (!existingKeys.has(candidate)) {
+      return candidate;
+    }
+  }
+  let suffix = 2;
+  while (existingKeys.has(`${baseKey}_${suffix}`)) {
+    suffix += 1;
+  }
+  return `${baseKey}_${suffix}`;
+}
+
 async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps) {
   let serverRoleAutoResolved = "";
+  const aiFlagOverrides = hasOwnFlag(flags, "client")
+    || hasOwnFlag(flags, "ai-client")
+    || hasOwnFlag(flags, "model")
+    || hasOwnFlag(flags, "ai-model")
+    || hasOwnFlag(flags, "permission-mode")
+    || hasOwnFlag(flags, "ai-permission-mode")
+    || hasOwnFlag(flags, "reasoning-effort")
+    || hasOwnFlag(flags, "ai-reasoning-effort");
   const bindingAction = await promptKeepChangeClear(ui, "Server bot binding", {
     allowClear: true,
     defaultValue: current.serverBotID ? "keep" : "change",
@@ -509,15 +613,39 @@ async function editTelegramBotGuided(ui, parsed, selected, current, flags, deps)
       flags["base-url"] || deps.defaultSiteURL,
       intFromRaw(flags["timeout-seconds"], 15) || 15,
       deps,
+      {
+        preferredUsername: current.username,
+        preferredName: current.username,
+      },
     );
-    current.serverBotID = serverBot.botID;
-    if (!current.roleProfile && serverBot.role) {
-      current.roleProfile = serverBot.role;
+    if (serverBot.matchMode === "group") {
+      current.serverBotID = "";
+      current.__preferServerIdentity = true;
+      if (!String(flags["role-profile"] || "").trim()) {
+        current.roleProfile = "";
+      }
+      if (!aiFlagOverrides) {
+        current.client = "";
+        current.model = "";
+        current.permissionMode = "";
+        current.reasoningEffort = "";
+      }
+      serverRoleAutoResolved = "__server_role_group__";
+      process.stdout.write(
+        `Matched server Telegram bot "${serverBot.name || current.username || current.key}" with roles: ${ensureArray(serverBot.roles).join(", ")}. Runtime will use the server role, so local role/AI fields can stay empty.\n`,
+      );
+    } else {
+      current.serverBotID = serverBot.botID;
+      current.__preferServerIdentity = true;
+      if (!current.roleProfile && serverBot.role) {
+        current.roleProfile = serverBot.role;
+      }
+      serverRoleAutoResolved = String(serverBot.role || current.roleProfile || "").trim();
+      applyRoleProfileDefaults(current, resolveRoleProfileDefaults(current.roleProfile || serverBot.role, deps));
     }
-    serverRoleAutoResolved = String(serverBot.role || current.roleProfile || "").trim();
-    applyRoleProfileDefaults(current, resolveRoleProfileDefaults(current.roleProfile || serverBot.role, deps));
   } else if (bindingAction === "clear") {
     current.serverBotID = "";
+    current.__preferServerIdentity = false;
   }
 
   const usernameAction = await promptKeepChangeClear(ui, "Telegram username", {
@@ -754,7 +882,8 @@ function printBotList(provider, state, deps) {
     entries.forEach((entry) => {
       process.stdout.write(
         [
-          `  - ${entry.key}${entry.isDefault ? " [default]" : ""}`,
+          `  - ${telegramEntryDisplayName(entry)}${entry.isDefault ? " [default]" : ""}`,
+          `    key: ${entry.key || "-"}`,
           `    server_bot_id: ${entry.serverBotID || "-"}`,
           `    username: ${entry.username ? `@${entry.username}` : "-"}`,
           `    token: ${entry.token ? maskSecret(entry.token) : "-"}`,
@@ -778,6 +907,7 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
     const selectedEntry = entry || {};
     process.stdout.write(`${providerLabel(provider, deps)} bot\n`);
     process.stdout.write(`  file: ${state.filePath}\n`);
+    process.stdout.write(`  name: ${telegramEntryDisplayName(selectedEntry)}\n`);
     process.stdout.write(`  key: ${selectedEntry.key || "-"}\n`);
     process.stdout.write(`  default: ${selectedEntry.isDefault ? "yes" : "no"}\n`);
     process.stdout.write(`  server_bot_id: ${selectedEntry.serverBotID || "-"}\n`);
@@ -810,8 +940,8 @@ async function chooseTelegramEntry(ui, parsedEnv, deps, title = "Select Telegram
     title,
     entries.map((entry) => ({
       value: entry.key,
-      label: `${entry.key}${entry.isDefault ? " [default]" : ""}`,
-      description: `${entry.serverBotID || "-"} ${entry.username ? `@${entry.username}` : ""} ${entry.client ? `AI:${entry.client}` : ""}`.trim(),
+      label: `${telegramEntryDisplayName(entry)}${entry.isDefault ? " [default]" : ""}`,
+      description: telegramEntryDisplayDescription(entry),
     })),
     { defaultIndex: 0 },
   );
@@ -844,7 +974,7 @@ async function resolveTelegramEntryForShow(ui, parsedEnv, flags, deps) {
   return chooseTelegramEntry(ui, parsedEnv, deps, "Select Telegram bot entry");
 }
 
-async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
+async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps, options = {}) {
   const lookup = requireDependency(deps, "listServerBots");
   const result = await lookup({ provider, baseURL, timeoutSeconds });
   const bots = ensureArray(result?.bots).map((bot) => ({
@@ -857,11 +987,40 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
       process.stdout.write(`Server bot profiles unavailable: ${result.error}\n`);
     }
     const manualID = await promptLine(ui, "Server bot UUID (blank to leave empty)", "");
-    return {
-      botID: manualID,
-      role: "",
-      name: "",
-    };
+      return {
+        botID: manualID,
+        role: "",
+        name: "",
+        roles: [],
+        matchMode: manualID ? "manual" : "blank",
+      };
+    }
+  const preferredIdentity = normalizeServerBotIdentityText(
+    firstNonEmptyString([options.preferredUsername, options.preferredName]),
+  );
+  if (preferredIdentity) {
+    const matchedByName = bots.filter(
+      (bot) => normalizeServerBotIdentityText(bot.name) === preferredIdentity,
+    );
+    if (matchedByName.length === 1) {
+      const match = matchedByName[0] || {};
+      return {
+        botID: String(match.id || "").trim(),
+        role: String(match.role || "").trim(),
+        name: String(match.name || "").trim(),
+        roles: summarizeServerBotRoles([match]),
+        matchMode: "exact",
+      };
+    }
+    if (matchedByName.length > 1) {
+      return {
+        botID: "",
+        role: "",
+        name: String(matchedByName[0]?.name || "").trim(),
+        roles: summarizeServerBotRoles(matchedByName),
+        matchMode: "group",
+      };
+    }
   }
   if (bots.length === 1) {
     const match = bots[0] || {};
@@ -869,8 +1028,30 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
       botID: String(match.id || "").trim(),
       role: String(match.role || "").trim(),
       name: String(match.name || "").trim(),
+      roles: summarizeServerBotRoles([match]),
+      matchMode: "exact",
     };
   }
+  const groupedByName = new Map();
+  bots.forEach((bot) => {
+    const nameKey = normalizeServerBotIdentityText(bot.name) || bot.id;
+    if (!groupedByName.has(nameKey)) {
+      groupedByName.set(nameKey, []);
+    }
+    groupedByName.get(nameKey).push(bot);
+  });
+  if (groupedByName.size === 1) {
+    const groupedBots = ensureArray(groupedByName.values().next().value);
+    if (groupedBots.length > 1) {
+      return {
+        botID: "",
+        role: "",
+        name: String(groupedBots[0]?.name || "").trim(),
+        roles: summarizeServerBotRoles(groupedBots),
+        matchMode: "group",
+      };
+    }
+  }
   const preferredRoleOrder = ["monitor", "review", "worker", "approval"];
   const roleGroups = new Map();
   bots.forEach((bot) => {
@@ -921,7 +1102,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
     { defaultIndex: 0 },
   );
   if (!roleChoice || roleChoice.value === "__blank__") {
-    return { botID: "", role: "", name: "" };
+    return { botID: "", role: "", name: "", roles: [], matchMode: "blank" };
   }
   if (roleChoice.value === "__manual__") {
     const manualID = await promptLine(ui, "Server bot UUID", "");
@@ -929,6 +1110,8 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
       botID: manualID,
       role: "",
       name: "",
+      roles: [],
+      matchMode: manualID ? "manual" : "blank",
     };
   }
   if (String(roleChoice.value || "").startsWith("role:")) {
@@ -938,6 +1121,8 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
       botID: String(match.id || "").trim(),
       role: String(match.role || "").trim(),
       name: String(match.name || "").trim(),
+      roles: summarizeServerBotRoles([match]),
+      matchMode: "exact",
     };
   }
   const selectedRole = String(roleChoice.value || "").slice(6);
@@ -965,7 +1150,7 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
     { defaultIndex: 0 },
   );
   if (!choice || choice.value === "__blank__") {
-    return { botID: "", role: "", name: "" };
+    return { botID: "", role: "", name: "", roles: [], matchMode: "blank" };
   }
   if (choice.value === "__manual__") {
     const manualID = await promptLine(ui, "Server bot UUID", "");
@@ -973,6 +1158,8 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
       botID: manualID,
       role: selectedRole,
       name: "",
+      roles: selectedRole ? [selectedRole] : [],
+      matchMode: manualID ? "manual" : "blank",
     };
   }
   const match = matches.find((bot) => bot.id === choice.value) || {};
@@ -980,6 +1167,72 @@ async function chooseServerBot(ui, provider, baseURL, timeoutSeconds, deps) {
     botID: String(match.id || "").trim(),
     role: String(match.role || "").trim(),
     name: String(match.name || "").trim(),
+    roles: summarizeServerBotRoles([match]),
+    matchMode: "exact",
+  };
+}
+
+async function resolveServerBotForNonInteractive(provider, flags, deps, options = {}) {
+  const requestedBotID = String(getServerBotIDFlag(flags) || "").trim();
+  const requestedName = normalizeServerBotIdentityText(
+    firstNonEmptyString([
+      flags["bot-name"],
+      flags.username,
+      options.preferredUsername,
+      options.preferredName,
+    ]),
+  );
+  if (!requestedBotID && !requestedName) {
+    return { botID: "", role: "", name: "", roles: [], matchMode: "blank" };
+  }
+  const lookup = await requireDependency(deps, "listServerBots")({
+    provider,
+    baseURL: flags["base-url"] || deps.defaultSiteURL,
+    timeoutSeconds: intFromRaw(flags["timeout-seconds"], 15) || 15,
+  });
+  const bots = ensureArray(lookup?.bots).map((bot) => ({
+    id: String(bot?.id || "").trim(),
+    role: String(bot?.role || bot?.bot_role || "").trim(),
+    name: String(bot?.name || "").trim(),
+  })).filter((bot) => bot.id);
+  if (!lookup?.ok) {
+    throw new Error(lookup?.error || "server bot lookup unavailable");
+  }
+  if (requestedBotID) {
+    const match = bots.find((bot) => bot.id === requestedBotID);
+    if (!match) {
+      throw new Error(`server bot ${requestedBotID} not found`);
+    }
+    return {
+      botID: match.id,
+      role: match.role,
+      name: match.name,
+      roles: summarizeServerBotRoles([match]),
+      matchMode: "exact",
+    };
+  }
+  const matchedByName = bots.filter(
+    (bot) => normalizeServerBotIdentityText(bot.name) === requestedName,
+  );
+  if (!matchedByName.length) {
+    throw new Error(`no server bot matched ${requestedName}`);
+  }
+  if (matchedByName.length === 1) {
+    const match = matchedByName[0] || {};
+    return {
+      botID: String(match.id || "").trim(),
+      role: String(match.role || "").trim(),
+      name: String(match.name || "").trim(),
+      roles: summarizeServerBotRoles([match]),
+      matchMode: "exact",
+    };
+  }
+  return {
+    botID: "",
+    role: "",
+    name: String(matchedByName[0]?.name || "").trim(),
+    roles: summarizeServerBotRoles(matchedByName),
+    matchMode: "group",
   };
 }
 
@@ -1090,35 +1343,9 @@ async function addTelegramBot(ui, flags, deps) {
   const state = loadProviderEnvState("telegram", deps);
   const parsed = { ...state.parsed };
   const nonInteractive = boolFromRaw(flags["non-interactive"] ?? flags.yes, false);
-  const serverBot = nonInteractive
-    ? {
-      botID: getServerBotIDFlag(flags),
-      role: String(flags.role || "").trim(),
-      name: "",
-    }
-    : await chooseServerBot(
-      ui,
-      "telegram",
-      flags["base-url"] || deps.defaultSiteURL,
-      intFromRaw(flags["timeout-seconds"], 15) || 15,
-      deps,
-    );
   const normalizeBotKey = requireDependency(deps, "normalizeTelegramBotEnvKey");
   const existingKeys = new Set(telegramEntriesForDisplay(parsed, deps).map((entry) => entry.key));
-  const defaultKeyHint = normalizeBotKey(flags["bot-key"] || serverBot.role || serverBot.name || "main", "main");
-  let botKey = normalizeBotKey(
-    nonInteractive
-      ? String(flags["bot-key"] || defaultKeyHint).trim()
-      : await promptRequiredLine(ui, "Local Telegram bot key", defaultKeyHint),
-    defaultKeyHint,
-  );
-  if (nonInteractive && existingKeys.has(botKey)) {
-    throw new Error(`Telegram bot key "${botKey}" already exists`);
-  }
-  while (!nonInteractive && existingKeys.has(botKey)) {
-    process.stdout.write(`Telegram bot key "${botKey}" already exists.\n`);
-    botKey = normalizeBotKey(await promptRequiredLine(ui, "Local Telegram bot key", `${botKey}_2`), `${botKey}_2`);
-  }
+  const defaultKeyHint = normalizeBotKey(flags["bot-key"] || "main", "main");
 
   const token = nonInteractive
     ? String(flags.token || "").trim()
@@ -1159,12 +1386,69 @@ async function addTelegramBot(ui, flags, deps) {
       ? String(flags.username || usernameDefault).trim()
       : (usernameDefault || await promptLine(ui, "Telegram username (without @)", usernameDefault)),
   );
+  const serverBot = nonInteractive
+    ? await resolveServerBotForNonInteractive("telegram", flags, deps, {
+      preferredUsername: username,
+      preferredName: username,
+    })
+    : await chooseServerBot(
+      ui,
+      "telegram",
+      flags["base-url"] || deps.defaultSiteURL,
+      intFromRaw(flags["timeout-seconds"], 15) || 15,
+      deps,
+      {
+        preferredUsername: username,
+        preferredName: username,
+      },
+    );
+  let botKey = normalizeBotKey(
+    nonInteractive
+      ? String(
+        flags["bot-key"]
+        || buildDerivedTelegramBotKey(
+          parsed,
+          deps,
+          [
+            serverBot.name,
+            username,
+            flags["bot-name"],
+            flags.username,
+            defaultKeyHint,
+          ],
+        ),
+      ).trim()
+      : buildDerivedTelegramBotKey(
+        parsed,
+        deps,
+        [
+          flags["bot-key"],
+          serverBot.name,
+          username,
+          flags["bot-name"],
+          flags.username,
+          defaultKeyHint,
+        ],
+      ),
+    defaultKeyHint,
+  );
+  if (nonInteractive && existingKeys.has(botKey)) {
+    throw new Error(`Telegram bot key "${botKey}" already exists`);
+  }
+  const serverGroupMatched = !nonInteractive && serverBot.matchMode === "group";
+  if (serverGroupMatched) {
+    process.stdout.write(
+      `Matched server Telegram bot "${serverBot.name || username || botKey}" with roles: ${ensureArray(serverBot.roles).join(", ")}. Runtime will use the server role, so local role/AI fields can stay empty.\n`,
+    );
+  }
   const defaultRoleProfile = firstNonEmptyString([flags["role-profile"], serverBot.role, ""]);
   const roleProfileAutoResolved = !nonInteractive && !String(flags["role-profile"] || "").trim() && Boolean(defaultRoleProfile);
   const roleProfile = requireDependency(deps, "normalizeRunnerRoleProfileName")(
     nonInteractive
       ? String(flags["role-profile"] || defaultRoleProfile).trim()
-      : (roleProfileAutoResolved ? defaultRoleProfile : await promptTelegramRoleProfile(ui, deps, defaultRoleProfile)),
+      : (serverGroupMatched && !String(flags["role-profile"] || "").trim()
+        ? ""
+        : (roleProfileAutoResolved ? defaultRoleProfile : await promptTelegramRoleProfile(ui, deps, defaultRoleProfile))),
   );
   const roleProfileDefaults = resolveRoleProfileDefaults(roleProfile, deps);
   const aiFlagOverrides = hasOwnFlag(flags, "client")
@@ -1176,33 +1460,45 @@ async function addTelegramBot(ui, flags, deps) {
     || hasOwnFlag(flags, "reasoning-effort")
     || hasOwnFlag(flags, "ai-reasoning-effort");
   const autoApplyRoleDefaults = !nonInteractive && roleProfileAutoResolved && !aiFlagOverrides;
+  const autoUseServerRoleRouting = !nonInteractive
+    && serverGroupMatched
+    && !String(flags["role-profile"] || "").trim()
+    && !aiFlagOverrides;
   const client = requireDependency(deps, "normalizeLocalAIClientName")(
     nonInteractive
       ? firstNonEmptyString([getAIClientFlag(flags), roleProfileDefaults.client])
-      : (autoApplyRoleDefaults
-        ? firstNonEmptyString([getAIClientFlag(flags), roleProfileDefaults.client])
-        : await promptAIClient(ui, deps, firstNonEmptyString([getAIClientFlag(flags), roleProfileDefaults.client]))),
+      : (autoUseServerRoleRouting
+        ? getAIClientFlag(flags)
+        : (autoApplyRoleDefaults
+          ? firstNonEmptyString([getAIClientFlag(flags), roleProfileDefaults.client])
+          : await promptAIClient(ui, deps, firstNonEmptyString([getAIClientFlag(flags), roleProfileDefaults.client])))),
     "",
   );
   const model = nonInteractive
     ? firstNonEmptyString([getAIModelFlag(flags), roleProfileDefaults.model])
-    : (autoApplyRoleDefaults
-      ? firstNonEmptyString([getAIModelFlag(flags), roleProfileDefaults.model])
-      : await promptLine(ui, "AI model", firstNonEmptyString([getAIModelFlag(flags), roleProfileDefaults.model])));
+    : (autoUseServerRoleRouting
+      ? getAIModelFlag(flags)
+      : (autoApplyRoleDefaults
+        ? firstNonEmptyString([getAIModelFlag(flags), roleProfileDefaults.model])
+        : await promptLine(ui, "AI model", firstNonEmptyString([getAIModelFlag(flags), roleProfileDefaults.model]))));
   const permissionMode = requireDependency(deps, "normalizeLocalAIPermissionMode")(
     nonInteractive
       ? firstNonEmptyString([getAIPermissionModeFlag(flags), roleProfileDefaults.permissionMode])
-      : (autoApplyRoleDefaults
-        ? firstNonEmptyString([getAIPermissionModeFlag(flags), roleProfileDefaults.permissionMode])
-        : await promptPermissionMode(ui, firstNonEmptyString([getAIPermissionModeFlag(flags), roleProfileDefaults.permissionMode]))),
+      : (autoUseServerRoleRouting
+        ? getAIPermissionModeFlag(flags)
+        : (autoApplyRoleDefaults
+          ? firstNonEmptyString([getAIPermissionModeFlag(flags), roleProfileDefaults.permissionMode])
+          : await promptPermissionMode(ui, firstNonEmptyString([getAIPermissionModeFlag(flags), roleProfileDefaults.permissionMode])))),
     "",
   );
   const reasoningEffort = requireDependency(deps, "normalizeLocalAIReasoningEffort")(
     nonInteractive
       ? firstNonEmptyString([getAIReasoningEffortFlag(flags), roleProfileDefaults.reasoningEffort])
-      : (autoApplyRoleDefaults
-        ? firstNonEmptyString([getAIReasoningEffortFlag(flags), roleProfileDefaults.reasoningEffort])
-        : await promptReasoningEffort(ui, firstNonEmptyString([getAIReasoningEffortFlag(flags), roleProfileDefaults.reasoningEffort]))),
+      : (autoUseServerRoleRouting
+        ? getAIReasoningEffortFlag(flags)
+        : (autoApplyRoleDefaults
+          ? firstNonEmptyString([getAIReasoningEffortFlag(flags), roleProfileDefaults.reasoningEffort])
+          : await promptReasoningEffort(ui, firstNonEmptyString([getAIReasoningEffortFlag(flags), roleProfileDefaults.reasoningEffort])))),
     "",
   );
 
@@ -1210,6 +1506,7 @@ async function addTelegramBot(ui, flags, deps) {
     key: botKey,
     serverBotID: String(getServerBotIDFlag(flags) || serverBot.botID || "").trim(),
     username,
+    __preferServerIdentity: serverBot.matchMode === "group" || Boolean(String(getServerBotIDFlag(flags) || serverBot.botID || "").trim()),
     token,
     roleProfile,
     client,
@@ -1218,9 +1515,11 @@ async function addTelegramBot(ui, flags, deps) {
     reasoningEffort,
   });
 
-  const hasCurrentDefault = Boolean(String(parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim());
+  const currentDefaultKey = normalizeBotKey(parsed.TELEGRAM_DEFAULT_BOT_KEY || "", "");
+  const hasCurrentDefault = telegramEntriesForDisplay(parsed, deps).some((entry) => entry.key === currentDefaultKey);
   if (
     boolFromRaw(flags.default, false)
+    || (nonInteractive && !hasCurrentDefault)
     || (!nonInteractive && !hasCurrentDefault && await promptYesNo(ui, "Set this bot as TELEGRAM_DEFAULT_BOT_KEY?", true))
   ) {
     nextParsed.TELEGRAM_DEFAULT_BOT_KEY = botKey;
@@ -1296,6 +1595,7 @@ async function editTelegramBot(ui, flags, deps) {
   if (nonInteractive) {
     if (getServerBotIDFlag(flags)) {
       current.serverBotID = getServerBotIDFlag(flags);
+      current.__preferServerIdentity = true;
     }
     if (Object.prototype.hasOwnProperty.call(flags, "username")) {
       current.username = requireDependency(deps, "normalizeTelegramBotUsername")(flags.username || "");
@@ -1368,10 +1668,21 @@ async function editTelegramBot(ui, flags, deps) {
         flags["base-url"] || deps.defaultSiteURL,
         intFromRaw(flags["timeout-seconds"], 15) || 15,
         deps,
+        {
+          preferredUsername: current.username,
+          preferredName: current.username,
+        },
       );
-      current.serverBotID = serverBot.botID;
-      if (!current.roleProfile && serverBot.role) {
-        current.roleProfile = serverBot.role;
+      if (serverBot.matchMode === "group") {
+        current.serverBotID = "";
+        process.stdout.write(
+          `Matched server Telegram bot "${serverBot.name || current.username || current.key}" with roles: ${ensureArray(serverBot.roles).join(", ")}. Keep role/AI fields empty if you want runtime role-based resolution.\n`,
+        );
+      } else {
+        current.serverBotID = serverBot.botID;
+        if (!current.roleProfile && serverBot.role) {
+          current.roleProfile = serverBot.role;
+        }
       }
     } else if (choice.value === "username") {
       current.username = requireDependency(deps, "normalizeTelegramBotUsername")(
@@ -1490,7 +1801,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
   );
   let serverBinding = null;
   let overallOK = Boolean(result.ok);
-  if (provider === "telegram" && String(envConfig.serverBotID || "").trim()) {
+  if (provider === "telegram" && (String(envConfig.serverBotID || "").trim() || String(envConfig.botUsername || "").trim() || String(envConfig.botKey || "").trim())) {
     const lookup = await requireDependency(deps, "listServerBots")({
       provider,
       baseURL: flags["base-url"] || deps.defaultSiteURL,
@@ -1503,18 +1814,37 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
       };
       overallOK = false;
     } else {
-      const match = ensureArray(lookup.bots).find((bot) => String(bot.id || "").trim() === String(envConfig.serverBotID || "").trim());
-      if (!match) {
-        serverBinding = {
-          ok: false,
-          detail: `server bot ${envConfig.serverBotID} not found`,
-        };
-        overallOK = false;
+      const normalizedServerIdentity = normalizeServerBotIdentityText(envConfig.botUsername || envConfig.botKey);
+      if (String(envConfig.serverBotID || "").trim()) {
+        const match = ensureArray(lookup.bots).find((bot) => String(bot.id || "").trim() === String(envConfig.serverBotID || "").trim());
+        if (!match) {
+          serverBinding = {
+            ok: false,
+            detail: `server bot ${envConfig.serverBotID} not found`,
+          };
+          overallOK = false;
+        } else {
+          serverBinding = {
+            ok: true,
+            detail: `${String(match.name || "").trim() || "(unnamed)"} [${String(match.role || "").trim() || "-"}]`,
+          };
+        }
       } else {
-        serverBinding = {
-          ok: true,
-          detail: `${String(match.name || "").trim() || "(unnamed)"} [${String(match.role || "").trim() || "-"}]`,
-        };
+        const matches = ensureArray(lookup.bots).filter(
+          (bot) => normalizeServerBotIdentityText(bot?.name) === normalizedServerIdentity,
+        );
+        if (!matches.length) {
+          serverBinding = {
+            ok: false,
+            detail: `no server bot matched ${envConfig.botUsername ? `@${envConfig.botUsername}` : envConfig.botKey}`,
+          };
+          overallOK = false;
+        } else {
+          serverBinding = {
+            ok: true,
+            detail: `${String(matches[0]?.name || "").trim() || "(unnamed)"} roles: ${summarizeServerBotRoles(matches).join(", ") || "-"}`,
+          };
+        }
       }
     }
   }

package/lib/selftest-bot-commands.mjs

@@ -84,20 +84,26 @@ function readTrailingJSON(rawText) {
   return readJSON(text.slice(start));
 }
 
-function createMockServer() {
-  const serverBots = [
-    {
-      id: "11111111-2222-3333-4444-555555555555",
-      name: "MonitorSelftestBot",
-      provider: "telegram",
-      bot_role: "monitor",
-      is_active: true,
-    },
-  ];
-  const telegramUsersByToken = new Map([
-    ["selftest-main-token", "MonitorSelftestBot"],
-    ["selftest-edited-token", "MonitorSelftestBot"],
-  ]);
+function createMockServer(options = {}) {
+  const serverBots = ensureArray(options.serverBots).length
+    ? ensureArray(options.serverBots)
+    : [
+      {
+        id: "11111111-2222-3333-4444-555555555555",
+        name: "MonitorSelftestBot",
+        provider: "telegram",
+        bot_role: "monitor",
+        is_active: true,
+      },
+    ];
+  const telegramUsersByToken = new Map(
+    ensureArray(options.telegramUsersByToken).length
+      ? ensureArray(options.telegramUsersByToken)
+      : [
+        ["selftest-main-token", "MonitorSelftestBot"],
+        ["selftest-edited-token", "MonitorSelftestBot"],
+      ],
+  );
 
   const server = http.createServer((req, res) => {
     const url = new URL(req.url || "/", "http://127.0.0.1");
@@ -271,7 +277,6 @@ export async function runSelftestBotCommands(push, deps) {
         ...env,
         METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
           "1", // provider: telegram
-          "main_test",
           "selftest-main-token",
           "y", // verify now
         ]),
@@ -280,22 +285,82 @@ export async function runSelftestBotCommands(push, deps) {
     const addState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
       "bot_add_guided_creates_named_telegram_entry",
-      String(addState.TELEGRAM_BOT_MAIN_TEST_SERVER_BOT_ID || "") === mock.bots[0].id
-        && String(addState.TELEGRAM_BOT_MAIN_TEST_USERNAME || "").trim().toLowerCase() === "monitorselftestbot"
-        && String(addState.TELEGRAM_BOT_MAIN_TEST_ROLE_PROFILE || "") === "monitor"
-        && String(addState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "") === "codex"
-        && String(addState.TELEGRAM_BOT_MAIN_TEST_AI_PERMISSION_MODE || "") === "read_only"
-        && String(addState.TELEGRAM_BOT_MAIN_TEST_AI_REASONING_EFFORT || "") === "low"
-        && String(addState.TELEGRAM_DEFAULT_BOT_KEY || "") === "main",
-      `default=${String(addState.TELEGRAM_DEFAULT_BOT_KEY || "")} role=${String(addState.TELEGRAM_BOT_MAIN_TEST_ROLE_PROFILE || "")} client=${String(addState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")}`,
+      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 || "")}`,
     );
 
+    const groupedMock = await createMockServer({
+      serverBots: [
+        { id: "977ef999-c40b-4cf6-a142-ade246f1b9cf", name: "RyoAI_bot", provider: "telegram", bot_role: "approval", is_active: true },
+        { id: "d74b57de-a635-4bac-a20f-f8ada188cf97", name: "RyoAI_bot", provider: "telegram", bot_role: "worker", is_active: true },
+        { id: "bbae9450-4236-487c-9a05-61dc4a626215", name: "RyoAI_bot", provider: "telegram", bot_role: "review", is_active: true },
+        { id: "353896c5-3b6b-422f-9eeb-5dc9354f77b3", name: "RyoAI_bot", provider: "telegram", bot_role: "monitor", is_active: true },
+      ],
+      telegramUsersByToken: [["selftest-group-token", "RyoAI_bot"]],
+    }).listen();
+    try {
+      await runCLI({
+        cliPath,
+        args: [
+          "bot", "global",
+          "--provider", "telegram",
+          "--non-interactive", "true",
+          "--api-base-url", `http://127.0.0.1:${groupedMock.port}/telegram`,
+        ],
+        env,
+      });
+      await runCLI({
+        cliPath,
+        args: [
+          "bot", "add",
+          "--base-url", `http://127.0.0.1:${groupedMock.port}`,
+          "--timeout-seconds", "5",
+        ],
+        env: {
+          ...env,
+          METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
+            "1",
+            "selftest-group-token",
+            "y",
+          ]),
+        },
+      });
+      const groupedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
+    push(
+      "bot_add_guided_autoresolves_server_bot_group_without_role_prompt",
+        String(groupedState.TELEGRAM_BOT_RYOAI_BOT_USERNAME || "").trim() === ""
+          && String(groupedState.TELEGRAM_BOT_RYOAI_BOT_SERVER_BOT_ID || "") === ""
+          && String(groupedState.TELEGRAM_BOT_RYOAI_BOT_ROLE_PROFILE || "") === ""
+          && String(groupedState.TELEGRAM_BOT_RYOAI_BOT_AI_CLIENT || "") === ""
+          && String(groupedState.TELEGRAM_BOT_RYOAI_BOT_AI_PERMISSION_MODE || "") === "",
+        `username=${String(groupedState.TELEGRAM_BOT_RYOAI_BOT_USERNAME || "")} server_bot_id=${String(groupedState.TELEGRAM_BOT_RYOAI_BOT_SERVER_BOT_ID || "")} role=${String(groupedState.TELEGRAM_BOT_RYOAI_BOT_ROLE_PROFILE || "")}`,
+      );
+    } finally {
+      await groupedMock.close();
+      await runCLI({
+        cliPath,
+        args: [
+          "bot", "global",
+          "--provider", "telegram",
+          "--non-interactive", "true",
+          "--api-base-url", telegramApiBaseURL,
+        ],
+        env,
+      });
+    }
+
     const showResult = await runCLI({
       cliPath,
       args: [
         "bot", "show",
         "--provider", "telegram",
-        "--bot-key", "main_test",
+        "--bot-key", "monitorselftestbot",
         "--json", "true",
       ],
       env,
@@ -303,7 +368,7 @@ export async function runSelftestBotCommands(push, deps) {
     const showPayload = readJSON(showResult.stdout);
     push(
       "bot_show_returns_selected_telegram_entry",
-      safeObject(showPayload.entry).key === "main_test"
+      safeObject(showPayload.entry).key === "monitorselftestbot"
         && safeObject(showPayload.entry).client === "codex",
       `key=${String(safeObject(showPayload.entry).key || "")} client=${String(safeObject(showPayload.entry).client || "")}`,
     );
@@ -315,7 +380,7 @@ export async function runSelftestBotCommands(push, deps) {
         ...env,
         METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
         "1", // provider: telegram
-        "1", // bot entry: main_test
+        "1", // bot entry: @monitorselftestbot
         "1", // edit mode: guided
         "1", // keep server bot binding
         "1", // keep username
@@ -338,11 +403,11 @@ export async function runSelftestBotCommands(push, deps) {
     const guidedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
       "bot_edit_guided_prompts_update_ai_binding_fields",
-      String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "") === "gemini"
-        && String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "") === "guided-gemini-pro"
-        && String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_PERMISSION_MODE || "") === "workspace_write"
-        && String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_REASONING_EFFORT || "") === "medium",
-      `client=${String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")} model=${String(guidedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "")}`,
+      String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "") === "gemini"
+        && String(guidedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "") === "guided-gemini-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 || "")}`,
     );
 
     await runCLI({
@@ -350,7 +415,7 @@ export async function runSelftestBotCommands(push, deps) {
       args: [
         "bot", "edit",
         "--provider", "telegram",
-        "--bot-key", "main_test",
+        "--bot-key", "monitorselftestbot",
         "--non-interactive", "true",
         "--token", "selftest-edited-token",
         "--client", "claude",
@@ -363,12 +428,12 @@ export async function runSelftestBotCommands(push, deps) {
     const editedState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
       "bot_edit_updates_ai_binding_fields",
-      String(editedState.TELEGRAM_BOT_MAIN_TEST_TOKEN || "") === "selftest-edited-token"
-        && String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "") === "claude"
-        && String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "") === "claude-3.7-sonnet"
-        && String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_PERMISSION_MODE || "") === "workspace_write"
-        && String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_REASONING_EFFORT || "") === "medium",
-      `client=${String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_CLIENT || "")} model=${String(editedState.TELEGRAM_BOT_MAIN_TEST_AI_MODEL || "")}`,
+      String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_TOKEN || "") === "selftest-edited-token"
+        && String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_CLIENT || "") === "claude"
+        && String(editedState.TELEGRAM_BOT_MONITORSELFTESTBOT_AI_MODEL || "") === "claude-3.7-sonnet"
+        && 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 || "")}`,
     );
 
     await runCLI({
@@ -378,7 +443,7 @@ export async function runSelftestBotCommands(push, deps) {
         ...env,
         METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
           "1", // provider: telegram
-          "1", // bot entry: main_test
+          "1", // bot entry: @monitorselftestbot
           "1", // confirm set default
         ]),
       },
@@ -386,7 +451,7 @@ export async function runSelftestBotCommands(push, deps) {
     const guidedDefaultState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
       "bot_set_default_guided_selects_entry",
-      String(guidedDefaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "main_test",
+      String(guidedDefaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
       `default=${String(guidedDefaultState.TELEGRAM_DEFAULT_BOT_KEY || "")}`,
     );
 
@@ -401,7 +466,7 @@ export async function runSelftestBotCommands(push, deps) {
         ...env,
         METHEUS_SCRIPTED_PROMPT_ANSWERS: JSON.stringify([
           "1", // provider: telegram
-          "1", // bot entry: main_test
+          "1", // bot entry: @monitorselftestbot
           "2", // output format: json
         ]),
       },
@@ -420,7 +485,7 @@ export async function runSelftestBotCommands(push, deps) {
       args: [
         "bot", "set-default",
         "--provider", "telegram",
-        "--bot-key", "main_test",
+        "--bot-key", "monitorselftestbot",
         "--non-interactive", "true",
       ],
       env,
@@ -428,7 +493,7 @@ export async function runSelftestBotCommands(push, deps) {
     const defaultState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
       "bot_set_default_updates_default_bot_key",
-      String(defaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "main_test",
+      String(defaultState.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
       `default=${String(defaultState.TELEGRAM_DEFAULT_BOT_KEY || "")}`,
     );
 
@@ -437,7 +502,7 @@ export async function runSelftestBotCommands(push, deps) {
       args: [
         "bot", "verify",
         "--provider", "telegram",
-        "--bot-key", "main_test",
+        "--bot-key", "monitorselftestbot",
         "--base-url", baseURL,
         "--timeout-seconds", "5",
         "--json", "true",
@@ -458,7 +523,7 @@ export async function runSelftestBotCommands(push, deps) {
       args: [
         "bot", "remove",
         "--provider", "telegram",
-        "--bot-key", "main_test",
+        "--bot-key", "monitorselftestbot",
         "--non-interactive", "true",
       ],
       env,
@@ -476,7 +541,7 @@ export async function runSelftestBotCommands(push, deps) {
     const telegramEntry = safeObject(listPayload[0]);
     push(
       "bot_remove_deletes_named_telegram_entry",
-      ensureArray(telegramEntry.entries).length === 0,
+      !ensureArray(telegramEntry.entries).some((entry) => String(safeObject(entry).key || "") === "monitorselftestbot"),
       `entries=${String(ensureArray(telegramEntry.entries).length)}`,
     );
 
@@ -488,11 +553,8 @@ export async function runSelftestBotCommands(push, deps) {
         "--non-interactive", "true",
         "--base-url", baseURL,
         "--timeout-seconds", "5",
-        "--bot-key", "explicit_test",
         "--server-bot-id", mock.bots[0].id,
-        "--username", "MonitorSelftestBot",
         "--token", "selftest-main-token",
-        "--role-profile", "monitor",
         "--ai-client", "codex",
         "--ai-model", "gpt-5-codex",
         "--ai-permission-mode", "read_only",
@@ -504,12 +566,13 @@ export async function runSelftestBotCommands(push, deps) {
     const aliasAddState = parseSimpleEnvText(fs.readFileSync(telegramEnvPath, "utf8"));
     push(
       "bot_add_accepts_ai_prefixed_option_aliases",
-      String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_SERVER_BOT_ID || "") === mock.bots[0].id
-        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_CLIENT || "") === "codex"
-        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_MODEL || "") === "gpt-5-codex"
-        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_PERMISSION_MODE || "") === "read_only"
-        && String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_REASONING_EFFORT || "") === "low",
-      `client=${String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_CLIENT || "")} model=${String(aliasAddState.TELEGRAM_BOT_EXPLICIT_TEST_AI_MODEL || "")}`,
+      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-codex"
+        && 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 || "")}`,
     );
 
     const guidedRemoveBeforeList = await runCLI({
@@ -524,7 +587,7 @@ export async function runSelftestBotCommands(push, deps) {
     const guidedRemoveBeforePayload = ensureArray(readJSON(guidedRemoveBeforeList.stdout));
     const guidedRemoveBeforeEntry = safeObject(guidedRemoveBeforePayload[0]);
     const guidedRemoveEntries = ensureArray(guidedRemoveBeforeEntry.entries);
-    const explicitEntryIndex = guidedRemoveEntries.findIndex((entry) => String(safeObject(entry).key || "") === "explicit_test");
+    const explicitEntryIndex = guidedRemoveEntries.findIndex((entry) => String(safeObject(entry).key || "") === "monitorselftestbot");
 
     await runCLI({
       cliPath,
@@ -552,7 +615,7 @@ export async function runSelftestBotCommands(push, deps) {
     push(
       "bot_remove_guided_deletes_selected_entry",
       explicitEntryIndex >= 0
-        && ensureArray(guidedRemoveEntry.entries).length === 0,
+        && !ensureArray(guidedRemoveEntry.entries).some((entry) => String(safeObject(entry).key || "") === "explicit_test"),
       `entries=${String(ensureArray(guidedRemoveEntry.entries).length)} selected=${String(explicitEntryIndex + 1)}`,
     );
 

package/package.json

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