@hua-labs/tap 0.2.3 → 0.2.5

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 // src/commands/init.ts
 import * as fs6 from "fs";
 import * as path6 from "path";
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 
 // src/state.ts
 import * as fs3 from "fs";
@@ -23,9 +23,16 @@ function detectPlatform() {
   return process.platform;
 }
 var _noGitWarned = false;
+var _loggedWarnings = /* @__PURE__ */ new Set();
 function _setNoGitWarned() {
   _noGitWarned = true;
 }
+function resetLoggedWarnings() {
+  _loggedWarnings.clear();
+}
+function wasWarningLogged(message) {
+  return _loggedWarnings.has(message);
+}
 function findRepoRoot(startDir = process.cwd()) {
   let dir = path.resolve(startDir);
   while (true) {
@@ -33,8 +40,8 @@ function findRepoRoot(startDir = process.cwd()) {
     if (fs.existsSync(path.join(dir, "package.json"))) {
       if (!_noGitWarned) {
         _setNoGitWarned();
-        logWarn(
-          "No .git directory found. Resolved repo root via package.json \u2014 comms directory may be created in an unexpected location. Use --comms-dir to specify explicitly."
+        log(
+          "No .git directory found. Resolved tap root via package.json. That's fine outside git; use --comms-dir to choose a different comms location."
         );
       }
       return dir;
@@ -45,8 +52,8 @@ function findRepoRoot(startDir = process.cwd()) {
   }
   if (!_noGitWarned) {
     _setNoGitWarned();
-    logWarn(
-      "No git repository or package.json found. Using current directory as root. Run 'git init' first, or use --comms-dir to specify the comms path."
+    log(
+      "No git repository or package.json found. Using the current directory as tap root. That's fine outside git; use --comms-dir to choose a different comms location."
     );
   }
   return process.cwd();
@@ -101,7 +108,9 @@ function logSuccess(message) {
   if (!_jsonMode) console.log(`  + ${message}`);
 }
 function logWarn(message) {
-  if (!_jsonMode) console.log(`  ! ${message}`);
+  if (_jsonMode) return;
+  _loggedWarnings.add(message);
+  console.log(`  ! ${message}`);
 }
 function logError(message) {
   if (!_jsonMode) console.error(`  x ${message}`);
@@ -111,6 +120,16 @@ function logHeader(message) {
   ${message}
 `);
 }
+function parseIntFlag(value, name, min, max) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw new RangeError(
+      `Invalid ${name}: ${value}. Must be an integer between ${min} and ${max}.`
+    );
+  }
+  return parsed;
+}
 function resolveInstanceId(identifier, state) {
   if (state.instances[identifier]) {
     return { ok: true, instanceId: identifier };
@@ -160,8 +179,8 @@ function findRepoRoot2(startDir = process.cwd()) {
     if (fs2.existsSync(path2.join(dir, "package.json"))) {
       if (!_noGitWarned) {
         _setNoGitWarned();
-        console.error(
-          "[tap] warning: No .git directory found. Resolved via package.json. Use --comms-dir to specify explicitly."
+        log(
+          "No .git directory found. Resolved tap root via package.json. That's fine outside git; use --comms-dir to choose a different comms location."
         );
       }
       return dir;
@@ -172,8 +191,8 @@ function findRepoRoot2(startDir = process.cwd()) {
   }
   if (!_noGitWarned) {
     _setNoGitWarned();
-    console.error(
-      "[tap] warning: No git repository found. Using cwd as root. Run 'git init' or use --comms-dir."
+    log(
+      "No git repository or package.json found. Using the current directory as tap root. That's fine outside git; use --comms-dir to choose a different comms location."
     );
   }
   return process.cwd();
@@ -187,7 +206,7 @@ function loadJsonFile(filePath) {
     return null;
   }
 }
-function loadSharedConfig2(repoRoot) {
+function loadSharedConfig(repoRoot) {
   return loadJsonFile(path2.join(repoRoot, SHARED_CONFIG_FILE));
 }
 function loadLocalConfig(repoRoot) {
@@ -211,7 +230,7 @@ function loadLegacyShellConfig(repoRoot) {
 }
 function resolveConfig(overrides = {}, startDir) {
   const repoRoot = findRepoRoot2(startDir);
-  const shared = loadSharedConfig2(repoRoot) ?? {};
+  const shared = loadSharedConfig(repoRoot) ?? {};
   const local = loadLocalConfig(repoRoot) ?? {};
   const legacy = loadLegacyShellConfig(repoRoot) ?? {};
   const sources = {
@@ -754,7 +773,39 @@ function parsePermissionMode(args) {
   }
   return "safe";
 }
+var INIT_HELP = `
+Usage:
+  tap init [options]
+
+Description:
+  Initialize the tap directory structure, state file, and permissions.
+  Optionally clone a shared comms repository.
+
+Options:
+  --comms-dir <path>    Override comms directory (default: tap-comms/)
+  --comms-repo <url>    Clone a shared comms git repo into comms directory
+  --permissions <mode>  Permission mode: safe (default) or full
+  --force               Re-initialize even if already set up
+  --help, -h            Show help
+
+Examples:
+  npx @hua-labs/tap init
+  npx @hua-labs/tap init --permissions full
+  npx @hua-labs/tap init --comms-repo https://github.com/org/comms.git
+  npx @hua-labs/tap init --comms-dir /shared/comms --force
+`.trim();
 async function initCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log(INIT_HELP);
+    return {
+      ok: true,
+      command: "init",
+      code: "TAP_NO_OP",
+      message: INIT_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const repoRoot = findRepoRoot();
   const commsDir = resolveCommsDir(args, repoRoot);
   const permMode = parsePermissionMode(args);
@@ -791,10 +842,19 @@ async function initCommand(args) {
     } else {
       log(`Cloning comms repo: ${commsRepoUrl}`);
       try {
-        execSync(`git clone "${commsRepoUrl}" "${commsDir}"`, {
-          stdio: "pipe",
-          encoding: "utf-8"
-        });
+        const cloneResult = spawnSync(
+          "git",
+          ["clone", commsRepoUrl, commsDir],
+          {
+            stdio: "pipe",
+            encoding: "utf-8"
+          }
+        );
+        if (cloneResult.status !== 0) {
+          throw new Error(
+            cloneResult.stderr || `git clone exited with code ${cloneResult.status}`
+          );
+        }
         logSuccess(`Cloned comms repo to ${commsDir}`);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -811,7 +871,7 @@ async function initCommand(args) {
     }
   }
   {
-    const sharedConfig = loadSharedConfig2(repoRoot) ?? {};
+    const sharedConfig = loadSharedConfig(repoRoot) ?? {};
     let configChanged = false;
     if (commsRepoUrl) {
       sharedConfig.commsRepoUrl = commsRepoUrl;
@@ -903,17 +963,17 @@ ${entry}
 // src/adapters/claude.ts
 import * as fs8 from "fs";
 import * as path8 from "path";
-import { execSync as execSync2 } from "child_process";
+import { execSync } from "child_process";
 
 // src/adapters/common.ts
 import * as fs7 from "fs";
 import * as os2 from "os";
 import * as path7 from "path";
-import { spawnSync } from "child_process";
+import { spawnSync as spawnSync2 } from "child_process";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function probeCommand(candidates) {
   for (const candidate of candidates) {
-    const result = spawnSync(candidate, ["--version"], {
+    const result = spawnSync2(candidate, ["--version"], {
       encoding: "utf-8",
       shell: process.platform === "win32"
     });
@@ -991,7 +1051,7 @@ function findPreferredBunCommand() {
   const candidates = process.platform === "win32" ? [path7.join(home, ".bun", "bin", "bun.exe"), "bun", "bun.cmd"] : [path7.join(home, ".bun", "bin", "bun"), "bun"];
   for (const candidate of candidates) {
     if (path7.isAbsolute(candidate) && !fs7.existsSync(candidate)) continue;
-    const result = spawnSync(candidate, ["--version"], {
+    const result = spawnSync2(candidate, ["--version"], {
       encoding: "utf-8",
       shell: process.platform === "win32"
     });
@@ -1017,7 +1077,7 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
   }
   if (!sourcePath) {
     issues.push(
-      "tap-comms MCP server entry not found. Reinstall @hua-labs/tap or run from a repo with packages/tap-plugin/channels/ available."
+      "tap MCP server entry not found. Reinstall @hua-labs/tap or run from a repo with packages/tap-plugin/channels/ available."
     );
     return { command: null, args: [], env, sourcePath, warnings, issues };
   }
@@ -1047,7 +1107,7 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
   }
   if (!command) {
     issues.push(
-      "bun is required to run the repo-local tap-comms MCP server (.ts source). Install bun: https://bun.sh"
+      "bun is required to run the repo-local tap MCP server (.ts source). Install bun: https://bun.sh"
     );
     return { command: null, args: [], env, sourcePath, warnings, issues };
   }
@@ -1062,13 +1122,14 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
 }
 
 // src/adapters/claude.ts
-var MCP_SERVER_KEY = "tap-comms";
+var MCP_SERVER_KEY = "tap";
+var OLD_MCP_SERVER_KEY = "tap-comms";
 function findMcpJsonPath(ctx) {
   return path8.join(ctx.repoRoot, ".mcp.json");
 }
 function findClaudeCommand() {
   try {
-    execSync2("claude --version", { stdio: "pipe" });
+    execSync("claude --version", { stdio: "pipe" });
     return "claude";
   } catch {
     return null;
@@ -1140,6 +1201,11 @@ var claudeAdapter = {
             `Existing "${MCP_SERVER_KEY}" entry in .mcp.json will be overwritten.`
           );
         }
+        if (config.mcpServers?.[OLD_MCP_SERVER_KEY]) {
+          conflicts.push(
+            `Legacy "${OLD_MCP_SERVER_KEY}" entry will be migrated to "${MCP_SERVER_KEY}".`
+          );
+        }
       } catch {
         warnings.push(
           ".mcp.json exists but is not valid JSON. Will be overwritten."
@@ -1149,7 +1215,7 @@ var claudeAdapter = {
     const serverEntry = buildMcpServerEntry(ctx);
     if (!serverEntry) {
       warnings.push(
-        "tap-comms MCP server entry not found. Skipping .mcp.json patch. Reinstall @hua-labs/tap or run from a repo with packages/tap-plugin/channels/ available."
+        "tap MCP server entry not found. Skipping .mcp.json patch. Reinstall @hua-labs/tap or run from a repo with packages/tap-plugin/channels/ available."
       );
       return {
         runtime: "claude",
@@ -1202,6 +1268,10 @@ var claudeAdapter = {
               );
             }
           }
+          const servers = config.mcpServers;
+          if (servers?.[OLD_MCP_SERVER_KEY]) {
+            delete servers[OLD_MCP_SERVER_KEY];
+          }
           if (op.key) {
             setNestedKey(config, op.key, op.value);
           }
@@ -1250,7 +1320,7 @@ var claudeAdapter = {
           checks.push({ name: "Config is valid JSON", passed: true });
           const entry = config.mcpServers?.[MCP_SERVER_KEY];
           checks.push({
-            name: "tap-comms entry present",
+            name: "tap entry present",
             passed: !!entry,
             message: entry ? void 0 : `mcpServers.${MCP_SERVER_KEY} not found`
           });
@@ -1343,8 +1413,10 @@ function readArtifactBackup(backupPath) {
 }
 
 // src/adapters/codex.ts
-var MCP_SELECTOR = "mcp_servers.tap-comms";
-var ENV_SELECTOR = "mcp_servers.tap-comms.env";
+var MCP_SELECTOR = "mcp_servers.tap";
+var ENV_SELECTOR = "mcp_servers.tap.env";
+var OLD_MCP_SELECTOR = "mcp_servers.tap-comms";
+var OLD_ENV_SELECTOR = "mcp_servers.tap-comms.env";
 function findCodexConfigPath2() {
   return path10.join(getHomeDir(), ".codex", "config.toml");
 }
@@ -1398,12 +1470,12 @@ function verifyManagedToml(content, ctx, configPath) {
     message: fs10.existsSync(configPath) ? void 0 : `${configPath} not found`
   });
   checks.push({
-    name: "tap-comms MCP table present",
+    name: "tap MCP table present",
     passed: !!mainTable,
     message: mainTable ? void 0 : `${MCP_SELECTOR} not found`
   });
   checks.push({
-    name: "tap-comms env table present",
+    name: "tap env table present",
     passed: !!envTable,
     message: envTable ? void 0 : `${ENV_SELECTOR} not found`
   });
@@ -1423,7 +1495,7 @@ function verifyManagedToml(content, ctx, configPath) {
       passed: mainTable.includes(
         `command = "${managed.command.replace(/\\/g, "\\\\")}"`
       ) && mainTable.includes(`args = [${expectedArgs}]`),
-      message: "Managed tap-comms command/args do not match expected values"
+      message: "Managed tap command/args do not match expected values"
     });
   }
   return checks;
@@ -1473,6 +1545,11 @@ var codexAdapter = {
       if (extractTomlTable(content, MCP_SELECTOR)) {
         conflicts.push(`Existing ${MCP_SELECTOR} table will be updated.`);
       }
+      if (extractTomlTable(content, OLD_MCP_SELECTOR)) {
+        conflicts.push(
+          `Legacy ${OLD_MCP_SELECTOR} table will be migrated to ${MCP_SELECTOR}.`
+        );
+      }
       if (extractTomlTable(content, ENV_SELECTOR)) {
         conflicts.push(`Existing ${ENV_SELECTOR} table will be updated.`);
       }
@@ -1538,6 +1615,12 @@ var codexAdapter = {
       return { ...artifact, backupPath };
     });
     let nextContent = existingContent;
+    if (extractTomlTable(nextContent, OLD_ENV_SELECTOR)) {
+      nextContent = removeTomlTable(nextContent, OLD_ENV_SELECTOR);
+    }
+    if (extractTomlTable(nextContent, OLD_MCP_SELECTOR)) {
+      nextContent = removeTomlTable(nextContent, OLD_MCP_SELECTOR);
+    }
     nextContent = replaceTomlTable(
       nextContent,
       MCP_SELECTOR,
@@ -1651,7 +1734,8 @@ var codexAdapter = {
 // src/adapters/gemini.ts
 import * as fs11 from "fs";
 import * as path11 from "path";
-var GEMINI_SELECTOR = "mcpServers.tap-comms";
+var GEMINI_SELECTOR = "mcpServers.tap";
+var OLD_GEMINI_SELECTOR = "mcpServers.tap-comms";
 function candidateConfigPaths(ctx) {
   const home = getHomeDir();
   return [
@@ -1713,7 +1797,7 @@ function verifyGeminiConfig(config, configPath, ctx) {
     message: fs11.existsSync(configPath) ? void 0 : `${configPath} not found`
   });
   checks.push({
-    name: "tap-comms entry present",
+    name: "tap entry present",
     passed: !!entry,
     message: entry ? void 0 : `${GEMINI_SELECTOR} not found`
   });
@@ -1779,6 +1863,11 @@ var geminiAdapter = {
         if (readNestedKey(config, GEMINI_SELECTOR) !== void 0) {
           conflicts.push(`Existing ${GEMINI_SELECTOR} entry will be updated.`);
         }
+        if (readNestedKey(config, OLD_GEMINI_SELECTOR) !== void 0) {
+          conflicts.push(
+            `Legacy ${OLD_GEMINI_SELECTOR} entry will be migrated to ${GEMINI_SELECTOR}.`
+          );
+        }
       } catch {
         warnings.push(
           `${configPath} exists but is not valid JSON. It will be replaced.`
@@ -1846,6 +1935,13 @@ var geminiAdapter = {
       existed: previousValue !== void 0,
       value: previousValue
     });
+    const oldValue = readNestedKey(config, OLD_GEMINI_SELECTOR);
+    if (oldValue !== void 0) {
+      const servers = config.mcpServers;
+      if (servers) {
+        delete servers["tap-comms"];
+      }
+    }
     setNestedKey2(config, GEMINI_SELECTOR, {
       command: managed.command,
       args: managed.args,
@@ -1927,15 +2023,16 @@ function getAdapter(runtime) {
 // src/engine/bridge.ts
 import * as fs13 from "fs";
 import * as net from "net";
+import * as os3 from "os";
 import * as path13 from "path";
 import { randomBytes } from "crypto";
-import { spawn, spawnSync as spawnSync2, execSync as execSync4 } from "child_process";
+import { spawn, spawnSync as spawnSync3, execSync as execSync3 } 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 execSync3 } from "child_process";
+import { execSync as execSync2 } from "child_process";
 function readNodeVersion(repoRoot) {
   const nvFile = path12.join(repoRoot, ".node-version");
   if (!fs12.existsSync(nvFile)) return null;
@@ -1978,7 +2075,7 @@ function probeFnmNode(desiredVersion) {
     );
     if (!fs12.existsSync(candidate)) continue;
     try {
-      const v = execSync3(`"${candidate}" --version`, {
+      const v = execSync2(`"${candidate}" --version`, {
         encoding: "utf-8",
         timeout: 5e3
       }).trim();
@@ -1992,7 +2089,7 @@ function probeFnmNode(desiredVersion) {
 }
 function detectNodeMajorVersion(command) {
   try {
-    const version2 = execSync3(`"${command}" --version`, {
+    const version2 = execSync2(`"${command}" --version`, {
       encoding: "utf-8",
       timeout: 5e3
     }).trim();
@@ -2006,7 +2103,7 @@ function checkStripTypesSupport(command) {
   const major = detectNodeMajorVersion(command);
   if (major !== null && major >= 22) return true;
   try {
-    execSync3(`"${command}" --experimental-strip-types -e ""`, {
+    execSync2(`"${command}" --experimental-strip-types -e ""`, {
       timeout: 5e3,
       stdio: "pipe"
     });
@@ -2097,8 +2194,10 @@ var APP_SERVER_HEALTH_TIMEOUT_MS = 1500;
 var APP_SERVER_START_TIMEOUT_MS = 2e4;
 var APP_SERVER_GATEWAY_START_TIMEOUT_MS = 5e3;
 var APP_SERVER_HEALTH_RETRY_MS = 250;
-var APP_SERVER_AUTH_QUERY_PARAM = "tap_token";
+var AUTH_SUBPROTOCOL_PREFIX = "tap-auth-";
 var APP_SERVER_AUTH_FILE_MODE = 384;
+var WINDOWS_SPAWN_WRAPPER_PREFIX = "tap-spawn-";
+var WINDOWS_SPAWN_WRAPPER_STALE_MS = 60 * 60 * 1e3;
 function appServerLogFilePath(stateDir, instanceId) {
   return path13.join(stateDir, "logs", `app-server-${instanceId}.log`);
 }
@@ -2135,12 +2234,66 @@ function removeFileIfExists(filePath) {
   } catch {
   }
 }
+function toPowerShellSingleQuotedString(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function toPowerShellStringArrayLiteral(values) {
+  return `@(${values.map(toPowerShellSingleQuotedString).join(", ")})`;
+}
+function cleanupStaleWindowsSpawnWrappers(now = Date.now()) {
+  let entries;
+  try {
+    entries = fs13.readdirSync(os3.tmpdir());
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.startsWith(WINDOWS_SPAWN_WRAPPER_PREFIX) || !/\.(cmd|ps1)$/i.test(entry)) {
+      continue;
+    }
+    const wrapperPath = path13.join(os3.tmpdir(), entry);
+    try {
+      const stats = fs13.statSync(wrapperPath);
+      if (now - stats.mtimeMs < WINDOWS_SPAWN_WRAPPER_STALE_MS) {
+        continue;
+      }
+      fs13.unlinkSync(wrapperPath);
+    } catch {
+    }
+  }
+}
+function buildWindowsDetachedWrapperScript(command, args, logPath, stderrLogPath, env) {
+  const lines = ["$ErrorActionPreference = 'Stop'"];
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== void 0 && value !== process.env[key]) {
+      lines.push(
+        `[Environment]::SetEnvironmentVariable(${toPowerShellSingleQuotedString(key)}, ${toPowerShellSingleQuotedString(value)}, 'Process')`
+      );
+    }
+  }
+  lines.push(
+    `$logPath = ${toPowerShellSingleQuotedString(logPath)}`,
+    `$stderrLogPath = ${toPowerShellSingleQuotedString(stderrLogPath)}`,
+    `$commandPath = ${toPowerShellSingleQuotedString(command)}`,
+    `$commandArgs = ${toPowerShellStringArrayLiteral(args)}`,
+    "$exitCode = 1",
+    "try {",
+    "  & $commandPath @commandArgs >> $logPath 2>> $stderrLogPath",
+    "  $exitCode = if ($null -ne $LASTEXITCODE) { $LASTEXITCODE } else { 0 }",
+    "} finally {",
+    "  Remove-Item -LiteralPath $PSCommandPath -Force -ErrorAction SilentlyContinue",
+    "}",
+    "exit $exitCode"
+  );
+  return `${lines.join("\r\n")}\r
+`;
+}
 function getWebSocketCtor() {
   const candidate = globalThis.WebSocket;
   return typeof candidate === "function" ? candidate : null;
 }
 function delay(ms) {
-  return new Promise((resolve11) => setTimeout(resolve11, ms));
+  return new Promise((resolve13) => setTimeout(resolve13, ms));
 }
 function isLoopbackHost(hostname) {
   return hostname === "127.0.0.1" || hostname === "localhost";
@@ -2158,8 +2311,11 @@ function resolvePowerShellCommand() {
 function resolveAuthGatewayScript(repoRoot) {
   const moduleDir = path13.dirname(fileURLToPath4(import.meta.url));
   const candidates = [
-    path13.join(moduleDir, "..", "bridges", "codex-app-server-auth-gateway.mjs"),
-    path13.join(moduleDir, "..", "bridges", "codex-app-server-auth-gateway.ts"),
+    // Bundled: dist/bridges/ sibling (npm install / built package)
+    path13.join(moduleDir, "bridges", "codex-app-server-auth-gateway.mjs"),
+    // Source: src/bridges/ sibling (monorepo dev with ts runner)
+    path13.join(moduleDir, "bridges", "codex-app-server-auth-gateway.ts"),
+    // Monorepo dist fallback
     path13.join(
       repoRoot,
       "packages",
@@ -2189,7 +2345,7 @@ function getBridgeRuntimeStateDir(repoRoot, instanceId) {
 }
 async function allocateLoopbackPort(hostname) {
   const bindHost = hostname === "localhost" ? "127.0.0.1" : hostname;
-  return await new Promise((resolve11, reject) => {
+  return await new Promise((resolve13, reject) => {
     const server = net.createServer();
     server.unref();
     server.once("error", reject);
@@ -2207,15 +2363,13 @@ async function allocateLoopbackPort(hostname) {
           reject(error);
           return;
         }
-        resolve11(port);
+        resolve13(port);
       });
     });
   });
 }
-function buildProtectedAppServerUrl(publicUrl, token) {
-  const url = new URL(publicUrl);
-  url.searchParams.set(APP_SERVER_AUTH_QUERY_PARAM, token);
-  return url.toString().replace(/\/(?=\?|$)/, "");
+function buildProtectedAppServerUrl(publicUrl, _token) {
+  return publicUrl;
 }
 function readGatewayTokenFromPath(tokenPath) {
   return fs13.readFileSync(tokenPath, "utf8").trim();
@@ -2330,7 +2484,7 @@ async function createManagedAppServerAuth(options) {
     throw new Error("Failed to spawn app-server auth gateway");
   }
   return {
-    mode: "query-token",
+    mode: "subprotocol",
     protectedUrl,
     upstreamUrl: upstreamUrl.toString().replace(/\/$/, ""),
     tokenPath,
@@ -2392,35 +2546,50 @@ function findReusableManagedAppServer(stateDir, publicUrl) {
   return null;
 }
 function startWindowsDetachedProcess(command, args, repoRoot, logPath, env = process.env) {
-  const ext = path13.extname(command).toLowerCase();
   const stderrLogPath = stderrLogFilePath(logPath);
-  const stdoutFd = fs13.openSync(logPath, "a");
-  const stderrFd = fs13.openSync(stderrLogPath, "a");
-  try {
-    const child = ext === ".ps1" ? spawn(
-      resolvePowerShellCommand(),
-      ["-NoLogo", "-NoProfile", "-File", command, ...args],
-      {
-        cwd: repoRoot,
-        detached: true,
-        stdio: ["ignore", stdoutFd, stderrFd],
-        env,
-        windowsHide: true
-      }
-    ) : spawn(command, args, {
-      cwd: repoRoot,
-      detached: true,
-      stdio: ["ignore", stdoutFd, stderrFd],
-      env,
-      windowsHide: true,
-      shell: ext === ".cmd" || ext === ".bat"
-    });
-    child.unref();
-    return child.pid ?? null;
-  } finally {
-    fs13.closeSync(stdoutFd);
-    fs13.closeSync(stderrFd);
+  const powerShellCommand = resolvePowerShellCommand();
+  cleanupStaleWindowsSpawnWrappers();
+  const wrapperPath = path13.join(
+    os3.tmpdir(),
+    `${WINDOWS_SPAWN_WRAPPER_PREFIX}${randomBytes(4).toString("hex")}.ps1`
+  );
+  fs13.writeFileSync(
+    wrapperPath,
+    buildWindowsDetachedWrapperScript(
+      command,
+      args,
+      logPath,
+      stderrLogPath,
+      env
+    )
+  );
+  const psCommand = [
+    "$p = Start-Process",
+    `-FilePath ${toPowerShellSingleQuotedString(powerShellCommand)}`,
+    `-ArgumentList ${toPowerShellStringArrayLiteral(["-NoLogo", "-NoProfile", "-File", wrapperPath])}`,
+    `-WorkingDirectory ${toPowerShellSingleQuotedString(repoRoot)}`,
+    "-WindowStyle Hidden",
+    "-PassThru",
+    "; Write-Output $p.Id"
+  ].join(" ");
+  const result = spawnSync3(
+    powerShellCommand,
+    ["-NoLogo", "-NoProfile", "-Command", psCommand],
+    {
+      encoding: "utf-8",
+      windowsHide: true
+    }
+  );
+  if (result.status !== 0) {
+    removeFileIfExists(wrapperPath);
+    return null;
   }
+  const pid = parseInt(result.stdout.trim(), 10);
+  if (!Number.isFinite(pid)) {
+    removeFileIfExists(wrapperPath);
+    return null;
+  }
+  return pid;
 }
 function startWindowsCodexAppServer(command, url, repoRoot, logPath) {
   return startWindowsDetachedProcess(
@@ -2444,7 +2613,7 @@ function findListeningProcessId(url, platform) {
   if (port == null || !Number.isFinite(port)) {
     return null;
   }
-  const result = spawnSync2(
+  const result = spawnSync3(
     resolvePowerShellCommand(),
     [
       "-NoLogo",
@@ -2482,12 +2651,12 @@ function resolveAppServerUrl(baseUrl, port) {
 }
 async function isTcpPortAvailable(hostname, port) {
   const bindHost = hostname === "localhost" ? "127.0.0.1" : hostname;
-  return await new Promise((resolve11) => {
+  return await new Promise((resolve13) => {
     const server = net.createServer();
     server.unref();
-    server.once("error", () => resolve11(false));
+    server.once("error", () => resolve13(false));
     server.listen(port, bindHost, () => {
-      server.close((error) => resolve11(!error));
+      server.close((error) => resolve13(!error));
     });
   });
 }
@@ -2517,12 +2686,12 @@ async function findNextAvailableAppServerPort(state, baseUrl, basePort = 4501, e
     `Failed to find a free app-server port starting at ${basePort}`
   );
 }
-async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_MS) {
+async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_MS, gatewayToken) {
   const WebSocket = getWebSocketCtor();
   if (!WebSocket) {
     return false;
   }
-  return new Promise((resolve11) => {
+  return new Promise((resolve13) => {
     let settled = false;
     let socket = null;
     const finish = (healthy) => {
@@ -2535,11 +2704,12 @@ async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_M
         socket?.close();
       } catch {
       }
-      resolve11(healthy);
+      resolve13(healthy);
     };
     const timer = setTimeout(() => finish(false), timeoutMs);
     try {
-      socket = new WebSocket(url);
+      const protocols = gatewayToken ? [`${AUTH_SUBPROTOCOL_PREFIX}${gatewayToken}`] : void 0;
+      socket = new WebSocket(url, protocols);
       socket.addEventListener("open", () => finish(true), { once: true });
       socket.addEventListener("error", () => finish(false), { once: true });
       socket.addEventListener("close", () => finish(false), { once: true });
@@ -2548,10 +2718,14 @@ async function checkAppServerHealth(url, timeoutMs = APP_SERVER_HEALTH_TIMEOUT_M
     }
   });
 }
-async function waitForAppServerHealth(url, timeoutMs) {
+async function waitForAppServerHealth(url, timeoutMs, gatewayToken) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    if (await checkAppServerHealth(url)) {
+    if (await checkAppServerHealth(
+      url,
+      APP_SERVER_HEALTH_TIMEOUT_MS,
+      gatewayToken
+    )) {
       return true;
     }
     await delay(APP_SERVER_HEALTH_RETRY_MS);
@@ -2564,7 +2738,7 @@ async function terminateProcess(pid, platform) {
   }
   try {
     if (platform === "win32") {
-      execSync4(`taskkill /PID ${pid} /F /T`, { stdio: "pipe" });
+      execSync3(`taskkill /PID ${pid} /F /T`, { stdio: "pipe" });
     } else {
       process.kill(pid, "SIGTERM");
       await delay(2e3);
@@ -2816,8 +2990,9 @@ Or start it manually:
     throw new Error("Tap auth gateway token is missing after startup.");
   }
   const gatewayHealthy = await waitForAppServerHealth(
-    buildProtectedAppServerUrl(effectiveUrl, gatewayToken),
-    APP_SERVER_GATEWAY_START_TIMEOUT_MS
+    effectiveUrl,
+    APP_SERVER_GATEWAY_START_TIMEOUT_MS,
+    gatewayToken
   );
   if (!gatewayHealthy) {
     await terminateProcess(pid, options.platform);
@@ -2853,7 +3028,11 @@ function logFilePath(stateDir, instanceId) {
 function runtimeHeartbeatFilePath(runtimeStateDir) {
   return path13.join(runtimeStateDir, "heartbeat.json");
 }
-function loadRuntimeHeartbeatTimestamp(runtimeStateDir) {
+function runtimeThreadStateFilePath(runtimeStateDir) {
+  return path13.join(runtimeStateDir, "thread.json");
+}
+function loadRuntimeBridgeHeartbeat(bridgeState) {
+  const runtimeStateDir = bridgeState?.runtimeStateDir;
   if (!runtimeStateDir) {
     return null;
   }
@@ -2862,13 +3041,35 @@ function loadRuntimeHeartbeatTimestamp(runtimeStateDir) {
     return null;
   }
   try {
-    const raw = fs13.readFileSync(heartbeatPath, "utf-8");
-    const parsed = JSON.parse(raw);
-    return typeof parsed.updatedAt === "string" ? parsed.updatedAt : null;
+    return JSON.parse(
+      fs13.readFileSync(heartbeatPath, "utf-8")
+    );
   } catch {
     return null;
   }
 }
+function loadRuntimeBridgeThreadState(bridgeState) {
+  const runtimeStateDir = bridgeState?.runtimeStateDir;
+  if (!runtimeStateDir) {
+    return null;
+  }
+  const threadPath = runtimeThreadStateFilePath(runtimeStateDir);
+  if (!fs13.existsSync(threadPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(
+      fs13.readFileSync(threadPath, "utf-8")
+    );
+    return parsed.threadId ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function loadRuntimeHeartbeatTimestamp(runtimeStateDir) {
+  const heartbeat = loadRuntimeBridgeHeartbeat({ runtimeStateDir });
+  return typeof heartbeat?.updatedAt === "string" ? heartbeat.updatedAt : null;
+}
 function resolveHeartbeatTimestamp(state) {
   return loadRuntimeHeartbeatTimestamp(state?.runtimeStateDir) ?? state?.lastHeartbeat ?? null;
 }
@@ -3038,6 +3239,7 @@ async function startBridge(options) {
           options.messageLookbackMinutes
         )
       } : {},
+      ...process.env.TAP_COLD_START_WARMUP === "true" ? { TAP_COLD_START_WARMUP: "true" } : {},
       ...options.threadId ? { TAP_THREAD_ID: options.threadId } : {},
       ...options.ephemeral ? { TAP_EPHEMERAL: "true" } : {},
       ...options.processExistingMessages ? { TAP_PROCESS_EXISTING: "true" } : {}
@@ -3169,8 +3371,49 @@ function getBridgeStatus(stateDir, instanceId) {
 }
 
 // src/commands/add.ts
+var ADD_HELP = `
+Usage:
+  tap add <claude|codex|gemini> [options]
+
+Description:
+  Install a runtime instance and configure it to use tap.
+
+Options:
+  --name <name>         Instance name (default: runtime name)
+  --port <port>         Port for app-server bridge
+  --agent-name <name>   Agent display name for bridge identification
+  --force               Re-install even if already configured
+  --headless            Enable headless reviewer mode (requires --name)
+  --role <role>         Headless role: reviewer, validator, long-running
+  --help, -h            Show help
+
+Examples:
+  npx @hua-labs/tap add claude
+  npx @hua-labs/tap add codex --name reviewer --port 4501 --headless --role reviewer
+`.trim();
+function normalizeAgentName(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+function resolveAgentName2(options) {
+  return normalizeAgentName(options.explicit) ?? normalizeAgentName(options.stored) ?? normalizeAgentName(options.env) ?? normalizeAgentName(options.fallback) ?? null;
+}
 async function addCommand(args) {
   const { positional, flags } = parseArgs(args);
+  if (flags["help"] === true || flags["h"] === true) {
+    log(ADD_HELP);
+    return {
+      ok: true,
+      command: "add",
+      code: "TAP_NO_OP",
+      message: ADD_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const runtimeArg = positional[0];
   if (!runtimeArg) {
     return {
@@ -3196,8 +3439,10 @@ async function addCommand(args) {
   const instanceName = typeof flags["name"] === "string" ? flags["name"] : void 0;
   const instanceId = buildInstanceId(runtime, instanceName);
   const portStr = typeof flags["port"] === "string" ? flags["port"] : void 0;
-  const port = portStr ? parseInt(portStr, 10) : null;
-  const agentNameFlag = typeof flags["agent-name"] === "string" ? flags["agent-name"] : null;
+  const port = portStr ? Number(portStr) : null;
+  const agentNameFlag = normalizeAgentName(
+    typeof flags["agent-name"] === "string" ? flags["agent-name"] : null
+  );
   const force = flags["force"] === true;
   const headlessFlag = flags["headless"] === true;
   const roleArg = typeof flags["role"] === "string" ? flags["role"] : void 0;
@@ -3232,20 +3477,21 @@ async function addCommand(args) {
     maxRounds: 5,
     qualitySeverityFloor: "high"
   } : null;
-  if (portStr && (port === null || isNaN(port))) {
+  if (portStr && (port === null || isNaN(port) || port < 1 || port > 65535)) {
     return {
       ok: false,
       command: "add",
       runtime,
       instanceId,
       code: "TAP_INVALID_ARGUMENT",
-      message: `Invalid port: ${portStr}`,
+      message: `Invalid port: ${portStr}. Must be between 1 and 65535.`,
       warnings: [],
       data: {}
     };
   }
   const repoRoot = findRepoRoot();
   const state = loadState(repoRoot);
+  const adapter = getAdapter(runtime);
   if (!state) {
     return {
       ok: false,
@@ -3258,7 +3504,39 @@ async function addCommand(args) {
       data: {}
     };
   }
-  if (state.instances[instanceId]?.installed && !force) {
+  const existingInstance = state.instances[instanceId];
+  const mode = adapter.bridgeMode();
+  const envAgentName = normalizeAgentName(
+    process.env.TAP_AGENT_NAME ?? process.env.CODEX_TAP_AGENT_NAME
+  );
+  const defaultAgentName = mode === "app-server" ? instanceId : null;
+  const resolvedAgentName = resolveAgentName2({
+    explicit: agentNameFlag,
+    env: envAgentName,
+    stored: existingInstance?.agentName ?? null,
+    fallback: defaultAgentName
+  });
+  if (existingInstance?.installed && !force) {
+    if (resolvedAgentName !== existingInstance.agentName) {
+      const updatedState = updateInstanceState(state, instanceId, {
+        ...existingInstance,
+        agentName: resolvedAgentName
+      });
+      saveState(repoRoot, updatedState);
+      return {
+        ok: true,
+        command: "add",
+        runtime,
+        instanceId,
+        code: "TAP_ADD_OK",
+        message: resolvedAgentName === null ? `${instanceId} updated` : `${instanceId} agent name updated to "${resolvedAgentName}".`,
+        warnings: [],
+        data: {
+          updatedFields: ["agentName"],
+          agentName: resolvedAgentName
+        }
+      };
+    }
     return {
       ok: true,
       command: "add",
@@ -3288,14 +3566,12 @@ async function addCommand(args) {
   logHeader(`@hua-labs/tap add ${instanceId}`);
   if (instanceName) log(`Instance name: ${instanceName}`);
   if (port !== null) log(`Port: ${port}`);
-  const existingAgentName = state.instances[instanceId]?.agentName ?? null;
-  const effectiveAgentName = agentNameFlag ?? existingAgentName ?? void 0;
+  if (resolvedAgentName) log(`Agent name: ${resolvedAgentName}`);
   const ctx = {
     ...createAdapterContext(state.commsDir, repoRoot),
     instanceId,
-    agentName: effectiveAgentName
+    agentName: resolvedAgentName ?? void 0
   };
-  const adapter = getAdapter(runtime);
   const warnings = [];
   log("Probing runtime...");
   const probe = await adapter.probe(ctx);
@@ -3375,7 +3651,6 @@ async function addCommand(args) {
     );
   }
   let bridge = null;
-  const mode = adapter.bridgeMode();
   if (mode === "app-server") {
     const bridgeScript = adapter.resolveBridgeScript?.(ctx);
     if (!bridgeScript) {
@@ -3383,36 +3658,34 @@ async function addCommand(args) {
       warnings.push("Bridge script not found. Run bridge manually.");
     } else {
       const { config: resolvedCfg } = resolveConfig({}, repoRoot);
-      {
-        log(`Starting bridge: ${bridgeScript}`);
-        try {
-          bridge = await startBridge({
-            instanceId,
-            runtime,
-            stateDir: ctx.stateDir,
-            commsDir: ctx.commsDir,
-            bridgeScript,
-            platform: ctx.platform,
-            agentName: agentNameFlag ?? void 0,
-            runtimeCommand: resolvedCfg.runtimeCommand,
-            appServerUrl: resolvedCfg.appServerUrl,
-            repoRoot,
-            port: port ?? void 0,
-            headless
-          });
-          logSuccess(`Bridge started (PID: ${bridge.pid})`);
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          logWarn(`Bridge not started: ${msg}`);
-          warnings.push(`Bridge not started: ${msg}`);
-        }
+      log(`Starting bridge: ${bridgeScript}`);
+      try {
+        bridge = await startBridge({
+          instanceId,
+          runtime,
+          stateDir: ctx.stateDir,
+          commsDir: ctx.commsDir,
+          bridgeScript,
+          platform: ctx.platform,
+          agentName: resolvedAgentName ?? void 0,
+          runtimeCommand: resolvedCfg.runtimeCommand,
+          appServerUrl: resolvedCfg.appServerUrl,
+          repoRoot,
+          port: port ?? void 0,
+          headless
+        });
+        logSuccess(`Bridge started (PID: ${bridge.pid})`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logWarn(`Bridge not started: ${msg}`);
+        warnings.push(`Bridge not started: ${msg}`);
       }
     }
   }
   const instanceState = {
     instanceId,
     runtime,
-    agentName: agentNameFlag ?? existingAgentName,
+    agentName: resolvedAgentName,
     port,
     installed: true,
     configPath: probe.configPath ?? "",
@@ -3424,7 +3697,7 @@ async function addCommand(args) {
     lastVerifiedAt: verify.ok ? (/* @__PURE__ */ new Date()).toISOString() : null,
     bridge,
     headless,
-    warnings: [...result.warnings, ...verify.warnings]
+    warnings: Array.from(/* @__PURE__ */ new Set([...result.warnings, ...verify.warnings]))
   };
   const newState = updateInstanceState(state, instanceId, instanceState);
   saveState(repoRoot, newState);
@@ -3432,6 +3705,13 @@ async function addCommand(args) {
   if (result.restartRequired) {
     logWarn(`Restart ${runtime} to pick up the new configuration.`);
   }
+  if (runtime === "claude") {
+    log("");
+    log("For real-time notifications:");
+    log("  claude --dangerously-load-development-channels server:tap-comms");
+    log("Or polling mode (tools still work):");
+    log("  claude");
+  }
   logHeader("Done!");
   return {
     ok: true,
@@ -3451,6 +3731,16 @@ async function addCommand(args) {
 }
 
 // src/commands/status.ts
+var STATUS_HELP = `
+Usage:
+  tap status
+
+Description:
+  Show all installed instances, their bridge status, and configuration info.
+
+Examples:
+  npx @hua-labs/tap status
+`.trim();
 function resolveStatus(inst, stateDir) {
   if (!inst.installed) return "not installed";
   switch (inst.bridgeMode) {
@@ -3477,7 +3767,18 @@ function instanceStatusLine(inst, status) {
   const warns = inst.warnings.length > 0 ? ` [${inst.warnings.length} warning(s)]` : "";
   return `${inst.instanceId.padEnd(20)} ${inst.runtime.padEnd(8)} ${status.padEnd(14)} ${mode.padEnd(14)}${bridgeInfo}${portStr}${restart}${warns}`;
 }
-async function statusCommand(_args) {
+async function statusCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log(STATUS_HELP);
+    return {
+      ok: true,
+      command: "status",
+      code: "TAP_NO_OP",
+      message: STATUS_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const repoRoot = findRepoRoot();
   const state = loadState(repoRoot);
   if (!state) {
@@ -3706,7 +4007,32 @@ function cleanEmptyParents(obj, keyPath) {
 }
 
 // src/commands/remove.ts
+var REMOVE_HELP = `
+Usage:
+  tap remove <instance>
+
+Description:
+  Remove a registered instance, stop its bridge, and rollback config changes.
+
+Arguments:
+  <instance>    Instance ID or runtime name (e.g. claude, codex-reviewer)
+
+Examples:
+  npx @hua-labs/tap remove claude
+  npx @hua-labs/tap remove codex-reviewer
+`.trim();
 async function removeCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log(REMOVE_HELP);
+    return {
+      ok: true,
+      command: "remove",
+      code: "TAP_NO_OP",
+      message: REMOVE_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const identifier = args.find((a) => !a.startsWith("-"));
   if (!identifier) {
     return {
@@ -3742,8 +4068,8 @@ async function removeCommand(args) {
     };
   }
   const instanceId = resolved.instanceId;
-  const instance = state.instances[instanceId];
-  if (!instance?.installed) {
+  const instance2 = state.instances[instanceId];
+  if (!instance2?.installed) {
     return {
       ok: true,
       command: "remove",
@@ -3755,7 +4081,7 @@ async function removeCommand(args) {
     };
   }
   logHeader(`@hua-labs/tap remove ${instanceId}`);
-  if (instance.bridge) {
+  if (instance2.bridge) {
     const ctx = createAdapterContext(state.commsDir, repoRoot);
     const stopped = await stopBridge({
       instanceId,
@@ -3768,7 +4094,7 @@ async function removeCommand(args) {
       log(`No running bridge for ${instanceId}`);
     }
   }
-  const result = await rollbackRuntime(instanceId, instance);
+  const result = await rollbackRuntime(instanceId, instance2);
   if (result.success) {
     logSuccess(`Rolled back ${result.restoredCount} artifact(s)`);
     for (const f of result.restoredFiles) logSuccess(`Restored: ${f}`);
@@ -3780,7 +4106,7 @@ async function removeCommand(args) {
       ok: true,
       command: "remove",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_REMOVE_OK",
       message: `${instanceId} removed successfully`,
       warnings: [],
@@ -3795,7 +4121,7 @@ async function removeCommand(args) {
     ok: false,
     command: "remove",
     instanceId,
-    runtime: instance.runtime,
+    runtime: instance2.runtime,
     code: "TAP_ROLLBACK_FAILED",
     message: "Rollback had errors. State preserved for retry.",
     warnings: result.errors,
@@ -3812,7 +4138,7 @@ function formatAge(seconds) {
 }
 var BRIDGE_HELP = `
 Usage:
-  tap-comms bridge <subcommand> [instance] [options]
+  tap bridge <subcommand> [instance] [options]
 
 Subcommands:
   start <instance>  Start bridge for an instance (e.g. codex, codex-reviewer)
@@ -3824,7 +4150,7 @@ Subcommands:
 
 Options:
   --agent-name <name>              Agent identity for bridge (or set TAP_AGENT_NAME env)
-                                   Saved to state \u2014 only needed on first start
+                                   Overrides the stored name from 'tap add' when needed
   --all                            Start all registered app-server instances
   --busy-mode <steer|wait>         How to handle active turns (default: steer)
   --poll-seconds <n>               Inbox poll interval (default: 5)
@@ -3860,16 +4186,31 @@ function redactProtectedUrl(url) {
   try {
     const parsed = new URL(url);
     if (parsed.searchParams.has("tap_token")) {
-      parsed.searchParams.set("tap_token", "***");
+      parsed.searchParams.delete("tap_token");
     }
     return parsed.toString().replace(/\/$/, "");
   } catch {
-    return url.replace(/tap_token=[^&]+/g, "tap_token=***");
+    return url.replace(/[?&]tap_token=[^&]+/g, "");
   }
 }
 function loadCurrentBridgeState(stateDir, instanceId, fallback) {
   return loadBridgeState(stateDir, instanceId) ?? fallback ?? null;
 }
+function formatThreadSummary(threadId, cwd) {
+  if (!threadId) {
+    return "-";
+  }
+  return cwd ? `${threadId} (${cwd})` : threadId;
+}
+function normalizeComparablePath(value) {
+  return path14.resolve(value).replace(/\\/g, "/").toLowerCase();
+}
+function sameOptionalPath(left, right) {
+  if (!left || !right) {
+    return left === right;
+  }
+  return normalizeComparablePath(left) === normalizeComparablePath(right);
+}
 function getSharedAppServerUsers(state, stateDir, currentInstanceId, appServerUrl) {
   const shared = [];
   for (const [id, inst] of Object.entries(state.instances)) {
@@ -3947,37 +4288,37 @@ async function bridgeStart(identifier, agentName, flags = {}) {
     };
   }
   const instanceId = resolved.instanceId;
-  let instance = state.instances[instanceId];
-  if (!instance?.installed) {
+  let instance2 = state.instances[instanceId];
+  if (!instance2?.installed) {
     return {
       ok: false,
       command: "bridge",
       instanceId,
-      runtime: instance?.runtime,
+      runtime: instance2?.runtime,
       code: "TAP_INSTANCE_NOT_FOUND",
-      message: `${instanceId} is not installed. Run: npx @hua-labs/tap add ${instance?.runtime ?? identifier}`,
+      message: `${instanceId} is not installed. Run: npx @hua-labs/tap add ${instance2?.runtime ?? identifier}`,
       warnings: [],
       data: {}
     };
   }
-  const adapter = getAdapter(instance.runtime);
+  const adapter = getAdapter(instance2.runtime);
   const mode = adapter.bridgeMode();
   if (mode !== "app-server") {
     return {
       ok: true,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_NO_OP",
       message: `${instanceId} uses ${mode} mode \u2014 no bridge needed.`,
       warnings: [],
       data: { bridgeMode: mode }
     };
   }
-  const resolvedAgentName = agentName ?? instance.agentName ?? void 0;
-  if (agentName && agentName !== instance.agentName) {
-    instance = { ...instance, agentName };
-    const updatedState = updateInstanceState(state, instanceId, instance);
+  const resolvedAgentName = agentName ?? instance2.agentName ?? void 0;
+  if (agentName && agentName !== instance2.agentName) {
+    instance2 = { ...instance2, agentName };
+    const updatedState = updateInstanceState(state, instanceId, instance2);
     saveState(repoRoot, updatedState);
     state = updatedState;
   }
@@ -3988,7 +4329,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       ok: false,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_BRIDGE_SCRIPT_MISSING",
       message: `Bridge script not found for ${instanceId}. Ensure the runtime is properly configured.`,
       warnings: [],
@@ -3997,8 +4338,8 @@ async function bridgeStart(identifier, agentName, flags = {}) {
   }
   const { config: resolvedConfig } = resolveConfig({}, repoRoot);
   const runtimeCommand = resolvedConfig.runtimeCommand;
-  const manageAppServer = instance.runtime === "codex" && flags["no-server"] !== true;
-  let effectivePort = instance.port;
+  const manageAppServer = instance2.runtime === "codex" && flags["no-server"] !== true;
+  let effectivePort = instance2.port;
   if (effectivePort == null && manageAppServer) {
     effectivePort = await findNextAvailableAppServerPort(
       state,
@@ -4006,8 +4347,8 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       4501,
       instanceId
     );
-    instance = { ...instance, port: effectivePort };
-    const updatedState = updateInstanceState(state, instanceId, instance);
+    instance2 = { ...instance2, port: effectivePort };
+    const updatedState = updateInstanceState(state, instanceId, instance2);
     saveState(repoRoot, updatedState);
     state = updatedState;
   }
@@ -4023,19 +4364,19 @@ async function bridgeStart(identifier, agentName, flags = {}) {
   if (effectivePort != null) log(`Port:          ${effectivePort}`);
   if (resolvedAgentName) log(`Agent name:    ${resolvedAgentName}`);
   const noAuth = flags["no-auth"] === true;
-  if (!manageAppServer && instance.runtime === "codex") {
+  if (!manageAppServer && instance2.runtime === "codex") {
     log("Auto server:   disabled (--no-server)");
   }
   if (noAuth && manageAppServer) {
     log("Auth gateway:  disabled (--no-auth)");
   }
-  const willBeHeadless = flags["headless"] === true || instance.headless?.enabled;
+  const willBeHeadless = flags["headless"] === true || instance2.headless?.enabled;
   if (willBeHeadless) {
-    const role = (typeof flags["role"] === "string" ? flags["role"] : null) ?? instance.headless?.role ?? "reviewer";
+    const role = (typeof flags["role"] === "string" ? flags["role"] : null) ?? instance2.headless?.role ?? "reviewer";
     log(`Headless:      ${role}`);
   }
   try {
-    if (!manageAppServer && instance.runtime === "codex") {
+    if (!manageAppServer && instance2.runtime === "codex") {
       log("Checking app-server health...");
       const healthy = await checkAppServerHealth(appServerUrl);
       if (healthy) {
@@ -4046,7 +4387,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
           ok: false,
           command: "bridge",
           instanceId,
-          runtime: instance.runtime,
+          runtime: instance2.runtime,
           code: "TAP_BRIDGE_START_FAILED",
           message: `App server not reachable at ${appServerUrl}. Start it first: codex app-server --listen ${appServerUrl}`,
           warnings: [],
@@ -4060,7 +4401,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         ok: false,
         command: "bridge",
         instanceId,
-        runtime: instance.runtime,
+        runtime: instance2.runtime,
         code: "TAP_INVALID_ARGUMENT",
         message: `Invalid --busy-mode: ${String(busyModeRaw)}. Must be "steer" or "wait".`,
         warnings: [],
@@ -4068,9 +4409,38 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       };
     }
     const busyMode = busyModeRaw;
-    const pollSeconds = typeof flags["poll-seconds"] === "string" ? parseInt(flags["poll-seconds"], 10) : void 0;
-    const reconnectSeconds = typeof flags["reconnect-seconds"] === "string" ? parseInt(flags["reconnect-seconds"], 10) : void 0;
-    const messageLookbackMinutes = typeof flags["message-lookback-minutes"] === "string" ? parseInt(flags["message-lookback-minutes"], 10) : void 0;
+    const pollSecondsRaw = typeof flags["poll-seconds"] === "string" ? flags["poll-seconds"] : void 0;
+    const reconnectSecondsRaw = typeof flags["reconnect-seconds"] === "string" ? flags["reconnect-seconds"] : void 0;
+    const lookbackRaw = typeof flags["message-lookback-minutes"] === "string" ? flags["message-lookback-minutes"] : void 0;
+    let pollSeconds;
+    let reconnectSeconds;
+    let messageLookbackMinutes;
+    try {
+      pollSeconds = parseIntFlag(pollSecondsRaw, "--poll-seconds", 1, 3600);
+      reconnectSeconds = parseIntFlag(
+        reconnectSecondsRaw,
+        "--reconnect-seconds",
+        1,
+        3600
+      );
+      messageLookbackMinutes = parseIntFlag(
+        lookbackRaw,
+        "--message-lookback-minutes",
+        1,
+        10080
+      );
+    } catch (err) {
+      return {
+        ok: false,
+        command: "bridge",
+        instanceId,
+        runtime: instance2.runtime,
+        code: "TAP_INVALID_ARGUMENT",
+        message: err instanceof Error ? err.message : String(err),
+        warnings: [],
+        data: {}
+      };
+    }
     const threadId = typeof flags["thread-id"] === "string" ? flags["thread-id"] : void 0;
     const ephemeral = flags["ephemeral"] === true;
     const processExistingMessages = flags["process-existing-messages"] === true;
@@ -4082,7 +4452,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         ok: false,
         command: "bridge",
         instanceId,
-        runtime: instance.runtime,
+        runtime: instance2.runtime,
         code: "TAP_INVALID_ARGUMENT",
         message: `Invalid --role: ${roleArg}. Must be: ${validRoles.join(", ")}`,
         warnings: [],
@@ -4094,10 +4464,10 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       role: roleArg ?? "reviewer",
       maxRounds: 5,
       qualitySeverityFloor: "high"
-    } : instance.headless;
+    } : instance2.headless;
     const bridge = await startBridge({
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       stateDir: ctx.stateDir,
       commsDir: ctx.commsDir,
       bridgeScript,
@@ -4138,14 +4508,14 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         log(`TUI connect:  ${bridge.appServer.url}`);
       }
     }
-    const updated = { ...instance, bridge, manageAppServer, noAuth };
+    const updated = { ...instance2, bridge, manageAppServer, noAuth };
     const newState = updateInstanceState(state, instanceId, updated);
     saveState(repoRoot, newState);
     return {
       ok: true,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_BRIDGE_START_OK",
       message: `Bridge for ${instanceId} started (PID: ${bridge.pid})`,
       warnings: [],
@@ -4158,7 +4528,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
       ok: false,
       command: "bridge",
       instanceId,
-      runtime: instance.runtime,
+      runtime: instance2.runtime,
       code: "TAP_BRIDGE_START_FAILED",
       message: msg,
       warnings: [],
@@ -4260,11 +4630,11 @@ async function bridgeStopOne(identifier) {
   }
   const instanceId = resolved.instanceId;
   const ctx = createAdapterContext(state.commsDir, repoRoot);
-  const instance = state.instances[instanceId];
+  const instance2 = state.instances[instanceId];
   const bridgeState = loadCurrentBridgeState(
     ctx.stateDir,
     instanceId,
-    instance?.bridge
+    instance2?.bridge
   );
   const appServer = bridgeState?.appServer ?? null;
   logHeader(`@hua-labs/tap bridge stop ${instanceId}`);
@@ -4312,8 +4682,8 @@ async function bridgeStopOne(identifier) {
       }
     }
   }
-  if (instance) {
-    const updated = { ...instance, bridge: null };
+  if (instance2) {
+    const updated = { ...instance2, bridge: null };
     const newState = updateInstanceState(state, instanceId, updated);
     saveState(repoRoot, newState);
   }
@@ -4385,9 +4755,9 @@ async function bridgeStopAll() {
       logSuccess(`Stopped bridge for ${instanceId}`);
       stopped.push(instanceId);
     }
-    const instance = state.instances[instanceId];
-    if (instance?.bridge) {
-      state.instances[instanceId] = { ...instance, bridge: null };
+    const instance2 = state.instances[instanceId];
+    if (instance2?.bridge) {
+      state.instances[instanceId] = { ...instance2, bridge: null };
       stateChanged = true;
     }
   }
@@ -4453,12 +4823,18 @@ function bridgeStatusAll() {
         pid: null,
         port: inst.port,
         lastHeartbeat: null,
+        threadId: null,
+        threadCwd: null,
+        savedThreadId: null,
+        savedThreadCwd: null,
         appServer: null
       };
       continue;
     }
     const status = getBridgeStatus(stateDir, instanceId);
     const bridgeState = loadBridgeState(stateDir, instanceId);
+    const runtimeHeartbeat = loadRuntimeBridgeHeartbeat(bridgeState);
+    const savedThread = loadRuntimeBridgeThreadState(bridgeState);
     const age = getHeartbeatAge(stateDir, instanceId);
     const pid = bridgeState?.pid ?? null;
     const heartbeat = getBridgeHeartbeatTimestamp(stateDir, instanceId);
@@ -4480,12 +4856,26 @@ function bridgeStatusAll() {
         );
       }
     }
+    if (runtimeHeartbeat?.threadId) {
+      log(
+        `  Thread:     ${formatThreadSummary(runtimeHeartbeat.threadId, runtimeHeartbeat.threadCwd)}`
+      );
+    }
+    if (savedThread?.threadId && (savedThread.threadId !== runtimeHeartbeat?.threadId || !sameOptionalPath(savedThread.cwd, runtimeHeartbeat?.threadCwd))) {
+      log(
+        `  Saved:      ${formatThreadSummary(savedThread.threadId, savedThread.cwd)}`
+      );
+    }
     bridges[instanceId] = {
       status,
       runtime: inst.runtime,
       pid,
       port: inst.port,
       lastHeartbeat: heartbeat,
+      threadId: runtimeHeartbeat?.threadId ?? null,
+      threadCwd: runtimeHeartbeat?.threadCwd ?? null,
+      savedThreadId: savedThread?.threadId ?? null,
+      savedThreadCwd: savedThread?.cwd ?? null,
       appServer: bridgeState?.appServer ?? null
     };
   }
@@ -4561,6 +4951,10 @@ function bridgeStatusOne(identifier) {
         pid: null,
         port: inst.port,
         lastHeartbeat: null,
+        threadId: null,
+        threadCwd: null,
+        savedThreadId: null,
+        savedThreadCwd: null,
         appServer: null
       }
     };
@@ -4569,6 +4963,8 @@ function bridgeStatusOne(identifier) {
   const stateDir = resolvedCfg2.stateDir;
   const status = getBridgeStatus(stateDir, instanceId);
   const bridgeState = loadBridgeState(stateDir, instanceId);
+  const runtimeHeartbeat = loadRuntimeBridgeHeartbeat(bridgeState);
+  const savedThread = loadRuntimeBridgeThreadState(bridgeState);
   const age = getHeartbeatAge(stateDir, instanceId);
   const heartbeat = getBridgeHeartbeatTimestamp(stateDir, instanceId);
   log(`Status:      ${status}`);
@@ -4577,6 +4973,16 @@ function bridgeStatusOne(identifier) {
     log(
       `Heartbeat:   ${heartbeat ?? "-"}${age !== null ? ` (${formatAge(age)})` : ""}`
     );
+    if (runtimeHeartbeat?.threadId) {
+      log(
+        `Thread:      ${formatThreadSummary(runtimeHeartbeat.threadId, runtimeHeartbeat.threadCwd)}`
+      );
+    }
+    if (savedThread?.threadId && (savedThread.threadId !== runtimeHeartbeat?.threadId || !sameOptionalPath(savedThread.cwd, runtimeHeartbeat?.threadCwd))) {
+      log(
+        `Saved:       ${formatThreadSummary(savedThread.threadId, savedThread.cwd)}`
+      );
+    }
     log(
       `Log:         ${path14.join(stateDir, "logs", `bridge-${instanceId}.log`)}`
     );
@@ -4625,6 +5031,10 @@ function bridgeStatusOne(identifier) {
       pid: bridgeState?.pid ?? null,
       port: inst.port,
       lastHeartbeat: heartbeat,
+      threadId: runtimeHeartbeat?.threadId ?? null,
+      threadCwd: runtimeHeartbeat?.threadCwd ?? null,
+      savedThreadId: savedThread?.threadId ?? null,
+      savedThreadCwd: savedThread?.cwd ?? null,
       appServer: bridgeState?.appServer ?? null
     }
   };
@@ -4683,8 +5093,22 @@ async function bridgeRestart(identifier, flags) {
     };
   }
   const { config: resolvedConfig } = resolveConfig({}, repoRoot);
-  const drainStr = typeof flags["drain-timeout"] === "string" ? flags["drain-timeout"] : "30";
-  const drainTimeout = parseInt(drainStr, 10) || 30;
+  const drainStr = typeof flags["drain-timeout"] === "string" ? flags["drain-timeout"] : void 0;
+  let drainTimeout;
+  try {
+    drainTimeout = parseIntFlag(drainStr, "--drain-timeout", 1, 300) ?? 30;
+  } catch (err) {
+    return {
+      ok: false,
+      command: "bridge",
+      instanceId,
+      runtime: instance.runtime,
+      code: "TAP_INVALID_ARGUMENT",
+      message: err instanceof Error ? err.message : String(err),
+      warnings: [],
+      data: {}
+    };
+  }
   logHeader(`@hua-labs/tap bridge restart ${instanceId}`);
   log(`Drain timeout: ${drainTimeout}s`);
   try {
@@ -4831,7 +5255,7 @@ async function bridgeCommand(args) {
 // src/engine/dashboard.ts
 import * as fs15 from "fs";
 import * as path15 from "path";
-import { execSync as execSync5 } from "child_process";
+import { execSync as execSync4 } from "child_process";
 function collectAgents(commsDir) {
   const heartbeatsPath = path15.join(commsDir, "heartbeats.json");
   if (!fs15.existsSync(heartbeatsPath)) return [];
@@ -4910,7 +5334,7 @@ function collectBridges(repoRoot) {
 }
 function collectPRs() {
   try {
-    const output = execSync5(
+    const output = execSync4(
       "gh pr list --state all --limit 10 --json number,title,author,state,url",
       { encoding: "utf-8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] }
     );
@@ -4980,7 +5404,7 @@ function collectDashboardSnapshot(repoRoot, commsDirOverride) {
 // src/commands/up.ts
 var UP_HELP = `
 Usage:
-  tap-comms up [bridge-start options]
+  tap up [bridge-start options]
 
 Description:
   Start all registered app-server bridge daemons with one command.
@@ -5004,7 +5428,18 @@ async function upCommand(args) {
     };
   }
   const repoRoot = findRepoRoot();
-  const result = await bridgeCommand(["start", "--all", ...args]);
+  const previousColdStartWarmup = process.env.TAP_COLD_START_WARMUP;
+  process.env.TAP_COLD_START_WARMUP = "true";
+  let result;
+  try {
+    result = await bridgeCommand(["start", "--all", ...args]);
+  } finally {
+    if (previousColdStartWarmup === void 0) {
+      delete process.env.TAP_COLD_START_WARMUP;
+    } else {
+      process.env.TAP_COLD_START_WARMUP = previousColdStartWarmup;
+    }
+  }
   const snapshot = collectDashboardSnapshot(repoRoot);
   const activeBridges = snapshot.bridges.filter(
     (bridge) => bridge.status === "running"
@@ -5035,7 +5470,7 @@ async function upCommand(args) {
 // src/commands/down.ts
 var DOWN_HELP = `
 Usage:
-  tap-comms down
+  tap down
 
 Description:
   Stop all running bridge daemons and managed app-servers.
@@ -5084,7 +5519,34 @@ async function downCommand(args) {
 // src/commands/serve.ts
 import * as path16 from "path";
 import { spawn as spawn2 } from "child_process";
+var SERVE_HELP = `
+Usage:
+  tap serve [options]
+
+Description:
+  Start the tap MCP server over stdio. This command takes over the
+  process \u2014 it is intended to be launched by an MCP host (e.g. Claude Code).
+
+Options:
+  --comms-dir <path>    Override comms directory (also reads TAP_COMMS_DIR env)
+  --help, -h            Show help
+
+Examples:
+  npx @hua-labs/tap serve
+  npx @hua-labs/tap serve --comms-dir /shared/comms
+`.trim();
 async function serveCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log(SERVE_HELP);
+    return {
+      ok: true,
+      command: "serve",
+      code: "TAP_NO_OP",
+      message: SERVE_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const repoRoot = findRepoRoot();
   let commsDir;
   const commsDirIdx = args.indexOf("--comms-dir");
@@ -5132,9 +5594,9 @@ async function serveCommand(args) {
       TAP_COMMS_DIR: commsDir
     }
   });
-  return new Promise((resolve11) => {
+  return new Promise((resolve13) => {
     child.on("error", (err) => {
-      resolve11({
+      resolve13({
         ok: false,
         command: "serve",
         code: "TAP_INTERNAL_ERROR",
@@ -5144,7 +5606,7 @@ async function serveCommand(args) {
       });
     });
     child.on("exit", (code) => {
-      resolve11({
+      resolve13({
         ok: code === 0,
         command: "serve",
         code: code === 0 ? "TAP_SERVE_OK" : "TAP_INTERNAL_ERROR",
@@ -5159,10 +5621,10 @@ async function serveCommand(args) {
 // src/commands/init-worktree.ts
 import * as fs16 from "fs";
 import * as path17 from "path";
-import { execSync as execSync6 } from "child_process";
+import { execSync as execSync5 } from "child_process";
 var INIT_WORKTREE_HELP = `
 Usage:
-  tap-comms init-worktree [options]
+  tap init-worktree [options]
 
 Options:
   --path <dir>         Worktree directory (required, e.g. ../hua-wt-3)
@@ -5183,7 +5645,7 @@ function warn(warnings, message) {
 }
 function run(cmd, opts) {
   try {
-    return execSync6(cmd, {
+    return execSync5(cmd, {
       cwd: opts?.cwd,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -5200,7 +5662,7 @@ function toAbsolute(p) {
 }
 function probeBun(candidate) {
   try {
-    const out = execSync6(`"${candidate}" --version`, {
+    const out = execSync5(`"${candidate}" --version`, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5e3
@@ -5214,7 +5676,7 @@ function findBun() {
   const candidates = process.platform === "win32" ? ["bun.exe", "bun"] : ["bun"];
   for (const name of candidates) {
     try {
-      const out = execSync6(
+      const out = execSync5(
         process.platform === "win32" ? `where ${name}` : `which ${name}`,
         { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5e3 }
       ).trim();
@@ -5345,7 +5807,7 @@ function step4GenerateMcpJson(opts, warnings) {
   );
   const mcpConfig = {
     mcpServers: {
-      "tap-comms": {
+      tap: {
         command: bunAbs,
         args: [channelEntry],
         cwd: wtAbs,
@@ -5445,7 +5907,7 @@ async function initWorktreeCommand(args) {
       ok: true,
       command: "init-worktree",
       code: "TAP_NO_OP",
-      message: "init-worktree help",
+      message: INIT_WORKTREE_HELP,
       warnings: [],
       data: {}
     };
@@ -5607,8 +6069,38 @@ function renderSnapshot(snapshot) {
     }
   }
 }
+var DASHBOARD_HELP = `
+Usage:
+  tap dashboard [options]
+
+Description:
+  Display a unified ops dashboard: agents, bridges, PRs, and warnings.
+
+Options:
+  --json                Output snapshot as JSON
+  --watch               Refresh dashboard on an interval
+  --interval <seconds>  Refresh interval in seconds (default: 5, min: 2)
+  --comms-dir <path>    Override comms directory
+  --help, -h            Show help
+
+Examples:
+  npx @hua-labs/tap dashboard
+  npx @hua-labs/tap dashboard --watch --interval 10
+  npx @hua-labs/tap dashboard --json
+`.trim();
 async function dashboardCommand(args) {
   const { flags } = parseArgs(args);
+  if (flags["help"] === true || flags["h"] === true) {
+    log(DASHBOARD_HELP);
+    return {
+      ok: true,
+      command: "dashboard",
+      code: "TAP_NO_OP",
+      message: DASHBOARD_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const jsonMode = flags["json"] === true;
   const watchMode = flags["watch"] === true;
   const intervalStr = typeof flags["interval"] === "string" ? flags["interval"] : "5";
@@ -5668,14 +6160,150 @@ import {
   mkdirSync as mkdirSync10,
   readdirSync as readdirSync4,
   readFileSync as readFileSync14,
+  renameSync as renameSync10,
   statSync as statSync2,
-  unlinkSync as unlinkSync3
+  unlinkSync as unlinkSync3,
+  writeFileSync as writeFileSync12
 } from "fs";
-import { execSync as execSync7 } from "child_process";
-import { join as join17 } from "path";
+import { homedir as homedir3 } from "os";
+import { spawnSync as spawnSync4 } from "child_process";
+import { dirname as dirname11, join as join17, resolve as resolve12 } from "path";
 var PASS = "pass";
 var WARN = "warn";
 var FAIL = "fail";
+var CODEX_ENV_DRIFT_KEYS = [
+  "TAP_COMMS_DIR",
+  "TAP_STATE_DIR",
+  "TAP_REPO_ROOT"
+];
+function normalizeComparablePath2(value) {
+  return resolve12(value).replace(/\\/g, "/").toLowerCase();
+}
+function samePath(left, right) {
+  return normalizeComparablePath2(left) === normalizeComparablePath2(right);
+}
+function looksLikePathToken(value) {
+  return /^[A-Za-z]:[\\/]/.test(value) || value.startsWith("/") || value.startsWith("\\") || value.startsWith(".") || value.includes("/") || value.includes("\\");
+}
+function sameCommandToken(left, right) {
+  return looksLikePathToken(left) || looksLikePathToken(right) ? samePath(left, right) : left === right;
+}
+function sameStringArray(left, right) {
+  return left.length === right.length && left.every((value, index) => sameCommandToken(value, right[index] ?? ""));
+}
+function appendWarningMessage(message, extra) {
+  return message.includes(extra) ? message : `${message}; ${extra}`;
+}
+function findCodexConfigPath3() {
+  return join17(homedir3(), ".codex", "config.toml");
+}
+function canonicalizeTrustPath3(targetPath) {
+  let resolved = resolve12(targetPath).replace(/\//g, "\\");
+  const driveRoot = /^[A-Za-z]:\\$/;
+  if (!driveRoot.test(resolved)) {
+    resolved = resolved.replace(/\\+$/g, "");
+  }
+  return resolved.startsWith("\\\\?\\") ? resolved : `\\\\?\\${resolved}`;
+}
+function trustSelector2(targetPath) {
+  return `projects.'${canonicalizeTrustPath3(targetPath)}'`;
+}
+function writeTomlAtomically(filePath, content) {
+  const dir = dirname11(filePath);
+  mkdirSync10(dir, { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  writeFileSync12(tmp, content, "utf-8");
+  renameSync10(tmp, filePath);
+}
+function hasInstalledCodexInstance(state) {
+  return !!state ? Object.values(state.instances).some(
+    (instance2) => instance2.runtime === "codex" && instance2.installed
+  ) : false;
+}
+function getCodexTrustTargets(repoRoot) {
+  return [...new Set([repoRoot, process.cwd()].map((value) => resolve12(value)))];
+}
+function buildCodexDoctorSpec(repoRoot, commsDir) {
+  const state = loadState(repoRoot);
+  if (!hasInstalledCodexInstance(state)) {
+    return null;
+  }
+  const ctx = createAdapterContext(commsDir, repoRoot);
+  const managed = buildManagedMcpServerSpec(ctx);
+  return {
+    configPath: findCodexConfigPath3(),
+    trustTargets: getCodexTrustTargets(repoRoot),
+    managed
+  };
+}
+function repairCodexConfig(repoRoot, commsDir) {
+  const spec = buildCodexDoctorSpec(repoRoot, commsDir);
+  if (!spec) {
+    throw new Error("No installed Codex instance found in tap state.");
+  }
+  if (!spec.managed.command || spec.managed.issues.length > 0) {
+    throw new Error(
+      spec.managed.issues[0] ?? "Unable to resolve the managed tap MCP server for Codex."
+    );
+  }
+  const existingContent = existsSync16(spec.configPath) ? readFileSync14(spec.configPath, "utf-8") : "";
+  const existingTapEnvTable = extractTomlTable(existingContent, "mcp_servers.tap.env");
+  const existingLegacyEnvTable = extractTomlTable(
+    existingContent,
+    "mcp_servers.tap-comms.env"
+  );
+  const preservedEnv = parseTomlAssignments(
+    existingTapEnvTable ?? existingLegacyEnvTable ?? ""
+  );
+  const repairedEnv = {
+    ...preservedEnv,
+    ...Object.fromEntries(
+      CODEX_ENV_DRIFT_KEYS.map((key) => [key, spec.managed.env[key]])
+    )
+  };
+  let nextContent = existingContent;
+  if (extractTomlTable(nextContent, "mcp_servers.tap-comms.env")) {
+    nextContent = removeTomlTable(nextContent, "mcp_servers.tap-comms.env");
+  }
+  if (extractTomlTable(nextContent, "mcp_servers.tap-comms")) {
+    nextContent = removeTomlTable(nextContent, "mcp_servers.tap-comms");
+  }
+  nextContent = replaceTomlTable(
+    nextContent,
+    "mcp_servers.tap",
+    renderTomlTable(
+      "mcp_servers.tap",
+      {
+        command: spec.managed.command,
+        args: spec.managed.args
+      },
+      extractTomlTable(existingContent, "mcp_servers.tap")
+    )
+  );
+  nextContent = replaceTomlTable(
+    nextContent,
+    "mcp_servers.tap.env",
+    renderTomlTable(
+      "mcp_servers.tap.env",
+      repairedEnv,
+      existingTapEnvTable ?? existingLegacyEnvTable
+    )
+  );
+  for (const trustTarget of spec.trustTargets) {
+    const selector = trustSelector2(trustTarget);
+    nextContent = replaceTomlTable(
+      nextContent,
+      selector,
+      renderTomlTable(
+        selector,
+        { trust_level: "trusted" },
+        extractTomlTable(existingContent, selector)
+      )
+    );
+  }
+  writeTomlAtomically(spec.configPath, nextContent);
+  return `Repaired Codex config at ${spec.configPath}. Restart Codex to reload MCP settings.`;
+}
 function countFiles(dir, ext = ".md") {
   if (!existsSync16(dir)) return 0;
   try {
@@ -5700,21 +6328,6 @@ 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({
@@ -5798,7 +6411,8 @@ function checkInstances(repoRoot, stateDir) {
       const running = isBridgeRunning(stateDir, id);
       const bridgeState = loadBridgeState(stateDir, id);
       const heartbeatAge = getHeartbeatAge(stateDir, id);
-      const runtimeHeartbeat = loadBridgeRuntimeHeartbeat(bridgeState);
+      const runtimeHeartbeat = loadRuntimeBridgeHeartbeat(bridgeState);
+      const savedThread = loadRuntimeBridgeThreadState(bridgeState);
       let status;
       let message;
       let fix;
@@ -5844,9 +6458,30 @@ function checkInstances(repoRoot, stateDir) {
       }
       const lastRuntimeError = runtimeHeartbeat?.lastError?.trim();
       if (lastRuntimeError) {
-        status = status === FAIL ? FAIL : WARN;
+        status = WARN;
         message = `${message}; bridge last error: ${lastRuntimeError}`;
       }
+      if (savedThread?.threadId && savedThread.cwd && !samePath(savedThread.cwd, repoRoot)) {
+        status = WARN;
+        message = appendWarningMessage(
+          message,
+          `saved thread cwd mismatch (${savedThread.cwd})`
+        );
+      }
+      if (runtimeHeartbeat?.threadId && savedThread?.threadId && runtimeHeartbeat.threadId !== savedThread.threadId) {
+        status = WARN;
+        message = appendWarningMessage(
+          message,
+          `saved thread ${savedThread.threadId} differs from active thread ${runtimeHeartbeat.threadId}`
+        );
+      }
+      if (runtimeHeartbeat?.threadCwd && !samePath(runtimeHeartbeat.threadCwd, repoRoot)) {
+        status = WARN;
+        message = appendWarningMessage(
+          message,
+          `active thread cwd mismatch (${runtimeHeartbeat.threadCwd})`
+        );
+      }
       checks.push({ name: `bridge: ${id}`, status, message, fix });
     } else {
       checks.push({
@@ -5919,15 +6554,25 @@ function checkMcpServer(repoRoot) {
     });
     return checks;
   }
-  const hasTapComms = config?.mcpServers?.["tap-comms"];
-  if (!hasTapComms) {
+  const mcpServers = config?.mcpServers;
+  const hasTap = mcpServers?.["tap"];
+  const hasOldKey = mcpServers?.["tap-comms"];
+  if (hasOldKey) {
     checks.push({
       name: "MCP config (.mcp.json)",
       status: WARN,
-      message: "tap-comms not configured"
+      message: 'Legacy "tap-comms" key found. Run "tap add claude" to migrate to the new "tap" key.'
+    });
+  }
+  if (!hasTap && !hasOldKey) {
+    checks.push({
+      name: "MCP config (.mcp.json)",
+      status: WARN,
+      message: "tap not configured"
     });
     return checks;
   }
+  const hasTapComms = hasTap ?? hasOldKey;
   checks.push({
     name: "MCP config (.mcp.json)",
     status: PASS,
@@ -5938,11 +6583,12 @@ function checkMcpServer(repoRoot) {
     let cmdAvailable = existsSync16(cmd);
     if (!cmdAvailable) {
       try {
-        execSync7(`"${cmd}" --version`, {
+        const result = spawnSync4(cmd, ["--version"], {
           stdio: "pipe",
-          timeout: 5e3
+          timeout: 5e3,
+          shell: process.platform === "win32"
         });
-        cmdAvailable = true;
+        cmdAvailable = result.status === 0;
       } catch {
       }
     }
@@ -6001,6 +6647,88 @@ function checkMcpServer(repoRoot) {
   });
   return checks;
 }
+function checkCodexConfig(repoRoot, commsDir) {
+  const spec = buildCodexDoctorSpec(repoRoot, commsDir);
+  if (!spec) {
+    return [];
+  }
+  const checks = [];
+  const fixHint = 'Run "tap doctor --fix" or "tap add codex --force".';
+  if (!existsSync16(spec.configPath)) {
+    checks.push({
+      name: "MCP config (~/.codex/config.toml)",
+      status: WARN,
+      message: `${spec.configPath} not found. ${fixHint}`,
+      fix: () => repairCodexConfig(repoRoot, commsDir)
+    });
+    return checks;
+  }
+  const content = readFileSync14(spec.configPath, "utf-8");
+  const tapTable = extractTomlTable(content, "mcp_servers.tap");
+  const tapEnvTable = extractTomlTable(content, "mcp_servers.tap.env");
+  const legacyTable = extractTomlTable(content, "mcp_servers.tap-comms");
+  const legacyEnvTable = extractTomlTable(content, "mcp_servers.tap-comms.env");
+  const selectedMain = parseTomlAssignments(tapTable ?? "");
+  const selectedEnv = parseTomlAssignments(
+    tapEnvTable ?? legacyEnvTable ?? ""
+  );
+  const issues = [];
+  if (legacyTable || legacyEnvTable) {
+    issues.push('legacy "tap-comms" key present');
+  }
+  if (!tapTable && !legacyTable) {
+    issues.push("tap MCP table missing");
+  }
+  if (!tapEnvTable && !legacyEnvTable) {
+    issues.push("tap MCP env table missing");
+  }
+  if (tapTable && spec.managed.command) {
+    const actualCommand = selectedMain.command;
+    if (typeof actualCommand !== "string") {
+      issues.push("tap MCP command missing");
+    } else if (!sameCommandToken(actualCommand, spec.managed.command)) {
+      issues.push(`tap MCP command drift (${actualCommand})`);
+    }
+    const actualArgs = selectedMain.args;
+    if (!Array.isArray(actualArgs)) {
+      issues.push("tap MCP args missing");
+    } else if (!sameStringArray(actualArgs, spec.managed.args)) {
+      issues.push(`tap MCP args drift (${JSON.stringify(actualArgs)})`);
+    }
+  }
+  for (const key of CODEX_ENV_DRIFT_KEYS) {
+    const expected = spec.managed.env[key];
+    const actual = selectedEnv[key];
+    if (typeof actual !== "string") {
+      issues.push(`${key} missing`);
+      continue;
+    }
+    if (!samePath(actual, expected)) {
+      issues.push(`${key} drift (${actual})`);
+    }
+  }
+  for (const trustTarget of spec.trustTargets) {
+    const trustTable = extractTomlTable(content, trustSelector2(trustTarget));
+    if (!trustTable || !trustTable.includes('trust_level = "trusted"')) {
+      issues.push(`missing trust for ${trustTarget}`);
+    }
+  }
+  if (issues.length === 0) {
+    checks.push({
+      name: "MCP config (~/.codex/config.toml)",
+      status: PASS,
+      message: spec.configPath
+    });
+    return checks;
+  }
+  checks.push({
+    name: "MCP config (~/.codex/config.toml)",
+    status: WARN,
+    message: `${issues.join("; ")}. ${fixHint}`,
+    fix: () => repairCodexConfig(repoRoot, commsDir)
+  });
+  return checks;
+}
 function checkBridgeTurnHealth(repoRoot) {
   const checks = [];
   const tmpDir = join17(repoRoot, ".tmp");
@@ -6115,7 +6843,35 @@ function renderCheck(check, fixMode) {
   const msg = check.message ? ` \u2014 ${check.message}${fixable}` : "";
   return `  ${icon} ${check.name}${msg}`;
 }
+var DOCTOR_HELP = `
+Usage:
+  tap doctor [options]
+
+Description:
+  Diagnose tap infrastructure health: comms directory, instances, bridges,
+  message lifecycle, and MCP server configuration.
+
+Options:
+  --fix                 Auto-repair detected issues where possible
+  --comms-dir <path>    Override comms directory
+  --help, -h            Show help
+
+Examples:
+  npx @hua-labs/tap doctor
+  npx @hua-labs/tap doctor --fix
+`.trim();
 async function doctorCommand(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log(DOCTOR_HELP);
+    return {
+      ok: true,
+      command: "doctor",
+      code: "TAP_NO_OP",
+      message: DOCTOR_HELP,
+      warnings: [],
+      data: {}
+    };
+  }
   const repoRoot = findRepoRoot();
   const overrides = {};
   let fixMode = false;
@@ -6137,6 +6893,7 @@ async function doctorCommand(args) {
     checks.push(...checkInstances(repoRoot, config.stateDir));
     checks.push(...checkMessageLifecycle(commsDir));
     checks.push(...checkMcpServer(repoRoot));
+    checks.push(...checkCodexConfig(repoRoot, commsDir));
     checks.push(...checkBridgeTurnHealth(repoRoot));
     return checks;
   }
@@ -6228,12 +6985,12 @@ async function doctorCommand(args) {
 }
 
 // src/commands/comms.ts
-import { execSync as execSync8 } from "child_process";
+import { execSync as execSync6, spawnSync as spawnSync5 } from "child_process";
 import * as fs17 from "fs";
 import * as path18 from "path";
 var COMMS_HELP = `
 Usage:
-  tap-comms comms <subcommand>
+  tap comms <subcommand>
 
 Subcommands:
   pull    Pull latest changes from comms remote repo
@@ -6260,7 +7017,7 @@ function commsPull(commsDir) {
     };
   }
   try {
-    const output = execSync8("git pull --rebase", {
+    const output = execSync6("git pull --rebase", {
       cwd: commsDir,
       encoding: "utf-8",
       stdio: "pipe"
@@ -6302,8 +7059,8 @@ function commsPush(commsDir) {
     };
   }
   try {
-    execSync8("git add -A", { cwd: commsDir, stdio: "pipe" });
-    const status = execSync8("git status --porcelain", {
+    execSync6("git add -A", { cwd: commsDir, stdio: "pipe" });
+    const status = execSync6("git status --porcelain", {
       cwd: commsDir,
       encoding: "utf-8",
       stdio: "pipe"
@@ -6320,11 +7077,23 @@ function commsPush(commsDir) {
       };
     }
     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" });
+    const commitResult = spawnSync5(
+      "git",
+      ["commit", "-m", `chore(comms): sync ${timestamp}`],
+      { cwd: commsDir, stdio: "pipe", encoding: "utf-8" }
+    );
+    if (commitResult.status !== 0) {
+      const msg = commitResult.stderr || `git commit exited with code ${commitResult.status}`;
+      return {
+        ok: false,
+        command: "comms",
+        code: "TAP_COMMS_PUSH_FAILED",
+        message: `Commit failed: ${msg}`,
+        warnings: [],
+        data: { commsDir }
+      };
+    }
+    execSync6("git push", { cwd: commsDir, stdio: "pipe" });
     logSuccess("Comms push complete");
     return {
       ok: true,
@@ -6390,7 +7159,12 @@ function emitResult(result, jsonMode) {
   } else {
     logError(result.message);
   }
+  const emittedWarnings = /* @__PURE__ */ new Set();
   for (const w of result.warnings) {
+    if (emittedWarnings.has(w) || wasWarningLogged(w)) {
+      continue;
+    }
+    emittedWarnings.add(w);
     logWarn(w);
   }
 }
@@ -6403,16 +7177,61 @@ function extractJsonFlag(args) {
   return { jsonMode, cleanArgs };
 }
 
+// src/cli-suggest.ts
+var COMMANDS = [
+  "init",
+  "init-worktree",
+  "add",
+  "remove",
+  "status",
+  "bridge",
+  "up",
+  "down",
+  "comms",
+  "dashboard",
+  "doctor",
+  "serve",
+  "version"
+];
+function suggestCommand(input) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const cmd of COMMANDS) {
+    const d = levenshtein(input.toLowerCase(), cmd);
+    if (d < bestDist && d <= Math.max(2, Math.floor(cmd.length / 2))) {
+      bestDist = d;
+      best = cmd;
+    }
+  }
+  return best;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    () => Array.from({ length: n + 1 }).fill(0)
+  );
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
 // src/cli.ts
 var HELP = `
 @hua-labs/tap \u2014 Cross-model AI agent communication setup
 
 Usage:
-  tap-comms <command> [options]
+  tap <command> [options]
 
 Commands:
   init                  Initialize comms directory and state
-  init-worktree         Set up a new git worktree with tap-comms
+  init-worktree         Set up a new git worktree with tap
   add <runtime>         Add a runtime instance (claude, codex, gemini)
   remove <instance>     Remove an instance and rollback config
   status                Show installed instances and bridge status
@@ -6422,7 +7241,7 @@ Commands:
   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)
+  serve                 Start tap MCP server (stdio)
   version               Show version
 
 Options:
@@ -6459,6 +7278,7 @@ function normalizeCommandName(command) {
 async function main() {
   const rawArgs = process.argv.slice(2);
   const { jsonMode, cleanArgs } = extractJsonFlag(rawArgs);
+  resetLoggedWarnings();
   setJsonMode(jsonMode);
   const command = cleanArgs[0];
   if (!command || command === "--help" || command === "-h") {
@@ -6516,21 +7336,27 @@ async function main() {
         break;
       case "serve": {
         const serveResult = await serveCommand(commandArgs);
-        if (!serveResult.ok) {
+        if (!serveResult.ok || serveResult.code === "TAP_NO_OP") {
           emitResult(serveResult, jsonMode);
         }
         process.exit(exitCode(serveResult));
         break;
       }
-      default:
+      default: {
+        const suggestion = suggestCommand(command);
+        const hint = suggestion ? `
+
+Did you mean: tap ${suggestion}?` : "\n\nRun tap --help for a list of commands.";
         result = {
           ok: false,
           command: "unknown",
           code: "TAP_INVALID_ARGUMENT",
-          message: `Unknown command: ${command}`,
+          message: `Unknown command: ${command}${hint}`,
           warnings: [],
-          data: { requestedCommand: command }
+          data: { requestedCommand: command, suggestion }
         };
+        break;
+      }
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);