# Operate runs This guide is for the person who looks after runs once workflows are in use. It shows how to find the runs that need attention, how to get each kind moving again or end it, and how to keep the store tidy. Every output shown is from a real run of the command. ## Find the runs that need attention List the runs, newest first: ```bash realm run list ``` It prints one line for each run: its ID, workflow, phase, last change and number of steps. ```text 566ba1b6-8e67-4255-9fd9-ed9b270b452d sync v1 abandoned 10/2/2026, 12:33:38 AM 1 step(s) 7be2233c-2f2d-4f22-98cd-f561496c129b sync v1 failed 10/2/2026, 12:32:56 AM 3 step(s) ``` Narrow the list with `--status ` or `--workflow `. To see only the runs that are open and have not moved for a while, use `--stuck`: ```bash realm run list --stuck ``` It prints: ```text No stuck runs found (threshold 24h). ``` By default a run counts as stuck after 24 hours without a change. Set another limit with `--older-than`, for example `--older-than 30m`. A run that is listed says why: ```text Stuck runs (threshold 0m): f4dee18d-e5a4-4989-885d-bea2a7b60483 sync v1 running 10/2/2026, 12:35:37 AM 1 step(s) idle: 0m ``` ## Look at one run ```bash realm run inspect ``` The first lines say where the run stands and, for a finished run, what ended it: ```text Phase: failed Sealed by: step_failure Cause: Step 'fetch' failed: Step 'fetch' failed after 3 attempts Completed: page_on_call, release_lock Failed: fetch Skipped: summarise ``` Further down, `Run Health` lists anything Realm finds wrong with the run, and `Drive failures` lists the times a driver gave up on it. See [Evidence](https://realmengine.dev/docs/concepts/evidence.md) for how to read the rest. ## Decide what to do | The run is | Do this | | ------------------------------------- | ----------------------------------------------------------------------------- | | `gate_waiting` | Answer the gate. See [Waiting at a gate](#waiting-at-a-gate). | | `running`, and its driver has stopped | Start a driver on it again. See [Open, with no driver](#open-with-no-driver). | | `failed`, and the cause is now fixed | Resume it. See [Failed](#failed). | | open, and should not continue | Abandon it. See [No longer wanted](#no-longer-wanted). | | finished, and old | Purge it. See [Keep the store tidy](#keep-the-store-tidy). | ## Waiting at a gate `realm run inspect` shows the gate's ID and choices. Answer with: ```bash realm run respond --gate --choice ``` See [Add a human gate](https://realmengine.dev/docs/guides/human-gates.md#6-answer-it). ## Open, with no driver A run in `running` moves only when a driver calls it. If the driver has stopped, start one on the same run. When the run owes the engine work — an `auto` step or a guard, as the `Owed to the engine:` line of `realm run inspect` says — run it from your shell, with no model and no key: ```bash realm run advance ``` It stops where the run next needs something else, such as an agent step or a question, and says which. An agent step needs a driver with a model: ```bash realm agent --run-id --model ``` `` is the model to drive the run with. Give the flags you drove the run with: the model flags (`--provider-module`, or `--provider`, `--model`, `--base-url` and `--strict-base-url`) as you used them, and `--extensions-module`, `--project`, `--schema-retries`, `--llm-timeout` or `--mint-writer-nonce` if you used them. Realm does not record the model or most of those flags: `realm run inspect` shows the provider of a drive failure, and the extension module the run loaded under `Extension Identity`. A run started by `realm workflow run` was never driven by a model: name any provider and model you want. Version 0.45.0 has a default model, so `--model` can be left out there. An assistant connected over MCP can pick the run up as well, by asking for its state and following the reply. ## Failed When the cause of a failure has been fixed, re-enable the failed step: ```bash realm run resume --from ``` It prints: ```text Resumed run '4a0eafe2-afff-40ca-8b89-ad0e92db1a9c': step 'fetch' re-enabled and run reset to 'running'. To run the step the engine owes ('fetch') without a model: realm run advance 4a0eafe2-afff-40ca-8b89-ad0e92db1a9c ``` The run is open again. Steps that had completed stay completed; the named step will run again. `fetch` is a step only the engine runs, so the second line names the call that runs it, with no model. When the step that is ready again is an agent step, the second line is `Drive it with: realm agent --run-id --provider --model ` instead, with `` and `` to fill in as above, and a third line names the other flags to add. The `realm run advance` line was added after version 0.46.0, which prints the `Drive it with:` lines for every step. Version 0.45.0 prints the `Drive it with:` line without `--provider --model `, and nothing after it. `--from` must name a step the run lists under `Failed`. For any other step, the command refuses: ```text Step 'fetch' is not in failed_steps for run '44df45a3-630d-4679-961e-4cc1616307b4'. ``` A run that was `aborted` cannot be resumed. Start a new run. ## No longer wanted To end an open run by hand: ```bash realm run abandon --reason "docs test" ``` It prints: ```text Run '566ba1b6-8e67-4255-9fd9-ed9b270b452d' abandoned (phase: 'abandoned'). Reason: docs test. … abandon is a kill — declared finalizers (if any) did NOT run and will not for this run. … ``` Two things to know before you abandon: - **Cleanup steps do not run.** A workflow's finalizers are skipped. - **A run waiting at a gate cannot be abandoned.** Answer the gate first. A run that has already finished is left alone: ```text Run '0fdae340-…' is already terminal (failed); cannot abandon a finished run. ``` To abandon every open run that has been idle for a while, preview first: ```bash realm run cleanup --older-than 7d --dry-run ``` It prints: ```text Would mark 1 run(s) as abandoned. • 79b5ba95-7bc1-4779-ab12-2e653139eb29 abandon is a kill — declared finalizers (if any) did NOT run and will not for this run. … ``` Without `--dry-run`, the same command abandons them. It leaves runs that are waiting at a gate. ## Keep the store tidy Run records stay on disk until you remove them. ### Keep a copy first `realm run export` writes everything Realm holds about a run to one file: ```bash realm run export --out ./run-44df45a3.json ``` It prints: ```text Exported run '44df45a3-630d-4679-961e-4cc1616307b4' to './run-44df45a3.json' (5.8 KB). phase: failed, attempts: 2, WAL steps: 0, sealed artifacts: 0 ``` ### Delete finished runs `realm run purge` deletes finished runs for good. It only reports what it would delete, unless you add `--force`: ```bash realm run purge --older-than 30d ``` It prints: ```text 6 run(s) WOULD be purged (21.3 KB to free): • 0fdae340-a7e5-4ff5-b83f-9fb6086a53be (failed, 3.6 KB) … 3 of 6 selected run(s) are resumable via 'realm run resume' — purging would destroy that path permanently. Re-run with --force to actually delete. ``` Read the list, then run it again with `--force`: ```text Purged 6/6 run(s) (21.3 KB freed, store-reported). 0 already gone, 0 blocked, 0 failed. 3 of 6 selected run(s) were resumable via 'realm run resume' — purging has destroyed that path for them. ``` Purge never touches a run that is still open. To purge one run, give its ID in place of `--older-than`. ### Remove leftovers `realm run gc` removes files that a crash can leave behind. Like purge, it only reports unless you add `--force`: ```bash realm run gc --older-than 1d ``` It prints, on a clean store: ```text No orphaned .tmp files found to reap. No run-less orphaned WAL/sidecar artifacts found to reap. gc does NOT yet reap orphaned .lock dirs (deferred — issue #164). Their presence in runsDir is expected and not a sign gc is broken. ``` ## Two rarer cases - **A step was started and never finished**, because the process running it died. `realm run reclaim ` reports such steps, and with `--force` makes them runnable again. The step's work may then happen twice, so read what it reports first. - **A run ended but its cleanup steps did not finish.** `realm run drain ` reports them, and with `--force` runs them. ## If you see something else - **`Run not found: `** No run has that ID in this store. Check the ID with `realm run list`. ## See also - [`realm run` commands that read](https://realmengine.dev/docs/reference/cli/realm-run-reading.md) - [`realm run` commands that act](https://realmengine.dev/docs/reference/cli/realm-run-acting.md) - [Run state and health findings](https://realmengine.dev/docs/reference/mcp/run-state-and-health.md) lists everything `Run Health` can report.