Module tracking 

File-based tracking backend: run directories under .soma/runs/.

JsonlEventSink is the lossless event consumer wired into EventBus; LocalTracker owns one run directory (manifest, status, logs). See docs/src/content/docs/design/tracking.md for the on-disk layout.

Structs

AgentNodeActivity

One step node’s share of the run’s agentic work. Spawned instances appear under their own hierarchical ids (parent/label).

AgenticActivity

Agent-level activity for one run, aggregated from the step events (AgentTurnStarted, EffectCompleted, ToolCalled, Suspended, AgentStepCompleted, …). Empty by_node means the run had no agent steps — or predates their telemetry.

CacheActivity

Per-run cache effectiveness, reconstructed from hit/miss events.

EffectSpan

One effect’s execution inside a step — the gantt substrate for agent runs, the per-effect analogue of NodeSpan. An unclosed span (outcome: "running") means the run died mid-effect.

HealthFlagRecord

One HealthFlag event with its wall time.

JsonlEventSink

Writes every event as one JSON line to events.jsonl, teeing metric-bearing events (TrialMetric, MetricReported) into a flat metrics.jsonl for cheap time-series reads.

LocalTracker

A run directory under <root>/runs/<run_id>/.

MetricPoint

One line of metrics.jsonl (also derivable from events).

NodeCacheCounts

One node’s share of CacheActivity.

NodeSpan

One execution span of a node, in event order. A node appears once per execution (re-runs and stream chunks produce separate spans).

RunInfo

Listing entry for one run: manifest identity plus derived liveness.

RunReader

Reader over one run directory.

TrialSpan

One trial’s lifetime, from study.json.

Constants

PARENT_ENV

Environment override for the parent run id.

STALE_HEARTBEAT_SECS

A Running status whose heartbeat is older than this is reported as crashed: the process died without finalizing.

Functions

advance_head

Advance HEAD after a run finished successfully.

checkout

Point HEAD at an existing run so the next run branches from it.

clear_head

Detach HEAD: the next run starts a new line. Absent HEAD is fine.

collect_git_info

Best-effort git context via subprocess; all-None outside a repo.

head_path

Path of the HEAD file for a tracking root (.soma/HEAD).

list_runs

All runs under <root>/runs/, newest first. Directories without a readable manifest are skipped.

load_manifest

Read a run’s manifest.

load_status

Read a run’s status file.

read_head

The run id in .soma/HEAD, if any. An unreadable, empty or whitespace-only HEAD reads as absent — never as an error, because a broken pointer must not stop a run from starting.

resolve_parent

Resolve the parent run for a run about to start.

resolve_parent_from

The precedence rule, with its inputs injected — the testable core.

run_exists

Whether <root>/runs/<run_id>/manifest.json exists.

summarize

Fold a run directory into a [RunSummary].

write_head

Point HEAD at run_id, atomically (write to a temp file, then rename) so a crash mid-write leaves the previous pointer intact rather than a truncated one.