@hua-labs/tap 0.2.0 → 0.2.2

package/dist/cli.mjs

@@ -1,6 +1,7 @@
 // src/commands/init.ts
 import * as fs6 from "fs";
 import * as path6 from "path";
+import { execSync } from "child_process";
 
 // src/state.ts
 import * as fs3 from "fs";
@@ -186,7 +187,7 @@ function loadJsonFile(filePath) {
     return null;
   }
 }
-function loadSharedConfig(repoRoot) {
+function loadSharedConfig2(repoRoot) {
   return loadJsonFile(path2.join(repoRoot, SHARED_CONFIG_FILE));
 }
 function loadLocalConfig(repoRoot) {
@@ -210,7 +211,7 @@ function loadLegacyShellConfig(repoRoot) {
 }
 function resolveConfig(overrides = {}, startDir) {
   const repoRoot = findRepoRoot2(startDir);
-  const shared = loadSharedConfig(repoRoot) ?? {};
+  const shared = loadSharedConfig2(repoRoot) ?? {};
   const local = loadLocalConfig(repoRoot) ?? {};
   const legacy = loadLegacyShellConfig(repoRoot) ?? {};
   const sources = {
@@ -218,7 +219,8 @@ function resolveConfig(overrides = {}, startDir) {
     commsDir: "auto",
     stateDir: "auto",
     runtimeCommand: "auto",
-    appServerUrl: "auto"
+    appServerUrl: "auto",
+    towerName: "auto"
   };
   let commsDir;
   if (overrides.commsDir) {
@@ -287,11 +289,25 @@ 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
   };
 }
+function saveSharedConfig(repoRoot, config) {
+  const filePath = path2.join(repoRoot, SHARED_CONFIG_FILE);
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs2.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  fs2.renameSync(tmp, filePath);
+}
 function resolvePath(repoRoot, p) {
   const normalized = normalizeTapPath(p);
   return path2.isAbsolute(normalized) ? normalized : path2.resolve(repoRoot, normalized);
@@ -753,6 +769,64 @@ async function initCommand(args) {
     };
   }
   logHeader("@hua-labs/tap init");
+  const commsRepoIdx = args.indexOf("--comms-repo");
+  const commsRepoUrl = commsRepoIdx !== -1 && args[commsRepoIdx + 1] ? args[commsRepoIdx + 1] : void 0;
+  if (commsRepoUrl) {
+    if (fs6.existsSync(commsDir) && fs6.readdirSync(commsDir).length > 0) {
+      const gitDir = path6.join(commsDir, ".git");
+      if (fs6.existsSync(gitDir)) {
+        log(`Comms directory exists: ${commsDir}`);
+        logSuccess("Comms directory is already a git repo \u2014 linking only");
+      } else {
+        logError(`Comms directory exists but is not a git repo: ${commsDir}`);
+        return {
+          ok: false,
+          command: "init",
+          code: "TAP_INIT_CLONE_FAILED",
+          message: `Comms directory "${commsDir}" exists but is not a git repo. Remove it or use --force to reinitialize.`,
+          warnings: [],
+          data: { commsDir, commsRepoUrl }
+        };
+      }
+    } else {
+      log(`Cloning comms repo: ${commsRepoUrl}`);
+      try {
+        execSync(`git clone "${commsRepoUrl}" "${commsDir}"`, {
+          stdio: "pipe",
+          encoding: "utf-8"
+        });
+        logSuccess(`Cloned comms repo to ${commsDir}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logError(`Failed to clone comms repo: ${msg}`);
+        return {
+          ok: false,
+          command: "init",
+          code: "TAP_INIT_CLONE_FAILED",
+          message: `Failed to clone comms repo: ${msg}`,
+          warnings: [],
+          data: { commsRepoUrl }
+        };
+      }
+    }
+  }
+  {
+    const sharedConfig = loadSharedConfig2(repoRoot) ?? {};
+    let configChanged = false;
+    if (commsRepoUrl) {
+      sharedConfig.commsRepoUrl = commsRepoUrl;
+      configChanged = true;
+    }
+    const commsDirRelative = path6.relative(repoRoot, commsDir);
+    if (commsDirRelative && commsDirRelative !== "tap-comms") {
+      sharedConfig.commsDir = commsDirRelative;
+      configChanged = true;
+    }
+    if (configChanged) {
+      saveSharedConfig(repoRoot, sharedConfig);
+      logSuccess("Saved comms config to tap-config.json");
+    }
+  }
   log(`Comms directory: ${commsDir}`);
   for (const dir of COMMS_DIRS) {
     const dirPath = path6.join(commsDir, dir);
@@ -829,7 +903,7 @@ ${entry}
 // src/adapters/claude.ts
 import * as fs8 from "fs";
 import * as path8 from "path";
-import { execSync } from "child_process";
+import { execSync as execSync2 } from "child_process";
 
 // src/adapters/common.ts
 import * as fs7 from "fs";
@@ -870,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(
@@ -929,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;
@@ -943,11 +1023,29 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
   }
   const isBundled = sourcePath.endsWith(".mjs");
   let command = bunCommand;
+  let args = [toForwardSlashPath(sourcePath)];
   if (!command && isBundled) {
-    command = process.execPath;
-    warnings.push(
-      "bun not found; using node to run the compiled MCP server. Install bun for better performance."
-    );
+    const isEphemeralSource = isEphemeralPath(sourcePath);
+    const isEphemeralNode = isEphemeralPath(process.execPath);
+    if (isEphemeralSource) {
+      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 (isEphemeralNode) {
+      command = "node";
+      warnings.push(
+        "Detected ephemeral node path. Using `node` from PATH for MCP config stability."
+      );
+    } else {
+      command = toForwardSlashPath(process.execPath);
+    }
+    if (!isEphemeralSource) {
+      warnings.push(
+        "bun not found; using node to run the compiled MCP server. Install bun for better performance."
+      );
+    }
   }
   if (!command) {
     issues.push(
@@ -956,8 +1054,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,
@@ -972,7 +1070,7 @@ function findMcpJsonPath(ctx) {
 }
 function findClaudeCommand() {
   try {
-    execSync("claude --version", { stdio: "pipe" });
+    execSync2("claude --version", { stdio: "pipe" });
     return "claude";
   } catch {
     return null;
@@ -1834,13 +1932,13 @@ import * as fs13 from "fs";
 import * as net from "net";
 import * as path13 from "path";
 import { randomBytes } from "crypto";
-import { spawn, spawnSync as spawnSync2, execSync as execSync3 } from "child_process";
+import { spawn, spawnSync as spawnSync2, execSync as execSync4 } from "child_process";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/runtime/resolve-node.ts
 import * as fs12 from "fs";
 import * as path12 from "path";
-import { execSync as execSync2 } from "child_process";
+import { execSync as execSync3 } from "child_process";
 function readNodeVersion(repoRoot) {
   const nvFile = path12.join(repoRoot, ".node-version");
   if (!fs12.existsSync(nvFile)) return null;
@@ -1883,7 +1981,7 @@ function probeFnmNode(desiredVersion) {
     );
     if (!fs12.existsSync(candidate)) continue;
     try {
-      const v = execSync2(`"${candidate}" --version`, {
+      const v = execSync3(`"${candidate}" --version`, {
         encoding: "utf-8",
         timeout: 5e3
       }).trim();
@@ -1897,7 +1995,7 @@ function probeFnmNode(desiredVersion) {
 }
 function detectNodeMajorVersion(command) {
   try {
-    const version2 = execSync2(`"${command}" --version`, {
+    const version2 = execSync3(`"${command}" --version`, {
       encoding: "utf-8",
       timeout: 5e3
     }).trim();
@@ -1911,7 +2009,7 @@ function checkStripTypesSupport(command) {
   const major = detectNodeMajorVersion(command);
   if (major !== null && major >= 22) return true;
   try {
-    execSync2(`"${command}" --experimental-strip-types -e ""`, {
+    execSync3(`"${command}" --experimental-strip-types -e ""`, {
       timeout: 5e3,
       stdio: "pipe"
     });
@@ -2469,7 +2567,7 @@ async function terminateProcess(pid, platform) {
   }
   try {
     if (platform === "win32") {
-      execSync3(`taskkill /PID ${pid} /F /T`, { stdio: "pipe" });
+      execSync4(`taskkill /PID ${pid} /F /T`, { stdio: "pipe" });
     } else {
       process.kill(pid, "SIGTERM");
       await delay(2e3);
@@ -2814,6 +2912,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,
@@ -2824,7 +2956,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.`
@@ -2976,6 +3111,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 {
@@ -3127,7 +3291,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...");
@@ -3215,14 +3385,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({
@@ -3232,7 +3396,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,
@@ -3248,7 +3412,6 @@ async function addCommand(args) {
       }
     }
   }
-  const existingAgentName = state.instances[instanceId]?.agentName ?? null;
   const instanceState = {
     instanceId,
     runtime,
@@ -3978,7 +4141,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 {
@@ -4469,6 +4632,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];
@@ -4528,12 +4806,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: {}
       };
@@ -4543,7 +4834,7 @@ async function bridgeCommand(args) {
 // src/engine/dashboard.ts
 import * as fs15 from "fs";
 import * as path15 from "path";
-import { execSync as execSync4 } from "child_process";
+import { execSync as execSync5 } from "child_process";
 function collectAgents(commsDir) {
   const heartbeatsPath = path15.join(commsDir, "heartbeats.json");
   if (!fs15.existsSync(heartbeatsPath)) return [];
@@ -4622,7 +4913,7 @@ function collectBridges(repoRoot) {
 }
 function collectPRs() {
   try {
-    const output = execSync4(
+    const output = execSync5(
       "gh pr list --state all --limit 10 --json number,title,author,state,url",
       { encoding: "utf-8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] }
     );
@@ -4835,7 +5126,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,
@@ -4869,7 +5162,7 @@ async function serveCommand(args) {
 // src/commands/init-worktree.ts
 import * as fs16 from "fs";
 import * as path17 from "path";
-import { execSync as execSync5 } from "child_process";
+import { execSync as execSync6 } from "child_process";
 var INIT_WORKTREE_HELP = `
 Usage:
   tap-comms init-worktree [options]
@@ -4893,7 +5186,7 @@ function warn(warnings, message) {
 }
 function run(cmd, opts) {
   try {
-    return execSync5(cmd, {
+    return execSync6(cmd, {
       cwd: opts?.cwd,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -4910,7 +5203,7 @@ function toAbsolute(p) {
 }
 function probeBun(candidate) {
   try {
-    const out = execSync5(`"${candidate}" --version`, {
+    const out = execSync6(`"${candidate}" --version`, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5e3
@@ -4924,7 +5217,7 @@ function findBun() {
   const candidates = process.platform === "win32" ? ["bun.exe", "bun"] : ["bun"];
   for (const name of candidates) {
     try {
-      const out = execSync5(
+      const out = execSync6(
         process.platform === "win32" ? `where ${name}` : `which ${name}`,
         { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5e3 }
       ).trim();
@@ -5376,11 +5669,12 @@ async function dashboardCommand(args) {
 import {
   existsSync as existsSync16,
   mkdirSync as mkdirSync10,
-  readdirSync as readdirSync3,
+  readdirSync as readdirSync4,
   readFileSync as readFileSync14,
   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";
@@ -5388,7 +5682,7 @@ var FAIL = "fail";
 function countFiles(dir, ext = ".md") {
   if (!existsSync16(dir)) return 0;
   try {
-    return readdirSync3(dir).filter((f) => f.endsWith(ext)).length;
+    return readdirSync4(dir).filter((f) => f.endsWith(ext)).length;
   } catch {
     return 0;
   }
@@ -5398,7 +5692,7 @@ function recentFileCount(dir, withinMs) {
   const cutoff = Date.now() - withinMs;
   let count = 0;
   try {
-    for (const f of readdirSync3(dir)) {
+    for (const f of readdirSync4(dir)) {
       if (!f.endsWith(".md")) continue;
       try {
         if (statSync2(join17(dir, f)).mtimeMs > cutoff) count++;
@@ -5409,6 +5703,21 @@ function recentFileCount(dir, withinMs) {
   }
   return count;
 }
+function loadBridgeRuntimeHeartbeat(bridgeState) {
+  const runtimeStateDir = bridgeState?.runtimeStateDir;
+  if (!runtimeStateDir) {
+    return null;
+  }
+  const heartbeatPath = join17(runtimeStateDir, "heartbeat.json");
+  if (!existsSync16(heartbeatPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync14(heartbeatPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
 function checkComms(commsDir) {
   const checks = [];
   checks.push({
@@ -5492,6 +5801,7 @@ function checkInstances(repoRoot, stateDir) {
       const running = isBridgeRunning(stateDir, id);
       const bridgeState = loadBridgeState(stateDir, id);
       const heartbeatAge = getHeartbeatAge(stateDir, id);
+      const runtimeHeartbeat = loadBridgeRuntimeHeartbeat(bridgeState);
       let status;
       let message;
       let fix;
@@ -5535,6 +5845,11 @@ function checkInstances(repoRoot, stateDir) {
         status = WARN;
         message = "Not running";
       }
+      const lastRuntimeError = runtimeHeartbeat?.lastError?.trim();
+      if (lastRuntimeError) {
+        status = status === FAIL ? FAIL : WARN;
+        message = `${message}; bridge last error: ${lastRuntimeError}`;
+      }
       checks.push({ name: `bridge: ${id}`, status, message, fix });
     } else {
       checks.push({
@@ -5588,35 +5903,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: "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}, 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;
       }
-    } catch {
+      const failures2 = heartbeat.consecutiveFailureCount ?? 0;
+      if (failures2 > 0 && heartbeatAge !== null && heartbeatAge < 60) {
+        checks.push({
+          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;
+      }
+    }
+    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;
@@ -5655,10 +6140,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) => [
@@ -5677,7 +6169,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}:`);
@@ -5737,6 +6230,158 @@ async function doctorCommand(args) {
   };
 }
 
+// src/commands/comms.ts
+import { execSync as execSync8 } from "child_process";
+import * as fs17 from "fs";
+import * as path18 from "path";
+var COMMS_HELP = `
+Usage:
+  tap-comms comms <subcommand>
+
+Subcommands:
+  pull    Pull latest changes from comms remote repo
+  push    Commit and push comms changes to remote repo
+
+Examples:
+  npx @hua-labs/tap comms pull
+  npx @hua-labs/tap comms push
+`.trim();
+function isGitRepo(dir) {
+  return fs17.existsSync(path18.join(dir, ".git"));
+}
+function commsPull(commsDir) {
+  logHeader("tap comms pull");
+  if (!isGitRepo(commsDir)) {
+    logError(`${commsDir} is not a git repository`);
+    return {
+      ok: false,
+      command: "comms",
+      code: "TAP_COMMS_NOT_REPO",
+      message: `Comms directory is not a git repo. Use 'tap init --comms-repo <url>' to set up.`,
+      warnings: [],
+      data: { commsDir }
+    };
+  }
+  try {
+    const output = execSync8("git pull --rebase", {
+      cwd: commsDir,
+      encoding: "utf-8",
+      stdio: "pipe"
+    });
+    logSuccess("Comms pull complete");
+    if (output.trim()) log(output.trim());
+    return {
+      ok: true,
+      command: "comms",
+      code: "TAP_COMMS_PULL_OK",
+      message: "Comms pull complete",
+      warnings: [],
+      data: { commsDir }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError(`Pull failed: ${msg}`);
+    return {
+      ok: false,
+      command: "comms",
+      code: "TAP_COMMS_PULL_FAILED",
+      message: `Pull failed: ${msg}`,
+      warnings: [],
+      data: { commsDir }
+    };
+  }
+}
+function commsPush(commsDir) {
+  logHeader("tap comms push");
+  if (!isGitRepo(commsDir)) {
+    logError(`${commsDir} is not a git repository`);
+    return {
+      ok: false,
+      command: "comms",
+      code: "TAP_COMMS_NOT_REPO",
+      message: `Comms directory is not a git repo. Use 'tap init --comms-repo <url>' to set up.`,
+      warnings: [],
+      data: { commsDir }
+    };
+  }
+  try {
+    execSync8("git add -A", { cwd: commsDir, stdio: "pipe" });
+    const status = execSync8("git status --porcelain", {
+      cwd: commsDir,
+      encoding: "utf-8",
+      stdio: "pipe"
+    }).trim();
+    if (!status) {
+      log("Nothing to push \u2014 comms directory is clean");
+      return {
+        ok: true,
+        command: "comms",
+        code: "TAP_COMMS_PUSH_OK",
+        message: "Nothing to push",
+        warnings: [],
+        data: { commsDir, changed: false }
+      };
+    }
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    execSync8(`git commit -m "chore(comms): sync ${timestamp}"`, {
+      cwd: commsDir,
+      stdio: "pipe"
+    });
+    execSync8("git push", { cwd: commsDir, stdio: "pipe" });
+    logSuccess("Comms push complete");
+    return {
+      ok: true,
+      command: "comms",
+      code: "TAP_COMMS_PUSH_OK",
+      message: "Comms push complete",
+      warnings: [],
+      data: { commsDir, changed: true }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError(`Push failed: ${msg}`);
+    return {
+      ok: false,
+      command: "comms",
+      code: "TAP_COMMS_PUSH_FAILED",
+      message: `Push failed: ${msg}`,
+      warnings: [],
+      data: { commsDir }
+    };
+  }
+}
+async function commsCommand(args) {
+  const subcommand = args[0];
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    log(COMMS_HELP);
+    return {
+      ok: true,
+      command: "comms",
+      code: "TAP_NO_OP",
+      message: COMMS_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
+  const repoRoot = findRepoRoot();
+  const commsDir = resolveCommsDir(args, repoRoot);
+  switch (subcommand) {
+    case "pull":
+      return commsPull(commsDir);
+    case "push":
+      return commsPush(commsDir);
+    default:
+      return {
+        ok: false,
+        command: "comms",
+        code: "TAP_INVALID_ARGUMENT",
+        message: `Unknown comms subcommand: ${subcommand}. Use pull or push.`,
+        warnings: [],
+        data: {}
+      };
+  }
+}
+
 // src/output.ts
 function emitResult(result, jsonMode) {
   if (jsonMode) {
@@ -5777,6 +6422,7 @@ Commands:
   bridge <sub> [inst]   Manage bridges (start, stop, status)
   up                    Start all registered bridge daemons
   down                  Stop all running bridge daemons
+  comms <pull|push>     Sync comms directory with remote repo
   dashboard             Show unified ops dashboard
   doctor                Diagnose tap infrastructure health
   serve                 Start tap-comms MCP server (stdio)
@@ -5804,6 +6450,7 @@ function normalizeCommandName(command) {
     case "bridge":
     case "up":
     case "down":
+    case "comms":
     case "dashboard":
     case "doctor":
     case "serve":
@@ -5861,6 +6508,9 @@ async function main() {
       case "down":
         result = await downCommand(commandArgs);
         break;
+      case "comms":
+        result = await commsCommand(commandArgs);
+        break;
       case "dashboard":
         result = await dashboardCommand(commandArgs);
         break;