Files
kandev/docs/specs/tasks/system-design/run-scheduling.md
T
2026-08-24 21:30:53 +00:00

83 lines
3.1 KiB
Markdown

---
status: current
system: tasks
requirements:
- REQ-TASKS-RUN-SCHEDULING-001
created: 2026-08-24
owners:
- cfl
---
# Queued Run Scheduling System Design
## Context and boundaries
The task system owns the persisted runs queue and its single backend-wide
consumer. Office supplies some run producers and Office-only maintenance, but
does not own a scheduler per workspace.
## Requirement mapping
| Requirement | Design sections |
| --- | --- |
| REQ-TASKS-RUN-SCHEDULING-001 | Queue ownership, classification, lifecycle, shutdown, recovery |
## Queue ownership and classification
The existing `runs` table is the durable queue. One scheduler claims work for all
workspaces in global request order while preserving the existing per-agent
serialization rule. Explicit `queue_run` workflow actions may enqueue from any
workflow style.
Interactive user launches stay on the interactive orchestrator path.
Office assignment subscribers and unstarted-task recovery classify a task as
Office-owned only through the authoritative Office project/workflow identity.
An ordinary Kanban runner never becomes autonomous by assignment alone.
Office recovery and cron work are disabled when their corresponding Office
configuration is absent.
## Scheduler lifecycle
The scheduler and each cron loop own one goroutine and one cancellation context.
The lifecycle is stopped -> running -> stopping -> stopped. Duplicate Start and
Stop calls are idempotent. Stop cancels future ticks and waits for the active
tick and handler fan-out before returning.
An in-process signal wakes the consumer immediately. A periodic safety pass
reclaims persisted work after a missed signal or restart. No new schema or run
state is introduced.
## Shutdown and recovery
Graceful shutdown stops external intake, joins queue and cron loops, stops the
orchestrator and agent runtime, then closes event-bus, repository, and database
resources. SQLite is never closed underneath live scheduler work. A blocked
handler keeps shutdown in progress; an outer supervisor may enforce its own
process grace period.
Queued and retryable runs remain durable across restart. A claimed run follows
the existing stale-claim recovery policy. In-memory signals and scheduler
contexts are not persistence sources.
## Failure and observability
Missed signals are recovered by the safety pass. An empty queue is a normal
wait state. Office configuration without an Office workflow does not trigger
ordinary Kanban scans. A signal-driven shutdown must not emit database-closed
scheduler errors or scheduler logs after the graceful-shutdown completion
message.
## Verification
- Test one global consumer across multiple workspaces, global FIFO ordering, and
per-agent serialization.
- Test Office classification, explicit `queue_run`, missed-signal recovery, and
restart recovery.
- Test idempotent lifecycle calls and shutdown while idle or inside a handler.
- Test that queued rows remain available after process restart.
## Related records
- [Global run scheduler ownership](../../../decisions/2026-08-01-global-run-scheduler-ownership.md)
- [Run scheduler lifecycle](../../../plans/run-scheduler-lifecycle/plan.md)