Concepts

The UI and on-disk metadata use this hierarchy, coarse to fine:

Run
└── Search
    └── Candidate
        └── Trial
            └── Replicate

• Problem: reusable definition under problems/<id>/.
• Run: one invocation of hillclimb. A single-problem run contains one search; a suite run contains one search per suite entry.
• Search: one search worker (engine process) exploring one problem.
• Candidate: an immutable code artifact produced by an operator. Any change to the code — however small — is a new candidate with a new id.
• Trial: one parameter set of a candidate's code (params). A candidate that declares no tunable parameters has exactly one trial; a tuned candidate has several, and its score is the best trial's.
• Replicate: one seeded execution of a trial. A trial's score is the median of its replicates, so seed variance is measured, never climbed.

hillclimb watch opens on the Runs screen. Metadata carries schema_version: 2; directories from the pre-v2 flat layout are ignored.

The four operators

Agents take turns as operators: draft a new approach, debug one that crashed, improve the best scorer so far, ensemble the survivors at the end. Every new candidate runs through your verifier, and the best solution.py is kept in the search's best/ folder.

Candidate statuses

Candidate statuses separate correctness from executability: passing means the verifier and tests succeeded, failing means the verifier succeeded and the suite completed with failing tests, and buggy means execution crashed, timed out, or broke the evaluation contract. Failing and buggy candidates may be debugged, but only passing candidates can rank, tune, reach holdout, or ship.

Search states

running (fresh heartbeat + live pid) · parked (rate limit; resume later) · stopped (user stop/kill) · done · failed (see last_error) · crashed (derived: stale heartbeat or dead pid) · unknown (no status.json yet).

Exit code 2 from run/resume means the search parked or was stopped — resume it.