Description
Operational Background Job Runs expose the durable job registry to authorized workspace operators through dots jobs run <jobId>. A successful request queues the named job for the selected company and returns immediately with an execution id. dots jobs status <executionId> then reads the tenant-scoped execution record, including current state, progress, result, and error.
The job subsystem persists queue state before a worker claims it. The runner can renew leases, report progress, checkpoint intermediate state, classify retries, observe cancellation, and recover abandoned claims. Manual runs therefore use the same durable execution machinery as scheduled and event-triggered work.
Selling Points
- Starts maintenance and backfill work without requiring direct database access or a server restart.
- Returns a durable receipt immediately so long-running operations do not depend on one HTTP connection.
- Lets operators inspect queued, running, retrying, completed, partial, failed, or cancelled states.
- Scopes both enqueue and status reads to the caller’s selected company.
- Applies each registered job’s timeout, retry, priority, and concurrency policy consistently.
User Story
An owner needs to rebuild graph caches after a large import. They run dots jobs run graph-precompute, receive an execution UUID, and continue other work. They later call dots jobs status with that UUID to see whether the job is still running and inspect its structured result without opening the database or server logs.
Extension Surface
This capability is automatable through stable CLI and HTTP entry points. packages/cli/src/commands/jobs.ts accepts a job id plus supported trigger details such as dry-run and batch limit. Downstream code extends the runnable roster by defining a JobDefinition and registering or replacing it through packages/jobs/src/registry.ts; operators do not need a new CLI command per job.
Capabilities & Limits
The surface can durably enqueue registered work, reject unknown jobs, return concurrency conflicts, expose tenant-scoped execution status, and pass bounded job-specific trigger details. The runner underneath supports progress, checkpoints, cancellation flags, retries, lease renewal, and execution-history retention.
The command does not create or edit job definitions, list arbitrary SQL, or bypass owner authorization. Status requires the execution id returned by the run. Some internal composition callers still use runtime.runJobById to execute a handler inline, but the shipped admin route used by dots jobs run calls jobSubsystem.runJob and returns a queued receipt.
Implementation Map
packages/cli/src/commands/jobs.tsjobs runjobs statuspackages/api/src/routes/admin.tspackages/jobs/src/subsystem.tspackages/jobs/src/scheduler.tspackages/jobs/src/providers/skip-locked.ts