pan-doctor git:20261101.e0923b3B

Immutable. This exact content never changes and is served at /api/v1/blob/8ad6d87e895e02fc.

---
name: pan-doctor
description: "pan doctor [options] — check Overdeck system health, dependencies, and configuration"
triggers:
  - pan doctor
  - system health
  - health check
  - overdeck status
  - check overdeck
allowed-tools:
  - Bash
  - Read
---

# System Health Check

## Overview

This skill guides you through checking the health of your Overdeck installation, including configuration, dependencies, and running services.

## When to Use

- After initial installation
- Troubleshooting agent issues
- Before starting a new work session
- Verifying configuration changes
- Periodic maintenance

## Quick Command

```bash
pan doctor
pan doctor github-quota [--json]   # GitHub API quota use per caller, active pauses, skipped projects (PAN-4264)
```

## JSON output (PAN-4643)

```bash
pan doctor --json
```

Prints exactly one JSON object to stdout — no banner, no colour, no summary sentence (those go to stderr instead) — with the same exit code as text mode (`1` on any `error` check, or on any `warn` check with `--strict`):

```json
{
  "schemaVersion": 1,
  "generatedAt": "2026-11-01T04:52:00.000Z",
  "strict": false,
  "exitCode": 0,
  "summary": { "ok": 40, "warn": 2, "error": 0 },
  "checks": [
    { "name": "Git", "status": "ok", "message": "Installed", "fix": null }
  ],
  "patrolBudgets": [
    { "patrol": "example-patrol", "actions": 3, "budget": 20, "suspended": false }
  ]
}
```

Use it to script health checks or feed a machine-readable report into another tool (for example `pan diagnose`, which runs it out-of-process to build a diagnostic bundle).

## Health Check Workflow

### 1. Run Diagnostics

```bash
# Full health check
pan doctor

# Expected output:
# ✓ Configuration file exists
# ✓ Linear API key configured
# ✓ GitHub token configured
# ✓ Skills directory exists
# ✓ tmux available
# ✓ Docker available
# ⚠ orphan-proposed-specs: proposed xBRIEF specs without work agents, grouped by project with remediation hints
```

### 2. Check Configuration

```bash
# View current config
cat ~/.overdeck.env

# Required settings:
# LINEAR_API_KEY=lin_api_xxx
# GITHUB_TOKEN=ghp_xxx (optional but recommended)
# WORKSPACE_ROOT=/path/to/workspaces
```

### 3. Check Running Services

```bash
# Dashboard status
curl -s http://localhost:3011/api/health || echo "Dashboard not running"

# Running agents
tmux list-sessions | grep agent

# Docker containers
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "(traefik|overdeck)"
```

### 4. Check Skills

```bash
# List installed skills
pan skills

# Verify skills are synced
ls -la ~/.claude/skills/ | head -20
```

### 5. Check Dependencies

```bash
# Node.js version (18+ required)
node --version

# npm version
npm --version

# tmux version
tmux -V

# Docker version
docker --version

# Git version
git --version
```

### 6. Herdr

Herdr is the default terminal backend and is strict: when it is selected but its binary or this home's
session socket is missing, agent launches fail and `pan doctor` exits 1. Doctor prints these rows:

| Row | Fix when it fails |
| --- | --- |
| `Terminal backend` | `pan install` (or set `terminal.backend: tmux` in `~/.overdeck/config.yaml`) |
| `Herdr binary` | `pan install` |
| `Herdr server` | `pan sync` (restarting a stale server is manual: `systemctl --user restart overdeck-herdr.service` closes every agent pane) |
| `Herdr config` | `pan sync` (sets `resume_agents_on_restore = false`) |
| `Herdr integration: <target>` | `pan sync` (pilot set `pi`, `omp`, `kimi`, `opencode`; `claude`, `codex`, `hermes` are not managed) |

Under an explicit tmux backend only the `Terminal backend` row appears.

### 7. Plan home `.pan/` tracking

Planning artifacts are committed under `.pan/` in each project's plan home. Before the Cut, Overdeck
wrote `.pan/` into project `.gitignore` files, and that rule makes every planning commit fail
(`The following paths are ignored by one of your .gitignore files: .pan`). The
`Plan home .pan/ tracking` row WARNs for each registered plan home where `git check-ignore` matches
`.pan/`, naming the rule's `file:line`:

| Rule source | Fix |
| --- | --- |
| Exact `.pan/` or `.pan` line in the repo's top-level `.gitignore` (Overdeck's legacy line) | `pan admin migrate-plan-home <key> --repair-ignore` removes that line and commits `.gitignore` alone (no migration, no tracker lookup), or delete the line and commit it yourself |
| Anything else (nested `.gitignore`, `.git/info/exclude`, `core.excludesFile`, a broader pattern) | Not Overdeck's rule: doctor never edits it. Remove or narrow it yourself |

Doctor only reports; it has no `--fix`.

### 8. Sync sources checkout

`pan sync` distributes from the primary checkout's `sync-sources/` when it can. The
`Sync Sources Checkout` row WARNs when that checkout is behind its upstream, on a branch other
than the remote's default branch, or has a detached HEAD, because every sync would then distribute
an old tree (PAN-3881). Doctor does not fetch; it compares with the last-fetched upstream ref and
says so in the row. Fix: fetch and fast-forward the checkout on its default branch, then `pan sync`.
The row is skipped (OK) when sync distributes a frozen `pan reload` generation's own copy; the
`Deployed Hooks` row covers that case.

## Health Checklist

| Component | Check Command | Expected |
|-----------|---------------|----------|
| Config | `cat ~/.overdeck.env` | File exists with keys |
| Node.js | `node --version` | v18+ |
| tmux | `tmux -V` | Any version |
| Docker | `docker info` | Running |
| Skills | `ls ~/.overdeck/skills/` | Skills present |
| Symlinks | `ls -la ~/.claude/skills/` | Symlinks to overdeck |
| Linear | `pan doctor` | API key valid |

## Component Status

### Dashboard

```bash
# Start dashboard
cd ~/.overdeck/dashboard && npm run dev

# Check health endpoint
curl http://localhost:3011/api/health

# View dashboard
open http://localhost:3010
```

### Traefik (if using)

```bash
# Check traefik
docker ps | grep traefik

# Traefik dashboard
curl -k https://traefik.overdeck.localhost:8080/api/overview
```

### Agents

```bash
# List all agents
tmux list-sessions -F "#{session_name}" | grep "^agent-"

# Check agent health
for session in $(tmux list-sessions -F "#{session_name}" | grep "^agent-"); do
  echo "=== $session ==="
  tmux capture-pane -t $session -p | tail -5
done
```

## Common Issues

### Configuration Missing

```bash
# Create config file
pan init

# Or manually
cat > ~/.overdeck.env << 'EOF'
LINEAR_API_KEY=your_key_here
GITHUB_TOKEN=your_token_here
WORKSPACE_ROOT=/home/user/workspaces
EOF
```

### Skills Not Synced

```bash
# Re-sync skills
pan sync

# Force overwrite
pan sync --force
```

### Dashboard Won't Start

```bash
# Check port in use
lsof -i :3010
lsof -i :3011

# Kill conflicting processes
kill $(lsof -t -i:3010)
kill $(lsof -t -i:3011)

# Restart
cd ~/.overdeck/dashboard && npm run dev
```

### tmux Issues

```bash
# Kill stuck server
tmux kill-server

# Fresh start
tmux new-session -d -s test
tmux kill-session -t test
```

## Maintenance Tasks

### Update Overdeck

```bash
npm update -g overdeck
pan init  # Re-copy bundled skills
pan sync  # Re-sync to AI tools
```

### Clean Up Old Workspaces

```bash
# List workspaces
ls -la $WORKSPACE_ROOT/

# Remove completed ones
rm -rf $WORKSPACE_ROOT/old-issue/
```

### Reset Configuration

```bash
# Backup and reset
cp ~/.overdeck.env ~/.overdeck.env.backup
pan init
```

## Related Skills

- `/pan:diagnose` - Deep troubleshooting
- `/pan:install` - Initial setup
- `/pan:sync` - Skill synchronization