schedule

Manage scheduled automations. Schedules can be **recurring** (cron or RRULE expression) or **one-shot** (a single `fire_at` timestamp). Schedules support three modes: **execute** (run a message through the assistant), **notify** (send a notification to the user), and **script** (run a shell command directly without LLM involvement).

## Schedule Syntax

### Cron

Standard 5-field cron syntax: `minute hour day-of-month month day-of-week`

| Field        | Values        | Special characters |
| ------------ | ------------- | ------------------ |
| Minute       | 0-59          | , - \* /           |
| Hour         | 0-23          | , - \* /           |
| Day of month | 1-31          | , - \* /           |
| Month        | 1-12          | , - \* /           |
| Day of week  | 0-7 (0,7=Sun) | , - \* /           |

Examples:

- `0 9 * * 1-5` - weekdays at 9:00 AM
- `30 8 * * *` - every day at 8:30 AM
- `0 */2 * * *` - every 2 hours
- `0 9 1 * *` - first of every month at 9:00 AM

### RRULE (RFC 5545)

iCalendar recurrence rules for complex patterns. Must include a DTSTART line.

Supported lines (all expressions must include DTSTART + at least one RRULE or RDATE):

| Line      | Purpose                                                 |
| --------- | ------------------------------------------------------- |
| `DTSTART` | Start date/time anchor (required)                       |
| `RRULE:`  | Recurrence rule (multiple lines = union of occurrences) |
| `RDATE`   | Add one-off dates not covered by the pattern            |
| `EXDATE`  | Exclude specific dates from the set                     |
| `EXRULE`  | Exclude an entire recurring series                      |

Exclusions (EXDATE, EXRULE) always take precedence over inclusions (RRULE, RDATE).

#### Basic examples

- `DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY` - every day at 9:00 AM UTC
- `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR` - Mon/Wed/Fri at 9:00 AM UTC
- `DTSTART:20250101T090000Z\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1,15` - 1st and 15th of each month

#### Bounded recurrence

- `DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY;COUNT=30` - daily for 30 occurrences then stop
- `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO;UNTIL=20250331T235959Z` - every Monday until end of March

#### Set construct examples

- `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR\nEXDATE:20250120T090000Z` - Mon/Wed/Fri except Jan 20
- `DTSTART:20250101T090000Z\nRRULE:FREQ=DAILY\nEXRULE:FREQ=WEEKLY;BYDAY=SA,SU` - every weekday (daily minus weekends)
- `DTSTART:20250101T090000Z\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1\nRDATE:20250704T090000Z` - 1st of each month plus July 4th
- `DTSTART:20250101T090000Z\nRRULE:FREQ=WEEKLY;BYDAY=TU\nRRULE:FREQ=WEEKLY;BYDAY=TH` - union of Tuesdays and Thursdays

## One-Shot Schedules (Reminders)

To create a one-time schedule that fires once and is done, pass `fire_at` (an ISO 8601 timestamp) instead of an `expression`. This replaces the old reminder concept - "remind me at 3pm" becomes a one-shot schedule with `fire_at`.

One-shot schedules:

- Fire once at the specified time, then are marked as `fired` and disabled.
- Support both `execute` and `notify` modes (see below).
- Can be cancelled before they fire.

Examples:

- "remind me at 3pm" → `schedule_create` with `fire_at: "2025-03-15T15:00:00-05:00"`, `mode: "notify"`
- "at 5pm, check my email and summarize it" → `schedule_create` with `fire_at`, `mode: "execute"`

## Mode

The `mode` parameter controls what happens when a schedule fires:

- **execute** (default) - sends the schedule's message to a background assistant conversation for autonomous handling. The assistant processes the message as if the user sent it.
- **notify** - sends a notification to the user via the notification pipeline. No assistant processing occurs.
- **script** - runs the `script` field as a shell command directly. No LLM invoked, no conversation created. stdout/stderr are captured in the schedule run record. Exit code 0 = success, non-zero = error. Commands run in the workspace directory with a 60-second timeout by default. Override the timeout per schedule with `timeout_ms` (range 1000–1800000 ms) when a script needs more or less time; pass `timeout_ms: null` on update to revert to the default. The guardian can also adjust this from the /assistant/settings/schedules page.

Use `notify` for simple reminders ("remind me to take medicine at 9am"), `execute` for tasks that need assistant action ("check my calendar at 8am and send me a digest"), and `script` for lightweight shell automations that don't need LLM involvement ("refresh a cache", "poll an API", "rotate logs").

## Inference Profile

Execute-mode runs use the default `mainAgent` model selection unless the schedule pins an `inference_profile` (a key from `llm.profiles`). Pin a profile when a recurring task should run on a specific model — e.g. a cost-optimized profile for a high-frequency digest. Pass `inference_profile: null` on update to revert to the default. The pinned profile is shown on the schedule's details page in settings.

## Conversation Reuse

Recurring schedules reuse the same conversation across runs by default — subsequent runs continue the conversation from the last successful run, preserving context and channel thread continuity. Set `reuse_conversation: false` explicitly if each run should start with a fresh conversation (e.g. independent reports that shouldn't accumulate prior context). One-shot schedules always create a fresh conversation.

- Only applies to **recurring** schedules; ignored for one-shot schedules.
- If the prior conversation has been deleted, a new one is created automatically.
- On the first run (no prior conversation), a new conversation is created as usual.

## Routing (notify mode)

Control how notify-mode schedules are delivered at trigger time with `routing_intent`:

- **single_channel** - deliver to one best channel
- **multi_channel** - deliver to a subset of channels
- **all_chann