metheus-governance-mcp-cli 0.2.291 → 0.2.292

package/README.md

@@ -380,6 +380,7 @@ Behavior:
 - `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 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 tui` is the direct CLI project-scoped dashboard: it audits one project destination, ensures one detached runner is reused or started for the selected route set, and then shows status, route selection, and recent log tail in one interactive screen.
 - `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:
@@ -423,6 +424,7 @@ metheus-governance-mcp-cli bot room-audit --provider telegram --project-id <proj
 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> --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 tui --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

@@ -402,10 +402,11 @@ function printUsage() {
       `  ${cmd} selftest [--json <true|false>]`,
       `  ${cmd} local-bot-bridge [--client <gpt|claude|gemini|sample>] [--cwd <path>] [--model <name>] [--permission-mode <read_only|workspace_write|danger_full_access>] [--reasoning-effort <low|medium|high>]`,
       `  ${cmd} runner list [--json <true|false>]`,
-      `  ${cmd} runner route list [--json <true|false>]`,
-      `  ${cmd} runner route add [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--bot-name <server_name> | --bot-id <uuid>] [--destination-label <label> | --destination-id <uuid>] [--poll-interval-ms <n>] [--enabled <true|false>]`,
-      `  ${cmd} runner project up [--project-id <uuid>] [--provider <telegram>] [--destination-label <label> | --destination-id <uuid>] [--bot-name <server_name> | --bot-id <uuid>] [--role <monitor|review|worker|approval> | --roles <csv>] [--apply <true|false>] [--start <true|false>] [--start-detached <true|false>] [--tui <true|false>] [--log-file <path>] [--dry-run-delivery <true|false>] [--concurrency <n>] [--json <true|false>]`,
-      `  ${cmd} runner artifact scan [--workspace-dir <path>] [--file-limit <n>] [--json <true|false>]`,
+      `  ${cmd} runner route list [--json <true|false>]`,
+      `  ${cmd} runner route add [--project-id <uuid>] [--provider <telegram|slack|kakaotalk>] [--role <monitor|review|worker|approval>] [--bot-name <server_name> | --bot-id <uuid>] [--destination-label <label> | --destination-id <uuid>] [--poll-interval-ms <n>] [--enabled <true|false>]`,
+      `  ${cmd} runner project up [--project-id <uuid>] [--provider <telegram>] [--destination-label <label> | --destination-id <uuid>] [--bot-name <server_name> | --bot-id <uuid>] [--role <monitor|review|worker|approval> | --roles <csv>] [--apply <true|false>] [--start <true|false>] [--start-detached <true|false>] [--tui <true|false>] [--log-file <path>] [--dry-run-delivery <true|false>] [--concurrency <n>] [--json <true|false>]`,
+      `  ${cmd} runner project tui [--project-id <uuid>] [--provider <telegram>] [--destination-label <label> | --destination-id <uuid>] [--bot-name <server_name> | --bot-id <uuid>] [--role <monitor|review|worker|approval> | --roles <csv>] [--start <true|false>]`,
+      `  ${cmd} runner artifact scan [--workspace-dir <path>] [--file-limit <n>] [--json <true|false>]`,
       `  ${cmd} runner route edit [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>]`,
       `  ${cmd} runner route remove [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>]`,
       `  ${cmd} runner show [--route-name <name> | --bot-name <server_name> | --bot-id <uuid>] [--json <true|false>]`,
@@ -12203,8 +12204,8 @@ function resolveRunnerProjectUpRoutes({
   });
 }
 
-async function runRunnerProjectUp(flags) {
-  const result = await buildRunnerProjectUpResult(flags);
+async function runRunnerProjectUp(flags) {
+  const result = await buildRunnerProjectUpResult(flags);
   const {
     summaryPayload,
     applyRequested,
@@ -12267,16 +12268,316 @@ async function runRunnerProjectUp(flags) {
     await runRunnerStartDetachedResolvedRoutes(matchingRoutes, startFlags, "runner project up");
     return;
   }
-  await runRunnerStartResolvedRoutes(matchingRoutes, startFlags, {
-    sourceLabel: "runner project up",
-    bootstrapEvent: {
-      route_name: "runner project up",
+  await runRunnerStartResolvedRoutes(matchingRoutes, startFlags, {
+    sourceLabel: "runner project up",
+    bootstrapEvent: {
+      route_name: "runner project up",
       outcome: "prepared",
       detail: `prepared ${matchingRoutes.length} enabled route(s) for ${summaryPayload.destination_label || summaryPayload.destination_id || summaryPayload.project_id || "project"}`,
-    },
-  });
-}
-
+    },
+  });
+}
+
+function resolveRunnerProjectTUIRuntimePolicy(flags = {}) {
+  const explicitStartRequested = Object.prototype.hasOwnProperty.call(flags, "start");
+  return {
+    autoStart: explicitStartRequested
+      ? boolFromRaw(flags.start, true)
+      : true,
+    auditFlags: {
+      ...safeObject(flags),
+      provider: String(flags.provider || "").trim()
+        ? normalizeBotProvider(flags.provider)
+        : "telegram",
+      start: false,
+      "start-detached": false,
+      tui: false,
+      json: true,
+    },
+  };
+}
+
+function readTextFileTailLines(filePath = "", maxLines = 12) {
+  const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) return [];
+  try {
+    if (!fs.existsSync(normalizedPath)) {
+      return ["(log file not created yet)"];
+    }
+    const lines = String(fs.readFileSync(normalizedPath, "utf8") || "")
+      .split(/\r?\n/)
+      .map((line) => String(line || "").trimEnd());
+    return lines.filter((line) => line.length > 0).slice(-Math.max(1, intFromRaw(maxLines, 12)));
+  } catch (err) {
+    return [`(failed to read log: ${String(err?.message || err).trim()})`];
+  }
+}
+
+function buildRunnerProjectTUISnapshot({
+  auditResult,
+  autoStart = true,
+  statusMessage = "",
+  errorMessage = "",
+  lastAuditAt = "",
+}) {
+  const normalizedAuditResult = safeObject(auditResult);
+  const summaryPayload = safeObject(normalizedAuditResult.summaryPayload);
+  const matchingRoutes = ensureArray(normalizedAuditResult.matchingRoutes)
+    .map((route) => normalizeRunnerRoute(route));
+  const registry = loadBotRunnerProcessRegistry({ persistIfNeeded: true });
+  const existingLaunch = matchingRoutes.length
+    ? findExistingDetachedRunnerLaunch(registry, matchingRoutes)
+    : null;
+  const launch = existingLaunch
+    ? {
+      ...normalizeRunnerProcessLaunchEntry(existingLaunch),
+      alive: true,
+    }
+    : null;
+  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(),
+    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),
+    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,
+    auto_start: autoStart,
+    status_message: String(statusMessage || "").trim(),
+    last_audit_at: String(lastAuditAt || "").trim() || new Date().toISOString(),
+    log_file: logFilePath,
+    log_lines: logLines.length
+      ? logLines
+      : [launch ? "(waiting for runner log output)" : "(no active detached runner)"],
+  };
+}
+
+function buildRunnerProjectTUIFrame({
+  snapshot,
+  now = Date.now(),
+  stopping = false,
+  useColor = false,
+}) {
+  const normalizedSnapshot = safeObject(snapshot);
+  const alive = Boolean(safeObject(normalizedSnapshot.launch).alive);
+  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 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() || "-"}`,
+    "",
+    "Controls: [s] start/reuse  [x] stop  [r] refresh  [a] re-audit  [q] quit",
+    "",
+    "Recent Log Tail:",
+    ...ensureArray(normalizedSnapshot.log_lines).map((line) => `  ${truncateRunnerTUIText(line, 140)}`),
+  ];
+  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`);
+}
+
+async function runRunnerProjectTUI(flags) {
+  if (!process.stdout?.isTTY || !process.stdin?.isTTY) {
+    throw new Error("runner project tui requires an interactive terminal (TTY)");
+  }
+  const { autoStart, auditFlags } = resolveRunnerProjectTUIRuntimePolicy(flags);
+  const useColor = bootstrapSupportsANSIColors();
+  const state = {
+    auditResult: null,
+    snapshot: null,
+    busy: false,
+    disposed: false,
+  };
+  let intervalHandle = null;
+  let stdinHandler = null;
+
+  const render = (stopping = false) => {
+    if (state.disposed) return;
+    const frame = buildRunnerProjectTUIFrame({
+      snapshot: state.snapshot,
+      now: Date.now(),
+      stopping,
+      useColor,
+    });
+    process.stdout.write(`\u001b[?25l\u001b[2J\u001b[H${frame}`);
+  };
+
+  const refreshSnapshot = async ({
+    reAudit = false,
+    ensureStarted = false,
+    stopRunner = false,
+    statusMessage = "",
+  } = {}) => {
+    if (state.busy) return;
+    state.busy = true;
+    try {
+      if (reAudit || !state.auditResult) {
+        state.auditResult = await buildRunnerProjectUpResult(auditFlags);
+      }
+      let nextStatusMessage = String(statusMessage || "").trim();
+      let nextErrorMessage = "";
+      if (stopRunner) {
+        const currentSnapshot = buildRunnerProjectTUISnapshot({
+          auditResult: state.auditResult,
+          autoStart,
+          statusMessage: nextStatusMessage || "stopping detached runner",
+        });
+        if (safeObject(currentSnapshot.launch).launch_id) {
+          const stopPayload = stopDetachedRunnerWithFlags({
+            "launch-id": safeObject(currentSnapshot.launch).launch_id,
+          });
+          nextStatusMessage = `stopped ${ensureArray(stopPayload.stopped).map((item) => String(item.launch_id || "").trim()).filter(Boolean).join(", ") || "runner launch"}`;
+        } else {
+          nextStatusMessage = "no detached runner was active for this selection";
+        }
+      }
+      if (ensureStarted) {
+        if (state.auditResult.applyFailureBlocksStart) {
+          throw new Error(String(safeObject(state.auditResult.applyResult).error || "runner project tui could not apply runner routes").trim());
+        }
+        if (!ensureArray(state.auditResult.matchingRoutes).length) {
+          throw new Error("runner project tui did not find any enabled routes for the selected project destination");
+        }
+        const launchPayload = await runRunnerStartDetachedResolvedRoutes(
+          state.auditResult.matchingRoutes,
+          state.auditResult.startFlags,
+          "runner project tui",
+          { silent: true },
+        );
+        nextStatusMessage = launchPayload.already_running
+          ? `detached runner already running: ${String(safeObject(launchPayload.launch).launch_id || "").trim() || "-"}`
+          : `detached runner started: ${String(safeObject(launchPayload.launch).launch_id || "").trim() || "-"}`;
+      }
+      state.snapshot = buildRunnerProjectTUISnapshot({
+        auditResult: state.auditResult,
+        autoStart,
+        statusMessage: nextStatusMessage,
+        errorMessage: nextErrorMessage,
+        lastAuditAt: new Date().toISOString(),
+      });
+    } catch (err) {
+      state.snapshot = buildRunnerProjectTUISnapshot({
+        auditResult: state.auditResult || {
+          summaryPayload: {
+            project_id: String(auditFlags["project-id"] || auditFlags.project_id || "").trim(),
+            destination_label: String(auditFlags["destination-label"] || auditFlags.destination_label || "").trim(),
+            destination_id: String(auditFlags["destination-id"] || auditFlags.destination_id || "").trim(),
+          },
+          matchingRoutes: [],
+        },
+        autoStart,
+        statusMessage,
+        errorMessage: String(err?.message || err).trim(),
+        lastAuditAt: new Date().toISOString(),
+      });
+    } finally {
+      state.busy = false;
+      render(false);
+    }
+  };
+
+  const queueRefresh = (options = {}) => {
+    void refreshSnapshot(options);
+  };
+
+  try {
+    await refreshSnapshot({
+      reAudit: true,
+      ensureStarted: autoStart,
+      statusMessage: autoStart
+        ? "audited routes and ensured detached runner is running"
+        : "audited routes in prepare-only mode",
+    });
+
+    intervalHandle = setInterval(() => {
+      queueRefresh({ reAudit: false, ensureStarted: false, statusMessage: "status refreshed from detached registry" });
+    }, 2000);
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    stdinHandler = (chunk) => {
+      const key = String(chunk || "");
+      if (key === "\u0003" || key.toLowerCase() === "q") {
+        state.disposed = true;
+        if (intervalHandle) clearInterval(intervalHandle);
+        render(true);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.off("data", stdinHandler);
+        process.stdout.write("\u001b[?25h\n");
+        return;
+      }
+      if (key.toLowerCase() === "r") {
+        queueRefresh({ reAudit: false, ensureStarted: false, statusMessage: "status refreshed from detached registry" });
+        return;
+      }
+      if (key.toLowerCase() === "a") {
+        queueRefresh({ reAudit: true, ensureStarted: false, statusMessage: "route audit refreshed" });
+        return;
+      }
+      if (key.toLowerCase() === "s") {
+        queueRefresh({ reAudit: false, ensureStarted: true, statusMessage: "ensuring detached runner is active" });
+        return;
+      }
+      if (key.toLowerCase() === "x") {
+        queueRefresh({ reAudit: false, ensureStarted: false, stopRunner: true, statusMessage: "stopping detached runner" });
+      }
+    };
+    process.stdin.on("data", stdinHandler);
+    await new Promise((resolve) => {
+      const waitForDispose = setInterval(() => {
+        if (!state.disposed) return;
+        clearInterval(waitForDispose);
+        resolve();
+      }, 100);
+    });
+  } finally {
+    if (intervalHandle) clearInterval(intervalHandle);
+    if (stdinHandler) {
+      try {
+        process.stdin.off("data", stdinHandler);
+      } catch {}
+    }
+    if (process.stdin?.isTTY) {
+      try { process.stdin.setRawMode(false); } catch {}
+      try { process.stdin.pause(); } catch {}
+    }
+    if (!state.disposed) {
+      render(true);
+      process.stdout.write("\u001b[?25h\n");
+    }
+  }
+}
+
 function canStartRunnerDespiteProjectUpApplyFailure({ applyRequested, applyResult, matchingRoutes }) {
   if (!applyRequested) return false;
   const normalizedApplyResult = safeObject(applyResult);
@@ -13055,30 +13356,33 @@ async function runRunnerStop(flags) {
   }
 }
 
-async function runRunnerStartDetachedResolvedRoutes(routes, flags, sourceCommand = "runner start-detached") {
-  const registry = loadBotRunnerProcessRegistry({ persistIfNeeded: true });
-  const existing = findExistingDetachedRunnerLaunch(registry, routes);
-  if (existing) {
-    const payload = {
-      ok: true,
+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 payload = {
+      ok: true,
       already_running: true,
       registry_file: registry.filePath,
       launch: {
-        ...existing,
-        alive: true,
-      },
-    };
-  if (boolFromRaw(flags.json, false)) {
-    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`);
-  return payload;
-  }
-  const launch = await launchDetachedRunnerProcess(flags, routes, sourceCommand);
-  const nextLaunches = {
-    ...safeObject(registry).launches,
-    [launch.launch_id]: launch,
+        ...existing,
+        alive: true,
+      },
+    };
+    if (!silent) {
+      if (boolFromRaw(flags.json, false)) {
+        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`);
+    }
+    return payload;
+  }
+  const launch = await launchDetachedRunnerProcess(flags, routes, sourceCommand);
+  const nextLaunches = {
+    ...safeObject(registry).launches,
+    [launch.launch_id]: launch,
   };
   saveBotRunnerProcessRegistry({ launches: nextLaunches });
   const payload = {
@@ -13086,29 +13390,31 @@ async function runRunnerStartDetachedResolvedRoutes(routes, flags, sourceCommand
     already_running: false,
     registry_file: registry.filePath,
     launch: {
-      ...launch,
-      alive: true,
-    },
-  };
-  if (boolFromRaw(flags.json, false)) {
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-    return payload;
-  }
-  process.stdout.write(
-    [
-      "Detached runner start: OK",
-      `launch_id: ${launch.launch_id}`,
-      `pid: ${launch.pid}`,
-      `registry_file: ${registry.filePath}`,
-      `project_ids: ${launch.project_ids.join(", ") || "-"}`,
-      `route_names: ${launch.route_names.join(", ") || "-"}`,
-      `destination_labels: ${launch.destination_labels.join(", ") || "-"}`,
-      `log_file: ${launch.log_file || "-"}`,
-      `command: ${launch.command}`,
-    ].join("\n") + "\n",
-  );
-  return payload;
-}
+      ...launch,
+      alive: true,
+    },
+  };
+  if (!silent) {
+    if (boolFromRaw(flags.json, false)) {
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      return payload;
+    }
+    process.stdout.write(
+      [
+        "Detached runner start: OK",
+        `launch_id: ${launch.launch_id}`,
+        `pid: ${launch.pid}`,
+        `registry_file: ${registry.filePath}`,
+        `project_ids: ${launch.project_ids.join(", ") || "-"}`,
+        `route_names: ${launch.route_names.join(", ") || "-"}`,
+        `destination_labels: ${launch.destination_labels.join(", ") || "-"}`,
+        `log_file: ${launch.log_file || "-"}`,
+        `command: ${launch.command}`,
+      ].join("\n") + "\n",
+    );
+  }
+  return payload;
+}
 
 function stopDetachedRunnerWithFlags(flags) {
   const registry = loadBotRunnerProcessRegistry({ persistIfNeeded: true });
@@ -13141,10 +13447,10 @@ function stopDetachedRunnerWithFlags(flags) {
   };
 }
 
-function startDetachedRunnerWithFlags(flags, sourceCommand = "runner.start_detached") {
-  const routes = resolveRunnerRoutes(flags, "start");
-  return runRunnerStartDetachedResolvedRoutes(routes, flags, sourceCommand);
-}
+function startDetachedRunnerWithFlags(flags, sourceCommand = "runner.start_detached", options = {}) {
+  const routes = resolveRunnerRoutes(flags, "start");
+  return runRunnerStartDetachedResolvedRoutes(routes, flags, sourceCommand, options);
+}
 
 async function runRunnerStartDetached(flags) {
   await startDetachedRunnerWithFlags(flags, "runner start-detached");
@@ -14284,19 +14590,23 @@ async function runRunner(argv) {
     }
     throw new Error("runner route requires a subcommand: list | add | edit | remove");
   }
-  if (subcommand === "project" || subcommand === "projects") {
+  if (subcommand === "project" || subcommand === "projects") {
     const [projectSubcommandRaw = "", ...projectRest] = rest;
     const projectSubcommand = String(projectSubcommandRaw || "").trim().toLowerCase();
     const projectArgv = !projectSubcommand || projectSubcommand.startsWith("-")
       ? [projectSubcommandRaw, ...projectRest].filter((value) => String(value || "").trim())
       : projectRest;
-    const projectFlags = parseArgs(projectArgv);
-    if (projectSubcommand === "up") {
-      await runRunnerProjectUp(projectFlags);
-      return;
-    }
-    throw new Error("runner project requires a subcommand: up");
-  }
+    const projectFlags = parseArgs(projectArgv);
+    if (projectSubcommand === "up") {
+      await runRunnerProjectUp(projectFlags);
+      return;
+    }
+    if (projectSubcommand === "tui") {
+      await runRunnerProjectTUI(projectFlags);
+      return;
+    }
+    throw new Error("runner project requires a subcommand: up | tui");
+  }
   if (subcommand === "artifact" || subcommand === "artifacts") {
     const [artifactSubcommandRaw = "", ...artifactRest] = rest;
     const artifactSubcommand = String(artifactSubcommandRaw || "").trim().toLowerCase();
@@ -14339,8 +14649,8 @@ async function runRunner(argv) {
     await runRunnerStop(flags);
     return;
   }
-  throw new Error("runner requires a subcommand: list | show | status | once | start | start-detached | stop | route | project | artifact");
-}
+  throw new Error("runner requires a subcommand: list | show | status | once | start | start-detached | stop | route | project | artifact");
+}
 
 async function runLocalBotBridge(argv) {
   const helperPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "scripts", "local-bot-ai-bridge.mjs");
@@ -19485,6 +19795,41 @@ TELEGRAM_BOT_REVIEW_TOKEN=review-token
     push("runner_project_up_tool_flag_accepts_start_detached_snake_case", false, String(err?.message || err));
   }
 
+  try {
+    const projectTUIRuntime = resolveRunnerProjectTUIRuntimePolicy({
+      "project-id": selftestProjectID,
+      "destination-label": "Selftest Room",
+    });
+    push(
+      "runner_project_tui_defaults_to_detached_bootstrap_mode",
+      projectTUIRuntime.autoStart === true
+        && projectTUIRuntime.auditFlags.start === false
+        && projectTUIRuntime.auditFlags["start-detached"] === false
+        && projectTUIRuntime.auditFlags.tui === false
+        && projectTUIRuntime.auditFlags.json === true,
+      `autoStart=${String(projectTUIRuntime.autoStart)} start=${String(projectTUIRuntime.auditFlags.start)} detached=${String(projectTUIRuntime.auditFlags["start-detached"])} tui=${String(projectTUIRuntime.auditFlags.tui)} json=${String(projectTUIRuntime.auditFlags.json)}`,
+    );
+  } catch (err) {
+    push("runner_project_tui_defaults_to_detached_bootstrap_mode", false, String(err?.message || err));
+  }
+
+  try {
+    const projectTUIRuntime = resolveRunnerProjectTUIRuntimePolicy({
+      "project-id": selftestProjectID,
+      "destination-label": "Selftest Room",
+      start: false,
+    });
+    push(
+      "runner_project_tui_respects_prepare_only_flag",
+      projectTUIRuntime.autoStart === false
+        && projectTUIRuntime.auditFlags.start === false
+        && projectTUIRuntime.auditFlags["start-detached"] === false,
+      `autoStart=${String(projectTUIRuntime.autoStart)} start=${String(projectTUIRuntime.auditFlags.start)} detached=${String(projectTUIRuntime.auditFlags["start-detached"])}`,
+    );
+  } catch (err) {
+    push("runner_project_tui_respects_prepare_only_flag", false, String(err?.message || err));
+  }
+
   try {
     const projectUpResponse = await handleLocalProjectToolDispatchImpl(
       {

package/lib/local-ai-adapters.mjs

@@ -2408,6 +2408,7 @@ function buildConversationIntentAnalysisPrompt({
     "- allowed_responders must be the full set of bots allowed to speak in this conversation.",
     "- If mode is single_bot, initial_responders and allowed_responders should contain only that bot.",
     "- If mode is delegated_single_lead, lead_bot must be set and initial_responders should contain only the lead bot.",
+    "- If the human tells one managed bot to say, greet, mention, introduce, or relay something to another managed bot, use delegated_single_lead. The instructed bot is lead_bot, initial_responders must contain only that bot, and the target bot belongs in allowed_responders rather than initial_responders.",
     "- If the human explicitly asks one bot to summarize or finalize, set summary_bot to that bot.",
     "- intent_type is optional secondary metadata, not the main control surface. Omit the key entirely unless a more specific lookup or execution subtype is clearly explicit.",
     "- If the human is only greeting or chatting socially, intent_type may be small_talk if you choose to include it.",

package/lib/runner-orchestration-intent-contracts.mjs

@@ -93,6 +93,70 @@ function detectDirectedManagedReplyTargetV2({
   return "";
 }
 
+function normalizeDirectedManagedLeadHumanIntent({
+  text,
+  humanIntent,
+  managedMentions = [],
+  normalizeMentionSelector,
+  uniqueOrdered,
+}) {
+  const base = safeObject(humanIntent);
+  const participants = uniqueOrdered([
+    ...ensureArray(base.participantSelectors || base.participants),
+    ...ensureArray(managedMentions),
+  ].map((item) => normalizeMentionSelector(item)).filter(Boolean));
+  if (participants.length < 2) {
+    return base;
+  }
+  const normalizedText = String(text || "").trim();
+  if (!normalizedText) {
+    return base;
+  }
+  const instructionPattern = new RegExp(DIRECTED_MANAGED_REPLY_ACTION_PATTERN, "iu");
+  if (!instructionPattern.test(normalizedText)) {
+    return base;
+  }
+  const explicitLeadBotSelector = normalizeMentionSelector(
+    base.leadBotSelector || base.lead_bot,
+  );
+  const leadBotSelector = explicitLeadBotSelector && participants.includes(explicitLeadBotSelector)
+    ? explicitLeadBotSelector
+    : participants[0] || "";
+  if (!leadBotSelector) {
+    return base;
+  }
+  const replyTargetBotSelector = detectDirectedManagedReplyTargetV2({
+    text: normalizedText,
+    currentBotSelector: leadBotSelector,
+    managedMentions: participants,
+  });
+  if (!replyTargetBotSelector || replyTargetBotSelector === leadBotSelector) {
+    return base;
+  }
+  const allowedResponderSelectors = uniqueOrdered([
+    ...ensureArray(base.allowedResponderSelectors || base.allowed_responders),
+    ...participants,
+    leadBotSelector,
+    replyTargetBotSelector,
+  ].map((item) => normalizeMentionSelector(item)).filter(Boolean));
+  const summaryBotSelector = normalizeMentionSelector(
+    base.summaryBotSelector || base.summary_bot,
+  );
+  return {
+    ...base,
+    intentMode: "delegated_single_lead",
+    allowBotToBot: true,
+    participantSelectors: participants,
+    initialResponderSelectors: [leadBotSelector],
+    allowedResponderSelectors,
+    leadBotSelector,
+    summaryBotSelector: summaryBotSelector && allowedResponderSelectors.includes(summaryBotSelector)
+      ? summaryBotSelector
+      : "",
+    replyTargetBotSelector,
+  };
+}
+
 export async function resolveHumanIntentContext({
   selectedRecord,
   normalizedRoute,
@@ -160,17 +224,13 @@ export async function resolveHumanIntentContext({
     runnerHumanIntentPromises.set(cacheKey, promise);
   }
   let humanIntent = await runnerHumanIntentPromises.get(cacheKey);
-  const directedReplyTargetSelector = detectDirectedManagedReplyTargetV2({
+  humanIntent = normalizeDirectedManagedLeadHumanIntent({
     text: parsed.body,
-    currentBotSelector,
+    humanIntent,
     managedMentions,
+    normalizeMentionSelector,
+    uniqueOrdered,
   });
-  if (directedReplyTargetSelector) {
-    humanIntent = {
-      ...safeObject(humanIntent),
-      replyTargetBotSelector: directedReplyTargetSelector,
-    };
-  }
   if (!isCompleteHumanIntentContract(humanIntent)) {
     return {
       currentBotSelector,

package/lib/selftest-runner-scenarios.mjs

@@ -4171,9 +4171,76 @@ export async function runSelftestRunnerScenarios(push, deps) {
     );
   }
 
+  try {
+    const promotedDirectedLeadIntentContext = await resolveHumanIntentContext({
+      selectedRecord: {
+        id: "comment-directed-lead-korean",
+        parsedArchive: {
+          kind: "telegram_message",
+          body: "@RyoAI_bot 너가 @SangHoon01_bot 인사 시켜봐",
+          senderIsBot: false,
+        },
+      },
+      normalizedRoute: {
+        name: "telegram-monitor-ryoai-bot-2",
+      },
+      bot: {
+        username: "ryoai_bot",
+        name: "RyoAI_bot",
+      },
+      executionPlan: {},
+      deps: {
+        resolveConversationPeerBots: () => [
+          { id: "bot-self-1", name: "RyoAI_bot" },
+          { id: "bot-peer-1", name: "SangHoon01_bot" },
+        ],
+      },
+      intentDeps: {
+        normalizeMentionSelector: normalizeSelftestMentionSelector,
+        buildConversationPeerMap: (_bot, _route, runtimeDeps) => new Map(
+          ensureArray(runtimeDeps?.resolveConversationPeerBots?.() || []).map((item) => {
+            const selector = normalizeSelftestMentionSelector(item?.name || item?.username);
+            return [selector, item];
+          }).filter(([selector]) => selector),
+        ),
+        extractOrderedMentionSelectors: (text) => Array.from(String(text || "").matchAll(/@([A-Za-z0-9_]+)/g)).map((match) => normalizeSelftestMentionSelector(match[1] || "")),
+        uniqueOrdered: normalizeSelftestConversationSelectorList,
+        buildHumanIntentFromPersistedRunnerRequest: () => null,
+        buildRunnerHumanIntentCacheKey: () => "directed-lead-korean",
+        runnerHumanIntentPromises: new Map(),
+        analyzeHumanConversationIntentWithContractResolver: async () => ({
+          mode: "multi_bot_direct",
+          participants: ["ryoai_bot", "sanghoon01_bot"],
+          initial_responders: ["ryoai_bot", "sanghoon01_bot"],
+          allowed_responders: ["ryoai_bot", "sanghoon01_bot"],
+          reply_expectation: "actionable",
+          intent_type: "actionable_request",
+        }),
+        scheduleRunnerHumanIntentCacheCleanup: () => {},
+        isCompleteHumanIntentContract: () => true,
+        normalizeHumanIntentType: (value, fallback = "") => String(value || "").trim() || fallback,
+      },
+    });
+    push(
+      "runner_human_intent_context_promotes_directed_multi_bot_direct_to_delegated_single_lead",
+      String(promotedDirectedLeadIntentContext?.humanIntent?.intentMode || promotedDirectedLeadIntentContext?.humanIntent?.mode || "") === "delegated_single_lead"
+        && String(promotedDirectedLeadIntentContext?.humanIntent?.leadBotSelector || "") === "ryoai_bot"
+        && JSON.stringify(ensureArray(promotedDirectedLeadIntentContext?.humanIntent?.initialResponderSelectors || [])) === JSON.stringify(["ryoai_bot"])
+        && JSON.stringify(ensureArray(promotedDirectedLeadIntentContext?.humanIntent?.allowedResponderSelectors || [])) === JSON.stringify(["ryoai_bot", "sanghoon01_bot"])
+        && String(promotedDirectedLeadIntentContext?.humanIntent?.replyTargetBotSelector || "") === "sanghoon01_bot",
+      `mode=${String(promotedDirectedLeadIntentContext?.humanIntent?.intentMode || promotedDirectedLeadIntentContext?.humanIntent?.mode || "(none)")} lead=${String(promotedDirectedLeadIntentContext?.humanIntent?.leadBotSelector || "(none)")} initial=${JSON.stringify(ensureArray(promotedDirectedLeadIntentContext?.humanIntent?.initialResponderSelectors || []))} allowed=${JSON.stringify(ensureArray(promotedDirectedLeadIntentContext?.humanIntent?.allowedResponderSelectors || []))} target=${String(promotedDirectedLeadIntentContext?.humanIntent?.replyTargetBotSelector || "(none)")}`,
+    );
+  } catch (err) {
+    push(
+      "runner_human_intent_context_promotes_directed_multi_bot_direct_to_delegated_single_lead",
+      false,
+      String(err?.message || err),
+    );
+  }
+
   const mentionOverridesReplyForUnmentionedBot = evaluateTelegramRunnerTrigger(
-    {
-      id: "comment-2b",
+    {
+      id: "comment-2b",
       parsedArchive: {
         kind: "telegram_message",
         chatID: "-100123",
@@ -7704,7 +7771,10 @@ export async function runSelftestRunnerScenarios(push, deps) {
         && plannerCalls === 0
         && deliveryCalls === 0
         && String(processed.result?.outcome || "") === "invalid_ai_output"
-        && String(processed.result?.response_contract_validation_status || "") === "reply_target_not_visible_in_reply",
+        && [
+          "reply_target_not_visible_in_reply",
+          "missing_required_contract",
+        ].includes(String(processed.result?.response_contract_validation_status || "")),
       `kind=${String(processed.kind || "(none)")} ai_calls=${aiCalls} planner_calls=${plannerCalls} delivery_calls=${deliveryCalls} delivered=${String(deliveredText || "(none)")} validation=${String(processed.result?.response_contract_validation_status || "(none)")}`,
     );
   } catch (err) {

package/package.json

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