@btraut/browser-bridge 0.7.3 → 0.8.1

package/dist/index.js

@@ -76,6 +76,498 @@ var successEnvelopeSchema = (result) => import_zod.z.object({
   result
 });
 
+// packages/shared/src/logging.ts
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+
+// packages/shared/src/runtime-config.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var DEFAULT_HOST = "127.0.0.1";
+var LEGACY_DEFAULT_PORT = 3210;
+var DETERMINISTIC_PORT_WINDOW = 2e3;
+var ENV_CORE_HOST = "BROWSER_BRIDGE_CORE_HOST";
+var ENV_VISION_HOST = "BROWSER_VISION_CORE_HOST";
+var ENV_CORE_PORT = "BROWSER_BRIDGE_CORE_PORT";
+var ENV_VISION_PORT = "BROWSER_VISION_CORE_PORT";
+var RUNTIME_METADATA_RELATIVE_PATH = ".context/browser-bridge/dev.json";
+var DEFAULT_LOG_DIRECTORY_RELATIVE_PATH = ".context/logs/browser-bridge";
+var resolveCwd = (cwd) => (0, import_node_path.resolve)(cwd ?? process.cwd());
+var resolveOptionalPath = (cwd, value) => {
+  if (!value) {
+    return void 0;
+  }
+  return (0, import_node_path.isAbsolute)(value) ? value : (0, import_node_path.resolve)(cwd, value);
+};
+var normalizeHost = (value) => {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+};
+var parsePort = (value, label, invalidPolicy) => {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value === "string" && value.trim().length === 0) {
+    return void 0;
+  }
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return Math.floor(parsed);
+  }
+  if (invalidPolicy === "throw") {
+    throw new Error(`Invalid ${label}: ${String(value)}`);
+  }
+  return void 0;
+};
+var hashString = (value) => {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+};
+var normalizePathForHash = (value) => value.replace(/\\/g, "/").toLowerCase();
+var sanitizeToken = (value) => value.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+var fallbackWorktreeId = (gitRoot) => {
+  const hash = hashString(normalizePathForHash(gitRoot)).toString(16).padStart(8, "0");
+  return `wt-${hash}`;
+};
+var extractWorktreeIdFromGitDir = (gitDir) => {
+  const normalized = gitDir.replace(/\\/g, "/");
+  const marker = "/.git/worktrees/";
+  const markerIndex = normalized.lastIndexOf(marker);
+  if (markerIndex < 0) {
+    return null;
+  }
+  const remainder = normalized.slice(markerIndex + marker.length);
+  const rawId = remainder.split("/")[0];
+  if (!rawId) {
+    return null;
+  }
+  const sanitized = sanitizeToken(rawId);
+  return sanitized.length > 0 ? sanitized : null;
+};
+var readWorktreeGitDir = (gitRoot) => {
+  const gitPath = (0, import_node_path.join)(gitRoot, ".git");
+  try {
+    const stats = (0, import_node_fs.statSync)(gitPath);
+    if (stats.isDirectory()) {
+      return gitPath;
+    }
+    if (!stats.isFile()) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(gitPath, "utf8");
+    const match = raw.match(/^gitdir:\s*(.+)$/m);
+    if (!match?.[1]) {
+      return null;
+    }
+    const candidate = match[1].trim();
+    return (0, import_node_path.isAbsolute)(candidate) ? candidate : (0, import_node_path.resolve)(gitRoot, candidate);
+  } catch {
+    return null;
+  }
+};
+var resolveEnvHost = (env) => {
+  const bridgeHost = normalizeHost(env[ENV_CORE_HOST]);
+  if (bridgeHost) {
+    return bridgeHost;
+  }
+  return normalizeHost(env[ENV_VISION_HOST]);
+};
+var resolveEnvPortRaw = (env) => {
+  if (env[ENV_CORE_PORT] !== void 0) {
+    return env[ENV_CORE_PORT];
+  }
+  return env[ENV_VISION_PORT];
+};
+var sanitizeMetadata = (raw) => {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const candidate = raw;
+  const host = normalizeHost(candidate.host);
+  const port = parsePort(candidate.port, "port", "ignore");
+  const gitRoot = normalizeHost(candidate.git_root);
+  const worktreeId = normalizeHost(candidate.worktree_id);
+  const extensionId = normalizeHost(candidate.extension_id);
+  const updatedAt = normalizeHost(candidate.updated_at);
+  if (!host && port === void 0 && !gitRoot && !worktreeId && !extensionId && !updatedAt) {
+    return null;
+  }
+  return {
+    host,
+    port,
+    git_root: gitRoot,
+    worktree_id: worktreeId,
+    extension_id: extensionId,
+    updated_at: updatedAt
+  };
+};
+var findGitRoot = (cwd = process.cwd()) => {
+  let current = (0, import_node_path.resolve)(cwd);
+  while (true) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(current, ".git"))) {
+      return current;
+    }
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+};
+var resolveWorktreeId = ({
+  cwd,
+  gitRoot
+} = {}) => {
+  const resolvedGitRoot = gitRoot ?? findGitRoot(resolveCwd(cwd));
+  if (!resolvedGitRoot) {
+    return null;
+  }
+  const gitDir = readWorktreeGitDir(resolvedGitRoot);
+  const parsedId = gitDir ? extractWorktreeIdFromGitDir(gitDir) : null;
+  if (parsedId) {
+    return parsedId;
+  }
+  return fallbackWorktreeId(resolvedGitRoot);
+};
+var resolveDeterministicCorePort = ({
+  cwd,
+  gitRoot
+} = {}) => {
+  const resolvedGitRoot = gitRoot ?? findGitRoot(resolveCwd(cwd));
+  if (!resolvedGitRoot) {
+    return LEGACY_DEFAULT_PORT;
+  }
+  const seed = normalizePathForHash(resolvedGitRoot);
+  return LEGACY_DEFAULT_PORT + hashString(seed) % DETERMINISTIC_PORT_WINDOW;
+};
+var resolveRuntimeMetadataPath = ({
+  cwd,
+  gitRoot,
+  metadataPath
+} = {}) => {
+  const resolvedCwd = resolveCwd(cwd);
+  const providedPath = resolveOptionalPath(resolvedCwd, metadataPath);
+  if (providedPath) {
+    return providedPath;
+  }
+  const root = gitRoot ?? findGitRoot(resolvedCwd) ?? resolvedCwd;
+  return (0, import_node_path.join)(root, RUNTIME_METADATA_RELATIVE_PATH);
+};
+var resolveLogDirectory = ({
+  cwd,
+  gitRoot,
+  logDir
+} = {}) => {
+  const resolvedCwd = resolveCwd(cwd);
+  const providedPath = resolveOptionalPath(resolvedCwd, logDir);
+  if (providedPath) {
+    return providedPath;
+  }
+  const resolvedGitRoot = gitRoot === void 0 ? findGitRoot(resolvedCwd) : gitRoot ? (0, import_node_path.resolve)(gitRoot) : null;
+  return (0, import_node_path.join)(
+    resolvedGitRoot ?? resolvedCwd,
+    DEFAULT_LOG_DIRECTORY_RELATIVE_PATH
+  );
+};
+var readRuntimeMetadata = ({
+  cwd,
+  gitRoot,
+  metadataPath
+} = {}) => {
+  const path9 = resolveRuntimeMetadataPath({ cwd, gitRoot, metadataPath });
+  if (!(0, import_node_fs.existsSync)(path9)) {
+    return null;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(path9, "utf8");
+    const parsed = JSON.parse(raw);
+    return sanitizeMetadata(parsed);
+  } catch {
+    return null;
+  }
+};
+var writeRuntimeMetadata = (metadata, {
+  cwd,
+  gitRoot,
+  metadataPath
+} = {}) => {
+  const path9 = resolveRuntimeMetadataPath({ cwd, gitRoot, metadataPath });
+  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(path9), { recursive: true });
+  (0, import_node_fs.writeFileSync)(path9, `${JSON.stringify(metadata, null, 2)}
+`, "utf8");
+  return path9;
+};
+var resolveCoreRuntime = (options = {}) => {
+  const env = options.env ?? process.env;
+  const resolvedCwd = resolveCwd(options.cwd);
+  const gitRoot = options.gitRoot === void 0 ? findGitRoot(resolvedCwd) : options.gitRoot ? (0, import_node_path.resolve)(options.gitRoot) : null;
+  const metadataPath = resolveRuntimeMetadataPath({
+    cwd: resolvedCwd,
+    gitRoot,
+    metadataPath: options.metadataPath
+  });
+  const metadata = options.metadata === void 0 ? readRuntimeMetadata({ metadataPath }) : sanitizeMetadata(options.metadata);
+  const deterministicPort = resolveDeterministicCorePort({
+    cwd: resolvedCwd,
+    gitRoot
+  });
+  const optionHost = normalizeHost(options.host);
+  const envHost = resolveEnvHost(env);
+  const metadataHost = normalizeHost(metadata?.host);
+  const host = optionHost ?? envHost ?? metadataHost ?? DEFAULT_HOST;
+  const hostSource = optionHost ? "option" : envHost ? "env" : metadataHost ? "metadata" : "default";
+  const optionPort = parsePort(options.port, "port", "throw");
+  const envPort = parsePort(
+    resolveEnvPortRaw(env),
+    "port",
+    options.strictEnvPort ? "throw" : "ignore"
+  );
+  const metadataPort = parsePort(metadata?.port, "port", "ignore");
+  let port;
+  let portSource;
+  if (optionPort !== void 0) {
+    port = optionPort;
+    portSource = "option";
+  } else if (envPort !== void 0) {
+    port = envPort;
+    portSource = "env";
+  } else if (metadataPort !== void 0) {
+    port = metadataPort;
+    portSource = "metadata";
+  } else {
+    port = deterministicPort;
+    portSource = "deterministic";
+  }
+  return {
+    host,
+    port,
+    hostSource,
+    portSource,
+    metadataPath,
+    metadata,
+    gitRoot,
+    worktreeId: resolveWorktreeId({ cwd: resolvedCwd, gitRoot }),
+    deterministicPort
+  };
+};
+
+// packages/shared/src/logging.ts
+var DEFAULT_LOG_ROTATION_MAX_BYTES = 10 * 1024 * 1024;
+var DEFAULT_LOG_RETENTION = 20;
+var DEFAULT_REDACT_KEYS = [
+  "authorization",
+  "cookie",
+  "setcookie",
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "accesstoken",
+  "refreshtoken",
+  "apikey",
+  "apikeyid",
+  "privatekey",
+  "clientsecret"
+];
+var REDACTED_VALUE = "[REDACTED]";
+var MAX_NORMALIZE_DEPTH = 8;
+var LOG_LEVEL_PRIORITY = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+var normalizeRedactionKey = (value) => value.replace(/[^a-zA-Z0-9]/g, "").toLowerCase();
+var sanitizeStreamName = (stream) => {
+  const sanitized = stream.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (sanitized.length === 0) {
+    throw new Error("Logger stream name must contain visible characters.");
+  }
+  return sanitized;
+};
+var normalizeForJson = (value, seen, depth = 0) => {
+  if (value === null) {
+    return null;
+  }
+  if (depth >= MAX_NORMALIZE_DEPTH) {
+    return "[MaxDepth]";
+  }
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "number" || valueType === "boolean") {
+    return value;
+  }
+  if (valueType === "bigint") {
+    return String(value);
+  }
+  if (valueType === "undefined" || valueType === "symbol" || valueType === "function") {
+    return String(value);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack ?? null
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeForJson(item, seen, depth + 1));
+  }
+  if (value instanceof Set) {
+    return Array.from(value.values()).map(
+      (item) => normalizeForJson(item, seen, depth + 1)
+    );
+  }
+  if (value instanceof Map) {
+    const mapped = {};
+    for (const [entryKey, entryValue] of value.entries()) {
+      mapped[String(entryKey)] = normalizeForJson(entryValue, seen, depth + 1);
+    }
+    return mapped;
+  }
+  if (typeof value === "object") {
+    const objectValue = value;
+    if (seen.has(objectValue)) {
+      return "[Circular]";
+    }
+    seen.add(objectValue);
+    const normalized = {};
+    for (const [key, nestedValue] of Object.entries(objectValue)) {
+      normalized[key] = normalizeForJson(nestedValue, seen, depth + 1);
+    }
+    seen.delete(objectValue);
+    return normalized;
+  }
+  return String(value);
+};
+var redactJson = (value, redactKeys) => {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactJson(item, redactKeys));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const record = value;
+  const redacted = {};
+  for (const [key, nestedValue] of Object.entries(record)) {
+    if (redactKeys.has(normalizeRedactionKey(key))) {
+      redacted[key] = REDACTED_VALUE;
+      continue;
+    }
+    redacted[key] = redactJson(nestedValue, redactKeys);
+  }
+  return redacted;
+};
+var streamFilePath = (logDir, stream) => (0, import_node_path2.join)(logDir, `${stream}.jsonl`);
+var rotationFilePath = (logDir, stream, index) => (0, import_node_path2.join)(logDir, `${stream}.${index}.jsonl`);
+var rotateStreamFiles = (logDir, stream, retention) => {
+  if (retention <= 1) {
+    (0, import_node_fs2.rmSync)(streamFilePath(logDir, stream), { force: true });
+    return;
+  }
+  const maxArchiveIndex = retention - 1;
+  (0, import_node_fs2.rmSync)(rotationFilePath(logDir, stream, maxArchiveIndex), { force: true });
+  for (let index = maxArchiveIndex - 1; index >= 1; index -= 1) {
+    const source = rotationFilePath(logDir, stream, index);
+    if (!(0, import_node_fs2.existsSync)(source)) {
+      continue;
+    }
+    const target = rotationFilePath(logDir, stream, index + 1);
+    (0, import_node_fs2.renameSync)(source, target);
+  }
+  const current = streamFilePath(logDir, stream);
+  if ((0, import_node_fs2.existsSync)(current)) {
+    (0, import_node_fs2.renameSync)(current, rotationFilePath(logDir, stream, 1));
+  }
+};
+var rotateIfNeeded = (state, pendingLine) => {
+  if (!(0, import_node_fs2.existsSync)(state.filePath)) {
+    return;
+  }
+  const pendingBytes = Buffer.byteLength(pendingLine, "utf8");
+  const currentSize = (0, import_node_fs2.statSync)(state.filePath).size;
+  if (currentSize + pendingBytes <= state.maxBytes) {
+    return;
+  }
+  rotateStreamFiles(state.logDir, state.stream, state.retention);
+};
+var buildLogger = (state, bindings) => {
+  const log = (level, event, fields = {}) => {
+    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[state.level]) {
+      return;
+    }
+    const payload = {
+      ts: state.now().toISOString(),
+      level,
+      stream: state.stream,
+      event,
+      ...bindings,
+      ...fields
+    };
+    const normalized = normalizeForJson(payload, /* @__PURE__ */ new WeakSet());
+    const redacted = redactJson(normalized, state.redactKeys);
+    const line = `${JSON.stringify(redacted)}
+`;
+    try {
+      rotateIfNeeded(state, line);
+      (0, import_node_fs2.appendFileSync)(state.filePath, line, "utf8");
+    } catch {
+    }
+  };
+  return {
+    stream: state.stream,
+    level: state.level,
+    logDir: state.logDir,
+    filePath: state.filePath,
+    child: (childBindings) => buildLogger(state, {
+      ...bindings,
+      ...childBindings
+    }),
+    log,
+    debug: (event, fields) => log("debug", event, fields),
+    info: (event, fields) => log("info", event, fields),
+    warn: (event, fields) => log("warn", event, fields),
+    error: (event, fields) => log("error", event, fields)
+  };
+};
+var createJsonlLogger = (options) => {
+  const stream = sanitizeStreamName(options.stream);
+  const logDir = resolveLogDirectory({
+    cwd: options.cwd,
+    gitRoot: options.gitRoot,
+    logDir: options.logDir
+  });
+  (0, import_node_fs2.mkdirSync)(logDir, { recursive: true });
+  const maxBytes = typeof options.maxBytes === "number" && options.maxBytes > 0 ? Math.floor(options.maxBytes) : DEFAULT_LOG_ROTATION_MAX_BYTES;
+  const retention = typeof options.retention === "number" && options.retention > 0 ? Math.max(1, Math.floor(options.retention)) : DEFAULT_LOG_RETENTION;
+  const state = {
+    stream,
+    level: options.level ?? "debug",
+    logDir,
+    filePath: streamFilePath(logDir, stream),
+    maxBytes,
+    retention,
+    redactKeys: new Set(
+      (options.redactKeys ?? DEFAULT_REDACT_KEYS).map(normalizeRedactionKey)
+    ),
+    now: options.now ?? (() => /* @__PURE__ */ new Date())
+  };
+  return buildLogger(state, options.bindings ?? {});
+};
+
 // packages/shared/src/schemas.ts
 var import_zod2 = require("zod");
 var LocatorRoleSchema = import_zod2.z.object({
@@ -589,7 +1081,7 @@ var import_zod3 = require("zod");
 
 // packages/cli/src/core-client.ts
 var import_node_child_process = require("node:child_process");
-var import_node_path = require("node:path");
+var import_node_path3 = require("node:path");
 var import_promises = require("node:timers/promises");
 var CoreClientError = class extends Error {
   constructor(info) {
@@ -598,29 +1090,9 @@ var CoreClientError = class extends Error {
     this.info = info;
   }
 };
-var DEFAULT_HOST = "127.0.0.1";
-var DEFAULT_PORT = 3210;
 var DEFAULT_TIMEOUT_MS = 3e4;
 var HEALTH_RETRY_MS = 250;
 var HEALTH_ATTEMPTS = 20;
-var resolveHost = (host) => {
-  const candidate = host?.trim() || process.env.BROWSER_BRIDGE_CORE_HOST || process.env.BROWSER_VISION_CORE_HOST;
-  if (candidate && candidate.length > 0) {
-    return candidate;
-  }
-  return DEFAULT_HOST;
-};
-var resolvePort = (port) => {
-  const candidate = port ?? (process.env.BROWSER_BRIDGE_CORE_PORT ? Number.parseInt(process.env.BROWSER_BRIDGE_CORE_PORT, 10) : process.env.BROWSER_VISION_CORE_PORT ? Number.parseInt(process.env.BROWSER_VISION_CORE_PORT, 10) : void 0);
-  if (candidate === void 0 || candidate === null) {
-    return DEFAULT_PORT;
-  }
-  const parsed = typeof candidate === "number" ? candidate : Number.parseInt(candidate, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`Invalid port: ${String(candidate)}`);
-  }
-  return parsed;
-};
 var resolveTimeoutMs = (timeoutMs) => {
   const candidate = timeoutMs ?? (process.env.BROWSER_BRIDGE_CORE_TIMEOUT_MS ? Number.parseInt(process.env.BROWSER_BRIDGE_CORE_TIMEOUT_MS, 10) : process.env.BROWSER_VISION_CORE_TIMEOUT_MS ? Number.parseInt(process.env.BROWSER_VISION_CORE_TIMEOUT_MS, 10) : void 0);
   if (candidate === void 0 || candidate === null) {
@@ -633,21 +1105,48 @@ var resolveTimeoutMs = (timeoutMs) => {
   return Math.floor(parsed);
 };
 var normalizePath = (path9) => path9.startsWith("/") ? path9 : `/${path9}`;
+var durationMs = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
 var createCoreClient = (options = {}) => {
-  const host = resolveHost(options.host);
-  const port = resolvePort(options.port);
-  const baseUrl = `http://${host}:${port}`;
+  const logger = options.logger ?? createJsonlLogger({
+    stream: "cli",
+    cwd: options.cwd
+  }).child({ scope: "core-client" });
+  let runtime = resolveCoreRuntime({
+    host: options.host,
+    port: options.port,
+    cwd: options.cwd,
+    strictEnvPort: true
+  });
+  let baseUrl = `http://${runtime.host}:${runtime.port}`;
   const timeoutMs = resolveTimeoutMs(options.timeoutMs);
   const fetchImpl = options.fetchImpl ?? fetch;
   const spawnImpl = options.spawnImpl ?? import_node_child_process.spawn;
   const ensureDaemon = options.ensureDaemon ?? true;
+  const allowRuntimeRefresh = options.host === void 0 && options.port === void 0 && process.env.BROWSER_BRIDGE_CORE_HOST === void 0 && process.env.BROWSER_VISION_CORE_HOST === void 0 && process.env.BROWSER_BRIDGE_CORE_PORT === void 0 && process.env.BROWSER_VISION_CORE_PORT === void 0;
+  const refreshRuntime = () => {
+    if (!allowRuntimeRefresh) {
+      return;
+    }
+    runtime = resolveCoreRuntime({
+      cwd: options.cwd,
+      strictEnvPort: true
+    });
+    baseUrl = `http://${runtime.host}:${runtime.port}`;
+  };
   const requestJson = async (method, path9, body) => {
+    const requestPath = normalizePath(path9);
+    const startedAt = process.hrtime.bigint();
+    logger.debug("cli.core.request.start", {
+      method,
+      path: requestPath,
+      base_url: baseUrl
+    });
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
       let response;
       try {
-        response = await fetchImpl(`${baseUrl}${normalizePath(path9)}`, {
+        response = await fetchImpl(`${baseUrl}${requestPath}`, {
           method,
           headers: {
             "content-type": "application/json"
@@ -657,6 +1156,13 @@ var createCoreClient = (options = {}) => {
         });
       } catch (error) {
         if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+          logger.warn("cli.core.request.timeout", {
+            method,
+            path: requestPath,
+            base_url: baseUrl,
+            timeout_ms: timeoutMs,
+            duration_ms: durationMs(startedAt)
+          });
           throw new CoreClientError({
             code: "TIMEOUT",
             message: `Core request timed out after ${timeoutMs}ms.`,
@@ -664,20 +1170,50 @@ var createCoreClient = (options = {}) => {
             details: {
               timeout_ms: timeoutMs,
               base_url: baseUrl,
-              path: normalizePath(path9)
+              path: requestPath
             }
           });
         }
+        logger.error("cli.core.request.failed", {
+          method,
+          path: requestPath,
+          base_url: baseUrl,
+          duration_ms: durationMs(startedAt),
+          error
+        });
         throw error;
       }
       const raw = await response.text();
       if (!raw) {
+        logger.warn("cli.core.request.empty_response", {
+          method,
+          path: requestPath,
+          base_url: baseUrl,
+          status: response.status,
+          duration_ms: durationMs(startedAt)
+        });
         throw new Error(`Empty response from Core (${response.status}).`);
       }
       try {
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        logger.debug("cli.core.request.end", {
+          method,
+          path: requestPath,
+          base_url: baseUrl,
+          status: response.status,
+          duration_ms: durationMs(startedAt)
+        });
+        return parsed;
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown JSON parse error";
+        logger.error("cli.core.request.invalid_json", {
+          method,
+          path: requestPath,
+          base_url: baseUrl,
+          status: response.status,
+          duration_ms: durationMs(startedAt),
+          error
+        });
         throw new Error(`Failed to parse Core response: ${message}`);
       }
     } finally {
@@ -697,56 +1233,108 @@ var createCoreClient = (options = {}) => {
           });
         } catch (error) {
           if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+            logger.warn("cli.core.health.timeout", {
+              base_url: baseUrl,
+              timeout_ms: timeoutMs
+            });
             return false;
           }
+          logger.warn("cli.core.health.fetch_failed", {
+            base_url: baseUrl,
+            error
+          });
           throw error;
         }
         if (!response.ok) {
+          logger.warn("cli.core.health.non_ok", {
+            base_url: baseUrl,
+            status: response.status
+          });
           return false;
         }
         const data = await response.json().catch(() => null);
-        return Boolean(data?.ok);
+        const ok = Boolean(data?.ok);
+        if (!ok) {
+          logger.warn("cli.core.health.not_ready", {
+            base_url: baseUrl
+          });
+        }
+        return ok;
       } finally {
         clearTimeout(timeout);
       }
-    } catch {
+    } catch (error) {
+      logger.warn("cli.core.health.error", {
+        base_url: baseUrl,
+        error
+      });
       return false;
     }
   };
   const spawnDaemon = () => {
-    const coreEntry = (0, import_node_path.resolve)(__dirname, "api.js");
+    const coreEntry = (0, import_node_path3.resolve)(__dirname, "api.js");
+    const startOptions = [];
+    if (runtime.hostSource === "option" || runtime.hostSource === "env") {
+      startOptions.push(`host: ${JSON.stringify(runtime.host)}`);
+    }
+    if (runtime.portSource === "option" || runtime.portSource === "env") {
+      startOptions.push(`port: ${runtime.port}`);
+    }
     const script = `const { startCoreServer } = require(${JSON.stringify(
       coreEntry
     )});
-startCoreServer({ host: ${JSON.stringify(
-      host
-    )}, port: ${port} })
+startCoreServer({ ${startOptions.join(
+      ", "
+    )} })
   .catch((err) => { console.error(err); process.exit(1); });`;
+    logger.info("cli.core.spawn.start", {
+      host: runtime.host,
+      port: runtime.port,
+      host_source: runtime.hostSource,
+      port_source: runtime.portSource
+    });
     const child = spawnImpl(process.execPath, ["-e", script], {
       detached: true,
       stdio: "ignore",
-      env: {
-        ...process.env,
-        BROWSER_BRIDGE_CORE_HOST: host,
-        BROWSER_BRIDGE_CORE_PORT: String(port),
-        BROWSER_VISION_CORE_HOST: host,
-        BROWSER_VISION_CORE_PORT: String(port)
-      }
+      env: { ...process.env }
+    });
+    child.on("error", (error) => {
+      logger.error("cli.core.spawn.error", {
+        host: runtime.host,
+        port: runtime.port,
+        error
+      });
     });
     child.unref();
   };
   const ensureCoreRunning = async () => {
+    refreshRuntime();
     if (await checkHealth()) {
+      logger.debug("cli.core.ensure_ready.already_running", {
+        base_url: baseUrl
+      });
       return;
     }
     spawnDaemon();
     for (let attempt = 0; attempt < HEALTH_ATTEMPTS; attempt += 1) {
       await (0, import_promises.setTimeout)(HEALTH_RETRY_MS);
+      refreshRuntime();
       if (await checkHealth()) {
+        logger.info("cli.core.ensure_ready.ready", {
+          base_url: baseUrl,
+          attempts: attempt + 1
+        });
         return;
       }
     }
-    throw new Error(`Core daemon failed to start on ${host}:${port}.`);
+    logger.error("cli.core.ensure_ready.failed", {
+      host: runtime.host,
+      port: runtime.port,
+      attempts: HEALTH_ATTEMPTS
+    });
+    throw new Error(
+      `Core daemon failed to start on ${runtime.host}:${runtime.port}.`
+    );
   };
   let ensurePromise = null;
   const ensureReady = async () => {
@@ -760,9 +1348,16 @@ startCoreServer({ host: ${JSON.stringify(
   };
   const post = async (path9, body) => {
     await ensureReady();
+    refreshRuntime();
     return requestJson("POST", path9, body);
   };
-  return { baseUrl, ensureReady, post };
+  return {
+    get baseUrl() {
+      return baseUrl;
+    },
+    ensureReady,
+    post
+  };
 };
 
 // packages/cli/src/cli-output.ts
@@ -857,37 +1452,76 @@ var getGlobalOptions = (command) => {
   const root = getRootCommand(command);
   return root.opts();
 };
-var createClientFromCommand = (command) => {
+var durationMs2 = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
+var commandLabel = (command) => {
+  const pieces = command.name().split(" ").filter((piece) => piece.length > 0);
+  return pieces.length > 0 ? pieces.join(".") : "unknown";
+};
+var createCliLogger = (command) => createJsonlLogger({ stream: "cli" }).child({
+  scope: "cli-runtime",
+  command: commandLabel(command)
+});
+var createClientFromCommand = (command, logger) => {
   const options = getGlobalOptions(command);
   return createCoreClient({
     host: options.host,
     port: options.port,
-    ensureDaemon: options.daemon !== false
+    ensureDaemon: options.daemon !== false,
+    logger: logger?.child({ scope: "core-client" })
   });
 };
 var runCommand = async (command, work) => {
   const options = getGlobalOptions(command);
-  const client = createClientFromCommand(command);
+  const logger = createCliLogger(command);
+  const startedAt = process.hrtime.bigint();
+  logger.info("cli.command.start", {
+    host: options.host ?? null,
+    port: options.port ?? null,
+    daemon: options.daemon !== false,
+    json: Boolean(options.json)
+  });
+  const client = createClientFromCommand(command, logger);
   try {
     const envelope2 = await work(client, options);
     outputEnvelope(envelope2, { json: Boolean(options.json) });
+    logger.info("cli.command.end", {
+      ok: envelope2.ok,
+      duration_ms: durationMs2(startedAt)
+    });
     if (!envelope2.ok) {
       process.exitCode = 1;
     }
   } catch (error) {
+    logger.error("cli.command.error", {
+      duration_ms: durationMs2(startedAt),
+      error
+    });
     outputError(error, { json: Boolean(options.json) });
     process.exitCode = 1;
   }
 };
 var runLocal = async (command, work) => {
   const options = getGlobalOptions(command);
+  const logger = createCliLogger(command).child({ mode: "local" });
+  const startedAt = process.hrtime.bigint();
+  logger.info("cli.command.start", {
+    json: Boolean(options.json)
+  });
   try {
     const envelope2 = await work(options);
     outputEnvelope(envelope2, { json: Boolean(options.json) });
+    logger.info("cli.command.end", {
+      ok: envelope2.ok,
+      duration_ms: durationMs2(startedAt)
+    });
     if (!envelope2.ok) {
       process.exitCode = 1;
     }
   } catch (error) {
+    logger.error("cli.command.error", {
+      duration_ms: durationMs2(startedAt),
+      error
+    });
     outputError(error, { json: Boolean(options.json) });
     process.exitCode = 1;
   }
@@ -971,6 +1605,149 @@ var registerDiagnosticsCommands = (program2) => {
   });
 };
 
+// packages/cli/src/open-path.ts
+var import_node_child_process2 = require("node:child_process");
+var openPath = async (target) => {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    const child2 = (0, import_node_child_process2.spawn)("open", [target], { detached: true, stdio: "ignore" });
+    child2.unref();
+    return;
+  }
+  if (platform === "win32") {
+    const child2 = (0, import_node_child_process2.spawn)("cmd", ["/c", "start", "", target], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child2.unref();
+    return;
+  }
+  const child = (0, import_node_child_process2.spawn)("xdg-open", [target], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+};
+
+// packages/cli/src/commands/dev.ts
+var ENV_EXTENSION_ID = "BROWSER_BRIDGE_EXTENSION_ID";
+var ACTIVATION_FLAG_PARAM = "bb_activate";
+var ACTIVATION_PORT_PARAM = "corePort";
+var ACTIVATION_WORKTREE_PARAM = "worktreeId";
+var normalizeToken = (value) => {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+};
+var resolveActivationExtensionId = (options) => {
+  const optionId = normalizeToken(options.optionExtensionId);
+  if (optionId) {
+    return { extensionId: optionId, source: "flag" };
+  }
+  const envId = normalizeToken(options.envExtensionId);
+  if (envId) {
+    return { extensionId: envId, source: "env" };
+  }
+  const metadataId = normalizeToken(options.metadataExtensionId);
+  if (metadataId) {
+    return { extensionId: metadataId, source: "metadata" };
+  }
+  return null;
+};
+var buildActivationOptionsUrl = (options) => {
+  const search = new URLSearchParams();
+  search.set(ACTIVATION_FLAG_PARAM, "1");
+  search.set(ACTIVATION_PORT_PARAM, String(options.corePort));
+  if (options.worktreeId) {
+    search.set(ACTIVATION_WORKTREE_PARAM, options.worktreeId);
+  }
+  return `chrome-extension://${options.extensionId}/options.html?${search.toString()}`;
+};
+var buildPersistedRuntimeMetadata = (runtime, extensionId) => ({
+  host: runtime.host,
+  port: runtime.port,
+  git_root: runtime.gitRoot ?? runtime.metadata?.git_root,
+  worktree_id: runtime.worktreeId ?? runtime.metadata?.worktree_id,
+  extension_id: extensionId,
+  updated_at: (/* @__PURE__ */ new Date()).toISOString()
+});
+var resolveRuntimeForCommand = (options) => resolveCoreRuntime({
+  host: options.host,
+  port: options.port,
+  strictEnvPort: true
+});
+var registerDevCommands = (program2) => {
+  const dev = program2.command("dev").description("Development commands");
+  dev.command("info").description("Print resolved runtime details for the current worktree").action(async (_options, command) => {
+    await runLocal(command, async (globalOptions) => {
+      const runtime = resolveRuntimeForCommand(globalOptions);
+      const logDir = resolveLogDirectory({ gitRoot: runtime.gitRoot });
+      return {
+        ok: true,
+        result: {
+          host: runtime.host,
+          hostSource: runtime.hostSource,
+          port: runtime.port,
+          portSource: runtime.portSource,
+          deterministicPort: runtime.deterministicPort,
+          worktreeId: runtime.worktreeId,
+          metadataPath: runtime.metadataPath,
+          logDir,
+          metadataSnapshot: runtime.metadata
+        }
+      };
+    });
+  });
+  dev.command("activate").description(
+    "Persist worktree runtime metadata and open extension options for activation"
+  ).option(
+    "--extension-id <id>",
+    "Chrome extension id to activate for this worktree"
+  ).action(async (options, command) => {
+    await runLocal(command, async (globalOptions) => {
+      const runtime = resolveRuntimeForCommand(globalOptions);
+      const extension = resolveActivationExtensionId({
+        optionExtensionId: options.extensionId,
+        envExtensionId: process.env[ENV_EXTENSION_ID],
+        metadataExtensionId: runtime.metadata?.extension_id
+      });
+      if (!extension) {
+        throw new CliError({
+          code: "INVALID_ARGUMENT",
+          message: "Missing extension id. Provide --extension-id <id>, set BROWSER_BRIDGE_EXTENSION_ID, or persist extension_id in metadata by running dev activate with --extension-id once.",
+          retryable: false,
+          details: {
+            metadataPath: runtime.metadataPath
+          }
+        });
+      }
+      const metadataPath = writeRuntimeMetadata(
+        buildPersistedRuntimeMetadata(runtime, extension.extensionId),
+        { metadataPath: runtime.metadataPath }
+      );
+      const activationUrl = buildActivationOptionsUrl({
+        extensionId: extension.extensionId,
+        corePort: runtime.port,
+        worktreeId: runtime.worktreeId
+      });
+      await openPath(activationUrl);
+      return {
+        ok: true,
+        result: {
+          extensionId: extension.extensionId,
+          extensionIdSource: extension.source,
+          host: runtime.host,
+          port: runtime.port,
+          metadataPath,
+          activationUrl
+        }
+      };
+    });
+  });
+};
+
 // packages/cli/src/locator.ts
 var buildLocator = (options) => {
   const locator = {};
@@ -1418,39 +2195,36 @@ var registerInspectCommands = (program2) => {
 };
 
 // packages/mcp-adapter/src/core-client.ts
-var DEFAULT_HOST2 = "127.0.0.1";
-var DEFAULT_PORT2 = 3210;
 var DEFAULT_TIMEOUT_MS2 = 3e4;
-var resolveHost2 = (host) => {
-  const candidate = host?.trim() || process.env.BROWSER_BRIDGE_CORE_HOST || process.env.BROWSER_VISION_CORE_HOST;
-  if (candidate && candidate.length > 0) {
-    return candidate;
-  }
-  return DEFAULT_HOST2;
-};
-var resolvePort2 = (port) => {
-  const candidate = port ?? (process.env.BROWSER_BRIDGE_CORE_PORT ? Number.parseInt(process.env.BROWSER_BRIDGE_CORE_PORT, 10) : process.env.BROWSER_VISION_CORE_PORT ? Number.parseInt(process.env.BROWSER_VISION_CORE_PORT, 10) : void 0);
-  if (candidate === void 0 || candidate === null) {
-    return DEFAULT_PORT2;
-  }
-  const parsed = typeof candidate === "number" ? candidate : Number.parseInt(candidate, 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new Error(`Invalid port: ${String(candidate)}`);
-  }
-  return parsed;
-};
 var normalizePath2 = (path9) => path9.startsWith("/") ? path9 : `/${path9}`;
+var durationMs3 = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
 var createCoreClient2 = (options = {}) => {
-  const host = resolveHost2(options.host);
-  const port = resolvePort2(options.port);
+  const logger = options.logger ?? createJsonlLogger({
+    stream: "mcp-adapter",
+    cwd: options.cwd
+  }).child({ scope: "core-client" });
+  const runtime = resolveCoreRuntime({
+    host: options.host,
+    port: options.port,
+    cwd: options.cwd,
+    strictEnvPort: true
+  });
+  const host = runtime.host;
+  const port = runtime.port;
   const baseUrl = `http://${host}:${port}`;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
   const fetchImpl = options.fetchImpl ?? fetch;
   const requestJson = async (path9, body) => {
+    const requestPath = normalizePath2(path9);
+    const startedAt = process.hrtime.bigint();
+    logger.debug("mcp.core.request.start", {
+      path: requestPath,
+      base_url: baseUrl
+    });
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      const response = await fetchImpl(`${baseUrl}${normalizePath2(path9)}`, {
+      const response = await fetchImpl(`${baseUrl}${requestPath}`, {
         method: "POST",
         headers: {
           "content-type": "application/json"
@@ -1460,14 +2234,42 @@ var createCoreClient2 = (options = {}) => {
       });
       const raw = await response.text();
       if (!raw) {
+        logger.warn("mcp.core.request.empty_response", {
+          path: requestPath,
+          base_url: baseUrl,
+          status: response.status,
+          duration_ms: durationMs3(startedAt)
+        });
         throw new Error(`Empty response from Core (${response.status}).`);
       }
       try {
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        logger.debug("mcp.core.request.end", {
+          path: requestPath,
+          base_url: baseUrl,
+          status: response.status,
+          duration_ms: durationMs3(startedAt)
+        });
+        return parsed;
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown JSON parse error";
+        logger.error("mcp.core.request.invalid_json", {
+          path: requestPath,
+          base_url: baseUrl,
+          status: response.status,
+          duration_ms: durationMs3(startedAt),
+          error
+        });
         throw new Error(`Failed to parse Core response: ${message}`);
       }
+    } catch (error) {
+      logger.error("mcp.core.request.failed", {
+        path: requestPath,
+        base_url: baseUrl,
+        duration_ms: durationMs3(startedAt),
+        error
+      });
+      throw error;
     } finally {
       clearTimeout(timeout);
     }
@@ -1913,25 +2715,57 @@ var DEFAULT_SERVER_NAME = "browser-bridge";
 var DEFAULT_SERVER_VERSION = "0.0.0";
 var DEFAULT_HTTP_HOST = "127.0.0.1";
 var DEFAULT_HTTP_PATH = "/mcp";
+var durationMs4 = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
+var resolveAdapterLogger = (options) => options.logger ?? createJsonlLogger({
+  stream: "mcp-adapter",
+  cwd: options.cwd
+});
 var createMcpServer = (options = {}) => {
+  const logger = resolveAdapterLogger(options);
   const server = new import_mcp.McpServer({
     name: options.name ?? DEFAULT_SERVER_NAME,
     version: options.version ?? DEFAULT_SERVER_VERSION
   });
-  const client = options.coreClient ?? createCoreClient2(options);
+  const client = options.coreClient ?? createCoreClient2({
+    ...options,
+    logger: logger.child({ scope: "core-client" })
+  });
   registerBrowserBridgeTools(server, client);
+  logger.info("mcp.server.created", {
+    name: options.name ?? DEFAULT_SERVER_NAME,
+    version: options.version ?? DEFAULT_SERVER_VERSION,
+    core_base_url: client.baseUrl
+  });
   return { server, client };
 };
 var startMcpServer = async (options = {}) => {
-  const handle = createMcpServer(options);
+  const logger = resolveAdapterLogger(options);
+  logger.info("mcp.stdio.start.begin", {
+    name: options.name ?? DEFAULT_SERVER_NAME,
+    version: options.version ?? DEFAULT_SERVER_VERSION
+  });
+  const handle = createMcpServer({
+    ...options,
+    logger
+  });
   const transport = new import_stdio.StdioServerTransport();
-  await handle.server.connect(transport);
+  try {
+    await handle.server.connect(transport);
+    logger.info("mcp.stdio.start.ready", {
+      core_base_url: handle.client.baseUrl
+    });
+  } catch (error) {
+    logger.error("mcp.stdio.start.failed", {
+      error
+    });
+    throw error;
+  }
   return { ...handle, transport };
 };
 var readJsonBody = async (req, maxBytes = 5 * 1024 * 1024) => {
   const chunks = [];
   let total = 0;
-  await new Promise((resolve2, reject) => {
+  await new Promise((resolve3, reject) => {
     req.on("data", (chunk) => {
       total += chunk.length;
       if (total > maxBytes) {
@@ -1941,7 +2775,7 @@ var readJsonBody = async (req, maxBytes = 5 * 1024 * 1024) => {
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolve2());
+    req.on("end", () => resolve3());
     req.on("error", (err) => reject(err));
   });
   const raw = Buffer.concat(chunks).toString("utf8");
@@ -1960,10 +2794,19 @@ var getHeaderValue = (value) => {
   return void 0;
 };
 var startMcpHttpServer = async (options = {}) => {
+  const logger = resolveAdapterLogger(options).child({ scope: "http-server" });
   const host = options.host ?? DEFAULT_HTTP_HOST;
   const port = typeof options.port === "number" ? options.port : 0;
   const path9 = options.path ?? DEFAULT_HTTP_PATH;
-  const client = options.coreClient ?? createCoreClient2(options);
+  logger.info("mcp.http.start.begin", {
+    host,
+    port,
+    path: path9
+  });
+  const client = options.coreClient ?? createCoreClient2({
+    ...options,
+    logger: logger.child({ scope: "core-client" })
+  });
   const sessions = /* @__PURE__ */ new Map();
   const closeAllSessions = async () => {
     const entries = Array.from(sessions.values());
@@ -1982,23 +2825,52 @@ var startMcpHttpServer = async (options = {}) => {
     );
   };
   const httpServer = (0, import_node_http.createServer)(async (req, res) => {
+    const startedAt = process.hrtime.bigint();
+    const requestLogger = logger.child({
+      scope: "http-request",
+      request_id: (0, import_node_crypto.randomUUID)()
+    });
+    requestLogger.debug("mcp.http.request.start", {
+      method: req.method,
+      url: req.url ?? ""
+    });
     try {
       const url = new URL(req.url ?? "", `http://${host}`);
       if (url.pathname !== path9) {
         res.writeHead(404, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: "Not Found" }));
+        requestLogger.warn("mcp.http.request.not_found", {
+          method: req.method,
+          pathname: url.pathname,
+          expected_path: path9,
+          status: 404,
+          duration_ms: durationMs4(startedAt)
+        });
         return;
       }
       const sessionId = getHeaderValue(req.headers["mcp-session-id"]);
+      requestLogger.debug("mcp.http.request.session", {
+        session_id: sessionId ?? null
+      });
       const parsedBody = req.method === "POST" ? await readJsonBody(req) : void 0;
       if (sessionId) {
         const entry = sessions.get(sessionId);
         if (!entry) {
           res.writeHead(404, { "content-type": "application/json" });
           res.end(JSON.stringify({ error: "Unknown session." }));
+          requestLogger.warn("mcp.http.request.unknown_session", {
+            session_id: sessionId,
+            status: 404,
+            duration_ms: durationMs4(startedAt)
+          });
           return;
         }
         await entry.transport.handleRequest(req, res, parsedBody);
+        requestLogger.info("mcp.http.request.forwarded", {
+          session_id: sessionId,
+          status: res.statusCode,
+          duration_ms: durationMs4(startedAt)
+        });
         return;
       }
       if (req.method !== "POST" || !(0, import_types.isInitializeRequest)(parsedBody)) {
@@ -2008,6 +2880,11 @@ var startMcpHttpServer = async (options = {}) => {
             error: "Missing mcp-session-id header. First request must be initialize."
           })
         );
+        requestLogger.warn("mcp.http.request.invalid_initialize", {
+          method: req.method,
+          status: 400,
+          duration_ms: durationMs4(startedAt)
+        });
         return;
       }
       let sessionEntry;
@@ -2016,6 +2893,9 @@ var startMcpHttpServer = async (options = {}) => {
         onsessioninitialized: (sid) => {
           if (sessionEntry) {
             sessions.set(sid, sessionEntry);
+            logger.info("mcp.http.session.opened", {
+              session_id: sid
+            });
           }
         },
         onsessionclosed: async (sid) => {
@@ -2028,6 +2908,9 @@ var startMcpHttpServer = async (options = {}) => {
             entry.transport.close(),
             entry.server.close()
           ]);
+          logger.info("mcp.http.session.closed", {
+            session_id: sid
+          });
         }
       });
       const sessionServer = new import_mcp.McpServer({
@@ -2038,7 +2921,18 @@ var startMcpHttpServer = async (options = {}) => {
       await sessionServer.connect(transport);
       sessionEntry = { transport, server: sessionServer };
       await transport.handleRequest(req, res, parsedBody);
+      requestLogger.info("mcp.http.request.initialized", {
+        status: res.statusCode,
+        duration_ms: durationMs4(startedAt)
+      });
     } catch (error) {
+      requestLogger.error("mcp.http.request.error", {
+        method: req.method,
+        url: req.url ?? "",
+        status: 500,
+        duration_ms: durationMs4(startedAt),
+        error
+      });
       res.writeHead(500, { "content-type": "application/json" });
       res.end(
         JSON.stringify({
@@ -2047,29 +2941,43 @@ var startMcpHttpServer = async (options = {}) => {
       );
     }
   });
-  const resolvedPort = await new Promise((resolve2, reject) => {
+  const resolvedPort = await new Promise((resolve3, reject) => {
     httpServer.listen(port, host, () => {
       const address = httpServer.address();
-      resolve2(typeof address === "object" && address ? address.port : port);
+      resolve3(typeof address === "object" && address ? address.port : port);
     });
     httpServer.on("error", reject);
   });
+  logger.info("mcp.http.start.ready", {
+    host,
+    port: resolvedPort,
+    path: path9,
+    core_base_url: client.baseUrl
+  });
   return {
     client,
     host,
     port: resolvedPort,
     path: path9,
     close: async () => {
-      await new Promise((resolve2, reject) => {
+      logger.info("mcp.http.stop.begin", {
+        host,
+        port: resolvedPort
+      });
+      await new Promise((resolve3, reject) => {
         httpServer.close((err) => {
           if (err) {
             reject(err);
           } else {
-            resolve2();
+            resolve3();
           }
         });
       });
       await closeAllSessions();
+      logger.info("mcp.http.stop.complete", {
+        host,
+        port: resolvedPort
+      });
     }
   };
 };
@@ -2098,19 +3006,19 @@ var checkboxPrompt = async (options) => {
 };
 
 // packages/cli/src/installer/mcp-install.ts
-var import_node_child_process2 = require("node:child_process");
+var import_node_child_process3 = require("node:child_process");
 
 // packages/cli/src/installer/cursor-mcp.ts
 var import_promises2 = __toESM(require("node:fs/promises"));
 var import_node_os = __toESM(require("node:os"));
-var import_node_path2 = __toESM(require("node:path"));
+var import_node_path4 = __toESM(require("node:path"));
 var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var resolveCursorUserSettingsPath = (options) => {
   const platform = options?.platform ?? process.platform;
   const homeDir = options?.homeDir ?? import_node_os.default.homedir();
   const env = options?.env ?? process.env;
   if (platform === "darwin") {
-    return import_node_path2.default.join(
+    return import_node_path4.default.join(
       homeDir,
       "Library",
       "Application Support",
@@ -2126,13 +3034,13 @@ var resolveCursorUserSettingsPath = (options) => {
         "APPDATA is not set; cannot resolve Cursor settings path."
       );
     }
-    return import_node_path2.default.join(appData, "Cursor", "User", "settings.json");
+    return import_node_path4.default.join(appData, "Cursor", "User", "settings.json");
   }
-  return import_node_path2.default.join(homeDir, ".config", "Cursor", "User", "settings.json");
+  return import_node_path4.default.join(homeDir, ".config", "Cursor", "User", "settings.json");
 };
 var installCursorMcp = async (settingsPath) => {
   const filePath = settingsPath ?? resolveCursorUserSettingsPath();
-  const dir = import_node_path2.default.dirname(filePath);
+  const dir = import_node_path4.default.dirname(filePath);
   await import_promises2.default.mkdir(dir, { recursive: true });
   let settings = {};
   try {
@@ -2168,15 +3076,15 @@ var installCursorMcp = async (settingsPath) => {
 
 // packages/cli/src/installer/mcp-install.ts
 var runQuiet = async (cmd, args) => {
-  await new Promise((resolve2, reject) => {
-    const child = (0, import_node_child_process2.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+  await new Promise((resolve3, reject) => {
+    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
     child.stderr?.on("data", (chunk) => {
       stderr += String(chunk);
     });
     child.on("error", reject);
     child.on("exit", (code) => {
-      if (code === 0) resolve2();
+      if (code === 0) resolve3();
       else {
         const suffix = stderr.trim() ? `: ${stderr.trim()}` : "";
         reject(new Error(`${cmd} exited with ${code ?? "unknown"}${suffix}`));
@@ -2344,10 +3252,10 @@ var import_turndown = __toESM(require("turndown"));
 // packages/core/src/artifacts.ts
 var import_promises3 = require("node:fs/promises");
 var import_node_os2 = __toESM(require("node:os"));
-var import_node_path3 = __toESM(require("node:path"));
+var import_node_path5 = __toESM(require("node:path"));
 var ARTIFACTS_DIR_NAME = "browser-agent";
 var resolveTempRoot = () => process.env.TMPDIR || process.env.TEMP || process.env.TMP || import_node_os2.default.tmpdir();
-var getArtifactRootDir = (sessionId) => import_node_path3.default.join(resolveTempRoot(), ARTIFACTS_DIR_NAME, sessionId);
+var getArtifactRootDir = (sessionId) => import_node_path5.default.join(resolveTempRoot(), ARTIFACTS_DIR_NAME, sessionId);
 var ensureArtifactRootDir = async (sessionId) => {
   const rootDir = getArtifactRootDir(sessionId);
   await (0, import_promises3.mkdir)(rootDir, { recursive: true });
@@ -2482,30 +3390,6 @@ var PROCESS_STARTED_AT = new Date(
   Date.now() - Math.floor(process.uptime() * 1e3)
 ).toISOString();
 
-// packages/cli/src/open-path.ts
-var import_node_child_process3 = require("node:child_process");
-var openPath = async (target) => {
-  const platform = process.platform;
-  if (platform === "darwin") {
-    const child2 = (0, import_node_child_process3.spawn)("open", [target], { detached: true, stdio: "ignore" });
-    child2.unref();
-    return;
-  }
-  if (platform === "win32") {
-    const child2 = (0, import_node_child_process3.spawn)("cmd", ["/c", "start", "", target], {
-      detached: true,
-      stdio: "ignore"
-    });
-    child2.unref();
-    return;
-  }
-  const child = (0, import_node_child_process3.spawn)("xdg-open", [target], {
-    detached: true,
-    stdio: "ignore"
-  });
-  child.unref();
-};
-
 // packages/cli/src/commands/open-artifacts.ts
 var registerOpenArtifactsCommand = (program2) => {
   program2.command("open-artifacts").description("Open the artifact folder for a session").requiredOption("--session-id <id>", "Session identifier").action(async (options, command) => {
@@ -2558,60 +3442,60 @@ var registerSessionCommands = (program2) => {
 // packages/cli/src/commands/skill.ts
 var import_promises7 = __toESM(require("node:fs/promises"));
 var import_node_os4 = __toESM(require("node:os"));
-var import_node_path8 = __toESM(require("node:path"));
+var import_node_path10 = __toESM(require("node:path"));
 
 // packages/cli/src/installer/harness-targets.ts
 var import_node_os3 = __toESM(require("node:os"));
-var import_node_path4 = __toESM(require("node:path"));
+var import_node_path6 = __toESM(require("node:path"));
 var getDefaultHarnessTargets = (homeDir) => {
   const home = homeDir ?? import_node_os3.default.homedir();
   return [
     {
       id: "codex",
       label: "Codex",
-      skillsDir: import_node_path4.default.join(home, ".agents", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".agents", "skills"),
       supportsMcpInstall: true
     },
     {
       id: "claude",
       label: "Claude",
-      skillsDir: import_node_path4.default.join(home, ".claude", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".claude", "skills"),
       supportsMcpInstall: true
     },
     {
       id: "cursor",
       label: "Cursor",
-      skillsDir: import_node_path4.default.join(home, ".cursor", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".cursor", "skills"),
       supportsMcpInstall: true
     },
     {
       id: "factory",
       label: "Factory",
-      skillsDir: import_node_path4.default.join(home, ".factory", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".factory", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "opencode",
       label: "OpenCode",
-      skillsDir: import_node_path4.default.join(home, ".opencode", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".opencode", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "gemini",
       label: "Gemini",
-      skillsDir: import_node_path4.default.join(home, ".gemini", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".gemini", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "github",
       label: "GitHub",
-      skillsDir: import_node_path4.default.join(home, ".github", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".github", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "ampcode",
       label: "Ampcode",
-      skillsDir: import_node_path4.default.join(home, ".ampcode", "skills"),
+      skillsDir: import_node_path6.default.join(home, ".ampcode", "skills"),
       supportsMcpInstall: false
     }
   ];
@@ -2619,7 +3503,7 @@ var getDefaultHarnessTargets = (homeDir) => {
 
 // packages/cli/src/installer/package-info.ts
 var import_promises4 = __toESM(require("node:fs/promises"));
-var import_node_path5 = __toESM(require("node:path"));
+var import_node_path7 = __toESM(require("node:path"));
 var PACKAGE_NAME = "@btraut/browser-bridge";
 var tryReadJson = async (filePath) => {
   try {
@@ -2632,12 +3516,12 @@ var tryReadJson = async (filePath) => {
 var resolveCliPackageRootDir = async () => {
   let dir = __dirname;
   for (let i = 0; i < 12; i++) {
-    const candidate = import_node_path5.default.join(dir, "package.json");
+    const candidate = import_node_path7.default.join(dir, "package.json");
     const parsed = await tryReadJson(candidate);
     if (parsed && parsed.name === PACKAGE_NAME) {
       return dir;
     }
-    const parent = import_node_path5.default.dirname(dir);
+    const parent = import_node_path7.default.dirname(dir);
     if (parent === dir) {
       break;
     }
@@ -2649,7 +3533,7 @@ var resolveCliPackageRootDir = async () => {
 };
 var readCliPackageVersion = async () => {
   const rootDir = await resolveCliPackageRootDir();
-  const pkgPath = import_node_path5.default.join(rootDir, "package.json");
+  const pkgPath = import_node_path7.default.join(rootDir, "package.json");
   const parsed = await tryReadJson(pkgPath);
   if (!parsed || typeof parsed.version !== "string" || !parsed.version) {
     throw new Error(`Unable to read version from ${pkgPath}`);
@@ -2658,14 +3542,14 @@ var readCliPackageVersion = async () => {
 };
 var resolveSkillSourceDir = async () => {
   const rootDir = await resolveCliPackageRootDir();
-  const packaged = import_node_path5.default.join(rootDir, "skills", "browser-bridge");
+  const packaged = import_node_path7.default.join(rootDir, "skills", "browser-bridge");
   try {
     await import_promises4.default.stat(packaged);
     return packaged;
   } catch {
   }
-  const repoRoot = import_node_path5.default.resolve(rootDir, "..", "..");
-  const docsSkill = import_node_path5.default.join(repoRoot, "docs", "skills", "browser-bridge");
+  const repoRoot = import_node_path7.default.resolve(rootDir, "..", "..");
+  const docsSkill = import_node_path7.default.join(repoRoot, "docs", "skills", "browser-bridge");
   try {
     await import_promises4.default.stat(docsSkill);
     return docsSkill;
@@ -2678,16 +3562,16 @@ var resolveSkillSourceDir = async () => {
 
 // packages/cli/src/installer/skill-install.ts
 var import_promises6 = __toESM(require("node:fs/promises"));
-var import_node_path7 = __toESM(require("node:path"));
+var import_node_path9 = __toESM(require("node:path"));
 
 // packages/cli/src/installer/skill-manifest.ts
 var import_promises5 = __toESM(require("node:fs/promises"));
-var import_node_path6 = __toESM(require("node:path"));
+var import_node_path8 = __toESM(require("node:path"));
 var SKILL_MANIFEST_FILENAME = "skill.json";
 var readSkillManifest = async (skillDir) => {
   try {
     const raw = await import_promises5.default.readFile(
-      import_node_path6.default.join(skillDir, SKILL_MANIFEST_FILENAME),
+      import_node_path8.default.join(skillDir, SKILL_MANIFEST_FILENAME),
       "utf8"
     );
     const parsed = JSON.parse(raw);
@@ -2702,7 +3586,7 @@ var readSkillManifest = async (skillDir) => {
 var writeSkillManifest = async (skillDir, version) => {
   const payload = { name: "browser-bridge", version };
   await import_promises5.default.writeFile(
-    import_node_path6.default.join(skillDir, SKILL_MANIFEST_FILENAME),
+    import_node_path8.default.join(skillDir, SKILL_MANIFEST_FILENAME),
     JSON.stringify(payload, null, 2) + "\n",
     "utf8"
   );
@@ -2710,7 +3594,7 @@ var writeSkillManifest = async (skillDir, version) => {
 
 // packages/cli/src/installer/skill-install.ts
 var installBrowserBridgeSkill = async (options) => {
-  const destDir = import_node_path7.default.join(options.destSkillsDir, "browser-bridge");
+  const destDir = import_node_path9.default.join(options.destSkillsDir, "browser-bridge");
   await import_promises6.default.mkdir(options.destSkillsDir, { recursive: true });
   await import_promises6.default.rm(destDir, { recursive: true, force: true });
   await import_promises6.default.cp(options.srcSkillDir, destDir, { recursive: true });
@@ -2722,9 +3606,9 @@ var installBrowserBridgeSkill = async (options) => {
 var getHarnessMarkerDir = (homeDir, harness) => {
   switch (harness) {
     case "codex":
-      return import_node_path8.default.join(homeDir, ".agents");
+      return import_node_path10.default.join(homeDir, ".agents");
     default:
-      return import_node_path8.default.join(homeDir, `.${harness}`);
+      return import_node_path10.default.join(homeDir, `.${harness}`);
   }
 };
 var registerSkillCommands = (program2) => {
@@ -2802,7 +3686,7 @@ var registerSkillCommands = (program2) => {
       const targets = getDefaultHarnessTargets();
       const rows = [];
       for (const t of targets) {
-        const skillDir = import_node_path8.default.join(t.skillsDir, "browser-bridge");
+        const skillDir = import_node_path10.default.join(t.skillsDir, "browser-bridge");
         let installed = false;
         try {
           await import_promises7.default.stat(skillDir);
@@ -2830,7 +3714,7 @@ var registerSkillCommands = (program2) => {
 // packages/cli/src/commands/install.ts
 var import_promises8 = __toESM(require("node:fs/promises"));
 var import_node_os5 = __toESM(require("node:os"));
-var import_node_path9 = __toESM(require("node:path"));
+var import_node_path11 = __toESM(require("node:path"));
 var formatInstallSummary = (options) => {
   const wantsSkill = options.setup.includes("skill");
   const wantsMcp = options.setup.includes("mcp");
@@ -2865,9 +3749,9 @@ var getHarnessMarkerDir2 = (harness) => {
   const homeDir = import_node_os5.default.homedir();
   switch (harness) {
     case "codex":
-      return import_node_path9.default.join(homeDir, ".agents");
+      return import_node_path11.default.join(homeDir, ".agents");
     default:
-      return import_node_path9.default.join(homeDir, `.${harness}`);
+      return import_node_path11.default.join(homeDir, `.${harness}`);
   }
 };
 var registerInstallCommand = (program2) => {
@@ -2962,6 +3846,7 @@ registerInspectCommands(program);
 registerArtifactsCommands(program);
 registerDiagnosticsCommands(program);
 registerDialogCommands(program);
+registerDevCommands(program);
 registerOpenArtifactsCommand(program);
 registerMcpCommand(program);
 registerSkillCommands(program);