metheus-governance-mcp-cli 0.2.288 → 0.2.290

package/README.md

@@ -379,7 +379,7 @@ Behavior:
 - `bot room-audit` now suggests executable runner routes for the managed server+local intersection. Room visibility is still reported, but a bot no longer has to appear in the admin list before route automation can prepare it.
 - `bot room-audit` defaults to `monitor` only unless you pass `--role` or `--roles`.
 - `bot room-audit --apply true` writes missing suggested routes into `~/.metheus/bot-runner.json` and disables overlapping enabled routes in the same project/provider/destination/bot scope that are outside the selected role set.
-- `runner project up` is the one-command direct CLI path for Telegram project operations: it runs the same room audit, applies the selected role routes, and starts detached polling by default unless you explicitly pass `--start false`.
+- `runner project up` is the direct CLI preparation path for Telegram project operations: it runs the same room audit and applies the selected role routes. Use `runner start-detached` for persistent polling, or let the TUI call `runner.project_up` to bootstrap detached polling in one step.
 - `runner project up` can be narrowed with `--bot-name`, `--bot-id`, `--role`, or `--roles <csv>` when you do not want every suggested role route for that room.
 - `bot remove` without flags starts a guided numbered flow: provider -> bot entry -> confirm removal.
 - Telegram stores one bot file per entry under `~/.metheus/telegram-bots/<ServerBotName>.env` with generic fields:
@@ -421,7 +421,6 @@ metheus-governance-mcp-cli bot remove --provider telegram --bot-name <server_bot
 metheus-governance-mcp-cli bot verify --provider telegram --bot-name <server_bot_name> --json true
 metheus-governance-mcp-cli bot room-audit --provider telegram --project-id <project_uuid> --destination-label <room_label> --json true
 metheus-governance-mcp-cli bot room-audit --provider telegram --project-id <project_uuid> --destination-label <room_label> --apply true --json true
-metheus-governance-mcp-cli runner project up --project-id <project_uuid> --provider telegram --destination-label <room_label>
 metheus-governance-mcp-cli runner project up --project-id <project_uuid> --provider telegram --destination-label <room_label> --start false
 metheus-governance-mcp-cli runner start-detached --project-id <project_uuid> --provider telegram --destination-label <room_label>
 metheus-governance-mcp-cli runner project up --project-id <project_uuid> --provider telegram --destination-label <room_label> --bot-name <server_bot_name> --roles monitor,review --start false
@@ -556,7 +555,7 @@ metheus-governance-mcp-cli runner start --route-name telegram-monitor --concurre
 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, and starts detached polling by default unless you explicitly pass `--start false`.
+- `runner project up` is the shortest practical direct CLI preparation path for Telegram: it audits one project destination and writes any missing suggested routes. Start persistent polling separately with `runner start-detached`, or use the TUI/local tool path that bootstraps detached polling for you.
 - 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.
@@ -569,7 +568,6 @@ Route management:
 Recommended operational path:
 
 ```bash
-metheus-governance-mcp-cli runner project up --project-id <project_uuid> --provider telegram --destination-label <room_label>
 metheus-governance-mcp-cli runner project up --project-id <project_uuid> --provider telegram --destination-label <room_label> --start false
 metheus-governance-mcp-cli runner start-detached --project-id <project_uuid> --provider telegram --destination-label <room_label>
 metheus-governance-mcp-cli runner project up --project-id <project_uuid> --provider telegram --destination-label <room_label> --bot-name <server_bot_name> --roles monitor,review --start false

package/cli.mjs

@@ -12292,17 +12292,21 @@ function resolveRunnerProjectUpExecutionPolicy(flags = {}) {
   const applyRequested = Object.prototype.hasOwnProperty.call(flags, "apply")
     ? boolFromRaw(flags.apply, true)
     : true;
-  const explicitStartDetachedRequested = Object.prototype.hasOwnProperty.call(flags, "start-detached");
+  const explicitStartDetachedRequested = Object.prototype.hasOwnProperty.call(flags, "start-detached")
+    || Object.prototype.hasOwnProperty.call(flags, "start_detached");
   const explicitDetachedAliasRequested = Object.prototype.hasOwnProperty.call(flags, "detached");
   const explicitStartRequested = Object.prototype.hasOwnProperty.call(flags, "start");
-  const startRequested = Object.prototype.hasOwnProperty.call(flags, "start")
+  const startRequested = explicitStartRequested
     ? boolFromRaw(flags.start, true)
     : false;
+  const startDetachedRaw = Object.prototype.hasOwnProperty.call(flags, "start-detached")
+    ? flags["start-detached"]
+    : flags.start_detached;
   const startDetachedRequested = explicitStartDetachedRequested
-    ? boolFromRaw(flags["start-detached"], true)
+    ? boolFromRaw(startDetachedRaw, true)
     : (explicitDetachedAliasRequested
       ? boolFromRaw(flags.detached, false)
-      : !explicitStartRequested);
+      : false);
   const shouldStartRunner = startRequested || startDetachedRequested;
   return {
     applyRequested,
@@ -12319,6 +12323,24 @@ function buildRunnerStartDetachedCommand(flags = {}) {
   })].join(" ");
 }
 
+function sleepSyncMilliseconds(durationMs) {
+  const numericDurationMs = Math.max(0, intFromRaw(durationMs, 0) || 0);
+  if (numericDurationMs <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, numericDurationMs);
+}
+
+function ensureDetachedRunnerBootstrapped(childPID, logFilePath = "") {
+  sleepSyncMilliseconds(1200);
+  if (isProcessAlive(childPID)) {
+    return;
+  }
+  const normalizedLogFilePath = String(logFilePath || "").trim();
+  if (normalizedLogFilePath && fs.existsSync(normalizedLogFilePath)) {
+    throw new Error(`detached runner exited during bootstrap; inspect ${normalizedLogFilePath}`);
+  }
+  throw new Error("detached runner exited during bootstrap before the polling loop became stable");
+}
+
 function buildRunnerProjectUpNextSteps({
   applyRequested,
   shouldStartRunner,
@@ -12350,7 +12372,7 @@ async function buildRunnerProjectUpResult(flags = {}) {
   const ui = createPrompter();
   try {
     if (shouldRenderPromptChrome(flags)) {
-      ui.setFlow("RUNNER PROJECT UP", "Audit one project destination, create missing runner routes, and start detached polling by default unless --start false is passed");
+      ui.setFlow("RUNNER PROJECT UP", "Audit one project destination, create missing runner routes, and optionally start polling when explicitly requested");
     }
     const provider = String(flags.provider || "").trim()
       ? normalizeBotProvider(flags.provider)
@@ -12448,7 +12470,7 @@ async function buildRunnerProjectUpResult(flags = {}) {
       route_apply_changed: Boolean(applyResult.changed),
       route_config_file: String(applyResult.filePath || auditPayload.routeSuggestionConfigFilePath || "-").trim() || "-",
       enabled_routes_for_selection: matchingRoutes.map((route) => normalizeRunnerRoute(route).name).filter(Boolean),
-      start_requested: shouldStartRunner,
+      start_requested: startRequested,
       start_detached_requested: startDetachedRequested,
       next_steps: [],
       applied_routes: ensureArray(applyResult.appliedRoutes).map((item) => safeObject(item)),
@@ -12844,12 +12866,13 @@ async function launchDetachedRunnerProcess(flags, routes, sourceCommand) {
     if (launched.status !== 0) {
       throw new Error(String(launched.stderr || launched.stdout || "failed to launch detached runner").trim());
     }
-    const childPID = intFromRawAllowZero(String(launched.stdout || "").trim().split(/\r?\n/).pop(), 0);
-    if (childPID <= 0) {
-      throw new Error("detached runner launch did not return a child process id");
-    }
-    return buildRunnerDetachedLaunchRecord(childPID, routes, startFlags, sourceCommand, detachedLogFilePath);
-  }
+    const childPID = intFromRawAllowZero(String(launched.stdout || "").trim().split(/\r?\n/).pop(), 0);
+    if (childPID <= 0) {
+      throw new Error("detached runner launch did not return a child process id");
+    }
+    ensureDetachedRunnerBootstrapped(childPID, detachedLogFilePath);
+    return buildRunnerDetachedLaunchRecord(childPID, routes, startFlags, sourceCommand, detachedLogFilePath);
+  }
   const launchTempDir = fs.mkdtempSync(path.join(os.tmpdir(), "metheus-runner-launch-"));
   const scriptPath = path.join(launchTempDir, "start-runner.sh");
   const pidFilePath = path.join(launchTempDir, "runner.pid");
@@ -12873,13 +12896,14 @@ async function launchDetachedRunnerProcess(flags, routes, sourceCommand) {
       });
       if (launched.error) {
         throw launched.error;
-      }
-      if (launched.status !== 0) {
-        throw new Error(String(launched.stderr || launched.stdout || "failed to launch detached runner in Terminal.app").trim());
-      }
-      const childPID = await waitForRunnerPIDFile(pidFilePath);
-      return buildRunnerDetachedLaunchRecord(childPID, routes, startFlags, sourceCommand, detachedLogFilePath);
-    }
+      }
+      if (launched.status !== 0) {
+        throw new Error(String(launched.stderr || launched.stdout || "failed to launch detached runner in Terminal.app").trim());
+      }
+      const childPID = await waitForRunnerPIDFile(pidFilePath);
+      ensureDetachedRunnerBootstrapped(childPID, detachedLogFilePath);
+      return buildRunnerDetachedLaunchRecord(childPID, routes, startFlags, sourceCommand, detachedLogFilePath);
+    }
     const terminalLauncher = resolveLinuxDetachedTerminalLauncher(scriptPath);
     if (!terminalLauncher) {
       throw new Error("no supported Linux terminal emulator was found (tried x-terminal-emulator, gnome-terminal, konsole, mate-terminal, tilix, alacritty, xterm). Install one of those terminals so runner.start_detached can open an independent window");
@@ -12890,12 +12914,13 @@ async function launchDetachedRunnerProcess(flags, routes, sourceCommand) {
       stdio: "ignore",
     });
     child.unref();
-    if (!child.pid) {
-      throw new Error("detached terminal launcher did not return a process id");
-    }
-    const runnerPID = await waitForRunnerPIDFile(pidFilePath);
-    return buildRunnerDetachedLaunchRecord(runnerPID, routes, startFlags, sourceCommand, detachedLogFilePath);
-  } finally {
+    if (!child.pid) {
+      throw new Error("detached terminal launcher did not return a process id");
+    }
+    const runnerPID = await waitForRunnerPIDFile(pidFilePath);
+    ensureDetachedRunnerBootstrapped(runnerPID, detachedLogFilePath);
+    return buildRunnerDetachedLaunchRecord(runnerPID, routes, startFlags, sourceCommand, detachedLogFilePath);
+  } finally {
     try {
       fs.rmSync(launchTempDir, { recursive: true, force: true });
     } catch {}
@@ -16970,7 +16995,7 @@ function buildLocalToolSpecs() {
     {
       name: "runner.project_up",
       description:
-        "Audit one project destination, create missing runner routes, and optionally start polling only when explicitly requested. Use this before runner.start_detached when the route is not ready yet.",
+        "Audit one project destination, create missing runner routes, and let front-end/TUI flows bootstrap detached polling in one step. Pass start=false and start_detached=false for prepare-only mode, or use runner.start_detached directly when routes are already ready.",
       inputSchema: buildRunnerProjectUpInputSchema(),
     },
     {
@@ -19330,15 +19355,15 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
   try {
     const projectUpPolicy = resolveRunnerProjectUpExecutionPolicy({});
     push(
-      "runner_project_up_default_policy_prefers_detached_start",
+      "runner_project_up_default_policy_keeps_prepare_only_for_direct_cli",
       projectUpPolicy.applyRequested === true
         && projectUpPolicy.startRequested === false
-        && projectUpPolicy.startDetachedRequested === true
-        && projectUpPolicy.shouldStartRunner === true,
+        && projectUpPolicy.startDetachedRequested === false
+        && projectUpPolicy.shouldStartRunner === false,
       `apply=${projectUpPolicy.applyRequested} start=${projectUpPolicy.startRequested} detached=${projectUpPolicy.startDetachedRequested} shouldStart=${projectUpPolicy.shouldStartRunner}`,
     );
   } catch (err) {
-    push("runner_project_up_default_policy_prefers_detached_start", false, String(err?.message || err));
+    push("runner_project_up_default_policy_keeps_prepare_only_for_direct_cli", false, String(err?.message || err));
   }
 
   try {
@@ -19407,10 +19432,24 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     push("runner_project_up_probe_failure_blocks_without_existing_route", false, String(err?.message || err));
   }
 
-  try {
-    const projectUpResponse = await handleLocalProjectToolDispatchImpl(
-      {
-        requestObj: {
+  try {
+    const projectUpPolicy = resolveRunnerProjectUpExecutionPolicy({ start_detached: true });
+    push(
+      "runner_project_up_tool_flag_accepts_start_detached_snake_case",
+      projectUpPolicy.applyRequested === true
+        && projectUpPolicy.startRequested === false
+        && projectUpPolicy.startDetachedRequested === true
+        && projectUpPolicy.shouldStartRunner === true,
+      `apply=${projectUpPolicy.applyRequested} start=${projectUpPolicy.startRequested} detached=${projectUpPolicy.startDetachedRequested} shouldStart=${projectUpPolicy.shouldStartRunner}`,
+    );
+  } catch (err) {
+    push("runner_project_up_tool_flag_accepts_start_detached_snake_case", false, String(err?.message || err));
+  }
+
+  try {
+    const projectUpResponse = await handleLocalProjectToolDispatchImpl(
+      {
+        requestObj: {
           jsonrpc: "2.0",
           id: 8,
           method: "tools/call",
@@ -19436,36 +19475,56 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
         workspaceSignalTrusted: true,
       },
       {
-        ...buildLocalProjectDispatchDeps(),
-        buildRunnerProjectUpResult: async () => ({
-          summaryPayload: {
+        ...buildLocalProjectDispatchDeps(),
+        buildRunnerProjectUpResult: async () => ({
+          summaryPayload: {
             ok: true,
             project_id: selftestProjectID,
             destination_label: "Selftest Room",
-            destination_id: "dest-1",
-            route_apply_requested: true,
-            route_apply_changed: true,
-            enabled_routes_for_selection: ["telegram-monitor-selftest"],
-            next_steps: [`${CLI_NAME} runner show --route-name telegram-monitor-selftest`],
-          },
-          matchingRoutes: [{ name: "telegram-monitor-selftest" }],
-          applyRequested: true,
-          applyResult: { ok: true, changed: true },
-          shouldStartRunner: false,
-          startDetachedRequested: false,
-          startFlags: {},
-        }),
-      },
-    );
-    const projectUpStructured = safeObject(safeObject(projectUpResponse).result)?.structuredContent || {};
-    push(
-      "local_runner_project_up_tool_dispatches",
-      projectUpStructured.ok === true
-        && ensureArray(projectUpStructured.enabled_routes_for_selection).includes("telegram-monitor-selftest"),
-      `routes=${ensureArray(projectUpStructured.enabled_routes_for_selection).join(",")} next=${ensureArray(projectUpStructured.next_steps).join(" | ")}`,
-    );
-  } catch (err) {
-    push("local_runner_project_up_tool_dispatches", false, String(err?.message || err));
+            destination_id: "dest-1",
+            route_apply_requested: true,
+            route_apply_changed: true,
+            enabled_routes_for_selection: ["telegram-monitor-selftest"],
+            next_steps: [`${CLI_NAME} runner show --route-name telegram-monitor-selftest`],
+            start_detached_requested: true,
+          },
+          matchingRoutes: [{ name: "telegram-monitor-selftest" }],
+          applyRequested: true,
+          applyResult: { ok: true, changed: true },
+          shouldStartRunner: true,
+          startDetachedRequested: true,
+          startFlags: {
+            "project-id": selftestProjectID,
+            provider: "telegram",
+            "destination-id": "dest-1",
+          },
+          applyFailureBlocksStart: false,
+        }),
+        startDetachedRunnerWithFlags: async () => ({
+          ok: true,
+          already_running: true,
+          registry_file: "registry.json",
+          launch: {
+            launch_id: "launch-project-up-1",
+            pid: 4242,
+            project_ids: [selftestProjectID],
+            route_names: ["telegram-monitor-selftest"],
+            destination_labels: ["Selftest Room"],
+          },
+        }),
+      },
+    );
+    const projectUpStructured = safeObject(safeObject(projectUpResponse).result)?.structuredContent || {};
+    push(
+      "local_runner_project_up_tool_dispatches",
+      projectUpStructured.ok === true
+        && ensureArray(projectUpStructured.enabled_routes_for_selection).includes("telegram-monitor-selftest")
+        && projectUpStructured.already_running === true
+        && String(safeObject(projectUpStructured.launch).launch_id || "").trim() === "launch-project-up-1",
+      `routes=${ensureArray(projectUpStructured.enabled_routes_for_selection).join(",")} launch=${String(safeObject(projectUpStructured.launch).launch_id || "").trim() || "-"} already_running=${projectUpStructured.already_running ? "true" : "false"}`,
+    );
+  } catch (err) {
+    push("local_runner_project_up_tool_dispatches", false, String(err?.message || err));
   }
 
   try {

package/lib/local-project-dispatch.mjs

@@ -629,13 +629,20 @@ export async function handleLocalProjectToolDispatch(
           ...toolArgs,
           ...(Object.prototype.hasOwnProperty.call(toolArgs, "project_id") ? {} : { project_id: resolveProjectID(toolArgs, args, workspaceDir, deps) }),
           ...(Object.prototype.hasOwnProperty.call(toolArgs, "start") ? {} : { start: false }),
-          ...(Object.prototype.hasOwnProperty.call(toolArgs, "start_detached") ? {} : { start_detached: false }),
+          ...(Object.prototype.hasOwnProperty.call(toolArgs, "start_detached") ? {} : { start_detached: true }),
           ...(Object.prototype.hasOwnProperty.call(toolArgs, "json") ? {} : { json: true }),
         };
         const result = await buildRunnerProjectUpResult(normalizedFlags);
+        let launchPayload = null;
+        if (result.shouldStartRunner && result.startDetachedRequested && !result.applyFailureBlocksStart) {
+          launchPayload = await startDetachedRunnerWithFlags(result.startFlags, "runner.project_up");
+        }
         const payload = {
           ...safeObject(result.summaryPayload),
           matching_routes: ensureArray(result.matchingRoutes).map((route) => String(safeObject(route).name || "").trim()).filter(Boolean),
+          launch: safeObject(launchPayload?.launch),
+          already_running: Boolean(launchPayload?.already_running),
+          registry_file: String(launchPayload?.registry_file || safeObject(result.summaryPayload).registry_file || "").trim(),
         };
         const text = [
           `ok: ${payload.ok ? "true" : "false"}`,
@@ -644,6 +651,10 @@ export async function handleLocalProjectToolDispatch(
           `destination_id: ${String(payload.destination_id || "").trim() || "-"}`,
           `route_apply_requested: ${payload.route_apply_requested ? "true" : "false"}`,
           `route_apply_changed: ${payload.route_apply_changed ? "true" : "false"}`,
+          `start_detached_requested: ${payload.start_detached_requested ? "true" : "false"}`,
+          `already_running: ${payload.already_running ? "true" : "false"}`,
+          `launch_id: ${String(safeObject(payload.launch).launch_id || "").trim() || "-"}`,
+          `pid: ${String(safeObject(payload.launch).pid || "").trim() || "-"}`,
           `enabled_routes_for_selection: ${ensureArray(payload.enabled_routes_for_selection).join(", ") || "-"}`,
           `next_steps: ${ensureArray(payload.next_steps).join(" | ") || "-"}`,
         ].join("\n");

package/package.json

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