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

Who writes, and which copy is authoritative

There are two answers to “what runs exist”, and that is deliberate. The ECS world is the live one: it knows wait reasons and tick-fresh progress for the runs the daemon is holding right now, and host.rs’s list() reads it. The runs directory is the durable one: it survives a crash or a daemon that is not running, and list_runs below reads it. Disk lags the world by at most one persistence tick, so the two disagreeing is expected rather than a bug, and every reconciliation of that gap goes through looks_abandoned.

The runtime’s persistence_bridge is the only thing that writes a live run’s state. The writers in this module are #[cfg(test)] so that stays true by compilation rather than by convention: a test can lay down a run directory to read back, and production has no second path to the same files.

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.

StatCache

A parse cache keyed by a file’s (mtime, len): the file is re-read and re-parsed only when its stat changes.

Enums

ForceCancelOutcome

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

LogStream

Which of a stage’s two logs to read.

RunStatus

Current status of a background run.

StageRunStatus

Status of an individual stage within a run.

StageSelector

Which stage’s logs to read.

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.

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).

final_output_path

Where a run’s answer lives, beside its meta.json.

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.

list_runs_cached

list_runs through a StatCache, for pollers: each meta.json is re-parsed only when its stat changes, and cache entries for deleted runs are dropped. Same ordering and skip-unreadable behavior as list_runs.

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_context_snapshot_cached

read_context_snapshot through a StatCache, for pollers. The snapshot is shared, not cloned: a context window is the largest thing in a run dir, and handing out copies per tick is the churn this cache removes.

read_final_output

Read a run’s final output, content included.

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.

read_stages_index_cached

read_stages_index through a StatCache, for pollers.

read_stages_index_from

read_stages_index for a run directory the caller already holds.

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_run_logs

Read a run’s logs, choosing the stage and the stream.

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.

visit_run_archive

Stream a run’s archive through a visit_points visitor without ever materializing the journal: one buffered pass over run.lvr, one record and one running window in memory. Returns None if the archive is missing or its preamble is invalid; a torn tail (a live run mid-append) just ends the walk with the points already visited.

visit_run_records

Stream a run’s raw journal records through visit, one at a time, without materializing the archive. Same lenient tail handling as visit_run_archive. For consumers that inspect records rather than replayed points (journal search).

write_meta

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