feat: panopticon doctor preflight command and fail-fast spawn errors

[tildesrc]

Summary

panopticon doctor — a preflight self-check for a pip-installed operator host, oriented around the question "can panopticon quickstart and the setup-repo workflow succeed here?"

• Host prerequisites (hard FAIL; the only thing that sets a non-zero exit) — Docker, git, tmux, and the claude CLI. setup-repo is a shell workflow the session service runs on the host to exec claude setup-token, so quickstart's final step needs claude present; remediation points at https://claude.ai/install.sh.
• Setup status (non-fatal WARN) — the panopticon-base image, the task service, and per-repo tokens. Before first start none exist yet (the base image is auto-built on first spawn; the service is started by panopticon start; the token is what setup-repo mints), so doctor reports them as a "here's what quickstart will do" checklist rather than red-flagging a machine that simply hasn't run quickstart. A fresh host with the four tools installed exits 0.
• doctor fetches repos lazily — only after the task service check passes — so the offline-before-first-start case reports cleanly instead of crashing.

Fail-fast spawn errors (defense-in-depth for container tasks):

• The spawner checks the env-file for a recognisable CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY before spawning a container task (the shell setup-repo path is exempt), and LocalRunner.spawn() checks the image exists and tmux is available before docker run/tmux. Missing preconditions surface as a legible LifecyclePhase.FAILED detail in the dashboard (referencing panopticon doctor) instead of a silently idle container.

Also wires make doctor (dev convenience) into the Makefile and updates docs/macos-setup.md.

Plan: plan.md

🤖 Generated with Claude Code

[tildesrc]

Code review — panopticon doctor + fail-fast spawn errors

Verdict: Request changes (one must-fix; otherwise solid). mypy strict is clean and the relevant 98 tests pass on the branch. LLM-free placement, clean command-runner injection, long-form flags, and no token leakage — all good; plan criteria essentially met.

Must-fix

• panopticon doctor crashes when the task service is down. terminal/__main__.py:47 evaluates client.list_repos() eagerly before any check runs, so an unreachable task service — doctor's headline use case — raises httpx.ConnectError and dies with a traceback instead of printing [FAIL] Task service not reachable … Run: make serve. Fetch repos defensively (e.g. run check_task_service first, then list repos, skipping the per-repo checks with a note when the service is down) and add a test. This path is currently untested — every test_doctor test passes a pre-fetched repo list, so the crash isn't caught.

Nits (non-blocking)

• Spawner fail-fast checks token presence but not shape (spawner.py _check_env_file_token). A malformed CLAUDE_CODE_OAUTH_TOKEN=garbage passes the pre-spawn check, the container spawns, and the agent 401s — exactly the silent-idle failure mode criterion 2 targets. doctor already has _TOKEN_PATTERNS; consider reusing it in the spawner, or noting the divergence deliberately.
• Env-file mode check is exact-equality (doctor.py:172, if mode != 0o600) — a stricter 0o400 file is reported FAIL. mode & 0o077 (reject any group/other access) matches the intent better.
• Minor: env-file line parsing is duplicated across spawner._check_env_file_token and doctor.check_repo_env_file (different packages, so sharing is awkward — acceptable).

Nice work on the test isolation and the actionable remediation messages.

🤖 Automated review via Claude Code