@reconcrap/boss-recommend-mcp 2.1.9 → 2.1.10

package/README.md

@@ -82,12 +82,13 @@ curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/ma
 MCP 工具：
 
 - `list_recommend_jobs`（只读读取推荐页岗位下拉框，返回可直接用于 cron/一次性任务的 `job_names`）
-- `prepare_recommend_pipeline_run`（只校验完整 payload；不启动筛选。若现在运行，返回 `READY + cron_ready=true` 后继续调用 `run_recommend` / `start_recommend_pipeline_run`；只有定时任务才继续 schedule）
-- `schedule_recommend_pipeline_run`（创建 package-owned 定时任务；保存已 READY 的完整 payload，启动 detached scheduler，到点后直接调用 `start_recommend_pipeline_run`）
+- `run_recommend`（`start_recommend_pipeline_run` 的短别名；用户已经确认且要现在启动时优先调用）
+- `start_recommend_pipeline_run`（异步启动；先经过前置门禁，通过后返回 `ACCEPTED + run_id`）
+- `prepare_recommend_pipeline_run`（只校验完整 payload；不启动筛选。主要用于显式预检或定时任务前校验；若现在运行，READY 后继续调用 `run_recommend` / `start_recommend_pipeline_run`）
+- `schedule_recommend_pipeline_run`（只用于用户明确要求稍后/cron/定时；保存已 READY 的完整 payload，启动 detached scheduler，到点后直接调用 `start_recommend_pipeline_run`）
 - `get_recommend_scheduled_run`（查询 package-owned 定时任务；到点后会显示内层 `run_id` 和 run 快照）
-- `run_recommend`（`start_recommend_pipeline_run` 的短别名；适合 Trae/Trae-CN 在 prepare READY 后正式启动）
-- `start_recommend_pipeline_run`（异步启动；同样先经过前置门禁，通过后返回 run_id）
-- `get_recommend_pipeline_run`（轮询 run_id 状态）
+- `get_recommend_pipeline_run`（用已知 `run_id` 轮询状态）
+- `list_recommend_pipeline_runs`（只读列出最近 run 摘要并返回 `latest_run`；忘记 `run_id` 时用它恢复，不要读磁盘 JSON）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
 - `pause_recommend_pipeline_run`（请求暂停 run；会在当前候选人处理完成后进入 paused）
 - `resume_recommend_pipeline_run`（继续 paused run；沿用同 run_id 与同 CSV）
@@ -265,7 +266,7 @@ BOSS_RECOMMEND_MCP_CONFIG_TARGETS   # JSON 数组或系统 path 分隔路径列
 BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS  # JSON 数组或系统 path 分隔路径列表，指定额外 skills 根目录
 ```
 
-推荐运行入口是 MCP 工具 `run_recommend` / `start_recommend_pipeline_run`。在 Trae/Trae-CN 这类普通 MCP 宿主中，`prepare_recommend_pipeline_run` 返回 `READY + cron_ready=true` 后，若用户要现在运行，应继续调用 `run_recommend` 或 `start_recommend_pipeline_run`，不要改用 terminal/shell/run_command/CLI/manual JSON-RPC，也不要用短延迟 `schedule_recommend_pipeline_run` 冒充立即启动。`prepare` 能返回结果就证明该宿主已经可以调用本 MCP server。
+推荐运行入口是 MCP 工具 `run_recommend` / `start_recommend_pipeline_run`。在 Trae/Trae-CN 这类普通 MCP 宿主中，用户完成总确认并要求现在运行时，应直接调用 `run_recommend` 或 `start_recommend_pipeline_run`。`prepare_recommend_pipeline_run` 只做显式预检或定时任务前校验；如果已经调用过 prepare 且返回 `READY + cron_ready=true`，下一步仍然必须调用 `run_recommend` / `start_recommend_pipeline_run`，不要改用 terminal/shell/run_command/PowerShell/CLI/manual JSON-RPC，也不要用短延迟 `schedule_recommend_pipeline_run` 冒充立即启动。`prepare` 能返回结果就证明该宿主已经可以调用本 MCP server。
 
 只有宿主是 QClaw 这类真正 shell-only agent、没有把 MCP tools 暴露给模型、且当前会话从未成功调用过 `boss-recommend/prepare_recommend_pipeline_run` 时，才使用 CDP-only CLI fallback。CLI fallback 也必须显式传本次用户确认的 rest level：
 
@@ -477,10 +478,11 @@ Trae-CN / 长对话防循环建议：
 
 说明：
 
-- `run_recommend` 与 `start_recommend_pipeline_run` 是同一个异步 MCP 启动入口，但不会跳过同步确认流程。
-- `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 只做参数门禁；它不启动筛选。普通 MCP 宿主现在运行时，prepare READY 后继续调用 `run_recommend` / `start_recommend_pipeline_run`，不要改用 CLI fallback。
+- `run_recommend` 与 `start_recommend_pipeline_run` 是同一个异步 MCP 启动入口，但不会跳过同步确认流程；普通 MCP 宿主现在运行时优先直接调用它们。
+- `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 只做参数门禁；它不启动筛选。普通 MCP 宿主只有在显式预检或定时任务准备时才需要先调用 prepare；prepare READY 后继续调用 `run_recommend` / `start_recommend_pipeline_run`，不要改用 CLI fallback。
 - `prepare_recommend_pipeline_run` 的 READY 响应会带 `prepared_only=true`、`run_started=false`、`recommended_next_tool=start_recommend_pipeline_run`、`alternate_next_tool=run_recommend` 和 `next_action.do_not_call_prepare_again=true`；agent 应直接照这个字段继续下一步。
 - `schedule_recommend_pipeline_run` / `boss-recommend-mcp schedule-run` 是推荐页定时启动的唯一推荐路径；它创建真实 package-owned detached scheduler，并返回 `schedule_id`。
+- 如果忘记了 `run_id`，调用 `list_recommend_pipeline_runs` 获取 `latest_run.run_id`；不要用 PowerShell、`Get-Content`、terminal、CLI 或手动读取 `~/.boss-recommend-mcp/runs/*.json` 来恢复状态。
 - 定时心跳默认 120 秒一次；`updated_at` 仍会在阶段或进度变化时刷新。
 - 每个 run 会持久化到 `~/.boss-recommend-mcp/runs/<run_id>.json`（可通过 `BOSS_RECOMMEND_HOME` 覆盖）。
 - screen 阶段会持久化 checkpoint：`~/.boss-recommend-mcp/runs/<run_id>.checkpoint.json`。

package/package.json

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

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

@@ -18,6 +18,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - recommend 失败时（如 `JOB_TRIGGER_NOT_FOUND/NO_RECOMMEND_IFRAME/BOSS_LOGIN_REQUIRED`）禁止降级到 recruit；先修 recommend 页面就绪/登录态。
 
 - **Trae-CN / 原生 MCP 启动强制规则**
+  - 用户完成总确认并要求“现在启动”时，优先直接调用 `boss-recommend/run_recommend` 或 `boss-recommend/start_recommend_pipeline_run`；不要为了即时启动先调用 prepare。
   - 如果当前会话里已经成功调用过 `boss-recommend/prepare_recommend_pipeline_run`，说明 Trae-CN 已经具备原生 MCP tool call 能力；下一步必须继续调用 `boss-recommend/start_recommend_pipeline_run` 或 `boss-recommend/run_recommend`。
   - `prepare_recommend_pipeline_run` 返回 `READY` 只代表参数校验通过，不代表已经启动；严禁再次调用 prepare 试图启动。
   - 在 Trae-CN、Trae、Codex、Cursor、Claude Code 等普通 MCP 宿主中，严禁用 `run_command`、终端、PowerShell、`npx ... run --detached`、手写 `tools/call` JSON-RPC 或任何 CLI fallback 启动 recommend run。
@@ -100,8 +101,18 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 用途：当用户需要为 cron / 一次性自动任务提前填写完整参数时，先用它读取推荐页岗位下拉框的全部可用岗位名；默认会复用/自动打开本机 9222 Chrome 并导航到推荐页。
   - 输出：优先把 `job_names` 里的值作为后续 `overrides.job` / `confirmation.job_value`。
   - 限制：只读岗位列表，不启动筛选任务；若返回 `BOSS_LOGIN_REQUIRED`，必须让用户在自动打开的 Chrome 完成登录后重试，本次 cron 不得创建。
+- 主工具：`run_recommend` / `start_recommend_pipeline_run`
+  - 用途：用户完成最终总确认并要“现在启动”时调用；这是即时运行的首选入口，不需要先 prepare。
+  - 必填：`instruction`
+  - 关键输入：
+    - `confirmation`：新流程只需要 `{ "final_confirmed": true }`；旧版 `page_confirmed/page_value/.../job_confirmed/job_value` 仍兼容但不要主动制造逐项确认。
+    - `overrides`：`page_scope/school_tag/degree/gender/recent_not_view/criteria/job/target_count/post_action/max_greet_count`
+    - `human_behavior`：必须包含本次用户确认的 `restLevel`（例如 `{ "restLevel": "medium" }`）
+    - 不要传 `follow_up.chat`；该路径属于 legacy-only 行为
+  - 若返回 `ACCEPTED + run_id`：记录 `run_id` 并停止本轮，不自动轮询。
+  - 若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`：只追问 `pending_questions`。
 - 准备/门禁工具：`prepare_recommend_pipeline_run`
-  - 用途：只校验参数是否完整，不启动筛选任务。
+  - 用途：只校验参数是否完整，不启动筛选任务；主要用于用户明确要求预检，或 cron/稍后/定时启动前校验。
   - 要求：若用户要“现在启动”，返回 `status=READY` 且 `cron_ready=true` 后，下一步必须调用 MCP 工具 `run_recommend` 或 `start_recommend_pipeline_run`，禁止改用 terminal/shell/run_command/CLI/manual JSON-RPC。只有用户要“稍后/cron/定时启动”时，才继续创建定时任务。
   - READY 响应会带 `prepared_only=true`、`run_started=false`、`recommended_next_tool=start_recommend_pipeline_run`、`alternate_next_tool=run_recommend`、`next_action.do_not_call_prepare_again=true`、`agent_guidance.native_mcp_required_after_prepare=true`；必须照这些字段继续，不得再次调用 prepare。
   - 若返回 `NEED_INPUT` / `NEED_CONFIRMATION` / `FAILED`：继续补齐 `pending_questions` 或修复登录/页面/config；不得先创建 cron。
@@ -112,13 +123,10 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 成功标准：必须返回 `status=SCHEDULED`、`schedule_created=true`、`schedule_id`、`run_at`。只有这个返回后，才可以告诉用户定时任务已创建。
 - Cron 查询工具：`get_recommend_scheduled_run`
   - 用途：用户问“任务是否启动/进度”时，先查 `schedule_id`。若到点后已启动，会返回内层 `run_id` 和 run 快照。
-- 主工具：`run_recommend` / `start_recommend_pipeline_run`
-- 必填：`instruction`
-- 关键输入：
-  - `confirmation`：新流程只需要 `{ "final_confirmed": true }`；旧版 `page_confirmed/page_value/.../job_confirmed/job_value` 仍兼容但不要主动制造逐项确认。
-  - `overrides`：`page_scope/school_tag/degree/gender/recent_not_view/criteria/job/target_count/post_action/max_greet_count`
-  - `human_behavior`：必须包含本次用户确认的 `restLevel`（例如 `{ "restLevel": "medium" }`）
-  - 不要传 `follow_up.chat`；该路径属于 legacy-only 行为
+- 状态恢复工具：`list_recommend_pipeline_runs`
+  - 用途：忘记 `run_id` 或用户问“刚才那个任务怎么样”但上下文里没有 run_id 时调用；读取最近 run 摘要并返回 `latest_run`。
+  - 限制：只返回紧凑摘要，不包含大体积候选人 `results`；拿到 `latest_run.run_id` 后再用 `get_recommend_pipeline_run` / `cancel_recommend_pipeline_run`。
+  - 在 Trae-CN 中禁止用 `run_command`、PowerShell、`Get-Content`、CLI 或直接读取 `~/.boss-recommend-mcp/runs/*.json` 来恢复 run_id 或状态。
 
 最小策略：
 
@@ -164,6 +172,7 @@ npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <sched
 
 - 用户未明确要求“持续跟进”时，不自动 `sleep + get_recommend_pipeline_run`。
 - 用户要求查进度时，再用 `get_recommend_pipeline_run`。
+- 如果当前对话已经丢失 `run_id`，先调用 `list_recommend_pipeline_runs`，再用 `latest_run.run_id` 调用 `get_recommend_pipeline_run`；不要改用终端读 JSON。
 - **长任务轮询节奏（强制）**：
   - 推荐任务可能运行数小时，禁止高频轮询。
   - 默认最小轮询间隔为 **30 分钟**（除非用户明确要求更频繁）。

package/src/cli.js

@@ -24,8 +24,12 @@ import {
   resumeBossChatRunTool
 } from "./chat-mcp.js";
 import {
+  cancelRecommendPipelineRunTool,
+  getRecommendPipelineRunTool,
   listRecommendJobsTool,
+  pauseRecommendPipelineRunTool,
   prepareRecommendPipelineRunTool,
+  resumeRecommendPipelineRunTool,
   startRecommendPipelineRunTool
 } from "./recommend-mcp.js";
 import {
@@ -2971,6 +2975,33 @@ function scheduleStatusCli(options = {}) {
   }
 }
 
+function isTerminalRecommendCliState(state) {
+  return ["completed", "failed", "canceled"].includes(String(state || "").trim().toLowerCase());
+}
+
+async function monitorDetachedRecommendCliRunControls(runId) {
+  const normalizedRunId = String(runId || "").trim();
+  if (!normalizedRunId) return;
+  while (true) {
+    const payload = getRecommendPipelineRunTool({
+      args: {
+        run_id: normalizedRunId
+      }
+    });
+    const state = String(payload?.run?.state || payload?.run?.status || "").trim().toLowerCase();
+    if (isTerminalRecommendCliState(state)) return;
+    const control = payload?.run?.control || {};
+    if (control.cancel_requested === true) {
+      cancelRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    } else if (control.pause_requested === true && state === "running") {
+      pauseRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    } else if (control.pause_requested === false && state === "paused") {
+      resumeRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    }
+    await sleepMs(1000);
+  }
+}
+
 async function runPipelineOnce(options = {}) {
   const workspaceRoot = getWorkspaceRoot(options);
   const { args, port } = buildRecommendRunCliInput(options);
@@ -2987,11 +3018,13 @@ async function runPipelineOnce(options = {}) {
       workspace_root: workspaceRoot,
       port
     }
-  });
-  if (result.status !== "ACCEPTED") {
-    process.exitCode = 1;
-  }
-}
+  });
+  if (result.status !== "ACCEPTED") {
+    process.exitCode = 1;
+  } else if (process.env[detachedRecommendRunChildEnv] === "1") {
+    await monitorDetachedRecommendCliRunControls(result.run_id);
+  }
+}
 
 function buildRecommendJobListCliInput(options = {}) {
   const targetUrlIncludes = String(options["target-url-includes"] || options.target_url_includes || "").trim();

package/src/core/run/index.js

@@ -28,14 +28,24 @@ function createRunId(prefix = "run") {
   return `${prefix}_${Date.now().toString(36)}_${random}`;
 }
 
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
-function createDeferred() {
-  let resolve;
-  let reject;
-  const promise = new Promise((promiseResolve, promiseReject) => {
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function errorDiagnostic(error) {
+  if (!error) return null;
+  const diagnostic = {
+    name: error?.name || "Error",
+    message: error?.message || String(error)
+  };
+  if (error?.code) diagnostic.code = error.code;
+  return diagnostic;
+}
+
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((promiseResolve, promiseReject) => {
     resolve = promiseResolve;
     reject = promiseReject;
   });
@@ -188,23 +198,20 @@ export function createRunLifecycleManager({
           summary: summary || entry.run.summary
         });
       }
-    } catch (error) {
-      if (error instanceof RunCanceledError || entry.controller.signal.aborted || entry.cancelRequested) {
-        setStatus(entry, RUN_STATUS_CANCELED, {
-          completedAt: now(),
-          error: null
-        });
-        return;
-      }
-      setStatus(entry, RUN_STATUS_FAILED, {
-        completedAt: now(),
-        error: {
-          name: error?.name || "Error",
-          message: error?.message || String(error)
-        }
-      });
-    }
-  }
+    } catch (error) {
+      if (error instanceof RunCanceledError || entry.controller.signal.aborted || entry.cancelRequested) {
+        setStatus(entry, RUN_STATUS_CANCELED, {
+          completedAt: now(),
+          error: error instanceof RunCanceledError ? null : errorDiagnostic(error)
+        });
+        return;
+      }
+      setStatus(entry, RUN_STATUS_FAILED, {
+        completedAt: now(),
+        error: errorDiagnostic(error)
+      });
+    }
+  }
 
   function startRun({ runId: requestedRunId = "", name, pid = process.pid, context = {}, progress = {}, checkpoint = {}, task }) {
     if (typeof task !== "function") {

package/src/index.js

@@ -101,6 +101,7 @@ const TOOL_GET_SCHEDULED_RUN = "get_recommend_scheduled_run";
 const TOOL_RUN_RECOMMEND = "run_recommend";
 const TOOL_START_RUN = "start_recommend_pipeline_run";
 const TOOL_GET_RUN = "get_recommend_pipeline_run";
+const TOOL_LIST_RUNS = "list_recommend_pipeline_runs";
 const TOOL_CANCEL_RUN = "cancel_recommend_pipeline_run";
 const TOOL_PAUSE_RUN = "pause_recommend_pipeline_run";
 const TOOL_RESUME_RUN = "resume_recommend_pipeline_run";
@@ -371,6 +372,68 @@ function getRunArtifacts(runId) {
   };
 }
 
+function isShutdownLikeError(error = {}) {
+  const text = normalizeText([
+    error?.code || "",
+    error?.message || error || ""
+  ].join(" "));
+  return /socket hang up|ECONNREFUSED|ECONNRESET|WebSocket is not open|Target closed|Session closed|Connection closed|RUN_PROCESS_EXITED|DETACHED_WORKER|RUN_WORKER/i.test(text);
+}
+
+function buildCanceledResultFromExisting(existing = {}, errorPayload = null, message = "流水线已取消。") {
+  const previousResult = existing.result && typeof existing.result === "object" ? existing.result : {};
+  const previousError = previousResult.error || existing.error || errorPayload || null;
+  return {
+    ...previousResult,
+    status: "CANCELED",
+    completion_reason: "canceled_by_user",
+    error: {
+      code: "PIPELINE_CANCELED",
+      message,
+      retryable: true,
+      shutdown_error: previousError || undefined
+    }
+  };
+}
+
+function finalizeRawRunStateAsCanceled(runId, existing = {}, {
+  errorPayload = null,
+  message = "流水线已取消。"
+} = {}) {
+  const normalizedRunId = normalizeText(runId);
+  if (!normalizedRunId) return null;
+  const now = new Date().toISOString();
+  const current = existing && typeof existing === "object" ? existing : {};
+  const result = buildCanceledResultFromExisting(current, errorPayload, message);
+  return writeRawRunState(normalizedRunId, {
+    ...current,
+    run_id: normalizedRunId,
+    mode: current.mode || RUN_MODE_ASYNC,
+    state: RUN_STATE_CANCELED,
+    status: RUN_STATE_CANCELED,
+    stage: current.stage || RUN_STAGE_PREFLIGHT,
+    started_at: current.started_at || now,
+    updated_at: now,
+    heartbeat_at: now,
+    completed_at: current.completed_at || now,
+    pid: Number.isInteger(current.pid) && current.pid > 0 ? current.pid : process.pid,
+    progress: current.progress || {},
+    last_message: message,
+    context: current.context || {},
+    control: {
+      ...(current.control || {}),
+      pause_requested: false,
+      pause_requested_at: null,
+      pause_requested_by: null,
+      cancel_requested: false
+    },
+    resume: current.resume || {},
+    artifacts: current.artifacts || undefined,
+    error: result.error,
+    result
+  });
+}
+
 function writeRawRunState(runId, payload) {
   const artifacts = getRunArtifacts(runId);
   fs.mkdirSync(path.dirname(artifacts.run_state_path), { recursive: true });
@@ -390,6 +453,110 @@ function readRawRunState(runId) {
   }
 }
 
+function getRunSortTime(run = {}, fallbackMs = 0) {
+  for (const key of ["updated_at", "heartbeat_at", "completed_at", "started_at", "updatedAt", "completedAt", "startedAt"]) {
+    const ms = Date.parse(run?.[key] || "");
+    if (Number.isFinite(ms)) return ms;
+  }
+  return fallbackMs;
+}
+
+function compactRunForList(run = {}) {
+  const state = normalizeText(run.state || run.status);
+  const result = run.result && typeof run.result === "object" ? run.result : null;
+  const error = run.error || result?.error || null;
+  return {
+    run_id: normalizeText(run.run_id || run.runId),
+    state,
+    status: state,
+    stage: normalizeText(run.stage || run.phase),
+    mode: normalizeText(run.mode),
+    started_at: run.started_at || run.startedAt || null,
+    updated_at: run.updated_at || run.updatedAt || null,
+    heartbeat_at: run.heartbeat_at || null,
+    completed_at: run.completed_at || run.completedAt || null,
+    pid: Number.isInteger(run.pid) && run.pid > 0 ? run.pid : null,
+    progress: run.progress || {},
+    last_message: normalizeText(run.last_message || error?.message || ""),
+    control: {
+      pause_requested: run.control?.pause_requested === true,
+      cancel_requested: run.control?.cancel_requested === true
+    },
+    error: error ? {
+      code: normalizeText(error.code || ""),
+      message: normalizeText(error.message || error || "")
+    } : null,
+    result: result ? {
+      status: normalizeText(result.status || ""),
+      completion_reason: normalizeText(result.completion_reason || ""),
+      output_csv: normalizeText(result.output_csv || result.result?.output_csv || ""),
+      report_json: normalizeText(result.report_json || result.result?.report_json || ""),
+      checkpoint_path: normalizeText(result.checkpoint_path || result.result?.checkpoint_path || "")
+    } : null,
+    resume: {
+      checkpoint_path: normalizeText(run.resume?.checkpoint_path || ""),
+      output_csv: normalizeText(run.resume?.output_csv || ""),
+      worker_stdout_path: normalizeText(run.resume?.worker_stdout_path || ""),
+      worker_stderr_path: normalizeText(run.resume?.worker_stderr_path || "")
+    }
+  };
+}
+
+function normalizeRunStateFilter(args = {}) {
+  const rawStates = Array.isArray(args.states)
+    ? args.states
+    : args.state === undefined
+      ? []
+      : [args.state];
+  return new Set(rawStates.map((item) => normalizeText(item)).filter(Boolean));
+}
+
+function handleListRunsTool(args = {}) {
+  const limit = Math.max(1, Math.min(100, Number.parseInt(String(args.limit || 20), 10) || 20));
+  const stateFilter = normalizeRunStateFilter(args);
+  const runsDir = getRunsDir();
+  if (!fs.existsSync(runsDir)) {
+    return {
+      status: "OK",
+      runs: [],
+      latest_run: null,
+      count: 0,
+      total_matching: 0,
+      message: "No recommend run state directory exists yet."
+    };
+  }
+  const entries = fs.readdirSync(runsDir, { withFileTypes: true });
+  const runs = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json") || entry.name.endsWith(".checkpoint.json")) continue;
+    const filePath = path.join(runsDir, entry.name);
+    const runId = entry.name.replace(/\.json$/, "");
+    const raw = readRawRunState(runId);
+    if (!raw) continue;
+    const state = normalizeText(raw.state || raw.status);
+    if (stateFilter.size > 0 && !stateFilter.has(state)) continue;
+    const stat = fs.statSync(filePath);
+    runs.push({
+      sort_ms: getRunSortTime(raw, Number(stat.mtimeMs || 0)),
+      run: compactRunForList(raw)
+    });
+  }
+  runs.sort((a, b) => b.sort_ms - a.sort_ms);
+  const compacted = runs.slice(0, limit).map((item) => item.run);
+  return {
+    status: "OK",
+    runs: compacted,
+    latest_run: compacted[0] || null,
+    count: compacted.length,
+    total_matching: runs.length,
+    limit,
+    filters: {
+      states: Array.from(stateFilter)
+    },
+    message: "Use latest_run.run_id with get_recommend_pipeline_run, cancel_recommend_pipeline_run, pause_recommend_pipeline_run, or resume_recommend_pipeline_run. In Trae-CN, do not use terminal, PowerShell, CLI, or filesystem scraping to recover run status."
+  };
+}
+
 function patchRawRunState(runId, patch) {
   const current = readRawRunState(runId);
   if (!current) return null;
@@ -1134,18 +1301,18 @@ function createToolsSchema() {
       inputSchema: createListRecommendJobsInputSchema()
     },
     {
-      name: TOOL_PREPARE_RUN,
-      description: "只校验 Boss 推荐页流水线参数是否完整；不会启动筛选任务。若用户要现在运行，返回 READY/cron_ready=true 后必须继续调用本 MCP server 的 run_recommend 或 start_recommend_pipeline_run；只有定时/稍后运行才调用 schedule_recommend_pipeline_run。prepare 能返回结果就证明原生 MCP 可用，禁止改用 terminal/shell/run_command/CLI/manual JSON-RPC。",
+      name: TOOL_RUN_RECOMMEND,
+      description: "立即通过原生 MCP 启动 Boss 推荐页筛选。它是 start_recommend_pipeline_run 的短别名；用户已经确认并要现在启动时，优先调用本工具，不需要先调用 prepare_recommend_pipeline_run。必须作为 MCP tool call 调用，禁止通过 terminal/shell/run_command/PowerShell/CLI/manual JSON-RPC 代替，也不要用 schedule_recommend_pipeline_run 冒充立即启动。",
       inputSchema: createRunInputSchema()
     },
     {
-      name: TOOL_RUN_RECOMMEND,
-      description: "立即通过原生 MCP 启动 Boss 推荐页筛选。它是 start_recommend_pipeline_run 的短别名，适合 Trae/Trae-CN 等代理在 prepare_recommend_pipeline_run 返回 READY 后继续正式运行；必须作为 MCP tool call 调用，禁止通过 terminal/shell/run_command/CLI/manual JSON-RPC 代替，也不要用 schedule_recommend_pipeline_run 冒充立即启动。",
+      name: TOOL_START_RUN,
+      description: "立即通过原生 MCP 异步启动 Boss 推荐页流水线（含同步门禁预检）。用户已经确认并要现在启动时，优先调用本工具或 run_recommend，不需要先调用 prepare_recommend_pipeline_run。必须作为 MCP tool call 调用，禁止通过 terminal/shell/run_command/PowerShell/CLI/manual JSON-RPC 代替，也不要用 schedule_recommend_pipeline_run 冒充立即启动。",
       inputSchema: createRunInputSchema()
     },
     {
-      name: TOOL_START_RUN,
-      description: "立即通过原生 MCP 异步启动 Boss 推荐页流水线（含同步门禁预检）；prepare_recommend_pipeline_run 返回 READY 后，如果用户要现在运行就调用本工具或 run_recommend。必须作为 MCP tool call 调用，禁止通过 terminal/shell/run_command/CLI/manual JSON-RPC 代替，也不要用 schedule_recommend_pipeline_run 冒充立即启动。",
+      name: TOOL_PREPARE_RUN,
+      description: "只校验 Boss 推荐页流水线参数是否完整；不会启动筛选任务。主要用于显式预检或稍后/cron/定时启动前校验。若用户要现在运行，READY/cron_ready=true 后必须继续调用本 MCP server 的 run_recommend 或 start_recommend_pipeline_run；prepare 能返回结果就证明原生 MCP 可用，禁止改用 terminal/shell/run_command/PowerShell/CLI/manual JSON-RPC，也禁止再次调用 prepare 试图启动。",
       inputSchema: createRunInputSchema()
     },
     {
@@ -1165,21 +1332,50 @@ function createToolsSchema() {
         additionalProperties: false
       }
     },
-    {
-      name: TOOL_GET_RUN,
-      description: "按 run_id 查询异步/同步流水线运行状态快照。",
-      inputSchema: {
-        type: "object",
-        properties: {
+    {
+      name: TOOL_GET_RUN,
+      description: "按已知 run_id 查询异步/同步流水线运行状态快照。若忘记 run_id，请先调用 list_recommend_pipeline_runs 找 latest_run；在 Trae-CN 中禁止用 terminal/PowerShell/CLI/filesystem scraping 查看 run JSON。",
+      inputSchema: {
+        type: "object",
+        properties: {
           run_id: { type: "string" }
         },
         required: ["run_id"],
-        additionalProperties: false
-      }
-    },
-    {
-      name: TOOL_CANCEL_RUN,
-      description: "取消指定 run_id 的运行中流水线。",
+        additionalProperties: false
+      }
+    },
+    {
+      name: TOOL_LIST_RUNS,
+      description: "只读列出最近的 Boss 推荐页 run 状态摘要，并返回 latest_run。用于忘记 run_id 后恢复状态/取消/暂停；摘要不会包含大体积候选人 results。Trae-CN 中必须用本工具恢复 run_id，禁止用 terminal/PowerShell/CLI/Get-Content 读取 ~/.boss-recommend-mcp/runs。",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 100,
+            description: "最多返回多少条最近 run；默认 20，最大 100。"
+          },
+          state: {
+            type: "string",
+            enum: ["queued", "running", "paused", "completed", "failed", "canceled"],
+            description: "可选，只返回某个状态。"
+          },
+          states: {
+            type: "array",
+            items: {
+              type: "string",
+              enum: ["queued", "running", "paused", "completed", "failed", "canceled"]
+            },
+            description: "可选，只返回这些状态；与 state 同时传时取并集。"
+          }
+        },
+        additionalProperties: false
+      }
+    },
+    {
+      name: TOOL_CANCEL_RUN,
+      description: "取消指定 run_id 的运行中流水线。",
       inputSchema: {
         type: "object",
         properties: {
@@ -1779,6 +1975,12 @@ function markDetachedWorkerFailed(runId, error, options = {}) {
     ...errorToDetachedWorkerPayload(error, options.message),
     ...(options.code ? { code: options.code } : {})
   };
+  if (existing.control?.cancel_requested === true && isShutdownLikeError(errorPayload)) {
+    return finalizeRawRunStateAsCanceled(normalizedRunId, existing, {
+      errorPayload,
+      message: "流水线已取消；detached worker 在取消收尾时关闭了浏览器连接。"
+    });
+  }
   const previousResult = existing.result && typeof existing.result === "object" ? existing.result : {};
   const result = {
     ...previousResult,
@@ -1876,7 +2078,8 @@ function buildWorkerLaunchFailedPayload(message) {
 
 function finalizeCanceledRun(runId, snapshot) {
   const canceledResult = {
-    status: "FAILED",
+    status: "CANCELED",
+    completion_reason: "canceled_by_user",
     error: {
       code: "PIPELINE_CANCELED",
       message: "流水线已取消。",
@@ -2047,16 +2250,25 @@ async function executeTrackedPipeline({
       }
     );
   } catch (error) {
-    const canceled = Boolean(signal?.aborted) || error?.code === "PIPELINE_ABORTED";
-    if (canceled) {
-      const canceledResult = {
-        status: "FAILED",
-        error: {
-          code: "PIPELINE_CANCELED",
-          message: "流水线已取消。",
-          retryable: true
-        }
-      };
+    const canceled = Boolean(signal?.aborted)
+      || error?.code === "PIPELINE_ABORTED"
+      || (isRunCancelRequested(runId) && isShutdownLikeError(error));
+    if (canceled) {
+      const canceledResult = {
+        status: "CANCELED",
+        completion_reason: "canceled_by_user",
+        error: {
+          code: "PIPELINE_CANCELED",
+          message: "流水线已取消。",
+          retryable: true,
+          shutdown_error: isShutdownLikeError(error)
+            ? {
+                code: error?.code || "SHUTDOWN_ERROR",
+                message: error?.message || String(error)
+              }
+            : undefined
+        }
+      };
       safeUpdateRunState(runId, {
         mode,
         state: RUN_STATE_CANCELED,
@@ -2105,21 +2317,35 @@ async function executeTrackedPipeline({
     };
   }
 
-  const terminalState = result?.status === "FAILED"
-    ? RUN_STATE_FAILED
-    : result?.status === "PAUSED"
-      ? (isRunCancelRequested(runId) ? RUN_STATE_CANCELED : RUN_STATE_PAUSED)
-      : RUN_STATE_COMPLETED;
+  const failedAfterCancel = result?.status === "FAILED"
+    && isRunCancelRequested(runId)
+    && isShutdownLikeError(result?.error || result);
+  const terminalState = failedAfterCancel
+    ? RUN_STATE_CANCELED
+    : result?.status === "FAILED"
+      ? RUN_STATE_FAILED
+      : result?.status === "PAUSED"
+      ? (isRunCancelRequested(runId) ? RUN_STATE_CANCELED : RUN_STATE_PAUSED)
+      : RUN_STATE_COMPLETED;
   const outputCsv = getOutputCsvFromResult(result) || resumeConfig.output_csv;
   const checkpointPath = normalizeText(result?.result?.checkpoint_path || resumeConfig.checkpoint_path);
-  const canceledError = terminalState === RUN_STATE_CANCELED
-    ? {
-        code: "PIPELINE_CANCELED",
-        message: "流水线已取消。",
-        retryable: true
-      }
-    : null;
-  safeUpdateRunState(runId, {
+  const canceledError = terminalState === RUN_STATE_CANCELED
+    ? {
+        code: "PIPELINE_CANCELED",
+        message: "流水线已取消。",
+        retryable: true,
+        shutdown_error: failedAfterCancel ? (result?.error || null) : undefined
+      }
+    : null;
+  const finalResult = failedAfterCancel
+    ? {
+        ...(result || {}),
+        status: "CANCELED",
+        completion_reason: "canceled_by_user",
+        error: canceledError
+      }
+    : result || null;
+  safeUpdateRunState(runId, {
     mode,
     state: terminalState,
     stage: runtimeCallbacks.getLastStage(),
@@ -2147,13 +2373,13 @@ async function executeTrackedPipeline({
       : terminalState === RUN_STATE_CANCELED
         ? canceledError
         : null,
-    result: result || null
-  });
-  return {
-    result,
-    lastStage: runtimeCallbacks.getLastStage(),
-    state: terminalState
-  };
+    result: finalResult
+  });
+  return {
+    result: finalResult,
+    lastStage: runtimeCallbacks.getLastStage(),
+    state: terminalState
+  };
 }
 
 function initializeRunStateOrThrow(runId, mode, workspaceRoot, args, pid = process.pid) {
@@ -2699,6 +2925,8 @@ async function handleRequest(message, workspaceRoot) {
         payload = await handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_RUN) {
         payload = handleGetRunTool(args);
+      } else if (toolName === TOOL_LIST_RUNS) {
+        payload = handleListRunsTool(args);
       } else if (toolName === TOOL_CANCEL_RUN) {
         payload = handleCancelRunTool(args);
       } else if (toolName === TOOL_PAUSE_RUN) {

package/src/recommend-mcp.js

@@ -345,9 +345,9 @@ function normalizeErrorText(error = {}) {
   ].join(" "));
 }
 
-function classifyRecommendRecovery(error = {}) {
-  const text = normalizeErrorText(error);
-  if (!text) return null;
+function classifyRecommendRecovery(error = {}) {
+  const text = normalizeErrorText(error);
+  if (!text) return null;
   if (/BOSS_LOGIN_REQUIRED/i.test(text)) return "login_required";
   if (/Could not find node with given id|No node with given id|Node is detached|Cannot find node|DETAIL_STALE_NODE|IMAGE_CAPTURE_STALE_NODE/i.test(text)) {
     return "transient_stale_dom";
@@ -358,8 +358,13 @@ function classifyRecommendRecovery(error = {}) {
   if (/(?:aborted|abort|timeout|timed out|fetch failed|socket|network|ECONNRESET|ETIMEDOUT|EAI_AGAIN)/i.test(text)) {
     return "transient_network_or_llm";
   }
-  return null;
-}
+  return null;
+}
+
+function isCancelShutdownError(error = {}) {
+  const text = normalizeErrorText(error);
+  return /socket hang up|ECONNREFUSED|ECONNRESET|WebSocket is not open|Target closed|Session closed|Connection closed|RUN_PROCESS_EXITED|DETACHED_WORKER|RUN_WORKER/i.test(text);
+}
 
 function buildConstrainedAgentRecovery(snapshot = {}, meta = {}, artifacts = null) {
   const error = snapshot?.error || snapshot?.result?.error || null;
@@ -574,15 +579,31 @@ function normalizeRunSnapshot(snapshot) {
   };
 }
 
-function mergePersistedControlRequest(normalized, existing) {
-  const control = {
-    ...(normalized?.control || {})
-  };
-  if (!normalized || TERMINAL_STATUSES.has(normalized.state)) return control;
-  const existingControl = plainRecord(existing?.control);
-  if (existingControl.cancel_requested === true) {
-    return {
-      ...control,
+function mergePersistedControlRequest(normalized, existing) {
+  const control = {
+    ...(normalized?.control || {})
+  };
+  const existingControl = plainRecord(existing?.control);
+  if (!normalized) return control;
+  if (TERMINAL_STATUSES.has(normalized.state)) {
+    if (
+      normalized.state === RUN_STATUS_FAILED
+      && existingControl.cancel_requested === true
+      && isCancelShutdownError(normalized.error || normalized.result?.error || "")
+    ) {
+      return {
+        ...control,
+        pause_requested: true,
+        pause_requested_at: existingControl.pause_requested_at || control.pause_requested_at || new Date().toISOString(),
+        pause_requested_by: existingControl.pause_requested_by || control.pause_requested_by || "cancel_recommend_pipeline_run",
+        cancel_requested: true
+      };
+    }
+    return control;
+  }
+  if (existingControl.cancel_requested === true) {
+    return {
+      ...control,
       pause_requested: true,
       pause_requested_at: existingControl.pause_requested_at || control.pause_requested_at || new Date().toISOString(),
       pause_requested_by: existingControl.pause_requested_by || control.pause_requested_by || "cancel_recommend_pipeline_run",
@@ -605,22 +626,81 @@ function mergePersistedControlRequest(normalized, existing) {
       pause_requested_by: null,
       cancel_requested: false
     };
-  }
-  return control;
-}
-
-function persistRecommendRunSnapshot(snapshot, {
-  persistActiveCheckpoint = false
-} = {}) {
-  const normalized = normalizeRunSnapshot(snapshot);
-  if (!normalized?.run_id) return normalized;
-  const artifacts = getRecommendRunArtifacts(normalized.run_id);
-  if (!artifacts) return normalized;
-  const existing = readJsonFile(artifacts.run_state_path);
-  normalized.control = mergePersistedControlRequest(normalized, existing);
-  if (persistActiveCheckpoint) {
-    persistRecommendCheckpointSnapshot(normalized);
-  }
+  }
+  return control;
+}
+
+function cancelErrorFromShutdown(shutdownError = null) {
+  return {
+    code: "PIPELINE_CANCELED",
+    message: "流水线已取消。",
+    retryable: true,
+    shutdown_error: shutdownError || undefined
+  };
+}
+
+function coerceCanceledTerminalSnapshot(normalized, existing) {
+  const existingControl = plainRecord(existing?.control);
+  const shutdownError = normalized?.error || normalized?.result?.error || null;
+  const shouldWrapCanceledShutdown = (
+    normalized
+    && (
+      (
+        normalized.state === RUN_STATUS_FAILED
+        && existingControl.cancel_requested === true
+      )
+      || normalized.state === RUN_STATUS_CANCELED
+    )
+    && isCancelShutdownError(shutdownError || "")
+  );
+  if (
+    !shouldWrapCanceledShutdown
+  ) {
+    return normalized;
+  }
+  const canceledError = cancelErrorFromShutdown(shutdownError);
+  return {
+    ...normalized,
+    state: RUN_STATUS_CANCELED,
+    status: RUN_STATUS_CANCELED,
+    last_message: "流水线已取消；取消收尾时浏览器连接已关闭。",
+    control: {
+      pause_requested: false,
+      pause_requested_at: null,
+      pause_requested_by: null,
+      cancel_requested: false
+    },
+    error: canceledError,
+    result: normalized.result ? {
+      ...normalized.result,
+      status: "CANCELED",
+      completion_reason: "canceled_by_user",
+      error: canceledError
+    } : {
+      status: "CANCELED",
+      completion_reason: "canceled_by_user",
+      error: canceledError,
+      run_id: normalized.run_id,
+      processed_count: normalized.progress?.processed || 0,
+      screened_count: normalized.progress?.screened || normalized.progress?.processed || 0,
+      passed_count: normalized.progress?.passed || 0
+    }
+  };
+}
+
+function persistRecommendRunSnapshot(snapshot, {
+  persistActiveCheckpoint = false
+} = {}) {
+  let normalized = normalizeRunSnapshot(snapshot);
+  if (!normalized?.run_id) return normalized;
+  const artifacts = getRecommendRunArtifacts(normalized.run_id);
+  if (!artifacts) return normalized;
+  const existing = readJsonFile(artifacts.run_state_path);
+  normalized.control = mergePersistedControlRequest(normalized, existing);
+  normalized = coerceCanceledTerminalSnapshot(normalized, existing);
+  if (persistActiveCheckpoint) {
+    persistRecommendCheckpointSnapshot(normalized);
+  }
   const payload = {
     run_id: normalized.run_id,
     mode: normalized.mode,
@@ -643,29 +723,59 @@ function persistRecommendRunSnapshot(snapshot, {
     summary: normalized.summary,
     artifacts: normalized.artifacts
   };
-  writeJsonAtomic(artifacts.run_state_path, payload);
-  return normalized;
-}
-
-function reconcilePersistedRecommendRunIfNeeded(persisted) {
-  if (!persisted || typeof persisted !== "object") return persisted;
-  const persistedState = normalizeText(persisted.state || persisted.status);
-  if (TERMINAL_STATUSES.has(persistedState)) return persisted;
+  writeJsonAtomic(artifacts.run_state_path, payload);
+  return normalized;
+}
+
+function patchPersistedRecommendRunControl(runId, controlPatch = {}, {
+  message = ""
+} = {}) {
+  const artifacts = getRecommendRunArtifacts(runId);
+  if (!artifacts) return null;
+  const current = readJsonFile(artifacts.run_state_path);
+  const state = normalizeText(current?.state || current?.status || "");
+  if (!current || TERMINAL_STATUSES.has(state)) return null;
+  const now = new Date().toISOString();
+  const patched = {
+    ...current,
+    updated_at: now,
+    heartbeat_at: current.heartbeat_at || now,
+    last_message: message || current.last_message || "",
+    control: {
+      ...(current.control || {}),
+      ...controlPatch
+    }
+  };
+  writeJsonAtomic(artifacts.run_state_path, patched);
+  return patched;
+}
+
+function reconcilePersistedRecommendRunIfNeeded(persisted) {
+  if (!persisted || typeof persisted !== "object") return persisted;
+  const persistedState = normalizeText(persisted.state || persisted.status);
+  if (TERMINAL_STATUSES.has(persistedState)) return persisted;
   if (isProcessAlive(persisted.pid)) return persisted;
 
-  const runId = normalizeRunId(persisted.run_id || persisted.runId);
-  const artifacts = getRecommendRunArtifacts(runId);
-  const checkpoint = artifacts?.checkpoint_path ? readJsonFile(artifacts.checkpoint_path) : null;
-  const now = new Date().toISOString();
-  const error = {
-    code: "RUN_PROCESS_EXITED",
-    message: `检测到推荐任务进程已退出（pid=${persisted.pid || "unknown"}），已自动标记为失败。`,
-    retryable: true
-  };
-  return persistRecommendRunSnapshot({
+  const runId = normalizeRunId(persisted.run_id || persisted.runId);
+  const artifacts = getRecommendRunArtifacts(runId);
+  const checkpoint = artifacts?.checkpoint_path ? readJsonFile(artifacts.checkpoint_path) : null;
+  const now = new Date().toISOString();
+  const cancelRequested = persisted.control?.cancel_requested === true;
+  const processExitedError = {
+    code: "RUN_PROCESS_EXITED",
+    message: `检测到推荐任务进程已退出（pid=${persisted.pid || "unknown"}）。`,
+    retryable: true
+  };
+  const error = cancelRequested
+    ? cancelErrorFromShutdown(processExitedError)
+    : {
+        ...processExitedError,
+        message: `检测到推荐任务进程已退出（pid=${persisted.pid || "unknown"}），已自动标记为失败。`
+      };
+  return persistRecommendRunSnapshot({
     runId,
     name: persisted.name || runId,
-    status: RUN_STATUS_FAILED,
+    status: cancelRequested ? RUN_STATUS_CANCELED : RUN_STATUS_FAILED,
     phase: persisted.stage || persisted.phase || "recommend:orphaned",
     progress: persisted.progress || {},
     context: persisted.context || {},
@@ -1813,20 +1923,45 @@ export function cancelRecommendPipelineRunTool({ args = {} } = {}) {
     }, runId);
   } catch {
     const persisted = readRecommendRunState(runId);
-    if (persisted && TERMINAL_STATUSES.has(persisted.state)) {
-      return {
-        status: "CANCEL_IGNORED",
-        run: persisted,
-        message: "目标任务已结束，无需取消。",
+    if (persisted && TERMINAL_STATUSES.has(persisted.state)) {
+      return {
+        status: "CANCEL_IGNORED",
+        run: persisted,
+        message: "目标任务已结束，无需取消。",
         runtime_evaluate_used: false,
         method_summary: {},
         method_log: [],
-        chrome: null
-      };
-    }
-    return getRecommendPipelineRunTool({ args });
-  }
-}
+        chrome: null
+      };
+    }
+    const cancelMessage = "已收到取消请求，将由 detached worker 在下一个安全边界停止。";
+    const patched = patchPersistedRecommendRunControl(runId, {
+      pause_requested: true,
+      pause_requested_at: new Date().toISOString(),
+      pause_requested_by: "cancel_recommend_pipeline_run",
+      cancel_requested: true
+    }, {
+      message: cancelMessage
+    });
+    if (patched) {
+      return {
+        status: "CANCEL_REQUESTED",
+        run: patched,
+        message: cancelMessage,
+        persistence: {
+          source: "disk",
+          active_control_available: false,
+          detached_control_requested: true
+        },
+        runtime_evaluate_used: false,
+        method_summary: {},
+        method_log: [],
+        chrome: null
+      };
+    }
+    return getRecommendPipelineRunTool({ args });
+  }
+}
 
 export function getRecommendMcpHealthSnapshot(runId) {
   const meta = getRecommendRunMeta(runId);