/hermit-doctor

name: hermit-doctor
description: Runs the hermit's read-only health checks (runtime, config, hooks, state integrity, cost and spend, scheduling and watchdog, channels, credentials, permissions, docker, backup) and reports the summary. Use when diagnosing an install, before a release, or after suspicious behavior. Activates on messages like "/hermit-doctor", "health check", "diagnose the hermit", "what's wrong", "run diagnostic".

Record notes only inside an open record's turn, using `bun ${CLAUDE_PLUGIN_ROOT}/scripts/task.ts note .claude-code-hermit <id>` with the note on stdin. Otherwise skip record notes. Never edit a task file directly.

Hermit Doctor

Runs read-only health checks against the current hermit install (`channel-liveness` is the only one that performs outbound API calls — see Notes) and surfaces the summary. Safe to run at any time. Produces no side effects beyond writing `.claude-code-hermit/state/doctor-report.json` and `.claude-code-hermit/state/doctor-alerts.json`, and appending a summary block to the open task record.

Notification route

A finding gets one notification per unresolved episode: the check script records it, you send it once, and it stays silent until it resolves. A send that never reached the operator is re-offered on the next run rather than counted as delivered. Every run sends the same two-leg notice and `channel-send.ts` resolves each leg against this install's own config: the maintainer leg reaches the configured `maintainer_channel_id`, else the primary chat on a `technical` profile (the client leg is dropped there, since both landed in one chat), else `state/watchdog-events.jsonl` on a `non-technical` one. A configured maintainer destination that is unreachable fails closed to `state/watchdog-events.jsonl` and never spills into the primary chat.

`--maintainer` is accepted and ignored (routine strings may still pass it): audience is decided by the row's own tier and the operator's config, not by the flag.

Steps

1. Run the check script:

   bun ${CLAUDE_PLUGIN_ROOT}/scripts/doctor-check.ts .claude-code-hermit

The script writes `.claude-code-hermit/state/doctor-report.json` and prints the same JSON to stdout. It exits 0 unconditionally — on any internal failure the failing check reports `status: "fail"` in its own entry rather than crashing the report.

2. Parse the JSON. For each check in the report (one entry per id), emit one line using this format:

• `✓ <id> — <detail>` when `status: ok`
• `⚠ <id> — <detail>` when `status: warn`
• `✗ <id> — <detail>` when `status: fail`

3. Inside an open record's turn, record the per-check summary with `task.ts note .claude-code-hermit <id>`. Otherwise skip the note.

4. Return the per-check lines to the caller and nothing else.

5. **Escalation.** The script already computed this — do not recompute it, and do not write alert state yourself. Read the `escalation` object from the step-1 JSON:

• `escalation.new` — findings owed to the operator, each `{id, status, detail}` plus an

optional `tier`. Empty means everything currently failing has already been announced; say nothing.

• `escalation.resolved` — check ids whose finding cleared. Recorded, never announced: there is

no "recovered" ping.

• `escalation.persisted: false` — the ledger could not be written. `prior_state_known: false` —

the ledger was unreadable and had to be rebuilt, so what was already announced is unknown. **On either, send nothing** and let the maintainer fallback record the findings in `state/watchdog-events.jsonl` instead; a notification you cannot dedup would repeat every run.

**When `escalation.new` is non-empty.** Compose one complete, concise summary covering every listed check, its detail, and a named next action, in the operator's configured language. When the finding is `classifier-denials`, name what was blocked by kind: a `bun` block is usually a hermit script, a call-shape/upstream matter the hermit reports; interpreter heredocs (`python3`, `node`) are something the hermit stops doing itself; an operator's own host needs an `autoMode.environment` entry naming it, added to `~/.claude/settings.json` from the terminal. Never offer to add classifier context on a chat reply.

**Rows carrying `tier: "maintainer"` go on the maintainer leg only.** Their content is what the `PermissionDenied` hook already keeps off a client chat, so the payload splits by audience and `channel-send.ts` decides where each leg lands (§ Notification route).

**Before sending, check the completed payload.** Use the configured language already in context (including the worker's language instruction); if unavailable, read only `config.language`. When unset, match the operator's conversation language. Check both `client` and `maintainer` prose and correct any language mismatch before sending. Only literal diagnostic excerpts may stay quoted in their original language; explanations and next actions must use the target language. Preserve identifiers, commands and paths. Keep a concrete next action for each finding; a `warn` status alone does not establish that it is minor or causes no blockage. Do this in the current turn, without another agent or model call.

Deliver it once through the canonical notice path:

   bun ${CLAUDE_PLUGIN_ROOT}/scripts/channel-send.ts .claude-code-hermit --notice

One payload, whatever the invocation: `{"client": "<plain headline for the rows without a tier, plus the one next step>", "maintainer": "<complete summary, every row>"}`. The client leg is the only part of this notice that can land in a client chat, so write it to the channel voice rule — no check ids, file paths, USD or token figures; what is wrong in plain words and what the operator should do about it. The maintainer leg is the complete richer version of the same notice, never a tiered-rows