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

1. Input Processing

• 1.1 Add shared keycheck input state storage for per-service file path, file size, inode/signature if available, and last processed byte offset.
• 1.2 Extend shared keycheck input reader to support high-watermark processing with safe reset on file truncation or rotation.
• 1.3 Migrate hand-rolled readers in OpenAI, OpenRouter, and Gemini to the shared input reader.
• 1.4 Keep a bounded tail fallback for first run or missing state, with clear logging of the active input mode.

2. Known-Key Occurrence Recording

• 2.1 Add a shared helper that resolves cached status for a key from checked/status files without provider API calls.
• 2.2 Add occurrence recording for skipped known keys, including service, cached status, source line, finding payload, and detector.
• 2.3 Mark cached occurrence rows distinctly from API-check rows in metadata.
• 2.4 Deduplicate cached occurrences per service/key/finding/source to avoid unbounded repeated rows.

3. DB Write Reliability

• 3.1 Ensure per-result keycheck DB writes do not run schema initialization or migration DDL.
• 3.2 Add bounded lock retry/backoff for keycheck result and occurrence writes.
• 3.3 Add keycheck runner counters for DB write success, retry, and failure counts per service.
• 3.4 Log DB write failures without preventing status-file updates.

4. Dashboard Visibility

• 4.1 Add dashboard panel comparing status-file current-state counts with latest DB observation timestamps.
• 4.2 Add keycheck pipeline health panel showing last completed service, current/stuck service, run duration, and DB write errors.
• 4.3 Add current usable-key view based on provider-specific access tiers and exact statuses.
• 4.4 Add historical source-yield view that includes cached known-key occurrences.
• 4.5 Label cached-status rows separately from fresh API-check rows in validation tables.

5. Verification

• 5.1 Add a smoke test or script that runs a checker over a small fixture and verifies status-file writes plus DB occurrence rows.
• 5.2 Verify OpenAI, OpenRouter, Gemini, AWS, and GCP checkers use bounded/incremental input processing.
• 5.3 Verify a known alive key found in a new source/query creates a cached occurrence without an API recheck.
• 5.4 Verify dashboard can show current-state file counts even when DB observations are stale.
• 5.5 Run python -m py_compile on changed Python modules.