mushi-health

Mushi Health Check

Run these checks in order. Stop and fix at the first ❌ before continuing.

Component map

#	Component	How to check
1	CLI credentials	mushi doctor
2	API + edge functions	mushi deploy check
3	Project overview	mushi status
4	BYOK key pool	mushi keys list or MCP list_byok_keys
5	Supabase logs	Supabase MCP get_logs
6	QA cron running	DB query on qa_story_runs

---

Step 1 — CLI credentials

mushi doctor

Expected output — every check prefixed OK (the CLI prints OK / WARN / FAIL text markers, not checkmarks):

OK CLI config file
OK API key configured
OK Project ID configured
OK Endpoint reachable

Exit codes: 0 all pass · 2 advisory warnings only · 1 any hard failure. Each FAIL line is followed by a → Fix: hint; mushi doctor --json includes the same hints in a hint field.

Fix if FAIL: follow the printed → Fix: hint, or re-run mushi login --api-key mushi_... --endpoint https://<ref>.supabase.co/functions/v1/api --project-id <pid>.

---

Step 2 — API + edge functions

mushi deploy check

Probes each edge function with a lightweight ping. Healthy output:

✓  api
✓  classify-report
✓  fix-worker
✓  story-mapper
✓  test-gen-from-story
✓  pdca-runner
✓  qa-story-runner

A ✗ on any line means that function is down. Check its logs in Step 5.

---

Step 3 — Project overview

mushi status

Confirm:

• Report count is non-zero (or expected zero for a brand-new project).
• autofix_agent shows the expected agent (cursor_cloud, mcp, etc.).
• No billing: quota_exceeded warning.

---

Step 4 — BYOK key pool

Via CLI:

mushi keys list

Via MCP (if the Mushi MCP server is active in Cursor):

list_byok_keys(projectId)

Healthy: at least one anthropic key with status=active, at least one firecrawl key with status=active.

Fix: Add a missing or exhausted key:

mushi keys add --provider anthropic --key sk-ant-... --label "primary" --priority 100
mushi keys add --provider firecrawl --key fc-...   --label "primary" --priority 100

---

Step 5 — Supabase edge function logs

Use the Supabase MCP (requires SUPABASE_ACCESS_TOKEN in MCP config):

get_logs(service: 'api')

Look for ERROR lines in the last 15 minutes, especially from:

• story-mapper — Firecrawl timeout or Claude quota
• test-gen-from-story — LLM key exhausted
• pdca-runner — failed PDCA cycle
• qa-story-runner — Browserbase quota or Firecrawl error

If the Supabase MCP is not wired in Cursor, use the CLI:

supabase functions logs story-mapper --project-ref <ref>
supabase functions logs qa-story-runner --project-ref <ref>

---

Step 6 — QA cron running

Verify scheduled tests are executing (requires Supabase MCP):

SELECT status, COUNT(*) 
FROM qa_story_runs 
WHERE created_at > NOW() - INTERVAL '2 hours'
GROUP BY status;

Healthy output: at least one completed row in the last 2 hours (if you have enabled stories).

If qa_story_runs is empty:

1. Confirm at least one story has enabled = true and approval_status = 'approved'.
2. Confirm the pg_cron job is registered: SELECT jobname, schedule FROM cron.job WHERE jobname LIKE 'qa%';
3. Manually trigger: mushi tdd run <qa-story-id> and re-check.

---

Pass/Fail Summary Template

After running all steps, record results:

Component	Status	Notes
CLI credentials	✅ / ❌
Edge functions	✅ / ❌	Which ones failed?
Project overview	✅ / ❌	Billing ok?
BYOK key pool	✅ / ❌	Missing providers?
Supabase logs	✅ / ❌	Any ERRORs?
QA cron	✅ / ❌	Last run at?

If all ✅ → pipeline is healthy.
If any ❌ → use mushi-debug for targeted diagnosis.

---

Common causes of all-red

Symptom	Likely cause	Fix
mushi doctor can't reach endpoint	Wrong MUSHI_API_ENDPOINT in ~/.config/mushi/config.json	Re-run mushi login --endpoint https://...
All edge functions ❌	Supabase project paused (free tier)	Restore the project in the Supabase dashboard
BYOK keys all quota_exhausted	Rate limits hit on all keys	Add a backup key for each provider
QA cron never fires	pg_cron job missing	Re-run migration 20260602000003_pdca_qa_improve_cron.sql