Skip to main content

Module runs

Module runs 

Source
Expand description

Observed-tier, READ-ONLY inventory of scheduled-job FIRES across the harnesses that keep a run store (Domain 11, concept 7).

A run is one execution of a crate::jobs::ScheduledJob, with its outcome and — where the harness leaves enough behind to recover it — the session the fire opened.

  • HermesHERMES_HOME/cron/executions.db, a profile-local SQLite audit ledger (cron/executions.py: “the ledger records what is known about each attempt; it is not a retry queue”). One executions row per attempt: id, job_id, source, process_id, pid, process_started_at, status, claimed_at, started_at, finished_at, error, status one of claimed | running | completed | failed | unknown. A Hermes profile home is a full HERMES_HOME, so each profiles/<name>/ has its own ledger.
  • OpenClawcron_run_logs in the shared state database (<state dir>/state/openclaw.sqlite) at the pinned 2026.7.1-2: store_key, job_id, seq, ts, status, error, …, session_id, session_key, run_id, run_at_ms, duration_ms, …, entry_json, status one of ok | error | skipped. store_key is path.resolve(cron.store) — the legacy cron/jobs.json path used purely as a per-store partition key; at the pin no such file exists, and neither does a cron/runs/*.jsonl run log (that shape is what openclaw doctor --fix imports FROM).
  • Claude Code — has no run store at all. A CronCreate fire is an ordinary turn inside the session that created the job, so runs.list / runs.get refuse for claude-code rather than inventing a fire record from turns. See RUN_HARNESSES.

Nothing here writes, claims, retries, or prunes. Every store is opened SQLITE_OPEN_READ_ONLY — these are live databases owned by a running scheduler.

Status words are the harness’s own. Hermes says completed/failed, OpenClaw says ok/error; renaming either onto a shared vocabulary would discard the distinction Hermes draws between failed (a terminal result it wrote) and unknown (an attempt whose owner died before writing one).

Delivery (ORCH-13). Where a fire’s output went is read from each harness’s own delivery record:

  • OpenClaw writes it onto the run-log row itself — delivery_status, delivery_error, delivered — and declares the destination on the job (cron_jobs.delivery_channel / delivery_to), so the row’s target is joined from there: the run log records the OUTCOME, never the address.
  • Hermes keeps a separate delivery_obligations ledger inside state.db (gateway/delivery_ledger.py), keyed by the CONVERSATION’s session_key and the platform surface — not by job or fire. So a fire is matched to an obligation the way [join_hermes_session] matches a session: by the fire’s own [claimed_at, finished_at] window, on the fire’s own surface. See [hermes_delivery] for the two questions asked, in order, and for why an unanchored ledger instant answers None.

None stays honest: a fire whose delivery nothing recorded says so rather than borrowing a neighbouring fire’s outcome.

Structs§

HarnessRun
Hard stop on how far a compression chain is followed from a fire’s own session to the readable tip. Hermes chains are short; a cycle in a corrupted store must not spin. One fire of one scheduled job, projected onto the uniform Domain 11 row.
RunDelivery
A fire’s delivery outcome (ORCH-13).
RunSource
One store the listing consulted, and what it found there.
RunsListing
Result of a runs.list: the rows plus every store that was consulted.
RunsQuery
Filters for a run-history read.

Constants§

RUN_HARNESSES
Harnesses that keep a run store at all. Every other harness answers runs.list / runs.get with UnsupportedAction, never an empty list — an absent store and an empty history are different answers.

Functions§

get_run
Read one fire by harness and id, with the verbatim native record beside the uniform row. Ok(None) means the harness’s stores hold no such run.
list_runs
Read every fire the query selects.
supports_runs
Whether harness keeps a run store.