metheus-governance-mcp-cli 0.2.292 → 0.2.294

package/cli.mjs

@@ -151,6 +151,9 @@ import {
   selectPendingArchiveComments,
   printRunnerResult,
 } from "./lib/runner-helpers.mjs";
+import {
+  normalizeRunnerRecentLocalInboundReceiptMap,
+} from "./lib/runner-local-inbound-receipts.mjs";
 import {
   normalizeRunnerConversationDecisionBundle,
   validateRunnerConversationDecisionBundle,
@@ -1966,88 +1969,6 @@ function prefersRunnerStateRecord(candidate, current) {
   return false;
 }
 
-function normalizeRunnerRecentLocalInboundReceiptRecord(rawReceipt, fallbackKey = "") {
-  const receipt = safeObject(rawReceipt);
-  const chatID = String(receipt.chat_id || receipt.chatID || "").trim();
-  const messageID = intFromRawAllowZero(receipt.message_id ?? receipt.messageID, 0);
-  const receiptKey = String(fallbackKey || `${chatID}:${messageID}`).trim();
-  if (!receiptKey || !chatID || !(messageID > 0)) {
-    return null;
-  }
-  const normalized = {
-    chat_id: chatID,
-    message_id: messageID,
-    receipt_origin: firstNonEmptyString([
-      receipt.receipt_origin,
-      receipt.receiptOrigin,
-      receipt.source_origin,
-      receipt.sourceOrigin,
-      "local_telegram_inbound",
-    ]),
-    receipt_route_key: firstNonEmptyString([
-      receipt.receipt_route_key,
-      receipt.receiptRouteKey,
-      receipt.source_route_key,
-      receipt.sourceRouteKey,
-    ]),
-    receipt_bot_username: normalizeTelegramMentionUsername(
-      firstNonEmptyString([
-        receipt.receipt_bot_username,
-        receipt.receiptBotUsername,
-        receipt.source_bot_username,
-        receipt.sourceBotUsername,
-      ]),
-    ),
-    kind: firstNonEmptyString([receipt.kind, "telegram_message"]),
-    sender: firstNonEmptyString([receipt.sender, receipt.from_name, receipt.fromName]),
-    sender_username: firstNonEmptyString([
-      receipt.sender_username,
-      receipt.senderUsername,
-      receipt.from_username,
-      receipt.fromUsername,
-    ]),
-    sender_is_bot: Boolean(receipt.sender_is_bot ?? receipt.senderIsBot ?? false),
-    body: firstNonEmptyString([receipt.body, receipt.text]),
-    occurred_at: firstNonEmptyString([receipt.occurred_at, receipt.occurredAt]),
-    received_at: firstNonEmptyString([receipt.received_at, receipt.receivedAt, new Date().toISOString()]),
-  };
-  const senderID = firstNonEmptyString([receipt.sender_id, receipt.senderID, receipt.from_id, receipt.fromID]);
-  if (senderID) {
-    normalized.sender_id = senderID;
-  }
-  const updateID = intFromRawAllowZero(receipt.update_id ?? receipt.updateID, 0);
-  if (updateID > 0) {
-    normalized.update_id = updateID;
-  }
-  const messageThreadID = intFromRawAllowZero(receipt.message_thread_id ?? receipt.messageThreadID, 0);
-  if (messageThreadID > 0) {
-    normalized.message_thread_id = messageThreadID;
-  }
-  const replyToMessageID = intFromRawAllowZero(receipt.reply_to_message_id ?? receipt.replyToMessageID, 0);
-  if (replyToMessageID > 0) {
-    normalized.reply_to_message_id = replyToMessageID;
-  }
-  const chatType = firstNonEmptyString([receipt.chat_type, receipt.chatType]);
-  if (chatType) {
-    normalized.chat_type = chatType;
-  }
-  const chatTitle = firstNonEmptyString([receipt.chat_title, receipt.chatTitle]);
-  if (chatTitle) {
-    normalized.chat_title = chatTitle;
-  }
-  return [receiptKey, normalized];
-}
-
-function normalizeRunnerRecentLocalInboundReceiptMap(rawReceipts) {
-  const normalizedEntries = [];
-  for (const [key, value] of Object.entries(safeObject(rawReceipts))) {
-    const normalizedEntry = normalizeRunnerRecentLocalInboundReceiptRecord(value, key);
-    if (!normalizedEntry) continue;
-    normalizedEntries.push(normalizedEntry);
-  }
-  return Object.fromEntries(normalizedEntries);
-}
-
 function mergeRunnerStateRecords(preferred, fallback) {
   const primary = safeObject(preferred);
   const secondary = safeObject(fallback);
@@ -7501,26 +7422,31 @@ async function syncRunnerRequestLedgerForProjectToServer({ normalizedRoute, runt
   }
 }
 
-function normalizeRunnerProcessLaunchEntry(rawEntry) {
-  const entry = safeObject(rawEntry);
-  return cleanupRunnerStateRecord({
-    launch_id: String(entry.launch_id || entry.launchID || "").trim(),
-    pid: intFromRawAllowZero(entry.pid, 0) || undefined,
-    started_at: String(entry.started_at || entry.startedAt || "").trim(),
-    command: String(entry.command || "").trim(),
-    cli_path: String(entry.cli_path || entry.cliPath || "").trim(),
-    working_directory: sanitizeWorkspaceCandidate(entry.working_directory || entry.workingDirectory) || String(entry.working_directory || entry.workingDirectory || "").trim(),
-    route_set_signature: String(entry.route_set_signature || entry.routeSetSignature || "").trim(),
-    route_keys: ensureArray(entry.route_keys || entry.routeKeys).map((item) => String(item || "").trim()).filter(Boolean),
-    route_names: ensureArray(entry.route_names || entry.routeNames).map((item) => String(item || "").trim()).filter(Boolean),
-    project_ids: ensureArray(entry.project_ids || entry.projectIds).map((item) => String(item || "").trim()).filter(Boolean),
-    provider: normalizeBotProvider(entry.provider),
-    destination_labels: ensureArray(entry.destination_labels || entry.destinationLabels).map((item) => String(item || "").trim()).filter(Boolean),
-    log_file: String(entry.log_file || entry.logFile || "").trim(),
-    created_by_pid: intFromRawAllowZero(entry.created_by_pid || entry.createdByPid, 0) || undefined,
-    source_command: String(entry.source_command || entry.sourceCommand || "").trim(),
-  });
-}
+function normalizeRunnerProcessLaunchEntry(rawEntry) {
+  const entry = safeObject(rawEntry);
+  const routeKeys = ensureArray(entry.route_keys || entry.routeKeys).map((item) => String(item || "").trim()).filter(Boolean);
+  return cleanupRunnerStateRecord({
+    launch_id: String(entry.launch_id || entry.launchID || "").trim(),
+    pid: intFromRawAllowZero(entry.pid, 0) || undefined,
+    started_at: String(entry.started_at || entry.startedAt || "").trim(),
+    command: String(entry.command || "").trim(),
+    cli_path: String(entry.cli_path || entry.cliPath || "").trim(),
+    working_directory: sanitizeWorkspaceCandidate(entry.working_directory || entry.workingDirectory) || String(entry.working_directory || entry.workingDirectory || "").trim(),
+    route_set_signature: String(entry.route_set_signature || entry.routeSetSignature || "").trim(),
+    route_keys: routeKeys,
+    route_names: ensureArray(entry.route_names || entry.routeNames).map((item) => String(item || "").trim()).filter(Boolean),
+    project_ids: ensureArray(entry.project_ids || entry.projectIds).map((item) => String(item || "").trim()).filter(Boolean),
+    provider: normalizeBotProvider(entry.provider),
+    destination_labels: ensureArray(entry.destination_labels || entry.destinationLabels).map((item) => String(item || "").trim()).filter(Boolean),
+    scheduling_target_keys: uniqueOrderedStrings([
+      ...ensureArray(entry.scheduling_target_keys || entry.schedulingTargetKeys).map((item) => String(item || "").trim()),
+      ...routeKeys.map((routeKey) => runnerSchedulingTargetKeyFromRouteKey(routeKey)).filter(Boolean),
+    ], (value) => String(value || "").trim()),
+    log_file: String(entry.log_file || entry.logFile || "").trim(),
+    created_by_pid: intFromRawAllowZero(entry.created_by_pid || entry.createdByPid, 0) || undefined,
+    source_command: String(entry.source_command || entry.sourceCommand || "").trim(),
+  });
+}
 
 function normalizeBotRunnerProcessRegistryContents(rawValue) {
   const launchesInput = safeObject(rawValue).launches;
@@ -12324,6 +12250,9 @@ function buildRunnerProjectTUISnapshot({
   const summaryPayload = safeObject(normalizedAuditResult.summaryPayload);
   const matchingRoutes = ensureArray(normalizedAuditResult.matchingRoutes)
     .map((route) => normalizeRunnerRoute(route));
+  const matchingRouteNames = matchingRoutes
+    .map((route) => String(route.name || runnerRouteKey(route)).trim())
+    .filter(Boolean);
   const registry = loadBotRunnerProcessRegistry({ persistIfNeeded: true });
   const existingLaunch = matchingRoutes.length
     ? findExistingDetachedRunnerLaunch(registry, matchingRoutes)
@@ -12334,22 +12263,60 @@ function buildRunnerProjectTUISnapshot({
       alive: true,
     }
     : null;
+  const destinationID = String(summaryPayload.destination_id || "").trim();
+  const destinationLabel = String(summaryPayload.destination_label || "").trim();
+  const projectID = String(summaryPayload.project_id || "").trim();
+  const relatedLaunches = Object.values(safeObject(registry).launches || {})
+    .map((entry) => normalizeRunnerProcessLaunchEntry(entry))
+    .filter((entry) => isProcessAlive(entry.pid))
+    .filter((entry) => {
+      const sameProject = ensureArray(entry.project_ids)
+        .map((item) => String(item || "").trim())
+        .includes(projectID);
+      if (!sameProject) return false;
+      const sameDestinationLabel = destinationLabel
+        ? ensureArray(entry.destination_labels)
+          .map((item) => String(item || "").trim().toLowerCase())
+          .includes(destinationLabel.toLowerCase())
+        : false;
+      const sameDestinationID = destinationID
+        ? ensureArray(entry.route_keys)
+          .map((item) => String(item || "").trim())
+          .some((item) => item.includes(`::${destinationID}`))
+        : false;
+      return sameDestinationLabel || sameDestinationID;
+    })
+    .map((entry) => {
+      const routeNames = ensureArray(entry.route_names)
+        .map((item) => String(item || "").trim())
+        .filter(Boolean);
+      const sharedRouteNames = routeNames.filter((routeName) => matchingRouteNames.includes(routeName));
+      return {
+        launch_id: String(entry.launch_id || "").trim(),
+        pid: intFromRawAllowZero(entry.pid, 0),
+        route_names: routeNames,
+        shared_route_names: sharedRouteNames,
+        source_command: String(entry.source_command || "").trim(),
+        same_selection: Boolean(launch && String(launch.launch_id || "").trim() === String(entry.launch_id || "").trim()),
+      };
+    });
   const logFilePath = String(launch?.log_file || "").trim();
   const logLines = readTextFileTailLines(logFilePath, 12);
   return {
-    project_id: String(summaryPayload.project_id || "").trim(),
-    destination_label: String(summaryPayload.destination_label || "").trim(),
-    destination_id: String(summaryPayload.destination_id || "").trim(),
+    project_id: projectID,
+    destination_label: destinationLabel,
+    destination_id: destinationID,
     room_probe_ok: Boolean(summaryPayload.room_probe_ok),
     route_apply_requested: Boolean(summaryPayload.route_apply_requested),
     route_apply_changed: Boolean(summaryPayload.route_apply_changed),
     route_config_file: String(summaryPayload.route_config_file || "").trim(),
     enabled_routes: ensureArray(summaryPayload.enabled_routes_for_selection).map((item) => String(item || "").trim()).filter(Boolean),
-    matching_routes: matchingRoutes.map((route) => String(route.name || runnerRouteKey(route)).trim()).filter(Boolean),
+    matching_routes: matchingRouteNames,
     next_steps: ensureArray(summaryPayload.next_steps).map((item) => String(item || "").trim()).filter(Boolean),
     warning: String(summaryPayload.warning || "").trim(),
     error: String(summaryPayload.error || errorMessage || "").trim(),
     launch,
+    related_launches: relatedLaunches,
     auto_start: autoStart,
     status_message: String(statusMessage || "").trim(),
     last_audit_at: String(lastAuditAt || "").trim() || new Date().toISOString(),
@@ -12360,6 +12327,25 @@ function buildRunnerProjectTUISnapshot({
   };
 }
 
+function buildRunnerProjectTUIKeyLine(label, value, labelWidth = 14) {
+  return `${bootstrapPadRight(`${label}:`, labelWidth)} ${String(value || "-").trim() || "-"}`;
+}
+
+function buildRunnerProjectTUIList(items = [], {
+  emptyText = "-",
+  bullet = "- ",
+  indent = "  ",
+  width = 140,
+} = {}) {
+  const normalizedItems = ensureArray(items)
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+  if (!normalizedItems.length) {
+    return [`${indent}${emptyText}`];
+  }
+  return normalizedItems.map((item) => `${indent}${bullet}${truncateRunnerTUIText(item, width)}`);
+}
+
 function buildRunnerProjectTUIFrame({
   snapshot,
   now = Date.now(),
@@ -12368,41 +12354,105 @@ function buildRunnerProjectTUIFrame({
 }) {
   const normalizedSnapshot = safeObject(snapshot);
   const alive = Boolean(safeObject(normalizedSnapshot.launch).alive);
-  const statusLabel = alive ? "RUNNING" : "STOPPED";
+  const statusLabel = alive ? "[ RUNNING ]" : "[ STOPPED ]";
   const statusDetail = alive
     ? `launch=${String(safeObject(normalizedSnapshot.launch).launch_id || "").trim() || "-"} pid=${String(safeObject(normalizedSnapshot.launch).pid || "").trim() || "-"}`
     : "no detached runner is active for this selection";
+  const enabledRoutes = ensureArray(normalizedSnapshot.enabled_routes);
+  const matchingRoutes = ensureArray(normalizedSnapshot.matching_routes);
+  const relatedLaunches = ensureArray(normalizedSnapshot.related_launches);
+  const selectedLaunch = safeObject(normalizedSnapshot.launch);
+  const otherLaunches = relatedLaunches.filter((launch) => !safeObject(launch).same_selection);
+  const overlappingLaunches = otherLaunches.filter((launch) => ensureArray(safeObject(launch).shared_route_names).length > 0);
+  const alertLines = [];
+  if (String(normalizedSnapshot.warning || "").trim()) {
+    alertLines.push(`warning: ${String(normalizedSnapshot.warning || "").trim()}`);
+  }
+  if (String(normalizedSnapshot.error || "").trim()) {
+    alertLines.push(`error: ${String(normalizedSnapshot.error || "").trim()}`);
+  }
+  if (overlappingLaunches.length) {
+    alertLines.push(`overlap: ${overlappingLaunches.length} other detached launch(es) share at least one route in this room`);
+  } else if (otherLaunches.length) {
+    alertLines.push(`notice: ${otherLaunches.length} other detached launch(es) are active for this project/destination`);
+  }
+  if (!alive) {
+    alertLines.push("runner is not active; press s to start or reuse a detached runner");
+  }
+  const stateHint = alive
+    ? "This screen can be closed with q. The detached runner keeps running."
+    : "No detached runner is attached to this selection yet.";
   const lines = [
-    "+----------------------------------------------------------------+",
-    "| RUNNER PROJECT TUI                                             |",
-    "| Project-scoped detached runner dashboard                       |",
-    "+----------------------------------------------------------------+",
-    `Status: ${statusLabel}${stopping ? " (closing TUI)" : ""}`,
-    `Detail: ${statusDetail}`,
-    `Project: ${String(normalizedSnapshot.project_id || "").trim() || "-"}`,
-    `Destination: ${String(normalizedSnapshot.destination_label || normalizedSnapshot.destination_id || "").trim() || "-"}`,
-    `Auto Start: ${normalizedSnapshot.auto_start ? "true" : "false"}`,
-    `Routes: ${ensureArray(normalizedSnapshot.enabled_routes).join(", ") || "-"}`,
-    `Room Probe OK: ${normalizedSnapshot.room_probe_ok ? "true" : "false"}`,
-    `Route Apply Changed: ${normalizedSnapshot.route_apply_changed ? "true" : "false"}`,
-    `Log File: ${String(normalizedSnapshot.log_file || "").trim() || "-"}`,
-    `Last Audit: ${String(normalizedSnapshot.last_audit_at || "").trim() || "-"}`,
-    `Updated: ${new Date(now).toLocaleString("sv-SE", { hour12: false })}`,
-    `Message: ${String(normalizedSnapshot.status_message || "").trim() || "-"}`,
-    `Warning: ${String(normalizedSnapshot.warning || "").trim() || "-"}`,
-    `Error: ${String(normalizedSnapshot.error || "").trim() || "-"}`,
+    "+======================================================================================+",
+    "| METHEUS PROJECT RUNNER                                                               |",
+    "| Detached runner dashboard                                                            |",
+    "+======================================================================================+",
+    "",
+    "[ STATUS ]",
+    `  ${statusLabel}${stopping ? " (closing TUI)" : ""}`,
+    `  ${statusDetail}`,
+    `  ${stateHint}`,
+    "",
+    "[ PROJECT ]",
+    `  ${buildRunnerProjectTUIKeyLine("Project", normalizedSnapshot.project_id)}`,
+    `  ${buildRunnerProjectTUIKeyLine("Destination", String(normalizedSnapshot.destination_label || normalizedSnapshot.destination_id || "").trim() || "-")}`,
+    `  ${buildRunnerProjectTUIKeyLine("Updated", new Date(now).toLocaleString("sv-SE", { hour12: false }))}`,
+    `  ${buildRunnerProjectTUIKeyLine("Last Audit", String(normalizedSnapshot.last_audit_at || "").trim() || "-")}`,
+    "",
+    "[ RUNNER ]",
+    `  ${buildRunnerProjectTUIKeyLine("Auto Start", normalizedSnapshot.auto_start ? "enabled" : "prepare-only")}`,
+    `  ${buildRunnerProjectTUIKeyLine("Room Probe", normalizedSnapshot.room_probe_ok ? "ok" : "failed")}`,
+    `  ${buildRunnerProjectTUIKeyLine("Apply Result", normalizedSnapshot.route_apply_changed ? "route file changed" : "no route file change")}`,
+    `  ${buildRunnerProjectTUIKeyLine("Active Launches", `${relatedLaunches.length}`)}`,
+    `  ${buildRunnerProjectTUIKeyLine("This Launch", alive ? String(selectedLaunch.launch_id || "-").trim() || "-" : "-")}`,
+    `  ${buildRunnerProjectTUIKeyLine("PID", alive ? String(selectedLaunch.pid || "-").trim() || "-" : "-")}`,
+    `  ${buildRunnerProjectTUIKeyLine("Log File", String(normalizedSnapshot.log_file || "").trim() || "-")}`,
+    "",
+    "[ ROUTES ]",
+    `  ${buildRunnerProjectTUIKeyLine("Enabled", `${enabledRoutes.length}`)}`,
+    `  ${buildRunnerProjectTUIKeyLine("Matched", `${matchingRoutes.length}`)}`,
+    ...buildRunnerProjectTUIList(matchingRoutes.length ? matchingRoutes : enabledRoutes, {
+      emptyText: "no routes selected",
+      bullet: "- ",
+      indent: "    ",
+      width: 96,
+    }),
     "",
-    "Controls: [s] start/reuse  [x] stop  [r] refresh  [a] re-audit  [q] quit",
+    "[ ALERTS ]",
+    ...buildRunnerProjectTUIList(alertLines, {
+      emptyText: "none",
+      bullet: "- ",
+      indent: "    ",
+      width: 96,
+    }),
+    "",
+    "[ CONTROLS ]",
+    "  s = start/reuse detached runner",
+    "  x = stop detached runner",
+    "  r = refresh status",
+    "  a = re-audit route selection",
+    "  q = quit this dashboard",
     "",
-    "Recent Log Tail:",
-    ...ensureArray(normalizedSnapshot.log_lines).map((line) => `  ${truncateRunnerTUIText(line, 140)}`),
+    "[ RECENT LOG TAIL ]",
+    ...ensureArray(normalizedSnapshot.log_lines).map((line) => `  ${truncateRunnerTUIText(line, 108)}`),
   ];
+  if (otherLaunches.length) {
+    lines.push("");
+    lines.push("[ OTHER ACTIVE LAUNCHES ]");
+    for (const launch of otherLaunches) {
+      const currentLaunch = safeObject(launch);
+      const sharedRoutes = ensureArray(currentLaunch.shared_route_names).join(", ") || "-";
+      lines.push(`  - ${String(currentLaunch.launch_id || "-").trim() || "-"} pid=${String(currentLaunch.pid || "-").trim() || "-"} source=${String(currentLaunch.source_command || "-").trim() || "-"}`);
+      lines.push(`    shared routes: ${truncateRunnerTUIText(sharedRoutes, 96)}`);
+      lines.push(`    all routes: ${truncateRunnerTUIText(ensureArray(currentLaunch.route_names).join(", ") || "-", 96)}`);
+    }
+  }
   const frame = lines.join("\n");
   if (!useColor) {
     return frame;
   }
   const statusColor = alive ? "\u001b[32m" : "\u001b[33m";
-  return frame.replace(`Status: ${statusLabel}`, `Status: ${statusColor}${statusLabel}\u001b[0m`);
+  return frame.replace(statusLabel, `${statusColor}${statusLabel}\u001b[0m`);
 }
 
 async function runRunnerProjectTUI(flags) {
@@ -13083,13 +13133,121 @@ function serializeCLIFlags(flags, options = {}) {
   return args;
 }
 
-function runnerDetachedRouteSetSignature(routes) {
-  return ensureArray(routes)
-    .map((route) => runnerRouteKey(normalizeRunnerRoute(route)))
-    .filter(Boolean)
-    .sort()
-    .join("||");
-}
+function runnerDetachedRouteSetSignature(routes) {
+  return ensureArray(routes)
+    .map((route) => runnerRouteKey(normalizeRunnerRoute(route)))
+    .filter(Boolean)
+    .sort()
+    .join("||");
+}
+
+function runnerSchedulingTargetKeyFromRouteKey(routeKey) {
+  const parts = String(routeKey || "").trim().split("::").filter(Boolean);
+  if (parts.length < 6) {
+    return "";
+  }
+  return [
+    String(parts[parts.length - 5] || "").trim(),
+    String(parts[parts.length - 4] || "").trim(),
+    String(parts[parts.length - 1] || "").trim(),
+  ].join("::");
+}
+
+function collectRunnerDetachedLaunchSchedulingTargetKeys(entryRaw) {
+  const entry = normalizeRunnerProcessLaunchEntry(entryRaw);
+  const explicitKeys = uniqueOrderedStrings(
+    ensureArray(entry.scheduling_target_keys || entry.schedulingTargetKeys),
+    (value) => String(value || "").trim(),
+  ).filter(Boolean);
+  if (explicitKeys.length > 0) {
+    return explicitKeys;
+  }
+  const routeKeyDerived = uniqueOrderedStrings(
+    ensureArray(entry.route_keys).map((value) => runnerSchedulingTargetKeyFromRouteKey(value)).filter(Boolean),
+    (value) => String(value || "").trim(),
+  ).filter(Boolean);
+  if (routeKeyDerived.length > 0) {
+    return routeKeyDerived;
+  }
+  const provider = normalizeBotProvider(entry.provider);
+  const projectIDs = ensureArray(entry.project_ids).map((value) => String(value || "").trim()).filter(Boolean);
+  const destinations = ensureArray(entry.destination_labels).map((value) => String(value || "").trim()).filter(Boolean);
+  return uniqueOrderedStrings(
+    projectIDs.flatMap((projectID) => destinations.map((destination) => [projectID, provider, destination].join("::"))),
+    (value) => String(value || "").trim(),
+  ).filter(Boolean);
+}
+
+function describeDetachedRunnerLaunch(entryRaw) {
+  const entry = normalizeRunnerProcessLaunchEntry(entryRaw);
+  return `launch_id=${entry.launch_id || "-"} pid=${entry.pid || "-"} routes=${ensureArray(entry.route_names).join(", ") || "-"}`;
+}
+
+function classifyDetachedRunnerLaunchReuse(registry, routes) {
+  const normalizedRoutes = ensureArray(routes).map((route) => normalizeRunnerRoute(route));
+  const targetSignature = runnerDetachedRouteSetSignature(normalizedRoutes);
+  const targetRouteKeys = normalizedRoutes.map((route) => runnerRouteKey(route)).filter(Boolean);
+  const targetRouteKeySet = new Set(targetRouteKeys);
+  const targetSchedulingTargetKeys = uniqueOrderedStrings(
+    normalizedRoutes.map((route) => runnerRouteSchedulingGroupKey(route)).filter(Boolean),
+    (value) => String(value || "").trim(),
+  ).filter(Boolean);
+  const aliveLaunches = Object.values(safeObject(registry).launches || {})
+    .map((entryRaw) => normalizeRunnerProcessLaunchEntry(entryRaw))
+    .filter((entry) => entry.launch_id && entry.pid && isProcessAlive(entry.pid));
+  const exact = aliveLaunches.find((entry) => entry.route_set_signature === targetSignature) || null;
+  if (exact) {
+    return {
+      kind: "reuse",
+      reason: "exact",
+      launch: exact,
+    };
+  }
+  if (!targetSchedulingTargetKeys.length) {
+    return {
+      kind: "none",
+    };
+  }
+  const sameTargetLaunches = aliveLaunches.filter((entry) => {
+    const entryTargetKeys = collectRunnerDetachedLaunchSchedulingTargetKeys(entry);
+    return entryTargetKeys.some((key) => targetSchedulingTargetKeys.includes(key));
+  });
+  if (!sameTargetLaunches.length) {
+    return {
+      kind: "none",
+    };
+  }
+  const supersets = sameTargetLaunches.filter((entry) => targetRouteKeys.every((routeKey) => ensureArray(entry.route_keys).includes(routeKey)));
+  if (supersets.length === 1) {
+    return {
+      kind: "reuse",
+      reason: "superset",
+      launch: supersets[0],
+    };
+  }
+  const conflictingLaunches = supersets.length > 1 ? supersets : sameTargetLaunches;
+  const overlapRouteNames = Array.from(
+    new Set(
+      conflictingLaunches.flatMap((entry) => ensureArray(entry.route_keys))
+        .filter((routeKey) => targetRouteKeySet.has(routeKey))
+        .map((routeKey) => {
+          const matchedRoute = normalizedRoutes.find((route) => runnerRouteKey(route) === routeKey);
+          return matchedRoute?.name || routeKey;
+        })
+        .filter(Boolean),
+    ),
+  );
+  const detail = supersets.length > 1
+    ? `multiple detached runners already cover the requested route set for the same project/provider/destination target (${conflictingLaunches.map((entry) => describeDetachedRunnerLaunch(entry)).join(" | ")})`
+    : `another detached runner already owns the same project/provider/destination target (${conflictingLaunches.map((entry) => describeDetachedRunnerLaunch(entry)).join(" | ")}). Stop it first or use runner project tui so one detached runner owns the full route set for that destination`;
+  return {
+    kind: "conflict",
+    detail,
+    launch: conflictingLaunches.length === 1 ? conflictingLaunches[0] : null,
+    conflicting_launches: conflictingLaunches,
+    overlapping_route_names: overlapRouteNames,
+  };
+}
 
 function buildRunnerDetachedPosixLaunchScript({
   scriptPath,
@@ -13149,25 +13307,28 @@ function buildRunnerDetachedLaunchRecord(childPID, routes, flags, sourceCommand,
     cli_path: cliPath,
     working_directory: path.dirname(cliPath),
     route_set_signature: runnerDetachedRouteSetSignature(normalizedRoutes),
-    route_keys: normalizedRoutes.map((route) => runnerRouteKey(route)),
-    route_names: normalizedRoutes.map((route) => route.name || runnerRouteKey(route)),
-    project_ids: Array.from(new Set(normalizedRoutes.map((route) => String(route.projectID || "").trim()).filter(Boolean))),
-    provider: firstNonEmptyString(normalizedRoutes.map((route) => route.provider)),
-    destination_labels: Array.from(new Set(normalizedRoutes.map((route) => String(route.destinationLabel || route.destinationID || "").trim()).filter(Boolean))),
-    log_file: String(logFilePath || "").trim(),
-    created_by_pid: process.pid,
-    source_command: sourceCommand,
-  });
-}
+    route_keys: normalizedRoutes.map((route) => runnerRouteKey(route)),
+    route_names: normalizedRoutes.map((route) => route.name || runnerRouteKey(route)),
+    project_ids: Array.from(new Set(normalizedRoutes.map((route) => String(route.projectID || "").trim()).filter(Boolean))),
+    provider: firstNonEmptyString(normalizedRoutes.map((route) => route.provider)),
+    destination_labels: Array.from(new Set(normalizedRoutes.map((route) => String(route.destinationLabel || route.destinationID || "").trim()).filter(Boolean))),
+    scheduling_target_keys: uniqueOrderedStrings(
+      normalizedRoutes.map((route) => runnerRouteSchedulingGroupKey(route)).filter(Boolean),
+      (value) => String(value || "").trim(),
+    ),
+    log_file: String(logFilePath || "").trim(),
+    created_by_pid: process.pid,
+    source_command: sourceCommand,
+  });
+}
 
-function findExistingDetachedRunnerLaunch(registry, routes) {
-  const targetSignature = runnerDetachedRouteSetSignature(routes);
-  if (!targetSignature) return null;
-  return Object.values(safeObject(registry).launches || {}).find((entryRaw) => {
-    const entry = normalizeRunnerProcessLaunchEntry(entryRaw);
-    return entry.route_set_signature === targetSignature && isProcessAlive(entry.pid);
-  }) || null;
-}
+function findExistingDetachedRunnerLaunch(registry, routes) {
+  const decision = classifyDetachedRunnerLaunchReuse(registry, routes);
+  if (decision.kind === "reuse" && decision.launch) {
+    return decision.launch;
+  }
+  return null;
+}
 
 async function launchDetachedRunnerProcess(flags, routes, sourceCommand) {
   const cliPath = fileURLToPath(import.meta.url);
@@ -13359,13 +13520,15 @@ async function runRunnerStop(flags) {
 async function runRunnerStartDetachedResolvedRoutes(routes, flags, sourceCommand = "runner start-detached", options = {}) {
   const silent = boolFromRaw(safeObject(options).silent, false);
   const registry = loadBotRunnerProcessRegistry({ persistIfNeeded: true });
-  const existing = findExistingDetachedRunnerLaunch(registry, routes);
-  if (existing) {
+  const reuseDecision = classifyDetachedRunnerLaunchReuse(registry, routes);
+  if (reuseDecision.kind === "reuse" && reuseDecision.launch) {
+    const existing = reuseDecision.launch;
     const payload = {
       ok: true,
-      already_running: true,
-      registry_file: registry.filePath,
-      launch: {
+      already_running: true,
+      reuse_reason: reuseDecision.reason,
+      registry_file: registry.filePath,
+      launch: {
         ...existing,
         alive: true,
       },
@@ -13375,15 +13538,24 @@ async function runRunnerStartDetachedResolvedRoutes(routes, flags, sourceCommand
         process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
         return payload;
       }
-      process.stdout.write(`Detached runner already running: launch_id=${existing.launch_id} pid=${existing.pid}${existing.log_file ? ` log_file=${existing.log_file}` : ""}\n`);
+      process.stdout.write(`Detached runner already running: launch_id=${existing.launch_id} pid=${existing.pid}${existing.log_file ? ` log_file=${existing.log_file}` : ""}${reuseDecision.reason ? ` reuse=${reuseDecision.reason}` : ""}\n`);
     }
     return payload;
   }
+  if (reuseDecision.kind === "conflict") {
+    const overlappingRouteNames = ensureArray(reuseDecision.overlapping_route_names)
+      .map((item) => String(item || "").trim())
+      .filter(Boolean);
+    const overlapSuffix = overlappingRouteNames.length
+      ? ` overlapping_routes=${overlappingRouteNames.join(", ")}`
+      : "";
+    throw new Error(`${String(reuseDecision.detail || "detached runner conflict").trim()}${overlapSuffix}`);
+  }
   const launch = await launchDetachedRunnerProcess(flags, routes, sourceCommand);
   const nextLaunches = {
     ...safeObject(registry).launches,
     [launch.launch_id]: launch,
-  };
+  };
   saveBotRunnerProcessRegistry({ launches: nextLaunches });
   const payload = {
     ok: true,
@@ -19658,10 +19830,176 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
   } catch (err) {
     push("detached_runner_launch_record_persists_log_file", false, String(err?.message || err));
   }
-
-  let detachedRunnerPosixTempDir = "";
-  try {
-    detachedRunnerPosixTempDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-detached-script-selftest-"));
+
+  try {
+    const routeBot1 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-1",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-1",
+      botName: "SelftestBot1",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const routeBot2 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-2",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-2",
+      botName: "SelftestBot2",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const supersetLaunch = buildRunnerDetachedLaunchRecord(
+      process.pid,
+      [routeBot1, routeBot2],
+      { tui: false },
+      "runner start-detached",
+    );
+    const decision = classifyDetachedRunnerLaunchReuse(
+      { launches: { [supersetLaunch.launch_id]: supersetLaunch } },
+      [routeBot2],
+    );
+    push(
+      "detached_runner_reuses_existing_superset_launch_for_same_target",
+      decision.kind === "reuse"
+        && decision.reason === "superset"
+        && String(safeObject(decision.launch).launch_id || "").trim() === supersetLaunch.launch_id,
+      `kind=${String(decision.kind || "")} reason=${String(decision.reason || "")} launch=${String(safeObject(decision.launch).launch_id || "")}`,
+    );
+  } catch (err) {
+    push("detached_runner_reuses_existing_superset_launch_for_same_target", false, String(err?.message || err));
+  }
+
+  try {
+    const routeBot1 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-1",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-1",
+      botName: "SelftestBot1",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const routeBot2 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-2",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-2",
+      botName: "SelftestBot2",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const supersetLaunch = buildRunnerDetachedLaunchRecord(
+      process.pid,
+      [routeBot1, routeBot2],
+      { tui: false },
+      "runner project tui",
+    );
+    const existing = findExistingDetachedRunnerLaunch(
+      { launches: { [supersetLaunch.launch_id]: supersetLaunch } },
+      [routeBot2],
+    );
+    push(
+      "detached_runner_existing_launch_lookup_reuses_superset_for_tui_snapshot",
+      String(safeObject(existing).launch_id || "").trim() === supersetLaunch.launch_id,
+      `launch=${String(safeObject(existing).launch_id || "").trim() || "(none)"}`,
+    );
+  } catch (err) {
+    push("detached_runner_existing_launch_lookup_reuses_superset_for_tui_snapshot", false, String(err?.message || err));
+  }
+
+  try {
+    const routeBot1 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-1",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-1",
+      botName: "SelftestBot1",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const routeBot2 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-2",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-2",
+      botName: "SelftestBot2",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const subsetLaunch = buildRunnerDetachedLaunchRecord(
+      process.pid,
+      [routeBot2],
+      { tui: false },
+      "runner start-detached",
+    );
+    const decision = classifyDetachedRunnerLaunchReuse(
+      { launches: { [subsetLaunch.launch_id]: subsetLaunch } },
+      [routeBot1, routeBot2],
+    );
+    push(
+      "detached_runner_blocks_partial_overlap_for_same_target",
+      decision.kind === "conflict"
+        && ensureArray(decision.overlapping_route_names).includes("telegram-monitor-selftest-bot-2")
+        && String(decision.detail || "").includes("runner project tui"),
+      `kind=${String(decision.kind || "")} overlap=${ensureArray(decision.overlapping_route_names).join(", ")} detail=${String(decision.detail || "")}`,
+    );
+  } catch (err) {
+    push("detached_runner_blocks_partial_overlap_for_same_target", false, String(err?.message || err));
+  }
+
+  try {
+    const routeBot1 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-1",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-1",
+      botName: "SelftestBot1",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const routeBot2 = normalizeRunnerRoute({
+      name: "telegram-monitor-selftest-bot-2",
+      projectID: selftestProjectID,
+      provider: "telegram",
+      role: "monitor",
+      botID: "bot-2",
+      botName: "SelftestBot2",
+      destinationID: "dest-1",
+      destinationLabel: "Selftest Room",
+    });
+    const singleLaunch = buildRunnerDetachedLaunchRecord(
+      process.pid,
+      [routeBot1],
+      { tui: false },
+      "runner start-detached",
+    );
+    const decision = classifyDetachedRunnerLaunchReuse(
+      { launches: { [singleLaunch.launch_id]: singleLaunch } },
+      [routeBot2],
+    );
+    push(
+      "detached_runner_blocks_disjoint_same_target_parallel_launches",
+      decision.kind === "conflict"
+        && ensureArray(decision.overlapping_route_names).length === 0
+        && String(decision.detail || "").includes("same project/provider/destination target"),
+      `kind=${String(decision.kind || "")} overlap=${ensureArray(decision.overlapping_route_names).join(", ")} detail=${String(decision.detail || "")}`,
+    );
+  } catch (err) {
+    push("detached_runner_blocks_disjoint_same_target_parallel_launches", false, String(err?.message || err));
+  }
+
+  let detachedRunnerPosixTempDir = "";
+  try {
+    detachedRunnerPosixTempDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-detached-script-selftest-"));
     const scriptPath = path.join(detachedRunnerPosixTempDir, "start-runner.sh");
     const pidFilePath = path.join(detachedRunnerPosixTempDir, "runner.pid");
     buildRunnerDetachedPosixLaunchScript({