Kernlift

Background jobs

How the web app runs its own periodic work once a minute on every platform, why one lock row is enough, and how /setup detects when it stopped.

The web app has work that no request triggers: retrying a failed fulfilment, finishing an AI task nobody is polling. That work is in one function, runScheduledJobs(), which runs one round of every job. Platforms differ only in what calls it. To check your own deployment, see Run background jobs.

One round, a fixed list of jobs

A round runs the jobs in order. A job that throws is recorded as failed and the next one still runs.

JobDoes
credit-sweepAn extension point. The template's ledger has nothing to expire or top up, so it reports zero; a project that adds expiring credits implements it here
billing-fulfilmentsRetries fulfilments that failed when an order was paid or refunded, with backoff
ai-channel-tasksAdvances asynchronous provider tasks nobody is polling, so they finish and settle credits
agent-maintenanceWith agent-starter only: gives a Cloudflare agent container with unfinished runs one maintenance round. Does nothing for an agent service reached by URL

These jobs belong to the web app, not to the Agent service. A deployment without the agent runs every one of them except agent-maintenance, and the agent service's own loop runs none of them.

Three ways a round starts

DeploymentTriggerSwitch
Node server (Fly.io, Railway, Docker, a VPS, pnpm dev)A loop inside the web process: first round five seconds after start, then one every minuteJOBS_IN_PROCESS, on by default
Cloudflare WorkerThe Cron Trigger "crons": ["* * * * *"] in wrangler.jsonc, handled by scheduled in the Worker entryThe triggers block
Anypnpm jobs:run from a system cron, a Kubernetes CronJob or a platform schedulerYour scheduler

The Node build starts the loop when the server process loads, so a fresh deployment with no traffic still retries fulfilments. pnpm dev does not evaluate the server entry, so there the loop starts with the first request. A Worker is not a long-running process and may not hold a timer, so the loop never starts there. Setting JOBS_IN_PROCESS=false turns the loop off and leaves scheduling to pnpm jobs:run.

One lock row keeps it to one round a minute

Triggers are allowed to overlap: every replica runs the loop, and a cron may fire next to it. The lock is a single row in config_settings, jobs.next_run_at, holding an ISO timestamp.

  1. A runner claims the round with a conditional update: move jobs.next_run_at forward only if it is not in the future. Exactly one caller's update changes the row. The others see zero rows updated and return "skipped".
  2. The claim pushes the timestamp five minutes ahead. If the runner dies mid-round, the lock expires after that.
  3. When the round ends, jobs.next_run_at is set to one minute after the round started, jobs.last_run_at to the finish time and jobs.last_report to the round's JSON report.

The comparison is a string comparison of ISO timestamps, which orders the same way on SQLite, D1 and Postgres, and the claim is one statement, so it needs no transaction.

The heartbeat on /setup

/setup stores no status flag for jobs. It reads jobs.last_run_at and jobs.last_report each time and evaluates them:

State/setup shows
No round recordedNot ready. A new deployment records its first round within a minute; if the message stays, nothing is starting them
Last round more than five minutes agoNot ready, with how long ago it ran
Last round had a failed jobNot ready, with each failed job's name and error
Last round recent and cleanReady

Every message ends with how rounds are started on the platform in deploy.config.json: the Cron Trigger on Cloudflare, min_machines_running = 1 on Fly.io, the web service on Railway, the web container on Docker. The item has no admin page to link to, because it is fixed in the platform.

Files

src/server/jobs/scheduled.ts
src/server/jobs/credit-sweep.ts
src/server/db/repositories/scheduled-jobs.repository.ts
src/server/jobs/in-process.ts
src/server-entry.ts
src/server-entry.node.ts
scripts/jobs/run.ts
src/server/jobs/heartbeat.ts
src/server/functions/setup-readiness.ts

pnpm validate:optional-agent runs rounds against the configured database and asserts the lock: a second call inside the minute skips, two concurrent calls run one round, and a crashed runner's lock is taken over.

Next steps