@hua-labs/tap 0.2.1 → 0.2.3

package/dist/cli.mjs

@@ -219,7 +219,8 @@ function resolveConfig(overrides = {}, startDir) {
     commsDir: "auto",
     stateDir: "auto",
     runtimeCommand: "auto",
-    appServerUrl: "auto"
+    appServerUrl: "auto",
+    towerName: "auto"
   };
   let commsDir;
   if (overrides.commsDir) {
@@ -288,8 +289,16 @@ function resolveConfig(overrides = {}, startDir) {
   } else {
     appServerUrl = DEFAULT_APP_SERVER_URL;
   }
+  const towerName = local.towerName ?? shared.towerName ?? null;
   return {
-    config: { repoRoot, commsDir, stateDir, runtimeCommand, appServerUrl },
+    config: {
+      repoRoot,
+      commsDir,
+      stateDir,
+      runtimeCommand,
+      appServerUrl,
+      towerName
+    },
     sources
   };
 }
@@ -935,6 +944,10 @@ function canWriteOrCreate(filePath) {
     return false;
   }
 }
+function isEphemeralPath(p) {
+  const normalized = p.replace(/\\/g, "/").toLowerCase();
+  return normalized.includes("/_npx/") || normalized.includes("\\_npx\\") || normalized.includes("/fnm_multishells/") || normalized.includes("\\fnm_multishells\\") || normalized.includes("/tmp/") || normalized.includes("\\temp\\");
+}
 function findLocalTapCommsSource(ctx) {
   const candidates = [
     path7.join(
@@ -994,8 +1007,10 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
   const warnings = [];
   const issues = [];
   const env = {
-    TAP_AGENT_NAME: "<set-per-session>",
-    TAP_COMMS_DIR: toForwardSlashPath(ctx.commsDir)
+    TAP_AGENT_NAME: ctx.agentName ?? "<set-per-session>",
+    TAP_COMMS_DIR: toForwardSlashPath(ctx.commsDir),
+    TAP_STATE_DIR: toForwardSlashPath(ctx.stateDir),
+    TAP_REPO_ROOT: toForwardSlashPath(ctx.repoRoot)
   };
   if (instanceId) {
     env.TAP_AGENT_ID = instanceId;
@@ -1007,9 +1022,25 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
     return { command: null, args: [], env, sourcePath, warnings, issues };
   }
   const isBundled = sourcePath.endsWith(".mjs");
+  const isEphemeralSource = isEphemeralPath(sourcePath);
   let command = bunCommand;
-  if (!command && isBundled) {
-    command = process.execPath;
+  let args = [toForwardSlashPath(sourcePath)];
+  if (isEphemeralSource && isBundled) {
+    command = "npx";
+    args = ["@hua-labs/tap", "serve"];
+    warnings.push(
+      "Detected npx cache path. Using `npx @hua-labs/tap serve` as stable MCP launcher."
+    );
+  } else if (!command && isBundled) {
+    const isEphemeralNode = isEphemeralPath(process.execPath);
+    if (isEphemeralNode) {
+      command = "node";
+      warnings.push(
+        "Detected ephemeral node path. Using `node` from PATH for MCP config stability."
+      );
+    } else {
+      command = toForwardSlashPath(process.execPath);
+    }
     warnings.push(
       "bun not found; using node to run the compiled MCP server. Install bun for better performance."
     );
@@ -1021,8 +1052,8 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
     return { command: null, args: [], env, sourcePath, warnings, issues };
   }
   return {
-    command: isBundled && command === process.execPath ? toForwardSlashPath(command) : command,
-    args: [toForwardSlashPath(sourcePath)],
+    command,
+    args,
     env,
     sourcePath,
     warnings,
@@ -1386,13 +1417,12 @@ function verifyManagedToml(content, ctx, configPath) {
     });
   }
   if (mainTable && managed.command) {
+    const expectedArgs = managed.args.map((a) => `"${a.replace(/\\/g, "\\\\")}"`).join(", ");
     checks.push({
       name: "Managed command configured",
       passed: mainTable.includes(
         `command = "${managed.command.replace(/\\/g, "\\\\")}"`
-      ) && mainTable.includes(
-        `args = ["${managed.args[0]?.replace(/\\/g, "\\\\") ?? ""}"]`
-      ),
+      ) && mainTable.includes(`args = [${expectedArgs}]`),
       message: "Managed tap-comms command/args do not match expected values"
     });
   }
@@ -2879,6 +2909,40 @@ function isBridgeRunning(stateDir, instanceId) {
   if (!state) return false;
   return isProcessAlive(state.pid);
 }
+function resolveAgentName(instanceId, explicit, context) {
+  if (explicit) return explicit;
+  try {
+    const repoRoot = context?.repoRoot ?? context?.stateDir?.replace(/[\\/].tap-comms$/, "") ?? process.cwd();
+    const state = loadState(repoRoot);
+    const stateAgent = state?.instances[instanceId]?.agentName;
+    if (stateAgent) return stateAgent;
+  } catch {
+  }
+  return process.env.TAP_AGENT_NAME || process.env.CODEX_TAP_AGENT_NAME || null;
+}
+function inferRestartMode(bridgeState, flags, savedMode) {
+  const wasManaged = bridgeState?.appServer != null;
+  const hadAuth = bridgeState?.appServer?.auth != null;
+  const manageAppServer = flags?.noServer === true ? false : flags?.noServer === void 0 ? savedMode?.manageAppServer ?? wasManaged : true;
+  const noAuth = flags?.noAuth === true ? true : flags?.noAuth === void 0 ? savedMode?.noAuth ?? !hadAuth : false;
+  return { manageAppServer, noAuth };
+}
+function cleanupHeadlessDispatch(inboxDir, agentName) {
+  const removed = [];
+  if (!fs13.existsSync(inboxDir)) return removed;
+  const normalizedAgent = agentName.replace(/-/g, "_");
+  const marker = `-headless-${normalizedAgent}-review-`;
+  try {
+    for (const file of fs13.readdirSync(inboxDir)) {
+      if (file.includes(marker)) {
+        fs13.unlinkSync(path13.join(inboxDir, file));
+        removed.push(file);
+      }
+    }
+  } catch {
+  }
+  return removed;
+}
 async function startBridge(options) {
   const {
     instanceId,
@@ -2889,7 +2953,10 @@ async function startBridge(options) {
     agentName,
     port
   } = options;
-  const resolvedAgent = agentName || process.env.TAP_AGENT_NAME || process.env.CODEX_TAP_AGENT_NAME;
+  const resolvedAgent = resolveAgentName(instanceId, agentName, {
+    repoRoot: options.repoRoot,
+    stateDir
+  });
   if (!resolvedAgent) {
     throw new Error(
       `No agent name for ${instanceId} bridge. Set TAP_AGENT_NAME env var or pass --agent-name flag.`
@@ -3041,6 +3108,35 @@ async function stopBridge(options) {
   clearBridgeState(stateDir, instanceId);
   return true;
 }
+async function restartBridge(options) {
+  const { instanceId, stateDir, platform } = options;
+  const drainTimeout = (options.drainTimeoutSeconds ?? 30) * 1e3;
+  const repoRoot = options.repoRoot ?? stateDir.replace(/[\\/].tap-comms$/, "");
+  const runtimeStateDir = getBridgeRuntimeStateDir(repoRoot, instanceId);
+  const heartbeatPath = path13.join(runtimeStateDir, "heartbeat.json");
+  if (fs13.existsSync(heartbeatPath)) {
+    const startWait = Date.now();
+    while (Date.now() - startWait < drainTimeout) {
+      try {
+        const hb = JSON.parse(fs13.readFileSync(heartbeatPath, "utf-8"));
+        if (!hb.activeTurnId) break;
+      } catch {
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 1e3));
+    }
+  }
+  if (options.headless?.enabled && options.commsDir) {
+    const agentName = options.agentName ?? instanceId;
+    cleanupHeadlessDispatch(path13.join(options.commsDir, "inbox"), agentName);
+  }
+  await stopBridge({ instanceId, stateDir, platform });
+  const restartOptions = {
+    ...options,
+    processExistingMessages: true
+  };
+  return startBridge(restartOptions);
+}
 function rotateLog(logPath) {
   if (!fs13.existsSync(logPath)) return;
   try {
@@ -3192,7 +3288,13 @@ async function addCommand(args) {
   logHeader(`@hua-labs/tap add ${instanceId}`);
   if (instanceName) log(`Instance name: ${instanceName}`);
   if (port !== null) log(`Port: ${port}`);
-  const ctx = { ...createAdapterContext(state.commsDir, repoRoot), instanceId };
+  const existingAgentName = state.instances[instanceId]?.agentName ?? null;
+  const effectiveAgentName = agentNameFlag ?? existingAgentName ?? void 0;
+  const ctx = {
+    ...createAdapterContext(state.commsDir, repoRoot),
+    instanceId,
+    agentName: effectiveAgentName
+  };
   const adapter = getAdapter(runtime);
   const warnings = [];
   log("Probing runtime...");
@@ -3280,14 +3382,8 @@ async function addCommand(args) {
       logWarn("Bridge script not found. Bridge not started.");
       warnings.push("Bridge script not found. Run bridge manually.");
     } else {
-      const resolvedAgentName = agentNameFlag || process.env.TAP_AGENT_NAME || process.env.CODEX_TAP_AGENT_NAME;
-      if (!resolvedAgentName) {
-        logWarn(
-          "No agent name set. Bridge not started. Use: npx @hua-labs/tap bridge start <instance> --agent-name <name>"
-        );
-        warnings.push("Bridge not auto-started: no agent name available.");
-      } else {
-        const { config: resolvedCfg } = resolveConfig({}, repoRoot);
+      const { config: resolvedCfg } = resolveConfig({}, repoRoot);
+      {
         log(`Starting bridge: ${bridgeScript}`);
         try {
           bridge = await startBridge({
@@ -3297,7 +3393,7 @@ async function addCommand(args) {
             commsDir: ctx.commsDir,
             bridgeScript,
             platform: ctx.platform,
-            agentName: resolvedAgentName,
+            agentName: agentNameFlag ?? void 0,
             runtimeCommand: resolvedCfg.runtimeCommand,
             appServerUrl: resolvedCfg.appServerUrl,
             repoRoot,
@@ -3313,7 +3409,6 @@ async function addCommand(args) {
       }
     }
   }
-  const existingAgentName = state.instances[instanceId]?.agentName ?? null;
   const instanceState = {
     instanceId,
     runtime,
@@ -4043,7 +4138,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         log(`TUI connect:  ${bridge.appServer.url}`);
       }
     }
-    const updated = { ...instance, bridge };
+    const updated = { ...instance, bridge, manageAppServer, noAuth };
     const newState = updateInstanceState(state, instanceId, updated);
     saveState(repoRoot, newState);
     return {
@@ -4534,6 +4629,121 @@ function bridgeStatusOne(identifier) {
     }
   };
 }
+async function bridgeRestart(identifier, flags) {
+  const repoRoot = findRepoRoot();
+  const state = loadState(repoRoot);
+  if (!state) {
+    return {
+      ok: false,
+      command: "bridge",
+      code: "TAP_NOT_INITIALIZED",
+      message: "Not initialized. Run: npx @hua-labs/tap init",
+      warnings: [],
+      data: {}
+    };
+  }
+  const resolved = resolveInstanceId(identifier, state);
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      command: "bridge",
+      code: resolved.code,
+      message: resolved.message,
+      warnings: [],
+      data: {}
+    };
+  }
+  const instanceId = resolved.instanceId;
+  const inst = state.instances[instanceId];
+  if (!inst) {
+    return {
+      ok: false,
+      command: "bridge",
+      code: "TAP_INSTANCE_NOT_FOUND",
+      message: `Instance not found: ${instanceId}`,
+      warnings: [],
+      data: {}
+    };
+  }
+  const adapter = getAdapter(inst.runtime);
+  const ctx = {
+    ...createAdapterContext(state.commsDir, repoRoot),
+    instanceId
+  };
+  const bridgeScript = adapter.resolveBridgeScript?.(ctx);
+  if (!bridgeScript) {
+    return {
+      ok: false,
+      command: "bridge",
+      instanceId,
+      code: "TAP_BRIDGE_SCRIPT_MISSING",
+      message: `Bridge script not found for ${instanceId}`,
+      warnings: [],
+      data: {}
+    };
+  }
+  const { config: resolvedConfig } = resolveConfig({}, repoRoot);
+  const drainStr = typeof flags["drain-timeout"] === "string" ? flags["drain-timeout"] : "30";
+  const drainTimeout = parseInt(drainStr, 10) || 30;
+  logHeader(`@hua-labs/tap bridge restart ${instanceId}`);
+  log(`Drain timeout: ${drainTimeout}s`);
+  try {
+    const currentBridgeState = loadBridgeState(ctx.stateDir, instanceId);
+    const { manageAppServer, noAuth } = inferRestartMode(
+      currentBridgeState,
+      {
+        noServer: flags["no-server"] === true ? true : void 0,
+        noAuth: flags["no-auth"] === true ? true : void 0
+      },
+      {
+        manageAppServer: inst.manageAppServer,
+        noAuth: inst.noAuth
+      }
+    );
+    const bridge = await restartBridge({
+      instanceId,
+      runtime: inst.runtime,
+      stateDir: ctx.stateDir,
+      commsDir: ctx.commsDir,
+      bridgeScript,
+      platform: ctx.platform,
+      agentName: inst.agentName ?? void 0,
+      runtimeCommand: resolvedConfig.runtimeCommand,
+      appServerUrl: resolvedConfig.appServerUrl,
+      repoRoot,
+      port: inst.port ?? void 0,
+      headless: inst.headless,
+      drainTimeoutSeconds: drainTimeout,
+      manageAppServer,
+      noAuth
+    });
+    logSuccess(`Bridge restarted (PID: ${bridge.pid})`);
+    const updated = { ...inst, bridge, manageAppServer, noAuth };
+    const newState = updateInstanceState(state, instanceId, updated);
+    saveState(repoRoot, newState);
+    return {
+      ok: true,
+      command: "bridge",
+      instanceId,
+      code: "TAP_BRIDGE_START_OK",
+      message: `Bridge for ${instanceId} restarted (PID: ${bridge.pid})`,
+      warnings: [],
+      data: { pid: bridge.pid }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError(msg);
+    return {
+      ok: false,
+      command: "bridge",
+      instanceId,
+      code: "TAP_BRIDGE_START_FAILED",
+      message: msg,
+      warnings: [],
+      data: {}
+    };
+  }
+}
 async function bridgeCommand(args) {
   const { positional, flags } = parseArgs(args);
   const subcommand = positional[0];
@@ -4593,12 +4803,25 @@ async function bridgeCommand(args) {
       }
       return bridgeStatusAll();
     }
+    case "restart": {
+      if (!identifierArg) {
+        return {
+          ok: false,
+          command: "bridge",
+          code: "TAP_INVALID_ARGUMENT",
+          message: "Missing instance. Usage: npx @hua-labs/tap bridge restart <instance>",
+          warnings: [],
+          data: {}
+        };
+      }
+      return bridgeRestart(identifierArg, flags);
+    }
     default:
       return {
         ok: false,
         command: "bridge",
         code: "TAP_INVALID_ARGUMENT",
-        message: `Unknown bridge subcommand: ${subcommand}. Use: start, stop, status`,
+        message: `Unknown bridge subcommand: ${subcommand}. Use: start, stop, restart, status`,
         warnings: [],
         data: {}
       };
@@ -4900,7 +5123,9 @@ async function serveCommand(args) {
       data: {}
     };
   }
-  const child = spawn2(managed.command, managed.args, {
+  const serveCommand2 = managed.command === "npx" ? "node" : managed.command;
+  const serveArgs = managed.command === "npx" && managed.sourcePath ? [managed.sourcePath] : managed.args;
+  const child = spawn2(serveCommand2, serveArgs, {
     stdio: "inherit",
     env: {
       ...process.env,
@@ -5446,6 +5671,7 @@ import {
   statSync as statSync2,
   unlinkSync as unlinkSync3
 } from "fs";
+import { execSync as execSync7 } from "child_process";
 import { join as join17 } from "path";
 var PASS = "pass";
 var WARN = "warn";
@@ -5674,35 +5900,205 @@ function checkMessageLifecycle(commsDir) {
 function checkMcpServer(repoRoot) {
   const checks = [];
   const mcpJson = join17(repoRoot, ".mcp.json");
-  if (existsSync16(mcpJson)) {
+  if (!existsSync16(mcpJson)) {
+    checks.push({
+      name: "MCP config (.mcp.json)",
+      status: WARN,
+      message: "Not found \u2014 MCP channel notifications won't work"
+    });
+    return checks;
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync14(mcpJson, "utf-8"));
+  } catch {
+    checks.push({
+      name: "MCP config (.mcp.json)",
+      status: WARN,
+      message: "File exists but invalid JSON"
+    });
+    return checks;
+  }
+  const hasTapComms = config?.mcpServers?.["tap-comms"];
+  if (!hasTapComms) {
+    checks.push({
+      name: "MCP config (.mcp.json)",
+      status: WARN,
+      message: "tap-comms not configured"
+    });
+    return checks;
+  }
+  checks.push({
+    name: "MCP config (.mcp.json)",
+    status: PASS,
+    message: `command: ${hasTapComms.command}`
+  });
+  if (hasTapComms.command) {
+    const cmd = hasTapComms.command;
+    let cmdAvailable = existsSync16(cmd);
+    if (!cmdAvailable) {
+      try {
+        execSync7(`"${cmd}" --version`, {
+          stdio: "pipe",
+          timeout: 5e3
+        });
+        cmdAvailable = true;
+      } catch {
+      }
+    }
+    checks.push({
+      name: "MCP command binary",
+      status: cmdAvailable ? PASS : FAIL,
+      message: cmdAvailable ? cmd : `Not found: ${cmd} (checked PATH and absolute)`
+    });
+  }
+  if (hasTapComms.args?.[0]) {
+    const mcpScript = hasTapComms.args[0];
+    checks.push({
+      name: "MCP server script",
+      status: existsSync16(mcpScript) ? PASS : FAIL,
+      message: existsSync16(mcpScript) ? mcpScript : `Not found: ${mcpScript}`
+    });
+    if (mcpScript.endsWith(".mjs") && hasTapComms.command && !hasTapComms.command.includes("bun")) {
+      checks.push({
+        name: "MCP SQLite support",
+        status: WARN,
+        message: "Node + .mjs = no SQLite (bun:sqlite unavailable). Use bun or .ts source for full features."
+      });
+    }
+  }
+  if (!hasTapComms.cwd) {
+    checks.push({
+      name: "MCP cwd field",
+      status: WARN,
+      message: "No cwd in .mcp.json \u2014 worktree sessions may fail to resolve MCP server dependencies"
+    });
+  } else {
+    checks.push({
+      name: "MCP cwd field",
+      status: PASS,
+      message: hasTapComms.cwd
+    });
+  }
+  const envCommsDir = hasTapComms.env?.TAP_COMMS_DIR;
+  if (!envCommsDir) {
+    checks.push({
+      name: "MCP TAP_COMMS_DIR",
+      status: FAIL,
+      message: "TAP_COMMS_DIR not set in .mcp.json env \u2014 server will fail to start"
+    });
+  } else {
+    checks.push({
+      name: "MCP TAP_COMMS_DIR",
+      status: existsSync16(envCommsDir) ? PASS : FAIL,
+      message: existsSync16(envCommsDir) ? envCommsDir : `Directory not found: ${envCommsDir}`
+    });
+  }
+  checks.push({
+    name: "MCP session cache",
+    status: PASS,
+    message: "If .mcp.json was changed mid-session, restart Claude (Ctrl+C \u2192 claude --resume) to reload"
+  });
+  return checks;
+}
+function checkBridgeTurnHealth(repoRoot) {
+  const checks = [];
+  const tmpDir = join17(repoRoot, ".tmp");
+  if (!existsSync16(tmpDir)) return checks;
+  const state = loadState(repoRoot);
+  const activeMatchers = /* @__PURE__ */ new Set();
+  if (state) {
+    for (const [id, inst] of Object.entries(state.instances)) {
+      if (inst?.installed && inst.bridgeMode === "app-server") {
+        activeMatchers.add(id);
+        if (inst.agentName) activeMatchers.add(inst.agentName);
+      }
+    }
+  }
+  let dirs;
+  try {
+    dirs = readdirSync4(tmpDir).filter((d) => {
+      if (!d.startsWith("codex-app-server-bridge")) return false;
+      const suffix = d.replace("codex-app-server-bridge-", "");
+      if (activeMatchers.size === 0) return true;
+      for (const matcher of activeMatchers) {
+        if (suffix === matcher || suffix.startsWith(matcher)) return true;
+      }
+      return false;
+    });
+  } catch {
+    return checks;
+  }
+  for (const dir of dirs) {
+    const heartbeatPath = join17(tmpDir, dir, "heartbeat.json");
+    if (!existsSync16(heartbeatPath)) continue;
+    let heartbeat;
     try {
-      const config = JSON.parse(readFileSync14(mcpJson, "utf-8"));
-      const hasTapComms = config?.mcpServers?.["tap-comms"];
+      heartbeat = JSON.parse(readFileSync14(heartbeatPath, "utf-8"));
+    } catch {
+      checks.push({
+        name: `turn: ${dir}`,
+        status: WARN,
+        message: "heartbeat.json unreadable"
+      });
+      continue;
+    }
+    const heartbeatAge = heartbeat.updatedAt ? Math.floor(
+      (Date.now() - new Date(heartbeat.updatedAt).getTime()) / 1e3
+    ) : null;
+    if (heartbeat.connected === false || heartbeat.initialized === false) {
       checks.push({
-        name: "MCP config (.mcp.json)",
-        status: hasTapComms ? PASS : WARN,
-        message: hasTapComms ? `command: ${hasTapComms.command}` : "tap-comms not configured"
+        name: `turn: ${dir}`,
+        status: FAIL,
+        message: `disconnected (connected=${heartbeat.connected}, initialized=${heartbeat.initialized})${heartbeat.lastError ? ` \u2014 ${heartbeat.lastError}` : ""}`
       });
-      if (hasTapComms?.args?.[0]) {
-        const mcpScript = hasTapComms.args[0];
+      continue;
+    }
+    if (heartbeatAge !== null && heartbeatAge > 300) {
+      checks.push({
+        name: `turn: ${dir}`,
+        status: FAIL,
+        message: `dead \u2014 heartbeat ${Math.round(heartbeatAge)}s ago, no updates`
+      });
+      continue;
+    }
+    if (heartbeat.activeTurnId) {
+      const ZOMBIE_THRESHOLD = 30 * 60;
+      const lastNotifAge = heartbeat.lastNotificationAt ? Math.floor(
+        (Date.now() - new Date(heartbeat.lastNotificationAt).getTime()) / 1e3
+      ) : null;
+      if (lastNotifAge !== null && lastNotifAge > ZOMBIE_THRESHOLD) {
+        checks.push({
+          name: `turn: ${dir}`,
+          status: WARN,
+          message: `zombie \u2014 active turn ${heartbeat.activeTurnId}, last notification ${Math.round(lastNotifAge / 60)}m ago (${heartbeat.lastNotificationMethod ?? "?"}). MCP tools may not be exposed in app-server turns \u2014 try bridge restart${heartbeat.lastError ? `. Error: ${heartbeat.lastError}` : ""}`
+        });
+        continue;
+      }
+      const failures2 = heartbeat.consecutiveFailureCount ?? 0;
+      if (failures2 > 0 && heartbeatAge !== null && heartbeatAge < 60) {
         checks.push({
-          name: "MCP server script",
-          status: existsSync16(mcpScript) ? PASS : FAIL,
-          message: existsSync16(mcpScript) ? mcpScript : `Not found: ${mcpScript}`
+          name: `turn: ${dir}`,
+          status: WARN,
+          message: `zombie \u2014 active turn ${heartbeat.activeTurnId}, ${failures2} consecutive failures. MCP tools may not be exposed in app-server turns \u2014 try bridge restart${heartbeat.lastError ? `. Error: ${heartbeat.lastError}` : ""}`
         });
+        continue;
       }
-    } catch {
+    }
+    const failures = heartbeat.consecutiveFailureCount ?? 0;
+    if (failures > 5) {
       checks.push({
-        name: "MCP config (.mcp.json)",
+        name: `turn: ${dir}`,
         status: WARN,
-        message: "File exists but invalid JSON"
+        message: `slow \u2014 ${failures} consecutive failures, last: ${heartbeat.lastError ?? "unknown"}`
       });
+      continue;
     }
-  } else {
+    const turnInfo = heartbeat.activeTurnId ? `active turn ${heartbeat.activeTurnId}` : `idle (last: ${heartbeat.lastTurnStatus ?? "none"})`;
     checks.push({
-      name: "MCP config (.mcp.json)",
-      status: WARN,
-      message: "Not found \u2014 MCP channel notifications won't work"
+      name: `turn: ${dir}`,
+      status: PASS,
+      message: `healthy \u2014 ${turnInfo}, heartbeat ${heartbeatAge ?? "?"}s ago`
     });
   }
   return checks;
@@ -5741,10 +6137,17 @@ async function doctorCommand(args) {
     checks.push(...checkInstances(repoRoot, config.stateDir));
     checks.push(...checkMessageLifecycle(commsDir));
     checks.push(...checkMcpServer(repoRoot));
+    checks.push(...checkBridgeTurnHealth(repoRoot));
     return checks;
   }
   const initialChecks = runAllChecks();
-  for (const section of ["Comms", "Instances", "Messages", "MCP"]) {
+  for (const section of [
+    "Comms",
+    "Instances",
+    "Messages",
+    "MCP",
+    "Turns"
+  ]) {
     const sectionChecks = {
       Comms: initialChecks.filter(
         (c) => [
@@ -5763,7 +6166,8 @@ async function doctorCommand(args) {
       ),
       MCP: initialChecks.filter(
         (c) => c.name.startsWith("MCP") || c.name === "MCP server script"
-      )
+      ),
+      Turns: initialChecks.filter((c) => c.name.startsWith("turn:"))
     }[section];
     if (sectionChecks.length > 0) {
       log(`${section}:`);
@@ -5824,7 +6228,7 @@ async function doctorCommand(args) {
 }
 
 // src/commands/comms.ts
-import { execSync as execSync7 } from "child_process";
+import { execSync as execSync8 } from "child_process";
 import * as fs17 from "fs";
 import * as path18 from "path";
 var COMMS_HELP = `
@@ -5856,7 +6260,7 @@ function commsPull(commsDir) {
     };
   }
   try {
-    const output = execSync7("git pull --rebase", {
+    const output = execSync8("git pull --rebase", {
       cwd: commsDir,
       encoding: "utf-8",
       stdio: "pipe"
@@ -5898,8 +6302,8 @@ function commsPush(commsDir) {
     };
   }
   try {
-    execSync7("git add -A", { cwd: commsDir, stdio: "pipe" });
-    const status = execSync7("git status --porcelain", {
+    execSync8("git add -A", { cwd: commsDir, stdio: "pipe" });
+    const status = execSync8("git status --porcelain", {
       cwd: commsDir,
       encoding: "utf-8",
       stdio: "pipe"
@@ -5916,11 +6320,11 @@ function commsPush(commsDir) {
       };
     }
     const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    execSync7(`git commit -m "chore(comms): sync ${timestamp}"`, {
+    execSync8(`git commit -m "chore(comms): sync ${timestamp}"`, {
       cwd: commsDir,
       stdio: "pipe"
     });
-    execSync7("git push", { cwd: commsDir, stdio: "pipe" });
+    execSync8("git push", { cwd: commsDir, stdio: "pipe" });
     logSuccess("Comms push complete");
     return {
       ok: true,