DSH Doctor

Deterministic diagnostics and recovery for DeepSeek Harness.

DSH Doctor is the safety net for the two ways a Harness usually breaks itself: it cannot converse (the Web UI opens but the loop is broken), or it cannot start (boot fails after a config, dependency, or plugin change). When the Web UI still opens, the Doctor button calls a loopback-only Host recovery service. When Harness cannot start, the same engine runs as a standalone CLI — including a boot probe that captures the failure and a one-click reset to the last healthy checkpoint, so plugin developers can experiment and always get back to a working state.

> DSH Doctor 0.2.0 targets @deepseek-ai/dsh 0.1.0-rc.6. DeepSeek Harness is a developer preview; unknown versions are scanned in conservative read-only mode.

简体中文

Install

Add Doctor to the Web profile:

dsh plugin --profile web add dsh-doctor
dsh --profile web

This installs one package with both Host and browser halves. It contributes:

• a persistent Doctor action beside Settings in the sidebar;
• an automatic recovery banner above the composer after a prompt or Agent failure;
• a full Doctor page in Settings with findings, checkpoints, and rollback;
• a floating emergency entry that appears in the frame overlay whenever the profile is broken, independent of the sidebar and conversation plugins.

If the Web UI cannot start:

npx dsh-doctor recover --profile web

CLI

# Scan one profile (offline and path-anonymized by default)
npx dsh-doctor scan

# Probe whether the Harness can boot and diagnose the failure from its output
npx dsh-doctor boot

# One-click recovery: reset configs to the healthy checkpoint, reconcile
# dependencies, then verify the boot again
npx dsh-doctor recover --profile web
npx dsh-doctor recover --profile web --yes   # also apply confirmed actions

# Snapshot the current profile as a healthy recovery baseline
npx dsh-doctor checkpoint --profile web

# Start the Harness; diagnose automatically when it fails to boot
npx dsh-doctor launch --auto-recover

# Restore a checkpoint
npx dsh-doctor rollback <checkpoint-id>

recover runs the safe actions with zero confirmation, then verifies the result by booting the Harness when it was down. The exit status is 1 when errors remain (or boot verification fails), warnings return 0 unless --strict is used, and invalid arguments or internal failures return 2. JSON output is available with --json.

What v0.2.0 checks

• Node, platform, Harness version and profile discovery;
• profile manifest, bundle shape, cordis.yml, cordis.patch.yml, and pnpm workspace syntax and permissions;
• missing dependencies, duplicate bundles, and broken profile links;
• live Cordis plugin phases when called from the Web UI;
• boot failures via a real boot probe (port watch + captured output mapped to repair actions);
• session records (session.jsonl.zstd) and storage caches for corruption;
• recent local fatal/plugin-failure log markers;
• non-registry and external plugin sources (flagged, but never blocking recovery);
• model route/credential state and an optional, tiny, non-session probe that verifies the model actually answers.

Recovery

Every mutation follows the same transaction:

1. Re-check the plan expiry and hashes of profile files. 2. Create a private pre-repair checkpoint. 3. Apply only selected actions. 4. Run a fresh structural scan (and boot verification when the Harness was down). 5. Roll back automatically when verification fails.

Safe one-click actions prepare Doctor state and reset the profile configuration to the latest healthy checkpoint. On a cold start with no healthy checkpoint, Doctor can synthesize minimal valid config files — after explicit confirmation, with the broken originals preserved in the pre-repair checkpoint. Dependency installation, disabling a boot-crashing plugin, quarantining a corrupt session file, and re-enabling a Doctor-disabled plugin require explicit confirmation. Doctor refuses to disable the connection, layout, settings, conversation, runtime, module-loader, or Doctor rescue entries.

Checkpoints are stored locally under $DSH_HOME/doctor/checkpoints/, with ten retained per profile and the newest healthy checkpoint always kept. They may contain exact copies of local configuration so that rollback is byte-accurate; they are never included in reports or uploaded. API keys are never printed, changed, or sent by Doctor.

See [Recovery matrix](./docs/RECOVERY_MATRIX.md) and [Security policy](./SECURITY.md).

Development

Requires Node 24 and pnpm.

pnpm install
pnpm check
npm pack --dry-run

License

MIT