Fix Checklist

🔧 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 — stop at the first mismatch:

#	File	Look for
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	same fields
4	data\raw\{provider}-last-failure.txt	raw of last failed attempt
5	data\usage-latest.json	full payload shape
6	data\usage-history.json	bucket history
7	data\logs\collector.log	collector diagnostics
8	data\logs\server-error.log	warnings and errors

📋 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 + 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 — timing / readiness

• Raw output lacks usage rows
• phase shows auth wait, loading, slash buffer, refresh pending, or ready-without-screen
• Retries expire before the provider reaches the usage screen

Change parser — text extraction

• Raw output clearly contains usage rows
• markers or parseDiagnostics show missing labels / percent / resets
• Normalized text splits one visible row into multiple fragments

Change UI — display only

• data\usage-latest.json is correct
• /api/usage is correct
• Only the browser display is stale, unknown, or visually 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: Architecture · API Reference