Concepts

Three gates, not an exit code.

Renest counts a restore as successful only when it clears three gates: the machine passes a pre-flight check, the application starts, and the environment produces real output (an image, or a non-empty training artifact). A clean exit from renest restore already includes the app starting and the packed run producing output, unless you pass --skip-launch or the nest carries no recipe to run again; a clean exit from the escape hatch, restore.sh, proves only that every file came back and matched its recorded fingerprint.

A clean exit proves only what the tool actually checked before it exited

Every restore checks one thing without exception: every file came back and matched its recorded fingerprint, byte for byte. That is the part Renest guarantees. What else a clean exit (exit code 0) proves depends on which tool you ran:

• renest restore exits 0 only after the application has started and, when the nest carries the recipe of the run that worked, run it again and produced output. Two exceptions: with --skip-launch it stops after the files and dependencies, and a nest with no recipe says plainly that nothing was drawn.
• The escape hatch, restore.sh, never starts the application. Its exit 0 proves the files and dependencies came back, and nothing more.

The file check alone is not the question you actually care about. An environment can verify perfectly and still be dead on this particular machine: a CPU missing an instruction set, a driver too old for the CUDA build inside the lock, a native library the image never shipped. The bytes are faithful; the machine can't run them. Treating the exit code as the verdict would mean calling that a success. We don't. A rebuild is judged at three gates, and apart from the two exceptions above, renest restore clears all three before it exits cleanly.

The pre-flight check refuses an unsuitable machine before anything is downloaded

Before fetching anything, renest restore compares this machine against what the nest records: the GPU driver against the CUDA release the lock actually needs, the CPU instruction set, the chip family, and room on disk. renest doctor given the nest's manifest runs the machine side of this on its own; renest restore --plan runs the checks, says what the rebuild would do, and stops before a single byte is fetched. The disk check does not just read the free-space figure — it actually writes, because on a quota-backed network volume the figure can say "plenty" while the disk itself is full. The host-side rules came out of machines that failed in the field, not out of a spec sheet.

When the pre-flight check refuses a machine, that is not a failed restore. It is the failure you were going to have later, delivered before the download and before the install. The refusal names what didn't match, so the fix is "pick a machine with a newer driver", not an afternoon of archaeology.

The application has to start on this machine

The environment isn't rebuilt until the thing you rebuilt it for actually starts. After the files and dependencies are in place, renest restore starts it: for an image workflow, ComfyUI is launched as a separate process and has to answer; for a fine-tuning setup, the training run is started. This gate exists because bytes can be perfect while the environment is still wrong in a way no file comparison can see — a library that belongs to the operating system, say — and starting the application is the cheapest honest test there is. If it fails to start, the report says why, reading the application's own log for a missing system library first.

The escape hatch, restore.sh, stops after the byte check and never starts the application. Starting it and judging the result is the job of the renest command-line tool.

The rebuilt environment has to produce real output

The last gate is the one the first two exist for. When a nest carries the workflow recipe of the run that worked, the restore submits that same run again and insists something comes out. For a fine-tuning setup, the run has to finish as it was packed to, and when the nest names the file the run produces, that file has to appear — some training tools exit cleanly without doing the work, which is why the nest names it. Not a green checkmark on a page — an actual file that exists because the environment did its job.

When there is nothing confirmed to reproduce — the nest carries no recipe, or no record of the recipe ever having produced anything — the restore says plainly that nothing was drawn, rather than letting "the app answered" read like a render.

One boundary, stated plainly: this gate asks whether output exists, not whether it is bit-for-bit identical to the original. Files are guaranteed byte for byte; pixels are not — floating-point behaviour differs across GPU models, and we won't promise what hardware doesn't.

A rebuild that exits cleanly and produces nothing counts as a failure

This is the part that keeps the other gates honest. When we measure ourselves, a run that verified every byte, exited 0, and then produced nothing is counted as a failure — a false success, the worst kind, because it's the kind that teaches you to stop checking. A pre-flight refusal on an incompatible machine is kept in a column of its own; it did its job. The rebuild that said "done" and wasn't lands in the failure count.

An exit code is a claim the software makes about itself. An image on disk is a fact the environment produced. We built the product to be judged by the second.