diff --git a/dokimi/changelog.d/20261028_120000_napetrov_fix-cli-exit-codes-audit.md b/dokimi/changelog.d/20261028_120000_napetrov_fix-cli-exit-codes-audit.md
new file mode 100644
index 000000000..6152a6485
--- /dev/null
+++ b/dokimi/changelog.d/20261028_120000_napetrov_fix-cli-exit-codes-audit.md
@@ -0,0 +1,3 @@
+### Changed
+
+- **Input and usage refusals exit 2, not 1** — the exit-code table (new in `docs/quickstart.md`, section Exit codes) gives 2 to a missing, unreadable, malformed or unusable input, a flag combination a command refuses, an output file that cannot be written, and a benchmark run or preflight with no provider credential. Exit 1 is left for a verdict or a gate that ran and failed, and for a runtime or model failure. The messages are unchanged. Scripts that branch on `$? -eq 1` for these cases must also accept 2. Affected: `personas` (approve, discover), `questions`, `eval` (score, ragas, grounding, validity, panel-score), `orchestrate`, `report` (eval, generate, model-compare), `baseline`, `novelty`, `catalog` (and `catalog probe`), `answers`, `arms`, `explore`, `tasks`, `subjects`, `repo` (`validate`, `scan`, `inspect`, `budget`, `fetch`, `reach`, `report`, `compare`), `library`, `tools`, `dashboard`, `run`, and `benchmark` (run, preflight, batch). Only the validation step of a command exits 2; a failure while it runs keeps 1. Specifically: `benchmark preflight` exits 2 when a provider credential, the output dir, the question set or the doc source is invalid, even when a failed check is also reported, and 1 when a check alone fails (an unreachable doc source); `benchmark batch` with nothing to run exits 2; `repo validate`, `scan`, `inspect`, `budget`, `fetch` and `reach` exit 2 for a malformed source string, an unpinned remote, a pinned local path that is not the repository root, a manifest path that leaves the tree, a manifest or profile error, or a bad scenario selection, and 1 for a clone, fetch or pin resolution that fails (including a pinned local source that is not a git repository, a pin absent locally, and a remote pin missing from origin) and for a harness run; `arms run` and `arms matrix-run` exit 2 for a bad spec or setup input, and 1 for a run failure or a failed sampling probe; a matrix probes every cell before its first answer, so a cell refused at the probe makes no answer call (probe calls are still model calls and can fail, exit 1); `catalog trigger-set` exits 2 for a duplicate question id, a question without text or an `@field` rule that labels none of its source's questions (refused before any `--rewrite` call), and 1 for a `--strict` refusal (a lint gate, as on main) and when a `--rewrite` returns nothing; a missing RAGAS extra stays 1. `repo run` and `repo tasks check` are not converted: their input refusals still exit 1. `tools preference` still exits 2 when every call failed or `--max-cost-usd` skipped calls. A `--static` file that cannot be read or is not JSON exits 2 in `repo scan`; a schema-invalid document exits 1.
diff --git a/dokimi/docs/benchmarking-and-comparison.md b/dokimi/docs/benchmarking-and-comparison.md
index 4d771b83e..8ee19935a 100644
--- a/dokimi/docs/benchmarking-and-comparison.md
+++ b/dokimi/docs/benchmarking-and-comparison.md
@@ -796,8 +796,8 @@ stderr as not compared, and `--strict` exits 1 on it as well, since it cannot
 vouch for that role. A malformed record in either file (no `question_id`) exits 2,
 naming the record on stderr, so it never reads as a failed `--strict` check.
 `baseline compare` also exits 2 on an eval file, saved baseline or `manifest.json`
-that is not valid JSON, not a JSON object, or cannot be read. `baseline save` exits 1
-on a bad eval file or `manifest.json`, and `baseline list` exits 1 on a bad
+that is not valid JSON, not a JSON object, or cannot be read. `baseline save` exits 2
+on a bad eval file or `manifest.json`, and `baseline list` exits 2 on a bad
 `manifest.json`. A `manifest.json` whose `baselines` is not a list, or whose entries
 lack a string `name` and `path` or have a `summary` that is not an object, is rejected
 the same way.
diff --git a/dokimi/docs/external-content.md b/dokimi/docs/external-content.md
index ba7929a61..370a67e36 100644
--- a/dokimi/docs/external-content.md
+++ b/dokimi/docs/external-content.md
@@ -186,7 +186,7 @@ WARNING questions root C:\Users\Public\content-repo\questions has no golden set
 ```
 
 `benchmark run` logs a warning and continues with generated questions only.
-`benchmark preflight` treats a missing golden set as an error and exits 1.
+`benchmark preflight` refuses a missing golden set and exits 2.
 If you are comparing arms, that is usually not what you want; check the coverage matrix first.
 
 `benchmark preflight` resolves the whole plan without calling a model, and
@@ -213,7 +213,7 @@ Resolved benchmark plan
   golden questions: C:\Users\Public\content-repo\questions\demo_golden.json (2 items)
 ```
 
-(It exited 1 here because no API keys were set: `✗ missing OPENAI_API_KEY for
+(It exited 2 here because no API keys were set: `✗ missing OPENAI_API_KEY for
 provider openai`. Key checks are part of the pre-flight.)
 
 For a direct N-arm comparison, hand `arms run` the question file itself:
diff --git a/dokimi/docs/quickstart.md b/dokimi/docs/quickstart.md
index f95bc0317..7fc46655b 100644
--- a/dokimi/docs/quickstart.md
+++ b/dokimi/docs/quickstart.md
@@ -241,6 +241,22 @@ so results from before are not comparable with older baselines; re-baseline —
 Costs scale roughly linearly with question count. Token counts are recorded
 per answer in `answers/<product>.json`.
 
+## Exit codes
+
+`dokimi` commands use three codes, so a script can tell a bad invocation from a
+failed check.
+
+| Code | Meaning | Examples |
+|------|---------|----------|
+| 0 | The command ran and, if it checks something, the check passed. | |
+| 1 | A verdict or a gate that ran and failed, or a runtime failure (a model call, a run, a clone or fetch). | `baseline compare --strict` over a changed model, `benchmark preflight` with a failed check alone, `repo reach` with a harness binary that cannot run, `catalog trigger-set --strict` over a lint finding |
+| 2 | A bad invocation: a missing, unreadable or malformed input file, a flag combination the command refuses, an output file that cannot be written, a missing provider credential, a source string that is malformed, unpinned or not a repository root. | `baseline save` on a bad eval file, `benchmark preflight` with no golden set, `repo scan --manifest ../x.yaml` |
+
+A command that validates its input and then runs exits 2 for the first and 1
+for the second. Not every command follows this yet: `repo run` and
+`repo tasks check` still exit 1 for their input refusals, and `tools preference`
+exits 2 when every call failed or `--max-cost-usd` skipped calls.
+
 ## Troubleshooting
 
 | Symptom | Fix |
diff --git a/dokimi/docs/repo-evaluation-contract.md b/dokimi/docs/repo-evaluation-contract.md
index a61f27da3..dae1183cc 100644
--- a/dokimi/docs/repo-evaluation-contract.md
+++ b/dokimi/docs/repo-evaluation-contract.md
@@ -1162,8 +1162,9 @@ scanned once, as the file it names.
 The report lists `warnings` for guidance the manifest names but the tree lacks:
 a glob with no match, a missing `also_scan` file, no guidance at all, and a
 guidance file that cannot be read (a link that dangles or leaves the tree, a
-binary file, a file over 2 MB), named with the reason. An invalid `--static`
-document is not merged, and the command exits 1. `--fail-on-fail` also exits 1
+binary file, a file over 2 MB), named with the reason. A `--static`
+file that cannot be read or is not JSON exits 2; a document that fails the
+`repo_static.v1` schema is not merged, and the command exits 1. `--fail-on-fail` also exits 1
 when any claim fails, an `also_scan` file is missing, a guidance file cannot be
 read, a Bazel build input (`BUILD`, `.bzl`, `.bazelrc`, ...) cannot be read, or no guidance file matched
 (`incomplete`). A glob that matches nothing
diff --git a/dokimi/dokimi/commands/_output.py b/dokimi/dokimi/commands/_output.py
index c2c6eed40..1d72ba552 100644
--- a/dokimi/dokimi/commands/_output.py
+++ b/dokimi/dokimi/commands/_output.py
@@ -9,12 +9,14 @@
 import sys
 from pathlib import Path
 
+from dokimi.exit_codes import EXIT_USAGE
+
 
 @contextlib.contextmanager
 def exit_on_unwritable(path: Path):
-    """Exit 1 naming ``path`` when an output write inside the block fails."""
+    """Exit 2 naming ``path`` when an output write inside the block fails (exit-code table in docs/quickstart.md)."""
     try:
         yield
     except OSError as exc:
         print(f"Error: cannot write {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
diff --git a/dokimi/dokimi/commands/answers.py b/dokimi/dokimi/commands/answers.py
index 4b08abe6a..8a998ee5f 100644
--- a/dokimi/dokimi/commands/answers.py
+++ b/dokimi/dokimi/commands/answers.py
@@ -19,6 +19,7 @@
     DEFAULT_MAX_TOKENS_PER_QUESTION,
     DEFAULT_RETRIEVAL_TOP_K,
 )
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _load_runtime_config() -> dict:
@@ -33,18 +34,18 @@ def _load_runtime_config() -> dict:
         loaded = yaml.safe_load(config_path.read_text(encoding="utf-8"))
     except yaml.YAMLError as exc:
         print(f"Error: invalid YAML in {config_path}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
     except (OSError, ValueError) as exc:  # ValueError covers bad UTF-8
         print(f"Error: cannot read {config_path}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
     if loaded is not None and not isinstance(loaded, dict):
         print(f"Error: expected a mapping in {config_path}", file=sys.stderr)
-        raise SystemExit(1)
+        raise SystemExit(EXIT_USAGE)
     config = loaded or {}
     for key in ("products", "retrieval"):
         if config.get(key) is not None and not isinstance(config[key], dict):
             print(f"Error: '{key}' in {config_path} must be a mapping", file=sys.stderr)
-            raise SystemExit(1)
+            raise SystemExit(EXIT_USAGE)
     return config
 
 
@@ -55,10 +56,10 @@ def _load_questions(path: str) -> list:
         return load_questions(path).questions
     except ValueError as exc:  # ArtifactValidationError: names the record and the fix
         print(f"Error: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
     except OSError as exc:
         print(f"Error: cannot read {path}: {exc.strerror or exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
 
 
 def _output_path(args: argparse.Namespace) -> Path:
@@ -104,7 +105,7 @@ def cmd_answers_generate(args: argparse.Namespace) -> None:
             )
         except ValueError as exc:
             print(f"Error: {exc}", file=sys.stderr)
-            raise SystemExit(1) from exc
+            raise SystemExit(EXIT_USAGE) from exc
 
     print(f"Generating answers for {args.product} (library_id={library_id})")
     print(f"Using model: {args.provider}/{args.model}")
diff --git a/dokimi/dokimi/commands/arms.py b/dokimi/dokimi/commands/arms.py
index b61ea4c99..0fbca01cb 100644
--- a/dokimi/dokimi/commands/arms.py
+++ b/dokimi/dokimi/commands/arms.py
@@ -7,10 +7,12 @@
 
 import argparse
 from collections import Counter
+import os
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from dokimi.exit_codes import EXIT_FAILURE, EXIT_USAGE
 from dokimi.utils import question_id
 from dokimi.eval.judge import JUDGE_PROVIDERS
 from dokimi.defaults import (
@@ -53,21 +55,32 @@ def judge_panel_roles(value: str) -> str:
 
 def cmd_arms_run(args: argparse.Namespace) -> None:
     """Run an N-arm treatment comparison and optionally judge it."""
-    from dokimi.eval.arms_run import LibraryIdError, run_arms
+    from dokimi.eval.arms_run import LibraryIdError, ProbeError, prepare_arms, run_prepared
 
+    # Setup (inputs, arms, plugins, sampling, judge) exits 2; a failed sampling probe is a run failure (1).
     try:
         specs = _parse_arm_specs(args.arms)
         questions = _load_questions(args.questions)
         config = _with_named_cell(run_config_from_args(args), args.matrix_cells, args.matrix_cell)
-        output = run_arms(config, specs, questions)
+        prepared = prepare_arms(config, specs, questions)
     except EmptyQuestionError:
         raise  # a bad input record, not an arm setup error: cli.main reports it (exit 2)
+    except ProbeError as exc:
+        print(f"Error running arms: {exc}", file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
     except LibraryIdError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     except (ValueError, OSError, RecursionError) as exc:
         print(f"Error building arms/plugins: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
+    try:
+        output = run_prepared(prepared, config, questions)
+    except EmptyQuestionError:
+        raise  # a bad input record, not a run error: cli.main reports it (exit 2)
+    except (ValueError, OSError, RecursionError) as exc:
+        print(f"Error running arms: {exc}", file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
 
     out_json = Path(args.out_json) if args.out_json else Path(f"results/arms/{args.product}.json")
     out_md = Path(args.out_md) if args.out_md else Path(f"results/arms/{args.product}.md")
@@ -95,6 +108,39 @@ def cmd_arms_matrix_run(args: argparse.Namespace) -> None:
     )
 
 
+def _load_matrix_inputs(config: ArmsRunConfig, arms: str, questions: str, matrix_cells: str):
+    """The arms, questions and cells of a matrix run, checked before any cell is set up. A refused
+    input exits 2; a failed sampling probe, a real call, exits 1."""
+    from dokimi.eval import arms_run
+    from dokimi.eval.cells import load_matrix_cells
+
+    try:
+        specs = _parse_arm_specs(arms)
+        loaded_questions = _load_questions(questions)
+        cells = load_matrix_cells(matrix_cells)
+        _validate_unique_cell_filenames(cells)
+        arms_run.check_matrix(config, cells)
+    except EmptyQuestionError:
+        raise  # a bad input record, not a cell error: cli.main reports it (exit 2)
+    except arms_run.ProbeError as exc:
+        print(f"Error loading matrix run inputs: {exc}", file=sys.stderr)
+        sys.exit(EXIT_FAILURE)
+    except (ValueError, OSError, RecursionError) as exc:
+        print(f"Error loading matrix run inputs: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    return specs, loaded_questions, cells
+
+
+def _check_cells_dir(cells_dir: Path) -> None:
+    """Exit 2 when *cells_dir* cannot be made: the nearest existing ancestor must be a directory
+    the process can write to. Creates nothing."""
+    # A dangling symlink exists as a link but not as a target: it is the nearest entry, and it is refused.
+    existing = next(p for p in (cells_dir, *cells_dir.parents) if p.exists() or p.is_symlink())
+    if not existing.is_dir() or not os.access(existing, os.W_OK | os.X_OK):
+        print(f"Error: cannot write {cells_dir}: {existing} is not a writable directory", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+
+
 def run_matrix(config: ArmsRunConfig, *, arms: str, questions: str, matrix_cells: str,
                out_dir: Path, out_json: Path | None = None, out_md: Path | None = None,
                plugin_deltas: bool = True) -> None:
@@ -105,32 +151,26 @@ def run_matrix(config: ArmsRunConfig, *, arms: str, questions: str, matrix_cells
     ``.md`` suffix.
     """
     from dokimi.eval import arms_run
-    from dokimi.eval.cells import load_matrix_cells
     from dokimi.eval.matrix_rollup import build_matrix_rollup, strip_internal_payloads
     from dokimi.report.matrix_rollup_report import render_matrix_rollup_report
     from dokimi.report.plugin_delta_report import render_plugin_delta_report
 
-    try:
-        specs = _parse_arm_specs(arms)
-        loaded_questions = _load_questions(questions)
-        cells = load_matrix_cells(matrix_cells)
-        _validate_unique_cell_filenames(cells)
-        arms_run.check_matrix(config, cells)
-    except (ValueError, OSError, RecursionError) as exc:
-        print(f"Error loading matrix run inputs: {exc}", file=sys.stderr)
-        sys.exit(1)
+    specs, loaded_questions, cells = _load_matrix_inputs(config, arms, questions, matrix_cells)
 
+    # The cells dir is made only when a cell finishes, so a cell refused in setup writes nothing.
+    # An uncreatable one is refused here, before any answer is paid for and then lost on exit.
     cells_dir = out_dir / "cells"
-    try:
-        cells_dir.mkdir(parents=True, exist_ok=True)
-    except OSError as exc:
-        print(f"Error: cannot write {cells_dir}: {exc}", file=sys.stderr)
-        sys.exit(1)
+    _check_cells_dir(cells_dir)
     cell_artifacts = []
 
     def save_cell(cell, output: dict) -> None:
         safe_name = _safe_name(cell.name)
         cell_json = cells_dir / f"{safe_name}.json"
+        try:
+            cells_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            print(f"Error: cannot write {cells_dir}: {exc}", file=sys.stderr)
+            sys.exit(EXIT_USAGE)
         _save_arms_output(output, cell_json, cells_dir / f"{safe_name}.md")
         cell_artifacts.append((cell.name, cell_json, output))
 
@@ -140,10 +180,11 @@ def save_cell(cell, output: dict) -> None:
         raise  # a bad input record, not a cell error: cli.main reports it (exit 2)
     except arms_run.LibraryIdError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     except arms_run.MatrixCellError as exc:
-        print(f"Error running matrix cell {exc.cell!r}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        verb = "building" if exc.usage else "running"
+        print(f"Error {verb} matrix cell {exc.cell!r}: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE if exc.usage else EXIT_FAILURE)
 
     rollup = build_matrix_rollup(
         library_name=config.product,
@@ -185,7 +226,7 @@ def cmd_arms_plugin_delta(args: argparse.Namespace) -> None:
         output = compare_plugin_runs(baseline, plugin)
     except (PluginDeltaError, ValueError, OSError, RecursionError) as exc:
         print(f"Error computing plugin delta: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     out_json = Path(args.out_json) if args.out_json else Path("results/arms/plugin_delta.json")
     _save_artifact_or_exit("plugin_delta", output, out_json)
@@ -488,7 +529,7 @@ def _write_report(path: Path, text: str) -> None:
         path.write_text(text, encoding="utf-8")
     except OSError as exc:
         print(f"Error: cannot write {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
 def _save_artifact_or_exit(kind: str, payload: dict, path: Path) -> None:
@@ -499,7 +540,7 @@ def _save_artifact_or_exit(kind: str, payload: dict, path: Path) -> None:
         save_artifact(kind, payload, path)
     except OSError as exc:
         print(f"Error: cannot write {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
 def _save_arms_output(output: dict, out_json: Path, out_md: Path) -> None:
@@ -510,7 +551,7 @@ def _save_arms_output(output: dict, out_json: Path, out_md: Path) -> None:
         ArmRunner.save(output, out_json)
     except OSError as exc:
         print(f"Error: cannot write {out_json}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     print(f"OK Saved arms comparison: {out_json}")
     _write_report(out_md, render_arms_report(output))
     print(f"OK Saved arms report:     {out_md}")
diff --git a/dokimi/dokimi/commands/baseline.py b/dokimi/dokimi/commands/baseline.py
index 20769c53d..c36fb7ca0 100644
--- a/dokimi/dokimi/commands/baseline.py
+++ b/dokimi/dokimi/commands/baseline.py
@@ -12,6 +12,7 @@
 from typing import Any, Dict, List, Optional, Tuple
 
 from dokimi.utils import normalize_model_ref
+from dokimi.exit_codes import EXIT_USAGE
 
 BASELINES_DIR = Path("baselines/eval")
 
@@ -37,7 +38,7 @@ def _read_json_object(path: Path, code: int) -> Dict[str, Any]:
     return data
 
 
-def _baseline_manifest(code: int = 1) -> Dict[str, Any]:
+def _baseline_manifest(code: int = EXIT_USAGE) -> Dict[str, Any]:
     """Load or create the baseline manifest; a corrupt one exits ``code``."""
     manifest_path = BASELINES_DIR / "manifest.json"
     if not manifest_path.exists():
@@ -140,7 +141,7 @@ def cmd_baseline_save(args: argparse.Namespace) -> None:
 
     eval_path = Path(args.from_eval)
     manifest = _baseline_manifest()  # first: a corrupt manifest fails fast and leaves no orphan file
-    eval_data = _read_json_object(eval_path, 1)
+    eval_data = _read_json_object(eval_path, EXIT_USAGE)
     product = args.product or eval_data.get("product", "unknown")
     timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%f")
     name = args.name or f"{product}-{timestamp}"
@@ -151,13 +152,13 @@ def cmd_baseline_save(args: argparse.Namespace) -> None:
         summary = _compute_summary(eval_data)
     except RecordError as exc:
         print(f"❌ {eval_path}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
 
     BASELINES_DIR.mkdir(parents=True, exist_ok=True)
     dest = BASELINES_DIR / f"{name}.json"
     if dest.exists():
         print(f"❌ Baseline already exists: {dest} (choose a different --name)", file=sys.stderr)
-        raise SystemExit(1)
+        raise SystemExit(EXIT_USAGE)
     dest.write_text(json.dumps(eval_data, indent=2), encoding="utf-8")
 
     manifest["baselines"].append({
@@ -205,7 +206,7 @@ def _pick_entry(args: argparse.Namespace, baselines: list, eval_data: dict) -> d
         entry = next((b for b in baselines if b["name"] == args.baseline), None)
         if not entry:
             print(f"❌ Baseline '{args.baseline}' not found.")
-            raise SystemExit(1)
+            raise SystemExit(EXIT_USAGE)
     else:
         product = args.product or eval_data.get("product")
         candidates = [b for b in baselines if b.get("product") == product] if product else baselines
@@ -260,7 +261,7 @@ def cmd_baseline_compare(args: argparse.Namespace) -> None:
     if not baselines:
         print("No baselines found. Save one first:")
         print("  dokimi baseline save --from-eval eval/oneTBB.json --product oneTBB")
-        raise SystemExit(1)
+        raise SystemExit(EXIT_USAGE)
 
     entry = _pick_entry(args, baselines, eval_data)
     baseline_data = _read_json_object(Path(entry["path"]), 2)
diff --git a/dokimi/dokimi/commands/benchmark.py b/dokimi/dokimi/commands/benchmark.py
index 2c50c724e..57abb83ae 100644
--- a/dokimi/dokimi/commands/benchmark.py
+++ b/dokimi/dokimi/commands/benchmark.py
@@ -9,7 +9,7 @@
 import os
 import sys
 from pathlib import Path
-from typing import Any, List, cast
+from typing import Any, Callable, List, cast
 
 from dokimi.commands.evaluate import _warn_judge_independence
 from dokimi.eval.judge import JUDGE_PROVIDERS
@@ -25,6 +25,7 @@
     JUDGE_MODEL_HELP,
 )
 from dokimi.commands.library import _load_registry
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _run_single_library(entry, output_dir: str, model: str, provider: str, judge_model: str, judge_provider: str = DEFAULT_JUDGE_PROVIDER, doc_source_override=None, max_tokens_per_question: int = DEFAULT_MAX_TOKENS_PER_QUESTION, force_regen: bool = False, concurrency: int = DEFAULT_CONCURRENCY, questions_from=None, questions_root=None) -> dict:
@@ -123,71 +124,93 @@ def _check_questions_from(questions_from: str, key: str) -> tuple[Path, list, st
         return qf, [], f"questions source invalid: {qf} ({exc})"
 
 
-def cmd_benchmark_preflight(args: argparse.Namespace) -> None:
-    """Validate the resolved benchmark plan without running LLM calls."""
+def _check_golden_set(questions_root: str, key: str, refuse: Callable[[str], None]) -> None:
+    """Preflight the golden set under a questions root; each problem is an input refusal."""
     from dokimi.orchestrator.pipeline import load_questions_payload
+
+    root = Path(questions_root)
+    golden = root / f"{key.lower()}_golden.json"
+    if not root.is_dir():
+        refuse(f"questions root not found: {root}")
+        return
+    if not golden.is_file():
+        refuse(f"questions root has no golden set: {golden}")
+        return
+    try:
+        golden_questions = load_questions_payload(golden)
+        print(f"  golden questions: {golden} ({len(golden_questions)} items)")
+        if not golden_questions:
+            refuse(f"golden set is empty: {golden}")
+            return
+        bad = next((i for i, q in enumerate(cast(List[Any], golden_questions)) if not isinstance(q, dict)), None)
+        if bad is not None:
+            refuse(f"golden set item {bad} is not a dict: {golden}")
+    except Exception as exc:
+        refuse(f"golden set invalid: {golden} ({exc})")
+
+
+def _check_doc_source(plan: dict, entry: Any, refuse: Callable[[str], None], errors: list[str],
+                      warnings: list[str]) -> None:
+    """The doc source must build. A --doc-source value the factory rejects is a refusal (exit 2);
+    a source that cannot be built is a failed check (exit 1)."""
     from dokimi.mcp.factory import create_doc_source_client
 
+    try:
+        create_doc_source_client(plan["doc_source"])
+        if plan["doc_source"] == "context7" and getattr(entry, "context7_id", None):
+            print(f"  context7_id: {entry.context7_id}")
+        elif plan["doc_source"] == "context7":
+            warnings.append("context7 id not pinned; client will resolve by target name")
+    except ValueError as exc:
+        refuse(f"doc source invalid: {plan['doc_source']} ({exc})")
+    except Exception as exc:  # the source cannot be reached or built: a failed check
+        errors.append(f"doc source check failed: {plan['doc_source']} ({exc})")
+
+
+def cmd_benchmark_preflight(args: argparse.Namespace) -> None:
+    """Validate the resolved benchmark plan without running LLM calls."""
     registry = _load_registry(args)
     try:
         entry = registry.get(args.library)
     except KeyError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     plan = _resolved_benchmark_plan(entry, args)
     _print_plan(plan)
 
     errors: list[str] = []
     warnings: list[str] = []
+    # Refusals are missing or invalid inputs and credentials (exit 2, as `benchmark run` refuses
+    # them). The other errors are failed checks (exit 1).
+    refusals: list[str] = []
+
+    def refuse(message: str) -> None:
+        refusals.append(message)
+        errors.append(message)
 
     for provider in {args.provider, args.judge_provider}:
         key = _credential_env_var(provider)
         if not os.environ.get(key):
-            errors.append(f"missing {key} for provider {provider}")
+            refuse(f"missing {key} for provider {provider}")
 
     try:
         Path(plan["output_dir"]).mkdir(parents=True, exist_ok=True)
     except OSError as exc:
-        errors.append(f"output dir not writable: {plan['output_dir']} ({exc})")
+        refuse(f"output dir not writable: {plan['output_dir']} ({exc})")
 
-    try:
-        client = create_doc_source_client(plan["doc_source"])
-        if plan["doc_source"] == "context7" and getattr(entry, "context7_id", None):
-            print(f"  context7_id: {entry.context7_id}")
-        elif plan["doc_source"] == "context7":
-            warnings.append("context7 id not pinned; client will resolve by target name")
-        _ = client
-    except Exception as exc:  # pragma: no cover - defensive for plugin clients
-        errors.append(f"doc source invalid: {plan['doc_source']} ({exc})")
+    _check_doc_source(plan, entry, refuse, errors, warnings)
 
     if plan["questions_from"]:
         qf, questions, problem = _check_questions_from(plan["questions_from"], entry.key)
         if problem:
-            errors.append(problem)
+            refuse(problem)
         else:
             print(f"  questions: {qf} ({len(questions)} items)")
 
     # Check golden set only if no external questions source (--questions-from takes precedence)
     if plan["questions_root"] and not plan["questions_from"]:
-        root = Path(plan["questions_root"])
-        golden = root / f"{entry.key.lower()}_golden.json"
-        if not root.is_dir():
-            errors.append(f"questions root not found: {root}")
-        elif not golden.is_file():
-            errors.append(f"questions root has no golden set: {golden}")
-        else:
-            try:
-                golden_questions = load_questions_payload(golden)
-                print(f"  golden questions: {golden} ({len(golden_questions)} items)")
-                if not golden_questions:
-                    errors.append(f"golden set is empty: {golden}")
-                else:
-                    bad = next((i for i, q in enumerate(cast(List[Any], golden_questions)) if not isinstance(q, dict)), None)
-                    if bad is not None:
-                        errors.append(f"golden set item {bad} is not a dict: {golden}")
-            except Exception as exc:
-                errors.append(f"golden set invalid: {golden} ({exc})")
+        _check_golden_set(plan["questions_root"], entry.key, refuse)
 
     same = _warn_judge_independence(
         answer_provider=args.provider,
@@ -207,7 +230,9 @@ def cmd_benchmark_preflight(args: argparse.Namespace) -> None:
         print("Errors:", file=sys.stderr)
         for item in errors:
             print(f"  ✗ {item}", file=sys.stderr)
-        sys.exit(1)
+        # A missing credential or input is a usage refusal (2), even with a failed check beside it;
+        # a failed check alone is a failed gate (1).
+        sys.exit(EXIT_USAGE if refusals else 1)
     print("✅ Preflight OK")
 
 
@@ -219,7 +244,7 @@ def cmd_benchmark_run(args: argparse.Namespace) -> None:
         entry = registry.get(args.library)
     except KeyError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     output_dir = args.output_dir or f"results/{entry.key}{DEFAULT_RESULTS_SUFFIX}"
     n_runs = getattr(args, "multi_run", 1)
@@ -231,7 +256,7 @@ def cmd_benchmark_run(args: argparse.Namespace) -> None:
         _, _, problem = _check_questions_from(questions_from, entry.key)
         if problem:
             print(f"Error: {problem}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
 
     if n_runs == 1:
         _run_single_library(
@@ -303,7 +328,7 @@ def cmd_benchmark_batch(args: argparse.Namespace) -> None:
 
     if not entries:
         print("No libraries to run.", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     print(f"Batch run: {len(entries)} libraries → {args.output_dir}")
     results = []
diff --git a/dokimi/dokimi/commands/catalog.py b/dokimi/dokimi/commands/catalog.py
index f81c5a7bd..9e941cf46 100644
--- a/dokimi/dokimi/commands/catalog.py
+++ b/dokimi/dokimi/commands/catalog.py
@@ -16,6 +16,7 @@
 import json
 import sys
 from pathlib import Path
+from dokimi.exit_codes import usage_exit
 
 
 def _skill_row(skill, review) -> dict:
@@ -62,7 +63,7 @@ def _scan_skills(args: argparse.Namespace, root: Path, report: dict, as_json: bo
     try:
         skills = read_skill_manifest(root)
     except ValueError as exc:
-        raise SystemExit(f"skills.yaml: {exc}") from exc
+        usage_exit(f"skills.yaml: {exc}")
     reviews = review_skills(skills)
     counts = {"ok": 0, "warn": 0, "error": 0}
     failed = False
@@ -102,7 +103,7 @@ def _scan_tasks(args: argparse.Namespace, root: Path, report: dict, as_json: boo
     try:
         tasks = read_task_manifest(root, tasks_subdir=args.tasks_subdir)
     except ValueError as exc:
-        raise SystemExit(str(exc)) from exc
+        usage_exit(str(exc))
     if not as_json:
         print(f"# tasks ({len(tasks)} declared under {root})")
     failed = False
@@ -121,7 +122,7 @@ def _scan_tasks(args: argparse.Namespace, root: Path, report: dict, as_json: boo
 def cmd_catalog_scan(args: argparse.Namespace) -> None:
     root = Path(args.root)
     if not root.is_dir():
-        raise SystemExit(f"--root is not a directory: {root}")
+        usage_exit(f"--root is not a directory: {root}")
 
     as_json = args.format == "json"
     report: dict = {"root": str(root), "skills": [], "tasks": []}
@@ -137,7 +138,7 @@ def cmd_catalog_scan(args: argparse.Namespace) -> None:
 
 
 def _write_trigger_set(args: argparse.Namespace, queries, catalog_root: Path) -> None:
-    """Write the query set to ``--out`` in ``--format``, or exit 1 naming ``--out`` when it cannot be written."""
+    """Write the query set to ``--out`` in ``--format``, or exit 2 naming ``--out`` when it cannot be written."""
     import json
 
     from dokimi.artifacts import ArtifactValidationError
@@ -154,9 +155,9 @@ def _write_trigger_set(args: argparse.Namespace, queries, catalog_root: Path) ->
                        else ts.to_skill_creator(queries, args.target))
             Path(args.out).write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
     except ArtifactValidationError as exc:  # the path was writable; the payload failed the schema
-        raise SystemExit(f"Error: questions set rejected: {exc}") from exc
+        usage_exit(f"Error: questions set rejected: {exc}")
     except (OSError, ValueError) as exc:  # unwritable --out: a directory, a file as parent, no permission, empty path (pathlib ValueError)
-        raise SystemExit(f"Error: cannot write --out {args.out}: {exc}") from exc
+        usage_exit(f"Error: cannot write --out {args.out}: {exc}")
 
 
 def _discover_catalog_skills(catalog_root: Path) -> list:
@@ -165,7 +166,7 @@ def _discover_catalog_skills(catalog_root: Path) -> list:
     try:
         return discover_skills(catalog_root)
     except (OSError, ValueError, RecursionError) as exc:  # unreadable, non-UTF-8, bad frontmatter or nesting too deep
-        raise SystemExit(f"--catalog {catalog_root}: {exc}") from exc
+        usage_exit(f"--catalog {catalog_root}: {exc}")
 
 
 def cmd_catalog_trigger_set(args: argparse.Namespace) -> None:
@@ -175,42 +176,40 @@ def cmd_catalog_trigger_set(args: argparse.Namespace) -> None:
 
     catalog_root = Path(args.catalog)
     if not catalog_root.is_dir():
-        raise SystemExit(f"--catalog is not a directory: {catalog_root}")
+        usage_exit(f"--catalog is not a directory: {catalog_root}")
     catalog = _discover_catalog_skills(catalog_root)
     # Checked before any --rewrite call, so a bad invocation costs no LLM calls.
     if args.format == "skill-creator":
         if not args.target:
-            raise SystemExit("--format skill-creator needs --target <skill>")
+            usage_exit("--format skill-creator needs --target <skill>")
         if args.target not in {s.name for s in catalog}:
-            raise SystemExit(f"--target {args.target!r} is not a skill in --catalog "
-                             f"(have: {', '.join(sorted(s.name for s in catalog))})")
+            usage_exit(f"--target {args.target!r} is not a skill in --catalog "
+                       f"(have: {', '.join(sorted(s.name for s in catalog))})")
     sources = _question_sources(args.questions or [])
     sources += _trigger_set_sources(args.trigger_set or [], catalog)
     if not sources:
-        raise SystemExit("give --questions PATH=LABEL or --trigger-set PATH[=TARGET]")
-    specs = list(args.questions or []) + list(args.trigger_set or [])
+        usage_exit("give --questions PATH=LABEL or --trigger-set PATH[=TARGET]")
+    # A --trigger-set source is labelled by @expected_skill whether or not its file has labels,
+    # so only --questions sources (named here) get the no-labels refusal.
+    specs = list(args.questions or []) + [None] * len(args.trigger_set or [])
 
     rewrite = None
     if args.rewrite:
         if not args.model:
-            raise SystemExit("--rewrite needs --model")
+            usage_exit("--rewrite needs --model")
         from dokimi.llm import llm_call
 
         def rewrite(text: str) -> str:
             return llm_call(ts.REWRITE_PROMPT + text, model=args.model, provider=args.provider)
 
     try:
-        queries = ts.build_trigger_set(sources, catalog, rewrite=rewrite)
+        queries = ts.build_trigger_set(sources, catalog, rewrite=rewrite, specs=specs)
+    except ts.TriggerSetInputError as exc:
+        usage_exit(str(exc))
     except ValueError as exc:
-        raise SystemExit(str(exc)) from exc
-    # An @field rule that resolves for no question in its source is a typo in the
-    # path, not a set of negatives; refuse it rather than write "nothing loads".
-    start = 0
-    for (qs, rule), spec in zip(sources, specs, strict=True):
-        chunk = queries[start:start + len(qs)]
-        start += len(qs)
-        if rule.startswith("@") and chunk and not any(q.labelled for q in chunk):
-            raise SystemExit(f"{spec}: {rule} resolves for none of {len(chunk)} questions")
+        # A --rewrite that returned nothing: a runtime failure, not a bad invocation.
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
     summary = ts.lint_summary(queries)
     if summary["label_unresolved"]:
         print(f"warning: {summary['label_unresolved']} questions have an unresolved @field label; "
@@ -219,9 +218,9 @@ def rewrite(text: str) -> str:
         args.strict and (summary["names_skill"] or summary["exam_framing"] or summary["label_unresolved"])
     ):
         # Refuse before writing, so a pipeline that only checks for the file
-        # cannot pick up a set with a mistyped label.
+        # cannot pick up a set with a mistyped label. A lint gate verdict: exit 1, as on main.
         print(json.dumps(summary, indent=2))
-        raise SystemExit(1)
+        sys.exit(1)
     _write_trigger_set(args, queries, catalog_root)
 
     print(json.dumps(summary, indent=2))
@@ -241,7 +240,7 @@ def cmd_catalog_formats(args: argparse.Namespace) -> None:
 
     root = Path(args.root)
     if not root.is_dir():
-        raise SystemExit(f"--root is not a directory: {root}")
+        usage_exit(f"--root is not a directory: {root}")
     packages = formats.detect_skill_packages(root)
     summary = formats.summarize(packages)
     if args.json:
@@ -266,11 +265,11 @@ def _question_sources(specs: list) -> list:
     for spec in specs:
         path, _, rule = spec.rpartition("=")  # labels never contain '=', paths may
         if not path or not rule:
-            raise SystemExit(f"--questions needs PATH=LABEL (a skill name, 'none' or '@field'): {spec}")
+            usage_exit(f"--questions needs PATH=LABEL (a skill name, 'none' or '@field'): {spec}")
         data = read_json_input(path, flag="--questions")
         questions = data.get("questions", data) if isinstance(data, dict) else data
         if not isinstance(questions, list) or not all(isinstance(q, dict) for q in questions):
-            raise SystemExit(f"{path}: expected a list of question objects")
+            usage_exit(f"{path}: expected a list of question objects")
         sources.append((questions, rule))
     return sources
 
@@ -295,16 +294,16 @@ def _trigger_set_sources(specs: list, catalog) -> list:
         try:
             fmt, queries = ts.read_trigger_set(data, target=target)
         except ValueError as exc:
-            raise SystemExit(f"{path}: {exc}") from exc
+            usage_exit(f"{path}: {exc}")
         if fmt == ts.FORMAT_SKILL_CREATOR:
             if target not in names:
-                raise SystemExit(f"{spec}: skill-creator target {target!r} is not a skill in "
-                                 f"--catalog (have: {', '.join(sorted(names))})")
+                usage_exit(f"{spec}: skill-creator target {target!r} is not a skill in "
+                           f"--catalog (have: {', '.join(sorted(names))})")
             if len(names) > 1:
                 print(f"note: {path}: skill-creator negatives are read as 'no skill loads'; in a "
                       f"catalog of {len(names)} a rival load counts as a false trigger", file=sys.stderr)
         elif target:
-            raise SystemExit(f"{spec}: =TARGET applies to skill-creator sets only, this is {fmt}")
+            usage_exit(f"{spec}: =TARGET applies to skill-creator sets only, this is {fmt}")
         print(f"read {path} as {fmt} ({len(queries)} queries)", file=sys.stderr)
         rows = ts.to_questions(queries)["questions"]
         for row, q in zip(rows, queries, strict=True):
diff --git a/dokimi/dokimi/commands/catalog_probe.py b/dokimi/dokimi/commands/catalog_probe.py
index abecfcdda..4cfb97a28 100644
--- a/dokimi/dokimi/commands/catalog_probe.py
+++ b/dokimi/dokimi/commands/catalog_probe.py
@@ -13,6 +13,7 @@
 import threading
 from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
+from dokimi.exit_codes import usage_exit
 
 
 def cmd_catalog_trigger_probe(args: argparse.Namespace) -> None:
@@ -109,7 +110,7 @@ def _labelled_queries(args: argparse.Namespace, names: set) -> list:
         data = json.loads(Path(args.trigger_set).read_text(encoding="utf-8"))
         _fmt, queries = ts.read_trigger_set(data, target=args.target)
     except (OSError, ValueError) as exc:
-        raise SystemExit(f"--trigger-set: {exc}") from exc
+        usage_exit(f"--trigger-set: {exc}")
     queries = [q for q in queries if q.labelled][: args.limit or None]
     if not queries:  # else nothing runs, and an empty summary reads as a probe that ran
         raise InputError(f"--trigger-set has no labelled queries: {args.trigger_set}"
diff --git a/dokimi/dokimi/commands/dashboard.py b/dokimi/dokimi/commands/dashboard.py
index f0087e70a..af64a5fec 100644
--- a/dokimi/dokimi/commands/dashboard.py
+++ b/dokimi/dokimi/commands/dashboard.py
@@ -8,6 +8,7 @@
 import argparse
 import sys
 from pathlib import Path
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def cmd_dashboard_generate(args: argparse.Namespace) -> None:
@@ -24,7 +25,7 @@ def cmd_dashboard_generate(args: argparse.Namespace) -> None:
 
     if not data.products:
         print("⚠ No evaluation results found. Run benchmark first.", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     print(f"Found {len(data.products)} product(s): {', '.join(p.product for p in data.products)}")
 
@@ -40,7 +41,7 @@ def cmd_dashboard_generate(args: argparse.Namespace) -> None:
             print(f"✅ JSON data:          {json_path}")
     except OSError as exc:
         print(f"Error: cannot write the dashboard to {output_dir}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     # Print quick summary to stdout
     print(f"\n{'─'*50}")
diff --git a/dokimi/dokimi/commands/evaluate.py b/dokimi/dokimi/commands/evaluate.py
index 9d3602f31..ba725e85b 100644
--- a/dokimi/dokimi/commands/evaluate.py
+++ b/dokimi/dokimi/commands/evaluate.py
@@ -21,6 +21,7 @@
 from dokimi.eval.judge import JUDGE_PROVIDERS
 from dokimi.eval.judge_validity import DEFAULT_MIN_ACCURACY, NoUsablePairs
 from dokimi.utils import normalize_model_ref, write_text_or_exit
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _warn_judge_independence(
@@ -53,7 +54,7 @@ def _load_answers(path: str):
         sys.exit(2)
 
 
-def _write_json_or_exit(path: Path, payload: dict, code: int = 1) -> None:
+def _write_json_or_exit(path: Path, payload: dict, code: int = EXIT_USAGE) -> None:
     """Write ``payload`` as JSON to ``path``, or exit ``code`` naming ``path`` when it cannot be written."""
     write_text_or_exit(path, json.dumps(payload, indent=2), code)
 
@@ -110,11 +111,11 @@ def cmd_eval_panel_score(args: argparse.Namespace) -> None:
                     f"Error: --judge-configs entry '{entry}' must be 'role:model:provider'.",
                     file=sys.stderr,
                 )
-                sys.exit(1)
+                sys.exit(EXIT_USAGE)
             role, model, provider = parts
             if role not in JUDGE_ROLES:
                 print(f"Error: unknown role '{role}'. Valid: {list(JUDGE_ROLES)}", file=sys.stderr)
-                sys.exit(1)
+                sys.exit(EXIT_USAGE)
             judges.append(JudgeConfig(role=role.strip(), model=model.strip(), provider=provider.strip(),
                                       temperature=args.judge_temperature))
         roles = [j.role for j in judges]
@@ -123,7 +124,7 @@ def cmd_eval_panel_score(args: argparse.Namespace) -> None:
         unknown = [r for r in roles if r not in JUDGE_ROLES]
         if unknown:
             print(f"Error: unknown roles: {unknown}. Valid: {list(JUDGE_ROLES)}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
         judges = [JudgeConfig(role=r, model=args.model, provider=args.provider,
                               temperature=args.judge_temperature) for r in roles]
 
diff --git a/dokimi/dokimi/commands/explore.py b/dokimi/dokimi/commands/explore.py
index c958300d2..b64656295 100644
--- a/dokimi/dokimi/commands/explore.py
+++ b/dokimi/dokimi/commands/explore.py
@@ -8,6 +8,7 @@
 import argparse
 import sys
 from pathlib import Path
+from dokimi.exit_codes import EXIT_USAGE, usage_exit
 
 _TASKS_ROOT_HELP = (
     "Directory of exploration task YAML files (default: data/explore_tasks of a "
@@ -28,7 +29,7 @@ def cmd_explore_list(args: argparse.Namespace) -> None:
     try:
         tasks = discover_explore_tasks(root, default_repo_root=default_repo_root)
     except (FileNotFoundError, ValueError) as exc:  # a task file that cannot be read or parsed
-        raise SystemExit(str(exc)) from exc
+        usage_exit(str(exc))
     for task in tasks:
         n_refs = len(task.references)
         print(f"{task.id}\t{task.product}\t{n_refs} ref(s)\t{task.query[:60]}")
@@ -56,7 +57,7 @@ def _build_arms(specs: list[str], output_root: Path):
         elif spec.startswith("command:"):
             template = spec[len("command:"):]
             if not template:
-                raise SystemExit("'command:' arm requires a template")
+                usage_exit("'command:' arm requires a template")
 
             def _factory(task, _template=template, _spec=spec):
                 return CommandExplorer(
@@ -67,9 +68,7 @@ def _factory(task, _template=template, _spec=spec):
 
             arms[spec] = _factory
         else:
-            raise SystemExit(
-                f"Unknown explore arm: '{spec}'. Valid: oracle, empty, command:<template>"
-            )
+            usage_exit(f"Unknown explore arm: '{spec}'. Valid: oracle, empty, command:<template>")
     return arms
 
 
@@ -92,13 +91,13 @@ def cmd_explore_run(args: argparse.Namespace) -> None:
                 load_explore_task(t, root=root, default_repo_root=default_repo_root) for t in ids
             ]
     except (FileNotFoundError, ValueError) as exc:  # a task file that cannot be read or parsed
-        raise SystemExit(str(exc)) from exc
+        usage_exit(str(exc))
     if not tasks:
-        raise SystemExit("No tasks selected. Pass --tasks <id[,id]> or --all.")
+        usage_exit("No tasks selected. Pass --tasks <id[,id]> or --all.")
 
     specs = [s.strip() for s in args.arms.split(",") if s.strip()]
     if not specs:
-        raise SystemExit("No arms selected. Pass --arms oracle,empty[,command:<tmpl>].")
+        usage_exit("No arms selected. Pass --arms oracle,empty[,command:<tmpl>].")
     output_root = Path(args.output_dir)
     arms = _build_arms(specs, output_root)
 
@@ -116,7 +115,7 @@ def cmd_explore_run(args: argparse.Namespace) -> None:
         save_artifact("explore_runs", output, out_json)
     except OSError as exc:
         print(f"Error: cannot write {out_json}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
     print(f"Saved explore run artifact: {out_json}")
 
     if args.out_md:
diff --git a/dokimi/dokimi/commands/inputs.py b/dokimi/dokimi/commands/inputs.py
index c39f0d8c8..f9e4fa8ab 100644
--- a/dokimi/dokimi/commands/inputs.py
+++ b/dokimi/dokimi/commands/inputs.py
@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from dokimi.exit_codes import usage_exit
 
 
 def read_text_or_exit(path: str | None, flag: str) -> str | None:
@@ -19,14 +20,14 @@ def read_text_or_exit(path: str | None, flag: str) -> str | None:
     try:
         return Path(path).read_text(encoding="utf-8")
     except (OSError, UnicodeDecodeError) as exc:
-        raise SystemExit(f"cannot read {flag} {path}: {exc}") from None
+        usage_exit(f"cannot read {flag} {path}: {exc}")
 
 
 def placebo_text_for_arms_or_exit(path: str | None, arms: tuple[str, ...]) -> str | None:
-    """The ``--placebo-text`` of an analyze run, checked against its arms before any model call.
+    """The ``--placebo-text`` of an analyze or probe run, checked against its arms before any model call.
 
-    A typo in --arms or --placebo-text would otherwise cost the extraction calls that run
-    before the measurement checks the same thing.
+    A typo in --arms or --placebo-text would otherwise cost the model calls (the extraction
+    of an analyze run, the wordings of a probe) that run before the measurement checks the same thing.
     """
     from dokimi.novelty.measure import check_arms
 
@@ -34,5 +35,5 @@ def placebo_text_for_arms_or_exit(path: str | None, arms: tuple[str, ...]) -> st
     try:
         check_arms(arms, placebo_text)
     except ValueError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     return placebo_text
diff --git a/dokimi/dokimi/commands/library.py b/dokimi/dokimi/commands/library.py
index 6f8486997..8134ce12b 100644
--- a/dokimi/dokimi/commands/library.py
+++ b/dokimi/dokimi/commands/library.py
@@ -12,10 +12,11 @@
 
 import argparse
 import sys
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _load_custom(cls, flag: str, value):
-    """``cls()`` for the bundled file, else ``cls`` over the file named by ``flag``; exit 1 if it cannot be read."""
+    """``cls()`` for the bundled file, else ``cls`` over the file named by ``flag``; exit 2 if it cannot be read."""
     import yaml
     from pathlib import Path as _Path
 
@@ -24,12 +25,12 @@ def _load_custom(cls, flag: str, value):
     path = _Path(value)
     if not path.is_file():
         print(f"Error: {flag} {value}: not a file", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     try:
         return cls(path=path)
     except (OSError, ValueError, yaml.YAMLError) as exc:  # unreadable, not UTF-8, not YAML
         print(f"Error: cannot read {flag} {value}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
 def _load_registry(args):
@@ -40,7 +41,7 @@ def _load_registry(args):
 
 
 def _load_registry_checked(args):
-    """`_load_registry` for the `library` commands: a bad --registry file exits 1 (benchmark keeps its own)."""
+    """`_load_registry` for the `library` commands: a bad --registry file exits 2 (benchmark keeps its own)."""
     from dokimi.registry import ProductRegistry
     return _load_custom(ProductRegistry, "--registry", getattr(args, "registry", None))
 
@@ -61,7 +62,7 @@ def cmd_library_list(args: argparse.Namespace) -> None:
             keys = set(intents.products_for(domain))
         except KeyError as exc:
             print(f"Error: {exc}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
         entries = [e for e in entries if e.key in keys]
     if not entries:
         print("Registry is empty.")
@@ -83,7 +84,7 @@ def cmd_library_show(args: argparse.Namespace) -> None:
         entry = registry.get(args.name)
     except KeyError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     domains = _load_intents(args).domains_for(entry.key)
     print(f"Key          : {entry.key}")
     print(f"Name         : {entry.name}")
diff --git a/dokimi/dokimi/commands/novelty.py b/dokimi/dokimi/commands/novelty.py
index 4c87c3b31..79c3f8a3f 100644
--- a/dokimi/dokimi/commands/novelty.py
+++ b/dokimi/dokimi/commands/novelty.py
@@ -19,7 +19,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, NoReturn
 
-from dokimi.commands.inputs import placebo_text_for_arms_or_exit, read_text_or_exit
+from dokimi.commands.inputs import placebo_text_for_arms_or_exit
 from dokimi.defaults import (
     DEFAULT_ANSWER_MODEL,
     DEFAULT_ANSWER_PROVIDER,
@@ -28,6 +28,7 @@
     DEFAULT_JUDGE_MODEL,
     DEFAULT_JUDGE_PROVIDER,
 )
+from dokimi.exit_codes import usage_exit
 
 if TYPE_CHECKING:
     from dokimi.novelty.tiers import RunSettings
@@ -118,7 +119,9 @@ def cmd_novelty_analyze(args: argparse.Namespace) -> None:
         result = analyze(artifact_bundle.text, config,
                          extractor=extractor, answerer=answerer, judge=judge,
                          artifact_bundle=artifact_bundle)
-    except (SelfJudgeError, ExtractionError, ValueError) as exc:
+    except SelfJudgeError as exc:  # the judge is the answering model: the flags contradict
+        usage_exit(str(exc))
+    except (ExtractionError, ValueError) as exc:  # a model failure under way
         raise SystemExit(str(exc)) from None
 
     out_dir = Path(args.out_dir) if args.out_dir else _default_dir(args.artifact)
@@ -172,7 +175,7 @@ def cmd_novelty_probe(args: argparse.Namespace) -> None:
     """Run the paired probes against a saved atom set and print the 2×2."""
     from dokimi.novelty.atoms import load_atoms_or_exit
     from dokimi.novelty.bundle import check_answer_key
-    from dokimi.novelty.measure import SelfJudgeError, run_measurement
+    from dokimi.novelty.measure import SelfJudgeError, check_self_judge, run_measurement
     from dokimi.novelty.probes import build_probe_set
     from dokimi.novelty.report import build_probe_record
 
@@ -180,16 +183,20 @@ def cmd_novelty_probe(args: argparse.Namespace) -> None:
     _warn_unread(saved_spans, "the atoms probed here leave out whatever those spans assert")
     verdict = check_answer_key(args.artifact, saved.get("bundle"), source=args.atoms)
     if not verdict.ok:
-        raise SystemExit(verdict.message)
+        usage_exit(verdict.message)
     for note in verdict.notes:
         print(note, file=sys.stderr)
     settings = _settings(args)
-    placebo_text = read_text_or_exit(args.placebo_text, "--placebo-text")
+    placebo_text = placebo_text_for_arms_or_exit(args.placebo_text, _arms(args.arms))
     extractor, answerer, judge = _clients(args)
     if saved.get("extractor") == answerer.model:
         print(f"WARNING: {answerer.model} extracted these atoms, so the model under measurement "
               "wrote its own answer key; extract with a different --extract-model",
               file=sys.stderr)
+    try:  # before the paraphrase calls below, which are paid
+        check_self_judge(judge.model, answerer.model, args.allow_self_judge)
+    except SelfJudgeError as exc:
+        usage_exit(str(exc))
     paraphrases, reversals = settings.values["paraphrases"], settings.values["reversals"]
     probe_set = build_probe_set(
         atoms, client=extractor if paraphrases or reversals else None,
@@ -208,7 +215,7 @@ def cmd_novelty_probe(args: argparse.Namespace) -> None:
             allow_self_judge=args.allow_self_judge, seed=args.seed,
             placebo_text=placebo_text,
         )
-    except (SelfJudgeError, ValueError) as exc:
+    except ValueError as exc:  # a model failure under way
         raise SystemExit(str(exc)) from None
 
     payload = build_probe_record(
@@ -236,7 +243,7 @@ def cmd_novelty_items(args: argparse.Namespace) -> None:
     try:
         cells, warnings = load_probe_cells(args.probes)
     except ProbeFileError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     for warning in warnings:
         print(f"WARNING: {warning}", file=sys.stderr)
 
@@ -350,14 +357,14 @@ def _cmd_routing_all_vs_all(args: argparse.Namespace) -> None:
     try:
         field = _routing_field(args, set(), left_out)
     except RoutingInputError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     except (OSError, ValueError, RecursionError) as exc:
-        raise SystemExit(f"cannot load the field: {exc}") from None
+        usage_exit(f"cannot load the field: {exc}")
     try:
         try:
             queries_by_skill = load_queries_by_skill(args.queries_by_skill)
         except (OSError, UnicodeDecodeError) as exc:
-            raise SystemExit(f"cannot read the queries: {exc}") from None
+            usage_exit(f"cannot read the queries: {exc}")
         selector = _client(args.model, args.provider, "selector", args) if args.model else None
         if selector is not None:
             # One call per query with a content word, each sending every card in the field.
@@ -369,7 +376,7 @@ def _cmd_routing_all_vs_all(args: argparse.Namespace) -> None:
             )
         result = all_vs_all(field, queries_by_skill, client=selector, seed=args.seed)
     except RoutingInputError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     without = [c.name for c in field if c.name not in queries_by_skill]
     if without:
         print(f"WARNING: {len(without)} skill(s) in the field have no queries, so they only "
@@ -409,18 +416,16 @@ def _field_record(args: argparse.Namespace, competitors: list, left_out: list[st
 def _check_all_vs_all_args(args: argparse.Namespace) -> None:
     """Refuse the flag combinations ``--all-vs-all`` cannot run with."""
     if args.artifact:
-        raise SystemExit("--all-vs-all takes no --artifact: every skill in the field is the "
-                         "gold in turn")
+        usage_exit("--all-vs-all takes no --artifact: every skill in the field is the gold in turn")
     if args.queries or args.queries_from_headings:
-        raise SystemExit("--all-vs-all takes --queries-by-skill, not --queries or "
-                         "--queries-from-headings")
+        usage_exit("--all-vs-all takes --queries-by-skill, not --queries or --queries-from-headings")
     if args.repeats > 1:
-        raise SystemExit("--all-vs-all takes no --repeats: it makes one call per query")
+        usage_exit("--all-vs-all takes no --repeats: it makes one call per query")
     if not args.queries_by_skill:
-        raise SystemExit("--all-vs-all needs --queries-by-skill <file>: a JSON object of skill "
-                         "name to the requests that should select it")
+        usage_exit("--all-vs-all needs --queries-by-skill <file>: a JSON object of skill "
+                   "name to the requests that should select it")
     if not args.out:
-        raise SystemExit("--all-vs-all needs --out <file>")
+        usage_exit("--all-vs-all needs --out <file>")
 
 
 def _warn_blind_skills(result: dict, queries_by_skill: dict[str, list[str]]) -> None:
@@ -466,10 +471,7 @@ def _print_attractors(result: dict) -> None:
 def cmd_novelty_routing(args: argparse.Namespace) -> None:
     """Can this artifact be selected against its competitors? Lexical floor, model on top."""
     if args.repeats > 1 and not args.model:
-        raise SystemExit(
-            "--repeats needs --model: the lexical floor is deterministic, so repeating it "
-            "measures nothing"
-        )
+        usage_exit("--repeats needs --model: the lexical floor is deterministic, so repeating it measures nothing")
     from dokimi.novelty.routing import (
         RoutingInputError,
         check_field,
@@ -484,7 +486,7 @@ def cmd_novelty_routing(args: argparse.Namespace) -> None:
     if args.all_vs_all:
         return _cmd_routing_all_vs_all(args)
     if not args.artifact:
-        raise SystemExit("pass --artifact <skill:path>, or --all-vs-all for the whole field")
+        usage_exit("pass --artifact <skill:path>, or --all-vs-all for the whole field")
     try:
         gold, body = _routing_card(args.artifact)
         artifact_file = skill_file(args.artifact)
@@ -495,21 +497,21 @@ def cmd_novelty_routing(args: argparse.Namespace) -> None:
         left_out: list[str] = []
         competitors = _routing_field(args, {gold.name}, left_out)
     except RoutingInputError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     except (OSError, ValueError, RecursionError) as exc:
-        raise SystemExit(f"cannot load an artifact: {exc}") from None
+        usage_exit(f"cannot load an artifact: {exc}")
     # Checked before the query file is read, so the message is about the real problem.
     try:
         check_field(gold, competitors)
     except RoutingInputError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
 
     self_derived = False
     if args.queries:
         try:
             queries = load_queries(args.queries)
         except RoutingInputError as exc:
-            raise SystemExit(str(exc)) from None
+            usage_exit(str(exc))
     elif args.queries_from_headings:
         queries = headings_as_queries(body)
         self_derived = True
@@ -517,10 +519,8 @@ def cmd_novelty_routing(args: argparse.Namespace) -> None:
               "defines both the problem scope and its own relevance, so this is triage, not "
               "a routing rate", file=sys.stderr)
     else:
-        raise SystemExit(
-            "pass --queries <file> with requests written independently of the artifact, or "
-            "--queries-from-headings for a self-derived triage run"
-        )
+        usage_exit("pass --queries <file> with requests written independently of the artifact, or "
+                   "--queries-from-headings for a self-derived triage run")
     candidates = [gold, *competitors]
     lexical = dict(lexical_routing(candidates, queries, gold=0),
                    queries_self_derived=self_derived)
@@ -621,9 +621,8 @@ def _refuse_no_queries(args: argparse.Namespace, queries: list[str], self_derive
                                "reason": reason, "queries_self_derived": self_derived,
                                "n_candidates": n_candidates}, indent=2),
                    encoding="utf-8")
-    raise SystemExit(f"no usable queries: {reason}. Pass --queries <file> with requests "
-                     f"written independently of the artifact, one per line or a JSON "
-                     f"list. Wrote {out} with status no_queries")
+    usage_exit(f"no usable queries: {reason}. Pass --queries <file> with requests written independently "
+               f"of the artifact, one per line or a JSON list. Wrote {out} with status no_queries")
 
 
 def cmd_novelty_shorten(args: argparse.Namespace) -> None:
@@ -639,7 +638,7 @@ def cmd_novelty_shorten(args: argparse.Namespace) -> None:
     try:
         spans, atoms, note = entry_point_only(saved.get("bundle"), spans, atoms)
     except ValueError as exc:
-        raise SystemExit(f"{args.atoms}: {exc}") from None
+        usage_exit(f"{args.atoms}: {exc}")
     if note:
         print(note, file=sys.stderr)
     _warn_unread(spans, "every candidate keeps them, since what they carry is unknown")
@@ -740,7 +739,7 @@ def _bundle_from_args(args: argparse.Namespace):
             max_total_words=args.max_resource_words,
         )
     except (OSError, ValueError, RecursionError) as exc:
-        raise SystemExit(f"cannot load --artifact {args.artifact}: {exc}") from None
+        usage_exit(f"cannot load --artifact {args.artifact}: {exc}")
     note = artifact_bundle.coverage_note()
     if note:
         print(f"NOTE: {note}", file=sys.stderr)
@@ -1005,10 +1004,7 @@ def _role_models(args: argparse.Namespace) -> dict[str, tuple[str, str]]:
     if args.judge_model:
         judge_model, judge_provider = args.judge_model, args.judge_provider or args.provider
     else:
-        try:
-            judge_model, judge_provider = default_judge(args.model, args.judge_provider)
-        except ValueError as exc:
-            raise SystemExit(str(exc)) from None
+        judge_model, judge_provider = default_judge(args.model, args.judge_provider)
     extract_model = args.extract_model or judge_model
     extract_provider = args.extract_provider or judge_provider
     return {
@@ -1032,7 +1028,7 @@ def _estimate_usd(
 
     try:
         models = _role_models(args)
-    except SystemExit as exc:
+    except ValueError as exc:
         print(f"The USD estimate is unavailable: {exc}", file=sys.stderr)
         return None
     usd = estimate_usd(by_role, n_tokens, models, tier, context_share)
@@ -1052,7 +1048,10 @@ def _estimate_usd(
 
 def _clients(args: argparse.Namespace):
     """Build the three role clients, defaulting so roles never silently collapse."""
-    models = _role_models(args)
+    try:
+        models = _role_models(args)
+    except ValueError as exc:
+        usage_exit(str(exc))
     return (
         _client(*models["extractor"], "extractor", args),
         _client(*models["answerer"], "answerer", args),
@@ -1127,7 +1126,7 @@ def _arms(spec: str) -> tuple[str, ...]:
     try:
         return parse_arms(spec)
     except ValueError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
 
 
 def _default_dir(ref: str) -> Path:
diff --git a/dokimi/dokimi/commands/novelty_view_inputs.py b/dokimi/dokimi/commands/novelty_view_inputs.py
index 21855ef4f..fd45db27d 100644
--- a/dokimi/dokimi/commands/novelty_view_inputs.py
+++ b/dokimi/dokimi/commands/novelty_view_inputs.py
@@ -1,22 +1,23 @@
 # Copyright (C) 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-"""`novelty view`: read the saved novelty artifact and atoms file, or exit 1 naming the bad one."""
+"""`novelty view`: read the saved novelty artifact and atoms file, or exit 2 naming the bad one."""
 
 from __future__ import annotations
 
 import sys
 from pathlib import Path
 from typing import NoReturn
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _fail(message: str) -> NoReturn:
     print(f"Error: {message}", file=sys.stderr)
-    raise SystemExit(1)
+    raise SystemExit(EXIT_USAGE)
 
 
 def load_view_inputs(novelty_path: str, atoms_path: str):
-    """``(artifact, atoms, spans)`` from the two files; an unreadable or invalid one exits 1."""
+    """``(artifact, atoms, spans)`` from the two files; an unreadable or invalid one exits 2."""
     from dokimi.artifacts import load_artifact
     from dokimi.novelty.atoms import load_atoms
 
diff --git a/dokimi/dokimi/commands/orchestrate.py b/dokimi/dokimi/commands/orchestrate.py
index f31b9bbac..e544b7068 100644
--- a/dokimi/dokimi/commands/orchestrate.py
+++ b/dokimi/dokimi/commands/orchestrate.py
@@ -18,6 +18,7 @@
     JUDGE_MODEL_FOR_PROVIDER,
     JUDGE_MODEL_HELP,
 )
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def cmd_evaluate(args: argparse.Namespace) -> None:
@@ -26,7 +27,7 @@ def cmd_evaluate(args: argparse.Namespace) -> None:
 
     if not getattr(args, "repo", None) and not getattr(args, "description", None):
         print("Error: either --repo or --description must be provided.", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     print(f"Starting full evaluation pipeline for {args.product}")
     if args.repo:
@@ -71,7 +72,7 @@ def cmd_evaluate(args: argparse.Namespace) -> None:
         )
     except OSError as exc:  # a missing --custom-questions file, an unusable --output-dir
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     # Run pipeline
     try:
diff --git a/dokimi/dokimi/commands/personas.py b/dokimi/dokimi/commands/personas.py
index 73248afdd..7b8a8195c 100644
--- a/dokimi/dokimi/commands/personas.py
+++ b/dokimi/dokimi/commands/personas.py
@@ -14,6 +14,7 @@
 from dokimi.defaults import DEFAULT_GENERATOR_MODEL, DEFAULT_GENERATOR_PROVIDER
 from dokimi.personas.analyzer import PersonaAnalyzer
 from dokimi.personas.generator import PersonaGenerator
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def cmd_personas_discover(args: argparse.Namespace) -> None:
@@ -25,7 +26,7 @@ def cmd_personas_discover(args: argparse.Namespace) -> None:
             "✗ Either --repo or --description must be provided.",
             file=sys.stderr,
         )
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     generator = PersonaGenerator(model=args.model, provider=args.provider)
 
@@ -79,40 +80,40 @@ def cmd_personas_approve(args: argparse.Namespace) -> None:
 
     if not persona_file.exists():
         print(f"✗ File not found: {persona_file}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     # Validate JSON structure
     try:
         personas = json.loads(persona_file.read_text(encoding="utf-8"))
     except OSError as e:
         print(f"✗ Cannot read {persona_file}: {e}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     except ValueError as e:  # JSONDecodeError and bad UTF-8
         print(f"✗ Cannot parse {persona_file}: {e}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     required_keys = {"product", "personas"}
     if not isinstance(personas, dict):
         print("✗ Invalid persona file. Expected a JSON object with keys: "
               f"{sorted(required_keys)}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     if not required_keys.issubset(personas.keys()):
         print(f"✗ Invalid persona file. Missing keys: {required_keys - personas.keys()}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     if not isinstance(personas["personas"], list):
         print("✗ Invalid persona file. `personas` must be a list", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     # Check each persona
     for p in personas["personas"]:
         if not isinstance(p, dict):
             print(f"✗ Invalid persona file. Each persona must be an object, got: {p!r}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
         required_fields = {"id", "name", "skill_level"}
         missing = required_fields - set(p.keys())
         if missing:
             print(f"✗ Persona '{p.get('id', '?')}' missing fields: {missing}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
 
     print(f"✓ Validated {len(personas['personas'])} personas")
     print(f"✓ File approved: {persona_file}")
diff --git a/dokimi/dokimi/commands/questions.py b/dokimi/dokimi/commands/questions.py
index 89cc2d795..c3e7e9dcf 100644
--- a/dokimi/dokimi/commands/questions.py
+++ b/dokimi/dokimi/commands/questions.py
@@ -13,15 +13,16 @@
 
 from dokimi.commands._output import exit_on_unwritable
 from dokimi.defaults import DEFAULT_GENERATOR_MODEL, DEFAULT_GENERATOR_PROVIDER
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _load_questions_json(path: str):
-    """Parse the questions file, or exit 1 naming it when it is missing, unreadable or not JSON."""
+    """Parse the questions file, or exit 2 naming it when it is missing, unreadable or not JSON."""
     try:
         return json.loads(Path(path).read_text(encoding="utf-8"))
     except (OSError, ValueError, RecursionError) as exc:
         print(f"Error: cannot read questions from {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
 def _extract_questions(questions_data, source: str) -> list:
@@ -32,34 +33,34 @@ def _extract_questions(questions_data, source: str) -> list:
         raw = questions_data
     else:
         print(f"Error: expected a JSON object or list of questions in {source}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     if not isinstance(raw, list):
         print(f"Error: 'questions' must be a list in {source}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     return raw
 
 
 def _read_json_input(path: str):
-    """The parsed JSON at ``path``, or exit 1 with a message naming the file."""
+    """The parsed JSON at ``path``, or exit 2 with a message naming the file."""
     try:
         return json.loads(Path(path).read_text(encoding="utf-8"))
     except (OSError, ValueError) as exc:  # ValueError covers JSONDecodeError and bad UTF-8
         print(f"Error: cannot read {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
 def _load_personas(path: str) -> list:
-    """The ``personas`` list of a personas file, or exit 1 with a message naming the file."""
+    """The ``personas`` list of a personas file, or exit 2 with a message naming the file."""
     data = _read_json_input(path)
     personas = data.get("personas") if isinstance(data, dict) else None
     if not isinstance(personas, list):
         print(f"Error: {path} must be a JSON object with a 'personas' list", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     for persona in personas:
         if not isinstance(persona, dict) or not {"id", "name", "skill_level"} <= persona.keys():
             print(f"Error: each persona in {path} must be an object with 'id', 'name' and "
                   f"'skill_level', got: {persona!r}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
     return personas
 
 
@@ -71,7 +72,7 @@ def cmd_questions_panel_review(args: argparse.Namespace) -> None:
     unknown = [r for r in reviewers if r not in DEFAULT_REVIEWERS]
     if unknown:
         print(f"Error: unknown reviewers: {unknown}. Valid: {DEFAULT_REVIEWERS}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     questions_data = _load_questions_json(args.questions)
 
@@ -88,7 +89,7 @@ def cmd_questions_panel_review(args: argparse.Namespace) -> None:
                 answers = read(questions_data, source=args.questions, section="answers")
             except RecordError as exc:
                 print(f"Error: {exc}", file=sys.stderr)
-                sys.exit(1)
+                sys.exit(EXIT_USAGE)
             raw = [{"question": r.question_text} for r in answers]
         else:
             raw = list(questions_data.values())
@@ -96,7 +97,7 @@ def cmd_questions_panel_review(args: argparse.Namespace) -> None:
         raw = questions_data
     if not isinstance(raw, list):
         print("Error: expected a list of questions", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     questions = [
         (q.get("question") or q.get("text") or "").strip() if isinstance(q, dict) else str(q)
         for q in raw if q
@@ -141,10 +142,10 @@ def cmd_questions_refine(args: argparse.Namespace) -> None:
         raw = load_questions(args.questions, validate=False).questions
     except OSError as exc:
         print(f"Error: cannot read {args.questions}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     except ValueError as exc:  # ArtifactValidationError: malformed JSON structure
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     target = {
         "beginner":     args.target_beginner,
@@ -178,11 +179,13 @@ def _validate_before_fill(cleaned: list) -> None:
             "questions": cleaned,
         }))
 
+    from dokimi.artifacts import ArtifactValidationError
+
     try:
         report = refiner.refine(raw, before_fill=_validate_before_fill if gap_filler else None)
-    except ValueError as exc:  # ArtifactValidationError: the input set cannot be gap-filled
+    except ArtifactValidationError as exc:  # the input set cannot be gap-filled (refused by before_fill)
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     print(report.summary())
 
     if not args.dry_run:
@@ -301,7 +304,7 @@ def cmd_questions_generate(args: argparse.Namespace) -> None:
         topics = _read_json_input(args.topics)
         if not isinstance(topics, list):
             print(f"Error: {args.topics} must be a JSON list of topics", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
     else:
         print(f"Extracting seed topics for {args.product}...")
 
@@ -321,7 +324,7 @@ def cmd_questions_generate(args: argparse.Namespace) -> None:
             )
         except ValueError as exc:
             print(f"Error: {exc}", file=sys.stderr)
-            raise SystemExit(1) from exc
+            raise SystemExit(EXIT_USAGE) from exc
 
         extractor = RagasSeedExtractor(mcp_client=mcp_client, cache_dir=Path(".cache/topics"))
         topics = extractor.extract_topics(
diff --git a/dokimi/dokimi/commands/repo.py b/dokimi/dokimi/commands/repo.py
index bed5ea661..88f64ad09 100644
--- a/dokimi/dokimi/commands/repo.py
+++ b/dokimi/dokimi/commands/repo.py
@@ -13,6 +13,8 @@
 from pathlib import Path
 from typing import Any
 
+from dokimi.exit_codes import EXIT_USAGE
+
 
 def _normalize_whitespace(text: str, max_len: int | None = 100) -> str:
     """One line: whitespace runs become one space, control characters are escaped, then truncated."""
@@ -22,26 +24,64 @@ def _normalize_whitespace(text: str, max_len: int | None = 100) -> str:
 
 
 def _write_json(path: str, payload: dict) -> None:
-    """Write a --out report as JSON, or exit 1 with `cannot write`."""
+    """Write a --out report as JSON, or exit 2 with `cannot write`."""
     try:
         Path(path).write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
     except OSError as exc:
         print(f"✗ cannot write {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
-def cmd_repo_validate(args: argparse.Namespace) -> None:
-    """Validate a repository's repo-eval.yaml and its tasks against one snapshot."""
-    from dokimi.repos import ManifestError, RepoSource, SourceError, check_repo, open_source
-    from dokimi.repos.source import base_opener
+def _source_tree(args: argparse.Namespace) -> tuple:
+    """The source (source, tree): a malformed string, unpinned remote or pinned local path that is not the repository root is a usage error (2); a clone, fetch or pin resolution failure is 1."""
+    from dokimi.repos import RepoSource, SourceError, open_source
+    from dokimi.repos.source import SourceArgumentError
 
     try:
         source = RepoSource.parse(args.source)
-        tree = open_source(source, _cache_dir(args))
-        manifest = _load_manifest(tree, args)
-    except (SourceError, ManifestError) as exc:
+    except SourceError as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    # 2 = malformed source string, unpinned remote, pinned local path inside a repository, manifest/profile errors; 1 = clone/fetch/resolve of a pin
+    # (incl. pinned local non-git source, pin absent locally, remote pin missing from origin).
+    try:
+        return source, open_source(source, _cache_dir(args))
+    except SourceArgumentError as exc:  # a pinned local path that is not the repository root
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    except SourceError as exc:
         print(f"✗ {exc}", file=sys.stderr)
         sys.exit(1)
+    except (OSError, ValueError) as exc:
+        # A cache dir that cannot be made, or git output that is not UTF-8: a failed read, not a usage error.
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _manifest_or_exit(tree, args: argparse.Namespace, *, guidance_default: bool = False,
+                      also_usage: tuple = ()) -> Any:
+    """The manifest of the tree. A bad manifest or a manifest path that leaves the tree is a usage error
+    (2); a failed `git show` (a blob fetched lazily from origin) is a fetch failure (1)."""
+    from dokimi.repos import ManifestError, SourceError
+    from dokimi.repos.source import SourceArgumentError
+
+    try:
+        return _load_manifest(tree, args, guidance_default=guidance_default)
+    except (SourceArgumentError, ManifestError, *also_usage) as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    except SourceError as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_repo_validate(args: argparse.Namespace) -> None:
+    """Validate a repository's repo-eval.yaml and its tasks against one snapshot."""
+    from dokimi.repos import check_repo
+    from dokimi.repos.source import base_opener
+
+    source, tree = _source_tree(args)
+    manifest = _manifest_or_exit(tree, args)
     open_base = base_opener(source, tree)
     report = check_repo(tree, manifest, open_base)
     if open_base is None:
@@ -79,21 +119,16 @@ def _read_static(path: str) -> Any:
         return json.loads(Path(path).read_text(encoding="utf-8"))
     except (OSError, ValueError, RecursionError) as exc:  # ValueError: bad JSON or UTF-8
         print(f"✗ --static {path}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
 
 def cmd_repo_scan(args: argparse.Namespace) -> None:
     """L0: check every mechanically checkable claim in the guidance against the same tree."""
     from dokimi.artifacts import save_artifact, stamp
-    from dokimi.repos import ManifestError, RepoSource, SourceError, open_source
     from dokimi.repos.l0 import scan_repo
 
-    try:
-        tree = open_source(RepoSource.parse(args.source), _cache_dir(args))
-        manifest = _load_manifest(tree, args, guidance_default=True)
-    except (SourceError, ManifestError, OSError, ValueError, RecursionError) as exc:
-        print(f"✗ {exc}", file=sys.stderr)
-        sys.exit(1)
+    _, tree = _source_tree(args)
+    manifest = _manifest_or_exit(tree, args, guidance_default=True, also_usage=(OSError,))
     static = _read_static(args.static) if args.static else None
     payload = scan_repo(tree, manifest, static)
     if args.out:
@@ -101,7 +136,7 @@ def cmd_repo_scan(args: argparse.Namespace) -> None:
             save_artifact("repo_readiness", payload, Path(args.out))
         except OSError as exc:
             print(f"✗ cannot write {args.out}: {exc}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
     static_info = payload["static"]
     static_errors = static_info["errors"] if static_info is not None else []
     for problem in static_errors:  # on stderr in --json mode too
@@ -145,21 +180,16 @@ def _scan_gate(payload: dict, fail_on_fail: bool) -> None:
 def cmd_repo_inspect(args: argparse.Namespace) -> None:
     """Static inspection: instruction files, check surfaces, launch risks, file inventory."""
     from dokimi.artifacts import save_artifact, stamp
-    from dokimi.repos import RepoSource, SourceError, open_source
     from dokimi.repos.environment import inspect_repo
 
-    try:
-        tree = open_source(RepoSource.parse(args.source), _cache_dir(args))
-    except SourceError as exc:
-        print(f"✗ {exc}", file=sys.stderr)
-        sys.exit(1)
+    _, tree = _source_tree(args)
     payload = inspect_repo(tree, large=args.large_bytes)
     if args.out:
         try:
             save_artifact("repo_environment", payload, Path(args.out))
         except OSError as exc:
             print(f"✗ cannot write {args.out}: {exc}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
     if args.json:
         print(json.dumps(stamp("repo_environment", dict(payload)), indent=2))
     else:
@@ -186,14 +216,21 @@ def cmd_repo_inspect(args: argparse.Namespace) -> None:
 def cmd_repo_fetch(args: argparse.Namespace) -> None:
     """Clone (once) and fetch a pinned remote source into the cache; print the SHA."""
     from dokimi.repos import RepoSource, SourceError, open_source
-    from dokimi.repos.source import GitTree
+    from dokimi.repos.source import GitTree, SourceArgumentError
 
-    try:
+    try:  # the source as typed: a usage error
         source = RepoSource.parse(args.source)
         if source.rev is None:
             raise SourceError("fetch needs a pinned source: <url-or-path>@<rev>")
-        tree = open_source(source, _cache_dir(args))
     except SourceError as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:  # the clone and fetch: a runtime failure (network, git, unknown revision)
+        tree = open_source(source, _cache_dir(args))
+    except SourceArgumentError as exc:  # a pinned local path that is not the repository root
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    except (SourceError, OSError, ValueError) as exc:
         print(f"✗ {exc}", file=sys.stderr)
         sys.exit(1)
     assert isinstance(tree, GitTree)
@@ -203,10 +240,33 @@ def cmd_repo_fetch(args: argparse.Namespace) -> None:
         print(f"{tree.sha}\t{tree.git_dir}")
 
 
+def _check_reach_flags(args: argparse.Namespace, kinds: tuple[str, ...]) -> None:
+    """Refuse a flag that would drop a scenario kind silently, or spend a budget that is not one."""
+    from dokimi.repos.reach import ReachError
+
+    # A typo would otherwise drop a scenario kind silently and still spend the budget.
+    unknown_kinds = sorted(set(kinds) - {"root", "cwd", "read"})
+    if unknown_kinds:
+        raise ReachError(f"unknown --scenarios kind(s) {', '.join(unknown_kinds)} (known: root, cwd, read)")
+    if not math.isfinite(args.budget) or args.budget <= 0:
+        raise ReachError(f"--budget must be > 0, got {args.budget:g}")
+
+
+def _tree_read_exit_code(exc: Exception) -> int:
+    """Reading the manifest or the probed files: a path that leaves the tree, a bad manifest or a bad
+    scenario selection is a usage error (2); a failed `git show` or ls-tree is a fetch failure (1)."""
+    from dokimi.repos import SourceError
+    from dokimi.repos.source import SourceArgumentError
+
+    git_failure = isinstance(exc, SourceError) and not isinstance(exc, SourceArgumentError)
+    return 1 if git_failure else EXIT_USAGE
+
+
 def cmd_repo_reach(args: argparse.Namespace) -> None:
     """L1 reach probe: which guidance files one harness/version/model loads."""
     from dokimi.repos import ManifestError, RepoSource, SourceError, open_source
     from dokimi.repos.harness_profile import ProfileError, load_profile
+    from dokimi.repos.source import SourceArgumentError
     from dokimi.repos.reach import (
         ReachError,
         format_matrix,
@@ -219,15 +279,22 @@ def cmd_repo_reach(args: argparse.Namespace) -> None:
 
     kinds = tuple(k.strip() for k in args.scenarios.split(",") if k.strip())
     only = tuple(args.only or ())
-    try:
-        # A typo would otherwise drop a scenario kind silently and still spend the budget.
-        unknown_kinds = sorted(set(kinds) - {"root", "cwd", "read"})
-        if unknown_kinds:
-            raise ReachError(f"unknown --scenarios kind(s) {', '.join(unknown_kinds)} (known: root, cwd, read)")
-        if not math.isfinite(args.budget) or args.budget <= 0:
-            raise ReachError(f"--budget must be > 0, got {args.budget:g}")
+    try:  # the arguments as typed: a usage error
+        _check_reach_flags(args, kinds)
         profile = load_profile(args.harness)
-        tree = open_source(RepoSource.parse(args.source), _cache_dir(args))
+        source = RepoSource.parse(args.source)
+    except (SourceError, ProfileError, ReachError) as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:  # the clone and fetch: a runtime failure
+        tree = open_source(source, _cache_dir(args))
+    except SourceArgumentError as exc:  # a pinned local path that is not the repository root
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    except (SourceError, OSError, ValueError) as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(1)
+    try:  # the manifest and the scenarios it selects: a usage error; a failed git read is a fetch failure (1)
         manifest = _load_manifest(tree, args, guidance_default=True)
         files = probe_files(tree, manifest, profile)
         available = [s.id for s in scenarios(files, kinds)]
@@ -241,16 +308,20 @@ def cmd_repo_reach(args: argparse.Namespace) -> None:
         planned_count = len(scenarios(files, kinds, only))
         if not planned_count:
             raise ReachError("no scenario selected (check --scenarios and --only)")
-        print(f"{len(files)} guidance files, {planned_count} scenarios, "
-              f"at most ${args.budget:g} each", file=sys.stderr)
-        out_dir = Path(args.out)
+    except (SourceError, ManifestError, ReachError) as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        sys.exit(_tree_read_exit_code(exc))
+    print(f"{len(files)} guidance files, {planned_count} scenarios, "
+          f"at most ${args.budget:g} each", file=sys.stderr)
+    out_dir = Path(args.out)
+    try:  # the harness runs: a runtime failure
         payload = run_reach(
             tree=tree, manifest=manifest, profile=profile, model=args.model, out_dir=out_dir,
             bin_path=args.bin, work_dir=Path(args.work_dir) if args.work_dir else None, kinds=kinds,
             only=only, salt=args.salt, max_turns=args.max_turns, budget_usd=args.budget,
             timeout_s=args.timeout, keep=args.keep,
         )
-    except (SourceError, ManifestError, ProfileError, ReachError) as exc:
+    except (SourceError, ProfileError, ReachError) as exc:  # ProfileError: --bin cannot run its version command
         print(f"✗ {exc}", file=sys.stderr)
         sys.exit(1)
     path = save_reach(payload, out_dir)
@@ -263,23 +334,22 @@ def cmd_repo_reach(args: argparse.Namespace) -> None:
 def cmd_repo_budget(args: argparse.Namespace) -> None:
     """What the repository puts into an agent's context at start-up, lazily and on demand."""
     from dokimi.artifacts import save_artifact, stamp
-    from dokimi.repos import RepoSource, SourceError, open_source
     from dokimi.repos.budget import budget
     from dokimi.repos.harness_profile import ProfileError, load_profile
 
-    try:
+    try:  # the harness profile: a usage error
         profile = load_profile(args.harness)
-        tree = open_source(RepoSource.parse(args.source), _cache_dir(args))
-    except (SourceError, ProfileError) as exc:
+    except ProfileError as exc:
         print(f"✗ {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
+    _, tree = _source_tree(args)
     payload = budget(tree, profile.guidance_names, profile.import_max_depth)
     if args.out:
         try:
             save_artifact("repo_budget", payload, Path(args.out))
         except OSError as exc:
             print(f"✗ cannot write {args.out}: {exc}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
     if args.json:
         print(json.dumps(stamp("repo_budget", dict(payload)), indent=2))
     else:
@@ -402,7 +472,8 @@ def register(sub, positive_int) -> None:
     scan_p.add_argument("--static", default=None,
                         help="repo_static.v1 document the repository's `static` entry point wrote; merged into "
                         "the report, its claims replacing the framework's on the same file, line and text. "
-                        "An invalid document is reported and makes the command exit 1")
+                        "A file that cannot be read or is not JSON exits 2; a schema-invalid document is "
+                        "reported and makes the command exit 1")
     scan_p.add_argument("--out", default=None, help="Write the repo_readiness.v1 report to this file")
     scan_p.add_argument("--json", action="store_true", help="Print the full report as JSON")
     scan_p.add_argument("--fail-on-fail", action="store_true", dest="fail_on_fail",
diff --git a/dokimi/dokimi/commands/repo_run.py b/dokimi/dokimi/commands/repo_run.py
index be2310534..11dd70cda 100644
--- a/dokimi/dokimi/commands/repo_run.py
+++ b/dokimi/dokimi/commands/repo_run.py
@@ -20,6 +20,7 @@
     from dokimi.repos.workspace import Arm
 
 from dokimi.repos.harness_profile import DELEGATION_MODES
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _context(args: argparse.Namespace, out: Path, pin: bool = False):
@@ -389,16 +390,16 @@ def cmd_repo_report(args: argparse.Namespace) -> None:
     batch_dir = Path(args.batch_dir)
     if not batch_dir.is_dir():
         print(f"✗ not a directory: {batch_dir}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     try:
         if args.hits:
             found = load_hits(batch_dir)
             print(json.dumps(found, indent=2) if args.json else format_hits(found))
             return
         summary = summarize(batch_dir)
-    except CellFileError as exc:
+    except CellFileError as exc:  # a cell file that is not the JSON repo run wrote: an input refusal
         print(f"✗ {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     print(json.dumps(summary, indent=2) if args.json else format_report(summary))
 
 
@@ -411,14 +412,14 @@ def cmd_repo_compare(args: argparse.Namespace) -> None:
     for d in dirs:
         if not d.is_dir():
             print(f"✗ not a directory: {d}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
     arms = [a for spec in args.arm for a in spec.split(",") if a] if args.arm else None
     try:
         summary = compare(dirs, args.baseline, arms, args.model, tuple(args.metric or ()),
                           pass_k=args.pass_k, path_stability=args.path_stability, tasks=args.task)
-    except (CompareError, CellFileError) as exc:
+    except (CompareError, CellFileError) as exc:  # an unusable baseline, arm, metric or cell file: exit 2
         print(f"✗ {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     print(json.dumps(summary, indent=2) if args.json else format_compare(summary))
 
 
diff --git a/dokimi/dokimi/commands/report.py b/dokimi/dokimi/commands/report.py
index 7e7449c0f..728f83937 100644
--- a/dokimi/dokimi/commands/report.py
+++ b/dokimi/dokimi/commands/report.py
@@ -9,6 +9,7 @@
 import sys
 import json
 from pathlib import Path
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def _write_combined_report(args, regular_runs, golden_runs, run_ids, warnings) -> None:
@@ -28,7 +29,7 @@ def _write_combined_report(args, regular_runs, golden_runs, run_ids, warnings) -
         )
     except OSError as exc:
         print(f"Error: cannot write {args.out}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
 
 
 def cmd_report_model_compare(args: argparse.Namespace) -> None:
@@ -41,11 +42,11 @@ def cmd_report_model_compare(args: argparse.Namespace) -> None:
     run_ids = [rid.strip() for rid in args.run_ids.split(",")]
     if not run_ids or any(not rid for rid in run_ids) or len(set(run_ids)) != len(run_ids):
         print("Error: --run-ids must contain unique, non-empty labels", file=sys.stderr)
-        raise SystemExit(1)
+        raise SystemExit(EXIT_USAGE)
 
     if not args.regular_runs and not args.golden_runs:
         print("Error: must provide at least --regular-runs or --golden-runs", file=sys.stderr)
-        raise SystemExit(1)
+        raise SystemExit(EXIT_USAGE)
 
     for flag, paths in (("--regular-runs", args.regular_runs), ("--golden-runs", args.golden_runs)):
         if paths and len(paths) != len(run_ids):
@@ -54,7 +55,7 @@ def cmd_report_model_compare(args: argparse.Namespace) -> None:
                 f"number of run IDs ({len(run_ids)})",
                 file=sys.stderr,
             )
-            raise SystemExit(1)
+            raise SystemExit(EXIT_USAGE)
 
     regular_runs = []
     if args.regular_runs:
@@ -102,10 +103,10 @@ def cmd_report_eval(args: argparse.Namespace) -> None:
         generate_report(eval_path=args.eval, out_path=out)
     except RecordError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
     except OSError as exc:
         print(f"Error: cannot write {out}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
 
 
 def cmd_report_generate(args: argparse.Namespace) -> None:
@@ -118,29 +119,29 @@ def cmd_report_generate(args: argparse.Namespace) -> None:
         eval_data = json.loads(Path(args.eval).read_text(encoding="utf-8"))
     except OSError as exc:
         print(f"Error: cannot read {args.eval}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
     except ValueError as exc:  # not UTF-8 or not JSON
         print(f"Error: {args.eval} is not valid JSON: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
     # Every --format: a report of no evaluations has nothing to show, and an empty
-    # eval means the run that wrote it judged nothing.
+    # eval means the run that wrote it judged nothing: a failed run, exit 1.
     evaluations = eval_data.get("evaluations", []) if isinstance(eval_data, dict) else eval_data
     if isinstance(evaluations, list) and not evaluations:  # {}, {"evaluations": []}, []
         print(f"Error: --eval {args.eval} holds no evaluations", file=sys.stderr)
         raise SystemExit(1)
     if not isinstance(eval_data, dict):
         print(f"Error: {args.eval} must hold a JSON object", file=sys.stderr)
-        raise SystemExit(1)
+        raise SystemExit(EXIT_USAGE)
     from dokimi.questions.artifact import load_questions
 
     try:
         questions_data = load_questions(args.questions).artifact
     except OSError as exc:
         print(f"Error: cannot read {args.questions}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
     except ValueError as exc:  # ArtifactValidationError: names the record and the fix
         print(f"Error: {exc}", file=sys.stderr)
-        raise SystemExit(1) from exc
+        raise SystemExit(EXIT_USAGE) from exc
 
     # Generate report
     generator = ReportGenerator()
@@ -152,7 +153,7 @@ def cmd_report_generate(args: argparse.Namespace) -> None:
         )
     except RecordError as exc:
         print(f"Error: {args.eval} {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
 
     print(f"Loaded {len(eval_data.get('evaluations', []))} evaluations from {args.eval}")
     print(f"Loaded {len(questions_data.get('questions', []))} questions from {args.questions}")
@@ -164,7 +165,7 @@ def cmd_report_generate(args: argparse.Namespace) -> None:
         output_path.write_text(report, encoding="utf-8")
     except OSError as exc:
         print(f"Error: cannot write {output_path}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
 
     print(f"\n✅ Generated report: {output_path}")
 
diff --git a/dokimi/dokimi/commands/run.py b/dokimi/dokimi/commands/run.py
index 46f48d699..570ec4b81 100644
--- a/dokimi/dokimi/commands/run.py
+++ b/dokimi/dokimi/commands/run.py
@@ -11,6 +11,7 @@
 import sys
 from pathlib import Path
 
+from dokimi.exit_codes import EXIT_USAGE
 from dokimi.report.json_report import write_json
 from dokimi.report.markdown_report import write_compare_report, write_run_report
 from dokimi.runner.compare import CompareInputError, compare_snapshots
@@ -19,33 +20,33 @@
 
 
 def _run_or_exit(root: Path, spec_path: Path) -> dict:
-    """Run the benchmark; a bad spec or doc selection exits 2, an unreadable doc exits 1.
+    """Run the benchmark; a bad spec, an unreadable doc or a doc selection it refuses exits 2.
 
-    Exit 1 is also the verdict code of --strict, and an unwritable output exits 1 too (see _write_outputs).
+    Exit 1 is the verdict code of --strict (see cmd_run).
     """
     try:
         load_benchmark_spec(spec_path)  # fail on a spec that cannot be read, parsed or validated, before the run
     except (RuntimeError, ValueError) as exc:
         print(f"Error: {spec_path}: {exc}", file=sys.stderr)
-        sys.exit(2)
+        sys.exit(EXIT_USAGE)
     try:
         return run_benchmark(root, spec_path)
     except DocLoadError as exc:
         print(f"❌ {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     except DocSelectionError as exc:  # e.g. fewer documents than the manifest's min_docs
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(2)
+        sys.exit(EXIT_USAGE)
 
 
 def _write_outputs(writes) -> None:
-    """Run each (writer, data, path); an unwritable path exits 1 naming it."""
+    """Run each (writer, data, path); an unwritable path exits 2 naming it."""
     for writer, data, path in writes:
         try:
             writer(data, path)
         except OSError as exc:
             print(f"Error: cannot write {path}: {exc}", file=sys.stderr)
-            sys.exit(1)
+            sys.exit(EXIT_USAGE)
 
 
 def cmd_run(args: argparse.Namespace) -> None:
@@ -140,7 +141,7 @@ def cmd_compare(args: argparse.Namespace) -> None:
         result = compare_snapshots(base, cand, spec=spec_data)
     except CompareInputError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(2)
+        sys.exit(EXIT_USAGE)
     _write_outputs(((write_json, result, out_json), (write_compare_report, result, out_md)))
     print(json.dumps(result["diff"], indent=2))
 
diff --git a/dokimi/dokimi/commands/subjects.py b/dokimi/dokimi/commands/subjects.py
index 6f5420561..97d416912 100644
--- a/dokimi/dokimi/commands/subjects.py
+++ b/dokimi/dokimi/commands/subjects.py
@@ -19,6 +19,7 @@
     JUDGE_MODEL_FOR_PROVIDER,
     JUDGE_MODEL_HELP,
 )
+from dokimi.exit_codes import EXIT_USAGE, usage_exit
 
 
 def cmd_subjects_list(args: argparse.Namespace) -> None:
@@ -27,12 +28,10 @@ def cmd_subjects_list(args: argparse.Namespace) -> None:
     # in-repo default root. Name the flag instead of printing an empty list that
     # reads like "no subjects exist".
     if not args.subjects_root:
-        raise SystemExit(
-            "no subjects root given; pass --subjects-root <checkout>/evaluation/subjects"
-        )
+        usage_exit("no subjects root given; pass --subjects-root <checkout>/evaluation/subjects")
     root = Path(args.subjects_root)
     if not root.is_dir():
-        raise SystemExit(f"--subjects-root is not a directory: {root}")
+        usage_exit(f"--subjects-root is not a directory: {root}")
     paths = sorted([*root.glob("*.toml"), *root.glob("*.json")])
     for path in paths:
         try:
@@ -52,7 +51,7 @@ def cmd_subjects_show(args: argparse.Namespace) -> None:
         descriptor = load_subject(args.subject)
     except (ValueError, FileNotFoundError) as exc:
         print(f"Error loading subject: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     if descriptor.subject.kind == "repo":
         print(json.dumps({
@@ -98,11 +97,11 @@ def cmd_subjects_run(args: argparse.Namespace) -> None:
         descriptor = load_subject(args.subject)
     except (ValueError, FileNotFoundError) as exc:
         print(f"Error loading subject: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     if descriptor.subject.kind == "repo":
         print("Error: repo subjects are not run by `subjects run` yet; "
               "check them with `repo validate`", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     # Attached, not produced: a novelty run costs atoms x probes x arms x (answer + grade), so it is
     # produced by `novelty analyze` and named here by path. A bad path fails now, before any cell
     # runs, rather than after the expensive part.
@@ -112,12 +111,12 @@ def cmd_subjects_run(args: argparse.Namespace) -> None:
         )
     except (ValueError, FileNotFoundError, json.JSONDecodeError) as exc:
         print(f"Error loading novelty artifact: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     try:
         work_tasks = _validate_subject_work_args(descriptor, args)
     except (ValueError, FileNotFoundError) as exc:
         print(f"Error loading subject work: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     out_dir, baseline_arm, questions = _run_plan(descriptor, args)
     matrix_path = out_dir / "matrix.cells.json"
@@ -126,7 +125,7 @@ def cmd_subjects_run(args: argparse.Namespace) -> None:
         matrix_path.write_text(json.dumps(_matrix_config_for_run(descriptor, args), indent=2), encoding="utf-8")
     except OSError as exc:
         print(f"Error: cannot write {out_dir}: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
 
     awareness_runs: list[dict] = []
     for product, questions_path in zip(descriptor.suite.products, questions, strict=True):
@@ -266,7 +265,7 @@ def register(sub, positive_int) -> None:
 
 
 def _run_plan(descriptor, args: argparse.Namespace) -> tuple[Path, str, list[str]]:
-    """The output dir, baseline arm name and per-product questions, or exit 1 when the descriptor cannot run.
+    """The output dir, baseline arm name and per-product questions, or exit 2 when the descriptor cannot run.
 
     Checked before anything is written, so a descriptor that cannot run leaves no output dir behind."""
     from dokimi.subjects.loader import awareness_arm_specs
@@ -279,7 +278,7 @@ def _run_plan(descriptor, args: argparse.Namespace) -> tuple[Path, str, list[str
         _validate_unique_product_output_dirs(descriptor.suite.products)
     except ValueError as exc:
         print(f"Error: {exc}", file=sys.stderr)
-        sys.exit(1)
+        sys.exit(EXIT_USAGE)
     return out_dir, baseline_arm, questions
 
 
@@ -406,7 +405,7 @@ def _run_subject_work(descriptor, args: argparse.Namespace, *, out_dir: Path, ta
     try:
         runner.validate_harnesses()
     except ValueError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     try:
         artifact = runner.run()
     except PreflightError as exc:
diff --git a/dokimi/dokimi/commands/tasks.py b/dokimi/dokimi/commands/tasks.py
index 0559f1ba6..cf04ea8c3 100644
--- a/dokimi/dokimi/commands/tasks.py
+++ b/dokimi/dokimi/commands/tasks.py
@@ -9,6 +9,8 @@
 import sys
 from pathlib import Path
 
+from dokimi.exit_codes import usage_exit
+
 _TASKS_ROOT_HELP = (
     "Directory holding one sub-directory per task (each with task.toml or task.md). "
     "Required for bare task names and for --all; the tasks live in a separate "
@@ -30,7 +32,7 @@ def _tasks_root(args: argparse.Namespace) -> Path | None:
         return None
     root = Path(args.tasks_root)
     if not root.is_dir():
-        raise SystemExit(f"--tasks-root is not a directory: {root}")
+        usage_exit(f"--tasks-root is not a directory: {root}")
     return root
 
 
@@ -40,7 +42,7 @@ def cmd_tasks_list(args: argparse.Namespace) -> None:
     try:
         tasks = discover_tasks(_tasks_root(args))
     except ValueError as exc:
-        raise SystemExit(str(exc)) from None
+        usage_exit(str(exc))
     for task in tasks:
         tags = task.metadata.get("tags") or []
         difficulty = task.metadata.get("difficulty", "?")
@@ -78,13 +80,13 @@ def cmd_tasks_inspect(args: argparse.Namespace) -> None:
     try:
         reports = [r.as_dict() for r in inspect_path(Path(args.path))]
     except FileNotFoundError as exc:
-        raise SystemExit(f"Error: {exc}") from None
+        usage_exit(f"Error: {exc}")
     payload = {"root": str(args.path), "items": reports}
     if args.out:
         try:
             save_artifact("task_inspect", payload, Path(args.out))
         except OSError as exc:
-            raise SystemExit(f"Error: cannot write {args.out}: {exc}") from None
+            usage_exit(f"Error: cannot write {args.out}: {exc}")
     if args.json:
         print(json.dumps(stamp("task_inspect", dict(payload)), indent=2, default=str))
     else:
@@ -128,7 +130,7 @@ def _select_swebench(args: argparse.Namespace) -> list:
 
     ids = None if args.all else [t.strip() for t in (args.tasks or "").split(",") if t.strip()]
     if ids == []:
-        raise SystemExit("No tasks selected. Pass --tasks <instance_id[,...]> or --all.")
+        usage_exit("No tasks selected. Pass --tasks <instance_id[,...]> or --all.")
     try:
         if ids is None:
             skipped = sorted(KNOWN_BAD.keys() & {str(r.get("instance_id")) for r in read_instances(Path(args.swe_bench))})
@@ -137,10 +139,10 @@ def _select_swebench(args: argparse.Namespace) -> list:
                       + ", ".join(skipped), file=sys.stderr)
         tasks = load_swebench(Path(args.swe_bench), Path(args.output_dir) / "swe-bench-tasks", ids)
     except (OSError, ValueError) as exc:  # SweBenchError and bad JSON are ValueErrors
-        raise SystemExit(f"--swe-bench: {exc}") from None
+        usage_exit(f"--swe-bench: {exc}")
     if not tasks:  # an empty run must not exit 0 with an empty artifact
-        raise SystemExit(f"--swe-bench: no runnable rows in {args.swe_bench} "
-                         "(--all skips the known-bad rows)")
+        usage_exit(f"--swe-bench: no runnable rows in {args.swe_bench} "
+                   "(--all skips the known-bad rows)")
     return tasks
 
 
@@ -157,9 +159,9 @@ def _select_tasks(args: argparse.Namespace) -> list:
             task_names = [t.strip() for t in args.tasks.split(",") if t.strip()]
             tasks = [load_task(t, root=root) for t in task_names]
     except (ValueError, OSError, RecursionError) as exc:  # a missing or unreadable task, deeply nested YAML
-        raise SystemExit(f"Error: {exc}") from None
+        usage_exit(f"Error: {exc}")
     if not tasks:
-        raise SystemExit("No tasks selected. Pass --tasks <name[,name]> or --all.")
+        usage_exit("No tasks selected. Pass --tasks <name[,name]> or --all.")
     return tasks
 
 
@@ -196,7 +198,7 @@ def cmd_tasks_run(args: argparse.Namespace) -> None:
 
     harnesses = [h.strip() for h in args.harnesses.split(",") if h.strip()]
     if not harnesses:
-        raise SystemExit("No harnesses selected. Pass --harnesses codex,claude-code.")
+        usage_exit("No harnesses selected. Pass --harnesses codex,claude-code.")
     if args.baseline_harness and args.baseline_harness not in harnesses:
         print(f"Also running baseline harness: {args.baseline_harness}")
         harnesses.insert(0, args.baseline_harness)
@@ -218,7 +220,7 @@ def cmd_tasks_run(args: argparse.Namespace) -> None:
     try:
         runner.validate_harnesses()
     except ValueError as exc:
-        raise SystemExit(f"Error: {exc}") from None
+        usage_exit(f"Error: {exc}")
     try:
         output = runner.run()
     except PreflightError as exc:
@@ -231,7 +233,7 @@ def cmd_tasks_run(args: argparse.Namespace) -> None:
     try:
         save_artifact("task_runs", output, out_json)
     except OSError as exc:
-        raise SystemExit(f"Error: cannot write {out_json}: {exc}") from None
+        usage_exit(f"Error: cannot write {out_json}: {exc}")
     print(f"Saved task run artifact: {out_json}")
 
     out_md = Path(args.out_md) if args.out_md else out_json.with_suffix(".md")
@@ -241,7 +243,7 @@ def cmd_tasks_run(args: argparse.Namespace) -> None:
         out_md.parent.mkdir(parents=True, exist_ok=True)
         out_md.write_text(render_task_runs_report(output), encoding="utf-8")
     except OSError as exc:
-        raise SystemExit(f"Error: cannot write {out_md}: {exc} (the artifact is saved at {out_json})") from None
+        usage_exit(f"Error: cannot write {out_md}: {exc} (the artifact is saved at {out_json})")
     print(f"Saved task run report:   {out_md}")
 
     _print_summary(output)
diff --git a/dokimi/dokimi/commands/tools.py b/dokimi/dokimi/commands/tools.py
index 5908fab7a..9e0ba9789 100644
--- a/dokimi/dokimi/commands/tools.py
+++ b/dokimi/dokimi/commands/tools.py
@@ -16,6 +16,7 @@
 from pathlib import Path
 
 from dokimi.defaults import DEFAULT_ANSWER_PROVIDER
+from dokimi.exit_codes import EXIT_USAGE, usage_exit
 
 PROVIDERS = ["openai", "anthropic", "amazon-bedrock", "google-vertex", "openrouter", "openai-codex"]
 
@@ -95,16 +96,17 @@ def _print_skipped(skipped: dict, n_groups: int) -> None:
 
 
 def _write_items(path: str, items: list) -> None:
-    """Write the probe items to ``path``, or exit 1 naming it when it cannot be written."""
+    """Write the probe items to ``path``, or exit 2 naming it when it cannot be written."""
     try:
         Path(path).write_text(json.dumps(items, indent=1), encoding="utf-8")
     except OSError as exc:
         print(f"Error: cannot write --items-out {path}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
 
 
 def _save_result(data: dict, path: str) -> None:
-    """Save the tool_preference artifact to ``path``, or exit 1 naming it when it cannot be written."""
+    """Save the tool_preference artifact to ``path``. An unwritable path exits 2 naming it; a payload
+    the schema rejects exits 1."""
     from dokimi.artifacts import ArtifactValidationError, save_artifact
 
     try:
@@ -114,7 +116,7 @@ def _save_result(data: dict, path: str) -> None:
         raise SystemExit(1) from None
     except (OSError, ValueError) as exc:  # unwritable path, including an empty one (pathlib ValueError)
         print(f"Error: cannot write {path}: {exc}", file=sys.stderr)
-        raise SystemExit(1) from None
+        raise SystemExit(EXIT_USAGE) from None
 
 
 def _check_out_json_writable(path: str) -> None:
@@ -133,7 +135,7 @@ def _check_out_json_writable(path: str) -> None:
         tmp.unlink()
     except (OSError, ValueError) as exc:
         print(f"Error: cannot write {path}: {exc}", file=sys.stderr)
-        raise SystemExit(2) from None
+        raise SystemExit(EXIT_USAGE) from None
 
 
 def cmd_tools_preference(args: argparse.Namespace) -> None:
@@ -142,11 +144,11 @@ def cmd_tools_preference(args: argparse.Namespace) -> None:
     try:
         doc = tp.load_groups(json.loads(Path(args.groups).read_text(encoding="utf-8")))
     except (OSError, RecursionError, ValueError, tp.GroupsError) as exc:
-        raise SystemExit(f"--groups {args.groups}: {exc}") from exc
+        usage_exit(f"--groups {args.groups}: {exc}")
     factors = list(dict.fromkeys(f for f in args.factors.split(",") if f)) if args.factors else list(tp.FACTORS)
     unknown = sorted(set(factors) - set(tp.FACTORS))
     if unknown:
-        raise SystemExit(f"--factors: unknown {unknown} (known: {', '.join(tp.FACTORS)})")
+        usage_exit(f"--factors: unknown {unknown} (known: {', '.join(tp.FACTORS)})")
     items = tp.build_items(doc, factors)
     n_pair = sum(i["kind"] == "pair" for i in items)
     print(f"{len(doc['groups'])} groups -> {len(items)} items ({n_pair} pair, {len(items) - n_pair} control)"
@@ -159,7 +161,7 @@ def cmd_tools_preference(args: argparse.Namespace) -> None:
     if args.dry_run:
         return
     if not args.model:
-        raise SystemExit("--model is required unless --dry-run")
+        usage_exit("--model is required unless --dry-run")
     _check_out_json_writable(args.out_json)
 
     def progress(done: int, total: int) -> None:
@@ -184,14 +186,14 @@ def progress(done: int, total: int) -> None:
         first = next(r["error"] for r in results if r["error"])
         print(f"Error: all {len(results)} call(s) failed ({first}); see results[].error in {args.out_json}",
               file=sys.stderr)
-        raise SystemExit(2)
+        raise SystemExit(2)  # the documented "run incomplete" exit (docs/quickstart.md), not a usage refusal
     if data["summary"]["n_skipped"]:
         why = (f"--max-cost-usd {args.max_cost_usd:g} reached"
                if u["cost_known_calls"] == u["n_calls"]
                else "a call came back with no price, so --max-cost-usd cannot be enforced")
         print(f"Error: {why}; {data['summary']['n_skipped']} of {len(results)} call(s) not run, "
               f"the summary covers the rest. See {args.out_json}", file=sys.stderr)
-        raise SystemExit(2)
+        raise SystemExit(2)  # the documented "run incomplete" exit (docs/quickstart.md), not a usage refusal
 
 
 def register(sub: argparse._SubParsersAction, positive_int) -> None:
diff --git a/dokimi/dokimi/eval/arm_runner.py b/dokimi/dokimi/eval/arm_runner.py
index 4b6045055..fff189845 100644
--- a/dokimi/dokimi/eval/arm_runner.py
+++ b/dokimi/dokimi/eval/arm_runner.py
@@ -37,7 +37,7 @@
 from dokimi.eval.judge_context import build as build_judge_context
 from dokimi.eval.judge_context import cite as cite_judge_materials
 from dokimi.eval.judge_context import join_injected
-from dokimi.eval.session import REMINDER_ARM_SUFFIX, run_session, session_turns_of
+from dokimi.eval.session import REMINDER_ARM_SUFFIX, check_session_questions, run_session, session_turns_of
 from dokimi.metrics.usage import to_record
 from dokimi.treatments.base import Treatment
 
@@ -232,10 +232,7 @@ def run(
         n = len(questions)
         if self.session_turns is not None:
             # Before any answer is paid for: a question short of follow-ups fails the run.
-            for i, q in enumerate(questions):
-                qid = question_id(q)
-                session_turns_of(q, question_text_of(q), self.session_turns,
-                                 label=f"#{i}" if qid is None else str(qid))
+            check_session_questions(questions, self.session_turns)
         results: Dict[int, Dict[str, Any]] = {}
         lock = threading.Lock()
         done = [0]
diff --git a/dokimi/dokimi/eval/arms_run.py b/dokimi/dokimi/eval/arms_run.py
index 34e05e405..8e178bde6 100644
--- a/dokimi/dokimi/eval/arms_run.py
+++ b/dokimi/dokimi/eval/arms_run.py
@@ -16,6 +16,7 @@
 import functools
 from collections.abc import Callable
 from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
 
 from dokimi.defaults import (
     DEFAULT_ANSWER_MODEL,
@@ -28,6 +29,10 @@
 from dokimi.eval.question_text import EmptyQuestionError
 from dokimi.utils import question_id
 
+if TYPE_CHECKING:
+    from dokimi.eval import Judge, JudgePanel
+    from dokimi.eval.arm_runner import ArmRunner
+
 
 @dataclass(frozen=True)
 class ArmsRunConfig:
@@ -79,12 +84,18 @@ class LibraryIdError(ValueError):
     """No library id can be named for a doc arm, so the run stops before any answer."""
 
 
+class ProbeError(ValueError):
+    """A sampling probe, a real call before the run, failed: a run failure (exit 1), not a refused input."""
+
+
 class MatrixCellError(ValueError):
-    """A matrix cell refused or failed its run: the reason's message, and the cell's name."""
+    """A matrix cell refused or failed its run: the reason's message, the cell's name, and whether
+    the cell was refused in setup (``usage``, exit 2) or failed while it ran (exit 1)."""
 
-    def __init__(self, cell: str, reason: Exception) -> None:
+    def __init__(self, cell: str, reason: Exception, *, usage: bool) -> None:
         super().__init__(str(reason))
         self.cell = cell
+        self.usage = usage
 
 
 def cell_config(config: ArmsRunConfig, cell: MatrixCellDescriptor) -> ArmsRunConfig:
@@ -212,7 +223,7 @@ def probe_sampling(model: str, provider: str, temperature, seed) -> None:
         llm_call_with_usage("Reply with OK.", model=model, provider=provider,
                             max_tokens=16, temperature=temperature, seed=seed)
     except Exception as exc:
-        raise ValueError(
+        raise ProbeError(
             f"Probe call to '{provider}/{model}' with temperature={temperature}, "
             f"seed={seed} failed, so every call in the run would too: {exc}"
         ) from exc
@@ -320,17 +331,28 @@ def _judge_records(runner, judge, config: ArmsRunConfig, records: list[dict]):
     )
 
 
-def run_arms(config: ArmsRunConfig, specs: list[str], questions: list[dict]) -> dict:
-    """Answer *questions* in every arm of *specs*, judge them when ``config.judge``, and
-    return the ``arms.v1`` output.
+@dataclass
+class PreparedArms:
+    """What a run needs, built and checked before any answer is paid for."""
+
+    runner: ArmRunner
+    judge: Judge | JudgePanel | None
+    library_id: str | None
+
 
-    Everything that can be refused (the config, the arms, the plugins, the sampling, the
-    judge) is refused before the first answer is paid for. A doc arm with no library id
-    raises :class:`LibraryIdError`; anything else refused raises ``ValueError``.
+def prepare_arms(config: ArmsRunConfig, specs: list[str], questions: list[dict]) -> PreparedArms:
+    """Setup and every refusal: the config, the arms, the plugins, the sampling, the judge.
+
+    Nothing here answers a question. A refused input raises ``ValueError`` (a usage error, exit 2),
+    a doc arm with no library id raises :class:`LibraryIdError`, and a failed sampling probe, a real
+    call, raises :class:`ProbeError` (a run failure, exit 1).
     """
     from dokimi.eval.arm_runner import ArmRunner
+    from dokimi.eval.session import check_session_questions
 
     _refuse_judged_session(config)
+    if config.session_turns is not None:
+        check_session_questions(questions, config.session_turns)
     treatments, library_id, plugin_set = _treatments(config, specs, questions)
     check_sampling_support(config)
     judge = None
@@ -354,22 +376,35 @@ def run_arms(config: ArmsRunConfig, specs: list[str], questions: list[dict]) ->
         session_turns=config.session_turns,
         turn_reminder=config.turn_reminder,
     )
-    records = runner.run(
+    return PreparedArms(runner=runner, judge=judge, library_id=library_id)
+
+
+def run_prepared(prepared: PreparedArms, config: ArmsRunConfig, questions: list[dict]) -> dict:
+    """Answer *questions* with a prepared run, judge them when it has a judge, and return the
+    ``arms.v1`` output. A failure here is a run failure (exit 1), not a refused input."""
+    records = prepared.runner.run(
         library_name=config.product,
         questions=questions,
-        library_id=library_id,
+        library_id=prepared.library_id,
         concurrency=config.concurrency,
     )
-    evaluations = None if judge is None else _judge_records(runner, judge, config, records)
-    return runner.build_output(
+    evaluations = None if prepared.judge is None else _judge_records(prepared.runner, prepared.judge, config, records)
+    return prepared.runner.build_output(
         config.product, records, evaluations=evaluations, baseline_arm=config.baseline_arm,
-        judge=judge,
+        judge=prepared.judge,
     )
 
 
+def run_arms(config: ArmsRunConfig, specs: list[str], questions: list[dict]) -> dict:
+    """Answer *questions* in every arm of *specs*, judge them when ``config.judge``, and
+    return the ``arms.v1`` output. Everything that can be refused is refused before the first answer."""
+    return run_prepared(prepare_arms(config, specs, questions), config, questions)
+
+
 def check_matrix(config: ArmsRunConfig, cells: list[MatrixCellDescriptor]) -> None:
     """Refuse a matrix with a cell the in-process runner cannot run, or whose provider would
-    refuse the sampling on every answer. Raises ``ValueError`` naming the first such cell."""
+    refuse the sampling on every answer. Raises ``ValueError`` naming the first such cell, or
+    :class:`ProbeError` when the cell's sampling probe fails."""
     for cell in cells:
         try:
             validate_supported_matrix_harnesses([cell])
@@ -378,6 +413,8 @@ def check_matrix(config: ArmsRunConfig, cells: list[MatrixCellDescriptor]) -> No
     for cell in cells:
         try:
             check_sampling_support(cell_config(config, cell))
+        except ProbeError as exc:
+            raise ProbeError(f"matrix cell '{cell.name}': {exc}") from exc
         except ValueError as exc:
             raise ValueError(f"matrix cell '{cell.name}': {exc}") from exc
 
@@ -389,15 +426,23 @@ def run_matrix(config: ArmsRunConfig, cells: list[MatrixCellDescriptor], specs:
     *on_cell* as soon as the cell finishes, so a later cell's failure keeps the earlier ones.
 
     Every cell is checked (:func:`check_matrix`) before the first one is paid for. A cell
-    that fails raises :class:`MatrixCellError` naming it; a bad question record
-    (``EmptyQuestionError``) and :class:`LibraryIdError` are not a cell's and pass through.
+    that fails raises :class:`MatrixCellError` naming it, with ``usage`` set when the cell was
+    refused in setup; a bad question record (``EmptyQuestionError``) and :class:`LibraryIdError`
+    are not a cell's and pass through.
     """
     check_matrix(config, cells)
-    for cell in cells:
+    prepared_cells = []
+    for cell in cells:  # every cell is set up and probed before the first answer
+        cell_cfg = cell_config(config, cell)
         try:
-            output = run_arms(cell_config(config, cell), specs, questions)
+            prepared_cells.append((cell, cell_cfg, prepare_arms(cell_cfg, specs, questions)))
         except (EmptyQuestionError, LibraryIdError):
             raise
         except (ValueError, OSError, RecursionError) as exc:
-            raise MatrixCellError(cell.name, exc) from exc
+            raise MatrixCellError(cell.name, exc, usage=not isinstance(exc, ProbeError)) from exc
+    for cell, cell_cfg, prepared in prepared_cells:
+        try:
+            output = run_prepared(prepared, cell_cfg, questions)
+        except (ValueError, OSError, RecursionError) as exc:
+            raise MatrixCellError(cell.name, exc, usage=False) from exc
         on_cell(cell, output)
diff --git a/dokimi/dokimi/eval/session.py b/dokimi/dokimi/eval/session.py
index 338a2d303..286fcae54 100644
--- a/dokimi/dokimi/eval/session.py
+++ b/dokimi/dokimi/eval/session.py
@@ -20,7 +20,9 @@
 from typing import Any, Dict, List, Optional, Sequence
 
 from dokimi import caching
+from dokimi.eval.question_text import question_text_of
 from dokimi.llm import LLM
+from dokimi.utils import question_id
 from dokimi.metrics.usage import UsageRecord
 
 logger = logging.getLogger(__name__)
@@ -52,6 +54,15 @@ def session_turns_of(question: Dict[str, Any], question_text: str,
     return [question_text, *follow_ups[: n_turns - 1]]
 
 
+def check_session_questions(questions: List[Dict[str, Any]], session_turns: int) -> None:
+    """Refuse a question that cannot run as a *session_turns* session (``ValueError``, exit 2):
+    a missing or malformed ``follow_ups``, or fewer follow-ups than the session needs."""
+    for i, q in enumerate(questions):
+        qid = question_id(q)
+        session_turns_of(q, question_text_of(q), session_turns,
+                         label=f"#{i}" if qid is None else str(qid))
+
+
 def _with_reminder(text: str, reminder: Optional[str]) -> str:
     if reminder is None:
         return text
diff --git a/dokimi/dokimi/exit_codes.py b/dokimi/dokimi/exit_codes.py
new file mode 100644
index 000000000..472a0fef7
--- /dev/null
+++ b/dokimi/dokimi/exit_codes.py
@@ -0,0 +1,29 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""Exit code of an input or usage refusal (the exit-code table is in docs/quickstart.md).
+
+A bad input file, an input the command cannot use, a flag combination it refuses and a
+missing credential all exit 2. Exit 1 is for a verdict or a gate that ran and failed.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import NoReturn
+
+EXIT_USAGE = 2
+#: Exit code of a run that ran and failed: a model call refused, a judge or a gate that failed.
+EXIT_FAILURE = 1
+
+
+def usage_exit(message: str) -> NoReturn:
+    """Print ``message`` to stderr and exit :data:`EXIT_USAGE`.
+
+    The raised ``SystemExit`` keeps ``message`` as its text, so an in-process caller can read it
+    with ``str()``; its ``code`` is still the status.
+    """
+    print(message, file=sys.stderr)
+    error = SystemExit(message)
+    error.code = EXIT_USAGE
+    raise error
diff --git a/dokimi/dokimi/external/trigger_set.py b/dokimi/dokimi/external/trigger_set.py
index 4c7990b82..3af81959a 100644
--- a/dokimi/dokimi/external/trigger_set.py
+++ b/dokimi/dokimi/external/trigger_set.py
@@ -44,6 +44,14 @@
 ExpectedSkill = Union[str, List[str], None]
 
 
+class TriggerSetInputError(ValueError):
+    """The question sources cannot form a trigger set: a duplicate id, a question with no text, or an
+    ``@field`` rule that labels none of its source's questions.
+
+    A usage error (exit 2). A rewrite that fails is a runtime error and stays a plain ValueError.
+    """
+
+
 class LabelUnresolved(LookupError):
     """An ``@field.path`` label rule found no such field on the question.
 
@@ -173,25 +181,31 @@ def build_trigger_set(
     sources: Sequence[tuple],
     catalog: Sequence[Skill],
     rewrite: Optional[Callable[[str], str]] = None,
+    specs: Optional[Sequence[str]] = None,
 ) -> List[TriggerQuery]:
     """Label, optionally rewrite, and lint questions.
 
     *sources* is ``[(questions, rule), ...]`` — a question list and the
     :func:`resolve_label` rule that labels it. *rewrite* maps question text to a
-    new query text and is given nothing but that text.
+    new query text and is given nothing but that text. When *specs* (one name per
+    source) is given, an ``@field`` rule that labels none of its source's questions
+    is refused, naming the source; without it such questions stay unlabelled. A ``None``
+    entry in *specs* exempts its source: a ``--trigger-set`` file is passed with the
+    ``@expected_skill`` rule, and a file with no labels is valid there.
     """
     out: List[TriggerQuery] = []
     seen: set = set()
-    for questions, rule in sources:
+    for index, (questions, rule) in enumerate(sources):
+        first = len(out)
         for q in questions:
             raw = question_id(q)
             qid = str(f"q{len(out) + 1}" if raw is None else raw)
             if qid in seen:
-                raise ValueError(f"duplicate question id across sources: {qid}")
+                raise TriggerSetInputError(f"duplicate question id across sources: {qid}")
             seen.add(qid)
             text = q.get("text") or q.get("question") or q.get("prompt") or q.get("question_text") or ""
             if not isinstance(text, str) or not text.strip():
-                raise ValueError(
+                raise TriggerSetInputError(
                     f"question {qid} has no text (looked in text, question, prompt, question_text)")
             try:
                 tq = TriggerQuery(id=qid, text=text, expected_skill=resolve_label(q, rule))
@@ -201,13 +215,22 @@ def build_trigger_set(
             tq.source_text = prior if isinstance(prior, str) else None
             extra = q.get(REACH_FIELDS)
             tq.reach = dict(extra) if isinstance(extra, dict) else {}
-            if rewrite is not None:
-                tq.source_text, tq.text = tq.source_text or text, rewrite(text).strip()
-                if not tq.text:
-                    raise ValueError(f"rewrite returned empty text for question {qid}")
-            tq.lint = lint_query(tq, catalog)
-            tq.lint["label_unresolved"] = not tq.labelled
             out.append(tq)
+        chunk = out[first:]
+        if (specs is not None and specs[index] is not None and rule.startswith("@") and chunk
+                and not any(tq.labelled for tq in chunk)):
+            # A typo in the path, not a set of negatives.
+            raise TriggerSetInputError(f"{specs[index]}: {rule} resolves for none of {len(chunk)} questions "
+                                       "(none has that field, so the file has no labels)")
+    # Every question has passed validation before the first rewrite call, so a refused set costs no model call.
+    for tq in out:
+        if rewrite is not None:
+            original = tq.text
+            tq.source_text, tq.text = tq.source_text or original, rewrite(original).strip()
+            if not tq.text:
+                raise ValueError(f"rewrite returned empty text for question {tq.id}")
+        tq.lint = lint_query(tq, catalog)
+        tq.lint["label_unresolved"] = not tq.labelled
     return out
 
 
diff --git a/dokimi/dokimi/novelty/analyze.py b/dokimi/dokimi/novelty/analyze.py
index b87522c07..ba1da32ce 100644
--- a/dokimi/dokimi/novelty/analyze.py
+++ b/dokimi/dokimi/novelty/analyze.py
@@ -165,6 +165,7 @@ def analyze(
             file it came from, which is the cut an author needs to decide what belongs in
             the body. Without it the run is entry-point-only and says so.
     """
+    measure.check_self_judge(judge.model, answerer.model, config.allow_self_judge)
     warnings: list[str] = []
     span_list = spans.segment(text)
     extraction = atoms_mod.ExtractionReport()
diff --git a/dokimi/dokimi/novelty/artifact.py b/dokimi/dokimi/novelty/artifact.py
index 7b110e93b..463c8c899 100644
--- a/dokimi/dokimi/novelty/artifact.py
+++ b/dokimi/dokimi/novelty/artifact.py
@@ -11,6 +11,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from dokimi.exit_codes import usage_exit
 
 
 def load_artifact_text(ref: str) -> tuple[str, str, str, str, str]:
@@ -44,4 +45,4 @@ def load_artifact_or_exit(ref: str) -> tuple[str, str, str, str, str]:
     try:
         return load_artifact_text(ref)
     except (OSError, ValueError, RecursionError) as exc:
-        raise SystemExit(f"cannot load --artifact {ref}: {exc}") from None
+        usage_exit(f"cannot load --artifact {ref}: {exc}")
diff --git a/dokimi/dokimi/novelty/atoms.py b/dokimi/dokimi/novelty/atoms.py
index 330b5e2b7..f4bf27991 100644
--- a/dokimi/dokimi/novelty/atoms.py
+++ b/dokimi/dokimi/novelty/atoms.py
@@ -27,6 +27,7 @@
 
 from .client import LLMClient, accepting
 from .spans import Span
+from dokimi.exit_codes import usage_exit
 
 ATOM_KINDS = ("proposition", "edge", "motif", "contract", "example")
 ATOM_TAGS = (
@@ -668,5 +669,5 @@ def load_atoms_or_exit(path) -> tuple[list[Atom], list[Span], dict]:
         atoms, spans = _atoms_from_record(data)
         _check_bundle_shape(data.get("bundle"))
     except (OSError, ValueError, RecursionError) as exc:
-        raise SystemExit(f"cannot read atoms from {path}: {exc}") from None
+        usage_exit(f"cannot read atoms from {path}: {exc}")
     return atoms, spans, data
diff --git a/dokimi/dokimi/novelty/measure.py b/dokimi/dokimi/novelty/measure.py
index 2143fcb58..97ce0a002 100644
--- a/dokimi/dokimi/novelty/measure.py
+++ b/dokimi/dokimi/novelty/measure.py
@@ -100,6 +100,19 @@ class SelfJudgeError(ValueError):
     """Raised when the judge model is also the answering model."""
 
 
+def check_self_judge(judge_model: str, answerer_model: str, allow_self_judge: bool) -> None:
+    """Refuse a judge that is the answering model, before any paid call.
+
+    Callers run this before extraction or paraphrase calls, so a refused run costs nothing.
+    """
+    if judge_model == answerer_model and not allow_self_judge:
+        raise SelfJudgeError(
+            f"judge model {judge_model!r} is the answering model; grading a response with "
+            "the model that produced it inflates the score. Pass a different --judge-model, "
+            "or --allow-self-judge to do it deliberately."
+        )
+
+
 @dataclass
 class ProbeRun:
     """One (probe, arm) result."""
@@ -255,12 +268,7 @@ def run_measurement(
             irrelevant context actively harms them.
         seed: Seed for the ``shuffled`` control, so the control is reproducible.
     """
-    if judge.model == answerer.model and not allow_self_judge:
-        raise SelfJudgeError(
-            f"judge model {judge.model!r} is the answering model; grading a response with "
-            "the model that produced it inflates the score. Pass a different --judge-model, "
-            "or --allow-self-judge to do it deliberately."
-        )
+    check_self_judge(judge.model, answerer.model, allow_self_judge)
     check_arms(arms, placebo_text)
 
     contexts = {
diff --git a/dokimi/dokimi/report/model_compare.py b/dokimi/dokimi/report/model_compare.py
index 90159883e..06dc3161d 100644
--- a/dokimi/dokimi/report/model_compare.py
+++ b/dokimi/dokimi/report/model_compare.py
@@ -7,7 +7,7 @@
 ----------
 check_run_consistency(runs, group_name, treatment_arm=None)
     Validate a list of (run_id, run_data) pairs before comparison.
-    Raises SystemExit on hard errors; returns a list of warning strings.
+    Hard errors exit 2 (a usage refusal: the runs cannot be compared); returns a list of warning strings.
 
 non_baseline_arms(run_data)
     The arm names in one artifact other than its baseline.
@@ -41,6 +41,7 @@
 from dokimi.records import Record, RecordError, arm_answers, arm_names, arm_scores, records
 from dokimi.eval.judge_context import PROTOCOL_MIXED as JUDGE_CONTEXT_MIXED
 from dokimi.eval import stats as arm_stats
+from dokimi.exit_codes import usage_exit
 
 #: Mirrors :data:`dokimi.eval.stats.HAS_SCIPY` — the hypothesis tests
 #: now live there, so probing for SciPy twice could only ever disagree. Still a
@@ -64,18 +65,18 @@ def load_run(path: str) -> dict[str, Any]:
     """Load a judged arms JSON file.  Raises SystemExit with a clear message on failure."""
     try:
         data = json.loads(Path(path).read_text(encoding="utf-8"))
-    except FileNotFoundError as exc:
-        raise SystemExit(f"Error: File not found: {path}") from exc
+    except FileNotFoundError:
+        usage_exit(f"Error: File not found: {path}")
     except OSError as exc:  # permission denied, a directory, an I/O error
-        raise SystemExit(f"Error: cannot read {path}: {exc.strerror or exc}") from exc
+        usage_exit(f"Error: cannot read {path}: {exc.strerror or exc}")
     except ValueError as exc:  # JSONDecodeError, or bytes that are not UTF-8
-        raise SystemExit(f"Error: Invalid JSON in {path}: {exc}") from exc
+        usage_exit(f"Error: Invalid JSON in {path}: {exc}")
     if isinstance(data, dict):
         for section in ("answers", "evaluations"):
             try:
                 records(data.get(section) or [], source=f"{path} {section}", kind=section)
             except RecordError as exc:
-                raise SystemExit(f"Error: {exc}") from exc
+                usage_exit(f"Error: {exc}")
     return data
 
 
@@ -106,7 +107,7 @@ def _section(run_data: dict, section: str) -> list[Record]:
     try:
         return records(run_data.get(section) or [], source=section, kind=section)
     except RecordError as exc:
-        raise SystemExit(f"Error: {exc}") from exc
+        usage_exit(f"Error: {exc}")
 
 
 def non_baseline_arms(run_data: dict) -> set[str]:
@@ -294,7 +295,7 @@ def _check_judge_context(runs: list[tuple[str, dict]], group_name: str) -> None:
     stamps = {rid: data.get("judge_context") for rid, data in runs if "evaluations" in data}
     mixed = sorted(rid for rid, s in stamps.items() if s == JUDGE_CONTEXT_MIXED)
     if mixed:
-        raise SystemExit(
+        usage_exit(
             f"Error [{group_name}]: {', '.join(mixed)} judged some answers on the stored "
             "treatment material and some on report snippets (judge_context "
             f"{JUDGE_CONTEXT_MIXED!r}); such a run pools with nothing, not even another "
@@ -302,7 +303,7 @@ def _check_judge_context(runs: list[tuple[str, dict]], group_name: str) -> None:
         )
     if len(set(stamps.values())) > 1:
         detail = ", ".join(f"{rid}={s or '<unstamped>'}" for rid, s in stamps.items())
-        raise SystemExit(
+        usage_exit(
             f"Error [{group_name}]: runs were judged under different judge_context "
             f"protocols ({detail}). The judge saw different evidence for the same "
             "answers, so the scores cannot be pooled. Re-run answering and judging "
@@ -321,7 +322,7 @@ def check_run_consistency(
     """Check runs for consistency problems; return warning strings.
 
     Hard errors (different ``baseline_arm``, different treatment arms, or
-    duplicate configurations without ``pool_replicates``) raise ``SystemExit``
+    duplicate configurations without ``pool_replicates``) exit 2 through ``usage_exit``
     immediately. Soft warnings (hash mismatch) are collected and returned.
     """
     if len(runs) < 2:
@@ -334,7 +335,7 @@ def check_run_consistency(
     unique_baselines = set(baseline_arms.values())
     if len(unique_baselines) > 1:
         detail = ", ".join(f"{rid}={arm}" for rid, arm in baseline_arms.items())
-        raise SystemExit(
+        usage_exit(
             f"Error [{group_name}]: runs have different baseline_arm values ({detail}). "
             "Comparing runs with different baselines produces meaningless deltas."
         )
@@ -368,7 +369,7 @@ def check_run_consistency(
                 f"{rid}={'/'.join(sorted(arms)) if arms else '<none scored>'}"
                 for rid, arms in per_run.items()
             )
-            raise SystemExit(
+            usage_exit(
                 f"Error [{group_name}]: runs are scored on {len(distinct)} different "
                 f"treatment arms ({detail}). Each run's delta would measure a different "
                 "treatment, so the comparison is confounded. Compare runs that share one "
@@ -394,7 +395,7 @@ def check_run_consistency(
             detail = ", ".join(
                 f"{rid}={'/'.join(sorted(d)[:1])[:19]}…" for rid, d in by_run.items() if d
             )
-            raise SystemExit(
+            usage_exit(
                 f"Error [{group_name}]: arm '{shared_arm}' carries "
                 f"{len(all_digests)} different prompt digests across runs ({detail}). "
                 "The arm name comes from the profile's frontmatter id, so an edited "
@@ -435,7 +436,7 @@ def check_run_consistency(
                 f"{key[0]} ({key[1]}) judged by {key[2] or 'n/a'} -> runs {', '.join(ids)}"
                 for key, ids in dupes.items()
             )
-            raise SystemExit(
+            usage_exit(
                 f"Error [{group_name}]: {len(dupes)} configuration(s) appear more than "
                 f"once ({detail}). These are replicates of one measurement, not rival "
                 "models; ranking them against each other reports sampling noise as a "
@@ -487,17 +488,13 @@ def extract_scores(
 
             if force_treatment_arm is not None:
                 if force_treatment_arm not in evaluation.conditions:
-                    raise SystemExit(
-                        f"Error: --treatment-arm '{force_treatment_arm}' not found in "
-                        f"question '{qid}'. Available arms: {list(evaluation.conditions)}"
-                    )
+                    usage_exit(f"Error: --treatment-arm '{force_treatment_arm}' not found in "
+                               f"question '{qid}'. Available arms: {list(evaluation.conditions)}")
                 target_arm: str | None = force_treatment_arm
             else:
                 if len(treatment_arms) > 1:
-                    raise SystemExit(
-                        f"Error: run has multiple non-baseline arms {treatment_arms} in "
-                        f"question '{qid}'. Use --treatment-arm to select one explicitly."
-                    )
+                    usage_exit(f"Error: run has multiple non-baseline arms {treatment_arms} in "
+                               f"question '{qid}'. Use --treatment-arm to select one explicitly.")
                 target_arm = treatment_arms[0] if treatment_arms else None
 
             if target_arm is not None and target_arm in evaluation.scores:
@@ -537,17 +534,13 @@ def extract_scores(
 
             if force_treatment_arm is not None:
                 if force_treatment_arm not in arms:
-                    raise SystemExit(
-                        f"Error: --treatment-arm '{force_treatment_arm}' not found in "
-                        f"question '{qid}'. Available arms: {list(arms)}"
-                    )
+                    usage_exit(f"Error: --treatment-arm '{force_treatment_arm}' not found in "
+                               f"question '{qid}'. Available arms: {list(arms)}")
                 treatment_arm = force_treatment_arm
             else:
                 if len(treatment_arms) > 1:
-                    raise SystemExit(
-                        f"Error: run has multiple non-baseline arms {treatment_arms} in "
-                        f"question '{qid}'. Use --treatment-arm to select one explicitly."
-                    )
+                    usage_exit(f"Error: run has multiple non-baseline arms {treatment_arms} in "
+                               f"question '{qid}'. Use --treatment-arm to select one explicitly.")
                 treatment_arm = treatment_arms[0] if treatment_arms else None
 
             # The inline ``evaluation.aggregate_score`` of each arm (records.py).
diff --git a/dokimi/dokimi/repos/source.py b/dokimi/dokimi/repos/source.py
index d436c1936..84d9e0c50 100644
--- a/dokimi/dokimi/repos/source.py
+++ b/dokimi/dokimi/repos/source.py
@@ -41,6 +41,12 @@ class SourceError(ValueError):
     """Raised for an unusable source spec or a git operation that failed."""
 
 
+class SourceArgumentError(SourceError):
+    """A source or a path that is wrong as given or as laid out: a local path that is not the repository
+    root, a path that leaves the tree, a link that goes nowhere. No git operation failed, so a caller
+    reports it as a usage error; a SourceError that is not this one is a failed clone, fetch or `git show`."""
+
+
 @dataclass(frozen=True)
 class RepoSource:
     """A parsed source spec. ``rev`` is ``None`` for an unpinned working tree."""
@@ -111,7 +117,7 @@ def __init__(self, root: str | Path):
     def _resolve(self, path: str) -> Path:
         target = (self.root / path).resolve()
         if not target.is_relative_to(self.root):
-            raise SourceError(f"path escapes the repository: {path}")
+            raise SourceArgumentError(f"path escapes the repository: {path}")
         return target
 
     def files(self) -> list[str]:
@@ -149,13 +155,13 @@ def resolve(self, path: str, dirs: bool = False) -> str:
         try:
             target = self._resolve(path)
         except (RuntimeError, OSError) as exc:  # a link loop (RuntimeError before Python 3.13)
-            raise SourceError(f"too many levels of symbolic links: {path}") from exc
+            raise SourceArgumentError(f"too many levels of symbolic links: {path}") from exc
         if target.is_dir() and dirs:
             return target.relative_to(self.root).as_posix()
         if target.is_dir():
-            raise SourceError(f"{path} links to a directory: {target.relative_to(self.root).as_posix()}")
+            raise SourceArgumentError(f"{path} links to a directory: {target.relative_to(self.root).as_posix()}")
         if not target.is_file():
-            raise SourceError(f"{path} links to nothing: {target.relative_to(self.root).as_posix()}")
+            raise SourceArgumentError(f"{path} links to nothing: {target.relative_to(self.root).as_posix()}")
         return target.relative_to(self.root).as_posix()
 
     def read_many(self, paths: list[str], max_bytes: int = READ_MANY_LIMIT,
@@ -229,26 +235,26 @@ def resolve(self, path: str, dirs: bool = False) -> str:
                 text = _git(self.git_dir, "show", f"{self.sha}:{head}")
                 base = posixpath.normpath(posixpath.join(posixpath.dirname(head), text))
                 if posixpath.isabs(text) or base == ".." or base.startswith("../"):
-                    raise SourceError(f"path escapes the repository: {head} -> {text}")
+                    raise SourceArgumentError(f"path escapes the repository: {head} -> {text}")
                 path = posixpath.normpath(posixpath.join(base, *parts[hop:]))
                 if path == ".." or path.startswith("../"):
-                    raise SourceError(f"path escapes the repository: {start}")
+                    raise SourceArgumentError(f"path escapes the repository: {start}")
                 continue
             if path not in self._links():
                 if path in self._dir_set() and dirs:
                     return path
                 if path in self._dir_set():
-                    raise SourceError(f"{start} links to a directory: {path}" if path != start
-                                      else f"{path} is a directory")
+                    raise SourceArgumentError(f"{start} links to a directory: {path}" if path != start
+                                              else f"{path} is a directory")
                 if path != start and path not in self.files():
-                    raise SourceError(f"{start} links to nothing: {path}")
+                    raise SourceArgumentError(f"{start} links to nothing: {path}")
                 return path
             text = _git(self.git_dir, "show", f"{self.sha}:{path}")
             target = posixpath.normpath(posixpath.join(posixpath.dirname(path), text))
             if posixpath.isabs(text) or target == ".." or target.startswith("../"):
-                raise SourceError(f"path escapes the repository: {path} -> {text}")
+                raise SourceArgumentError(f"path escapes the repository: {path} -> {text}")
             path = target
-        raise SourceError(f"too many levels of symbolic links: {start}")
+        raise SourceArgumentError(f"too many levels of symbolic links: {start}")
 
     def read_many(self, paths: list[str], max_bytes: int = READ_MANY_LIMIT,
                   skipped: dict[str, str] | None = None) -> dict[str, str]:
@@ -358,7 +364,7 @@ def open_source(source: RepoSource, cache_dir: Path | None = None) -> RepoTree:
         # ls-tree lists paths relative to -C, git show reads them from the root.
         prefix = _git(Path(source.location), "rev-parse", "--show-prefix").strip()
         if prefix:
-            raise SourceError(f"{source.location} is {prefix!r} inside a repository; give its root")
+            raise SourceArgumentError(f"{source.location} is {prefix!r} inside a repository; give its root")
         sha = resolve_rev(Path(source.location), source.rev)
         return GitTree(Path(source.location), sha, label=f"{source.location}@{sha[:12]}")
     git_dir = ensure_clone(source.location, cache_dir or default_cache_dir())
diff --git a/dokimi/dokimi/utils.py b/dokimi/dokimi/utils.py
index cda2ff68c..e96d22285 100644
--- a/dokimi/dokimi/utils.py
+++ b/dokimi/dokimi/utils.py
@@ -7,6 +7,7 @@
 from typing import Tuple, Dict, Any
 
 from dokimi.defaults import BEDROCK_MODEL_IDS, bedrock_profile
+from dokimi.exit_codes import EXIT_USAGE
 
 
 def parse_frontmatter(text: str) -> "Tuple[Dict[str, Any], str]":
@@ -215,7 +216,7 @@ def read_json_input(path: str | os.PathLike[str], *, flag: str) -> Any:
         raise InputError(f"{flag} {path}: {reason}") from exc
 
 
-def write_text_or_exit(path: Path, text: str, code: int = 1) -> None:
+def write_text_or_exit(path: Path, text: str, code: int = EXIT_USAGE) -> None:
     """Write ``text`` to ``path`` (creating parents), or exit ``code`` naming ``path`` when it cannot be written."""
     import sys
     try:
diff --git a/dokimi/scripts/growth_baseline.json b/dokimi/scripts/growth_baseline.json
index ca7478bcc..138c6576f 100644
--- a/dokimi/scripts/growth_baseline.json
+++ b/dokimi/scripts/growth_baseline.json
@@ -1,10 +1,10 @@
 {
   "files": {
-    "dokimi/commands/novelty.py": {"lines": 1190, "rationale": "estimate-only projection and W1 routing cost output (#164) from main, plus the #172 routing field, --all-vs-all, tied/unscored caveat and blind-skill warning, --repeats refused under --all-vs-all; file split tracked separately"},
+    "dokimi/commands/novelty.py": {"lines": 1189, "rationale": "estimate-only projection and W1 routing cost output (#164) from main, plus the #172 routing field, --all-vs-all, tied/unscored caveat and blind-skill warning, --repeats refused under --all-vs-all; file split tracked separately"},
     "dokimi/harnesses/benchflow.py": {"lines": 869},
     "dokimi/harnesses/docker_solver.py": {"lines": 899, "rationale": "pre-existing when the gate was introduced"},
     "dokimi/llm.py": {"lines": 1118, "rationale": "grew on main in #180 (replay a stored retry) after #93 seeded this baseline; split it in its own PR"},
-    "dokimi/report/model_compare.py": {"lines": 1207, "rationale": "grew on main in #73 (judge-validity --context stored) before the ratchet landed; split it in its own PR"},
+    "dokimi/report/model_compare.py": {"lines": 1200, "rationale": "grew on main in #73 (judge-validity --context stored) before the ratchet landed; split it in its own PR"},
     "tests/test_arm_runner.py": {"lines": 1175, "rationale": "pre-existing when the gate was introduced"},
     "tests/test_benchflow_harness.py": {"lines": 1716, "rationale": "pre-existing when the gate was introduced"},
     "tests/test_container_agent.py": {"lines": 1251, "rationale": "pre-existing when the gate was introduced"},
@@ -17,13 +17,12 @@
   },
   "functions": {
     "dokimi/commands/benchmark.py::cmd_benchmark_batch": {"complexity": 11},
-    "dokimi/commands/benchmark.py::cmd_benchmark_preflight": {"complexity": 21},
-    "dokimi/commands/catalog.py::cmd_catalog_trigger_set": {"complexity": 15},
+    "dokimi/commands/benchmark.py::cmd_benchmark_preflight": {"complexity": 14},
+    "dokimi/commands/catalog.py::cmd_catalog_trigger_set": {"complexity": 14},
     "dokimi/commands/evaluate.py::cmd_eval_judge_validity": {"complexity": 29, "rationale": "grew on main in #73 (judge-validity --context stored) from 25 to 29 before the ratchet landed; split it in its own PR"},
     "dokimi/commands/judge_reliability.py::cmd_eval_cross_judge": {"complexity": 30, "rationale": "pre-existing when the gate was introduced"},
     "dokimi/commands/novelty.py::cmd_novelty_routing": {"complexity": 13, "rationale": "W8 adds the --repeats guard after main's no_queries handling raised the file; the command is split with the rest of novelty.py in a separate PR"},
-    "dokimi/commands/repo.py::cmd_repo_scan": {"complexity": 13},
-    "dokimi/commands/repo.py::cmd_repo_validate": {"complexity": 11, "rationale": "grew on main in #150 (repo validate --fail-on-warning) from 10 to 11 before the ratchet landed; split it in its own PR"},
+    "dokimi/commands/repo.py::cmd_repo_scan": {"complexity": 12},
     "dokimi/commands/repo_run.py::_context": {"complexity": 11, "rationale": "went over the cap on main in #120 (built-in review graders) after #93 seeded this baseline; split it in its own PR"},
     "dokimi/commands/report.py::cmd_report_model_compare": {"complexity": 12},
     "dokimi/commands/tools.py::cmd_tools_preference": {"complexity": 11},
diff --git a/dokimi/tests/test_answers_command.py b/dokimi/tests/test_answers_command.py
index 64dd7245a..1eb720361 100644
--- a/dokimi/tests/test_answers_command.py
+++ b/dokimi/tests/test_answers_command.py
@@ -59,7 +59,7 @@ def test_invalid_yaml_config_exits(tmp_path, monkeypatch, capsys):
     _point_config(monkeypatch, path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "invalid YAML" in capsys.readouterr().err
 
 
@@ -69,7 +69,7 @@ def test_non_utf8_config_exits_with_message(tmp_path, monkeypatch, capsys):
     _point_config(monkeypatch, path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"cannot read {path}" in capsys.readouterr().err
 
 
@@ -79,7 +79,7 @@ def test_unreadable_config_exits_with_message(tmp_path, monkeypatch, capsys):
     _point_config(monkeypatch, path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"cannot read {path}" in capsys.readouterr().err
 
 
@@ -89,7 +89,7 @@ def test_non_mapping_config_exits(tmp_path, monkeypatch, capsys):
     _point_config(monkeypatch, path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "expected a mapping" in capsys.readouterr().err
 
 
@@ -99,7 +99,7 @@ def test_non_utf8_config_exits(tmp_path, monkeypatch, capsys):
     _point_config(monkeypatch, path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"cannot read {path}" in capsys.readouterr().err
 
 
@@ -107,7 +107,7 @@ def test_unreadable_config_path_exits(tmp_path, monkeypatch, capsys):
     _point_config(monkeypatch, tmp_path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"cannot read {tmp_path}" in capsys.readouterr().err
 
 
@@ -121,7 +121,7 @@ def test_config_section_of_the_wrong_shape_exits(tmp_path, monkeypatch, capsys,
     _point_config(monkeypatch, path)
     with pytest.raises(SystemExit) as exc:
         answers._load_runtime_config()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"'{key}' in {path} must be a mapping" in capsys.readouterr().err
 
 
@@ -132,7 +132,7 @@ def fail(path):
     monkeypatch.setattr(dokimi.questions.artifact, "load_questions", fail)
     with pytest.raises(SystemExit) as exc:
         answers._load_questions("q.json")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "record 3 has no question text" in capsys.readouterr().err
 
 
@@ -299,12 +299,12 @@ def _get_timestamp(self):
 
 
 @pytest.mark.parametrize("kind", ["missing", "directory"])
-def test_generate_unreadable_questions_exits_1_naming_the_path(tmp_path, monkeypatch, capsys, kind):
+def test_generate_unreadable_questions_exits_2_naming_the_path(tmp_path, monkeypatch, capsys, kind):
     _point_config(monkeypatch, tmp_path / "absent.yaml")
     path = tmp_path / "q.json"
     if kind == "directory":
         path.mkdir()
     with pytest.raises(SystemExit) as exc:
         answers.cmd_answers_generate(_args(questions=str(path)))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot read {path}" in capsys.readouterr().err
diff --git a/dokimi/tests/test_arm_runner.py b/dokimi/tests/test_arm_runner.py
index a46992e66..1e2118175 100644
--- a/dokimi/tests/test_arm_runner.py
+++ b/dokimi/tests/test_arm_runner.py
@@ -514,7 +514,7 @@ def test_matrix_run_checks_every_cell_before_running_the_first(monkeypatch, tmp_
                         lambda model, provider, **kw: ["seed"] if model == "m-bad" else [])
     monkeypatch.setattr(arms_run, "probe_sampling", lambda *a: None)
     ran = []
-    monkeypatch.setattr(arms_run, "run_arms", lambda *a, **kw: ran.append(1))
+    monkeypatch.setattr(arms_run, "run_prepared", lambda *a, **kw: ran.append(1))
     args = build_parser().parse_args(
         ["arms", "matrix-run", "--product", "oneTBB", "--questions", str(questions),
          "--arms", "baseline", "--matrix-cells", str(cells), "--seed", "1",
diff --git a/dokimi/tests/test_arms_matrix_cells_input.py b/dokimi/tests/test_arms_matrix_cells_input.py
index 6ef1cff25..c4b77a41c 100644
--- a/dokimi/tests/test_arms_matrix_cells_input.py
+++ b/dokimi/tests/test_arms_matrix_cells_input.py
@@ -26,7 +26,7 @@ def _run(tmp_path, cells, capsys, *argv):
     ])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     return capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_arms_output_errors.py b/dokimi/tests/test_arms_output_errors.py
index 048849bb8..034eed4ef 100644
--- a/dokimi/tests/test_arms_output_errors.py
+++ b/dokimi/tests/test_arms_output_errors.py
@@ -1,7 +1,7 @@
 # Copyright (C) 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-"""`arms plugin-delta`: an unwritable output exits 1 with a message."""
+"""`arms plugin-delta`, `arms run` and `arms matrix-run`: an unwritable output exits 2 with a message."""
 
 from __future__ import annotations
 
@@ -26,24 +26,24 @@ def _plugin_delta(tmp_path: Path, *out: str) -> None:
     args.func(args)
 
 
-def test_unwritable_out_json_exits_1_naming_the_path(tmp_path, capsys):
+def test_unwritable_out_json_exits_2_naming_the_path(tmp_path, capsys):
     blocker = tmp_path / "blocker"
     blocker.write_text("x", encoding="utf-8")  # a regular file: nothing can be created below it
     target = blocker / "delta.json"
     with pytest.raises(SystemExit) as exc:
         _plugin_delta(tmp_path, "--out-json", str(target))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"Error: cannot write {target}" in err
     assert "Traceback" not in err
 
 
-def test_unwritable_out_md_exits_1_naming_the_path(tmp_path, capsys):
+def test_unwritable_out_md_exits_2_naming_the_path(tmp_path, capsys):
     out_md = tmp_path / "is-a-dir"
     out_md.mkdir()
     with pytest.raises(SystemExit) as exc:
         _plugin_delta(tmp_path, "--out-json", str(tmp_path / "delta.json"), "--out-md", str(out_md))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write {out_md}" in capsys.readouterr().err
 
 
@@ -57,17 +57,17 @@ def _blocker(tmp_path: Path) -> Path:
     return blocker
 
 
-def test_save_arms_output_exits_1_naming_an_unwritable_json(tmp_path, capsys):
+def test_save_arms_output_exits_2_naming_an_unwritable_json(tmp_path, capsys):
     from dokimi.commands.arms import _save_arms_output
 
     target = _blocker(tmp_path) / "arms.json"
     with pytest.raises(SystemExit) as exc:
         _save_arms_output({}, target, tmp_path / "arms.md")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write {target}" in capsys.readouterr().err
 
 
-def test_save_arms_output_exits_1_naming_an_unwritable_report(tmp_path, capsys):
+def test_save_arms_output_exits_2_naming_an_unwritable_report(tmp_path, capsys):
     from dokimi.commands.arms import _save_arms_output
 
     out_md = tmp_path / "is-a-dir"
@@ -75,11 +75,11 @@ def test_save_arms_output_exits_1_naming_an_unwritable_report(tmp_path, capsys):
     output = _arms_artifact()
     with pytest.raises(SystemExit) as exc:
         _save_arms_output(output, tmp_path / "arms.json", out_md)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write {out_md}" in capsys.readouterr().err
 
 
-def test_matrix_run_exits_1_naming_an_uncreatable_out_dir(tmp_path, capsys):
+def test_matrix_run_exits_2_naming_an_uncreatable_out_dir(tmp_path, capsys):
     cells = tmp_path / "cells.json"
     cells.write_text(json.dumps({"cells": [{"name": "c1", "model": "m", "provider": "anthropic", "harness": "arms-runner"}]}), encoding="utf-8")
     questions = tmp_path / "questions.json"
@@ -89,12 +89,12 @@ def test_matrix_run_exits_1_naming_an_uncreatable_out_dir(tmp_path, capsys):
                  "--matrix-cells", str(cells), "--out-dir", str(out_dir))
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"Error: cannot write {out_dir / 'cells'}" in err and "Traceback" not in err
 
 
-def test_plugin_delta_exits_1_on_a_deeply_nested_artifact(tmp_path, capsys):
+def test_plugin_delta_exits_2_on_a_deeply_nested_artifact(tmp_path, capsys):
     deep = tmp_path / "deep.json"
     deep.write_text("[" * 100000, encoding="utf-8")
     plugin = tmp_path / "plugin.json"
@@ -102,7 +102,7 @@ def test_plugin_delta_exits_1_on_a_deeply_nested_artifact(tmp_path, capsys):
     args = _args("plugin-delta", "--baseline-json", str(deep), "--plugin-json", str(plugin))
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert "Error computing plugin delta" in err and "Traceback" not in err
 
@@ -119,7 +119,8 @@ def _matrix_run(tmp_path: Path, out_dir: Path, *extra: str):
 def _stub_matrix(monkeypatch, tmp_path):
     from dokimi.commands import arms
 
-    monkeypatch.setattr("dokimi.eval.arms_run.run_arms", lambda *a, **k: {})
+    monkeypatch.setattr("dokimi.eval.arms_run.prepare_arms", lambda *a, **k: None)
+    monkeypatch.setattr("dokimi.eval.arms_run.run_prepared", lambda *a, **k: {})
     monkeypatch.setattr(arms, "_save_arms_output", lambda *a, **k: None)
     delta = tmp_path / "out" / "delta.json"
     rollup = {"plugin_deltas": [{"artifact": str(delta), "_artifact_payload": {"d": 1}}]}
@@ -141,7 +142,7 @@ def save(kind, payload, path, *a, **k):
 
 
 @pytest.mark.parametrize("which", ["delta_json", "delta_md", "rollup_json", "rollup_md"])
-def test_matrix_run_exits_1_naming_an_unwritable_delta_or_rollup(tmp_path, monkeypatch, capsys, which):
+def test_matrix_run_exits_2_naming_an_unwritable_delta_or_rollup(tmp_path, monkeypatch, capsys, which):
     delta = _stub_matrix(monkeypatch, tmp_path)
     out_dir = tmp_path / "out"
     rollup_json = out_dir / "matrix-rollup.json"
@@ -153,13 +154,13 @@ def test_matrix_run_exits_1_naming_an_unwritable_delta_or_rollup(tmp_path, monke
     args = _matrix_run(tmp_path, out_dir)
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"Error: cannot write {bad}" in err and "Traceback" not in err
 
 
 @pytest.mark.parametrize("kind", ["directory", "deep"])
-def test_arms_run_exits_1_on_an_unreadable_questions_file(tmp_path, capsys, kind):
+def test_arms_run_exits_2_on_an_unreadable_questions_file(tmp_path, capsys, kind):
     questions = tmp_path / "q.json"
     if kind == "directory":
         questions.mkdir()
@@ -169,12 +170,12 @@ def test_arms_run_exits_1_on_an_unreadable_questions_file(tmp_path, capsys, kind
                                       "--questions", str(questions)])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert capsys.readouterr().err.startswith("Error building arms/plugins:")
 
 
 @pytest.mark.parametrize("kind", ["directory", "deep"])
-def test_matrix_run_exits_1_on_an_unreadable_questions_file(tmp_path, capsys, kind):
+def test_matrix_run_exits_2_on_an_unreadable_questions_file(tmp_path, capsys, kind):
     args = _matrix_run(tmp_path, tmp_path / "out")
     questions = Path(args.questions)
     questions.unlink()
@@ -184,18 +185,54 @@ def test_matrix_run_exits_1_on_an_unreadable_questions_file(tmp_path, capsys, ki
         questions.write_text("[" * 100000, encoding="utf-8")
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert capsys.readouterr().err.startswith("Error loading matrix run inputs:")
 
 
 @pytest.mark.parametrize("error", [PermissionError("denied"), RecursionError("deep")], ids=lambda e: type(e).__name__)
-def test_matrix_run_exits_1_when_a_cell_cannot_read_its_inputs(tmp_path, monkeypatch, capsys, error):
+def test_matrix_run_exits_2_when_a_cell_cannot_read_its_inputs(tmp_path, monkeypatch, capsys, error):
     def build(*a, **k):
         raise error
 
-    monkeypatch.setattr("dokimi.eval.arms_run.run_arms", build)
+    monkeypatch.setattr("dokimi.eval.arms_run.prepare_arms", build)
     args = _matrix_run(tmp_path, tmp_path / "out")
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
-    assert capsys.readouterr().err.startswith("Error running matrix cell 'c1':")
+    assert exc.value.code == 2
+    assert capsys.readouterr().err.startswith("Error building matrix cell 'c1':")
+
+
+def test_matrix_run_refuses_an_uncreatable_out_dir_before_any_cell_is_answered(tmp_path, monkeypatch, capsys):
+    import dokimi.eval.arms_run as arms_run
+
+    monkeypatch.setattr(arms_run, "check_sampling_support", lambda config: None)
+    answered = []
+    monkeypatch.setattr(arms_run, "run_prepared", lambda *a, **k: answered.append(a) or {})
+    out_dir = _blocker(tmp_path) / "out"
+
+    args = _matrix_run(tmp_path, out_dir)
+    with pytest.raises(SystemExit) as exc:
+        args.func(args)
+    assert exc.value.code == 2
+    assert answered == []
+    assert f"Error: cannot write {out_dir / 'cells'}" in capsys.readouterr().err
+
+
+def test_matrix_run_refuses_a_dangling_cells_symlink_before_any_cell_is_answered(tmp_path, monkeypatch, capsys):
+    # A dangling link at cells/ does not exist, so the walk used to reach the writable out dir and
+    # pass; the first cell was then answered and its save failed on the link.
+    import dokimi.eval.arms_run as arms_run
+
+    monkeypatch.setattr(arms_run, "check_sampling_support", lambda config: None)
+    answered = []
+    monkeypatch.setattr(arms_run, "run_prepared", lambda *a, **k: answered.append(a) or {})
+    out_dir = tmp_path / "out"
+    out_dir.mkdir()
+    (out_dir / "cells").symlink_to(tmp_path / "missing")
+
+    args = _matrix_run(tmp_path, out_dir)
+    with pytest.raises(SystemExit) as exc:
+        args.func(args)
+    assert exc.value.code == 2
+    assert answered == []
+    assert f"Error: cannot write {out_dir / 'cells'}" in capsys.readouterr().err
diff --git a/dokimi/tests/test_arms_run_config.py b/dokimi/tests/test_arms_run_config.py
index cdaefb559..9198604fe 100644
--- a/dokimi/tests/test_arms_run_config.py
+++ b/dokimi/tests/test_arms_run_config.py
@@ -80,14 +80,13 @@ def test_a_doc_arm_without_a_library_id_stops_the_run_before_any_answer(command,
     with pytest.raises(SystemExit) as exc:
         args.func(args)
 
-    assert exc.value.code == 1
+    assert exc.value.code == 2  # a library id that cannot be named is a setup refusal
     # Not under "Error building arms/plugins" or "Error running matrix cell": the id is the
     # product's, not an arm's or a cell's.
     assert capsys.readouterr().err == "Error: cannot name a library id for 'demo'\n"
 
 
-def test_a_failing_matrix_cell_is_named_and_the_cells_before_it_are_kept(tmp_path, provider_calls,
-                                                                        capsys):
+def test_a_refused_matrix_cell_is_named_and_no_cell_is_answered(tmp_path, provider_calls, capsys):
     provider_calls.fake.respond = lambda request: "Use parallel_for."
     questions = tmp_path / "q.json"
     questions.write_text(json.dumps([{"id": "q1", "question": "How?"}]), encoding="utf-8")
@@ -104,10 +103,11 @@ def test_a_failing_matrix_cell_is_named_and_the_cells_before_it_are_kept(tmp_pat
     with pytest.raises(SystemExit) as exc:
         args.func(args)
 
-    assert exc.value.code == 1
+    assert exc.value.code == 2  # every cell is set up before the first answer; a bad spec is a setup refusal
     assert capsys.readouterr().err.startswith(
-        "Error running matrix cell 'bad': Unknown plugin spec: 'plugin:no-such-plugin'")
-    assert sorted(p.name for p in (out / "cells").iterdir()) == ["ok.json", "ok.md"]
+        "Error building matrix cell 'bad': Unknown plugin spec: 'plugin:no-such-plugin'")
+    assert not list((out / "cells").glob("*.json"))
+    assert provider_calls.calls == []
 
 
 def test_run_matrix_checks_every_cell_before_the_first_is_paid_for(monkeypatch, provider_calls):
diff --git a/dokimi/tests/test_baseline_unreadable_input.py b/dokimi/tests/test_baseline_unreadable_input.py
index fc1d528d9..661b742cd 100644
--- a/dokimi/tests/test_baseline_unreadable_input.py
+++ b/dokimi/tests/test_baseline_unreadable_input.py
@@ -31,12 +31,12 @@ def _run(*argv: str) -> None:
 
 
 @pytest.mark.parametrize("content", ["{not json", "[1, 2]", "null"])
-def test_save_exits_1_on_an_invalid_eval_file(run, tmp_path, capsys, content):
+def test_save_exits_2_on_an_invalid_eval_file(run, tmp_path, capsys, content):
     bad = tmp_path / "bad.json"
     bad.write_text(content, encoding="utf-8")
     with pytest.raises(SystemExit) as exc:
         run("save", "--from-eval", str(bad), "--name", "b")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert str(bad) in err
     assert not (tmp_path / "baselines" / "b.json").exists()
@@ -57,19 +57,19 @@ def test_a_non_object_eval_file_is_reported_by_its_json_type(run, tmp_path, caps
     assert f"got {type_name}" in capsys.readouterr().err
 
 
-def test_save_exits_1_on_an_eval_file_that_is_not_utf8(run, tmp_path, capsys):
+def test_save_exits_2_on_an_eval_file_that_is_not_utf8(run, tmp_path, capsys):
     bad = tmp_path / "bad.json"
     bad.write_bytes(b"\xff\xfe")
     with pytest.raises(SystemExit) as exc:
         run("save", "--from-eval", str(bad), "--name", "b")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(bad) in capsys.readouterr().err
 
 
-def test_save_exits_1_on_a_directory_given_as_the_eval_file(run, tmp_path, capsys):
+def test_save_exits_2_on_a_directory_given_as_the_eval_file(run, tmp_path, capsys):
     with pytest.raises(SystemExit) as exc:
         run("save", "--from-eval", str(tmp_path), "--name", "b")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(tmp_path) in capsys.readouterr().err
 
 
@@ -102,7 +102,7 @@ def test_a_corrupt_manifest_exits_with_a_message_in_every_subcommand(run, tmp_pa
     manifest = tmp_path / "baselines" / "manifest.json"
     manifest.parent.mkdir()
     manifest.write_text(content, encoding="utf-8")
-    for argv, code in ((("save", "--from-eval", str(good)), 1), (("list",), 1),
+    for argv, code in ((("save", "--from-eval", str(good)), 2), (("list",), 2),
                        (("compare", "--eval", str(good)), 2)):
         with pytest.raises(SystemExit) as exc:
             run(*argv)
@@ -122,7 +122,7 @@ def test_save_reports_a_corrupt_manifest_before_an_invalid_eval_file(run, tmp_pa
     manifest.write_text("{truncated", encoding="utf-8")
     with pytest.raises(SystemExit) as exc:
         run("save", "--from-eval", str(bad), "--name", "b")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert str(manifest) in err
     assert str(bad) not in err
@@ -146,7 +146,7 @@ def test_a_manifest_entry_of_the_wrong_shape_exits_with_a_message_in_every_subco
     manifest = tmp_path / "baselines" / "manifest.json"
     manifest.parent.mkdir()
     manifest.write_text('{"baselines": [%s, %s]}' % (_GOOD_ENTRY, entry), encoding="utf-8")
-    for argv, code in ((("save", "--from-eval", str(good)), 1), (("list",), 1),
+    for argv, code in ((("save", "--from-eval", str(good)), 2), (("list",), 2),
                        (("compare", "--eval", str(good)), 2)):
         with pytest.raises(SystemExit) as exc:
             run(*argv)
@@ -226,3 +226,13 @@ def test_compare_exits_2_when_the_saved_baseline_file_is_corrupt(run, tmp_path,
         run("compare", "--baseline", "b", "--eval", str(good))
     assert exc.value.code == 2
     assert str(saved) in capsys.readouterr().err
+
+
+def test_compare_with_no_saved_baseline_exits_2_and_says_to_save_one(run, tmp_path, capsys):
+    # Nothing saved is a missing input, the same class as a named baseline that is not there (exit 2).
+    eval_file = tmp_path / "eval.json"
+    eval_file.write_text(json.dumps(_EVAL), encoding="utf-8")
+    with pytest.raises(SystemExit) as exc:
+        run("compare", "--eval", str(eval_file))
+    assert exc.value.code == 2
+    assert "No baselines found. Save one first" in capsys.readouterr().out
diff --git a/dokimi/tests/test_benchmark_command_question_set.py b/dokimi/tests/test_benchmark_command_question_set.py
index 70cc65579..b767e0582 100644
--- a/dokimi/tests/test_benchmark_command_question_set.py
+++ b/dokimi/tests/test_benchmark_command_question_set.py
@@ -320,12 +320,78 @@ def test_preflight_fails_before_any_call(monkeypatch, tmp_path, capsys, prefligh
     with pytest.raises(SystemExit) as exc:
         _preflight(monkeypatch, tmp_path, *preflight_args(tmp_path), env=env)
 
-    assert exc.value.code == 1
+    # A missing credential or a missing/invalid question set or output dir is an input refusal
+    # (2), the same as `benchmark run`. Only a failed check that is not an input stays 1.
+    assert exc.value.code == 2
     captured = capsys.readouterr()
     assert message in captured.err
     assert "Preflight OK" not in captured.out
 
 
+def _preflight_with_doc_source(monkeypatch, tmp_path, *extra, error=None, credential=True):
+    for key in ("OPENAI_API_KEY", "ANTHROPIC_API_KEY"):
+        monkeypatch.delenv(key, raising=False)
+    if credential:
+        monkeypatch.setenv("OPENAI_API_KEY", "test")
+    monkeypatch.setattr(benchmark, "_load_registry", lambda args: _Registry())
+    # By default a failure of the check itself (the source cannot be reached), not a bad --doc-source value.
+    failure = error or RuntimeError("doc source unreachable")
+
+    def broken_client(doc_source):
+        raise failure
+
+    monkeypatch.setattr("dokimi.mcp.factory.create_doc_source_client", broken_client)
+    args = build_parser().parse_args([
+        "benchmark", "preflight", "--library", "onetbb",
+        "--doc-source", "local:docs",
+        "--provider", "openai", "--judge-provider", "openai",
+        "--output-dir", str(tmp_path / "out"), *extra,
+    ])
+    args.func(args)
+
+
+@pytest.mark.outcome("pinned-questions-preflight")
+def test_preflight_check_failure_alone_stays_1(monkeypatch, tmp_path, capsys):
+    # Guard: a doc source that does not resolve is a failed check, not an input refusal.
+    with pytest.raises(SystemExit) as exc:
+        _preflight_with_doc_source(monkeypatch, tmp_path)
+    assert exc.value.code == 1
+    assert "doc source check failed" in capsys.readouterr().err
+
+
+@pytest.mark.outcome("pinned-questions-preflight")
+def test_preflight_doc_source_value_rejected_by_the_factory_is_a_refusal(monkeypatch, tmp_path, capsys):
+    # The factory's ValueError says the --doc-source value is bad: exit 2, not a failed check.
+    with pytest.raises(SystemExit) as exc:
+        _preflight_with_doc_source(monkeypatch, tmp_path, error=ValueError("no such format"))
+    assert exc.value.code == 2
+    err = capsys.readouterr().err
+    assert "doc source invalid: local:docs (no such format)" in err
+    assert "doc source check failed" not in err
+
+
+@pytest.mark.outcome("pinned-questions-preflight")
+def test_preflight_missing_credential_wins_over_a_check_failure(monkeypatch, tmp_path, capsys):
+    with pytest.raises(SystemExit) as exc:
+        _preflight_with_doc_source(monkeypatch, tmp_path, credential=False)
+    assert exc.value.code == 2
+    err = capsys.readouterr().err
+    assert "missing OPENAI_API_KEY" in err and "doc source check failed" in err
+
+
+@pytest.mark.outcome("pinned-questions-preflight")
+def test_preflight_input_error_wins_over_a_check_failure(monkeypatch, tmp_path, capsys):
+    # An input the run would refuse (here an unwritable output dir) makes the refusal a usage
+    # error (2), even when a check also failed.
+    blocker = tmp_path / "file"
+    blocker.write_text("not a directory", encoding="utf-8")
+    with pytest.raises(SystemExit) as exc:
+        _preflight_with_doc_source(monkeypatch, tmp_path, "--output-dir", str(blocker / "out"))
+    assert exc.value.code == 2
+    err = capsys.readouterr().err
+    assert "output dir not writable" in err and "doc source check failed" in err
+
+
 @pytest.mark.outcome("pinned-questions-preflight")
 def test_preflight_questions_from_skips_root_check(monkeypatch, tmp_path, capsys):
     """When --questions-from is set, preflight does not require a golden set in the root."""
@@ -365,7 +431,7 @@ def test_preflight_rejects_an_unwritable_output_dir(monkeypatch, tmp_path, capsy
     with pytest.raises(SystemExit) as exc:
         _preflight(monkeypatch, tmp_path, "--output-dir", str(blocker / "out"))
 
-    assert exc.value.code == 1
+    assert exc.value.code == 2  # unwritable output is an input refusal (docs/quickstart.md)
     assert "output dir not writable" in capsys.readouterr().err
 
 
@@ -397,7 +463,7 @@ def test_run_rejects_an_unusable_questions_from_before_any_call(
     with pytest.raises(SystemExit) as exc:
         benchmark.cmd_benchmark_run(args)
 
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert message in capsys.readouterr().err
     assert calls == []
 
diff --git a/dokimi/tests/test_dashboard_cli.py b/dokimi/tests/test_dashboard_cli.py
index 2f1db6618..61b30b105 100644
--- a/dokimi/tests/test_dashboard_cli.py
+++ b/dokimi/tests/test_dashboard_cli.py
@@ -31,7 +31,7 @@ def _results(tmp_path):
     return tmp_path / "results"
 
 
-def test_generate_exits_1_with_a_message_when_the_output_dir_is_a_file(tmp_path, capsys):
+def test_generate_exits_2_with_a_message_when_the_output_dir_is_a_file(tmp_path, capsys):
     results = _results(tmp_path)
     blocker = tmp_path / "out"
     blocker.write_text("not a directory", encoding="utf-8")
@@ -41,7 +41,7 @@ def test_generate_exits_1_with_a_message_when_the_output_dir_is_a_file(tmp_path,
     with pytest.raises(SystemExit) as exc:
         args.func(args)
 
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write the dashboard to ")
     assert "Traceback" not in err
diff --git a/dokimi/tests/test_eval_output_write_errors.py b/dokimi/tests/test_eval_output_write_errors.py
index 07f145cd5..0feb5e7ca 100644
--- a/dokimi/tests/test_eval_output_write_errors.py
+++ b/dokimi/tests/test_eval_output_write_errors.py
@@ -222,7 +222,7 @@ def test_report_eval_names_the_sidecar_when_it_cannot_be_written(tmp_path, monke
     )
     with pytest.raises(SystemExit) as exc:
         cli.main()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert str(tmp_path / "r.qa.json") in err and f"cannot write {out}" not in err
 
diff --git a/dokimi/tests/test_evaluate_cli_inputs.py b/dokimi/tests/test_evaluate_cli_inputs.py
index ef9902c50..01ff734a7 100644
--- a/dokimi/tests/test_evaluate_cli_inputs.py
+++ b/dokimi/tests/test_evaluate_cli_inputs.py
@@ -15,22 +15,22 @@ def _evaluate(*extra: str):
     args.func(args)
 
 
-def test_a_missing_custom_questions_file_exits_1_with_a_message(tmp_path, capsys):
+def test_a_missing_custom_questions_file_exits_2_with_a_message(tmp_path, capsys):
     missing = tmp_path / "missing.json"
     with pytest.raises(SystemExit) as exc:
         _evaluate("--output-dir", str(tmp_path / "out"), "--custom-questions", str(missing))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"Error: --custom-questions path does not exist: {missing}" in err
     assert "Traceback" not in err
 
 
-def test_an_unwritable_output_dir_exits_1_with_a_message(tmp_path, capsys):
+def test_an_unwritable_output_dir_exits_2_with_a_message(tmp_path, capsys):
     blocker = tmp_path / "file"
     blocker.write_text("x", encoding="utf-8")
     with pytest.raises(SystemExit) as exc:
         _evaluate("--output-dir", str(blocker))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ") and str(blocker) in err
     assert "Traceback" not in err
diff --git a/dokimi/tests/test_exit_codes_boundaries.py b/dokimi/tests/test_exit_codes_boundaries.py
new file mode 100644
index 000000000..309e100f5
--- /dev/null
+++ b/dokimi/tests/test_exit_codes_boundaries.py
@@ -0,0 +1,614 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""The validation/runtime boundary of the exit-code table (docs/quickstart.md).
+
+Only input and usage validation exits 2. A failure while the run is under way (an arm run,
+a fetch, a probe workspace, a model call, a missing optional dependency) keeps the code it
+had before the audit, 1.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from dokimi import cli
+from dokimi.commands import benchmark, evaluate
+from dokimi.eval import arms_run
+from dokimi.records import RecordError
+from dokimi.repos import SourceError
+from dokimi.repos.reach import ReachError
+
+PIN = "a" * 40
+
+
+def _argv(monkeypatch, *argv):
+    monkeypatch.setattr("sys.argv", ["dokimi", *argv])
+
+
+def _questions(tmp_path):
+    path = tmp_path / "q.json"
+    path.write_text(json.dumps([{"id": "q1", "question": "How do I parallelize a loop?"}]), encoding="utf-8")
+    return str(path)
+
+
+def _arms_argv(tmp_path, *extra):
+    return ["arms", "run", "--product", "onedal", "--questions", _questions(tmp_path),
+            "--arms", "baseline", "--out-json", str(tmp_path / "a.json"),
+            "--out-md", str(tmp_path / "a.md"), *extra]
+
+
+# ── arms run: a runtime failure keeps 1; an unusable arm spec is 2 ─────────────────────────
+
+@pytest.mark.parametrize(
+    "error",
+    [ValueError("simulated runtime failure in the arm run"),
+     RecordError("answers[0]: missing question_id")],
+    ids=["value-error", "record-error"],
+)
+def test_arm_run_failure_keeps_exit_1(error, tmp_path, monkeypatch, capsys):
+    def boom(self, *args, **kwargs):
+        raise error
+
+    monkeypatch.setattr("dokimi.eval.arm_runner.ArmRunner.run", boom)
+    _argv(monkeypatch, *_arms_argv(tmp_path))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert str(error) in capsys.readouterr().err
+
+
+def test_arm_run_sampling_probe_failure_keeps_exit_1_before_any_answer(tmp_path, monkeypatch, capsys):
+    # The probe is one real model call: its failure is a model failure, not a usage error.
+    def refused(*args, **kwargs):
+        raise arms_run.ProbeError("Probe call to 'openai/m' failed, so every call in the run would too")
+
+    answered = []
+    monkeypatch.setattr("dokimi.eval.arms_run.probe_sampling", refused)
+    monkeypatch.setattr("dokimi.eval.arm_runner.ArmRunner.run",
+                        lambda self, *a, **k: answered.append(1) or [])
+    _argv(monkeypatch, *_arms_argv(tmp_path, "--judge", "--judge-temperature", "0.5"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert not answered
+    assert "Probe call" in capsys.readouterr().err
+
+
+def test_arm_run_unknown_arm_spec_exits_2(tmp_path, monkeypatch, capsys):
+    _argv(monkeypatch, "arms", "run", "--product", "onedal", "--questions", _questions(tmp_path),
+          "--arms", "no-such-arm-kind", "--out-json", str(tmp_path / "a.json"),
+          "--out-md", str(tmp_path / "a.md"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "Error building arms/plugins" in capsys.readouterr().err
+
+
+@pytest.fixture
+def fresh_probe_cache():
+    # probe_sampling is cached per process; each test starts with no cached probe.
+    arms_run.probe_sampling.cache_clear()
+    yield
+    arms_run.probe_sampling.cache_clear()
+
+
+def test_matrix_cell_refused_at_probe_stops_before_any_answer(tmp_path, monkeypatch, capsys, fresh_probe_cache):
+    # Cell 1 is accepted, cell 2 refuses the temperature. Every cell is probed before the first
+    # answer, so the refusal costs no answer call and writes no cell artifact.
+    probed = []
+
+    def fake_usage(prompt, model, provider="openai", **kwargs):
+        probed.append(model)
+        if model == "reject-temp-model":
+            raise RuntimeError("400: temperature not supported for this model")
+        return ("OK", {})
+
+    answered = []
+    monkeypatch.setattr("dokimi.llm.llm_call_with_usage", fake_usage)
+    monkeypatch.setattr("dokimi.eval.arm_runner.ArmRunner.run",
+                        lambda self, *a, **k: answered.append(1) or [])
+    cells = tmp_path / "cells.json"
+    cells.write_text(json.dumps({"cells": [
+        {"id": "cell-ok", "model": "gpt-4o-mini", "provider": "openai", "harness": "arms-runner"},
+        {"id": "cell-bad", "model": "reject-temp-model", "provider": "openai", "harness": "arms-runner"},
+    ]}), encoding="utf-8")
+    _argv(monkeypatch, "arms", "matrix-run", "--product", "onedal", "--questions", _questions(tmp_path),
+          "--arms", "baseline", "--matrix-cells", str(cells), "--temperature", "0.5",
+          "--out-dir", str(tmp_path / "matrix"))
+    from dokimi.exit_codes import EXIT_FAILURE
+
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == EXIT_FAILURE
+    assert probed == ["gpt-4o-mini", "reject-temp-model"]  # each cell probed once, in order
+    assert answered == []
+    assert not (tmp_path / "matrix" / "cells").exists()
+    assert "matrix cell 'cell-bad'" in capsys.readouterr().err
+
+
+def test_matrix_cell_that_cannot_be_set_up_exits_2_before_any_answer(tmp_path, monkeypatch, capsys):
+    # Cell 2 cannot be set up (a refused input, not a model failure): usage error, and cell 1,
+    # which was set up, has not been answered or written either.
+    real_prepare = arms_run.prepare_arms
+    calls = []
+
+    def prepare(config, specs, questions):
+        calls.append(config.model)
+        if config.model == "bad-cell-model":
+            raise ValueError("this cell names a harness that cannot run its plugins")
+        return real_prepare(config, specs, questions)
+
+    answered = []
+    monkeypatch.setattr("dokimi.eval.arms_run.prepare_arms", prepare)
+    monkeypatch.setattr("dokimi.eval.arm_runner.ArmRunner.run",
+                        lambda self, *a, **k: answered.append(1) or [])
+    cells = tmp_path / "cells.json"
+    cells.write_text(json.dumps({"cells": [
+        {"id": "cell-ok", "model": "gpt-4o-mini", "provider": "openai", "harness": "arms-runner"},
+        {"id": "cell-bad", "model": "bad-cell-model", "provider": "openai", "harness": "arms-runner"},
+    ]}), encoding="utf-8")
+    _argv(monkeypatch, "arms", "matrix-run", "--product", "onedal", "--questions", _questions(tmp_path),
+          "--arms", "baseline", "--matrix-cells", str(cells), "--out-dir", str(tmp_path / "matrix"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert calls == ["gpt-4o-mini", "bad-cell-model"]
+    assert answered == []
+    assert not (tmp_path / "matrix").exists()
+    assert "Error building matrix cell 'cell-bad'" in capsys.readouterr().err
+
+
+# ── repo fetch / reach: a fetch failure keeps 1; a bad source or profile is 2 ──────────────
+
+def _failed_fetch(source, cache_dir=None):
+    raise SourceError("git fetch failed: could not connect to 127.0.0.1:9")
+
+
+def test_repo_fetch_git_failure_keeps_exit_1(monkeypatch, capsys):
+    monkeypatch.setattr("dokimi.repos.open_source", _failed_fetch)
+    _argv(monkeypatch, "repo", "fetch", f"https://127.0.0.1:9/example.git@{PIN}")
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "git fetch failed" in capsys.readouterr().err
+
+
+def test_repo_fetch_unpinned_remote_exits_2(monkeypatch, capsys):
+    _argv(monkeypatch, "repo", "fetch", "https://example.com/example.git")
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "must be pinned" in capsys.readouterr().err
+
+
+REPO_SOURCE_COMMANDS = ["validate", "scan", "inspect", "budget"]
+
+
+@pytest.mark.parametrize("command", REPO_SOURCE_COMMANDS)
+def test_repo_unreachable_source_keeps_exit_1(command, tmp_path, monkeypatch, capsys):
+    # A pinned source that cannot be fetched is a fetch failure (network), not a bad invocation.
+    # open_source is stubbed, so the result does not depend on git, the network or the host.
+    monkeypatch.setattr("dokimi.repos.open_source", _failed_fetch)
+    _argv(monkeypatch, "repo", command, f"https://127.0.0.1:9/example.git@{PIN}",
+          "--cache-dir", str(tmp_path / "cache"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "✗ git fetch failed" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("error", [
+    OSError("[Errno 17] File exists: '/tmp/cache'"),  # the cache dir cannot be made
+    ValueError("'utf-8' codec can't decode byte 0xe9 in position 3"),  # git output is not UTF-8
+])
+@pytest.mark.parametrize("command", REPO_SOURCE_COMMANDS)
+def test_repo_source_os_or_value_error_keeps_exit_1_with_a_message(error, command, tmp_path, monkeypatch, capsys):
+    # open_source can raise these outside SourceError; the command prints them and keeps 1, as on main.
+    def open_failed(source, cache_dir=None):
+        raise error
+
+    monkeypatch.setattr("dokimi.repos.open_source", open_failed)
+    _argv(monkeypatch, "repo", command, f"https://127.0.0.1:9/example.git@{PIN}",
+          "--cache-dir", str(tmp_path / "cache"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert str(error) in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("error", [
+    OSError("[Errno 20] Not a directory: '/tmp/cache'"),  # the cache dir cannot be made
+    ValueError("'utf-8' codec can't decode byte 0xe9 in position 3"),  # git output is not UTF-8
+])
+@pytest.mark.parametrize("command", ["fetch", "reach"])
+def test_repo_fetch_and_reach_os_or_value_error_keeps_exit_1_with_a_message(command, error, tmp_path,
+                                                                            monkeypatch, capsys):
+    # fetch and reach print the failure and keep 1, as the other repo commands do; no traceback.
+    def open_failed(source, cache_dir=None):
+        raise error
+
+    monkeypatch.setattr("dokimi.repos.open_source", open_failed)
+    extra = ["--model", "m", "--out", str(tmp_path / "out")] if command == "reach" else []
+    _argv(monkeypatch, "repo", command, f"https://127.0.0.1:9/example.git@{PIN}",
+          "--cache-dir", str(tmp_path / "cache"), *extra)
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert str(error) in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("command", REPO_SOURCE_COMMANDS)
+def test_repo_unpinned_remote_exits_2_for_every_source_command(command, tmp_path, monkeypatch, capsys):
+    _argv(monkeypatch, "repo", command, "https://example.com/example.git",
+          "--cache-dir", str(tmp_path / "cache"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "✗" in capsys.readouterr().err
+
+
+def test_repo_reach_fetch_failure_keeps_exit_1(tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr("dokimi.repos.open_source", _failed_fetch)
+    _argv(monkeypatch, "repo", "reach", f"https://127.0.0.1:9/example.git@{PIN}",
+          "--model", "m", "--out", str(tmp_path / "out"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "git fetch failed" in capsys.readouterr().err
+
+
+@pytest.mark.skipif(shutil.which("git") is None, reason="needs git")
+@pytest.mark.parametrize("command", [*REPO_SOURCE_COMMANDS, "fetch", "reach"])
+def test_repo_pinned_local_source_inside_a_repository_exits_2(command, tmp_path, monkeypatch, capsys):
+    # A pinned local path that is a subdirectory, not the root, is a mistyped argument; no git operation
+    # failed. open_source says so before it resolves the pin.
+    repo = tmp_path / "repo"
+    (repo / "sub").mkdir(parents=True)
+    (repo / "sub" / "f.txt").write_text("x", encoding="utf-8")
+    # gpgsign is off here: a host with a global commit.gpgsign=true would refuse the commit.
+    for args in (["init", "-q"], ["add", "-A"],
+                 ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false",
+                  "commit", "-q", "-m", "init"]):
+        subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True)
+    extra = ["--model", "m"] if command == "reach" else []
+    err = _expect_exit(monkeypatch, capsys, 2, "repo", command, f"{repo / 'sub'}@HEAD", *extra)
+    assert "inside a repository; give its root" in err
+
+
+@pytest.mark.parametrize("command", ["validate", "scan"])
+def test_repo_manifest_path_leaving_the_tree_exits_2_with_a_message(command, tmp_path, monkeypatch, capsys):
+    # The tree refuses a path that escapes it with SourceError; the manifest is the caller's input.
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _argv(monkeypatch, "repo", command, str(repo), "--manifest", "../x.yaml")
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "path escapes the repository" in capsys.readouterr().err
+
+
+REACH_ARGS = ["--harness", "claude-code", "--model", "m", "--out", "reach-out"]
+
+
+@pytest.mark.parametrize("command", ["validate", "scan", "reach"])
+def test_repo_manifest_read_that_fails_in_git_keeps_exit_1(command, tmp_path, monkeypatch, capsys):
+    # A `git show` that fails while the manifest is read (a blob fetched lazily from origin that is gone)
+    # is a fetch failure, not a bad manifest path: exit 1, as on main.
+    def failing_load(tree, args, **kwargs):
+        raise SourceError("git show failed: fatal: could not fetch the blob from promisor remote")
+
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    monkeypatch.setattr("dokimi.commands.repo._load_manifest", failing_load)
+    extra = [*REACH_ARGS[:-1], str(tmp_path / "reach-out")] if command == "reach" else []
+    err = _expect_exit(monkeypatch, capsys, 1, "repo", command, str(repo), *extra)
+    assert "git show failed" in err
+
+
+def _expect_exit(monkeypatch, capsys, code, *argv):
+    _argv(monkeypatch, *argv)
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == code
+    return capsys.readouterr().err
+
+
+def test_repo_validate_invalid_manifest_exits_2(tmp_path, monkeypatch, capsys):
+    (tmp_path / ".agent-eval").mkdir()
+    (tmp_path / ".agent-eval" / "repo-eval.yaml").write_text("schema: no-such-schema\n", encoding="utf-8")
+    err = _expect_exit(monkeypatch, capsys, 2, "repo", "validate", str(tmp_path))
+    assert err.startswith("✗ ")
+
+
+def test_repo_budget_unknown_harness_exits_2(tmp_path, monkeypatch, capsys):
+    err = _expect_exit(monkeypatch, capsys, 2, "repo", "budget", str(tmp_path), "--harness", "no-such-harness")
+    assert "no harness profile" in err
+
+
+@pytest.mark.parametrize("command", ["report", "compare"])
+def test_repo_report_and_compare_batch_that_is_not_a_directory_exit_2(command, tmp_path, monkeypatch, capsys):
+    missing = tmp_path / "no-such-batch"
+    extra = ["--baseline", "none"] if command == "compare" else []
+    err = _expect_exit(monkeypatch, capsys, 2, "repo", command, str(missing), *extra)
+    assert f"not a directory: {missing}" in err
+
+
+def test_repo_scan_unwritable_out_exits_2(tmp_path, monkeypatch, capsys):
+    (tmp_path / "AGENTS.md").write_text("# guidance\n", encoding="utf-8")
+    blocker = tmp_path / "blocker"
+    blocker.write_text("a file, not a directory", encoding="utf-8")
+    out = blocker / "scan.json"
+    err = _expect_exit(monkeypatch, capsys, 2, "repo", "scan", str(tmp_path), "--out", str(out))
+    assert f"cannot write {out}" in err
+
+
+def test_repo_reach_unknown_harness_profile_exits_2(tmp_path, monkeypatch, capsys):
+    _argv(monkeypatch, "repo", "reach", str(tmp_path), "--harness", "no-such-harness",
+          "--model", "m", "--out", str(tmp_path / "out"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "no harness profile" in capsys.readouterr().err
+
+
+def test_repo_reach_probe_workspace_failure_keeps_exit_1(tmp_path, monkeypatch, capsys):
+    (tmp_path / "CLAUDE.md").write_text("# guidance\n", encoding="utf-8")
+
+    def workspace_failed(*args, **kwargs):
+        raise ReachError("could not create the probe workspace")
+
+    monkeypatch.setattr("dokimi.repos.reach.run_reach", workspace_failed)
+    _argv(monkeypatch, "repo", "reach", str(tmp_path), "--model", "m", "--out", str(tmp_path / "out"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "probe workspace" in capsys.readouterr().err
+
+
+def test_repo_reach_unrunnable_harness_binary_keeps_exit_1_with_a_message(tmp_path, monkeypatch, capsys):
+    # run_reach asks the harness for its version first: a --bin that cannot run is a runtime failure
+    # and must print its message, not escape as a ProfileError traceback.
+    (tmp_path / "CLAUDE.md").write_text("# guidance\n", encoding="utf-8")
+    _argv(monkeypatch, "repo", "reach", str(tmp_path), "--model", "m", "--bin", str(tmp_path / "no-such-claude"),
+          "--out", str(tmp_path / "out"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "cannot run" in capsys.readouterr().err
+
+
+def test_repo_reach_workspace_source_error_keeps_exit_1_with_a_message(tmp_path, monkeypatch, capsys):
+    (tmp_path / "CLAUDE.md").write_text("# guidance\n", encoding="utf-8")
+
+    def links_escape(*args, **kwargs):
+        raise SourceError("path escapes the repository: ../x")
+
+    monkeypatch.setattr("dokimi.repos.reach.run_reach", links_escape)
+    _argv(monkeypatch, "repo", "reach", str(tmp_path), "--model", "m", "--out", str(tmp_path / "out"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "path escapes the repository" in capsys.readouterr().err
+
+
+# ── benchmark batch: nothing selected is a usage refusal, as with an unknown library ───────
+
+class _NoLibraries:
+    def get(self, key):
+        raise KeyError(key)
+
+    def list(self):
+        return []
+
+
+def test_batch_with_no_known_library_exits_2(monkeypatch, capsys):
+    monkeypatch.setattr(benchmark, "_load_registry", lambda args: _NoLibraries())
+    _argv(monkeypatch, "benchmark", "batch", "--libraries", "no-such-library")
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "No libraries to run." in capsys.readouterr().err
+
+
+# ── benchmark preflight: an invalid --doc-source is 2; a source that fails its check is 1 ──
+
+class _OneLibrary:
+    def get(self, key):
+        from dokimi.registry import ProductEntry
+
+        return ProductEntry(key="onetbb", name="oneTBB", description="TBB", doc_sources=["local:docs"])
+
+
+def test_preflight_unknown_doc_source_format_exits_2(tmp_path, monkeypatch, capsys):
+    monkeypatch.setenv("OPENAI_API_KEY", "test")
+    monkeypatch.setattr(benchmark, "_load_registry", lambda args: _OneLibrary())
+    _argv(monkeypatch, "benchmark", "preflight", "--library", "onetbb",
+          "--doc-source", "bogus:docs", "--output-dir", str(tmp_path / "out"),
+          "--provider", "openai", "--judge-provider", "openai")
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "Unknown --doc-source format" in capsys.readouterr().err
+
+
+def test_external_content_walkthrough_states_the_exit_of_a_preflight_without_keys(tmp_path, monkeypatch, capsys):
+    # The walkthrough shows a preflight run with no API keys and says what it exited with; that number
+    # must be the real refusal, so the page cannot drift from the code.
+    doc = Path(__file__).resolve().parents[1] / "docs" / "external-content.md"
+    stated = int(re.search(r"It exited (\d+) here because no API keys were set", doc.read_text(encoding="utf-8")).group(1))
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.setattr(benchmark, "_load_registry", lambda args: _OneLibrary())
+    _argv(monkeypatch, "benchmark", "preflight", "--library", "onetbb", "--output-dir", str(tmp_path / "out"),
+          "--provider", "openai", "--judge-provider", "openai")
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == stated
+    assert "missing OPENAI_API_KEY for provider openai" in capsys.readouterr().err
+
+
+# ── catalog trigger-set: input refusals are 2; a rewrite that returns nothing is 1 ─────────
+
+def _skill_root(tmp_path):
+    root = tmp_path / "skills"
+    skill = root / "linux-perf"
+    skill.mkdir(parents=True)
+    (skill / "SKILL.md").write_text(
+        '---\nname: linux-perf\ndescription: "Profile Linux programs with perf."\n---\n# linux-perf\nbody\n',
+        encoding="utf-8",
+    )
+    return root
+
+
+def _trigger_questions(tmp_path, questions):
+    path = tmp_path / "q.json"
+    path.write_text(json.dumps({"questions": questions}), encoding="utf-8")
+    return f"{path}=@metadata.skill_under_test"
+
+
+def test_trigger_set_rewrite_returning_nothing_keeps_exit_1(tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr("dokimi.llm.llm_call", lambda *args, **kwargs: "   ")
+    spec = _trigger_questions(tmp_path, [
+        {"id": "1", "text": "perf shows low IPC", "metadata": {"skill_under_test": "linux-perf"}},
+    ])
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--questions", spec, "--rewrite", "--model", "m", "--out", str(tmp_path / "o.json"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert "rewrite returned empty text" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    "text_fields",
+    [{}, {"text": ""}, {"text": "   "}, {"text": None}, {"text": 5}],
+    ids=["missing", "empty", "whitespace", "null", "not-a-string"],
+)
+def test_trigger_set_question_without_text_exits_2(text_fields, tmp_path, monkeypatch, capsys):
+    spec = _trigger_questions(tmp_path, [
+        {"id": "1", **text_fields, "metadata": {"skill_under_test": "linux-perf"}},
+    ])
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--questions", spec, "--out", str(tmp_path / "o.json"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "has no text" in capsys.readouterr().err
+
+
+def test_trigger_set_no_text_refused_before_any_rewrite_call(tmp_path, monkeypatch, capsys):
+    # The set is refused on its second question; the first must not have been sent to the rewrite model.
+    rewrite_calls = []
+    monkeypatch.setattr("dokimi.llm.llm_call", lambda *args, **kwargs: rewrite_calls.append(1) or "rewritten")
+    spec = _trigger_questions(tmp_path, [
+        {"id": "1", "text": "perf shows low IPC", "metadata": {"skill_under_test": "linux-perf"}},
+        {"id": "2", "metadata": {"skill_under_test": "linux-perf"}},
+    ])
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--questions", spec, "--rewrite", "--model", "m", "--out", str(tmp_path / "o.json"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "has no text" in capsys.readouterr().err
+    assert rewrite_calls == []
+    assert not (tmp_path / "o.json").exists()
+
+
+def test_trigger_set_file_without_labels_is_valid_and_its_questions_stay_unlabelled(tmp_path, monkeypatch, capsys):
+    # A --trigger-set file whose questions carry no expected_skill is valid: they are read unlabelled.
+    path = tmp_path / "unlabelled.json"
+    path.write_text(json.dumps({"questions": [{"id": "u1", "question": "How do I cook rice?"}]}), encoding="utf-8")
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--format", "questions", "--trigger-set", str(path), "--out", str(tmp_path / "o.json"))
+    cli.main()
+    assert (tmp_path / "o.json").exists()
+    assert "Traceback" not in capsys.readouterr().err
+
+
+def test_questions_file_with_a_field_label_and_no_labels_is_refused_and_says_so(tmp_path, monkeypatch, capsys):
+    # A --questions source whose rule is a field no question has is a mistyped path, not a set of
+    # negatives: exit 2, and the message says the file has no labels.
+    path = tmp_path / "unlabelled.json"
+    path.write_text(json.dumps({"questions": [{"id": "u1", "question": "How do I cook rice?"}]}), encoding="utf-8")
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--format", "questions", "--questions", f"{path}=@expected_skill", "--out", str(tmp_path / "o.json"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "@expected_skill resolves for none of 1 questions (none has that field, so the file has no labels)" \
+        in capsys.readouterr().err
+
+
+def test_trigger_set_unresolved_field_rule_is_refused_before_any_rewrite_call(tmp_path, monkeypatch, capsys):
+    # A mistyped @field path labels no question: exit 2, and none of the questions was sent to --rewrite.
+    rewrite_calls = []
+    monkeypatch.setattr("dokimi.llm.llm_call", lambda *args, **kwargs: rewrite_calls.append(1) or "rewritten")
+    path = tmp_path / "q.json"
+    path.write_text(json.dumps({"questions": [
+        {"id": str(i), "text": f"question {i}", "metadata": {"skill_under_test": "linux-perf"}} for i in range(3)
+    ]}), encoding="utf-8")
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--questions", f"{path}=@metadata.skil_under_test", "--rewrite", "--model", "m",
+          "--out", str(tmp_path / "o.json"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 2
+    assert "resolves for none of 3 questions" in capsys.readouterr().err
+    assert rewrite_calls == []
+    assert not (tmp_path / "o.json").exists()
+
+
+def test_trigger_set_strict_refusal_exits_1(tmp_path, monkeypatch, capsys):
+    # One question is labelled and one is not, so the set has an unresolved label; --strict refuses it.
+    # --strict is a lint gate over a valid set: its verdict is exit 1, as on main.
+    spec = _trigger_questions(tmp_path, [
+        {"id": "1", "text": "perf shows low IPC", "metadata": {"skill_under_test": "linux-perf"}},
+        {"id": "2", "text": "what is the weather"},
+    ])
+    _argv(monkeypatch, "catalog", "trigger-set", "--catalog", str(_skill_root(tmp_path)),
+          "--questions", spec, "--strict", "--out", str(tmp_path / "o.json"))
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    assert not (tmp_path / "o.json").exists()
+    # The gate that fired is the unresolved label: the summary is printed before the exit.
+    assert json.loads(capsys.readouterr().out)["label_unresolved"] == 1
+
+
+# ── evaluate: a missing optional dependency keeps its base exit (a message, exit 1) ────────
+
+def test_missing_ragas_extra_keeps_its_base_exit(monkeypatch):
+    real_find_spec = importlib.util.find_spec
+
+    def without_ragas(name, *args, **kwargs):
+        return None if name == "ragas" else real_find_spec(name, *args, **kwargs)
+
+    monkeypatch.setattr(importlib.util, "find_spec", without_ragas)
+    message = "RAGAS meta-evaluation needs the ragas extra: pip install 'dokimi[ragas]'"
+    with pytest.raises(SystemExit) as exc:
+        evaluate._require_ragas()
+    assert exc.value.code == message
+
+
+# ── questions refine: only the artifact refusal is a usage error; a run-time ValueError is not ──
+
+def test_refine_runtime_value_error_is_not_a_usage_refusal(tmp_path, monkeypatch):
+    # A ValueError from the refiner's own steps (here the similarity pass) is a run failure. It must
+    # reach the top level (exit 1, a traceback), not be turned into the input refusal (exit 2).
+    from dokimi.questions.refiner import QuestionRefiner
+
+    def similarity_failed(self, questions):
+        raise ValueError("similarity backend returned NaN")
+
+    monkeypatch.setattr(QuestionRefiner, "_deduplicate", similarity_failed)
+    _argv(monkeypatch, "questions", "refine", "--questions", _questions(tmp_path),
+          "--product", "numba", "--dry-run")
+    with pytest.raises(ValueError, match="similarity backend returned NaN"):
+        cli.main()
diff --git a/dokimi/tests/test_exit_codes_input_errors.py b/dokimi/tests/test_exit_codes_input_errors.py
new file mode 100644
index 000000000..7da5ad766
--- /dev/null
+++ b/dokimi/tests/test_exit_codes_input_errors.py
@@ -0,0 +1,108 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""Exit codes of the input and usage refusals, per command (the exit-code table in docs/quickstart.md).
+
+A bad input file, an input the command cannot use, a flag combination it refuses and a
+missing credential exit 2. Exit 1 is reserved for a verdict or a gate that ran and failed.
+Each case is one command; argparse refusals are excluded by the ``usage:`` guard, so a
+case cannot pass on a flag typo.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from dokimi import cli
+
+
+def _missing(tmp_path):
+    return str(tmp_path / "missing.json")
+
+
+def _personas_approve(tmp_path):
+    return ["personas", "approve", "--file", _missing(tmp_path)]
+
+
+def _personas_discover_no_source(tmp_path):
+    return ["personas", "discover", "--product", "lib"]
+
+
+def _tools_preference_missing_groups(tmp_path):
+    return ["tools", "preference", "--groups", _missing(tmp_path), "--model", "m"]
+
+
+def _report_eval_missing(tmp_path):
+    return ["report", "eval", "--product", "lib", "--eval", _missing(tmp_path)]
+
+
+def _report_generate_missing_questions(tmp_path):
+    eval_file = tmp_path / "eval.json"  # a readable eval, so the questions file is the refusal
+    eval_file.write_text('{"evaluations": [{"question_id": "q1"}]}', encoding="utf-8")  # a run that judged something
+    return ["report", "generate", "--product", "lib", "--eval", str(eval_file),
+            "--questions", _missing(tmp_path)]
+
+
+def _baseline_save_missing(tmp_path):
+    return ["baseline", "save", "--from-eval", _missing(tmp_path)]
+
+
+def _novelty_routing_flag_combination(tmp_path):
+    return ["novelty", "routing", "--all-vs-all", "--artifact", _missing(tmp_path)]
+
+
+def _library_list_unknown_domain(tmp_path):
+    return ["library", "list", "--domain", "no-such-domain"]
+
+
+@pytest.mark.parametrize(
+    ("argv_for", "needle"),
+    [
+        pytest.param(_personas_approve, "missing.json", id="personas_approve"),
+        pytest.param(_personas_discover_no_source, "Either --repo or --description must be provided.",
+                     id="personas_discover_no_source"),
+        pytest.param(_tools_preference_missing_groups, "missing.json", id="tools_preference_missing_groups"),
+        pytest.param(_report_eval_missing, "missing.json", id="report_eval_missing"),
+        pytest.param(_report_generate_missing_questions, "missing.json", id="report_generate_missing_questions"),
+        pytest.param(_baseline_save_missing, "missing.json", id="baseline_save_missing"),
+        pytest.param(_novelty_routing_flag_combination, "--all-vs-all takes no --artifact",
+                     id="novelty_routing_flag_combination"),
+        pytest.param(_library_list_unknown_domain, "Intent domain 'no-such-domain' not found",
+                     id="library_list_unknown_domain"),
+    ],
+)
+def test_input_or_usage_refusal_exits_2_with_a_message(argv_for, needle, tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr("sys.argv", ["dokimi", *argv_for(tmp_path)])
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    err = capsys.readouterr().err
+    assert "usage:" not in err, "argparse refused the flags; the case does not reach the rule"
+    assert "Traceback" not in err
+    # The message must name the input at fault, not just any exit 2.
+    assert needle in err
+    assert exc.value.code == 2
+
+
+def test_explore_list_without_a_bundled_task_root_exits_2(tmp_path, monkeypatch, capsys):
+    monkeypatch.setattr("dokimi.explore.tasks.EXPLORE_TASKS_ROOT", tmp_path / "absent")
+    monkeypatch.setattr("sys.argv", ["dokimi", "explore", "list"])
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert "Pass --tasks-root" in capsys.readouterr().err
+    assert exc.value.code == 2
+
+
+def test_benchmark_preflight_missing_credential_exits_2(tmp_path, monkeypatch, capsys):
+    for var in ("OPENAI_API_KEY", "AWS_BEARER_TOKEN_BEDROCK"):
+        monkeypatch.delenv(var, raising=False)
+    monkeypatch.setattr(
+        "sys.argv",
+        ["dokimi", "benchmark", "preflight", "--library", "onetbb", "--provider", "openai",
+         "--judge-provider", "openai", "--output-dir", str(tmp_path / "out")],
+    )
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    err = capsys.readouterr().err
+    assert "usage:" not in err
+    assert "missing OPENAI_API_KEY for provider openai" in err
+    assert exc.value.code == 2
diff --git a/dokimi/tests/test_explore_run_outputs.py b/dokimi/tests/test_explore_run_outputs.py
index 72d6af8fe..38ccaf818 100644
--- a/dokimi/tests/test_explore_run_outputs.py
+++ b/dokimi/tests/test_explore_run_outputs.py
@@ -34,7 +34,7 @@ def test_an_unwritable_output_is_reported_not_a_traceback(tmp_path, capsys, flag
     target = _blocker(tmp_path) / "report"
     with pytest.raises(SystemExit) as exc:
         _run(tmp_path, flag, str(target))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write {target}" in capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_import_architecture.py b/dokimi/tests/test_import_architecture.py
index ebeb4eb10..7762689d9 100644
--- a/dokimi/tests/test_import_architecture.py
+++ b/dokimi/tests/test_import_architecture.py
@@ -68,7 +68,7 @@
     # What everything shares: defaults, registries, artifact and record I/O, the LLM and
     # process chokepoints, console output.
     ("foundation", (
-        "dokimi", "dokimi._version", "dokimi.artifacts", "dokimi.caching", "dokimi.cli_flags",
+        "dokimi", "dokimi._version", "dokimi.artifacts", "dokimi.caching", "dokimi.cli_flags", "dokimi.exit_codes",
         "dokimi.config", "dokimi.console", "dokimi.container_policy", "dokimi.defaults",
         "dokimi.intents", "dokimi.llm", "dokimi.llm_pricing",
         "dokimi.process", "dokimi.records", "dokimi.registry", "dokimi.utils",
diff --git a/dokimi/tests/test_library_cli_inputs.py b/dokimi/tests/test_library_cli_inputs.py
index 85476a6db..46c6d0869 100644
--- a/dokimi/tests/test_library_cli_inputs.py
+++ b/dokimi/tests/test_library_cli_inputs.py
@@ -16,7 +16,7 @@ def _run(argv, capsys):
     args = build_parser().parse_args(argv)
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     return capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_matrix_rollup.py b/dokimi/tests/test_matrix_rollup.py
index ca199ac1e..bbe0789e9 100644
--- a/dokimi/tests/test_matrix_rollup.py
+++ b/dokimi/tests/test_matrix_rollup.py
@@ -205,7 +205,7 @@ def test_arms_matrix_run_rejects_sanitized_cell_name_collisions(tmp_path: Path):
 
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
 def test_arms_matrix_run_rejects_unwired_harnesses(tmp_path: Path):
@@ -242,7 +242,7 @@ def test_arms_matrix_run_rejects_unwired_harnesses(tmp_path: Path):
 
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
 def test_arms_run_selected_matrix_cell_rejects_unwired_harness(tmp_path: Path):
@@ -281,7 +281,7 @@ def test_arms_run_selected_matrix_cell_rejects_unwired_harness(tmp_path: Path):
 
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
 def test_arms_matrix_run_keeps_cell_artifacts_away_from_generated_names(tmp_path: Path, monkeypatch):
diff --git a/dokimi/tests/test_model_compare_exit_codes.py b/dokimi/tests/test_model_compare_exit_codes.py
new file mode 100644
index 000000000..7366b57d1
--- /dev/null
+++ b/dokimi/tests/test_model_compare_exit_codes.py
@@ -0,0 +1,36 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+"""Runs that cannot be compared are refused with exit 2, as a missing --treatment-arm is.
+
+The refusals are input errors: the command was given runs it cannot pool. A message match alone
+would pass if a refusal went back to the default exit status 1, so each case also pins the code.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from dokimi.report.model_compare import check_run_consistency
+from tests.test_model_compare import _V1, _run_pair, _stamped
+
+_NULL_ARM = {"baseline_arm": "baseline", "answers": [
+    {"question_id": "q1", "question_text": "Q?", "arms": {"baseline": {"answer": "b"}, "docs": None}}]}
+_OTHER_ARM = {"baseline_arm": "baseline", "answers": [
+    {"question_id": "q1", "question_text": "Q?", "arms": {"baseline": {"answer": "b"}, "skill": {"answer": "s"}}}]}
+
+REFUSED_RUNS = {
+    "baseline-arm": ([_run_pair("a", baseline="no-context"), _run_pair("b", baseline="baseline")], "different baseline_arm"),
+    "same-model": ([_run_pair("a", model="same"), _run_pair("b", model="same")], "--pool-replicates"),
+    "treatment-arms": ([("a", _NULL_ARM), ("b", _OTHER_ARM)], "different treatment arms"),
+    "judge-context": ([_stamped("a", None), _stamped("b", _V1)], "judge_context"),
+    "mixed-run": ([_stamped("a", _V1 + "+snippet_fallback"), _stamped("b", _V1)], "pools with nothing"),
+}
+
+
+@pytest.mark.parametrize("name", REFUSED_RUNS)
+def test_runs_that_cannot_be_compared_exit_2(name):
+    runs, message = REFUSED_RUNS[name]
+    with pytest.raises(SystemExit, match=message) as exc:
+        check_run_consistency(runs, "regular")
+    assert exc.value.code == 2
diff --git a/dokimi/tests/test_novelty_analyze.py b/dokimi/tests/test_novelty_analyze.py
index 2a456e0ca..c814879bc 100644
--- a/dokimi/tests/test_novelty_analyze.py
+++ b/dokimi/tests/test_novelty_analyze.py
@@ -132,6 +132,32 @@ def _analyze(tmp_path, **overrides):
     return analyze(body, config, extractor=extractor, answerer=answerer, judge=judge)
 
 
+def test_a_self_judged_run_is_refused_before_any_extraction_call(tmp_path):
+    """The judge check runs before the first paid call, not after the extraction."""
+    from dokimi.novelty.measure import SelfJudgeError
+
+    calls = []
+
+    def counting(prompt, system):
+        calls.append(prompt)
+        return ("x", None)
+
+    path = tmp_path / "accel-tuning" / "SKILL.md"
+    path.parent.mkdir(parents=True)
+    path.write_text(SKILL, encoding="utf-8")
+    kind, name, description, frontmatter, body = load_artifact_text(f"skill:{path}")
+    config = AnalyzeConfig(
+        artifact_ref=f"skill:{path}", artifact_kind=kind, name=name,
+        description=description, frontmatter=frontmatter, concurrency=1,
+    )
+    extractor = LLMClient(model="same-m", role="extractor", transport=counting)
+    answerer = LLMClient(model="same-m", role="answerer", transport=counting)
+    judge = LLMClient(model="same-m", role="judge", transport=counting)
+    with pytest.raises(SelfJudgeError):
+        analyze(body, config, extractor=extractor, answerer=answerer, judge=judge)
+    assert calls == []
+
+
 def test_skill_reference_splits_frontmatter_from_body(tmp_path):
     path = tmp_path / "accel-tuning" / "SKILL.md"
     path.parent.mkdir(parents=True)
diff --git a/dokimi/tests/test_novelty_journey.py b/dokimi/tests/test_novelty_journey.py
index 3bddae704..ffcee0a5c 100644
--- a/dokimi/tests/test_novelty_journey.py
+++ b/dokimi/tests/test_novelty_journey.py
@@ -186,10 +186,62 @@ def test_probing_atoms_from_a_changed_artifact_is_refused(tmp_path, skill, stub_
     _run("novelty", "atoms", "--artifact", f"skill:{skill}", "--include-resources",
          "--extract-model", "extractor-m", "--out", str(atoms_out))
     (skill / "references" / "new.md").write_text("Another reference.\n", encoding="utf-8")
-    with pytest.raises(SystemExit, match="files changed"):
+    with pytest.raises(SystemExit, match="files changed") as exc:
         _run("novelty", "probe", "--artifact", f"skill:{skill}", "--atoms", str(atoms_out),
              "--model", "model-a", "--judge-model", "judge-m",
              "--out", str(tmp_path / "p.json"))
+    assert exc.value.code == 2  # an atoms file this artifact cannot use: an input refusal
+
+
+@pytest.mark.parametrize("command", ["analyze", "probe"])
+def test_a_judge_that_is_the_answering_model_is_refused_with_exit_2(command, tmp_path, skill, stub_models,
+                                                                    monkeypatch, capsys):
+    atoms_out = tmp_path / "atoms.json"
+    _run("novelty", "atoms", "--artifact", f"skill:{skill}", "--extract-model", "extractor-m",
+         "--out", str(atoms_out))
+    # Count the prompts from here on: the refusal must come before any extraction or paraphrase call.
+    prompts = []
+    scripted = client_mod.LLMClient
+
+    def recording_client(**kwargs):
+        def transport(prompt, system):
+            prompts.append(prompt)
+            return stub_models(prompt, system)
+        return scripted(**{**kwargs, "transport": transport})
+
+    monkeypatch.setattr(client_mod, "LLMClient", recording_client)
+    extra = ["--atoms", str(atoms_out), "--out", str(tmp_path / "p.json")] if command == "probe" else \
+        ["--out-dir", str(tmp_path / "out")]
+    with pytest.raises(SystemExit) as exc:
+        _run("novelty", command, "--artifact", f"skill:{skill}", "--model", "model-a",
+             "--judge-model", "model-a", *extra)
+    assert exc.value.code == 2
+    assert "is the answering model" in capsys.readouterr().err
+    assert prompts == [], "a model was called before the self-judge check refused"
+
+
+def test_probe_refuses_an_unknown_arm_before_any_model_call(tmp_path, skill, stub_models, monkeypatch, capsys):
+    atoms_out = tmp_path / "atoms.json"
+    _run("novelty", "atoms", "--artifact", f"skill:{skill}", "--extract-model", "extractor-m",
+         "--out", str(atoms_out))
+    # Count the prompts the probe sends from here on: the atoms step above is not part of the refusal.
+    prompts = []
+    scripted = client_mod.LLMClient  # the factory stub_models installed
+
+    def recording_client(**kwargs):
+        def transport(prompt, system):
+            prompts.append(prompt)
+            return stub_models(prompt, system)
+        return scripted(**{**kwargs, "transport": transport})
+
+    monkeypatch.setattr(client_mod, "LLMClient", recording_client)
+    with pytest.raises(SystemExit) as exc:
+        _run("novelty", "probe", "--artifact", f"skill:{skill}", "--atoms", str(atoms_out),
+             "--model", "model-a", "--judge-model", "judge-m", "--arms", "no_artifact,full,no-such-arm",
+             "--out", str(tmp_path / "p.json"))
+    assert exc.value.code == 2
+    assert "unknown novelty arms" in capsys.readouterr().err
+    assert prompts == [], "a model was called before the arm check refused"
 
 
 @pytest.mark.outcome("cjm-novelty-remeasure")
diff --git a/dokimi/tests/test_novelty_settings_parity.py b/dokimi/tests/test_novelty_settings_parity.py
index 7d727e7af..713ab052b 100644
--- a/dokimi/tests/test_novelty_settings_parity.py
+++ b/dokimi/tests/test_novelty_settings_parity.py
@@ -238,8 +238,21 @@ def _kept_estimate(step: dict) -> dict:
     return {**step, "stdout": payload, "stderr": stderr}
 
 
-# Runs main refuses only after the extraction calls it had already made.
-REFUSED_BEFORE_ANY_CALL = {"run/arms-without-full"}
+# Runs main refuses only after the model calls it had already made (the extraction of `analyze`,
+# the probe wordings of `probe`).
+REFUSED_BEFORE_ANY_CALL = {"run/arms-without-full", "probe/arms-without-baseline"}
+# Input refusals from the arm-set checks: main raised the message as the exit status, visible only at interpreter exit.
+# The exit-code table (docs/quickstart.md) makes these exit 2, and usage_exit prints the message before raising.
+ARMS_REFUSALS = {"estimate/arms-without-full", "estimate/arms-without-baseline",
+                 "probe/arms-without-baseline", "run/arms-without-full"}
+
+
+def _refusal_as_exit_2(step: dict[str, Any]) -> dict[str, Any]:
+    if isinstance(step["status"], str):
+        return {**step, "status": 2, "stderr": step["stderr"] + step["status"] + "\n"}
+    return step
+
+
 # `novelty atoms` runs whose cap binds.
 CAPPED_ATOMS = {"atoms/max-atoms-1"}
 # Intended change: the cap warning says how far the cap reached instead of calling the
@@ -264,15 +277,17 @@ def test_no_setting_bill_or_tier_record_differs_from_main(name, tmp_path):
     for step_coverage in coverage:
         if step_coverage is not None:
             _check_headline(step_coverage)
+    expected = [_refusal_as_exit_2(step) if name in ARMS_REFUSALS else step
+                for step in golden[name]]
     if name.startswith("estimate/"):
         assert [_kept_estimate(step) for step in steps] == [
-            _kept_estimate(step) for step in golden[name]]
+            _kept_estimate(step) for step in expected]
     else:
-        expected = json.loads(json.dumps(golden[name]).replace(CAP_WARNING_ON_MAIN, CAP_WARNING))
+        expected = json.loads(json.dumps(expected).replace(CAP_WARNING_ON_MAIN, CAP_WARNING))
         if name in REFUSED_BEFORE_ANY_CALL:
             # Intended change: the arm and placebo checks now run before the clients are
             # built, so the refusal makes no model call. Same status and output as on main.
-            expected = [dict(step, calls=[]) for step in expected]
+            expected = [*expected[:-1], dict(expected[-1], calls=[])]  # the refused step is the last
         if name in CAPPED_ATOMS:
             # Intended change: `novelty atoms` prints the cap warning `analyze` records.
             expected = [dict(step, stderr=f"{step['stderr']}WARNING {CAP_WARNING}\n")
diff --git a/dokimi/tests/test_novelty_view_inputs.py b/dokimi/tests/test_novelty_view_inputs.py
index 609068c1e..ac96766c5 100644
--- a/dokimi/tests/test_novelty_view_inputs.py
+++ b/dokimi/tests/test_novelty_view_inputs.py
@@ -23,7 +23,7 @@ def _err(tmp_path, novelty, atoms, capsys):
     out = tmp_path / "annotated.md"
     with pytest.raises(SystemExit) as exc:
         _view(novelty, atoms, out)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert not out.exists()
     return capsys.readouterr().err
 
diff --git a/dokimi/tests/test_personas_approve.py b/dokimi/tests/test_personas_approve.py
index 5e2643c9e..bef1a5c27 100644
--- a/dokimi/tests/test_personas_approve.py
+++ b/dokimi/tests/test_personas_approve.py
@@ -39,10 +39,10 @@ def test_approve_accepts_a_valid_persona_file(tmp_path, monkeypatch, capsys):
     ],
     ids=["not-an-object", "personas-not-a-list", "persona-not-an-object", "not-utf8"],
 )
-def test_approve_exits_1_with_a_message_on_an_invalid_file(tmp_path, monkeypatch, capsys, content):
+def test_approve_exits_2_with_a_message_on_an_invalid_file(tmp_path, monkeypatch, capsys, content):
     f = tmp_path / "personas.json"
     f.write_bytes(content)
-    assert _approve(f, monkeypatch) == 1
+    assert _approve(f, monkeypatch) == 2
     err = capsys.readouterr().err
     assert err.startswith("✗ ") and "Traceback" not in err
     if content.startswith(b"\xff"):
@@ -51,6 +51,6 @@ def test_approve_exits_1_with_a_message_on_an_invalid_file(tmp_path, monkeypatch
         assert "'not-an-object'" in err
 
 
-def test_approve_exits_1_when_the_path_is_a_directory(tmp_path, monkeypatch, capsys):
-    assert _approve(tmp_path, monkeypatch) == 1
+def test_approve_exits_2_when_the_path_is_a_directory(tmp_path, monkeypatch, capsys):
+    assert _approve(tmp_path, monkeypatch) == 2
     assert f"Cannot read {tmp_path}" in capsys.readouterr().err
diff --git a/dokimi/tests/test_personas_discover_output.py b/dokimi/tests/test_personas_discover_output.py
index 6329b25d7..3248088ef 100644
--- a/dokimi/tests/test_personas_discover_output.py
+++ b/dokimi/tests/test_personas_discover_output.py
@@ -54,31 +54,31 @@ def fakes(monkeypatch):
 
 
 @pytest.mark.parametrize("kind", ["under-a-file", "is-a-directory"])
-def test_discover_exits_1_when_the_personas_output_cannot_be_written(tmp_path, capsys, fakes, kind):
+def test_discover_exits_2_when_the_personas_output_cannot_be_written(tmp_path, capsys, fakes, kind):
     out = _outputs(tmp_path)[kind]
     args = SimpleNamespace(repo=None, description="d", product="p", output=str(out), count=1,
                            model="m", provider="x", save_analysis=False, github_token=None)
     with pytest.raises(SystemExit) as exc:
         personas_cmd.cmd_personas_discover(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
 
 
-def test_discover_exits_1_when_the_analysis_cannot_be_written(tmp_path, capsys, fakes):
+def test_discover_exits_2_when_the_analysis_cannot_be_written(tmp_path, capsys, fakes):
     blocker = tmp_path / "file"
     blocker.write_text("x", encoding="utf-8")
     args = SimpleNamespace(repo="o/r", description=None, product="p", output=str(blocker / "out.json"),
                            count=1, model="m", provider="x", save_analysis=True, github_token="t")
     with pytest.raises(SystemExit) as exc:
         personas_cmd.cmd_personas_discover(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and "p_analysis.json" in err
 
 
 @pytest.mark.parametrize("kind", ["under-a-file", "is-a-directory"])
-def test_analyze_exits_1_when_the_report_cannot_be_written(tmp_path, monkeypatch, capsys, kind):
+def test_analyze_exits_2_when_the_report_cannot_be_written(tmp_path, monkeypatch, capsys, kind):
     from dokimi.questions import quality_analyzer
 
     class _Report:
@@ -109,6 +109,6 @@ def save_report(self, report, path):
                                      "--product", "p", "--output", str(out)])
     with pytest.raises(SystemExit) as exc:
         cli.main()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
diff --git a/dokimi/tests/test_questions_artifact.py b/dokimi/tests/test_questions_artifact.py
index b5201201c..5ac6c7ebd 100644
--- a/dokimi/tests/test_questions_artifact.py
+++ b/dokimi/tests/test_questions_artifact.py
@@ -566,7 +566,7 @@ def no_client(*a, **kw):
                                       "--questions", str(src)])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "record 0 (id 'q1'), `question`: '' should be non-empty" in capsys.readouterr().err
 
 
@@ -625,7 +625,7 @@ def test_report_generate_refuses_malformed_questions_with_error_exit(tmp_path, m
                                       "--questions", str(src), "--output", str(out)])
     with pytest.raises(SystemExit) as exc_info:
         args.func(args)
-    assert exc_info.value.code == 1
+    assert exc_info.value.code == 2
     assert "Error:" in capsys.readouterr().err
 
 
@@ -640,7 +640,7 @@ def test_questions_refine_refuses_malformed_questions_with_error_exit(tmp_path,
                                       "--questions", str(src), "--output", str(out)])
     with pytest.raises(SystemExit) as exc_info:
         args.func(args)
-    assert exc_info.value.code == 1
+    assert exc_info.value.code == 2
     assert "Error:" in capsys.readouterr().err
 
 
@@ -654,7 +654,7 @@ def test_questions_refine_names_an_unreadable_questions_file(tmp_path, capsys, k
                                       "--questions", str(src), "--output", str(tmp_path / "out.json")])
     with pytest.raises(SystemExit) as exc_info:
         args.func(args)
-    assert exc_info.value.code == 1
+    assert exc_info.value.code == 2
     assert f"Error: cannot read {src}" in capsys.readouterr().err
 
 
@@ -700,7 +700,7 @@ def test_report_generate_prints_an_error_for_an_empty_question(tmp_path, capsys)
                                       "--questions", str(src), "--output", str(tmp_path / "r.md")])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert capsys.readouterr().err.startswith("Error: ")
 
 
@@ -790,7 +790,7 @@ def fail_fill(self, *a, **k):
                                       "--fill-gaps"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "Error:" in capsys.readouterr().err
     assert not out.exists()
 
diff --git a/dokimi/tests/test_questions_generate_config.py b/dokimi/tests/test_questions_generate_config.py
index 2e75e8a98..6cf77ea2f 100644
--- a/dokimi/tests/test_questions_generate_config.py
+++ b/dokimi/tests/test_questions_generate_config.py
@@ -27,8 +27,8 @@ def _generate(tmp_path, monkeypatch, config_text):
     ("products: [unclosed\n", "invalid YAML"),
     ("- a\n- b\n", "expected a mapping"),
 ])
-def test_an_invalid_runtime_config_exits_1_with_a_message(tmp_path, monkeypatch, capsys, text, message):
+def test_an_invalid_runtime_config_exits_2_with_a_message(tmp_path, monkeypatch, capsys, text, message):
     with pytest.raises(SystemExit) as exc:
         _generate(tmp_path, monkeypatch, text)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert message in capsys.readouterr().err
diff --git a/dokimi/tests/test_questions_generate_inputs.py b/dokimi/tests/test_questions_generate_inputs.py
index 4c9d0043d..a874bfa0e 100644
--- a/dokimi/tests/test_questions_generate_inputs.py
+++ b/dokimi/tests/test_questions_generate_inputs.py
@@ -21,11 +21,11 @@ def _generate(monkeypatch, *extra):
 
 @pytest.mark.parametrize("content", [None, "{not json", "[1, 2]", '{"personas": "dev"}', "{}"],
                          ids=["missing", "malformed", "not-an-object", "personas-not-a-list", "no-personas"])
-def test_generate_exits_1_on_an_unusable_personas_file(tmp_path, monkeypatch, capsys, content):
+def test_generate_exits_2_on_an_unusable_personas_file(tmp_path, monkeypatch, capsys, content):
     bad = tmp_path / "personas.json"
     if content is not None:
         bad.write_text(content, encoding="utf-8")
-    assert _generate(monkeypatch, "--personas", str(bad)) == 1
+    assert _generate(monkeypatch, "--personas", str(bad)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ") and str(bad) in err
 
@@ -35,33 +35,33 @@ def test_generate_exits_1_on_an_unusable_personas_file(tmp_path, monkeypatch, ca
     [[1, "x"], [{"id": "p1", "name": "dev"}], [{"name": "dev", "skill_level": "beginner"}],
      [{"id": "p1", "skill_level": "beginner"}]],
     ids=["items-not-objects", "missing-skill-level", "missing-id", "missing-name"])
-def test_generate_exits_1_on_personas_missing_required_fields(tmp_path, monkeypatch, capsys, personas):
+def test_generate_exits_2_on_personas_missing_required_fields(tmp_path, monkeypatch, capsys, personas):
     bad = tmp_path / "personas.json"
     bad.write_text(json.dumps({"personas": personas}), encoding="utf-8")
-    assert _generate(monkeypatch, "--personas", str(bad)) == 1
+    assert _generate(monkeypatch, "--personas", str(bad)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ") and str(bad) in err and "skill_level" in err
 
 
 @pytest.mark.parametrize("content", ["5", '{"a": 1}'], ids=["number", "object"])
-def test_generate_exits_1_when_topics_is_not_a_list(tmp_path, monkeypatch, capsys, content):
+def test_generate_exits_2_when_topics_is_not_a_list(tmp_path, monkeypatch, capsys, content):
     personas = tmp_path / "personas.json"
     personas.write_text(json.dumps(GOOD_PERSONAS), encoding="utf-8")
     bad = tmp_path / "topics.json"
     bad.write_text(content, encoding="utf-8")
-    assert _generate(monkeypatch, "--personas", str(personas), "--topics", str(bad)) == 1
+    assert _generate(monkeypatch, "--personas", str(personas), "--topics", str(bad)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ") and str(bad) in err and "list" in err
 
 
 @pytest.mark.parametrize("content", [None, "{not json"], ids=["missing", "malformed"])
-def test_generate_exits_1_on_an_unreadable_topics_file(tmp_path, monkeypatch, capsys, content):
+def test_generate_exits_2_on_an_unreadable_topics_file(tmp_path, monkeypatch, capsys, content):
     personas = tmp_path / "personas.json"
     personas.write_text(json.dumps(GOOD_PERSONAS), encoding="utf-8")
     bad = tmp_path / "topics.json"
     if content is not None:
         bad.write_text(content, encoding="utf-8")
-    assert _generate(monkeypatch, "--personas", str(personas), "--topics", str(bad)) == 1
+    assert _generate(monkeypatch, "--personas", str(personas), "--topics", str(bad)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ") and str(bad) in err
 
@@ -87,7 +87,7 @@ def _unwritable_outputs(tmp_path):
 
 
 @pytest.mark.parametrize("which", [0, 1], ids=["under-a-file", "is-a-directory"])
-def test_generate_exits_1_when_the_output_cannot_be_written(tmp_path, monkeypatch, capsys, which):
+def test_generate_exits_2_when_the_output_cannot_be_written(tmp_path, monkeypatch, capsys, which):
     personas = tmp_path / "personas.json"
     personas.write_text(json.dumps(GOOD_PERSONAS), encoding="utf-8")
     topics = tmp_path / "topics.json"
@@ -96,7 +96,7 @@ def test_generate_exits_1_when_the_output_cannot_be_written(tmp_path, monkeypatc
     monkeypatch.setattr("dokimi.commands.answers._load_runtime_config", dict)
     monkeypatch.setattr("dokimi.questions.QuestionGenerator", _FakeGenerator)
     assert _generate(monkeypatch, "--personas", str(personas), "--topics", str(topics),
-                     "--output", str(out)) == 1
+                     "--output", str(out)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
 
diff --git a/dokimi/tests/test_questions_input_errors.py b/dokimi/tests/test_questions_input_errors.py
index 092632ef7..82bca5a14 100644
--- a/dokimi/tests/test_questions_input_errors.py
+++ b/dokimi/tests/test_questions_input_errors.py
@@ -32,13 +32,13 @@ def _bad_files(tmp_path):
 
 @pytest.mark.parametrize("cmd", [cmd_questions_analyze, cmd_questions_panel_review])
 @pytest.mark.parametrize("case", ["invalid json", "not utf-8", "a directory", "missing", "nested too deep"])
-def test_unreadable_questions_file_exits_1_with_a_message(cmd, case, tmp_path, capsys):
+def test_unreadable_questions_file_exits_2_with_a_message(cmd, case, tmp_path, capsys):
     path = _bad_files(tmp_path)[case]
 
     with pytest.raises(SystemExit) as exc:
         cmd(_args(path, tmp_path))
 
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ")
     assert str(path) in err
diff --git a/dokimi/tests/test_questions_output_unwritable.py b/dokimi/tests/test_questions_output_unwritable.py
index 13537e786..9daee81a9 100644
--- a/dokimi/tests/test_questions_output_unwritable.py
+++ b/dokimi/tests/test_questions_output_unwritable.py
@@ -59,19 +59,19 @@ def _run(monkeypatch, *argv):
 
 
 @pytest.mark.parametrize("out", ["under-a-file", "is-a-directory"], indirect=True)
-def test_refine_exits_1_when_the_output_cannot_be_written(monkeypatch, capsys, questions_file, out):
+def test_refine_exits_2_when_the_output_cannot_be_written(monkeypatch, capsys, questions_file, out):
     monkeypatch.setattr("dokimi.questions.artifact.save_questions_artifact",
                         lambda data, path: _write(path))
     assert _run(monkeypatch, "refine", "--product", "p", "--questions", str(questions_file),
-                "--output", str(out)) == 1
+                "--output", str(out)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
 
 
 @pytest.mark.parametrize("out", ["under-a-file", "is-a-directory"], indirect=True)
-def test_panel_review_exits_1_when_the_output_cannot_be_written(monkeypatch, capsys, questions_file, out):
+def test_panel_review_exits_2_when_the_output_cannot_be_written(monkeypatch, capsys, questions_file, out):
     monkeypatch.setattr("dokimi.questions.panel_reviewer.QuestionPanelReviewer", _FakeReviewer)
     assert _run(monkeypatch, "panel-review", "--product", "p", "--questions", str(questions_file),
-                "--output", str(out)) == 1
+                "--output", str(out)) == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
diff --git a/dokimi/tests/test_ragas_runtime.py b/dokimi/tests/test_ragas_runtime.py
index fac203366..be8d9dde5 100644
--- a/dokimi/tests/test_ragas_runtime.py
+++ b/dokimi/tests/test_ragas_runtime.py
@@ -76,7 +76,7 @@ def test_ragas_without_the_extra_exits_with_the_install_command(monkeypatch, tmp
     monkeypatch.setitem(sys.modules, "ragas.llms", None)
     with pytest.raises(SystemExit) as exc:
         _run_ragas_eval([], tmp_path / "answers.json", object())
-    assert "pip install 'dokimi[ragas]'" in str(exc.value.code)
+    assert "pip install 'dokimi[ragas]'" in str(exc.value)
     assert not (tmp_path / "answers_ragas.json").exists()
 
 
@@ -91,4 +91,4 @@ def test_ragas_commands_exit_before_any_work_without_the_extra(monkeypatch, tmp_
     run = cmd_eval_ragas if command == "eval_ragas" else cmd_answers_generate
     with pytest.raises(SystemExit) as exc:
         run(args)
-    assert "pip install 'dokimi[ragas]'" in str(exc.value.code)
+    assert "pip install 'dokimi[ragas]'" in str(exc.value)
diff --git a/dokimi/tests/test_record_readers.py b/dokimi/tests/test_record_readers.py
index 2b58cfe02..ee83a7108 100644
--- a/dokimi/tests/test_record_readers.py
+++ b/dokimi/tests/test_record_readers.py
@@ -281,7 +281,7 @@ def test_report_eval_exits_cleanly_naming_the_file(tmp_path, capsys):
     path, out = _id_less_eval(tmp_path), tmp_path / "r.md"
     with pytest.raises(SystemExit) as exc:
         cmd_report_eval(argparse.Namespace(eval=str(path), out=str(out), product="P", run_id=None))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: {path}[1]: missing question_id" in capsys.readouterr().err
     assert not out.exists()
 
@@ -296,7 +296,7 @@ def test_report_generate_exits_cleanly_naming_the_file(tmp_path, capsys, fmt):
     with pytest.raises(SystemExit) as exc:
         cmd_report_generate(argparse.Namespace(eval=str(path), questions=str(questions), format=fmt,
                                                output=str(out), product="P"))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: {path} evaluations[1]: missing question_id" in capsys.readouterr().err
     assert not out.exists()
 
@@ -326,7 +326,7 @@ def test_plugin_delta_names_the_file_with_the_malformed_record(tmp_path, monkeyp
     assert not (tmp_path / "d.json").exists()
 
 
-def test_plugin_delta_exits_1_with_a_message_on_an_unreadable_arms_file(tmp_path, capsys):
+def test_plugin_delta_exits_2_with_a_message_on_an_unreadable_arms_file(tmp_path, capsys):
     from dokimi.cli import build_parser
 
     unreadable = tmp_path / "b.json"
@@ -336,7 +336,7 @@ def test_plugin_delta_exits_1_with_a_message_on_an_unreadable_arms_file(tmp_path
                                       "--out-json", str(tmp_path / "d.json")])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "b.json" in capsys.readouterr().err
     assert not (tmp_path / "d.json").exists()
 
diff --git a/dokimi/tests/test_repo_budget.py b/dokimi/tests/test_repo_budget.py
index ec4b5c229..3016ca070 100644
--- a/dokimi/tests/test_repo_budget.py
+++ b/dokimi/tests/test_repo_budget.py
@@ -321,7 +321,7 @@ def test_cli_json_and_bad_source(tmp_path, capsys):
     assert data["totals"]["start"] == 1
     with pytest.raises(SystemExit) as exc:
         _run(["repo", "budget", str(tmp_path / "missing")], capsys)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
 @pytest.mark.outcome("cjm-repo-budget")
@@ -333,7 +333,7 @@ def test_cli_out_writes_the_inventory(tmp_path, capsys):
     assert "| start | guidance | AGENTS.md | 1 |" in out  # the table still prints
     with pytest.raises(SystemExit) as exc:  # a parent that is a file cannot become a directory
         _run(["repo", "budget", str(tmp_path), "--out", str(tmp_path / "AGENTS.md" / "b.json")], capsys)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
 def test_imports_must_exist_to_be_counted(tmp_path):
diff --git a/dokimi/tests/test_repo_compare.py b/dokimi/tests/test_repo_compare.py
index 7cc208e22..2cc94e8b3 100644
--- a/dokimi/tests/test_repo_compare.py
+++ b/dokimi/tests/test_repo_compare.py
@@ -560,7 +560,7 @@ def test_a_metric_no_cell_reports_is_refused(tmp_path, capsys):
     args = build_parser().parse_args(["repo", "compare", str(b), "--baseline", "guidance:none", "--metric", "typo"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1 and "--metric typo" in capsys.readouterr().err
+    assert exc.value.code == 2 and "--metric typo" in capsys.readouterr().err
 
 
 def test_a_task_lacking_a_metric_is_listed_as_unpaired_for_that_metric(tmp_path):
@@ -698,7 +698,7 @@ def test_cli_passes_model_and_metric_and_refuses_a_missing_dir(tmp_path, capsys)
     args = build_parser().parse_args(["repo", "compare", str(tmp_path / "nope"), "--baseline", "guidance:none"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1 and "not a directory" in capsys.readouterr().err
+    assert exc.value.code == 2 and "not a directory" in capsys.readouterr().err
 
 
 def test_cli_exits_on_a_bad_baseline(tmp_path, capsys):
@@ -707,7 +707,7 @@ def test_cli_exits_on_a_bad_baseline(tmp_path, capsys):
     args = build_parser().parse_args(["repo", "compare", str(b), "--baseline", "guidance:raw"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1 and "no finished cell matches the baseline" in capsys.readouterr().err
+    assert exc.value.code == 2 and "no finished cell matches the baseline" in capsys.readouterr().err
 
 
 def test_a_repeated_treatment_or_metric_is_one_comparison(tmp_path):
@@ -732,7 +732,7 @@ def test_an_empty_arm_list_is_refused_not_an_empty_comparison(tmp_path, capsys,
     args = build_parser().parse_args(["repo", "compare", str(b), "--baseline", "guidance:none", "--arm", spec])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1 and "no treatment arms" in capsys.readouterr().err
+    assert exc.value.code == 2 and "no treatment arms" in capsys.readouterr().err
 
 
 @pytest.mark.parametrize("bad", [float("inf"), float("-inf"), float("nan")])
@@ -755,7 +755,7 @@ def test_an_unusable_cost_rejects_the_cell_naming_it(tmp_path, capsys, bad):
     with pytest.raises(SystemExit) as exc:
         args.func(args)
     err = capsys.readouterr().err
-    assert exc.value.code == 1 and "has no usable `agent`" in err and "Traceback" not in err
+    assert exc.value.code == 2 and "has no usable `agent`" in err and "Traceback" not in err
     assert "fix_0__guidance-none__m-1__r1" in err and "guidance-raw" not in err
 
 
diff --git a/dokimi/tests/test_repo_compare_reading.py b/dokimi/tests/test_repo_compare_reading.py
index d098aa3ea..aafcad6cb 100644
--- a/dokimi/tests/test_repo_compare_reading.py
+++ b/dokimi/tests/test_repo_compare_reading.py
@@ -179,7 +179,7 @@ def test_task_refuses_an_id_no_cell_has(tmp_path, capsys):
     args = build_parser().parse_args(["repo", "compare", str(b), "--baseline", "guidance:none", "--task", "t9"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1 and "no finished cell of the compared batches has --task t9" in capsys.readouterr().err
+    assert exc.value.code == 2 and "no finished cell of the compared batches has --task t9" in capsys.readouterr().err
 
 
 def test_min_detectable_effect_arithmetic():
diff --git a/dokimi/tests/test_repo_deep_input.py b/dokimi/tests/test_repo_deep_input.py
index 8ba8548dd..33a745c51 100644
--- a/dokimi/tests/test_repo_deep_input.py
+++ b/dokimi/tests/test_repo_deep_input.py
@@ -1,7 +1,7 @@
 # Copyright (C) 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-"""`repo` commands exit 1 with a message on deeply nested or non-UTF-8 manifest, static and harness files."""
+"""`repo` commands exit 2 with a message on deeply nested or non-UTF-8 manifest, static and harness files."""
 
 from __future__ import annotations
 
@@ -20,10 +20,10 @@ def _run(*argv: str) -> None:
     args.func(args)
 
 
-def _exits_1_naming(capsys, path, *argv: str) -> None:
+def _exits_2_naming(capsys, path, *argv: str) -> None:
     with pytest.raises(SystemExit) as exc:
         _run(*argv)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(path) in capsys.readouterr().err
 
 
@@ -35,29 +35,29 @@ def repo(tmp_path):
 
 
 @pytest.mark.parametrize("command", [["scan"], ["validate"], ["reach", "--model", "m", "--dry-run"]])
-def test_a_deeply_nested_manifest_file_exits_1_naming_it(repo, tmp_path, capsys, command):
+def test_a_deeply_nested_manifest_file_exits_2_naming_it(repo, tmp_path, capsys, command):
     manifest = tmp_path / "deep.yaml"
     manifest.write_text(DEEP, encoding="utf-8")
-    _exits_1_naming(capsys, manifest, command[0], str(repo), "--manifest-file", str(manifest), *command[1:])
+    _exits_2_naming(capsys, manifest, command[0], str(repo), "--manifest-file", str(manifest), *command[1:])
 
 
-def test_a_deeply_nested_static_file_exits_1(repo, tmp_path, capsys):
+def test_a_deeply_nested_static_file_exits_2(repo, tmp_path, capsys):
     static = tmp_path / "static.json"
     static.write_text(DEEP, encoding="utf-8")
     manifest = tmp_path / "m.yaml"
     manifest.write_text("schema: repo_manifest.v1\nid: toy\nguidance:\n  globs: ['AGENTS.md']\n", encoding="utf-8")
     with pytest.raises(SystemExit) as exc:
         _run("scan", str(repo), "--manifest-file", str(manifest), "--static", str(static))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("✗ ") and str(static) in err
 
 
 @pytest.mark.parametrize("command", [["budget"], ["reach", "--model", "m", "--dry-run"]])
-def test_a_deeply_nested_harness_file_exits_1_naming_it(repo, tmp_path, capsys, command):
+def test_a_deeply_nested_harness_file_exits_2_naming_it(repo, tmp_path, capsys, command):
     profile = tmp_path / "profile.yaml"
     profile.write_text(DEEP, encoding="utf-8")
-    _exits_1_naming(capsys, profile, command[0], str(repo), "--harness", str(profile), *command[1:])
+    _exits_2_naming(capsys, profile, command[0], str(repo), "--harness", str(profile), *command[1:])
 
 
 def test_load_profile_reports_a_deeply_nested_file(tmp_path):
@@ -76,9 +76,9 @@ def test_load_manifest_reports_a_repo_manifest_it_cannot_read(repo, content):
 
 
 @pytest.mark.parametrize("command", [["validate"], ["reach", "--model", "m", "--dry-run"]])
-def test_a_non_utf8_repo_manifest_exits_1(repo, capsys, command):
+def test_a_non_utf8_repo_manifest_exits_2(repo, capsys, command):
     (repo / ".agent-eval" / "repo-eval.yaml").write_bytes(b"\xff\xfe\x00bad")
-    _exits_1_naming(capsys, "repo-eval.yaml", command[0], str(repo), *command[1:])
+    _exits_2_naming(capsys, "repo-eval.yaml", command[0], str(repo), *command[1:])
 
 
 def test_load_manifest_reports_a_repo_manifest_it_has_no_permission_to_read(repo, monkeypatch):
diff --git a/dokimi/tests/test_repo_harness_profile_unreadable.py b/dokimi/tests/test_repo_harness_profile_unreadable.py
index ab2ebe2ac..fb05a038c 100644
--- a/dokimi/tests/test_repo_harness_profile_unreadable.py
+++ b/dokimi/tests/test_repo_harness_profile_unreadable.py
@@ -1,7 +1,7 @@
 # Copyright (C) 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-"""`repo budget` and `repo reach` exit 1 with a message on a --harness file that cannot be read."""
+"""`repo budget` and `repo reach` exit 2 with a message on a --harness file that cannot be read."""
 
 from __future__ import annotations
 
@@ -49,18 +49,18 @@ def deny(self, *args, **kwargs):
 
 
 @pytest.mark.parametrize("kind", ["non-utf8", "unreadable"])
-def test_repo_budget_exits_1_on_a_harness_file_it_cannot_read(tmp_path, capsys, kind):
+def test_repo_budget_exits_2_on_a_harness_file_it_cannot_read(tmp_path, capsys, kind):
     path = _bad_profile(tmp_path, kind)
     with pytest.raises(SystemExit) as exc:
         _run("budget", str(tmp_path), "--harness", str(path))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(path) in capsys.readouterr().err
 
 
 @pytest.mark.parametrize("kind", ["non-utf8", "unreadable"])
-def test_repo_reach_exits_1_on_a_harness_file_it_cannot_read(tmp_path, capsys, kind):
+def test_repo_reach_exits_2_on_a_harness_file_it_cannot_read(tmp_path, capsys, kind):
     path = _bad_profile(tmp_path, kind)
     with pytest.raises(SystemExit) as exc:
         _run("reach", str(tmp_path), "--model", "m", "--harness", str(path), "--dry-run")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(path) in capsys.readouterr().err
diff --git a/dokimi/tests/test_repo_inspect_cli.py b/dokimi/tests/test_repo_inspect_cli.py
index 65cfd325c..8d47b6728 100644
--- a/dokimi/tests/test_repo_inspect_cli.py
+++ b/dokimi/tests/test_repo_inspect_cli.py
@@ -41,7 +41,7 @@ def test_cli_json_prints_the_stamped_payload(tmp_path, capsys):
 
 @pytest.mark.outcome("cjm-repo-inspect")
 @pytest.mark.parametrize("case", ["missing source", "unwritable out"])
-def test_cli_exits_1_when_it_cannot_read_or_write(tmp_path, capsys, case):
+def test_cli_exits_2_when_it_cannot_read_or_write(tmp_path, capsys, case):
     _repo(tmp_path / "toy", {"AGENTS.md": "x"})
     (tmp_path / "file").write_text("x")
     argv = ["repo", "inspect", str(tmp_path / "toy"), "--out", str(tmp_path / "file" / "env.json")]
@@ -50,5 +50,5 @@ def test_cli_exits_1_when_it_cannot_read_or_write(tmp_path, capsys, case):
     args = build_parser().parse_args(argv)
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "✗" in capsys.readouterr().err
diff --git a/dokimi/tests/test_repo_l0_cases.py b/dokimi/tests/test_repo_l0_cases.py
index ad2fe1bf3..698c3ff6e 100644
--- a/dokimi/tests/test_repo_l0_cases.py
+++ b/dokimi/tests/test_repo_l0_cases.py
@@ -713,12 +713,12 @@ def test_cli_exit_codes(tmp_path, capsys):
     assert _cli(tmp_path, empty, "--fail-on-fail") == 1
 
 
-def test_scan_exits_1_with_a_message_on_a_file_that_is_not_utf8(tmp_path, capsys):
+def test_scan_exits_2_with_a_message_on_a_file_that_is_not_utf8(tmp_path, capsys):
     root = tmp_path / "r"
     _git_repo(root, {"AGENTS.md": "`src/a.h`\n", "src/a.h": "", "ev/tasks/t/task.json": "{}"})
     binary = tmp_path / "static.json"
     binary.write_bytes(b'{"schema": "\xff\xfe"}')
-    assert _cli(tmp_path, root, "--static", str(binary)) == 1
+    assert _cli(tmp_path, root, "--static", str(binary)) == 2
     err = capsys.readouterr().err
     assert err.startswith("✗ ") and "utf-8" in err
 
@@ -727,7 +727,7 @@ def test_scan_exits_1_with_a_message_on_a_file_that_is_not_utf8(tmp_path, capsys
     args = build_parser().parse_args(["repo", "scan", str(root), "--manifest-file", str(manifest)])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("✗ ") and str(manifest) in err
 
diff --git a/dokimi/tests/test_repo_manifest.py b/dokimi/tests/test_repo_manifest.py
index 928684680..93ccde3a4 100644
--- a/dokimi/tests/test_repo_manifest.py
+++ b/dokimi/tests/test_repo_manifest.py
@@ -464,7 +464,7 @@ def test_repo_validate_out_writes_the_report(tmp_path, capsys):
 
     with pytest.raises(SystemExit) as exc:
         _run_cli([*argv[:-1], str(tmp_path / "no" / "dir" / "v.json")])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "cannot write" in capsys.readouterr().err
 
 
@@ -646,7 +646,7 @@ def test_a_mistyped_manifest_path_is_an_error_not_a_default_scan(tmp_path, capsy
     args = build_parser().parse_args(["repo", "scan", str(root), "--manifest", ".agent-eval/repo-evel.yaml"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "manifest not found" in capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_repo_reach.py b/dokimi/tests/test_repo_reach.py
index bea0759fa..a046375d9 100644
--- a/dokimi/tests/test_repo_reach.py
+++ b/dokimi/tests/test_repo_reach.py
@@ -702,7 +702,7 @@ def test_repo_reach_cli_manifest_file_and_a_failed_scenario(tmp_path, monkeypatc
     args = build_parser().parse_args([*base, "--manifest-file", str(tmp_path / "nope.yaml"), "--dry-run"])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1 and "nope.yaml" in capsys.readouterr().err
+    assert exc.value.code == 2 and "nope.yaml" in capsys.readouterr().err
 
     monkeypatch.setenv("FAKE_MODE", "crash")
     (tmp_path / "work").mkdir()
@@ -759,7 +759,7 @@ def test_repo_reach_rejects_selections_that_would_drop_scenarios(tmp_path, capsy
                                       "--model", "m", "--dry-run", *extra])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert message in capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_repo_report_hits.py b/dokimi/tests/test_repo_report_hits.py
index 50acc93ef..2dd2474b6 100644
--- a/dokimi/tests/test_repo_report_hits.py
+++ b/dokimi/tests/test_repo_report_hits.py
@@ -167,7 +167,7 @@ def test_hits_refuse_a_cell_with_no_rep_as_the_table_refuses_a_malformed_cell(tm
     path.write_text(json.dumps(rec))
     with pytest.raises(SystemExit) as stopped:
         _cli(capsys, str(batch), "--hits")
-    assert stopped.value.code == 1
+    assert stopped.value.code == 2  # an input refusal exits 2 (the exit-code audit)
     assert capsys.readouterr().err.strip() == f"✗ {path} has no usable `rep`"
 
 
diff --git a/dokimi/tests/test_repo_report_unreadable_cell.py b/dokimi/tests/test_repo_report_unreadable_cell.py
index 1cc58aab9..d67264347 100644
--- a/dokimi/tests/test_repo_report_unreadable_cell.py
+++ b/dokimi/tests/test_repo_report_unreadable_cell.py
@@ -1,7 +1,7 @@
 # Copyright (C) 2026 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-"""`repo report` and `repo compare` exit 1 with a message, not a traceback, on a corrupt cell file."""
+"""`repo report` and `repo compare` exit 2 with a message, not a traceback, on a corrupt cell file."""
 
 from __future__ import annotations
 
@@ -40,39 +40,39 @@ def _no_constant(name: str) -> None:
 
 
 @pytest.mark.parametrize("content", _CORRUPT)
-def test_report_exits_1_naming_a_corrupt_result_file(tmp_path, capsys, content):
+def test_report_exits_2_naming_a_corrupt_result_file(tmp_path, capsys, content):
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": content})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert str(batch / "t__a__m__r1" / "result.json") in err
     assert "Traceback" not in err
 
 
 @pytest.mark.parametrize("content", _CORRUPT)
-def test_compare_exits_1_naming_a_corrupt_result_file(tmp_path, capsys, content):
+def test_compare_exits_2_naming_a_corrupt_result_file(tmp_path, capsys, content):
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": content})
     with pytest.raises(SystemExit) as exc:
         _run("compare", str(batch), "--baseline", "a")
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(batch / "t__a__m__r1" / "result.json") in capsys.readouterr().err
 
 
-def test_report_exits_1_naming_a_corrupt_unsupported_file(tmp_path, capsys):
+def test_report_exits_2_naming_a_corrupt_unsupported_file(tmp_path, capsys):
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/unsupported.json": b"{not json"})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(batch / "t__a__m__r1" / "unsupported.json") in capsys.readouterr().err
 
 
 @pytest.mark.parametrize("content", [b"{not json", b"{}", b'{"cells": 3}', b'{"cells": [1]}'])
-def test_report_exits_1_naming_a_corrupt_plan_file(tmp_path, capsys, content):
+def test_report_exits_2_naming_a_corrupt_plan_file(tmp_path, capsys, content):
     batch = _batch(tmp_path, "b1", {"_eval/plan.json": content})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert str(batch / "_eval" / "plan.json") in capsys.readouterr().err
 
 
@@ -93,11 +93,11 @@ def test_report_still_reads_an_empty_batch(tmp_path, capsys):
 
 @pytest.mark.parametrize("content", _NO_GRADE)
 @pytest.mark.parametrize("argv", [("report",), ("compare", "--baseline", "a")], ids=["report", "compare"])
-def test_a_result_file_without_a_usable_grade_exits_1(tmp_path, capsys, argv, content):
+def test_a_result_file_without_a_usable_grade_exits_2(tmp_path, capsys, argv, content):
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": content})
     with pytest.raises(SystemExit) as exc:
         _run(argv[0], str(batch), *argv[1:])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"{batch / 't__a__m__r1' / 'result.json'} has no usable `grade`" in err
     assert "Traceback" not in err
@@ -148,14 +148,14 @@ def test_a_result_file_without_a_usable_grade_exits_1(tmp_path, capsys, argv, co
 
 @pytest.mark.parametrize("key, value", _BAD_FIELDS)
 @pytest.mark.parametrize("argv", [("report",), ("compare", "--baseline", "a")], ids=["report", "compare"])
-def test_a_result_file_without_usable_agent_task_arm_or_model_exits_1(tmp_path, capsys, argv, key, value):
+def test_a_result_file_without_usable_agent_task_arm_or_model_exits_2(tmp_path, capsys, argv, key, value):
     rec = {k: v for k, v in _GOOD.items() if k != key}
     if value is not None:
         rec[key] = value
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": json.dumps(rec).encode()})
     with pytest.raises(SystemExit) as exc:
         _run(argv[0], str(batch), *argv[1:])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"{batch / 't__a__m__r1' / 'result.json'} has no usable `{key}`" in err
     assert "Traceback" not in err
@@ -212,7 +212,7 @@ def test_deltas_that_would_overflow_when_squared_are_rejected_with_a_message(tmp
     batch = _three_task_batch(tmp_path, cost, -cost)
     with pytest.raises(SystemExit) as exc:
         _run(cmd[0], str(batch), *cmd[1:])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "has no usable `agent`" in capsys.readouterr().err
 
 
@@ -231,62 +231,62 @@ def test_a_result_file_with_a_score_task_and_no_score_only_is_accepted(tmp_path,
     assert json.loads(capsys.readouterr().out)["rows"][0]["cost_unknown"] == 1
 
 
-def test_a_deeply_nested_result_file_exits_1_naming_the_file(tmp_path, capsys):
+def test_a_deeply_nested_result_file_exits_2_naming_the_file(tmp_path, capsys):
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": b"[" * 100000})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert str(batch / "t__a__m__r1" / "result.json") in err and "Traceback" not in err
 
 
-def test_an_unreadable_result_file_exits_1_naming_the_file(tmp_path, capsys):
+def test_an_unreadable_result_file_exits_2_naming_the_file(tmp_path, capsys):
     batch = _batch(tmp_path, "b1", {})
     (batch / "t__a__m__r1" / "result.json").mkdir(parents=True)  # a directory where the file belongs
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert f"cannot read {batch / 't__a__m__r1' / 'result.json'}" in err and "Traceback" not in err
 
 
 @pytest.mark.parametrize("key", ["timed_out", "is_error", "over_budget", "cost_usd", "num_turns"])
-def test_a_result_file_missing_an_agent_key_exits_1(tmp_path, capsys, key):
+def test_a_result_file_missing_an_agent_key_exits_2(tmp_path, capsys, key):
     agent = {k: v for k, v in _GOOD["agent"].items() if k != key}
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": json.dumps({**_GOOD, "agent": agent}).encode()})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "has no usable `agent`" in capsys.readouterr().err
 
 
-def test_a_result_file_without_grade_status_exits_1(tmp_path, capsys):
+def test_a_result_file_without_grade_status_exits_2(tmp_path, capsys):
     grade = {k: v for k, v in _GOOD["grade"].items() if k != "status"}
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": json.dumps({**_GOOD, "grade": grade}).encode()})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "has no usable `grade`" in capsys.readouterr().err
 
 
 @pytest.mark.parametrize("cost", ["NaN", "Infinity", "-Infinity", "1e999", "9" * 400])
 @pytest.mark.parametrize("cmd", [("report",), ("compare", "--baseline", "a")], ids=["report", "compare"])
-def test_a_result_file_with_a_non_finite_cost_exits_1(tmp_path, capsys, cmd, cost):
+def test_a_result_file_with_a_non_finite_cost_exits_2(tmp_path, capsys, cmd, cost):
     text = json.dumps(_GOOD).replace("0.1", cost)
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": text.encode()})
     with pytest.raises(SystemExit) as exc:
         _run(cmd[0], str(batch), *cmd[1:])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert "has no usable `agent`" in err and "Traceback" not in err
 
 
-def test_a_score_task_result_file_without_grade_score_exits_1(tmp_path, capsys):
+def test_a_score_task_result_file_without_grade_score_exits_2(tmp_path, capsys):
     rec = {**_GOOD, "score_task": True, "grade": {"status": "ok", "success": True}}
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": json.dumps(rec).encode()})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "has no usable `grade`" in capsys.readouterr().err
 
 
@@ -298,21 +298,21 @@ def test_a_score_task_result_file_with_a_null_grade_score_is_accepted(tmp_path,
 
 
 @pytest.mark.parametrize("value", ["false", 0, None, []])
-def test_a_result_file_with_a_non_bool_score_task_exits_1(tmp_path, capsys, value):
+def test_a_result_file_with_a_non_bool_score_task_exits_2(tmp_path, capsys, value):
     rec = {**_GOOD, "score_task": value, "grade": {"status": "ok", "score": 1.0, "success": True}}
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": json.dumps(rec).encode()})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "has no usable `score_task`" in capsys.readouterr().err
 
 
-def test_a_score_task_result_file_without_grade_success_exits_1(tmp_path, capsys):
+def test_a_score_task_result_file_without_grade_success_exits_2(tmp_path, capsys):
     rec = {**_GOOD, "score_task": True, "grade": {"status": "ok", "score": 1.0}}
     batch = _batch(tmp_path, "b1", {"t__a__m__r1/result.json": json.dumps(rec).encode()})
     with pytest.raises(SystemExit) as exc:
         _run("report", str(batch))
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "has no usable `grade`" in capsys.readouterr().err
 
 
@@ -325,14 +325,14 @@ def _two_arm_batch(tmp_path, rec):
 
 
 @_CMDS
-def test_a_cell_shape_the_checks_miss_exits_1_naming_the_cell(tmp_path, capsys, monkeypatch, cmd):
+def test_a_cell_shape_the_checks_miss_exits_2_naming_the_cell(tmp_path, capsys, monkeypatch, cmd):
     from dokimi.repos import report
 
     monkeypatch.setattr(report, "_check_cell", lambda path, rec: None)
     batch = _two_arm_batch(tmp_path, {**_GOOD, "grade": "x"})
     with pytest.raises(SystemExit) as exc:
         _run(cmd[0], str(batch), *cmd[1:])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert "t__a__m__r1" in err and "result.json" in err and "unexpected shape" in err
 
@@ -340,7 +340,7 @@ def test_a_cell_shape_the_checks_miss_exits_1_naming_the_cell(tmp_path, capsys,
 @_CMDS
 @pytest.mark.parametrize("exc", [KeyError("k"), TypeError("t"), AttributeError("a"), OverflowError("o"), ValueError("v")],
                          ids=lambda e: type(e).__name__)
-def test_each_cell_shape_error_exits_1_naming_the_cell(tmp_path, capsys, monkeypatch, cmd, exc):
+def test_each_cell_shape_error_exits_2_naming_the_cell(tmp_path, capsys, monkeypatch, cmd, exc):
     from dokimi.repos import compare, report
 
     def boom(recs):
@@ -351,7 +351,7 @@ def boom(recs):
     batch = _two_arm_batch(tmp_path, _GOOD)
     with pytest.raises(SystemExit) as raised:
         _run(cmd[0], str(batch), *cmd[1:])
-    assert raised.value.code == 1
+    assert raised.value.code == 2
     err = capsys.readouterr().err
     assert "t__a__m__r1" in err and f"unexpected shape ({type(exc).__name__}" in err
 
@@ -426,3 +426,12 @@ def test_a_grade_metric_beyond_the_bound_is_left_out(tmp_path, capsys, huge):
     out = json.loads(capsys.readouterr().out, parse_constant=_no_constant)
     row = next(r for r in out["comparisons"] if r["measure"] == "metric:m1")
     assert [t["task"] for t in row["tasks"]] == ["t2"]
+
+
+def test_compare_with_a_baseline_no_cell_matches_exits_2_naming_it(tmp_path, capsys):
+    # An unusable --baseline is an input refusal (exit 2), not a failed gate (exit 1).
+    batch = _two_arm_batch(tmp_path, _GOOD)
+    with pytest.raises(SystemExit) as exc:
+        _run("compare", str(batch), "--baseline", "nosucharm")
+    assert exc.value.code == 2
+    assert "no finished cell matches the baseline 'nosucharm'" in capsys.readouterr().err
diff --git a/dokimi/tests/test_report_cli_inputs.py b/dokimi/tests/test_report_cli_inputs.py
index 21309b6ed..1f4918964 100644
--- a/dokimi/tests/test_report_cli_inputs.py
+++ b/dokimi/tests/test_report_cli_inputs.py
@@ -26,10 +26,10 @@ def _generate(tmp_path, eval_path, fmt="markdown"):
     args.func(args)
 
 
-def _err(tmp_path, eval_path, capsys, fmt="markdown"):
+def _err(tmp_path, eval_path, capsys, fmt="markdown", code=2):
     with pytest.raises(SystemExit) as exc:
         _generate(tmp_path, eval_path, fmt)
-    assert exc.value.code == 1
+    assert exc.value.code == code
     return capsys.readouterr().err
 
 
@@ -63,7 +63,7 @@ def test_eval_json_that_is_not_an_object_is_rejected(tmp_path, capsys, text):
 
 
 @pytest.mark.parametrize("target", ["is_a_directory", "parent_is_a_file"])
-def test_an_unwritable_output_exits_1_naming_the_path(tmp_path, capsys, monkeypatch, target):
+def test_an_unwritable_output_exits_2_naming_the_path(tmp_path, capsys, monkeypatch, target):
     monkeypatch.setattr("dokimi.report.ReportGenerator.generate_report", lambda self, **kw: "report")
     ev = tmp_path / "ev.json"
     ev.write_text(ONE_EVALUATION, encoding="utf-8")
@@ -81,12 +81,12 @@ def test_an_unwritable_output_exits_1_naming_the_path(tmp_path, capsys, monkeypa
     ])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write {out}" in capsys.readouterr().err
 
 
 @pytest.mark.parametrize("evaluations", ["null", "5"])
-def test_non_list_evaluations_exit_1_with_its_path(tmp_path, capsys, evaluations):
+def test_non_list_evaluations_exit_2_with_its_path(tmp_path, capsys, evaluations):
     bad = tmp_path / "evd.json"
     bad.write_text(f'{{"evaluations": {evaluations}}}', encoding="utf-8")
     assert f"{bad} evaluations: expected a list of records" in _err(tmp_path, bad, capsys)
@@ -97,7 +97,7 @@ def test_non_list_evaluations_exit_1_with_its_path(tmp_path, capsys, evaluations
 def test_an_eval_with_no_evaluations_exits_1_and_writes_no_report(tmp_path, capsys, text, fmt):
     empty = tmp_path / "empty.json"
     empty.write_text(text, encoding="utf-8")
-    err = _err(tmp_path, empty, capsys, fmt)
+    err = _err(tmp_path, empty, capsys, fmt, code=1)  # a run that judged nothing failed: a verdict, not a bad flag
     assert err == f"Error: --eval {empty} holds no evaluations\n"
     assert not (tmp_path / "r.md").exists()
 
@@ -121,7 +121,7 @@ def test_the_failure_analysis_shows_n_a_rates_for_zero_evaluations():
 
 
 @pytest.mark.parametrize("kind", ["missing", "directory"])
-def test_generate_unreadable_questions_exits_1_naming_the_path(tmp_path, capsys, kind):
+def test_generate_unreadable_questions_exits_2_naming_the_path(tmp_path, capsys, kind):
     ev = tmp_path / "ev.json"
     ev.write_text(ONE_EVALUATION, encoding="utf-8")
     qs = tmp_path / "nope.json"
@@ -133,13 +133,13 @@ def test_generate_unreadable_questions_exits_1_naming_the_path(tmp_path, capsys,
     ])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot read ") and str(qs) in err
     assert "Traceback" not in err
 
 
-def test_report_eval_unwritable_out_exits_1_naming_the_path(tmp_path, capsys):
+def test_report_eval_unwritable_out_exits_2_naming_the_path(tmp_path, capsys):
     ev = tmp_path / "ev.json"
     ev.write_text('{"evaluations": []}', encoding="utf-8")
     blocker = tmp_path / "blocker"
@@ -150,12 +150,12 @@ def test_report_eval_unwritable_out_exits_1_naming_the_path(tmp_path, capsys):
     ])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
 
 
-def test_model_compare_unwritable_out_exits_1_naming_the_path(tmp_path, capsys):
+def test_model_compare_unwritable_out_exits_2_naming_the_path(tmp_path, capsys):
     run = tmp_path / "run.json"
     run.write_text(json.dumps({"baseline_arm": "baseline", "evaluations": [
         {"question_id": f"q{i}", "question_text": "q", "category": "", "difficulty": "easy",
@@ -170,6 +170,6 @@ def test_model_compare_unwritable_out_exits_1_naming_the_path(tmp_path, capsys):
     ])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot write ") and str(out) in err
diff --git a/dokimi/tests/test_report_eval_input_errors.py b/dokimi/tests/test_report_eval_input_errors.py
index 0368742a8..95865cb7b 100644
--- a/dokimi/tests/test_report_eval_input_errors.py
+++ b/dokimi/tests/test_report_eval_input_errors.py
@@ -19,7 +19,7 @@
     (json.dumps({"evaluations": {}}).encode(), "`evaluations` list"),
 ], ids=["missing", "malformed", "not-utf8", "not-an-object", "no-evaluations",
         "evaluations-not-a-list"])
-def test_report_eval_exits_1_with_a_message_on_an_unreadable_eval_file(tmp_path, monkeypatch, capsys,
+def test_report_eval_exits_2_with_a_message_on_an_unreadable_eval_file(tmp_path, monkeypatch, capsys,
                                                                        content, reason):
     from dokimi import cli
 
@@ -30,13 +30,13 @@ def test_report_eval_exits_1_with_a_message_on_an_unreadable_eval_file(tmp_path,
                                      "--out", str(out)])
     with pytest.raises(SystemExit) as exc:
         cli.main()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: ") and str(eval_file) in err and reason in err
     assert not out.exists()
 
 
-def test_report_eval_exits_1_with_a_message_when_the_eval_path_is_a_directory(tmp_path, monkeypatch, capsys):
+def test_report_eval_exits_2_with_a_message_when_the_eval_path_is_a_directory(tmp_path, monkeypatch, capsys):
     from dokimi import cli
 
     out = tmp_path / "r.md"
@@ -44,7 +44,7 @@ def test_report_eval_exits_1_with_a_message_when_the_eval_path_is_a_directory(tm
                                      "--out", str(out)])
     with pytest.raises(SystemExit) as exc:
         cli.main()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     err = capsys.readouterr().err
     assert err.startswith("Error: cannot read ") and str(tmp_path) in err
     assert not out.exists()
diff --git a/dokimi/tests/test_run_compare_errors.py b/dokimi/tests/test_run_compare_errors.py
index a09b1f314..d9b8f4336 100644
--- a/dokimi/tests/test_run_compare_errors.py
+++ b/dokimi/tests/test_run_compare_errors.py
@@ -187,20 +187,20 @@ def _blocked(tmp_path):
 
 
 @pytest.mark.parametrize("which", ["json", "md"])
-def test_compare_exits_1_when_an_output_cannot_be_written(tmp_path, monkeypatch, capsys, which):
+def test_compare_exits_2_when_an_output_cannot_be_written(tmp_path, monkeypatch, capsys, which):
     good = _snapshot(tmp_path / "good.json")
     blocked = _blocked(tmp_path) / "out"
     outs = {"json": str(tmp_path / "c.json"), "md": str(tmp_path / "c.md")}
     outs[which] = str(blocked)
     code = _main(monkeypatch, "compare", "--base", good, "--candidate", good,
                  "--out-json", outs["json"], "--out-md", outs["md"])
-    assert code == 1
+    assert code == 2
     err = capsys.readouterr().err
     assert f"Error: cannot write {blocked}" in err and "Traceback" not in err
 
 
 @pytest.mark.parametrize("which", ["json", "md"])
-def test_run_exits_1_when_an_output_cannot_be_written(tmp_path, monkeypatch, capsys, which):
+def test_run_exits_2_when_an_output_cannot_be_written(tmp_path, monkeypatch, capsys, which):
     (tmp_path / "docs").mkdir()
     (tmp_path / "docs" / "a.md").write_text("# A\n\ntext\n", encoding="utf-8")
     spec = tmp_path / "spec.yaml"
@@ -210,6 +210,6 @@ def test_run_exits_1_when_an_output_cannot_be_written(tmp_path, monkeypatch, cap
     outs[which] = str(blocked)
     code = _main(monkeypatch, "run", "--root", str(tmp_path), "--spec", str(spec),
                  "--out-json", outs["json"], "--out-md", outs["md"])
-    assert code == 1
+    assert code == 2
     err = capsys.readouterr().err
     assert f"Error: cannot write {blocked}" in err and "Traceback" not in err
diff --git a/dokimi/tests/test_runner_run.py b/dokimi/tests/test_runner_run.py
index 764c42768..126b5a783 100644
--- a/dokimi/tests/test_runner_run.py
+++ b/dokimi/tests/test_runner_run.py
@@ -133,7 +133,7 @@ def test_a_found_doc_that_did_not_load_is_a_clean_error(tmp_path):
             run_benchmark(tmp_path, _spec(tmp_path))
 
 
-def test_run_command_exits_1_without_a_traceback_when_a_doc_does_not_load(tmp_path, capsys):
+def test_run_command_exits_2_without_a_traceback_when_a_doc_does_not_load(tmp_path, capsys):
     from dokimi.cli import build_parser
 
     found = [tmp_path / "docs/a.md"]
@@ -143,6 +143,6 @@ def test_run_command_exits_1_without_a_traceback_when_a_doc_does_not_load(tmp_pa
          patch("dokimi.runner.run.load_docs", return_value={}):
         with pytest.raises(SystemExit) as exc:
             args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "1 of 1 selected document(s) did not load" in capsys.readouterr().err
     assert not (tmp_path / "o.json").exists()  # no snapshot over the docs that did load
diff --git a/dokimi/tests/test_session_runner.py b/dokimi/tests/test_session_runner.py
index b30b2332d..a72d01f01 100644
--- a/dokimi/tests/test_session_runner.py
+++ b/dokimi/tests/test_session_runner.py
@@ -513,3 +513,39 @@ def test_a_session_artifact_is_refused_by_every_judge_command(cmd, fake_llm, tmp
         cli.main()
     assert exc.value.code == 2 and "measurement-only" in capsys.readouterr().err
     assert len(fake_llm.requests) == 4  # the answers only: no judge call
+
+
+# A session question that cannot run is a refused input (exit 2), so it is refused in setup,
+# before any sampling probe, client or answer: the same for `arms run` and `arms matrix-run`.
+@pytest.mark.parametrize("bad", [
+    {"id": "q9", "question": "Q?"},
+    {"id": "q9", "question": "Q?", "follow_ups": "Why?"},
+    {"id": "q9", "question": "Q?", "follow_ups": ["ok", "   "]},
+])
+def test_prepare_arms_refuses_a_session_question_that_cannot_run(fake_llm, monkeypatch, bad):
+    import dokimi.eval.arms_run as arms_run
+
+    monkeypatch.setattr(arms_run, "check_sampling_support", lambda config: None)
+    config = arms_run.ArmsRunConfig(product="oneTBB", session_turns=2)
+
+    with pytest.raises(ValueError, match="q9"):
+        arms_run.prepare_arms(config, ["baseline"], [SESSION_Q, bad])
+    assert fake_llm.requests == []
+
+
+def test_arms_run_exits_2_on_a_session_question_without_follow_ups(fake_llm, monkeypatch, tmp_path):
+    import json
+
+    import dokimi.eval.arms_run as arms_run
+    from dokimi.cli import build_parser
+
+    monkeypatch.setattr(arms_run, "check_sampling_support", lambda config: None)
+    questions = tmp_path / "questions.json"
+    questions.write_text(json.dumps({"questions": [{"id": "q1", "question": "How?"}]}), encoding="utf-8")
+    args = build_parser().parse_args(["arms", "run", "--product", "oneTBB", "--questions", str(questions),
+                                      "--arms", "baseline", "--session-turns", "2"])
+
+    with pytest.raises(SystemExit) as exc:
+        args.func(args)
+    assert exc.value.code == 2
+    assert fake_llm.requests == []
diff --git a/dokimi/tests/test_skill_loader.py b/dokimi/tests/test_skill_loader.py
index 339e80338..60668911e 100644
--- a/dokimi/tests/test_skill_loader.py
+++ b/dokimi/tests/test_skill_loader.py
@@ -311,7 +311,7 @@ def test_discovery_ignores_a_dangling_skill_md_symlink(tmp_path):
     assert [s.name for s in discover_skills(root)] == ["linux-perf"]
 
 
-def test_arms_run_exits_1_with_a_message_when_skill_md_is_a_directory(tmp_path, monkeypatch, capsys):
+def test_arms_run_exits_2_with_a_message_when_skill_md_is_a_directory(tmp_path, monkeypatch, capsys):
     from dokimi import cli
 
     skill = tmp_path / "perf"
@@ -322,7 +322,7 @@ def test_arms_run_exits_1_with_a_message_when_skill_md_is_a_directory(tmp_path,
                                      "--arms", f"skill:{skill}", "--out-json", str(tmp_path / "out.json")])
     with pytest.raises(SystemExit) as exc:
         cli.main()
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert "No SKILL.md found" in capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_skill_selection.py b/dokimi/tests/test_skill_selection.py
index c6fdbc98a..622468da2 100644
--- a/dokimi/tests/test_skill_selection.py
+++ b/dokimi/tests/test_skill_selection.py
@@ -249,9 +249,10 @@ def test_trigger_set_cli_rejects_a_label_path_that_never_resolves(tmp_path, cata
     qfile.write_text(json.dumps({"questions": [
         {"id": "1", "text": "perf shows low IPC", "metadata": {"skill_under_test": "linux-perf"}},
     ]}), encoding="utf-8")
-    with pytest.raises(SystemExit, match="resolves for none of 1 questions"):
+    with pytest.raises(SystemExit, match="resolves for none of 1 questions") as exc:
         _run_cli(["catalog", "trigger-set", "--catalog", str(catalog),
                   "--questions", f"{qfile}=@metadata.skil_under_test", "--out", str(tmp_path / "o.json")])
+    assert exc.value.code == 2  # a path typo is an input refusal (docs/quickstart.md)
 
 
 @pytest.mark.parametrize(
@@ -459,7 +460,7 @@ def test_trigger_set_cli_checks_each_source_and_inputs(tmp_path, catalog, capsys
     named = _qfile(tmp_path, "named.json", [{"id": "3", "text": "use linux-perf here"}])
     with pytest.raises(SystemExit) as exc:
         _run_cli(base + ["--strict", "--questions", f"{named}=linux-perf"])
-    assert exc.value.code == 1 and not out.exists()
+    assert exc.value.code == 1 and not out.exists()  # --strict is a lint gate: 1, as on main
 
 
 def test_trigger_set_cli_writes_each_format(tmp_path, catalog, capsys):
@@ -485,7 +486,7 @@ def test_trigger_set_cli_exits_with_a_message_when_out_cannot_be_written(tmp_pat
     with pytest.raises(SystemExit, match=rf"Error: cannot write --out {re.escape(str(out))}: ") as exc:
         _run_cli(["catalog", "trigger-set", "--catalog", str(catalog), "--out", str(out),
                   "--questions", f"{q}=@skills", "--format", fmt, "--target", "linux-perf"])
-    assert exc.value.code != 0 and isinstance(exc.value.code, str)
+    assert exc.value.code == 2
     assert list(out.iterdir()) == []
 
 
@@ -501,7 +502,7 @@ def reject(*_a, **_k):
     with pytest.raises(SystemExit, match=r"Error: questions set rejected: record 1: bad shape") as exc:
         _run_cli(["catalog", "trigger-set", "--catalog", str(catalog), "--out", str(tmp_path / "o.json"),
                   "--questions", f"{q}=@skills", "--format", "questions"])
-    assert "cannot write" not in exc.value.code
+    assert "cannot write" not in str(exc.value)
 
 
 @pytest.mark.parametrize("fmt", ["reach", "skill-creator", "questions"])
@@ -510,7 +511,7 @@ def test_trigger_set_cli_exits_with_a_message_when_out_is_empty(tmp_path, catalo
     with pytest.raises(SystemExit, match=r"Error: cannot write --out : ") as exc:
         _run_cli(["catalog", "trigger-set", "--catalog", str(catalog), "--out", "",
                   "--questions", f"{q}=@skills", "--format", fmt, "--target", "linux-perf"])
-    assert isinstance(exc.value.code, str)
+    assert exc.value.code == 2
 
 
 # ── review round 3 ───────────────────────────────────────────────────────
@@ -681,7 +682,7 @@ def test_trigger_set_cli_strict_rejects_unresolved_labels(tmp_path, catalog, cap
     out.unlink()
     with pytest.raises(SystemExit) as exc:
         _run_cli(_ts(catalog, out, "--strict", "--questions", f"{q}=@metadata.s"))
-    assert exc.value.code == 1 and not out.exists()
+    assert exc.value.code == 1 and not out.exists()  # --strict is a lint gate: 1, as on main
 
 
 def test_trigger_set_cli_rejects_questions_without_text(tmp_path, catalog):
diff --git a/dokimi/tests/test_subjects.py b/dokimi/tests/test_subjects.py
index 8e31f6992..e7f51624f 100644
--- a/dokimi/tests/test_subjects.py
+++ b/dokimi/tests/test_subjects.py
@@ -871,7 +871,7 @@ def fail_if_called(config, **kw):
     with pytest.raises(SystemExit) as excinfo:
         args.func(args)
 
-    assert excinfo.value.code == 1
+    assert excinfo.value.code == 2
     assert "Error loading subject work: Task directory not found" in capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_subjects_run_input.py b/dokimi/tests/test_subjects_run_input.py
index f252eb901..3efb70bbe 100644
--- a/dokimi/tests/test_subjects_run_input.py
+++ b/dokimi/tests/test_subjects_run_input.py
@@ -34,7 +34,7 @@ def _run(tmp_path: Path, monkeypatch, *, subject_id: str, products: str, questio
     args = build_parser().parse_args(["subjects", "run", str(descriptor), *extra_args])
     with pytest.raises(SystemExit) as exc:
         args.func(args)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
 @pytest.mark.parametrize(
@@ -45,7 +45,7 @@ def _run(tmp_path: Path, monkeypatch, *, subject_id: str, products: str, questio
         ("s", '["a", "b"]', '["q1.json", "q2.json", "q3.json"]', "suite.questions must contain either"),
     ],
 )
-def test_an_unrunnable_descriptor_exits_1_with_its_reason(
+def test_an_unrunnable_descriptor_exits_2_with_its_reason(
     tmp_path, monkeypatch, capsys, subject_id, products, questions, message
 ):
     _run(tmp_path, monkeypatch, subject_id=subject_id, products=products, questions=questions)
@@ -54,7 +54,7 @@ def test_an_unrunnable_descriptor_exits_1_with_its_reason(
     assert not (tmp_path / "results").exists()
 
 
-def test_an_unknown_baseline_spec_exits_1_with_its_reason(tmp_path, monkeypatch, capsys):
+def test_an_unknown_baseline_spec_exits_2_with_its_reason(tmp_path, monkeypatch, capsys):
     _run(tmp_path, monkeypatch, subject_id="s", products='["a"]', questions='["q.json"]', baseline="nosuchkind:x")
 
     first_line = capsys.readouterr().err.splitlines()[0]
@@ -62,7 +62,7 @@ def test_an_unknown_baseline_spec_exits_1_with_its_reason(tmp_path, monkeypatch,
     assert not (tmp_path / "results").exists()
 
 
-def test_a_baseline_named_like_an_awareness_arm_exits_1_with_its_reason(tmp_path, monkeypatch, capsys):
+def test_a_baseline_named_like_an_awareness_arm_exits_2_with_its_reason(tmp_path, monkeypatch, capsys):
     other = tmp_path / "other" / "docs"
     other.mkdir(parents=True)
     _run(tmp_path, monkeypatch, subject_id="s", products='["a"]', questions='["q.json"]',
@@ -72,7 +72,7 @@ def test_a_baseline_named_like_an_awareness_arm_exits_1_with_its_reason(tmp_path
     assert not (tmp_path / "results").exists()
 
 
-def test_an_out_dir_that_is_a_file_exits_1_naming_it(tmp_path, monkeypatch, capsys):
+def test_an_out_dir_that_is_a_file_exits_2_naming_it(tmp_path, monkeypatch, capsys):
     blocker = tmp_path / "out"
     blocker.write_text("x", encoding="utf-8")
     _run(tmp_path, monkeypatch, subject_id="s", products='["a"]', questions='["q.json"]',
@@ -83,7 +83,7 @@ def test_an_out_dir_that_is_a_file_exits_1_naming_it(tmp_path, monkeypatch, caps
     assert blocker.read_text(encoding="utf-8") == "x"
 
 
-def test_an_out_dir_under_a_file_exits_1_naming_it(tmp_path, monkeypatch, capsys):
+def test_an_out_dir_under_a_file_exits_2_naming_it(tmp_path, monkeypatch, capsys):
     blocker = tmp_path / "out"
     blocker.write_text("x", encoding="utf-8")
     target = blocker / "sub"
@@ -93,7 +93,7 @@ def test_an_out_dir_under_a_file_exits_1_naming_it(tmp_path, monkeypatch, capsys
     assert capsys.readouterr().err.splitlines()[0].startswith(f"Error: cannot write {target}: ")
 
 
-def test_an_unwritable_scorecard_exits_1_naming_it(tmp_path, monkeypatch, capsys):
+def test_an_unwritable_scorecard_exits_2_naming_it(tmp_path, monkeypatch, capsys):
     import dokimi.artifacts
     import dokimi.commands.arms
     import dokimi.subjects
@@ -126,7 +126,7 @@ def _stub_run(monkeypatch, saved):
     monkeypatch.setattr("dokimi.commands.subjects._run_subject_work", lambda *a, **k: {})
 
 
-def test_an_unwritable_report_dir_exits_1_after_the_scorecard_is_saved(tmp_path, monkeypatch, capsys):
+def test_an_unwritable_report_dir_exits_2_after_the_scorecard_is_saved(tmp_path, monkeypatch, capsys):
     saved: list = []
     _stub_run(monkeypatch, saved)
     blocker = tmp_path / "blocker"
@@ -140,7 +140,7 @@ def test_an_unwritable_report_dir_exits_1_after_the_scorecard_is_saved(tmp_path,
     assert capsys.readouterr().err.splitlines()[0].startswith(f"Error: cannot write {target}: ")
 
 
-def test_a_report_path_that_is_a_directory_exits_1_naming_it(tmp_path, monkeypatch, capsys):
+def test_a_report_path_that_is_a_directory_exits_2_naming_it(tmp_path, monkeypatch, capsys):
     saved: list = []
     _stub_run(monkeypatch, saved)
     target = tmp_path / "report.md"
@@ -179,10 +179,10 @@ def run(self):
                            work_command_template=None, work_dry_run=False, work_repeats=1)
     with pytest.raises(SystemExit) as exc:
         _run_subject_work(descriptor, args, out_dir=tmp_path / "out", tasks=[object()])
-    assert exc.value.code == 1
+    assert exc.value.code == 2
 
 
-def test_work_exits_1_when_the_task_runs_report_dir_cannot_be_created(tmp_path, monkeypatch, capsys):
+def test_work_exits_2_when_the_task_runs_report_dir_cannot_be_created(tmp_path, monkeypatch, capsys):
     blocker = tmp_path / "blocker"
     blocker.write_text("x", encoding="utf-8")
     saved: list = []
@@ -194,7 +194,7 @@ def test_work_exits_1_when_the_task_runs_report_dir_cannot_be_created(tmp_path,
     assert capsys.readouterr().err.splitlines()[0].startswith(f"Error: cannot write {expected}: ")
 
 
-def test_work_exits_1_when_the_task_runs_json_cannot_be_written(tmp_path, monkeypatch, capsys):
+def test_work_exits_2_when_the_task_runs_json_cannot_be_written(tmp_path, monkeypatch, capsys):
     blocker = tmp_path / "blocker"
     blocker.write_text("x", encoding="utf-8")
     target = blocker / "work" / "task-runs.json"
@@ -207,7 +207,7 @@ def save(kind, data, path):
     assert capsys.readouterr().err.splitlines()[0].startswith(f"Error: cannot write {target}: ")
 
 
-def test_work_exits_1_when_the_task_runs_report_path_is_a_directory(tmp_path, monkeypatch, capsys):
+def test_work_exits_2_when_the_task_runs_report_path_is_a_directory(tmp_path, monkeypatch, capsys):
     work_dir = tmp_path / "work"
     (work_dir / "task-runs.md").mkdir(parents=True)
 
diff --git a/dokimi/tests/test_tools_preference_items_out.py b/dokimi/tests/test_tools_preference_items_out.py
index 68d02e7c1..d24d406ee 100644
--- a/dokimi/tests/test_tools_preference_items_out.py
+++ b/dokimi/tests/test_tools_preference_items_out.py
@@ -21,20 +21,20 @@ def _preference(items_out: Path) -> None:
     args.func(args)
 
 
-def test_an_items_out_inside_a_regular_file_exits_1_naming_the_path(tmp_path, capsys):
+def test_an_items_out_inside_a_regular_file_exits_2_naming_the_path(tmp_path, capsys):
     blocker = tmp_path / "blocker"
     blocker.write_text("x", encoding="utf-8")
     target = blocker / "items.json"
     with pytest.raises(SystemExit) as exc:
         _preference(target)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write --items-out {target}" in capsys.readouterr().err
 
 
-def test_an_items_out_that_is_a_directory_exits_1_naming_the_path(tmp_path, capsys):
+def test_an_items_out_that_is_a_directory_exits_2_naming_the_path(tmp_path, capsys):
     with pytest.raises(SystemExit) as exc:
         _preference(tmp_path)
-    assert exc.value.code == 1
+    assert exc.value.code == 2
     assert f"Error: cannot write --items-out {tmp_path}" in capsys.readouterr().err
 
 
diff --git a/dokimi/tests/test_trigger_set_readers.py b/dokimi/tests/test_trigger_set_readers.py
index 53ab065d1..268bf9aee 100644
--- a/dokimi/tests/test_trigger_set_readers.py
+++ b/dokimi/tests/test_trigger_set_readers.py
@@ -196,3 +196,14 @@ def test_task_formats_name_the_reader_as_consumer(tmp_path, queries):
     for path in (reach, sc):
         report = detect(path)
         assert report.consumers == ["catalog trigger-set"], report
+
+
+def test_a_trigger_set_with_no_labels_is_valid_while_a_questions_typo_is_refused(catalog):
+    """A --trigger-set file has no labels to find, but its rule is still @expected_skill."""
+    unlabelled = [{"id": "u", "text": "save this array to disk"}]
+    qs = ts.build_trigger_set([(unlabelled, "@expected_skill")], discover_skills(catalog),
+                              specs=[None])
+    assert [q.labelled for q in qs] == [False]
+    with pytest.raises(ts.TriggerSetInputError, match="resolves for none"):
+        ts.build_trigger_set([(unlabelled, "@expected_skill")], discover_skills(catalog),
+                             specs=["typo.json=@expected_skill"])