@reconcrap/boss-recommend-mcp 1.3.34 → 1.3.35

package/README.md

@@ -16,7 +16,7 @@ Boss 推荐页自动化流水线 MCP（stdio）服务。
 
 - 单独运行 chat-only 任务，不需要再单独安装 `boss-chat`
 - 在 recommend screen 完成后，通过同一个父 run 自动进入 `chat_followup`
-- 继续把聊天页状态保存在工作区下的 `.boss-chat/`
+- 继续把聊天页状态保存在用户目录下的 `~/.boss-recommend-mcp/boss-chat/`（可通过 `BOSS_CHAT_HOME` 覆盖）
 
 MCP 工具：
 
@@ -68,7 +68,7 @@ MCP 工具：
 - 在真正开始 search/screen 前，会进行最后一轮全参数总确认（岗位 + 全部筛选参数 + criteria + target_count + post_action + max_greet_count）
 - npm 全局安装后会自动执行 install：生成 skill、导出 MCP 模板，并自动尝试写入已检测到的外部 agent MCP 配置（含 Trae / trae-cn / Cursor / Claude / OpenClaw）
 - npm / npx 安装后会自动初始化 `screening-config.json` 模板（优先写入 workspace 的 `config/`，不可写时回退到用户目录）
-- npm 安装流程会预创建运行目录（跨平台）：`~/.boss-recommend-mcp`、`~/.boss-recommend-mcp/runs`、`<workspace>/.boss-chat` 及其 `logs/runs/profiles/reports/artifacts`
+- npm 安装流程会预创建运行目录（跨平台）：`~/.boss-recommend-mcp`、`~/.boss-recommend-mcp/runs`、`~/.boss-recommend-mcp/boss-chat` 及其 `logs/runs/profiles/reports/artifacts/state`
 - `post_action` 必须在每次完整运行开始时确认一次
 - `target_count` 会在每次运行开始时询问一次（可留空，不设上限）
 - 当 `post_action=greet` 时，必须在运行开始时确认 `max_greet_count`
@@ -111,6 +111,7 @@ node src/cli.js start
 
 ```bash
 BOSS_RECOMMEND_HOME               # 统一状态目录，默认 ~/.boss-recommend-mcp
+BOSS_CHAT_HOME                    # 覆盖 boss-chat 运行态目录；默认 ~/.boss-recommend-mcp/boss-chat
 BOSS_RECOMMEND_SCREEN_CONFIG      # 显式指定 screening-config.json 路径（最高优先级）
 BOSS_RECOMMEND_MCP_CONFIG_TARGETS   # JSON 数组或系统 path 分隔路径列表，指定额外 mcp.json 目标文件
 BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS  # JSON 数组或系统 path 分隔路径列表，指定额外 skills 根目录
@@ -149,6 +150,8 @@ node src/cli.js run --instruction "推荐页筛选985男生，近14天没有，
 - `doctor` / `run` 默认优先读取 `~/.boss-recommend-mcp/screening-config.json`；如需强制其它路径，请设置 `BOSS_RECOMMEND_SCREEN_CONFIG`
 - 首次运行时，若仍检测到默认占位词（如 `replace-with-openai-api-key`），pipeline 会返回配置目录并要求用户修改后确认“已修改完成”再继续
 - 在 `npx` 临时目录（如 `AppData\\Local\\npm-cache\\_npx\\...`）执行时，不会再把该临时目录当作 `screening-config.json` 目标路径
+- `boss-chat` 运行态默认固定写入 `~/.boss-recommend-mcp/boss-chat`；即使宿主把 MCP 进程启动在系统根目录，也不会再尝试写入 `/.boss-chat`
+- 若当前工作区存在历史 `.boss-chat` 且新用户目录尚未初始化，首次运行会自动把 `logs/runs/profiles/reports/artifacts/state` 迁移到新目录，并保留旧目录作为只读历史来源
 
 配置样例见：
 
@@ -217,6 +220,7 @@ node src/cli.js chat run --job "算法工程师" --start-from unread --criteria
 - `baseUrl` / `apiKey` / `model` 不再单独传入，固定复用 recommend 的 `screening-config.json`
 - 若缺少 `follow_up.chat` 必填项，pipeline 会返回 `NEED_INPUT`
 - recommend 成功后，父 run 继续存活并进入 `chat_followup`；chat 结束后父 run 才会进入最终终态
+- `boss-chat` 子任务状态统一写入 `~/.boss-recommend-mcp/boss-chat`（或 `BOSS_CHAT_HOME` 指定目录），不再依赖工作区 `cwd`
 
 ## Chat-only
 
@@ -230,11 +234,12 @@ node src/cli.js chat run --job "算法工程师" --start-from unread --criteria
 - MCP：
   - `boss_chat_health_check`
   - `prepare_boss_chat_run`
-  - `start_boss_chat_run`
-  - `get_boss_chat_run`
-  - `pause_boss_chat_run`
-  - `resume_boss_chat_run`
-  - `cancel_boss_chat_run`
+- `start_boss_chat_run`
+- `get_boss_chat_run`
+- `pause_boss_chat_run`
+- `resume_boss_chat_run`
+- `cancel_boss_chat_run`
+- vendored `boss-chat` CLI 还支持 `--data-dir <path>` 与 `BOSS_CHAT_HOME`，优先级高于兼容旧行为的 `<cwd>/.boss-chat`
 
 chat-only 交互建议：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "1.3.34",
+  "version": "1.3.35",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",

package/src/boss-chat.js

@@ -1,8 +1,9 @@
-import fs from "node:fs";
-import path from "node:path";
-import process from "node:process";
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 import { getScreenConfigResolution, resolveSharedLlmTransportConfig } from "./adapters.js";
 
@@ -11,12 +12,14 @@ const packageRoot = path.resolve(path.dirname(currentFilePath), "..");
 const VENDORED_BOSS_CHAT_DIR = path.join(packageRoot, "vendor", "boss-chat-cli");
 const DEFAULT_BOSS_CHAT_POLL_MS = 1500;
 const PREPARE_BOSS_CHAT_MAX_ATTEMPTS = 3;
-const PREPARE_BOSS_CHAT_RETRY_DELAY_MS = 1200;
-const BOSS_CHAT_TERMINAL_STATES = new Set(["completed", "failed", "canceled"]);
-const CHAT_REQUIRED_FIELDS = ["job", "start_from", "target_count", "criteria"];
-export const TARGET_COUNT_CANONICAL_ALL = "all";
-export const TARGET_COUNT_ACCEPTED_EXAMPLES = [TARGET_COUNT_CANONICAL_ALL, -1, 20, "全部候选人"];
-const TARGET_COUNT_WRAPPER_KEYS = ["target_count", "targetCount", "value", "count", "limit"];
+const PREPARE_BOSS_CHAT_RETRY_DELAY_MS = 1200;
+const BOSS_CHAT_TERMINAL_STATES = new Set(["completed", "failed", "canceled"]);
+const CHAT_REQUIRED_FIELDS = ["job", "start_from", "target_count", "criteria"];
+const BOSS_CHAT_RUNTIME_SUBDIR = "boss-chat";
+const BOSS_CHAT_RUNTIME_CHILD_DIRS = ["logs", "runs", "profiles", "reports", "artifacts", "state"];
+export const TARGET_COUNT_CANONICAL_ALL = "all";
+export const TARGET_COUNT_ACCEPTED_EXAMPLES = [TARGET_COUNT_CANONICAL_ALL, -1, 20, "全部候选人"];
+const TARGET_COUNT_WRAPPER_KEYS = ["target_count", "targetCount", "value", "count", "limit"];
 const LLM_THINKING_LEVEL_FIELDS = [
   "llmThinkingLevel",
   "thinkingLevel",
@@ -28,13 +31,173 @@ function normalizeText(value) {
   return String(value || "").replace(/\s+/g, " ").trim();
 }
 
-function pathExists(targetPath) {
-  try {
-    return fs.existsSync(targetPath);
+function pathExists(targetPath) {
+  try {
+    return fs.existsSync(targetPath);
   } catch {
     return false;
-  }
-}
+  }
+}
+
+function getStateHome() {
+  return process.env.BOSS_RECOMMEND_HOME
+    ? path.resolve(process.env.BOSS_RECOMMEND_HOME)
+    : path.join(os.homedir(), ".boss-recommend-mcp");
+}
+
+function isRootDirectory(targetPath) {
+  const resolved = path.resolve(String(targetPath || ""));
+  const parsed = path.parse(resolved);
+  return resolved.toLowerCase() === String(parsed.root || "").toLowerCase();
+}
+
+function isSystemDirectoryWorkspaceRoot(workspaceRoot) {
+  const root = path.resolve(String(workspaceRoot || ""));
+  const normalized = root.replace(/\\/g, "/").toLowerCase();
+  if (process.platform === "win32") {
+    return (
+      normalized.endsWith("/windows")
+      || normalized.endsWith("/windows/system32")
+      || normalized.endsWith("/windows/syswow64")
+      || normalized.endsWith("/program files")
+      || normalized.endsWith("/program files (x86)")
+    );
+  }
+  return (
+    normalized === "/system"
+    || normalized.startsWith("/system/")
+    || normalized === "/usr"
+    || normalized.startsWith("/usr/")
+    || normalized === "/bin"
+    || normalized.startsWith("/bin/")
+    || normalized === "/sbin"
+    || normalized.startsWith("/sbin/")
+  );
+}
+
+function isEphemeralWorkspaceRoot(workspaceRoot) {
+  const normalized = path.resolve(String(workspaceRoot || ""))
+    .replace(/\\/g, "/")
+    .toLowerCase();
+  return (
+    normalized.includes("/appdata/local/npm-cache/_npx/")
+    || normalized.includes("/node_modules/@reconcrap/boss-recommend-mcp")
+  );
+}
+
+function isSafeBossChatLegacyWorkspaceRoot(workspaceRoot) {
+  const root = path.resolve(String(workspaceRoot || ""));
+  if (!root) return false;
+  const home = path.resolve(os.homedir());
+  return !(
+    isEphemeralWorkspaceRoot(root)
+    || isRootDirectory(root)
+    || root.toLowerCase() === home.toLowerCase()
+    || isSystemDirectoryWorkspaceRoot(root)
+  );
+}
+
+export function getBossChatDataDir() {
+  if (process.env.BOSS_CHAT_HOME) {
+    return path.resolve(process.env.BOSS_CHAT_HOME);
+  }
+  return path.join(getStateHome(), BOSS_CHAT_RUNTIME_SUBDIR);
+}
+
+export function getLegacyBossChatWorkspaceDataDir(workspaceRoot) {
+  if (!isSafeBossChatLegacyWorkspaceRoot(workspaceRoot)) return null;
+  return path.join(path.resolve(String(workspaceRoot)), ".boss-chat");
+}
+
+export function resolveBossChatRuntimeLayout(workspaceRoot) {
+  const dataDir = getBossChatDataDir();
+  const legacyWorkspaceDir = getLegacyBossChatWorkspaceDataDir(workspaceRoot);
+  const migrationSourceDir =
+    legacyWorkspaceDir && pathExists(legacyWorkspaceDir) && !pathExists(dataDir)
+      ? legacyWorkspaceDir
+      : null;
+  return {
+    workspace_root: workspaceRoot ? path.resolve(String(workspaceRoot)) : null,
+    data_dir: dataDir,
+    legacy_workspace_dir: legacyWorkspaceDir,
+    migration_source_dir: migrationSourceDir,
+    migration_pending: Boolean(migrationSourceDir),
+    directories: [
+      dataDir,
+      ...BOSS_CHAT_RUNTIME_CHILD_DIRS.map((name) => path.join(dataDir, name))
+    ]
+  };
+}
+
+export function ensureBossChatRuntimeReady(workspaceRoot) {
+  const runtime = resolveBossChatRuntimeLayout(workspaceRoot);
+  const created = [];
+  const existed = [];
+  const failed = [];
+  let migration = {
+    attempted: false,
+    performed: false,
+    source: runtime.migration_source_dir,
+    target: runtime.data_dir,
+    message: runtime.migration_source_dir
+      ? `Pending legacy boss-chat migration from ${runtime.migration_source_dir}`
+      : ""
+  };
+
+  if (runtime.migration_source_dir) {
+    try {
+      fs.cpSync(runtime.migration_source_dir, runtime.data_dir, {
+        recursive: true,
+        force: false,
+        errorOnExist: false
+      });
+      migration = {
+        attempted: true,
+        performed: true,
+        source: runtime.migration_source_dir,
+        target: runtime.data_dir,
+        message: `Migrated legacy boss-chat runtime from ${runtime.migration_source_dir} to ${runtime.data_dir}. Legacy source was preserved.`
+      };
+    } catch (error) {
+      migration = {
+        attempted: true,
+        performed: false,
+        source: runtime.migration_source_dir,
+        target: runtime.data_dir,
+        message: error?.message || "Legacy boss-chat migration failed."
+      };
+      failed.push({
+        path: runtime.data_dir,
+        message: `Legacy migration failed: ${migration.message}`
+      });
+    }
+  }
+
+  for (const directory of runtime.directories) {
+    try {
+      const existedBefore = pathExists(directory);
+      fs.mkdirSync(directory, { recursive: true });
+      if (existedBefore) {
+        existed.push(directory);
+      } else {
+        created.push(directory);
+      }
+    } catch (error) {
+      failed.push({
+        path: directory,
+        message: error?.message || String(error)
+      });
+    }
+  }
+
+  return {
+    ...runtime,
+    created,
+    existed,
+    failed,
+    migration
+  };
+}
 
 function parsePositiveInteger(value, fallback = null) {
   const parsed = Number.parseInt(String(value ?? ""), 10);
@@ -469,9 +632,12 @@ function buildTargetCountNeedInputDiagnostics(input = {}, missingFields = []) {
   };
 }
 
-function buildBossChatCliArgs(command, input, resolvedConfig) {
-  const args = [command, "--json"];
-  if (command === "prepare-run") {
+function buildBossChatCliArgs(command, input, resolvedConfig, runtimeLayout = null) {
+  const args = [command, "--json"];
+  if (runtimeLayout?.data_dir) {
+    args.push("--data-dir", runtimeLayout.data_dir);
+  }
+  if (command === "prepare-run") {
     const normalized = normalizeBossChatStartInput(input);
     args.push("--profile", normalized.profile);
     if (normalized.job) args.push("--job", normalized.job);
@@ -535,9 +701,9 @@ function buildBossChatCliArgs(command, input, resolvedConfig) {
   return args;
 }
 
-async function spawnBossChatCli({ workspaceRoot, command, input = {} }) {
-  const cliPath = resolveBossChatCliPath(workspaceRoot);
-  if (!cliPath) {
+async function spawnBossChatCli({ workspaceRoot, command, input = {} }) {
+  const cliPath = resolveBossChatCliPath(workspaceRoot);
+  if (!cliPath) {
     return {
       ok: false,
       exitCode: -1,
@@ -549,12 +715,36 @@ async function spawnBossChatCli({ workspaceRoot, command, input = {} }) {
           code: "BOSS_CHAT_CLI_MISSING",
           message: "未找到 vendored boss-chat CLI。"
         }
-      }
-    };
-  }
-
-  let configResolution = null;
-  if (command === "start-run" || command === "prepare-run") {
+      }
+    };
+  }
+
+  const runtimeLayout = ensureBossChatRuntimeReady(workspaceRoot);
+  const runtimeInitFailed = runtimeLayout.failed.some((item) => item.path === runtimeLayout.data_dir)
+    && !pathExists(runtimeLayout.data_dir);
+  if (runtimeInitFailed) {
+    return {
+      ok: false,
+      exitCode: 1,
+      stdout: "",
+      stderr: "",
+      payload: {
+        status: "FAILED",
+        error: {
+          code: "BOSS_CHAT_RUNTIME_INIT_FAILED",
+          message: runtimeLayout.failed
+            .filter((item) => item.path === runtimeLayout.data_dir)
+            .map((item) => item.message)
+            .join("; ") || "无法初始化 boss-chat runtime 目录。"
+        },
+        data_dir: runtimeLayout.data_dir,
+        migration: runtimeLayout.migration
+      }
+    };
+  }
+
+  let configResolution = null;
+  if (command === "start-run" || command === "prepare-run") {
     configResolution = resolveBossChatScreenConfig(workspaceRoot);
     if (!configResolution.ok) {
       return {
@@ -568,13 +758,13 @@ async function spawnBossChatCli({ workspaceRoot, command, input = {} }) {
           config_path: configResolution.config_path,
           config_dir: configResolution.config_dir
         }
-      };
-    }
-  }
-
-  const args = [cliPath, ...buildBossChatCliArgs(command, input, configResolution?.config || {})];
-  const cwd = path.resolve(String(workspaceRoot || process.cwd()));
-  return new Promise((resolve) => {
+      };
+    }
+  }
+
+  const args = [cliPath, ...buildBossChatCliArgs(command, input, configResolution?.config || {}, runtimeLayout)];
+  const cwd = path.resolve(String(workspaceRoot || process.cwd()));
+  return new Promise((resolve) => {
     const child = spawn(process.execPath, args, {
       cwd,
       env: process.env,
@@ -639,41 +829,52 @@ async function spawnBossChatCli({ workspaceRoot, command, input = {} }) {
   });
 }
 
-export function getBossChatHealthCheck(workspaceRoot, input = {}) {
-  const cliDir = resolveBossChatCliDir(workspaceRoot);
-  const cliPath = resolveBossChatCliPath(workspaceRoot);
-  const configResolution = resolveBossChatScreenConfig(workspaceRoot);
-  const resolvedPort = parsePositiveInteger(input.port)
-    || (configResolution.ok ? configResolution.config.debugPort : 9222);
-  if (!cliDir || !cliPath) {
+export function getBossChatHealthCheck(workspaceRoot, input = {}) {
+  const cliDir = resolveBossChatCliDir(workspaceRoot);
+  const cliPath = resolveBossChatCliPath(workspaceRoot);
+  const configResolution = resolveBossChatScreenConfig(workspaceRoot);
+  const runtimeLayout = resolveBossChatRuntimeLayout(workspaceRoot);
+  const resolvedPort = parsePositiveInteger(input.port)
+    || (configResolution.ok ? configResolution.config.debugPort : 9222);
+  if (!cliDir || !cliPath) {
     return {
       status: "FAILED",
-      error: {
-        code: "BOSS_CHAT_CLI_MISSING",
-        message: "未找到 vendored boss-chat CLI。"
-      }
-    };
-  }
-  if (!configResolution.ok) {
+      error: {
+        code: "BOSS_CHAT_CLI_MISSING",
+        message: "未找到 vendored boss-chat CLI。"
+      },
+      data_dir: runtimeLayout.data_dir,
+      legacy_workspace_dir: runtimeLayout.legacy_workspace_dir,
+      migration_pending: runtimeLayout.migration_pending
+    };
+  }
+  if (!configResolution.ok) {
     return {
       status: "FAILED",
-      error: configResolution.error,
-      config_path: configResolution.config_path,
-      config_dir: configResolution.config_dir,
-      cli_dir: cliDir,
-      cli_path: cliPath
-    };
-  }
-  return {
+      error: configResolution.error,
+      config_path: configResolution.config_path,
+      config_dir: configResolution.config_dir,
+      cli_dir: cliDir,
+      cli_path: cliPath,
+      data_dir: runtimeLayout.data_dir,
+      legacy_workspace_dir: runtimeLayout.legacy_workspace_dir,
+      migration_pending: runtimeLayout.migration_pending
+    };
+  }
+  return {
     status: "OK",
     server: "boss-chat",
-    cli_dir: cliDir,
-    cli_path: cliPath,
-    config_path: configResolution.config_path,
-    debug_port: resolvedPort,
-    shared_llm_config: true
-  };
-}
+    cli_dir: cliDir,
+    cli_path: cliPath,
+    config_path: configResolution.config_path,
+    debug_port: resolvedPort,
+    shared_llm_config: true,
+    data_dir: runtimeLayout.data_dir,
+    legacy_workspace_dir: runtimeLayout.legacy_workspace_dir,
+    migration_source_dir: runtimeLayout.migration_source_dir,
+    migration_pending: runtimeLayout.migration_pending
+  };
+}
 
 export async function startBossChatRun({ workspaceRoot, input = {} }) {
   const missingFields = getMissingBossChatStartFields(input);

package/src/cli.js

@@ -18,10 +18,12 @@ import {
 } from "./adapters.js";
 import {
   cancelBossChatRun,
+  ensureBossChatRuntimeReady,
   getBossChatHealthCheck,
   getBossChatRun,
   pauseBossChatRun,
   prepareBossChatRun,
+  resolveBossChatRuntimeLayout,
   resumeBossChatRun,
   startBossChatRun
 } from "./boss-chat.js";
@@ -742,30 +744,22 @@ function ensureUserConfig(options = {}) {
   throw lastError || new Error("No writable target for screening-config.json");
 }
 
-function getBossChatDataDir(workspaceRoot) {
-  return path.join(path.resolve(String(workspaceRoot || process.cwd())), ".boss-chat");
-}
-
 function collectRuntimeDirectories(options = {}) {
   const workspaceRoot = getWorkspaceRoot(options);
   const stateHome = getStateHome();
-  const bossChatRoot = getBossChatDataDir(workspaceRoot);
+  const runtime = resolveBossChatRuntimeLayout(workspaceRoot);
+  const bossChatRoot = runtime.data_dir;
   const recommendRuntimeDirs = [
     stateHome,
     path.join(stateHome, "runs")
   ];
-  const bossChatRuntimeDirs = [
-    bossChatRoot,
-    path.join(bossChatRoot, "logs"),
-    path.join(bossChatRoot, "runs"),
-    path.join(bossChatRoot, "profiles"),
-    path.join(bossChatRoot, "reports"),
-    path.join(bossChatRoot, "artifacts")
-  ];
+  const bossChatRuntimeDirs = runtime.directories || [bossChatRoot];
   return {
     workspaceRoot,
     stateHome,
     bossChatRoot,
+    legacyBossChatRoot: runtime.legacy_workspace_dir,
+    migrationPending: runtime.migration_pending,
     directories: dedupePaths([
       ...recommendRuntimeDirs,
       ...bossChatRuntimeDirs
@@ -774,19 +768,20 @@ function collectRuntimeDirectories(options = {}) {
 }
 
 function ensureRuntimeDirectories(options = {}) {
-  const { workspaceRoot, stateHome, bossChatRoot, directories } = collectRuntimeDirectories(options);
-  const created = [];
-  const existed = [];
-  const failed = [];
+  const { workspaceRoot, stateHome } = collectRuntimeDirectories(options);
+  const runtime = ensureBossChatRuntimeReady(workspaceRoot);
+  const recommendCreated = [];
+  const recommendExisted = [];
+  const failed = [...runtime.failed];
 
-  for (const directory of directories) {
+  for (const directory of [stateHome, path.join(stateHome, "runs")]) {
     try {
       const existedBefore = fs.existsSync(directory);
       ensureDir(directory);
       if (existedBefore) {
-        existed.push(directory);
+        recommendExisted.push(directory);
       } else {
-        created.push(directory);
+        recommendCreated.push(directory);
       }
     } catch (error) {
       failed.push({
@@ -799,9 +794,12 @@ function ensureRuntimeDirectories(options = {}) {
   return {
     workspaceRoot,
     stateHome,
-    bossChatRoot,
-    created,
-    existed,
+    bossChatRoot: runtime.data_dir,
+    legacyBossChatRoot: runtime.legacy_workspace_dir,
+    migrationPending: runtime.migration_pending,
+    migration: runtime.migration,
+    created: dedupePaths([...recommendCreated, ...runtime.created]),
+    existed: dedupePaths([...recommendExisted, ...runtime.existed]),
     failed
   };
 }
@@ -1343,10 +1341,13 @@ function printPaths() {
   const codexHome = getCodexHome();
   const stateHome = getStateHome();
   const calibrationResolution = getFeaturedCalibrationResolution(process.cwd());
+  const bossChatRuntime = resolveBossChatRuntimeLayout(getWorkspaceRoot({}));
   console.log(`package_root=${packageRoot}`);
   console.log(`skill_sources=${bundledSkillNames.map((name) => getSkillSourceDir(name)).join(" | ")}`);
   console.log(`codex_home=${codexHome}`);
   console.log(`state_home=${stateHome}`);
+  console.log(`boss_chat_runtime=${bossChatRuntime.data_dir}`);
+  console.log(`boss_chat_legacy_workspace_runtime=${bossChatRuntime.legacy_workspace_dir || ""}`);
   console.log(`skill_targets=${bundledSkillNames.map((name) => path.join(codexHome, "skills", name)).join(" | ")}`);
   console.log(`config_target=${getUserConfigPath()}`);
   console.log(`legacy_config_target=${getLegacyUserConfigPath()}`);
@@ -1408,6 +1409,9 @@ function installAll(options = {}) {
   );
   console.log(`- recommend runtime: ${runtimeDirsResult.stateHome}`);
   console.log(`- boss-chat runtime: ${runtimeDirsResult.bossChatRoot}`);
+  if (runtimeDirsResult.migration?.performed) {
+    console.log(`- boss-chat migration: ${runtimeDirsResult.migration.message}`);
+  }
   if (runtimeDirsResult.failed.length > 0) {
     for (const item of runtimeDirsResult.failed) {
       console.warn(`Runtime dir warning: ${item.path} -> ${item.message}`);
@@ -1628,6 +1632,9 @@ export async function runCli(argv = process.argv) {
       );
       console.log(`- recommend runtime: ${runtimeDirsResult.stateHome}`);
       console.log(`- boss-chat runtime: ${runtimeDirsResult.bossChatRoot}`);
+      if (runtimeDirsResult.migration?.performed) {
+        console.log(`- boss-chat migration: ${runtimeDirsResult.migration.message}`);
+      }
       if (runtimeDirsResult.failed.length > 0) {
         for (const item of runtimeDirsResult.failed) {
           console.warn(`Runtime dir warning: ${item.path} -> ${item.message}`);
@@ -1716,12 +1723,15 @@ export const __testables = {
   buildBossChatCliInput,
   buildDefaultMcpArgs,
   buildMcpLaunchConfig,
+  collectRuntimeDirectories,
+  ensureBossChatRuntimeReady,
+  ensureRuntimeDirectories,
   getBossChatCliRunTarget,
   getDefaultMcpPackageSpecifier,
   getRunFollowUp,
   installSkill,
   isInstalledPackageRoot,
-  ensureRuntimeDirectories,
+  resolveBossChatRuntimeLayout,
   runBossChatCliCommand,
   runPipelineOnce
 };

package/src/test-boss-chat.js

@@ -4,16 +4,18 @@ import os from "node:os";
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 
-import {
-  cancelBossChatRun,
-  getBossChatHealthCheck,
-  getBossChatRun,
-  pauseBossChatRun,
-  prepareBossChatRun,
-  resumeBossChatRun,
-  startBossChatRun
-} from "./boss-chat.js";
-import { __testables as cliTestables } from "./cli.js";
+import {
+  cancelBossChatRun,
+  ensureBossChatRuntimeReady,
+  getBossChatHealthCheck,
+  getBossChatRun,
+  pauseBossChatRun,
+  prepareBossChatRun,
+  resolveBossChatRuntimeLayout,
+  resumeBossChatRun,
+  startBossChatRun
+} from "./boss-chat.js";
+import { __testables as cliTestables, runCli } from "./cli.js";
 import { __testables as indexTestables } from "./index.js";
 import { BossChatApp } from "../vendor/boss-chat-cli/src/app.js";
 import { __testables as vendorCliTestables } from "../vendor/boss-chat-cli/src/cli.js";
@@ -56,8 +58,8 @@ async function callTool(workspaceRoot, name, args = {}, id = 1) {
   return response?.result?.structuredContent;
 }
 
-function createBossChatTestWorkspace() {
-  const workspaceRoot = fs.mkdtempSync(path.join(os.tmpdir(), "boss-recommend-boss-chat-"));
+function createBossChatTestWorkspace() {
+  const workspaceRoot = fs.mkdtempSync(path.join(os.tmpdir(), "boss-recommend-boss-chat-"));
   const configDir = path.join(workspaceRoot, "config");
   const cliDir = path.join(workspaceRoot, "boss-chat-cli", "src");
   fs.mkdirSync(configDir, { recursive: true });
@@ -72,26 +74,13 @@ function createBossChatTestWorkspace() {
     debugPort: 9666
   }, null, 2));
 
-  fs.writeFileSync(path.join(cliDir, "cli.js"), [
-    "#!/usr/bin/env node",
-    "const fs = require('node:fs');",
-    "const path = require('node:path');",
-    "const cwd = process.cwd();",
-    "const statePath = path.join(cwd, '.boss-chat', 'stub-state.json');",
-    "fs.mkdirSync(path.dirname(statePath), { recursive: true });",
-    "const raw = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf8') : '{}';",
-    "const state = JSON.parse(raw || '{}');",
-    "state.counter = Number.isInteger(state.counter) ? state.counter : 0;",
-    "state.prepare_calls = Number.isInteger(state.prepare_calls) ? state.prepare_calls : 0;",
-    "if (!Number.isInteger(state.prepare_fail_budget)) {",
-    "  const configured = Number.parseInt(process.env.BOSS_CHAT_STUB_PREPARE_FAILS || '0', 10);",
-    "  state.prepare_fail_budget = Number.isFinite(configured) && configured > 0 ? configured : 0;",
-    "}",
-    "state.runs = state.runs && typeof state.runs === 'object' ? state.runs : {};",
-    "state.get_calls = state.get_calls && typeof state.get_calls === 'object' ? state.get_calls : {};",
-    "const argv = process.argv.slice(2);",
-    "const command = String(argv[0] || '').trim();",
-    "const options = {};",
+  fs.writeFileSync(path.join(cliDir, "cli.js"), [
+    "#!/usr/bin/env node",
+    "const fs = require('node:fs');",
+    "const path = require('node:path');",
+    "const argv = process.argv.slice(2);",
+    "const command = String(argv[0] || '').trim();",
+    "const options = {};",
     "for (let index = 1; index < argv.length; index += 1) {",
     "  const token = String(argv[index] || '');",
     "  if (!token.startsWith('--')) continue;",
@@ -102,11 +91,25 @@ function createBossChatTestWorkspace() {
     "    index += 1;",
     "  } else {",
     "    options[key] = true;",
-    "  }",
-    "}",
-    "function saveAndPrint(payload) {",
-    "  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));",
-    "  process.stdout.write(`${JSON.stringify(payload)}\\n`);",
+    "  }",
+    "}",
+    "const cwd = process.cwd();",
+    "const dataDir = String(options['data-dir'] || process.env.BOSS_CHAT_HOME || path.join(cwd, '.boss-chat'));",
+    "const statePath = path.join(dataDir, 'stub-state.json');",
+    "fs.mkdirSync(path.dirname(statePath), { recursive: true });",
+    "const raw = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf8') : '{}';",
+    "const state = JSON.parse(raw || '{}');",
+    "state.counter = Number.isInteger(state.counter) ? state.counter : 0;",
+    "state.prepare_calls = Number.isInteger(state.prepare_calls) ? state.prepare_calls : 0;",
+    "if (!Number.isInteger(state.prepare_fail_budget)) {",
+    "  const configured = Number.parseInt(process.env.BOSS_CHAT_STUB_PREPARE_FAILS || '0', 10);",
+    "  state.prepare_fail_budget = Number.isFinite(configured) && configured > 0 ? configured : 0;",
+    "}",
+    "state.runs = state.runs && typeof state.runs === 'object' ? state.runs : {};",
+    "state.get_calls = state.get_calls && typeof state.get_calls === 'object' ? state.get_calls : {};",
+    "function saveAndPrint(payload) {",
+    "  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));",
+    "  process.stdout.write(`${JSON.stringify(payload)}\\n`);",
     "}",
     "if (command === 'prepare-run') {",
     "  state.prepare_calls += 1;",
@@ -186,29 +189,40 @@ function createBossChatTestWorkspace() {
     "process.exit(1);"
   ].join("\n"), "utf8");
 
-  return workspaceRoot;
-}
-
-function readStubState(workspaceRoot) {
-  const statePath = path.join(workspaceRoot, ".boss-chat", "stub-state.json");
-  return JSON.parse(fs.readFileSync(statePath, "utf8"));
-}
-
-async function withBossChatWorkspace(testFn) {
-  const workspaceRoot = createBossChatTestWorkspace();
-  const previousScreenConfig = process.env.BOSS_RECOMMEND_SCREEN_CONFIG;
-  process.env.BOSS_RECOMMEND_SCREEN_CONFIG = path.join(workspaceRoot, "config", "screening-config.json");
-  try {
-    await testFn(workspaceRoot);
-  } finally {
-    if (previousScreenConfig === undefined) {
-      delete process.env.BOSS_RECOMMEND_SCREEN_CONFIG;
-    } else {
-      process.env.BOSS_RECOMMEND_SCREEN_CONFIG = previousScreenConfig;
-    }
-    fs.rmSync(workspaceRoot, { recursive: true, force: true });
-  }
-}
+  return workspaceRoot;
+}
+
+function getTestChatDataDir(workspaceRoot) {
+  return resolveBossChatRuntimeLayout(workspaceRoot).data_dir;
+}
+
+function readStubState(workspaceRoot) {
+  const statePath = path.join(getTestChatDataDir(workspaceRoot), "stub-state.json");
+  return JSON.parse(fs.readFileSync(statePath, "utf8"));
+}
+
+async function withBossChatWorkspace(testFn) {
+  const workspaceRoot = createBossChatTestWorkspace();
+  const previousScreenConfig = process.env.BOSS_RECOMMEND_SCREEN_CONFIG;
+  const previousBossChatHome = process.env.BOSS_CHAT_HOME;
+  process.env.BOSS_RECOMMEND_SCREEN_CONFIG = path.join(workspaceRoot, "config", "screening-config.json");
+  process.env.BOSS_CHAT_HOME = path.join(workspaceRoot, "user-boss-chat");
+  try {
+    await testFn(workspaceRoot);
+  } finally {
+    if (previousScreenConfig === undefined) {
+      delete process.env.BOSS_RECOMMEND_SCREEN_CONFIG;
+    } else {
+      process.env.BOSS_RECOMMEND_SCREEN_CONFIG = previousScreenConfig;
+    }
+    if (previousBossChatHome === undefined) {
+      delete process.env.BOSS_CHAT_HOME;
+    } else {
+      process.env.BOSS_CHAT_HOME = previousBossChatHome;
+    }
+    fs.rmSync(workspaceRoot, { recursive: true, force: true });
+  }
+}
 
 async function captureConsoleLogs(fn) {
   const messages = [];
@@ -224,12 +238,15 @@ async function captureConsoleLogs(fn) {
   return messages;
 }
 
-async function testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli() {
-  await withBossChatWorkspace(async (workspaceRoot) => {
-    const health = getBossChatHealthCheck(workspaceRoot);
-    assert.equal(health.status, "OK");
-    assert.equal(health.shared_llm_config, true);
-    assert.equal(health.debug_port, 9666);
+async function testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli() {
+  await withBossChatWorkspace(async (workspaceRoot) => {
+    const health = getBossChatHealthCheck(workspaceRoot);
+    assert.equal(health.status, "OK");
+    assert.equal(health.shared_llm_config, true);
+    assert.equal(health.debug_port, 9666);
+    assert.equal(health.data_dir, getTestChatDataDir(workspaceRoot));
+    assert.equal(health.legacy_workspace_dir, path.join(workspaceRoot, ".boss-chat"));
+    assert.equal(health.migration_pending, false);
 
     const prepared = await prepareBossChatRun({
       workspaceRoot,
@@ -259,9 +276,10 @@ async function testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli() {
     assert.equal(preflightTargetQuestion.recommended_argument_patch.target_count, "all");
     assert.equal(Array.isArray(preflightTargetQuestion.options), true);
 
-    const stateAfterPrepare = readStubState(workspaceRoot);
-    assert.equal(stateAfterPrepare.last_prepare_args.profile, "default");
-    assert.equal(stateAfterPrepare.last_prepare_args.port, "9666");
+    const stateAfterPrepare = readStubState(workspaceRoot);
+    assert.equal(stateAfterPrepare.last_prepare_args.profile, "default");
+    assert.equal(stateAfterPrepare.last_prepare_args["data-dir"], getTestChatDataDir(workspaceRoot));
+    assert.equal(stateAfterPrepare.last_prepare_args.port, "9666");
     assert.equal(stateAfterPrepare.last_prepare_args.baseurl, "https://api.example.com/v1");
     assert.equal(stateAfterPrepare.last_prepare_args.apikey, "sk-test-key");
     assert.equal(stateAfterPrepare.last_prepare_args.model, "gpt-4.1-mini");
@@ -281,9 +299,10 @@ async function testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli() {
     assert.equal(started.status, "ACCEPTED");
     assert.equal(Boolean(started.run_id), true);
 
-    const stateAfterStart = readStubState(workspaceRoot);
-    assert.equal(stateAfterStart.last_start_args.profile, "default");
-    assert.equal(stateAfterStart.last_start_args.job, "算法工程师");
+    const stateAfterStart = readStubState(workspaceRoot);
+    assert.equal(stateAfterStart.last_start_args.profile, "default");
+    assert.equal(stateAfterStart.last_start_args["data-dir"], getTestChatDataDir(workspaceRoot));
+    assert.equal(stateAfterStart.last_start_args.job, "算法工程师");
     assert.equal(stateAfterStart.last_start_args["start-from"], "unread");
     assert.equal(stateAfterStart.last_start_args.criteria, "有 AI Agent 经验");
     assert.equal(stateAfterStart.last_start_args.targetCount, "2");
@@ -389,11 +408,99 @@ async function testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli() {
       }
     });
     assert.equal(canceled.run.state, "canceled");
-  });
-}
-
-async function testBossChatPrepareShouldRetryWhenChatPageIsNotReady() {
-  await withBossChatWorkspace(async (workspaceRoot) => {
+  });
+}
+
+async function testBossChatRuntimeShouldMigrateLegacyWorkspaceDataOnce() {
+  await withBossChatWorkspace(async (workspaceRoot) => {
+    const legacyDir = path.join(workspaceRoot, ".boss-chat");
+    const legacyStatePath = path.join(legacyDir, "state", "default.json");
+    const legacyRunPath = path.join(legacyDir, "runs", "legacy-run.json");
+    fs.mkdirSync(path.dirname(legacyStatePath), { recursive: true });
+    fs.mkdirSync(path.dirname(legacyRunPath), { recursive: true });
+    fs.writeFileSync(legacyStatePath, JSON.stringify({ cursor: 7 }, null, 2));
+    fs.writeFileSync(legacyRunPath, JSON.stringify({ run_id: "legacy-run" }, null, 2));
+
+    const before = resolveBossChatRuntimeLayout(workspaceRoot);
+    assert.equal(before.data_dir, getTestChatDataDir(workspaceRoot));
+    assert.equal(before.legacy_workspace_dir, legacyDir);
+    assert.equal(before.migration_source_dir, legacyDir);
+    assert.equal(before.migration_pending, true);
+
+    const ready = ensureBossChatRuntimeReady(workspaceRoot);
+    assert.equal(ready.migration.attempted, true);
+    assert.equal(ready.migration.performed, true);
+    assert.equal(fs.existsSync(path.join(ready.data_dir, "state", "default.json")), true);
+    assert.equal(fs.existsSync(path.join(ready.data_dir, "runs", "legacy-run.json")), true);
+    assert.deepEqual(
+      JSON.parse(fs.readFileSync(path.join(ready.data_dir, "state", "default.json"), "utf8")),
+      { cursor: 7 }
+    );
+    assert.equal(fs.existsSync(legacyStatePath), true);
+
+    const after = resolveBossChatRuntimeLayout(workspaceRoot);
+    assert.equal(after.migration_pending, false);
+    assert.equal(after.migration_source_dir, null);
+
+    const secondReady = ensureBossChatRuntimeReady(workspaceRoot);
+    assert.equal(secondReady.migration.attempted, false);
+    assert.equal(secondReady.migration.performed, false);
+  });
+}
+
+function testBossChatRuntimeShouldResolveUserDirForRootWorkspace() {
+  const previousBossChatHome = process.env.BOSS_CHAT_HOME;
+  const previousRecommendHome = process.env.BOSS_RECOMMEND_HOME;
+  const runtimeRoot = fs.mkdtempSync(path.join(os.tmpdir(), "boss-chat-root-runtime-"));
+  try {
+    delete process.env.BOSS_CHAT_HOME;
+    process.env.BOSS_RECOMMEND_HOME = runtimeRoot;
+    const rootWorkspace = path.parse(process.cwd()).root;
+    const runtime = resolveBossChatRuntimeLayout(rootWorkspace);
+    assert.equal(runtime.data_dir, path.join(runtimeRoot, "boss-chat"));
+    assert.equal(runtime.legacy_workspace_dir, null);
+    assert.equal(runtime.migration_pending, false);
+
+    const ready = ensureBossChatRuntimeReady(rootWorkspace);
+    assert.equal(fs.existsSync(ready.data_dir), true);
+    assert.equal(fs.existsSync(path.join(ready.data_dir, "runs")), true);
+  } finally {
+    if (previousBossChatHome === undefined) {
+      delete process.env.BOSS_CHAT_HOME;
+    } else {
+      process.env.BOSS_CHAT_HOME = previousBossChatHome;
+    }
+    if (previousRecommendHome === undefined) {
+      delete process.env.BOSS_RECOMMEND_HOME;
+    } else {
+      process.env.BOSS_RECOMMEND_HOME = previousRecommendHome;
+    }
+    fs.rmSync(runtimeRoot, { recursive: true, force: true });
+  }
+}
+
+async function testBossChatWhereShouldPrintUserRuntimePath() {
+  await withBossChatWorkspace(async (workspaceRoot) => {
+    const previousWorkspaceRoot = process.env.BOSS_WORKSPACE_ROOT;
+    process.env.BOSS_WORKSPACE_ROOT = workspaceRoot;
+    try {
+      const logs = await captureConsoleLogs(async () => {
+        await runCli(["node", "src/cli.js", "where"]);
+      });
+      assert.equal(logs.some((line) => line.includes(`boss_chat_runtime=${getTestChatDataDir(workspaceRoot)}`)), true);
+      assert.equal(logs.some((line) => line.includes(`boss_chat_legacy_workspace_runtime=${path.join(workspaceRoot, ".boss-chat")}`)), true);
+    } finally {
+      if (previousWorkspaceRoot === undefined) {
+        delete process.env.BOSS_WORKSPACE_ROOT;
+      } else {
+        process.env.BOSS_WORKSPACE_ROOT = previousWorkspaceRoot;
+      }
+    }
+  });
+}
+
+async function testBossChatPrepareShouldRetryWhenChatPageIsNotReady() {
+  await withBossChatWorkspace(async (workspaceRoot) => {
     const previousPrepareFails = process.env.BOSS_CHAT_STUB_PREPARE_FAILS;
     process.env.BOSS_CHAT_STUB_PREPARE_FAILS = "2";
     try {
@@ -412,8 +519,26 @@ async function testBossChatPrepareShouldRetryWhenChatPageIsNotReady() {
         process.env.BOSS_CHAT_STUB_PREPARE_FAILS = previousPrepareFails;
       }
     }
-  });
-}
+  });
+}
+
+function testVendorBossChatCliShouldResolveExplicitDataDir() {
+  const cwd = path.join(path.parse(process.cwd()).root, "workspace");
+  const args = vendorCliTestables.parseArgs(["start-run", "--data-dir", "/tmp/boss-chat-data"]);
+  assert.equal(args.dataDir, "/tmp/boss-chat-data");
+  assert.equal(
+    vendorCliTestables.resolveDataDir(args, { BOSS_CHAT_HOME: "/tmp/ignored" }, cwd),
+    path.resolve("/tmp/boss-chat-data")
+  );
+  assert.equal(
+    vendorCliTestables.resolveDataDir({}, { BOSS_CHAT_HOME: "/tmp/from-env" }, cwd),
+    path.resolve("/tmp/from-env")
+  );
+  assert.equal(
+    vendorCliTestables.resolveDataDir({}, {}, cwd),
+    path.join(path.resolve(cwd), ".boss-chat")
+  );
+}
 
 async function testBossChatPageShouldTreatBlankChatShellAsOnChatPage() {
   const fakeChromeClient = {
@@ -2879,9 +3004,12 @@ async function testBossChatReportStoreShouldWriteReadableMarkdownAndCsv() {
   assert.match(csvContent, /先看项目经历，再看实习时长/);
 }
 
-async function main() {
-  await testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli();
-  await testBossChatPrepareShouldRetryWhenChatPageIsNotReady();
+async function main() {
+  await testBossChatAdapterShouldResolveSharedConfigAndInvokeLocalCli();
+  await testBossChatRuntimeShouldMigrateLegacyWorkspaceDataOnce();
+  testBossChatRuntimeShouldResolveUserDirForRootWorkspace();
+  await testBossChatWhereShouldPrintUserRuntimePath();
+  await testBossChatPrepareShouldRetryWhenChatPageIsNotReady();
   await testBossChatPageShouldTreatBlankChatShellAsOnChatPage();
   await testBossChatRecoverToChatIndexShouldForceNavigateAndWaitForCompleteLoad();
   await testBossChatPageShouldFallbackToEscapeWhenClosingCandidateDetail();
@@ -2889,8 +3017,9 @@ async function main() {
   await testBossChatPageShouldWaitForPanelsClosedInStrictConversationReady();
   await testBossChatPageShouldSurfaceCandidateDetailOverlayAndContentState();
   await testBossChatMcpToolsShouldValidateAndRoute();
-  await testBossChatCliShouldSupportRunAndFollowUpParsing();
-  await testVendorBossChatCliShouldWaitForHydratedChatShell();
+  await testBossChatCliShouldSupportRunAndFollowUpParsing();
+  testVendorBossChatCliShouldResolveExplicitDataDir();
+  await testVendorBossChatCliShouldWaitForHydratedChatShell();
   await testVendorBossChatCliShouldRetryJobListDuringPromptRunProfile();
   testCliShouldPinInstalledPackageVersionInGeneratedMcpConfig();
   testVendorBossChatCliShouldParseSharedLlmTransportArgs();

package/vendor/boss-chat-cli/src/cli.js

@@ -178,13 +178,14 @@ function parseTargetCount(value) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
 }
 
-function parseArgs(argv) {
-  const args = {
-    command: 'run',
-    profile: 'default',
-    dryRun: false,
-    noState: false,
-    json: false,
+function parseArgs(argv) {
+  const args = {
+    command: 'run',
+    profile: 'default',
+    dataDir: '',
+    dryRun: false,
+    noState: false,
+    json: false,
     runId: '',
     detachedWorker: false,
     overrides: {
@@ -213,13 +214,17 @@ function parseArgs(argv) {
       index += 1;
     }
 
-    switch (name) {
-      case 'profile':
-        args.profile = value || args.profile;
-        break;
-      case 'dry-run':
-        args.dryRun = true;
-        break;
+    switch (name) {
+      case 'profile':
+        args.profile = value || args.profile;
+        break;
+      case 'data-dir':
+      case 'dataDir':
+        args.dataDir = String(value || '').trim();
+        break;
+      case 'dry-run':
+        args.dryRun = true;
+        break;
       case 'no-state':
         args.noState = true;
         break;
@@ -293,8 +298,16 @@ function parseArgs(argv) {
   if (positionals.length > 0) {
     args.command = positionals[0];
   }
-  return args;
-}
+  return args;
+}
+
+function resolveDataDir(args = {}, env = process.env, cwd = process.cwd()) {
+  const explicit = String(args?.dataDir || '').trim();
+  if (explicit) return path.resolve(explicit);
+  const fromEnv = String(env?.BOSS_CHAT_HOME || '').trim();
+  if (fromEnv) return path.resolve(fromEnv);
+  return path.join(path.resolve(String(cwd || process.cwd())), '.boss-chat');
+}
 
 function printUsage() {
   console.log('Usage: boss-chat <command> [options]');
@@ -308,11 +321,12 @@ function printUsage() {
   console.log('  resume-run                      Resume paused async run');
   console.log('  cancel-run                      Cancel async run');
   console.log('');
-  console.log('Common options:');
-  console.log('  --profile <name>                Profile name (default: default)');
-  console.log('  --json                          JSON output for agent integration');
-  console.log('  --run-id <id>                   Target async run_id (for get/pause/resume/cancel)');
-  console.log('');
+  console.log('Common options:');
+  console.log('  --profile <name>                Profile name (default: default)');
+  console.log('  --data-dir <path>               Runtime data dir (default: $BOSS_CHAT_HOME or <cwd>/.boss-chat)');
+  console.log('  --json                          JSON output for agent integration');
+  console.log('  --run-id <id>                   Target async run_id (for get/pause/resume/cancel)');
+  console.log('');
   console.log('Run options:');
   console.log('  --dry-run                       Evaluate and click, but do not request resume');
   console.log('  --no-state                      Disable in-run candidate deduplication');
@@ -1511,10 +1525,10 @@ async function executeRunCommand(args, dataDir) {
   }
 }
 
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const dataDir = path.join(process.cwd(), '.boss-chat');
-  await mkdir(dataDir, { recursive: true });
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const dataDir = resolveDataDir(args);
+  await mkdir(dataDir, { recursive: true });
 
   if (args.command === 'help') {
     printUsage();
@@ -1558,11 +1572,12 @@ async function main() {
   }
 }
 
-export const __testables = {
-  parseArgs,
-  connectBossChatPage,
-  hasHydratedChatShell,
-  promptRunProfile,
+export const __testables = {
+  parseArgs,
+  resolveDataDir,
+  connectBossChatPage,
+  hasHydratedChatShell,
+  promptRunProfile,
   resolveJobsWithRetry,
   waitForChatShellHydration,
 };