Blind spots

stoop sees files. Here is everything it can't see, and what covers each gap.

A peregrine on a dead branch, half lost in valley fog.

The network

A response from a server never shows up as a file read. So a run that connects out is not recorded, and stoop says where it connected:

stoop: not recorded: it used the network (connect to 192.168.64.1:53), whose results a file trace cannot see; cover it with --probe, or pass --allow-network to record it anyway

Connections to local services (a database on a Unix socket or localhost) are treated the same way. You have two ways to cover it:

--probe CMD

Tell stoop how to check the external thing. The probe's output is hashed into the proof and must match before a skip. It runs before the command and again after, and if it changed in between, nothing is recorded.

$ stoop run --probe 'curl -s https://example.com | sha256sum' \
    -- sh -c 'curl -s https://example.com > page.html'
stoop: run sh-c98f8f9c8fef6d65: no proof yet
stoop: recorded 71 inputs for sh-c98f8f9c8fef6d65
$ stoop run --probe 'curl -s https://example.com | sha256sum' \
    -- sh -c 'curl -s https://example.com > page.html'
stoop: skip sh-c98f8f9c8fef6d65: 71 inputs unchanged since 0s ago (100ms)

Good probes are cheap and exact: a lockfile hash from a registry, git ls-remote for a dependency's branch, a schema version from a migration table.

--allow-network
Record it anyway. You are saying the network can't change the result, for example a download whose content is already pinned by a checksum the command verifies.

The clock and randomness

A test that depends on today's date, or on a random seed, reads nothing that a trace can see. Two settings bound how long that can hide:

  • Expiry. A proof stops counting after 7 days by default. --max-age changes that; shorter is safer.
  • The nightly full run. STOOP_FULL=1 never skips and still records, so a scheduled run re-proves everything. See the recipe.

Flaky tests stay flaky. If one passes once, stoop records that pass. The determinism check on the roadmap is aimed at this.

Services outside the process tree

If a command depends on something it doesn't open itself, such as a daemon that reads files on its behalf, those reads are invisible. Cover the daemon's state with a probe, or don't wrap that step.

Output outside the repository

stoop checks that what a run wrote inside the repository is still there. It doesn't track output written elsewhere. A step whose whole job is to produce files outside the repository (publishing, deploying, filling a shared cache) shouldn't be wrapped.

Reading .git

A command that reads .git could depend on history, which a working-tree comparison can't see. Such runs aren't recorded. If the read can't change the result, add .git to .stoopignore.

Platforms

Tracing needs Linux on x86-64 or arm64. Elsewhere stoop runs the command untraced and records nothing. Programs that use io_uring for file access are told it is unavailable (ENOSYS) so they fall back to calls the tracer can see; Node, for one, handles this.