# Exprun

> Use when expgen has produced an experiment handoff and the task is to execute, monitor, repair operational failures, and report full experiments.

- Skill: `opendcai/exprun` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add opendcai/exprun`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opendcai/exprun/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: opendcai (https://skillmd.com/u/opendcai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opendcai/exprun

---


# Exprun

## Purpose

Exprun is the execution counterpart to `expgen`. It consumes `exp_handoff.yaml`, builds a full run matrix, launches experiments, monitors progress, handles operational repair, and writes final results.

Use `expgen` first when the experiment repository or handoff does not exist.

## State Machine

Use `exprun_state.json` in the chosen output directory. Resolve bundled scripts relative to this `SKILL.md`.

```bash
python scripts/exp_state_guard.py init --dir <output-dir>
python scripts/exp_state_guard.py enter --dir <output-dir> --stage handoff
python scripts/validate_handoff.py --file <output-dir>/exp_handoff.yaml
python scripts/exp_state_guard.py pass --dir <output-dir> --stage handoff --artifact exp_handoff.yaml
python scripts/exp_state_guard.py enter --dir <output-dir> --stage plan
python scripts/exp_state_guard.py pass --dir <output-dir> --stage plan --artifact full/matrix.yaml
python scripts/exp_state_guard.py enter --dir <output-dir> --stage run
python scripts/exp_state_guard.py pass --dir <output-dir> --stage run --artifact full/run_monitors.jsonl --artifact full/monitoring_summary.json
python scripts/exp_state_guard.py enter --dir <output-dir> --stage report
python scripts/exp_state_guard.py pass --dir <output-dir> --stage report --artifact full/final_report.md
```

Legal order:

```text
handoff -> plan -> run -> report
```

Hard rules:

- If the handoff is invalid, block before planning.
- Do not change the research claim, metric direction, or validated protocol from `exp_handoff.yaml`.
- Repair only operational failures: transient infra, resumable job failure, output collection, or log aggregation.
- Block on semantic drift, repeated deterministic failure, budget overrun, or missing raw outputs.
- Subagents may inspect logs or propose repairs, but only the orchestrator calls the state guard.

## Dispatcher

Use `scripts/dispatch_node.py` to identify the current stage and reference file:

```bash
python scripts/dispatch_node.py --dir <output-dir>
```

The dispatcher is advisory routing; `exp_state_guard.py` is authoritative state control.

## Workflow

1. Validate `exp_handoff.yaml`.
2. Freeze repository/config snapshot.
3. Build `full/matrix.yaml` across variants, seeds, scales, and repeats.
4. Launch runs with stable per-run output directories.
5. Monitor every interval `t`; default `t` is 30 minutes for long runs.
6. Record command, PID/job id, status, metrics path, artifact integrity, budget, and next action.
7. Repair only operational failures and record repair evidence.
8. Write `full/final_report.md`.

## Required Artifacts

Handoff pass requires:

- `exp_handoff.yaml`

Plan pass requires:

- `full/matrix.yaml`

Run pass requires:

- `full/run_monitors.jsonl`
- `full/monitoring_summary.json`

Report pass requires:

- `full/final_report.md`

## Output

Exprun should produce:

- `exprun_state.json`
- `events.jsonl`
- `full/matrix.yaml`
- `full/run_monitors.jsonl`
- `full/monitoring_summary.json`
- `full/final_report.md`
- optional `experiment_results.yaml`