[AI-assisted] fix(cron): preserve legacy array stores (#84433)

IWhatsskill · clawsweeper[bot] · Takhoffman · web-flow · commit 29f8715f05c8 · 2026-05-20T05:01:24.000Z
Summary: - The PR changes cron store loading to normalize legacy top-level array `jobs.json` files into the versioned store shape and adds store, service, doctor, gateway tests plus a changelog entry. - Reproducibility: yes. Current `main` clearly maps a top-level parsed array to `{}` before reading `.jobs`, and the PR body supplies before/after runtime output for the load/add/save path. Automerge notes: - PR branch already contained follow-up commit before automerge: [AI-assisted] fix(cron): preserve legacy array stores Validation: - ClawSweeper review passed for head 446014b. - Required merge gates passed before the squash merge. Prepared head SHA: 446014b Review: #84433 (comment) Co-authored-by: JARVIS-Glasses <284122573+JARVIS-Glasses@users.noreply.github.com> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: takhoffman Co-authored-by: takhoffman <781889+takhoffman@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,6 +17,7 @@ Docs: https://docs.openclaw.ai
 - Codex: give `image_generate` dynamic-tool calls a 120s default watchdog when no per-call or configured image timeout is set, so image generation no longer falls back to the generic 30s bridge timeout. (#84254) Thanks @moritzmmayerhofer.
 - Codex: avoid duplicate dynamic tool terminal diagnostics while large diagnostic backlogs drain without blocking tool responses. (#82937) Thanks @galiniliev.
 - CLI/message: include a stable top-level `messageId` in `openclaw message --json` output when channel sends return one. (#84191) Thanks @100menotu001.
+- Cron: preserve legacy top-level array `jobs.json` stores when loading or adding scheduled jobs so old cron jobs are no longer treated as an empty store during upgrade. Fixes #60799. (#84433) Thanks @IWhatsskill.
 - Gateway/agents: use an agent's `identity.name` in Gateway agent summaries when `agents.list[].name` is unset, so configured agent labels remain visible in clients. (#84355; refs #57835) Thanks @luoyanglang.
 - Plugins/hooks: apply a default 30-second timeout to `before_compaction` and `after_compaction` hooks so a hung plugin handler no longer blocks compaction completion. (#84153)
 - Discord: preserve disabled presentation buttons when adapting and rendering Discord message controls. (#84188) Thanks @100menotu001.
diff --git a/src/commands/doctor-cron.test.ts b/src/commands/doctor-cron.test.ts
@@ -80,6 +80,11 @@ async function writeCronStore(storePath: string, jobs: Array<Record<string, unkn
   );
 }
 
+async function writeLegacyCronArrayStore(storePath: string, jobs: Array<Record<string, unknown>>) {
+  await fs.mkdir(path.dirname(storePath), { recursive: true });
+  await fs.writeFile(storePath, JSON.stringify(jobs, null, 2), "utf-8");
+}
+
 async function readPersistedJobs(storePath: string): Promise<Array<Record<string, unknown>>> {
   const persisted = JSON.parse(await fs.readFile(storePath, "utf-8")) as {
     jobs: Array<Record<string, unknown>>;
@@ -300,6 +305,29 @@ describe("maybeRepairLegacyCronStore", () => {
     expectNoteContaining("Cron store normalized", "Doctor changes");
   });
 
+  it("repairs legacy top-level array cron stores instead of treating them as empty (#60799)", async () => {
+    const storePath = await makeTempStorePath();
+    await writeLegacyCronArrayStore(storePath, [createLegacyCronJob()]);
+
+    await maybeRepairLegacyCronStore({
+      cfg: createCronConfig(storePath),
+      options: {},
+      prompter: makePrompter(true),
+    });
+
+    const persisted = JSON.parse(await fs.readFile(storePath, "utf-8")) as {
+      version?: unknown;
+      jobs?: Array<Record<string, unknown>>;
+    };
+    const job = requirePersistedJob(persisted.jobs ?? [], 0);
+    expect(persisted.version).toBe(1);
+    expect(job.jobId).toBeUndefined();
+    expect(job.id).toBe("legacy-job");
+    expect(job.notify).toBeUndefined();
+    expectNoteContaining("Legacy cron job storage detected", "Cron");
+    expectNoteContaining("Cron store normalized", "Doctor changes");
+  });
+
   it("repairs malformed persisted cron ids before list rendering sees them", async () => {
     const storePath = await makeTempStorePath();
     await writeCronStore(storePath, [
diff --git a/src/cron/service/ops.test.ts b/src/cron/service/ops.test.ts
@@ -6,7 +6,7 @@ import { findTaskByRunId, resetTaskRegistryForTests } from "../../tasks/task-reg
 import { setupCronServiceSuite, writeCronStoreSnapshot } from "../service.test-harness.js";
 import { loadCronStore } from "../store.js";
 import type { CronJob } from "../types.js";
-import { run, start, stop, update } from "./ops.js";
+import { add, run, start, stop, update } from "./ops.js";
 import { createCronServiceState } from "./state.js";
 import { runMissedJobs } from "./timer.js";
 
@@ -101,6 +101,11 @@ async function writeDueIsolatedJobSnapshot(storePath: string, now: number) {
   });
 }
 
+async function writeLegacyCronArraySnapshot(storePath: string, jobs: CronJob[]) {
+  await fs.mkdir(path.dirname(storePath), { recursive: true });
+  await fs.writeFile(storePath, JSON.stringify(jobs, null, 2), "utf-8");
+}
+
 async function expectDueIsolatedManualRunProgresses(storePath: string, now: number) {
   const state = createOkIsolatedCronState({ storePath, now, summary: "done" });
 
@@ -153,6 +158,59 @@ function createMissedIsolatedJob(now: number): CronJob {
 }
 
 describe("cron service ops seam coverage", () => {
+  it("preserves legacy top-level array jobs when adding a new job (#60799)", async () => {
+    const { storePath } = await makeStorePath();
+    const now = Date.parse("2026-05-20T08:00:00.000Z");
+    const legacyJobs: CronJob[] = [
+      {
+        id: "legacy-alpha",
+        name: "legacy alpha",
+        enabled: true,
+        createdAtMs: now - 120_000,
+        updatedAtMs: now - 120_000,
+        schedule: { kind: "every", everyMs: 3_600_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "alpha" },
+        state: { nextRunAtMs: now + 3_600_000 },
+      },
+      {
+        id: "legacy-beta",
+        name: "legacy beta",
+        enabled: true,
+        createdAtMs: now - 60_000,
+        updatedAtMs: now - 60_000,
+        schedule: { kind: "every", everyMs: 7_200_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "beta" },
+        state: { nextRunAtMs: now + 7_200_000 },
+      },
+    ];
+    await writeLegacyCronArraySnapshot(storePath, legacyJobs);
+    const state = createOkIsolatedCronState({ storePath, now });
+
+    const newJob = await add(state, {
+      name: "new after upgrade",
+      enabled: true,
+      schedule: { kind: "every", everyMs: 10_800_000 },
+      sessionTarget: "main",
+      wakeMode: "next-heartbeat",
+      payload: { kind: "systemEvent", text: "new" },
+    });
+    if (state.timer) {
+      clearTimeout(state.timer);
+    }
+
+    const loaded = await loadCronStore(storePath);
+    const raw = JSON.parse(await fs.readFile(storePath, "utf-8")) as {
+      jobs: Array<Record<string, unknown>>;
+    };
+
+    expect(loaded.jobs.map((job) => job.id)).toEqual(["legacy-alpha", "legacy-beta", newJob.id]);
+    expect(raw.jobs.map((job) => job.id)).toEqual(["legacy-alpha", "legacy-beta", newJob.id]);
+  });
+
   it("start marks interrupted running jobs failed, persists, and arms the timer", async () => {
     const { storePath } = await makeStorePath();
     const now = Date.parse("2026-03-23T12:00:00.000Z");
diff --git a/src/cron/store.test.ts b/src/cron/store.test.ts
@@ -136,6 +136,66 @@ describe("cron store", () => {
     expect(loaded.jobs[0]?.enabled).toBe(true);
   });
 
+  it("loads legacy top-level array stores instead of treating them as empty", async () => {
+    const store = await makeStorePath();
+    const first = makeStore("legacy-array-1", true).jobs[0];
+    const second = makeStore("legacy-array-2", false).jobs[0];
+    await fs.mkdir(path.dirname(store.storePath), { recursive: true });
+    await fs.writeFile(
+      store.storePath,
+      JSON.stringify([first, "bad-row", null, second], null, 2),
+      "utf-8",
+    );
+
+    const loaded = await loadCronStore(store.storePath);
+
+    expect(loaded.version).toBe(1);
+    expect(loaded.jobs.map((job) => job.id)).toEqual(["legacy-array-1", "legacy-array-2"]);
+    expect(loaded.jobs[0]?.state).toStrictEqual(first.state);
+    expect(loaded.jobs[1]?.enabled).toBe(false);
+  });
+
+  it("loads legacy top-level array stores synchronously", async () => {
+    const store = await makeStorePath();
+    const job = makeStore("legacy-array-sync", true).jobs[0];
+    await fs.mkdir(path.dirname(store.storePath), { recursive: true });
+    await fs.writeFile(store.storePath, JSON.stringify([job], null, 2), "utf-8");
+
+    const loaded = loadCronStoreSync(store.storePath);
+
+    expect(loaded.jobs).toHaveLength(1);
+    expect(loaded.jobs[0]?.id).toBe("legacy-array-sync");
+    expect(loaded.jobs[0]?.state).toStrictEqual(job.state);
+  });
+
+  it("preserves legacy top-level array jobs through a load-add-save round trip", async () => {
+    const store = await makeStorePath();
+    const legacy = makeStore("legacy-array-preserved", true).jobs[0];
+    legacy.state = { nextRunAtMs: legacy.createdAtMs + 60_000 };
+    const added = makeStore("new-job", true).jobs[0];
+    await fs.mkdir(path.dirname(store.storePath), { recursive: true });
+    await fs.writeFile(store.storePath, JSON.stringify([legacy], null, 2), "utf-8");
+
+    const loaded = await loadCronStore(store.storePath);
+    loaded.jobs.push(added);
+    await saveCronStore(store.storePath, loaded);
+
+    const config = JSON.parse(await fs.readFile(store.storePath, "utf-8")) as {
+      version?: unknown;
+      jobs?: Array<Record<string, unknown>>;
+    };
+    const stateFile = JSON.parse(
+      await fs.readFile(store.storePath.replace(/\.json$/, "-state.json"), "utf-8"),
+    ) as { jobs: Record<string, { state?: Record<string, unknown> }> };
+
+    expect(config.version).toBe(1);
+    expect(config.jobs?.map((job) => job.id)).toEqual(["legacy-array-preserved", "new-job"]);
+    expect(config.jobs?.[0]?.state).toStrictEqual({});
+    expect(stateFile.jobs["legacy-array-preserved"]?.state?.nextRunAtMs).toBe(
+      legacy.createdAtMs + 60_000,
+    );
+  });
+
   it("skips non-object persisted jobs instead of hydrating scalar rows", async () => {
     const store = await makeStorePath();
     const valid = makeStore("job-valid", true).jobs[0];
diff --git a/src/cron/store.ts b/src/cron/store.ts
@@ -54,6 +54,18 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function normalizeCronStoreFile(parsed: unknown): CronStoreFile {
+  const rawJobs = Array.isArray(parsed)
+    ? parsed
+    : isRecord(parsed) && Array.isArray(parsed.jobs)
+      ? parsed.jobs
+      : [];
+  return {
+    version: 1,
+    jobs: rawJobs.filter(isRecord) as never as CronStoreFile["jobs"],
+  };
+}
+
 function stripRuntimeOnlyCronFields(store: CronStoreFile): unknown {
   return {
     version: store.version,
@@ -156,10 +168,7 @@ function loadStateFileSync(statePath: string): CronStateFile | null {
 
 function hasInlineState(jobs: Array<Record<string, unknown> | null | undefined>): boolean {
   return jobs.some(
-    (job) =>
-      job != null &&
-      isRecord(job.state) &&
-      Object.keys(job.state).length > 0,
+    (job) => job != null && isRecord(job.state) && Object.keys(job.state).length > 0,
   );
 }
 
@@ -215,23 +224,13 @@ export async function loadCronStore(storePath: string): Promise<CronStoreFile> {
         cause: err,
       });
     }
-    const parsedRecord =
-      parsed && typeof parsed === "object" && !Array.isArray(parsed)
-        ? (parsed as Record<string, unknown>)
-        : {};
-    const jobs = Array.isArray(parsedRecord.jobs)
-      ? (parsedRecord.jobs.filter(isRecord) as never[])
-      : [];
-    const store = {
-      version: 1 as const,
-      jobs: jobs.filter(Boolean) as never as CronStoreFile["jobs"],
-    };
+    const store = normalizeCronStoreFile(parsed);
+    const jobs = store.jobs as unknown as Array<Record<string, unknown>>;
 
     // Load state file and merge.
     const statePath = resolveStatePath(storePath);
     const stateFile = await loadStateFile(statePath);
-    const hasLegacyInlineState =
-      !stateFile && hasInlineState(jobs as unknown as Array<Record<string, unknown>>);
+    const hasLegacyInlineState = !stateFile && hasInlineState(jobs);
 
     if (stateFile) {
       // State file exists: merge state by job ID. Inline state in jobs.json is ignored.
@@ -285,21 +284,11 @@ export function loadCronStoreSync(storePath: string): CronStoreFile {
         cause: err,
       });
     }
-    const parsedRecord =
-      parsed && typeof parsed === "object" && !Array.isArray(parsed)
-        ? (parsed as Record<string, unknown>)
-        : {};
-    const jobs = Array.isArray(parsedRecord.jobs)
-      ? (parsedRecord.jobs.filter(isRecord) as never[])
-      : [];
-    const store = {
-      version: 1 as const,
-      jobs: jobs.filter(Boolean) as never as CronStoreFile["jobs"],
-    };
+    const store = normalizeCronStoreFile(parsed);
+    const jobs = store.jobs as unknown as Array<Record<string, unknown>>;
 
     const stateFile = loadStateFileSync(resolveStatePath(storePath));
-    const hasLegacyInlineState =
-      !stateFile && hasInlineState(jobs as unknown as Array<Record<string, unknown>>);
+    const hasLegacyInlineState = !stateFile && hasInlineState(jobs);
 
     if (stateFile) {
       for (const job of store.jobs) {
diff --git a/src/gateway/server.cron.test.ts b/src/gateway/server.cron.test.ts
@@ -527,6 +527,85 @@ describe("gateway server cron", () => {
     }
   });
 
+  test("cron.add preserves legacy top-level array stores (#60799)", async () => {
+    const { prevSkipCron } = await setupCronTestRun({
+      tempPrefix: "openclaw-gw-cron-legacy-array-",
+      cronEnabled: false,
+    });
+    const storePath = testState.cronStorePath;
+    expect(typeof storePath).toBe("string");
+    const now = Date.parse("2026-05-20T08:00:00.000Z");
+    await fs.writeFile(
+      storePath as string,
+      JSON.stringify(
+        [
+          {
+            id: "gw-legacy-alpha",
+            name: "gateway legacy alpha",
+            enabled: true,
+            createdAtMs: now - 120_000,
+            updatedAtMs: now - 120_000,
+            schedule: { kind: "every", everyMs: 3_600_000 },
+            sessionTarget: "main",
+            wakeMode: "next-heartbeat",
+            payload: { kind: "systemEvent", text: "alpha" },
+            state: { nextRunAtMs: now + 3_600_000 },
+          },
+          {
+            id: "gw-legacy-beta",
+            name: "gateway legacy beta",
+            enabled: true,
+            createdAtMs: now - 60_000,
+            updatedAtMs: now - 60_000,
+            schedule: { kind: "every", everyMs: 7_200_000 },
+            sessionTarget: "main",
+            wakeMode: "next-heartbeat",
+            payload: { kind: "systemEvent", text: "beta" },
+            state: { nextRunAtMs: now + 7_200_000 },
+          },
+        ],
+        null,
+        2,
+      ),
+      "utf-8",
+    );
+    const cronState = await createDirectCronState();
+
+    try {
+      const addRes = await directCronReq(cronState, "cron.add", {
+        name: "gateway new after upgrade",
+        enabled: true,
+        schedule: { kind: "every", everyMs: 10_800_000 },
+        sessionTarget: "main",
+        wakeMode: "next-heartbeat",
+        payload: { kind: "systemEvent", text: "new" },
+      });
+      const newJobId = expectCronJobIdFromResponse(addRes);
+
+      const persisted = JSON.parse(await fs.readFile(storePath as string, "utf-8")) as {
+        version?: unknown;
+        jobs?: Array<Record<string, unknown>>;
+      };
+      expect(persisted.version).toBe(1);
+      expect(persisted.jobs?.map((job) => job.id)).toEqual([
+        "gw-legacy-alpha",
+        "gw-legacy-beta",
+        newJobId,
+      ]);
+
+      const listRes = await directCronReq(cronState, "cron.list", { includeDisabled: true });
+      expect(listRes.ok).toBe(true);
+      const listedJobs = (listRes.payload as { jobs?: Array<Record<string, unknown>> } | null)
+        ?.jobs;
+      expect(listedJobs?.map((job) => job.id)).toEqual(
+        expect.arrayContaining(["gw-legacy-alpha", "gw-legacy-beta", newJobId]),
+      );
+      expect(listedJobs).toHaveLength(3);
+    } finally {
+      await cleanupCronTestRun({ cronState, prevSkipCron });
+    }
+  });
+
   test("handles cron patch merge and validation semantics", { timeout: 45_000 }, async () => {
     const { prevSkipCron } = await setupCronTestRun({
       tempPrefix: "openclaw-gw-cron-patch-",
