@swarmclawai/swarmclaw 1.9.17 → 1.9.18

package/README.md

@@ -407,6 +407,24 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.18 Highlights
+
+Schedule preflight release: schedules now show server-backed timing forecasts before save, with timezone-aware cron previews and warnings for risky drafts.
+
+- **Schedule preview API.** `POST /api/schedules/preview` validates a draft schedule through the same normalization path as saved schedules and returns the next calculated runs.
+- **Timezone-aware schedule sheet.** Cron schedules can set an explicit timezone, preview the next runs from the server, and see warnings before saving.
+- **Stagger and one-shot controls.** Operators can add a stagger window to recurring schedules and choose a run-once delay from the schedule workflow.
+- **CLI access.** `swarmclaw schedules preview --data '{...}'` exposes the same forecast for scripts and release automation.
+
+### v1.9.17 Highlights
+
+Agent configuration history release: SwarmClaw now surfaces saved agent versions directly in the agent editor, giving operators a fast rollback path for agent settings.
+
+- **Agent sheet history.** Advanced settings list recent saved versions with relative time, actor, and provider/model snapshot.
+- **One-click restore.** Operators can restore a prior agent configuration through the existing version-restore API without leaving the agent workflow.
+- **Stale-form protection.** Successful restore reloads agent state and closes the sheet so operators reopen the refreshed record.
+- **Regression coverage.** New tests cover config-version list/restore routes and summary formatting.
+
 ### v1.9.16 Highlights
 
 Agent planning controls release: strict planning is now a first-class agent setting instead of a hidden persisted field, so operators can decide which agents must expose machine-readable plans before multi-step work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.17",
+  "version": "1.9.18",
   "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/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/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/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/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/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/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/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/app/api/schedules/preview/route.test.ts

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { POST as previewSchedule } from './route'
+
+test('POST /api/schedules/preview returns a timing forecast without persisting', async () => {
+  const agentId = `missing-preview-agent-${Date.now()}`
+  const response = await previewSchedule(new Request('http://local/api/schedules/preview', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      agentId,
+      name: 'Preview smoke',
+      taskPrompt: 'Review the queue',
+      scheduleType: 'cron',
+      cron: '0 9 * * *',
+      timezone: 'UTC',
+      status: 'active',
+    }),
+  }))
+
+  assert.equal(response.status, 200)
+  const payload = await response.json() as Record<string, unknown>
+  assert.equal(payload.ok, true)
+  assert.equal(payload.scheduleType, 'cron')
+  assert.equal(payload.timezone, 'UTC')
+  assert.equal(Array.isArray(payload.nextRuns), true)
+  assert.equal((payload.nextRuns as unknown[]).length, 5)
+  assert.match(String((payload.warnings as string[]).join('\n')), /Agent not found/)
+})
+
+test('POST /api/schedules/preview rejects invalid draft timing', async () => {
+  const response = await previewSchedule(new Request('http://local/api/schedules/preview', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      agentId: 'schedule-preview-agent-invalid',
+      taskPrompt: 'Review the queue',
+      scheduleType: 'cron',
+      cron: '0 9 * * *',
+      timezone: 'Not/AZone',
+    }),
+  }))
+
+  assert.equal(response.status, 400)
+  const payload = await response.json() as Record<string, unknown>
+  assert.match(String(payload.error || ''), /invalid timezone/)
+})

package/src/app/api/schedules/preview/route.ts

@@ -0,0 +1,14 @@
+import { NextResponse } from 'next/server'
+import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { previewScheduleFromRoute } from '@/lib/server/schedules/schedule-route-service'
+
+export const dynamic = 'force-dynamic'
+
+export async function POST(req: Request) {
+  const { data: body, error } = await safeParseBody(req)
+  if (error) return error
+  const result = previewScheduleFromRoute((body || {}) as Record<string, unknown>)
+  return result.ok
+    ? NextResponse.json(result.payload)
+    : NextResponse.json(result.payload, { status: result.status })
+}

package/src/cli/index.js

@@ -582,6 +582,7 @@ const COMMAND_GROUPS = [
       cmd('list', 'GET', '/schedules', 'List schedules'),
       cmd('get', 'GET', '/schedules/:id', 'Get schedule by id'),
       cmd('history', 'GET', '/schedules/:id/history', 'Get schedule revision history'),
+      cmd('preview', 'POST', '/schedules/preview', 'Preview schedule timing and validation', { expectsJsonBody: true }),
       cmd('create', 'POST', '/schedules', 'Create schedule', { expectsJsonBody: true }),
       cmd('update', 'PUT', '/schedules/:id', 'Update schedule', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/schedules/:id', 'Delete schedule'),

package/src/cli/spec.js

@@ -418,6 +418,7 @@ const COMMAND_GROUPS = {
     description: 'Scheduled task automation',
     commands: {
       list: { description: 'List schedules', method: 'GET', path: '/schedules' },
+      preview: { description: 'Preview schedule timing and validation', method: 'POST', path: '/schedules/preview' },
       create: { description: 'Create schedule', method: 'POST', path: '/schedules' },
       get: { description: 'Get schedule by id (from list)', virtualGet: true, collectionPath: '/schedules', params: ['id'] },
       history: { description: 'Get schedule revision history', method: 'GET', path: '/schedules/:id/history', params: ['id'] },

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

@@ -59,7 +59,8 @@ function badgeClass(status: string): string {
 
 function formatScheduleCadence(schedule: Schedule): string {
   if (schedule.scheduleType === 'cron' && schedule.cron) {
-    return cronToHuman(schedule.cron)
+    const timezone = schedule.timezone ? ` (${schedule.timezone})` : ''
+    return `${cronToHuman(schedule.cron)}${timezone}`
   }
   if (schedule.scheduleType === 'interval' && schedule.intervalMs) {
     const minutes = Math.round(schedule.intervalMs / 60_000)

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

@@ -2,13 +2,13 @@
 
 import { useEffect, useState, useMemo } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
-import { createSchedule, updateSchedule, deleteSchedule } from '@/lib/schedules/schedules'
+import { createSchedule, updateSchedule, deleteSchedule, previewSchedule } from '@/lib/schedules/schedules'
 import { BottomSheet } from '@/components/shared/bottom-sheet'
 import { AgentPickerList } from '@/components/shared/agent-picker-list'
 import { ConfirmDialog } from '@/components/shared/confirm-dialog'
 import { inputClass } from '@/components/shared/form-styles'
 import { AgentAvatar } from '@/components/agents/agent-avatar'
-import type { ScheduleTaskMode, ScheduleType, ScheduleStatus } from '@/types'
+import type { Schedule, SchedulePreviewResponse, ScheduleTaskMode, ScheduleType, ScheduleStatus } from '@/types'
 import cronstrue from 'cronstrue'
 import { SectionLabel } from '@/components/shared/section-label'
 import { SCHEDULE_TEMPLATES, type ScheduleTemplate } from '@/lib/schedules/schedule-templates'
@@ -32,20 +32,6 @@ const CRON_PRESETS = [
   { label: 'Weekly Mon 9am', cron: '0 9 * * 1' },
 ]
 
-async function getNextRunsAsync(cron: string, count: number = 3): Promise<Date[]> {
-  try {
-    const { CronExpressionParser } = await import('cron-parser')
-    const interval = CronExpressionParser.parse(cron)
-    const runs: Date[] = []
-    for (let i = 0; i < count; i++) {
-      runs.push(interval.next().toDate())
-    }
-    return runs
-  } catch {
-    return []
-  }
-}
-
 function formatCronHuman(cron: string): string {
   try {
     return cronstrue.toString(cron, { use24HourTimeFormat: false })
@@ -54,11 +40,6 @@ function formatCronHuman(cron: string): string {
   }
 }
 
-function formatDate(d: Date): string {
-  return d.toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' }) +
-    ' ' + d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
-}
-
 const STEPS_CREATE = ['Template', 'What', 'When', 'Review'] as const
 const STEPS_EDIT = ['What', 'When', 'Review'] as const
 type Step = 0 | 1 | 2 | 3
@@ -107,6 +88,11 @@ export function ScheduleSheet() {
   const [taskMode, setTaskMode] = useState<ScheduleTaskMode>('task')
   const [message, setMessage] = useState('')
   const [customCron, setCustomCron] = useState(false)
+  const [timezone, setTimezone] = useState('')
+  const [staggerSec, setStaggerSec] = useState(0)
+  const [timingPreview, setTimingPreview] = useState<SchedulePreviewResponse | null>(null)
+  const [timingPreviewLoading, setTimingPreviewLoading] = useState(false)
+  const [timingPreviewError, setTimingPreviewError] = useState('')
   const [confirmDelete, setConfirmDelete] = useState(false)
   const [deleting, setDeleting] = useState(false)
 
@@ -136,6 +122,8 @@ export function ScheduleSheet() {
         setTaskMode(editing.taskMode === 'wake_only' ? 'wake_only' : editing.taskMode === 'protocol' ? 'protocol' : 'task')
         setMessage(editing.message || '')
         setCustomCron(!CRON_PRESETS.some((p) => p.cron === editing.cron))
+        setTimezone(editing.timezone || '')
+        setStaggerSec(editing.staggerSec || 0)
       } else if (templatePrefill) {
         // Opened from a quick-start card with pre-filled values
         setName(templatePrefill.name)
@@ -148,6 +136,10 @@ export function ScheduleSheet() {
         if (templatePrefill.intervalMs) setIntervalMs(templatePrefill.intervalMs)
         setAgentId('')
         setStatus('active')
+        setTaskMode('task')
+        setMessage('')
+        setTimezone('')
+        setStaggerSec(0)
         setStep(1) // Skip template picker, go to "What" step
         setTemplatePrefill(null)
       } else {
@@ -162,26 +154,22 @@ export function ScheduleSheet() {
         setTaskMode('task')
         setMessage('')
         setCustomCron(false)
+        setTimezone('')
+        setStaggerSec(0)
       }
+      setTimingPreview(null)
+      setTimingPreviewError('')
+      setTimingPreviewLoading(false)
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open, editingId])
 
   const cronHuman = useMemo(() => formatCronHuman(cron), [cron])
-  const [nextRuns, setNextRuns] = useState<Date[]>([])
-  useEffect(() => {
-    getNextRunsAsync(cron).then(setNextRuns)
-  }, [cron])
-
-  const onClose = () => {
-    setConfirmDelete(false)
-    setDeleting(false)
-    setOpen(false)
-    setEditingId(null)
-  }
 
-  const handleSave = async () => {
-    const data = {
+  const buildScheduleData = () => {
+    const trimmedTimezone = timezone.trim()
+    const normalizedStaggerSec = Math.max(0, Math.trunc(staggerSec || 0))
+    return {
       name: name.trim(),
       agentId,
       taskPrompt: taskMode === 'wake_only' ? message : taskPrompt,
@@ -192,8 +180,67 @@ export function ScheduleSheet() {
       cron: scheduleType === 'cron' ? cron : undefined,
       intervalMs: scheduleType === 'interval' ? intervalMs : undefined,
       runAt: scheduleType === 'once' ? Date.now() + intervalMs : undefined,
+      timezone: scheduleType === 'cron' && trimmedTimezone ? trimmedTimezone : undefined,
+      staggerSec: normalizedStaggerSec > 0 ? normalizedStaggerSec : undefined,
       status,
     }
+  }
+
+  useEffect(() => {
+    if (!open || step === templateStep) {
+      setTimingPreview(null)
+      setTimingPreviewError('')
+      setTimingPreviewLoading(false)
+      return
+    }
+
+    const taskText = taskMode === 'wake_only' ? message.trim() : taskPrompt.trim()
+    const hasTiming = scheduleType === 'cron'
+      ? cron.trim().length > 0
+      : intervalMs > 0
+    if (!agentId || !taskText || !hasTiming) {
+      setTimingPreview(null)
+      setTimingPreviewError('')
+      setTimingPreviewLoading(false)
+      return
+    }
+
+    let cancelled = false
+    const timer = window.setTimeout(() => {
+      setTimingPreviewLoading(true)
+      setTimingPreviewError('')
+      previewSchedule(buildScheduleData() as Partial<Schedule>)
+        .then((result) => {
+          if (cancelled) return
+          setTimingPreview(result)
+          setTimingPreviewError(result.ok ? '' : result.error)
+        })
+        .catch((err: unknown) => {
+          if (cancelled) return
+          setTimingPreview(null)
+          setTimingPreviewError(err instanceof Error ? err.message : 'Failed to preview schedule')
+        })
+        .finally(() => {
+          if (!cancelled) setTimingPreviewLoading(false)
+        })
+    }, 300)
+
+    return () => {
+      cancelled = true
+      window.clearTimeout(timer)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, step, templateStep, name, agentId, taskPrompt, taskMode, message, scheduleType, cron, intervalMs, status, timezone, staggerSec])
+
+  const onClose = () => {
+    setConfirmDelete(false)
+    setDeleting(false)
+    setOpen(false)
+    setEditingId(null)
+  }
+
+  const handleSave = async () => {
+    const data = buildScheduleData()
     try {
       if (editing) {
         await updateSchedule(editing.id, data)
@@ -227,10 +274,56 @@ export function ScheduleSheet() {
 
   // Step validation
   const step0Valid = name.trim().length > 0 && agentId.length > 0 && (taskMode === 'wake_only' ? message.trim().length > 0 : taskPrompt.trim().length > 0)
-  const step1Valid = scheduleType === 'cron' ? cron.trim().length > 0 : intervalMs > 0
+  const step1Valid = (scheduleType === 'cron' ? cron.trim().length > 0 : intervalMs > 0) && !timingPreviewError
 
   const selectedAgent = agentId ? agents[agentId] : null
   const creatorAgent = editing?.createdByAgentId ? agents[editing.createdByAgentId] : null
+  const previewOk = timingPreview && timingPreview.ok ? timingPreview : null
+
+  const timingPreviewPanel = (
+    <div className="p-4 rounded-[14px] bg-surface border border-white/[0.06]">
+      <div className="flex flex-wrap items-center gap-2 mb-2">
+        <div className="text-[14px] text-text-2 font-600">
+          {scheduleType === 'cron' ? cronHuman : previewOk?.cadence || (scheduleType === 'once' ? 'Run once' : `Every ${Math.round(intervalMs / 60000)} minutes`)}
+        </div>
+        {previewOk?.timezone && (
+          <span className="rounded-[999px] bg-white/[0.05] px-2 py-0.5 text-[11px] font-600 text-text-3">
+            {previewOk.timezone}
+          </span>
+        )}
+      </div>
+      {scheduleType === 'cron' && cron && (
+        <div className="font-mono text-[12px] text-text-3/50 mb-3">{cron}</div>
+      )}
+      {timingPreviewLoading && (
+        <div className="text-[12px] text-text-3">Checking schedule...</div>
+      )}
+      {timingPreviewError && (
+        <div className="text-[12px] text-red-400">{timingPreviewError}</div>
+      )}
+      {previewOk && !timingPreviewLoading && (
+        <>
+          {previewOk.nextRuns.length > 0 ? (
+            <div className="space-y-1.5">
+              <div className="text-[11px] text-text-3/60 uppercase tracking-wider font-600">Next runs</div>
+              {previewOk.nextRuns.map((run) => (
+                <div key={run.iso} className="text-[12px] text-text-3 font-mono">{run.label}</div>
+              ))}
+            </div>
+          ) : (
+            <div className="text-[12px] text-text-3">No future runs calculated.</div>
+          )}
+          {previewOk.warnings.length > 0 && (
+            <div className="mt-3 space-y-1.5">
+              {previewOk.warnings.map((warning) => (
+                <div key={warning} className="text-[12px] text-amber-300">{warning}</div>
+              ))}
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
 
   return (
     <BottomSheet open={open} onClose={onClose} wide>
@@ -501,21 +594,32 @@ export function ScheduleSheet() {
                 <input type="text" value={cron} onChange={(e) => setCron(e.target.value)} placeholder="0 * * * *" className={`${inputClass} font-mono text-[14px] mb-3`} />
               )}
 
-              {/* Human-readable preview */}
-              <div className="p-4 rounded-[14px] bg-surface border border-white/[0.06]">
-                <div className="text-[14px] text-text-2 font-600 mb-2">{cronHuman}</div>
-                {cron && (
-                  <div className="font-mono text-[12px] text-text-3/50 mb-3">{cron}</div>
-                )}
-                {nextRuns.length > 0 && (
-                  <div className="space-y-1.5">
-                    <div className="text-[11px] text-text-3/60 uppercase tracking-wider font-600">Next runs</div>
-                    {nextRuns.map((d, i) => (
-                      <div key={i} className="text-[12px] text-text-3 font-mono">{formatDate(d)}</div>
-                    ))}
-                  </div>
-                )}
+              <div className="grid grid-cols-1 sm:grid-cols-2 gap-3 mb-3">
+                <div>
+                  <SectionLabel>Timezone</SectionLabel>
+                  <input
+                    type="text"
+                    value={timezone}
+                    onChange={(e) => setTimezone(e.target.value)}
+                    placeholder="UTC or America/New_York"
+                    className={inputClass}
+                    style={{ fontFamily: 'inherit' }}
+                  />
+                </div>
+                <div>
+                  <SectionLabel>Stagger (seconds)</SectionLabel>
+                  <input
+                    type="number"
+                    min={0}
+                    value={staggerSec}
+                    onChange={(e) => setStaggerSec(Math.max(0, parseInt(e.target.value, 10) || 0))}
+                    className={inputClass}
+                    style={{ fontFamily: 'inherit' }}
+                  />
+                </div>
               </div>
+
+              {timingPreviewPanel}
             </div>
           )}
 
@@ -529,6 +633,34 @@ export function ScheduleSheet() {
                 className={inputClass}
                 style={{ fontFamily: 'inherit' }}
               />
+              <div className="mt-3 mb-3">
+                <SectionLabel>Stagger (seconds)</SectionLabel>
+                <input
+                  type="number"
+                  min={0}
+                  value={staggerSec}
+                  onChange={(e) => setStaggerSec(Math.max(0, parseInt(e.target.value, 10) || 0))}
+                  className={inputClass}
+                  style={{ fontFamily: 'inherit' }}
+                />
+              </div>
+              {timingPreviewPanel}
+            </div>
+          )}
+
+          {scheduleType === 'once' && (
+            <div className="mb-8">
+              <SectionLabel>Run After (minutes)</SectionLabel>
+              <input
+                type="number"
+                value={Math.round(intervalMs / 60000)}
+                onChange={(e) => setIntervalMs(Math.max(1, parseInt(e.target.value) || 1) * 60000)}
+                className={inputClass}
+                style={{ fontFamily: 'inherit' }}
+              />
+              <div className="mt-3">
+                {timingPreviewPanel}
+              </div>
             </div>
           )}
 
@@ -620,6 +752,15 @@ export function ScheduleSheet() {
               {scheduleType === 'once' && (
                 <div className="text-[12px] text-text-3 font-mono mt-0.5">Run once</div>
               )}
+              {scheduleType === 'cron' && timezone.trim() && (
+                <div className="text-[12px] text-text-3 mt-1">Timezone: {timezone.trim()}</div>
+              )}
+              {staggerSec > 0 && (
+                <div className="text-[12px] text-text-3 mt-1">Stagger: up to {staggerSec} seconds</div>
+              )}
+              {previewOk?.nextRuns[0] && (
+                <div className="text-[12px] text-text-3 mt-1">Next: {previewOk.nextRuns[0].label}</div>
+              )}
             </div>
             {editing && (
               <div>

package/src/lib/schedules/schedules.ts

@@ -1,5 +1,5 @@
 import { api } from '@/lib/app/api-client'
-import type { Schedule, ScheduleHistoryEntry } from '@/types'
+import type { Schedule, ScheduleHistoryEntry, SchedulePreviewResponse } from '@/types'
 
 export interface ScheduleArchiveResponse {
   ok: boolean
@@ -31,6 +31,9 @@ export const fetchSchedules = (includeArchived = false) =>
 export const createSchedule = (data: Omit<Schedule, 'id' | 'createdAt' | 'lastRunAt' | 'nextRunAt'>) =>
   api<Schedule>('POST', '/schedules', data)
 
+export const previewSchedule = (data: Partial<Schedule>) =>
+  api<SchedulePreviewResponse>('POST', '/schedules/preview', data, { timeoutMs: 8_000 })
+
 export const updateSchedule = (id: string, data: Partial<Schedule>) =>
   api<Schedule>('PUT', `/schedules/${id}`, data)
 

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

@@ -51,6 +51,15 @@ function normalizeScheduleTimestamp(value: unknown): number | null {
   return Math.trunc(parsedTime)
 }
 
+function isValidTimeZone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value })
+    return true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Parse natural "at HH:MM" time expressions into a cron string.
  * Supports: "at 09:00", "at 14:30", "at 9am", "at 2:30pm", "daily at 09:00"
@@ -226,7 +235,14 @@ export function normalizeSchedulePayload(payload: SchedulePayload, opts: Normali
 
   // Preserve timezone and stagger
   const timezone = trimString(normalized.timezone)
-  if (timezone) normalized.timezone = timezone
+  if (timezone) {
+    if (!isValidTimeZone(timezone)) {
+      return { ok: false, error: `Error: invalid timezone: ${timezone}.` }
+    }
+    normalized.timezone = timezone
+  } else if (normalized.timezone != null) {
+    delete normalized.timezone
+  }
   const staggerSec = normalizePositiveInt(normalized.staggerSec)
   if (staggerSec != null) normalized.staggerSec = staggerSec
   else if (normalized.staggerSec != null) delete normalized.staggerSec

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

@@ -0,0 +1,89 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { previewSchedulePayload } from './schedule-preview'
+
+const NOW = Date.parse('2026-05-06T12:00:00.000Z')
+
+function basePayload(overrides: Record<string, unknown> = {}) {
+  return {
+    agentId: 'agent-1',
+    name: 'Preview schedule',
+    taskPrompt: 'Review the queue',
+    status: 'active',
+    ...overrides,
+  }
+}
+
+describe('previewSchedulePayload', () => {
+  it('forecasts cron schedules with an explicit timezone', () => {
+    const preview = previewSchedulePayload(basePayload({
+      scheduleType: 'cron',
+      cron: '0 9 * * *',
+      timezone: 'UTC',
+    }), { now: NOW })
+
+    assert.equal(preview.ok, true)
+    if (!preview.ok) return
+    assert.equal(preview.scheduleType, 'cron')
+    assert.equal(preview.timezone, 'UTC')
+    assert.equal(preview.nextRuns.length, 5)
+    assert.equal(preview.nextRunAt, Date.parse('2026-05-07T09:00:00.000Z'))
+    assert.equal(preview.nextRuns[0].iso, '2026-05-07T09:00:00.000Z')
+    assert.deepEqual(preview.warnings, [])
+  })
+
+  it('warns when cron schedules rely on host local time', () => {
+    const preview = previewSchedulePayload(basePayload({
+      scheduleType: 'cron',
+      cron: '0 9 * * *',
+    }), { now: NOW, count: 2 })
+
+    assert.equal(preview.ok, true)
+    if (!preview.ok) return
+    assert.equal(preview.nextRuns.length, 2)
+    assert.match(preview.warnings.join('\n'), /host local timezone/)
+  })
+
+  it('rejects invalid timezone values before saving', () => {
+    const preview = previewSchedulePayload(basePayload({
+      scheduleType: 'cron',
+      cron: '0 9 * * *',
+      timezone: 'Not/AZone',
+    }), { now: NOW })
+
+    assert.equal(preview.ok, false)
+    if (preview.ok) return
+    assert.match(preview.error, /invalid timezone/)
+  })
+
+  it('forecasts interval schedules from the preview time', () => {
+    const preview = previewSchedulePayload(basePayload({
+      scheduleType: 'interval',
+      intervalMs: 30 * 60_000,
+    }), { now: NOW, count: 3 })
+
+    assert.equal(preview.ok, true)
+    if (!preview.ok) return
+    assert.equal(preview.scheduleType, 'interval')
+    assert.equal(preview.nextRuns.length, 3)
+    assert.deepEqual(preview.nextRuns.map((run) => run.at), [
+      NOW + 30 * 60_000,
+      NOW + 60 * 60_000,
+      NOW + 90 * 60_000,
+    ])
+  })
+
+  it('warns when a run-once schedule is already in the past', () => {
+    const preview = previewSchedulePayload(basePayload({
+      scheduleType: 'once',
+      runAt: NOW - 60_000,
+    }), { now: NOW })
+
+    assert.equal(preview.ok, true)
+    if (!preview.ok) return
+    assert.equal(preview.nextRunAt, null)
+    assert.equal(preview.nextRuns.length, 0)
+    assert.match(preview.warnings.join('\n'), /past/)
+  })
+})

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

@@ -0,0 +1,171 @@
+import { CronExpressionParser } from 'cron-parser'
+
+import { normalizeSchedulePayload } from '@/lib/server/schedules/schedule-normalization'
+import type { SchedulePreviewResponse, SchedulePreviewRun, ScheduleType } from '@/types'
+
+type SchedulePayload = Record<string, unknown>
+
+export interface PreviewScheduleOptions {
+  cwd?: string | null
+  now?: number
+  count?: number
+}
+
+const DEFAULT_PREVIEW_RUNS = 5
+
+function trimString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function positiveNumber(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return null
+  return Math.trunc(value)
+}
+
+function formatDuration(ms: number): string {
+  const minutes = Math.round(ms / 60_000)
+  if (minutes <= 1) return 'Every minute'
+  if (minutes < 60) return `Every ${minutes} minutes`
+  const hours = Math.round(minutes / 60)
+  if (hours < 24) return hours === 1 ? 'Every hour' : `Every ${hours} hours`
+  const days = Math.round(hours / 24)
+  return days === 1 ? 'Every day' : `Every ${days} days`
+}
+
+function formatRunLabel(timestamp: number, timezone: string | null): string {
+  const date = new Date(timestamp)
+  try {
+    return new Intl.DateTimeFormat('en-US', {
+      weekday: 'short',
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+      ...(timezone ? { timeZone: timezone, timeZoneName: 'short' as const } : {}),
+    }).format(date)
+  } catch {
+    return date.toISOString()
+  }
+}
+
+function buildPreviewRun(timestamp: number, timezone: string | null): SchedulePreviewRun {
+  return {
+    at: timestamp,
+    iso: new Date(timestamp).toISOString(),
+    label: formatRunLabel(timestamp, timezone),
+  }
+}
+
+function buildCronRuns(cron: string, timezone: string | null, now: number, count: number): SchedulePreviewRun[] {
+  const interval = CronExpressionParser.parse(cron, {
+    currentDate: new Date(now),
+    ...(timezone ? { tz: timezone } : {}),
+  })
+  const runs: SchedulePreviewRun[] = []
+  for (let index = 0; index < count; index += 1) {
+    runs.push(buildPreviewRun(interval.next().getTime(), timezone))
+  }
+  return runs
+}
+
+function buildIntervalRuns(intervalMs: number, timezone: string | null, now: number, count: number): SchedulePreviewRun[] {
+  const runs: SchedulePreviewRun[] = []
+  for (let index = 1; index <= count; index += 1) {
+    runs.push(buildPreviewRun(now + (intervalMs * index), timezone))
+  }
+  return runs
+}
+
+function cadenceLabel(scheduleType: ScheduleType, payload: SchedulePayload): string {
+  if (scheduleType === 'cron') {
+    const cron = trimString(payload.cron)
+    return cron ? `Cron ${cron}` : 'Cron'
+  }
+  if (scheduleType === 'interval') {
+    const intervalMs = positiveNumber(payload.intervalMs)
+    return intervalMs ? formatDuration(intervalMs) : 'Interval'
+  }
+  return 'Run once'
+}
+
+export function previewSchedulePayload(
+  payload: SchedulePayload,
+  options: PreviewScheduleOptions = {},
+): SchedulePreviewResponse {
+  const now = typeof options.now === 'number' ? options.now : Date.now()
+  const count = Math.max(1, Math.min(10, Math.trunc(options.count ?? DEFAULT_PREVIEW_RUNS)))
+  const normalized = normalizeSchedulePayload({
+    ...payload,
+    nextRunAt: undefined,
+  }, {
+    cwd: options.cwd,
+    now,
+  })
+  if (!normalized.ok) {
+    return { ok: false, error: normalized.error }
+  }
+
+  const value = normalized.value
+  const scheduleType = value.scheduleType === 'cron' || value.scheduleType === 'once'
+    ? value.scheduleType
+    : 'interval'
+  const timezone = trimString(value.timezone) || null
+  const warnings: string[] = []
+  const staggerSec = positiveNumber(value.staggerSec)
+
+  if (scheduleType === 'cron' && !timezone) {
+    warnings.push('Timezone is not set, so cron runs use the host local timezone.')
+  }
+  if (staggerSec) {
+    warnings.push(`Stagger may delay each run by up to ${staggerSec} seconds.`)
+  }
+  if (value.status === 'paused') {
+    warnings.push('Paused schedules keep their forecast but will not run until reactivated.')
+  }
+  if (value.status === 'archived') {
+    warnings.push('Archived schedules do not run until restored.')
+  }
+
+  let nextRuns: SchedulePreviewRun[] = []
+  try {
+    if (scheduleType === 'cron') {
+      const cron = trimString(value.cron)
+      if (!cron) {
+        return { ok: false, error: 'Error: cron schedules require a cron expression.' }
+      }
+      nextRuns = buildCronRuns(cron, timezone, now, count)
+    } else if (scheduleType === 'interval') {
+      const intervalMs = positiveNumber(value.intervalMs)
+      if (!intervalMs) {
+        return { ok: false, error: 'Error: interval schedules require intervalMs.' }
+      }
+      nextRuns = buildIntervalRuns(intervalMs, timezone, now, count)
+    } else {
+      const runAt = positiveNumber(value.runAt)
+      if (!runAt) {
+        warnings.push('Run-once schedules need a runAt timestamp before they can be queued.')
+      } else if (runAt <= now) {
+        warnings.push('Run-once timestamp is in the past.')
+      } else {
+        nextRuns = [buildPreviewRun(runAt, timezone)]
+      }
+    }
+  } catch {
+    return { ok: false, error: 'Error: invalid schedule timing.' }
+  }
+
+  if (nextRuns.length === 0 && value.status !== 'archived') {
+    warnings.push('No future runs could be calculated from this schedule.')
+  }
+
+  return {
+    ok: true,
+    scheduleType,
+    cadence: cadenceLabel(scheduleType, value),
+    timezone,
+    nextRunAt: nextRuns[0]?.at ?? null,
+    nextRuns,
+    warnings,
+    normalized: value,
+  }
+}

package/src/lib/server/schedules/schedule-route-service.ts

@@ -19,7 +19,8 @@ import { pushMainLoopEventToMainSessions } from '@/lib/server/agents/main-agent-
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { notify } from '@/lib/server/ws-hub'
 import { appendScheduleHistoryEntry } from '@/lib/server/schedules/schedule-history'
-import type { Schedule } from '@/types'
+import { previewSchedulePayload } from '@/lib/server/schedules/schedule-preview'
+import type { Schedule, SchedulePreviewResponse } from '@/types'
 import type { ScheduleLike } from '@/lib/schedules/schedule-dedupe'
 import type { ServiceResult } from '@/lib/server/service-result'
 
@@ -39,6 +40,29 @@ export function listSchedulesForApi(includeArchived: boolean) {
   return filtered
 }
 
+export function previewScheduleFromRoute(body: Record<string, unknown>): ServiceResult<SchedulePreviewResponse> {
+  const result = previewSchedulePayload(body, {
+    cwd: WORKSPACE_DIR,
+    now: Date.now(),
+  })
+  if (!result.ok) return serviceFail(400, result.error)
+
+  const agents = loadAgents()
+  const agentId = typeof result.normalized.agentId === 'string' ? result.normalized.agentId : ''
+  const agent = agentId ? agents[agentId] : null
+  const warnings = [...result.warnings]
+  if (agentId && !agent) {
+    warnings.push(`Agent not found: ${agentId}`)
+  } else if (agent && isAgentDisabled(agent)) {
+    warnings.push(buildAgentDisabledMessage(agent, 'take scheduled work'))
+  }
+
+  return serviceOk({
+    ...result,
+    warnings,
+  })
+}
+
 export function createScheduleFromRoute(body: Record<string, unknown>): ServiceResult<ScheduleLike> {
   const now = Date.now()
   const schedules = loadSchedules()

package/src/types/schedule.ts

@@ -82,3 +82,26 @@ export interface Schedule {
   createdAt: number
   updatedAt?: number
 }
+
+export interface SchedulePreviewRun {
+  at: number
+  iso: string
+  label: string
+}
+
+export type SchedulePreviewResponse =
+  | {
+      ok: true
+      scheduleType: ScheduleType
+      cadence: string
+      timezone: string | null
+      nextRunAt: number | null
+      nextRuns: SchedulePreviewRun[]
+      warnings: string[]
+      normalized: Partial<Schedule> & Record<string, unknown>
+    }
+  | {
+      ok: false
+      error: string
+      warnings?: string[]
+    }