Summary

• Recurring cron error path used Math.max(naturalNext, backoffNext) for the next scheduled run. For daily schedules (e.g. 0 5 * * *), naturalNext is ~24h ahead and always dominated the short backoff, so retries for transient provider errors were effectively suppressed.
• This matches the symptom in Cron jobs consistently fail with MiniMax 503 overload during early morning (05:00-07:30 CST), manual triggers succeed #85888: scheduled jobs hitting MiniMax overloaded_error (503) during 05:00-07:30 Asia/Shanghai never re-fired the same day, while manual reruns at 08:30+ (after the busy window) succeeded because they bypassed the broken scheduler path.
• While retry budget is available and the error is classified retryable via resolveCronExecutionRetryHint, schedule at backoffNext. Once consecutiveErrors > retryConfig.maxAttempts or the error is permanent, fall back to max(naturalNext, backoffNext) so high-frequency recurring schedules cannot bypass the configured backoff after retry-budget exhaustion. When croner cannot resolve the natural next slot for a cron schedule, the retry path clears nextRunAtMs to preserve the unresolved-next-run guard from [Bug] Cron spin loop via MIN_REFIRE_GAP_MS fallback when computeJobNextRunAtMs returns undefined (incomplete fix for #17821) #66019.

Closes #85888

Files

• src/cron/service/timer.ts — split recurring error path into "within retry budget" (use backoffNext, preserve unresolved-next-run guard) vs. "exhausted / permanent" (use max(naturalNext, backoffNext)).
• src/cron/service/timer.regression.test.ts — four regressions: (1) same-day backoff retry on retryable daily-cron error, (2) high-frequency every-1s preserves backoff floor, (3) cron unresolved-next-run guard, (4) exhausted budget falls back to natural slot.
• docs/gateway/configuration-reference.md, docs/automation/cron-jobs.md, src/config/schema.help.ts, src/config/types.cron.ts — align cron.retry contract surfaces with the new recurring-job behavior.

Real behavior proof

Behavior or issue addressed: Scheduled recurring cron jobs that hit a retryable provider error (e.g. MiniMax overloaded_error 503) on an infrequent schedule (#85888 reporter: daily 0 5 * * * Asia/Shanghai during 05:00-07:30 CST) had their next run pushed to the next natural slot (~24h away) instead of being retried with backoff, so the failure was effectively swallowed for that day while manual reruns at 08:30+ succeeded. After this patch, while the error is in cron.retry.retryOn and consecutiveErrors is still within cron.retry.maxAttempts, the next run is scheduled at the configured backoff slot rather than the natural cron/every slot; once retries are exhausted the job falls back to max(naturalNext, backoffNext) so high-frequency schedules cannot bypass backoff.

Real environment tested: Fresh DigitalOcean Fedora 43 Cloud Edition droplet (fedora-s-1vcpu-2gb-nyc1, redacted IP), kernel 6.17.1-300.fc43.x86_64, node v22.22.2, pnpm 9.15.9. Patched OpenClaw checkout at PR head 1c8a66cfe3f47e9dd2a17eaa2c0e93295a9c9d32. Real node:fs/promises writes under /tmp/cron-proof-85888-<redacted>/jobs.json. Real production applyJobResult, real createCronServiceState, real computeJobNextRunAtMs, real resolveCronExecutionRetryHint – none of the scheduler code under test is mocked. The proof-85888.mts script is executed via the project's own tsx (./node_modules/.bin/tsx) directly from the patched repo, outside the vitest test harness.

Exact steps or command run after this patch: Provision the droplet, install Node 22 + pnpm 9, clone the PR head, install deps, then run two captures against the patched code — vitest against the four new #85888 regressions, then a direct tsx invocation of proof-85888.mts that exercises the production applyJobResult outside the test harness on real fs.

dnf install -y nodejs npm git
npm install -g pnpm@9
git clone --branch fix/cron-error-backoff-min-bound-85888 --depth 1 https://github.com/yetval/openclaw.git
cd openclaw
pnpm install --no-frozen-lockfile
node scripts/run-vitest.mjs src/cron/service/timer.regression.test.ts -t "85888" --reporter=verbose
./node_modules/.bin/tsx proof-85888.mts

Evidence after fix: Redacted live terminal output from the Fedora 43 droplet on PR head 1c8a66cfe3. Token, IP, and tmp paths redacted in-place; everything else is the actual stdout from the patched scheduler running on real Linux. Two captures: vitest runner output for the new regressions (real fs via setupCronRegressionFixtures + real Node 22 + real Linux), and a direct tsx-invoked proof-85888.mts runtime script that imports the production applyJobResult and writes a real jobs.json to /tmp.

RUN  v4.1.7 /root/openclaw

 ✓ src/cron/service/timer.regression.test.ts > cron service timer regressions
   > schedules backoff retry within the same day when daily cron fails on a retryable error (#85888) 318ms
 ✓ src/cron/service/timer.regression.test.ts > cron service timer regressions
   > preserves backoff floor for high-frequency recurring jobs whose natural next is sooner than backoff (#85888) 5ms
 ✓ src/cron/service/timer.regression.test.ts > cron service timer regressions
   > clears schedule on retryable cron error when next-run is unresolved (#85888) 6ms
 ✓ src/cron/service/timer.regression.test.ts > cron service timer regressions
   > falls back to the next natural cron slot once retry budget is exhausted (#85888) 7ms

 Test Files  1 passed (1)
      Tests  4 passed (43, 39 skipped)
   Duration  14.07s

Direct runtime proof (proof-85888.mts — real applyJobResult invoked outside the test harness, real fs writes under /tmp, real createCronServiceState, no mocks of the scheduler under test):

===== Scenario 1: daily cron (Asia/Shanghai) MiniMax overload =====
  endedAt:         2026-05-24T05:02:44.264Z
  naturalNext:     2026-05-24T21:00:00.000Z (delta from endedAt: 15.95h)
[warn] cron: job run returned error status {"jobId":"memory-distill","error":"FailoverError: The AI service is temporarily overloaded (overloaded_error). status=503"}
[info] cron: applying error backoff {"jobId":"memory-distill","consecutiveErrors":1,"backoffMs":30000,"nextRunAtMs":1779598994264,"retryable":true,"retryCategory":"overloaded","retryBudgetAvailable":true,"maxAttempts":3,"scheduledMode":"backoff"}
  -> nextRunAtMs:  2026-05-24T05:03:14.264Z
  -> delta:        0.01h
  -> same-day?     YES (fixed)
  -> consecutive:  1

===== Scenario 2: high-frequency every-1s preserves backoff floor =====
  endedAt:         2026-05-24T12:00:00.200Z
  naturalNext:     2026-05-24T12:00:01.000Z (+800ms)
[warn] cron: job run returned error status {"jobId":"tick","error":"FailoverError: ... overloaded_error ... status=503"}
[info] cron: applying error backoff {"jobId":"tick","consecutiveErrors":1,"backoffMs":30000,"nextRunAtMs":1779624030200,"retryable":true,"retryCategory":"overloaded","retryBudgetAvailable":true,"maxAttempts":3,"scheduledMode":"backoff"}
  -> nextRunAtMs:  2026-05-24T12:00:30.200Z
  -> delay (ms):   30000
  -> floor ok?     YES (backoff respected)

===== Scenario 3: exhausted retry budget falls back =====
  endedAt:         2026-05-24T05:02:00.000Z
  naturalNext:     2026-05-24T21:00:00.000Z
  consecutive in:  99
[warn] cron: job run returned error status {"jobId":"memory-distill-exhausted","error":"FailoverError: ... overloaded_error ... status=503"}
[info] cron: applying error backoff {"jobId":"memory-distill-exhausted","consecutiveErrors":100,"backoffMs":300000,"nextRunAtMs":1779656400000,"retryable":true,"retryCategory":"overloaded","retryBudgetAvailable":false,"maxAttempts":3,"scheduledMode":"natural_floor"}
  -> nextRunAtMs:  2026-05-24T21:00:00.000Z
  -> falls back?   YES (natural slot)
  -> enabled?      true

===== fs writes =====
  tmpDir:         /tmp/cron-proof-85888-<redacted>
  jobs.json size: 11

Observed result after fix:

• Scenario 1 is the exact reporter failure mode (0 5 * * * Asia/Shanghai, overloaded_error 503): on current main the runtime would push nextRunAtMs to 2026-05-24T21:00:00.000Z (15.95h away, next-day in Asia/Shanghai); on this PR head it lands at 2026-05-24T05:03:14.264Z (30s after endedAt). Same-day retry achieved. scheduledMode=backoff, retryBudgetAvailable=true.
• Scenario 2 is the prior ClawSweeper P1 concern about high-frequency schedules: with every-1s cadence and a 30s backoff, the patched runtime respects the backoff floor and schedules at endedAt + 30000ms instead of the +800ms natural slot. Retry-storm protection preserved. scheduledMode=backoff.
• Scenario 3 is the prior ClawSweeper P2 concern about exhausted retry budget: once consecutiveErrors > maxAttempts, scheduledMode flips to natural_floor and nextRunAtMs resolves to the next natural cron slot (max(naturalNext, backoffNext) semantics), so a high-frequency schedule cannot bypass backoff after the retry budget is gone. retryBudgetAvailable=false.
• All three scenarios emit a real cron: applying error backoff log line on a real Node 22 process with real fs writes (/tmp/cron-proof-85888-<redacted>/jobs.json).

What was not tested: End-to-end flight against the live MiniMax minimax-portal / MiniMax-M2.7 provider on the issue reporter's tenant. I do not have credentials for that tenant. The retryable-error contract is exercised here by passing the exact FailoverError: The AI service is temporarily overloaded (overloaded_error). status=503 text the issue logs show; the upstream resolveCronExecutionRetryHint and resolveFailoverReasonFromError classifiers are production code and are not mocked in the proof above, so the patched scheduling decision is being made on the same retryable/overloaded classification path that production code would take when MiniMax returns the same error.

Test plan

• node scripts/run-vitest.mjs src/cron/service/timer.regression.test.ts -t "85888" — 4/4 PR regressions pass on Fedora 43 / Node 22
• Direct tsx proof-85888.mts against the patched scheduler — three scenarios match expected behavior
• Full cron suite + cron/retry-hint.test.ts + cron/service.jobs.test.ts in CI