dsh-doctor

Self-healing watchdog for the DeepSeek Harness web profile. Recovers from plugin-induced boot failures within a 60-second downtime budget. Captures every tool error through the official tools/* event hooks. Watches every live session and nudges stuck turns back to life. (A dsh doctor CLI subcommand for already-broken installs is planned for v0.3.0.)

dsh-doctor runs as an independent Node process (LaunchAgent on macOS, systemd user unit on Linux, Task Scheduler on Windows) so it survives even when dsh web cannot spawn a child. It is fully independent of dsh-daemon: it does not call it, does not require it, and does not conflict with it. If both are installed, you get layered protection.

---

Table of contents

• What it does
• When to use it
• Install
• Usage
• Architecture
• Configuration
• Tools
• Tool error handling
• Session watching
• Safety guarantees
• Troubleshooting
• Roadmap
• Development
• Contributing
• Security
• License

---

What it does

Four jobs, in one plugin:

Job	Where it runs	Time budget	Trigger
1. Web boot recovery	Standalone Node process (LaunchAgent / systemd / Task Scheduler)	60 seconds per incident	dsh web health probe fails N times in a row
2. CLI doctor	(planned for v0.3.0)	—	—
3. Tool error capture	In-process, attached to the tools/* cordis event waterfalls	Passive — never blocks the host	Any tool call fails in any session
4. Live session watch	In-process, attached to session/event	Tick every 30 s, no events lost	A turn is running with no new event for watchIdleThresholdMs (default 3 min)

1. Web boot recovery (60 s budget)

Every 30 s the watchdog probes http://127.0.0.1:$DSH_WEB_PORT/health. After 3 consecutive failures it enters the triage state machine, with a hard 60-second ceiling on total downtime per incident.

Simple path (~10 s) — the most common case, a single broken plugin:

1. Read the last 200 lines of the dsh web log.
2. Run triage against a regex pattern table (EADDRINUSE, duplicate loader entry, schema parse error, module-not-found, plugin load error, …).
3. If the failing bundle is identified, disable that single row in ~/.dsh/profiles/web/cordis.patch.yml (write the change to a sibling cordis.patch.yml.dr-disabled-<bundle> file — your original is never edited).
4. Restart dsh web. The boot succeeds because the offending bundle is gone.

Complex path (≤60 s) — multiple bundles, the simple path didn't work, or the failure is unknown:

1. Drop a safe-mode patch into the profile that overrides every bundle with a no-op config (safeMode: true), except an explicit allow-list (safeModeBundles, default ["dsh-core"]).
2. Restart dsh web. The profile boots in safe mode — all your dsh_doctor_* tools are still available, every other plugin is silenced.
3. Write a restart-lock marker so a dsh doctor invocation running in parallel can skip the 60 s budget and work unbounded until safe mode is gone.

Invariants enforced on every recovery:

• The watchdog only kills the PID it reads from ~/.dsh/profiles/web/.dsh-web.pid. It never invokes pkill, killall, or any pattern-killer.
• A sibling file pattern means your real cordis.patch.yml is never silently mutated. Inspect / revert at any time.
• If 60 s elapses without a healthy probe, the watchdog backs off and retries on the next probe tick instead of thrashing.

2. CLI doctor (planned for v0.3.0)

⚠️ Not shipped yet. A future release will add a dsh doctor subcommand that runs the same triage + recovery engine in the foreground with no time budget, for users whose dsh web is so broken it never even started. Today, the only recovery path is the in-process plugin + standalone watchdog (jobs 1 + 3 + 4 above).

Until then, the recommended way to recover a completely dead install is: ask any working dsh agent to call dsh_doctor_diagnose to identify the failing bundle, then manually disable that bundle in ~/.dsh/profiles/web/cordis.patch.yml and dsh web to restart.

Track progress: https://github.com/d86e/dsh-doctor/issues

3. Tool error capture

Every tool call in dsh passes through a tools/* cordis event waterfall. dsh-doctor subscribes to tools/execute and tools/post-execute and runs every failed result through a classifier (default: transient / agent / business) and a policy (default: record + log, optionally defer). The doctor never mutates the waterfall itself — it observes.

The 9th model-facing tool, dsh_doctor_drain_deferred(sessionId), lets the agent pull queued errors at a quiet moment in the current turn and decide what to do.

4. Live session watch

Every session in the dsh process emits a session/event (turn/start, turn/end, tool/call, tool/result, user/message, assistant/message, …). dsh-doctor keeps a per-session state machine:

                    ┌──────────────┐
                    │  event fires │ ◀── every session event
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  reset idle  │
                    │   counter    │
                    └──────┬───────┘
                           │
              (every watchTickIntervalMs)
                           │
                    ┌──────▼───────────────────┐
                    │ is turn running?         │
                    │ is no-event-time > N?    │
                    │ cooldown elapsed?        │
                    │ nudgesSent < cap?        │
                    │ user is not currently    │
                    │ driving the session?     │
                    └──────┬───────────────────┘
                       yes  │
                    ┌──────▼────────────────────┐
                    │ agent.followup("继续")    │
                    │ count +1                  │
                    └───────────────────────────┘

The doctor does not write code, does not run commands, does not touch the model. It sends a 继续 user message through the same agent.followup primitive the dsh community's dsh-auto-continue uses. If the agent is in a true infinite loop, dsh_doctor_watch_cancel is also exposed for explicit user intervention.

Manual control tools are also exposed: dsh_doctor_watch_list shows every tracked session, dsh_doctor_watch_nudge lets you inject a custom message, dsh_doctor_watch_cancel aborts the current turn with kind: 'user' so it is not confused with a system stop.

---

When to use it

You want dsh-doctor if you:

• Have ever had a bad plugin update take down your dsh web for hours because you had to SSH in, read logs, edit JSON, and restart by hand.
• Run multiple plugins and want a layer between "broken plugin" and "completely dead profile."
• Run long, unattended agent tasks that occasionally get stuck waiting on a flaky network call or an interrupted LLM stream.
• Already use dsh-auto-continue and want a more thorough, self-contained solution (dsh-doctor subsumes its core logic — keep using both if you depend on its UI; or uninstall it once you upgrade to dsh-doctor ≥ 0.2.0).
• Want layered protection alongside dsh-daemon (they don't conflict; dsh-doctor also covers the "dsh web came up at all" case).

You do not want dsh-doctor if:

• You are on a single-plugin setup and prefer to fix breakage by hand.
• You want an "AI automatically debugs my DSH install" agent — that's a different product. dsh-doctor is a watchdog, not an AI.

---

Install

Option A — from git (recommended)

# Install into the web profile (the only profile dsh-doctor supports today)
dsh plugin --profile web add https://github.com/d86e/dsh-doctor.git
dsh plugin --profile web reload

You can pin a version with a git ref:

# Pin a specific tag
dsh plugin --profile web add https://github.com/d86e/dsh-doctor.git#v0.2.0

# Or a branch
dsh plugin --profile web add https://github.com/d86e/dsh-doctor.git#main

The doctor is published as a git repository rather than an npm package because DSH plugins are loaded as cordis.patch.yml composition rows by the host process — they never need to be require()'d from a node_modules tree. Git install keeps the version control simple: a git pull && dsh plugin reload is the entire upgrade story.

That's the entire install story. On the very first load, the doctor plugin automatically:

1. Writes ~/.dsh/doctor/watchdog.js (standalone dep-free Node).
2. Writes the platform service spec (LaunchAgent on macOS, systemd user unit on Linux, Task Scheduler XML on Windows).
3. Registers and starts the service.
4. The service immediately starts probing http://127.0.0.1:3080/health every 30 s.

The auto-install runs as a detached child process so a slow launchctl or systemctl call never blocks dsh boot. It is idempotent — every subsequent plugin load checks for the script + service + running pid, and does nothing if everything is already in place.

The 12 dsh_doctor_* tools also register as soon as the plugin loads. You can call dsh_doctor_status from any agent to confirm:

> dsh_doctor_status
{
  "installed": true,
  "running": true,
  "pid": 25632,
  "platform": "darwin",
  ...
}

Opting out of auto-install

Set autoInstall: false in cordis.patch.yml:

- insert:
    - id: dsh-doctor
      name: '@d86e/dsh-doctor'
      config:
        autoInstall: false

or the env var DSH_DOCTOR_AUTO_INSTALL=0. You can then install the watchdog manually through the model-facing dsh_doctor_install tool:

> dsh_doctor_install

dsh_doctor_install supports dryRun: true to preview the writes without actually registering the service, and a purgeLogs: true flag in dsh_doctor_uninstall to also delete ~/.dsh/doctor/logs/.

Option B — npm package

If you prefer npm, the same source is also published as @d86e/dsh-doctor:

dsh plugin --profile web add @d86e/dsh-doctor

dsh plugin add accepts a git URL, a <owner>/<repo> shorthand, or an npm package name — they all end up in the same place.

Option C — dynamic (sandboxed one-off)

Useful for a single session, no install. Ask any agent:

> Use the dsh doctor from https://raw.githubusercontent.com/d86e/dsh-doctor/v0.2.0/lib/index.js

Then call dsh_doctor_install when you are ready to make it permanent.

---

Usage

After install, you can ask the agent:

> dsh_doctor_status
> dsh_doctor_diagnose
> dsh_doctor_watch_list
> dsh_doctor_safe_mode_enter
> dsh_doctor_drain_deferred

From a shell:

# (Planned) dsh doctor                  # unbounded CLI doctor (foreground)
# (Planned) dsh doctor --dry-run        # triage only, no writes

To uninstall:

> dsh_doctor_uninstall

---

Architecture

See docs/ARCHITECTURE.md for the full state machine, file layout, and inter-process protocol.

┌──────────────────────────────────────────────────────────────┐
│  dsh web process (cordis composition rows)                  │
│                                                              │
│   ┌────────────────────┐  ┌────────────────────┐            │
│   │ tools/ event hooks │  │ session/event hooks│            │
│   └────────┬───────────┘  └─────────┬──────────┘            │
│            │                       │                         │
│            ▼                       ▼                         │
│   ┌──────────────────────────────────────────────┐          │
│   │  dsh-doctor (apply)                          │          │
│   │   ├ tool error capture (waterfall listener)  │          │
│   │   ├ session watch (timer + ctx.agents)       │          │
│   │   └ 12 dsh_doctor_* tools                    │          │
│   └──────────────────────────────────────────────┘          │
└──────────────────────────┬───────────────────────────────────┘
                           │ (file-system state)
                           ▼
  ┌──────────────────────────────────────────────────┐
  │  $DSH_HOME/doctor/                               │
  │   ├ watchdog.js      standalone dep-free script  │
  │   ├ watchdog.pid     current watchdog pid       │
  │   ├ installed-marker  plugin-version stamp      │
  │   ├ stopped-marker   pause flag                 │
  │   ├ safe-mode.patch  auto-generated disable     │
  │   └ logs/                                        │
  │     ├ watchdog.log   (5MB × 3 rotation)         │
  │     ├ doctor.log     (5MB × 3 rotation)         │
  │     └ tool-errors.log                          │
  └──────────────────────────────────────────────────┘
                           ▲
                           │ (HTTP /health probe)
                           │
  ┌────────────────────────┴─────────────────────────┐
  │  watchdog.js (LaunchAgent / systemd / Task Sched) │
  │   - 30 s health probe                             │
  │   - triage + simple/complex recovery              │
  │   - no pkill, no killall, no remote fetch          │
  └────────────────────────────────────────────────────┘

---

Configuration

All knobs can be set either in cordis.patch.yml (under config:) or via DSH_DOCTOR_* environment variables.

Field	Env var	Default	Description
healthIntervalMs	DSH_DOCTOR_HEALTH_INTERVAL	30000	Health probe period
healthFailuresToRecover	DSH_DOCTOR_HEALTH_FAILURES	3	Failures before triage
recoveryBudgetMs	DSH_DOCTOR_BUDGET_MS	60000	Hard ceiling per incident (watchdog)
logMaxBytes	—	5242880	Per-log rotation size
logBackups	—	3	Rotated log files kept
safeModeBundles	—	["dsh-core"]	Bundles kept in safe mode
toolErrorCapture	DSH_DOCTOR_TOOL_ERROR_CAPTURE	true	Subscribe to tools/*
toolErrorMaxQueue	DSH_DOCTOR_TOOL_ERROR_QUEUE	500	Per-session queue cap
watchEnabled	DSH_DOCTOR_WATCH_ENABLED	true	Master switch for session watch
watchIdleThresholdMs	DSH_DOCTOR_WATCH_IDLE_MS	600000	Idle timeout (10 min)
watchNudgeCooldownMs	DSH_DOCTOR_WATCH_COOLDOWN_MS	300000	Min interval between nudges
watchMaxNudgesPerSession	DSH_DOCTOR_WATCH_MAX_NUDGES	3	Cap before giving up
watchContinueText	DSH_DOCTOR_WATCH_TEXT	"继续"	Text to inject (supports {elapsed}, {turn}, {sessionId})
watchTickIntervalMs	DSH_DOCTOR_WATCH_TICK_MS	30000	Idle-check period

Tool error classifier — replace it

If the default classification (network/5xx/429 → transient, 401/403/quota/context-overflow → agent, else → business) is wrong for your stack, pass your own classifier / policy when you register the plugin from a wrapper bundle. Both functions receive the full ToolErrorContext and return synchronously.

Session watch text — localize it

watchContinueText accepts the placeholders {elapsed} (seconds since last event), {turn} (current turn number), {sessionId}. So "已经过去 {elapsed} 了，请继续第 {turn} 步" works.

---

Tools

12 model-facing tools, all dsh_doctor_* prefixed.

Tool	Purpose
dsh_doctor_install	Generate the standalone watchdog and platform service
dsh_doctor_uninstall	Unregister, remove state files (logs optional)
dsh_doctor_status	Installed? running? uptime? last 5 recoveries? watch snapshot?
dsh_doctor_pause	Stop recovery, keep probing
dsh_doctor_resume	Re-enable recovery
dsh_doctor_diagnose	One-shot triage, no writes
dsh_doctor_safe_mode_enter	Manually drop a safe-mode patch
dsh_doctor_safe_mode_exit	Remove the safe-mode patch
dsh_doctor_drain_deferred	Pull queued agent-class tool errors for a session
dsh_doctor_watch_list	List every session the doctor is tracking
dsh_doctor_watch_nudge	Manually inject a "继续" message into a session
dsh_doctor_watch_cancel	Cancel the current turn of a session (kind=user)

---

Tool error handling

By default the doctor observes tool errors; it never retries and never mutates the waterfall. To change that, the installToolErrorCapture API is exported for wrapper bundles:

import { installToolErrorCapture, defaultClassify, defaultPolicy } from '@d86e/dsh-doctor/tool-errors'

installToolErrorCapture(ctx, config, log, {
  // user classifier: nil-pointers count as agent-class
  (ctx) => ctx.message.includes('panic') ? 'agent' : null,
}, defaultPolicy)

See src/tool-errors.ts for the full contract.

---

Session watching

The doctor keeps a per-session state machine in-process. It is read-only with respect to the model and the agent's tool calls — the only action it takes is agent.followup({content: [{type: 'text', text: '继续'}], source: {kind: 'user'}}).

Three protections against over-firing:

1. Cooldown — two nudges to the same session must be at least watchNudgeCooldownMs apart.
2. Cap — a session that has been nudged watchMaxNudgesPerSession times in its lifetime is left alone until the next turn/end:completed.
3. User override — if a real user/message (source.kind === 'user') arrived within 5 s of the candidate nudge time, the doctor steps back and assumes the human is driving.

The watch is degrades silently if the dsh host does not expose ctx.agents (i.e. an older dsh). The 12 tools still work, the watchdog still works — only the in-process nudging is gone.

---

Safety guarantees

• No network calls by the watchdog (it probes 127.0.0.1 only).
• No pkill / killall anywhere. Only the recorded ~/.dsh/profiles/web/.dsh-web.pid is signaled.
• No silent mutation of your cordis.patch.yml. Disable / safe-mode actions write to sibling files (cordis.patch.yml.dr-disabled-<bundle>, cordis.patch.yml.dr-safemode).
• The watchdog is dep-free (only node:fs/path/os/http/child_process/crypto). It runs even if dsh cannot start its own node_modules.
• No telemetry, no analytics, no phone-home.
• dsh_doctor_safe_mode_exit is idempotent — running it twice is safe.
• Nudges never modify model state — they only send a user message through the same primitive the dsh-auto-continue community plugin uses.

---

Troubleshooting

See docs/TROUBLESHOOTING.md.

---

Roadmap

Done:

• ✅ 0.2.0 — Live session watch with idle detection + nudge + cancel.
• ✅ 0.1.0 — Web boot recovery, CLI doctor, tool error capture.

Future:

• Optional browser notification bridge (for users running the dsh Web UI).
• Pluggable triage patterns (load your own regex table from a file).
• dsh_doctor_simulate — run a fake failure end-to-end against a test profile to validate the watchdog.

---

Development

git clone https://github.com/d86e/dsh-doctor
cd dsh-doctor
pnpm install
pnpm test          # 83 unit tests
pnpm run build     # tsc → lib/
pnpm run typecheck

tests/dsh-smoke.sh is a shell-only smoke that builds → packs → would dsh plugin add. It is skipped in CI because the CI host does not have dsh installed.

---

Contributing

See CONTRIBUTING.md.

---

Security

See SECURITY.md. Report vulnerabilities via the GitHub Security tab — do not file a public issue.

---

License

MIT — 2026 Tommy (d86e).