# Bisecting a regression

Give Haystack a version that worked, a version that does not, and a script that
tells the two apart. Haystack checks out real commits from that range in cloud
sandboxes and returns the first bad commit and its clean parent.

## The command

```bash
haystack verify bisect --repo . --good py-1.42.1 --bad py-1.43.0 \
  --predicate ./check.py
```

- `--repo`: local clone or git URL. For a local clone, sandboxes clone its origin remote.
- `--good` and `--bad`: range boundaries specified as a tag, branch, or SHA.
- `--predicate`: the test script described below.
- `--signal`: one-line description of the regression for the results page.
- `--label`: title for the run.
- `--wave-width`: maximum commits probed concurrently while narrowing.

Refs resolve to exact commits before the request leaves your machine, so an
invalid ref fails immediately.

## Predicate contract

The predicate is the interface between your test and the search. It runs with
the repository checkout as its working directory, must bring up its own
dependencies, and must return deterministic results:

- Exit 0: good; behavior is correct at this commit.
- Exit 1: bad; the regression is present.
- Exit 125: untestable; skip this commit and never narrow on it.
- Any other exit: infrastructure failure; never narrow on the error.

## Results

The command immediately prints a run ID and results URL. The results page shows
the live probe timeline, the first bad commit, its clean parent, the predicate
readings on each side, and an independent confirmation probe at the reported
bad revision.

```bash
haystack verify watch
haystack verify status
haystack verify findings
```

A found culprit makes `haystack verify watch` exit 1 on purpose: the search
succeeded and the regression is real. Coding agents can start the same search
with the `verify_bisect` tool exposed by `haystack verify mcp`.

Repositories whose predicate runs directly from a source checkout work
generically. Compiled projects require a repository-specific build recipe.