Skip to content

Fix Checklist

Jump to bottom
savvy773 edited this page May 26, 2026 · 2 revisions

Fix Checklist

Full reference: docs/fix_check.md

Use this page when a provider shows wrong data, stays partial, or the dashboard isn't refreshing correctly.

Fast Health Check

cd D:\Code\_toolkit\aI_usage
pnpm check
.\scripts\start-server.ps1 -Status

Then test a live refresh:

Invoke-RestMethod `
  -Method Post `
  -Uri 'http://127.0.0.1:5173/api/usage/refresh' `
  -ContentType 'application/json' `
  -Headers @{ Origin = 'http://127.0.0.1:5173' } `
  -Body '{}'

Invoke-RestMethod 'http://127.0.0.1:5173/api/usage'

Expected: server running · no CSRF error · all providers eventually ok · refreshState.refreshing becomes false.

Debug Order

Check in this sequence:

  1. data\raw\{provider}-latest.parsed.json → phase, markers, parseDiagnostics, status
  2. data\raw\{provider}-latest.txt → actual raw terminal output
  3. data\raw\{provider}-last-failure.parsed.json
  4. data\raw\{provider}-last-failure.txt
  5. data\usage-latest.json
  6. data\usage-history.json
  7. data\logs\collector.log
  8. data\logs\server-error.log

Phase Meanings

Phase Meaning Next check
usage-output-complete Parser found enough data Check usage-latest.json and UI
codex-loading Codex still starting Wait — don't send /status too early
codex-status-refresh-pending Codex asked to rerun /status Same-session retry should happen
codex-status-output-without-limits Codex answered, limit rows missing Inspect raw text
gemini-auth-wait Gemini waiting for auth/trust Don't spend /model during auth wait
gemini-slash-buffer-waiting /model still in input buffer Check confirmation Enter timing
gemini-ready-without-model-screen Prompt returned, no model panel Check slash reissue guard
gemini-model-screen-incomplete Model panel open, rows incomplete Check \r handling
startup/redraw with markers=none Boot output only Treat as collector timing

Common Symptoms

Symptom Likely Cause Fix Direction
Cross-site POST form submissions are forbidden Missing JSON body or Origin header Send {} with Origin: http://127.0.0.1:5173
Source changes ignored Preview server not restarted Run .\scripts\start-server.ps1 again
All providers partial in one bucket CLI startup/auth timing or node-pty path Inspect latest and last-failure raw snapshots
UI shows usable values after partial Storage carried forward previous snapshot Check provider status/message for latest failure
Gemini has status rows but no models /model panel not opened or not settled Check slash buffer, auth wait, reissue guard
Codex shows Unknown or 100% Parser read a status line instead of limit rows Narrow Codex parser to limit rows

When to Change Code

Change collector when raw output lacks usage rows, or phase shows auth wait / loading / slash buffer / refresh pending / ready-without-screen.

Change parser when raw output clearly contains usage rows but markers or parseDiagnostics show missing labels / percent / resets.

Change UI when data\usage-latest.json and /api/usage are correct but only the browser display is stale or wrong.

Validation After Fixes

pnpm check
pnpm lint
.\scripts\start-server.ps1

Then confirm:

  • POST /api/usage/refresh succeeds
  • GET /api/usage returns current statuses
  • Latest parsed snapshots match displayed values
  • data/usage-history.json has a new or updated bucket
  • Browser first paint includes server-rendered provider data

See Also

Clone this wiki locally