@swarmclawai/swarmclaw 1.9.22 → 1.9.24

package/src/lib/server/gateways/gateway-profile-service.ts

@@ -27,6 +27,29 @@ function normalizeNullableNumber(value: unknown): number | null {
   return typeof value === 'number' && Number.isFinite(value) ? value : null
 }
 
+function normalizeLifecycleState(value: unknown): NonNullable<GatewayProfile['lifecycleState']> {
+  return value === 'draining' || value === 'cordoned' ? value : 'active'
+}
+
+function normalizeControlAction(value: unknown): GatewayProfile['lastControlAction'] {
+  return value === 'activate' || value === 'drain' || value === 'cordon' || value === 'restart'
+    ? value
+    : null
+}
+
+function normalizeControlRequest(value: unknown): GatewayProfile['controlRequest'] {
+  if (!value || typeof value !== 'object') return null
+  const request = value as Record<string, unknown>
+  const requestedAt = normalizeNullableNumber(request.requestedAt)
+  if (request.action !== 'restart' || !requestedAt) return null
+  return {
+    action: 'restart',
+    requestedAt,
+    source: 'swarmclaw',
+    reason: normalizeText(request.reason),
+  }
+}
+
 function normalizeDeployment(value: unknown): OpenClawDeploymentConfig | null {
   if (!value || typeof value !== 'object') return null
   const deployment = value as Record<string, unknown>
@@ -106,6 +129,11 @@ export function createGatewayProfile(input: Record<string, unknown>): GatewayPro
     wsUrl: normalizeText(input.wsUrl),
     credentialId: normalizeText(input.credentialId),
     status: typeof input.status === 'string' && input.status.trim() ? input.status as GatewayProfile['status'] : 'unknown',
+    lifecycleState: normalizeLifecycleState(input.lifecycleState),
+    lastControlAction: normalizeControlAction(input.lastControlAction),
+    lastControlActionAt: normalizeNullableNumber(input.lastControlActionAt),
+    lastControlReason: normalizeText(input.lastControlReason),
+    controlRequest: normalizeControlRequest(input.controlRequest),
     notes: typeof input.notes === 'string' ? input.notes : null,
     tags: normalizeTags(input.tags),
     lastError: null,
@@ -149,6 +177,11 @@ export function updateGatewayProfile(id: string, input: Record<string, unknown>)
       : 'unknown'
     gateway.status = nextStatus
   }
+  if (input.lifecycleState !== undefined) gateway.lifecycleState = normalizeLifecycleState(input.lifecycleState)
+  if (input.lastControlAction !== undefined) gateway.lastControlAction = normalizeControlAction(input.lastControlAction)
+  if (input.lastControlActionAt !== undefined) gateway.lastControlActionAt = normalizeNullableNumber(input.lastControlActionAt)
+  if (input.lastControlReason !== undefined) gateway.lastControlReason = normalizeText(input.lastControlReason)
+  if (input.controlRequest !== undefined) gateway.controlRequest = normalizeControlRequest(input.controlRequest)
   if (input.notes !== undefined) gateway.notes = typeof input.notes === 'string' ? input.notes : null
   if (input.tags !== undefined) gateway.tags = normalizeTags(input.tags)
   if (input.lastError !== undefined) gateway.lastError = typeof input.lastError === 'string' ? input.lastError : null
@@ -167,6 +200,44 @@ export function updateGatewayProfile(id: string, input: Record<string, unknown>)
   return gateway
 }
 
+export function controlGatewayProfile(
+  id: string,
+  input: { action: NonNullable<GatewayProfile['lastControlAction']>; reason?: string | null },
+  now = Date.now(),
+): GatewayProfile | null {
+  const gateways = loadGatewayProfiles()
+  const gateway = gateways[id]
+  if (!gateway) return null
+
+  const action = normalizeControlAction(input.action)
+  if (!action) return null
+
+  gateway.lifecycleState = action === 'drain'
+    ? 'draining'
+    : action === 'cordon'
+      ? 'cordoned'
+      : action === 'activate'
+        ? 'active'
+        : normalizeLifecycleState(gateway.lifecycleState)
+  gateway.lastControlAction = action
+  gateway.lastControlActionAt = now
+  gateway.lastControlReason = normalizeText(input.reason)
+  gateway.controlRequest = action === 'restart'
+    ? {
+        action: 'restart',
+        requestedAt: now,
+        source: 'swarmclaw',
+        reason: normalizeText(input.reason),
+      }
+    : null
+  gateway.updatedAt = now
+
+  gateways[id] = gateway
+  saveGatewayProfiles(gateways)
+  notify('gateways')
+  return gateway
+}
+
 export function deleteGatewayProfileAndDetachAgents(id: string): boolean {
   const gateways = loadGatewayProfiles()
   const deleted = gateways[id]

package/src/lib/server/operations/operation-pulse.test.ts

@@ -88,6 +88,11 @@ function gateway(overrides: Partial<GatewayProfile>): GatewayProfile {
     wsUrl: overrides.wsUrl ?? null,
     credentialId: overrides.credentialId ?? null,
     status: overrides.status || 'healthy',
+    lifecycleState: overrides.lifecycleState || 'active',
+    lastControlAction: overrides.lastControlAction ?? null,
+    lastControlActionAt: overrides.lastControlActionAt ?? null,
+    lastControlReason: overrides.lastControlReason ?? null,
+    controlRequest: overrides.controlRequest ?? null,
     notes: overrides.notes ?? null,
     tags: overrides.tags || [],
     lastError: overrides.lastError ?? null,
@@ -190,4 +195,33 @@ describe('operation pulse', () => {
     assert.ok((pulse.actions[0]?.summary || '').includes('no available OpenClaw execution environments'))
     assert.equal(pulse.actions[0]?.evidence.includes('0/2 environments'), true)
   })
+
+  it('surfaces gateways that are unavailable for automatic new work', () => {
+    const pulse = buildOperationPulse({
+      range: '24h',
+      now,
+      missions: [],
+      runs: [],
+      approvals: [],
+      connectors: [],
+      gateways: [
+        gateway({
+          lifecycleState: 'cordoned',
+          stats: {
+            nodeCount: 1,
+            connectedNodeCount: 1,
+            environmentCount: 1,
+            availableEnvironmentCount: 1,
+            lastTopologyCheckedAt: now - 1000,
+          },
+        }),
+      ],
+    })
+
+    assert.equal(pulse.kpis.gatewayAttention, 1)
+    assert.equal(pulse.actions[0]?.kind, 'gateway')
+    assert.equal(pulse.actions[0]?.severity, 'medium')
+    assert.ok((pulse.actions[0]?.summary || '').includes('cordoned from automatic new work'))
+    assert.equal(pulse.actions[0]?.evidence.includes('lifecycle:cordoned'), true)
+  })
 })

package/src/lib/server/operations/operation-pulse.ts

@@ -84,8 +84,10 @@ function gatewayAttentionReason(gateway: GatewayProfile, now: number): {
   const errorCount = gateway.stats?.lastTopologyErrorCount || 0
   const checkedAt = gateway.stats?.lastTopologyCheckedAt || gateway.lastCheckedAt || null
   const staleTopology = !checkedAt || now - checkedAt > GATEWAY_TOPOLOGY_STALE_MS
+  const lifecycleState = gateway.lifecycleState || 'active'
   const evidence = [
     `status:${gateway.status}`,
+    `lifecycle:${lifecycleState}`,
     `${gateway.stats?.connectedNodeCount || 0}/${gateway.stats?.nodeCount || 0} nodes`,
     `${gateway.stats?.availableEnvironmentCount || 0}/${gateway.stats?.environmentCount || 0} environments`,
   ]
@@ -106,6 +108,22 @@ function gatewayAttentionReason(gateway: GatewayProfile, now: number): {
     }
   }
 
+  if (lifecycleState === 'cordoned') {
+    return {
+      severity: 'medium',
+      summary: `${gateway.name} is cordoned from automatic new work.`,
+      evidence,
+    }
+  }
+
+  if (lifecycleState === 'draining') {
+    return {
+      severity: 'medium',
+      summary: `${gateway.name} is draining and will not receive automatic new work.`,
+      evidence,
+    }
+  }
+
   if (errorCount > 0) {
     return {
       severity: 'medium',

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'))
+    }
+  })
+})