feat(bench): publish an end-to-end token/cost number for a real /understand run

[t1mdurden]

What problem are you trying to solve?

There is no published end-to-end cost figure for a real /understand run, so a user cannot
predict what a run will spend before starting one.

The large-monorepo benchmark added in perf(bench): add reproducible large-monorepo benchmark and scale report is careful and honest about this. docs/benchmarks/large-monorepo.md says so
directly:

It does not run an LLM, call an API, count tokens, estimate cost, generate a knowledge graph,
or render the dashboard. Do not present these results as an end-to-end /understand benchmark.
estimatedAgentInputBytes is the size of the deterministic batch payload, not a token estimate.

That is the right disclaimer, and it leaves a real gap. The deterministic half of the pipeline
(scan, imports, batch planning, Tree-sitter extraction) is measured and reproducible. The half that
costs money — Phase 2 onward, one LLM pass per batch across the whole repository — has no published
number at any repository size.

The gap is visible in the issue tracker: token consumption problem, Heavy token usage,
question: Incremental update consumes more tokens than the initial build,
feat: add --caveman mode for reduced-token analysis, feat: --hybrid flag routes file-analyzer batches to local Gemma via Ollama, and several more. Every one of those is a discussion about cost
with no shared baseline to argue against. A --caveman mode that reduces tokens by an unknown
amount from an unknown starting point cannot be evaluated, and neither can a regression that makes
a phase more expensive.

Proposed solution (optional)

Extend the existing benchmark rather than build a second one. Concretely:

1. Add an opt-in --with-llm mode to benchmark:large-repo that runs the real /understand
   pipeline and records, per phase: input tokens, output tokens, cached tokens, wall clock, and
   number of agent invocations.
2. Add those fields to large-repo-report-1.0.0.schema.json as an optional llm object, so a
   deterministic-only report stays valid and the two kinds of report stay distinguishable.
3. Publish one reference run in the README next to the feature list: repository name, file count,
   line count, model, and total tokens for a full build and for an incremental update.

Point 3 is the one that matters to a user deciding whether to run this on a large repository.
Points 1 and 2 are what make point 3 reproducible and defensible.

Alternatives you've considered

• Reading token usage out of the host agent's own logs after a run. This works for one person on
  one machine and produces nothing comparable across users, models, or versions.
• Inferring cost from estimatedAgentInputBytes. The benchmark doc explicitly rules this out, and
  it would miss output tokens and the multi-agent fan-out entirely.
• Treating cost as the host agent's concern rather than the plugin's. That does not hold here: the
  plugin decides the batch plan, the number of agents, and how many phases run, so it owns the
  shape of the spend.

Which part of the project?

core / agents (benchmark harness and the /understand pipeline)

Anything else?

Happy to run the harness on a public repository and contribute the resulting report pair if the
--with-llm mode lands. I have no preference about which model is used for the reference run, only
that the number exists and is reproducible.