feat: add doctor command for diagnosing installs and cleaning stale daemon state (#1254)

* feat: add `doctor` command for install diagnostics and cleanup

Adds `agent-browser doctor`, a one-shot diagnostic that checks
environment, Chrome install, daemon state, config, encryption key,
providers, network reachability, and a live headless launch test.
Auto-cleans stale `.sock` / `.pid` / `.version` / `.stream` sidecar
files on every run. Destructive repairs (reinstall Chrome, purge old
state, close version-mismatched daemons, generate missing encryption
key) are gated behind `--fix`. Supports `--offline`, `--quick`, and
`--json`.

* fixes

docs/src/app/commands/page.mdx

@@ -379,6 +379,19 @@ agent-browser dashboard start --port <n>  # Start on a specific port
 agent-browser dashboard stop          # Stop the dashboard server
 ```
 
+## Doctor
+
+Diagnose your install, auto-clean stale daemon files, and optionally repair common problems.
+
+```bash
+agent-browser doctor                     # Full diagnosis (env, Chrome, daemons, config, providers, network, launch test)
+agent-browser doctor --offline --quick   # Local-only, fastest
+agent-browser doctor --fix               # Also run destructive repairs (reinstall Chrome, purge old state, ...)
+agent-browser doctor --json              # Structured JSON output for agents
+```
+
+Exit code is `0` if all checks pass (warnings are fine), `1` if any fail. See the [Installation page](/installation#doctor) for the full check catalog.
+
 ## Chat
 
 Use natural language to control the browser via AI. The `chat` command translates instructions into agent-browser commands, executes them, and streams the AI response. Requires `AI_GATEWAY_API_KEY` to be set.

docs/src/app/installation/page.mdx

@@ -75,6 +75,51 @@ agent-browser upgrade
 
 Detects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically. Displays the version change on success, or informs you if you are already on the latest version.
 
+## Doctor
+
+`doctor` diagnoses your install and auto-cleans stale daemon files. Run it whenever something stops working unexpectedly, or after upgrades:
+
+```bash
+agent-browser doctor                     # Full diagnosis
+agent-browser doctor --offline --quick   # Local-only, fastest (~<1s)
+agent-browser doctor --fix               # Also run destructive repairs
+agent-browser doctor --json              # Structured output
+```
+
+It checks:
+
+<table>
+<thead>
+<tr><th>Category</th><th>What it checks</th></tr>
+</thead>
+<tbody>
+<tr><td>Environment</td><td>CLI version, platform, home directory, state and socket dirs, free disk space</td></tr>
+<tr><td>Chrome</td><td>Chrome install path and version, cache dir, Puppeteer fallback, user-data dir and profile count, optional <code>lightpanda</code> engine</td></tr>
+<tr><td>Daemons</td><td>Running daemons per session, stale <code>.sock</code> / <code>.pid</code> / <code>.version</code> / <code>.stream</code> files (auto-cleaned), version mismatch with the CLI, dashboard process liveness</td></tr>
+<tr><td>Config</td><td><code>~/.agent-browser/config.json</code>, <code>./agent-browser.json</code>, and any file at <code>AGENT_BROWSER_CONFIG</code> parse as valid JSON</td></tr>
+<tr><td>Security</td><td>Encryption key env var or <code>~/.agent-browser/.encryption-key</code> (with 0600 permissions on unix), state file count and age vs <code>AGENT_BROWSER_STATE_EXPIRE_DAYS</code>, action policy file</td></tr>
+<tr><td>Providers</td><td>Env vars for Browserless, Browserbase, Browser Use, Kernel, AgentCore (AWS creds), Appium (for <code>--provider ios</code>), and <code>AI_GATEWAY_API_KEY</code> for chat</td></tr>
+<tr><td>Network</td><td>Reachability of the Chrome for Testing CDN, AI Gateway (if configured), and any currently selected provider endpoint (skipped under <code>--offline</code>)</td></tr>
+<tr><td>Launch test</td><td>Spawns a scratch session, launches headless Chrome, navigates to <code>about:blank</code>, then closes. Measures wall time (skipped under <code>--quick</code>)</td></tr>
+</tbody>
+</table>
+
+Stale sidecar files are always cleaned. Destructive actions are opt-in via `--fix`:
+
+<table>
+<thead>
+<tr><th>Check</th><th>What <code>--fix</code> does</th></tr>
+</thead>
+<tbody>
+<tr><td>Chrome missing</td><td>Runs <code>agent-browser install</code></td></tr>
+<tr><td>Version-mismatched daemons</td><td>Sends <code>close</code> to each and cleans files</td></tr>
+<tr><td>Old state files</td><td>Deletes state files older than <code>AGENT_BROWSER_STATE_EXPIRE_DAYS</code> (default 30)</td></tr>
+<tr><td>Missing encryption key</td><td>Generates a new key at <code>~/.agent-browser/.encryption-key</code> (0600, unix); never overwrites an existing key</td></tr>
+</tbody>
+</table>
+
+Exit code is `0` if all checks pass (warnings are fine), `1` if any fail.
+
 ## Custom browser
 
 Use a custom browser executable instead of bundled Chromium: