/dex-doctor

name: dex-doctor
description: "Whole-system checkup: verifies every Dex feature honestly (working/off/broken/couldn't-check), self-heals what's provably safe, guides the rest. Use when the user says 'is Dex healthy', 'something's broken', 'check my setup', 'run diagnostics'. Not for discovering unused *features*; use `dex-level-up`. Not for applying an update; use `dex-update`."

/dex-doctor — Full System Checkup

Diagnose everything, heal what's safe, guide the user through the rest.

Purpose

One honest answer to "is my Dex actually working?" Built against the failure modes found in the July 2026 audit: checks that never ran, checks that probed an easier path than the real feature, "off" reported as "broken", and background jobs that died silently for months.

When to Run

• User asks "is everything working?", "what's broken?", "check my setup"
• Something feels off — features silently not happening
• After an update, migration, or machine change
• User invokes `/dex-doctor` directly

Cardinal rules

1. **Never report "off" as a problem.** A feature the user never enabled is healthy. List it under "Off — that's fine", once, without nagging. 2. **Never hide "couldn't check".** If a probe failed to run, say so prominently. An unknown presented as a pass is how watchdogs go blind. 3. **Never claim a heal worked without re-checking it.** 4. **Heal conservatively.** Tier 1 only automatically. Tier 2 only after an explicit yes, one item at a time. Tier 3 is always the user's hands. Never delete or overwrite user data; never touch credentials.

Credential scan mode

Credential scanning is local and read-only. Inspect the worktree, index, approved Git common directory and primary object database, reachable refs, stashes, tags, and only archives the user explicitly selects. Report opaque redacted finding IDs plus explicit inspected and uninspected scope categories; never print paths or matched values. Existing `.mcp.json` is scan/report-only and remains byte-identical.

Render migration, security, active `.mcp.json` residual, and optional history hygiene as separate deterministic states using `render_credential_status`; do not paraphrase it. Provider revoke/rotate is always user-driven. Replacement health is read-only and runs only after the user explicitly chooses a remediation check. History cleanup is optional privacy hygiene, never a current-danger warning or prerequisite. Use only a preinstalled `git-filter-repo`, after verified restrictive bundle backup and typed consent; never install it, push, or force-push. If migration capability fails, scanning and guidance remain available and Doctor names the failed capability with manual move/validation/rewind steps.

For an optional cleanup request, use the in-process contracts in `core.utils.history_hygiene`; never interpolate revoked values into a shell command. Run `prepare_history_cleanup` only when security is `remediated`, after the user explicitly chooses the exact `refs/heads/*`, `refs/tags/*`, or `refs/stash/*` refs and confirms either verified external-backup evidence or no-external-backup acknowledgement. Show the returned opaque transaction ID, selected refs, recovery-bundle evidence, and this exact consent string:

`CLEAN OPTIONAL HISTORY <transaction-id>`

If `prepare_history_cleanup` returns `optional-tool-unavailable` or `optional-platform-unsupported`, surface its `guidance` verbatim and stop; both are calm honest states, never a current-danger warning. `optional-platform-unsupported` means this operating system lacks the directory file-descriptor substrate the guided path needs (it runs on Linux, including WSL2 or a Linux container; macOS is not supported). No recovery state was created; offer the manual advanced path and note that history cleanup is optional privacy hygiene.

Call `apply_history_cleanup` only after the user types that string exactly. Preparation must have already produced and verified the mode-`0700` transaction directory and mode-`0600` `history.bundle`, `objects.json`, and `manifest.json` under `System/.dex/adoption/history-backups/<transaction-id>/`, while passing the 10 GiB shared-cap and 1 MiB free-space margin checks. Apply must preserve Git remote configuration and never fetch, push, force-push, install software, or call a provider.

The verified bundle and manifest cover every restorable ref, not only selected refs, and include restrictive config/index recovery artifacts plus opaque HEAD/index/tracked-worktree/remote state authority. Apply still passes only the explicitly selected refs to `git-filter-repo`. Any changed unselected branch, tag, stash, remote-tracking, replace, notes, backup, or other ref—or any HEAD, index, tracked-worktree, or remote-config collateral—must return `recovery-required`, never a clean result. Credential equality is memory-only; no value-derived digest or replacement file may be persisted.

Render the post-cleanup rescan result exactly as `history-clean`, `history-cleanup-pending`, or `history-scope-unknown`. If apply is interrupted or reports `recovery-required`, lead with “Do not push.” Preserve the bundle and call `rewind_history_cleanup` only through its exact-ref guard. If that guard refuses, give the returned manual verified-bundle recovery guidance; do not improvise ref updates. Always state that history rewind does not reverse provider rotation.

Retention is a separate explicit operation. `preview_retention` protects the newest history bundle and selects only verified bundles older than 90 days with two later successful release activations and valid backup posture. Call `delete_retention_candidates` only with the unchanged candidate tuple and exact-set SHA-256 that the user acknowledged. Never auto-delete or upload a recovery bundle.

Execution

Step 1: Run the collector (quick mode + safe auto-heals)

cd "$VAULT_PATH" && .venv/bin/python core/utils/doctor.py --heal 2>/dev/null \
  || python3 core/utils/doctor.py --he