metheus-governance-mcp-cli 0.2.103 → 0.2.105

package/README.md

@@ -95,7 +95,7 @@ Runner template:
   },
   "role_profiles": {
     "monitor": {
-      "client": "codex",
+      "client": "gpt",
       "model": "",
       "permission_mode": "read_only",
       "reasoning_effort": "low"
@@ -106,7 +106,7 @@ Runner template:
       "bot_id": "<server_bot_uuid>",
       "bot_name": "<bot_name>",
       "role_profile": "monitor",
-      "client": "codex",
+      "client": "gpt",
       "model": "",
       "permission_mode": "read_only",
       "reasoning_effort": "low"
@@ -194,15 +194,18 @@ Fill provider bot secrets and provider-local transport options locally. Project
 Built-in helper command for legacy fallback/testing:
 
 ```bash
-metheus-governance-mcp-cli local-bot-bridge --client codex --no-update
+metheus-governance-mcp-cli local-bot-bridge --client gpt --no-update
 ```
 
 Supported `--client` values:
-- `codex`
+- `gpt`
 - `claude`
 - `gemini`
 - `sample`
 
+Compatibility note:
+- `codex` is still accepted as an alias for `gpt` because the GPT adapter runs through the Codex CLI binary.
+
 Use `sample` first for smoke tests before switching to a real AI client.
 
 Gemini CLI note:
@@ -280,7 +283,7 @@ Behavior:
 - Slack and KakaoTalk currently use a single local token entry per provider in this command flow.
 - `bot verify` checks the configured local token, cross-checks the server bot binding, prints the effective runtime role profile summary that the runner will use, and shows which local runner routes currently point at this bot entry.
 - `bot show` prints one local bot entry in detail, including grouped role summaries when one server bot name expands to multiple roles and any linked local runner routes.
-- In `bot show` and `bot verify`, `stored_*` fields come from the local env file and `live_server_*` fields come from the current server `me/bots` response.
+- In `bot show` and `bot verify`, `saved_local_file` means the values already stored on disk under `~/.metheus/telegram-bots/*.env`, while `current_server_protocol` means the fresh `/api/v1/me/bots` response from the server right now.
 - `bot global` edits Telegram-wide local settings such as API base URL, allowed updates, and default bot key.
 - `bot set-default` updates `TELEGRAM_DEFAULT_BOT_KEY`.
 - `bot migrate` moves legacy `TELEGRAM_BOT_TOKEN` into a named Telegram bot entry.
@@ -302,6 +305,8 @@ For direct Telegram adds, the CLI derives the local file name from the matched s
 
 For direct Telegram edits, prefer `--bot-name` or `--bot-id` because server bot identity is the source of truth. Use `--bot-key` only when you intentionally need the advanced local selector. If one server bot name expands to multiple roles such as `approval / worker / review / monitor`, prefer the guided `bot edit` flow so you can keep the current grouped settings, edit one role only, or walk every role in sequence instead of forcing one entry-level AI override.
 
+For runner commands, you can still use `--route-name` directly, but normal operator workflows can also use `--bot-name` or `--bot-id` when those identify one enabled route uniquely. Use `runner list` first if you are not sure which route belongs to which server bot.
+
 Current support status:
 
 - Telegram: full local bot entry management, token verification, bot-to-AI binding, inbound runner support
@@ -376,7 +381,7 @@ Execution model:
 - local runner stores workspace mapping and role profiles
 - runner resolves `project_id -> workspace_dir`
 - runner resolves server bot role to a local `role_profile`
-- runner executes the mapped client adapter (`codex` / `claude` / `gemini`)
+- runner executes the mapped client adapter (`gpt` / `claude` / `gemini`)
 - legacy `command` remains readable for migration, but execution is disabled by default unless `METHEUS_ALLOW_LEGACY_RUNNER_COMMAND=1`
 
 Commands:
@@ -419,7 +424,8 @@ Why `workspace_dir` matters:
 - without a valid project mapping, bots may answer with a generic local root instead of the real project workspace
 
 Role profile fields:
-- `client`: `codex`, `claude`, `gemini`, or `sample`
+- `client`: `gpt`, `claude`, `gemini`, or `sample`
+- `codex` is still accepted as a compatibility alias for `gpt`
 - `model`: optional CLI-specific model name
 - `permission_mode`: `read_only`, `workspace_write`, `danger_full_access`
 - `reasoning_effort`: `low`, `medium`, `high`

package/cli.mjs

@@ -185,7 +185,7 @@ const CTXPACK_PUSH_TOOL_NAMES = ["ctxpack.push", "ctxpack.update", "ctxpack.save
 const CLI_META = loadCLIMeta();
 const CLI_NAME = CLI_META.name || "metheus-governance-mcp-cli";
 const CLI_VERSION = CLI_META.version || "0.0.0";
-const DEFAULT_BOT_RUNNER_CLIENT = DEFAULT_LOCAL_AI_CLIENT;
+const DEFAULT_BOT_RUNNER_CLIENT = "gpt";
 const SELF_UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const SELF_UPDATE_TIMEOUT_SECONDS = 6;
 const SELF_UPDATE_ENV_KEY = "METHEUS_CLI_AUTO_UPDATE";
@@ -242,21 +242,21 @@ function printUsage() {
       `  ${cmd} setup [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--workspace-fallback-dir <path>] [--name <server_name>]`,
       `  ${cmd} bot setup [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot list [--provider <telegram|slack|kakaotalk>] [--json <true|false>]`,
-      `  ${cmd} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--json <true|false>]`,
+      `  ${cmd} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--json <true|false>]`,
       `  ${cmd} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>]`,
       `  ${cmd} bot remove [--provider <telegram|slack|kakaotalk>]`,
-      `  ${cmd} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>]`,
-      `  ${cmd} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>]`,
-      `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--timeout-seconds <n>] [--json <true|false>]`,
+      `  ${cmd} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>]`,
+      `  ${cmd} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>]`,
+      `  ${cmd} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--timeout-seconds <n>] [--json <true|false>]`,
       `  ${cmd} bot global --provider telegram [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <key>]`,
       `  ${cmd} doctor [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--timeout-seconds <n>] [--strict <true|false>]`,
       `  ${cmd} proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--include-drafts <true|false>] [--auto-pull-on-conflict <true|false>] [--timeout-seconds <n>]`,
       `  ${cmd} selftest [--json <true|false>]`,
-      `  ${cmd} local-bot-bridge [--client <codex|claude|gemini|sample>] [--cwd <path>] [--model <name>] [--permission-mode <read_only|workspace_write|danger_full_access>] [--reasoning-effort <low|medium|high>]`,
+      `  ${cmd} local-bot-bridge [--client <gpt|claude|gemini|sample>] [--cwd <path>] [--model <name>] [--permission-mode <read_only|workspace_write|danger_full_access>] [--reasoning-effort <low|medium|high>]`,
       `  ${cmd} runner list [--json <true|false>]`,
-      `  ${cmd} runner once [--route-name <name>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--bot-name <name>] [--bot-id <uuid>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--context-comments <n>] [--archive-replies <true|false>]`,
-      `  ${cmd} runner start [--route-name <name>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--bot-name <name>] [--bot-id <uuid>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--poll-interval-ms <n>] [--context-comments <n>] [--archive-replies <true|false>]`,
+      `  ${cmd} runner once [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--context-comments <n>] [--archive-replies <true|false>]`,
+      `  ${cmd} runner start [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--role-profile <name>] [--mentions-only <true|false>] [--reply-to-bot-messages <true|false>] [--direct-messages <true|false>] [--ignore-edited-messages <true|false>] [--dry-run-delivery <true|false>] [--poll-interval-ms <n>] [--context-comments <n>] [--archive-replies <true|false>]`,
       `  ${cmd} ctxpack pull [--project-id <uuid>] [--base-url <url>] [--workspace-dir <path|auto>] [--paths <csv>] [--timeout-seconds <n>]`,
       `  ${cmd} auth status`,
       `  ${cmd} auth login [--base-url <url>] [--flow <auto|device|callback|manual>] [--keycloak-url <url>] [--realm <name>] [--client-id <id>] [--open-browser <true|false>] [--callback-port <n>] [--timeout-seconds <n>] [--manual <true|false>]`,
@@ -832,7 +832,7 @@ function defaultLocalBotBridgeCommand(client = DEFAULT_BOT_RUNNER_CLIENT) {
 function defaultBotRunnerRoleProfiles() {
   return {
     monitor: {
-      client: "codex",
+      client: "gpt",
       model: "",
       permission_mode: "read_only",
       reasoning_effort: "low",
@@ -844,7 +844,7 @@ function defaultBotRunnerRoleProfiles() {
       reasoning_effort: "medium",
     },
     worker: {
-      client: "codex",
+      client: "gpt",
       model: "",
       permission_mode: "danger_full_access",
       reasoning_effort: "medium",
@@ -1243,6 +1243,7 @@ function normalizeBotRunnerConfigContents(parsed, filePath) {
   const defaults = defaultBotRunnerRoleProfiles();
   const rawRoleProfiles = safeObject(raw.role_profiles || raw.roleProfiles);
   const roleProfiles = {};
+  let migrated = rawVersion < BOT_RUNNER_CONFIG_VERSION;
   const roleProfileNames = new Set([
     ...Object.keys(defaults),
     ...Object.keys(rawRoleProfiles).map((name) => normalizeRunnerRoleProfileName(name)).filter(Boolean),
@@ -1253,6 +1254,10 @@ function normalizeBotRunnerConfigContents(parsed, filePath) {
       rawRoleProfiles[profileName],
       defaults[profileName] || {},
     );
+    const rawClient = String(safeObject(rawRoleProfiles[profileName]).client || safeObject(rawRoleProfiles[profileName]).cli || "").trim().toLowerCase();
+    if (rawClient === "codex") {
+      migrated = true;
+    }
   }
 
   const botBindings = {};
@@ -1262,6 +1267,10 @@ function normalizeBotRunnerConfigContents(parsed, filePath) {
     if (!binding.name || (!binding.botID && !binding.botName)) continue;
     if (!binding.roleProfile && !binding.client && !binding.model && !binding.permissionMode && !binding.reasoningEffort) continue;
     botBindings[binding.name] = binding;
+    const rawClient = String(safeObject(rawBinding).client || "").trim().toLowerCase();
+    if (rawClient === "codex") {
+      migrated = true;
+    }
   }
 
   const projectMappings = {};
@@ -1274,7 +1283,6 @@ function normalizeBotRunnerConfigContents(parsed, filePath) {
   }
 
   const routes = [];
-  let migrated = rawVersion < BOT_RUNNER_CONFIG_VERSION;
   for (const rawRoute of ensureArray(raw.routes)) {
     const routeSource = safeObject(rawRoute);
     const route = normalizeRunnerRoute(routeSource);
@@ -2568,15 +2576,32 @@ async function runRunnerOnce(flags) {
 
 function buildRunnerRouteListRows() {
   const config = loadBotRunnerConfig({ persistIfNeeded: true });
+  const telegramState = readTelegramEnvState();
+  const telegramEntries = ensureArray(telegramState.entries);
   return ensureArray(config.routes).map((rawRoute, index) => {
     const route = normalizeRunnerRoute(rawRoute);
+    const matchedTelegramEntry = route.provider === "telegram"
+      ? telegramEntries.find((entry) => {
+        const current = safeObject(entry);
+        return (
+          (route.botID && current.serverBotID && current.serverBotID === route.botID)
+          || (route.botName && current.serverBotName && current.serverBotName === route.botName)
+        );
+      })
+      : null;
+    const resolvedBotName = firstNonEmptyString([
+      route.botName,
+      matchedTelegramEntry?.serverBotName,
+      matchedTelegramEntry?.key,
+      "-",
+    ]);
     return {
       index: index + 1,
       name: route.name || runnerRouteKey(route),
       enabled: route.enabled !== false,
       provider: route.provider || "-",
       projectID: route.projectID || "-",
-      botName: route.botName || "-",
+      botName: resolvedBotName,
       botID: route.botID || "-",
       role: route.role || "-",
       roleProfile: route.roleProfile || "-",
@@ -2605,13 +2630,14 @@ async function runRunnerList(flags) {
         `  - ${row.name}${row.enabled ? "" : " [disabled]"}`,
         `    provider: ${row.provider}`,
         `    project_id: ${row.projectID}`,
-        `    bot_name: ${row.botName}`,
+        `    server_bot_name: ${row.botName}`,
         `    bot_id: ${row.botID}`,
         `    role: ${row.role}`,
         `    role_profile: ${row.roleProfile}`,
         `    destination_label: ${row.destinationLabel}`,
         `    poll_interval_ms: ${row.pollIntervalMs}`,
         `    run_once: ${CLI_NAME} runner once --route-name ${row.name}`,
+        row.botName ? `    run_once_by_bot_name: ${CLI_NAME} runner once --bot-name "${row.botName}"` : "",
       ].join("\n") + "\n",
     );
   });

package/lib/bot-commands.mjs

@@ -216,24 +216,25 @@ function printBotUsage(deps) {
       "",
       `  ${cliName} bot setup`,
       `  ${cliName} bot list [--provider <telegram|slack|kakaotalk>] [--json <true|false>]`,
-      `  ${cliName} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--json <true|false>]`,
-      `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--server-bot-id <uuid>] [--token <token>] [--default <true|false>] [--verify <true|false>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>] [--bot-key <advanced_key>] [--username <fallback_name>] [--role-profile <name>]`,
-      `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--username <fallback_name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>]`,
-      `  ${cliName} bot remove [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>]`,
-      `  ${cliName} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--non-interactive <true|false>]`,
-      `  ${cliName} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--keep-legacy-token <true|false>] [--non-interactive <true|false>]`,
-      `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--bot-key <advanced_key>] [--timeout-seconds <n>] [--json <true|false>]`,
+      `  ${cliName} bot show [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--json <true|false>]`,
+      `  ${cliName} bot add [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--server-bot-id <uuid>] [--token <token>] [--default <true|false>] [--verify <true|false>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>] [--username <fallback_name>] [--role-profile <name>]`,
+      `  ${cliName} bot edit [--provider <telegram|slack|kakaotalk>] [--base-url <url>] [--timeout-seconds <n>] [--non-interactive <true|false>] [--bot-name <server_name>] [--bot-id <uuid>] [--username <fallback_name>] [--token <token>] [--role-profile <name>] [--ai-client <name>] [--ai-model <name>] [--ai-permission-mode <mode>] [--ai-reasoning-effort <level>]`,
+      `  ${cliName} bot remove [--provider <telegram|slack|kakaotalk>] [--non-interactive <true|false>] [--bot-name <server_name>] [--bot-id <uuid>]`,
+      `  ${cliName} bot set-default --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--non-interactive <true|false>]`,
+      `  ${cliName} bot migrate --provider telegram [--bot-name <server_name>] [--bot-id <uuid>] [--keep-legacy-token <true|false>] [--non-interactive <true|false>]`,
+      `  ${cliName} bot verify [--provider <telegram|slack|kakaotalk>] [--bot-name <server_name>] [--bot-id <uuid>] [--timeout-seconds <n>] [--json <true|false>]`,
       `  ${cliName} bot global --provider telegram [--non-interactive <true|false>] [--api-base-url <url>] [--auto-clear-webhook <true|false>] [--allowed-updates <csv>] [--default-bot-key <advanced_key>]`,
       "",
       `Behavior:`,
       `  - bot setup asks for provider first, then shows a numbered action menu.`,
       `  - bot add without flags uses the shortest practical guided flow: provider -> token -> verify -> optional username fallback -> optional default bot.`,
       `  - in the normal Telegram path, bot add does not ask for a local bot key or a server role/profile choice.`,
-      `  - server bot name/UUID is the source of truth; --bot-key is an advanced local selector only.`,
-      `  - runner commands use route names. Use runner list first, then run runner once/start with --route-name.`,
+      `  - server bot name/UUID is the source of truth; --bot-key is an advanced compatibility selector only.`,
+      `  - runner commands can auto-select by --bot-name or --bot-id when one enabled route matches. Use runner list first if you are unsure.`,
       `  - bot edit without flags asks for provider, existing entry, then walks field-by-field in a numbered flow.`,
       `  - in the normal Telegram edit path, the CLI keeps or re-resolves the server bot binding automatically instead of asking you to pick a server role/profile UUID first.`,
       `  - bot set-default / bot verify / bot remove also support guided numbered selection when run without flags.`,
+      `  - advanced selectors: --bot-key is still supported for compatibility, but prefer --bot-name or --bot-id in normal operator workflows.`,
       "",
     ].join("\n"),
   );
@@ -812,7 +813,7 @@ function telegramEntryDisplayName(entry) {
 
 function displayLocalAIClientName(clientName) {
   const normalized = String(clientName || "").trim().toLowerCase();
-  if (normalized === "codex" || normalized === "gpt") return "GPT";
+  if (normalized === "gpt" || normalized === "codex") return "GPT";
   if (normalized === "claude") return "Claude";
   if (normalized === "gemini") return "Gemini";
   if (normalized === "sample") return "Sample";
@@ -1307,12 +1308,15 @@ function printBotList(provider, state, deps) {
     }
     process.stdout.write(`  default: ${String(state.parsed.TELEGRAM_DEFAULT_BOT_KEY || "").trim() || "-"}\n`);
     entries.forEach((entry) => {
+      const advancedSelectorLine = entry.key
+        ? `    advanced_local_selector: ${entry.key} (compatibility only)`
+        : "";
       process.stdout.write(
         [
           `  - ${telegramEntryDisplayName(entry)}${entry.isDefault ? " [default]" : ""}`,
           `    entry_file: ${resolveTelegramEntryFilePath(entry, deps) || "-"}`,
-          `    local_selector: ${entry.key || "-"}${entry.key ? " (advanced)" : ""}`,
           `    server_bot_id: ${entry.serverBotID || "-"}`,
+          `    server_name: ${entry.serverBotName || telegramEntryDisplayName(entry)}`,
           `    server_role_ids: ${formatTelegramServerRoleIDs(entry.serverRoleIDs) || "-"}`,
           `    fallback_username: ${entry.username ? `@${entry.username}` : "-"}`,
           `    token: ${entry.token ? maskSecret(entry.token) : "-"}`,
@@ -1321,6 +1325,7 @@ function printBotList(provider, state, deps) {
           `    model: ${entry.model || "-"}`,
           `    permission_mode: ${entry.permissionMode || "-"}`,
           `    reasoning_effort: ${entry.reasoningEffort || "-"}`,
+          advancedSelectorLine,
         ].join("\n") + "\n",
       );
     });
@@ -1341,42 +1346,43 @@ function printBotShow(provider, state, entry, deps, extras = {}) {
       `global_file: ${state.filePath}`,
       `entry_file: ${resolveTelegramEntryFilePath(selectedEntry, deps) || "-"}`,
       `server_name: ${telegramEntryDisplayName(selectedEntry)}`,
+      `comparison_help: saved_local_file = values stored on disk | current_server_protocol = fresh /api/v1/me/bots response`,
     ];
-    appendTextSection(lines, "stored_local_entry", [
-      `local_selector: ${selectedEntry.key || "-"}${selectedEntry.key ? " (advanced)" : ""}`,
-      `default: ${selectedEntry.isDefault ? "yes" : "no"}`,
-      `stored_server_bot_id: ${selectedEntry.serverBotID || "-"}`,
-      `stored_server_name: ${selectedEntry.serverBotName || "-"}`,
-      `stored_server_roles: ${ensureArray(selectedEntry.serverRoles).join(", ") || "-"}`,
-      `stored_server_role_ids: ${formatTelegramServerRoleIDs(selectedEntry.serverRoleIDs) || "-"}`,
-      `fallback_username: ${selectedEntry.username ? `@${selectedEntry.username}` : "-"}`,
+    appendTextSection(lines, "saved_local_file", [
+      `default_entry: ${selectedEntry.isDefault ? "yes" : "no"}`,
+      `server_bot_id_in_file: ${selectedEntry.serverBotID || "-"}`,
+      `server_name_in_file: ${selectedEntry.serverBotName || "-"}`,
+      `server_roles_in_file: ${ensureArray(selectedEntry.serverRoles).join(", ") || "-"}`,
+      `server_role_ids_in_file: ${formatTelegramServerRoleIDs(selectedEntry.serverRoleIDs) || "-"}`,
+      `fallback_username_in_file: ${selectedEntry.username ? `@${selectedEntry.username}` : "-"}`,
       `token: ${selectedEntry.token ? maskSecret(selectedEntry.token) : "(not configured)"}`,
       `role_profile: ${selectedEntry.roleProfile || "-"}`,
       `ai_client: ${selectedEntry.client ? displayLocalAIClientName(selectedEntry.client) : "-"}`,
       `ai_model: ${selectedEntry.model || "-"}`,
       `permission_mode: ${selectedEntry.permissionMode || "-"}`,
       `reasoning_effort: ${selectedEntry.reasoningEffort || "-"}`,
+      selectedEntry.key ? `advanced_local_selector: ${selectedEntry.key} (compatibility only)` : "",
     ]);
     if (Object.keys(serverBinding).length) {
       const liveLines = [
         `status: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}`,
         `binding_mode: ${serverBinding.mode || "-"}`,
-        `live_server_name: ${serverBinding.name || "-"}`,
-        `live_server_bot_id: ${serverBinding.serverBotID || selectedEntry.serverBotID || "-"}`,
+        `server_name_now: ${serverBinding.name || "-"}`,
+        `server_bot_id_now: ${serverBinding.serverBotID || selectedEntry.serverBotID || "-"}`,
       ];
       if (serverBinding.mode === "group") {
-        liveLines.push(`live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`);
-        liveLines.push(`live_server_role_ids: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`);
+        liveLines.push(`server_roles_now: ${ensureArray(serverBinding.roles).join(", ") || "-"}`);
+        liveLines.push(`server_role_ids_now: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`);
         const groupedProfiles = safeObject(serverBinding.effectiveRoleProfiles);
         Object.keys(groupedProfiles).forEach((role) => {
           liveLines.push(`runtime_role_profile[${role}]: ${formatRoleProfileOutputLine(groupedProfiles[role])}`);
         });
       } else if (serverBinding.effectiveRoleProfile) {
-        liveLines.push(`live_server_role: ${serverBinding.role || "-"}`);
-        liveLines.push(`live_server_role_ids: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`);
+        liveLines.push(`server_role_now: ${serverBinding.role || "-"}`);
+        liveLines.push(`server_role_ids_now: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`);
         liveLines.push(`runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}`);
       }
-      appendTextSection(lines, "live_server_binding", liveLines);
+      appendTextSection(lines, "current_server_protocol", liveLines);
     }
     const routeLines = [`count: ${intFromRaw(routeLinks.total, 0)}`];
     ensureArray(routeLinks.routes).forEach((route) => {
@@ -1752,7 +1758,7 @@ async function promptAIClient(ui, deps, defaultValue = "") {
 
 function suggestedAIModelsForClient(clientName) {
   const normalizedClient = String(clientName || "").trim().toLowerCase();
-  if (normalizedClient === "codex") {
+  if (normalizedClient === "gpt") {
     return [
       { value: "gpt-5.4", label: "gpt-5.4", description: "recommended GPT model" },
       { value: "gpt-5.3-codex", label: "gpt-5.3-codex", description: "stable GPT codex model" },
@@ -2254,9 +2260,9 @@ async function buildTelegramEntrySelectionRows(entries, flags, deps) {
       label = serverName;
     }
     const descriptionParts = [
-      current.key ? `local_selector:${current.key} (advanced)` : "",
       current.serverBotID ? `stored_server_bot_id:${current.serverBotID}` : "",
       current.client ? `ai_client:${displayLocalAIClientName(current.client)}` : "",
+      current.key ? `advanced_selector:${current.key}` : "",
     ].filter(Boolean);
     return {
       value: current.key,
@@ -2821,28 +2827,29 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
       `global_file: ${envConfig.filePath}`,
       provider === "telegram" ? `entry_file: ${resolveTelegramEntryFilePath(envConfig, deps) || "-"}` : "",
       `detail: ${result.detail || "-"}`,
+      provider === "telegram" ? `comparison_help: saved_local_file = values stored on disk | current_server_protocol = fresh /api/v1/me/bots response` : "",
     ];
     if (provider === "telegram") {
-      appendTextSection(lines, "stored_local_entry", [
-        `local_selector: ${envConfig.botKey || "-"}${envConfig.botKey ? " (advanced)" : ""}`,
-        `stored_server_bot_id: ${envConfig.serverBotID || "-"}`,
-        `stored_server_name: ${envConfig.serverBotName || "-"}`,
-        `stored_server_roles: ${ensureArray(envConfig.serverRoles).join(", ") || "-"}`,
-        `stored_server_role_ids: ${formatTelegramServerRoleIDs(envConfig.serverRoleIDs) || "-"}`,
+      appendTextSection(lines, "saved_local_file", [
+        `server_bot_id_in_file: ${envConfig.serverBotID || "-"}`,
+        `server_name_in_file: ${envConfig.serverBotName || "-"}`,
+        `server_roles_in_file: ${ensureArray(envConfig.serverRoles).join(", ") || "-"}`,
+        `server_role_ids_in_file: ${formatTelegramServerRoleIDs(envConfig.serverRoleIDs) || "-"}`,
         `role_profile: ${envConfig.roleProfile || "-"}`,
         `ai_client: ${envConfig.client ? displayLocalAIClientName(envConfig.client) : "-"}`,
         `ai_model: ${envConfig.model || "-"}`,
         `permission_mode: ${envConfig.permissionMode || "-"}`,
         `reasoning_effort: ${envConfig.reasoningEffort || "-"}`,
+        envConfig.botKey ? `advanced_local_selector: ${envConfig.botKey} (compatibility only)` : "",
       ]);
     }
     if (provider === "telegram" && serverBinding) {
       const liveLines = [
         `status: ${serverBinding.ok ? "OK" : "FAIL"}${serverBinding.detail ? ` (${serverBinding.detail})` : ""}`,
         `binding_mode: ${serverBinding.mode || "-"}`,
-        `live_server_name: ${serverBinding.name || "-"}`,
-        `live_server_roles: ${ensureArray(serverBinding.roles).join(", ") || "-"}`,
-        `live_server_role_ids: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`,
+        `server_name_now: ${serverBinding.name || "-"}`,
+        `server_roles_now: ${ensureArray(serverBinding.roles).join(", ") || "-"}`,
+        `server_role_ids_now: ${formatTelegramServerRoleIDs(serverBinding.serverRoleIDs) || "-"}`,
       ];
       if (serverBinding.mode === "group") {
         const groupedProfiles = safeObject(serverBinding.effectiveRoleProfiles);
@@ -2852,7 +2859,7 @@ async function verifyProviderEntry(ui, provider, flags, deps) {
       } else if (serverBinding.effectiveRoleProfile) {
         liveLines.push(`runtime_role_profile: ${formatRoleProfileOutputLine(serverBinding.effectiveRoleProfile)}`);
       }
-      appendTextSection(lines, "live_server_binding", liveLines);
+      appendTextSection(lines, "current_server_protocol", liveLines);
     }
     if (provider === "telegram" && routeLinks) {
       const routeSection = [`count: ${intFromRaw(routeLinks.total, 0)}`];

package/lib/local-ai-adapters.mjs

@@ -3,8 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-export const SUPPORTED_LOCAL_AI_CLIENTS = ["codex", "claude", "gemini", "sample"];
-export const DEFAULT_LOCAL_AI_CLIENT = "codex";
+export const SUPPORTED_LOCAL_AI_CLIENTS = ["gpt", "claude", "gemini", "sample"];
+export const DEFAULT_LOCAL_AI_CLIENT = "gpt";
 
 const SUPPORTED_PERMISSION_MODES = ["read_only", "workspace_write", "danger_full_access"];
 const SUPPORTED_REASONING_EFFORTS = ["low", "medium", "high"];
@@ -18,7 +18,7 @@ const GEMINI_HOME_SYNC_FILES = [
   "settings.json",
 ];
 const LOCAL_AI_MODEL_MAPPINGS = {
-  codex: [
+  gpt: [
     {
       display: "gpt-5.4",
       execution: "gpt-5.4",
@@ -589,8 +589,8 @@ function runSampleAdapter(payload) {
 
 export function normalizeLocalAIClientName(rawValue, fallback = DEFAULT_LOCAL_AI_CLIENT) {
   const value = String(rawValue || "").trim().toLowerCase();
-  if (["gpt", "openai-gpt", "openai"].includes(value)) {
-    return "codex";
+  if (["gpt", "openai-gpt", "openai", "codex"].includes(value)) {
+    return "gpt";
   }
   if (SUPPORTED_LOCAL_AI_CLIENTS.includes(value)) {
     return value;
@@ -734,7 +734,7 @@ export function runLocalAIClient({
     METHEUS_AI_RUNNER_REASONING_EFFORT: normalizedReasoningEffort,
     METHEUS_RUNNER_WORKSPACE_DIR: resolvedWorkspaceDir,
   };
-  if (normalizedClient === "codex") {
+  if (normalizedClient === "gpt") {
     return runCodexAdapter({
       promptText,
       workspaceDir: resolvedWorkspaceDir,

package/lib/selftest-bot-commands.mjs

@@ -236,20 +236,20 @@ export async function runSelftestBotCommands(push, deps) {
   try {
     push(
       "display_model_labels_map_to_tested_execution_ids",
-      resolveLocalAIExecutionModel("codex", "gpt-5.4") === "gpt-5.4"
-        && resolveLocalAIExecutionModel("codex", "gpt-5.3-codex") === "gpt-5.3-codex"
-        && resolveLocalAIExecutionModel("codex", "gpt-5.3-codex-spark") === "gpt-5.3-codex-spark"
-        && resolveLocalAIExecutionModel("codex", "GPT-5.4") === "gpt-5.4"
-        && resolveLocalAIExecutionModel("codex", "GPT-5.3-CODEX") === "gpt-5.3-codex"
-        && resolveLocalAIExecutionModel("codex", "GPT-5.3-CODEX-Spark") === "gpt-5.3-codex-spark"
+      resolveLocalAIExecutionModel("gpt", "gpt-5.4") === "gpt-5.4"
+        && resolveLocalAIExecutionModel("gpt", "gpt-5.3-codex") === "gpt-5.3-codex"
+        && resolveLocalAIExecutionModel("gpt", "gpt-5.3-codex-spark") === "gpt-5.3-codex-spark"
+        && resolveLocalAIExecutionModel("gpt", "GPT-5.4") === "gpt-5.4"
+        && resolveLocalAIExecutionModel("gpt", "GPT-5.3-CODEX") === "gpt-5.3-codex"
+        && resolveLocalAIExecutionModel("gpt", "GPT-5.3-CODEX-Spark") === "gpt-5.3-codex-spark"
         && resolveLocalAIExecutionModel("claude", "Sonnet 4.6r") === "sonnet"
         && resolveLocalAIExecutionModel("claude", "Haiku 4.5") === "haiku"
         && resolveLocalAIExecutionModel("claude", "Opus 4.6") === "opus"
         && resolveLocalAIExecutionModel("gemini", "gemini-3.1-pro") === "auto-gemini-3",
       [
-        `gpt54=${resolveLocalAIExecutionModel("codex", "gpt-5.4")}`,
-        `gpt53codex=${resolveLocalAIExecutionModel("codex", "gpt-5.3-codex")}`,
-        `spark=${resolveLocalAIExecutionModel("codex", "gpt-5.3-codex-spark")}`,
+        `gpt54=${resolveLocalAIExecutionModel("gpt", "gpt-5.4")}`,
+        `gpt53codex=${resolveLocalAIExecutionModel("gpt", "gpt-5.3-codex")}`,
+        `spark=${resolveLocalAIExecutionModel("gpt", "gpt-5.3-codex-spark")}`,
         `claude=${resolveLocalAIExecutionModel("claude", "Sonnet 4.6r")}`,
         `gemini=${resolveLocalAIExecutionModel("gemini", "gemini-3.1-pro")}`,
       ].join(" "),
@@ -257,11 +257,11 @@ export async function runSelftestBotCommands(push, deps) {
 
     push(
       "blank_model_defaults_to_first_display_model_for_each_client",
-      suggestLocalAIModelDisplayName("codex", "") === "gpt-5.4"
+      suggestLocalAIModelDisplayName("gpt", "") === "gpt-5.4"
         && suggestLocalAIModelDisplayName("claude", "") === "Sonnet 4.6r"
         && suggestLocalAIModelDisplayName("gemini", "") === "gemini-3.1-pro",
       [
-        `codex=${suggestLocalAIModelDisplayName("codex", "")}`,
+        `gpt=${suggestLocalAIModelDisplayName("gpt", "")}`,
         `claude=${suggestLocalAIModelDisplayName("claude", "")}`,
         `gemini=${suggestLocalAIModelDisplayName("gemini", "")}`,
       ].join(" "),
@@ -367,7 +367,7 @@ export async function runSelftestBotCommands(push, deps) {
         && String(addState.TELEGRAM_BOT_SERVER_ROLES || "") === "monitor"
         && String(addState.TELEGRAM_BOT_TOKEN || "") === "selftest-main-token"
         && String(addState.TELEGRAM_BOT_ROLE_PROFILE || "") === "monitor"
-        && String(addState.TELEGRAM_BOT_AI_CLIENT || "") === "codex"
+        && String(addState.TELEGRAM_BOT_AI_CLIENT || "") === "gpt"
         && String(addState.TELEGRAM_BOT_AI_PERMISSION_MODE || "") === "read_only"
         && String(addState.TELEGRAM_BOT_AI_REASONING_EFFORT || "") === "low"
         && String(addGlobals.TELEGRAM_DEFAULT_BOT_KEY || "") === "monitorselftestbot",
@@ -553,7 +553,7 @@ export async function runSelftestBotCommands(push, deps) {
     push(
       "bot_show_returns_selected_telegram_entry",
       safeObject(showPayload.entry).key === "monitorselftestbot"
-        && safeObject(showPayload.entry).client === "codex"
+        && safeObject(showPayload.entry).client === "gpt"
         && safeObject(showPayload.serverBinding).mode === "single",
       `key=${String(safeObject(showPayload.entry).key || "")} client=${String(safeObject(showPayload.entry).client || "")} mode=${String(safeObject(showPayload.serverBinding).mode || "")}`,
     );
@@ -773,7 +773,7 @@ export async function runSelftestBotCommands(push, deps) {
       String(aliasAddState.TELEGRAM_BOT_SERVER_BOT_ID || "") === mock.bots[0].id
         && String(aliasAddState.TELEGRAM_BOT_SERVER_NAME || "") === "MonitorSelftestBot"
         && String(aliasAddState.TELEGRAM_BOT_SERVER_ROLES || "") === "monitor"
-        && String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "") === "codex"
+        && String(aliasAddState.TELEGRAM_BOT_AI_CLIENT || "") === "gpt"
         && 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",

package/package.json

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

package/postinstall.mjs

@@ -75,7 +75,7 @@ function botRunnerTemplate() {
       },
       role_profiles: {
         monitor: {
-          client: "codex",
+          client: "gpt",
           model: "",
           permission_mode: "read_only",
           reasoning_effort: "low",
@@ -87,7 +87,7 @@ function botRunnerTemplate() {
           reasoning_effort: "medium",
         },
         worker: {
-          client: "codex",
+          client: "gpt",
           model: "",
           permission_mode: "danger_full_access",
           reasoning_effort: "medium",
@@ -104,7 +104,7 @@ function botRunnerTemplate() {
           bot_id: "<server_bot_uuid>",
           bot_name: "<bot_name>",
           role_profile: "monitor",
-          client: "codex",
+          client: "gpt",
           model: "",
           permission_mode: "read_only",
           reasoning_effort: "low",