exprun

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

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.

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:

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:

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