jorinyang/dsh-doctor

---

DSH crashed? Can't start?

Two commands to catch your emotions and fix the root cause.

# ① Install
dsh plugin --profile web add @jorinyang/dsh-doctor

# ② Fix
dsh-doctor

Built-in CLI, auto-registered to system PATH on install. Repairs are fully reversible — roll back anytime.

---

💡 What it is

DeepSeek Harness ships no built-in doctor command. When DSH crashes, fails to start, or a plugin breaks the profile, you're left staring at errors and hoping a restart will help.

dsh-doctor is the first all-in-one "diagnose + repair + rollback" tool for DSH, and it's also a runtime self-healing service:

---

✨ Why dsh-doctor

🎯 Two commands to revive a crashed DSH

No need to read error logs or hand-edit configs:

dsh-doctor          # diagnose first
dsh-doctor fix      # then repair

↩️ Reversible repairs — safe to fix

Every fix writes a journal recording the undo step of each change. Broke something? One command to undo:

dsh-doctor rollback              # undo the most recent repair
dsh-doctor rollback --list       # list all journals
dsh-doctor rollback --id <id>    # undo a specific journal

⚡ Runtime self-healing — works while DSH is alive

Not just stop-and-fix. dsh-doctor wires into Cordis's native runtime:

• ctx.provide('dsh-doctor') — expose diagnose/repair/rollback to other plugins
• ctx.on('internal/status') — reactive plugin-lifecycle monitoring with FAILED alerts
• ctx.effect() — reversible effects, no residue on unload

🌍 Cross-platform, zero config

Auto-registers to system PATH on install — Windows / macOS / Linux / fish.

---

🚀 Quick start

Option A: DSH plugin (for the agent)

# install from npm
dsh plugin --profile web add @jorinyang/dsh-doctor

# restart dsh web
dsh web

Then ask the agent:

run dsh_doctor                     # diagnose
run dsh_doctor_fix with scope safe # repair
run dsh_doctor_rollback            # rollback if needed

Option B: global CLI

npm install -g @jorinyang/dsh-doctor
# or
npx @jorinyang/dsh-doctor

Demo

$ dsh-doctor diagnose --profile web

DSH Diagnostic Report  (profile: web, port: 3080)
DSH home: ~/.dsh

  [OK]   Node.js v24.15.0
  [OK]   pnpm 11.9.0
  [OK]   DSH 0.1.0-rc.6
  [OK]   DSH home exists
  [OK]   profile dir exists: web
  ...
  [XX]   bundle missing: some-broken-plugin
         fix: Run pnpm install in profile dir

  48 pass  0 fail  3 warn
  ✓ No blocking issues found; DSH should start normally.

---

📖 Command reference

Options

Repair scopes

---

🏗️ How it works

dsh-doctor aligns with DeepSeek Harness / Cordis's Spatiotemporal Composability paradigm:

flowchart LR
    subgraph CLI["🔧 dsh-doctor CLI (offline)"]
        D[Diagnose]
        F[Repair]
        R[Rollback]
    end

    subgraph Runtime["⚡ Runtime service (online)"]
        SVC[dsh-doctor service]
        WATCH[Lifecycle monitor]
    end

    DSH["🖥️ DeepSeek Harness"]

    D -->|finds issues| F
    F -->|writes journal| R
    R -->|LIFO restore| DSH
    F -->|reversible changes| DSH

    SVC -->|diagnose/repair/rollback| DSH
    WATCH -->|internal/status| DSH

Temporal — reversible repairs

Every change records a reverse undo function; rollback replays LIFO:

• overwritten file → original saved, restored on rollback
• created file/dir → deleted on rollback (empty dirs only)
• system-boundary ops (pnpm install, killed processes) → flagged manual

Spatial — runtime self-healing

Wires into Cordis primitives to declare deps and react to changes:

• ctx.provide — provide services
• ctx.on — reactive listeners
• ctx.effect — reversible effects

---

🆚 vs. traditional approaches

---

❓ FAQ

Q: DSH is so broken the plugin can't load — still usable?

Yes. dsh-doctor is a self-contained CLI that doesn't depend on DSH running. Just run dsh-doctor fix.

Q: Will repair break my config?

No. Every reversible change records an undo step first. dsh-doctor rollback restores it.

Q: safe / deps / full — which to pick?

Start with safe (files/config only, zero risk). Escalate to deps (reinstall) then full (process cleanup) only if needed.

Q: Does it conflict with built-in DSH commands?

No. It's an independent plugin + CLI; it doesn't modify DSH core.

---

🤝 Contributing

Issues and PRs welcome. For bug reports, please include dsh-doctor diagnose output.

📄 License

MIT

---