metheus-governance-mcp-cli 0.2.166 → 0.2.168

package/README.md

@@ -441,6 +441,7 @@ 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 add` now auto-uses the suggested route name, `5000` ms poll interval, and `enabled=true` unless you pass explicit flags or edit the route later.
 - `runner project up` is the shortest practical route bootstrap path for Telegram: it audits one project destination, writes any missing suggested routes, then starts polling for that same destination unless you pass `--start false`.
+- if room visibility probe fails but one or more enabled routes already exist for that project destination, `runner project up` now treats the probe failure as a warning and can still start those existing routes.
 - `runner project up --dry-run-delivery true` lets the started runner validate route execution without sending a real provider message.
 - In public Telegram bot conversations, the stored route role is treated as a hint only. Live room context, the current human request, and recent bot replies take priority over the stored route role hint when the local AI client decides how to answer.
 - `runner route edit` updates one stored route. Use it when the destination, role, or server bot for an existing route changes.
@@ -519,6 +520,9 @@ Workspace/source-of-truth model:
 - use local tool `runner.start_detached` to launch an existing runner route in a separate local terminal
 - use local tool `runner.status` to inspect detached runner processes launched by this CLI
 - use local tool `runner.stop` to stop detached runner processes launched by this CLI
+- detached runner lifecycle belongs to the local Governance MCP tools, not to the current Codex/Claude/Gemini chat turn
+- client AI should resolve workspace + route and then request `runner.start_detached`; it should not try to keep the polling runner attached to its own session
+- the operational goal is: AI session may exit, but detached runner must continue polling independently on the local machine
 - `runner.start_detached` opens a separate terminal window on Windows, Terminal.app on macOS, and a supported Linux terminal emulator (`x-terminal-emulator`, `gnome-terminal`, `konsole`, `mate-terminal`, `tilix`, `alacritty`, or `xterm`)
 - on Linux, install one of those terminal emulators first; detached runner launch will fail fast if none are available
 - `bot-runner.json` stores executable route config and role profiles; it is not the project workspace registry
@@ -591,6 +595,23 @@ Mapping behavior:
 - `project.workspace.bind` updates the workspace registry directly; it does not need `bot-runner.json` side effects to succeed
 - use `runner.project_up` after workspace binding to prepare executable routes for one project destination
 - use `runner.show` to inspect the selected route before launching it
+- use `runner.start_detached` to hand runner lifecycle over to the local machine after route preparation; do not rely on the current client AI process to keep polling alive
+
+Recommended local runner bootstrap:
+
+```text
+1. project.workspace
+2. project.workspace.bind   # only when the registry binding is missing or wrong
+3. runner.project_up
+4. runner.show
+5. runner.start_detached
+6. runner.status / runner.stop
+```
+
+Operational principle:
+- the local Governance MCP tools own runner startup and lifecycle
+- the client AI only decides when to start/inspect/stop the runner
+- the detached runner must keep running even if the current AI tool session exits
 
 Runner command contract:
 - stdin: JSON payload containing project, destination, trigger message, and recent context comments

package/cli.mjs

@@ -4720,7 +4720,16 @@ function resolveRunnerProjectUpRoutes({
 
 async function runRunnerProjectUp(flags) {
   const result = await buildRunnerProjectUpResult(flags);
-  const { summaryPayload, applyRequested, applyResult, shouldStartRunner, matchingRoutes, startDetachedRequested, startFlags } = result;
+  const {
+    summaryPayload,
+    applyRequested,
+    applyResult,
+    shouldStartRunner,
+    matchingRoutes,
+    startDetachedRequested,
+    startFlags,
+    applyFailureBlocksStart,
+  } = result;
   if (boolFromRaw(flags.json, false)) {
     process.stdout.write(`${JSON.stringify(summaryPayload, null, 2)}\n`);
   } else {
@@ -4746,11 +4755,12 @@ async function runRunnerProjectUp(flags) {
         `enabled_routes_for_selection: ${summaryPayload.enabled_routes_for_selection.join(", ") || "-"}`,
         `start_requested: ${summaryPayload.start_requested ? "true" : "false"}`,
         `start_detached_requested: ${summaryPayload.start_detached_requested ? "true" : "false"}`,
+        ...(summaryPayload.warning ? [`warning: ${summaryPayload.warning}`] : []),
         `next_steps: ${summaryPayload.next_steps.join(" | ") || "-"}`,
       ].join("\n") + "\n",
     );
   }
-  if (applyRequested && applyResult.ok === false) {
+  if (applyFailureBlocksStart) {
     process.exitCode = 1;
     if (shouldStartRunner) {
       throw new Error(String(applyResult.error || "runner project up could not apply runner routes").trim());
@@ -4775,6 +4785,17 @@ async function runRunnerProjectUp(flags) {
   await runRunnerStartResolvedRoutes(matchingRoutes, startFlags);
 }
 
+function canStartRunnerDespiteProjectUpApplyFailure({ applyRequested, applyResult, matchingRoutes }) {
+  if (!applyRequested) return false;
+  const normalizedApplyResult = safeObject(applyResult);
+  if (normalizedApplyResult.ok !== false) return false;
+  const errorText = String(normalizedApplyResult.error || "").trim();
+  if (errorText !== "route apply skipped because the Telegram room visibility probe failed") {
+    return false;
+  }
+  return ensureArray(matchingRoutes).length > 0;
+}
+
 async function buildRunnerProjectUpResult(flags = {}) {
   const ui = createPrompter();
   try {
@@ -4855,8 +4876,13 @@ async function buildRunnerProjectUpResult(flags = {}) {
       ...(botNameFilter ? { "bot-name": botNameFilter } : {}),
       ...(botIDFilter ? { "bot-id": botIDFilter } : {}),
     };
+    const applyFailureWarningOnly = canStartRunnerDespiteProjectUpApplyFailure({
+      applyRequested,
+      applyResult,
+      matchingRoutes,
+    });
     const summaryPayload = {
-      ok: !applyRequested || applyResult.ok !== false,
+      ok: !applyRequested || applyResult.ok !== false || applyFailureWarningOnly,
       provider,
       project_id: String(auditPayload.projectID || "").trim(),
       destination_label: String(destination.destinationLabel || "").trim(),
@@ -4889,7 +4915,11 @@ async function buildRunnerProjectUpResult(flags = {}) {
       summaryPayload.next_steps.push(`${CLI_NAME} runner show --route-name ${summaryPayload.enabled_routes_for_selection[0] || "<route_name>"}`);
     }
     if (applyRequested && applyResult.ok === false && applyResult.error) {
-      summaryPayload.error = String(applyResult.error || "").trim();
+      if (applyFailureWarningOnly) {
+        summaryPayload.warning = String(applyResult.error || "").trim();
+      } else {
+        summaryPayload.error = String(applyResult.error || "").trim();
+      }
     }
     return {
       summaryPayload,
@@ -4899,6 +4929,7 @@ async function buildRunnerProjectUpResult(flags = {}) {
       startDetachedRequested,
       matchingRoutes,
       startFlags,
+      applyFailureBlocksStart: applyRequested && applyResult.ok === false && !applyFailureWarningOnly,
     };
   } finally {
     ui.close();
@@ -8609,6 +8640,9 @@ function appendProjectHintToInitialize(responseObj, args, options = {}) {
     `- Use \`${projectWorkspaceBindTool}\` only when you need to explicitly write/update the local project-workspaces.json registry binding.`,
     `- Use \`${runnerProjectUpTool}\` to audit a project destination and create/select runner routes before starting polling. Then use \`${runnerShowTool}\` to inspect the resolved route if needed.`,
     `- To run automated polling independently of the current AI session, call \`${runnerStartDetachedTool}\` after the workspace binding and route are ready. Use \`${runnerStatusTool}\` to inspect detached runner processes and \`${runnerStopTool}\` to stop them later.`,
+    "- Treat detached runner lifecycle as owned by the local Governance MCP tools, not by the current AI session.",
+    `- Do not keep a long-running runner attached to the current client AI turn. Use \`${runnerStartDetachedTool}\` so the runner survives after the AI session exits.`,
+    "- The AI should resolve the project workspace, prepare the route, and request detached start; the runner process itself must continue independently in a separate local terminal/process.",
     `- After resolving the local workspace, call \`${projectSummaryTool}\` for project overview/agenda/server metadata.`,
     `- If user enters a Project ID in text (e.g., "Project ID <uuid>"), pass that exact UUID as \`project_id\` argument when calling \`${projectSummaryTool}\`.`,
     `- \`${projectDescribeTool}\` and \`${projectGetTool}\` are aliases of \`${projectSummaryTool}\`.`,
@@ -9812,6 +9846,34 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     push("detached_runner_linux_launcher_selects_supported_terminal", false, String(err?.message || err));
   }
 
+  try {
+    push(
+      "runner_project_up_probe_failure_allows_existing_route_start",
+      canStartRunnerDespiteProjectUpApplyFailure({
+        applyRequested: true,
+        applyResult: { ok: false, error: "route apply skipped because the Telegram room visibility probe failed" },
+        matchingRoutes: [{ name: "telegram-monitor-selftest" }],
+      }) === true,
+      "existing_routes=1 probe_failure=warning_only",
+    );
+  } catch (err) {
+    push("runner_project_up_probe_failure_allows_existing_route_start", false, String(err?.message || err));
+  }
+
+  try {
+    push(
+      "runner_project_up_probe_failure_blocks_without_existing_route",
+      canStartRunnerDespiteProjectUpApplyFailure({
+        applyRequested: true,
+        applyResult: { ok: false, error: "route apply skipped because the Telegram room visibility probe failed" },
+        matchingRoutes: [],
+      }) === false,
+      "existing_routes=0 probe_failure=blocked",
+    );
+  } catch (err) {
+    push("runner_project_up_probe_failure_blocks_without_existing_route", false, String(err?.message || err));
+  }
+
   try {
     const projectUpResponse = await handleLocalProjectToolDispatchImpl(
       {

package/package.json

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