erun jobs

The platform's record of work in flight: what agents and orchestrators are working on right now, and what recently finished. Builds are reported after the work completes; a job is claimed before it starts, which is the half that lets two actors see each other and stop duplicating work.

Four subcommands: list, show, start, and finish. This is the host-side counterpart to erun exec job, which starts and observes work inside one environment — erun jobs observes the tenant's whole queue, including work that never entered an environment at all.

Synopsis

erun jobs list [flags]
erun jobs show JOB_ID [flags]
erun jobs start [flags]
erun jobs finish JOB_ID [flags]

Every subcommand accepts --erun-alias (defaults to the sole configured erun-type alias when only one is set up), --dry-run (trace the resolved HTTP call without sending it), and the global --output json for structured results.

Subcommands

jobs list

Lists jobs, the live queue first, narrowed by any combination of --status, --environment-id, --issue, --scope, and --actor. Each entry names what is being done, by whom, and how long it has been going.

A RUNNING job is work in flight, and so is PLANNED — work recorded before it starts. ABANDONED means its actor stopped updating it and the platform swept it — read it as dropped, not as failed. An empty queue is [], never null.

PLANNED is never swept to ABANDONED, and that exemption is the point of the status: the sweep exists to clear a RUNNING job whose actor went quiet, and a parked plan has no actor yet to go quiet. Backlog work stays in the backlog until someone picks it up or supersedes it.

jobs show

Shows one job in full by JOB_ID, including the scope it claims and the in-pod job id it mirrors, when there is one.

jobs start

Records that this actor is starting a piece of work: --type, --summary, and --actor are required; --actor-kind, --environment, --issue, --scope, --status, and --local-job-id are optional.

--status PLANNED records work that has not started — a triage/plan item parked against its issue, visible in the pipeline view before any code exists. It is a claim on --scope exactly as a running job is, so two actors cannot both plan the same work.

With --scope set this is a claim. If an open job already holds that scope, the command fails with 409 naming the holder — its actor, its prose summary, and when it started — so you can pick up something else instead of duplicating the work.

--type is one of fix, review, gate, release, deploy, investigate, plan, triage, or maintenance; an unknown value is refused rather than stored, so the queue can group without a free-text bucket. The --summary is prose describing the work, never the command that performs it — a summary that is only a shell command is refused, and the pod's own job record keeps the command line as technical detail.

jobs finish

Reports how a job ended (--status SUCCEEDED|FAILED|ABANDONED|SUPERSEDED), opens a planned one (--status RUNNING), refreshes what it is doing (--summary), or records the in-pod job id it mirrors (--local-job-id). A job that has already finished cannot be updated: its outcome is the record that coordination and reporting both read, and no status reopens it.

Examples

erun jobs list --status PLANNED
erun jobs list --status RUNNING
erun jobs list --issue sophium/erun#2109
erun jobs start --type fix --issue sophium/erun#2109 --scope sophium/erun#2109 \
  --summary "fixing the jobs claim race" --actor erun/code4
erun jobs start --type triage --status PLANNED --issue sophium/erun#2109 \
  --scope sophium/erun#2109 --summary "planning the jobs claim fix" --actor erun/ideas
erun jobs finish job_01H... --status RUNNING      # the planned work has begun
erun jobs finish job_01H... --status SUCCEEDED

Error behaviour

Failure	Behaviour
No erun-type alias configured.	Aborts naming erun cloud init erun --api-url <url> as the fix.
More than one erun-type alias configured, --erun-alias omitted.	Aborts asking for an explicit --erun-alias.
JOB_ID does not exist, or belongs to another tenant (show, finish).	404 Not Found.
--scope is already held by an open job (start).	409 naming the holder, what it is doing, and since when.
--status is a value outside the vocabulary (finish).	Aborts before sending anything.
--type is outside the vocabulary, or --summary is only a shell command (start).	400, naming the field.

Claiming is advisory

The scope claim is server-side coordination, not a distributed lock: two claims landing at the same instant can both be recorded. Making a scope exclusive in the database would wedge it permanently the moment an actor disappeared without closing its job. What the queue gives an operator is that overlap made visible, and a sweep closes a RUNNING job whose actor stopped updating it so a vanished actor cannot hold a scope forever.

See also

• MCP overview § Jobs — the jobs_list/jobs_show/jobs_start/jobs_finish tool spec.
• erun exec job — starting and observing work inside one environment (not yet covered by a page of its own).