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).

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).

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.

Does muhar work outside Go?

Yes. muhar edits text and runs any sh -c command. The examples on Writing good mutants 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).

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).

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). 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 lists every page with a one-line description; llms-full.txt is the whole site as one Markdown file. The spec format is published as a JSON Schema. 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. 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. Include the muhar command, the spec, the exit status and stdout.