scion-scheduler

Scion Scheduler

Schedule future events that deliver messages to agents — either one-shot (fire once at a specific time) or recurring (fire on a cron schedule). All schedules are project-scoped — an agent can only create and manage schedules within its own project.

For full command syntax: scion schedule --help and its subcommands.

Two ways to schedule — when to use which

Scion has two scheduling mechanisms. They solve different problems:

	scion message --in/--at	scion schedule create / create-recurring
Nature	fire-and-forget delayed send	durable, project-scoped event
Manageable	no handle once sent	list, inspect, cancel, pause, resume, delete, history
Visibility	only sender knows it exists	any agent in the project can scion schedule list
Recurrence	no	yes (create-recurring --cron)

Use scion message --in for a simple self-callback during your own wait — you need a poke, not a managed object.

Use scion schedule create when any of these apply:

• The event is recurring
• Another agent may need to inspect, cancel, or take over the schedule
• The wait outlives the current agent's session
• You need execution history or failure tracking

Waiting on external processes — the blocked-wait pairing rule

When waiting on an external, non-agent process (CI run, build job, deploy, third-party API), calling sciontool status blocked "..." alone is not sufficient. That command marks intentional waiting for the stall detector — it does not poll anything or wake you when the external condition resolves. Without a separate wake mechanism, you go fully idle and only resume if an unrelated inbound message happens to arrive.

Correct pattern: schedule a self-callback, then set blocked status.

scion message --in 5m agent:<self> "recheck CI status"
sciontool status blocked "Waiting for CI run to complete"

The self-callback delivers the wake-up; status blocked prevents the stall detector from flagging you during the wait. Neither replaces the other.