Verifying an install

~/.saphan/bin/saphan version # per-user installs
saphan version # package / installer installs (already on PATH)

It is version, not --version, and the CLI and the agent disagree. Measured:

One install puts these binaries side by side and they answer the same question in two languages. The first thing anyone does after installing is ask what they got, and the spelling most people try first is the one that fails on the CLI. Use version.

Every scripted path verifies checksums before anything lands: install.sh checks each binary against SHA256SUMS and refuses on mismatch with nothing installed; the macOS installer checks its payload digest before extraction. For what the engine itself re-checks after delivery to a runner — digest and version re-resolved on the machine that will execute — see Runners: what happens during a run.

version proves the stamp, not the behaviour

The commit in saphan version is written into the binary by the linker, from git, at the moment of linking. Nothing in that chain binds what the file does to what it says, so the stamp is evidence that a build happened at that commit — not that the running code is that commit's code.

This is not theoretical. An install has been observed producing a binary that reported the correct commit and still behaved as the code from before a fix that commit contained; a second install, from the same unchanged tree, produced a correct one. The root cause was not established. What the incident settles is the predicate, not the mechanism: a version check passed on a defective binary, so a version check cannot be what closes an upgrade.

Verify an install two ways, both cheap:

By content — the bytes you shipped are the bytes now installed:

shasum -a 256 ~/.saphan/dist/<os>-<arch>/saphan # on the build box
ssh <host> 'sha256sum "$HOME/.saphan/bin/saphan"' # on the machine

Equal digests mean the delivery is honest end to end. This is strictly stronger than the stamp, because it pins the content rather than a string inside it.

By behaviour — exercise the thing you upgraded for. Whatever the change was, there is some verb whose outcome differs before and after it; run that one. A proc spawn costs no model tokens and is the cheapest carrier for such a check:

saphan run --workspace <workspace> --stream <fresh-slug> --backend proc \
 --actor <you> --binary /usr/bin/true --profile execute \
 --workdir <fresh empty dir> --wall-clock 1m

Two rules make such a probe mean something. Use a fresh stream slug and a fresh empty workdir — a reused one carries channel files and prior rows that change the answer for reasons unrelated to the upgrade. And know which inputs make the old behaviour reachable at all: a probe that omits the flag the defect needed will pass on the old binary and the new one alike, for the same reason, and prove nothing. If you cannot state what the probe would print on the old binary, it is not yet a check.