Monthly option for fixed-time scheduled tasks

[oskarsonc]

Problem or use case

Some recurring work runs once a month, such as a monthly report, a dependency audit, a billing review, or cleanup of old branches. A scheduled task cannot express that today.

• fixed_time takes a time of day and optional weekdays. It can run daily or weekly, but not monthly.
• A 30-day interval drifts against the calendar. It counts from when the task was created or last updated, so it cannot run on "the 1st of each month at 09:00".

The workaround is a daily task whose prompt says "if today is not the 1st, stop". That starts an agent turn every day, and most of those turns do nothing.

The Codex app has a monthly option for its scheduled tasks.

Proposed solution

Add an optional day-of-month list to fixed_time instead of a new schedule type:

{ type: "fixed_time", timeOfDay: "09:00", monthDays: [1] }       // 1st of every month
{ type: "fixed_time", timeOfDay: "09:00", monthDays: [1, 15] }   // 1st and 15th

• monthDays is an optional array of integers from 1 to 31. Without it, the schedule behaves as it does now.
• The schema rejects a schedule that sets both monthDays and weekdays.
• If a month has no such day, the task runs on the last day of that month. For example, 31 runs on April 30, so 31 also means "end of month".
• Existing tasks keep working because the field is optional.

Files that would change:

• packages/contracts/src/scheduledTask.ts gets the new field and the check that rejects it together with weekdays.
• In apps/server/src/scheduledTasks/Schedule.ts, nextScheduledRunAt now looks at most 8 days ahead. It must look up to a month ahead. isSameSchedule and describeSchedule must also read the new field.
• The web and mobile schedule editors get a "Monthly" choice with a day picker.
• The schedule_task and update_scheduled_task MCP tool schemas and the orchestration instructions document the field.
• Schedule.test.ts and ScheduledTaskService.schedule.test.ts get cases for short months, leap years, and DST changes.

One question for maintainers. The scheduler skips a fixed-time run that is more than 10 minutes late. If a laptop is asleep at 09:00 on the 1st, a monthly task loses that month's run. Should a monthly run fire once when the server comes back, or keep the current skip behavior?

Why this would help

The change adds one optional field to the existing fixed_time schedule and covers monthly work without the daily date-check workaround and its extra agent turns.

I can implement this if maintainers approve the direction and scope.

[itsjeremyjohnson]

+1, and here is a concrete use case.

We run a fresh-thread scheduled task that pulls each client's Search Console page-indexing report on the 3rd of every month. Indexing data needs a few days after month end to settle, so the run has to land on a fixed day of the month.

fixed_time only covers daily and weekly schedules, and a 30-day interval drifts away from the calendar. Our workaround is an external cron (0 5 3 * *) that POSTs to the task's webhook trigger. It works, but it means running a second scheduler and keeping the webhook URL on disk.

monthDays: [3] on fixed_time would cover our case. We would also use a "last day of month" option for month-end reporting if one existed.