pai-doctor

name	pai-doctor
description	Health probe suite for the PAI ecosystem. Use when user says doctor, is everything ok, health check, what's broken, pai status.

pai-doctor skill

When to use

User intent:

• "doctor", "health check", "is everything ok", "what's broken"
• "pai status", "ecosystem state"
• Before launching an expensive task (verify pai-anywhere is up before omc ralph)
• Cron-driven daily health digest (pair with pai-statusline-banner)

What it runs

pai-doctor has no standalone script and is not itself on $PATH. It shells out to the installed pai-anywhere binary, which has two modes:

• pai-anywhere doctor [--json] — read-only host inspection (18 checks). Exit 0.
• pai-anywhere doctor --post-install [--json] (alias pai-anywhere verify) — install-integrity probes (15). Exit 2 if any probe fails.

Prefer --json and read the checks / probes array; each item is {id, title, status, summary, details?}. The plain-text form ends with Summary: N pass, M warn, K fail, … (info in host mode, skip in post-install). There is no --fix flag — do not pass one.

Host inspection — pai-anywhere doctor (18 checks)

• host: host.os, host.user
• deps: dep.bun, dep.git, dep.tailscale, dep.fail2ban, dep.ufw
• network / security: tailscale.status, tailscale.serve, network.listeners, pulse.bind, firewall.ufw, hardening.fail2ban, ssh.dropin
• profile / manifest: profile.existing_claude, profile.managed_user, profile.managed, manifest

Install integrity — pai-anywhere doctor --post-install (15 probes)

• profile: profile.exists, profile.isolated, profile.user_claude_preserved
• PAI: pai.claude_md, pai.system_prompt, pai.algorithm_latest, pai.settings_json, pai.hooks_configured, pai.hook_files
• pulse / gateway: pulse.loopback, pulse.health, gateway.service, gateway.auth_gate
• tailscale / manifest: tailscale.private_serve, manifest.valid

Status values: pass, warn, fail, plus info (host mode) / skip (post-install).

Execution

Via the Hermes terminal toolset: pai-anywhere doctor --json (add --post-install for integrity). ~1–2s on a Linux VPS. Zero AI cost.

Terminal blocked by Tirith? On pending_approval / pattern_key: "tirith:unknown", run it through execute_code: subprocess.run(["pai-anywhere","doctor","--json"], capture_output=True, text=True, timeout=10). Do not retry terminal unchanged.

Output

Translate the pai-anywhere JSON into the digest schema pai-statusline-banner consumes:

schema: pai-hermes.doctor.v1
generatedAt: ISO-8601
passCount / warnCount / failCount: integer
probes: array of {id, title, status}

Or just extract the final Summary: counts for a one-line report.

Caveats

• pai-anywhere must be installed and on $PATH. If absent, fall back to a minimal check: Pulse loopback HTTP 200 + $PAI_PROPOSALS_DIR writable.
• Some checks legitimately warn/skip/info on a headless VPS (no audio, Tailscale Serve not configured yet, managed PAI profile not created).
• pulse.bind / pulse.loopback expect Pulse on loopback (127.0.0.1:31337); a non-loopback bind is flagged.
• --post-install exits 2 when any probe fails — treat exit 2 as "fails present", not as a failure to run the tool.

Triggers in Hermes natural language

• "pai doctor" → run host inspection
• "is the system ok?" → run + summarize warns/fails
• "what's broken with PAI" → run --post-install, focus on fail probes
• "before I ralph, verify pai-anywhere" → pai-anywhere verify before chaining to omc