@reconcrap/boss-recommend-mcp 2.0.45 → 2.0.46

package/package.json

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

package/src/core/browser/index.js

@@ -42,6 +42,9 @@ const BOSS_LOGIN_DOM_SELECTORS = [
 ];
 const HUMAN_INTERACTION_CONFIG = new WeakMap();
 const DEFAULT_HUMAN_BEHAVIOR_PROFILE = "paced_with_rests";
+export const DETERMINISTIC_CLICK_OPTIONS = Object.freeze({
+  humanRestEnabled: false
+});
 const HUMAN_BEHAVIOR_PROFILES = Object.freeze({
   baseline: Object.freeze({
     enabled: false,
@@ -1293,8 +1296,12 @@ export async function clickNodeCenter(client, nodeId, {
   const clickPointTarget = humanClickPointEnabled
     ? resolveHumanClickPointForBox(box, mergedHumanInteraction)
     : { ...box.center, mode: "center" };
-  await clickPoint(client, clickPointTarget.x, clickPointTarget.y, clickOptions);
-  return box;
+  const clickResult = await clickPoint(client, clickPointTarget.x, clickPointTarget.y, clickOptions);
+  return {
+    ...box,
+    click_target: clickPointTarget,
+    click_result: clickResult
+  };
 }
 
 export async function pressKey(client, key, {

package/src/domains/chat/detail.js

@@ -2,6 +2,7 @@ import {
   clearFocusedInput,
   clickNodeCenter,
   clickPoint,
+  DETERMINISTIC_CLICK_OPTIONS,
   getFrameDocumentNodeId,
   getAttributesMap,
   getNodeBox,
@@ -572,9 +573,12 @@ export async function selectChatPrimaryLabel(client, {
     }
     if (matched) {
       if (matched.center) {
-        await clickPoint(client, matched.center.x, matched.center.y);
+        await clickPoint(client, matched.center.x, matched.center.y, DETERMINISTIC_CLICK_OPTIONS);
       } else {
-        await clickNodeCenter(client, matched.node_id, { scrollIntoView: true });
+        await clickNodeCenter(client, matched.node_id, {
+          ...DETERMINISTIC_CLICK_OPTIONS,
+          scrollIntoView: true
+        });
       }
       if (settleMs > 0) await sleep(settleMs);
       return {
@@ -633,9 +637,12 @@ export async function selectChatMessageFilter(client, {
     const matched = candidates[0];
     if (matched) {
       if (matched.center) {
-        await clickPoint(client, matched.center.x, matched.center.y);
+        await clickPoint(client, matched.center.x, matched.center.y, DETERMINISTIC_CLICK_OPTIONS);
       } else {
-        await clickNodeCenter(client, matched.node_id, { scrollIntoView: true });
+        await clickNodeCenter(client, matched.node_id, {
+          ...DETERMINISTIC_CLICK_OPTIONS,
+          scrollIntoView: true
+        });
       }
       if (settleMs > 0) await sleep(settleMs);
       return {
@@ -1499,7 +1506,7 @@ export async function closeChatResumeModal(client, {
     const closeTarget = await findVisibleTarget(client, rootState.roots, CHAT_RESUME_CLOSE_SELECTORS);
     if (closeTarget) {
       try {
-        await clickPoint(client, closeTarget.center.x, closeTarget.center.y);
+        await clickPoint(client, closeTarget.center.x, closeTarget.center.y, DETERMINISTIC_CLICK_OPTIONS);
         attempts.push({
           mode: "close-selector",
           selector: closeTarget.selector,

package/src/domains/chat/jobs.js

@@ -1,6 +1,7 @@
 import {
   clickNodeCenter,
   clickPoint,
+  DETERMINISTIC_CLICK_OPTIONS,
   getAttributesMap,
   getNodeBox,
   getOuterHTML,
@@ -240,7 +241,7 @@ async function clickFirstVisible(client, rootNodeId, selectors = []) {
       try {
         const box = await getNodeBox(client, nodeId);
         if (box.rect.width <= 2 || box.rect.height <= 2) continue;
-        await clickPoint(client, box.center.x, box.center.y);
+        await clickPoint(client, box.center.x, box.center.y, DETERMINISTIC_CLICK_OPTIONS);
         return {
           clicked: true,
           selector,
@@ -265,6 +266,7 @@ async function openChatJobDropdown(client, rootNodeId, {
   const started = Date.now();
   const triedPoints = new Set();
   const attempts = [];
+  const initialClose = await closeChatJobDropdownQuietly(client, rootNodeId, Math.min(settleMs, 300));
   for (const selector of CHAT_JOB_TRIGGER_SELECTORS) {
     const currentRootNodeId = await freshTopRootNodeId(client, rootNodeId);
     const nodeIds = await safeQuerySelectorAll(client, currentRootNodeId, selector);
@@ -283,7 +285,7 @@ async function openChatJobDropdown(client, rootNodeId, {
           const pointKey = `${nodeId}:${Math.round(x)}:${Math.round(y)}`;
           if (triedPoints.has(pointKey)) continue;
           triedPoints.add(pointKey);
-          await clickPoint(client, x, y);
+          await clickPoint(client, x, y, DETERMINISTIC_CLICK_OPTIONS);
           if (settleMs > 0) await sleep(Math.min(settleMs, 800));
           const remaining = Math.max(300, timeoutMs - (Date.now() - started));
           const optionsResult = await waitForChatJobOptions(client, currentRootNodeId, {
@@ -298,7 +300,8 @@ async function openChatJobDropdown(client, rootNodeId, {
             node_id: nodeId,
             point: pointName,
             center: { x, y },
-            visible_option_count: visibleCount
+            visible_option_count: visibleCount,
+            initial_close: initialClose
           };
           attempts.push(attempt);
           if (visibleCount > 0) {
@@ -548,9 +551,10 @@ export async function selectChatJob(client, rootNodeId, {
   }
 
   if (matched.center) {
-    await clickPoint(client, matched.center.x, matched.center.y);
+    await clickPoint(client, matched.center.x, matched.center.y, DETERMINISTIC_CLICK_OPTIONS);
   } else {
     await clickNodeCenter(client, matched.node_id, {
+      ...DETERMINISTIC_CLICK_OPTIONS,
       scrollIntoView: true
     });
   }

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

@@ -754,6 +754,7 @@ export async function runChatWorkflow({
   let requestSatisfiedCount = 0;
   let requestSkippedCount = 0;
   let contextSetup = {};
+  let contextRecoveryAttempts = 0;
   let lastHumanEvent = null;
 
   function recordHumanEvent(event = null) {
@@ -826,6 +827,7 @@ export async function runChatWorkflow({
     forceRefresh = false
   } = {}) {
     runControl.setPhase("chat:recover_shell");
+    contextRecoveryAttempts += 1;
     const shellRecovery = await recoverChatShell(client, {
       targetUrl,
       timeoutMs: readyTimeoutMs,
@@ -866,6 +868,7 @@ export async function runChatWorkflow({
     const recovery = {
       reason,
       total_refresh: Boolean(forceRefresh),
+      attempt: contextRecoveryAttempts,
       shell: shellRecovery,
       candidate_list: candidateList,
       counters
@@ -917,6 +920,7 @@ export async function runChatWorkflow({
       request_skipped: 0,
       unique_seen: compactInfiniteListState(listState).seen_count,
       scroll_count: compactInfiniteListState(listState).scroll_count,
+      context_recoveries: contextRecoveryAttempts,
       list_end_reason: listEndReason,
       viewport_checks: viewportGuard.getStats().checks,
       viewport_recoveries: viewportGuard.getStats().recoveries,
@@ -960,6 +964,7 @@ export async function runChatWorkflow({
       requested: requestedCount,
       request_satisfied: requestSatisfiedCount,
       request_skipped: requestSkippedCount,
+      context_recoveries: contextRecoveryAttempts,
       results
     };
   }
@@ -981,6 +986,7 @@ export async function runChatWorkflow({
     screening_mode: normalizedScreeningMode,
     unique_seen: compactInfiniteListState(listState).seen_count,
     scroll_count: 0,
+    context_recoveries: contextRecoveryAttempts,
     viewport_checks: viewportGuard.getStats().checks,
     viewport_recoveries: viewportGuard.getStats().recoveries
   });
@@ -1015,6 +1021,18 @@ export async function runChatWorkflow({
         const error = new Error(`CHAT_JOB_GUARD_FAILED: requested=${job}; selected=${jobGuard.selected_label || "unknown"}; reason=${jobGuard.reason || "unknown"}`);
         error.code = "CHAT_JOB_GUARD_FAILED";
         error.chat_job_guard = compactChatJobGuard(jobGuard);
+        runControl.checkpoint({
+          chat_context_step: "job_guard_failed",
+          job_guard: compactChatJobGuard(jobGuard),
+          error: {
+            code: error.code,
+            message: error.message
+          }
+        });
+        if (contextRecoveryAttempts < 2) {
+          await recoverAndReapplyChatContext("job_guard_failed", error, { forceRefresh: true });
+          continue;
+        }
         throw error;
       }
       if (!jobGuard.already_current) {
@@ -1688,6 +1706,7 @@ export async function runChatWorkflow({
       request_skipped: requestSkippedCount,
       unique_seen: compactInfiniteListState(listState).seen_count,
       scroll_count: compactInfiniteListState(listState).scroll_count,
+      context_recoveries: contextRecoveryAttempts,
       list_end_reason: listEndReason || null,
       viewport_checks: viewportGuard.getStats().checks,
       viewport_recoveries: viewportGuard.getStats().recoveries,
@@ -1739,6 +1758,7 @@ export async function runChatWorkflow({
           human_rest_count: humanRestController.getState().rest_count,
           human_rest_ms: humanRestController.getState().total_rest_ms,
           human_rest_last: restResult,
+          context_recoveries: contextRecoveryAttempts,
           last_human_event: lastHumanEvent
         });
       }
@@ -1781,6 +1801,7 @@ export async function runChatWorkflow({
     requested: requestedCount,
     request_satisfied: requestSatisfiedCount,
     request_skipped: requestSkippedCount,
+    context_recoveries: contextRecoveryAttempts,
     results
   };
 }
@@ -1893,6 +1914,7 @@ export function createChatRunService({
         requested: 0,
         request_satisfied: 0,
         request_skipped: 0,
+        context_recoveries: 0,
         human_behavior_enabled: effectiveHumanBehavior.enabled,
         human_behavior_profile: effectiveHumanBehavior.profile,
         human_rest_enabled: effectiveHumanRestEnabled,

package/src/domains/recommend/detail.js

@@ -1,7 +1,8 @@
-import {
-  clickNodeCenter,
-  clickPoint,
-  getFrameDocumentNodeId,
+import {
+  clickNodeCenter,
+  clickPoint,
+  DETERMINISTIC_CLICK_OPTIONS,
+  getFrameDocumentNodeId,
   getNodeBox,
   getOuterHTML,
   pressKey,
@@ -507,11 +508,11 @@ export async function closeRecommendDetail(client, {
     const closeTarget = await findVisibleCloseTarget(client, rootState.roots, DETAIL_CLOSE_SELECTORS);
     if (closeTarget) {
       try {
-        if (closeTarget.center) {
-          await clickPoint(client, closeTarget.center.x, closeTarget.center.y);
-        } else {
-          await clickNodeCenter(client, closeTarget.node_id);
-        }
+        if (closeTarget.center) {
+          await clickPoint(client, closeTarget.center.x, closeTarget.center.y, DETERMINISTIC_CLICK_OPTIONS);
+        } else {
+          await clickNodeCenter(client, closeTarget.node_id, DETERMINISTIC_CLICK_OPTIONS);
+        }
         attempts.push({
           mode: "close-selector",
           selector: closeTarget.selector,
@@ -732,7 +733,7 @@ async function clickOutsideRecommendDetail(client, detailState) {
       root: target?.root || null
     };
   }
-  await clickPoint(client, point.x, point.y);
+  await clickPoint(client, point.x, point.y, DETERMINISTIC_CLICK_OPTIONS);
   return {
     clicked: true,
     mode: "outside-modal-click",

package/src/domains/recommend/filters.js

@@ -1,6 +1,7 @@
 import {
   clickNodeCenter,
   countSelectors,
+  DETERMINISTIC_CLICK_OPTIONS,
   findFirstNode,
   getAttributesMap,
   getNodeBox,
@@ -117,7 +118,7 @@ export async function ensureFilterPanelClosed(client, frameNodeId, triggerNodeId
   attempts.push("Escape");
 
   if (await getFilterPanelCount(client, frameNodeId) > 0 && triggerNodeId) {
-    await clickNodeCenter(client, triggerNodeId);
+    await clickNodeCenter(client, triggerNodeId, DETERMINISTIC_CLICK_OPTIONS);
     await sleep(500);
     attempts.push("filter-trigger-toggle");
   }
@@ -125,6 +126,19 @@ export async function ensureFilterPanelClosed(client, frameNodeId, triggerNodeId
   return attempts;
 }
 
+async function dismissRecommendControlOverlays(client, settleMs = 250) {
+  if (typeof client?.Input?.dispatchKeyEvent !== "function") {
+    return ["Escape-unavailable"];
+  }
+  await pressKey(client, "Escape", {
+    code: "Escape",
+    windowsVirtualKeyCode: 27,
+    nativeVirtualKeyCode: 27
+  });
+  if (settleMs > 0) await sleep(settleMs);
+  return ["Escape"];
+}
+
 async function findFilterTriggerCandidates(client, frameNodeId) {
   const candidates = [];
   const seen = new Set();
@@ -147,6 +161,7 @@ export async function openFilterPanel(client, frameNodeId) {
     throw new Error("Recommend filter trigger was not found");
   }
 
+  const preOpenDismissalAttempts = await dismissRecommendControlOverlays(client);
   const existingPanelNodeId = await waitForSelector(client, frameNodeId, RECOMMEND_FILTER_SELECTORS.panel, {
     timeoutMs: 300,
     intervalMs: 100
@@ -157,7 +172,7 @@ export async function openFilterPanel(client, frameNodeId) {
       trigger: triggerCandidates[0],
       trigger_box: triggerBox,
       panel_node_id: existingPanelNodeId,
-      initial_close_attempts: [],
+      initial_close_attempts: preOpenDismissalAttempts,
       already_open: true
     };
   }
@@ -169,11 +184,13 @@ export async function openFilterPanel(client, frameNodeId) {
     triggerCandidates = await findFilterTriggerCandidates(client, frameNodeId);
     for (const trigger of triggerCandidates) {
       const triggerBox = await getNodeBox(client, trigger.nodeId);
-      await clickNodeCenter(client, trigger.nodeId);
+      const clickBox = await clickNodeCenter(client, trigger.nodeId, DETERMINISTIC_CLICK_OPTIONS);
       attempts.push({
         selector: trigger.selector,
         node_id: trigger.nodeId,
-        center: triggerBox.center
+        center: triggerBox.center,
+        click_target: clickBox.click_target,
+        click_result: clickBox.click_result
       });
       const panelNodeId = await waitForSelector(client, frameNodeId, RECOMMEND_FILTER_SELECTORS.panel, {
         timeoutMs: 2500,
@@ -184,7 +201,10 @@ export async function openFilterPanel(client, frameNodeId) {
           trigger,
           trigger_box: triggerBox,
           panel_node_id: panelNodeId,
-          initial_close_attempts: closeAttempts,
+          initial_close_attempts: [
+            ...preOpenDismissalAttempts,
+            ...closeAttempts
+          ],
           open_attempts: attempts
         };
       }
@@ -236,7 +256,7 @@ async function clickFirstAvailableNode(client, nodeIds) {
   const errors = [];
   for (const nodeId of nodeIds) {
     try {
-      const box = await clickNodeCenter(client, nodeId);
+      const box = await clickNodeCenter(client, nodeId, DETERMINISTIC_CLICK_OPTIONS);
       return {
         clicked: true,
         node_id: nodeId,
@@ -301,7 +321,10 @@ export async function selectFirstSafeFilterOption(client, frameNodeId, {
     throw new Error("No safe non-active recommend filter option was found");
   }
 
-  const box = await clickNodeCenter(client, selected.node_id, { scrollIntoView: true });
+  const box = await clickNodeCenter(client, selected.node_id, {
+    ...DETERMINISTIC_CLICK_OPTIONS,
+    scrollIntoView: true
+  });
   await sleep(300);
 
   return {
@@ -338,7 +361,10 @@ export async function selectFilterOption(client, frameNodeId, {
     throw new Error(`No matching recommend filter option was found for ${target}`);
   }
 
-  const box = await clickNodeCenter(client, selected.node_id, { scrollIntoView: true });
+  const box = await clickNodeCenter(client, selected.node_id, {
+    ...DETERMINISTIC_CLICK_OPTIONS,
+    scrollIntoView: true
+  });
   await sleep(300);
 
   return {
@@ -409,7 +435,10 @@ export async function selectFilterOptions(client, frameNodeId, {
       continue;
     }
 
-    const box = await clickNodeCenter(client, selected.node_id, { scrollIntoView: true });
+    const box = await clickNodeCenter(client, selected.node_id, {
+      ...DETERMINISTIC_CLICK_OPTIONS,
+      scrollIntoView: true
+    });
     selectedOptions.push({
       group: selected.group,
       label: selected.label,

package/src/domains/recommend/jobs.js

@@ -1,12 +1,12 @@
 import {
   clickNodeCenter,
+  DETERMINISTIC_CLICK_OPTIONS,
   getAttributesMap,
   getNodeBox,
   getOuterHTML,
   pressKey,
   querySelectorAll,
-  sleep,
-  waitForSelector
+  sleep
 } from "../../core/browser/index.js";
 import {
   htmlToText,
@@ -108,7 +108,9 @@ export async function waitForRecommendJobTrigger(client, frameNodeId, {
 export async function openRecommendJobDropdown(client, frameNodeId, {
   timeoutMs = 4000,
   triggerTimeoutMs = Math.max(8000, timeoutMs),
-  triggerIntervalMs = 250
+  triggerIntervalMs = 250,
+  dismissBeforeOpen = true,
+  maxAttempts = 3
 } = {}) {
   const trigger = await waitForRecommendJobTrigger(client, frameNodeId, {
     timeoutMs: triggerTimeoutMs,
@@ -118,36 +120,72 @@ export async function openRecommendJobDropdown(client, frameNodeId, {
     throw new Error("Recommend job trigger was not found");
   }
 
-  let optionNodeId = await waitForSelector(client, frameNodeId, RECOMMEND_JOB_SELECTORS.option, {
+  const alreadyOpen = await waitForVisibleRecommendJobOptions(client, frameNodeId, {
     timeoutMs: 300,
     intervalMs: 100
   });
-  if (optionNodeId) {
-    const options = await listRecommendJobOptions(client, frameNodeId, { openDropdown: false });
-    if (options.some((option) => option.visible)) {
+  if (alreadyOpen.visible_options.length) {
+    return {
+      opened: true,
+      already_open: true,
+      trigger,
+      options: alreadyOpen.options
+    };
+  }
+
+  const attempts = [];
+  const attemptLimit = Math.max(1, Math.floor(Number(maxAttempts) || 1));
+  if (dismissBeforeOpen) {
+    await closeRecommendJobDropdown(client);
+  }
+  for (let attempt = 1; attempt <= attemptLimit; attempt += 1) {
+    if (attempt > 1) await closeRecommendJobDropdown(client);
+    const triggerBox = await clickNodeCenter(client, trigger.node_id, DETERMINISTIC_CLICK_OPTIONS);
+    const opened = await waitForVisibleRecommendJobOptions(client, frameNodeId, {
+      timeoutMs,
+      intervalMs: 200
+    });
+    attempts.push({
+      attempt,
+      trigger_box: triggerBox,
+      option_count: opened.options.length,
+      visible_option_count: opened.visible_options.length
+    });
+    if (opened.visible_options.length) {
       return {
         opened: true,
-        already_open: true,
+        already_open: false,
         trigger,
-        options
+        options: opened.options,
+        attempts
       };
     }
   }
+  const error = new Error("Recommend job dropdown did not expose visible options after trigger click");
+  error.job_dropdown_attempts = attempts;
+  throw error;
+}
 
-  await clickNodeCenter(client, trigger.node_id);
-  optionNodeId = await waitForSelector(client, frameNodeId, RECOMMEND_JOB_SELECTORS.option, {
-    timeoutMs,
-    intervalMs: 200
-  });
-  if (!optionNodeId) {
-    throw new Error("Recommend job dropdown did not mount options after trigger click");
+async function waitForVisibleRecommendJobOptions(client, frameNodeId, {
+  timeoutMs = 4000,
+  intervalMs = 200
+} = {}) {
+  const started = Date.now();
+  let lastOptions = [];
+  while (Date.now() - started <= timeoutMs) {
+    lastOptions = await listRecommendJobOptions(client, frameNodeId, { openDropdown: false });
+    const visibleOptions = lastOptions.filter((option) => option.visible);
+    if (visibleOptions.length) {
+      return {
+        options: lastOptions,
+        visible_options: visibleOptions
+      };
+    }
+    await sleep(intervalMs);
   }
-  const options = await listRecommendJobOptions(client, frameNodeId, { openDropdown: false });
   return {
-    opened: true,
-    already_open: false,
-    trigger,
-    options
+    options: lastOptions,
+    visible_options: []
   };
 }
 
@@ -174,12 +212,22 @@ export async function listRecommendJobOptions(client, frameNodeId, {
 }
 
 export async function closeRecommendJobDropdown(client) {
+  if (typeof client?.Input?.dispatchKeyEvent !== "function") {
+    return {
+      ok: false,
+      reason: "dispatch_key_unavailable"
+    };
+  }
   await pressKey(client, "Escape", {
     code: "Escape",
     windowsVirtualKeyCode: 27,
     nativeVirtualKeyCode: 27
   });
   await sleep(300);
+  return {
+    ok: true,
+    reason: "escape"
+  };
 }
 
 export async function selectRecommendJob(client, frameNodeId, {
@@ -205,11 +253,16 @@ export async function selectRecommendJob(client, frameNodeId, {
     ? opened.options
     : await listRecommendJobOptions(client, frameNodeId, { openDropdown: false });
   const visibleOptions = options.filter((option) => option.visible);
-  const match = visibleOptions.find((option) => jobLabelMatches(option.label, target))
-    || options.find((option) => jobLabelMatches(option.label, target));
+  const hiddenMatches = options.filter((option) => !option.visible && jobLabelMatches(option.label, target));
+  const match = visibleOptions.find((option) => jobLabelMatches(option.label, target));
 
   if (!match) {
     await closeRecommendJobDropdown(client);
+    if (hiddenMatches.length) {
+      const error = new Error(`Matched recommend job has no visible clickable option: ${hiddenMatches[0].label}`);
+      error.hidden_job_matches = hiddenMatches.map(compactJobOption);
+      throw error;
+    }
     return {
       requested: target,
       selected: false,
@@ -234,7 +287,7 @@ export async function selectRecommendJob(client, frameNodeId, {
     throw new Error(`Matched recommend job has no clickable center: ${match.label}`);
   }
 
-  const clickedBox = await clickNodeCenter(client, match.node_id);
+  const clickedBox = await clickNodeCenter(client, match.node_id, DETERMINISTIC_CLICK_OPTIONS);
   if (settleMs > 0) await sleep(settleMs);
   return {
     requested: target,

package/src/domains/recommend/refresh.js

@@ -103,7 +103,7 @@ function compactFilterReapplyError(error) {
 
 export function isRetryableRecommendJobSelectionError(error) {
   const message = String(error?.message || error || "");
-  return /Recommend job trigger was not found|Recommend job dropdown did not mount options/i.test(message);
+  return /Recommend job trigger was not found|Recommend job dropdown did not mount options|Recommend job dropdown did not expose visible options|Matched recommend job has no clickable center|Matched recommend job has no visible clickable option/i.test(message);
 }
 
 function compactJobSelectionAttempt({

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

@@ -449,15 +449,43 @@ function compactError(error, fallbackCode = "RECOMMEND_RUN_ERROR") {
   if (error.close_result) {
     result.close_result = compactCloseResult(error.close_result);
   }
+  if (error.refresh_attempt) {
+    result.refresh_attempt = error.refresh_attempt;
+  }
+  if (error.list_end_reason) {
+    result.list_end_reason = error.list_end_reason;
+  }
+  if (error.target_count != null) {
+    result.target_count = error.target_count;
+  }
+  if (error.passed_count != null) {
+    result.passed_count = error.passed_count;
+  }
   return result;
 }
 
-function createRecommendCloseFailureError(closeResult) {
-  const error = new Error(closeResult?.reason || "Recommend detail did not close before recovery");
-  error.code = "DETAIL_CLOSE_FAILED";
-  error.close_result = closeResult || null;
-  return error;
-}
+function createRecommendCloseFailureError(closeResult) {
+  const error = new Error(closeResult?.reason || "Recommend detail did not close before recovery");
+  error.code = "DETAIL_CLOSE_FAILED";
+  error.close_result = closeResult || null;
+  return error;
+}
+
+function createRecommendRefreshFailureError(refreshAttempt, {
+  listEndReason = "",
+  targetCount = 0,
+  passedCount = 0
+} = {}) {
+  const reason = refreshAttempt?.reason || "refresh_failed";
+  const detail = refreshAttempt?.error ? `: ${refreshAttempt.error}` : "";
+  const error = new Error(`Recommend refresh failed before target was reached (${reason}${detail})`);
+  error.code = "RECOMMEND_END_REFRESH_FAILED";
+  error.refresh_attempt = refreshAttempt || null;
+  error.list_end_reason = listEndReason || null;
+  error.target_count = targetCount;
+  error.passed_count = passedCount;
+  return error;
+}
 
 export function isRecoverableImageCaptureError(error) {
   const code = String(error?.code || "");
@@ -960,9 +988,9 @@ export async function runRecommendWorkflow({
           refresh_forced_recent_not_view: true,
           list_end_reason: listEndReason
         });
-        if (refreshResult.ok) {
-          rootState = refreshResult.root_state || await getRecommendRoots(client);
-          rootState = await ensureRecommendViewport(rootState, "refresh_after");
+        if (refreshResult.ok) {
+          rootState = refreshResult.root_state || await getRecommendRoots(client);
+          rootState = await ensureRecommendViewport(rootState, "refresh_after");
           cardNodeIds = await waitForRecommendCardNodeIds(client, rootState.iframe.documentNodeId, {
             timeoutMs: cardTimeoutMs,
             intervalMs: 300
@@ -976,12 +1004,17 @@ export async function runRecommendWorkflow({
               forced_recent_not_view: true
             }
           });
-          listEndReason = "";
-          continue;
-        }
-      }
-      break;
-    }
+          listEndReason = "";
+          continue;
+        }
+        throw createRecommendRefreshFailureError(compactRefresh, {
+          listEndReason,
+          targetCount: targetPassCount,
+          passedCount: countPassedResults(results)
+        });
+      }
+      break;
+    }
 
     const index = results.length;
     let cardNodeId = nextCandidateResult.item.node_id;

package/src/domains/recommend/scopes.js

@@ -1,5 +1,6 @@
 import {
   clickNodeCenter,
+  DETERMINISTIC_CLICK_OPTIONS,
   getAttributesMap,
   getNodeBox,
   getOuterHTML,
@@ -220,7 +221,7 @@ export async function selectRecommendPageScope(client, frameNodeId, {
     };
   }
 
-  const clickBox = await clickNodeCenter(client, targetTab.node_id);
+  const clickBox = await clickNodeCenter(client, targetTab.node_id, DETERMINISTIC_CLICK_OPTIONS);
   if (settleMs > 0) await sleep(settleMs);
   const after = await waitForRecommendPageScope(client, frameNodeId, effectiveScope, {
     timeoutMs,

package/src/domains/recruit/detail.js

@@ -1,6 +1,7 @@
 import {
   clickNodeCenter,
   clickPoint,
+  DETERMINISTIC_CLICK_OPTIONS,
   getFrameDocumentNodeId,
   getNodeBox,
   getOuterHTML,
@@ -305,9 +306,9 @@ export async function closeRecruitDetail(client, {
     if (closeTarget) {
       try {
         if (closeTarget.center) {
-          await clickPoint(client, closeTarget.center.x, closeTarget.center.y);
+          await clickPoint(client, closeTarget.center.x, closeTarget.center.y, DETERMINISTIC_CLICK_OPTIONS);
         } else {
-          await clickNodeCenter(client, closeTarget.node_id);
+          await clickNodeCenter(client, closeTarget.node_id, DETERMINISTIC_CLICK_OPTIONS);
         }
         attempts.push({
           mode: "close-selector",

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

@@ -147,10 +147,23 @@ function compactRefreshAttempt(refreshAttempt) {
 
 function compactError(error, fallbackCode = "RECRUIT_RUN_ERROR") {
   if (!error) return null;
-  return {
+  const result = {
     code: error.code || fallbackCode,
     message: error.message || String(error)
   };
+  if (error.refresh_attempt) {
+    result.refresh_attempt = error.refresh_attempt;
+  }
+  if (error.list_end_reason) {
+    result.list_end_reason = error.list_end_reason;
+  }
+  if (error.target_count != null) {
+    result.target_count = error.target_count;
+  }
+  if (error.processed_count != null) {
+    result.processed_count = error.processed_count;
+  }
+  return result;
 }
 
 function createRecruitCloseFailureError(closeResult) {
@@ -160,6 +173,34 @@ function createRecruitCloseFailureError(closeResult) {
   return error;
 }
 
+function createRecruitRefreshFailureError(refreshAttempt, {
+  listEndReason = "",
+  targetCount = 0,
+  processedCount = 0
+} = {}) {
+  const reason = refreshAttempt?.application?.post_search_state?.ok === false
+    ? "search_result_not_ready"
+    : refreshAttempt?.application?.post_search_state?.counts?.candidate_card === 0
+      ? "no_cards_after_refresh"
+      : "refresh_failed";
+  const error = new Error(`Recruit/search refresh failed before target was reached (${reason})`);
+  error.code = "RECRUIT_END_REFRESH_FAILED";
+  error.refresh_attempt = refreshAttempt || null;
+  error.list_end_reason = listEndReason || null;
+  error.target_count = targetCount;
+  error.processed_count = processedCount;
+  return error;
+}
+
+function isRefreshableListStall(reason = "") {
+  return new Set([
+    "stable_visible_signature",
+    "max_scrolls_exhausted",
+    "scroll_failed",
+    "scroll_anchor_unavailable"
+  ]).has(String(reason || ""));
+}
+
 export function isStaleRecruitNodeError(error) {
   const message = String(error?.message || error || "");
   return /Could not find node with given id|No node with given id|Node is detached|Cannot find node/i.test(message);
@@ -610,7 +651,7 @@ export async function runRecruitWorkflow({
     if (!nextCandidateResult.ok) {
       listEndReason = nextCandidateResult.reason || "list_exhausted";
       if (
-        nextCandidateResult.end_reached
+        (nextCandidateResult.end_reached || isRefreshableListStall(nextCandidateResult.reason))
         && refreshOnEnd
         && results.length < limit
         && refreshRounds < Math.max(0, Number(maxRefreshRounds) || 0)
@@ -658,6 +699,11 @@ export async function runRecruitWorkflow({
           listEndReason = "";
           continue;
         }
+        throw createRecruitRefreshFailureError(compactRefresh, {
+          listEndReason,
+          targetCount: limit,
+          processedCount: results.length
+        });
       }
       break;
     }

package/src/domains/recruit/search.js

@@ -2,6 +2,7 @@ import {
   clearFocusedInput,
   clickNodeCenter,
   countSelectors,
+  DETERMINISTIC_CLICK_OPTIONS,
   describeNode,
   findFirstNode,
   getAttributesMap,
@@ -315,7 +316,10 @@ async function clickFirstNodeBySelectors(client, rootNodeId, selectors, {
     throw new Error(`Recruit search node was not found for selectors: ${selectors.join(", ")}`);
   }
   try {
-    const box = await clickNodeCenter(client, found.nodeId, { scrollIntoView });
+    const box = await clickNodeCenter(client, found.nodeId, {
+      ...DETERMINISTIC_CLICK_OPTIONS,
+      scrollIntoView
+    });
     await sleep(250);
     return {
       clicked: true,
@@ -337,6 +341,26 @@ async function clickFirstNodeBySelectors(client, rootNodeId, selectors, {
   }
 }
 
+async function dismissRecruitSearchOverlays(client, settleMs = 250) {
+  if (typeof client?.Input?.dispatchKeyEvent !== "function") {
+    return {
+      method: "Escape",
+      skipped: true,
+      reason: "dispatch_key_unavailable"
+    };
+  }
+  await pressKey(client, "Escape", {
+    code: "Escape",
+    windowsVirtualKeyCode: 27,
+    nativeVirtualKeyCode: 27
+  });
+  if (settleMs > 0) await sleep(settleMs);
+  return {
+    method: "Escape",
+    settle_ms: settleMs
+  };
+}
+
 export async function getRecruitSearchCounts(client, frameNodeId) {
   return countSelectors(client, frameNodeId, {
     keyword_input: RECRUIT_SEARCH_SELECTORS.keywordInput.join(", "),
@@ -495,7 +519,10 @@ export async function setRecruitJobTitle(client, frameNodeId, jobTitle, {
   }
   let box = null;
   if (!lookup.candidate.active) {
-    box = await clickNodeCenter(client, lookup.candidate.node_id, { scrollIntoView: true });
+    box = await clickNodeCenter(client, lookup.candidate.node_id, {
+      ...DETERMINISTIC_CLICK_OPTIONS,
+      scrollIntoView: true
+    });
     await sleep(500);
   }
   return {
@@ -527,7 +554,10 @@ export async function setRecruitDegree(client, frameNodeId, degree) {
   if (!candidate) {
     throw new Error(`Recruit degree option was not found: ${degreeLabel}`);
   }
-  const box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+  const box = await clickNodeCenter(client, candidate.node_id, {
+    ...DETERMINISTIC_CLICK_OPTIONS,
+    scrollIntoView: true
+  });
   await sleep(350);
   return {
     applied: true,
@@ -573,7 +603,10 @@ export async function setRecruitDegrees(client, frameNodeId, degrees = []) {
 
     let box = null;
     if (!candidate.active) {
-      box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+      box = await clickNodeCenter(client, candidate.node_id, {
+        ...DETERMINISTIC_CLICK_OPTIONS,
+        scrollIntoView: true
+      });
       await sleep(350);
     }
     selected.push({
@@ -638,7 +671,10 @@ export async function setRecruitSchools(client, frameNodeId, schools = []) {
 
     let box = null;
     if (!clickableActive) {
-      box = await clickNodeCenter(client, clickable.node_id, { scrollIntoView: true });
+      box = await clickNodeCenter(client, clickable.node_id, {
+        ...DETERMINISTIC_CLICK_OPTIONS,
+        scrollIntoView: true
+      });
       await sleep(350);
     }
 
@@ -683,7 +719,10 @@ export async function setRecruitRecentViewedFilter(client, frameNodeId, enabled)
 
   let box = null;
   if (candidate.active !== enabled) {
-    box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+    box = await clickNodeCenter(client, candidate.node_id, {
+      ...DETERMINISTIC_CLICK_OPTIONS,
+      scrollIntoView: true
+    });
     await sleep(900);
   }
 
@@ -722,7 +761,10 @@ async function selectRecruitNationalCityThroughPicker(client, frameNodeId, {
     { match: "exact", timeoutMs: Math.min(optionTimeoutMs, 6000) }
   );
   if (categoryLookup.candidate) {
-    const box = await clickNodeCenter(client, categoryLookup.candidate.node_id, { scrollIntoView: true });
+    const box = await clickNodeCenter(client, categoryLookup.candidate.node_id, {
+      ...DETERMINISTIC_CLICK_OPTIONS,
+      scrollIntoView: true
+    });
     await sleep(400);
     path.push({
       label: "城市",
@@ -765,7 +807,10 @@ async function selectRecruitNationalCityThroughPicker(client, frameNodeId, {
       discovered_options: summarizeTextCandidates(popularLookup.candidates)
     };
   }
-  const popularBox = await clickNodeCenter(client, popularLookup.candidate.node_id, { scrollIntoView: true });
+  const popularBox = await clickNodeCenter(client, popularLookup.candidate.node_id, {
+    ...DETERMINISTIC_CLICK_OPTIONS,
+    scrollIntoView: true
+  });
   await sleep(400);
   path.push({
     label: "热门",
@@ -801,7 +846,10 @@ async function selectRecruitNationalCityThroughPicker(client, frameNodeId, {
     };
   }
 
-  const nationalBox = await clickNodeCenter(client, nationalLookup.candidate.node_id, { scrollIntoView: true });
+  const nationalBox = await clickNodeCenter(client, nationalLookup.candidate.node_id, {
+    ...DETERMINISTIC_CLICK_OPTIONS,
+    scrollIntoView: true
+  });
   await sleep(700);
   path.push({
     label: "全国",
@@ -953,7 +1001,10 @@ export async function setRecruitCity(client, frameNodeId, city, {
     };
   }
 
-  const box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+  const box = await clickNodeCenter(client, candidate.node_id, {
+    ...DETERMINISTIC_CLICK_OPTIONS,
+    scrollIntoView: true
+  });
   await sleep(600);
   return {
     applied: true,
@@ -1057,6 +1108,7 @@ export async function applyRecruitSearchParams(client, {
   if (!controls.ok) {
     throw new Error(`Recruit search controls were not ready after navigation; counts=${JSON.stringify(controls.counts || {})}`);
   }
+  const overlayDismissal = await dismissRecruitSearchOverlays(client);
   const initialRoots = await getRecruitRoots(client);
   let frameNodeId = initialRoots.iframe.documentNodeId;
   const initialFrameNodeId = frameNodeId;
@@ -1137,6 +1189,7 @@ export async function applyRecruitSearchParams(client, {
     applied: true,
     search_params: normalizedSearchParams,
     reset,
+    overlay_dismissal: overlayDismissal,
     controls,
     initial_iframe: {
       selector: initialRoots.iframe.selector,