saboteur 0.6.0 → 0.7.0

data/README.md

@@ -47,11 +47,17 @@ accepted mutants or change their scores. See [Opt-in survivor baseline](#opt-in-
 
 ### The unchanged suite is checked first
 
-Every run with selected subjects runs the loaded unchanged suite twice (the specs chosen with `--test`, if given) in fresh
+Every run with selected subjects runs the loaded unchanged suite twice (the specs chosen with `--test` if given,
+otherwise the inferred specs) in fresh
 supervised children before coverage lookup or incremental verdict reuse. This
 costs two suite runs even on a cache hit, plus a coverage-building suite run on
-a cache miss. Both baseline passes must be green, complete and in the same
-RSpec order at the run seed. A failure exits 3, stops mutation, prints the failing example ids and the first ten lines of the
+a cache miss. Before the first pass, a run over the whole suite announces the example
+count and the real number of full passes (a cached map only counts as
+reused when it loads clean); once the first baseline pass is timed, the
+run estimates the time left for the remaining baseline and coverage
+passes from it - mutation time is not part of that estimate. Past 1,000
+examples the announcement also names `--test` as the way to scope the run. Both baseline passes must be green, complete and in the same
+RSpec order at the run seed. Set `c.baseline_passes = 1` (or `--baseline-passes 1`) for a faster PR loop: the run says so up front and gives up the order-stability comparison between passes (#55). A failure exits 3, stops mutation, prints the failing example ids and the first ten lines of the
 failure inline, and names the log and fix. Long phases
 print their elapsed time about every 30 seconds, with the examples finished so far, the percentage and a rough estimate of the time left (it assumes equally long examples) once the suite child has logged its first count, and each phase's log holds
 the suite's progress and full failure detail. Each suite pass
@@ -82,21 +88,24 @@ hazard guard is a syntactic filter. It recognizes destructive calls written
 as direct calls: `FileUtils.rm*`/`remove_entry*` (also as bare names under
 `include FileUtils`), `File.delete`/`unlink`, `Dir.rmdir`/`delete`/`unlink`,
 `rmtree`, `system`/`exec`/`spawn` (bare or on `Kernel`/`Process`), backticks
-and `%x`, `IO.popen`, any `Open3` method, and `open` with a leading `|`. It
+and `%x`, `IO.popen`, any `Open3` method, `open` with a leading `|`, and
+`send`/`public_send`/`__send__` with a literal symbol or string selector
+naming one of these (dynamic selectors stay out of scope). It
 suppresses any mutant that would leave such a call in place while altering
 code inside it or anywhere else in the same method. A mutant that removes
 every hazardous call in the method still runs, provided its replacement
 introduces no new hazard. The match is by name on the written call: calls
-reached through aliases, variables, `send` or other indirection are not
+reached through aliases, variables or other indirection are not
 recognized, so the guard cannot promise to find every destructive call. The
 summary reports how many mutants were suppressed. Extend or replace the list
 with `c.hazard` (same tag shapes: `"FileUtils.rm_rf"`, or a bare name like
 `"system"`); `--allow-hazardous` runs the suppressed mutants anyway.
 
 Behind the guard, a canary snapshots the tracked files (or every file,
-outside a repository) before mutating and re-checks after each method's
-mutants. If anything vanished, the run aborts with exit 3 and names the most
-recent mutant's digest. That check happens after the damage and restores
+outside a repository) before mutating and probes the snapshot after every
+mutant - a cheap stat pass, no tree walk. If anything vanished, the run
+aborts with exit 3 and names the digest of the mutant that just ran, not
+the method's last mutant. A fuller check still runs after each method. That check happens after the damage and restores
 nothing; it limits how far a bad mutant gets. Recover from your own backup,
 a fresh checkout or a reclone - a deleted `.git` or uncommitted work is gone
 unless you have another copy. The canary is the backstop for the destructive
@@ -104,8 +113,18 @@ forms the syntactic guard cannot see.
 
 On Linux 6.2 and later (Landlock ABI 3) each mutant child also runs under
 a Landlock sandbox: the child cannot create, write, rename, unlink or
-truncate files in the project tree, except `tmp/`, the cache dir and the
-system temp dir, plus anything in `c.sandbox_writable`. Every other path
+truncate files in the project tree, except `tmp/` and the
+system temp dir, plus anything in `c.sandbox_writable`. The project
+`tmp/` grant applies only when `tmp/` already exists - the run never
+creates it for the grant - so create it before the run if your suite
+writes there, or grant the directory with `c.sandbox_writable`. The cache dir
+is denied too - a mutant cannot delete the baseline, the reports or
+other children's logs; its own log is opened before the fork and
+arrives as an inherited descriptor. Grants are additive, though: a
+cache dir placed inside `tmp/`, the system temp dir or a
+`c.sandbox_writable` entry stays writable, and the tool cannot deny
+what another grant allows - keep the cache outside every grant for
+the isolation to bite. Every other path
 is denied for writing, `/dev/shm` and `/dev/tty` included; `/dev/null`
 stays writable. Inherited
 descriptors already open for writing outside the granted dirs are closed
@@ -123,9 +142,9 @@ grant that directory with `c.sandbox_writable` or opt out with
 sockets and IPC are never restricted - and a checkout inside the system
 temp dir cannot be protected, because everything under it stays writable
 so that real test suites keep working - the run warns when the effective
-write set (every grant realpath'd, the cache dir and the system temp dir
+write set (every grant realpath'd, the system temp dir
 included) contains the project root, however it happened: a checkout
-inside the system temp dir, `cache_dir = "."`, a symlinked `tmp`, or an
+inside the system temp dir, a symlinked `tmp`, or an
 overlapping `c.sandbox_writable` grant. `c.sandbox = "strict"` refuses to
 run at all in that situation, since the sandbox would protect nothing.
 The sandbox applies to every mutant
@@ -255,10 +274,12 @@ above the limit, with `exitCause` `maxTimeouts` or `maxErrors` in the JSON repor
 their own causes when they fail too. The gates cannot be combined with `--agent`.
 The GitHub Action has no input for them yet.
 
-Other flags: `--jobs N` (concurrent workers), `--timeout-factor N`,
+Other flags: `--jobs N` (concurrent workers), `--timeout-factor N`, `--baseline-passes N`, `--max-duration DUR`,
 `--config PATH`, `--integration NAME`, `--reeval class_eval|nesting`,
 `--json PATH`, `--no-cache` (rebuild the coverage map), `--allow-focus`.
 
+Two presets bundle the common loops (#244): `saboteur pr [REF]` is the pull-request loop - `--since REF` (default `main`), one baseline check and a ten-minute `--max-duration` that opts out of the budget-specific exit 4 (normal and incomplete verdicts still fail the run); `saboteur audit` is the whole project: `--all`, all operators, both baseline checks and both reports (an explicit `--test` replaces the injected `--all`; configured selection limits such as `since`, subjects, exclusions and a configured budget still apply). The run prints the expansion up front, and an explicit flag after the preset wins.
+
 A stray `fit`, `fdescribe` or `:focus` example, with `filter_run_when_matching :focus`, makes RSpec skip
 every other example. The baseline stays green and the score would cover only the focused ones, so
 saboteur exits 2 and names the focused examples. Remove the focus, or pass `--allow-focus` (config
@@ -269,24 +290,58 @@ check compares what RSpec runs with what it would run without the stray focus, s
 
 For pull requests, start with `--since` against your target branch. This is a
 workflow recommendation, not a CLI default: plain `run` still checks the whole
-configured project. To scope the specs as well, pass them with `--test` and no
+configured project. To scope the specs yourself, pass them with `--test` and no
 source operands: `bundle exec saboteur run --since origin/main --test spec/billing_spec.rb`.
-With `--since` and no `--test`, the run warns before it starts that the two baseline passes
-run the loaded suite (a cold coverage cache adds one more pass), and how to
-scope them.
-
-`--since origin/main --guess-tests` does that scoping for you: it picks the spec
-named after each changed source file (`lib/a/b.rb` runs `spec/a/b_spec.rb`; `app/`
-files and `spec/lib/` work too) and runs only those for the baseline passes, the
-coverage pass and every mutant, as `--test` would. It is a naming guess, not
-coverage: a spec that reaches the changed file only through another file does not
-run: a mutant only that spec would kill can survive, and a line that none of the
-guessed specs executes is reported as NoCoverage. The agent JSON records the guessed specs as its
-`tests`, so its follow-up commands keep the same `--test` scope (with `--no-guess-tests`, so a `guess_tests`
-in the config file cannot conflict) instead of widening to the whole suite. If any changed file has no such
-spec, or nothing changed, the whole suite runs as before and the run says so.
-`--guess-tests` needs `--since` and cannot be combined with `--test`. Keep whole-project runs on main: diff mode does not check every method affected by a
-dependency change. [The pull-request guide](docs/pull-requests.md) covers
+A changed Ruby file whose changed lines cover no method mutates nothing; the run
+warns and names the file instead of silently selecting zero subjects. An untracked
+file inside the configured `include` set counts as fully changed: a brand-new,
+never-committed source file is selected in full rather than silently skipped,
+because a diff cannot see it (#295). The union reads race-free
+(O_NOFOLLOW/O_NONBLOCK, validated on the opened descriptor) and streams its
+line count, so a swapped-in symlink or FIFO is skipped quietly and a huge
+untracked fixture outside `include` is never even opened. Comment-only
+or formatting-only changes within discovered methods are skipped without this
+warning; the run reports those skipped methods. A changed Ruby file that an
+include pattern covers but `c.exclude` removes mutates nothing either, and the
+run warns and names up to five such files - narrow or remove the `c.exclude`
+entry, or pass the file as a positional source operand (configured excludes are
+then ignored). `--subject` cannot help here: it filters subjects inside the
+files left after excludes.
+
+Without `--test`, the run infers the specs: the spec named after each mutated
+file (`lib/a/b.rb` runs `spec/a/b_spec.rb`; `app/` files and `spec/lib/` work
+too) runs for the baseline passes, the coverage pass and every mutant, as
+`--test` would. With `--since` only the changed files count; without it every
+included file does. It is a naming guess, not coverage: a spec that reaches the
+mutated file only through another file does not run, so a mutant only that
+spec would kill can survive, and a line none of the inferred specs executes is
+reported as NoCoverage. A file needs no inferred spec when it has no mutation
+subjects (with `--since`: none on its changed lines), such as a comment-only
+change within a method or a deletion leaving only blank/comment context; the
+run says so and skips those files. When no file has a mutation subject at all,
+the run reports that there is nothing to mutate. A `--subject` run infers only
+from the named subjects' files: an unrelated spec-less file never stops a
+one-method run, and a subject file with no conventional spec stops the run
+like any other unmatched file. With `--since` only named subjects on changed
+lines count: an unchanged subject file, one whose changes sit in other
+methods, or one with a comment-only change is skipped, not stopped.
+
+A file that needs a spec and has none stops the run before it boots (exit 2)
+and names both ways out: `--test` with the specs to run, or `--all` for the
+whole suite. An unmatched file no longer silently narrows the selected source
+scope or widens the test run to the whole suite. Whole-project audits should
+use `--all` explicitly. The agent JSON records the inferred specs as its
+`tests`, so its follow-up commands keep the same scope.
+
+`--all` (config `c.test_selection = :all`) runs the whole configured suite.
+With `--since` or `--all` and no inferred or named specs, the run warns before
+it starts that the two baseline passes run the loaded suite (a cold coverage
+cache adds one more pass). `--guess-tests` is a deprecated alias for the
+default inference and `--no-guess-tests` warns and is ignored; use `--all` for
+the whole suite. `--all` cannot be combined with `--test` or `--guess-tests`,
+and `--guess-tests` cannot be combined with `--test`. Keep whole-project runs
+on main: diff mode does not check every method affected by a dependency change.
+[The pull-request guide](docs/pull-requests.md) covers
 checkout history, a GitHub Actions example, configuration and limits.
 
 Doctor warns when an ignore subject matches no method discovered in the included
@@ -326,8 +381,21 @@ printed once as `path:line in Subject`, with the source line and the tests that
 covered it, then one compact line per mutation: `operator original -> replacement digest`,
 and a hint on what kind of test would kill it. The summary has the counts per
 status, the score, a table of scores per file (worst first) and a one-line
-legend. `--verbose` adds the score split, mean time, whole-body score and
-kill causes. Colour is on when stdout is a terminal and `NO_COLOR` is not set;
+legend. When survivors remain, the Next steps footer prints the complete
+replay command - ref, subjects, specs, sources, seed and the run settings
+the agent protocol records, including the CLI-only switches that change
+candidate availability or boot (`--allow-hazardous`, `--allow-focus`) -
+shell-escaped and printed in full however long it gets, so running it
+as-is replays the survivor with the same selection. Framework and
+generation settings from the config file (arid/hazard patterns,
+whole-file, require, rspec_args, rails) ride along through the command's
+`--config` or the default config path. Only knobs that cannot change a
+by-digest replay (`--max-mutants-per-method`, `--fail-fast`,
+`--threshold`) are left out. The agent protocol instead omits a command
+longer than 1024 bytes, and the agent rebuilds it from the run's
+provenance. `--verbose` adds the score split, mean time, whole-body score and
+kill causes, and prints one line per finished subject with its result
+marks, so a survivor is attributable to a method before the run ends. Colour is on when stdout is a terminal and `NO_COLOR` is not set;
 `--color` and `--no-color` override that. While mutants run, stderr shows
 `done/total (percent) eta`: a live counter on a terminal, and dots with a
 counter every 50 mutants otherwise. Skipped and reused mutants are not
@@ -353,7 +421,13 @@ survivor's notes. The JSON report goes to `.saboteur/report.json` and a self-con
 report (one file, no scripts, no network) to `.saboteur/report.html`. Change
 the paths with `--json` / `--html` or `c.json_report` / `c.html_report` in
 `config/saboteur.rb`; set either to `nil` to turn that report off. The two paths
-must differ. The HTML page shows the covered mutation score
+must differ. When an artifact cannot be written - a read-only tree inside a
+sandboxed run - the HTML report and the score history warn and the run still
+exits by its results. An explicitly requested JSON report (`--json` or
+`c.json_report`) is different: it is the completion evidence an outer harness
+trusts, so a failed write fails the run with exit 3 rather than leaving a
+stale or partial file presented as this run's; the default
+`.saboteur/report.json` stays best-effort. The HTML page shows the covered mutation score
 `(killed + timeout) / (killed + survived + timeout)`, which leaves NoCoverage,
 RanAtLoad and Unreachable out and keeps survivors accepted on the ignore list
 in the denominator. A tool
@@ -415,10 +489,33 @@ changed line and prints none.
 
 New to survivors? The [reading survivors guide](docs/guides/reading-survivors.md) walks one from the diff to the test that kills it.
 
-Exit codes: 0 no survivors (or all on the ignore list), or the score meets
-`--threshold`; 1 survivors, or the score is below `--threshold` or missing;
-2 bad configuration or a missing source or test; 3 the tool failed (with
-`--threshold`, also any errored or resource-limited mutant).
+Exit codes: 0 no survivors (or all on the ignore list), or the score
+meets `--threshold`; 1 survivors, or the score is below `--threshold` or
+missing; 2 bad configuration or a missing source or test; 3 the tool
+failed (with `--threshold`, also any errored or resource-limited
+mutant). Unexpected `StandardError` or `LoadError` failures print
+`saboteur: internal error (...) - please report it` and exit 3, rather
+than dying with a bare stack trace and an accidental exit code. The full
+backtrace lands in `<cache_dir>/internal-error.log` (default
+`.saboteur/`), and `--verbose` also prints it to stderr. When the cache
+dir cannot hold the log, a private pid-keyed fallback in the system temp
+dir takes it (created with `O_EXCL | O_NOFOLLOW`, mode 0600, so it never
+follows or overwrites a pre-existing path). Logs are always written
+private, and a nested run reads them back only through a no-follow,
+non-blocking descriptor - a regular file, same owner, no group/other
+bits (or, where the platform lacks those flags, only the `O_EXCL` temp
+fallback is written and no excerpt is read). The message names the log only
+after a successful write: an unset `cache_dir`, or a log writable nowhere,
+leaves the one-liner standing alone. The executable
+loads the crash reporter before the CLI, so a failure while it is
+loading, being built, or parsing arguments gets the same report;
+failures earlier than that - coverage setup or the reporter's own load -
+get only the bare one-liner and still exit 3. Once the crash
+reporter has loaded, agent mode reports the same failure as agent
+JSON, using a standalone payload if the agent reporter has not
+loaded. Before the crash reporter loads, only the one-line
+diagnostic and exit 3 are available.
+`--max-duration 10m` budgets the whole run, baselines included: the budget is checked before every subject and between mutants inside one, so past the budget the run finishes only the mutant in flight (bounded by its timeout), then stops before the next subject. Admitted phases (baseline checks, the coverage map build) are capped at the time left, as are verdict checks and timeout calibrations - admission is per check and per sequence, so nothing forks with no time left. A phase that hits only its budget-shortened cap stops the run as budget-exhausted rather than failing as a suite error. A kill or timeout the budget leaves uncheckable is reported as `unverified` - outside the score, never cached, listed under the early stop - instead of becoming an error, reports which selected subjects never ran and which mutants were omitted, marks the JSON and agent output partial (`earlyStop.reason: "max_duration"`), and exits 4; `--max-duration-ok` (or `c.max_duration_ok = true`) leaves the exit to the plain verdict instead, which can still fail the run - 1 on survivors, 3 when the budget stopped the run before any mutant verdict was verified. In agent mode the exit code stays verdict-driven and the budget shows up in `incomplete[]` and `earlyStop` (#245).
 
 ### Rejected kills
 
@@ -452,6 +549,9 @@ Saboteur.configure do |c|
   c.sandbox_writable = []        # extra dirs mutant children may write, e.g. ["db", "log"]
   c.ignore_file = "config/saboteur_ignore.rb"
   c.seed = 1                     # Ruby's random seed in every test run
+  c.baseline_passes = 2          # unchanged-suite checks before mutating; 1 skips the order-stability check (#55)
+  c.max_duration = nil           # wall-clock budget in seconds, e.g. 600; an exhausted budget exits 4 (#245)
+  c.max_duration_ok = false        # true: an exhausted budget does not fail the run
   c.allow_focus = false          # true runs a suite narrowed by fit/fdescribe/:focus instead of exit 2
   c.fingerprint_extra = []       # extra globs whose contents invalidate caches, e.g. ["data/*.csv"]
 end
@@ -670,6 +770,27 @@ An entry without a reason is rejected.
 saboteur needs Ruby's `Coverage` for itself. Disable SimpleCov for the run
 (most projects already guard it with an environment variable).
 
+### Threads alive at fork time
+
+Threads do not survive `fork`, so a run names any that are alive when the
+workers fork. Two are well known:
+
+- `AR Pool Reaper` only maintains the parent's connection pool. It is
+  expected harmless when children reconnect the database after fork -
+  saboteur's rails mode does exactly that. Without verified
+  reconnection, do not assume the inherited connection state is safe.
+- `DEBUGGER__::SESSION@server` is the debug gem's remote console. What
+  it does in children depends on `RUBY_DEBUG_FORK_MODE`: with `parent`
+  no debugger runs in children; with `child` or `both` (the gem's
+  default) the debugger activates in children and can pause or
+  interfere with supervised mutation runs. For unattended runs, do not
+  start the remote debugger at all: drop `RUBY_DEBUG_OPEN` or require
+  `debug` without `:open`.
+
+Any other thread gets a generic caveat: a thread that does not run in a
+child cannot do background work a mutant's test may rely on, so results
+can differ when one is left behind.
+
 ## Filter mutations
 
 The built-in source also swaps `select` / `reject` and `select!` / `reject!`.
@@ -732,6 +853,10 @@ and `tap` links are never removed. Tests can observe frozenness, copies and a
 query chain, and dropping such a link mostly yields noise, so this operator
 leaves them out. Arid statements and nested definitions are skipped.
 
+If you confirm the shorter chain is equivalent across the intended
+inputs (for example a duplicated column), simplify the code or ignore
+the mutant.
+
 Chain removal is on by default, like `argument_removal` and `pair_removal`.
 Its proposals follow the other fine proposals, with the same validation,
 deduplication and `max_mutants_per_method` cap.
@@ -786,11 +911,12 @@ Public API, stable across minor versions:
 - `Saboteur::Integration::Base` for other test frameworks (RSpec is the only one
   that ships).
 - `Saboteur.hook(:before_boot | :after_boot | :before_fork | :after_fork |
-  :around_mutant)` in files listed under `hooks:`.
+  :around_mutant)` in files listed under `hooks:`. An extensionless hooks
+  path resolves its `.rb`, the way `require` does.
 
 ## 🌍 Where it has run
 
-An early release (0.4.0). Tested on the RSpec suites of plain gems
+Tested on the RSpec suites of plain gems
 (dry-inflector, tty-color, hashie, addressable) and of two Rails 8.1 apps:
 human-essentials on Postgres (4,080 mutants, 6 workers; the 2026-10-10 run, before
 the baseline check and the coarse-gate removal) and lobsters on SQLite,
@@ -955,7 +1081,7 @@ Cache and baseline identities include the policy. Re-propose and review old surv
 
 Trust boundary: `--dry-run` never boots the app or runs its tests, but custom `sources` entries (`path.rb:ClassName`) are still `require`d to generate candidates, so their code runs. Only preview with sources you trust.
 
-`bundle exec saboteur run --list-operators` lists every builtin name and description. All builtin operators run by default, including [`range`](docs/operators/range.md), [`operator_assignment`](docs/operators/operator_assignment.md), and [`condition_negation`](docs/operators/condition_negation.md). `--operators arithmetic,comparison` or `c.operators = ["arithmetic", "comparison"]` still selects a subset; `all` selects every name. There is no opt-in tier. `--exclude-operators range,condition_negation` or `c.exclude_operators = ["range", "condition_negation"]` removes named operators from that selection; exclusion wins if a name is in both lists. An empty selection means all, while an empty exclusion means none. CLI lists replace their corresponding config lists. These controls apply to builtin operators, not custom source plugins. Selection and exclusions invalidate cached verdict identity and are carried into agent rerun/replay commands.
+`bundle exec saboteur run --list-operators` lists every builtin name and description. All builtin operators run by default, including [`range`](docs/operators/range.md), [`operator_assignment`](docs/operators/operator_assignment.md), [`condition_negation`](docs/operators/condition_negation.md), [`method_swap`](docs/operators/method_swap.md), [`operand_replacement`](docs/operators/operand_replacement.md), and [`interpolation_removal`](docs/operators/interpolation_removal.md). `--operators arithmetic,comparison` or `c.operators = ["arithmetic", "comparison"]` still selects a subset; `all` selects every name. There is no opt-in tier. `--exclude-operators range,condition_negation` or `c.exclude_operators = ["range", "condition_negation"]` removes named operators from that selection; exclusion wins if a name is in both lists. An empty selection means all, while an empty exclusion means none. CLI lists replace their corresponding config lists. These controls apply to builtin operators, not custom source plugins. Selection and exclusions invalidate cached verdict identity and are carried into agent rerun/replay commands.
 
 
 All operators run unless you select a smaller set; exclusions always remove operators from that set.

data/exe/saboteur

@@ -2,15 +2,42 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
-# Line coverage must be set up before any target code loads, so it happens
-# first. For `run` it also counts from here: what executes while the app and
+# Coverage comes first because it only measures files loaded after it -
+# the crash reporter must stay measurable - and it loads inside the same
+# guarded begin as the reporter: every later failure, even while the CLI
+# is being required, gets the full report (the bounded one-liner, the log
+# file, the --verbose backtrace and agent JSON when the CLI loaded far
+# enough). If even the reporter cannot load, a bare normalized one-liner
+# (one line, invalid bytes scrubbed, bounded length) still exits 3.
+begin
+  require "coverage"
+  Coverage.setup(lines: true, methods: true, branches: true) if Coverage.state == :idle
+
+  require "saboteur/crash_report"
+rescue LoadError, StandardError => e
+  message = e.message.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?").gsub(/\s+/, " ").strip
+  message = "#{message[0...160]}..." if message.length > 160
+  warn "saboteur: internal error (#{e.class}: #{message}) - please report it: " \
+       "https://github.com/vamsipavanmahesh/saboteur/issues"
+  exit 3
+end
+
+# For `run` coverage counts from here: what executes while the app and
 # spec files load is how ran-at-load mutants are told apart from uncovered
 # ones. The engine suspends counting right after boot and reads the
 # counters as the map's load lines (a forked child would not inherit them).
-require "coverage"
-Coverage.setup(lines: true, methods: true, branches: true) if Coverage.state == :idle
-Coverage.resume if ARGV.first == "run" && Coverage.state == :suspended
+begin
+  Coverage.resume if ARGV.first == "run" && Coverage.state == :suspended
 
-require "saboteur/cli"
+  require "saboteur/cli"
 
-exit Saboteur::CLI.new(ARGV).call
+  exit Saboteur::CLI.new(ARGV).call
+rescue LoadError, StandardError => e
+  # Agent mode is visible in the raw arguments; the CLI may never have
+  # loaded, so this scan must not depend on it.
+  agent = ARGV.include?("--agent") || ARGV.include?("--format=agent") ||
+          ARGV.each_cons(2).any? { |flag, value| flag == "--format" && value == "agent" }
+  exit Saboteur::CrashReport.call(e, verbose: ARGV.include?("--verbose"), agent: agent,
+                                     err: $stderr, out: $stdout,
+                                     log_path: File.join(Dir.pwd, ".saboteur", "internal-error.log"))
+end

data/lib/saboteur/baseline/workflow.rb

@@ -4,6 +4,7 @@
 require_relative "acceptance"
 require_relative "comparison"
 require_relative "../engine"
+require_relative "../text"
 
 module Saboteur
   module Baseline
@@ -70,7 +71,7 @@ module Saboteur
 
         bytes = File.read(path)
         @baseline_digest = Digest::SHA256.hexdigest(bytes)
-        manifest = Manifest.new(JSON.parse(bytes))
+        manifest = Manifest.new(JSON.parse(Text.utf8_strict(bytes)))
         metadata = manifest.to_h.fetch("metadata")
         candidates = manifest.candidates.values
         restored = metadata.slice("snapshot", "subjects", "complete", "issues").merge(

data/lib/saboteur/baseline_health.rb

@@ -4,6 +4,8 @@
 require "json"
 require "tempfile"
 
+require_relative "text"
+
 module Saboteur
   # Two fresh supervised children check the full suite without changing methods
   # or writing caches. This samples stability; it cannot prove absence of flakes.
@@ -49,8 +51,9 @@ module Saboteur
 
     def check_run(number, expected)
       Tempfile.create("saboteur-baseline") do |log|
-        result = @supervisor.run(timeout: @config["baseline_timeout"]) { |writer| record(writer, log.path) }
-        data = read_result(result, number)
+        result = @supervisor.run(timeout: @config["baseline_timeout"],
+                                 label: "baseline child died during setup/run") { |writer| record(writer, log.path) }
+        data = read_result(result, number, log)
         verify_execution(data, number, expected)
         raise Error, "baseline run #{number} left processes running; fix suite cleanup" if result.leftover_pids.any?
 
@@ -64,9 +67,12 @@ module Saboteur
       raise Error, "baseline check failed: #{e.class}: #{e.message}; check suite hooks and setup"
     end
 
-    def read_result(result, number)
+    def read_result(result, number, log = nil)
       raise Error, "baseline run #{number} stopped: #{result.detail}" if result.stopped_by
-      raise Error, "baseline run #{number} exited without a result; check suite boot and exits" if result.payload.empty?
+      if result.payload.empty?
+        raise Error, "baseline child died during setup/run: baseline run #{number} exited without a " \
+                     "result#{exit_detail(result.exit_status)}; check suite boot and exits#{log_tail(log)}"
+      end
       if result.child_failed?
         raise Error, "baseline run #{number} exited unsuccessfully; fix suite cleanup and exit handlers"
       end
@@ -77,6 +83,30 @@ module Saboteur
       data
     end
 
+    # The child's own output when it died without answering: the redirect
+    # puts its last words in this log, not on the terminal (#289). Bounded
+    # (about 2 KB, 20 lines) and scrubbed before it joins the error. Read
+    # through the parent's open handle, and strictly best-effort: a dead
+    # handle must never mask the real exit or signal error.
+    def log_tail(log)
+      return "" unless log
+
+      log.seek([log.size - 2048, 0].max)
+      tail = Text.utf8(log.read(2048).to_s).lines.last(20).map(&:chomp).join(" / ")
+      tail.empty? ? "" : "; child log tail: #{tail}"
+    rescue SystemCallError, IOError
+      ""
+    end
+
+    # The child's ending when the supervisor reaped one ("exit 1",
+    # "signal SIGKILL", ...): an empty result's cause is usually there (#255).
+    def exit_detail(status)
+      return "" unless status.is_a?(Process::Status)
+      return " (signal #{Signal.signame(status.termsig)})" if status.signaled?
+
+      " (exit #{status.exitstatus})"
+    end
+
     def verify_execution(data, number, expected)
       unless data["passed"] == true
         raise Error, "baseline run #{number} failed: #{data['error'] || 'fix the unchanged suite'}"
@@ -93,8 +123,12 @@ module Saboteur
         exception = example.execution_result.exception
         next unless exception
 
-        message = exception.message.to_s.lines.map(&:strip).find { |line| !line.empty? }.to_s[0, 200]
-        "#{example.id}: #{example.full_description.to_s[0, 200]}: #{message}"
+        # Exception text and example names can arrive locale-tagged or as
+        # raw path bytes (e.g. Errno::EILSEQ): scrub each field before any
+        # strip, truncation or interpolation - all three raise on bad tags.
+        # This detail ships in a JSON payload, so it must be valid UTF-8.
+        message = Text.utf8(exception.message.to_s).lines.map(&:strip).find { |line| !line.empty? }.to_s[0, 200]
+        "#{Text.utf8(example.id.to_s)}: #{Text.utf8(example.full_description.to_s)[0, 200]}: #{message}"
       end.first(5).join("; ")
     end
 

data/lib/saboteur/cli/exit_status.rb

@@ -8,7 +8,26 @@ module Saboteur
     module ExitStatus
       private
 
+      # Last resort: a bug must not escape as a bare stack trace and an accidental exit 1.
+      def internal_error(error)
+        CrashReport.call(error, verbose: @verbose, agent: agent?, err: @err, out: @out, log_path: crash_log_path)
+      end
+
+      # The crash log lives with the other run state. A broken config (or a
+      # nil cache_dir) must not swallow the crash report itself, so fall
+      # back to no log.
+      def crash_log_path
+        dir = config.path("cache_dir")
+        dir && File.join(dir, CrashReport::LOG_NAME)
+      rescue StandardError
+        nil
+      end
+
       def exit_code(report)
+        return EXIT_BUDGET if budget_exhausted?(report)
+
+        return EXIT_TOOL if untested_partial?(report)
+
         return EXIT_TOOL if mostly_errored?(report)
 
         return EXIT_TOOL if incomplete_under_threshold?(report)
@@ -16,6 +35,24 @@ module Saboteur
         failed_quality_gate?(report) || gates.failed?(report, @err) ? EXIT_SURVIVORS : EXIT_OK
       end
 
+      # A spent --max-duration budget exits 4 on its own, before the gates:
+      # the run is partial by design, and --max-duration-ok opts back into
+      # the plain verdict.
+      def budget_exhausted?(report)
+        report.early_stop&.reason == "max_duration" && !config["max_duration_ok"]
+      end
+
+      # A run stopped before any mutant was tested has no verdict to fall
+      # back on: --max-duration-ok must not turn it green. Unverified
+      # results are not tested verdicts, so an unverified-only stop has no
+      # score either (#296). Exit 3, like the other incomplete shapes.
+      def untested_partial?(report)
+        return false unless report.early_stop && report.score_breakdown.tested.zero?
+
+        @err.puts("saboteur: the run stopped before any mutant was tested, so there is no score to judge")
+        true
+      end
+
       def gates = (@gates ||= Gates.new(config))
 
       def mostly_errored?(report)
@@ -33,9 +70,11 @@ module Saboteur
       # incomplete run that mostly errored keeps its distinct cause, so the
       # harness rule means the same thing in both modes.
       def agent_exit_cause(report, payload)
+        return "budgetExhausted" if budget_exhausted?(report)
+
         case payload[:verdict]
         when "clean" then "ok"
-        when "survivors" then report.early_stop ? "failFast" : "survivors"
+        when "survivors" then report.early_stop&.reason == "fail_fast" ? "failFast" : "survivors"
         else report.majority_errored? ? "errorMajority" : "incomplete"
         end
       end
@@ -45,22 +84,28 @@ module Saboteur
       def exit_cause(report, code)
         case code
         when EXIT_OK then "ok"
+        when EXIT_BUDGET then "budgetExhausted"
         when EXIT_SURVIVORS then survivors_cause(report)
-        else report.majority_errored? ? "errorMajority" : "incompleteUnderThreshold"
+        else
+          if report.majority_errored?
+            "errorMajority"
+          else
+            report.early_stop && report.score_breakdown.tested.zero? ? "incomplete" : "incompleteUnderThreshold"
+          end
         end
       end
 
       # A run stopped by --fail-fast always exits 1: it stopped on a survivor, and
       # its score covers only the subjects that ran, so no threshold can pass it.
       def survivors_cause(report)
-        return "failFast" if report.early_stop
+        return "failFast" if report.early_stop&.reason == "fail_fast"
 
         gates.cause || (config["threshold"].nil? ? "survivors" : "belowThreshold")
       end
 
       # With --threshold the score decides; without it any unignored survivor does.
       def failed_quality_gate?(report)
-        return true if report.early_stop
+        return true if report.early_stop&.reason == "fail_fast"
 
         threshold = config["threshold"]
         return report.unignored_survivors.any? if threshold.nil?

data/lib/saboteur/cli/help_options.rb

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # The option map `saboteur help` prints per command. run, pr and audit
+    # share the run parser: the presets take every run option.
+    module HelpOptions
+      def option_lines
+        run = parser.summarize
+        { "run" => run, "pr" => run, "audit" => run, "doctor" => doctor_parser.summarize,
+          "baseline" => baseline_parser.summarize }
+      end
+    end
+  end
+end

data/lib/saboteur/cli/presets.rb

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class CLI
+    # Opinionated bundles (#244): pr is the fast changed-lines loop (one
+    # baseline check, a 10-minute budget that does not fail the build),
+    # audit is the whole project with both reports. Preset flags go first,
+    # so an explicit flag after them wins on the usual last-flag rule.
+    module Presets
+      PRESETS = {
+        "pr" => %w[--baseline-passes 1 --max-duration 10m --max-duration-ok],
+        "audit" => %w[--all --operators all --baseline-passes 2 --json .saboteur/audit-report.json
+                      --html .saboteur/audit-report.html]
+      }.freeze
+
+      private
+
+      def preset(name)
+        flags = PRESETS.fetch(name).dup
+        if name == "pr"
+          ref = @argv.first.nil? || @argv.first.start_with?("-") ? "main" : @argv.shift
+          flags += ["--since", ref]
+        end
+        # An explicit scope beats the injected whole-suite --all, which
+        # would otherwise reject the combination: named tests, and the
+        # deprecated inference alias (#245).
+        explicit_scope = @argv.any? { |arg| arg == "--test" || arg.start_with?("--test=") || arg == "--guess-tests" }
+        flags.delete("--all") if explicit_scope
+        @err.puts("saboteur: preset '#{name}': #{flags.join(' ')} (explicit flags override)")
+        @argv = flags + @argv
+        run_command
+      end
+    end
+  end
+end