feat(frontend): show local timezone alongside UTC in schedule displays (#1564)

## Summary

Follows up on #1496. Shows the user's local timezone alongside UTC in
all schedule-related displays, so users don't have to mentally convert
UTC times.

- Add `getCronDescriptionWithLocal()` that inserts "UTC" after the time
in cron descriptions and appends the local equivalent in parentheses
- Update schedule column, details card, and form preview to use the new
function
- Add "Times are in UTC" helper text to the schedule form
- Sub-daily schedules (every hour, every 15 min) skip the annotation
since local offset adds no value

**Before:** `At 05:30 AM, Monday through Friday`
**After:** `At 05:30 AM UTC, Monday through Friday (6:30 AM GMT+1)`

Edit
<img width="1291" height="602" alt="s1"
src="https://github.com/user-attachments/assets/d8a6135d-c0f0-4dfb-b26f-2853cfe4cc8c"
/>

List
<img width="1320" height="257" alt="s2"
src="https://github.com/user-attachments/assets/3e460d18-0ccf-4d56-9070-cefb89738243"
/>

Show
<img width="1386" height="317" alt="s3"
src="https://github.com/user-attachments/assets/5b240bac-ca57-4599-b3b8-4e8af2509514"
/>


## Why UTC input (not local-first input)

We considered letting users input cron schedules in their local timezone
and converting to UTC behind the scenes, but rejected it:

- **DST drift**: `getTimezoneOffset()` returns the offset at input time,
not execution time. A user in London (UTC+0 winter, UTC+1 summer) who
sets "9 AM local" in January gets `0 9 * * *` UTC — which silently
becomes 10 AM local in summer
- **Fractional offsets**: UTC+5:30 (India, 1.4B people), UTC+5:45
(Nepal), UTC+12:45 (Chatham Islands) require shifting both hour and
minute fields, with minute overflow creating double-wrap edge cases
- **Day-of-week wrapping**: Timezone shifts crossing midnight require
adjusting day-of-week fields — ranges like `1-5` must become `0-4` or
`2-6`, with modular wrapping on each element
- **Round-trip conversion**: Editing an existing schedule requires
reverse-converting UTC→local, which may produce a different cron than
originally entered if DST changed since creation

UTC input avoids all of these. Showing the local equivalent next to it
gives users the "when does this fire for me?" answer without any
conversion complexity or correctness risks.

## Test plan

- [x] Unit tests for `getCronDescriptionWithLocal()` — daily, weekly,
monthly schedules include UTC + local; sub-daily schedules return plain
description; invalid cron falls back gracefully
- [x] All frontend unit tests pass
- [x] Production build passes with 0 errors, 0 warnings
- [x] Visual verification against Kind cluster: schedule list, detail
card, and form preview all show dual timezone


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Schedule descriptions now include a UTC label and, when appropriate, a
parenthetical local-time preview; sub-daily schedules omit timezone
annotations. Table and detail labels simplified to “Schedule”. Schedule
preview areas note “Times are in UTC”.

* **Tests**
* Added tests validating the timezone-aware schedule description
behavior and edge cases (sub-daily, invalid cron, 12h/24h formats).

* **Documentation**
* Added a frontend spec defining timezone display rules for cron
schedules.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
Co-authored-by: jsell-rh <jsell@redhat.com>

Author: 4 people

components/frontend/src/app/projects/[name]/scheduled-sessions/[scheduledSessionName]/_components/scheduled-session-details-card.tsx

@@ -6,7 +6,7 @@ import { Info } from "lucide-react";
 
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
-import { getCronDescription, getNextRuns } from "@/lib/cron";
+import { getCronDescriptionWithLocal, getNextRuns } from "@/lib/cron";
 import { formatScheduleDateTime, formatScheduleTime } from "@/lib/format-timestamp";
 import { INACTIVITY_TIMEOUT_TOOLTIP } from "@/lib/constants";
 import { useRunnerTypes } from "@/services/queries/use-runner-types";
@@ -51,11 +51,11 @@ export function ScheduledSessionDetailsCard({
             <dd className="font-mono">{scheduledSession.name}</dd>
           </div>
           <div>
-            <dt className="text-muted-foreground">Schedule (UTC)</dt>
+            <dt className="text-muted-foreground">Schedule</dt>
             <dd>
               <span className="font-mono">{scheduledSession.schedule}</span>
               <span className="text-muted-foreground ml-2">
-                ({getCronDescription(scheduledSession.schedule)})
+                ({getCronDescriptionWithLocal(scheduledSession.schedule)})
               </span>
             </dd>
           </div>

components/frontend/src/app/projects/[name]/scheduled-sessions/_components/scheduled-session-form.tsx

@@ -6,7 +6,7 @@ import { useForm } from "react-hook-form";
 import { zodResolver } from "@hookform/resolvers/zod";
 import * as z from "zod";
 import { ArrowLeft, Loader2, AlertCircle, X, Info } from "lucide-react";
-import { getCronDescription, getNextRuns } from "@/lib/cron";
+import { getCronDescriptionWithLocal, getNextRuns } from "@/lib/cron";
 import { formatScheduleDateTime } from "@/lib/format-timestamp";
 
 import { Button } from "@/components/ui/button";
@@ -210,7 +210,7 @@ export function ScheduledSessionForm({ projectName, mode, initialData }: Schedul
       }
       form.setValue("model", modelsData.defaultModel, { shouldDirty: false });
     }
-  }, [modelsData?.defaultModel, form, isEdit, initialData]);
+  }, [modelsData, form, isEdit, initialData]);
 
   // Resolve workflow state once OOTB workflows finish loading. The Skeleton
   // guard on the Select (workflowsLoading || !workflowResolved) ensures Radix
@@ -233,7 +233,7 @@ export function ScheduledSessionForm({ projectName, mode, initialData }: Schedul
 
   const effectiveCron = schedulePreset === "custom" ? (customCron ?? "") : schedulePreset;
   const nextRuns = useMemo(() => getNextRuns(effectiveCron, 3), [effectiveCron]);
-  const cronDescription = useMemo(() => effectiveCron ? getCronDescription(effectiveCron) : "", [effectiveCron]);
+  const cronDescription = useMemo(() => effectiveCron ? getCronDescriptionWithLocal(effectiveCron) : "", [effectiveCron]);
 
   const handleRunnerTypeChange = (value: string, onChange: (v: string) => void) => {
     onChange(value);
@@ -393,6 +393,7 @@ export function ScheduledSessionForm({ projectName, mode, initialData }: Schedul
                       </SelectContent>
                     </Select>
                     <FormMessage />
+                    <p className="text-xs text-muted-foreground">Times are in UTC</p>
                   </FormItem>
                 )}
               />

components/frontend/src/components/workspace-sections/scheduled-sessions-tab.tsx

@@ -1,8 +1,9 @@
 "use client";
 
+import { useMemo } from "react";
 import { formatDistanceToNow } from "date-fns";
 import { Plus, RefreshCw, MoreVertical, Play, Pause, Pencil, PlayCircle, Trash2, Calendar, Loader2, AlertCircle } from "lucide-react";
-import { getCronDescription } from "@/lib/cron";
+import { getCronDescriptionWithLocal } from "@/lib/cron";
 import { formatScheduleTime } from "@/lib/format-timestamp";
 
 import { Button } from "@/components/ui/button";
@@ -35,7 +36,12 @@ export function SchedulesSection({ projectName }: SchedulesSectionProps) {
   const resumeMutation = useResumeScheduledSession();
   const triggerMutation = useTriggerScheduledSession();
 
-  const items = scheduledSessions ?? [];
+  const items = useMemo(() => scheduledSessions ?? [], [scheduledSessions]);
+
+  const cronDescriptions = useMemo(
+    () => new Map(items.map((ss) => [ss.name, getCronDescriptionWithLocal(ss.schedule)])),
+    [items]
+  );
 
   const handleTrigger = (name: string) => {
     triggerMutation.mutate(
@@ -124,7 +130,7 @@ export function SchedulesSection({ projectName }: SchedulesSectionProps) {
               <TableHeader>
                 <TableRow>
                   <TableHead className="min-w-[180px]">Name</TableHead>
-                  <TableHead>Schedule (UTC)</TableHead>
+                  <TableHead>Schedule</TableHead>
                   <TableHead>Status</TableHead>
                   <TableHead className="hidden md:table-cell">Last Run</TableHead>
                   <TableHead className="w-[50px]">Actions</TableHead>
@@ -154,7 +160,7 @@ export function SchedulesSection({ projectName }: SchedulesSectionProps) {
                         </Link>
                       </TableCell>
                       <TableCell>
-                        <div className="text-sm">{getCronDescription(ss.schedule)}</div>
+                        <div className="text-sm">{cronDescriptions.get(ss.name)}</div>
                         <div className="text-xs text-muted-foreground font-mono">{ss.schedule}</div>
                       </TableCell>
                       <TableCell>

components/frontend/src/lib/__tests__/cron.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { getCronDescription, getNextRuns } from '../cron';
+import { getCronDescription, getCronDescriptionWithLocal, getNextRuns } from '../cron';
 
 describe('getCronDescription', () => {
   it('returns human-readable description for standard cron expressions', () => {
@@ -32,3 +32,63 @@ describe('getNextRuns', () => {
     expect(getNextRuns('invalid', 3)).toEqual([]);
   });
 });
+
+describe('getCronDescriptionWithLocal', () => {
+  it('includes UTC label for daily schedule', () => {
+    const result = getCronDescriptionWithLocal('0 9 * * *');
+    expect(result).toContain('UTC');
+  });
+
+  it('appends parenthesized local time when browser is not in UTC', () => {
+    const result = getCronDescriptionWithLocal('0 9 * * *');
+    const isUtcEnv = new Date().getTimezoneOffset() === 0;
+    if (isUtcEnv) {
+      expect(result).not.toContain('(');
+    } else {
+      expect(result).toMatch(/UTC\s*\([^)]+\)$/);
+    }
+  });
+
+  it('returns plain description without timezone for sub-daily schedules', () => {
+    const everyMinute = getCronDescriptionWithLocal('* * * * *');
+    expect(everyMinute).not.toContain('UTC');
+    expect(everyMinute).toBe(getCronDescription('* * * * *'));
+
+    const every15Min = getCronDescriptionWithLocal('*/15 * * * *');
+    expect(every15Min).not.toContain('UTC');
+    expect(every15Min).toBe(getCronDescription('*/15 * * * *'));
+
+    const everyHour = getCronDescriptionWithLocal('0 * * * *');
+    expect(everyHour).not.toContain('UTC');
+    expect(everyHour).toBe(getCronDescription('0 * * * *'));
+
+    const every2Hours = getCronDescriptionWithLocal('0 */2 * * *');
+    expect(every2Hours).not.toContain('UTC');
+    expect(every2Hours).toBe(getCronDescription('0 */2 * * *'));
+  });
+
+  it('falls back to plain description for invalid cron', () => {
+    const result = getCronDescriptionWithLocal('not-valid');
+    expect(result).toBe('not-valid');
+  });
+
+  it('includes UTC label for weekday schedule', () => {
+    const result = getCronDescriptionWithLocal('30 14 * * 1-5');
+    expect(result).toContain('UTC');
+  });
+
+  it('includes UTC label for weekly schedule', () => {
+    const result = getCronDescriptionWithLocal('0 9 * * 1');
+    expect(result).toContain('UTC');
+  });
+
+  it('includes UTC label for monthly schedule', () => {
+    const result = getCronDescriptionWithLocal('0 12 1 * *');
+    expect(result).toContain('UTC');
+  });
+
+  it('inserts UTC after time portion for both 12h and 24h formats', () => {
+    const result = getCronDescriptionWithLocal('30 14 * * *');
+    expect(result).toMatch(/14:30\s*(PM\s*)?UTC|02:30\s*PM\s*UTC/);
+  });
+});

components/frontend/src/lib/cron.ts

@@ -1,5 +1,6 @@
 import cronstrue from "cronstrue";
 import { CronExpressionParser } from "cron-parser";
+import { formatTimeLocal } from "./format-timestamp";
 
 /**
  * Returns a human-readable description of a cron expression.
@@ -29,3 +30,38 @@ export function getNextRuns(cronExpr: string, count: number): Date[] {
     return [];
   }
 }
+
+/**
+ * Returns a cron description with UTC and local timezone labels.
+ * Sub-daily schedules return the plain description without timezone annotation.
+ */
+export function getCronDescriptionWithLocal(cronExpr: string): string {
+  const description = getCronDescription(cronExpr);
+
+  const runs = getNextRuns(cronExpr, 2);
+  if (runs.length < 2) {
+    return description;
+  }
+
+  const subDaily = runs[1].getTime() - runs[0].getTime() < 24 * 60 * 60 * 1000;
+
+  if (subDaily) {
+    return description;
+  }
+
+  const timePattern = /(\d{1,2}:\d{2}(\s*[AP]M)?)/;
+
+  if (!timePattern.test(description)) {
+    return description;
+  }
+
+  const withUtc = description.replace(timePattern, "$1 UTC");
+
+  const local = formatTimeLocal(runs[0]);
+
+  if (local.endsWith("UTC")) {
+    return withUtc;
+  }
+
+  return `${withUtc} (${local})`;
+}

specs/frontend/schedule-timezone-display.spec.md

@@ -0,0 +1,118 @@
+# Schedule Timezone Display Specification
+
+## Purpose
+
+Defines how the frontend displays cron-based schedule times to users. All schedules are stored and configured in UTC. The frontend annotates displayed times with the UTC label and, when the user's browser is not in UTC, appends the local timezone equivalent so users can understand when a schedule will fire in their own timezone without performing mental offset calculations.
+
+## Requirements
+
+### Requirement: UTC Label on Daily-or-Longer Schedules
+
+When displaying a human-readable cron description for a schedule that fires once per day or less frequently (daily, weekly, monthly), the system SHALL insert "UTC" immediately after the time portion in the description.
+
+#### Scenario: Daily schedule at 09:00
+
+- GIVEN a cron expression `0 9 * * *`
+- WHEN the frontend renders the schedule description
+- THEN the description SHALL contain "09:00 UTC" or "9:00 AM UTC"
+
+#### Scenario: Weekday schedule at 14:30
+
+- GIVEN a cron expression `30 14 * * 1-5`
+- WHEN the frontend renders the schedule description
+- THEN the description SHALL contain "14:30 UTC" or "02:30 PM UTC"
+
+#### Scenario: Monthly schedule
+
+- GIVEN a cron expression `0 12 1 * *`
+- WHEN the frontend renders the schedule description
+- THEN the description SHALL contain "UTC" after the time portion
+
+### Requirement: Local Timezone Parenthetical
+
+When the user's browser timezone differs from UTC, the system SHALL append the equivalent local time in parentheses after the UTC-labeled description.
+
+#### Scenario: User in UTC+1 viewing a daily schedule
+
+- GIVEN a cron expression `0 9 * * *`
+- AND the user's browser is in a UTC+1 timezone
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL match the pattern `<description> UTC (<local time> <timezone>)`
+- AND the local time SHALL reflect the browser's offset (e.g., "10:00 AM GMT+1")
+
+#### Scenario: User in UTC viewing a daily schedule
+
+- GIVEN a cron expression `0 9 * * *`
+- AND the user's browser is in UTC
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL contain "UTC"
+- AND the output SHALL NOT contain a parenthesized local time (since local equals UTC)
+
+### Requirement: Sub-Daily Schedules Omit Timezone Annotation
+
+Schedules that fire more frequently than once per day (every minute, every N minutes, hourly, every N hours) SHALL display the plain cron description without any UTC label or local timezone parenthetical.
+
+#### Scenario: Every 5 minutes
+
+- GIVEN a cron expression `*/5 * * * *`
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL be the plain human-readable description (e.g., "Every 5 minutes")
+- AND the output SHALL NOT contain "UTC"
+
+#### Scenario: Every 2 hours
+
+- GIVEN a cron expression `0 */2 * * *`
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL be the plain human-readable description
+- AND the output SHALL NOT contain "UTC"
+
+#### Scenario: Hourly
+
+- GIVEN a cron expression `0 * * * *`
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL be the plain human-readable description
+- AND the output SHALL NOT contain "UTC"
+
+### Requirement: Sub-Daily Detection
+
+The system SHALL determine whether a schedule is sub-daily by comparing the interval between consecutive future run times. If the interval between the first two next runs is less than 24 hours, the schedule is sub-daily.
+
+#### Scenario: Every 12 hours classified as sub-daily
+
+- GIVEN a cron expression `0 */12 * * *`
+- WHEN the system evaluates whether the schedule is sub-daily
+- THEN it SHALL classify the schedule as sub-daily regardless of the current time of day
+
+### Requirement: Graceful Fallback
+
+The system SHALL gracefully handle invalid or unparseable cron expressions by returning the raw expression string without modification.
+
+#### Scenario: Invalid cron expression
+
+- GIVEN an invalid cron expression `not-a-cron`
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL be the raw string `not-a-cron`
+
+#### Scenario: Cron expression with no recognizable time portion
+
+- GIVEN a valid cron expression whose human-readable description does not contain a recognizable time pattern
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL be the plain description without UTC annotation
+
+### Requirement: Both 12-Hour and 24-Hour Format Support
+
+The system SHALL correctly identify and annotate time portions in both 12-hour format (e.g., "02:30 PM") and 24-hour format (e.g., "14:30"), depending on the user's locale settings.
+
+#### Scenario: 24-hour locale
+
+- GIVEN a cron expression `30 14 * * *`
+- AND the user's locale produces 24-hour time format "14:30"
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL contain "14:30 UTC"
+
+#### Scenario: 12-hour locale
+
+- GIVEN a cron expression `30 14 * * *`
+- AND the user's locale produces 12-hour time format "02:30 PM"
+- WHEN the frontend renders the schedule description
+- THEN the output SHALL contain "02:30 PM UTC"