@fangyb/ahchat-bridge 0.1.21 → 0.1.23

package/dist/cli.cjs

@@ -3679,9 +3679,8 @@ var require_websocket_server = __commonJS({
 
 // src/cli.ts
 init_cjs_shims();
-var import_node_os13 = __toESM(require("os"), 1);
-var import_node_path22 = __toESM(require("path"), 1);
-var import_node_fs10 = __toESM(require("fs"), 1);
+var import_node_path23 = __toESM(require("path"), 1);
+var import_node_fs11 = __toESM(require("fs"), 1);
 
 // ../../node_modules/.pnpm/cac@6.7.14/node_modules/cac/dist/index.mjs
 init_cjs_shims();
@@ -5097,11 +5096,11 @@ var RotatingFileStream = class extends import_stream.Writable {
   timeout;
   timeoutPromise;
   constructor(generator, options) {
-    const { encoding, history, maxFiles, maxSize, path: path23 } = options;
+    const { encoding, history, maxFiles, maxSize, path: path24 } = options;
     super({ decodeStrings: true, defaultEncoding: encoding });
     this.createGzip = import_zlib.createGzip;
     this.exec = import_child_process.exec;
-    this.filename = path23 + generator(null);
+    this.filename = path24 + generator(null);
     this.fsCreateReadStream = import_fs.createReadStream;
     this.fsCreateWriteStream = import_fs.createWriteStream;
     this.fsOpen = import_promises.open;
@@ -5113,7 +5112,7 @@ var RotatingFileStream = class extends import_stream.Writable {
     this.options = options;
     this.stdout = process.stdout;
     if (maxFiles || maxSize)
-      options.history = path23 + (history ? history : this.generator(null) + ".txt");
+      options.history = path24 + (history ? history : this.generator(null) + ".txt");
     this.on("close", () => this.finished ? null : this.emit("finish"));
     this.on("finish", () => this.finished = this.clear());
     (async () => {
@@ -5241,9 +5240,9 @@ var RotatingFileStream = class extends import_stream.Writable {
     return this.move();
   }
   async findName() {
-    const { interval, path: path23, intervalBoundary } = this.options;
+    const { interval, path: path24, intervalBoundary } = this.options;
     for (let index = 1; index < 1e3; ++index) {
-      const filename = path23 + this.generator(interval && intervalBoundary ? new Date(this.prev) : this.rotation, index);
+      const filename = path24 + this.generator(interval && intervalBoundary ? new Date(this.prev) : this.rotation, index);
       if (!await exists(filename))
         return filename;
     }
@@ -5273,11 +5272,11 @@ var RotatingFileStream = class extends import_stream.Writable {
     return this.unlink(filename);
   }
   async classical() {
-    const { compress, path: path23, rotate } = this.options;
+    const { compress, path: path24, rotate } = this.options;
     let rotatedName = "";
     for (let count = rotate; count > 0; --count) {
-      const currName = path23 + this.generator(count);
-      const prevName = count === 1 ? this.filename : path23 + this.generator(count - 1);
+      const currName = path24 + this.generator(count);
+      const prevName = count === 1 ? this.filename : path24 + this.generator(count - 1);
       if (!await exists(prevName))
         continue;
       if (!rotatedName)
@@ -5715,7 +5714,7 @@ function createModuleLogger(module2) {
 
 // src/start.ts
 init_cjs_shims();
-var import_node_path20 = __toESM(require("path"), 1);
+var import_node_path21 = __toESM(require("path"), 1);
 
 // ../shared/src/index.ts
 init_cjs_shims();
@@ -29753,10 +29752,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path23) {
-  if (!path23)
+function getElementAtPath(obj, path24) {
+  if (!path24)
     return obj;
-  return path23.reduce((acc, key) => acc?.[key], obj);
+  return path24.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -30165,11 +30164,11 @@ function explicitlyAborted(x2, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path23, issues) {
+function prefixIssues(path24, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path23);
+    iss.path.unshift(path24);
     return iss;
   });
 }
@@ -30316,16 +30315,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path23 = []) => {
+  const processError = (error52, path24 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path23, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path24, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path23, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path23, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
       } else {
-        const fullpath = [...path23, ...issue2.path];
+        const fullpath = [...path24, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -30352,17 +30351,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error52, path23 = []) => {
+  const processError = (error52, path24 = []) => {
     var _a3, _b2;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path23, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path24, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path23, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path23, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
       } else {
-        const fullpath = [...path23, ...issue2.path];
+        const fullpath = [...path24, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -30394,8 +30393,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path23 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path23) {
+  const path24 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path24) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -43168,13 +43167,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path23 = ref.slice(1).split("/").filter(Boolean);
-  if (path23.length === 0) {
+  const path24 = ref.slice(1).split("/").filter(Boolean);
+  if (path24.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path23[0] === defsKey) {
-    const key = path23[1];
+  if (path24[0] === defsKey) {
+    const key = path24[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -49771,8 +49770,8 @@ var HttpAgentRegistry = class {
   agents = /* @__PURE__ */ new Map();
   apiUrl(suffix) {
     const base = this.serverApiUrl.replace(/\/$/, "");
-    const path23 = suffix.startsWith("/") ? suffix : `/${suffix}`;
-    return `${base}${path23}`;
+    const path24 = suffix.startsWith("/") ? suffix : `/${suffix}`;
+    return `${base}${path24}`;
   }
   async refresh() {
     const attempt = async () => {
@@ -49864,8 +49863,8 @@ var HttpSubscriptionRegistry = class {
   subscriptions = /* @__PURE__ */ new Map();
   apiUrl(suffix) {
     const base = this.serverApiUrl.replace(/\/$/, "");
-    const path23 = suffix.startsWith("/") ? suffix : `/${suffix}`;
-    return `${base}${path23}`;
+    const path24 = suffix.startsWith("/") ? suffix : `/${suffix}`;
+    return `${base}${path24}`;
   }
   async refresh() {
     const attempt = async () => {
@@ -50753,19 +50752,220 @@ async function dumpAgentContext(agentId, deps) {
 // src/listDir.ts
 init_cjs_shims();
 var import_promises10 = __toESM(require("fs/promises"), 1);
+var import_node_path12 = __toESM(require("path"), 1);
+
+// src/runtimeEnv.ts
+init_cjs_shims();
+var import_node_child_process2 = require("child_process");
+var import_node_fs4 = require("fs");
+var import_node_os8 = __toESM(require("os"), 1);
 var import_node_path11 = __toESM(require("path"), 1);
+var MIN_NODE_MAJOR = 20;
+function getHomeDir() {
+  return process.env.USERPROFILE || import_node_os8.default.homedir();
+}
+function splitPath(value) {
+  if (!value) return [];
+  return value.split(import_node_path11.default.delimiter).filter((entry) => entry.length > 0);
+}
+function uniq(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+function parseNodeVersionMajor(version2) {
+  const raw = version2.trim().replace(/^v/, "");
+  const [majorRaw] = raw.split(".");
+  if (!majorRaw) return null;
+  const major = Number.parseInt(majorRaw, 10);
+  return Number.isFinite(major) ? major : null;
+}
+function joinHomePath(home, suffix) {
+  const parts = suffix.split(/[\\/]+/).filter((part) => part.length > 0);
+  return import_node_path11.default.join(home, ...parts);
+}
+function sortNodeVersionDirsDesc(names) {
+  return [...names].sort((a, b2) => {
+    const aParts = a.replace(/^v/, "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+    const bParts = b2.replace(/^v/, "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i += 1) {
+      const delta = (bParts[i] ?? 0) - (aParts[i] ?? 0);
+      if (delta !== 0) return delta;
+    }
+    return b2.localeCompare(a);
+  });
+}
+function listNodeVersionBins(root, binSuffix) {
+  if (!(0, import_node_fs4.existsSync)(root)) return [];
+  try {
+    return sortNodeVersionDirsDesc((0, import_node_fs4.readdirSync)(root)).map((version2) => import_node_path11.default.join(root, version2, ...binSuffix)).filter((candidate) => (0, import_node_fs4.existsSync)(candidate));
+  } catch {
+    return [];
+  }
+}
+function getNodeRuntimeStatus(version2 = process.versions.node) {
+  const major = parseNodeVersionMajor(version2);
+  return {
+    version: version2,
+    major,
+    supported: major !== null && major >= MIN_NODE_MAJOR
+  };
+}
+function getNodeToolExtraPathEntries(env2 = process.env) {
+  const home = getHomeDir();
+  const entries = [];
+  if (process.platform === "win32") {
+    for (const envName of ["NVM_SYMLINK", "NVM_HOME"]) {
+      const value = env2[envName];
+      if (value && (0, import_node_fs4.existsSync)(value)) entries.push(value);
+    }
+    for (const candidate of [
+      import_node_path11.default.join(home, "AppData", "Roaming", "npm"),
+      import_node_path11.default.join(home, ".volta", "bin"),
+      import_node_path11.default.join(home, ".asdf", "shims"),
+      import_node_path11.default.join(env2.ProgramFiles ?? "C:\\Program Files", "nodejs"),
+      import_node_path11.default.join(env2.LOCALAPPDATA ?? import_node_path11.default.join(home, "AppData", "Local"), "Programs", "nodejs")
+    ]) {
+      if ((0, import_node_fs4.existsSync)(candidate)) entries.push(candidate);
+    }
+    return uniq(entries);
+  }
+  const nvmRoot = env2.NVM_DIR ?? import_node_path11.default.join(home, ".nvm");
+  entries.push(...listNodeVersionBins(import_node_path11.default.join(nvmRoot, "versions", "node"), ["bin"]));
+  const fnmRoots = [
+    import_node_path11.default.join(home, ".fnm", "node-versions"),
+    import_node_path11.default.join(home, ".local", "share", "fnm", "node-versions")
+  ];
+  for (const fnmRoot of fnmRoots) {
+    entries.push(...listNodeVersionBins(fnmRoot, ["installation", "bin"]));
+  }
+  for (const candidate of [
+    import_node_path11.default.join(home, ".volta", "bin"),
+    import_node_path11.default.join(home, ".asdf", "shims"),
+    import_node_path11.default.join(home, ".local", "bin"),
+    "/opt/homebrew/bin",
+    "/usr/local/bin"
+  ]) {
+    if ((0, import_node_fs4.existsSync)(candidate)) entries.push(candidate);
+  }
+  return uniq(entries);
+}
+function buildAugmentedPath(env2 = process.env) {
+  return uniq([...getNodeToolExtraPathEntries(env2), ...splitPath(env2.PATH)]).join(import_node_path11.default.delimiter);
+}
+function withAugmentedPathEnv(env2 = process.env) {
+  return { ...env2, PATH: buildAugmentedPath(env2) };
+}
+function executableNames(name) {
+  if (process.platform !== "win32") return [name];
+  if (/\.(cmd|exe|bat)$/i.test(name)) return [name];
+  return [`${name}.cmd`, `${name}.exe`, `${name}.bat`, name];
+}
+function canExecute(candidate) {
+  try {
+    if (process.platform === "win32") return (0, import_node_fs4.existsSync)(candidate);
+    (0, import_node_fs4.accessSync)(candidate, import_node_fs4.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveCommand(names, env2 = process.env) {
+  const pathEntries = splitPath(buildAugmentedPath(env2));
+  for (const entry of pathEntries) {
+    for (const name of names) {
+      for (const executableName of executableNames(name)) {
+        const candidate = import_node_path11.default.join(entry, executableName);
+        if (canExecute(candidate)) return { name, path: candidate };
+      }
+    }
+  }
+  return void 0;
+}
+function readCommandVersion(executablePath, args = ["--version"], env2 = process.env) {
+  try {
+    return (0, import_node_child_process2.execFileSync)(executablePath, args, {
+      env: withAugmentedPathEnv(env2),
+      timeout: 1e4
+    }).toString().trim();
+  } catch {
+    return void 0;
+  }
+}
+function probeCommand(name, args = ["--version"], env2 = process.env) {
+  const resolved = resolveCommand([name], env2);
+  if (!resolved) {
+    return {
+      name,
+      ok: false,
+      message: `${name} was not found on PATH`
+    };
+  }
+  const version2 = readCommandVersion(resolved.path, args, env2);
+  return {
+    name,
+    path: resolved.path,
+    version: version2,
+    ok: Boolean(version2),
+    message: version2 ? void 0 : `${name} was found but did not run successfully`
+  };
+}
+function resolveUserPath(input) {
+  const home = getHomeDir();
+  let value = input.trim();
+  if (value === "~") value = home;
+  else if (value.startsWith("~/") || value.startsWith("~\\")) value = joinHomePath(home, value.slice(2));
+  else if (value === "$HOME") value = home;
+  else if (value.startsWith("$HOME/") || value.startsWith("$HOME\\")) value = joinHomePath(home, value.slice(6));
+  else if (value === "${HOME}") value = home;
+  else if (value.startsWith("${HOME}/") || value.startsWith("${HOME}\\")) value = joinHomePath(home, value.slice(8));
+  else if (value === "$env:USERPROFILE") value = home;
+  else if (value.startsWith("$env:USERPROFILE\\") || value.startsWith("$env:USERPROFILE/")) {
+    value = joinHomePath(home, value.slice("$env:USERPROFILE".length + 1));
+  } else if (value === "%USERPROFILE%") value = home;
+  else if (value.startsWith("%USERPROFILE%\\") || value.startsWith("%USERPROFILE%/")) {
+    value = joinHomePath(home, value.slice("%USERPROFILE%".length + 1));
+  }
+  return import_node_path11.default.isAbsolute(value) ? import_node_path11.default.normalize(value) : import_node_path11.default.resolve(value);
+}
+function assertBridgeUserSlug(user) {
+  const value = user.trim();
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error('Bridge --user may only contain letters, numbers, "_" and "-"');
+  }
+  return value;
+}
+function resolveBridgeDataDir(opts) {
+  if (opts.dataDir) return resolveUserPath(opts.dataDir);
+  if (opts.user) return resolveUserPath(`~/.ahchat/users/${assertBridgeUserSlug(opts.user)}`);
+  return void 0;
+}
+function normalizeBridgeServerUrls(rawUrl) {
+  const url2 = new URL(rawUrl);
+  if (url2.protocol === "http:" || url2.protocol === "https:") {
+    url2.protocol = url2.protocol === "https:" ? "wss:" : "ws:";
+    if (url2.pathname === "/" || url2.pathname === "") url2.pathname = "/ws/bridge";
+  }
+  if (url2.protocol !== "ws:" && url2.protocol !== "wss:") {
+    throw new Error(`Unsupported bridge server URL protocol: ${url2.protocol}`);
+  }
+  const serverUrl = url2.toString();
+  const serverApiUrl = `${url2.protocol === "wss:" ? "https" : "http"}://${url2.host}`;
+  return { serverUrl, serverApiUrl };
+}
+
+// src/listDir.ts
 var logger17 = createModuleLogger("bridge.listDir");
 function shouldIncludeEntry(name) {
   if (!name.startsWith(".")) return true;
   return name === ".ahchat-attachments";
 }
 async function listDirectoryEntries(dirPath) {
-  logger17.info("listDirectoryEntries start", { path: dirPath });
-  const raw = await import_promises10.default.readdir(dirPath, { withFileTypes: true });
+  const resolvedDirPath = resolveUserPath(dirPath);
+  logger17.info("listDirectoryEntries start", { path: dirPath, resolvedPath: resolvedDirPath });
+  const raw = await import_promises10.default.readdir(resolvedDirPath, { withFileTypes: true });
   const entries = [];
   for (const entry of raw) {
     if (!shouldIncludeEntry(entry.name)) continue;
-    const fullPath = import_node_path11.default.join(dirPath, entry.name);
+    const fullPath = import_node_path12.default.join(resolvedDirPath, entry.name);
     const isDir = entry.isDirectory();
     let size;
     let mtime;
@@ -50784,6 +50984,7 @@ async function listDirectoryEntries(dirPath) {
   });
   logger17.info("listDirectoryEntries ok", {
     path: dirPath,
+    resolvedPath: resolvedDirPath,
     count: entries.length,
     dirCount: entries.filter((e7) => e7.type === "dir").length,
     fileCount: entries.filter((e7) => e7.type === "file").length
@@ -50793,9 +50994,9 @@ async function listDirectoryEntries(dirPath) {
 
 // src/logScanner.ts
 init_cjs_shims();
-var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path12 = __toESM(require("path"), 1);
-var import_node_os8 = __toESM(require("os"), 1);
+var import_node_fs5 = __toESM(require("fs"), 1);
+var import_node_path13 = __toESM(require("path"), 1);
+var import_node_os9 = __toESM(require("os"), 1);
 var import_node_readline = __toESM(require("readline"), 1);
 var logger18 = createModuleLogger("bridge.logScanner");
 var DEFAULT_LIMIT = 500;
@@ -50803,17 +51004,17 @@ var MAX_LIMIT = 2e3;
 function listLogFiles(logsDir, baseName) {
   let names;
   try {
-    names = import_node_fs4.default.readdirSync(logsDir);
+    names = import_node_fs5.default.readdirSync(logsDir);
   } catch (e7) {
     logger18.warn("listLogFiles: readdir failed", { logsDir, error: e7 });
     return [];
   }
   const pattern = new RegExp(`^${baseName.replace(".", "\\.")}(\\.\\d+)?$`);
-  return names.filter((n2) => pattern.test(n2)).map((n2) => import_node_path12.default.join(logsDir, n2));
+  return names.filter((n2) => pattern.test(n2)).map((n2) => import_node_path13.default.join(logsDir, n2));
 }
 async function scanFile(filePath, source, filter, limit, state) {
-  const file2 = import_node_path12.default.basename(filePath);
-  const stream = import_node_fs4.default.createReadStream(filePath, { encoding: "utf-8" });
+  const file2 = import_node_path13.default.basename(filePath);
+  const stream = import_node_fs5.default.createReadStream(filePath, { encoding: "utf-8" });
   const rl2 = import_node_readline.default.createInterface({ input: stream, crlfDelay: Infinity });
   let lineNum = 0;
   for await (const line of rl2) {
@@ -50851,7 +51052,7 @@ async function scanLocalLogs(logsDir, baseName, filter) {
   };
 }
 async function scanBridgeLogs(filter) {
-  const logDir = import_node_path12.default.join(import_node_os8.default.homedir(), ".ahchat", "logs");
+  const logDir = import_node_path13.default.join(import_node_os9.default.homedir(), ".ahchat", "logs");
   logger18.info("scanBridgeLogs start", {
     logDir,
     startIso: filter.startIso,
@@ -50869,15 +51070,15 @@ async function scanBridgeLogs(filter) {
 
 // src/skillStore.ts
 init_cjs_shims();
-var import_node_fs5 = __toESM(require("fs"), 1);
-var import_node_path13 = __toESM(require("path"), 1);
+var import_node_fs6 = __toESM(require("fs"), 1);
+var import_node_path14 = __toESM(require("path"), 1);
 var logger19 = createModuleLogger("bridge.skillStore");
 var ALLOWED_NAMES = /* @__PURE__ */ new Set(["log-analysis"]);
 var SkillStore = class {
   skillsDir;
   constructor(dataDir) {
-    this.skillsDir = import_node_path13.default.join(dataDir, "skills");
-    import_node_fs5.default.mkdirSync(this.skillsDir, { recursive: true });
+    this.skillsDir = import_node_path14.default.join(dataDir, "skills");
+    import_node_fs6.default.mkdirSync(this.skillsDir, { recursive: true });
     logger19.info("SkillStore initialized", { skillsDir: this.skillsDir });
   }
   read(name) {
@@ -50885,9 +51086,9 @@ var SkillStore = class {
       logger19.warn("Skill read: unknown name", { name, allowed: [...ALLOWED_NAMES] });
       return "";
     }
-    const filePath = import_node_path13.default.join(this.skillsDir, `${name}.md`);
+    const filePath = import_node_path14.default.join(this.skillsDir, `${name}.md`);
     try {
-      const content = import_node_fs5.default.readFileSync(filePath, "utf-8");
+      const content = import_node_fs6.default.readFileSync(filePath, "utf-8");
       logger19.info("Skill read", { name, bytes: content.length });
       return content;
     } catch (e7) {
@@ -50900,19 +51101,19 @@ var SkillStore = class {
     if (!ALLOWED_NAMES.has(name)) {
       throw new Error(`Unknown skill name: ${name}`);
     }
-    const filePath = import_node_path13.default.join(this.skillsDir, `${name}.md`);
+    const filePath = import_node_path14.default.join(this.skillsDir, `${name}.md`);
     const tmpPath = `${filePath}.tmp`;
     let existing = "";
     try {
-      existing = import_node_fs5.default.readFileSync(filePath, "utf-8");
+      existing = import_node_fs6.default.readFileSync(filePath, "utf-8");
     } catch {
     }
     if (existing === content) {
       logger19.info("Skill already in sync", { name, bytes: content.length });
       return;
     }
-    import_node_fs5.default.writeFileSync(tmpPath, content, "utf-8");
-    import_node_fs5.default.renameSync(tmpPath, filePath);
+    import_node_fs6.default.writeFileSync(tmpPath, content, "utf-8");
+    import_node_fs6.default.renameSync(tmpPath, filePath);
     logger19.info("Skill seeded/re-synced", {
       name,
       bytes: content.length,
@@ -50923,8 +51124,8 @@ var SkillStore = class {
 
 // src/lockfile.ts
 init_cjs_shims();
-var import_node_fs6 = __toESM(require("fs"), 1);
-var import_node_path14 = __toESM(require("path"), 1);
+var import_node_fs7 = __toESM(require("fs"), 1);
+var import_node_path15 = __toESM(require("path"), 1);
 var logger20 = createModuleLogger("bridge.lockfile");
 var lockPath = null;
 function isProcessAlive(pid) {
@@ -50938,10 +51139,10 @@ function isProcessAlive(pid) {
   }
 }
 function acquireLock(dataDir) {
-  const file2 = import_node_path14.default.join(dataDir, "bridge.lock");
+  const file2 = import_node_path15.default.join(dataDir, "bridge.lock");
   lockPath = file2;
-  if (import_node_fs6.default.existsSync(file2)) {
-    const raw = import_node_fs6.default.readFileSync(file2, "utf-8").trim();
+  if (import_node_fs7.default.existsSync(file2)) {
+    const raw = import_node_fs7.default.readFileSync(file2, "utf-8").trim();
     const pid = Number.parseInt(raw, 10);
     if (Number.isFinite(pid) && pid > 0) {
       if (isProcessAlive(pid)) {
@@ -50950,15 +51151,15 @@ function acquireLock(dataDir) {
       logger20.warn("Removing stale bridge.lock (process not found)", { pid, path: file2 });
     }
   }
-  import_node_fs6.default.mkdirSync(import_node_path14.default.dirname(file2), { recursive: true });
-  import_node_fs6.default.writeFileSync(file2, String(process.pid), "utf-8");
+  import_node_fs7.default.mkdirSync(import_node_path15.default.dirname(file2), { recursive: true });
+  import_node_fs7.default.writeFileSync(file2, String(process.pid), "utf-8");
   logger20.info("Acquired bridge lock", { path: file2, pid: process.pid });
   const release = () => {
     try {
-      if (lockPath && import_node_fs6.default.existsSync(lockPath)) {
-        const current = import_node_fs6.default.readFileSync(lockPath, "utf-8").trim();
+      if (lockPath && import_node_fs7.default.existsSync(lockPath)) {
+        const current = import_node_fs7.default.readFileSync(lockPath, "utf-8").trim();
         if (current === String(process.pid)) {
-          import_node_fs6.default.unlinkSync(lockPath);
+          import_node_fs7.default.unlinkSync(lockPath);
           logger20.info("Released bridge lock", { path: lockPath });
         }
       }
@@ -51319,14 +51520,14 @@ async function handleGroupArchivedPush(deps, payload) {
 
 // src/sessionStore.ts
 init_cjs_shims();
-var import_node_fs7 = __toESM(require("fs"), 1);
-var import_node_path15 = __toESM(require("path"), 1);
+var import_node_fs8 = __toESM(require("fs"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 var logger23 = createModuleLogger("session.store");
 var SessionStore = class {
   filePath;
   cache;
   constructor(dataDir) {
-    this.filePath = import_node_path15.default.join(dataDir, "sessions.json");
+    this.filePath = import_node_path16.default.join(dataDir, "sessions.json");
     this.cache = this.loadFromDisk();
   }
   cacheKey(agentId, scope) {
@@ -51361,8 +51562,8 @@ var SessionStore = class {
   }
   loadFromDisk() {
     try {
-      if (!import_node_fs7.default.existsSync(this.filePath)) return {};
-      const raw = import_node_fs7.default.readFileSync(this.filePath, "utf-8");
+      if (!import_node_fs8.default.existsSync(this.filePath)) return {};
+      const raw = import_node_fs8.default.readFileSync(this.filePath, "utf-8");
       const parsed = JSON.parse(raw);
       if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
       const map2 = parsed;
@@ -51386,9 +51587,9 @@ var SessionStore = class {
   }
   saveToDisk() {
     try {
-      const dir = import_node_path15.default.dirname(this.filePath);
-      import_node_fs7.default.mkdirSync(dir, { recursive: true });
-      import_node_fs7.default.writeFileSync(this.filePath, JSON.stringify(this.cache, null, 2), "utf-8");
+      const dir = import_node_path16.default.dirname(this.filePath);
+      import_node_fs8.default.mkdirSync(dir, { recursive: true });
+      import_node_fs8.default.writeFileSync(this.filePath, JSON.stringify(this.cache, null, 2), "utf-8");
     } catch (e7) {
       logger23.error("Failed to save sessions file", { error: e7, path: this.filePath });
     }
@@ -51397,9 +51598,9 @@ var SessionStore = class {
 
 // src/ensureClaudeCli.ts
 init_cjs_shims();
-var import_node_child_process2 = require("child_process");
-var import_node_fs8 = require("fs");
-var import_node_path16 = require("path");
+var import_node_child_process3 = require("child_process");
+var import_node_fs9 = require("fs");
+var import_node_path17 = require("path");
 var logger24 = createModuleLogger("bridge.ensureCli");
 var DEFAULT_INSTALL_TIMEOUT_MS = 6e5;
 function getInstallTimeoutMs() {
@@ -51408,48 +51609,42 @@ function getInstallTimeoutMs() {
   const parsed = Number.parseInt(raw, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_INSTALL_TIMEOUT_MS;
 }
-function detectClaudeCli() {
-  try {
-    return (0, import_node_child_process2.execFileSync)("claude", ["--version"], { timeout: 1e4 }).toString().trim();
-  } catch {
-    return void 0;
-  }
-}
 function getNpmGlobalBin() {
+  const npm = resolveCommand(["npm"]);
+  if (!npm) return void 0;
   try {
-    const bin = (0, import_node_child_process2.execSync)("npm bin -g", { timeout: 5e3 }).toString().trim() || void 0;
+    const bin = (0, import_node_child_process3.execFileSync)(npm.path, ["bin", "-g"], {
+      env: withAugmentedPathEnv(),
+      timeout: 5e3
+    }).toString().trim() || void 0;
     if (bin) return bin;
   } catch {
   }
   try {
-    const prefix = (0, import_node_child_process2.execSync)("npm prefix -g", { timeout: 5e3 }).toString().trim();
-    if (prefix) return (0, import_node_path16.join)(prefix, "bin");
+    const prefix = (0, import_node_child_process3.execFileSync)(npm.path, ["prefix", "-g"], {
+      env: withAugmentedPathEnv(),
+      timeout: 5e3
+    }).toString().trim();
+    if (prefix) return (0, import_node_path17.join)(prefix, "bin");
   } catch {
   }
   return void 0;
 }
 function resolveClaudeBinary() {
-  const whichCmd = process.platform === "win32" ? "where" : "which";
-  try {
-    const out = (0, import_node_child_process2.execFileSync)(whichCmd, ["claude"], { timeout: 5e3 }).toString();
-    const first = out.split(/\r?\n/).map((l4) => l4.trim()).find(Boolean);
-    if (first) return first;
-  } catch {
-  }
-  return resolveViaNpmBin();
+  return resolveCommand(["claude", "anthropic-cli"])?.path ?? resolveViaNpmBin();
 }
 function getNpmClaudeCandidates(bin) {
   if (process.platform === "win32") {
-    return ["claude.cmd", "claude.exe", "claude", "anthropic-cli.cmd", "anthropic-cli.exe", "anthropic-cli"].map((name) => (0, import_node_path16.join)(bin, name));
+    return ["claude.cmd", "claude.exe", "claude", "anthropic-cli.cmd", "anthropic-cli.exe", "anthropic-cli"].map((name) => (0, import_node_path17.join)(bin, name));
   }
-  return [(0, import_node_path16.join)(bin, "claude"), (0, import_node_path16.join)(bin, "anthropic-cli")];
+  return [(0, import_node_path17.join)(bin, "claude"), (0, import_node_path17.join)(bin, "anthropic-cli")];
 }
 function resolveViaNpmBin() {
   const bin = getNpmGlobalBin();
   if (!bin) return void 0;
   for (const candidate of getNpmClaudeCandidates(bin)) {
     try {
-      (0, import_node_fs8.accessSync)(candidate, import_node_fs8.constants.X_OK);
+      (0, import_node_fs9.accessSync)(candidate, import_node_fs9.constants.X_OK);
       return candidate;
     } catch {
     }
@@ -51459,40 +51654,32 @@ function resolveViaNpmBin() {
 function detectViaNpmBin() {
   const binPath = resolveViaNpmBin();
   if (!binPath) return void 0;
-  try {
-    return (0, import_node_child_process2.execFileSync)(binPath, ["--version"], { timeout: 1e4 }).toString().trim();
-  } catch {
-  }
-  return void 0;
+  return readCommandVersion(binPath);
 }
 function detectResolvedClaudeCli() {
-  const viaPath = detectClaudeCli();
-  if (viaPath) {
-    return { version: viaPath, path: resolveClaudeBinary() };
-  }
-  const npmBinPath = resolveViaNpmBin();
-  if (!npmBinPath) return void 0;
-  try {
-    const version2 = (0, import_node_child_process2.execFileSync)(npmBinPath, ["--version"], { timeout: 1e4 }).toString().trim();
-    return { version: version2, path: npmBinPath };
-  } catch {
-  }
+  const resolvedPath = resolveClaudeBinary();
+  if (!resolvedPath) return void 0;
+  const version2 = readCommandVersion(resolvedPath);
+  if (version2) return { version: version2, path: resolvedPath };
   return void 0;
 }
 function detectVersionFromResolvedCandidates() {
   const candidates = [resolveClaudeBinary(), resolveViaNpmBin()].filter((p) => Boolean(p));
   for (const p of candidates) {
-    try {
-      (0, import_node_fs8.accessSync)(p, import_node_fs8.constants.X_OK);
-      return (0, import_node_child_process2.execFileSync)(p, ["--version"], { timeout: 1e4 }).toString().trim();
-    } catch {
-    }
+    const version2 = readCommandVersion(p);
+    if (version2) return version2;
   }
   return void 0;
 }
 function installClaudeCli() {
+  const npm = resolveCommand(["npm"]);
+  if (!npm) {
+    logger24.error("npm not found; cannot install Claude Code CLI");
+    return void 0;
+  }
   logger24.info("Installing Claude Code CLI via npm...");
-  const result = (0, import_node_child_process2.spawnSync)("npm", ["install", "-g", "@anthropic-ai/claude-code"], {
+  const result = (0, import_node_child_process3.spawnSync)(npm.path, ["install", "-g", "@anthropic-ai/claude-code"], {
+    env: withAugmentedPathEnv(),
     stdio: "inherit",
     timeout: getInstallTimeoutMs()
   });
@@ -51524,7 +51711,10 @@ function installClaudeCli() {
   logger24.error("claude not found after successful npm install -g", {
     npmGlobalBin: npmBin ?? "unknown",
     pathDirectories: envPath.split(process.platform === "win32" ? ";" : ":").slice(0, 10),
-    npmPrefix: (0, import_node_child_process2.execSync)("npm prefix -g", { timeout: 5e3 }).toString().trim() || "unknown"
+    npmPrefix: (0, import_node_child_process3.execFileSync)(npm.path, ["prefix", "-g"], {
+      env: withAugmentedPathEnv(),
+      timeout: 5e3
+    }).toString().trim() || "unknown"
   });
   return void 0;
 }
@@ -51554,21 +51744,21 @@ async function ensureClaudeCli() {
 // src/forkAgentFiles.ts
 init_cjs_shims();
 var fs11 = __toESM(require("fs/promises"), 1);
-var path17 = __toESM(require("path"), 1);
+var path18 = __toESM(require("path"), 1);
 
 // src/sessionSlug.ts
 init_cjs_shims();
-var import_node_os9 = __toESM(require("os"), 1);
-var import_node_path17 = __toESM(require("path"), 1);
-var CLAUDE_PROJECTS_DIR = import_node_path17.default.join(import_node_os9.default.homedir(), ".claude", "projects");
+var import_node_os10 = __toESM(require("os"), 1);
+var import_node_path18 = __toESM(require("path"), 1);
+var CLAUDE_PROJECTS_DIR = import_node_path18.default.join(import_node_os10.default.homedir(), ".claude", "projects");
 function cwdToSlug(cwd) {
   return cwd.replace(/[^a-zA-Z0-9-]/g, "-");
 }
 function sessionDirForCwd(cwd) {
-  return import_node_path17.default.join(CLAUDE_PROJECTS_DIR, cwdToSlug(cwd));
+  return import_node_path18.default.join(CLAUDE_PROJECTS_DIR, cwdToSlug(cwd));
 }
 function sessionFilePath(cwd, sessionId) {
-  return import_node_path17.default.join(sessionDirForCwd(cwd), `${sessionId}.jsonl`);
+  return import_node_path18.default.join(sessionDirForCwd(cwd), `${sessionId}.jsonl`);
 }
 
 // src/forkAgentFiles.ts
@@ -51600,9 +51790,9 @@ async function forkAgentFiles(sourceAgentId, newAgentId, sourceWorkdir, newWorkd
     logger25.error("Workdir copy failed", { error: e7 });
     throw e7;
   }
-  const srcNotebook = path17.join(dataDir, "agent-memory", sourceAgentId, "notebook.md");
-  const dstNotebookDir = path17.join(dataDir, "agent-memory", newAgentId);
-  const dstNotebook = path17.join(dstNotebookDir, "notebook.md");
+  const srcNotebook = path18.join(dataDir, "agent-memory", sourceAgentId, "notebook.md");
+  const dstNotebookDir = path18.join(dataDir, "agent-memory", newAgentId);
+  const dstNotebook = path18.join(dstNotebookDir, "notebook.md");
   try {
     const nbStat = await fs11.stat(srcNotebook).catch(() => null);
     if (nbStat?.isFile()) {
@@ -51629,7 +51819,7 @@ async function forkAgentFiles(sourceAgentId, newAgentId, sourceWorkdir, newWorkd
       if (srcStat?.isFile()) {
         const dstDir = sessionDirForCwd(newWorkdir);
         await fs11.mkdir(dstDir, { recursive: true });
-        const dstPath = path17.join(dstDir, `${sourceSessionId}.jsonl`);
+        const dstPath = path18.join(dstDir, `${sourceSessionId}.jsonl`);
         await fs11.copyFile(srcPath, dstPath);
         sessionStore.set(newAgentId, { kind: "single" }, sourceSessionId);
         sessionCopied = true;
@@ -51677,12 +51867,12 @@ async function forkAgentFiles(sourceAgentId, newAgentId, sourceWorkdir, newWorkd
 // src/modelQuerier.ts
 init_cjs_shims();
 var import_promises11 = __toESM(require("fs/promises"), 1);
-var import_node_os10 = __toESM(require("os"), 1);
-var import_node_path18 = __toESM(require("path"), 1);
+var import_node_os11 = __toESM(require("os"), 1);
+var import_node_path19 = __toESM(require("path"), 1);
 var logger26 = createModuleLogger("bridge.modelQuerier");
 async function listModels(queryFn, opts = {}) {
   const t0 = Date.now();
-  const cwd = opts.cwd ?? import_node_path18.default.join(import_node_os10.default.homedir(), ".ahchat", "workspaces", "_list_models");
+  const cwd = opts.cwd ?? import_node_path19.default.join(import_node_os11.default.homedir(), ".ahchat", "workspaces", "_list_models");
   await import_promises11.default.mkdir(cwd, { recursive: true });
   const fn = queryFn ?? QA$;
   const ic2 = new InputController();
@@ -51745,8 +51935,8 @@ async function listModels(queryFn, opts = {}) {
 // src/promptOptimizer.ts
 init_cjs_shims();
 var import_promises12 = __toESM(require("fs/promises"), 1);
-var import_node_os11 = __toESM(require("os"), 1);
-var import_node_path19 = __toESM(require("path"), 1);
+var import_node_os12 = __toESM(require("os"), 1);
+var import_node_path20 = __toESM(require("path"), 1);
 var logger27 = createModuleLogger("bridge.promptOptimizer");
 var OPTIMIZER_SYSTEM_PROMPT = `You are an expert prompt editor for AHChat Agent creation.
 
@@ -51789,7 +51979,7 @@ async function optimizePrompt(queryFn, opts) {
   const prompt = opts.systemPrompt.trim();
   if (!prompt) throw new Error("systemPrompt is required");
   const t0 = Date.now();
-  const cwd = opts.cwd ?? import_node_path19.default.join(import_node_os11.default.homedir(), ".ahchat", "workspaces", "_prompt_optimizer");
+  const cwd = opts.cwd ?? import_node_path20.default.join(import_node_os12.default.homedir(), ".ahchat", "workspaces", "_prompt_optimizer");
   await import_promises12.default.mkdir(cwd, { recursive: true });
   const fn = queryFn ?? QA$;
   const ic2 = new InputController();
@@ -51877,7 +52067,7 @@ function isRunningAsRoot2() {
   }
 }
 async function syncClaudeCredentialsToNodeAccessibleDir(agentConfigDir) {
-  const rootClaudeDir = import_node_path20.default.join(process.env.HOME ?? "/root", ".claude");
+  const rootClaudeDir = import_node_path21.default.join(process.env.HOME ?? "/root", ".claude");
   const fs16 = await import("fs/promises");
   try {
     await fs16.access(rootClaudeDir);
@@ -51887,8 +52077,8 @@ async function syncClaudeCredentialsToNodeAccessibleDir(agentConfigDir) {
   }
   const filesToSync = [".credentials.json", "settings.json", ".credentials.backup.json"];
   for (const file2 of filesToSync) {
-    const src = import_node_path20.default.join(rootClaudeDir, file2);
-    const dest = import_node_path20.default.join(agentConfigDir, file2);
+    const src = import_node_path21.default.join(rootClaudeDir, file2);
+    const dest = import_node_path21.default.join(agentConfigDir, file2);
     try {
       await fs16.copyFile(src, dest);
       logger28.info("Synced credential file", { file: file2, from: src, to: dest });
@@ -51911,7 +52101,7 @@ async function chownRecursive(dirPath, uid, gid) {
     return;
   }
   for (const entry of entries) {
-    const fullPath = import_node_path20.default.join(dirPath, entry.name);
+    const fullPath = import_node_path21.default.join(dirPath, entry.name);
     if (entry.isDirectory()) {
       await chownRecursive(fullPath, uid, gid);
     } else {
@@ -51926,7 +52116,7 @@ async function chownRecursive(dirPath, uid, gid) {
 async function startBridge(config2) {
   ensureDir(config2.dataDir);
   ensureDir(config2.agentConfigDir);
-  const workspacesDir = import_node_path20.default.join(config2.dataDir, "workspaces");
+  const workspacesDir = import_node_path21.default.join(config2.dataDir, "workspaces");
   ensureDir(workspacesDir);
   process.env.CLAUDE_CONFIG_DIR = config2.agentConfigDir;
   installBridgeFetchAuth(config2.serverApiUrl, config2.bridgeToken);
@@ -51955,7 +52145,7 @@ Bridge token (register this machine at Settings \u2192 \u5DF2\u8FDE\u63A5\u7684\
 `);
   wsMetrics.start(5e3);
   const sessionStore = new SessionStore(config2.dataDir);
-  const memoryRoot = import_node_path20.default.join(config2.dataDir, "agent-memory");
+  const memoryRoot = import_node_path21.default.join(config2.dataDir, "agent-memory");
   const memoryStore = new AgentMemoryStore(memoryRoot);
   logger28.info("Agent memory store initialized", { rootDir: memoryRoot });
   const smithNotebook = memoryStore.read(SMITH_AGENT_ID);
@@ -52384,21 +52574,58 @@ function compactEnv(env2) {
 
 // src/protocol.ts
 init_cjs_shims();
-var import_node_child_process3 = require("child_process");
-var import_node_fs9 = __toESM(require("fs"), 1);
-var import_node_os12 = __toESM(require("os"), 1);
-var import_node_path21 = __toESM(require("path"), 1);
+var import_node_child_process4 = require("child_process");
+var import_node_fs10 = __toESM(require("fs"), 1);
+var import_node_os13 = __toESM(require("os"), 1);
+var import_node_path22 = __toESM(require("path"), 1);
 var logger29 = createModuleLogger("bridge.protocol");
+function shellSingleQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function psSingleQuote(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function desktopExecQuote(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function getStableCliPath() {
+  return import_node_path22.default.join(import_node_os13.default.homedir(), ".ahchat", "bridge", "cli.cjs");
+}
 function getStableExePath() {
-  const bridgeDir = import_node_path21.default.join(import_node_os12.default.homedir(), ".ahchat", "bridge");
-  import_node_fs9.default.mkdirSync(bridgeDir, { recursive: true });
-  const stablePath = import_node_path21.default.join(bridgeDir, "cli.cjs");
-  import_node_fs9.default.copyFileSync(__filename, stablePath);
-  if (process.platform !== "win32") import_node_fs9.default.chmodSync(stablePath, 493);
+  const bridgeDir = import_node_path22.default.join(import_node_os13.default.homedir(), ".ahchat", "bridge");
+  import_node_fs10.default.mkdirSync(bridgeDir, { recursive: true });
+  const stablePath = getStableCliPath();
+  import_node_fs10.default.copyFileSync(__filename, stablePath);
+  if (process.platform !== "win32") import_node_fs10.default.chmodSync(stablePath, 493);
   return stablePath;
 }
+function writePosixLauncher(bridgeDir, stableExePath) {
+  const launchScriptPath = import_node_path22.default.join(bridgeDir, "launch-bridge.sh");
+  const augmentedPath = buildAugmentedPath();
+  import_node_fs10.default.writeFileSync(
+    launchScriptPath,
+    [
+      "#!/bin/bash",
+      "set -e",
+      `export PATH=${shellSingleQuote(augmentedPath)}:"\${PATH:-}"`,
+      `SAVED_NODE=${shellSingleQuote(process.execPath)}`,
+      `BRIDGE_CLI=${shellSingleQuote(stableExePath)}`,
+      'NODE_BIN=""',
+      'if [ -x "$SAVED_NODE" ]; then NODE_BIN="$SAVED_NODE"; fi',
+      'if [ -z "$NODE_BIN" ]; then NODE_BIN="$(command -v node || true)"; fi',
+      'if [ -z "$NODE_BIN" ]; then',
+      `  echo "Node.js ${MIN_NODE_MAJOR}+ is required to launch AHChat Bridge. Install Node, then rerun: npx -y @fangyb/ahchat-bridge install" >&2`,
+      "  exit 1",
+      "fi",
+      'exec "$NODE_BIN" "$BRIDGE_CLI" launch --url "$1"',
+      ""
+    ].join("\n")
+  );
+  import_node_fs10.default.chmodSync(launchScriptPath, 493);
+  return launchScriptPath;
+}
 function registerProtocolHandler() {
-  const platform = import_node_os12.default.platform();
+  const platform = import_node_os13.default.platform();
   if (platform === "win32") {
     registerWindows();
   } else if (platform === "darwin") {
@@ -52411,22 +52638,42 @@ function registerProtocolHandler() {
 function registerWindows() {
   const nodeExe = process.execPath;
   const stableExePath = getStableExePath();
-  const bridgeDir = import_node_path21.default.join(import_node_os12.default.homedir(), ".ahchat", "bridge");
-  const psLauncherPath = import_node_path21.default.join(bridgeDir, "launch-bridge.ps1");
-  import_node_fs9.default.writeFileSync(
+  const bridgeDir = import_node_path22.default.join(import_node_os13.default.homedir(), ".ahchat", "bridge");
+  const augmentedPath = buildAugmentedPath();
+  const psLauncherPath = import_node_path22.default.join(bridgeDir, "launch-bridge.ps1");
+  import_node_fs10.default.writeFileSync(
     psLauncherPath,
     [
       `param([string]$url)`,
-      `& '${nodeExe.replace(/'/g, "''")}' '${stableExePath.replace(/'/g, "''")}' launch --url $url`
+      `$env:PATH = ${psSingleQuote(augmentedPath)} + [System.IO.Path]::PathSeparator + $env:PATH`,
+      `$candidates = @(`,
+      `  ${psSingleQuote(nodeExe)},`,
+      `  "$env:NVM_SYMLINK\\node.exe",`,
+      `  "$env:ProgramFiles\\nodejs\\node.exe",`,
+      `  "$env:LOCALAPPDATA\\Programs\\nodejs\\node.exe"`,
+      `)`,
+      `$node = $null`,
+      `foreach ($candidate in $candidates) {`,
+      `  if ($candidate -and (Test-Path $candidate)) { $node = $candidate; break }`,
+      `}`,
+      `if (-not $node) {`,
+      `  $cmd = Get-Command node -ErrorAction SilentlyContinue`,
+      `  if ($cmd) { $node = $cmd.Source }`,
+      `}`,
+      `if (-not $node) {`,
+      `  Write-Error 'Node.js ${MIN_NODE_MAJOR}+ is required to launch AHChat Bridge. Install Node, then rerun: npx -y @fangyb/ahchat-bridge install'`,
+      `  exit 1`,
+      `}`,
+      `& $node ${psSingleQuote(stableExePath)} launch --url $url`
     ].join("\r\n")
   );
   const handlerValue = `powershell -ExecutionPolicy Bypass -File "${psLauncherPath}" -url "%1"`;
-  const psRegisterPath = import_node_path21.default.join(bridgeDir, "register-protocol.ps1");
-  import_node_fs9.default.writeFileSync(
+  const psRegisterPath = import_node_path22.default.join(bridgeDir, "register-protocol.ps1");
+  import_node_fs10.default.writeFileSync(
     psRegisterPath,
     [
-      `$handler = '${handlerValue.replace(/'/g, "''")}'`,
-      `$icon    = '${nodeExe.replace(/'/g, "''")}'`,
+      `$handler = ${psSingleQuote(handlerValue)}`,
+      `$icon    = ${psSingleQuote(nodeExe)}`,
       `New-Item         -Path 'HKCU:\\Software\\Classes\\ahchat' -Force | Out-Null`,
       `Set-ItemProperty -Path 'HKCU:\\Software\\Classes\\ahchat' -Name '(Default)' -Value 'URL:ahchat' -Force`,
       `New-ItemProperty -Path 'HKCU:\\Software\\Classes\\ahchat' -Name 'URL Protocol' -Value '' -PropertyType String -Force | Out-Null`,
@@ -52437,7 +52684,7 @@ function registerWindows() {
     ].join("\r\n")
   );
   try {
-    (0, import_node_child_process3.execSync)(`powershell -ExecutionPolicy Bypass -File "${psRegisterPath}"`, { stdio: "pipe" });
+    (0, import_node_child_process4.execSync)(`powershell -ExecutionPolicy Bypass -File "${psRegisterPath}"`, { stdio: "pipe" });
   } catch (e7) {
     logger29.error("Failed to register Windows protocol handler", { error: e7 });
     throw new Error("Failed to register Windows protocol handler");
@@ -52445,18 +52692,10 @@ function registerWindows() {
   logger29.info("Windows protocol handler registered", { psLauncherPath });
 }
 function registerMacOS() {
-  const appDir = import_node_path21.default.join(import_node_os12.default.homedir(), "Applications", "AHChatBridge.app");
-  const nodeExe = process.execPath;
+  const appDir = import_node_path22.default.join(import_node_os13.default.homedir(), "Applications", "AHChatBridge.app");
   const stableExePath = getStableExePath();
-  const bridgeDir = import_node_path21.default.join(import_node_os12.default.homedir(), ".ahchat", "bridge");
-  const launchScriptPath = import_node_path21.default.join(bridgeDir, "launch-bridge.sh");
-  import_node_fs9.default.writeFileSync(
-    launchScriptPath,
-    `#!/bin/bash
-exec ${JSON.stringify(nodeExe)} ${JSON.stringify(stableExePath)} launch --url "$1"
-`
-  );
-  import_node_fs9.default.chmodSync(launchScriptPath, 493);
+  const bridgeDir = import_node_path22.default.join(import_node_os13.default.homedir(), ".ahchat", "bridge");
+  const launchScriptPath = writePosixLauncher(bridgeDir, stableExePath);
   const escapedScriptPath = launchScriptPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
   const appleScript = [
     `on open location thisURL`,
@@ -52464,29 +52703,29 @@ exec ${JSON.stringify(nodeExe)} ${JSON.stringify(stableExePath)} launch --url "$
     `  do shell script "/bin/bash " & (quoted form of launchScript) & " " & (quoted form of thisURL) & " >/tmp/ahchat-bridge.log 2>&1 &"`,
     `end open location`
   ].join("\n");
-  const tmpScript = import_node_path21.default.join(import_node_os12.default.tmpdir(), "AHChatBridge.applescript");
-  import_node_fs9.default.writeFileSync(tmpScript, appleScript);
+  const tmpScript = import_node_path22.default.join(import_node_os13.default.tmpdir(), "AHChatBridge.applescript");
+  import_node_fs10.default.writeFileSync(tmpScript, appleScript);
   try {
-    import_node_fs9.default.rmSync(appDir, { recursive: true, force: true });
+    import_node_fs10.default.rmSync(appDir, { recursive: true, force: true });
   } catch {
   }
   try {
-    (0, import_node_child_process3.execSync)(`osacompile -o ${JSON.stringify(appDir)} ${JSON.stringify(tmpScript)}`, { stdio: "pipe" });
+    (0, import_node_child_process4.execSync)(`osacompile -o ${JSON.stringify(appDir)} ${JSON.stringify(tmpScript)}`, { stdio: "pipe" });
   } finally {
     try {
-      import_node_fs9.default.unlinkSync(tmpScript);
+      import_node_fs10.default.unlinkSync(tmpScript);
     } catch {
     }
   }
-  const plistPath = import_node_path21.default.join(appDir, "Contents", "Info.plist");
+  const plistPath = import_node_path22.default.join(appDir, "Contents", "Info.plist");
   const urlTypes = JSON.stringify([{ CFBundleURLName: "AHChat Bridge", CFBundleURLSchemes: ["ahchat"] }]);
-  (0, import_node_child_process3.execSync)(
+  (0, import_node_child_process4.execSync)(
     `/usr/bin/plutil -insert CFBundleURLTypes -json ${JSON.stringify(urlTypes)} ${JSON.stringify(plistPath)}`,
     { stdio: "pipe" }
   );
   const lsregister = "/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister";
   try {
-    (0, import_node_child_process3.execSync)(`${lsregister} -f ${JSON.stringify(appDir)}`, { stdio: "pipe" });
+    (0, import_node_child_process4.execSync)(`${lsregister} -f ${JSON.stringify(appDir)}`, { stdio: "pipe" });
   } catch (e7) {
     logger29.warn("lsregister failed; URL scheme registration may be delayed", { error: e7 });
   }
@@ -52494,36 +52733,38 @@ exec ${JSON.stringify(nodeExe)} ${JSON.stringify(stableExePath)} launch --url "$
 }
 function registerLinux() {
   const stableExePath = getStableExePath();
+  const bridgeDir = import_node_path22.default.join(import_node_os13.default.homedir(), ".ahchat", "bridge");
+  const launchScriptPath = writePosixLauncher(bridgeDir, stableExePath);
   const desktopFile = [
     `[Desktop Entry]`,
     `Name=AHChat Bridge`,
-    `Exec=${process.execPath} ${stableExePath} launch --url %u`,
+    `Exec=${desktopExecQuote(launchScriptPath)} %u`,
     `Type=Application`,
     `NoDisplay=true`,
     `MimeType=x-scheme-handler/ahchat;`
   ].join("\n");
-  const desktopPath = import_node_path21.default.join(import_node_os12.default.homedir(), ".local", "share", "applications", "ahchat-bridge.desktop");
-  import_node_fs9.default.mkdirSync(import_node_path21.default.dirname(desktopPath), { recursive: true });
-  import_node_fs9.default.writeFileSync(desktopPath, desktopFile);
+  const desktopPath = import_node_path22.default.join(import_node_os13.default.homedir(), ".local", "share", "applications", "ahchat-bridge.desktop");
+  import_node_fs10.default.mkdirSync(import_node_path22.default.dirname(desktopPath), { recursive: true });
+  import_node_fs10.default.writeFileSync(desktopPath, desktopFile);
   try {
-    (0, import_node_child_process3.execSync)("update-desktop-database ~/.local/share/applications/", { stdio: "pipe" });
+    (0, import_node_child_process4.execSync)("update-desktop-database ~/.local/share/applications/", { stdio: "pipe" });
   } catch (e7) {
     logger29.warn("update-desktop-database not available; run it manually if needed", { error: e7 });
   }
   logger29.info("Linux protocol handler registered", { desktopPath });
 }
 function unregisterProtocolHandler() {
-  const platform = import_node_os12.default.platform();
+  const platform = import_node_os13.default.platform();
   if (platform === "win32") {
     try {
-      (0, import_node_child_process3.execSync)(
+      (0, import_node_child_process4.execSync)(
         `powershell -ExecutionPolicy Bypass -Command "Remove-Item -Path 'HKCU:\\Software\\Classes\\ahchat' -Recurse -Force -ErrorAction SilentlyContinue"`,
         { stdio: "pipe" }
       );
-      const bridgeDir = import_node_path21.default.join(import_node_os12.default.homedir(), ".ahchat", "bridge");
+      const bridgeDir = import_node_path22.default.join(import_node_os13.default.homedir(), ".ahchat", "bridge");
       for (const f7 of ["launch-bridge.ps1", "register-protocol.ps1"]) {
         try {
-          import_node_fs9.default.unlinkSync(import_node_path21.default.join(bridgeDir, f7));
+          import_node_fs10.default.unlinkSync(import_node_path22.default.join(bridgeDir, f7));
         } catch {
         }
       }
@@ -52532,17 +52773,17 @@ function unregisterProtocolHandler() {
       logger29.warn("Failed to unregister Windows protocol handler", { error: e7 });
     }
   } else if (platform === "darwin") {
-    const appDir = import_node_path21.default.join(import_node_os12.default.homedir(), "Applications", "AHChatBridge.app");
+    const appDir = import_node_path22.default.join(import_node_os13.default.homedir(), "Applications", "AHChatBridge.app");
     try {
-      import_node_fs9.default.rmSync(appDir, { recursive: true, force: true });
+      import_node_fs10.default.rmSync(appDir, { recursive: true, force: true });
       logger29.info("macOS protocol handler unregistered");
     } catch (e7) {
       logger29.warn("Failed to unregister macOS protocol handler", { error: e7 });
     }
   } else {
-    const desktopPath = import_node_path21.default.join(import_node_os12.default.homedir(), ".local", "share", "applications", "ahchat-bridge.desktop");
+    const desktopPath = import_node_path22.default.join(import_node_os13.default.homedir(), ".local", "share", "applications", "ahchat-bridge.desktop");
     try {
-      import_node_fs9.default.unlinkSync(desktopPath);
+      import_node_fs10.default.unlinkSync(desktopPath);
       logger29.info("Linux protocol handler unregistered");
     } catch (e7) {
       logger29.warn("Failed to unregister Linux protocol handler", { error: e7 });
@@ -52550,20 +52791,21 @@ function unregisterProtocolHandler() {
   }
 }
 function isProtocolRegistered() {
-  const platform = import_node_os12.default.platform();
+  const platform = import_node_os13.default.platform();
+  const stableCliExists = import_node_fs10.default.existsSync(getStableCliPath());
   if (platform === "win32") {
     try {
-      (0, import_node_child_process3.execSync)('REG QUERY "HKCU\\Software\\Classes\\ahchat" /ve', { stdio: "pipe" });
-      return true;
+      (0, import_node_child_process4.execSync)('REG QUERY "HKCU\\Software\\Classes\\ahchat" /ve', { stdio: "pipe" });
+      return stableCliExists;
     } catch {
       return false;
     }
   } else if (platform === "darwin") {
-    const appDir = import_node_path21.default.join(import_node_os12.default.homedir(), "Applications", "AHChatBridge.app");
-    return import_node_fs9.default.existsSync(import_node_path21.default.join(appDir, "Contents", "Info.plist"));
+    const appDir = import_node_path22.default.join(import_node_os13.default.homedir(), "Applications", "AHChatBridge.app");
+    return stableCliExists && import_node_fs10.default.existsSync(import_node_path22.default.join(appDir, "Contents", "Info.plist"));
   } else {
-    const desktopPath = import_node_path21.default.join(import_node_os12.default.homedir(), ".local", "share", "applications", "ahchat-bridge.desktop");
-    return import_node_fs9.default.existsSync(desktopPath);
+    const desktopPath = import_node_path22.default.join(import_node_os13.default.homedir(), ".local", "share", "applications", "ahchat-bridge.desktop");
+    return stableCliExists && import_node_fs10.default.existsSync(desktopPath);
   }
 }
 
@@ -52571,14 +52813,14 @@ function isProtocolRegistered() {
 var logger30 = createModuleLogger("bridge");
 function readCliVersion() {
   const candidates = [
-    import_node_path22.default.resolve(__dirname, "../package.json"),
-    import_node_path22.default.resolve(__dirname, "../../package.json"),
-    import_node_path22.default.resolve(process.cwd(), "packages/bridge/package.json")
+    import_node_path23.default.resolve(__dirname, "../package.json"),
+    import_node_path23.default.resolve(__dirname, "../../package.json"),
+    import_node_path23.default.resolve(process.cwd(), "packages/bridge/package.json")
   ];
   for (const candidate of candidates) {
-    if (!import_node_fs10.default.existsSync(candidate)) continue;
+    if (!import_node_fs11.default.existsSync(candidate)) continue;
     try {
-      const parsed = JSON.parse(import_node_fs10.default.readFileSync(candidate, "utf8"));
+      const parsed = JSON.parse(import_node_fs11.default.readFileSync(candidate, "utf8"));
       if (parsed && typeof parsed === "object" && "version" in parsed && typeof parsed.version === "string" && parsed.version.length > 0) {
         return parsed.version;
       }
@@ -52586,26 +52828,7 @@ function readCliVersion() {
       logger30.warn("Unable to read CLI package version candidate", { error: e7, candidate });
     }
   }
-  return "0.1.21";
-}
-function resolveDataDir(dataDir) {
-  const userHome = process.env.USERPROFILE || import_node_os13.default.homedir();
-  if (/^~[/\\]/.test(dataDir)) {
-    return import_node_path22.default.join(import_node_os13.default.homedir(), dataDir.slice(2));
-  }
-  if (dataDir === "$env:USERPROFILE") {
-    return userHome;
-  }
-  if (dataDir.startsWith("$env:USERPROFILE\\") || dataDir.startsWith("$env:USERPROFILE/")) {
-    return import_node_path22.default.join(userHome, dataDir.slice("$env:USERPROFILE".length + 1));
-  }
-  if (dataDir === "%USERPROFILE%") {
-    return userHome;
-  }
-  if (dataDir.startsWith("%USERPROFILE%\\") || dataDir.startsWith("%USERPROFILE%/")) {
-    return import_node_path22.default.join(userHome, dataDir.slice("%USERPROFILE%".length + 1));
-  }
-  return dataDir;
+  return "0.1.23";
 }
 function parseAhchatUrl(url2) {
   try {
@@ -52620,29 +52843,107 @@ function parseAhchatUrl(url2) {
     const token = decodeURIComponent(rest.slice(lastTilde + 1));
     if (!serverUrl || !token) return null;
     return { serverUrl, token };
-  } catch {
+  } catch (e7) {
+    logger30.warn("Unable to parse ahchat launch URL", { error: e7 });
     return null;
   }
 }
+function assertSupportedNode() {
+  const status = getNodeRuntimeStatus();
+  if (status.supported) return;
+  throw new Error(
+    `Node.js ${MIN_NODE_MAJOR}+ is required to run AHChat Bridge. Current version: ${status.version}`
+  );
+}
 async function run(args) {
-  const dataDir = args.dataDir ? resolveDataDir(args.dataDir) : void 0;
+  assertSupportedNode();
+  process.env.PATH = buildAugmentedPath();
+  const dataDir = resolveBridgeDataDir(args);
   let config2 = loadBridgeConfig(dataDir ? { dataDir } : void 0);
   if (args.serverUrl) {
-    const wsUrl = new URL(args.serverUrl);
-    const httpBase = `${wsUrl.protocol === "wss:" ? "https" : "http"}://${wsUrl.host}`;
-    config2 = { ...config2, serverUrl: args.serverUrl, serverApiUrl: httpBase };
+    const urls = normalizeBridgeServerUrls(args.serverUrl);
+    config2 = { ...config2, serverUrl: urls.serverUrl, serverApiUrl: urls.serverApiUrl };
   }
   if (args.token) config2 = { ...config2, bridgeToken: args.token };
   if (args.logLevel) config2 = { ...config2, logLevel: args.logLevel };
   await startBridge(config2);
 }
+function buildDoctorReport(args) {
+  process.env.PATH = buildAugmentedPath();
+  const node = getNodeRuntimeStatus();
+  let server = null;
+  if (args.serverUrl) {
+    try {
+      server = { ok: true, ...normalizeBridgeServerUrls(args.serverUrl) };
+    } catch (e7) {
+      server = {
+        ok: false,
+        error: e7 instanceof Error ? e7.message : String(e7)
+      };
+    }
+  }
+  const claude = resolveCommand(["claude", "anthropic-cli"]);
+  return {
+    node,
+    npm: probeCommand("npm"),
+    npx: probeCommand("npx"),
+    claude: claude ? { ok: true, name: claude.name, path: claude.path } : { ok: false, name: "claude", message: "claude was not found on PATH" },
+    dataDir: resolveBridgeDataDir(args) ?? resolveUserPath("~/.ahchat"),
+    server,
+    tokenProvided: Boolean(args.token),
+    pathPreview: (process.env.PATH ?? "").split(import_node_path23.default.delimiter).slice(0, 12)
+  };
+}
+function writeDoctorText(report) {
+  const node = report.node;
+  const npm = report.npm;
+  const npx = report.npx;
+  const claude = report.claude;
+  const server = report.server;
+  const lines = [
+    "AHChat Bridge doctor",
+    `- Node: ${node.supported ? "ok" : "error"} (${node.version}, requires >=${MIN_NODE_MAJOR})`,
+    `- npm: ${npm.ok ? `ok (${npm.version ?? npm.path})` : `missing (${npm.message ?? "not found"})`}`,
+    `- npx: ${npx.ok ? `ok (${npx.version ?? npx.path})` : `missing (${npx.message ?? "not found"})`}`,
+    `- Claude CLI: ${claude.ok ? `ok (${claude.path})` : `missing (${claude.message ?? "not found"})`}`,
+    `- Data dir: ${String(report.dataDir)}`,
+    `- Token: ${report.tokenProvided ? "provided" : "not provided"}`
+  ];
+  if (server) {
+    lines.push(
+      server.ok ? `- Server: ok (${server.serverUrl}, api ${server.serverApiUrl})` : `- Server: error (${server.error ?? "invalid URL"})`
+    );
+  }
+  if (!node.supported) {
+    lines.push(`
+Install Node.js ${MIN_NODE_MAJOR}+ first, then rerun the bridge command.`);
+  } else if (!npm.ok || !npx.ok) {
+    lines.push("\nNode is installed, but npm/npx is not available on PATH. Reinstall Node.js or fix PATH.");
+  } else if (!claude.ok) {
+    lines.push("\nClaude Code CLI is missing. The bridge can try to install it on first run with npm.");
+  }
+  process.stdout.write(`${lines.join("\n")}
+`);
+}
+function doctor(args) {
+  const report = buildDoctorReport(args);
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+    return;
+  }
+  writeDoctorText(report);
+}
 var cli = dist_default("ahchat-bridge");
-cli.command("run", "Start the bridge and connect to server").option("--server-url <url>", "WebSocket URL of the AHChat server").option("--token <token>", "Auth token for server registration").option("--data-dir <dir>", "Data directory (default: ~/.ahchat)").option("--log-level <level>", "Log level (default: INFO)").action((args) => {
+cli.command("run", "Start the bridge and connect to server").option("--server-url <url>", "WebSocket URL of the AHChat server").option("--token <token>", "Auth token for server registration").option("--user <slug>", "User data-dir slug; derives ~/.ahchat/users/<slug>").option("--data-dir <dir>", "Data directory (default: ~/.ahchat)").option("--log-level <level>", "Log level (default: INFO)").action((args) => {
   void run(args).catch((e7) => {
     logger30.error("Bridge failed to start", { error: e7 });
     process.exit(1);
   });
 });
+cli.command("doctor", "Check Node, npm, Claude CLI, PATH, and bridge launch options").option("--server-url <url>", "WebSocket URL of the AHChat server").option("--token <token>", "Auth token for server registration").option("--user <slug>", "User data-dir slug; derives ~/.ahchat/users/<slug>").option("--data-dir <dir>", "Data directory (default: ~/.ahchat)").option("--json", "Print machine-readable JSON").action((args) => {
+  doctor(args);
+});
 cli.command("launch", "Launch bridge from ahchat:// URL (called by OS)").option("--url <url>", "ahchat:// URL with server and token params").action((args) => {
   const parsed = parseAhchatUrl(args.url);
   if (!parsed) {