@reconcrap/boss-recommend-mcp 2.1.2 → 2.1.3

package/README.md

@@ -83,6 +83,8 @@ MCP 工具：
 
 - `list_recommend_jobs`（只读读取推荐页岗位下拉框，返回可直接用于 cron/一次性任务的 `job_names`）
 - `prepare_recommend_pipeline_run`（只校验完整 payload 是否已可用于 cron/一次性任务；不启动筛选，返回 `READY + cron_ready=true` 后才应创建 cron）
+- `schedule_recommend_pipeline_run`（创建 package-owned 定时任务；保存已 READY 的完整 payload，启动 detached scheduler，到点后直接调用 `start_recommend_pipeline_run`）
+- `get_recommend_scheduled_run`（查询 package-owned 定时任务；到点后会显示内层 `run_id` 和 run 快照）
 - `start_recommend_pipeline_run`（异步启动；同样先经过前置门禁，通过后返回 run_id）
 - `get_recommend_pipeline_run`（轮询 run_id 状态）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
@@ -120,15 +122,18 @@ Cron / 一次性定时任务设置建议先在设置阶段完成 Chrome/登录/
 
 ```bash
 boss-recommend-mcp prepare-run --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --slow-live --port 9222
+boss-recommend-mcp schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --slow-live --port 9222
+boss-recommend-mcp schedule-status --schedule-id <schedule_id>
 ```
 
-只有输出 `status: "READY"` 且 `cron_ready: true` 后，才把同一份 payload 写入 cron 并在到点时调用 `start_recommend_pipeline_run` / `boss-recommend-mcp run --detached`。如果设置阶段返回 `BOSS_LOGIN_REQUIRED`、`NEED_INPUT` 或 `NEED_CONFIRMATION`，先让用户登录或补齐确认，不要创建 cron。
+只有 `prepare-run` 输出 `status: "READY"` 且 `cron_ready: true` 后，才继续调用 `schedule-run`。只有 `schedule-run` 输出 `status: "SCHEDULED"` 且带有 `schedule_id` 后，才算定时任务真的创建成功。不要让外部 AI harness 自己拼 `/tmp/*.log` shell cron 或未来对话提醒；那类 cron 容易丢失 JSON/file 参数并在到点后重新卡确认门禁。
 
 状态机：
 
 - `NEED_INPUT`
 - `NEED_CONFIRMATION`
 - `READY`（仅准备工具）
+- `SCHEDULED`（仅定时工具）
 - `COMPLETED`
 - `FAILED`
 
@@ -269,6 +274,16 @@ npx -y @reconcrap/boss-recommend-mcp@latest run --detached --instruction-file bo
 
 `--detached` 会让父进程输出 `ACCEPTED + run_id` 后退出，子进程继续持有 Chrome DevTools 会话并执行长任务。岗位发现可以使用只读 CLI：
 
+如果是稍后启动/cron/定时任务，不要手写系统 cron；用 package-owned scheduler：
+
+```bash
+npx -y @reconcrap/boss-recommend-mcp@latest prepare-run --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --slow-live --port 9222
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --slow-live --port 9222
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <schedule_id>
+```
+
+`schedule-run` 会保存同一份已验证 payload 并启动 detached scheduler worker；到点后 worker 会直接调用包内 `start_recommend_pipeline_run`，不会重新让 AI harness 拼参数。
+
 ```bash
 npx -y @reconcrap/boss-recommend-mcp@latest list-jobs --slow-live --port 9222
 # 源码模式（GitHub clone 后）
@@ -463,6 +478,7 @@ Trae-CN / 长对话防循环建议：
 
 - `start_recommend_pipeline_run` 为异步入口，但不会跳过同步确认流程。
 - `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 用于 cron 设置阶段；它不启动筛选，只确认 payload 已经不需要到点后再问用户。
+- `schedule_recommend_pipeline_run` / `boss-recommend-mcp schedule-run` 是推荐页定时启动的唯一推荐路径；它创建真实 package-owned detached scheduler，并返回 `schedule_id`。
 - 定时心跳默认 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.2",
+  "version": "2.1.3",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",
@@ -79,11 +79,11 @@
     "live:chat-image-screening": "node scripts/live-chat-image-screening-smoke.js"
   },
   "files": [
-    "bin",
-    "config/screening-config.example.json",
-    "skills",
-    "scripts/install-macos.sh",
-    "scripts/postinstall.cjs",
+    "bin",
+    "config/screening-config.example.json",
+    "skills",
+    "scripts/install-macos.sh",
+    "scripts/postinstall.cjs",
     "src/core",
     "src/domains",
     "src/chat-mcp.js",
@@ -93,6 +93,7 @@
     "src/index.js",
     "src/parser.js",
     "src/recommend-mcp.js",
+    "src/recommend-scheduler.js",
     "src/recruit-mcp.js",
     "src/run-state.js",
     "README.md"

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

@@ -94,8 +94,14 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 限制：只读岗位列表，不启动筛选任务；若返回 `BOSS_LOGIN_REQUIRED`，必须让用户在自动打开的 Chrome 完成登录后重试，本次 cron 不得创建。
 - Cron 准备工具：`prepare_recommend_pipeline_run`
   - 用途：只校验参数是否已可用于 cron / 一次性任务，不启动筛选任务。
-  - 要求：只有返回 `status=READY` 且 `cron_ready=true` 后，才允许创建 cron。
+  - 要求：只有返回 `status=READY` 且 `cron_ready=true` 后，才允许继续创建定时任务。
   - 若返回 `NEED_INPUT` / `NEED_CONFIRMATION` / `FAILED`：继续补齐 `pending_questions` 或修复登录/页面/config；不得先创建 cron。
+- Cron 创建工具：`schedule_recommend_pipeline_run`
+  - 用途：保存已经 READY 的完整 payload，并启动 package-owned detached scheduler；到点后由包内 worker 直接调用 `start_recommend_pipeline_run`。
+  - 必填：同 `start_recommend_pipeline_run` 的完整 payload，另加 `schedule_delay_minutes` / `schedule_delay_seconds` / `schedule_run_at` 之一。
+  - 成功标准：必须返回 `status=SCHEDULED`、`schedule_created=true`、`schedule_id`、`run_at`。只有这个返回后，才可以告诉用户定时任务已创建。
+- Cron 查询工具：`get_recommend_scheduled_run`
+  - 用途：用户问“任务是否启动/进度”时，先查 `schedule_id`。若到点后已启动，会返回内层 `run_id` 和 run 快照。
 - 主工具：`start_recommend_pipeline_run`
 - 必填：`instruction`
 - 关键输入：
@@ -119,16 +125,30 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 2. 收集 Stage A 全部筛选项、`target_count`、`post_action`、`max_greet_count`（如需要）和本次 `rest_level`。
 3. 调用 `list_recommend_jobs`；若 Chrome 未打开，工具会尝试自动打开本机 9222 Chrome 并进入推荐页。若返回 `BOSS_LOGIN_REQUIRED` 或页面不可用，停止 cron 创建，让用户登录/修复后重试。
 4. 用 `job_names` 中的精确岗位名完成岗位确认，并完成最终总确认，写入 `job_confirmed=true` 与 `final_confirmed=true`。
-5. 调用 `prepare_recommend_pipeline_run` 传入将来要执行的完整 payload；只有 `READY + cron_ready=true` 才能创建 cron。
-6. cron 到点时只调用 `start_recommend_pipeline_run`，并传入准备阶段验证过的同一份 payload。到点后若 Chrome/登录异常，应作为运行失败处理，不得再向用户追问参数。
+5. 调用 `prepare_recommend_pipeline_run` 传入将来要执行的完整 payload；只有 `READY + cron_ready=true` 才能继续。
+6. 立即调用 `schedule_recommend_pipeline_run`，传入同一份完整 payload 和 `schedule_delay_minutes` / `schedule_run_at`。禁止让 OpenClaw 自己写 `/tmp/*.log` shell cron、自然语言提醒、或未来对话回调来代替此工具。
+7. 只有拿到 `SCHEDULED + schedule_id` 后才告诉用户定时任务已创建。回复必须包含 `schedule_id`，而不是只说“10 分钟后会启动”。
+8. 到点后由 package-owned detached scheduler 启动；若 Chrome/登录异常，应作为 schedule/run 失败处理，不得再向用户追问参数。
 
-Shell-only OpenClaw/QClaw cron 设置同样先运行：
+Shell-only OpenClaw/QClaw cron 设置同样先运行 prepare：
 
 ```powershell
 npx -y @reconcrap/boss-recommend-mcp@latest prepare-run --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --slow-live --port 9222
 ```
 
-仅当上述命令输出 `READY` 且 `cron_ready=true` 后，才把对应的 detached `run` 命令写入 cron。
+仅当上述命令输出 `READY` 且 `cron_ready=true` 后，才允许继续创建定时任务。
+
+然后必须用 package-owned scheduler 创建定时任务，不要手写系统 cron：
+
+```powershell
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-run --schedule-delay-minutes 10 --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --slow-live --port 9222
+```
+
+用户查询时：
+
+```powershell
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <schedule_id>
+```
 
 ## Async Run Policy
 
@@ -173,14 +193,15 @@ npx -y @reconcrap/boss-recommend-mcp@latest prepare-run --instruction-file .\bos
 推荐做法：
 
 1. 将锁定的用户原文写入 instruction 文件，将已确认参数写入 `overrides` 与 `confirmation` JSON 文件。
-2. 先用 `prepare-run` 校验完整 payload 已 cron-ready；未返回 `READY + cron_ready=true` 不得创建 cron 或启动 run。
-3. 用 detached CLI 启动，让父命令返回启动证据，子进程继续持有 CDP 会话：
+2. 先用 `prepare-run` 校验完整 payload 已 cron-ready；未返回 `READY + cron_ready=true` 不得创建定时任务或启动 run。
+3. 若用户要“现在启动”，用 detached CLI 启动，让父命令返回启动证据，子进程继续持有 CDP 会话：
 
 ```powershell
 npx -y @reconcrap/boss-recommend-mcp@latest run --detached --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --slow-live --port 9222
 ```
 
-4. 若返回 `ACCEPTED + run_id`，即任务已启动；记录 `run_id/stdout_path/stderr_path`。若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`，说明 cron 设置阶段漏掉了准备门禁，应回到 `prepare-run` 补齐，不能在到点后继续问用户确认。
+4. 若用户要“稍后/cron/定时启动”，用 `schedule-run`，不是 `run --detached`。若 `schedule-run` 未返回 `SCHEDULED + schedule_id`，不得告诉用户定时任务已创建。
+5. 若即时 `run --detached` 返回 `ACCEPTED + run_id`，即任务已启动；记录 `run_id/stdout_path/stderr_path`。若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`，说明设置阶段漏掉了准备门禁，应回到 `prepare-run` 补齐，不能在到点后继续问用户确认。
 
 兼容路径：
 

package/src/cli.js

@@ -28,6 +28,10 @@ import {
   prepareRecommendPipelineRunTool,
   startRecommendPipelineRunTool
 } from "./recommend-mcp.js";
+import {
+  getRecommendScheduledRunTool,
+  scheduleRecommendPipelineRunTool
+} from "./recommend-scheduler.js";
 import {
   getBossScreenConfigResolution,
   resolveBossChatRuntimeLayout as resolveCdpBossChatRuntimeLayout,
@@ -2694,6 +2698,8 @@ function printHelp() {
   console.log("  boss-recommend-mcp              Start the MCP server");
   console.log("  boss-recommend-mcp start        Start the MCP server");
   console.log("  boss-recommend-mcp prepare-run  Validate a cron-ready recommend run payload without starting screening");
+  console.log("  boss-recommend-mcp schedule-run Create a package-owned delayed recommend run");
+  console.log("  boss-recommend-mcp schedule-status Check a package-owned delayed recommend run");
   console.log("  boss-recommend-mcp run          Start a CDP-only recommend run through the shared run service");
   console.log("  boss-recommend-mcp list-jobs    CDP-only list of exact recommend job names for cron/one-shot inputs");
   console.log("  boss-recommend-mcp chat <subcommand>  Run CDP-only boss-chat health/prepare/status commands");
@@ -2711,6 +2717,8 @@ function printHelp() {
   console.log("");
   console.log("Run command:");
   console.log("  boss-recommend-mcp prepare-run --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
+  console.log("  boss-recommend-mcp schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file overrides.json --confirmation-file confirmation.json");
+  console.log("  boss-recommend-mcp schedule-status --schedule-id <id>");
   console.log("  boss-recommend-mcp run --instruction \"推荐页上筛选211男生，近14天没有，有大模型平台经验\" --overrides-file overrides.json --confirmation-file confirmation.json");
   console.log("  boss-recommend-mcp run --detached --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
   console.log("  boss-recommend-mcp list-jobs --slow-live --port 9222");
@@ -2907,6 +2915,62 @@ async function preparePipelineOnce(options = {}) {
   }
 }
 
+function addScheduleOptions(args, options = {}) {
+  const scheduleId = String(options["schedule-id"] || options.schedule_id || options.scheduleId || "").trim();
+  if (scheduleId) args.schedule_id = scheduleId;
+  const runAt = String(options["schedule-run-at"] || options.schedule_run_at || options.scheduleRunAt || options["run-at"] || options.run_at || "").trim();
+  if (runAt) args.schedule_run_at = runAt;
+  const delayMinutes = parseNonNegativeInteger(options["schedule-delay-minutes"] ?? options.schedule_delay_minutes ?? options.scheduleDelayMinutes);
+  if (delayMinutes !== undefined) args.schedule_delay_minutes = delayMinutes;
+  const delaySeconds = parseNonNegativeInteger(options["schedule-delay-seconds"] ?? options.schedule_delay_seconds ?? options.scheduleDelaySeconds);
+  if (delaySeconds !== undefined) args.schedule_delay_seconds = delaySeconds;
+  return args;
+}
+
+async function schedulePipelineOnce(options = {}) {
+  const workspaceRoot = getWorkspaceRoot(options);
+  const { args, port } = buildRecommendRunCliInput(options);
+  addScheduleOptions(args, options);
+  const result = await scheduleRecommendPipelineRunTool({
+    workspaceRoot,
+    args
+  });
+  printJson({
+    ...result,
+    cli: {
+      ...(result.cli || {}),
+      command: "schedule-run",
+      cdp_only: true,
+      package_owned_scheduler: true,
+      workspace_root: workspaceRoot,
+      port
+    }
+  });
+  if (result.status !== "SCHEDULED") {
+    process.exitCode = 1;
+  }
+}
+
+function scheduleStatusCli(options = {}) {
+  const scheduleId = String(options["schedule-id"] || options.schedule_id || options.scheduleId || "").trim();
+  const result = getRecommendScheduledRunTool({
+    args: {
+      schedule_id: scheduleId
+    }
+  });
+  printJson({
+    ...result,
+    cli: {
+      command: "schedule-status",
+      cdp_only: true,
+      package_owned_scheduler: true
+    }
+  });
+  if (result.status !== "OK") {
+    process.exitCode = 1;
+  }
+}
+
 async function runPipelineOnce(options = {}) {
   const workspaceRoot = getWorkspaceRoot(options);
   const { args, port } = buildRecommendRunCliInput(options);
@@ -3120,6 +3184,39 @@ export async function runCli(argv = process.argv) {
         process.exitCode = 1;
       }
       break;
+    case "schedule-run":
+    case "schedule":
+      try {
+        await schedulePipelineOnce(options);
+      } catch (error) {
+        printJson({
+          status: "FAILED",
+          schedule_created: false,
+          error: {
+            code: "INVALID_CLI_INPUT",
+            message: error.message || "Invalid CLI input",
+            retryable: false
+          }
+        });
+        process.exitCode = 1;
+      }
+      break;
+    case "schedule-status":
+    case "scheduled-run":
+      try {
+        scheduleStatusCli(options);
+      } catch (error) {
+        printJson({
+          status: "FAILED",
+          error: {
+            code: "INVALID_CLI_INPUT",
+            message: error.message || "Invalid CLI input",
+            retryable: false
+          }
+        });
+        process.exitCode = 1;
+      }
+      break;
     case "list-jobs":
     case "jobs":
     case "recommend-jobs":
@@ -3282,6 +3379,8 @@ export const __testables = {
   resolveBossChatRuntimeLayout: resolveCdpBossChatRuntimeLayout,
   runBossChatCliCommand,
   preparePipelineOnce,
+  schedulePipelineOnce,
+  scheduleStatusCli,
   runPipelineOnce
 };
 

package/src/index.js

@@ -39,6 +39,12 @@ import {
   startRecruitPipelineRunTool,
   validateRecruitPipelineArgs
 } from "./recruit-mcp.js";
+import {
+  __setRecommendSchedulerSpawnForTests,
+  getRecommendScheduledRunTool,
+  runScheduledRecommendWorker,
+  scheduleRecommendPipelineRunTool
+} from "./recommend-scheduler.js";
 import {
   __resetRecommendMcpStateForTests,
   __setRecommendMcpConnectorForTests,
@@ -90,6 +96,8 @@ const require = createRequire(import.meta.url);
 const { version: SERVER_VERSION } = require("../package.json");
 
 const TOOL_PREPARE_RUN = "prepare_recommend_pipeline_run";
+const TOOL_SCHEDULE_RUN = "schedule_recommend_pipeline_run";
+const TOOL_GET_SCHEDULED_RUN = "get_recommend_scheduled_run";
 const TOOL_START_RUN = "start_recommend_pipeline_run";
 const TOOL_GET_RUN = "get_recommend_pipeline_run";
 const TOOL_CANCEL_RUN = "cancel_recommend_pipeline_run";
@@ -1083,6 +1091,36 @@ function createListRecommendJobsInputSchema() {
   };
 }
 
+function createScheduleRunInputSchema() {
+  const base = createRunInputSchema();
+  return {
+    ...base,
+    properties: {
+      ...base.properties,
+      schedule_id: {
+        type: "string",
+        description: "可选，自定义定时任务 id；默认自动生成"
+      },
+      schedule_run_at: {
+        type: "string",
+        description: "ISO 时间字符串；到点后由 package-owned detached scheduler 启动已准备好的 payload"
+      },
+      schedule_delay_minutes: {
+        type: "number",
+        minimum: 0,
+        description: "从现在开始延迟多少分钟后启动；适合 OpenClaw cron/定时任务设置"
+      },
+      schedule_delay_seconds: {
+        type: "number",
+        minimum: 0,
+        description: "从现在开始延迟多少秒后启动；主要用于短延迟或测试"
+      }
+    },
+    required: ["instruction"],
+    additionalProperties: false
+  };
+}
+
 function createToolsSchema() {
   return [
     {
@@ -1095,6 +1133,23 @@ function createToolsSchema() {
       description: "只校验 Boss 推荐页流水线参数是否已可用于 cron/一次性任务；不会启动筛选任务。只有返回 READY/cron_ready=true 后才应创建定时任务。",
       inputSchema: createRunInputSchema()
     },
+    {
+      name: TOOL_SCHEDULE_RUN,
+      description: "创建 package-owned Boss 推荐页定时任务：先校验 READY/cron_ready，再保存完整 payload，并由 detached scheduler 到点直接启动，不再依赖 AI harness 自己拼 shell cron。",
+      inputSchema: createScheduleRunInputSchema()
+    },
+    {
+      name: TOOL_GET_SCHEDULED_RUN,
+      description: "查询 package-owned 推荐页定时任务状态；返回 schedule_id、worker 状态、到点后启动的 run_id 与运行快照。",
+      inputSchema: {
+        type: "object",
+        properties: {
+          schedule_id: { type: "string" }
+        },
+        required: ["schedule_id"],
+        additionalProperties: false
+      }
+    },
     {
       name: TOOL_START_RUN,
       description: "异步启动 Boss 推荐页流水线（含同步门禁预检）；只有在前置确认与页面就绪通过后才返回 run_id。",
@@ -2626,6 +2681,10 @@ async function handleRequest(message, workspaceRoot) {
         payload = await listRecommendJobsTool({ workspaceRoot, args });
       } else if (toolName === TOOL_PREPARE_RUN) {
         payload = prepareRecommendPipelineRunTool({ workspaceRoot, args });
+      } else if (toolName === TOOL_SCHEDULE_RUN) {
+        payload = await scheduleRecommendPipelineRunTool({ workspaceRoot, args });
+      } else if (toolName === TOOL_GET_SCHEDULED_RUN) {
+        payload = getRecommendScheduledRunTool({ args });
       } else if (toolName === TOOL_START_RUN) {
         payload = await handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_RUN) {
@@ -2825,6 +2884,12 @@ export const __testables = {
   resetRecommendMcpStateForTests() {
     __resetRecommendMcpStateForTests();
   },
+  setRecommendSchedulerSpawnForTests(nextImpl) {
+    __setRecommendSchedulerSpawnForTests(nextImpl);
+  },
+  runScheduledRecommendWorkerForTests(options = {}) {
+    return runScheduledRecommendWorker(options);
+  },
   setChatMcpConnectorForTests(nextImpl) {
     forceChatInProcForTests = typeof nextImpl === "function";
     __setChatMcpConnectorForTests(nextImpl);

package/src/recommend-scheduler.js

@@ -0,0 +1,482 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { getStateHome } from "./run-state.js";
+import {
+  getRecommendPipelineRunTool,
+  prepareRecommendPipelineRunTool,
+  startRecommendPipelineRunTool
+} from "./recommend-mcp.js";
+
+const SCHEDULE_WORKER_FLAG = "--schedule-worker";
+const SCHEDULE_ID_FLAG = "--schedule-id";
+const TERMINAL_SCHEDULE_STATES = new Set(["completed", "failed", "canceled"]);
+const TERMINAL_RUN_STATES = new Set(["completed", "failed", "canceled"]);
+
+let spawnProcessImpl = spawn;
+
+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 nowIso() {
+  return new Date().toISOString();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseNonNegativeNumber(raw, fallback = null) {
+  if (raw === undefined || raw === null || raw === "") return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function parseRunAt(args = {}) {
+  const direct = normalizeText(args.schedule_run_at || args.scheduleRunAt || args.run_at || args.runAt);
+  if (direct) {
+    const timestamp = Date.parse(direct);
+    if (!Number.isFinite(timestamp)) {
+      return {
+        ok: false,
+        error: `Invalid schedule_run_at: ${direct}`
+      };
+    }
+    return {
+      ok: true,
+      runAtMs: timestamp,
+      source: "schedule_run_at"
+    };
+  }
+
+  const delaySeconds = parseNonNegativeNumber(args.schedule_delay_seconds ?? args.scheduleDelaySeconds, null);
+  if (delaySeconds !== null) {
+    return {
+      ok: true,
+      runAtMs: Date.now() + Math.round(delaySeconds * 1000),
+      source: "schedule_delay_seconds"
+    };
+  }
+
+  const delayMinutes = parseNonNegativeNumber(args.schedule_delay_minutes ?? args.scheduleDelayMinutes, null);
+  if (delayMinutes !== null) {
+    return {
+      ok: true,
+      runAtMs: Date.now() + Math.round(delayMinutes * 60 * 1000),
+      source: "schedule_delay_minutes"
+    };
+  }
+
+  return {
+    ok: false,
+    error: "schedule_run_at or schedule_delay_minutes/schedule_delay_seconds is required"
+  };
+}
+
+function safeIdPart(value) {
+  return normalizeText(value).replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+
+function createScheduleId(raw = "") {
+  const requested = safeIdPart(raw);
+  if (requested) return requested;
+  const suffix = Math.random().toString(36).slice(2, 10);
+  return `mcp_recommend_schedule_${Date.now().toString(36)}_${suffix}`;
+}
+
+function getSchedulesDir() {
+  return path.join(getStateHome(), "schedules");
+}
+
+function getScheduleArtifacts(scheduleId) {
+  const id = safeIdPart(scheduleId);
+  if (!id) throw new Error("schedule_id is required");
+  return {
+    schedule_path: path.join(getSchedulesDir(), `${id}.json`),
+    worker_stdout_path: path.join(getSchedulesDir(), `${id}.worker.stdout.log`),
+    worker_stderr_path: path.join(getSchedulesDir(), `${id}.worker.stderr.log`)
+  };
+}
+
+function writeJsonAtomic(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  fs.renameSync(tempPath, filePath);
+  return payload;
+}
+
+function readJsonFile(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readSchedule(scheduleId) {
+  const artifacts = getScheduleArtifacts(scheduleId);
+  return readJsonFile(artifacts.schedule_path);
+}
+
+function writeSchedule(scheduleId, patch) {
+  const artifacts = getScheduleArtifacts(scheduleId);
+  const current = readJsonFile(artifacts.schedule_path) || {};
+  return writeJsonAtomic(artifacts.schedule_path, {
+    ...current,
+    ...patch,
+    schedule_id: scheduleId,
+    updated_at: nowIso()
+  });
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function stripScheduleArgs(args = {}) {
+  const cloned = clonePlain(args, {});
+  for (const key of [
+    "schedule_id",
+    "scheduleId",
+    "schedule_run_at",
+    "scheduleRunAt",
+    "run_at",
+    "runAt",
+    "schedule_delay_seconds",
+    "scheduleDelaySeconds",
+    "schedule_delay_minutes",
+    "scheduleDelayMinutes"
+  ]) {
+    delete cloned[key];
+  }
+  return cloned;
+}
+
+function buildFailedSchedulePayload(error, extra = {}) {
+  return {
+    status: "FAILED",
+    schedule_created: false,
+    error: {
+      code: "RECOMMEND_SCHEDULE_FAILED",
+      message: error?.message || String(error || "Unable to schedule recommend run"),
+      retryable: true
+    },
+    ...extra
+  };
+}
+
+function launchScheduleWorker(scheduleId) {
+  const artifacts = getScheduleArtifacts(scheduleId);
+  fs.mkdirSync(path.dirname(artifacts.worker_stdout_path), { recursive: true });
+  const stdoutFd = fs.openSync(artifacts.worker_stdout_path, "a");
+  const stderrFd = fs.openSync(artifacts.worker_stderr_path, "a");
+  let child;
+  try {
+    child = spawnProcessImpl(process.execPath, [
+      thisFilePath,
+      SCHEDULE_WORKER_FLAG,
+      SCHEDULE_ID_FLAG,
+      scheduleId
+    ], {
+      cwd: process.cwd(),
+      detached: true,
+      stdio: ["ignore", stdoutFd, stderrFd],
+      windowsHide: true,
+      env: process.env
+    });
+  } finally {
+    fs.closeSync(stdoutFd);
+    fs.closeSync(stderrFd);
+  }
+  if (typeof child?.unref === "function") child.unref();
+  return {
+    pid: child.pid || null,
+    stdoutPath: artifacts.worker_stdout_path,
+    stderrPath: artifacts.worker_stderr_path
+  };
+}
+
+export async function scheduleRecommendPipelineRunTool({ workspaceRoot = "", args = {} } = {}) {
+  const runArgs = stripScheduleArgs(args);
+  const prepared = prepareRecommendPipelineRunTool({ workspaceRoot, args: runArgs });
+  if (prepared.status !== "READY" || prepared.cron_ready !== true) {
+    return {
+      ...prepared,
+      status: prepared.status || "FAILED",
+      schedule_created: false,
+      cron_ready: false,
+      message: "Recommend schedule was not created because the run payload is not READY."
+    };
+  }
+
+  const due = parseRunAt(args);
+  if (!due.ok) {
+    return {
+      status: "FAILED",
+      schedule_created: false,
+      cron_ready: true,
+      error: {
+        code: "INVALID_SCHEDULE_TIME",
+        message: due.error,
+        retryable: false
+      },
+      prepare: prepared
+    };
+  }
+
+  const scheduleId = createScheduleId(args.schedule_id || args.scheduleId);
+  const artifacts = getScheduleArtifacts(scheduleId);
+  const runAtIso = new Date(due.runAtMs).toISOString();
+  const createdAt = nowIso();
+  try {
+    writeJsonAtomic(artifacts.schedule_path, {
+      schedule_id: scheduleId,
+      state: "scheduled",
+      status: "scheduled",
+      created_at: createdAt,
+      updated_at: createdAt,
+      run_at: runAtIso,
+      run_at_ms: due.runAtMs,
+      time_source: due.source,
+      workspace_root: path.resolve(workspaceRoot || process.cwd()),
+      args: runArgs,
+      prepare: prepared,
+      worker_stdout_path: artifacts.worker_stdout_path,
+      worker_stderr_path: artifacts.worker_stderr_path,
+      pid: null,
+      run_id: null,
+      run: null,
+      error: null
+    });
+  } catch (error) {
+    return buildFailedSchedulePayload(error, { prepare: prepared });
+  }
+
+  let worker;
+  try {
+    worker = launchScheduleWorker(scheduleId);
+  } catch (error) {
+    writeSchedule(scheduleId, {
+      state: "failed",
+      status: "failed",
+      error: {
+        code: "SCHEDULE_WORKER_LAUNCH_FAILED",
+        message: error?.message || String(error || "Unable to launch schedule worker"),
+        retryable: true
+      }
+    });
+    return buildFailedSchedulePayload(error, {
+      schedule_created: true,
+      schedule_id: scheduleId,
+      schedule: readSchedule(scheduleId),
+      prepare: prepared
+    });
+  }
+
+  const schedule = writeSchedule(scheduleId, {
+    state: "scheduled",
+    status: "scheduled",
+    pid: worker.pid,
+    worker_stdout_path: worker.stdoutPath,
+    worker_stderr_path: worker.stderrPath
+  });
+
+  return {
+    status: "SCHEDULED",
+    schedule_created: true,
+    cron_ready: true,
+    schedule_id: scheduleId,
+    run_at: runAtIso,
+    run_at_ms: due.runAtMs,
+    worker_pid: worker.pid,
+    worker_stdout_path: worker.stdoutPath,
+    worker_stderr_path: worker.stderrPath,
+    schedule,
+    prepare: prepared,
+    message: "Recommend run schedule created. The package-owned detached scheduler will start the prepared payload at run_at."
+  };
+}
+
+export function getRecommendScheduledRunTool({ args = {} } = {}) {
+  const scheduleId = safeIdPart(args.schedule_id || args.scheduleId);
+  if (!scheduleId) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "INVALID_SCHEDULE_ID",
+        message: "schedule_id is required",
+        retryable: false
+      }
+    };
+  }
+  const schedule = readSchedule(scheduleId);
+  if (!schedule) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "SCHEDULE_NOT_FOUND",
+        message: `schedule_id=${scheduleId} not found`,
+        retryable: false
+      }
+    };
+  }
+  let next = schedule;
+  if (!TERMINAL_SCHEDULE_STATES.has(normalizeText(schedule.state || schedule.status)) && schedule.pid && !isProcessAlive(schedule.pid)) {
+    next = writeSchedule(scheduleId, {
+      state: "failed",
+      status: "failed",
+      completed_at: nowIso(),
+      error: {
+        code: "SCHEDULE_WORKER_EXITED",
+        message: `Scheduled worker process exited before reaching a terminal state (pid=${schedule.pid}).`,
+        retryable: true
+      }
+    });
+  }
+  return {
+    status: "OK",
+    schedule_id: scheduleId,
+    schedule: next
+  };
+}
+
+export async function runScheduledRecommendWorker({ scheduleId }) {
+  const normalizedScheduleId = safeIdPart(scheduleId);
+  if (!normalizedScheduleId) return { ok: false, error: "schedule_id is required" };
+  let schedule = readSchedule(normalizedScheduleId);
+  if (!schedule) return { ok: false, error: `schedule_id=${normalizedScheduleId} not found` };
+  const runAtMs = Number(schedule.run_at_ms);
+  if (!Number.isFinite(runAtMs)) {
+    writeSchedule(normalizedScheduleId, {
+      state: "failed",
+      status: "failed",
+      completed_at: nowIso(),
+      error: {
+        code: "INVALID_SCHEDULE_STATE",
+        message: "schedule is missing a valid run_at_ms",
+        retryable: false
+      }
+    });
+    return { ok: false, error: "schedule is missing a valid run_at_ms" };
+  }
+
+  schedule = writeSchedule(normalizedScheduleId, {
+    state: "waiting",
+    status: "waiting",
+    pid: process.pid,
+    worker_started_at: nowIso()
+  });
+
+  while (Date.now() < runAtMs) {
+    await sleep(Math.min(30_000, Math.max(50, runAtMs - Date.now())));
+    const latest = readSchedule(normalizedScheduleId);
+    if (normalizeText(latest?.state) === "canceled") return { ok: true, canceled: true };
+  }
+
+  writeSchedule(normalizedScheduleId, {
+    state: "launching",
+    status: "launching",
+    launch_started_at: nowIso()
+  });
+
+  const started = await startRecommendPipelineRunTool({
+    workspaceRoot: schedule.workspace_root,
+    args: clonePlain(schedule.args, {})
+  });
+  if (started.status !== "ACCEPTED") {
+    writeSchedule(normalizedScheduleId, {
+      state: "failed",
+      status: "failed",
+      completed_at: nowIso(),
+      launch_payload: started,
+      error: started.error || {
+        code: "RECOMMEND_START_NOT_ACCEPTED",
+        message: started.status || "start_recommend_pipeline_run did not return ACCEPTED",
+        retryable: true
+      }
+    });
+    return { ok: false, error: started.error?.message || started.status || "not accepted" };
+  }
+
+  writeSchedule(normalizedScheduleId, {
+    state: "running",
+    status: "running",
+    run_id: started.run_id,
+    run: started.run || null,
+    launch_payload: started,
+    launched_at: nowIso()
+  });
+
+  while (true) {
+    const payload = getRecommendPipelineRunTool({ args: { run_id: started.run_id } });
+    const runState = normalizeText(payload?.run?.state || payload?.run?.status);
+    writeSchedule(normalizedScheduleId, {
+      state: runState && TERMINAL_RUN_STATES.has(runState) ? runState : "running",
+      status: runState && TERMINAL_RUN_STATES.has(runState) ? runState : "running",
+      run_id: started.run_id,
+      run: payload?.run || null,
+      last_poll_at: nowIso(),
+      completed_at: runState && TERMINAL_RUN_STATES.has(runState) ? nowIso() : undefined,
+      error: runState === "failed" ? (payload?.run?.error || payload?.error || null) : null
+    });
+    if (TERMINAL_RUN_STATES.has(runState)) break;
+    await sleep(1000);
+  }
+  return { ok: true, run_id: started.run_id };
+}
+
+export function __setRecommendSchedulerSpawnForTests(nextImpl) {
+  spawnProcessImpl = typeof nextImpl === "function" ? nextImpl : spawn;
+}
+
+function parseScheduleWorkerOptions(argv = process.argv.slice(2)) {
+  if (!Array.isArray(argv) || !argv.includes(SCHEDULE_WORKER_FLAG)) return null;
+  const idIndex = argv.indexOf(SCHEDULE_ID_FLAG);
+  return {
+    scheduleId: idIndex >= 0 ? normalizeText(argv[idIndex + 1]) : ""
+  };
+}
+
+const thisFilePath = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === thisFilePath) {
+  const options = parseScheduleWorkerOptions(process.argv.slice(2));
+  if (options) {
+    runScheduledRecommendWorker(options).then((result) => {
+      if (!result?.ok) process.exitCode = 1;
+    }).catch((error) => {
+      try {
+        writeSchedule(options.scheduleId, {
+          state: "failed",
+          status: "failed",
+          completed_at: nowIso(),
+          error: {
+            code: "SCHEDULE_WORKER_UNHANDLED_ERROR",
+            message: error?.message || String(error || "schedule worker failed"),
+            retryable: true
+          }
+        });
+      } catch {}
+      console.error("[boss-recommend-mcp] scheduled recommend worker failed", error);
+      process.exitCode = 1;
+    });
+  }
+}