Verify a fix

twin verify rebuilds the reporter’s environment as replay does, applies your fix, reruns the command and reports whether the captured failure is gone. With --patch nothing has to be pushed first.

Two ways to supply the fix

A local patch

Write the fix in your clone, export it as a unified diff, and verify it:

git diff > fix.patch
twin verify twin-capsule.json --patch fix.patch

The sandbox checks out the capsule’s commit, applies the reporter’s working-tree diff, then applies your patch with git apply. Make the patch against the capsule’s commit.

A pushed commit

To check a fix branch or a PR head, pass its full commit SHA as --ref. --repo points at a fork:

twin verify twin-capsule.json --ref <full-commit-sha>
twin verify twin-capsule.json --ref "$(git rev-parse HEAD)" --repo https://github.com/you/project

With --ref, the capsule’s working-tree diff is not applied: the commit is taken as the whole tree.

The capsule can be a file path or an https:// URL. Pass exactly one of --patch and --ref, or twin exits with status 2. The capsule must record a failure; otherwise twin stops with the capsule recorded a passing run; there is no failure to verify a fix for.

The echarts fix, verified before pushing

The run recorded for the case study. It predates the baseline run described below, which adds one more machine.

Verify on solari (machine AkhV_ntXHJrec7VZ…, run e179d260)
  ✓ prepare workspace  0.3s
  ✓ install node 22.23.3  2.1s
  ✓ check out 984bf46b2f90  4.2s
  ✓ upload candidate fix  0.0s
  ✓ apply candidate fix  0.3s
  ✓ install npm 10.9.9  4.7s
  ✓ install dependencies (npm ci)  46.8s

Attempts
  1  PASS  8.1s
  2  PASS  1.7s
  expected  FAIL exit1:0aee0834ac9c4d2d

FIXED: the command passes in the reporter's environment with the fix applied.

The run without the fix comes first

Before it applies your fix, twin verify runs the command once on its own machine, exactly as a replay of the capsule would, including pinning npm packages to the capsule’s versions. If that run does not fail the way the capsule recorded, the verdict is INCONCLUSIVE and the fix is never tried, because a pass with the fix would prove nothing.

The usual reason is a failure that replay cannot copy: the OS, a variable recorded by name only, or a package manager other than npm. Check the Notes, or run twin bisect against a passing capsule.

INCONCLUSIVE: the failure did not reproduce without the fix (it passed), so the fix cannot be verified. Replay installs from the lockfile; for a failure that needs freshly resolved dependency versions, use twin bisect.

The baseline run costs one more machine and about as long as a replay.

Fixes that change dependencies

The capsule’s packages are pinned after the fix is applied and its dependencies are installed. A package that the fix names in package.json, through an overrides entry or a changed range, keeps the version the fix resolves. That lets a fix like this one verify as FIXED:

"overrides": { "jsdom": { "lru-cache": "^11.3.2" } }

Every other package is still pinned to the capsule, so a patch that does not touch the cause reports STILL FAILING. The lru-cache case study shows both results.

Verdicts

Verdict	Meaning	Exit
FIXED	The command passes in the reporter’s environment with the fix applied.	0
STILL FAILING	The fix does not change the captured failure.	1
DIFFERENT FAILURE	With the fix it still fails, but differently.	1
FLAKY	Attempts disagreed with each other.	1
INCONCLUSIVE	The failure did not reproduce without the fix, setup failed (does the fix apply?) or an attempt timed out.	1

A patch that does not apply fails the apply candidate fix step. The run is INCONCLUSIVE and twin prints the error from git apply.

Options

Option	Default	What it does
--patch <file>		Unified diff applied on top of the capsule’s tree.
--ref <sha>		Check out this commit instead (for example a fix branch).
--repo <url>	the capsule’s remote	Clone from here (forks); use with --ref.
--attempts <n>	3	Runs of the command.
--no-pin	off	Do not install the capsule’s recorded npm package versions over the lockfile install.
--env <NAME=value>	none	Value for a variable the capsule recorded by name only. Repeatable.
--timeout <minutes>	15	Maximum time per attempt.
-v, --verbose	off	Stream the sandbox’s output.
--json	off	Machine-readable report on stdout. The verdict field uses replay’s names, so FIXED is not-reproduced.
--comment <file>		Also write a Markdown pull request comment to <file>.

Exit status: 0 fixed, 1 otherwise, 2 usage error.

Note

FIXED means the captured command passes in the captured environment. It says nothing about other tests or other environments.

A comment for the pull request

--comment <file> also writes the verdict as Markdown that you can post on a PR:

twin verify https://github.com/user-attachments/files/<id>/twin-capsule.json \
  --ref "$(git rev-parse HEAD)" --comment verdict.md
gh pr comment --body-file verdict.md

The comment has a headline such as ✅ FIXED in the reporter's environment, a table with the command, the reporter’s environment, the checked commit, the attempts that passed and a link to the capsule, and the full log in a collapsed section. It starts with a hidden <!-- twin-verify verdict=… --> marker so a CI job can find and update its own comment.

In CI

The GitHub Action runs twin verify <capsule> --ref <PR head sha> --repo <PR head repo> on pull requests that close an issue with a capsule attached, and comments the verdict on the PR.