truf-server/openspec/changes/fix-keycheck-accounting-visibility/proposal.md

Why

Keycheck current-state files, DB observations, and dashboard views can diverge, making it unclear whether usable provider keys are still being found and which sources produced them. This is urgent because the scanner is running continuously, but large input files, known-key skipping, and SQLite lock behavior can hide fresh usable findings from operator-visible stats.

What Changes

• Add reliable keycheck accounting for fresh checks and known-key occurrences.
• Track current-state file counts separately from DB-observed validation rows.
• Ensure hourly keychecks process recent findings efficiently without replaying multi-GB JSONL inputs from the beginning.
• Preserve source/query/finding attribution even when a key was already classified as alive, dead, no-balance, or limited.
• Surface keycheck pipeline health, write lag, skipped-known counts, and usable/no-quota status in dashboard views.
• Reduce DB lock impact on keycheck result recording so file state and DB state remain explainably consistent.

Capabilities

New Capabilities

• keycheck-accounting: Defines reliable current-state, historical occurrence, and dashboard visibility behavior for keycheck results.

Modified Capabilities

Impact

• app/keycheck_runner.py and app/keycheckers/*: keycheck execution, input reading, skip behavior, and result recording.
• app/scanner_db.py: keycheck DB writes, lock handling, and occurrence recording.
• app/dashboard.py: operator-facing keycheck and usable-key reporting.
• Runtime files under runtime/keychecks/: current-state status files remain authoritative but gain clearer relationship to DB observations.
• Runtime DB scanner_active.db: keycheck rows and attribution semantics become more complete and auditable.