From a1db26707d6f1037e596d2e21e4305951110d16c Mon Sep 17 00:00:00 2001
From: Gustavo Madeira Santana <gumadeiras@gmail.com>
Date: Mon, 20 Apr 2026 11:49:25 -0400
Subject: [PATCH] cron: clarify split store docs

---
 docs/automation/cron-jobs.md | 4 ++++
 src/cron/store.ts            | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
index dd6b70fcc79..868abacfcaf 100644
--- a/docs/automation/cron-jobs.md
+++ b/docs/automation/cron-jobs.md
@@ -369,6 +369,10 @@ Model override note:
 }
 ```
 
+The runtime state sidecar is derived from `cron.store`: a `.json` store such as
+`~/clawd/cron/jobs.json` uses `~/clawd/cron/jobs-state.json`, while a store path
+without a `.json` suffix appends `-state.json`.
+
 Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
 
 **One-shot retry**: transient errors (rate limit, overload, network, server error) retry up to 3 times with exponential backoff. Permanent errors disable immediately.
diff --git a/src/cron/store.ts b/src/cron/store.ts
index 3921dce8c78..85d1582c2c4 100644
--- a/src/cron/store.ts
+++ b/src/cron/store.ts
@@ -226,7 +226,7 @@ export async function saveCronStore(
     }
   }
 
-  // Write state file first (safer ordering for migration — see PR_DRAFT.md Atomicity).
+  // Write state first so migration never leaves stripped config without runtime state.
   if (stateChanged || migrating) {
     await atomicWrite(statePath, stateJson);
     serializedStoreCache.set(stateCacheKey, stateJson);