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

`shelltime doctor` now checks the whole setup and, for every problem, says
what it breaks and the exact command or config change that fixes it:

- system: shelltime on PATH, newer release available
- storage: ~/.shelltime exists and is writable, log size vs logCleanup
- configuration: which file is used, shadowed and unparseable local
  files, apiEndpoint, invalid exclude regexes, proxy URL, enableMetrics
- account: token present and accepted by the server (401/403 vs unreachable)
- privacy: data masking, encryption without a running daemon, legacy
  tokens without an encryption key
- daemon: binary, service, socket, CLI/daemon version mismatch
- shell hooks: rc lines, hook script, bash-preexec
- Claude Code / Codex: OTEL config, legacy shell OTEL blocks, statusline,
  Codex sign-in
- AI usage receiver: aiCodeOtel disabled, port mismatch, not listening
- sync: queued failed uploads and heartbeats

The report ends with a "How to fix" list grouped by action. `--fix`
applies the safe fixes (hooks, cc/codex install, daemon install, log
cleanup) after confirmation (`--yes` skips it), `--offline` skips the
network checks and `--format json` prints a machine-readable report.
doctor exits 1 when any check fails and no longer aborts on a config
error or on an unsupported OS.


Claude-Session: https://claude.ai/code/session_01KzQHztW9fdhyWDwPmanhLN

Co-authored-by: Claude <noreply@anthropic.com>

Author: AnnatarHe

README.md

@@ -72,7 +72,7 @@ shelltime codex install
 | `shelltime init` | Bootstrap auth, hooks, daemon, and AI-code integrations |
 | `shelltime auth` | Authenticate with `shelltime.xyz` |
 | `shelltime update` | Download and install the latest release in place |
-| `shelltime doctor` | Check installation and environment health |
+| `shelltime doctor` | Diagnose setup problems and show how to fix each one (`--fix` applies the safe fixes, `--offline`, `--format json`) |
 | `shelltime web` | Open the ShellTime dashboard in a browser |
 
 ### Tracking and sync

cmd/cli/main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"os"
@@ -22,6 +23,11 @@ var (
 )
 
 func main() {
+	os.Exit(run())
+}
+
+// run holds main's body so its deferred cleanup finishes before main sets the exit code.
+func run() int {
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
 	defer cancel()
 	cli.VersionFlag = &cli.BoolFlag{
@@ -113,8 +119,14 @@ func main() {
 		commands.UpdateCommand,
 	}
 	err = app.Run(os.Args)
-	if err != nil {
+	// doctor already reported its problems; it only needs a non-zero exit code.
+	doctorFailed := errors.Is(err, commands.ErrDoctorFoundProblems)
+	if err != nil && !doctorFailed {
 		slog.Error("CLI error", slog.Any("err", err))
 	}
 	commands.CloseLogger()
+	if doctorFailed {
+		return 1
+	}
+	return 0
 }

commands/daemon.status.go

@@ -116,6 +116,10 @@ func requestDaemonStatus(socketPath string, timeout time.Duration) (*daemon.Stat
 		return nil, 0, err
 	}
 	defer conn.Close()
+	// Bound the whole exchange: a socket file whose owner never answers would otherwise block.
+	if err := conn.SetDeadline(start.Add(timeout)); err != nil {
+		return nil, 0, err
+	}
 
 	// Send status request
 	msg := daemon.SocketMessage{