Cross-tool token-efficiency: naive baseline + tokens-at-fixed-recall metric

[Mathews-Tom]

Summary

Adds an offline, benchmark-only cross-tool token-efficiency comparison: how many tokens archex retrieval spends to localize a task's required files versus a naive grep/read agent, measured at a fixed required-file recall.

This is Stack B / Workstream M4 of the token-savings-metric-honesty plan. It produces a defensible "vs grep / full-file read" number without any in-process metric, reporter, retrieval, or default-path change.

What this adds

• archex/benchmark/cross_tool.py: the naive token model and the tokens-at-fixed-recall metric.
  • archex path: the targeted returned regions of archex_query, in rank order; cost to localize = region tokens consumed until the required files are covered.
  • naive path: grep the corpus for the task keywords (deterministic, in-process matching over archex's own gitignore-aware corpus), then read either whole grep-hit files (full_file) or +/-K context windows around the hits (grep_window), in grep-relevance order.
  • Both tokenized with the existing cl100k_base encoder. The naive model is a pure, deterministic function of the corpus snapshot, the keywords, and K.
• archex_returned_regions helper in benchmark/strategies.py exposing the bundle's ranked regions (same pipeline as run_archex_query).
• format_cross_tool_comparison reporter: per-corpus aggregate plus per-task tables.
• archex benchmark cross-tool subcommand to run the comparison and write the artifact.

Recall held equal

A token delta is reported only for tasks where both paths reach the target required-file recall (default 100%). Tasks where the naive grep path never reaches a required file are marked unreached and excluded from the aggregate, so the efficiency number never compares unequal recall. Localization is aggregated as its own corpus and never merged with comprehension.

Out of scope (unchanged)

• Not in DEFAULT_STRATEGIES; no product code path.
• No in-process metrics ledger, metrics reporter, retrieval ranking, or default change.

Stack

Stack-Id: cross-tool-efficiency-cfdfb5
Base: main
Position: 1/2

1. feat/cross-tool-token-model -> this PR
2. feat/cross-tool-artifact-docs -> per-corpus artifact + docs

Depends on: (none - root)

Validation

• uv run ruff check — pass (changed files)
• uv run ruff format --check — pass (changed files)
• uv run pyright — pass (changed files)
• uv run pytest tests/benchmark/test_cross_tool.py tests/benchmark/test_reporter.py tests/benchmark/test_runner.py --no-cov — 105 passed