GW-029: Add performance budgets, counters, and regression benchmarks

[trippyogi]

Outcome

Add explicit performance budgets, provider/request counters, and regression benchmarks for scan, hunt, check, replay, and store operations.

The project should be able to prove that agent scouting remains bounded and responsive as candidate pagination, richer evidence, persistence, and resume support are added.

Why this matters

Gitworthy's wall time is usually the sum of a bounded number of provider checks. Without measured budgets, later features can quietly multiply requests, clones, bytes, or serial latency and make MCP workflows too slow or expensive for daily agent use.

Scope

• Define versioned performance counters for elapsed time, GitHub requests, retries, pages, bytes downloaded/read, git subprocesses, clone/object-cache hits, npm entries/bytes, candidates considered, candidates preflighted, and persistence work.
• Add per-run and per-candidate budgets with typed exhaustion/partial statuses.
• Expose counters in structured results and verbose diagnostics without leaking secrets.
• Add deterministic offline microbenchmarks and representative frozen hunt/check benchmarks.
• Record baseline median/p95 values and allowed regression thresholds.
• Add CI regression checks for deterministic benchmarks while keeping noisy live measurements advisory.
• Cover cold-cache and warm-cache paths.
• Document budget defaults and how configuration overrides are validated.

Non-goals

• No vanity benchmark against unrelated tools.
• No hard release gate based on noisy public-network latency.
• No unbounded concurrency to improve headline wall time.
• No performance optimization that weakens evidence coverage or safety checks.

Dependencies and readiness

• Depends on GW-028 / issue GW-028: Add complete compact hunt decisions, partial persistence, and resume #37.
• Contributor readiness: BLOCKED until GW-028: Add complete compact hunt decisions, partial persistence, and resume #37 lands. Existing timings_ms and perf fields provide a starting point.

Acceptance criteria

• Primary runs expose documented counters and budget state.
• Request, page, byte, subprocess, candidate, and elapsed-time limits are enforced centrally.
• Budget exhaustion returns a structured partial/VERIFY result with preserved progress.
• Cold and warm cache behavior are measurable separately.
• Frozen benchmark fixtures exercise check and hunt without network variance.
• CI fails only on deterministic regressions beyond documented tolerances.
• Live benchmark output is advisory and clearly separated.
• Counter and budget fields have a versioned schema and CLI/MCP parity.
• No secrets, raw tokens, or sensitive URLs appear in verbose timing output.

Tests and validation

• Counter accuracy tests using injected providers.
• Every budget boundary and one-over-limit case.
• Partial persistence on budget exhaustion.
• Cold/warm cache benchmark fixtures.
• Retry and pagination accounting tests.
• Regression-threshold tests with known benchmark data.
• Cancellation interaction with counters and partial runs.

Suggested 0.7 performance goals

Establish measured baselines before fixing exact numbers, then target:

• Bounded default hunts with no more than the configured 3–5 full preflights.
• No unreported provider requests.
• No full repository checkout for evidence inspection.
• Warm-cache repeated checks materially faster and lower-request than cold runs.
• Partial results available on cancellation or provider budget exhaustion.

Likely implementation areas

• Shared RunBudget and counter types.
• HTTP, git, npm, scan, hunt, and store instrumentation.
• Frozen benchmark runner and CI job.
• Result schemas and verbose renderer.

Compatibility

Existing timing fields should remain or receive a documented migration. Budget defaults affect operational behavior and require release notes if tightened.

[trippyogi]

Shipped initial slice in #75 (RunBudget counters, frozen bench in CI). Remaining AC items (harder budgets/exhaustion partials, full counter set, cold/warm baselines) stay open.