Manual · Sheet 06

GUIDE

How it works

1. Load and validate config: hyperfixer.config.json is parsed and validated (unique gate names, numeric costs). Any config problem is exit 2, before anything runs.
2. Sort and group: enabled gates are sorted by cost; gates with equal cost form one group and run concurrently.
3. Execute with guards: each gate is a plain argv command (no shell). Output is captured, a per-gate timeout (default 10 min) sends SIGTERM then SIGKILL, parsers extract structured findings.
4. Fail-fast: when a group produces a fail or error, every later cost group is skipped. Siblings in the same group always finish.
5. Cache: a gate with inputs globs is fingerprinted (command + file contents, hashed per file). Same fingerprint and a previous pass means an instant hit; failures are never cached.
6. Verdict: .hyperfixer/verdict.json is written with per-gate results and a one-line hint. Exit 0 only when at least one gate executed and none failed.

The correct way to use it

1. hyperfixer init, then open the generated config and check the detected gates match your project.
2. hyperfixer doctor, fix anything red before trusting the pipeline.
3. Loop while coding: hyperfixer fix --quiet || hyperfixer hint, autofixable noise disappears first, then fix the hint, re-run until exit 0. hint proves staleness by content, not by clock.
4. Declare inputs on every gate you can, caching is what makes the loop fast.
5. Order costs by real runtime, cheap first. Keep expensive gates (mutation, e2e) above 50 so the pre-commit profile skips them and pre-push runs them.
6. Enforce: hyperfixer install-hooks (git) plus hyperfixer install-claude (Claude Code) plus the GitHub Action in CI.
7. In agent instructions, tell the agent to branch on exit codes: 0 done, 1 read the hint and fix code, 2 fix setup or config, never retry blindly.

Errors you can hit, and the fix

Symptom	Cause	Fix
exit 2, "config must be a JSON object" or a parse error	Malformed hyperfixer.config.json	Fix the JSON; hyperfixer doctor validates it
exit 2, duplicate gate name "x"	Two gates share a name	Rename one, names must be unique
FAIL, [pipeline] no gates executed	--max-cost below every gate, or all gates disabled	Raise --max-cost or enable gates; exit 2, an empty pipeline is a setup problem, never green
Gate error, "command failed to start"	Binary not installed or typo in command	Install the tool, or mark the gate "optional": true to skip instead
Gate error, "timed out after Xms"	Hung tool, watch mode, or a prompt waiting for stdin	Remove watch flags, raise timeoutMs if genuinely slow. Known limit: a gate that forks children may not be fully bounded, kill strays manually
[typecheck] Cannot find type definition file for 'bun-types' (TS2688)	tsconfig references types not installed	bun add -d @types/bun and use "types": ["@types/bun"]
Typecheck green but findings look empty on failure	tsc --pretty output defeats the parser	Keep --pretty false in the command (init default); raw detail is always in outputTail
Stryker crashes with ts.parseConfigFileTextToJson is not a function	TypeScript 7 installed, Stryker needs the TS 5 API	bun add -d typescript@~5.9 and set "disableTypeChecks": true in stryker.conf
Mutation gate very slow	Bun has no official Stryker runner, command runner re-runs the suite per mutant	Keep "mutate" scoped to few files, run it only pre-push or in CI
warning: verdict may be stale on stderr from hint	verdict.json older than 10 minutes	Re-run hyperfixer run, then hint
Lint gate red on .hyperfixer/verdict.json	The linter checks the verdict output dir	Exclude .hyperfixer/ from the linter config (Biome: files.includes scoped to src and test)
Suspicious green after big changes	Cache hit on a gate whose inputs globs miss some files	Fix the globs to cover every dependency, or --no-cache to force a full run
exit 2, "another hyperfixer run is in progress"	Concurrent run holds .hyperfixer/lock	Wait for it; stale locks (dead pid or older than 15 min) are stolen automatically
Git hook did not run	Foreign hook left untouched (install exits 1), or core.hooksPath points elsewhere	Read the install output, merge manually; hooks resolve via git rev-parse --git-path hooks, worktree safe
Agent bypassed the Claude hook	Alias or wrapper (gp, scripts) instead of plain git push	By design best effort; the git hooks and CI layers catch what the matcher misses
CLI does not start	No JS runtime on PATH	Install Node >= 20, Bun >= 1.1 or Deno >= 2, hyperfixer runs on all three

Reading the verdict like an agent

exit 0  done, commit or continue
exit 1  read hint, open file:line, fix CODE, re-run
exit 2  fix SETUP: config JSON, gate names, empty pipeline, lock held
exit 3  INFRASTRUCTURE failed: timeout or tool crash, do NOT edit code

The hint is always the first blocking finding. The full list, per-gate outputTail and timings live in .hyperfixer/verdict.json. Cached entries carry "cached": true, skipped gates carry a note explaining why.