fix(cron): add doctor migration for oversized quarantine sidecars

cxbAsDev · cxbAsDev · commit 0549437f7ca4 · 2026-07-19T13:49:49.000+08:00
diff --git a/src/commands/doctor/cron/index.test.ts b/src/commands/doctor/cron/index.test.ts
@@ -291,6 +291,43 @@ describe("collectLegacyCronStoreHealthFindings", () => {
     await expect(readPersistedJobs(storePath)).resolves.toEqual([]);
   });
 
+  it("reports an oversized cron quarantine sidecar as a legacy repair finding", async () => {
+    const storePath = await makeTempStorePath();
+    await writeCurrentCronStore(storePath, []);
+    const quarantinePath = resolveCronQuarantinePath(storePath);
+    await fs.mkdir(path.dirname(quarantinePath), { recursive: true });
+    await fs.writeFile(quarantinePath, "x".repeat(8 * 1024 * 1024 + 1), "utf-8");
+
+    const findings = await collectLegacyCronStoreHealthFindings({
+      cfg: createCronConfig(storePath),
+    });
+    expect(findings).toEqual([
+      expect.objectContaining({
+        checkId: "core/doctor/legacy-cron-store",
+        path: quarantinePath,
+        requirement: "cron-quarantine-oversized",
+      }),
+    ]);
+  });
+
+  it("archives an oversized cron quarantine sidecar when repairing", async () => {
+    const storePath = await makeTempStorePath();
+    await writeCurrentCronStore(storePath, []);
+    const quarantinePath = resolveCronQuarantinePath(storePath);
+    await fs.mkdir(path.dirname(quarantinePath), { recursive: true });
+    await fs.writeFile(quarantinePath, "x".repeat(8 * 1024 * 1024 + 1), "utf-8");
+
+    await maybeRepairLegacyCronStore({
+      cfg: createCronConfig(storePath),
+      options: {},
+      prompter: makePrompter(true),
+    });
+
+    await expect(fs.access(quarantinePath)).rejects.toThrow(/ENOENT/);
+    const archives = await fs.readdir(path.dirname(quarantinePath));
+    expect(archives.some((name) => name.endsWith(".archive.json"))).toBe(true);
+  });
+
   it("returns no findings for an already-normalized empty cron store", async () => {
     const storePath = await makeTempStorePath();
     await writeCurrentCronStore(storePath, []);
diff --git a/src/commands/doctor/cron/index.ts b/src/commands/doctor/cron/index.ts
@@ -2,7 +2,11 @@
 import { note } from "../../../../packages/terminal-core/src/note.js";
 import { formatCliCommand } from "../../../cli/command-format.js";
 import type { OpenClawConfig } from "../../../config/types.openclaw.js";
-import { loadCronQuarantineFile, resolveCronJobsStorePath } from "../../../cron/store.js";
+import {
+  CRON_QUARANTINE_MAX_BYTES,
+  loadCronQuarantineFile,
+  resolveCronJobsStorePath,
+} from "../../../cron/store.js";
 import type { HealthFinding } from "../../../flows/health-checks.js";
 import { shortenHomePath } from "../../../utils.js";
 import type { DoctorPrompter, DoctorOptions } from "../../doctor-prompter.js";
@@ -13,6 +17,11 @@ import {
   type LegacyCronRepairResult,
   type LegacyCronRepairState,
 } from "./legacy-repair.js";
+import {
+  archiveOversizedCronQuarantineSidecar,
+  formatArchivedQuarantineNote,
+  isOversizedCronQuarantineSidecar,
+} from "./oversized-quarantine.js";
 import {
   formatLegacyIssuePreview,
   formatUnresolvedCommandPromptAdvisory,
@@ -138,6 +147,18 @@ export async function collectLegacyCronStoreHealthFindings(params: {
     rawJobs,
   } = state;
 
+  if (isOversizedCronQuarantineSidecar(quarantinePath)) {
+    findings.push(
+      legacyCronStoreFinding({
+        message: `Cron quarantine sidecar at ${shortenHomePath(quarantinePath)} exceeds the ${CRON_QUARANTINE_MAX_BYTES} byte safety cap.`,
+        path: quarantinePath,
+        requirement: "cron-quarantine-oversized",
+        fixHint: `Run ${formatCliCommand("openclaw doctor --fix")} to archive the oversized sidecar and start fresh.`,
+      }),
+    );
+    return findings;
+  }
+
   try {
     const quarantine = await loadCronQuarantineFile(quarantinePath);
     if (quarantine.jobs.length > 0) {
@@ -276,6 +297,26 @@ export async function maybeRepairLegacyCronStore(params: {
     sqliteProjectionBackfillCount,
     rawJobs,
   } = state;
+  if (isOversizedCronQuarantineSidecar(quarantinePath)) {
+    note(
+      [
+        `Cron quarantine sidecar at ${shortenHomePath(quarantinePath)} exceeds the ${CRON_QUARANTINE_MAX_BYTES} byte safety cap.`,
+        `- The runtime cannot safely load the existing sidecar; it must be archived before new quarantine writes can proceed.`,
+      ].join("\n"),
+      "Cron",
+    );
+    const shouldArchive = await params.prompter.confirm({
+      message: "Archive the oversized quarantine sidecar now?",
+      initialValue: true,
+    });
+    if (shouldArchive) {
+      const archivePath = archiveOversizedCronQuarantineSidecar(quarantinePath);
+      note(
+        formatArchivedQuarantineNote({ archivePath, originalPath: quarantinePath }),
+        "Doctor changes",
+      );
+    }
+  }
   try {
     const quarantine = await loadCronQuarantineFile(quarantinePath);
     if (quarantine.jobs.length > 0) {
diff --git a/src/commands/doctor/cron/oversized-quarantine.ts b/src/commands/doctor/cron/oversized-quarantine.ts
@@ -0,0 +1,38 @@
+import { randomBytes } from "node:crypto";
+// Doctor migration for cron quarantine sidecars that exceed the bounded read cap.
+import fs from "node:fs";
+import { CRON_QUARANTINE_MAX_BYTES } from "../../../cron/store.js";
+import { shortenHomePath } from "../../../utils.js";
+
+/** Returns true when a regular quarantine sidecar exists and is above the cap. */
+export function isOversizedCronQuarantineSidecar(filePath: string): boolean {
+  try {
+    const stat = fs.statSync(filePath);
+    return stat.isFile() && stat.size > CRON_QUARANTINE_MAX_BYTES;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Moves an oversized quarantine sidecar to a timestamped archive path so the
+ * runtime can start fresh without discarding the legacy artifact.
+ */
+export function archiveOversizedCronQuarantineSidecar(filePath: string): string {
+  const timestamp = Date.now();
+  const random = randomBytes(4).toString("hex");
+  const archivePath = `${filePath}.oversized.${timestamp}.${random}.archive.json`;
+  fs.renameSync(filePath, archivePath);
+  return archivePath;
+}
+
+/** Human-readable note describing the archived sidecar. */
+export function formatArchivedQuarantineNote(params: {
+  archivePath: string;
+  originalPath: string;
+}): string {
+  return `Archived oversized cron quarantine sidecar (${CRON_QUARANTINE_MAX_BYTES} bytes) from ${shortenHomePath(params.originalPath)} to ${shortenHomePath(params.archivePath)}.`;
+}
diff --git a/src/cron/store.test.ts b/src/cron/store.test.ts
@@ -324,7 +324,7 @@ describe("cron store", () => {
     await fs.writeFile(quarantinePath, "x".repeat(8 * 1024 * 1024 + 1), "utf-8");
 
     await expect(loadCronQuarantineFile(quarantinePath)).rejects.toThrow(
-      /File exceeds 8388608 bytes/,
+      /Cron quarantine file at .* exceeds 8388608 bytes/,
     );
   });
 
diff --git a/src/cron/store.ts b/src/cron/store.ts
@@ -11,7 +11,21 @@ import { replaceFileAtomic } from "../infra/replace-file.js";
 
 // Cron quarantine sidecars are small JSON files; cap reads so a corrupted or
 // hostile file cannot OOM the cron load path.
-const CRON_QUARANTINE_MAX_BYTES = 8 * 1024 * 1024;
+export const CRON_QUARANTINE_MAX_BYTES = 8 * 1024 * 1024;
+
+/** Thrown when a persisted cron quarantine sidecar exceeds the bounded read cap. */
+export class CronQuarantineOversizedError extends Error {
+  override readonly name = "CronQuarantineOversizedError";
+  readonly code = "CRON_QUARANTINE_OVERSIZED";
+  constructor(
+    readonly filePath: string,
+    readonly maxBytes: number,
+  ) {
+    super(
+      `Cron quarantine file at ${filePath} exceeds ${maxBytes} bytes; run openclaw doctor --fix to archive it.`,
+    );
+  }
+}
 import {
   openOpenClawStateDatabase,
   runOpenClawStateWriteTransaction,
@@ -273,6 +287,9 @@ export async function loadCronQuarantineFile(pathLocal: string): Promise<CronQua
     if ((err as { code?: unknown })?.code === "ENOENT") {
       return { version: 1, jobs: [] };
     }
+    if (err instanceof Error && err.message.includes("exceeds")) {
+      throw new CronQuarantineOversizedError(pathLocal, CRON_QUARANTINE_MAX_BYTES);
+    }
     throw err;
   }
 }
@@ -331,22 +348,12 @@ export async function saveCronQuarantineFile(params: {
   }
   const quarantinePath = resolveCronQuarantinePath(params.storePath);
 
-  // Load existing quarantine entries for deduplication. If the file does not
-  // exist or is too large to read safely, start with empty state. Unexpected
-  // shapes (e.g. unrecognized version) must propagate to avoid data loss.
-  let existing: CronQuarantineFile = { version: 1, jobs: [] };
-  let existingKeys = new Set<string>();
-  try {
-    existing = await loadCronQuarantineFile(quarantinePath);
-    existingKeys = new Set(existing.jobs.map(quarantineEntryKey));
-  } catch (error: unknown) {
-    const err = error as Error;
-    if (err && (err.message.includes("ENOENT") || err.message.includes("exceeds"))) {
-      // File missing or exceeds the read cap — start fresh.
-    } else {
-      throw error;
-    }
-  }
+  // Load existing quarantine entries for deduplication. A missing file starts
+  // with empty state; an oversized sidecar is a legacy-data migration issue
+  // that must be resolved with `openclaw doctor --fix` rather than silently
+  // discarded here.
+  const existing = await loadCronQuarantineFile(quarantinePath);
+  const existingKeys = new Set(existing.jobs.map(quarantineEntryKey));
 
   const seen = new Set(existingKeys);
   const nextJobs = existing.jobs.slice();
