# Operations — running and reproducing the WP42 laboratory

# Prerequisites (controller)

macOS laptop with Claude Code ≥ 2.1.316 (claude --version), Python 3.12 venv in the repo (uv venv -p 3.12 .venv && uv pip install -p .venv/bin/python pandas numpy openpyxl python-docx python-pptx reportlab matplotlib statsmodels scipy flask pypdf playwright polars pyarrow duckdb xlsxwriter jinja2 markdown pillow jsonschema lifelines pytest), LibreOffice (brew install --cask libreoffice, used to recalculate workbook formulas before evaluation), LaTeX (latexmk).
API key file ~/Desktop/Cluster/secrets/wp42/.env containing ANTHROPIC_API_KEY=… (mode 600). Never commit it.
Hidden oracles in ~/wp42-oracles/<TASK_ID>/ (regenerate with benchmark/scenarios/<TASK_ID>/generate.py --seed <seed> --oracle-root ~/wp42-oracles; seeds are in benchmark/taxonomy/registry.csv). After regeneration, the validators' evaluator fixes (version 1.1) must be re-applied from ~/wp42-oracles/<TASK_ID>/validation/ diffs if evaluate.py is overwritten — generate.py does not write evaluate.py.

# Prerequisites (executor nodes)

For each node in src/wp42/config.py NODES: passwordless SSH alias, Claude Code installed (claude --version, 2.1.314 in the pilot), ~/wp42/.env (API key, mode 600), ~/wp42/venv (same packages as the controller + playwright install chromium), LibreOffice in /Applications, python -m wp42.cli sync-tools to copy the portal package to ~/wp42/tools/wp42.

# Commands

bash

export PYTHONPATH=src
.venv/bin/python -m pytest -q tests                                   # harness unit tests
.venv/bin/python scripts/freeze.py --tasks ACC-01 … RES-01            # freeze manifest (hashes) before a stage
.venv/bin/python scripts/verify_freeze.py                             # exit 1 and list if anything changed
.venv/bin/python -m wp42.cli assign --tasks … --arms A0 A1 A2 A3 A4 --reps 2 --seed 4242 --model claude-opus-5-5 --stage pilot
.venv/bin/python -m wp42.cli run --where "stage='pilot' AND status='assigned'" --parallel 12   # Ctrl-C = graceful stop
.venv/bin/python -m wp42.cli status | ledger
.venv/bin/python -m wp42.cli evaluate --where "status='collected'"   # (re)evaluate + judge
.venv/bin/python -m wp42.cli reset-run --run-ids <id>                 # infra error → rerun (log an amendment)
.venv/bin/python -m wp42.cli kill-all                                 # emergency shutdown on every node
.venv/bin/python -m wp42.cli export --tag pilot                       # data/validated/*.parquet|csv
.venv/bin/python analysis/econometrics/estimate.py --tag pilot        # tables + analysis/derived/estimates_pilot.json
.venv/bin/python analysis/figures/make_figures.py --tag pilot         # vector figures
.venv/bin/python -m wp42.dashboard --serve 8642                       # private dashboard

# Where things are

Raw, immutable: data/raw/wp42.sqlite (store), data/raw/runs/<run_id>/raw_stream.jsonl (+ raw_stream_recovery.jsonl, out/, collection.json, receipt.json, judgments.json).
Validated: data/validated/runs_<tag>.parquet (one row per run with every metric), judgments_<tag>, receipts_<tag>, events_<tag>.
Protocol: protocol/preregistration/{PREREGISTRATION.md,freeze_manifest.json}, protocol/amendments.csv, protocol/ethics/, protocol/power_analysis/.
Scenario validation reports: ~/wp42-oracles/<TASK_ID>/validation/report.md (outside the repo; summarised in the manuscript appendix).

# Known gotchas

timeout does not exist on macOS; claude -p waits 3 s for stdin unless < /dev/null; resume costs are cumulative in total_cost_usd; GUI Apple Events time out over SSH (TCC); a stray /tmp/bisect.py on the laptop shadows the stdlib when Python runs with cwd=/tmp; openpyxl workbooks carry no cached values (hence LibreOffice recalculation on the controller); zsh does not word-split $VAR (list task ids explicitly).

spb/wp42_uqo