metheus-governance-mcp-cli 0.2.60 → 0.2.61

package/README.md

@@ -190,6 +190,7 @@ Checks:
 - local bot runner v2 config validity
 - project workspace mapping presence
 - role profile -> local CLI availability
+- route dry-run / trigger-policy safety warnings
 - local provider token presence for active project destinations
 - codex/claude/gemini/antigravity/cursor registration state
 - gateway `tools/list` reachability
@@ -202,6 +203,7 @@ Direct bot posting:
 - it does not use a server-stored bot token
 - the destination identifier is resolved from the current project's saved Chat Destinations on the Metheus server
 - if multiple active destinations exist for the same provider, pass `destination_id` or `destination_label`
+- pass `dry_run_delivery=true` to preview the resolved bot/destination locally without sending the provider message
 - direct local delivery is implemented today for:
   - Telegram
   - Slack
@@ -239,6 +241,7 @@ Common flags:
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor
 metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --poll-interval-ms 5000
 metheus-governance-mcp-cli runner start --project-id <project_uuid> --provider telegram --role monitor --mentions-only true
+metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --dry-run-delivery true
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --role-profile review
 metheus-governance-mcp-cli runner once --project-id <project_uuid> --provider telegram --role monitor --command "python C:\\path\\to\\reply.py"
 ```
@@ -299,6 +302,9 @@ Notes:
 - `runner once` processes the most recent pending archived inbound message
 - `runner start` keeps polling and stores per-route cursor state in `~/.metheus/bot-runner-state.json`
 - first start primes the cursor to the latest inbound message and does not reply to old backlog
+- when inline filters match a configured route in `~/.metheus/bot-runner.json`, the runner reuses that route's canonical name/destination and state cursor instead of creating a new anonymous route key
+- stale anonymous route keys in `~/.metheus/bot-runner-state.json` are auto-migrated to the matching configured route when possible; `doctor` warns if ambiguous legacy keys still remain
+- `--dry-run-delivery true` resolves the real bot and destination but skips provider send and archive mirror writes
 - when `trigger_policy.mentions_only=true`, unmentioned group messages are archived but skipped for reply generation
 - mirrored bot replies are deduped by `chat_id + message_id`
 - provider bot messages are ignored during inbound import by default

package/cli.mjs

@@ -78,8 +78,8 @@ function printUsage() {
       `  ${cmd} proxy [--project-id <uuid>] [--ctxpack-key <key>] [--base-url <url>] [--workspace-dir <path|auto>] [--include-drafts <true|false>] [--auto-pull-on-conflict <true|false>] [--timeout-seconds <n>]`,
       `  ${cmd} selftest [--json <true|false>]`,
       `  ${cmd} local-bot-bridge [--client <codex|claude|gemini|sample>] [--cwd <path>] [--model <name>] [--permission-mode <read_only|workspace_write|danger_full_access>] [--reasoning-effort <low|medium|high>]`,
-      `  ${cmd} runner once [--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>] [--command <shell command>] [--context-comments <n>] [--archive-replies <true|false>]`,
-      `  ${cmd} runner start [--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>] [--command <shell command>] [--poll-interval-ms <n>] [--context-comments <n>] [--archive-replies <true|false>]`,
+      `  ${cmd} runner once [--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>] [--command <shell command>] [--context-comments <n>] [--archive-replies <true|false>]`,
+      `  ${cmd} runner start [--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>] [--command <shell command>] [--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>]`,
@@ -823,6 +823,7 @@ function botRunnerConfigTemplate() {
           dedupe_outbound: defaultArchivePolicy.dedupeOutbound,
           skip_bot_messages: defaultArchivePolicy.skipBotMessages,
         },
+        dry_run_delivery: false,
         poll_interval_ms: 5000,
         context_comments: 8,
         archive_replies: true,
@@ -848,6 +849,7 @@ function serializeRunnerRoute(route) {
     archive_work_item_id: normalized.archiveWorkItemID,
     trigger_policy: serializeRunnerTriggerPolicy(normalized.triggerPolicy),
     archive_policy: serializeRunnerArchivePolicy(normalized.archivePolicy),
+    ...(normalized.dryRunDelivery ? { dry_run_delivery: true } : {}),
     ...(normalized.workspaceDir ? { workspace_dir: normalized.workspaceDir } : {}),
     ...(normalized.command ? { command: normalized.command } : {}),
     poll_interval_ms: normalized.pollIntervalMs,
@@ -1060,17 +1062,239 @@ function rememberProjectWorkspaceMapping({ projectID, workspaceDir, source }) {
   };
 }
 
+function parseRunnerStateRouteKey(routeKey) {
+  const text = String(routeKey || "").trim();
+  if (!text) return null;
+  const parts = text.split("::");
+  if (parts.length < 6) return null;
+  return {
+    raw: text,
+    name: String(parts[0] || "").trim(),
+    projectID: String(parts[1] || "").trim(),
+    provider: normalizeBotProvider(parts[2]),
+    role: normalizeBotRole(parts[3]),
+    botSelector: String(parts[4] || "").trim(),
+    destinationSelector: parts.slice(5).join("::").trim(),
+  };
+}
+
+function runnerStateRouteKeyIsUnnamed(parsedKey) {
+  const routeKey = safeObject(parsedKey);
+  if (!routeKey.projectID || !routeKey.provider || !routeKey.role) {
+    return false;
+  }
+  return routeKey.name === "-";
+}
+
+function runnerStateRouteKeyLooksAnonymous(parsedKey) {
+  const routeKey = safeObject(parsedKey);
+  if (!runnerStateRouteKeyIsUnnamed(routeKey)) {
+    return false;
+  }
+  return routeKey.botSelector !== "-" || routeKey.destinationSelector !== "-";
+}
+
+function runnerStateSelectorMatchesRoute(selector, idValue, labelValue) {
+  const normalizedSelector = String(selector || "").trim();
+  if (!normalizedSelector || normalizedSelector === "-") {
+    return true;
+  }
+  if (normalizedSelector === String(idValue || "").trim()) {
+    return true;
+  }
+  return matchesRunnerRouteText(labelValue, normalizedSelector);
+}
+
+function findConfiguredRoutesForAnonymousStateKey(parsedKey, runnerConfig) {
+  const routeKey = safeObject(parsedKey);
+  const enabledRoutes = ensureArray(runnerConfig?.routes)
+    .map((route) => normalizeRunnerRoute(route))
+    .filter((route) => route.enabled);
+  return enabledRoutes.filter((route) => {
+    if (route.projectID !== routeKey.projectID) return false;
+    if (route.provider !== routeKey.provider) return false;
+    if (route.role !== routeKey.role) return false;
+    if (!runnerStateSelectorMatchesRoute(routeKey.botSelector, route.botID, route.botName)) {
+      return false;
+    }
+    if (!runnerStateSelectorMatchesRoute(routeKey.destinationSelector, route.destinationID, route.destinationLabel)) {
+      return false;
+    }
+    return true;
+  });
+}
+
+function configuredRunnerRouteKeys(runnerConfig) {
+  return new Set(
+    ensureArray(runnerConfig?.routes)
+      .map((route) => normalizeRunnerRoute(route))
+      .filter((route) => route.enabled)
+      .map((route) => runnerRouteKey(route)),
+  );
+}
+
+function runnerStateCursorRank(state) {
+  const record = safeObject(state);
+  const processedAt = Date.parse(String(record.last_processed_created_at || "").trim());
+  const updatedAt = Date.parse(String(record.updated_at || "").trim());
+  return {
+    processedAt: Number.isFinite(processedAt) ? processedAt : 0,
+    updatedAt: Number.isFinite(updatedAt) ? updatedAt : 0,
+    providerUpdateID: intFromRawAllowZero(record.last_provider_update_id, 0),
+  };
+}
+
+function prefersRunnerStateRecord(candidate, current) {
+  const candidateRank = runnerStateCursorRank(candidate);
+  const currentRank = runnerStateCursorRank(current);
+  if (candidateRank.processedAt !== currentRank.processedAt) {
+    return candidateRank.processedAt > currentRank.processedAt;
+  }
+  if (candidateRank.providerUpdateID !== currentRank.providerUpdateID) {
+    return candidateRank.providerUpdateID > currentRank.providerUpdateID;
+  }
+  if (candidateRank.updatedAt !== currentRank.updatedAt) {
+    return candidateRank.updatedAt > currentRank.updatedAt;
+  }
+  return false;
+}
+
+function mergeRunnerStateRecords(preferred, fallback) {
+  const primary = safeObject(preferred);
+  const secondary = safeObject(fallback);
+  const pickString = (...values) => firstNonEmptyString(values);
+  const pickNumber = (...values) => {
+    for (const value of values) {
+      if (value === 0 || value === "0") return 0;
+      const parsed = intFromRawAllowZero(value, Number.NaN);
+      if (Number.isFinite(parsed) && !Number.isNaN(parsed) && parsed > 0) {
+        return parsed;
+      }
+    }
+    return 0;
+  };
+  return {
+    last_processed_comment_id: pickString(primary.last_processed_comment_id, secondary.last_processed_comment_id),
+    last_processed_created_at: pickString(primary.last_processed_created_at, secondary.last_processed_created_at),
+    last_source_message_id: pickNumber(primary.last_source_message_id, secondary.last_source_message_id) || undefined,
+    last_source_kind: pickString(primary.last_source_kind, secondary.last_source_kind),
+    last_error: pickString(primary.last_error, secondary.last_error),
+    updated_at: pickString(primary.updated_at, secondary.updated_at, new Date().toISOString()),
+    last_action: pickString(primary.last_action, secondary.last_action),
+    last_reason: pickString(primary.last_reason, secondary.last_reason),
+    last_reply_message_id: pickNumber(primary.last_reply_message_id, secondary.last_reply_message_id) || undefined,
+    local_receive_mode: pickString(primary.local_receive_mode, secondary.local_receive_mode),
+    local_telegram_polling_ready: Boolean(primary.local_telegram_polling_ready || secondary.local_telegram_polling_ready),
+    local_telegram_webhook_cleared_url: pickString(primary.local_telegram_webhook_cleared_url, secondary.local_telegram_webhook_cleared_url),
+    local_telegram_webhook_cleared_at: pickString(primary.local_telegram_webhook_cleared_at, secondary.local_telegram_webhook_cleared_at),
+    last_provider_update_id: pickNumber(primary.last_provider_update_id, secondary.last_provider_update_id) || undefined,
+    last_local_poll_at: pickString(primary.last_local_poll_at, secondary.last_local_poll_at),
+  };
+}
+
+function cleanupRunnerStateRecord(record) {
+  const cleaned = {};
+  for (const [key, value] of Object.entries(safeObject(record))) {
+    if (value === undefined) continue;
+    cleaned[key] = value;
+  }
+  return cleaned;
+}
+
+function migrateBotRunnerStateRoutes(routes, runnerConfig) {
+  const currentRoutes = safeObject(routes);
+  const nextRoutes = { ...currentRoutes };
+  const migratedKeys = [];
+  const remainingAnonymousKeys = [];
+  let changed = false;
+  const configuredKeys = configuredRunnerRouteKeys(runnerConfig);
+
+  for (const [routeKey, routeState] of Object.entries(currentRoutes)) {
+    const parsedKey = parseRunnerStateRouteKey(routeKey);
+    if (!runnerStateRouteKeyLooksAnonymous(parsedKey)) {
+      continue;
+    }
+    const matches = findConfiguredRoutesForAnonymousStateKey(parsedKey, runnerConfig);
+    if (matches.length !== 1) {
+      remainingAnonymousKeys.push(routeKey);
+      continue;
+    }
+    const canonicalRoute = normalizeRunnerRoute(matches[0]);
+    const canonicalKey = runnerRouteKey(canonicalRoute);
+    if (!canonicalKey || canonicalKey === routeKey) {
+      continue;
+    }
+    const existingCanonicalState = safeObject(nextRoutes[canonicalKey]);
+    const sourceState = safeObject(routeState);
+    const preferredState = prefersRunnerStateRecord(sourceState, existingCanonicalState)
+      ? sourceState
+      : existingCanonicalState;
+    const fallbackState = preferredState === sourceState ? existingCanonicalState : sourceState;
+    nextRoutes[canonicalKey] = cleanupRunnerStateRecord(
+      mergeRunnerStateRecords(preferredState, fallbackState),
+    );
+    delete nextRoutes[routeKey];
+    migratedKeys.push({
+      from: routeKey,
+      to: canonicalKey,
+    });
+    changed = true;
+  }
+
+  for (const routeKey of Object.keys(nextRoutes)) {
+    const parsedKey = parseRunnerStateRouteKey(routeKey);
+    if (!runnerStateRouteKeyIsUnnamed(parsedKey)) {
+      continue;
+    }
+    if (configuredKeys.has(routeKey)) {
+      continue;
+    }
+    if (!remainingAnonymousKeys.includes(routeKey)) {
+      remainingAnonymousKeys.push(routeKey);
+    }
+  }
+
+  return {
+    routes: nextRoutes,
+    changed,
+    migratedKeys,
+    remainingAnonymousKeys,
+  };
+}
+
 function loadBotRunnerState() {
   const filePath = botRunnerStateFilePath();
   try {
     if (!fs.existsSync(filePath)) {
-      return { filePath, routes: {} };
+      return {
+        filePath,
+        routes: {},
+        migrated: false,
+        migratedKeys: [],
+        remainingAnonymousKeys: [],
+      };
     }
     const parsed = tryJsonParse(fs.readFileSync(filePath, "utf8"));
-    const routes = safeObject(parsed?.routes);
-    return { filePath, routes };
+    const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
+    const migratedState = migrateBotRunnerStateRoutes(safeObject(parsed?.routes), runnerConfig);
+    if (migratedState.changed) {
+      saveBotRunnerState({ routes: migratedState.routes });
+    }
+    return {
+      filePath,
+      routes: migratedState.routes,
+      migrated: migratedState.changed,
+      migratedKeys: migratedState.migratedKeys,
+      remainingAnonymousKeys: migratedState.remainingAnonymousKeys,
+    };
   } catch {
-    return { filePath, routes: {} };
+    return {
+      filePath,
+      routes: {},
+      migrated: false,
+      migratedKeys: [],
+      remainingAnonymousKeys: [],
+    };
   }
 }
 
@@ -1121,6 +1345,10 @@ function normalizeRunnerRoute(rawRoute, overrides = {}) {
   const workspaceDir = String(route.workspace_dir || route.workspaceDir || "").trim();
   const triggerPolicy = normalizeRunnerTriggerPolicy(route.trigger_policy || route.triggerPolicy, route);
   const archivePolicy = normalizeRunnerArchivePolicy(route.archive_policy || route.archivePolicy, route);
+  const dryRunDelivery = boolFromRaw(
+    route.dry_run_delivery ?? route.dryRunDelivery ?? process.env.METHEUS_BOT_DELIVERY_DRY_RUN,
+    false,
+  );
   return {
     name,
     enabled: boolFromRaw(route.enabled, true),
@@ -1136,6 +1364,7 @@ function normalizeRunnerRoute(rawRoute, overrides = {}) {
     archiveWorkItemID,
     triggerPolicy,
     archivePolicy,
+    dryRunDelivery,
     workspaceDir,
     command,
     pollIntervalMs: intFromRaw(route.poll_interval_ms || route.pollIntervalMs, 5000),
@@ -1195,6 +1424,161 @@ function validateRunnerRoute(route, { requireCommand = true, config = null } = {
   return errors;
 }
 
+function hasRunnerFlag(flags, flagName) {
+  return Object.prototype.hasOwnProperty.call(flags, flagName);
+}
+
+function matchesRunnerRouteText(candidate, expected) {
+  const expectedText = String(expected || "").trim();
+  if (!expectedText) {
+    return true;
+  }
+  return String(candidate || "").trim().toLowerCase() === expectedText.toLowerCase();
+}
+
+function configuredRunnerRouteMatchesInlineSelection(route, inlineRoute, flags) {
+  const candidate = normalizeRunnerRoute(route);
+  if (hasRunnerFlag(flags, "route-name") && !matchesRunnerRouteText(candidate.name, flags["route-name"])) {
+    return false;
+  }
+  if (inlineRoute.projectID && candidate.projectID !== inlineRoute.projectID) {
+    return false;
+  }
+  if (inlineRoute.provider && candidate.provider !== inlineRoute.provider) {
+    return false;
+  }
+  if (inlineRoute.role && candidate.role !== inlineRoute.role) {
+    return false;
+  }
+  if (hasRunnerFlag(flags, "role-profile") && candidate.roleProfile !== inlineRoute.roleProfile) {
+    return false;
+  }
+  if (inlineRoute.botID && candidate.botID !== inlineRoute.botID) {
+    return false;
+  }
+  if (inlineRoute.botName && !matchesRunnerRouteText(candidate.botName, inlineRoute.botName)) {
+    return false;
+  }
+  if (inlineRoute.destinationID && candidate.destinationID !== inlineRoute.destinationID) {
+    return false;
+  }
+  if (inlineRoute.destinationLabel && !matchesRunnerRouteText(candidate.destinationLabel, inlineRoute.destinationLabel)) {
+    return false;
+  }
+  if (inlineRoute.archiveThreadID && candidate.archiveThreadID !== inlineRoute.archiveThreadID) {
+    return false;
+  }
+  if (inlineRoute.archiveWorkItemID && candidate.archiveWorkItemID !== inlineRoute.archiveWorkItemID) {
+    return false;
+  }
+  return true;
+}
+
+function applyRunnerRouteFlagOverrides(route, flags) {
+  const merged = normalizeRunnerRoute(route);
+  if (hasRunnerFlag(flags, "route-name")) {
+    merged.name = String(flags["route-name"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "project-id")) {
+    merged.projectID = String(flags["project-id"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "provider")) {
+    merged.provider = normalizeBotProvider(flags.provider);
+  }
+  if (hasRunnerFlag(flags, "role")) {
+    merged.role = normalizeBotRole(flags.role);
+  }
+  if (hasRunnerFlag(flags, "role-profile")) {
+    merged.roleProfile = normalizeRunnerRoleProfileName(flags["role-profile"]);
+  }
+  if (hasRunnerFlag(flags, "bot-name")) {
+    merged.botName = String(flags["bot-name"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "bot-id")) {
+    merged.botID = String(flags["bot-id"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "destination-id")) {
+    merged.destinationID = String(flags["destination-id"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "destination-label")) {
+    merged.destinationLabel = String(flags["destination-label"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "archive-thread-id")) {
+    merged.archiveThreadID = String(flags["archive-thread-id"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "archive-work-item-id")) {
+    merged.archiveWorkItemID = String(flags["archive-work-item-id"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "workspace-dir")) {
+    merged.workspaceDir = String(flags["workspace-dir"] || "").trim();
+  }
+  if (hasRunnerFlag(flags, "command")) {
+    merged.command = String(flags.command || "").trim();
+  }
+  if (hasRunnerFlag(flags, "dry-run-delivery")) {
+    merged.dryRunDelivery = boolFromRaw(flags["dry-run-delivery"], merged.dryRunDelivery);
+  }
+  if (hasRunnerFlag(flags, "poll-interval-ms")) {
+    merged.pollIntervalMs = intFromRaw(flags["poll-interval-ms"], merged.pollIntervalMs);
+  }
+  if (hasRunnerFlag(flags, "context-comments")) {
+    merged.contextComments = intFromRaw(flags["context-comments"], merged.contextComments);
+  }
+  if (hasRunnerFlag(flags, "archive-replies")) {
+    const archiveReplies = boolFromRaw(flags["archive-replies"], merged.archiveReplies);
+    merged.archiveReplies = archiveReplies;
+    merged.archivePolicy = {
+      ...safeObject(merged.archivePolicy),
+      mirrorReplies: archiveReplies,
+    };
+  }
+  if (
+    hasRunnerFlag(flags, "mentions-only")
+    || hasRunnerFlag(flags, "direct-messages")
+    || hasRunnerFlag(flags, "reply-to-bot-messages")
+    || hasRunnerFlag(flags, "ignore-edited-messages")
+  ) {
+    merged.triggerPolicy = {
+      ...safeObject(merged.triggerPolicy),
+      ...(hasRunnerFlag(flags, "mentions-only")
+        ? { mentionsOnly: boolFromRaw(flags["mentions-only"], merged.triggerPolicy?.mentionsOnly) }
+        : {}),
+      ...(hasRunnerFlag(flags, "direct-messages")
+        ? { directMessages: boolFromRaw(flags["direct-messages"], merged.triggerPolicy?.directMessages) }
+        : {}),
+      ...(hasRunnerFlag(flags, "reply-to-bot-messages")
+        ? { replyToBotMessages: boolFromRaw(flags["reply-to-bot-messages"], merged.triggerPolicy?.replyToBotMessages) }
+        : {}),
+      ...(hasRunnerFlag(flags, "ignore-edited-messages")
+        ? { ignoreEditedMessages: boolFromRaw(flags["ignore-edited-messages"], merged.triggerPolicy?.ignoreEditedMessages) }
+        : {}),
+    };
+  }
+  if (
+    hasRunnerFlag(flags, "dedupe-inbound")
+    || hasRunnerFlag(flags, "dedupe-outbound")
+    || hasRunnerFlag(flags, "skip-bot-messages")
+    || hasRunnerFlag(flags, "archive-replies")
+  ) {
+    merged.archivePolicy = {
+      ...safeObject(merged.archivePolicy),
+      ...(hasRunnerFlag(flags, "archive-replies")
+        ? { mirrorReplies: boolFromRaw(flags["archive-replies"], merged.archivePolicy?.mirrorReplies) }
+        : {}),
+      ...(hasRunnerFlag(flags, "dedupe-inbound")
+        ? { dedupeInbound: boolFromRaw(flags["dedupe-inbound"], merged.archivePolicy?.dedupeInbound) }
+        : {}),
+      ...(hasRunnerFlag(flags, "dedupe-outbound")
+        ? { dedupeOutbound: boolFromRaw(flags["dedupe-outbound"], merged.archivePolicy?.dedupeOutbound) }
+        : {}),
+      ...(hasRunnerFlag(flags, "skip-bot-messages")
+        ? { skipBotMessages: boolFromRaw(flags["skip-bot-messages"], merged.archivePolicy?.skipBotMessages) }
+        : {}),
+    };
+  }
+  return merged;
+}
+
 function resolveRunnerRoutes(flags, mode) {
   const inlineRoute = normalizeRunnerRoute({
     name: flags["route-name"],
@@ -1221,45 +1605,76 @@ function resolveRunnerRoutes(flags, mode) {
       dedupe_outbound: flags["dedupe-outbound"],
       skip_bot_messages: flags["skip-bot-messages"],
     },
+    dry_run_delivery: flags["dry-run-delivery"],
     workspace_dir: flags["workspace-dir"],
     command: flags.command,
     poll_interval_ms: flags["poll-interval-ms"],
     context_comments: flags["context-comments"],
     archive_replies: flags["archive-replies"],
   });
-  const inlineRequested = Boolean(
-    inlineRoute.projectID
-    || inlineRoute.command
+  const selectionRequested = Boolean(
+    String(flags["route-name"] || "").trim()
+    || inlineRoute.projectID
     || inlineRoute.botID
     || inlineRoute.botName
-      || inlineRoute.roleProfile
-      || inlineRoute.destinationID
-      || inlineRoute.destinationLabel
-      || inlineRoute.archiveThreadID
-      || inlineRoute.archiveWorkItemID
-      || Object.prototype.hasOwnProperty.call(flags, "mentions-only")
-      || Object.prototype.hasOwnProperty.call(flags, "direct-messages")
-      || Object.prototype.hasOwnProperty.call(flags, "reply-to-bot-messages")
-      || Object.prototype.hasOwnProperty.call(flags, "ignore-edited-messages")
-      || Object.prototype.hasOwnProperty.call(flags, "dedupe-inbound")
-      || Object.prototype.hasOwnProperty.call(flags, "dedupe-outbound")
-      || Object.prototype.hasOwnProperty.call(flags, "skip-bot-messages")
-      || inlineRoute.workspaceDir
-      || flags.provider
-      || flags.role,
+    || inlineRoute.roleProfile
+    || inlineRoute.destinationID
+    || inlineRoute.destinationLabel
+    || inlineRoute.archiveThreadID
+    || inlineRoute.archiveWorkItemID
+    || flags.provider
+    || flags.role
+  );
+  const overrideRequested = Boolean(
+    inlineRoute.command
+    || inlineRoute.workspaceDir
+    || hasRunnerFlag(flags, "mentions-only")
+    || hasRunnerFlag(flags, "direct-messages")
+    || hasRunnerFlag(flags, "reply-to-bot-messages")
+    || hasRunnerFlag(flags, "ignore-edited-messages")
+    || hasRunnerFlag(flags, "dry-run-delivery")
+    || hasRunnerFlag(flags, "dedupe-inbound")
+    || hasRunnerFlag(flags, "dedupe-outbound")
+    || hasRunnerFlag(flags, "skip-bot-messages")
+    || hasRunnerFlag(flags, "archive-replies")
+    || hasRunnerFlag(flags, "poll-interval-ms")
+    || hasRunnerFlag(flags, "context-comments")
+  );
+  const inlineRequested = Boolean(
+    selectionRequested
+    || overrideRequested
+    || hasRunnerFlag(flags, "project-id")
+    || inlineRoute.projectID
   );
-  if (inlineRequested) {
-    return [inlineRoute];
-  }
 
   const config = loadBotRunnerConfig({ persistIfNeeded: true });
   const routeNameFilter = String(flags["route-name"] || "").trim().toLowerCase();
-  const routes = ensureArray(config.routes)
+  const configuredRoutes = ensureArray(config.routes)
     .map((rawRoute) => normalizeRunnerRoute(rawRoute))
     .filter((route) => route.enabled)
     .filter((route) => !routeNameFilter || String(route.name || "").trim().toLowerCase() === routeNameFilter);
-  if (routes.length > 0) {
-    return routes;
+
+  if (selectionRequested) {
+    const matchedRoutes = configuredRoutes.filter((route) => configuredRunnerRouteMatchesInlineSelection(route, inlineRoute, flags));
+    if (matchedRoutes.length === 1) {
+      return [applyRunnerRouteFlagOverrides(matchedRoutes[0], flags)];
+    }
+    if (matchedRoutes.length > 1) {
+      const matchList = matchedRoutes
+        .map((route) => route.name || runnerRouteKey(route))
+        .join(", ");
+      throw new Error(
+        `Multiple enabled runner routes matched the provided filters. Narrow with --route-name, --bot-name, or --destination-label. Matches: ${matchList}`,
+      );
+    }
+  }
+
+  if (inlineRequested) {
+    return [inlineRoute];
+  }
+
+  if (configuredRoutes.length > 0) {
+    return configuredRoutes;
   }
 
   const help = routeNameFilter
@@ -2474,6 +2889,7 @@ function buildRunnerInputPayload({
       workspace_dir: String(executionPlan?.workspaceDir || "").trim(),
       workspace_source: String(executionPlan?.workspaceSource || "").trim(),
       command_fallback: executionPlan?.usedCommandFallback === true,
+      dry_run_delivery: Boolean(route.dryRunDelivery),
     },
     trigger_policy: serializeRunnerTriggerPolicy(route.triggerPolicy),
     archive_policy: serializeRunnerArchivePolicy(route.archivePolicy),
@@ -2513,6 +2929,9 @@ function printRunnerResult(mode, result, jsonMode) {
   if (result.detail) {
     process.stdout.write(`  detail: ${result.detail}\n`);
   }
+  if (result.delivery?.dry_run) {
+    process.stdout.write("  dry_run_delivery: true\n");
+  }
   if (result.thread_id) {
     process.stdout.write(`  thread: ${result.thread_id}\n`);
   }
@@ -2692,13 +3111,17 @@ async function processRunnerRouteOnce(route, runtime, mode) {
       contextWindow,
       executionPlan,
     });
-    const typingHeartbeat = startRunnerTypingHeartbeat({
-      provider: normalizedRoute.provider,
-      destination,
-      timeoutSeconds: runtime.timeoutSeconds,
-      action: "typing",
-      intervalMs: 4000,
-    });
+    const typingHeartbeat = normalizedRoute.dryRunDelivery
+      ? {
+          async stop() {},
+        }
+      : startRunnerTypingHeartbeat({
+          provider: normalizedRoute.provider,
+          destination,
+          timeoutSeconds: runtime.timeoutSeconds,
+          action: "typing",
+          intervalMs: 4000,
+        });
     let aiResult;
     try {
       aiResult = await runRunnerAIExecution({
@@ -2752,6 +3175,7 @@ async function processRunnerRouteOnce(route, runtime, mode) {
       archiveDedupeOutbound: normalizedRoute.archivePolicy.dedupeOutbound,
       archiveThreadID: archiveThread.threadID,
       archiveWorkItemID: archiveThread.workItemID,
+      dryRun: normalizedRoute.dryRunDelivery,
     });
     saveRunnerRouteState(
       routeKey,
@@ -2766,8 +3190,8 @@ async function processRunnerRouteOnce(route, runtime, mode) {
     return {
       route_key: routeKey,
       route_name: normalizedRoute.name,
-      outcome: "replied",
-      detail: `replied as ${bot.name || bot.id}${executionPlan.usedCommandFallback ? " (legacy command fallback)" : ""}`,
+      outcome: deliveryResult.delivery.dryRun ? "dry_run" : "replied",
+      detail: `${deliveryResult.delivery.dryRun ? "dry-run prepared" : "replied"} as ${bot.name || bot.id}${executionPlan.usedCommandFallback ? " (legacy command fallback)" : ""}`,
       thread_id: archiveThread.threadID,
       comment_id: selectedRecord.id,
       execution_mode: executionPlan.mode,
@@ -4857,6 +5281,9 @@ function collectRunnerRouteDiagnostics(route, runnerConfig) {
   if (normalizedRoute.command) {
     warnings.push("legacy command fallback is still configured");
   }
+  if (normalizedRoute.dryRunDelivery) {
+    warnings.push("dry_run_delivery is enabled");
+  }
   if (normalizedRoute.workspaceDir) {
     warnings.push("legacy route.workspace_dir override is still configured");
   }
@@ -4940,6 +5367,7 @@ async function runDoctor(flags) {
     addDoctorCheck(rows, "warn", "local bot runner config", `${runnerTemplate.error} (${runnerTemplate.filePath})`);
   } else {
     const runnerConfig = loadBotRunnerConfig({ persistIfNeeded: true });
+    const runnerState = loadBotRunnerState();
     const enabledRoutes = ensureArray(runnerConfig.routes).filter((routeRaw) => safeObject(routeRaw).enabled);
     if (!enabledRoutes.length) {
       addDoctorCheck(rows, "warn", "local bot runner config", `template ready (${runnerTemplate.filePath}), no enabled routes`);
@@ -4996,6 +5424,24 @@ async function runDoctor(flags) {
         }
       }
     }
+    if (runnerState.migrated && runnerState.migratedKeys.length > 0) {
+      addDoctorCheck(
+        rows,
+        "ok",
+        "runner state migration",
+        `migrated ${runnerState.migratedKeys.length} stale route key(s) in ${runnerState.filePath}`,
+      );
+    }
+    if (runnerState.remainingAnonymousKeys.length > 0) {
+      addDoctorCheck(
+        rows,
+        "warn",
+        "runner state migration",
+        `anonymous route keys remain in ${runnerState.filePath}: ${runnerState.remainingAnonymousKeys.join(", ")}`,
+      );
+    } else {
+      addDoctorCheck(rows, "ok", "runner state migration", "no stale anonymous route keys detected");
+    }
   }
 
   const resolved = await resolveAccessTokenForCommand(context.baseURL, timeoutSeconds);
@@ -6855,6 +7301,10 @@ function patchServerToolSpecsForLocalRouting(tools) {
           type: "string",
           description: "Optional project chat destination label when a project has multiple active destinations.",
         },
+        dry_run_delivery: {
+          type: "boolean",
+          description: "If true, resolve bot and destination locally but do not send the provider message or mirror an archive reply.",
+        },
       },
     };
     return {
@@ -6966,6 +7416,7 @@ async function performLocalBotDelivery({
   archiveDedupeOutbound = true,
   archiveThreadID = "",
   archiveWorkItemID = "",
+  dryRun = false,
 }) {
   const normalizedProvider = normalizeBotProvider(provider);
   const destinations = await listProjectChatDestinations({
@@ -6980,15 +7431,35 @@ async function performLocalBotDelivery({
     throw new Error(`local ${normalizedProvider} env is not ready (${providerEnv.error})`);
   }
 
-  const delivery = await deliverLocalProviderMessage({
-    provider: normalizedProvider,
-    token: providerEnv.token,
-    destination,
-    text,
-    disableWebPagePreview,
-    replyToMessageID,
-    timeoutSeconds,
-  });
+  let delivery;
+  if (dryRun) {
+    delivery = {
+      statusCode: 204,
+      body: {
+        ok: true,
+        dry_run: true,
+        provider: normalizedProvider,
+        text,
+        disable_web_page_preview: Boolean(disableWebPagePreview),
+        reply_to_message_id: intFromRawAllowZero(replyToMessageID, 0),
+      },
+      ok: true,
+      url: "",
+      dryRun: true,
+      effectiveReplyToMessageID: intFromRawAllowZero(replyToMessageID, 0),
+      replySupported: normalizedProvider === "telegram",
+    };
+  } else {
+    delivery = await deliverLocalProviderMessage({
+      provider: normalizedProvider,
+      token: providerEnv.token,
+      destination,
+      text,
+      disableWebPagePreview,
+      replyToMessageID,
+      timeoutSeconds,
+    });
+  }
   if (!delivery.ok) {
     const responseJSON = safeObject(delivery.body);
     const errorDetail =
@@ -7016,6 +7487,22 @@ async function performLocalBotDelivery({
       archiveThreadID,
       archiveWorkItemID,
     });
+      if (dryRun) {
+        archive = {
+          ok: true,
+          dry_run: true,
+          skipped: true,
+          thread_id: thread.threadID,
+          work_item_id: thread.workItemID,
+          reason: "dry_run_delivery",
+        };
+        return {
+          provider: normalizedProvider,
+          destination,
+          delivery,
+          archive,
+        };
+      }
       const deliveredBody = safeObject(delivery.body);
       const deliveredResult = safeObject(deliveredBody.result || deliveredBody.message || deliveredBody.data);
       const deliveredMessageID = intFromRawAllowZero(
@@ -7154,6 +7641,12 @@ async function handleLocalBotMessageToolCall({
       : toolArgs.archiveReplies,
     true,
   );
+  const dryRunDelivery = boolFromRaw(
+    Object.prototype.hasOwnProperty.call(toolArgs, "dry_run_delivery")
+      ? toolArgs.dry_run_delivery
+      : toolArgs.dryRunDelivery,
+    false,
+  );
   const result = await performLocalBotDelivery({
     siteBaseURL,
     token,
@@ -7174,6 +7667,7 @@ async function handleLocalBotMessageToolCall({
     disableWebPagePreview,
     replyToMessageID,
     archiveReplies,
+    dryRun: dryRunDelivery,
   });
 
   return jsonRpcResult(
@@ -7192,6 +7686,7 @@ async function handleLocalBotMessageToolCall({
       status: result.delivery.statusCode,
       url: result.delivery.url,
       body: result.delivery.body,
+      dry_run_delivery: Boolean(result.delivery.dryRun),
       reply_supported: result.delivery.replySupported,
       archive: result.archive,
     }),
@@ -9122,6 +9617,176 @@ async function runSelftest(flags = {}) {
     `mode=${commandFallbackPlan.mode} fallback=${String(commandFallbackPlan.fallbackReason || "(none)")}`,
   );
 
+  let runnerRouteResolveTempRoot = "";
+  let originalResolveHome;
+  let originalResolveUserProfile;
+  try {
+    runnerRouteResolveTempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-route-selftest-"));
+    originalResolveHome = process.env.HOME;
+    originalResolveUserProfile = process.env.USERPROFILE;
+    const resolveHome = path.join(runnerRouteResolveTempRoot, "home");
+    const resolveMetheusDir = path.join(resolveHome, ".metheus");
+    fs.mkdirSync(resolveMetheusDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(resolveMetheusDir, "bot-runner.json"),
+      `${JSON.stringify({
+        version: 2,
+        project_mappings: {
+          [selftestProjectID]: {
+            workspace_dir: path.join(runnerRouteResolveTempRoot, "workspace"),
+            source: "selftest",
+          },
+        },
+        role_profiles: defaultBotRunnerRoleProfiles(),
+        routes: [
+          {
+            name: "telegram-monitor",
+            enabled: true,
+            project_id: selftestProjectID,
+            provider: "telegram",
+            role: "monitor",
+            role_profile: "monitor",
+            bot_name: "RyoAI_bot",
+            destination_label: "AI incubating CHAT ROOM",
+            archive_work_item_id: "304ce77a-7032-421c-aeda-bc54daf088dd",
+          },
+        ],
+      }, null, 2)}\n`,
+      "utf8",
+    );
+    process.env.HOME = resolveHome;
+    process.env.USERPROFILE = resolveHome;
+    const resolvedRunnerRoutes = resolveRunnerRoutes(
+      {
+        "project-id": selftestProjectID,
+        provider: "telegram",
+        role: "monitor",
+        "role-profile": "monitor",
+        "bot-name": "RyoAI_bot",
+        "dry-run-delivery": true,
+      },
+      "once",
+    );
+    const resolvedRunnerRoute = normalizeRunnerRoute(resolvedRunnerRoutes[0]);
+    push(
+      "bot_runner_inline_filters_reuse_configured_route",
+      resolvedRunnerRoutes.length === 1
+        && resolvedRunnerRoute.name === "telegram-monitor"
+        && resolvedRunnerRoute.destinationLabel === "AI incubating CHAT ROOM"
+        && resolvedRunnerRoute.dryRunDelivery === true
+        && runnerRouteKey(resolvedRunnerRoute) === "telegram-monitor::11111111-1111-1111-1111-111111111111::telegram::monitor::RyoAI_bot::AI incubating CHAT ROOM",
+      `name=${resolvedRunnerRoute.name || "(none)"} destination=${resolvedRunnerRoute.destinationLabel || "(none)"} key=${runnerRouteKey(resolvedRunnerRoute)}`,
+    );
+  } catch (err) {
+    push("bot_runner_inline_filters_reuse_configured_route", false, String(err?.message || err));
+  } finally {
+    if (typeof originalResolveHome === "string") {
+      process.env.HOME = originalResolveHome;
+    } else {
+      delete process.env.HOME;
+    }
+    if (typeof originalResolveUserProfile === "string") {
+      process.env.USERPROFILE = originalResolveUserProfile;
+    } else {
+      delete process.env.USERPROFILE;
+    }
+    if (runnerRouteResolveTempRoot) {
+      try {
+        fs.rmSync(runnerRouteResolveTempRoot, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+
+  let runnerStateMigrationTempRoot = "";
+  let originalStateMigrationHome;
+  let originalStateMigrationUserProfile;
+  try {
+    runnerStateMigrationTempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-state-selftest-"));
+    originalStateMigrationHome = process.env.HOME;
+    originalStateMigrationUserProfile = process.env.USERPROFILE;
+    const migrationHome = path.join(runnerStateMigrationTempRoot, "home");
+    const migrationMetheusDir = path.join(migrationHome, ".metheus");
+    fs.mkdirSync(migrationMetheusDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(migrationMetheusDir, "bot-runner.json"),
+      `${JSON.stringify({
+        version: 2,
+        project_mappings: {
+          [selftestProjectID]: {
+            workspace_dir: path.join(runnerStateMigrationTempRoot, "workspace"),
+            source: "selftest",
+          },
+        },
+        role_profiles: defaultBotRunnerRoleProfiles(),
+        routes: [
+          {
+            name: "telegram-monitor",
+            enabled: true,
+            project_id: selftestProjectID,
+            provider: "telegram",
+            role: "monitor",
+            role_profile: "monitor",
+            bot_name: "RyoAI_bot",
+            destination_label: "AI incubating CHAT ROOM",
+          },
+        ],
+      }, null, 2)}\n`,
+      "utf8",
+    );
+    fs.writeFileSync(
+      path.join(migrationMetheusDir, "bot-runner-state.json"),
+      `${JSON.stringify({
+        version: 1,
+        routes: {
+          "-::11111111-1111-1111-1111-111111111111::telegram::monitor::RyoAI_bot::-": {
+            last_processed_comment_id: "comment-a",
+            last_processed_created_at: "2026-03-13T06:00:00.000Z",
+            last_source_message_id: 41,
+            last_source_kind: "telegram_message",
+            updated_at: "2026-03-13T06:00:01.000Z",
+            last_action: "replied",
+            last_reply_message_id: 501,
+          },
+        },
+      }, null, 2)}\n`,
+      "utf8",
+    );
+    process.env.HOME = migrationHome;
+    process.env.USERPROFILE = migrationHome;
+    const migratedRunnerState = loadBotRunnerState();
+    const canonicalRunnerStateKey = "telegram-monitor::11111111-1111-1111-1111-111111111111::telegram::monitor::RyoAI_bot::AI incubating CHAT ROOM";
+    const persistedRunnerState = tryJsonParse(
+      fs.readFileSync(path.join(migrationMetheusDir, "bot-runner-state.json"), "utf8"),
+    );
+    push(
+      "bot_runner_state_auto_migrates_anonymous_route_key",
+      migratedRunnerState.migrated === true
+        && migratedRunnerState.migratedKeys.length === 1
+        && Boolean(migratedRunnerState.routes[canonicalRunnerStateKey])
+        && !migratedRunnerState.routes["-::11111111-1111-1111-1111-111111111111::telegram::monitor::RyoAI_bot::-"]
+        && Boolean(safeObject(persistedRunnerState.routes)[canonicalRunnerStateKey]),
+      `migrated=${String(migratedRunnerState.migrated)} key=${canonicalRunnerStateKey}`,
+    );
+  } catch (err) {
+    push("bot_runner_state_auto_migrates_anonymous_route_key", false, String(err?.message || err));
+  } finally {
+    if (typeof originalStateMigrationHome === "string") {
+      process.env.HOME = originalStateMigrationHome;
+    } else {
+      delete process.env.HOME;
+    }
+    if (typeof originalStateMigrationUserProfile === "string") {
+      process.env.USERPROFILE = originalStateMigrationUserProfile;
+    } else {
+      delete process.env.USERPROFILE;
+    }
+    if (runnerStateMigrationTempRoot) {
+      try {
+        fs.rmSync(runnerStateMigrationTempRoot, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+
   const defaultMonitorTriggerPolicy = normalizeRunnerTriggerPolicy({}, { role: "monitor" });
   push(
     "bot_runner_default_monitor_trigger_policy",
@@ -9356,6 +10021,35 @@ async function runSelftest(flags = {}) {
         && intFromRawAllowZero(e2eState.last_reply_message_id, 0) === 501,
       `outcome=${e2eResult.outcome} sent=${telegramE2EServer.state.sentMessages.length} mirrored=${String(mirroredReply?.id || "(none)")} state_reply=${String(e2eState.last_reply_message_id || "(none)")}`,
     );
+    const sentCountBeforeDryRun = telegramE2EServer.state.sentMessages.length;
+    const commentCountBeforeDryRun = telegramE2EServer.state.comments.length;
+    const dryRunResult = await performLocalBotDelivery({
+      siteBaseURL: telegramE2EServer.baseURL,
+      token: e2eToken,
+      timeoutSeconds: 10,
+      actorUserID: e2eActorUserID,
+      bot: e2eBot,
+      projectID: selftestProjectID,
+      provider: "telegram",
+      destinationSelectors: {
+        destinationLabel: e2eDestination.label,
+      },
+      text: "dry-run smoke",
+      disableWebPagePreview: true,
+      replyToMessageID: 41,
+      archiveReplies: true,
+      archiveThreadID: e2eThreadID,
+      archiveWorkItemID: e2eWorkItemID,
+      dryRun: true,
+    });
+    push(
+      "telegram_delivery_dry_run_skips_send_and_archive",
+      Boolean(dryRunResult.delivery?.dryRun)
+        && String(dryRunResult.archive?.reason || "") === "dry_run_delivery"
+        && telegramE2EServer.state.sentMessages.length === sentCountBeforeDryRun
+        && telegramE2EServer.state.comments.length === commentCountBeforeDryRun,
+      `dry_run=${String(dryRunResult.delivery?.dryRun || false)} sent=${telegramE2EServer.state.sentMessages.length} comments=${telegramE2EServer.state.comments.length}`,
+    );
   } catch (err) {
     push("telegram_runner_e2e_local_mock", false, String(err?.message || err));
   } finally {

package/package.json

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