@reconcrap/boss-recommend-mcp 2.0.1 → 2.0.3

package/package.json

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

package/skills/boss-chat/SKILL.md

@@ -57,6 +57,9 @@ description: "Use when users want Boss chat-page screening/outreach via the bund
   - 只在用户明确是 chat-only 任务时使用本 skill。
   - 只要用户提到推荐页、先找人后沟通、或需要推荐筛选阶段，禁止直接调用 `start_boss_chat_run`；必须先交给 `boss-recommend-pipeline` 完成推荐页任务。
   - 不得在 recommend 任务尚未完成时并行启动独立 chat run。
+- 启动或准备 chat run 时，若本机默认 `127.0.0.1:9222` Chrome DevTools 端口不可连，工具会自动打开 Chrome 并导航到 `https://www.zhipin.com/web/chat/index`。
+- 只有工具返回 `BOSS_LOGIN_REQUIRED` / `requires_login=true` 时，才要求用户在自动打开的 Chrome 窗口人工登录 Boss 后重试；不要把“没开 9222 Chrome”当作缺参。
+- 若本机找不到 Chrome，可提示用户设置 `BOSS_MCP_CHROME_PATH` 或 `BOSS_RECOMMEND_CHROME_PATH`；非本机 debug host 不自动启动。
 - `job` / `start_from` / `criteria` 缺一不可；缺参时只补缺口。
 - `target_count` 在 chat-only 启动前也是必填项，不能默认省略。
 - 当用户说“全部候选人/所有候选人”时，必须按“扫到底（unlimited）”处理，不要再追问正整数。

package/skills/boss-recommend-pipeline/SKILL.md

@@ -31,6 +31,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - `criteria` 必须是用户开放式自然语言；禁止“严格/宽松执行”等预设替代。
   - `post_action=greet` 时，必须确认 `max_greet_count`；禁止自动默认为 `target_count`。
   - 正式执行前必须 `final_confirmed=true`。
+  - 真实筛选禁止传 `detail_limit: 0`；recommend 默认必须打开候选人详情/CV。只有用户明确要求“卡片-only 调试”时，才允许同时传 `detail_limit: 0` 和 `allow_card_only_screening: true`。
 
 - **Instruction 原文锁定**
   - 首次用户需求原文锁定为 `locked_instruction_raw`。
@@ -117,8 +118,14 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 
 - 执行前必须通过：
   - `screening-config.json` 可用且非占位值（`baseUrl/apiKey/model`）
-  - Chrome DevTools 端口可连
-  - Boss 已登录且位于 `https://www.zhipin.com/web/chat/recommend`
+  - 工具可连接或自动启动本机 Chrome DevTools 端口（默认 `127.0.0.1:9222`）
+  - Boss 已登录；若当前没有 9222 Chrome，工具会自动打开 Chrome 并导航到 `https://www.zhipin.com/web/chat/recommend`
+  - 只有工具返回 `BOSS_LOGIN_REQUIRED` / `requires_login=true` 时，才要求用户人工登录 Boss 后重试
+
+- 不要在运行前要求用户手动打开 9222 Chrome。只有这些情况需要人工介入：
+  - 工具明确报告 `BOSS_LOGIN_REQUIRED`
+  - 本机找不到 Chrome 可执行文件，并提示设置 `BOSS_MCP_CHROME_PATH` 或 `BOSS_RECOMMEND_CHROME_PATH`
+  - 用户配置的是非本机 debug host，工具无法安全自动启动
 
 - `PIPELINE_PREFLIGHT_FAILED` 处理顺序：
   1. 若 `screen_config` 失败：让用户提供真实 `baseUrl/apiKey/model`，并在 `guidance.config_path` 修改后明确回复“已修改完成”。
@@ -152,3 +159,4 @@ MCP 不可用时：
 - 页面就绪失败提示必须包含 `debug_port`、recommend URL、以及登录 URL（若未登录）：
   - `https://www.zhipin.com/web/chat/recommend`
   - `https://www.zhipin.com/web/user/?ka=bticket`
+- 若错误是 `BOSS_LOGIN_REQUIRED`，提示用户在自动打开的 Chrome 窗口完成登录，然后原参数重试；不要改用 search/recruit 路径。

package/skills/boss-recruit-pipeline/SKILL.md

@@ -25,6 +25,9 @@ description: "Use when users want Boss search/recruit-page screening via the uni
 - 如果用户说聊天页、未读、全部聊天、求简历，必须交给 `boss-chat`。
 - 禁止调用旧包：`@reconcrap/boss-recruit-mcp`、`boss-recruit-mcp`、旧本地 recruit repo、旧 vendor 脚本。
 - 浏览器自动化必须走 CDP-only 2.x MCP 工具；不得要求用户启用 legacy page-JS 或 `Runtime.evaluate` 路径。
+- 启动 search/recruit run 时，若本机默认 `127.0.0.1:9222` Chrome DevTools 端口不可连，工具会自动打开 Chrome 并导航到 `https://www.zhipin.com/web/chat/search`。
+- 只有工具返回 `BOSS_LOGIN_REQUIRED` / `requires_login=true` 时，才要求用户在自动打开的 Chrome 窗口人工登录 Boss 后重试；不要把“没开 9222 Chrome”当作缺参。
+- 若本机找不到 Chrome，可提示用户设置 `BOSS_MCP_CHROME_PATH` 或 `BOSS_RECOMMEND_CHROME_PATH`；非本机 debug host 不自动启动。
 - 若用户未提供岗位，必须先询问岗位。搜索页岗位选择在关键词输入框旁边；不要猜测默认岗位。
 - 若用户提供城市、学历、学校、关键词、过滤已看、人选目标数、筛选条件、post action、max greet 等参数，必须逐项传入或确认。
 - `post_action=greet` 时必须确认 `max_greet_count`；不要默认等于 `target_count`。

package/src/chat-mcp.js

@@ -4,8 +4,13 @@ import process from "node:process";
 import {
   assertNoForbiddenCdpCalls,
   bringPageToFront,
-  connectToChromeTarget,
+  connectToChromeTargetOrOpen,
+  createBossLoginRequiredError,
+  detectBossLoginState,
   enableDomains,
+  getMainFrameUrl,
+  isBossLoginUrl,
+  waitForMainFrameUrl,
   sleep
 } from "./core/browser/index.js";
 import {
@@ -472,6 +477,14 @@ async function waitForHealthyChat(client, config, {
   const started = Date.now();
   let lastCheck = null;
   while (Date.now() - started <= timeoutMs) {
+    const loginDetection = await detectBossLoginState(client).catch(() => null);
+    if (loginDetection?.requires_login) {
+      return {
+        status: "login_required",
+        summary: "Boss login is required",
+        loginDetection
+      };
+    }
     const roots = await resolveChatSelfHealRoots(client, config);
     lastCheck = await runSelfHealCheck({
       client,
@@ -493,24 +506,18 @@ async function connectChatChromeSession({
   allowNavigate = true,
   slowLive = false
 } = {}) {
-  let session;
-  try {
-    session = await connectToChromeTarget({
-      host,
-      port,
-      targetUrlIncludes
-    });
-  } catch (error) {
-    if (!allowNavigate) throw error;
-    session = await connectToChromeTarget({
-      host,
-      port,
-      targetPredicate: (target) => (
-        target?.type === "page"
-        && isRecoverableChatTargetUrl(target?.url)
-      )
-    });
-  }
+  const session = await connectToChromeTargetOrOpen({
+    host,
+    port,
+    targetUrlIncludes,
+    targetUrl: CHAT_TARGET_URL,
+    allowNavigate,
+    slowLive,
+    fallbackTargetPredicate: (target) => (
+      target?.type === "page"
+      && (isRecoverableChatTargetUrl(target?.url) || String(target?.url || "").includes("zhipin.com"))
+    )
+  });
 
   const { client, target } = session;
   await enableDomains(client, ["Page", "DOM", "Input", "Network", "Accessibility"]);
@@ -527,20 +534,90 @@ async function connectChatChromeSession({
   if (allowNavigate && shouldNavigateToChat(targetUrl)) {
     await client.Page.navigate({ url: CHAT_TARGET_URL });
     const settleMs = slowLive ? 10000 : 5000;
-    await sleep(settleMs);
+    const waited = await waitForMainFrameUrl(
+      client,
+      (url) => isBossLoginUrl(url) || !shouldNavigateToChat(url),
+      { timeoutMs: settleMs, intervalMs: 500 }
+    );
     navigation = {
       navigated: true,
       url: CHAT_TARGET_URL,
-      settle_ms: settleMs
+      settle_ms: settleMs,
+      observed_url: waited.url || null,
+      observed_url_ok: waited.ok
     };
   }
+  let currentUrl = await getMainFrameUrl(client).catch(() => navigation.url || targetUrl);
+  if (allowNavigate && shouldNavigateToChat(currentUrl) && !isBossLoginUrl(currentUrl)) {
+    await client.Page.navigate({ url: CHAT_TARGET_URL });
+    const settleMs = slowLive ? 10000 : 5000;
+    const waited = await waitForMainFrameUrl(
+      client,
+      (url) => isBossLoginUrl(url) || !shouldNavigateToChat(url),
+      { timeoutMs: settleMs, intervalMs: 500 }
+    );
+    navigation = {
+      navigated: true,
+      url: CHAT_TARGET_URL,
+      settle_ms: settleMs,
+      observed_url: waited.url || null,
+      observed_url_ok: waited.ok,
+      reason: "observed_url_mismatch"
+    };
+    currentUrl = await getMainFrameUrl(client).catch(() => waited.url || currentUrl);
+  }
+  const loginDetection = await detectBossLoginState(client, { currentUrl }).catch(() => ({
+    requires_login: isBossLoginUrl(currentUrl),
+    reason: "login_detection_failed",
+    current_url: currentUrl
+  }));
+  if (loginDetection.requires_login) {
+    await session.close?.();
+    throw createBossLoginRequiredError({
+      domain: "chat",
+      currentUrl: loginDetection.current_url || currentUrl,
+      targetUrl: CHAT_TARGET_URL,
+      loginDetection,
+      chrome: session.chrome || null
+    });
+  }
+  if (shouldNavigateToChat(currentUrl)) {
+    await session.close?.();
+    throw new Error(`Boss chat page did not navigate to ${CHAT_TARGET_URL}; current URL: ${currentUrl || "unknown"}`);
+  }
 
   const selfHealConfig = buildChatSelfHealConfig();
   const health = await waitForHealthyChat(client, selfHealConfig, {
     timeoutMs: slowLive ? 180000 : 90000,
     intervalMs: slowLive ? 1200 : 800
   });
+  if (health?.loginDetection?.requires_login) {
+    await session.close?.();
+    throw createBossLoginRequiredError({
+      domain: "chat",
+      currentUrl: health.loginDetection.current_url || currentUrl,
+      targetUrl: CHAT_TARGET_URL,
+      loginDetection: health.loginDetection,
+      chrome: session.chrome || null
+    });
+  }
   if (!health || health.status !== HEALTH_STATUS.HEALTHY) {
+    const latestUrl = await getMainFrameUrl(client).catch(() => currentUrl);
+    const latestLoginDetection = await detectBossLoginState(client, { currentUrl: latestUrl }).catch(() => ({
+      requires_login: isBossLoginUrl(latestUrl),
+      reason: "login_detection_failed",
+      current_url: latestUrl
+    }));
+    if (latestLoginDetection.requires_login) {
+      await session.close?.();
+      throw createBossLoginRequiredError({
+        domain: "chat",
+        currentUrl: latestLoginDetection.current_url || latestUrl,
+        targetUrl: CHAT_TARGET_URL,
+        loginDetection: latestLoginDetection,
+        chrome: session.chrome || null
+      });
+    }
     throw new Error(`Boss chat page is not healthy: ${health?.status || "missing"}`);
   }
 
@@ -845,13 +922,21 @@ async function startBossChatRunInternal(args = {}, { workspaceRoot = "" } = {})
       slowLive: normalized.slowLive
     });
   } catch (error) {
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       error: {
-        code: "BOSS_CHAT_PAGE_NOT_READY",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "BOSS_CHAT_PAGE_NOT_READY",
         message: error?.message || "Boss chat page is not ready",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        chrome: error?.chrome || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || CHAT_TARGET_URL,
         retryable: true
-      }
+      },
+      chrome: error?.chrome || null
     };
   }
 
@@ -880,7 +965,8 @@ async function startBossChatRunInternal(args = {}, { workspaceRoot = "" } = {})
       host: normalized.host,
       port: normalized.port,
       target_url: session.navigation?.url || session.target?.url || CHAT_TARGET_URL,
-      target_id: session.target?.id || null
+      target_id: session.target?.id || null,
+      auto_launch: session.chrome || null
     },
     health: session.health || null
   });
@@ -912,12 +998,19 @@ export async function prepareBossChatRunTool({ workspaceRoot = "", args = {} } =
       slowLive: normalized.slowLive
     });
   } catch (error) {
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       stage: "chat_run_setup",
       error: {
-        code: "BOSS_CHAT_PAGE_NOT_READY",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "BOSS_CHAT_PAGE_NOT_READY",
         message: error?.message || "Boss chat page is not ready",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        chrome: error?.chrome || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || CHAT_TARGET_URL,
         retryable: true
       },
       runtime_evaluate_used: false,
@@ -926,7 +1019,8 @@ export async function prepareBossChatRunTool({ workspaceRoot = "", args = {} } =
       chrome: {
         host: normalized.host,
         port: normalized.port,
-        target_url: CHAT_TARGET_URL
+        target_url: CHAT_TARGET_URL,
+        auto_launch: error?.chrome || null
       }
     };
   }
@@ -979,16 +1073,24 @@ export async function prepareBossChatRunTool({ workspaceRoot = "", args = {} } =
         host: normalized.host,
         port: normalized.port,
         target_url: session.navigation?.url || session.target?.url || CHAT_TARGET_URL,
-        target_id: session.target?.id || null
+        target_id: session.target?.id || null,
+        auto_launch: session.chrome || null
       }
     };
   } catch (error) {
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       stage: "chat_run_setup",
       error: {
-        code: "BOSS_CHAT_PREPARE_FAILED",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "BOSS_CHAT_PREPARE_FAILED",
         message: error?.message || "Boss chat CDP-only prepare failed",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        chrome: error?.chrome || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || CHAT_TARGET_URL,
         retryable: true
       },
       runtime_evaluate_used: false,
@@ -998,7 +1100,8 @@ export async function prepareBossChatRunTool({ workspaceRoot = "", args = {} } =
         host: normalized.host,
         port: normalized.port,
         target_url: session.navigation?.url || session.target?.url || CHAT_TARGET_URL,
-        target_id: session.target?.id || null
+        target_id: session.target?.id || null,
+        auto_launch: session.chrome || null
       }
     };
   } finally {
@@ -1073,17 +1176,25 @@ export async function bossChatHealthCheckTool({ workspaceRoot = "", args = {} }
         host,
         port,
         target_url: session.navigation?.url || session.target?.url || CHAT_TARGET_URL,
-        target_id: session.target?.id || null
+        target_id: session.target?.id || null,
+        auto_launch: session.chrome || null
       },
       message: "Boss chat CDP-only health check passed with shared self-heal probes."
     };
   } catch (error) {
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       ...basePayload,
       error: {
-        code: "BOSS_CHAT_PAGE_NOT_READY",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "BOSS_CHAT_PAGE_NOT_READY",
         message: error?.message || "Boss chat page is not ready",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        chrome: error?.chrome || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || CHAT_TARGET_URL,
         retryable: true
       },
       runtime_evaluate_used: false,
@@ -1093,7 +1204,8 @@ export async function bossChatHealthCheckTool({ workspaceRoot = "", args = {} }
         host,
         port,
         target_url: session?.navigation?.url || session?.target?.url || targetUrlIncludes,
-        target_id: session?.target?.id || null
+        target_id: session?.target?.id || null,
+        auto_launch: error?.chrome || session?.chrome || null
       }
     };
   } finally {

package/src/core/browser/index.js

@@ -1,7 +1,12 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import CDP from "chrome-remote-interface";
 
 export const DEFAULT_CHROME_HOST = "127.0.0.1";
 export const DEFAULT_CHROME_PORT = 9222;
+export const BOSS_LOGIN_URL = "https://www.zhipin.com/web/user/?ka=bticket";
 
 export const ALLOWED_CDP_DOMAINS = new Set([
   "Accessibility",
@@ -14,6 +19,21 @@ export const ALLOWED_CDP_DOMAINS = new Set([
 
 export const FORBIDDEN_CDP_DOMAINS = new Set(["Runtime"]);
 
+const BOSS_LOGIN_URL_PATTERN = /(?:zhipin\.com\/web\/user(?:\/|\?|$)|passport\.zhipin\.com|login\.zhipin\.com)/i;
+const BOSS_LOGIN_TEXT_PATTERN = /扫码登录|验证码登录|密码登录|登录后|请登录|登录BOSS直聘|Boss登录|BOSS登录/i;
+const CHROME_DEBUG_UNAVAILABLE_PATTERN = /ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|connect|socket hang up/i;
+const BOSS_LOGIN_DOM_SELECTORS = [
+  ".login-box",
+  ".login-form",
+  ".login-dialog",
+  ".sign-form",
+  ".qrcode-box",
+  ".user-login",
+  "input[name='phone']",
+  "input[placeholder*='手机号']",
+  "input[placeholder*='验证码']"
+];
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -49,6 +69,378 @@ export function assertNoForbiddenCdpCalls(methodLog = []) {
   }
 }
 
+export function isBossLoginUrl(url) {
+  return BOSS_LOGIN_URL_PATTERN.test(String(url || ""));
+}
+
+export function createBossLoginRequiredError({
+  domain = "boss",
+  currentUrl = "",
+  targetUrl = "",
+  loginUrl = BOSS_LOGIN_URL,
+  loginDetection = null,
+  chrome = null
+} = {}) {
+  const error = new Error(`Boss login is required before starting the ${domain} run.`);
+  error.code = "BOSS_LOGIN_REQUIRED";
+  error.requires_login = true;
+  error.current_url = currentUrl || null;
+  error.target_url = targetUrl || null;
+  error.login_url = loginUrl;
+  error.login_detection = loginDetection || null;
+  error.chrome = chrome || null;
+  error.retryable = true;
+  return error;
+}
+
+export async function detectBossLoginState(client, { currentUrl = "" } = {}) {
+  const inspectedUrl = currentUrl || await getMainFrameUrl(client).catch(() => "");
+  if (isBossLoginUrl(inspectedUrl)) {
+    return {
+      requires_login: true,
+      reason: "url",
+      current_url: inspectedUrl,
+      matched_selectors: []
+    };
+  }
+
+  let root = null;
+  try {
+    root = await getDocumentRoot(client, { depth: 1, pierce: true });
+  } catch (error) {
+    return {
+      requires_login: false,
+      reason: "dom_unavailable",
+      current_url: inspectedUrl,
+      error: error?.message || String(error || "")
+    };
+  }
+
+  const matchedSelectors = [];
+  for (const selector of BOSS_LOGIN_DOM_SELECTORS) {
+    const nodeId = await querySelector(client, root.nodeId, selector).catch(() => 0);
+    if (nodeId) matchedSelectors.push(selector);
+  }
+
+  if (matchedSelectors.length === 0) {
+    return {
+      requires_login: false,
+      reason: "no_login_dom",
+      current_url: inspectedUrl,
+      matched_selectors: []
+    };
+  }
+
+  const html = await getOuterHTML(client, root.nodeId).catch(() => "");
+  const looksLikeLogin = BOSS_LOGIN_TEXT_PATTERN.test(html);
+  return {
+    requires_login: looksLikeLogin,
+    reason: looksLikeLogin ? "dom" : "login_selector_without_login_text",
+    current_url: inspectedUrl,
+    matched_selectors: matchedSelectors
+  };
+}
+
+export function isChromeDebugUnavailableError(error) {
+  return CHROME_DEBUG_UNAVAILABLE_PATTERN.test(String(error?.message || error || ""));
+}
+
+function pathExists(targetPath) {
+  try {
+    return Boolean(targetPath) && fs.existsSync(targetPath);
+  } catch {
+    return false;
+  }
+}
+
+function ensureDir(targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true });
+}
+
+function isLocalChromeHost(host) {
+  const normalized = String(host || "").trim().toLowerCase();
+  return !normalized || normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+}
+
+function getCodexHome() {
+  return process.env.CODEX_HOME
+    ? path.resolve(process.env.CODEX_HOME)
+    : path.join(os.homedir(), ".codex");
+}
+
+function getDefaultChromeExecutableCandidates() {
+  const candidates = [
+    process.env.BOSS_MCP_CHROME_PATH,
+    process.env.BOSS_RECOMMEND_CHROME_PATH
+  ].filter(Boolean);
+  if (process.platform === "win32") {
+    candidates.push(
+      path.join(process.env.LOCALAPPDATA || "", "Google", "Chrome", "Application", "chrome.exe"),
+      path.join(process.env.ProgramFiles || "", "Google", "Chrome", "Application", "chrome.exe"),
+      path.join(process.env["ProgramFiles(x86)"] || "", "Google", "Chrome", "Application", "chrome.exe")
+    );
+  } else if (process.platform === "darwin") {
+    candidates.push(
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      path.join(os.homedir(), "Applications", "Google Chrome.app", "Contents", "MacOS", "Google Chrome"),
+      "/Applications/Chromium.app/Contents/MacOS/Chromium"
+    );
+  } else {
+    candidates.push(
+      "/usr/bin/google-chrome",
+      "/usr/bin/google-chrome-stable",
+      "/usr/bin/chromium-browser",
+      "/usr/bin/chromium",
+      "/snap/bin/chromium"
+    );
+  }
+  return Array.from(new Set(candidates.filter(Boolean)));
+}
+
+export function getChromeExecutable() {
+  return getDefaultChromeExecutableCandidates().find((candidate) => pathExists(candidate)) || null;
+}
+
+export function getBossChromeUserDataDir(port = DEFAULT_CHROME_PORT) {
+  const sharedPath = path.join(getCodexHome(), "boss-mcp", `chrome-profile-${port}`);
+  ensureDir(sharedPath);
+  return sharedPath;
+}
+
+export async function waitForChromeDebugPort({
+  host = DEFAULT_CHROME_HOST,
+  port = DEFAULT_CHROME_PORT,
+  timeoutMs = 8000,
+  intervalMs = 300
+} = {}) {
+  const started = Date.now();
+  let lastError = null;
+  while (Date.now() - started <= timeoutMs) {
+    try {
+      const targets = await listChromeTargets({ host, port });
+      return {
+        ok: true,
+        elapsed_ms: Date.now() - started,
+        targets
+      };
+    } catch (error) {
+      lastError = error;
+      await sleep(intervalMs);
+    }
+  }
+  return {
+    ok: false,
+    elapsed_ms: Date.now() - started,
+    error: lastError?.message || String(lastError || "Chrome debug port did not become ready")
+  };
+}
+
+export async function launchChromeDebugInstance({
+  host = DEFAULT_CHROME_HOST,
+  port = DEFAULT_CHROME_PORT,
+  url = "about:blank",
+  slowLive = false
+} = {}) {
+  if (!isLocalChromeHost(host)) {
+    throw new Error(`Cannot auto-launch Chrome for non-local debug host: ${host}`);
+  }
+  const chromePath = getChromeExecutable();
+  if (!chromePath) {
+    throw new Error("Chrome executable not found. Set BOSS_MCP_CHROME_PATH or BOSS_RECOMMEND_CHROME_PATH.");
+  }
+  const userDataDir = getBossChromeUserDataDir(port);
+  const args = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${userDataDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--new-window",
+    url
+  ];
+  const child = spawn(chromePath, args, {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: false
+  });
+  child.unref();
+  const readiness = await waitForChromeDebugPort({
+    host,
+    port,
+    timeoutMs: slowLive ? 30000 : 12000,
+    intervalMs: slowLive ? 700 : 300
+  });
+  if (!readiness.ok) {
+    throw new Error(`Chrome launched but DevTools port ${port} did not become reachable: ${readiness.error}`);
+  }
+  return {
+    launched: true,
+    chrome_path: chromePath,
+    user_data_dir: userDataDir,
+    port,
+    url,
+    readiness: {
+      elapsed_ms: readiness.elapsed_ms,
+      target_count: readiness.targets.length
+    }
+  };
+}
+
+export async function ensureChromeDebugPort({
+  host = DEFAULT_CHROME_HOST,
+  port = DEFAULT_CHROME_PORT,
+  url = "about:blank",
+  slowLive = false,
+  launchIfMissing = true
+} = {}) {
+  try {
+    const targets = await listChromeTargets({ host, port });
+    return {
+      launched: false,
+      reused: true,
+      port,
+      target_count: targets.length
+    };
+  } catch (error) {
+    if (!launchIfMissing || !isChromeDebugUnavailableError(error)) {
+      throw error;
+    }
+    return launchChromeDebugInstance({ host, port, url, slowLive });
+  }
+}
+
+export async function openChromeTarget({
+  host = DEFAULT_CHROME_HOST,
+  port = DEFAULT_CHROME_PORT,
+  url
+} = {}) {
+  const encodedUrl = encodeURIComponent(url || "about:blank");
+  const endpoint = `http://${host}:${port}/json/new?${encodedUrl}`;
+  const methods = ["PUT", "GET"];
+  let lastError = null;
+  for (const method of methods) {
+    try {
+      const response = await fetch(endpoint, { method });
+      if (response.ok) {
+        let payload = null;
+        try {
+          payload = await response.json();
+        } catch {}
+        return {
+          ok: true,
+          method,
+          target_id: payload?.id || null,
+          url: payload?.url || url || null
+        };
+      }
+      lastError = new Error(`DevTools /json/new returned ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  return {
+    ok: false,
+    error: lastError?.message || "Failed to open Chrome target"
+  };
+}
+
+export async function connectToChromeTargetOrOpen({
+  host = DEFAULT_CHROME_HOST,
+  port = DEFAULT_CHROME_PORT,
+  targetUrlIncludes,
+  targetPredicate,
+  fallbackTargetPredicate,
+  targetUrl,
+  allowNavigate = true,
+  slowLive = false,
+  launchIfMissing = true
+} = {}) {
+  let chrome = null;
+  if (allowNavigate && targetUrl) {
+    chrome = await ensureChromeDebugPort({
+      host,
+      port,
+      url: targetUrl,
+      slowLive,
+      launchIfMissing
+    });
+  }
+
+  try {
+    const session = await connectToChromeTarget({
+      host,
+      port,
+      targetUrlIncludes,
+      targetPredicate
+    });
+    return {
+      ...session,
+      chrome: {
+        ...(chrome || { launched: false, reused: true, port }),
+        target_created: false
+      }
+    };
+  } catch (primaryError) {
+    if (!allowNavigate) throw primaryError;
+
+    if (typeof fallbackTargetPredicate === "function") {
+      try {
+        const session = await connectToChromeTarget({
+          host,
+          port,
+          targetPredicate: fallbackTargetPredicate
+        });
+        return {
+          ...session,
+          chrome: {
+            ...(chrome || { launched: false, reused: true, port }),
+            target_created: false,
+            fallback_target: true
+          }
+        };
+      } catch {}
+    }
+
+    let openAttempt = null;
+    if (targetUrl) {
+      openAttempt = await openChromeTarget({ host, port, url: targetUrl });
+      if (openAttempt.ok) {
+        const session = await connectToChromeTarget({
+          host,
+          port,
+          targetPredicate: (target) => (
+            (openAttempt.target_id && target?.id === openAttempt.target_id)
+            || String(target?.url || "").includes(targetUrlIncludes || targetUrl)
+            || (targetUrl.includes("zhipin.com") && String(target?.url || "").includes("zhipin.com"))
+          )
+        });
+        return {
+          ...session,
+          chrome: {
+            ...(chrome || { launched: false, reused: true, port }),
+            target_created: true,
+            open_attempt: openAttempt
+          }
+        };
+      }
+    }
+
+    const session = await connectToChromeTarget({
+      host,
+      port,
+      targetPredicate: (target) => target?.type === "page"
+    });
+    return {
+      ...session,
+      chrome: {
+        ...(chrome || { launched: false, reused: true, port }),
+        target_created: false,
+        open_attempt: openAttempt,
+        fallback_any_page: true
+      }
+    };
+  }
+}
+
 export function createGuardedCdpClient(client, { methodLog = [] } = {}) {
   return new Proxy(client, {
     get(target, property, receiver) {

package/src/domains/recommend/run-service.js

@@ -332,7 +332,7 @@ export async function runRecommendWorkflow({
   fallbackPageScope = "recommend",
   filter = {},
   maxCandidates = 5,
-  detailLimit = 0,
+  detailLimit,
   closeDetail = true,
   delayMs = 0,
   cardTimeoutMs = 10000,
@@ -362,7 +362,7 @@ export async function runRecommendWorkflow({
   const normalizedFallbackPageScope = normalizeRecommendPageScope(fallbackPageScope) || "recommend";
   const postActionEnabled = normalizedPostAction !== "none";
   const limit = Math.max(1, Number(maxCandidates) || 1);
-  const detailCountLimit = Math.max(0, Number(detailLimit) || 0);
+  const detailCountLimit = detailLimit == null ? limit : Math.max(0, Number(detailLimit) || 0);
   const effectiveDetailLimit = postActionEnabled ? limit : detailCountLimit;
   const networkRecorder = effectiveDetailLimit > 0
     ? createRecommendDetailNetworkRecorder(client)
@@ -785,7 +785,7 @@ export function createRecommendRunService({
     fallbackPageScope = "recommend",
     filter = {},
     maxCandidates = 5,
-    detailLimit = 0,
+    detailLimit,
     closeDetail = true,
     delayMs = 0,
     cardTimeoutMs = 10000,
@@ -814,6 +814,8 @@ export function createRecommendRunService({
     const normalizedPostAction = normalizeRecommendPostAction(postAction) || "none";
     const requestedPageScope = normalizeRecommendPageScope(pageScope) || "recommend";
     const normalizedFallbackPageScope = normalizeRecommendPageScope(fallbackPageScope) || "recommend";
+    const candidateLimit = Math.max(1, Number(maxCandidates) || 1);
+    const normalizedDetailLimit = detailLimit == null ? candidateLimit : Math.max(0, Number(detailLimit) || 0);
     return manager.startRun({
       name,
       context: {
@@ -825,7 +827,7 @@ export function createRecommendRunService({
         fallback_page_scope: normalizedFallbackPageScope,
         filter: normalizedFilter,
         max_candidates: maxCandidates,
-        detail_limit: detailLimit,
+        detail_limit: normalizedDetailLimit,
         close_detail: closeDetail,
         cv_acquisition_mode: cvAcquisitionMode,
         max_image_pages: maxImagePages,
@@ -846,7 +848,7 @@ export function createRecommendRunService({
       },
       progress: {
         card_count: 0,
-        target_count: Math.max(1, Number(maxCandidates) || 1),
+        target_count: candidateLimit,
         processed: 0,
         screened: 0,
         detail_opened: 0,
@@ -864,7 +866,7 @@ export function createRecommendRunService({
         fallbackPageScope: normalizedFallbackPageScope,
         filter: normalizedFilter,
         maxCandidates,
-        detailLimit,
+        detailLimit: normalizedDetailLimit,
         closeDetail,
         delayMs,
         cardTimeoutMs,

package/src/index.js

@@ -540,7 +540,11 @@ function createRunInputSchema() {
       detail_limit: {
         type: "integer",
         minimum: 0,
-        description: "打开详情的人数上限；默认 0，0 表示只用卡片信息"
+        description: "打开详情/CV 的人数上限；默认跟随 target_count/max_candidates。生产筛选不应传 0；只有 allow_card_only_screening=true 时才会接受 0 作为调试卡片-only 模式"
+      },
+      allow_card_only_screening: {
+        type: "boolean",
+        description: "高级调试开关；默认 false。只有显式为 true 时，recommend 才会尊重 detail_limit=0 并只用卡片信息筛选"
       },
       delay_ms: {
         type: "integer",

package/src/recommend-mcp.js

@@ -4,8 +4,13 @@ import process from "node:process";
 import {
   assertNoForbiddenCdpCalls,
   bringPageToFront,
-  connectToChromeTarget,
+  connectToChromeTargetOrOpen,
+  createBossLoginRequiredError,
+  detectBossLoginState,
   enableDomains,
+  getMainFrameUrl,
+  isBossLoginUrl,
+  waitForMainFrameUrl,
   sleep
 } from "./core/browser/index.js";
 import {
@@ -75,6 +80,15 @@ function parseNonNegativeInteger(raw, fallback) {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
 }
 
+function resolveRecommendDetailLimit(args = {}, normalized = {}) {
+  const fallback = parsePositiveInteger(normalized.targetCount, 5);
+  const requested = parseNonNegativeInteger(args.detail_limit, fallback);
+  if (requested === 0 && args.allow_card_only_screening !== true) {
+    return fallback;
+  }
+  return requested;
+}
+
 function methodSummary(methodLog = []) {
   const summary = {};
   for (const entry of methodLog || []) {
@@ -517,27 +531,36 @@ export async function listRecommendJobsTool({ workspaceRoot = "", args = {} } =
         host,
         port,
         target_url: session.navigation?.url || session.target?.url || RECOMMEND_TARGET_URL,
-        target_id: session.target?.id || null
+        target_id: session.target?.id || null,
+        auto_launch: session.chrome || null
       },
       method_summary: methodSummary(session.methodLog || []),
       method_log: session.methodLog || []
     };
   } catch (error) {
     const methodLog = session?.methodLog || [];
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       stage: "recommend_job_list",
       cdp_only: true,
       runtime_evaluate_used: methodLog.some((entry) => String(entry?.method || entry).startsWith("Runtime.")),
       error: {
-        code: "RECOMMEND_JOB_LIST_FAILED",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "RECOMMEND_JOB_LIST_FAILED",
         message: error?.message || "Failed to read recommend job list",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || RECOMMEND_TARGET_URL,
+        chrome: error?.chrome || null,
         retryable: true
       },
       chrome: {
         host,
         port,
-        target_url: targetUrlIncludes
+        target_url: targetUrlIncludes,
+        auto_launch: error?.chrome || session?.chrome || null
       },
       method_summary: methodSummary(methodLog),
       method_log: methodLog
@@ -576,6 +599,14 @@ async function waitForHealthyRecommend(client, config, {
   const started = Date.now();
   let lastCheck = null;
   while (Date.now() - started <= timeoutMs) {
+    const loginDetection = await detectBossLoginState(client).catch(() => null);
+    if (loginDetection?.requires_login) {
+      return {
+        status: "login_required",
+        summary: "Boss login is required",
+        loginDetection
+      };
+    }
     const roots = await resolveRecommendSelfHealRoots(client, config);
     lastCheck = await runSelfHealCheck({
       client,
@@ -601,24 +632,18 @@ async function connectRecommendChromeSession({
   allowNavigate = true,
   slowLive = false
 } = {}) {
-  let session;
-  try {
-    session = await connectToChromeTarget({
-      host,
-      port,
-      targetUrlIncludes
-    });
-  } catch (error) {
-    if (!allowNavigate) throw error;
-    session = await connectToChromeTarget({
-      host,
-      port,
-      targetPredicate: (target) => (
-        target?.type === "page"
-        && String(target?.url || "").includes("zhipin.com/web/chat")
-      )
-    });
-  }
+  const session = await connectToChromeTargetOrOpen({
+    host,
+    port,
+    targetUrlIncludes,
+    targetUrl: RECOMMEND_TARGET_URL,
+    allowNavigate,
+    slowLive,
+    fallbackTargetPredicate: (target) => (
+      target?.type === "page"
+      && String(target?.url || "").includes("zhipin.com")
+    )
+  });
 
   const { client, target } = session;
   await enableDomains(client, ["Page", "DOM", "Input", "Network", "Accessibility"]);
@@ -635,12 +660,56 @@ async function connectRecommendChromeSession({
   if (allowNavigate && shouldNavigateToRecommend(targetUrl)) {
     await client.Page.navigate({ url: RECOMMEND_TARGET_URL });
     const settleMs = slowLive ? 12000 : 5000;
-    await sleep(settleMs);
+    const waited = await waitForMainFrameUrl(
+      client,
+      (url) => isBossLoginUrl(url) || !shouldNavigateToRecommend(url),
+      { timeoutMs: settleMs, intervalMs: 500 }
+    );
+    navigation = {
+      navigated: true,
+      url: RECOMMEND_TARGET_URL,
+      settle_ms: settleMs,
+      observed_url: waited.url || null,
+      observed_url_ok: waited.ok
+    };
+  }
+  let currentUrl = await getMainFrameUrl(client).catch(() => navigation.url || targetUrl);
+  if (allowNavigate && shouldNavigateToRecommend(currentUrl) && !isBossLoginUrl(currentUrl)) {
+    await client.Page.navigate({ url: RECOMMEND_TARGET_URL });
+    const settleMs = slowLive ? 12000 : 5000;
+    const waited = await waitForMainFrameUrl(
+      client,
+      (url) => isBossLoginUrl(url) || !shouldNavigateToRecommend(url),
+      { timeoutMs: settleMs, intervalMs: 500 }
+    );
     navigation = {
       navigated: true,
       url: RECOMMEND_TARGET_URL,
-      settle_ms: settleMs
+      settle_ms: settleMs,
+      observed_url: waited.url || null,
+      observed_url_ok: waited.ok,
+      reason: "observed_url_mismatch"
     };
+    currentUrl = await getMainFrameUrl(client).catch(() => waited.url || currentUrl);
+  }
+  const loginDetection = await detectBossLoginState(client, { currentUrl }).catch(() => ({
+    requires_login: isBossLoginUrl(currentUrl),
+    reason: "login_detection_failed",
+    current_url: currentUrl
+  }));
+  if (loginDetection.requires_login) {
+    await session.close?.();
+    throw createBossLoginRequiredError({
+      domain: "recommend",
+      currentUrl: loginDetection.current_url || currentUrl,
+      targetUrl: RECOMMEND_TARGET_URL,
+      loginDetection,
+      chrome: session.chrome || null
+    });
+  }
+  if (shouldNavigateToRecommend(currentUrl)) {
+    await session.close?.();
+    throw new Error(`Boss recommend page did not navigate to ${RECOMMEND_TARGET_URL}; current URL: ${currentUrl || "unknown"}`);
   }
 
   const selfHealConfig = buildRecommendSelfHealConfig();
@@ -648,7 +717,33 @@ async function connectRecommendChromeSession({
     timeoutMs: slowLive ? 180000 : 90000,
     intervalMs: slowLive ? 1200 : 800
   });
+  if (health?.loginDetection?.requires_login) {
+    await session.close?.();
+    throw createBossLoginRequiredError({
+      domain: "recommend",
+      currentUrl: health.loginDetection.current_url || currentUrl,
+      targetUrl: RECOMMEND_TARGET_URL,
+      loginDetection: health.loginDetection,
+      chrome: session.chrome || null
+    });
+  }
   if (!health || health.status !== HEALTH_STATUS.HEALTHY) {
+    const latestUrl = await getMainFrameUrl(client).catch(() => currentUrl);
+    const latestLoginDetection = await detectBossLoginState(client, { currentUrl: latestUrl }).catch(() => ({
+      requires_login: isBossLoginUrl(latestUrl),
+      reason: "login_detection_failed",
+      current_url: latestUrl
+    }));
+    if (latestLoginDetection.requires_login) {
+      await session.close?.();
+      throw createBossLoginRequiredError({
+        domain: "recommend",
+        currentUrl: latestLoginDetection.current_url || latestUrl,
+        targetUrl: RECOMMEND_TARGET_URL,
+        loginDetection: latestLoginDetection,
+        chrome: session.chrome || null
+      });
+    }
     throw new Error(`Boss recommend page is not healthy: ${health?.status || "missing"}`);
   }
 
@@ -867,7 +962,7 @@ function getRunOptions(args, parsed, normalized, session) {
     fallbackPageScope: "recommend",
     filter: normalized.filter,
     maxCandidates: normalized.targetCount,
-    detailLimit: parseNonNegativeInteger(args.detail_limit, 0),
+    detailLimit: resolveRecommendDetailLimit(args, normalized),
     closeDetail: true,
     delayMs: parseNonNegativeInteger(args.delay_ms, 0),
     cardTimeoutMs: slowLive ? 180000 : 90000,
@@ -955,13 +1050,21 @@ async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = ""
       slowLive: normalized.slowLive
     });
   } catch (error) {
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       error: {
-        code: "BOSS_RECOMMEND_PAGE_NOT_READY",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "BOSS_RECOMMEND_PAGE_NOT_READY",
         message: error?.message || "Boss recommend page is not ready",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        chrome: error?.chrome || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || RECOMMEND_TARGET_URL,
         retryable: true
-      }
+      },
+      chrome: error?.chrome || null
     };
   }
 
@@ -991,7 +1094,8 @@ async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = ""
       host: normalized.host,
       port: normalized.port,
       target_url: session.navigation?.url || session.target?.url || RECOMMEND_TARGET_URL,
-      target_id: session.target?.id || null
+      target_id: session.target?.id || null,
+      auto_launch: session.chrome || null
     },
     health: session.health || null
   });

package/src/recruit-mcp.js

@@ -4,8 +4,13 @@ import path from "node:path";
 import {
   assertNoForbiddenCdpCalls,
   bringPageToFront,
-  connectToChromeTarget,
+  connectToChromeTargetOrOpen,
+  createBossLoginRequiredError,
+  detectBossLoginState,
   enableDomains,
+  getMainFrameUrl,
+  isBossLoginUrl,
+  waitForMainFrameUrl,
   sleep
 } from "./core/browser/index.js";
 import {
@@ -586,6 +591,32 @@ function attachMethodEvidence(payload, runId) {
   };
 }
 
+async function waitForRecruitSearchControlsOrLogin(client, {
+  timeoutMs = 90000,
+  intervalMs = 300
+} = {}) {
+  const started = Date.now();
+  let lastControls = null;
+  while (Date.now() - started <= timeoutMs) {
+    const loginDetection = await detectBossLoginState(client).catch(() => null);
+    if (loginDetection?.requires_login) {
+      return {
+        ok: false,
+        reason: "login_required",
+        loginDetection
+      };
+    }
+    const remainingMs = Math.max(1, timeoutMs - (Date.now() - started));
+    lastControls = await waitForRecruitSearchControls(client, {
+      timeoutMs: Math.min(remainingMs, 1500),
+      intervalMs
+    });
+    if (lastControls.ok) return lastControls;
+    await sleep(intervalMs);
+  }
+  return lastControls || { ok: false, reason: "timeout" };
+}
+
 async function connectRecruitChromeSession({
   host = DEFAULT_RECRUIT_HOST,
   port = DEFAULT_RECRUIT_PORT,
@@ -593,24 +624,18 @@ async function connectRecruitChromeSession({
   allowNavigate = true,
   slowLive = false
 } = {}) {
-  let session;
-  try {
-    session = await connectToChromeTarget({
-      host,
-      port,
-      targetUrlIncludes
-    });
-  } catch (error) {
-    if (!allowNavigate) throw error;
-    session = await connectToChromeTarget({
-      host,
-      port,
-      targetPredicate: (target) => (
-        target?.type === "page"
-        && String(target?.url || "").includes("zhipin.com/web/chat")
-      )
-    });
-  }
+  const session = await connectToChromeTargetOrOpen({
+    host,
+    port,
+    targetUrlIncludes,
+    targetUrl: RECRUIT_TARGET_URL,
+    allowNavigate,
+    slowLive,
+    fallbackTargetPredicate: (target) => (
+      target?.type === "page"
+      && String(target?.url || "").includes("zhipin.com")
+    )
+  });
 
   const { client, target } = session;
   await enableDomains(client, ["Page", "DOM", "Input", "Network", "Accessibility"]);
@@ -620,21 +645,102 @@ async function connectRecruitChromeSession({
   await bringPageToFront(client);
 
   const targetUrl = String(target?.url || "");
+  let navigation = {
+    navigated: false,
+    url: targetUrl
+  };
   if (allowNavigate && !targetUrl.includes(targetUrlIncludes)) {
     await client.Page.navigate({ url: RECRUIT_TARGET_URL });
-    await sleep(slowLive ? 8000 : 3000);
+    const settleMs = slowLive ? 8000 : 3000;
+    const waited = await waitForMainFrameUrl(
+      client,
+      (url) => isBossLoginUrl(url) || String(url || "").includes(RECRUIT_TARGET_URL),
+      { timeoutMs: settleMs, intervalMs: 500 }
+    );
+    navigation = {
+      navigated: true,
+      url: RECRUIT_TARGET_URL,
+      settle_ms: settleMs,
+      observed_url: waited.url || null,
+      observed_url_ok: waited.ok
+    };
+  }
+  let currentUrl = await getMainFrameUrl(client).catch(() => targetUrl);
+  if (allowNavigate && !String(currentUrl || "").includes(RECRUIT_TARGET_URL) && !isBossLoginUrl(currentUrl)) {
+    await client.Page.navigate({ url: RECRUIT_TARGET_URL });
+    const settleMs = slowLive ? 8000 : 3000;
+    const waited = await waitForMainFrameUrl(
+      client,
+      (url) => isBossLoginUrl(url) || String(url || "").includes(RECRUIT_TARGET_URL),
+      { timeoutMs: settleMs, intervalMs: 500 }
+    );
+    navigation = {
+      navigated: true,
+      url: RECRUIT_TARGET_URL,
+      settle_ms: settleMs,
+      observed_url: waited.url || null,
+      observed_url_ok: waited.ok,
+      reason: "observed_url_mismatch"
+    };
+    currentUrl = await getMainFrameUrl(client).catch(() => waited.url || currentUrl);
+  }
+  const loginDetection = await detectBossLoginState(client, { currentUrl }).catch(() => ({
+    requires_login: isBossLoginUrl(currentUrl),
+    reason: "login_detection_failed",
+    current_url: currentUrl
+  }));
+  if (loginDetection.requires_login) {
+    await session.close?.();
+    throw createBossLoginRequiredError({
+      domain: "search",
+      currentUrl: loginDetection.current_url || currentUrl,
+      targetUrl: RECRUIT_TARGET_URL,
+      loginDetection,
+      chrome: session.chrome || null
+    });
+  }
+  if (!String(currentUrl || "").includes(RECRUIT_TARGET_URL)) {
+    await session.close?.();
+    throw new Error(`Boss search page did not navigate to ${RECRUIT_TARGET_URL}; current URL: ${currentUrl || "unknown"}`);
   }
 
-  const controls = await waitForRecruitSearchControls(client, {
+  const controls = await waitForRecruitSearchControlsOrLogin(client, {
     timeoutMs: slowLive ? 180000 : 90000,
     intervalMs: 300
   });
+  if (controls.loginDetection?.requires_login) {
+    await session.close?.();
+    throw createBossLoginRequiredError({
+      domain: "search",
+      currentUrl: controls.loginDetection.current_url || currentUrl,
+      targetUrl: RECRUIT_TARGET_URL,
+      loginDetection: controls.loginDetection,
+      chrome: session.chrome || null
+    });
+  }
   if (!controls.ok) {
+    const latestUrl = await getMainFrameUrl(client).catch(() => currentUrl);
+    const latestLoginDetection = await detectBossLoginState(client, { currentUrl: latestUrl }).catch(() => ({
+      requires_login: isBossLoginUrl(latestUrl),
+      reason: "login_detection_failed",
+      current_url: latestUrl
+    }));
+    if (latestLoginDetection.requires_login) {
+      await session.close?.();
+      throw createBossLoginRequiredError({
+        domain: "search",
+        currentUrl: latestLoginDetection.current_url || latestUrl,
+        targetUrl: RECRUIT_TARGET_URL,
+        loginDetection: latestLoginDetection,
+        chrome: session.chrome || null
+      });
+    }
     throw new Error("Boss recruit search page did not expose ready search controls");
   }
 
   return {
     ...session,
+    navigation,
     controls
   };
 }
@@ -712,13 +818,21 @@ async function startRecruitPipelineRunInternal(args = {}, { workspaceRoot = "" }
       slowLive: args.slow_live === true
     });
   } catch (error) {
+    const loginRequired = error?.code === "BOSS_LOGIN_REQUIRED";
     return {
       status: "FAILED",
       error: {
-        code: "BOSS_SEARCH_PAGE_NOT_READY",
+        code: loginRequired ? "BOSS_LOGIN_REQUIRED" : "BOSS_SEARCH_PAGE_NOT_READY",
         message: error?.message || "Boss recruit search page is not ready",
+        requires_login: Boolean(error?.requires_login),
+        login_url: error?.login_url || null,
+        login_detection: error?.login_detection || null,
+        chrome: error?.chrome || null,
+        current_url: error?.current_url || null,
+        target_url: error?.target_url || RECRUIT_TARGET_URL,
         retryable: true
-      }
+      },
+      chrome: error?.chrome || null
     };
   }
 
@@ -747,7 +861,8 @@ async function startRecruitPipelineRunInternal(args = {}, { workspaceRoot = "" }
       host: normalizeText(args.host) || DEFAULT_RECRUIT_HOST,
       port: parsePositiveInteger(args.port, DEFAULT_RECRUIT_PORT),
       target_url: session.target?.url || RECRUIT_TARGET_URL,
-      target_id: session.target?.id || null
+      target_id: session.target?.id || null,
+      auto_launch: session.chrome || null
     },
     parsed
   });