# FAQ

## Why did my run exit 2 when the tests pass?

Exit 2 is `HARNESS BROKEN`. Read the reason on stdout. The two common causes: the `test` command fails on pristine source in `root` (often a wrong `root`, or a command that only works from another directory), or the control's `old` text no longer matches the file. Run the `test` command by hand from `root` first. If stdout is empty, the 2 came from Go's flag parser: check the flags ([exit codes](output.md#exit-codes)).

## Is a COULD_NOT_MUTATE line a failure?

Treat it as one. The guard it names was never tested in this run, so the run says nothing about it. The usual cause is drift: the code changed and the spec's `old` text did not. Update the spec in the same change as the code. muhar prints `NOTE: could-not-mutate is NOT a clean gate` whenever one appears.

## What happens to a mutant that does not compile?

It fails the suite, so muhar reports it `CAUGHT`. For Go, a typo in `new` therefore looks like a caught mutant. Check that each `new` compiles when you write it — temporarily apply it and build. A separate unviable verdict is planned ([assay#2639](https://github.com/medici-finance/assay/issues/2639)).

## I pressed Ctrl-C. Is my source tree clean?

Not necessarily. An interrupt exits 130 straight away, without restoring the file under test in a sequential run, and without removing worker copies with `-j` above 1. Run `git status` and restore any mutated file; remove leftover `muhar-*` directories from the temp directory. Details and the tracking issue: [Signals and cleanup](internals.md#signals).

## Does muhar work outside Go?

Yes. muhar edits text and runs any `sh -c` command. The examples on [Writing good mutants](writing-mutants.md) cover JSON, shell and YAML. The Go-specific parts — the per-run build cache and the `go.mod` rewrite — only take effect for Go trees and are harmless elsewhere.

## Why is -j 0 only 2 workers on my 32-core runner?

Each worker holds a copy of the tree and runs its own suite, so memory grows with workers. The cap keeps `-j 0` safe on runners whose memory does not scale with cores. Pass an explicit `-j` to go higher ([CLI reference](cli.md#j-cap)).

## Can I use absolute file paths?

With `-j 1`, yes. With `-j` above 1 or `-j 0`, no: an absolute path points at the original tree, not the worker's copy, and produces wrong verdicts ([spec reference](spec.md#absolute-paths)).

## Can mutations depend on each other?

No. Each mutation is planted on pristine source and restored before the next, so every verdict is about one edit alone. To test a combination, write it as one mutation whose `old` and `new` span both changes, if they are adjacent, or as a separate spec.

## How do I run only the mutations for my change?

Not yet. Today every mutation in the spec runs. A diff-scoped mode is planned ([assay#2640](https://github.com/medici-finance/assay/issues/2640)). Meanwhile, split specs by package and run the ones your change touches.

## How do AI agents use this site?

Every page has a plain-Markdown twin at the same path with `.md` in place of `.html`, linked from the page head and footer. [llms.txt](llms.txt) lists every page with a one-line description; [llms-full.txt](llms-full.txt) is the whole site as one Markdown file. The spec format is published as a [JSON Schema](schema/spec.v1.json). Every flag, spec field, verdict and exit code has a stable anchor, so links such as `cli.html#flag-shard` and `spec.html#field-old` will keep working.

## How should an agent read a muhar result?

Check the exit status first: anything but 0 means no verdict. Then parse the `Totals:` line and each verdict line with the patterns on [Output and exit codes](output.md#parsing). Report a `NOT_CAUGHT` line as a missing test for the named guard, and a `COULD_NOT_MUTATE` line as a spec that needs updating — never either as a pass.

## Where do I report a bug?

In the [medici-finance/assay issue tracker](https://github.com/medici-finance/assay/issues). Include the muhar command, the spec, the exit status and stdout.

---

Source of this page: https://muhar.assay.guide/faq