# Configuration Use an isolated writable root with `python3 harness/rh.py --root PATH ...`. It contains `lanes/NAME/INTAKE.toml`, optional sweep/cadence/outreach TOML files, and runtime JSON/JSONL ledgers. Never use a real lane as a tutorial fixture. See [examples/toy-lane](../examples/toy-lane). | Setting | Meaning | |---|---| | `RH_LAUNCH_RECEIPTS` | Directory of the launcher's `JOB.log.selection.json` receipts. `rh bughunt verdicts` takes a referee's model family from the receipt named after the verdict's folder, not from the referee's self-report. Unset: the self-report is used and flagged. | | `MEM_GUARD_LIMIT_GB` | `harness/tools/mem_guard.py` (launchd, every few seconds on a compute host): kill any user process whose physical footprint passes this, default 8. The window server, agent sessions, the browser, tmux and Apple binaries are spared. | | `MEM_GUARD_JOB_GB` | Cap on one launcher job's processes together. A job's processes are those carrying `RH_JOB=` in their environment (launch.sh sets it on the executor, every worker inherits it) plus the process tree under its pid file in `MEM_GUARD_JOBS_DIR` (default `~/.local/state/research-harness/remote-jobs`). Over the cap the job is stopped whole, a `MEMKILL` line with its peak goes into its `STATUS.md`, the owner is pushed and `MEM_GUARD_TELL` (run on `MEM_GUARD_TELL_HOST` over ssh when set) tells the conductor. Unset: off. macOS ignores `ulimit -v`, so this watcher is the cap. | | `MEM_GUARD_MIN_FREE_PCT` | While free memory (`kern.memorystatus_level`) is under this, stop the largest job, one every `MEM_GUARD_COOLDOWN_S` (default 20). Unset: off. `mem_guard.py --every 3` loops and writes `MEM_GUARD_HEARTBEAT` (default `~/.local/state/mem-guard/heartbeat`) after each pass. | | `LAUNCH_MAX_PEAK_GB` | `launch.sh --host` refuses a job unless the host's memory-guard heartbeat (`LAUNCH_MEMGUARD_HEARTBEAT`, on the host) is under 60 s old and the spec has a line `Peak RSS: N GB` measured with `/usr/bin/time -l`. A declared peak over this (default 8) is refused and belongs on a pod. `FORCE_LAUNCH` does not skip it. | | `MEM_GUARD_TOTAL_GB` | Cap on all unspared processes outside app bundles together; over it, the largest is killed until they fit. Unset: off. | | `HOST_WATCH_NOTIFY` | `harness/tools/host_watch.py` (launchd, every 5 min): push critical memory pressure with the largest processes, resume apps the kernel suspended for swap exhaustion once pressure eases, and report a browser renderer above 90% CPU for an hour with the session that started it. Also `HOST_WATCH_SWAP_GB` (default 16), `HOST_WATCH_SPIN_CPU`, `HOST_WATCH_SPIN_S`. | | `RH_POD_LANES` | Comma-separated eligible pod lane names; empty by default. | | `RH_SELECTION_GATE` | Optional selection package root; defaults to bundled `selection/` beside `harness/`. `~` expands. V2 requires NumPy. | | `RH_POLICY_EXCLUDED` | Explicit legacy evidence-policy exemptions; empty by default. New deployments should keep it empty. The capacity hook also recognizes these exemptions. | | `RH_REAP_EXCLUDED` | Comma-separated protected pod names or lane names; empty by default. | | `RH_ROLES_FILE` | Local generated roles/routes JSON; default `.runtime/roles.json`. | | `RH_AGENT_ALERTS` | Agent alert JSONL queue; default `.runtime/agent-alerts.jsonl`. | | `RH_NOTIFY_COMMAND` | Optional pod/provider notification executable and quoted arguments; no service supplied. | | `RH_CONTACTS` | Private contact file; default `.runtime/contacts.json`. Rows take a `name` and an optional `language` code such as `pt`. See [outreach](outreach.md). | | `RH_VOICE_COMMAND`, `RH_SCIENCE_CHECK_COMMAND` | Separately supplied lint commands. Missing required commands refuse lint. | | `RH_TRASH_COMMAND` | Reversible disposal adapter; default `/usr/bin/trash`. Linux deployments must supply a compatible Trash command. There is no destructive fallback. | | `RH_SSH_KEY`, `RH_KNOWN_HOSTS` | SSH identity and strict known-hosts file; defaults `.runtime/ssh/id_ed25519` and `.runtime/ssh/known_hosts`; set explicitly for an existing SSH setup. | | `RH_GH` | GitHub CLI executable used by metadata discovery; default `gh`. | | `RH_PAPER_CACHE`, `RH_PAPER_CACHE_TTL_DAYS`, `RH_PAPER_CITING_TTL_DAYS` | Paper-lookup cache directory (default `.runtime/paper-cache`) and TTLs: 30 days for a search, 7 for a citation list, because a stale citation list can hide the paper that scooped a result last week. Point every lane at one directory to share both the cache and the quota. | | `RH_PAPER_CONTACT` | Address sent to OpenAlex's and Crossref's polite pools, as a `mailto` parameter and in the User-Agent; empty by default, and a contact address is the operator's to supply, never this repository's. | | `RH_OPENALEX_KEY`, `RH_SEMANTIC_SCHOLAR_KEY` | Optional API keys. The whole chain works with neither: Europe PMC, arXiv and Crossref need no key and Semantic Scholar answers keyless at a lower rate. OpenAlex takes its key as a URL parameter, Semantic Scholar as an `x-api-key` header, never in the URL. | | `RH_PAPER__PER_DAY` | Sustained requests a day for one source (`OPENALEX`, `SEMANTICSCHOLAR`, `EUROPEPMC`, `ARXIV`, `CROSSREF`), spread over the day by a token bucket in the cache directory and shared by every lane and every parallel job. Defaults are the free limits: OpenAlex 1,000, Semantic Scholar 5,000, Europe PMC and Crossref 20,000, arXiv one request every three seconds. A source with no tokens left is skipped, not waited for. Raise one only to match a key you actually hold. | | `RH_XCAPTURE_ROOT` | Private root holding `x_capture/KEY.jsonl`; generator default is current directory. | | `RH_EVIDENCE_ROOT` | Explicit harness root for leaderboard ingestion. No home/archive discovery. | | `MODEL_REVIEW_ROOT`, `MODEL_DRAFTS_LOG` | Explicit private review receipt tree and draft-outcome ledger. | | `MODEL_STATE`, `MODEL_LEDGER`, `MODEL_OVERRIDES` | Private scoring state directory (default `.runtime/leaderboard`), optional ledger path and exclusions config. | | `LAUNCH_ARTIFACT_DIR` | Standalone job specs/logs; default `$PWD/.runtime/jobs` after entering WORKDIR. A sweep passes its own spec path. | | `LAUNCH_STATE`, `LAUNCH_SELECTOR`, `LAUNCH_CODEX` | Job registry (default `$PWD/.runtime/job-registry`), optional selector override and Codex executable. | | `LAUNCH_MAX_CONCURRENT`, `LAUNCH_TMUX`, `LAUNCH_GUARD` | Default four other live Codex `job-*` tmux sessions; games/open-source/bio are exempt. The guard counts sessions, excludes dead/known non-Codex routes, and refuses an unreadable count. Allowance limits are enforced by the wrapper. | | `LAUNCH_URGENT` | Nonblank reason logged by the launcher; Codex receives `-c service_tier=priority`. Forwarded to remote executors with canonical `RSTACK_LANE`; concurrency still applies. | | `LAUNCH_ROLE`, `LAUNCH_EFFORT` | Role and effort; fixed model overrides also require a reason. | | `LAUNCH_YIELD_LEDGER`, `LAUNCH_NOTIFY_COMMAND` | After every job the launcher checks the two hard-rule lines (`You asked: ...` first in `STATUS.md`, `Shipped: ...` first in `REPORT.md`), writes `lint restate-ask=N shipped-line=N` to the job log, and appends one row per job to the yield ledger (default `$PWD/.runtime/job-yield.jsonl`). A job missing either line is reported through `LAUNCH_NOTIFY_COMMAND`, called with one message argument, if one is set. The lint reports and never changes the job's exit status, and a missing or broken notifier is not an error: a finished job must not be turned into a failed one by its own bookkeeping. | | `LAUNCH_IDEA`, `LAUNCH_IDEA_ROOT` | Optional promoted-idea admission check before execution. Requires an `rh` command on PATH. | | `LAUNCH_ROUND`, `LAUNCH_FAMILY`, `LAUNCH_GENERATOR`, `LAUNCH_PARAMS`, `LAUNCH_SCORER`, `LAUNCH_HYPOTHESIS`, `LAUNCH_NEW_EVIDENCE` | Setting `LAUNCH_ROUND` puts the job through the round gate ([`harness/tools/rounds.py`](../harness/tools/rounds.py)) before the registry write, the log or any spend: it refuses a repeated method, a reopened dead end, a dry streak and an unread KB, and otherwise opens the round in the lane's `ROUNDS.jsonl`. The repeat check is a hash of `(generator, params, scorer)`, so renaming the family does not get past it, and `LAUNCH_HYPOTHESIS` is what lets a deliberate repeat through. A round cannot start while the previous one has no logged outcome, which is what makes the ledger a precondition rather than a courtesy. A refusal exits 78 and runs nothing. Without `LAUNCH_ROUND` the job behaves exactly as before. The gate also asserts the lane's `SPEC.json` ([`harness/tools/spec.py`](../harness/tools/spec.py)): the challenge capture must match its pinned sha256, every string the lane is scored against must appear in that capture byte for byte, declared lengths must match, the size cap must be declared and present, and every ranking condition must be scored or excused with a reason. A lane with no external challenge sets `"challenge": null` with a reason and still declares its ranking. No `SPEC.json` is a refusal, for every lane. `spec.py --lane L diff` re-reads the live page and reports any scored string that has left it; that is the one step with network and is meant to be scheduled, not run by a worker. | | `LAUNCH_HOST` (or `--host HOST`) | Run the executor on another machine over ssh; empty means here. `HOST` is an ssh alias, validated before it reaches an ssh argv. The work dir must exist at the **same absolute path** there, or the run refuses rather than landing in the remote `$HOME`. Admission, the word cap, the registry, model selection, the prompt and the log stay on the controller. | | `LAUNCH_SSH`, `LAUNCH_REMOTE_EXECUTOR`, `LAUNCH_PULL_MAX_SIZE` | With `--host`: the ssh command (default `ssh`), the remote `agent_executor.py` (default `$HOME/.local/share/research-harness/agent_executor.py`, expanded on the host) and the cap on each pulled-back file (default `4m`). After every attempt the heavy outputs stay on the host and only `STATUS.md`, `REPORT.md`, `PLAN.md`, `RESULTS.jsonl`, `*.selection.json` and the job's `.last.md` come back, so status reads here as it did before. A failed pull is logged and does not fail the run. | | `EVENT_WATCH_CONF`, `EVENT_WATCH_STATE`, `EVENT_WATCH_NOTIFY` | Watch rules (default `.runtime/event-watch/config`), cursor/event state (default `.runtime/event-watch/state`) and optional notification executable. | | `POLL_GUARD_STATE` | Private hook fingerprint directory; default `.runtime/poll-guard`. | | `CS_BASE`, `CS_BIN`, `CS_STATE`, `CS_AUTO_READ` | Optional daemon URL, CLI, cookie directory (default `.runtime/cs`) and path-separated auto-readable roots. Auto-read roots default to empty. No port is assumed when the URL is unset: the CLI is asked. | | `CS_HOST`, `CS_REMOTE_BIN`, `CS_TUNNEL_PORT` | Drive the daemon on another machine (an ssh alias) over a tunnel, for science whose data lives there. The auto-readable roots are then checked on that machine, and a prompt for a path missing there is held. | All data paths default to the current workspace/runtime, not a personal HOME. Absolute data paths are accepted when a caller supplies a documented setting, CLI path or lane configuration. Standard system executable paths such as `/usr/bin/ssh` and `/usr/bin/trash` are executable dependencies, not data discovery. Provider CLIs manage their own login/config outside the harness; choose HOME and provider-specific config directories before invocation. Judgment roles are `review`, `judge`, `audit`, `taste`, `design`, and `ideation`; `judge`/`audit` use `review` and `design` uses `taste` unless an explicit row exists. Pass `--role ROLE --made-by MODEL` (or `LAUNCH_MADE_BY`); the maker is required for review/judge/audit, and the first eligible model from another family is selected. Judgment jobs follow the selected model's CLI route automatically; their specs name the role and must contain no model names. A judgment `--model` pin requires `--model-override 'Ricardo: REASON'` (or `MODEL_OVERRIDE_REASON`), while family independence and exclusions still apply. Accepted overrides append role/model/reason/job/utc to `RH_MODEL_OVERRIDE_LOG` (default `model-overrides.jsonl` beside `RH_ROLES_FILE`); other roles retain their explicit-executor behavior. | Additional setting | Meaning | |---|---| | `AGENT_BACKEND` (or `LAUNCH_BACKEND`) | `codex` (default) or `claude`; invalid values refuse. `tools/launch.sh` reads either name; both set to different values refuse. The role comes from `LAUNCH_ROLE` (default `batch`). Judgment roles use the selected model's CLI; other roles refuse when their top model has no compatible route for the chosen CLI. | | `LAUNCH_CLAUDE`, `LAUNCH_CLAUDE_BUDGET` | Claude executable and per-run dollar cap (default `1.00`); no automatic Claude retries. | | `LAUNCH_CLAUDE_TOOLS`, `LAUNCH_TIMEOUT_SECONDS` | Claude jobs from `tools/launch.sh`: the `--allowedTools` list (default `Read,Write,Edit`; a job that runs its own code adds `Bash` and says so) and the wall-clock cap in whole seconds (default `5400`; `0` means none). The CLI has no turn limit, so spend and the clock are the two bounds. | | `LAUNCH_CODEX_SANDBOX` | How much a codex job may touch: `read-only`, `workspace-write` (the default), `danger-full-access`, or `bypass`. The first three become `--sandbox MODE`; `bypass` is the single `--dangerously-bypass-approvals-and-sandbox` flag, which turns off approvals and the sandbox together and is not a sandbox level. An unknown value refuses rather than being passed through. The default is deliberate: a job whose transcript is written outside its work dir needs a wider mode, and the host says so once rather than the tool shipping with the sandbox off. | | `RH_POD_GATE_CONFIG`, `RH_POD_GATE_AUDIT` | Capacity policy (default `$RH_ROOT/pod-gate.json`) and audit log (default `$RH_ROOT/.runtime/pod-gate-audit.jsonl`). | | `RH_HARVEST_STATE` | Snapshot state override; default `/.harvest-state`. | | `RH_ENV_FILE` | Host env file of `KEY=VALUE` lines read once at import; default `$XDG_CONFIG_HOME/research-harness/env` (else `~/.config/...`). The real environment wins. Keep host paths here, never in the repo. See [harness sync](harness-sync.md). | | `RH_DISK_FLOOR_BYTES` | Free bytes required before a full harvest snapshot; default 12 GB. | | `RH_OWNER_ALIASES` | Comma-separated older names for the operator, accepted as an idea `source_type` and as a lint-exception `decided_by`; empty by default. | | `RH_INTAKE_LANES` | Comma-separated lanes the scheduled intake runs, in order; default every lane with an `INTAKE.toml`, alphabetically. | | `RH_OUTREACH_ROOT` | Approval hook's ledger root; default repo `.runtime`. | | `RH_ANSWERS_FILE` | Optional local answers file; default `.runtime/ANSWERS.md`; CLI `--answers-file` overrides it. | | `RH_TRANSCRIPTS_ROOT` | Explicit Claude project-transcript tree for session-model detection; disabled when unset. | | `RH_CS_DB_ROOT` | Explicit daemon data root containing `orgs/*/operon-cli.db`; disabled when unset. | | `RH_REMOTE_RUNNER` | Deployed runner path on a pod; default relative `research-harness/pod/runner.py`; quote-safe in the SSH shell command. | | `RH_RUNNER_SOCKET` | Local pod-runner socket; default `.runtime/rh-pod-runner.sock`; CLI `--socket` overrides it. | A sweep worker cannot reach X and cannot download. Two asks exist so that is not a dead end. A search worker may write one `X QUERY : ` line in its report; the sweep files it in the lane's `X_REQUESTS.jsonl`, adds it to `X_QUERIES.txt` for the general session's browser step, and one `rh intake x-search` with that query clears it. The receipt rule does not move: a lead with no X search is still incomplete and still unpromotable, so the ask is a way to get the search run, not a substitute for it. While the ask is open, that lead's receipt is pending rather than failed: if its X source is `blocked` and every other source is complete, the sweep is delivered and the lead stays queued (a SURVIVED one goes back in the queue), so one fresh lead does not fail every pass until someone runs its query. A wrong X entry, or any other incomplete source, still fails. For data, [`inputs.py`](../harness/tools/inputs.py) stages a public file once, by hash, and the worker prompt now lists what is staged and how to get a path offline; a worker that needs an unstaged file says `BLOCKED: need from ` and a person stages it. Before 11-07 neither was reachable from a sweep: a lead found during a run could never have its X query asked, and no prompt mentioned staged inputs at all. `SWEEP.toml`'s `host` (default empty, meaning here) is the machine a lane's workers run on, an ssh alias validated in the same shape `launch.sh` validates. It reaches the launcher as `LAUNCH_HOST`, so the work dir must exist at the same absolute path there. An explicit `LAUNCH_HOST` in the environment wins over it, which is how one run moves without editing the lane. Before 11-07 the only way to say where a lane's work ran was a flag on each launch. `SWEEP.toml`'s `min_free_gib` (default 30) is the floor on **the machine that runs the workers**: the lane's `host` when it has one, otherwise the controller. `controller_min_free_gib` (default 2) is the controller's own floor, because specs, logs, receipts and pulled-back status files land there even when the work does not. If the host's disk cannot be read, the sweep refuses rather than assuming it has room. Before 11-07 the floor always measured the controller, so moving the workers to a second machine refused every sweep on a disk that was not doing the work. On a host where the work dir does not exist yet, the floor is measured at its nearest existing parent, because the sweep's mirror creates it right after this check (11-10). `SWEEP.toml`'s `worker_path` (default empty) lists absolute directories put first on the worker's `PATH`, both here and on the host (as `LAUNCH_REMOTE_PATH`). A lane whose checkers need a venv names its `bin` directory there, so a bare `python3` in any stage is that interpreter. 11-10: a math kill test was blocked on a missing `flint` module because the m5 worker ran the system `python3`. Capacity policy uses `mode = audit|enforce` and `enforce_lanes` drawn from `RH_POD_LANES`. Hooks are not installed automatically. Set `RH_ROOT` explicitly when using them in a deployment. The launcher stays synchronous so a sweep can bound its process group. Codex capacity retries are limited to five attempts. Claude has one attempt so a retry cannot reset its dollar cap. Codex uses workspace-write; Claude uses acceptEdits and preapproved file tools, without an OS sandbox from this runner. External access and credentials belong to the caller. No watchdog is installed. Launchd templates under [harness/templates](../harness/templates) contain `@...@` placeholders. Render them into your own scheduler directory, choose Python and root paths, and inspect before loading. Template files are not active jobs. Linux users can schedule the same commands with their existing scheduler. Linux/container system files are the only absolute data defaults. They are named configuration settings, rather than private-machine locations: `RH_MEMINFO` defaults to `/proc/meminfo`; `RH_CGROUP_ROOT` defaults to `/sys/fs/cgroup`; remote probes use `RH_REMOTE_CGROUP_ROOT` (default `/sys/fs/cgroup`) and `RH_REMOTE_UPTIME` (default `/proc/uptime`). `RH_POD_WORKSPACE` defaults to the container contract `/workspace` and can also be overridden with `--workspace`. Harvest's `/workspace/` check is a remote-path allowlist, not discovery of local files. `MODEL_MINE_OUT` defaults to `.runtime/model-mine` and `--out` overrides it. Missing evidence fails directly, without probing a made-up absolute sentinel file. New lanes created with `rh lane new` also contain `LANE.json` (frozen problem, metric, deadline, test/bar, submission rules and access declarations) and `SELECTION.json` (v2 policy). Lint checks their hashes and lane limits. A 24-hour setup grace applies only while workers are disabled and no idea, intake, sweep or sealed-scoring history exists. Afterwards the ordinary reading, queue and delivery checks apply. `workers_enabled=false` refuses real sweeps while preserving previews. These local hashes detect accidental edits; they are not an authenticated audit service. Lane registry entries (`RH_LANE_REGISTRY` or `lanes/REGISTRY.json`) may declare `"x": false` to bar that lane's drafts from X review. The optional field must be a boolean and is independent of lifecycle status. Aliases resolve to the same policy; `x:true` cannot override an explicit no-X rule in the canonical or alias RULES.md. Encode prose restrictions with `x:false` so consumers need no natural-language inference.