henitai 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cda194514bf677d142e24c97c1589714041d2c88c4d2b33ffaf642e79c7ebe5d
-  data.tar.gz: 8505d5d6add5b850c5accb4904f43351e129b9261699c58051c35faa1a4b3758
+  metadata.gz: 49d5bc19a4c6d8335797de16d71488d9ffdbb5b85c03b541da1f99a5ba39a009
+  data.tar.gz: bb6490909c3c87cbe815ed960b649e23d60850ee41bb019097f6a4772de777ab
 SHA512:
-  metadata.gz: b17e21c51f0d4aac03154d8b782d4e361ea8fa792c03a984b9d5b94deccd2411ffb3fe8a7e6fe096b76b33f2bc211a813618c059642b4dec3e54b8fab4d01d8a
-  data.tar.gz: 109527f73b390086f03b5249dd90e97bf57ad3e34551f94d1f80b8f1e5968699e8d6cefe394ebf87bc10465b2a759de737d5f54257807e654a92cd040fa73f59
+  metadata.gz: 10d2c66aa8f8ca9ecd64a482d4bc73880f1598e3174a9df220201874333eab2d846903560dec5270fed4291b401a58f7a41b0e28fcafd5918fbd631bfb77e70b
+  data.tar.gz: d2c3859f3c70d28032a7a18b859df7713d6e39ca265004c8be86fe0d15ec450aea2e0bf2a60b147e6d2098c6c1f436829bdef87e6ff68353782790c9419465d6

data/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-13
+
+### Added
+- `henitai run --incremental`: verdict reuse from the history store. Killed
+  verdicts are reused when the subject's source and every covering test file
+  are byte-identical to what was recorded; Survived verdicts are additionally
+  gated on the live per-test covering set (membership and content) plus a
+  run-level dependency fingerprint over spec helpers, support files,
+  fixtures/factories, `Gemfile.lock`, `.henitai.yml`, and `.rspec` (ADR-11).
+  Reused mutants carry `fromCache: true` in the JSON report; the terminal
+  prints the reused split and an executed-only MS/MSI line. `--force` bypasses
+  reuse; every doubt (missing per-test map, ambiguous ids, legacy rows,
+  timeout/error verdicts) resolves to re-execution
+- Canonical report merge: scoped and partial runs (`--since`, subject
+  patterns, `--survivors-from`) merge into `reports/mutation-report.json`
+  keyed by `stableId` instead of overwriting it; full runs still replace it
+- Checkpoint reporting: long runs persist partial JSON/HTML results
+  incrementally, so a crashed or aborted run keeps its finished verdicts
+- Reports-directory locking: concurrent runs against the same `reports_dir`
+  fail fast with `ConcurrentRunError`; when the recorded owner pid is dead the
+  error names the likely orphaned child and the `lsof` command to find it
+- `henitai run --dry-run`: list the post-filter mutant set without executing
+  any tests (always exits 0)
+- `--strict-exit-codes` (opt-in): exit 3 when mutants timed out, 4 on
+  runtime/compile errors; precedence 2 > 3 > 4 > 1 > 0
+- Auto-calibrated per-mutant timeout from the measured test baseline
+  (`--timeout-multiplier`, default 3.0) when `mutation.timeout` is unset
+- Runtime-aware test ordering: per-test durations from the coverage pass
+  prioritize fast tests within a mutant run
+- Richer `# henitai:disable` directives: operator lists, reasons, and
+  `begin`/`end` regions
+- GitHub Actions annotation reporter
+- `HENITAI_WORKER_SLOT` environment variable for per-worker resource
+  isolation in parallel runs
+- `EqualityIdentityOperator`: the hard-to-kill `==`/`eql?`/`equal?` pairing
+  moved out of the default light set into its own operator (ADR-10)
+
+### Fixed
+- Mutants in `module_function` modules were unkillable: `module_function`
+  copies the method onto the module's singleton and activation only replaced
+  the instance side, so callers kept running original code and every such
+  mutant falsely survived. Activation now re-copies the injected method when
+  the pre-injection shape proves a `module_function` copy
+- Per-test coverage attributed each line only to the first test that executed
+  it; the map now credits every test whose run increments a line's hit count,
+  fixing silent test under-selection (a latent false-Survived risk)
+- Coverage freshness now watches the dependency file set as well: edits are
+  detected by mtime, deletions via a recorded path manifest
+  (`henitai_dependency_manifest.json`); `henitai clean` removes the sidecar
+- Stable-id collisions between same-signature mutants are disambiguated with
+  a site offset (`legacyStableId` is emitted temporarily so scoped runs
+  replace pre-offset canonical entries instead of duplicating them)
+- Child stdout/stderr capture is capped (`max_log_bytes`) so runaway mutants
+  cannot exhaust memory on long runs
+- Flaky-retry counter no longer inflates when a respawned child fails again
+
+### Changed
+- Terminal reporter renders original nodes from their source slice and reuses
+  a memoized unparse of the mutated node shared with the JSON reporter
+  (a dogfood profile spent 27% of wall time re-unparsing survivors)
+- The survivor dependency fingerprint prunes generated artifact trees
+  (fixture projects' `reports/`, `coverage/`, `mutation-logs/`) during the
+  scan — only on evidence of actual output, never by directory name alone —
+  cutting fingerprint time from ~0.7s to ~1.5ms and keeping smoke runs from
+  invalidating survivor reuse
+- Mutant children no longer emit unconditional debug lines, coverage-formatter
+  warnings for deliberately suppressed coverage, or rspec-mocks `__send__`
+  redefinition warnings into their logs
+
+### Internal
+- Architecture documentation gained §8.11 (incremental verdict reuse) and
+  ADR-11 (content-fingerprint verdict reuse, not git scoping); new backlog
+  tickets for CI warm verdict cache, child null formatter, and auto-`--since`
+- Spec writes into the repository checkout are rejected wholesale — mutants
+  that reroute CLI dispatch into `init` now count as kills instead of
+  littering the working tree
+- `.henitai-pi-agent/` session transcripts untracked
+
 ## [0.2.1] - 2026-06-25
 
 ### Fixed
@@ -302,7 +380,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLI critical path: `henitai run` now executes the full pipeline, supports `--since`, returns CI-friendly exit codes, and `henitai version` prints `Henitai::VERSION`
 - RSpec per-test coverage output: `henitai/coverage_formatter` now writes `coverage/henitai_per_test.json`
 
-[Unreleased]: https://github.com/martinotten/henitai/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/martinotten/henitai/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/martinotten/henitai/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/martinotten/henitai/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/martinotten/henitai/compare/v0.1.10...v0.2.0
 [0.1.10]: https://github.com/martinotten/henitai/compare/v0.1.9...v0.1.10

data/README.md

@@ -75,14 +75,28 @@ includes:
 excludes:
   - lib/henitai/eager_load.rb   # standalone entry points with no in-process coverage
 
+test_excludes:
+  - spec/end_to_end/*_spec.rb   # never select these files for individual mutants
+
 mutation:
   operators: light   # light | full
   timeout: 10.0
   max_flaky_retries: 3
+  max_log_bytes: 5000000
+  max_timeout: 30.0
   sampling:
     ratio: 0.05
     strategy: stratified
 reports_dir: reports
+reporters:
+  - terminal
+  - json
+  - html
+
+reports:
+  checkpoint: true
+  checkpoint_every: 200
+  checkpoint_interval: 30.0
 
 thresholds:
   high: 80
@@ -94,6 +108,15 @@ when a value is invalid.
 
 CLI flags override the corresponding values from `.henitai.yml`.
 
+`test_excludes` removes matching test files from per-mutant selection. A mutant
+with no tests left is reported as `NoCoverage` and is not executed.
+`mutation.max_log_bytes` is a positive per-stream byte cap for captured child
+output. `mutation.max_timeout` caps auto-calibrated timeouts; an explicit
+`mutation.timeout` still takes precedence. When JSON or HTML reporting is
+enabled, `reports.checkpoint*` controls periodic canonical-report checkpoints.
+Each checkpoint updates `mutation-report.json`; when the HTML reporter is
+configured, it also regenerates `mutation-report.html` from that merged JSON.
+
 Before mutation testing starts, Henitai checks whether the current coverage data
 covers the configured source files. If not, Henitai runs the configured test
 suite once to bootstrap a usable coverage baseline. If coverage is still
@@ -110,6 +133,16 @@ yet enable the per-test coverage formatter.
 Henitai currently defaults to linear mutant execution. Set `jobs` in
 `.henitai.yml` or pass `--jobs N` to opt into parallel mutant execution.
 
+Every forked test child sees a `HENITAI_WORKER_SLOT` environment variable
+holding a stable worker-slot index (`0..jobs-1`; always `0` on the linear
+path). A flaky-retry respawn keeps the original attempt's value. Test suites
+that touch shared external resources can isolate themselves per slot without
+any henitai-side hooks — for example a per-worker database:
+
+```ruby
+database: "myapp_test_#{ENV.fetch('HENITAI_WORKER_SLOT', '0')}"
+```
+
 By default, Henitai keeps child test output out of the live terminal. Each
 baseline or mutant run writes captured stdout/stderr to `reports/mutation-logs/`
 and the terminal only shows progress plus a concise summary. Pass
@@ -117,7 +150,47 @@ and the terminal only shows progress plus a concise summary. Pass
 
 `henitai version` prints the installed version. `henitai run` exits with `0`
 when the mutation score meets the low threshold, `1` when it does not, and `2`
-for framework errors.
+for framework errors. With `--strict-exit-codes` (opt-in, additive) it also
+exits `3` when one or more mutants timed out and `4` when runtime/compile
+errors are present; precedence `2` > `3` > `4` > `1` > `0`. The timeout code
+is informational — a run can pass its threshold and still exit `3`.
+
+For pull-request feedback, add the `github` reporter to `reporters:` in
+`.henitai.yml`: it prints one `::warning file=...,line=...` workflow command
+per survived mutant, so survivors appear as inline annotations on the PR diff
+in GitHub Actions. All other statuses stay silent.
+
+`henitai run --incremental` reuses still-valid `Killed` and `Survived`
+verdicts from the history store (`reports/mutation-history.sqlite3`) instead
+of re-executing them. A `Killed` verdict is reused when the subject's source
+and every covering test file are byte-identical to what was recorded. A
+`Survived` verdict needs more proof, because a *new* test could now kill it:
+it is reused only when, additionally, the live covering set derived from the
+current per-test coverage map matches the recorded set exactly (no test
+added, dropped, or changed) and the dependency fingerprint (spec helpers,
+`spec/support`, fixtures/factories, `Gemfile.lock`, `.henitai.yml`, `.rspec`)
+is unchanged. When per-test coverage is unavailable, survivors simply
+re-execute — reuse never happens on doubt (see ADR-11).
+Reused mutants stay visible in the report (`fromCache: true` beside
+`stableId`) and count toward MS/MSI; the terminal prints
+`N of M verdicts reused from history (K killed, S survived)` plus an
+executed-only MS/MSI line so cached verdicts are never mistaken for fresh
+results.
+Generated mutants temporarily include `legacyStableId` so scoped runs replace
+canonical entries written before site-offset IDs were introduced instead of
+duplicating them.
+Timeouts and errors always re-execute. `--force` bypasses reuse.
+`henitai run --dry-run` lists the post-filter mutant set without executing
+mutants and always exits `0`. Gate 0 may still run the configured test suite to
+refresh baseline coverage.
+
+Every `henitai run`, including a dry run, acquires a fail-fast advisory lock at
+`<reports_dir>/.henitai-run.lock`. `henitai clean` uses the same lock, so it
+cannot delete artifacts from a live run. Contention is a framework error (exit
+code `2`); direct `Runner#run` callers receive `Henitai::ConcurrentRunError`.
+The persistent JSON lock file records the last owner's PID and start time. It
+is coordination metadata, not evidence of an active run: the kernel lock is
+authoritative, and the file may be the only artifact a dry run creates.
 
 `henitai run --survivors-from ...` performs a partial rerun: it reports only
 the selected survivors, skips threshold-based exit checks, and does not update
@@ -125,6 +198,52 @@ the run trend history. Dirty worktree changes are included, so you can edit
 tests locally without committing first; if source files under `includes` are
 dirty, Henitai reruns the matched survivors conservatively.
 
+### Skipping mutations inline
+
+A `# henitai:disable` magic comment excludes code from mutation at the call
+site, without touching `.henitai.yml`:
+
+```ruby
+def risky_calc(x)
+  x * 2 # henitai:disable            — skips mutants on this line
+end
+
+# henitai:disable                     — skips every mutant in this method
+def legacy_shim(x)
+  x - 1
+end
+```
+
+The line form applies to mutants starting on that line. The method form is a
+standalone comment in the contiguous comment block directly above a `def`
+(a blank line breaks the association). Trailing text is allowed
+(`# henitai:disable -- reviewed defensive branch`). Skipped mutants are
+reported as `Ignored`, so they stay visible in the report instead of silently
+vanishing. Use `mutation.ignore_patterns` for repo-wide policy and
+`# henitai:disable` for one-off, reviewed exclusions.
+
+Directives can also target specific operators, carry a reason (serialized as
+`statusReason`, visible in the HTML report), and cover regions:
+
+```ruby
+x = a + b  # henitai:disable ArithmeticOperator            — only this operator
+x = a + b  # henitai:disable ArithmeticOperator: log noise — with a reason
+
+# henitai:disable RegexMutator: timing-sensitive matcher
+def parse(line)
+  ...
+end
+
+# henitai:disable-start ConditionalExpression
+...region...
+# henitai:disable-end
+```
+
+Operator names must exactly match the canonical names from
+`henitai operator list`; unknown names, unmatched or nested
+`disable-start`/`disable-end` directives abort the run (exit `2`) with the
+offending file and line. Regions do not nest.
+
 The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/workspaces/henitai/assets/schema/henitai.schema.json) for editor autocompletion.
 
 ## Operator sets
@@ -132,7 +251,7 @@ The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/wor
 **Light** (default) — high-signal, low-noise operators covering the majority of real-world defects:
 
 - `ArithmeticOperator` — `+` ↔ `-`, `*` ↔ `/`
-- `EqualityOperator` — `==` ↔ `!=`, `>` ↔ `<`, etc.
+- `EqualityOperator` — `==` ↔ `!=`, `>` ↔ `<`, etc. (relational operators only)
 - `LogicalOperator` — `&&` ↔ `||`
 - `BooleanLiteral` — `true` ↔ `false`, `!expr`
 - `ConditionalExpression` — remove branch bodies
@@ -151,6 +270,7 @@ The repository ships a JSON Schema at [`assets/schema/henitai.schema.json`](/wor
 - `AssignmentExpression` — mutate compound assignment
 - `UnaryOperator` — remove unary `-` and `~`
 - `UpdateOperator` — swap compound assignments (`+=`↔`-=`, `*=`↔`/=`, `||=`↔`&&=`)
+- `EqualityIdentityOperator` — `==` ↔ `eql?`/`equal?` (hardest equality pairing to kill; see [ADR-10](docs/architecture/adr/ADR-10-split-equality-identity-mutations.md))
 
 ## Stryker Dashboard integration
 
@@ -184,6 +304,7 @@ git clone https://github.com/martinotten/henitai
 cd henitai
 bundle install
 bundle exec rspec        # run tests
+bundle exec ruby bin/verify-process-free-specs # verify self-mutation-safe specs
 bundle exec rake smoke:integration:all # run rspec/minitest integration smoke projects
 bundle exec rubocop      # lint
 bundle exec henitai clean # remove stale generated report artifacts

data/assets/schema/henitai.schema.json

@@ -33,6 +33,12 @@
         "type": "string"
       }
     },
+    "test_excludes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "mutation": {
       "type": "object",
       "additionalProperties": false,
@@ -43,10 +49,22 @@
         "timeout": {
           "type": "number"
         },
+        "timeout_multiplier": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
         "max_flaky_retries": {
           "type": "integer",
           "minimum": 0
         },
+        "max_log_bytes": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
+        "max_timeout": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
         "ignore_patterns": {
           "type": "array",
           "items": {
@@ -106,6 +124,23 @@
     "reports_dir": {
       "type": "string"
     },
+    "reports": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "checkpoint": {
+          "type": "boolean"
+        },
+        "checkpoint_every": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
+        "checkpoint_interval": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      }
+    },
     "dashboard": {
       "type": "object",
       "additionalProperties": false,

data/lib/henitai/available_cpu_count.rb

@@ -5,6 +5,9 @@ require "etc"
 module Henitai
   # Detects the effective CPU count available to the current process.
   class AvailableCpuCount
+    CFS_QUOTA_PATH = "/sys/fs/cgroup/cpu/cpu.cfs_quota_us"
+    CFS_PERIOD_PATH = "/sys/fs/cgroup/cpu/cpu.cfs_period_us"
+
     class << self
       def detect
         counts = [Etc.nprocessors, cgroup_cpu_quota, cpuset_cpu_count].compact.select(&:positive?)
@@ -14,38 +17,30 @@ module Henitai
       private
 
       def cgroup_cpu_quota
-        parse_cpu_max(read_limit("/sys/fs/cgroup/cpu.max")) ||
-          parse_cpu_cfs(
-            read_limit("/sys/fs/cgroup/cpu/cpu.cfs_quota_us"),
-            read_limit("/sys/fs/cgroup/cpu/cpu.cfs_period_us")
-          )
+        quota = parse_cpu_max(read_limit("/sys/fs/cgroup/cpu.max"))
+        return quota if quota
+
+        quota_count(read_limit(CFS_QUOTA_PATH), read_limit(CFS_PERIOD_PATH))
       end
 
       def cpuset_cpu_count
-        count_cpu_list(read_limit("/sys/fs/cgroup/cpuset.cpus.effective")) ||
-          count_cpu_list(read_limit("/sys/fs/cgroup/cpuset.cpus"))
+        count = count_cpu_list(read_limit("/sys/fs/cgroup/cpuset.cpus.effective"))
+        return count if count
+
+        count_cpu_list(read_limit("/sys/fs/cgroup/cpuset.cpus"))
       end
 
       def read_limit(path)
         return unless File.file?(path)
 
-        File.read(path).strip
-      rescue Errno::ENOENT, Errno::EACCES
-        nil
+        File.read(path)
+      rescue Errno::ENOENT, Errno::EACCES then nil
       end
 
       def parse_cpu_max(value)
-        return if value.nil? || value.empty?
+        return if value.nil?
 
         quota, period = value.split
-        return if quota == "max"
-
-        quota_count(quota, period)
-      end
-
-      def parse_cpu_cfs(quota, period)
-        return if quota.nil? || period.nil? || quota == "-1"
-
         quota_count(quota, period)
       end
 
@@ -55,16 +50,14 @@ module Henitai
         return if quota_value <= 0 || period_value <= 0
 
         [quota_value / period_value, 1].max
-      rescue ArgumentError
-        nil
+      rescue ArgumentError then nil
       end
 
       def count_cpu_list(value)
         return if value.nil? || value.empty?
 
         value.split(",").sum { |entry| cpu_list_entry_size(entry) }
-      rescue ArgumentError
-        nil
+      rescue ArgumentError then nil
       end
 
       def cpu_list_entry_size(entry)

data/lib/henitai/canonical_report_merger.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Henitai
+  # Merges a scoped/partial run's Stryker schema into the previously-written
+  # canonical report on disk instead of letting it fully replace the file.
+  #
+  # Pure and fail-safe: any anomaly (missing/corrupt prior file, mismatched
+  # shape, a merge that would end up thinner than the current run alone)
+  # falls back to the current run's schema by itself -- structurally never
+  # worse than the unconditional overwrite this replaces.
+  #
+  # Merges at mutant granularity, keyed by `stableId`, not file granularity:
+  # a `--survivors-from` rerun's schema only contains the re-verified
+  # survivors for a file, so replacing that file's whole entry would drop
+  # every other mutant (e.g. Killed ones) in the same file.
+  module CanonicalReportMerger
+    # @param prune_missing [Boolean] when true, prior file entries whose source
+    #   file no longer exists on disk are dropped from the merged report (a
+    #   deleted module, or one removed from `includes`). Off by default so the
+    #   merge stays a pure schema operation; the reporter enables it because it
+    #   runs from the project root where relative source paths resolve.
+    def self.merge(current_schema, prior_path, prune_missing: false)
+      current = stringify(current_schema)
+      return current unless File.exist?(prior_path)
+
+      prior = JSON.parse(File.read(prior_path))
+      return current unless prior.is_a?(Hash) && prior["files"].is_a?(Hash)
+
+      merged = merge_files(current, prior, prune_missing:)
+      return current unless safe?(merged, current)
+
+      merged
+    rescue StandardError
+      stringify(current_schema)
+    end
+
+    def self.merge_files(current, prior, prune_missing:)
+      merged_files = overlay_current_mutants(deep_dup(prior["files"]), current)
+      merged_files.reject! { |_, file| file["mutants"].empty? }
+      prune_missing_source_files(merged_files) if prune_missing
+      current.merge("files" => merged_files)
+    end
+    private_class_method :merge_files
+
+    # Drops entries carried over from the prior report whose source file no
+    # longer exists on disk (deleted module, or dropped from `includes`). Files
+    # produced by the current run always exist, so a scoped rerun never removes
+    # in-scope-but-untouched findings -- only genuinely gone paths.
+    def self.prune_missing_source_files(merged_files)
+      merged_files.select! { |file, _| File.exist?(file) }
+    end
+    private_class_method :prune_missing_source_files
+
+    def self.overlay_current_mutants(merged_files, current)
+      strip_rerun_mutants(merged_files, mutant_ids(current))
+      append_current_mutants(merged_files, current)
+      merged_files
+    end
+    private_class_method :overlay_current_mutants
+
+    def self.strip_rerun_mutants(merged_files, current_ids)
+      merged_files.each_value { |file| file["mutants"].reject! { |m| current_ids.include?(m["stableId"]) } }
+    end
+    private_class_method :strip_rerun_mutants
+
+    def self.append_current_mutants(merged_files, current)
+      current.fetch("files", {}).each do |file, entry|
+        target = merged_files[file] ||= { "mutants" => [] }
+        target["source"] = entry["source"]
+        target["language"] = entry["language"]
+        target["mutants"] += entry["mutants"]
+      end
+    end
+    private_class_method :append_current_mutants
+
+    def self.mutant_ids(schema)
+      schema.fetch("files", {}).each_value.flat_map do |file|
+        file.fetch("mutants", []).flat_map do |mutant|
+          [mutant["stableId"], mutant["legacyStableId"]].compact
+        end
+      end.to_set
+    end
+    private_class_method :mutant_ids
+
+    def self.safe?(merged, current)
+      mutant_count(merged) >= mutant_count(current)
+    end
+    private_class_method :safe?
+
+    def self.mutant_count(schema)
+      schema.fetch("files", {}).values.sum { |file| file.fetch("mutants", []).size }
+    end
+    private_class_method :mutant_count
+
+    def self.deep_dup(object)
+      Marshal.load(Marshal.dump(object))
+    end
+    private_class_method :deep_dup
+
+    def self.stringify(schema)
+      JSON.parse(JSON.generate(schema))
+    end
+    private_class_method :stringify
+  end
+end

data/lib/henitai/canonical_report_writer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Henitai
+  # Writes a Stryker schema to the canonical report path.
+  #
+  # Authoritative (full-run) writes replace the file wholesale; non-authoritative
+  # writes (scoped/partial runs, and every incremental checkpoint after the
+  # first) merge into the existing report via {CanonicalReportMerger}, pruning
+  # entries whose source file no longer exists. Shared by the JSON reporter and
+  # the {CheckpointReporter} so both persist the report identically.
+  module CanonicalReportWriter
+    def self.write(schema, path:, authoritative:)
+      output = authoritative ? schema : CanonicalReportMerger.merge(schema, path, prune_missing: true)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(output))
+      output
+    end
+  end
+end

data/lib/henitai/checkpoint_reporter.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Henitai
+  # Progress observer that flushes the canonical report to disk periodically
+  # during a run, so a crash on a long run keeps partial results and the report
+  # grows visibly mid-run instead of appearing only at the end (Gate 5).
+  #
+  # Each flush serialises only the mutants completed since the previous flush
+  # and folds them into the on-disk JSON report. When HTML reporting is active,
+  # the self-contained HTML report is regenerated from that merged JSON schema.
+  # Reuses {Result#to_stryker_schema} and {CanonicalReportWriter}.
+  #
+  # On a full (authoritative) run the first flush replaces the report — wiping
+  # entries left by earlier runs, including deleted files — and later flushes
+  # merge their batch in. On a scoped/partial run every flush merges, matching
+  # the end-of-run reporter's behaviour.
+  class CheckpointReporter
+    MONOTONIC = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+    def initialize(config:, source_provider:, authoritative:, started_at: Time.now, clock: MONOTONIC)
+      @config = config
+      @source_provider = source_provider
+      @authoritative = authoritative
+      @started_at = started_at
+      @clock = clock
+      @batch = []
+      @last_flush_at = clock.call
+      @flushed = false
+    end
+
+    def progress(mutant, **)
+      @batch << mutant
+      flush! if due?
+    end
+
+    private
+
+    def due?
+      @batch.size >= @config.checkpoint_every ||
+        (@clock.call - @last_flush_at) >= @config.checkpoint_interval
+    end
+
+    def flush!
+      first_full_flush = @authoritative && !@flushed
+      merged_schema = CanonicalReportWriter.write(
+        build_schema(@batch),
+        path: canonical_path,
+        authoritative: first_full_flush
+      )
+      write_html(merged_schema) if html_reporter?
+      @flushed = true
+      @batch = []
+      @last_flush_at = @clock.call
+    end
+
+    def build_schema(mutants)
+      Result.new(
+        mutants: mutants,
+        started_at: @started_at,
+        finished_at: Time.now,
+        thresholds: @config.thresholds,
+        source_provider: @source_provider,
+        authoritative: @authoritative
+      ).to_stryker_schema
+    end
+
+    def canonical_path
+      File.join(@config.reports_dir, "mutation-report.json")
+    end
+
+    def html_reporter?
+      Array(@config.reporters).map(&:to_s).include?("html")
+    end
+
+    def write_html(schema)
+      Reporter::Html.new(config: @config).report_schema(schema)
+    end
+  end
+end

data/lib/henitai/cli/clean_command.rb

@@ -16,22 +16,28 @@ module Henitai
         return if @command_halted
 
         config = load_config(options)
-        removed_paths = cleanup_report_artifacts(config)
+        removed_paths = ReportsDirectoryLock.new(reports_dir: config.reports_dir).synchronize do
+          cleanup_report_artifacts(config)
+        end
         puts clean_summary(removed_paths)
       rescue StandardError => e
         handle_run_error(e)
       end
 
       def cleanup_report_artifacts(config)
-        removed_paths = report_cleanup_paths(config).select { |path| File.exist?(path) }
-        removed_paths.each { |path| FileUtils.rm_f(path) }
-        removed_paths
+        removed_dirs = cleanup_dir_paths(config).select { |path| File.directory?(path) }
+        removed_dirs.each { |path| FileUtils.rm_rf(path) }
+        removed_files = cleanup_file_paths(config).select { |path| File.file?(path) }
+        removed_files.each { |path| FileUtils.rm_f(path) }
+        removed_dirs + removed_files
       end
 
-      def report_cleanup_paths(config)
-        REPORT_CLEANUP_PATHS.map do |relative_path|
-          File.join(config.reports_dir, *relative_path)
-        end
+      def cleanup_file_paths(config)
+        REPORT_CLEANUP_PATHS.map { |relative_path| File.join(config.reports_dir, *relative_path) }
+      end
+
+      def cleanup_dir_paths(config)
+        REPORT_CLEANUP_DIRS.map { |relative_path| File.join(config.reports_dir, *relative_path) }
       end
 
       def clean_summary(removed_paths)