@reconcrap/boss-recruit-mcp 1.0.20 → 1.0.21

package/src/run-state.js

@@ -0,0 +1,294 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const RUN_MODE_SYNC = "sync";
+export const RUN_MODE_ASYNC = "async";
+
+export const RUN_STATE_QUEUED = "queued";
+export const RUN_STATE_RUNNING = "running";
+export const RUN_STATE_COMPLETED = "completed";
+export const RUN_STATE_FAILED = "failed";
+export const RUN_STATE_CANCELED = "canceled";
+
+export const RUN_STAGE_PREFLIGHT = "preflight";
+export const RUN_STAGE_PAGE_READY = "page_ready";
+export const RUN_STAGE_JOB_LIST = "job_list";
+export const RUN_STAGE_SEARCH = "search";
+export const RUN_STAGE_SCREEN = "screen";
+export const RUN_STAGE_FINALIZE = "finalize";
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 120_000;
+const DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000;
+
+const VALID_RUN_MODES = new Set([RUN_MODE_SYNC, RUN_MODE_ASYNC]);
+const VALID_RUN_STATES = new Set([
+  RUN_STATE_QUEUED,
+  RUN_STATE_RUNNING,
+  RUN_STATE_COMPLETED,
+  RUN_STATE_FAILED,
+  RUN_STATE_CANCELED
+]);
+const VALID_RUN_STAGES = new Set([
+  RUN_STAGE_PREFLIGHT,
+  RUN_STAGE_PAGE_READY,
+  RUN_STAGE_JOB_LIST,
+  RUN_STAGE_SEARCH,
+  RUN_STAGE_SCREEN,
+  RUN_STAGE_FINALIZE
+]);
+
+function toIsoNow() {
+  return new Date().toISOString();
+}
+
+function parsePositiveInteger(raw, fallback) {
+  const value = Number.parseInt(String(raw || ""), 10);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+export function getRunHeartbeatIntervalMs() {
+  return parsePositiveInteger(process.env.BOSS_RECRUIT_RUN_HEARTBEAT_MS, DEFAULT_HEARTBEAT_INTERVAL_MS);
+}
+
+export function getRunRetentionMs() {
+  return parsePositiveInteger(process.env.BOSS_RECRUIT_RUN_RETENTION_MS, DEFAULT_RETENTION_MS);
+}
+
+export function getStateHome() {
+  return process.env.BOSS_RECRUIT_HOME
+    ? path.resolve(process.env.BOSS_RECRUIT_HOME)
+    : path.join(os.homedir(), "\.boss-recruit-mcp");
+}
+
+export function getRunsDir() {
+  return path.join(getStateHome(), "runs");
+}
+
+function ensureRunsDir() {
+  fs.mkdirSync(getRunsDir(), { recursive: true });
+}
+
+function normalizeRunId(runId) {
+  return String(runId || "").trim();
+}
+
+function getRunStatePath(runId) {
+  const normalized = normalizeRunId(runId);
+  if (!normalized || normalized.includes("/") || normalized.includes("\\")) {
+    throw new Error("Invalid run_id");
+  }
+  return path.join(getRunsDir(), `${normalized}.json`);
+}
+
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeWriteJson(filePath, payload) {
+  ensureRunsDir();
+  const tempPath = `${filePath}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  fs.renameSync(tempPath, filePath);
+}
+
+function defaultProgress(progress = {}) {
+  return {
+    processed: Number.isInteger(progress.processed) && progress.processed >= 0 ? progress.processed : 0,
+    passed: Number.isInteger(progress.passed) && progress.passed >= 0 ? progress.passed : 0,
+    skipped: Number.isInteger(progress.skipped) && progress.skipped >= 0 ? progress.skipped : 0,
+    greet_count: Number.isInteger(progress.greet_count) && progress.greet_count >= 0 ? progress.greet_count : 0
+  };
+}
+
+function normalizeRunMode(mode) {
+  const normalized = String(mode || "").trim().toLowerCase();
+  return VALID_RUN_MODES.has(normalized) ? normalized : RUN_MODE_SYNC;
+}
+
+function normalizeRunState(state) {
+  const normalized = String(state || "").trim().toLowerCase();
+  return VALID_RUN_STATES.has(normalized) ? normalized : RUN_STATE_QUEUED;
+}
+
+function normalizeRunStage(stage) {
+  const normalized = String(stage || "").trim().toLowerCase();
+  return VALID_RUN_STAGES.has(normalized) ? normalized : RUN_STAGE_PREFLIGHT;
+}
+
+function normalizeMessage(message) {
+  const normalized = String(message || "").replace(/\s+/g, " ").trim();
+  return normalized || null;
+}
+
+export function createRunId() {
+  if (typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString("hex");
+}
+
+export function createRunStateSnapshot({
+  runId,
+  mode = RUN_MODE_SYNC,
+  state = RUN_STATE_QUEUED,
+  stage = RUN_STAGE_PREFLIGHT,
+  pid = process.pid,
+  lastMessage = null
+} = {}) {
+  const now = toIsoNow();
+  return {
+    run_id: normalizeRunId(runId) || createRunId(),
+    mode: normalizeRunMode(mode),
+    state: normalizeRunState(state),
+    stage: normalizeRunStage(stage),
+    started_at: now,
+    updated_at: now,
+    heartbeat_at: now,
+    pid: Number.isInteger(pid) && pid > 0 ? pid : process.pid,
+    progress: defaultProgress(),
+    last_message: normalizeMessage(lastMessage),
+    error: null,
+    result: null
+  };
+}
+
+export function writeRunState(snapshot) {
+  const runId = normalizeRunId(snapshot?.run_id);
+  if (!runId) {
+    throw new Error("run_id is required");
+  }
+  const now = toIsoNow();
+  const payload = {
+    run_id: runId,
+    mode: normalizeRunMode(snapshot.mode),
+    state: normalizeRunState(snapshot.state),
+    stage: normalizeRunStage(snapshot.stage),
+    started_at: String(snapshot.started_at || now),
+    updated_at: String(snapshot.updated_at || now),
+    heartbeat_at: String(snapshot.heartbeat_at || now),
+    pid: Number.isInteger(snapshot.pid) && snapshot.pid > 0 ? snapshot.pid : process.pid,
+    progress: defaultProgress(snapshot.progress),
+    last_message: normalizeMessage(snapshot.last_message),
+    error: snapshot.error || null,
+    result: snapshot.result || null
+  };
+  safeWriteJson(getRunStatePath(runId), payload);
+  return payload;
+}
+
+export function readRunState(runId) {
+  const payload = safeReadJson(getRunStatePath(runId));
+  if (!payload) return null;
+  return {
+    run_id: normalizeRunId(payload.run_id),
+    mode: normalizeRunMode(payload.mode),
+    state: normalizeRunState(payload.state),
+    stage: normalizeRunStage(payload.stage),
+    started_at: String(payload.started_at || ""),
+    updated_at: String(payload.updated_at || ""),
+    heartbeat_at: String(payload.heartbeat_at || ""),
+    pid: Number.isInteger(payload.pid) && payload.pid > 0 ? payload.pid : process.pid,
+    progress: defaultProgress(payload.progress),
+    last_message: normalizeMessage(payload.last_message),
+    error: payload.error || null,
+    result: payload.result || null
+  };
+}
+
+export function updateRunState(runId, updater) {
+  const current = readRunState(runId);
+  if (!current) return null;
+  const patch = typeof updater === "function" ? updater({ ...current }) : updater;
+  if (!patch || typeof patch !== "object") {
+    return current;
+  }
+  const now = toIsoNow();
+  const next = {
+    ...current,
+    ...patch,
+    run_id: current.run_id,
+    mode: normalizeRunMode(patch.mode ?? current.mode),
+    state: normalizeRunState(patch.state ?? current.state),
+    stage: normalizeRunStage(patch.stage ?? current.stage),
+    progress: defaultProgress({
+      ...current.progress,
+      ...(patch.progress || {})
+    }),
+    last_message: normalizeMessage(
+      Object.prototype.hasOwnProperty.call(patch, "last_message")
+        ? patch.last_message
+        : current.last_message
+    ),
+    updated_at: now,
+    heartbeat_at: String(
+      Object.prototype.hasOwnProperty.call(patch, "heartbeat_at")
+        ? (patch.heartbeat_at || now)
+        : current.heartbeat_at
+    )
+  };
+  return writeRunState(next);
+}
+
+export function touchRunHeartbeat(runId, message = null) {
+  return updateRunState(runId, (current) => ({
+    heartbeat_at: toIsoNow(),
+    last_message: message ?? current.last_message
+  }));
+}
+
+export function updateRunProgress(runId, progressPatch = {}, message = null) {
+  const patch = {
+    progress: {}
+  };
+  if (Number.isInteger(progressPatch.processed) && progressPatch.processed >= 0) {
+    patch.progress.processed = progressPatch.processed;
+  }
+  if (Number.isInteger(progressPatch.passed) && progressPatch.passed >= 0) {
+    patch.progress.passed = progressPatch.passed;
+  }
+  if (Number.isInteger(progressPatch.skipped) && progressPatch.skipped >= 0) {
+    patch.progress.skipped = progressPatch.skipped;
+  }
+  if (Number.isInteger(progressPatch.greet_count) && progressPatch.greet_count >= 0) {
+    patch.progress.greet_count = progressPatch.greet_count;
+  }
+  if (message !== null) {
+    patch.last_message = message;
+  }
+  return updateRunState(runId, patch);
+}
+
+export function cleanupExpiredRuns(retentionMs = getRunRetentionMs()) {
+  ensureRunsDir();
+  const removed = [];
+  const failed = [];
+  const now = Date.now();
+  const entries = fs.readdirSync(getRunsDir(), { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const filePath = path.join(getRunsDir(), entry.name);
+    try {
+      const stat = fs.statSync(filePath);
+      const age = now - Number(stat.mtimeMs || 0);
+      if (age < retentionMs) continue;
+      fs.unlinkSync(filePath);
+      removed.push(filePath);
+    } catch (error) {
+      failed.push({
+        file: filePath,
+        reason: error.message || String(error)
+      });
+    }
+  }
+  return { removed, failed };
+}
+

package/src/test-index-async.js

@@ -0,0 +1,231 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { __testables } from "./index.js";
+
+const {
+  handleRequest,
+  activeAsyncRuns,
+  setRunPipelineImplForTests
+} = __testables;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeToolCall(id, name, args = {}) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method: "tools/call",
+    params: {
+      name,
+      arguments: args
+    }
+  };
+}
+
+async function readToolPayload(response) {
+  return response?.result?.structuredContent;
+}
+
+async function waitForTerminalRunState(runId, timeoutMs = 4000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const response = await handleRequest(
+      makeToolCall(100, "get_recruit_pipeline_run", { run_id: runId }),
+      process.cwd()
+    );
+    const payload = await readToolPayload(response);
+    const state = payload?.run?.state;
+    if (["completed", "failed", "canceled"].includes(String(state || "").toLowerCase())) {
+      return payload.run;
+    }
+    await sleep(80);
+  }
+  throw new Error(`Timed out waiting terminal run state for run_id=${runId}`);
+}
+
+async function testAsyncStartStatusCancelAndSyncCompatibility() {
+  const previousHome = process.env.BOSS_RECRUIT_HOME;
+  const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "boss-recruit-index-async-"));
+
+  setRunPipelineImplForTests(async (input, _deps, runtime) => {
+    if (runtime?.precheckOnly) {
+      if (input.instruction.includes("need-confirm")) {
+        return {
+          status: "NEED_CONFIRMATION",
+          required_confirmations: ["keyword"],
+          pending_questions: [
+            {
+              field: "keyword",
+              question: "请先确认关键词"
+            }
+          ]
+        };
+      }
+      if (input.instruction.includes("precheck-fail")) {
+        return {
+          status: "FAILED",
+          error: {
+            code: "BOSS_LOGIN_REQUIRED",
+            message: "mock login required",
+            retryable: true
+          }
+        };
+      }
+      return {
+        status: "READY_TO_START_ASYNC"
+      };
+    }
+
+    runtime?.onStage?.({ stage: "preflight", message: "preflight started" });
+    await sleep(50);
+
+    if (input.instruction.includes("fail")) {
+      runtime?.onStage?.({ stage: "search", message: "search failed" });
+      return {
+        status: "FAILED",
+        error: {
+          code: "SEARCH_CLI_FAILED",
+          message: "mock search failed",
+          retryable: true
+        }
+      };
+    }
+
+    runtime?.onStage?.({ stage: "screen", message: "screen running" });
+    for (let i = 1; i <= 40; i += 1) {
+      if (runtime?.signal?.aborted) {
+        const error = new Error("aborted");
+        error.code = "PIPELINE_ABORTED";
+        throw error;
+      }
+      runtime?.onProgress?.({
+        stage: "screen",
+        processed: i,
+        passed: Math.floor(i / 5),
+        skipped: i - Math.floor(i / 5),
+        greet_count: 0,
+        line: `处理第 ${i} 位候选人`
+      });
+      await sleep(input.instruction.includes("slow") ? 25 : 5);
+    }
+
+    return {
+      status: "COMPLETED",
+      result: {
+        processed_count: 40,
+        passed_count: 8
+      }
+    };
+  });
+
+  process.env.BOSS_RECRUIT_HOME = tempHome;
+
+  try {
+    const gatedStartResponse = await handleRequest(
+      makeToolCall(1, "start_recruit_pipeline_run", { instruction: "need-confirm slow task" }),
+      process.cwd()
+    );
+    const gatedStartPayload = await readToolPayload(gatedStartResponse);
+    assert.equal(gatedStartPayload.status, "NEED_CONFIRMATION");
+    assert.deepEqual(gatedStartPayload.required_confirmations, ["keyword"]);
+    assert.equal(gatedStartPayload.run_id, undefined);
+
+    const startResponse = await handleRequest(
+      makeToolCall(2, "start_recruit_pipeline_run", { instruction: "slow task for cancel" }),
+      process.cwd()
+    );
+    const started = await readToolPayload(startResponse);
+    assert.equal(started.status, "ACCEPTED");
+    assert.equal(typeof started.run_id, "string");
+    assert.equal(started.poll_after_sec >= 5 && started.poll_after_sec <= 15, true);
+
+    const statusResponse = await handleRequest(
+      makeToolCall(3, "get_recruit_pipeline_run", { run_id: started.run_id }),
+      process.cwd()
+    );
+    const initialStatus = await readToolPayload(statusResponse);
+    assert.equal(initialStatus.status, "RUN_STATUS");
+    assert.equal(["queued", "running"].includes(initialStatus.run.state), true);
+
+    const cancelResponse = await handleRequest(
+      makeToolCall(4, "cancel_recruit_pipeline_run", { run_id: started.run_id }),
+      process.cwd()
+    );
+    const canceled = await readToolPayload(cancelResponse);
+    assert.equal(["CANCEL_REQUESTED", "CANCEL_IGNORED"].includes(canceled.status), true);
+
+    const canceledRun = await waitForTerminalRunState(started.run_id);
+    assert.equal(canceledRun.state, "canceled");
+
+    const defaultAsyncGatedResponse = await handleRequest(
+      makeToolCall(5, "run_recruit_pipeline", { instruction: "need-confirm default async" }),
+      process.cwd()
+    );
+    const defaultAsyncGatedPayload = await readToolPayload(defaultAsyncGatedResponse);
+    assert.equal(defaultAsyncGatedPayload.status, "NEED_CONFIRMATION");
+    assert.deepEqual(defaultAsyncGatedPayload.required_confirmations, ["keyword"]);
+
+    const defaultAsyncResponse = await handleRequest(
+      makeToolCall(6, "run_recruit_pipeline", { instruction: "fast async accepted run" }),
+      process.cwd()
+    );
+    const defaultAsyncPayload = await readToolPayload(defaultAsyncResponse);
+    assert.equal(defaultAsyncPayload.status, "ACCEPTED");
+    assert.equal(typeof defaultAsyncPayload.run_id, "string");
+    const completedDefaultAsyncRun = await waitForTerminalRunState(defaultAsyncPayload.run_id);
+    assert.equal(completedDefaultAsyncRun.state, "completed");
+
+    const syncResponse = await handleRequest(
+      makeToolCall(7, "run_recruit_pipeline", {
+        instruction: "fast forced sync run",
+        execution_mode: "sync"
+      }),
+      process.cwd()
+    );
+    const syncPayload = await readToolPayload(syncResponse);
+    assert.equal(syncPayload.status, "COMPLETED");
+    assert.equal(typeof syncPayload.result.run_id, "string");
+    assert.equal(syncPayload.result.processed_count, 40);
+
+    const failedSyncResponse = await handleRequest(
+      makeToolCall(8, "run_recruit_pipeline", {
+        instruction: "force fail",
+        execution_mode: "sync"
+      }),
+      process.cwd()
+    );
+    const syncFailedPayload = await readToolPayload(failedSyncResponse);
+    assert.equal(syncFailedPayload.status, "FAILED");
+    assert.equal(typeof syncFailedPayload.diagnostics?.run_id, "string");
+    assert.equal(typeof syncFailedPayload.diagnostics?.last_stage, "string");
+
+    const precheckFailedResponse = await handleRequest(
+      makeToolCall(9, "start_recruit_pipeline_run", { instruction: "precheck-fail" }),
+      process.cwd()
+    );
+    const precheckFailedPayload = await readToolPayload(precheckFailedResponse);
+    assert.equal(precheckFailedPayload.status, "FAILED");
+    assert.equal(precheckFailedPayload.error.code, "BOSS_LOGIN_REQUIRED");
+
+    assert.equal(activeAsyncRuns.size >= 0, true);
+  } finally {
+    setRunPipelineImplForTests(null);
+    if (previousHome === undefined) {
+      delete process.env.BOSS_RECRUIT_HOME;
+    } else {
+      process.env.BOSS_RECRUIT_HOME = previousHome;
+    }
+    fs.rmSync(tempHome, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  await testAsyncStartStatusCancelAndSyncCompatibility();
+  console.log("index async tests passed");
+}
+
+await main();

package/src/test-parser.js

@@ -302,39 +302,6 @@ function testCriteriaConfirmationPrompt() {
   assert.equal(confirmedCriteria.needs_criteria_confirmation, false);
 }
 
-function testNaturalSentenceExtractsCityAndKeywordWithoutMissing() {
-  const r = parseRecruitInstruction({
-    instruction: "找杭州本科及以上做算法的人，本科学校必须是211或qs100院校，有CCF-A论文或会议成果，目标3人",
-    confirmation: null,
-    overrides: null
-  });
-
-  assert.equal(r.searchParams.city, "杭州");
-  assert.equal(r.proposed_keyword, "算法");
-  assert.deepEqual(r.missing_fields, []);
-  assert.equal(r.has_unresolved_missing_fields, false);
-  assert.equal(r.needs_keyword_confirmation, true);
-  assert.match(r.screenParams.criteria, /CCF-A论文/);
-}
-
-function testExplicitCriteriaTextIsPreserved() {
-  const r = parseRecruitInstruction({
-    instruction:
-      "关键词：算法，城市：杭州，学历：本科及以上，学校：985、211、qs100，目标人数：3人，筛选条件：必须有CCF-A论文或者会议成果，本科学校必须至少是211或者qs100院校",
-    confirmation: {
-      keyword_confirmed: true,
-      keyword_value: "算法",
-      search_params_confirmed: true
-    },
-    overrides: null
-  });
-
-  assert.equal(
-    r.screenParams.criteria,
-    "必须有CCF-A论文或者会议成果，本科学校必须至少是211或者qs100院校"
-  );
-}
-
 function main() {
   testNeedInput();
   testExampleExtraction();
@@ -347,8 +314,6 @@ function main() {
   testDefaultsCanOnlyApplyWhenExplicitlyRequested();
   testRecentViewedFilterPromptAndNegativeOverride();
   testCriteriaConfirmationPrompt();
-  testNaturalSentenceExtractsCityAndKeywordWithoutMissing();
-  testExplicitCriteriaTextIsPreserved();
   // eslint-disable-next-line no-console
   console.log("parser tests passed");
 }

package/src/test-run-state.js

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  RUN_MODE_ASYNC,
+  RUN_STAGE_SCREEN,
+  RUN_STATE_COMPLETED,
+  RUN_STATE_QUEUED,
+  RUN_STATE_RUNNING,
+  cleanupExpiredRuns,
+  createRunId,
+  createRunStateSnapshot,
+  getRunsDir,
+  readRunState,
+  touchRunHeartbeat,
+  updateRunProgress,
+  updateRunState,
+  writeRunState
+} from "./run-state.js";
+
+function withTempHome(testFn) {
+  const previous = process.env.BOSS_RECRUIT_HOME;
+  const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "boss-recruit-run-state-"));
+  process.env.BOSS_RECRUIT_HOME = tempHome;
+  try {
+    testFn(tempHome);
+  } finally {
+    if (previous === undefined) {
+      delete process.env.BOSS_RECRUIT_HOME;
+    } else {
+      process.env.BOSS_RECRUIT_HOME = previous;
+    }
+    fs.rmSync(tempHome, { recursive: true, force: true });
+  }
+}
+
+function testRunStateLifecycle() {
+  withTempHome(() => {
+    const runId = createRunId();
+    const queued = writeRunState(createRunStateSnapshot({
+      runId,
+      mode: RUN_MODE_ASYNC,
+      state: RUN_STATE_QUEUED,
+      stage: "preflight"
+    }));
+    assert.equal(queued.run_id, runId);
+    assert.equal(queued.state, RUN_STATE_QUEUED);
+
+    const running = updateRunState(runId, {
+      state: RUN_STATE_RUNNING,
+      stage: RUN_STAGE_SCREEN,
+      last_message: "screening in progress"
+    });
+    assert.equal(running.state, RUN_STATE_RUNNING);
+    assert.equal(running.stage, RUN_STAGE_SCREEN);
+    const heartbeatBeforeProgress = running.heartbeat_at;
+
+    const progressed = updateRunProgress(runId, {
+      processed: 7,
+      passed: 2,
+      skipped: 5,
+      greet_count: 1
+    });
+    assert.equal(progressed.progress.processed, 7);
+    assert.equal(progressed.progress.passed, 2);
+    assert.equal(progressed.progress.skipped, 5);
+    assert.equal(progressed.progress.greet_count, 1);
+    assert.equal(progressed.heartbeat_at, heartbeatBeforeProgress);
+
+    const heartbeated = touchRunHeartbeat(runId, "still running");
+    assert.equal(heartbeated.last_message, "still running");
+    assert.equal(Date.parse(heartbeated.heartbeat_at) >= Date.parse(heartbeatBeforeProgress), true);
+
+    const completed = updateRunState(runId, {
+      state: RUN_STATE_COMPLETED,
+      stage: "finalize",
+      result: {
+        status: "COMPLETED",
+        result: {
+          processed_count: 7
+        }
+      }
+    });
+    assert.equal(completed.state, RUN_STATE_COMPLETED);
+    assert.equal(completed.result.status, "COMPLETED");
+
+    const reloaded = readRunState(runId);
+    assert.equal(reloaded.state, RUN_STATE_COMPLETED);
+    assert.equal(reloaded.progress.processed, 7);
+  });
+}
+
+function testRunStateCleanup() {
+  withTempHome(() => {
+    const runId = createRunId();
+    writeRunState(createRunStateSnapshot({ runId, mode: RUN_MODE_ASYNC }));
+    const runFile = path.join(getRunsDir(), `${runId}.json`);
+    const oldSeconds = Math.floor((Date.now() - 3 * 24 * 60 * 60 * 1000) / 1000);
+    fs.utimesSync(runFile, oldSeconds, oldSeconds);
+
+    const cleaned = cleanupExpiredRuns(1000);
+    assert.equal(cleaned.removed.some((item) => item.endsWith(`${runId}.json`)), true);
+    assert.equal(fs.existsSync(runFile), false);
+  });
+}
+
+function main() {
+  testRunStateLifecycle();
+  testRunStateCleanup();
+  console.log("run-state tests passed");
+}
+
+main();
+