Schedules and occurrences
A task holds the work to do. Its optional schedule determines when it becomes due. An occurrence records one scheduled run and whether it is pending, completed, or canceled.
Choose a schedule
Use one scheduling option when creating or updating a task:
| Option | Use it for | Format |
|---|---|---|
--at | A single future reminder | ISO timestamp with Z or an explicit offset |
--every | A fixed interval | Integer duration such as 30m, 2h, or 1d |
--cron | A calendar routine | Five-field cron expression, such as 0 9 * * 1-5 |
For --at, choose a future timestamp. For example, 2030-01-15T09:00:00-06:00 means January 15, 2030, at 9 AM with a UTC offset of minus six hours; substitute the date you intend.
Intervals accept s, m, h, or d, with a minimum of 60 seconds and a maximum of 365 days. Cron uses UTC by default. Add --timezone America/Chicago, or another IANA time zone, for a local calendar routine. --timezone applies only to cron.
A task created without a schedule remains a private task but does not produce scheduled occurrences. Use socra task update TASK_ID --clear-schedule to remove a schedule.
When work becomes due
Tasks persists an occurrence before publishing its due event. The Socra Agent integration delivers an agent-owned task to the matching agent's mailbox. The runtime reads the current task and occurrence before acting and skips inactive work.
Timing is approximate. Delivery, computer startup, and provider availability can delay execution. After downtime, missed recurring intervals coalesce into one occurrence rather than producing a separate run for every missed interval.
Delivery can happen more than once. Before repeating an action after an interruption, the agent should inspect the occurrence history and any work already performed. A schedule does not authorize extra access or external actions. An agent's internal run summary does not automatically notify a person; the task needs an authorized reporting destination.
Complete the right thing
| Action | Result |
|---|---|
| Complete a recurring occurrence | Finishes that run and preserves the recurring schedule |
| Complete a one-time occurrence | Finishes the occurrence and its task |
| Complete the task | Ends the task and its entire recurring series |
| Pause the task | Stops scheduling without completing the task |
| Cancel the task | Cancels the task and stops scheduling |
Occurrences can remain pending until explicitly completed. Publishing or receiving a due event does not complete the work.
Change or recover a task
Changing a schedule invalidates outstanding occurrences. Deleting a task hides it, cancels pending occurrences, and stops scheduling. Canceling or deleting cannot undo actions already in progress.
Deletion is recoverable with socra task restore TASK_ID. Restoring or reopening leaves scheduling paused. Inspect the task before using socra task resume TASK_ID. Update a one-time schedule whose timestamp has passed before resuming it.
Check a missed run
Have the owning agent retrieve the task and list its occurrences with the CLI. Check its status, schedule_paused, next_run_at, and time zone.
If an occurrence exists but the work is incomplete, inspect the agent's activity and availability. Check that it has access to the required resources and that its model connection can run. A task owned by your personal identity will not arrive in an agent's mailbox.
After an interrupted run, inspect the result before retrying. Complete the occurrence only after the work succeeds.