Add general-purpose `jcode doctor` diagnostic command

[quangdang46]

Add general-purpose jcode doctor diagnostic command

Summary

Add a top-level jcode doctor (and jcode doctor --only <area>) command that inspects the user's environment and prints a structured report covering: auth, sessions, swarm readiness, MCP, browser, ambient, extensions, disk headroom, cgroup/CPU/memory budgets, and known platform quirks. Today jcode auth-test and jcode provider doctor cover auth only.

Reference: pi_agent_rust pi doctor.

Why

• Several existing issues are environment problems users could self-diagnose if doctor existed: [Bug] It doesn't work at all 1jehuang/jcode#231, Bug: Server fails to start with "No credentials configured" error despite successful OpenCode Go auth 1jehuang/jcode#234, Bug: Infinite reload loop causing CPU 100% — caused by stale builds/stable directory 1jehuang/jcode#216, auto_server_reload causes infinite reload loop when binary hash is "unknown" 1jehuang/jcode#213, Bug: Infinite reload loop causing CPU 100% — caused by stale builds/stable directory 1jehuang/jcode#216, Terminal corruption after /quit - typed input invisible 1jehuang/jcode#214, Jcode crashed back to terminal prompt during tool-heavy workflow session 1jehuang/jcode#218, [Upstream #175] Repeated emergency compaction loop accumulates [Emergency compaction] markers and inflates compacted_count past messages.len() (active_messages() fallback) #135, [Upstream #177] Tried for hours: UNUSABLE - Unstable Provider Setup, Broken Model Management, and Concerning Telemetry Collection #136, [Upstream #207] No command can delete a session #153, [Upstream #233] Add logging instrumentation to 5 uninstrumented source modules #170. Even when the bug is real, support response speeds up if the user pastes a doctor report.
• Swarm sessions in particular benefit from a pre-flight that catches cgroup CPU quota mismatches, NUMA topology surprises, and target/tmp headroom before a 10-agent run dies halfway through.

Current state in jcode

• src/auth/doctor.rs exists but is scoped to auth.
• No top-level Doctor subcommand in src/cli/args.rs. provider doctor exists as a subsub.

Implementation checklist

1. Subcommand and routing

• Add Doctor { only: Option<DoctorArea>, format: ReportFormat, fix: bool } to the top-level Command enum in src/cli/args.rs.
• DoctorArea: auth, sessions, swarm, mcp, browser, ambient, extensions, system, all (default).
• ReportFormat: text (default), json, markdown.

2. Probe library

• New module src/doctor/ with one file per area. Each probe returns DoctorFinding { area, severity: Info|Warn|Fail, summary, details, suggested_fix: Option<String>, fix_command: Option<String> }.
• auth: reuse src/auth/doctor.rs; report each configured provider's status.
• sessions:
  • Sessions dir exists, writable, byte budget OK.
  • Detect orphaned .lock files (link to Terminal corruption after /quit - typed input invisible 1jehuang/jcode#214/Bug: Infinite reload loop causing CPU 100% — caused by stale builds/stable directory 1jehuang/jcode#216 root causes).
  • Detect v1 → v2 unmigrated sessions if the session-tree issue lands.
• swarm:
  • Cgroup CPU quota and cpuset size (Linux).
  • NUMA topology.
  • Cgroup memory limit vs current RSS.
  • Free disk on $CARGO_TARGET_DIR and $TMPDIR.
  • Recommended max concurrent workers.
• mcp:
  • Parse ~/.jcode/mcp.json and .jcode/mcp.json; for each server, attempt a 1-second handshake; report whether the agent will actually see those tools (this would have caught feat(nix): add flake.nix for build, devShell, and checks (#95) #206 fast).
• browser:
  • Run the existing jcode browser status logic and surface its output as DoctorFindings.
• ambient:
  • Confirm ambient runner config, last cycle, queued tasks.
• extensions (after the extension-runtime issue lands):
  • List loaded extensions, declared caps, trust state, and last error.
• system:
  • OS, libc, terminal, locale (catches fix(mobile-core): honor https://wss:// scheme in gateway host (#77) #186 keyboard map issues).
  • $PATH ordering of ~/.local/bin vs ~/.cargo/bin (per AGENTS.md).
  • Termux detection and known-broken combos (catches jcode fails to execute in Termux due to missing dynamic linker and LD_PRELOAD conflict 1jehuang/jcode#235).

3. --fix

• For findings that carry fix_command, --fix prompts and runs them. Default: no autorun.
• Examples of fix_command: jcode session migrate, jcode browser setup, chmod 600 ~/.jcode/auth.json.

4. Output

• Text mode: headed by an overall status (OK, WARN, FAIL), then a per-area summary with colors. Exit code: 0 if all probes are Info, 1 if any Warn, 2 if any Fail.
• JSON mode: stable schema documented in docs/DOCTOR.md. Use this for scripting and CI.

5. Integration with existing commands

• jcode auth-test --doctor-format=json becomes a thin alias to jcode doctor --only auth --format json.

Testing

Unit

• Each probe has a unit test driven by fixtures (e.g. mock cgroup files under a temp dir).
• JSON schema is stable: a snapshot test rejects accidental changes.

Integration

• On a clean Linux box, jcode doctor exits 0 and contains an auth finding suggesting jcode login --provider claude.
• Simulate an unwritable ~/.jcode/sessions/ and verify Fail is reported.

Manual

• Run on macOS and Windows; verify platform-specific probes degrade gracefully.

Acceptance criteria

• jcode doctor runs in <2 s with no network calls (auth probes are local; live checks are opt-in via --live).
• Exit codes follow the documented convention.
• JSON output validates against docs/doctor.schema.json.
• jcode doctor --only swarm --format json matches the field set called out in pi_agent_rust's doctor docs.

References

• pi_agent_rust: pi doctor.

---

Implementation notes addendum (Devin gap-analysis pass, 2026-05-21)

Verified jcode code paths

• Existing diagnostic-shaped subcommand: src/cli/auth_test.rs (provider auth probing). Reuse this pattern for doctor.
• Health-relevant code surfaces:
  • Storage: src/storage.rs (config/data dirs, perms harden)
  • Auth: src/auth/, src/auth/doctor.rs (already partially exists!) → fold into the new doctor command
  • Session storage health: src/session.rs, src/session_active_pids.rs
  • MCP servers: src/mcp/
  • Update channel: src/update.rs
  • Shell PATH: src/cli/startup.rs (look at how the launcher resolves jcode vs ~/.local/bin)

Recommended check buckets (mirror pi_agent_rust pi doctor --only ...)

• config — required dirs exist, perms, settings parse cleanly
• auth — credentials present and non-expired (reuse auth/doctor.rs)
• shell — ~/.local/bin precedes ~/.cargo/bin, completions installed
• sessions — session dir writable, no orphaned *.lock, index reachable
• providers — at least one provider can list models
• extensions (depends on TypeScript/QuickJS extension runtime for user-defined tools, commands, and hooks #3) — preflight check installed extensions
• mcp — MCP server connectivity
• swarm — jcode-specific: ambient daemon health
• update — current binary version vs latest

CLI surface

• jcode doctor (default: text)
• jcode doctor --format json|markdown|text
• jcode doctor --only auth,sessions
• jcode doctor --fix (apply safe auto-fixes: chmod, create-dir, install completions)
• Exit code: 0 on all-pass, 1 on warnings, 2 on errors. Important for CI gating.

Cross-references

• TypeScript/QuickJS extension runtime for user-defined tools, commands, and hooks #3 Extension preflight is part of doctor's extensions bucket.
• Extension capability policy: --extension-policy safe|balanced|permissive + command-level exec mediation #14 --explain-extension-policy ties in cleanly with doctor --only extensions.
• Fixture-based conformance test suite for built-in tools #20 Conformance fixtures should add a doctor exit-code regression.

Reference

• pi_agent_rust: pi doctor — output formats, --only, --fix, swarm preflight details.