@reconcrap/boss-recommend-mcp 2.0.35 → 2.0.37

package/config/screening-config.example.json

@@ -1,4 +1,4 @@
-{
+{
   "baseUrl": "https://api.openai.com/v1",
   "apiKey": "replace-with-openai-api-key",
   "model": "gpt-4.1-mini",

package/package.json

@@ -1,119 +1,119 @@
-{
-  "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.0.35",
-  "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
-  "keywords": [
-    "boss",
-    "mcp",
-    "codex",
-    "recruiting",
-    "boss-zhipin",
-    "recommend"
-  ],
-  "type": "module",
-  "main": "src/index.js",
-  "bin": {
-    "boss-recommend-mcp": "bin/boss-recommend-mcp.js"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "cli": "node src/cli.js",
-    "install:local": "node src/cli.js install",
-    "postinstall": "node scripts/postinstall.cjs",
-    "test:parser": "node src/test-parser.js",
-    "test:run-state": "node src/test-run-state.js",
-    "test:cdp-browser": "node src/test-cdp-browser.js",
-    "test:core-capture": "node src/test-core-capture.js",
-    "test:core-cv-capture-target": "node src/test-core-cv-capture-target.js",
-    "test:core-cv-acquisition": "node src/test-core-cv-acquisition.js",
-    "test:core-greet-quota": "node src/test-core-greet-quota.js",
-    "test:core-infinite-list": "node src/test-core-infinite-list.js",
-    "test:core-reporting": "node src/test-core-reporting.js",
-    "test:core-run": "node src/test-core-run.js",
-    "test:core-screening": "node src/test-core-screening.js",
-    "test:core-self-heal": "node src/test-core-self-heal.js",
-    "test:installer-migration": "node src/test-installer-migration.js",
-    "test:recommend-actions": "node src/test-recommend-actions.js",
-    "test:recommend-domain": "node src/test-recommend-domain.js",
-    "test:recommend-run-service": "node src/test-recommend-run-service.js",
-    "test:recommend-mcp": "node src/test-recommend-mcp.js",
-    "test:recruit-domain": "node src/test-recruit-domain.js",
-    "test:recruit-mcp": "node src/test-recruit-mcp.js",
-    "test:chat-domain": "node src/test-chat-domain.js",
-    "test:chat-run-service": "node src/test-chat-run-service.js",
-    "test:chat-mcp": "node src/test-chat-mcp.js",
-    "test:async": "node src/test-index-async.js",
-    "test:runtime-scan": "node src/test-runtime-scan.js",
-    "scan:runtime": "node scripts/scan-forbidden-runtime.js",
-    "scan:runtime:json": "node scripts/scan-forbidden-runtime.js --json",
-    "scan:runtime:strict": "node scripts/scan-forbidden-runtime.js --fail-on-findings",
-    "scan:runtime:package": "node scripts/scan-forbidden-runtime.js --package-surface",
-    "scan:runtime:package:strict": "node scripts/scan-forbidden-runtime.js --package-surface --fail-on-legacy",
-    "scan:legacy-boundary": "node scripts/scan-legacy-boundary.js",
-    "scan:package-boundary": "node scripts/scan-package-boundary.js",
-    "gate:phase9-static": "node scripts/phase9-static-gate.js",
-    "gate:phase10-complete": "node scripts/phase10-completion-gate.js",
-    "live:cdp-smoke": "node scripts/live-cdp-smoke.js",
-    "live:run-lifecycle": "node scripts/live-run-lifecycle-smoke.js",
-    "live:screening": "node scripts/live-screening-smoke.js",
-    "live:detail": "node scripts/live-detail-smoke.js",
-    "live:infinite-list": "node scripts/live-infinite-list-smoke.js",
-    "live:scroll-end": "node scripts/live-scroll-end-screenshot.js",
-    "live:refresh-round": "node scripts/live-refresh-round-smoke.js",
-    "live:self-heal": "node scripts/live-self-heal-smoke.js",
-    "live:recommend-actions": "node scripts/live-recommend-actions-smoke.js",
-    "live:recommend-phase10-full": "node scripts/live-recommend-phase10-full.js",
-    "live:recommend-domain": "node scripts/live-recommend-domain-smoke.js",
-    "live:recommend-run-service": "node scripts/live-recommend-run-service-smoke.js",
-    "live:recommend-mcp": "node scripts/live-recommend-mcp-smoke.js",
-    "live:search-phase10-full": "node scripts/live-search-phase10-full.js",
-    "live:recruit-domain": "node scripts/live-recruit-domain-smoke.js",
-    "live:recruit-run-service": "node scripts/live-recruit-run-service-smoke.js",
-    "live:recruit-mcp": "node scripts/live-recruit-mcp-smoke.js",
-    "live:chat-domain": "node scripts/live-chat-domain-smoke.js",
-    "live:chat-run-service": "node scripts/live-chat-run-service-smoke.js",
-    "live:chat-mcp": "node scripts/live-chat-mcp-smoke.js",
-    "live:cv-capture-target": "node scripts/live-cv-capture-target-smoke.js",
-    "live:chat-phase10-full": "node scripts/live-chat-phase10-full.js",
-    "live:chat-image-screening": "node scripts/live-chat-image-screening-smoke.js"
-  },
-  "files": [
-    "bin",
-    "config/screening-config.example.json",
-    "skills",
-    "scripts/postinstall.cjs",
-    "src/core",
-    "src/domains",
-    "src/chat-mcp.js",
-    "src/chat-runtime-config.js",
-    "src/cli.js",
-    "src/index.js",
-    "src/parser.js",
-    "src/recommend-mcp.js",
-    "src/recruit-mcp.js",
-    "src/run-state.js",
-    "README.md"
-  ],
-  "dependencies": {
-    "chrome-remote-interface": "^0.33.3",
-    "sharp": "^0.34.4",
-    "ws": "^8.19.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "devDependencies": {},
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/reconcrap-cpu/boss-recommend-mcp.git"
-  },
-  "author": "",
-  "bugs": {
-    "url": "https://github.com/reconcrap-cpu/boss-recommend-mcp/issues"
-  },
-  "homepage": "https://github.com/reconcrap-cpu/boss-recommend-mcp#readme"
-}
+{
+  "name": "@reconcrap/boss-recommend-mcp",
+  "version": "2.0.37",
+  "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
+  "keywords": [
+    "boss",
+    "mcp",
+    "codex",
+    "recruiting",
+    "boss-zhipin",
+    "recommend"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "boss-recommend-mcp": "bin/boss-recommend-mcp.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "cli": "node src/cli.js",
+    "install:local": "node src/cli.js install",
+    "postinstall": "node scripts/postinstall.cjs",
+    "test:parser": "node src/test-parser.js",
+    "test:run-state": "node src/test-run-state.js",
+    "test:cdp-browser": "node src/test-cdp-browser.js",
+    "test:core-capture": "node src/test-core-capture.js",
+    "test:core-cv-capture-target": "node src/test-core-cv-capture-target.js",
+    "test:core-cv-acquisition": "node src/test-core-cv-acquisition.js",
+    "test:core-greet-quota": "node src/test-core-greet-quota.js",
+    "test:core-infinite-list": "node src/test-core-infinite-list.js",
+    "test:core-reporting": "node src/test-core-reporting.js",
+    "test:core-run": "node src/test-core-run.js",
+    "test:core-screening": "node src/test-core-screening.js",
+    "test:core-self-heal": "node src/test-core-self-heal.js",
+    "test:installer-migration": "node src/test-installer-migration.js",
+    "test:recommend-actions": "node src/test-recommend-actions.js",
+    "test:recommend-domain": "node src/test-recommend-domain.js",
+    "test:recommend-run-service": "node src/test-recommend-run-service.js",
+    "test:recommend-mcp": "node src/test-recommend-mcp.js",
+    "test:recruit-domain": "node src/test-recruit-domain.js",
+    "test:recruit-mcp": "node src/test-recruit-mcp.js",
+    "test:chat-domain": "node src/test-chat-domain.js",
+    "test:chat-run-service": "node src/test-chat-run-service.js",
+    "test:chat-mcp": "node src/test-chat-mcp.js",
+    "test:async": "node src/test-index-async.js",
+    "test:runtime-scan": "node src/test-runtime-scan.js",
+    "scan:runtime": "node scripts/scan-forbidden-runtime.js",
+    "scan:runtime:json": "node scripts/scan-forbidden-runtime.js --json",
+    "scan:runtime:strict": "node scripts/scan-forbidden-runtime.js --fail-on-findings",
+    "scan:runtime:package": "node scripts/scan-forbidden-runtime.js --package-surface",
+    "scan:runtime:package:strict": "node scripts/scan-forbidden-runtime.js --package-surface --fail-on-legacy",
+    "scan:legacy-boundary": "node scripts/scan-legacy-boundary.js",
+    "scan:package-boundary": "node scripts/scan-package-boundary.js",
+    "gate:phase9-static": "node scripts/phase9-static-gate.js",
+    "gate:phase10-complete": "node scripts/phase10-completion-gate.js",
+    "live:cdp-smoke": "node scripts/live-cdp-smoke.js",
+    "live:run-lifecycle": "node scripts/live-run-lifecycle-smoke.js",
+    "live:screening": "node scripts/live-screening-smoke.js",
+    "live:detail": "node scripts/live-detail-smoke.js",
+    "live:infinite-list": "node scripts/live-infinite-list-smoke.js",
+    "live:scroll-end": "node scripts/live-scroll-end-screenshot.js",
+    "live:refresh-round": "node scripts/live-refresh-round-smoke.js",
+    "live:self-heal": "node scripts/live-self-heal-smoke.js",
+    "live:recommend-actions": "node scripts/live-recommend-actions-smoke.js",
+    "live:recommend-phase10-full": "node scripts/live-recommend-phase10-full.js",
+    "live:recommend-domain": "node scripts/live-recommend-domain-smoke.js",
+    "live:recommend-run-service": "node scripts/live-recommend-run-service-smoke.js",
+    "live:recommend-mcp": "node scripts/live-recommend-mcp-smoke.js",
+    "live:search-phase10-full": "node scripts/live-search-phase10-full.js",
+    "live:recruit-domain": "node scripts/live-recruit-domain-smoke.js",
+    "live:recruit-run-service": "node scripts/live-recruit-run-service-smoke.js",
+    "live:recruit-mcp": "node scripts/live-recruit-mcp-smoke.js",
+    "live:chat-domain": "node scripts/live-chat-domain-smoke.js",
+    "live:chat-run-service": "node scripts/live-chat-run-service-smoke.js",
+    "live:chat-mcp": "node scripts/live-chat-mcp-smoke.js",
+    "live:cv-capture-target": "node scripts/live-cv-capture-target-smoke.js",
+    "live:chat-phase10-full": "node scripts/live-chat-phase10-full.js",
+    "live:chat-image-screening": "node scripts/live-chat-image-screening-smoke.js"
+  },
+  "files": [
+    "bin",
+    "config/screening-config.example.json",
+    "skills",
+    "scripts/postinstall.cjs",
+    "src/core",
+    "src/domains",
+    "src/chat-mcp.js",
+    "src/chat-runtime-config.js",
+    "src/cli.js",
+    "src/index.js",
+    "src/parser.js",
+    "src/recommend-mcp.js",
+    "src/recruit-mcp.js",
+    "src/run-state.js",
+    "README.md"
+  ],
+  "dependencies": {
+    "chrome-remote-interface": "^0.33.3",
+    "sharp": "^0.34.4",
+    "ws": "^8.19.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "devDependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reconcrap-cpu/boss-recommend-mcp.git"
+  },
+  "author": "",
+  "bugs": {
+    "url": "https://github.com/reconcrap-cpu/boss-recommend-mcp/issues"
+  },
+  "homepage": "https://github.com/reconcrap-cpu/boss-recommend-mcp#readme"
+}

package/src/core/run/index.js

@@ -47,6 +47,7 @@ function snapshotFromEntry(entry) {
   return clone({
     runId: run.runId,
     name: run.name,
+    pid: run.pid,
     status: run.status,
     phase: run.phase,
     progress: run.progress,
@@ -205,11 +206,14 @@ export function createRunLifecycleManager({
     }
   }
 
-  function startRun({ name, context = {}, progress = {}, checkpoint = {}, task }) {
+  function startRun({ runId: requestedRunId = "", name, pid = process.pid, context = {}, progress = {}, checkpoint = {}, task }) {
     if (typeof task !== "function") {
       throw new Error("startRun requires a task function");
     }
-    const runId = createRunId(idPrefix);
+    const runId = String(requestedRunId || "").trim() || createRunId(idPrefix);
+    if (runs.has(runId)) {
+      throw new Error(`Run already exists: ${runId}`);
+    }
     const startedAt = now();
     const entry = {
       controller: new AbortController(),
@@ -219,6 +223,7 @@ export function createRunLifecycleManager({
       run: {
         runId,
         name: name || runId,
+        pid: Number.isInteger(pid) && pid > 0 ? pid : process.pid,
         status: RUN_STATUS_QUEUED,
         phase: "queued",
         progress,

package/src/domains/recommend/refresh.js

@@ -88,6 +88,105 @@ export function buildRecommendFilterSelectionOptions(filter = {}, {
   };
 }
 
+function refreshFailureReason(method = "") {
+  return method === "page_navigate" ? "page_navigate_failed" : "page_reload_failed";
+}
+
+async function applyRefreshMethod(client, method, {
+  jobLabel = "",
+  pageScope = "recommend",
+  fallbackPageScope = "recommend",
+  filter = {},
+  targetUrl = RECOMMEND_TARGET_URL,
+  forceRecentNotView = true,
+  cardTimeoutMs = 30000,
+  reloadSettleMs = 8000
+} = {}) {
+  const started = Date.now();
+  let currentRootState = null;
+  let jobSelection = null;
+  let pageScopeResult = null;
+  let filterResult = null;
+  try {
+    if (method === "page_navigate") {
+      await client.Page.navigate({ url: targetUrl || RECOMMEND_TARGET_URL });
+    } else {
+      await client.Page.reload({ ignoreCache: true });
+    }
+    if (reloadSettleMs > 0) await sleep(reloadSettleMs);
+    currentRootState = await waitForRecommendRoots(client, {
+      timeoutMs: Math.max(45000, reloadSettleMs * 6),
+      intervalMs: 500
+    });
+    if (!currentRootState?.iframe?.documentNodeId) {
+      throw new Error("Recommend iframe was not ready after refresh reload");
+    }
+    if (jobLabel) {
+      jobSelection = await selectRecommendJob(client, currentRootState.iframe.documentNodeId, {
+        jobLabel,
+        settleMs: reloadSettleMs > 10000 ? 12000 : 6000
+      });
+      if (!jobSelection.selected) {
+        throw new Error(`Requested recommend job was not selected after refresh reload: ${jobSelection.reason}`);
+      }
+      currentRootState = await getRecommendRoots(client);
+    }
+    pageScopeResult = await selectRecommendPageScope(
+      client,
+      currentRootState.iframe.documentNodeId,
+      {
+        pageScope,
+        fallbackScope: fallbackPageScope,
+        settleMs: reloadSettleMs > 10000 ? 3000 : 1200,
+        timeoutMs: Math.max(10000, Math.min(cardTimeoutMs, 60000))
+      }
+    );
+    if (!pageScopeResult.selected) {
+      throw new Error(`Recommend page scope was not selected after refresh reload: ${pageScopeResult.reason || pageScope}`);
+    }
+    currentRootState = await getRecommendRoots(client);
+    filterResult = await selectAndConfirmFirstSafeFilter(
+      client,
+      currentRootState.iframe.documentNodeId,
+      buildRecommendFilterSelectionOptions(filter, { forceRecentNotView })
+    );
+    const cardNodeIds = await waitForRecommendCardNodeIds(client, currentRootState.iframe.documentNodeId, {
+      timeoutMs: cardTimeoutMs,
+      intervalMs: 500
+    });
+    if (!cardNodeIds.length) {
+      throw new Error("No recommend candidate cards were found after refresh reload");
+    }
+    return {
+      ok: true,
+      method,
+      target_url: method === "page_navigate" ? (targetUrl || RECOMMEND_TARGET_URL) : null,
+      job_selection: jobSelection,
+      page_scope: pageScopeResult,
+      filter: filterResult,
+      card_count: cardNodeIds.length,
+      root_state: currentRootState,
+      forced_recent_not_view: forceRecentNotView,
+      elapsed_ms: Date.now() - started
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      method,
+      reason: refreshFailureReason(method),
+      error: error?.message || String(error),
+      target_url: method === "page_navigate" ? (targetUrl || RECOMMEND_TARGET_URL) : null,
+      job_selection: jobSelection,
+      page_scope: pageScopeResult,
+      filter: filterResult,
+      card_count: 0,
+      root_state: currentRootState,
+      forced_recent_not_view: forceRecentNotView,
+      elapsed_ms: Date.now() - started
+    };
+  }
+}
+
 export async function refreshRecommendListAtEnd(client, {
   rootState = null,
   jobLabel = "",
@@ -103,9 +202,10 @@ export async function refreshRecommendListAtEnd(client, {
   reloadSettleMs = 8000
 } = {}) {
   const attempts = [];
-  let currentRootState = rootState || await getRecommendRoots(client);
+  let currentRootState = rootState || null;
 
   if (preferEndRefreshButton) {
+    currentRootState = currentRootState || await getRecommendRoots(client);
     const buttonResult = await clickRecommendEndRefreshButton(
       client,
       currentRootState.iframe.documentNodeId,
@@ -159,82 +259,49 @@ export async function refreshRecommendListAtEnd(client, {
     }
   }
 
-  let fallbackMethod = "page_reload";
-  try {
-    let method = "page_reload";
-    if (forceNavigate && typeof client?.Page?.navigate === "function") {
-      await client.Page.navigate({ url: targetUrl || RECOMMEND_TARGET_URL });
-      method = "page_navigate";
-      fallbackMethod = method;
-    } else {
-      await client.Page.reload({ ignoreCache: true });
-      fallbackMethod = method;
-    }
-    if (reloadSettleMs > 0) await sleep(reloadSettleMs);
-    currentRootState = await waitForRecommendRoots(client, {
-      timeoutMs: Math.max(30000, reloadSettleMs * 4),
-      intervalMs: 500
+  const fallbackMethods = [];
+  if (forceNavigate && typeof client?.Page?.navigate === "function") {
+    fallbackMethods.push("page_navigate");
+  }
+  if (typeof client?.Page?.reload === "function") {
+    fallbackMethods.push("page_reload");
+  }
+  if (!fallbackMethods.length) {
+    fallbackMethods.push("page_reload");
+  }
+
+  let lastRefreshResult = null;
+  for (const method of fallbackMethods) {
+    const refreshResult = await applyRefreshMethod(client, method, {
+      jobLabel,
+      pageScope,
+      fallbackPageScope,
+      filter,
+      targetUrl,
+      forceRecentNotView,
+      cardTimeoutMs,
+      reloadSettleMs
     });
-    if (!currentRootState?.iframe?.documentNodeId) {
-      throw new Error("Recommend iframe was not ready after refresh reload");
-    }
-    let jobSelection = null;
-    if (jobLabel) {
-      jobSelection = await selectRecommendJob(client, currentRootState.iframe.documentNodeId, {
-        jobLabel,
-        settleMs: reloadSettleMs > 10000 ? 12000 : 6000
-      });
-      if (!jobSelection.selected) {
-        throw new Error(`Requested recommend job was not selected after refresh reload: ${jobSelection.reason}`);
-      }
-      currentRootState = await getRecommendRoots(client);
+    if (refreshResult.ok) {
+      return {
+        ...refreshResult,
+        attempts
+      };
     }
-    const pageScopeResult = await selectRecommendPageScope(
-      client,
-      currentRootState.iframe.documentNodeId,
-      {
-        pageScope,
-        fallbackScope: fallbackPageScope,
-        settleMs: reloadSettleMs > 10000 ? 3000 : 1200,
-        timeoutMs: Math.max(10000, Math.min(cardTimeoutMs, 60000))
-      }
-    );
-    if (!pageScopeResult.selected) {
-      throw new Error(`Recommend page scope was not selected after refresh reload: ${pageScopeResult.reason || pageScope}`);
-    }
-    currentRootState = await getRecommendRoots(client);
-    const filterResult = await selectAndConfirmFirstSafeFilter(
-      client,
-      currentRootState.iframe.documentNodeId,
-      buildRecommendFilterSelectionOptions(filter, { forceRecentNotView })
-    );
-    const cardNodeIds = await waitForRecommendCardNodeIds(client, currentRootState.iframe.documentNodeId, {
-      timeoutMs: cardTimeoutMs,
-      intervalMs: 500
-    });
-    return {
-      ok: cardNodeIds.length > 0,
-      method,
-      attempts,
-      target_url: method === "page_navigate" ? (targetUrl || RECOMMEND_TARGET_URL) : null,
-      job_selection: jobSelection,
-      page_scope: pageScopeResult,
-      filter: filterResult,
-      card_count: cardNodeIds.length,
-      root_state: currentRootState,
-      forced_recent_not_view: forceRecentNotView
-    };
-  } catch (error) {
-    return {
+    attempts.push(refreshResult);
+    lastRefreshResult = refreshResult;
+  }
+
+  return {
+    ...(lastRefreshResult || {
       ok: false,
-      method: fallbackMethod,
-      reason: fallbackMethod === "page_navigate" ? "page_navigate_failed" : "page_reload_failed",
-      error: error?.message || String(error),
-      attempts,
-      target_url: fallbackMethod === "page_navigate" ? (targetUrl || RECOMMEND_TARGET_URL) : null,
+      method: fallbackMethods[fallbackMethods.length - 1] || "page_reload",
+      reason: "refresh_failed",
+      error: "Recommend refresh did not run",
       card_count: 0,
       root_state: currentRootState,
       forced_recent_not_view: forceRecentNotView
-    };
-  }
+    }),
+    attempts
+  };
 }

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

@@ -355,16 +355,22 @@ function compactRefreshAttempt(refreshAttempt) {
   return {
     ok: Boolean(refreshAttempt.ok),
     method: refreshAttempt.method || "",
+    reason: refreshAttempt.reason || null,
+    error: refreshAttempt.error || null,
     forced_recent_not_view: Boolean(refreshAttempt.forced_recent_not_view),
     target_url: refreshAttempt.target_url || null,
     card_count: refreshAttempt.card_count || 0,
+    elapsed_ms: refreshAttempt.elapsed_ms || 0,
     attempts: (refreshAttempt.attempts || []).map((attempt) => ({
       ok: Boolean(attempt.ok),
       method: attempt.method || "",
       reason: attempt.reason || null,
+      error: attempt.error || null,
       label: attempt.label || null,
       before_card_count: attempt.before_card_count || 0,
-      after_card_count: attempt.after_card_count || 0
+      after_card_count: attempt.after_card_count || 0,
+      card_count: attempt.card_count || 0,
+      elapsed_ms: attempt.elapsed_ms || 0
     })),
     job_selection: compactJobSelection(refreshAttempt.job_selection),
     page_scope: compactPageScopeSelection(refreshAttempt.page_scope),
@@ -1260,6 +1266,8 @@ export function createRecommendRunService({
   const manager = lifecycle || createRunLifecycleManager({ idPrefix, onSnapshot });
 
   function startRecommendRun({
+    runId = "",
+    pid = process.pid,
     client,
     targetUrl = "",
     criteria = "",
@@ -1307,7 +1315,9 @@ export function createRecommendRunService({
     const candidateLimit = Math.max(1, Number(maxCandidates) || 1);
     const normalizedDetailLimit = detailLimit == null ? null : Math.max(0, Number(detailLimit) || 0);
     return manager.startRun({
+      runId,
       name,
+      pid,
       context: {
         domain: "recommend",
         target_url: targetUrl,

package/src/index.js

@@ -46,6 +46,7 @@ import {
   getRecommendPipelineRunTool,
   listRecommendJobsTool,
   pauseRecommendPipelineRunTool,
+  prepareRecommendPipelineRunTool,
   resumeRecommendPipelineRunTool,
   startRecommendPipelineRunTool
 } from "./recommend-mcp.js";
@@ -116,6 +117,16 @@ const FRAMING_LINE = "line";
 const DETACHED_WORKER_FLAG = "--detached-worker";
 const DETACHED_WORKER_RUN_ID_FLAG = "--run-id";
 const DETACHED_WORKER_RESUME_FLAG = "--resume";
+const AGENT_RUNTIME_HINT_KEYS = [
+  "CODEX_CI",
+  "CODEX_THREAD_ID",
+  "CODEX_HOME",
+  "OPENCLAW_HOME",
+  "OPENCLAW",
+  "TRAE_CN",
+  "TRAE_HOME",
+  "TRAE_AGENT"
+];
 const featuredCalibrationUnsupportedCode = "FEATURED_CALIBRATION_UNSUPPORTED_CDP_ONLY";
 const recommendSelfHealApplyUnsupportedCode = "RECOMMEND_SELF_HEAL_APPLY_UNSUPPORTED_CDP_ONLY";
 const detachedLegacyPipelineUnsupportedCode = "DETACHED_LEGACY_PIPELINE_UNSUPPORTED_CDP_ONLY";
@@ -138,6 +149,31 @@ function normalizeText(value) {
   return String(value || "").replace(/\s+/g, " ").trim();
 }
 
+function clonePlain(value, fallback = null) {
+  try {
+    return value === undefined ? fallback : JSON.parse(JSON.stringify(value));
+  } catch {
+    return fallback;
+  }
+}
+
+function isLikelyAgentRuntime() {
+  for (const key of AGENT_RUNTIME_HINT_KEYS) {
+    if (normalizeText(process.env[key] || "")) return true;
+  }
+  const originHints = [
+    normalizeText(process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE || ""),
+    normalizeText(process.env.TERM_PROGRAM || "")
+  ].join(" ").toLowerCase();
+  return /codex|openclaw|trae/.test(originHints);
+}
+
+function shouldStartRecommendDetached() {
+  if (normalizeText(process.env.BOSS_RECOMMEND_CDP_INPROC || "") === "1") return false;
+  if (normalizeText(process.env.BOSS_RECOMMEND_CDP_DETACHED || "") === "1") return true;
+  return isLikelyAgentRuntime();
+}
+
 function isUnlimitedTargetCountToken(value) {
   const token = normalizeText(value).toLowerCase();
   if (!token) return false;
@@ -255,17 +291,65 @@ function getDefaultAcceptedMessage(args = {}) {
   return `异步流水线已启动（detached）。默认不自动轮询；如需进度请按需调用 get_recommend_pipeline_run（建议至少每 ${recommendedMinutes} 分钟查询一次）。`;
 }
 
-function getRunArtifacts(runId) {
-  const normalizedRunId = normalizeText(runId);
-  return {
-    run_state_path: path.join(getRunsDir(), `${normalizedRunId}.json`),
-    checkpoint_path: path.join(getRunsDir(), `${normalizedRunId}.checkpoint.json`)
-  };
-}
+function getRunArtifacts(runId) {
+  const normalizedRunId = normalizeText(runId);
+  return {
+    run_state_path: path.join(getRunsDir(), `${normalizedRunId}.json`),
+    checkpoint_path: path.join(getRunsDir(), `${normalizedRunId}.checkpoint.json`)
+  };
+}
+
+function writeRawRunState(runId, payload) {
+  const artifacts = getRunArtifacts(runId);
+  fs.mkdirSync(path.dirname(artifacts.run_state_path), { recursive: true });
+  const tempPath = `${artifacts.run_state_path}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  fs.renameSync(tempPath, artifacts.run_state_path);
+  return payload;
+}
+
+function readRawRunState(runId) {
+  const artifacts = getRunArtifacts(runId);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(artifacts.run_state_path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function patchRawRunState(runId, patch) {
+  const current = readRawRunState(runId);
+  if (!current) return null;
+  const now = new Date().toISOString();
+  const next = {
+    ...current,
+    ...patch,
+    run_id: current.run_id || runId,
+    updated_at: now,
+    heartbeat_at: current.heartbeat_at || now,
+    control: {
+      ...(current.control || {}),
+      ...(patch.control || {})
+    },
+    resume: {
+      ...(current.resume || {}),
+      ...(patch.resume || {})
+    }
+  };
+  return writeRawRunState(runId, next);
+}
+
+function createDetachedRecommendRunId() {
+  const suffix = Math.random().toString(36).slice(2, 10);
+  return `mcp_recommend_${Date.now().toString(36)}_${suffix}`;
+}
 
 function buildRunContext(workspaceRoot, args = {}) {
+  const clonedArgs = clonePlain(args, {});
   return {
     workspace_root: path.resolve(workspaceRoot),
+    args: clonedArgs,
     instruction: String(args?.instruction || ""),
     confirmation: args?.confirmation && typeof args.confirmation === "object" ? args.confirmation : {},
     overrides: args?.overrides && typeof args.overrides === "object" ? args.overrides : {},
@@ -273,25 +357,40 @@ function buildRunContext(workspaceRoot, args = {}) {
   };
 }
 
-function resolveRunContext(snapshot) {
-  const workspaceRoot = normalizeText(snapshot?.context?.workspace_root || "");
-  const instruction = typeof snapshot?.context?.instruction === "string"
-    ? snapshot.context.instruction
-    : "";
-  if (!workspaceRoot || !instruction.trim()) return null;
-  return {
-    workspaceRoot,
-    args: {
+function resolveRunContext(snapshot) {
+  const workspaceRoot = normalizeText(snapshot?.context?.workspace_root || "");
+  const storedArgs = snapshot?.context?.args && typeof snapshot.context.args === "object" && !Array.isArray(snapshot.context.args)
+    ? clonePlain(snapshot.context.args, {})
+    : null;
+  const instruction = typeof storedArgs?.instruction === "string"
+    ? storedArgs.instruction
+    : typeof snapshot?.context?.instruction === "string"
+      ? snapshot.context.instruction
+      : "";
+  const confirmation = storedArgs?.confirmation && typeof storedArgs.confirmation === "object" && !Array.isArray(storedArgs.confirmation)
+    ? storedArgs.confirmation
+    : snapshot?.context?.confirmation && typeof snapshot.context.confirmation === "object"
+      ? snapshot.context.confirmation
+      : {};
+  const overrides = storedArgs?.overrides && typeof storedArgs.overrides === "object" && !Array.isArray(storedArgs.overrides)
+    ? storedArgs.overrides
+    : snapshot?.context?.overrides && typeof snapshot.context.overrides === "object"
+      ? snapshot.context.overrides
+      : {};
+  const followUp = storedArgs && Object.prototype.hasOwnProperty.call(storedArgs, "follow_up")
+    ? storedArgs.follow_up
+    : snapshot?.context?.follow_up && typeof snapshot.context.follow_up === "object"
+      ? snapshot.context.follow_up
+      : null;
+  if (!workspaceRoot || !instruction.trim()) return null;
+  return {
+    workspaceRoot,
+    args: {
+      ...(storedArgs || {}),
       instruction,
-      confirmation: snapshot?.context?.confirmation && typeof snapshot.context.confirmation === "object"
-        ? snapshot.context.confirmation
-        : {},
-      overrides: snapshot?.context?.overrides && typeof snapshot.context.overrides === "object"
-        ? snapshot.context.overrides
-        : {},
-      follow_up: snapshot?.context?.follow_up && typeof snapshot.context.follow_up === "object"
-        ? snapshot.context.follow_up
-        : null
+      confirmation,
+      overrides,
+      follow_up: followUp
     }
   };
 }
@@ -1827,35 +1926,184 @@ async function runDetachedWorker({ runId, resumeRun = false, workerPid = process
       : "detached worker 已启动，准备执行。"
   });
 
-  await executeTrackedPipeline({
-    runId: normalizedRunId,
-    mode: RUN_MODE_ASYNC,
+  const started = await startRecommendPipelineRunTool({
     workspaceRoot: executionContext.workspaceRoot,
     args: executionContext.args,
-    signal: new AbortController().signal,
-    resumeRun
+    runId: normalizedRunId
   });
+  if (started?.status !== "ACCEPTED") {
+    const failedPayload = started?.error || {
+      code: "RUN_WORKER_START_FAILED",
+      message: started?.status || "detached recommend worker failed to start",
+      retryable: true
+    };
+    safeUpdateRunState(normalizedRunId, {
+      state: RUN_STATE_FAILED,
+      stage: snapshot.stage || RUN_STAGE_PREFLIGHT,
+      last_message: failedPayload.message,
+      error: failedPayload,
+      result: {
+        status: "FAILED",
+        error: failedPayload
+      }
+    });
+    return { ok: false, error: failedPayload.message };
+  }
+
+  while (true) {
+    const payload = getRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    const state = normalizeText(payload?.run?.state || payload?.run?.status || "");
+    if (TERMINAL_RUN_STATES.has(state)) break;
+    const persisted = readRawRunState(normalizedRunId);
+    if (persisted?.control?.cancel_requested === true) {
+      cancelRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    } else if (persisted?.control?.pause_requested === true && state === RUN_STATE_RUNNING) {
+      pauseRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    } else if (persisted?.control?.pause_requested === false && state === RUN_STATE_PAUSED) {
+      resumeRecommendPipelineRunTool({ args: { run_id: normalizedRunId } });
+    }
+    await sleepMs(1000);
+  }
   return { ok: true };
 }
-
+
 async function handleStartRunTool({ workspaceRoot, args }) {
-  return startRecommendPipelineRunTool({ workspaceRoot, args });
+  if (!shouldStartRecommendDetached()) {
+    return startRecommendPipelineRunTool({ workspaceRoot, args });
+  }
+
+  const prepared = prepareRecommendPipelineRunTool({ workspaceRoot, args });
+  if (prepared.status !== "READY") return prepared;
+
+  cleanupExpiredRuns();
+  const runId = createDetachedRecommendRunId();
+  try {
+    initializeRunStateOrThrow(runId, RUN_MODE_ASYNC, workspaceRoot, args, process.pid);
+  } catch (error) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "RUN_STATE_IO_ERROR",
+        message: `无法写入运行状态目录：${error.message || "unknown"}`,
+        retryable: false
+      }
+    };
+  }
+
+  let worker;
+  try {
+    worker = launchDetachedRunWorker({ runId });
+    safeUpdateRunState(runId, { pid: worker.pid || process.pid });
+  } catch (error) {
+    const failed = buildWorkerLaunchFailedPayload(error?.message || "无法启动 detached recommend worker。");
+    safeUpdateRunState(runId, {
+      state: RUN_STATE_FAILED,
+      stage: RUN_STAGE_PREFLIGHT,
+      last_message: failed.error.message,
+      error: failed.error,
+      result: failed
+    });
+    return failed;
+  }
+
+  const run = readRunState(runId);
+  return {
+    status: "ACCEPTED",
+    run_id: runId,
+    state: "queued",
+    run,
+    poll_after_sec: getRecommendedPollAfterSec(args),
+    message: getDefaultAcceptedMessage(args),
+    post_action: prepared.post_action,
+    target_count_semantics: prepared.target_count_semantics,
+    review: prepared.review
+  };
 }
 
 function handleGetRunTool(args) {
   return getRecommendPipelineRunTool({ args });
 }
 
+function patchDetachedRecommendControl(args, controlPatch, {
+  status,
+  message,
+  lastMessage
+} = {}) {
+  const runId = normalizeText(args?.run_id || args?.runId || "");
+  if (!runId) return null;
+  const current = readRawRunState(runId);
+  const state = normalizeText(current?.state || current?.status || "");
+  if (!current || TERMINAL_RUN_STATES.has(state)) return null;
+  const patched = patchRawRunState(runId, {
+    last_message: lastMessage || message || current.last_message || "",
+    control: controlPatch
+  });
+  if (!patched) return null;
+  return {
+    status,
+    run: patched,
+    message,
+    persistence: {
+      source: "disk",
+      active_control_available: false,
+      detached_control_requested: true
+    },
+    runtime_evaluate_used: false,
+    method_summary: {},
+    method_log: [],
+    chrome: null
+  };
+}
+
 function handleCancelRunTool(args) {
-  return cancelRecommendPipelineRunTool({ args });
+  const result = cancelRecommendPipelineRunTool({ args });
+  if (result?.status === "RUN_STATUS" && result?.persistence?.active_control_available === false) {
+    return patchDetachedRecommendControl(args, {
+      pause_requested: true,
+      pause_requested_at: new Date().toISOString(),
+      pause_requested_by: TOOL_CANCEL_RUN,
+      cancel_requested: true
+    }, {
+      status: "CANCEL_REQUESTED",
+      message: "已收到取消请求，将由 detached worker 在下一个安全边界停止。",
+      lastMessage: "已收到取消请求，将由 detached worker 在下一个安全边界停止。"
+    }) || result;
+  }
+  return result;
 }
 
 function handlePauseRunTool(args) {
-  return pauseRecommendPipelineRunTool({ args });
+  const result = pauseRecommendPipelineRunTool({ args });
+  if (result?.status === "RUN_STATUS" && result?.persistence?.active_control_available === false) {
+    return patchDetachedRecommendControl(args, {
+      pause_requested: true,
+      pause_requested_at: new Date().toISOString(),
+      pause_requested_by: TOOL_PAUSE_RUN,
+      cancel_requested: false
+    }, {
+      status: "PAUSE_REQUESTED",
+      message: "暂停请求已写入 detached run 控制文件。",
+      lastMessage: "暂停请求已写入 detached run 控制文件。"
+    }) || result;
+  }
+  return result;
 }
 
 function handleResumeRunTool(args) {
-  return resumeRecommendPipelineRunTool({ args });
+  const result = resumeRecommendPipelineRunTool({ args });
+  if (result?.status === "FAILED" && result?.error?.code === "RUN_NOT_ACTIVE") {
+    return patchDetachedRecommendControl(args, {
+      pause_requested: false,
+      pause_requested_at: null,
+      pause_requested_by: null,
+      cancel_requested: false
+    }, {
+      status: "RESUME_REQUESTED",
+      message: "恢复请求已写入 detached run 控制文件。",
+      lastMessage: "恢复请求已写入 detached run 控制文件。"
+    }) || result;
+  }
+  return result;
 }
 
 function handleGetFeaturedCalibrationStatusTool(workspaceRoot) {

package/src/recommend-mcp.js

@@ -140,6 +140,15 @@ function clonePlain(value, fallback = null) {
   }
 }
 
+function plainRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function nonEmptyRecord(value) {
+  const record = plainRecord(value);
+  return Object.keys(record).length ? record : null;
+}
+
 function normalizeRunId(runId) {
   const normalized = normalizeText(runId);
   if (!normalized || normalized.includes("/") || normalized.includes("\\")) return "";
@@ -191,11 +200,29 @@ function recommendSearchParamsForCsv(searchParams = {}) {
   };
 }
 
-function selectedRecommendJobForCsv(meta = {}) {
+function getSnapshotRequestContext(snapshot = {}) {
+  const context = plainRecord(snapshot?.context);
+  const shared = plainRecord(context.shared_run_context);
+  return {
+    context,
+    confirmation: nonEmptyRecord(context.confirmation) || plainRecord(shared.confirmation),
+    overrides: nonEmptyRecord(context.overrides) || plainRecord(shared.overrides),
+    followUp: context.follow_up ?? shared.follow_up ?? null,
+    shared
+  };
+}
+
+function selectedRecommendJobForCsv(meta = {}, snapshot = {}) {
+  const { confirmation, overrides, shared } = getSnapshotRequestContext(snapshot);
   const value = normalizeText(
     meta.args?.confirmation?.job_value
     || meta.normalized?.job
     || meta.args?.overrides?.job
+    || confirmation.job_value
+    || overrides.job
+    || shared.confirmation?.job_value
+    || shared.overrides?.job
+    || shared.job_label
     || ""
   );
   return {
@@ -206,21 +233,28 @@ function selectedRecommendJobForCsv(meta = {}) {
 }
 
 function buildRecommendCsvInputRows(snapshot = {}, meta = {}) {
-  const searchParams = recommendSearchParamsForCsv(meta.parsed?.searchParams || {});
-  const screenParams = meta.parsed?.screenParams || {};
+  const { context, confirmation, overrides, followUp, shared } = getSnapshotRequestContext(snapshot);
+  const searchParams = recommendSearchParamsForCsv(meta.parsed?.searchParams || {
+    school_tag: overrides.school_tag ?? confirmation.school_tag_value,
+    degree: overrides.degree ?? confirmation.degree_value,
+    gender: overrides.gender ?? confirmation.gender_value,
+    recent_not_view: overrides.recent_not_view ?? confirmation.recent_not_view_value
+  });
+  const parsedScreenParams = meta.parsed?.screenParams || {};
+  const screenParams = {
+    criteria: parsedScreenParams.criteria || meta.normalized?.criteria || overrides.criteria || "",
+    target_count: parsedScreenParams.target_count || snapshot.progress?.target_count || meta.normalized?.targetCount || overrides.target_count || confirmation.target_count_value || shared.max_candidates || "",
+    post_action: parsedScreenParams.post_action || overrides.post_action || confirmation.post_action_value || shared.post_action || "none",
+    max_greet_count: parsedScreenParams.max_greet_count ?? overrides.max_greet_count ?? confirmation.max_greet_count_value ?? shared.max_greet_count ?? ""
+  };
   return buildLegacyScreenInputRows({
-    instruction: meta.args?.instruction || "",
+    instruction: meta.args?.instruction || context.instruction || shared.instruction || "",
     selectedPage: "recommend",
-    selectedJob: selectedRecommendJobForCsv(meta),
+    selectedJob: selectedRecommendJobForCsv(meta, snapshot),
     userSearchParams: cloneReportInput(searchParams, {}),
     effectiveSearchParams: cloneReportInput(searchParams, {}),
-    screenParams: {
-      criteria: screenParams.criteria || meta.normalized?.criteria || "",
-      target_count: screenParams.target_count || snapshot.progress?.target_count || meta.normalized?.targetCount || "",
-      post_action: screenParams.post_action || "none",
-      max_greet_count: screenParams.max_greet_count ?? ""
-    },
-    followUp: meta.args?.follow_up || meta.args?.overrides?.follow_up || null
+    screenParams,
+    followUp: meta.args?.follow_up || meta.args?.overrides?.follow_up || followUp || overrides.follow_up || null
   });
 }
 
@@ -237,6 +271,16 @@ function readRecommendRunState(runId) {
   return readJsonFile(artifacts.run_state_path);
 }
 
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function getRecommendRunMeta(runId) {
   return recommendRunMeta.get(runId) || {};
 }
@@ -475,12 +519,14 @@ function normalizeRunSnapshot(snapshot) {
     || snapshot.status === RUN_STATUS_PAUSED
   ) ? buildLegacyRecommendResult({ ...snapshot, progress }) : null;
   const recovery = buildConstrainedAgentRecovery(snapshot, meta, artifacts);
+  const snapshotContext = plainRecord(snapshot.context);
+  const metaArgs = plainRecord(meta.args);
   const oldContext = {
-    workspace_root: meta.workspaceRoot || null,
-    instruction: meta.args?.instruction || "",
-    confirmation: clonePlain(meta.args?.confirmation || {}, {}),
-    overrides: clonePlain(meta.args?.overrides || {}, {}),
-    follow_up: clonePlain(meta.args?.follow_up || {}, {}),
+    workspace_root: meta.workspaceRoot || snapshotContext.workspace_root || null,
+    instruction: metaArgs.instruction || snapshotContext.instruction || "",
+    confirmation: clonePlain(metaArgs.confirmation ?? snapshotContext.confirmation ?? {}, {}),
+    overrides: clonePlain(metaArgs.overrides ?? snapshotContext.overrides ?? {}, {}),
+    follow_up: clonePlain(metaArgs.follow_up ?? snapshotContext.follow_up ?? null, null),
     target_count_semantics: TARGET_COUNT_SEMANTICS
   };
   return {
@@ -494,12 +540,12 @@ function normalizeRunSnapshot(snapshot) {
     updated_at: snapshot.updatedAt,
     completed_at: toIsoOrNull(snapshot.completedAt),
     heartbeat_at: snapshot.updatedAt,
-    pid: process.pid || null,
+    pid: Number.isInteger(snapshot.pid) && snapshot.pid > 0 ? snapshot.pid : process.pid || null,
     last_message: snapshot.error?.message || snapshot.phase || null,
     context: {
-      ...(snapshot.context || {}),
+      ...snapshotContext,
       ...oldContext,
-      shared_run_context: snapshot.context || {}
+      shared_run_context: snapshotContext
     },
     control: {
       pause_requested: snapshot.status === RUN_STATUS_PAUSED,
@@ -521,6 +567,41 @@ 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,
+      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
+    };
+  }
+  if (existingControl.pause_requested === true && normalized.state !== RUN_STATUS_PAUSED) {
+    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 || "pause_recommend_pipeline_run"
+    };
+  }
+  if (existingControl.pause_requested === false && normalized.state === RUN_STATUS_PAUSED) {
+    return {
+      ...control,
+      pause_requested: false,
+      pause_requested_at: null,
+      pause_requested_by: null,
+      cancel_requested: false
+    };
+  }
+  return control;
+}
+
 function persistRecommendRunSnapshot(snapshot, {
   persistActiveCheckpoint = false
 } = {}) {
@@ -528,6 +609,8 @@ function persistRecommendRunSnapshot(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);
   }
@@ -557,6 +640,38 @@ function persistRecommendRunSnapshot(snapshot, {
   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;
+  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({
+    runId,
+    name: persisted.name || runId,
+    status: RUN_STATUS_FAILED,
+    phase: persisted.stage || persisted.phase || "recommend:orphaned",
+    progress: persisted.progress || {},
+    context: persisted.context || {},
+    checkpoint: checkpoint || persisted.checkpoint || {},
+    startedAt: persisted.started_at || persisted.startedAt || now,
+    updatedAt: now,
+    completedAt: now,
+    pid: Number.isInteger(persisted.pid) && persisted.pid > 0 ? persisted.pid : null,
+    error,
+    summary: persisted.summary || null
+  });
+}
+
 function persistRecommendLifecycleSnapshot(snapshot, event = {}) {
   return persistRecommendRunSnapshot(snapshot, {
     persistActiveCheckpoint: event?.type === "checkpoint"
@@ -1154,6 +1269,47 @@ function getRunOptions(args, parsed, normalized, session, configResolution = nul
   };
 }
 
+function prepareRecommendPipelineStart(args = {}, { workspaceRoot = "" } = {}) {
+  const parsed = parseRecommendPipelineRequest(args);
+  const gate = evaluateRecommendPipelineGate(parsed, args);
+  if (gate) return { response: gate };
+  const configResolution = resolveBossScreeningConfig(workspaceRoot);
+  const normalized = normalizeRecommendStartInput(args, parsed, configResolution);
+  const debugTestOptions = collectRecommendDebugTestOptions(args, normalized);
+  if (debugTestOptions.length && !isDebugTestMode(args)) {
+    return {
+      response: {
+        status: "FAILED",
+        error: {
+          code: "DEBUG_TEST_MODE_REQUIRED",
+          message: `这些参数属于调试/测试路径，正式 live run 不会默认启用：${debugTestOptions.join(", ")}。如确需测试，请显式传 debug_test_mode=true。`,
+          retryable: false
+        },
+        debug_test_options: debugTestOptions
+      }
+    };
+  }
+  if (normalized.screeningMode === "llm" && !configResolution.ok) {
+    return {
+      response: {
+        status: "FAILED",
+        error: {
+          code: "SCREEN_CONFIG_ERROR",
+          message: configResolution.error?.message || "screening-config.json is required for LLM screening.",
+          retryable: true
+        },
+        config_path: configResolution.config_path || null,
+        candidate_paths: configResolution.candidate_paths || []
+      }
+    };
+  }
+  return {
+    parsed,
+    configResolution,
+    normalized
+  };
+}
+
 async function closeRecommendRunSession(runId) {
   const meta = recommendRunMeta.get(runId);
   if (!meta || meta.closed) return;
@@ -1199,34 +1355,19 @@ function trackRecommendRun(runId) {
     });
 }
 
-async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = "" } = {}) {
-  const parsed = parseRecommendPipelineRequest(args);
-  const gate = evaluateRecommendPipelineGate(parsed, args);
-  if (gate) return gate;
-  const configResolution = resolveBossScreeningConfig(workspaceRoot);
-  const normalized = normalizeRecommendStartInput(args, parsed, configResolution);
-  const debugTestOptions = collectRecommendDebugTestOptions(args, normalized);
-  if (debugTestOptions.length && !isDebugTestMode(args)) {
+async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = "", runId = "" } = {}) {
+  const prepared = prepareRecommendPipelineStart(args, { workspaceRoot });
+  if (prepared.response) return prepared.response;
+  const { parsed, configResolution, normalized } = prepared;
+  const fixedRunId = normalizeRunId(runId);
+  if (runId && !fixedRunId) {
     return {
       status: "FAILED",
       error: {
-        code: "DEBUG_TEST_MODE_REQUIRED",
-        message: `这些参数属于调试/测试路径，正式 live run 不会默认启用：${debugTestOptions.join(", ")}。如确需测试，请显式传 debug_test_mode=true。`,
+        code: "INVALID_RUN_ID",
+        message: "run_id is invalid",
         retryable: false
-      },
-      debug_test_options: debugTestOptions
-    };
-  }
-  if (normalized.screeningMode === "llm" && !configResolution.ok) {
-    return {
-      status: "FAILED",
-      error: {
-        code: "SCREEN_CONFIG_ERROR",
-        message: configResolution.error?.message || "screening-config.json is required for LLM screening.",
-        retryable: true
-      },
-      config_path: configResolution.config_path || null,
-      candidate_paths: configResolution.candidate_paths || []
+      }
     };
   }
 
@@ -1260,7 +1401,11 @@ async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = ""
 
   let started;
   try {
-    started = recommendRunService.startRecommendRun(getRunOptions(args, parsed, normalized, session, configResolution));
+    started = recommendRunService.startRecommendRun({
+      ...getRunOptions(args, parsed, normalized, session, configResolution),
+      runId: fixedRunId || undefined,
+      pid: process.pid
+    });
   } catch (error) {
     await session.close?.();
     return {
@@ -1311,8 +1456,24 @@ async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = ""
   };
 }
 
-export async function startRecommendPipelineRunTool({ workspaceRoot = "", args = {} } = {}) {
-  const started = await startRecommendPipelineRunInternal(args, { workspaceRoot });
+export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {} } = {}) {
+  const prepared = prepareRecommendPipelineStart(args, { workspaceRoot });
+  if (prepared.response) return prepared.response;
+  const { parsed, normalized } = prepared;
+  return {
+    status: "READY",
+    review: parsed.review,
+    post_action: {
+      requested: normalized.postAction,
+      execute_post_action: args.dry_run_post_action === true ? false : args.execute_post_action !== false,
+      max_greet_count: normalized.maxGreetCount
+    },
+    target_count_semantics: TARGET_COUNT_SEMANTICS
+  };
+}
+
+export async function startRecommendPipelineRunTool({ workspaceRoot = "", args = {}, runId = "" } = {}) {
+  const started = await startRecommendPipelineRunInternal(args, { workspaceRoot, runId });
   if (started.status !== "ACCEPTED") return started;
   return attachMethodEvidence(started, started.run_id);
 }
@@ -1339,12 +1500,14 @@ export function getRecommendPipelineRunTool({ args = {} } = {}) {
   } catch {
     const persisted = readRecommendRunState(runId);
     if (persisted) {
+      const reconciled = reconcilePersistedRecommendRunIfNeeded(persisted);
       return {
         status: "RUN_STATUS",
-        run: persisted,
+        run: reconciled,
         persistence: {
           source: "disk",
-          active_control_available: false
+          active_control_available: false,
+          stale_process_reconciled: reconciled?.state !== persisted.state
         },
         runtime_evaluate_used: false,
         method_summary: {},