pan-restart git:20260717.bdd780aA

Immutable. This exact content is served forever at /api/v1/blob/333d65c763b04387.

---
name: pan-restart
description: "pan restart — scoped restart (dashboard by default; --cliproxy, --traefik, or --full) that will not strand shared sidecars"
---

# Restart Overdeck

Use this whenever a Overdeck component needs to be restarted. The `pan restart`
command is scope-aware: by default it restarts **only the dashboard** and leaves
CLIProxy, Traefik, and TLDR running — so a dashboard restart cannot strand the
system or kill unrelated dependencies.

## Canonical paths

| Situation                                                        | Command                        |
|------------------------------------------------------------------|--------------------------------|
| Dashboard restart (rebuild, stale state, `EADDRINUSE` on 3010/3011) | `pan restart`                  |
| GPT-routed agents returning 502s (CLIProxy died)                 | `pan restart --cliproxy`       |
| `.localhost` routing / Traefik changes                           | `pan restart --traefik`        |
| Whole-stack rebuild (use sparingly — stops CLIProxy & Traefik)   | `pan restart --full`           |

## Execution

```bash
# Build first if dashboard server or CLI code changed
cd ~/Projects/overdeck && npm run build

# Dashboard-only restart (safe — leaves CLIProxy, Traefik, TLDR running)
pan restart

# Scoped alternatives
pan restart --cliproxy
pan restart --traefik
pan restart --full       # nuclear — stops & restarts everything

# Explicit force cases
pan restart --force              # bypass the agent deploy-window gate
pan restart --cliproxy --force   # redownload the pinned CLIProxy binary
```

Each stage is health-gated: the command waits for `GET /api/health` (dashboard)
or port binding (CLIProxy) to succeed before reporting `✓`, and exits non-zero
with a `[stage] reason` message on timeout.

## Identity guard

When `pan restart` would restart the dashboard, it refuses to run from a
non-primary checkout: either a workspace worktree or any linked Git worktree,
including a handoff worktree. It exits with code 2 and names the primary
checkout where the command must run.

The post-boot health gate verifies both `repoRoot` and `mode` from
`GET /api/health`. If another server holds the port, the command reports
`port held by non-primary server (cwd=…, mode=…)`; a 200 response from the wrong
server is a failure, not a successful restart.

## Important Notes

- `pan restart` is idempotent: it stops the old listener(s), starts a new one,
  then polls until the health check passes.
- `pan restart --dashboard` NEVER touches CLIProxy, Traefik, or TLDR — that
  scope contract is enforced by tests.
- Agent-issued dashboard and full restarts consult the deploy-window gate before
  acquiring the restart lock. Active verification, merge, post-merge, flywheel,
  restart, or `pan dev` ownership refuses the restart because it would disconnect
  live conversations and terminals; `--force` explicitly bypasses this gate.
- For `--cliproxy`, `--force` has a separate meaning: it redownloads the binary at
  the pinned version before restarting it.
- If the dashboard restart fails, shared sidecars are left running so recovery
  is possible with another `pan restart` once the root cause is fixed.
- NEVER use `pkill -f "node.*server"` — it can kill unrelated Node processes.
- Prefer `pan restart` over `pan down && pan up` whenever you only need to
  cycle one component. `pan down && pan up` tears down everything and takes
  longer to recover.