saboteur 0.7.0 → 0.8.0

data/CHANGELOG.md

@@ -6,6 +6,663 @@ All notable changes are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-18
+
+### Added
+
+- `--test-command` runs a mutation-visibility check before the first
+  mutant (#441). The command runs once with the first subject's file
+  replaced by a load-time error; if it still passes, the command cannot
+  see mutants in that file - a `RUBYLIB`/`-I` path or an installed gem
+  anchors it to the real tree, or the suite never loads the file - and
+  the run warns loudly that the score would read 0.0 % instead of
+  silently reporting every mutant Survived.
+
+
+- `--shard K/N` (#470): run one deterministic slice of the planned candidate
+  inventory - `K` is the 1-based shard and `N` the number of shards. Each
+  planned mutant is assigned by a SHA-256 of its candidate identity, never by
+  position, so the split stays stable when an earlier subject gains or loses a
+  mutant. The terminal, JSON and agent outputs name the shard, the inventory
+  digest and the selected/planned counts, and a shard run is always reported
+  partial. See docs/guides/sharding.md for the CI matrix setup.
+
+- `saboteur survivors <report.json>` (#475): a read-only terminal browser
+  for the Stryker JSON report - list and filter survivors (with the
+  ranked-findings order available via `--ranked`), and `--show DIGEST`
+  prints the diff, the exact replay command and an ignore-file entry
+  template. It never boots the project or edits the ignore file.
+- `--flaky-check survivors|decisive` (#476): one reordered confirmation
+  rerun per new survivor (and per fresh kill in `decisive` mode). A
+  verdict the confirmation disagrees with becomes `unverified` - named
+  with its decisive tests, outside the score, never retried until it
+  passes.
+- `saboteur badge` writes Shields endpoint JSON from the opt-in score
+  history and `saboteur trend` prints the covered-score delta against the
+  last comparable record (#474). A README badge needs no hosted service:
+  commit the written JSON and point a Shields endpoint badge at its raw
+  URL. An incomplete run is refused as badge evidence unless
+  `--mark-partial` labels the badge as partial, and the trend never
+  compares records with different selection, inventory, schema version
+  or operator policy.
+- `c.sandbox = "seatbelt"`, an opt-in macOS sandbox for mutant children
+  (#436): each child applies a Seatbelt profile (writes denied except the
+  granted dirs, the system temp dir, and its own inherited logs) via
+  `sandbox_init`, after a forked probe proves a deny-default profile
+  really blocks a write. A macOS without Seatbelt degrades to the hazard
+  guard and canary with a one-time note; an errored probe or a profile
+  that does not enforce refuses the run (the Landlock probe's pinned
+  semantics, #178), and a child whose profile refuses to apply fails
+  closed instead of running the mutant.
+  On Linux the value behaves like `true`. Opt-in because Apple deprecates
+  `sandbox_init` without a published replacement; #436 tracks the
+  ecosystem's response.
+- `saboteur run --dry-run --format json` prints a versioned machine-readable
+  mutant inventory without booting the suite (#469): schema version, run
+  metadata, subjects, every planned mutant with its stable digest, operator,
+  file, line and byte-range edits, and every skipped candidate with its
+  reason (inline suppression, hazard refusal or the per-method cap).
+  `--dry-run --agent` now names this flag instead of only refusing.
+- A `regex_replacement` operator (#135): drops each regex anchor
+  (`\A`, `\z`, `\Z`, `^`, `$`) in turn and swaps each bare `+` or `*`
+  quantifier, so a validation like `/\A\d+\z/` finally gets mutants.
+  Escaped characters, character classes and lazy or possessive stacks stay
+  untouched; interpolated regexes stay out. The operator policy version
+  moves to 3: histories stamped with an older policy stay readable but
+  never trend-compare against new runs.
+- Methods defined by a non-interpolated `class_eval`/`module_eval` heredoc
+  are mutation subjects (#544): the heredoc body is re-parsed against the
+  real file's bytes, so mutants inside it are generated and judged like
+  ordinary defs (the faraday shape that used to produce 0 subjects). An
+  interpolated heredoc still yields no subjects and keeps the
+  code-in-strings warning (#467).
+- Per-path score gate config (#473, slice 1): `score_gate "app/payments/**/*",
+  min_score: 95` in `saboteur.rb` declares a per-subtree score floor,
+  validated at load (min_score 0-100, pattern must match an included file).
+  Enforcement lands with slice 2 (#570).
+- Per-path score gates are enforced (#473, slice 2): each `score_gate`
+  subtree from slice 1 (#565) is scored with the run's own formula. A gate under its floor fails the run like the
+  count gates (`scoreGate` cause in the JSON report); a gate with nothing
+  executed under it passes vacuously and says so. Score gates cannot combine
+  with `--agent`, like `--threshold`.
+- Peak-memory measurement (#202, slice 1): each worker reports its kernel
+  peak RSS (VmHWM) when it retires, and the JSON report records it under
+  `saboteur.memory` as per-worker `peakMb` values plus the supervisor's own
+  peak. No total is printed: fork copy-on-write makes per-process RSS
+  non-additive. The section is omitted where procfs is unavailable.
+
+### Changed
+
+- Any `--since` run whose resolved range has no changes now refuses with
+  exit 2 instead of passing with 0 subjects (#643) - scheduled or no-op
+  runs included. The common hit is `saboteur pr <merge_sha>` on a
+  checkout AT the merge commit, which diffed the merge against itself;
+  the refusal names the base and the resolved range and says to fetch
+  the merge's parent or point `--since` at the change's base.
+- A run whose effective include set selects no Ruby file now refuses with
+  exit 2 instead of passing with 0 subjects (#447). The default include
+  targets plain gems, so a first run on a Rails-shaped tree used to be a
+  green gate that mutated nothing on every CI run; the refusal names the
+  stale pattern and points at the install generator.
+- A `--subject` pattern that matches no subject now fails the run (exit 2)
+  instead of passing silently with zero subjects (#379). When some patterns
+  match, the run keeps them and the summary names the missing pattern and
+  the matched count.
+
+### Fixed
+
+- A single `using` anywhere in a file used to skip every subject in the
+  file. Refinement skips are now scope-granular (#634): a bare `using`
+  skips only subjects after it in its own class/module body (or the
+  rest of the file at the top level), so one module's refinement no
+  longer skips a sibling module's methods. A `using` inside a method
+  or block body still skips the whole file.
+
+- `scope :name, -> { ... }` and `define_singleton_method` bodies are now
+  subjects (#194): the human-essentials dogfood showed a scope's lambda
+  going unmutated. The call is a singleton subject of the enclosing owner;
+  the lambda or block body mutates, and re-evaluating the whole call
+  re-registers the method.
+- An arid statement (a logging or instrumentation call) whose block carries
+  real work is now mutated inside the block (#464). The walk used to skip
+  the whole statement, so a method like one wrapped in
+  `Notifications.instrument ... do |payload| ... end` produced only the
+  coarse `body_raise` and no statement_removal, boolean_logic or other
+  fine mutants on the changed lines. The block body is walked like any
+  other, and such a statement also keeps the method out of the
+  nothing-to-remove coarse check.
+- A loaded class defining a singleton `hash` that does not return an
+  Integer (forem's `ReactionCategory`) no longer crashes the boot as an
+  internal TypeError: every `Coverage.result` read now refuses with a
+  diagnostic explaining the violated `#hash` contract and blaming the
+  application's code (#564).
+- A `--since` diff that deletes a method no longer reports the deletion as
+  "differ only in comments or formatting" and no longer names the method the
+  deleted lines drifted onto. The run says what was deleted instead: `N
+  changed subject(s) were deleted, nothing to mutate: ...` (#466).
+- An error-dominated run no longer prints a bare score above the "tested almost nothing" warning: the terminal reports "score n/a (N of M mutants scored, X % of scored)" so the scored share cannot be misread as a run-wide score (#557).
+- Preflight no longer refuses a precompiled Ruby (mise, ruby-build) whose
+  binary tops the 50 MB evidence-document cap (#364): tool identity
+  digests stream with an executable-sized bound instead. The cap for JSON
+  evidence documents is unchanged.
+- A missing `rspec-core` no longer crashes saboteur into the internal-error
+  report with a bare `LoadError`: the RSpec integration refuses with
+  "rspec is not in the bundle" and names the remedy, adding the gem to the
+  test group or pointing `c.integration` at the suite's framework (#482).
+  Only the framework's own `LoadError` converts; a `LoadError` raised by
+  the app's own files, or for a different feature such as `rspec/core_ext`,
+  keeps the crash route.
+- A `--since` run whose changed methods were all skipped - refinements,
+  no coverage, or any other skip reason - used to exit 0 with `score n/a`,
+  a green run that tested nothing. It now exits 3 and names each skipped
+  subject with its reason, and a partially skipped diff announces each
+  skip up front instead of only in the end-of-run summary (#574).
+
+- `saboteur badge` escapes incomplete-run reasons with `.inspect` in its
+  refusal message, so a reason carrying newlines or control characters
+  cannot spoof extra output lines (#474).
+- `c.sandbox = "seatbelt"` grants now match real paths on macOS: the
+  kernel resolves `/var` to `/private/var` when it checks a write
+  against a Seatbelt subpath grant, so a granted dir under a symlinked
+  parent (like `Dir.mktmpdir` under `/var/folders`) silently matched
+  nothing and the child saw its own writable dir denied. Granted dirs
+  are now resolved with `File.realpath` before the profile is built,
+  the same view `fcntl(F_GETPATH)` reports back.
+
+- The artifact dir now ignores itself (#426): a run writes logs,
+  coverage maps and reports under the cache dir, and the marker
+  `.gitignore` keeps a `git add -A` from committing them. An existing
+  `.gitignore` there is left alone.
+- Rejected kills no longer surface as generic errors: the terminal
+  lists them in a `Rejected kills` section and annotates the error count,
+  and report.json flags each rejected mutant with `rejectedKill: true`
+  instead of carrying only the `rejectedKills` count (#375).
+
+- A changed file the diff only deletes from no longer hard-stops a
+  --since run for want of a spec (#484): a deletion-only file yields no
+  subject and no fine-grained mutant, so test inference treats it as
+  subjectless instead of demanding a spec, and the run goes ahead.
+- The pr preset no longer hard-stops when a changed file's coverage
+  lives in a consolidated spec the diff itself touches: a spec added
+  or changed in the diff that reads a constant the uncovered file
+  defines covers that file and runs, instead of exit 2 (#538). The
+  stop remains for a mutable change no changed spec exercises.
+- Dependency trees are never treated as changed source on a `--since`
+  run (#504): a vendored bundle or `node_modules`, tracked or
+  untracked, git-ignored or not, is rejected at enumeration, so the
+  diff scope never lists, reads or warns on it. The `.bundle/config`
+  file itself is project configuration and stays visible.
+- The project-local bundler path (`.bundle/config`'s `BUNDLE_PATH`) now
+  joins the dependency shield in its quoted and non-canonical forms
+  (#567): matching quotes are stripped, an inline `#` comment is ignored
+  the way Bundler::YAMLSerializer ignores it, a relative path is
+  normalized against the project root, and an absolute path (the system
+  bundle) stays outside the shield. A config that is not a regular file
+  or cannot be parsed - including a NUL byte in the value - means no
+  shield rather than a crash or a hang.
+
+- A `--max-duration` budget that cannot cover the cold coverage map build
+  now stops the run before the build starts, instead of spending the
+  whole budget mid-build and keeping nothing - the trap where every
+  `--incremental` resume redid the baselines and died at the same point.
+  Once the baseline passes are timed, a build costing about one more
+  full pass than the budget holds is refused up front, with the
+  shortfall and the remedies (a higher budget, fewer
+  `--baseline-passes`, or one unbudgeted run to warm the coverage
+  cache) in the message (#427).
+
+- The first-pass ETA no longer reads like a second baseline check when
+  the baseline is done (#465): with a cold coverage cache the remaining
+  pass is the coverage map build, and the message now names the coverage
+  build and any remaining baseline passes separately.
+- Def-time macro mutants - a `deprecate`-style helper, a `before_action`
+  block, any DSL whose only caller is a class body - no longer report as
+  survived: the closure captured while the app loads keeps the pristine
+  definition, so replacing the method later cannot judge them. They now
+  report as `ran at load`, outside the score (#409).
+- A mutant on the continuation line of a multi-line interpolated
+  statement is no longer misclassified missing_test (#498): attribution
+  now spans the whole enclosing statement, because an interpolation's own
+  statements are eager and Ruby's per-line events on continuation lines
+  are not reliable per example.
+- `--incremental` now sees dependency-declaration edits on projects
+  that commit no lockfile (the library convention): the verdict
+  fingerprint hashed only `Gemfile.lock` / `gems.locked`, so the digest
+  was a constant and every cached verdict was reused across a `Gemfile`,
+  `gems.rb` or `*.gemspec` edit (#408). Manifests and gemspecs anywhere
+  under the project root are hashed always.
+
+- A `--since` change inside a constant literal saboteur refuses to mutate
+  (unvettable load-time code, or an unsupported literal form) no longer
+  reads like an unexplained miss in the umbrella "no subjects covering the
+  changed lines" warning: the warning now says how many of the files sit
+  in a constant literal that is not mutated, named by the constant
+  warnings above it (#537).
+
+- ERB generator templates (`.rb` files with ERB interpolation, as Rails
+  generators carry under `lib/generators/**/templates/`) no longer print a
+  per-file "does not parse" warning on every discovery pass: they can
+  never parse as plain Ruby, so they are skipped with one summarized note
+  per run. A real syntax error in a plain Ruby file still warns per file
+  (#372).
+- A `c.sources` entry that looks like a source glob now fails with a
+  pointer to `c.include` (#488): `c.sources` registers custom operator
+  sources (`builtin` or `path.rb:ClassName`), not the files to mutate.
+- A baseline stopped by a containment limit (process count or memory)
+  now names the knob and its current value in the refusal (#459): a
+  suite that forks heavily by design, or legitimately needs more
+  memory, is pointed at `c.max_processes` / `c.max_memory_mb` instead
+  of reading as a suite failure.
+
+- A baseline that passed but leaked child processes no longer reads as a
+  suite failure quoting an empty "Failures:" section (#486): the refusal
+  says the suite passed, names each leaked process (pid and command,
+  captured before the supervisor's kill) and skips the log excerpt, which
+  only holds RSpec output.
+- Engine setup load failures are reported clearly instead of as a bare
+  quit (#378): when RSpec dies while loading spec files, the error names
+  the files that failed to load, parsed from RSpec's own load-failure
+  output, and suggests the remedy - exclude the broken subtrees with
+  `--exclude-pattern` (for a Rails engine's embedded spec/dummy) or name
+  the suite with `--test`.
+
+- A spec file whose later examples rely on state left by earlier ones no
+  longer turns its mutants into errors (#557). When a covering example
+  fails even with the method unchanged, saboteur retries once with the
+  file's examples in defined order, from the start through the last
+  covering example. The kill stands only if that run passes unchanged.
+
+- Spec and test files vendored under `lib/` (capybara ships its driver
+  suite at `lib/capybara/spec/**`) are no longer swept into the default
+  mutation scope (#504): the default exclude now shields
+  `lib/**/spec/**`, `lib/**/test/**`, `lib/**/tests/**` and the
+  `*_spec.rb` / `*_test.rb` / `test_*.rb` shapes under `lib/`. A config's
+  own `c.exclude` replaces the shields wholesale, and the shields never
+  trip the stale-pattern warning.
+
+- A --since run whose changed lines sit inside a heredoc now says so
+  (#467). Code embedded in a string - a class_eval/module_eval argument or
+  a template constant - evaluates methods the static walk cannot see, so
+  the generic "may not parse, or every change may sit outside a method"
+  hint misdiagnosed it; the warning now names the files and the
+  code-in-a-string blind spot.
+
+- The "nothing to mutate" note on an empty selection now prints only
+  once (#468). An empty-selection run already ends with the
+  "0 subjects, 0 mutants" summary, and announcing the note again as a
+  report warning at the end of the run read like a second failure; it
+  is now a one-time inform when nothing has a subject.
+
+- `--incremental` no longer reuses a stored verdict after the project source
+  set changes: a file added after the coverage map was built (a conditional
+  require, a Zeitwerk autoload) can load into a mutant run unseen, and the
+  reused verdict read as a false green. The set is paths only; content edits
+  to other files stay the documented cross-file tradeoff (#396).
+- A factory assigned inside `class << self` now keeps its own scope in the
+  owner path, so a constant defined there is named after the factory's
+  singleton: `Host::W.singleton_class::V#n`. An outer factory with no
+  `class << self` of its own still opens no scope, even when a `class <<
+  self` encloses it (#438).
+
+- A class factory assigned inside `class << self` no longer shares its
+  method ids with a same-named factory in the class body (#406). The two
+  unrelated classes each keep their own subjects: the singleton-side one is
+  now named `Host.singleton_class::Widget#doubled`, so reports, `--subject`
+  filters, ignore entries and the unchanged-syntax comparison can name it.
+- `--test-command` keeps env-exported bundler settings the child needs:
+  `Bundler.with_unbundled_env` strips every `BUNDLE_*` key, so a
+  shell-exported `BUNDLE_PATH` (common in CI without a `.bundle/config`)
+  left the child's bundler unable to find the app's gems and the run
+  failed at baseline (#449). Values present in the pre-bundler
+  environment are re-added; bundler-activated values and anchor keys
+  stay dropped.
+- `--test-command` no longer inherits bundler anchors (`BUNDLE_GEMFILE`,
+  `BUNDLE_BIN_PATH`, `BUNDLER_SETUP`, ...) from a `bundle exec` parent or
+  an exported shell environment (#435). The anchored child resolved the
+  project gem from the real tree, never exercised the mutated copy, and
+  reported every mutant Survived; the child now gets the unbundled
+  environment and resolves its Gemfile from the mutated copy.
+- Test selection consults `config/saboteur_custom_map.rb` again (#369).
+  The map is the documented escape hatch for layouts the naming guess
+  cannot match, but guess-tests never called it, so a mapped file still
+  stopped the run as unmatched. A matching entry now wins over the naming
+  convention, its specs run as the inferred ones, and an empty entry marks
+  the file intentionally untested so it needs no inferred spec. The map is
+  now documented in the README. Mapped spec values that are globs are
+  expanded against the project root (the literal glob string never
+  reached RSpec), a winning entry whose specs match no file stops the
+  run with a config error naming the entry, and an empty entry's file
+  is dropped from mutation with a named diagnostic instead of running
+  the whole suite (#369 review).
+
+- The marker sweep no longer kills a marked process it cannot identify
+  (#389). A process that started before the run's root carries the marker
+  only through an exec chain the run did not spawn, so it is left alone,
+  and an escapee is signalled only when a fresh snapshot shows the same
+  pid still owned by the same start time, so a recycled pid is never
+  killed by mistake.
+- The spec-name guess now tries the underscored require name of a dashed
+  path: `lib/acts-as-taggable-on/x.rb` finds
+  `spec/acts_as_taggable_on/x_spec.rb` (and the `spec/lib/` form) instead
+  of stopping on an unmatched file (#383). The literal dashed name still
+  wins when both exist.
+
+- Factory-block subjects resolve to the right owner (#352). A class factory
+  assigned inside `class << self` binds its constant on the singleton
+  class, so re-evaluation now resolves a factory constant after a sclass
+  scope there instead of raising "cannot resolve" for every mutant of its
+  methods. And a constant or keyword class inside a factory block binds on
+  the enclosing lexical scope: `FactoryProbe::Nested::RULES` and
+  `M::HELPER` are now ordinary subjects under their lexical owner instead
+  of a phantom `FactoryProbe::Outer::Nested::RULES` skipped as defined
+  inside a block.
+- Constants assigned inside `class << self` are now named with their real
+  owner, the singleton class (`Host.singleton_class::RULES`), instead of the
+  attached class (#380, #390). A same-named constant in the class body no
+  longer collides with it or triggers a false "assigned more than once"
+  refusal. Read matching follows: reads inside `class << self` still count
+  toward the attached class's constant through singleton ancestry, and a
+  singleton-class write shadows the attached class's constant for reads
+  below it.
+
+- A spec file that calls `exit` at load now refuses the run with a
+  clear diagnostic instead of terminating the loader mid-require (#411).
+
+### Changed
+
+- The dirty-tree warning splits its count (#309, #316): changes inside
+  the mutation scope (the Ruby files the configured include and
+  exclude select; source operands narrow the run after the warning),
+  outside it, and saboteur setup files (the config file the run reads, a
+  `BUNDLE_GEMFILE` trial Gemfile and its lock), each as tracked and
+  untracked, naming up to five scope and setup paths. The groups add up
+  to the count. A tree of untracked notes or trial setup files no longer
+  reads like application edits about to be mutated.
+- A broken `.rb` symlink under `include` (dangling, a loop, or through a
+  regular file) is skipped instead of ending the run with an internal
+  error: it has no real path, so it is not mutation source (#503).
+- The `each`/`map` method swap is no longer emitted where the call stands
+  as a non-last statement (#399): its return value is discarded there, and
+  both names run the same block, so the swap is treated as equivalent.
+  The last statement of a body and calls nested inside an
+  expression stay swappable, as does any call on a lazy receiver:
+  lazy.map defers its block, so the swap is not equivalent there (#431).
+  Only a `.lazy` in the receiver chain is detected: a lazy enumerator held
+  in a variable, parameter or instance variable is not, and its swaps are
+  suppressed.
+  The discard analysis now recurses through branch tails: an each/map call
+  that is the last expression of a discarded if/elsif/else/unless/case/when
+  branch, begin/rescue body, or while/until body is suppressed too (#440).
+- A `--since` run where only some changed files have a guessed spec now
+  runs the mapped subset with a loud warning per unmapped file instead of
+  stopping with "so nothing ran"; the stop message and the warning name
+  same-basename specs found under `spec/**`, so the file can be passed to
+  `--test` without hunting; a basename containing glob metacharacters is
+  matched literally, never as a pattern. A run with no guesses at all
+  still stops, as
+  do full runs, `--subject` runs, and any run with a `--threshold` or a
+  `--max-*` gate, since the gate would judge a score the unmapped file
+  never joined (#370).
+
+- A `--since` run now stops when every changed source file sits outside the
+  include scope (#483), naming the hidden files and the ways out (extend
+  `include`, or `--test` the specs). The old fallback ran the whole suite
+  against zero subjects - the slow full run the `pr` preset exists to
+  avoid - and its message read as if the diff had touched no source.
+
+- The rerun and replay commands in the Next steps footer and the agent
+  protocol leave out an empty `--operators` or `--exclude-operators` list
+  that was not typed on the command line (#317): the config the command
+  reads again supplies the same empty list. A typed empty list stays, since
+  it may clear a configured value, and non-empty lists stay as before.
+- `--since` no longer treats a line whose only change is layout as
+  changed (#313). Wrapping existing statements in a block used to put
+  every re-indented statement in scope; now only the new block lines and
+  real edits get line-level mutants. A line is layout-only when
+  `git diff -b` pairs it with a base line and Prism lexes both to the
+  same tokens, so whitespace inside strings, heredocs and regexps, and a
+  moved `__LINE__`, still count as changes.
+- `--since` runs every spec file the diff adds or changes next to the
+  inferred specs (#307). A request or controller spec whose name maps to no
+  changed file used to be left out, so a mutant only it killed was reported
+  as a survivor. A spec the diff adds beyond inference runs only when the
+  configured RSpec suite loads it (its pattern, exclude pattern and default
+  path) and it is a regular file; inferred specs run as before. A changed
+  `*_spec.rb` that does not run, or that the diff deletes, is named with
+  the reason, also before a stop on an unmatched file. `--test` and
+  `--all` are unchanged.
+
+- **Breaking change:** the pr preset no longer accepts a budget-stopped
+  run by default. It exits 4; pass `--max-duration-ok` explicitly to
+  accept the ordinary verdict. The terminal prints how many planned
+  mutants did not run, or says the count is unknown when planning did not
+  finish. (#654)
+
+
+### Fixed
+
+- A non-Rails suite that connects ActiveRecord to sqlite `:memory:` and
+  loads its schema at require time no longer gets a bare "Could not find
+  table" baseline failure (#387): every forked child reconnects to a fresh,
+  empty in-memory database, so the child now detects that shape and the
+  refusal names the cause and the remedies - move schema setup to
+  `before(:suite)`, or load it in an `after_fork` hook (README recipe
+  added). The Rails integration's per-child snapshot is unchanged.
+- `saboteur run --test a_spec.rb b_spec.rb` refused: spec files in the source scope now fail as a
+  usage error pointing at repeating `--test`, instead of a green run that mutates nothing; the
+  `--since` "no subjects covering" warning names the misuse when every file is a spec file (#371).
+- A mutant's test that daemonizes - forks an intermediate child that calls
+  `setsid` and exits at once - no longer leaves a sleeping grandchild the
+  supervisor never kills (#365). The tree poll can miss a descendant that
+  leaves the process group and loses its parent between two polls, so
+  every child now carries a unique marker in its environment (which
+  reaches exec'd descendants) and in its comm via `PR_SET_NAME` (which
+  reaches fork-only ones), and the end-of-run kill also sweeps the process
+  table for the marker. Linux only for now; a self-renaming daemon still
+  needs the CPU backstop.
+
+- The Landlock ABI probe no longer flakes fail-closed with "Success -
+  landlock_create_ruleset probe" on runners where the first errno read
+  gets clobbered between the syscall and the read: the errno reader is
+  built before the probe, and a failure return paired with errno 0
+  (impossible from a real kernel answer) is probed once more. Genuinely
+  unknown errors still fail closed.
+- `rspec_args` that hold only options and their values (such as
+  `["--require", "spec_helper"]`) no longer leave the suite with no
+  files under `exe/saboteur`: RSpec adds its default path only when `$0`
+  is `rspec`, and the value was taken for a path. saboteur now adds the
+  default path whenever RSpec's own parse finds no file or directory to
+  run, and a `--default-path` from `.rspec` wins over `spec`.
+- `script/preflight` no longer loses why a git probe died: a probe
+  whose child never ran git (the spawn failed, or a signal killed
+  the forked child, as macOS does pre-exec under memory pressure)
+  is retried once and, when it still fails, the error names the
+  cause instead of printing an empty detail; a failure git
+  reported itself is raised at once with git's own words (#319).
+
+- The whole-suite empty-coverage guard no longer passes when the map holds
+  spec-file lines only: the recorder maps the suite's spec files alongside
+  the included files, and the guard checked whole-map emptiness, so a suite
+  exercising none of the included files still recorded its own spec code
+  and the run exited 0 instead of 3. The guard now checks each included
+  file.
+
+- Coverage-guided selection no longer drops a mutant's killing tests when a
+  `case` has a `when X` arm whose body is bare `nil`: Ruby spans that arm
+  from the `when` to the case's end, containing its sibling arms, and the
+  recorder stored the span as-is, so edits inside the sibling arms were
+  narrowed to the nil-arm's takers. Sibling arms are disjoint by
+  definition; a span containing one of them is now rejected when the map
+  is recorded (coverage map format 9).
+
+- `script/preflight` full mode no longer rejects its own RSpec report: the
+  fd3 shim now attaches a dedicated JSON formatter to the pipe instead of
+  redirecting RSpec's output stream, so a project's progress formatter
+  (`.rspec` `--format progress`) and spec output stay on stdout and cannot
+  corrupt the report.
+
+- `--incremental` no longer reuses a verdict when a file the covering
+  tests touched changed: the dependency files from the run's coverage map
+  join the verdict fingerprint (#197). The same holds for a dependency
+  with only method coverage (an endless def), a file that ran while the
+  app loaded, a loaded source the coverage map never observed, and a
+  helper required lazily inside a test outside the include list, which
+  the coverage build now records in the map so its changes invalidate
+  verdicts too (#344, #353; coverage map format 10).
+- `--test-command` survivors no longer carry the `missing_test`
+  classification: the run's only recorded evidence is the pseudo-test id,
+  which is not real coverage (#305).
+- `--test-command` on macOS no longer refuses every tree containing an
+  internal symlink: the disposable copy root is canonicalized before
+  symlink targets are judged against it (/var vs /private/var) (#305).
+
+- Suites that turn warnings into errors (`--warnings` plus a raising
+  `Warning.warn` or `Warning.process` handler, dry-rb/hanami-style) no
+  longer error every mutant: the re-evaluation's own "method redefined"
+  notice is silenced while the mutant is installed, the same guard the
+  whole-file strategy already had (#603).
+
+- A mutant reported Survived when the suite itself replaced its
+  definition mid-run: a `before(:each)` that re-loads the mutated source
+  file (rolify-style `load "lib/..."`, #597) puts the original back
+  before any test calls it, so every selected test passing proved
+  nothing. The child now records which definition the mutant's
+  evaluation installed and compares it with what is in place after the
+  tests; a positively identified different def marks the mutant
+  Unreachable (out of the score), never Survived, only when no test ever
+  invoked the mutant, and the warning names the re-load site. A run
+  where every mutant ends Unreachable exits 3 instead of going silently
+  green. (#662)
+
+- A scoped (`--since`) run that skips a subject for no coverage now
+  names the loaded specs (or says none) and points at `--test`. Coverage
+  in sibling spec files may not have been loaded; the existing exit-3
+  gate is unchanged. (#636)
+
+
+### Added
+
+- guess-tests now tries the flattened spec root and a `spec/unit/` prefix
+  after the mirrored guesses: `lib/pundit/policy_finder.rb` finds
+  `spec/policy_finder_spec.rb` and `lib/aasm/base.rb` finds
+  `spec/unit/base_spec.rb`, so `--subject` and `--since` stop hard-stopping
+  on pundit, aasm and shoulda-matchers style layouts (#394, #370, #393).
+- Methods defined in the four core class factories (`X = Data.define(...)`,
+  `Struct.new`, `Class.new`, `Module.new` with a block) are mutation
+  subjects instead of skipped subjects (#290): the finder names the
+  generated class as the owner, and the mutant is re-evaluated through
+  `X.class_eval`, leaving the generated class itself untouched. Defs in
+  any other block stay skipped as "defined inside a block".
+- `define_method(:m) { ... }` calls with a literal name and a block are
+  mutation subjects (#194): the block body is mutated and the whole call is
+  re-evaluated on the enclosing owner. A computed name, an explicit
+  receiver, or a lambda argument stays unsupported, and a call in a block
+  whose owner is unknown keeps the "defined inside a block" skip reason.
+
+- A fault-injection e2e probe now pins cache-dir removal during the
+  baseline window (#300): deleting `.saboteur` while the baseline holds
+  the suite open changes neither the exit code nor the run evidence -
+  later phases recreate the directory and the report holds the same
+  verdicts; only the in-flight baseline log is lost. Other windows are
+  not pinned to recover (a missing mutant log fails the run by design),
+  so stop the run before deleting the cache, as `saboteur help` says.
+
+- `saboteur doctor` now documents its version scope (#318): it certifies no
+  versions of Rails, databases or application tools saboteur never invokes.
+  A mismatched tool the suite loads still surfaces through the boot check's
+  LoadError or the baseline refusal with the tool's own output; a narrower
+  doctor check first needs the tool name, the expected and actual versions
+  and the failure output, recorded on the issue.
+- `--test-command CMD` / `c.test_command`: run an external command per
+  mutant and take its exit status as the verdict - for apps that cannot
+  load inside saboteur's Ruby. Serial, no coverage, unsandboxed. Mutants
+  are applied in a fresh disposable copy of the tree per execution - the
+  runner's own writes never touch the real files or follow symlinks - and
+  the command's process group is terminated on every exit path. One
+  budget-bounded neutral preflight checks the command on an untouched
+  copy before any mutant exists; the shell's 126/127 read as setup
+  errors, blank and non-string commands are rejected, and nested
+  saboteur runs are refused (#140, #305). The preflight runs under an
+  absolute deadline admitted after the tree copy, and a spent budget
+  stops the run as budget-exhausted rather than a command failure.
+  Internal symlinks are rebuilt as relative links inside the copy, so an
+  alias sees the mutant while nothing can link out; escaping or looping
+  links refuse the run. Copy and write failures become error outcomes
+  with bounded context instead of crashing the run. Output capture is a
+  bounded in-memory ring buffer, scrubbed to valid UTF-8 for reports,
+  and its drain is time-bounded so a session-escaped descendant holding
+  the pipe cannot stall the run. Subjects outside the project root are
+  refused.
+- Survivor classification labels in the JSON report (#192): each survivor
+  carries `classification` - `likely_equivalent` when the mutant compiles
+  to the original's instructions, `arid` when every line an edit touches
+  matches an arid pattern, `missing_test` when a test covered the line
+  and passed. The HTML report badges each survivor with the same label
+  and the agent JSON carries it on each shown finding. Labels are
+  heuristics for triage order only, never a diagnosis: scores and the
+  exit code never change.
+- `--since` mutates changed entries of constant hash and array literals:
+  the assignments join the diff scope as subjects, `pair_removal` edits hash
+  entries, the new default-on `element_removal` operator edits array
+  elements (in methods too, so array literals grow mutant totals the way
+  hashes do), and the tests are the specs covering a read of the constant.
+  Unsupported forms (namespaced targets, `||=`/`&&=`, non-literal values,
+  condition-guarded writes, or a constant written more than once in one
+  file counting every write) are named in the diagnostics instead of being
+  mutated or reported survived (#306).
+- Constant replay vets the whole file: `--since` replays a constant's file
+  only when its load-time code is limited to requires, pure defs,
+  class/module nesting and literal assignments and trips no hazard denylist
+  entry; anything else needs the constant listed in `c.whole_file` (the
+  existing whole-file opt-in) or the literal moved into its own file.
+  Constants whose only reads capture the value at load time elsewhere -
+  including a capture inside a boot-time block - are dropped with a
+  diagnostic. Spec files count as consumers: the coverage map records spec
+  line hits, directory test paths and the default spec tree feed the
+  consumer scan, `element_removal` honors the arid policy, arid patterns
+  screen constant entries too, and constant mutation respects `c.sources`
+  (no `builtin`, no constant mutants) (#306, #319).
+- Constant replay hardening from the #319 lens review: `require` and
+  `require_relative` count as vetted load code only with a plain
+  literal-string argument and no block, so `require(build_path)` no longer
+  reruns helper code on every mutant; rooted constant writes (`::RULES`,
+  `::Shop::RULES`) share one identity with the bare write, and an
+  unrooted qualified write (`Shop::RULES`) resolves through the lexical
+  scope, so it demotes every literal on its scope chain it may overwrite
+  (`Shop::RULES` inside `module Outer; module Shop` overwrites
+  `Outer::Shop::RULES`); either way a re-assigning write demotes the
+  first literal to unsupported instead of leaving it scored; the --all consumer scan reads
+  the configured integration's loaded spec files instead of guessing the
+  conventional spec tree; and an arid pattern that cannot judge an entry's
+  bytes (binary source against a UTF-8 pattern) keeps the mutant instead
+  of raising (#319).
+- Fault-injection e2e specs pin exit 3 with a clear, test-blame-free message
+  when the cache dir is read-only, is occupied by a regular file, or holds an
+  unwritable baseline log (#251).
+- A dropped mutation that does not parse is now named in the warnings with
+  its subject and operator instead of only counting toward invalid
+  mutations (#116).
+- `docs/stability.md`: the agent JSON payload and the exit codes are stable
+  public APIs with a deprecation process, pinned by a new contract spec; a
+  governance note in CONTRIBUTING covers maintainer availability (#249).
+- `saboteur doctor` says plainly on macOS that mutants run unsandboxed,
+  advising a container for filesystem containment and network denial or
+  stubbing for real-API risk, and the README carries a short per-platform
+  sandbox and network statement (#247).
+- Ignore-list entries accept a triage `state:` - `accepted_equivalent`
+  (the default) and `wont_fix` suppress the survivor's exit failure (it
+  still counts in the score), `todo` records the decision to fix and keeps
+  the survivor counting as an unignored survivor. The HTML report badges the
+  state; in the JSON report `accepted_equivalent` keeps the plain
+  `ignored: <reason>` while `wont_fix` and `todo` are labelled
+  (`ignored: <reason> (wont_fix)`, `todo: <reason>`), and all three keep
+  status `Survived` (#155).
+
+### Removed
+- The stale self-deprecating benchmark claims in the README ('rerun
+  pending'): speed and memory numbers now live only with the harness and raw
+  data that reproduce them, or are framed as dated history (#243).
+
 ## [0.7.0] - 2026-10-16
 
 ### Upgrade notes