metheus-governance-mcp-cli 0.2.113 → 0.2.114

package/README.md

@@ -388,11 +388,20 @@ Commands:
 
 ```bash
 metheus-governance-mcp-cli runner list
+metheus-governance-mcp-cli runner route add
+metheus-governance-mcp-cli runner route edit --route-name telegram-monitor
+metheus-governance-mcp-cli runner route remove --route-name telegram-monitor
 metheus-governance-mcp-cli runner show --route-name telegram-monitor
 metheus-governance-mcp-cli runner once --route-name telegram-monitor
 metheus-governance-mcp-cli runner start --route-name telegram-monitor
 ```
 
+Route management:
+- `runner route add` creates one executable route by selecting the project, provider, role, server bot, and project chat destination in order.
+- `runner route edit` updates one stored route. Use it when the destination, role, or server bot for an existing route changes.
+- `runner route remove` deletes one stored route from `~/.metheus/bot-runner.json`.
+- `runner list` and `runner route list` are equivalent. They show which routes are executable and how `--bot-name` would resolve.
+
 Recommended operational path:
 
 ```bash
@@ -405,6 +414,7 @@ What `runner list` means:
 - `server_bot_name_source=route_config` means the route file already stores the name directly
 - `server_bot_name_source=telegram_env_lookup` means the CLI resolved the name from the local Telegram bot file
 - `route_alias_by_server_bot_name` is a convenience selector, not a separate execution target
+- `run_once_by_server_bot_name` in `runner show` or docs means "find the one enabled route that matches this server bot name, then run that route"
 
 Debug/selection overrides:
 

package/cli.mjs

@@ -91,7 +91,15 @@ import {
   writeSelftestReport,
 } from "./lib/selftest-support.mjs";
 import { runSelftestBotCommands } from "./lib/selftest-bot-commands.mjs";
-import { runBotCommand } from "./lib/bot-commands.mjs";
+import {
+  createPrompter,
+  promptChoice,
+  promptConfirmChoice,
+  promptLine,
+  promptRequiredLine,
+  shouldRenderPromptChrome,
+  runBotCommand,
+} from "./lib/bot-commands.mjs";
 import { handleLocalBotMessageToolCall as handleLocalBotMessageToolCallImpl } from "./lib/local-tool-shims.mjs";
 import { handleLocalProjectToolDispatch as handleLocalProjectToolDispatchImpl } from "./lib/local-project-dispatch.mjs";
 import {
@@ -255,6 +263,10 @@ function printUsage() {
       `  ${cmd} selftest [--json <true|false>]`,
       `  ${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 route list [--json <true|false>]`,
+      `  ${cmd} runner route add [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--bot-name <server_name> | --bot-id <uuid>] [--destination-label <label> | --destination-id <uuid>] [--poll-interval-ms <n>] [--enabled <true|false>]`,
+      `  ${cmd} runner route edit [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>]`,
+      `  ${cmd} runner route remove [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>]`,
       `  ${cmd} runner show [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--json <true|false>]`,
       `  ${cmd} runner once [--route-name <name> | --bot-name <server_name when one enabled route matches> | --bot-id <uuid when one enabled route matches>] [--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 when one enabled route matches> | --bot-id <uuid when one enabled route matches>] [--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>]`,
@@ -2661,6 +2673,595 @@ function buildRunnerRouteListRows() {
   });
 }
 
+function slugifyRunnerRouteSegment(rawValue) {
+  return String(rawValue || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function buildRunnerRouteNameSuggestion({ provider = "", role = "", botName = "" }, existingNames = []) {
+  const segments = [
+    slugifyRunnerRouteSegment(provider),
+    slugifyRunnerRouteSegment(role),
+    slugifyRunnerRouteSegment(botName),
+  ].filter(Boolean);
+  const base = segments.join("-") || "runner-route";
+  const existing = new Set(ensureArray(existingNames).map((name) => String(name || "").trim().toLowerCase()).filter(Boolean));
+  if (!existing.has(base)) {
+    return base;
+  }
+  let suffix = 2;
+  while (existing.has(`${base}-${suffix}`)) {
+    suffix += 1;
+  }
+  return `${base}-${suffix}`;
+}
+
+function upsertRunnerRouteConfig(config, route) {
+  const normalizedConfig = safeObject(config);
+  const normalizedRoute = normalizeRunnerRoute(route);
+  const routeName = String(normalizedRoute.name || "").trim();
+  if (!routeName) {
+    throw new Error("route name is required");
+  }
+  const routes = ensureArray(normalizedConfig.routes).map((item) => normalizeRunnerRoute(item));
+  const index = routes.findIndex((item) => String(item.name || "").trim().toLowerCase() === routeName.toLowerCase());
+  if (index >= 0) {
+    routes[index] = normalizedRoute;
+  } else {
+    routes.push(normalizedRoute);
+  }
+  return {
+    ...normalizedConfig,
+    routes,
+  };
+}
+
+function removeRunnerRouteFromConfig(config, routeName) {
+  const normalizedConfig = safeObject(config);
+  const target = String(routeName || "").trim().toLowerCase();
+  return {
+    ...normalizedConfig,
+    routes: ensureArray(normalizedConfig.routes)
+      .map((route) => normalizeRunnerRoute(route))
+      .filter((route) => String(route.name || "").trim().toLowerCase() !== target),
+  };
+}
+
+function formatRunnerRouteChoiceLabel(route, telegramEntries = []) {
+  const normalizedRoute = normalizeRunnerRoute(route);
+  const resolvedName = resolveConfiguredRunnerRouteServerBotName(normalizedRoute, telegramEntries);
+  const routeName = normalizedRoute.name || runnerRouteKey(normalizedRoute);
+  const role = normalizedRoute.role || "-";
+  const botName = resolvedName || normalizedRoute.botName || normalizedRoute.botID || "-";
+  const destination = normalizedRoute.destinationLabel || normalizedRoute.destinationID || "-";
+  return `${routeName}${normalizedRoute.enabled ? "" : " [disabled]"} - ${normalizedRoute.provider || "-"} | ${role} | ${botName} | ${destination}`;
+}
+
+async function selectRunnerManagementRoute(ui, flags, { title = "Select runner route" } = {}) {
+  const config = loadBotRunnerConfig({ persistIfNeeded: true });
+  const routes = ensureArray(config.routes).map((route) => normalizeRunnerRoute(route));
+  if (!routes.length) {
+    throw new Error(`No runner route is configured in ${config.filePath}.`);
+  }
+  const selectionFilters = {
+    "route-name": flags["route-name"],
+    "bot-name": flags["bot-name"],
+    "bot-id": flags["bot-id"],
+  };
+  const filtered = routes.filter((route) => {
+    if (selectionFilters["route-name"] && !matchesRunnerRouteText(route.name, selectionFilters["route-name"])) return false;
+    const candidateBotName = resolveConfiguredRunnerRouteServerBotName(route, ensureArray(readTelegramEnvState().entries));
+    if (selectionFilters["bot-name"] && !matchesRunnerRouteText(candidateBotName, selectionFilters["bot-name"])) return false;
+    if (selectionFilters["bot-id"] && String(route.botID || "").trim() !== String(selectionFilters["bot-id"] || "").trim()) return false;
+    return true;
+  });
+  if (filtered.length === 1) {
+    return {
+      route: filtered[0],
+      config,
+    };
+  }
+  if (filtered.length > 1) {
+    const matches = filtered.map((route) => route.name || runnerRouteKey(route)).join(", ");
+    throw new Error(`Multiple runner routes matched the provided selectors. Narrow with --route-name. Matches: ${matches}`);
+  }
+  const telegramEntries = ensureArray(readTelegramEnvState().entries);
+  const selected = await promptChoice(
+    ui,
+    title,
+    routes.map((route) => ({
+      value: route.name || runnerRouteKey(route),
+      label: route.name || runnerRouteKey(route),
+      description: formatRunnerRouteChoiceLabel(route, telegramEntries).replace(/^[^-]+ - /, ""),
+    })),
+    { defaultIndex: 0 },
+  );
+  const selectedName = String(selected?.value || "").trim().toLowerCase();
+  const matchedRoute = routes.find((route) => String(route.name || runnerRouteKey(route)).trim().toLowerCase() === selectedName);
+  if (!matchedRoute) {
+    throw new Error("selected runner route was not found");
+  }
+  return {
+    route: matchedRoute,
+    config,
+  };
+}
+
+async function selectRunnerRouteProvider(ui, flags, currentProvider = "") {
+  const flagged = normalizeBotProvider(flags.provider || "");
+  if (flagged) {
+    return flagged;
+  }
+  if (currentProvider) {
+    return currentProvider;
+  }
+  const options = PROVIDER_ENV_ORDER.map((provider) => ({
+    value: provider,
+    label: providerEnvConfig(provider).label,
+    description: summarizeProviderSupport(provider),
+  }));
+  const selected = await promptChoice(ui, "Select runner route provider", options, { defaultIndex: 0 });
+  return normalizeBotProvider(selected?.value || "telegram") || "telegram";
+}
+
+async function resolveRunnerRouteProjectID(ui, flags, config, currentProjectID = "") {
+  const flagged = String(flags["project-id"] || "").trim();
+  if (flagged) {
+    if (!isUUID(flagged)) {
+      throw new Error("project_id must be a valid UUID");
+    }
+    return flagged;
+  }
+  if (currentProjectID && isUUID(currentProjectID)) {
+    return currentProjectID;
+  }
+  const projectMappings = safeObject(config.projectMappings);
+  const options = Object.entries(projectMappings)
+    .filter(([projectID]) => isUUID(projectID))
+    .map(([projectID, rawMapping]) => ({
+      value: projectID,
+      label: projectID,
+      description: String(safeObject(rawMapping).workspaceDir || "").trim() || "-",
+    }));
+  if (options.length === 1) {
+    return options[0].value;
+  }
+  if (options.length > 1) {
+    const selected = await promptChoice(ui, "Select runner route project", options, { defaultIndex: 0 });
+    return String(selected?.value || "").trim();
+  }
+  while (true) {
+    const projectID = String(await promptRequiredLine(ui, "Project UUID", "") || "").trim();
+    if (isUUID(projectID)) return projectID;
+    process.stdout.write("Project UUID must be valid.\n");
+  }
+}
+
+async function selectRunnerRole(ui, flags, currentRole = "") {
+  const flagged = normalizeBotRole(flags.role || "");
+  if (flagged) {
+    return flagged;
+  }
+  const roleOptions = ["monitor", "review", "worker", "approval"].map((role) => ({
+    value: role,
+    label: role,
+    description: role === "monitor"
+      ? "inbound triage and monitoring"
+      : role === "review"
+        ? "review and analysis"
+        : role === "worker"
+          ? "workspace execution"
+          : "final approval actions",
+  }));
+  const defaultIndex = Math.max(0, roleOptions.findIndex((item) => item.value === currentRole));
+  const selected = await promptChoice(ui, "Select runner route role", roleOptions, { defaultIndex });
+  return normalizeBotRole(selected?.value || currentRole) || "monitor";
+}
+
+async function resolveRunnerCommandToken(baseURL, timeoutSeconds) {
+  const resolved = await resolveAccessTokenForCommand(baseURL || DEFAULT_SITE_URL, timeoutSeconds);
+  if (!resolved.token) {
+    throw new Error("auth token missing; run auth login first");
+  }
+  return {
+    siteBaseURL: normalizeSiteBaseURL(baseURL || DEFAULT_SITE_URL),
+    token: resolved.token,
+  };
+}
+
+async function selectRunnerServerBotProfile(ui, { provider, role, flags, currentBotID = "", currentBotName = "" }) {
+  const flaggedBotID = String(flags["bot-id"] || "").trim();
+  const flaggedBotName = String(flags["bot-name"] || "").trim();
+  const timeoutSeconds = intFromRaw(flags["timeout-seconds"], 15) || 15;
+  const { siteBaseURL, token } = await resolveRunnerCommandToken(flags["base-url"], timeoutSeconds);
+  const bots = await listUserBotsForRunner({
+    siteBaseURL,
+    token,
+    timeoutSeconds,
+  });
+  const candidates = ensureArray(bots)
+    .filter((bot) => bot.isActive && bot.provider === provider && bot.role === role);
+  if (!candidates.length) {
+    throw new Error(`No active ${providerEnvConfig(provider).label} server bot exists for role "${role}".`);
+  }
+  const resolveChoice = (bot) => ({
+    name: String(bot.name || "").trim(),
+    id: String(bot.id || "").trim(),
+  });
+  if (flaggedBotID) {
+    const matched = candidates.find((bot) => bot.id === flaggedBotID);
+    if (!matched) {
+      throw new Error(`No active ${providerEnvConfig(provider).label} server bot matched bot-id ${flaggedBotID} for role "${role}".`);
+    }
+    return resolveChoice(matched);
+  }
+  if (flaggedBotName) {
+    const matchedByName = candidates.filter((bot) => matchesRunnerRouteText(bot.name, flaggedBotName));
+    if (matchedByName.length === 1) {
+      return resolveChoice(matchedByName[0]);
+    }
+    if (matchedByName.length > 1) {
+      throw new Error(`Multiple active ${providerEnvConfig(provider).label} server bots matched "${flaggedBotName}" for role "${role}". Use --bot-id instead.`);
+    }
+    throw new Error(`No active ${providerEnvConfig(provider).label} server bot matched "${flaggedBotName}" for role "${role}".`);
+  }
+  const currentIndex = Math.max(0, candidates.findIndex((bot) => (
+    (currentBotID && bot.id === currentBotID)
+    || (currentBotName && matchesRunnerRouteText(bot.name, currentBotName))
+  )));
+  if (candidates.length === 1) {
+    return resolveChoice(candidates[0]);
+  }
+  const selected = await promptChoice(
+    ui,
+    `Select server bot for role "${role}"`,
+    candidates.map((bot) => ({
+      value: bot.id,
+      label: String(bot.name || "").trim() || bot.id,
+      description: `server_bot_id:${bot.id}`,
+    })),
+    { defaultIndex: currentIndex },
+  );
+  const matched = candidates.find((bot) => bot.id === String(selected?.value || "").trim());
+  if (!matched) {
+    throw new Error("selected server bot was not found");
+  }
+  return resolveChoice(matched);
+}
+
+async function selectRunnerDestination(ui, { projectID, provider, flags, currentDestinationID = "", currentDestinationLabel = "" }) {
+  const timeoutSeconds = intFromRaw(flags["timeout-seconds"], 15) || 15;
+  const { siteBaseURL, token } = await resolveRunnerCommandToken(flags["base-url"], timeoutSeconds);
+  const destinations = await listProjectChatDestinations({
+    siteBaseURL,
+    projectID,
+    token,
+    timeoutSeconds,
+  });
+  const candidates = ensureArray(destinations)
+    .map((item) => normalizeChatDestination(item))
+    .filter((item) => item.isActive && item.provider === provider);
+  const flaggedID = String(flags["destination-id"] || "").trim();
+  const flaggedLabel = String(flags["destination-label"] || "").trim();
+  if (flaggedID) {
+    const matched = candidates.find((item) => item.id === flaggedID);
+    if (!matched) {
+      throw new Error(`No active ${providerEnvConfig(provider).label} destination matched destination-id ${flaggedID}.`);
+    }
+    return { id: matched.id, label: matched.label || matched.id };
+  }
+  if (flaggedLabel) {
+    const matchedByLabel = candidates.filter((item) => matchesRunnerRouteText(item.label, flaggedLabel));
+    if (matchedByLabel.length === 1) {
+      return { id: matchedByLabel[0].id, label: matchedByLabel[0].label || matchedByLabel[0].id };
+    }
+    if (matchedByLabel.length > 1) {
+      throw new Error(`Multiple active ${providerEnvConfig(provider).label} destinations matched "${flaggedLabel}". Use --destination-id instead.`);
+    }
+    throw new Error(`No active ${providerEnvConfig(provider).label} destination matched "${flaggedLabel}".`);
+  }
+  const currentIndex = Math.max(0, candidates.findIndex((item) => (
+    (currentDestinationID && item.id === currentDestinationID)
+    || (currentDestinationLabel && matchesRunnerRouteText(item.label, currentDestinationLabel))
+  )));
+  if (candidates.length === 1) {
+    return { id: candidates[0].id, label: candidates[0].label || candidates[0].id };
+  }
+  if (!candidates.length) {
+    throw new Error(`No active ${providerEnvConfig(provider).label} destination exists for project ${projectID}.`);
+  }
+  const selected = await promptChoice(
+    ui,
+    "Select project chat destination",
+    candidates.map((item) => ({
+      value: item.id,
+      label: item.label || item.id,
+      description: `chat_id:${item.chatID}`,
+    })),
+    { defaultIndex: currentIndex },
+  );
+  const matched = candidates.find((item) => item.id === String(selected?.value || "").trim());
+  if (!matched) {
+    throw new Error("selected destination was not found");
+  }
+  return { id: matched.id, label: matched.label || matched.id };
+}
+
+function buildRunnerRoutePayload({
+  currentRoute = null,
+  name = "",
+  enabled = true,
+  projectID = "",
+  provider = "",
+  role = "",
+  roleProfile = "",
+  serverBotName = "",
+  serverBotID = "",
+  destinationID = "",
+  destinationLabel = "",
+  pollIntervalMs = 5000,
+}) {
+  const triggerPolicy = currentRoute
+    ? safeObject(currentRoute.triggerPolicy)
+    : defaultRunnerTriggerPolicyForRole(roleProfile || role);
+  const archivePolicy = currentRoute
+    ? safeObject(currentRoute.archivePolicy)
+    : defaultRunnerArchivePolicyForRole(roleProfile || role);
+  return normalizeRunnerRoute({
+    ...(currentRoute ? serializeRunnerRoute(currentRoute) : {}),
+    name,
+    enabled,
+    project_id: projectID,
+    provider,
+    role,
+    role_profile: roleProfile,
+    server_bot_name: serverBotName,
+    server_bot_id: serverBotID,
+    destination_id: destinationID,
+    destination_label: destinationLabel,
+    trigger_policy: triggerPolicy,
+    archive_policy: archivePolicy,
+    poll_interval_ms: pollIntervalMs,
+  });
+}
+
+async function runRunnerRouteAdd(flags) {
+  const ui = createPrompter();
+  try {
+    if (shouldRenderPromptChrome(flags)) {
+      ui.setFlow("RUNNER ROUTE ADD", "Create one executable runner route from server bot and destination");
+    }
+    const config = loadBotRunnerConfig({ persistIfNeeded: true });
+    const provider = await selectRunnerRouteProvider(ui, flags, "");
+    const projectID = await resolveRunnerRouteProjectID(ui, flags, config);
+    const role = await selectRunnerRole(ui, flags, "");
+    const botSelection = await selectRunnerServerBotProfile(ui, { provider, role, flags });
+    const destination = await selectRunnerDestination(ui, {
+      projectID,
+      provider,
+      flags,
+    });
+    const suggestedName = buildRunnerRouteNameSuggestion({
+      provider,
+      role,
+      botName: botSelection.name,
+    }, ensureArray(config.routes).map((route) => normalizeRunnerRoute(route).name));
+    const routeName = String(flags.name || "").trim() || await promptRequiredLine(ui, "Runner route name", suggestedName);
+    const pollIntervalMs = intFromRaw(flags["poll-interval-ms"], 0) || intFromRaw(await promptLine(ui, "Poll interval (ms)", "5000"), 5000);
+    const enabled = !Object.prototype.hasOwnProperty.call(flags, "enabled")
+      ? true
+      : boolFromRaw(flags.enabled, true);
+    if (!Object.prototype.hasOwnProperty.call(flags, "enabled")) {
+      const enabledChoice = await promptChoice(
+        ui,
+        "Route enabled state",
+        [
+          { value: "enabled", label: "Enabled", description: "route will run immediately" },
+          { value: "disabled", label: "Disabled", description: "save the route but keep it inactive" },
+        ],
+        { defaultIndex: enabled ? 0 : 1 },
+      );
+      flags.enabled = enabledChoice?.value === "disabled" ? "false" : "true";
+    }
+    const nextRoute = buildRunnerRoutePayload({
+      name: routeName,
+      enabled: boolFromRaw(flags.enabled, true),
+      projectID,
+      provider,
+      role,
+      roleProfile: role,
+      serverBotName: botSelection.name,
+      serverBotID: botSelection.id,
+      destinationID: destination.id,
+      destinationLabel: destination.label,
+      pollIntervalMs,
+    });
+    const saved = upsertRunnerRouteConfig(config, nextRoute);
+    const filePath = saveBotRunnerConfig(saved, config.filePath);
+    process.stdout.write(`Saved runner route "${nextRoute.name}" to ${filePath}\n`);
+  } finally {
+    ui.close();
+  }
+}
+
+async function runRunnerRouteEdit(flags) {
+  const ui = createPrompter();
+  try {
+    if (shouldRenderPromptChrome(flags)) {
+      ui.setFlow("RUNNER ROUTE EDIT", "Update one executable runner route");
+    }
+    const selection = await selectRunnerManagementRoute(ui, flags, { title: "Select runner route to edit" });
+    const currentRoute = normalizeRunnerRoute(selection.route);
+    const config = selection.config;
+
+    const projectChange = await promptChoice(
+      ui,
+      "Project selection",
+      [
+        { value: "keep", label: "Keep current project", description: currentRoute.projectID || "-" },
+        { value: "change", label: "Change project", description: "select another mapped project or enter a UUID" },
+      ],
+      { defaultIndex: 0 },
+    );
+    const projectID = projectChange?.value === "change"
+      ? await resolveRunnerRouteProjectID(ui, {}, config)
+      : currentRoute.projectID;
+
+    const nameAction = await promptChoice(
+      ui,
+      "Runner route name",
+      [
+        { value: "keep", label: "Keep current value", description: currentRoute.name || runnerRouteKey(currentRoute) },
+        { value: "change", label: "Change value", description: "rename this route" },
+      ],
+      { defaultIndex: 0 },
+    );
+    const routeName = nameAction?.value === "change"
+      ? await promptRequiredLine(ui, "Runner route name", currentRoute.name || "")
+      : currentRoute.name;
+
+    const roleAction = await promptChoice(
+      ui,
+      "Runner role",
+      [
+        { value: "keep", label: "Keep current role", description: currentRoute.role || "-" },
+        { value: "change", label: "Change role", description: "select a different execution role" },
+      ],
+      { defaultIndex: 0 },
+    );
+    const role = roleAction?.value === "change"
+      ? await selectRunnerRole(ui, {}, currentRoute.role)
+      : currentRoute.role;
+
+    const botAction = await promptChoice(
+      ui,
+      "Server bot selection",
+      [
+        { value: "keep", label: "Keep current server bot", description: currentRoute.botName || currentRoute.botID || "-" },
+        { value: "change", label: "Change server bot", description: "pick the server bot that should own this route" },
+      ],
+      { defaultIndex: role !== currentRoute.role ? 1 : 0 },
+    );
+    const botSelection = botAction?.value === "change" || role !== currentRoute.role
+      ? await selectRunnerServerBotProfile(ui, {
+        provider: currentRoute.provider,
+        role,
+        flags: {},
+        currentBotID: currentRoute.botID,
+        currentBotName: currentRoute.botName,
+      })
+      : { name: currentRoute.botName, id: currentRoute.botID };
+
+    const destinationAction = await promptChoice(
+      ui,
+      "Project chat destination",
+      [
+        { value: "keep", label: "Keep current destination", description: currentRoute.destinationLabel || currentRoute.destinationID || "-" },
+        { value: "change", label: "Change destination", description: "select another active project destination" },
+      ],
+      { defaultIndex: projectID !== currentRoute.projectID ? 1 : 0 },
+    );
+    const destination = destinationAction?.value === "change" || projectID !== currentRoute.projectID
+      ? await selectRunnerDestination(ui, {
+        projectID,
+        provider: currentRoute.provider,
+        flags: {},
+        currentDestinationID: currentRoute.destinationID,
+        currentDestinationLabel: currentRoute.destinationLabel,
+      })
+      : { id: currentRoute.destinationID, label: currentRoute.destinationLabel };
+
+    const pollAction = await promptChoice(
+      ui,
+      "Poll interval (ms)",
+      [
+        { value: "keep", label: "Keep current value", description: String(currentRoute.pollIntervalMs || 5000) },
+        { value: "change", label: "Change value", description: "set a different poll interval" },
+      ],
+      { defaultIndex: 0 },
+    );
+    const pollIntervalMs = pollAction?.value === "change"
+      ? intFromRaw(await promptRequiredLine(ui, "Poll interval (ms)", String(currentRoute.pollIntervalMs || 5000)), currentRoute.pollIntervalMs || 5000)
+      : currentRoute.pollIntervalMs;
+
+    const enabledChoice = await promptChoice(
+      ui,
+      "Route enabled state",
+      [
+        { value: "keep", label: "Keep current state", description: currentRoute.enabled ? "enabled" : "disabled" },
+        { value: "enabled", label: "Enable route", description: "runner can execute this route" },
+        { value: "disabled", label: "Disable route", description: "keep it configured but inactive" },
+      ],
+      { defaultIndex: 0 },
+    );
+    const enabled = enabledChoice?.value === "enabled"
+      ? true
+      : enabledChoice?.value === "disabled"
+        ? false
+        : currentRoute.enabled;
+
+    const confirmed = await promptConfirmChoice(ui, "Save runner route changes now?", {
+      confirmDescription: "write the updated route to bot-runner.json",
+      cancelDescription: "leave the route unchanged",
+    });
+    if (!confirmed) {
+      process.stdout.write("Cancelled.\n");
+      return;
+    }
+    const nextRoute = buildRunnerRoutePayload({
+      currentRoute,
+      name: routeName,
+      enabled,
+      projectID,
+      provider: currentRoute.provider,
+      role,
+      roleProfile: role,
+      serverBotName: botSelection.name,
+      serverBotID: botSelection.id,
+      destinationID: destination.id,
+      destinationLabel: destination.label,
+      pollIntervalMs,
+    });
+    const nextConfig = {
+      ...config,
+      routes: ensureArray(config.routes)
+        .map((route) => normalizeRunnerRoute(route))
+        .filter((route) => String(route.name || "").trim().toLowerCase() !== String(currentRoute.name || "").trim().toLowerCase()),
+    };
+    const filePath = saveBotRunnerConfig(upsertRunnerRouteConfig(nextConfig, nextRoute), config.filePath);
+    process.stdout.write(`Updated runner route "${nextRoute.name}" in ${filePath}\n`);
+  } finally {
+    ui.close();
+  }
+}
+
+async function runRunnerRouteRemove(flags) {
+  const ui = createPrompter();
+  try {
+    if (shouldRenderPromptChrome(flags)) {
+      ui.setFlow("RUNNER ROUTE REMOVE", "Delete one executable runner route");
+    }
+    const selection = await selectRunnerManagementRoute(ui, flags, { title: "Select runner route to remove" });
+    const currentRoute = normalizeRunnerRoute(selection.route);
+    const confirmed = await promptConfirmChoice(ui, `Remove runner route "${currentRoute.name || runnerRouteKey(currentRoute)}"?`, {
+      confirmDescription: "delete the route from bot-runner.json",
+      cancelDescription: "keep the route unchanged",
+    });
+    if (!confirmed) {
+      process.stdout.write("Cancelled.\n");
+      return;
+    }
+    const nextConfig = removeRunnerRouteFromConfig(selection.config, currentRoute.name);
+    const filePath = saveBotRunnerConfig(nextConfig, selection.config.filePath);
+    process.stdout.write(`Removed runner route "${currentRoute.name}" from ${filePath}\n`);
+  } finally {
+    ui.close();
+  }
+}
+
 async function runRunnerList(flags) {
   const rows = buildRunnerRouteListRows();
   if (boolFromRaw(flags.json, false)) {
@@ -2875,6 +3476,31 @@ async function runRunnerStart(flags) {
 async function runRunner(argv) {
   const [subcommandRaw = "", ...rest] = argv;
   const subcommand = String(subcommandRaw || "").trim().toLowerCase();
+  if (subcommand === "route" || subcommand === "routes") {
+    const [routeSubcommandRaw = "", ...routeRest] = rest;
+    const routeSubcommand = String(routeSubcommandRaw || "").trim().toLowerCase();
+    const routeArgv = !routeSubcommand || routeSubcommand.startsWith("-")
+      ? [routeSubcommandRaw, ...routeRest].filter((value) => String(value || "").trim())
+      : routeRest;
+    const routeFlags = parseArgs(routeArgv);
+    if (!routeSubcommand || routeSubcommand === "list" || routeSubcommand.startsWith("-")) {
+      await runRunnerList(routeFlags);
+      return;
+    }
+    if (routeSubcommand === "add") {
+      await runRunnerRouteAdd(routeFlags);
+      return;
+    }
+    if (routeSubcommand === "edit") {
+      await runRunnerRouteEdit(routeFlags);
+      return;
+    }
+    if (routeSubcommand === "remove" || routeSubcommand === "rm" || routeSubcommand === "delete") {
+      await runRunnerRouteRemove(routeFlags);
+      return;
+    }
+    throw new Error("runner route requires a subcommand: list | add | edit | remove");
+  }
   const flags = parseArgs(rest);
   if (subcommand === "list") {
     await runRunnerList(flags);
@@ -2892,7 +3518,7 @@ async function runRunner(argv) {
     await runRunnerStart(flags);
     return;
   }
-  throw new Error("runner requires a subcommand: list | once | start");
+  throw new Error("runner requires a subcommand: list | show | once | start | route");
 }
 
 async function runLocalBotBridge(argv) {
@@ -5973,6 +6599,10 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     defaultLocalBotBridgeCommand,
     resolveRunnerExecutionPlan,
     normalizeRunnerRoute,
+    buildRunnerRouteNameSuggestion,
+    buildRunnerRoutePayload,
+    upsertRunnerRouteConfig,
+    removeRunnerRouteFromConfig,
     buildRunnerExecutionDeps,
     defaultBotRunnerRoleProfiles,
     resolveRunnerRoutes,

package/lib/bot-commands.mjs

@@ -201,7 +201,7 @@ function providerTokenKey(provider, deps) {
   return safeObject(requireDependency(deps, "providerEnvConfig")(provider)).tokenKey || "";
 }
 
-function shouldRenderPromptChrome(flags) {
+export function shouldRenderPromptChrome(flags) {
   const parsedFlags = safeObject(flags);
   if (boolFromRaw(parsedFlags["non-interactive"] ?? parsedFlags.yes, false)) return false;
   if (boolFromRaw(parsedFlags.json, false)) return false;
@@ -240,7 +240,7 @@ function printBotUsage(deps) {
   );
 }
 
-function createPrompter() {
+export function createPrompter() {
   let flowTitle = "";
   let flowSubtitle = "";
   let stepIndex = 0;
@@ -311,7 +311,7 @@ function createPrompter() {
   };
 }
 
-async function promptLine(ui, promptText, defaultValue = "") {
+export async function promptLine(ui, promptText, defaultValue = "") {
   ui.beginPrompt(promptText, [
     String(defaultValue || "").trim()
       ? `Press Enter to keep the current value: ${defaultValue}`
@@ -323,7 +323,7 @@ async function promptLine(ui, promptText, defaultValue = "") {
   return text || String(defaultValue || "").trim();
 }
 
-async function promptRequiredLine(ui, promptText, defaultValue = "") {
+export async function promptRequiredLine(ui, promptText, defaultValue = "") {
   while (true) {
     const answer = await promptLine(ui, promptText, defaultValue);
     if (answer) return answer;
@@ -331,7 +331,7 @@ async function promptRequiredLine(ui, promptText, defaultValue = "") {
   }
 }
 
-async function promptYesNo(ui, promptText, defaultValue = true) {
+export async function promptYesNo(ui, promptText, defaultValue = true) {
   ui.beginPrompt(promptText, ["Choose y or n, then press Enter."]);
   const hint = defaultValue ? "Y/n" : "y/N";
   while (true) {
@@ -343,7 +343,7 @@ async function promptYesNo(ui, promptText, defaultValue = true) {
   }
 }
 
-async function promptConfirmChoice(
+export async function promptConfirmChoice(
   ui,
   title,
   {
@@ -367,7 +367,7 @@ function formatChoiceLabel(option) {
   return `${String(option.label || option.value || "").trim()}${option.description ? ` - ${option.description}` : ""}`;
 }
 
-async function promptChoice(ui, title, options, { defaultIndex = 0, allowCancel = false } = {}) {
+export async function promptChoice(ui, title, options, { defaultIndex = 0, allowCancel = false } = {}) {
   const list = ensureArray(options).filter((item) => item && item.value !== undefined);
   if (!list.length) {
     throw new Error(`no options available for ${title}`);
@@ -399,7 +399,7 @@ async function promptChoice(ui, title, options, { defaultIndex = 0, allowCancel
   }
 }
 
-async function promptKeepChangeClear(ui, title, { allowClear = true, defaultValue = "keep" } = {}) {
+export async function promptKeepChangeClear(ui, title, { allowClear = true, defaultValue = "keep" } = {}) {
   const options = [
     { value: "keep", label: "Keep current value" },
     { value: "change", label: "Change value" },
@@ -2054,36 +2054,18 @@ async function maybePromptGroupedServerRoleProfiles(ui, serverBot, deps) {
     }
     return true;
   }
-  const remaining = new Set(roles);
-  while (remaining.size) {
-    const roleChoice = await promptChoice(
-      ui,
-      "Select role to edit",
-      [
-        ...Array.from(remaining).map((role) => ({
-          value: role,
-          label: role,
-          description: formatRoleProfileSummary(currentRoleProfileState(role, deps)),
-        })),
-        {
-          value: "__done__",
-          label: "Done",
-          description: "finish grouped role editing",
-        },
-      ],
-      { defaultIndex: 0 },
-    );
-    if (!roleChoice || roleChoice.value === "__done__") {
-      break;
-    }
+  const roleChoice = await promptChoice(
+    ui,
+    "Select role to edit",
+    roles.map((role) => ({
+      value: role,
+      label: role,
+      description: formatRoleProfileSummary(currentRoleProfileState(role, deps)),
+    })),
+    { defaultIndex: 0 },
+  );
+  if (roleChoice?.value) {
     await promptRoleExecutionProfile(ui, roleChoice.value, deps);
-    remaining.delete(roleChoice.value);
-    if (!remaining.size) {
-      break;
-    }
-    if (!await promptYesNo(ui, "Edit another role?", false)) {
-      break;
-    }
   }
   return true;
 }

package/lib/selftest-bot-commands.mjs

@@ -479,14 +479,6 @@ export async function runSelftestBotCommands(push, deps) {
             "2", // worker AI model: Sonnet 4.6r
             "4", // worker permission: danger_full_access
             "4", // worker reasoning: high
-            "y", // edit another role
-            "3", // select role to edit: approval
-            "2", // approval: edit settings
-            "4", // approval AI client: gemini
-            "2", // approval AI model: gemini-3.1-pro
-            "4", // approval permission: danger_full_access
-            "4", // approval reasoning: high
-            "n", // stop editing roles
             "1", // keep current default setting
             "y", // save
           ]),
@@ -501,13 +493,13 @@ export async function runSelftestBotCommands(push, deps) {
       const groupedRunnerConfig = readJSON(fs.readFileSync(groupedRunnerConfigPath, "utf8"));
       const groupedRoleProfiles = safeObject(groupedRunnerConfig.role_profiles || groupedRunnerConfig.roleProfiles);
       push(
-      "bot_edit_grouped_server_roles_updates_role_profiles",
+        "bot_edit_grouped_server_roles_updates_role_profiles",
         String(safeObject(safeObject(groupedRoleProfiles).worker).client || "") === "claude"
           && String(safeObject(safeObject(groupedRoleProfiles).worker).model || "") === "Sonnet 4.6r"
           && String(safeObject(safeObject(groupedRoleProfiles).worker).permission_mode || "") === "danger_full_access"
           && String(safeObject(safeObject(groupedRoleProfiles).worker).reasoning_effort || "") === "high"
-          && String(safeObject(safeObject(groupedRoleProfiles).approval).client || "") === "gemini"
-          && String(safeObject(safeObject(groupedRoleProfiles).approval).model || "") === "gemini-3.1-pro",
+          && String(safeObject(safeObject(groupedRoleProfiles).approval).client || "") === "claude"
+          && String(safeObject(safeObject(groupedRoleProfiles).approval).model || "") === "Sonnet 4.6r",
         `worker=${JSON.stringify(safeObject(safeObject(groupedRoleProfiles).worker))} approval=${JSON.stringify(safeObject(safeObject(groupedRoleProfiles).approval))}`,
       );
 
@@ -527,7 +519,7 @@ export async function runSelftestBotCommands(push, deps) {
         "bot_show_reports_grouped_server_roles",
         safeObject(groupedShowPayload.serverBinding).mode === "group"
           && safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).worker?.client === "claude"
-          && safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).approval?.client === "gemini"
+          && safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).approval?.client === "claude"
           && String(safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).monitor?.model || "") === "gpt-5.4",
         `mode=${String(safeObject(groupedShowPayload.serverBinding).mode || "")} worker=${String(safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).worker?.client || "")} approval=${String(safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).approval?.client || "")} monitor_model=${String(safeObject(safeObject(groupedShowPayload.serverBinding).effectiveRoleProfiles).monitor?.model || "")}`,
       );

package/lib/selftest-runner-scenarios.mjs

@@ -28,6 +28,10 @@ export async function runSelftestRunnerScenarios(push, deps) {
   const defaultLocalBotBridgeCommand = requireDependency(deps, "defaultLocalBotBridgeCommand");
   const resolveRunnerExecutionPlan = requireDependency(deps, "resolveRunnerExecutionPlan");
   const normalizeRunnerRoute = requireDependency(deps, "normalizeRunnerRoute");
+  const buildRunnerRouteNameSuggestion = requireDependency(deps, "buildRunnerRouteNameSuggestion");
+  const buildRunnerRoutePayload = requireDependency(deps, "buildRunnerRoutePayload");
+  const upsertRunnerRouteConfig = requireDependency(deps, "upsertRunnerRouteConfig");
+  const removeRunnerRouteFromConfig = requireDependency(deps, "removeRunnerRouteFromConfig");
   const buildRunnerExecutionDeps = requireDependency(deps, "buildRunnerExecutionDeps");
   const defaultBotRunnerRoleProfiles = requireDependency(deps, "defaultBotRunnerRoleProfiles");
   const resolveRunnerRoutes = requireDependency(deps, "resolveRunnerRoutes");
@@ -139,6 +143,51 @@ export async function runSelftestRunnerScenarios(push, deps) {
     `mapping=${String(migratedRunnerConfig.projectMappings?.[selftestProjectID]?.workspaceDir || "(none)")}`,
   );
 
+  const suggestedRouteName = buildRunnerRouteNameSuggestion(
+    { provider: "telegram", role: "monitor", botName: "Server Protocol Monitor Bot" },
+    ["telegram-monitor-server-protocol-monitor-bot"],
+  );
+  push(
+    "runner_route_name_suggestion_is_slugged_and_unique",
+    suggestedRouteName === "telegram-monitor-server-protocol-monitor-bot-2",
+    `suggested=${suggestedRouteName}`,
+  );
+
+  const routePayload = buildRunnerRoutePayload({
+    name: "telegram-monitor-server-protocol-monitor-bot",
+    enabled: true,
+    projectID: selftestProjectID,
+    provider: "telegram",
+    role: "monitor",
+    roleProfile: "monitor",
+    serverBotName: "Server Protocol Monitor Bot",
+    serverBotID: "11111111-2222-3333-4444-555555555555",
+    destinationID: "dest-1",
+    destinationLabel: "Main Room",
+    pollIntervalMs: 5000,
+  });
+  const routeConfigWithPayload = upsertRunnerRouteConfig(
+    normalizeBotRunnerConfigContents({ version: 2, routes: [] }, "selftest-runner-route-add.json"),
+    routePayload,
+  );
+  const savedRoute = (Array.isArray(routeConfigWithPayload.routes) ? routeConfigWithPayload.routes : [])
+    .map((route) => normalizeRunnerRoute(route))[0];
+  push(
+    "runner_route_payload_persists_server_identity_fields",
+    String(savedRoute.name || "") === "telegram-monitor-server-protocol-monitor-bot"
+      && String(savedRoute.botName || "") === "Server Protocol Monitor Bot"
+      && String(savedRoute.botID || "") === "11111111-2222-3333-4444-555555555555"
+      && String(savedRoute.destinationID || "") === "dest-1",
+    `name=${String(savedRoute.name || "")} bot_name=${String(savedRoute.botName || "")} bot_id=${String(savedRoute.botID || "")} destination_id=${String(savedRoute.destinationID || "")}`,
+  );
+
+  const routeConfigWithoutPayload = removeRunnerRouteFromConfig(routeConfigWithPayload, "telegram-monitor-server-protocol-monitor-bot");
+  push(
+    "runner_route_remove_drops_named_route",
+    (Array.isArray(routeConfigWithoutPayload.routes) ? routeConfigWithoutPayload.routes.length : 0) === 0,
+    `remaining=${Array.isArray(routeConfigWithoutPayload.routes) ? routeConfigWithoutPayload.routes.length : 0}`,
+  );
+
   const roleProfileOverrideConfig = normalizeBotRunnerConfigContents(
     {
       version: 2,

package/package.json

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