feat(cli): rebuild doctor with fix guidance, --fix, --offline and json output

[AnnatarHe]

Summary

shelltime doctor used to check only the folder, the log size, config parsing, the daemon service and the hook for $SHELL. It also stopped at the first config error, and on any OS other than macOS/Linux. It now checks the whole setup. Each problem comes with a plain-language explanation of what it breaks and the exact command or config change that fixes it.

Section	What it checks
System	shelltime on PATH; a newer release is available (Homebrew-aware hint)
Storage	~/.shelltime exists and is writable; log.log size against logCleanup.thresholdMB (was hard-coded to 100MB)
Configuration	Which file is used; config.toml shadowed by config.yaml; a config.local.* that doesn't parse (silently ignored today); apiEndpoint; invalid exclude regexes (silently skipped today); proxy.url; enableMetrics
Account	A token is configured, and the server accepts it. 401/403 is reported as "token rejected"; a network error as "couldn't reach"
Privacy	dataMasking off; encrypted: true with no daemon running (uploads go unencrypted); an older token without an encryption key (also unencrypted)
Daemon	Binary, service, socket, and a version mismatch between the CLI and the daemon
Shell Hooks	rc lines, hook script and bash-preexec.sh
Claude Code / Codex	OTEL config (including the Codex endpoint), legacy shell OTEL blocks, statusline, Codex sign-in
AI Usage Receiver	aiCodeOtel disabled while Claude Code/Codex report to it; grpcPort ≠ 54027; receiver not listening
Sync	Queued failed uploads (sync-pending.jsonl) and pending heartbeats

The report ends with a How to fix list grouped by action, so one command that resolves several problems (e.g. shelltime daemon install) appears once. Paths under $HOME are shown as ~/….

New flags:

• --fix: lists the safe automatic fixes, asks for confirmation, applies them, then re-runs the checks. --yes skips the prompt.
  • The fixes are: hooks install for the current shell, cc install, codex install, daemon install, and clearing an oversized log.
  • Config edits stay hints only, so user YAML comments are never rewritten.
• --offline: skips the network checks (token, encryption key, latest version).
• --format json: prints a machine-readable report (version, summary, checks[] with id, status, message, fix and autoFix).
• Exit code: doctor exits 1 when any check fails. main now runs through run() int, so deferred cleanup still happens before exiting. Every other command's exit behavior is unchanged.

Supporting changes:

• model: exported AICodeOtelEndpoint and added DefaultAICodeOtelGRPCPort. Added ClaudeSettingsAICodeOtelEnvService.StatusLineCommand(), CodexOtelConfigService.Endpoint(), ConfigFilePaths() and ValidateConfigFile().
• requestDaemonStatus: now sets a deadline for the whole exchange, so a socket that never answers can't hang doctor or daemon status.
• Docs: updated README.md and the FAQ in docs/CONFIG.md. Also fixed the stale sync-pending.txt → sync-pending.jsonl there.

Test plan

• go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...: all packages pass.
• New commands/doctor_test.go:
  • per-section tests for every check;
  • --format json, flag validation, --fix --yes (hook and Claude Code fixes applied, daemon install deduplicated to one run), and --fix declined;
  • the network and service-manager seams are stubbed.
• Model unit tests for the new helpers.
• go vet is clean, and the changed files are gofmt-clean.
• Ran the built binary in sandbox HOMEs:
  • an empty setup gives readable fixes and exit code 1;
  • --offline --format json parses;
  • the --fix prompt declines cleanly;
  • against the real API, an unreachable server is reported as a warning, not a failure.
• Note: go test -race ./daemon/ fails TestSocketTopicProcessor_TrackPreAndPostRouted on main as well, so that race isn't caused by this PR. CI doesn't run with -race.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KzQHztW9fdhyWDwPmanhLN

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Scope note: this was a manual read of commands/doctor.go and commands/doctor_checks.go. The model/ changes and the tests were not reviewed in depth, and build/vet/tests were not run.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.90446% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
commands/doctor_checks.go	94.99%	30 Missing ⚠️
commands/doctor.go	94.36%	8 Missing ⚠️
commands/daemon.status.go	50.00%	1 Missing ⚠️
model/codex_otel_config.go	94.11%	1 Missing ⚠️

Flag	Coverage Δ
unittests	85.45% <94.90%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
model/aicode_otel_claude_settings.go	86.39% <100.00%> (+1.04%)	⬆️
model/aicode_otel_env.go	91.41% <100.00%> (ø)
model/config.go	96.29% <100.00%> (+0.20%)	⬆️
commands/daemon.status.go	92.42% <50.00%> (-1.33%)	⬇️
model/codex_otel_config.go	88.05% <94.11%> (+1.78%)	⬆️
commands/doctor.go	93.42% <94.36%> (+2.88%)	⬆️
commands/doctor_checks.go	94.99% <94.99%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.