@swarmclawai/swarmclaw 1.9.22 → 1.9.23

package/README.md

@@ -151,13 +151,13 @@ clawhub install swarmclaw
 
 [Browse on ClawHub](https://clawhub.ai/skills/swarmclaw)
 
-## v1.9.17 Highlights
+## v1.9.23 Highlights
 
-Agent configuration history is now visible in the agent editor, so operators can review recent saved versions and restore prior settings without leaving the agent workflow.
+Schedule reliability is now more deterministic for recurring autonomous work, especially after restarts or stale stored timing state.
 
-- **Agent sheet history.** Advanced agent settings list recent saved versions with timestamp, actor, and provider/model snapshot.
-- **One-click restore.** Restoring a prior version uses the existing config-version restore API, refreshes agent state, and closes the sheet to avoid stale form data.
-- **Regression coverage.** New tests cover config-version list/restore routes and UI summary formatting.
+- **Cron drift repair.** Active schedules repair stale future cron slots before they skip the nearest run.
+- **Stable stagger.** Staggered schedules keep a deterministic per-schedule offset.
+- **Mission continuity.** Schedule-created board tasks keep a persistent mission link across recurring runs.
 
 ## Hosted Deploys
 
@@ -409,6 +409,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.23 Highlights
+
+Schedule reliability release: recurring work now repairs stale timing state before it can skip the nearest run, and scheduled board tasks keep mission context across repeat launches.
+
+- **Cron drift repair.** Active cron schedules repair missing or invalid `nextRunAt` values and stale future cron slots before the scheduler decides whether work is due.
+- **Tick-time advancement.** Cron and interval schedules now advance from the scheduler tick time instead of the process wall clock, making restart and catch-up behavior deterministic.
+- **Stable stagger.** Schedule stagger offsets are deterministic per schedule, avoiding thundering-herd launches without moving a saved next-run target on every recompute.
+- **Mission continuity.** Schedule-created board tasks attach to a persistent mission link, so recurring runs share the same operational context.
+
 ### v1.9.22 Highlights
 
 Research tools release: agents now get direct `web_extract` and `web_crawl` tools alongside `web_search`, `web_fetch`, and the unified `web` tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.22",
+  "version": "1.9.23",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",
@@ -88,7 +88,7 @@
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/electron-signing-config.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/agent-config-history.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/provider-diagnostics.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/server/schedules/schedule-preview.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/server/session-tools/web-crawl.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/config-versions/config-versions-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/preview/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/agent-config-history.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/provider-diagnostics.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/server/schedules/schedule-timing.test.ts src/lib/server/schedules/schedule-preview.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/server/session-tools/web-crawl.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/config-versions/config-versions-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/preview/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

package/src/components/schedules/schedule-console.tsx

@@ -162,6 +162,8 @@ function historyActionLabel(action: ScheduleHistoryEntry['action']): string {
       return 'Skipped'
     case 'failed':
       return 'Failed'
+    case 'repaired':
+      return 'Repaired'
     default:
       return action
   }
@@ -171,6 +173,7 @@ function historyActionBadge(action: ScheduleHistoryEntry['action']): string {
   if (action === 'created' || action === 'restored' || action === 'run_started') return badgeClass('completed')
   if (action === 'failed') return badgeClass('failed')
   if (action === 'skipped' || action === 'archived') return badgeClass('paused')
+  if (action === 'repaired') return badgeClass('running')
   return badgeClass('running')
 }
 

package/src/lib/server/runtime/scheduler.test.ts

@@ -202,6 +202,135 @@ describe('scheduler wake targeting', () => {
     assert.deepEqual(output.deliveryModes, ['silent'])
   })
 
+  it('repairs stale future cron next-run slots without launching a run', () => {
+    const output = runSchedulerWithTempDataDir(`
+      const storageMod = await import('@/lib/server/storage')
+      const schedulerMod = await import('@/lib/server/runtime/scheduler')
+      const storage = storageMod.default || storageMod
+      const scheduler = schedulerMod.default || schedulerMod
+
+      const now = Date.parse('2026-05-06T07:30:00.000Z')
+      const staleFuture = Date.parse('2026-05-12T08:00:00.000Z')
+
+      storage.saveSchedules({
+        'sched-cron': {
+          id: 'sched-cron',
+          name: 'Daily status',
+          agentId: 'agent-1',
+          taskPrompt: 'Send the daily status.',
+          scheduleType: 'cron',
+          cron: '0 8 * * *',
+          timezone: 'UTC',
+          status: 'active',
+          nextRunAt: staleFuture,
+          createdAt: now - 10_000,
+          updatedAt: now - 10_000,
+        },
+      })
+
+      await scheduler.runSchedulerTickForTests(now)
+      const schedule = storage.loadSchedules()['sched-cron']
+
+      console.log(JSON.stringify({
+        status: schedule.status,
+        nextRunAt: schedule.nextRunAt,
+        taskCount: Object.keys(storage.loadTasks()).length,
+        historyAction: schedule.history?.[0]?.action || null,
+        historyReason: schedule.history?.[0]?.metadata?.reason || null,
+      }))
+    `)
+
+    assert.equal(output.status, 'active')
+    assert.equal(output.nextRunAt, Date.parse('2026-05-06T08:00:00.000Z'))
+    assert.equal(output.taskCount, 0)
+    assert.equal(output.historyAction, 'repaired')
+    assert.equal(output.historyReason, 'stale_future')
+  })
+
+  it('advances cron schedules from the scheduler tick time after firing', () => {
+    const output = runSchedulerWithTempDataDir(`
+      const storageMod = await import('@/lib/server/storage')
+      const schedulerMod = await import('@/lib/server/runtime/scheduler')
+      const heartbeatWakeMod = await import('@/lib/server/runtime/heartbeat-wake')
+      const storage = storageMod.default || storageMod
+      const scheduler = schedulerMod.default || schedulerMod
+      const heartbeatWake = heartbeatWakeMod.default || heartbeatWakeMod
+
+      const now = Date.parse('2030-01-01T08:00:30.000Z')
+      const dueAt = Date.parse('2030-01-01T08:00:00.000Z')
+
+      storage.saveAgents({
+        'agent-1': {
+          id: 'agent-1',
+          name: 'Daily Agent',
+          description: '',
+          systemPrompt: '',
+          provider: 'openai',
+          model: 'gpt-test',
+          threadSessionId: 'thread-main',
+          createdAt: now - 10_000,
+          updatedAt: now - 10_000,
+        },
+      })
+
+      storage.saveSessions({
+        'thread-main': {
+          id: 'thread-main',
+          name: 'Daily Agent',
+          cwd: process.env.WORKSPACE_DIR,
+          user: 'tester',
+          provider: 'openai',
+          model: 'gpt-test',
+          claudeSessionId: null,
+          messages: [],
+          createdAt: now - 10_000,
+          lastActiveAt: now - 5_000,
+          active: true,
+          currentRunId: null,
+          agentId: 'agent-1',
+          shortcutForAgentId: 'agent-1',
+        },
+      })
+
+      storage.saveSchedules({
+        'sched-cron': {
+          id: 'sched-cron',
+          name: 'Daily wake',
+          agentId: 'agent-1',
+          taskPrompt: 'Wake for the daily status.',
+          taskMode: 'wake_only',
+          message: 'Run the daily status.',
+          scheduleType: 'cron',
+          cron: '0 8 * * *',
+          timezone: 'UTC',
+          status: 'active',
+          nextRunAt: dueAt,
+          createdInSessionId: 'thread-main',
+          createdAt: now - 10_000,
+          updatedAt: now - 10_000,
+        },
+      })
+
+      await scheduler.runSchedulerTickForTests(now)
+      const schedule = storage.loadSchedules()['sched-cron']
+      const wakes = heartbeatWake.snapshotPendingHeartbeatWakesForTests()
+
+      console.log(JSON.stringify({
+        status: schedule.status,
+        nextRunAt: schedule.nextRunAt,
+        runNumber: schedule.runNumber,
+        historyAction: schedule.history?.[0]?.action || null,
+        wakeCount: wakes.length,
+      }))
+    `)
+
+    assert.equal(output.status, 'active')
+    assert.equal(output.nextRunAt, Date.parse('2030-01-02T08:00:00.000Z'))
+    assert.equal(output.runNumber, 1)
+    assert.equal(output.historyAction, 'run_started')
+    assert.equal(output.wakeCount, 1)
+  })
+
   it('reuses a persistent mission for scheduled task runs', () => {
     const output = runSchedulerWithTempDataDir(`
       const storageMod = await import('@/lib/server/storage')

package/src/lib/server/runtime/scheduler.ts

@@ -2,7 +2,6 @@ import { listAgents } from '@/lib/server/agents/agent-repository'
 import { loadSchedules, upsertSchedule, upsertSchedules } from '@/lib/server/schedules/schedule-repository'
 import { loadTasks, upsertTask } from '@/lib/server/tasks/task-repository'
 import { enqueueTask } from '@/lib/server/runtime/queue'
-import { CronExpressionParser } from 'cron-parser'
 import { pushMainLoopEventToMainSessions } from '@/lib/server/agents/main-agent-loop'
 import { getScheduleSignatureKey } from '@/lib/schedules/schedule-dedupe'
 import { dispatchWake } from '@/lib/server/runtime/wake-dispatcher'
@@ -14,6 +13,7 @@ import { hasActiveProtocolRunForSchedule, launchProtocolRunForSchedule } from '@
 import { hmrSingleton } from '@/lib/shared-utils'
 import { log } from '@/lib/server/logger'
 import { appendScheduleHistoryEntry } from '@/lib/server/schedules/schedule-history'
+import { assessScheduleNextRunRepair, computeScheduleNextRunAt } from '@/lib/server/schedules/schedule-timing'
 import type { Schedule } from '@/types'
 
 const TAG = 'scheduler'
@@ -52,7 +52,7 @@ export function startScheduler() {
   if (schedulerState.intervalId) return
   log.info(TAG, 'Starting scheduler engine (60s tick)')
 
-  // Compute initial nextRunAt for cron schedules missing it
+  // Compute initial timing and repair stale nextRunAt values before the first tick.
   computeNextRuns()
 
   schedulerState.intervalId = setInterval(tick, TICK_INTERVAL)
@@ -66,32 +66,64 @@ export function stopScheduler() {
   }
 }
 
-function computeNextRuns() {
+function computeNextRuns(now = Date.now()): Record<string, Schedule> {
   const schedules = loadSchedules()
   const changedEntries: Array<[string, Schedule]> = []
   for (const schedule of Object.values(schedules)) {
     if (schedule.status !== 'active') continue
-    if (schedule.scheduleType === 'cron' && schedule.cron && !schedule.nextRunAt) {
-      try {
-        const interval = CronExpressionParser.parse(
-          schedule.cron,
-          schedule.timezone ? { tz: schedule.timezone } : undefined,
-        )
-        schedule.nextRunAt = interval.next().getTime()
-        changedEntries.push([schedule.id, schedule])
-      } catch (err) {
-        log.error(TAG, `Invalid cron for ${schedule.id}:`, err)
-        schedule.status = 'failed'
-        changedEntries.push([schedule.id, schedule])
-      }
+    const assessment = assessScheduleNextRunRepair(schedule, now)
+    if (!assessment.ok) {
+      log.error(TAG, `Invalid cron for ${schedule.id}`)
+      const failedSchedule = appendScheduleHistoryEntry({
+        ...schedule,
+        status: 'failed',
+        updatedAt: now,
+      }, {
+        now,
+        actor: 'system',
+        action: 'failed',
+        summary: `Schedule failed because cron could not be parsed: "${schedule.name}"`,
+        changes: [{
+          field: 'status',
+          label: 'Status',
+          before: 'active',
+          after: 'failed',
+        }],
+        metadata: { reason: 'invalid_cron' },
+      })
+      schedules[schedule.id] = failedSchedule
+      changedEntries.push([schedule.id, failedSchedule])
+      continue
+    }
+    if (assessment.repair) {
+      const repairedSchedule = appendScheduleHistoryEntry({
+        ...schedule,
+        nextRunAt: assessment.nextRunAt,
+        updatedAt: now,
+      }, {
+        now,
+        actor: 'system',
+        action: 'repaired',
+        summary: `Schedule timing repaired: "${schedule.name}"`,
+        changes: [{
+          field: 'nextRunAt',
+          label: 'Next run',
+          before: assessment.previousNextRunAt == null ? null : String(assessment.previousNextRunAt),
+          after: String(assessment.nextRunAt),
+        }],
+        metadata: { reason: assessment.reason },
+      })
+      schedules[schedule.id] = repairedSchedule
+      changedEntries.push([schedule.id, repairedSchedule])
     }
   }
   if (changedEntries.length > 0) upsertSchedules(changedEntries)
+  return schedules
 }
 
 async function tick(now = Date.now()) {
   await processDueWatchJobs(now)
-  const schedules = loadSchedules()
+  const schedules = computeNextRuns(now)
   const agents = listAgents()
   const tasks = loadTasks()
   const inFlightScheduleKeys = new Set<string>(
@@ -101,27 +133,22 @@ async function tick(now = Date.now()) {
       .filter((value: string) => value.length > 0),
   )
 
-  const applyStagger = (ts: number, staggerSec: number | null | undefined): number => {
-    if (!staggerSec || staggerSec <= 0) return ts
-    return ts + Math.floor(Math.random() * staggerSec * 1000)
-  }
-
   const advanceSchedule = (schedule: Schedule): void => {
-    if (schedule.scheduleType === 'cron' && schedule.cron) {
-      try {
-        const interval = CronExpressionParser.parse(
-          schedule.cron,
-          schedule.timezone ? { tz: schedule.timezone } : undefined,
-        )
-        schedule.nextRunAt = applyStagger(interval.next().getTime(), schedule.staggerSec)
-      } catch {
-        schedule.status = 'failed'
-      }
-    } else if (schedule.scheduleType === 'interval' && schedule.intervalMs) {
-      schedule.nextRunAt = applyStagger(now + schedule.intervalMs, schedule.staggerSec)
-    } else if (schedule.scheduleType === 'once') {
+    if (schedule.scheduleType === 'once') {
       schedule.status = 'completed'
       schedule.nextRunAt = undefined
+      return
+    }
+
+    try {
+      const nextRunAt = computeScheduleNextRunAt(schedule, now)
+      if (nextRunAt == null) {
+        schedule.status = 'failed'
+      } else {
+        schedule.nextRunAt = nextRunAt
+      }
+    } catch {
+      schedule.status = 'failed'
     }
   }
 

package/src/lib/server/schedules/schedule-history.test.ts

@@ -118,4 +118,18 @@ describe('schedule history', () => {
     assert.equal(history[24].id, 'hist-5')
     assert.equal(schedule.revision, 30)
   })
+
+  it('retains scheduler repair history entries', () => {
+    const history = normalizeScheduleHistory([{
+      id: 'hist-repair',
+      at: 1_000,
+      actor: 'system',
+      action: 'repaired',
+      revision: 1,
+      summary: 'Schedule timing repaired',
+    }])
+
+    assert.equal(history.length, 1)
+    assert.equal(history[0].action, 'repaired')
+  })
 })

package/src/lib/server/schedules/schedule-history.ts

@@ -57,6 +57,7 @@ const HISTORY_ACTIONS = new Set<ScheduleHistoryAction>([
   'run_started',
   'skipped',
   'failed',
+  'repaired',
 ])
 
 function cleanActor(value: string): string {

package/src/lib/server/schedules/schedule-lifecycle.ts

@@ -1,5 +1,3 @@
-import { CronExpressionParser } from 'cron-parser'
-
 import { genId } from '@/lib/id'
 import type { BoardTask, Schedule, ScheduleStatus, Session } from '@/types'
 import { pushMainLoopEventToMainSessions } from '@/lib/server/agents/main-agent-loop'
@@ -19,6 +17,7 @@ import {
 import { notify } from '@/lib/server/ws-hub'
 import { getScheduleClusterIds } from '@/lib/server/schedules/schedule-service'
 import { appendScheduleHistoryEntry } from '@/lib/server/schedules/schedule-history'
+import { computeScheduleNextRunAt } from '@/lib/server/schedules/schedule-timing'
 
 type RestorableScheduleStatus = Exclude<ScheduleStatus, 'archived'>
 
@@ -50,33 +49,11 @@ export interface SchedulePurgeResult {
 }
 
 function computeNextRunAt(schedule: Pick<Schedule, 'scheduleType' | 'cron' | 'intervalMs' | 'runAt' | 'timezone' | 'staggerSec'>, now: number): number | undefined {
-  const applyStagger = (timestamp: number): number => {
-    if (!schedule.staggerSec || schedule.staggerSec <= 0) return timestamp
-    return timestamp + Math.floor(Math.random() * schedule.staggerSec * 1000)
-  }
-
-  if (schedule.scheduleType === 'once') {
-    return typeof schedule.runAt === 'number' && Number.isFinite(schedule.runAt)
-      ? applyStagger(schedule.runAt)
-      : undefined
-  }
-  if (schedule.scheduleType === 'interval') {
-    return typeof schedule.intervalMs === 'number' && Number.isFinite(schedule.intervalMs)
-      ? applyStagger(now + schedule.intervalMs)
-      : undefined
-  }
-  if (schedule.scheduleType === 'cron' && typeof schedule.cron === 'string' && schedule.cron.trim()) {
-    try {
-      const interval = CronExpressionParser.parse(
-        schedule.cron,
-        schedule.timezone ? { tz: schedule.timezone } : undefined,
-      )
-      return applyStagger(interval.next().getTime())
-    } catch {
-      return undefined
-    }
+  try {
+    return computeScheduleNextRunAt(schedule, now)
+  } catch {
+    return undefined
   }
-  return undefined
 }
 
 function cloneSchedule(schedule: Schedule): Schedule {

package/src/lib/server/schedules/schedule-normalization.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { CronExpressionParser } from 'cron-parser'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+import { computeScheduleNextRunAt } from '@/lib/server/schedules/schedule-timing'
 
 type SchedulePayload = Record<string, unknown>
 
@@ -86,15 +86,6 @@ function parseAtTimeToCron(atTime: string): string | null {
   return `${minutes} ${hours} * * *`
 }
 
-/**
- * Apply a random stagger offset (in seconds) to a timestamp.
- */
-function applyStagger(timestamp: number, staggerSec: number | null | undefined): number {
-  if (!staggerSec || staggerSec <= 0) return timestamp
-  const offset = Math.floor(Math.random() * staggerSec * 1000)
-  return timestamp + offset
-}
-
 function normalizePositiveInt(value: unknown): number | null {
   const parsed = typeof value === 'number'
     ? value
@@ -326,24 +317,11 @@ export function normalizeSchedulePayload(payload: SchedulePayload, opts: Normali
   }
 
   if (normalized.status !== 'archived' && normalized.nextRunAt == null) {
-    if (normalized.scheduleType === 'once') {
-      if (runAt != null) normalized.nextRunAt = applyStagger(runAt, normalized.staggerSec as number | null)
-    } else if (normalized.scheduleType === 'interval') {
-      if (intervalMs != null) normalized.nextRunAt = applyStagger(now + intervalMs, normalized.staggerSec as number | null)
-    } else if (normalized.scheduleType === 'cron' && normalized.cron) {
-      try {
-        const cronTimezone = trimString(normalized.timezone)
-        const interval = CronExpressionParser.parse(
-          normalized.cron as string,
-          {
-            ...(cronTimezone ? { tz: cronTimezone } : {}),
-            currentDate: new Date(now),
-          },
-        )
-        normalized.nextRunAt = applyStagger(interval.next().getTime(), normalized.staggerSec as number | null)
-      } catch {
-        return { ok: false, error: 'Error: invalid cron expression.' }
-      }
+    try {
+      const computedNextRunAt = computeScheduleNextRunAt(normalized, now)
+      if (computedNextRunAt != null) normalized.nextRunAt = computedNextRunAt
+    } catch {
+      return { ok: false, error: 'Error: invalid cron expression.' }
     }
   }
 

package/src/lib/server/schedules/schedule-timing.test.ts

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  assessScheduleNextRunRepair,
+  computeScheduleNextRunAt,
+  stableScheduleStaggerMs,
+} from '@/lib/server/schedules/schedule-timing'
+
+describe('schedule timing', () => {
+  it('computes cron next runs from the provided scheduler time', () => {
+    const nextRunAt = computeScheduleNextRunAt({
+      id: 'sched-daily',
+      name: 'Daily status',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: '0 8 * * *',
+      timezone: 'UTC',
+    }, Date.parse('2030-01-01T08:00:30.000Z'))
+
+    assert.equal(nextRunAt, Date.parse('2030-01-02T08:00:00.000Z'))
+  })
+
+  it('uses deterministic schedule stagger inside the configured window', () => {
+    const schedule = {
+      id: 'sched-staggered',
+      name: 'Staggered status',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: '0 8 * * *',
+      timezone: 'UTC',
+      staggerSec: 30,
+    }
+
+    const first = stableScheduleStaggerMs(schedule)
+    const second = stableScheduleStaggerMs(schedule)
+
+    assert.equal(first, second)
+    assert.ok(first >= 0)
+    assert.ok(first < 30_000)
+  })
+
+  it('repairs stale future cron slots to the earliest upcoming slot', () => {
+    const assessment = assessScheduleNextRunRepair({
+      id: 'sched-stale',
+      name: 'Daily status',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: '0 8 * * *',
+      timezone: 'UTC',
+      status: 'active',
+      nextRunAt: Date.parse('2026-05-12T08:00:00.000Z'),
+    }, Date.parse('2026-05-06T07:30:00.000Z'))
+
+    assert.equal(assessment.ok, true)
+    assert.equal(assessment.repair, true)
+    if (assessment.ok && assessment.repair) {
+      assert.equal(assessment.reason, 'stale_future')
+      assert.equal(assessment.nextRunAt, Date.parse('2026-05-06T08:00:00.000Z'))
+    }
+  })
+
+  it('flags invalid due cron schedules before they launch', () => {
+    const assessment = assessScheduleNextRunRepair({
+      id: 'sched-invalid',
+      name: 'Broken cron',
+      agentId: 'agent-1',
+      scheduleType: 'cron',
+      cron: 'not a cron',
+      status: 'active',
+      nextRunAt: Date.parse('2026-05-06T07:00:00.000Z'),
+    }, Date.parse('2026-05-06T07:30:00.000Z'))
+
+    assert.equal(assessment.ok, false)
+    if (!assessment.ok) {
+      assert.equal(assessment.reason, 'invalid_cron')
+      assert.equal(assessment.previousNextRunAt, Date.parse('2026-05-06T07:00:00.000Z'))
+    }
+  })
+})

package/src/lib/server/schedules/schedule-timing.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto'
+
+import { CronExpressionParser } from 'cron-parser'
+
+import type { ScheduleType } from '@/types'
+
+export type ScheduleTimingRepairReason = 'missing' | 'invalid' | 'stale_future'
+
+export type ScheduleTimingInput = {
+  id?: string | null
+  name?: string | null
+  agentId?: string | null
+  taskPrompt?: string | null
+  scheduleType?: ScheduleType | string | null
+  cron?: string | null
+  intervalMs?: number | null
+  runAt?: number | null
+  timezone?: string | null
+  staggerSec?: number | null
+  nextRunAt?: number | null
+  status?: string | null
+}
+
+export type ScheduleNextRunRepairAssessment =
+  | { ok: true; repair: false }
+  | {
+      ok: true
+      repair: true
+      reason: ScheduleTimingRepairReason
+      nextRunAt: number
+      previousNextRunAt: number | null
+    }
+  | {
+      ok: false
+      reason: 'invalid_cron'
+      previousNextRunAt: number | null
+    }
+
+const CRON_REPAIR_TOLERANCE_MS = 1_000
+
+function trimString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function normalizeTimestamp(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null
+  const normalized = Math.trunc(value)
+  return normalized > 0 ? normalized : null
+}
+
+function normalizeNow(value: number): number {
+  return Number.isFinite(value) ? Math.trunc(value) : Date.now()
+}
+
+function normalizeStaggerWindowMs(staggerSec: unknown): number {
+  if (typeof staggerSec !== 'number' || !Number.isFinite(staggerSec) || staggerSec <= 0) return 0
+  return Math.min(Math.trunc(staggerSec * 1000), Number.MAX_SAFE_INTEGER)
+}
+
+function stableScheduleKey(schedule: ScheduleTimingInput): string {
+  return [
+    trimString(schedule.id),
+    trimString(schedule.agentId),
+    trimString(schedule.name),
+    trimString(schedule.taskPrompt),
+    trimString(schedule.scheduleType),
+    trimString(schedule.cron),
+    typeof schedule.intervalMs === 'number' && Number.isFinite(schedule.intervalMs) ? Math.trunc(schedule.intervalMs) : '',
+    typeof schedule.runAt === 'number' && Number.isFinite(schedule.runAt) ? Math.trunc(schedule.runAt) : '',
+    trimString(schedule.timezone),
+  ].join('\0')
+}
+
+export function stableScheduleStaggerMs(schedule: ScheduleTimingInput): number {
+  const windowMs = normalizeStaggerWindowMs(schedule.staggerSec)
+  if (windowMs <= 0) return 0
+  const digest = createHash('sha256').update(stableScheduleKey(schedule)).digest()
+  const value = digest.readBigUInt64BE(0)
+  return Number(value % BigInt(windowMs))
+}
+
+function applyStableStagger(timestamp: number, schedule: ScheduleTimingInput): number {
+  return Math.trunc(timestamp + stableScheduleStaggerMs(schedule))
+}
+
+function parseCron(schedule: ScheduleTimingInput, now: number) {
+  const cron = trimString(schedule.cron)
+  if (!cron) return null
+  const timezone = trimString(schedule.timezone)
+  return CronExpressionParser.parse(cron, {
+    ...(timezone ? { tz: timezone } : {}),
+    currentDate: new Date(normalizeNow(now)),
+  })
+}
+
+export function computeScheduleNextRunAt(schedule: ScheduleTimingInput, now: number): number | undefined {
+  const scheduleType = trimString(schedule.scheduleType)
+  if (scheduleType === 'once') {
+    const runAt = normalizeTimestamp(schedule.runAt)
+    return runAt == null ? undefined : applyStableStagger(runAt, schedule)
+  }
+  if (scheduleType === 'interval') {
+    const intervalMs = normalizeTimestamp(schedule.intervalMs)
+    return intervalMs == null ? undefined : applyStableStagger(normalizeNow(now) + intervalMs, schedule)
+  }
+  if (scheduleType === 'cron') {
+    const interval = parseCron(schedule, now)
+    if (!interval) return undefined
+    return applyStableStagger(interval.next().getTime(), schedule)
+  }
+  return undefined
+}
+
+function computeCronWindow(schedule: ScheduleTimingInput, now: number): { earliest: number; latest: number; nextRunAt: number } | null {
+  const interval = parseCron(schedule, now)
+  if (!interval) return null
+  const earliest = interval.next().getTime()
+  const latest = earliest + normalizeStaggerWindowMs(schedule.staggerSec)
+  return {
+    earliest,
+    latest,
+    nextRunAt: applyStableStagger(earliest, schedule),
+  }
+}
+
+export function assessScheduleNextRunRepair(
+  schedule: ScheduleTimingInput,
+  now: number,
+): ScheduleNextRunRepairAssessment {
+  if (trimString(schedule.status) && trimString(schedule.status) !== 'active') return { ok: true, repair: false }
+
+  const previousNextRunAt = normalizeTimestamp(schedule.nextRunAt)
+  const hasNextRunAt = schedule.nextRunAt != null
+  if (previousNextRunAt != null && previousNextRunAt <= normalizeNow(now)) {
+    if (trimString(schedule.scheduleType) === 'cron') {
+      try {
+        if (!parseCron(schedule, now)) return { ok: false, reason: 'invalid_cron', previousNextRunAt }
+      } catch {
+        return { ok: false, reason: 'invalid_cron', previousNextRunAt }
+      }
+    }
+    return { ok: true, repair: false }
+  }
+
+  if (previousNextRunAt == null) {
+    try {
+      const nextRunAt = computeScheduleNextRunAt(schedule, now)
+      if (nextRunAt == null) return { ok: true, repair: false }
+      return {
+        ok: true,
+        repair: true,
+        reason: hasNextRunAt ? 'invalid' : 'missing',
+        nextRunAt,
+        previousNextRunAt: null,
+      }
+    } catch {
+      return { ok: false, reason: 'invalid_cron', previousNextRunAt: null }
+    }
+  }
+
+  if (trimString(schedule.scheduleType) !== 'cron') return { ok: true, repair: false }
+
+  try {
+    const window = computeCronWindow(schedule, now)
+    if (!window) return { ok: true, repair: false }
+    const tooEarly = previousNextRunAt < window.earliest - CRON_REPAIR_TOLERANCE_MS
+    const tooLate = previousNextRunAt > window.latest + CRON_REPAIR_TOLERANCE_MS
+    if (!tooEarly && !tooLate) return { ok: true, repair: false }
+    return {
+      ok: true,
+      repair: true,
+      reason: 'stale_future',
+      nextRunAt: window.nextRunAt,
+      previousNextRunAt,
+    }
+  } catch {
+    return { ok: false, reason: 'invalid_cron', previousNextRunAt }
+  }
+}

package/src/lib/server/tasks/task-lifecycle.ts

@@ -8,6 +8,9 @@ import {
   type TaskCompletionValidation,
 } from '@/lib/server/tasks/task-validation'
 import { syncTaskExecutionPolicyState } from '@/lib/server/tasks/task-execution-policy'
+import { createMission, startMission } from '@/lib/server/missions/mission-service'
+import { getMission } from '@/lib/server/missions/mission-repository'
+import { loadSessions } from '@/lib/server/storage'
 
 export interface BuildBoardTaskInput {
   id?: string
@@ -84,6 +87,7 @@ export interface PrepareScheduledTaskRunOptions {
     | 'agentId'
     | 'taskPrompt'
     | 'linkedTaskId'
+    | 'linkedMissionId'
     | 'runNumber'
     | 'createdInSessionId'
     | 'createdByAgentId'
@@ -98,20 +102,45 @@ export interface PrepareScheduledTaskRunOptions {
   scheduleSignature?: string | null
 }
 
+function ensureScheduleMission(schedule: PrepareScheduledTaskRunOptions['schedule']): string | null {
+  const existingMissionId = typeof schedule.linkedMissionId === 'string' ? schedule.linkedMissionId.trim() : ''
+  if (existingMissionId && getMission(existingMissionId)) return existingMissionId
+
+  const rootSessionId = typeof schedule.createdInSessionId === 'string' ? schedule.createdInSessionId.trim() : ''
+  if (!rootSessionId) return existingMissionId || null
+  const sessions = loadSessions()
+  if (!sessions[rootSessionId]) return existingMissionId || null
+
+  const mission = createMission({
+    title: `Scheduled task: ${schedule.name}`,
+    goal: schedule.taskPrompt || schedule.name,
+    successCriteria: ['Scheduled run is queued, executed, and reported back to the task board.'],
+    rootSessionId,
+    agentIds: [schedule.agentId].filter(Boolean),
+    reportSchedule: null,
+  })
+  startMission(mission.id)
+  schedule.linkedMissionId = mission.id
+  return mission.id
+}
+
 export function prepareScheduledTaskRun(params: PrepareScheduledTaskRunOptions): { taskId: string; task: BoardTask } {
   const { schedule, tasks, now, scheduleSignature } = params
   const title = `[Sched] ${schedule.name} (run #${schedule.runNumber})`
   const existingTaskId = typeof schedule.linkedTaskId === 'string' ? schedule.linkedTaskId : ''
   const existingTask = existingTaskId ? tasks[existingTaskId] : null
+  const missionId = ensureScheduleMission(schedule)
 
   if (existingTask && existingTask.status !== 'queued' && existingTask.status !== 'running') {
+    const task = resetTaskForRerun(existingTask, {
+      title,
+      now,
+      runNumber: schedule.runNumber,
+    })
+    task.missionId = missionId
     return {
       taskId: existingTaskId,
-      task: resetTaskForRerun(existingTask, {
-        title,
-        now,
-        runNumber: schedule.runNumber,
-      }),
+      task,
     }
   }
 
@@ -125,6 +154,7 @@ export function prepareScheduledTaskRun(params: PrepareScheduledTaskRunOptions):
       sourceScheduleId: schedule.id,
       sourceScheduleName: schedule.name,
       sourceScheduleKey: scheduleSignature || null,
+      missionId,
       createdInSessionId: schedule.createdInSessionId || null,
       createdByAgentId: schedule.createdByAgentId || null,
       followupConnectorId: schedule.followupConnectorId || null,

package/src/types/schedule.ts

@@ -3,7 +3,7 @@ import type { ExtensionManagedResourceMarker } from './extension'
 export type ScheduleType = 'cron' | 'interval' | 'once'
 export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'failed' | 'archived'
 export type ScheduleTaskMode = 'task' | 'wake_only' | 'protocol'
-export type ScheduleHistoryAction = 'created' | 'updated' | 'archived' | 'restored' | 'run_started' | 'skipped' | 'failed'
+export type ScheduleHistoryAction = 'created' | 'updated' | 'archived' | 'restored' | 'run_started' | 'skipped' | 'failed' | 'repaired'
 
 export interface ScheduleHistoryChange {
   field: string
@@ -55,7 +55,7 @@ export interface Schedule {
   nextRunAt?: number
   /** IANA timezone for schedule evaluation (default: system local) */
   timezone?: string | null
-  /** Random stagger window in seconds added to nextRunAt to avoid thundering herd */
+  /** Deterministic stagger window in seconds added to nextRunAt to avoid thundering herd */
   staggerSec?: number | null
   /** Last delivery status for this schedule */
   lastDeliveryStatus?: 'ok' | 'error' | null

package/src/types/task.ts

@@ -182,6 +182,7 @@ export interface BoardTask {
   cwd?: string | null
   file?: string | null
   sessionId?: string | null
+  missionId?: string | null
   completionReportPath?: string | null
   result?: string | null
   error?: string | null