Module runstate 

On-disk run state for background agent executions.

Each run lives under ~/.leviath/runs/<run-id>/ with:

• meta.json - run metadata, updated atomically (tmp + rename)
• output.log - append-only combined worker stdout (legacy/fallback)
• stages.json - index of per-stage records
• stages/<idx>/output.log - readable agent output for that stage
• stages/<idx>/logs.log - operational events + tool activity
• stages/<idx>/context.json - context snapshot for that stage

The dashboard’s activity log is persisted separately at:

• ~/.leviath/dashboard.log - never cleared, appended across sessions

Structs

ContextSnapshot

Snapshot of the full context window, written to context.json alongside meta.json.

RegionEntrySnapshot

One content entry within a region, captured at snapshot time.

RegionSnapshot

Per-region token snapshot written by the background worker after each inference.

RunMeta

Metadata for a single background agent run.

StageRecord

Metadata record for a single stage within a run.

Enums

ForceCancelOutcome

The outcome of forcing a run to a terminal state on disk.

RunStatus

Current status of a background run.

StageRunStatus

Status of an individual stage within a run.

Constants

STALE_AFTER_SECS

How long a run may claim to be live on disk, while the daemon is not holding it, before anything treats it as abandoned.

Functions

append_dashboard_log

Append a timestamped line to the persistent dashboard activity log at the default dashboard_log_path. Silently ignores I/O errors - best-effort.

append_dashboard_log_to

Append a timestamped line to the dashboard activity log at an explicit path. Silently ignores I/O errors - the dashboard log is best-effort.

append_stage_log

Append a line of operational/tool-activity log to the per-stage logs file.

append_stage_output

Append a line of readable agent output to the per-stage output log.

context_history

A run’s context-window history: the full window (+ metadata) at each recorded point over time, oldest first. Empty when there’s no readable archive.

create_run

Create the run directory and write initial metadata.

dashboard_log_path

Path to the persistent dashboard activity log (~/.leviath/dashboard.log).

force_cancel

Force a run’s on-disk metadata to Cancelled, in the runs dir resolved from the environment. See force_cancel_in.

force_cancel_in

Force the run in run_dir to Cancelled, stamping updated_at with now.

force_error_in

Force the run in run_dir to Error with message, stamping updated_at.

is_terminal_status

Whether an on-disk run status means the run has finished and should be left alone. Starting/Running/WaitingInput are all “still going” as far as anything reading the runs dir is concerned.

list_runs

List all runs, sorted by started_at descending (most recent first). Silently skips any runs whose metadata cannot be read.

looks_abandoned

Whether a run that claims to be live on disk has nothing driving it: the daemon is not holding it and it has not moved in STALE_AFTER_SECS.

new_run_id

Generate a unique run ID: <agent_name>-<timestamp>-<random>.

read_context_snapshot

Read the context snapshot for a run, if present.

read_meta

Read run metadata for a given run ID.

read_run_archive

Read + parse a run’s portable archive (<run_dir>/run.lvr), returning its records, or None if the archive is missing or unreadable.

read_stage_context

Read the context snapshot for a specific stage, if present.

read_stages_index

Read the stages index for a run, or return an empty vec on any error.

run_dir

Directory for a specific run.

runs_dir

Directory where all run state is stored.

stage_dir

Directory for per-stage files within a run.

tail_file

Read the last max_bytes of any file on disk, returning UTF-8 text. If the file is smaller than max_bytes the whole file is returned. Partial UTF-8 at the truncation boundary is handled by skipping to the first newline. Returns an empty string on any I/O error.

tail_stage_log

Read the last max_bytes of the operational log for a specific stage.

tail_stage_output

Read the last max_bytes of the readable output log for a specific stage.

write_context_snapshot

Atomically write a context snapshot for the run.

write_meta

Atomically write run metadata (write to tmp, then rename).

write_stage_context

Atomically write a context snapshot for a specific stage.

write_stages_index

Atomically write the stages index for a run.