What a Run Can Prove: From Commit to Evidence

OpenResearch treats a run as more than a process that eventually exits. This chapter follows the run from a recorded experiment commit through source staging, backend state, supervision, terminal outcome, and log inspection. The practical question is what a run can actually prove: it can establish which source was submitted and what the execution channel recorded, but a “done” status by itself says almost nothing about whether the resulting claim is interpretable.

That distinction matters because research tools often compress an execution into a colored status and a number. OpenResearch keeps more of the lifecycle visible. A run belongs to an experiment and project, carries a backend descriptor and command, records a commit, preserves output, and can be reattached to a supervisor after the initiating service restarts. These records make a result inspectable. They do not turn every printed metric into valid science.

From a branch to a supervised run

The first important transition happens before a provider sees any code. OpenResearch resolves the experiment branch's recorded commit rather than reading whatever happens to be in the agent's worktree. It archives that commit, computes a SHA-256 digest, stores the archive under a content-addressed name, and attaches the digest, path, and size to the backend descriptor. The run therefore has two identities: the Git revision that defines the source and the archive identity used to transport that source.

This is a stronger boundary than asking a remote machine to clone a mutable branch. A branch can move after an agent launches a job. A worktree can contain uncommitted files. A remote clone can resolve a different ref or depend on network state at the moment of cloning. The source snapshot avoids those ambiguities by making the submitted payload a durable object associated with the recorded commit. If a later supervisor needs to recover the run, it can use the descriptor and validate the archive's digest rather than trusting the current checkout.

The local backend makes the boundary especially visible. It extracts the committed snapshot into an isolated run directory and executes the fixed command there, not directly inside the agent's worktree. The run directory carries the launcher, merged output, process identifier, and eventual exit code. Remote adapters use their own transport, but the same principle applies: the provider receives the staged snapshot and starts the recorded command from that extracted source. The boundary is about source identity, not about making every runtime environment identical.

Once the source is staged, the run enters the local lifecycle. A newly submitted run is starting: the system has reserved and submitted it, but it has not necessarily observed the backend actually running. It becomes running when execution is confirmed. It can then reach a terminal outcome such as done, failed, or cancelled. Terminal outcomes are treated as immutable. A later status update cannot quietly turn a failed historical run into a successful one, and a new interpretation should not overwrite the execution outcome.

The starting state is not a cosmetic prelude.