Scheduled tasks: file-based config in the repo, with a CLI to export and apply

[TechFeatured]

Before submitting

• I searched existing issues and discussions and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server (scheduled tasks), CLI

Problem or use case

Scheduled tasks exist only in each environment's local state (statev2.sqlite, the scheduled_tasks table). Their prompt, cadence, model and workspace strategy can be edited only in the Schedules UI or through the schedule_task MCP tool, and t3 has no schedule subcommand. For a team that runs a handful of recurring agent jobs from one repo, that causes three problems:

1. No history or review. A prompt is effectively code: it decides what an unattended agent publishes, files or emails. Changes to it don't go through a PR, can't be diffed, and are easy to break. Ours had drifted from the repo's skills: three of five prompts named a skill path and a script that had since been deleted.
2. Moving machines means rebuilding by hand. I moved five recurring schedules from a laptop to an always-on cloud box. Each had to be re-created field by field through schedule_task on the new environment, the project needed a default model first, and the time zone had to match or timeOfDay meant a different hour. Nothing could be exported or applied.
3. Stale references fail silently until run time. One weekly schedule pointed at a provider instance that was later removed (ThreadManagementProviderInstanceDisabledError). Nothing showed it until its next run failed.

Our workaround is to keep each prompt in the repo (.claude/schedules/<name>.md) and set the T3 prompt to "Follow .claude/schedules/<name>.md in this checkout", since every run starts in a fresh worktree from origin/main. That covers the prompt, but cadence, model and workspace strategy still live only in T3.

Proposed solution

Let a project declare schedules in files, the way it declares scripts:

# .t3/schedules/press-room-daily.yaml
title: Daily press-room run
schedule: { type: fixed_time, timeOfDay: "09:00", timeZone: America/Phoenix }
prompt: |
  Run /publishing:setup-room then /campaigns:gate for every client room...
# or: promptFile: .t3/schedules/press-room-daily.md
model: { instanceId: claudeAgent, model: claude-opus-5-5 }
workspace: { type: worktree, baseRef: origin/main, startFromOrigin: true }
freshSession: true
environment: <environment id or label>   # which machine runs it, so a repo cloned on several machines does not run it on each

• Loading: T3 reads these files from the project's default branch (or a configured ref) and keeps the matching scheduled tasks in sync. In the UI they show as "from repo", and their fields can't be edited there.
• Local overrides: only an enabled toggle is kept per environment, so pausing a job doesn't need a commit.
• Validation: when a file is loaded, a missing provider instance or model, an unknown environment, or a bad schedule shows as an error on the task, instead of failing on the next run.
• CLI: t3 schedule list | export [--project] | apply <dir> [--dry-run]. export writes the current schedules out as files, which makes adopting this and moving to another machine one command each.
• Time zone: an explicit timeZone per schedule, so a fixed_time schedule means the same hour on every machine. scheduler: scheduled task times shown in UTC instead of local/system time (IST) #18632 is related.

Why this matters

Recurring agent jobs are becoming real production work: publishing, abuse sweeps, reports emailed to people. They need the same things as other automation: review, history, rollback and a way to move between machines. Keeping them in the repo next to the skills and scripts they call stops the prompts drifting from the code.

Alternatives considered

• A prompt file only (our workaround): it works for the instruction text, but cadence, model, environment and workspace still drift, and moving machines is still manual.
• GitHub Actions cron: that loses T3's environment, providers, MCP sign-ins and threads, which are the reason to run these in T3.