pan-diagnose · diff

git:20260920.abade5a to git:20261101.e0923b3

25 added, 0 removed. Audit C to C.

---

name: pan-diagnose

description: Troubleshoot common Overdeck issues

triggers:

- pan diagnose

- troubleshoot overdeck

- debug overdeck

- overdeck not working

- fix overdeck

allowed-tools:

- Bash

- Read

- Grep

- Glob

---

# Troubleshooting Guide

## Overview

This skill helps diagnose and fix common issues with Overdeck installation, configuration, and operation.

+ ## Run it

+ `pan diagnose` (PAN-4643) collects a redacted diagnostic bundle (config, logs,

+ `pan doctor --json`, environment and service reachability) and, with your

+ consent, starts Claude Code or Codex in that bundle's directory with this

+ skill as a copy named `TROUBLESHOOTING.md`. It works even when the dashboard,

+ the supervisor, or Herdr is down — that is when you need it most.

+ ```bash

+ pan diagnose # pick a harness interactively, then launch it

+ pan diagnose --bundle-only # just collect and print the bundle path

+ pan diagnose --harness codex --describe "dashboard will not start"

+ pan diagnose --no-issue # never draft or create an upstream issue

+ ```

+ Flags: `--harness <claude-code|codex>`, `--describe <text>`, `--bundle-only`, `--no-issue`, `--yes` (skip the launch confirmation). See `pan diagnose --help` for the authoritative list.

+ ## When `pan diagnose` started this session

+ - Read `MANIFEST.md` in the bundle directory first — it lists every file, what was redacted, and what collection failed.

+ - Open `doctor.json` and check `checks` entries with `status: "error"` before `"warn"`.

+ - If `services.json` reports `dashboard.reachable: false` or `supervisor.reachable: false`, treat the dashboard as down: see the Dashboard Issues section below, or suggest `pan up` / `pan restart`.

+ - Confirm with the operator before editing any config file in the bundle's `config/` directory.

+ - Never paste an unredacted secret into an issue or a message — the bundle is already redacted; quote from it, don't re-fetch the original file.

## Issue Categories

1. [Installation Issues](#installation-issues)

2. [Configuration Issues](#configuration-issues)

3. [Agent Issues](#agent-issues)

4. [Dashboard Issues](#dashboard-issues)

5. [Skill Issues](#skill-issues)

6. [Network Issues](#network-issues)

---

## Installation Issues

### "pan: command not found"

```bash

# Check if installed

npm list -g overdeck

# Install globally

npm install -g overdeck

# Or use npx

npx overdeck doctor

# Check PATH

echo $PATH | tr ':' '\n' | grep npm

```

### "Cannot find module" errors

```bash

# Reinstall dependencies

npm install -g overdeck --force

# Clear npm cache if needed

npm cache clean --force

npm install -g overdeck

```

### Node.js version issues

```bash

# Check version

node --version

# Need Node 18+

# Use nvm to switch

nvm install 18

nvm use 18

```

---

## Configuration Issues

### "LINEAR_API_KEY not found"

```bash

# Check config file exists

cat ~/.overdeck.env

# Create/update config

echo "LINEAR_API_KEY=lin_api_xxx" >> ~/.overdeck.env

# Verify

grep LINEAR_API_KEY ~/.overdeck.env

```

### "Invalid Linear API key"

```bash

# Test the key

curl -H "Authorization: lin_api_xxx" \

https://api.linear.app/graphql \

-d '{"query": "{ viewer { id } }"}'

# Get a new key from: Linear > Settings > API > Personal API Keys

```

### "GitHub token invalid"

```bash

# Test the token

curl -H "Authorization: token ghp_xxx" \

https://api.github.com/user

# Create new token: GitHub > Settings > Developer settings > Personal access tokens

# Required scopes: repo, read:org

```

### Config file permissions

```bash

# Fix permissions (should be readable only by owner)

chmod 600 ~/.overdeck.env

```

---

## Agent Issues

### Agent won't start

```bash

# Check tmux is available

which tmux

tmux -V

# Try starting manually

tmux new-session -d -s test-agent "echo 'test'; sleep 5"

tmux capture-pane -t test-agent -p

tmux kill-session -t test-agent

# Check for existing session

tmux list-sessions | grep agent-ISSUE

```

### Agent is stuck

```bash

# Check what it's doing

tmux capture-pane -t agent-ISSUE-123 -p | tail -50

# Look for:

# - API rate limits

# - Waiting for user input

# - Long-running commands

# - Error messages

# Try sending a message (ALWAYS use pan tell, NOT raw tmux)

pan tell ISSUE-123 "What is your current status?"

```

**WARNING:** DO NOT use raw `tmux send-keys` - agents often forget the Enter key. Always use `pan tell` which handles this correctly.

### OpenCode conversation stuck after a permission ask

An OpenCode Task subagent can block its parent turn if its permission request

does not reach ACP. First check whether the host watchdog already recovered it:

```bash

CONVERSATION=conv-YYYYMMDD-NNNN

grep '"source":"watchdog"' \

"$HOME/.overdeck/agents/$CONVERSATION/acp-session.jsonl" | tail -5

```

If the turn is still stuck, list the pending asks on the host's recorded port,

then reply to the relevant permission id:

```bash

OPENCODE_PORT=$(cat "$HOME/.overdeck/agents/$CONVERSATION/opencode-port")

curl -sS "http://127.0.0.1:$OPENCODE_PORT/permission"

curl -sS -X POST \

"http://127.0.0.1:$OPENCODE_PORT/permission/<permission-id>/reply" \

-H 'content-type: application/json' \

-d '{"reply":"always"}'

```

If `opencode-port` is absent, the conversation predates the watchdog. Use

`ss -ltnp` to find the loopback port owned by its `opencode acp` process.

### Agent crashed

```bash

# Check if session exists

tmux has-session -t agent-ISSUE-123 2>/dev/null && echo "Running" || echo "Not running"

# If dead, check workspace for clues

cd /path/to/workspaces/ISSUE-123

cat .pan/context.md

cat .pan/continue.json

# Resume with new agent

pan start ISSUE-123

```

### Multiple agents for same issue

```bash

# List all

tmux list-sessions | grep ISSUE-123

# Kill duplicates

tmux kill-session -t agent-ISSUE-123-old

```

---

## Dashboard Issues

### Dashboard won't start

```bash

# Check port availability

lsof -i :3010 # Frontend

lsof -i :3011 # Backend API

# Kill processes using ports

kill $(lsof -t -i:3010) 2>/dev/null

kill $(lsof -t -i:3011) 2>/dev/null

# Start fresh

cd ~/.overdeck/dashboard

npm run dev

```

### "CORS error" in browser

```bash

# Check API is running

curl http://localhost:3011/api/health

# Check frontend is pointing to correct API

# Should be http://localhost:3011

# Try different browser or incognito mode

```

### Dashboard shows stale data

```bash

# Restart the API server

pkill -f "node.*dashboard.*server"

cd ~/.overdeck/dashboard/server && npm run dev

# Hard refresh browser

# Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)

```

### WebSocket not connecting

```bash

# Check server logs

cd ~/.overdeck/dashboard/server

npm run dev 2>&1 | grep -i websocket

# Check firewall

sudo ufw status

```

---

## Skill Issues

### Skills not showing up

```bash

# Check sync status

pan skills

# Re-sync

pan sync --force

# Verify symlinks

ls -la ~/.claude/skills/ | grep overdeck

# Check Claude Code recognizes them

# Restart Claude Code after syncing

```

### "Skill already exists"

```bash

# Check what's there

ls -la ~/.claude/skills/skill-name

# If it's a project skill, symlink won't be created (by design)

# If you want to override, remove the project skill first

```

### Skill not triggering

```bash

# Check trigger patterns in SKILL.md

cat ~/.overdeck/skills/skill-name/SKILL.md | head -20

# Ensure you're using exact trigger phrases

# Try: /skill-name instead of natural language

```

---

## Network Issues

### Can't reach Linear API

```bash

# Test connectivity

curl -v https://api.linear.app/graphql

# Check DNS

nslookup api.linear.app

# Check proxy settings

echo $HTTP_PROXY $HTTPS_PROXY

```

### Traefik not routing

```bash

# Check Traefik is running

docker ps | grep traefik

# Check Traefik logs

docker logs traefik

# Verify DNS resolution

ping myapp.overdeck.localhost

# Check /etc/hosts

grep overdeck.localhost /etc/hosts

```

### WSL2 networking

```bash

# Get WSL2 IP

hostname -I

# Check Windows can reach WSL2

# From Windows: ping <wsl-ip>

# Port forwarding (from Windows PowerShell as Admin)

netsh interface portproxy show all

```

---

## Collecting Diagnostics

For bug reports, collect:

```bash

# System info

echo "=== System ===" > diagnostics.txt

uname -a >> diagnostics.txt

node --version >> diagnostics.txt

npm --version >> diagnostics.txt

# Config (redact secrets!)

echo "=== Config ===" >> diagnostics.txt

cat ~/.overdeck.env | sed 's/=.*/=REDACTED/' >> diagnostics.txt

# Status

echo "=== Doctor ===" >> diagnostics.txt

pan doctor >> diagnostics.txt 2>&1

# tmux

echo "=== tmux ===" >> diagnostics.txt

tmux list-sessions >> diagnostics.txt 2>&1

# Skills

echo "=== Skills ===" >> diagnostics.txt

ls -la ~/.overdeck/skills/ >> diagnostics.txt

ls -la ~/.claude/skills/ >> diagnostics.txt

cat diagnostics.txt

```

## Related Skills

- `/pan:health` - Quick health check

- `/pan:install` - Reinstallation

- `/pan:setup` - Configuration