# Architecture

This document expands on the README's overview. It is the canonical reference for the watchdog state machine, the CLI doctor, the triage decision tree, the file layout under `$DSH_HOME/doctor/`, the in-process tool error capture, and the in-process session watch.

## Scope (v0.2.0)

dsh-doctor v0.2.0 ships four independent jobs in one plugin:

| Job | Where it runs | Time budget |
| --- | --- | --- |
| Web boot recovery | Standalone Node (`watchdog.js`) | 60 s ceiling per incident |
| CLI doctor | `dsh doctor` in your shell | No budget — runs to completion |
| Tool error capture | In-process, on the `tools/*` cordis events | Passive — never blocks the host |
| Live session watch | In-process, on the `session/event` cordis event | Tick every 30 s, never blocks the host |

All four are observable independently through `dsh_doctor_status` and the 12 model-facing tools.

## Components

### 1. Plugin process — `apply(ctx, config)`

- Runs **inside the dsh host process** (cordis composition row).
- Registers 12 model-facing tools on the `tools` service:
  - 9 for installation / status / triage / safe-mode / drain.
  - 3 for live session watch.
- Wires the **tool error capture** to the public `tools/execute` and
  `tools/post-execute` cordis events.
- Wires the **session watch** to the public `session/event` cordis
  event and the `ctx.agents` service (both injected by the dsh host
  at load time).

### 2. Standalone watchdog — `$DSH_HOME/doctor/watchdog.js`

- A dep-free Node script (only `node:fs/path/os/http/child_process/crypto`).
- Runs as a per-user platform service (LaunchAgent on macOS, systemd
  user unit on Linux, Task Scheduler on Windows).
- Probes `http://127.0.0.1:$DSH_WEB_PORT/health` every 30 s.
- Triage + simple / complex recovery within a 60 s ceiling per incident.
- Generated by `dsh_doctor_install` and replaced on every install.

### 3. Filesystem state — `$DSH_HOME/doctor/`

| File | Purpose |
| --- | --- |
| `config.json` | Last-resolved config (env overrides applied). |
| `installed-marker` | Write-once flag set by `dsh_doctor_install`. |
| `stopped-marker` | Pause flag (set by `dsh_doctor_pause`). |
| `restart-lock` | Set by the watchdog when it enters triage; the CLI doctor looks for this and disables its own 60 s budget if found. |
| `last-known-good` | JSON snapshot of the last healthy profile patch. |
| `safe-mode.patch` | Auto-generated patch that overrides every bundle in the profile with a no-op config except the allow-list. |
| `watchdog.js` | The standalone script (regenerated on every install). |
| `watchdog.pid` | Current watchdog pid. |
| `logs/watchdog.log` (5 MB × 3) | Watchdog own log. |
| `logs/doctor.log` (5 MB × 3) | Plugin process log. |
| `logs/tool-errors.log` (5 MB × 3) | In-process tool error capture log. |
| `platform/...` | The platform service spec (LaunchAgent / systemd / Windows XML + VBS). |

## Watchdog state machine

```
            ┌──────────────────────────┐
            │  IDLE                    │
            │  30 s health probe tick  │
            └────────────┬─────────────┘
                         │ /health fails 3×
                         ▼
            ┌──────────────────────────┐
            │  TRIAGE                  │
            │  - read 200 log lines    │
            │  - regex pattern table   │
            │  - elapsed: ~5 s         │
            └────────────┬─────────────┘
                         │  simple plan
                         ▼
            ┌──────────────────────────┐
            │  SIMPLE PATH             │
            │  - write sibling patch   │
            │    to disable one row    │
            │  - kill recorded pid     │
            │  - start dsh web         │
            │  - elapsed: 10–25 s      │
            └────────────┬─────────────┘
                         │  /health still failing
                         │  or 60 s budget exceeded
                         ▼
            ┌──────────────────────────┐
            │  COMPLEX PATH            │
            │  - drop safe-mode patch  │
            │  - kill, start, probe    │
            │  - elapsed: 25–50 s      │
            └────────────┬─────────────┘
                         │  /health back
                         ▼
            ┌──────────────────────────┐
            │  RECOVERED               │
            │  - back to IDLE          │
            └──────────────────────────┘

            If 60 s budget exceeded: back off to IDLE,
            retry on the next probe tick (no thrashing).
```

## CLI state machine

```
            ┌──────────────────────────┐
            │  TRIAGE                  │
            │  (same triage engine)    │
            └────────────┬─────────────┘
                         │  simple plan
                         ▼
            ┌──────────────────────────┐
            │  APPLY                   │
            │  (same writeFileAtomic)  │
            └────────────┬─────────────┘
                         │
                         ▼
            ┌──────────────────────────┐
            │  VERIFY                  │
            │  - restart dsh web       │
            │  - probe /health         │
            └────────────┬─────────────┘
                         │
                ┌────────┴────────┐
                │ healthy?        │
                └───┬─────────┬──┘
                yes │         │ no
                    ▼         ▼
            ┌────────────┐   ┌────────────────┐
            │  DONE      │   │  ITERATE       │
            │  summary   │   │  next plan /   │
            │  printed   │   │  disable more  │
            └────────────┘   │  bundles       │
                             │  (no budget)   │
                             └────────────────┘
```

The CLI doctor does **not** exit until either:

- dsh web reports healthy and the human quits the doctor, or
- Every non-allow-listed bundle is disabled and the profile still fails
  to boot (then it exits with a summary telling the human what to do).

## Triage decision tree

The triage engine runs a priority-ordered regex table against the last
N log lines. The first match wins.

| Priority | Pattern | Plan |
| --- | --- | --- |
| 100 | `EADDRINUSE` + `:$PORT` | `kill-pid-and-restart` (port is busy with the old pid) |
| 90 | `Duplicate loader entry` | `disable-row` (the second listed bundle) |
| 80 | `Schema (parse\|validation) error [^\n]*?(@scope/bad-pkg\|^\S+$)` | `disable-row` |
| 70 | `Cannot find module` | `disable-row` (the module name) |
| 60 | `Plugin load error: <id>` | `disable-row` |
| — | no match | `safe-mode` (complex path) |

## Session watch state machine (per session)

```
        ┌──────────────────────────────────────────────┐
        │  every session/event                         │
        │   ├ turn/start → turnRunning = true          │
        │   ├ turn/end:completed → reset nudgesSent    │
        │   ├ turn/end:error → record lastFailure      │
        │   ├ user/message:user → reset nudgesSent     │
        │   └ everything else → lastEventAt = now      │
        └──────────────────────────────────────────────┘
                              │
                              │ every watchTickIntervalMs
                              ▼
        ┌──────────────────────────────────────────────┐
        │  candidate?                                  │
        │   turnRunning? AND                           │
        │   now - lastEventAt ≥ watchIdleThresholdMs? │
        │   nudgesSent < watchMaxNudgesPerSession?     │
        │   now - lastNudgeAt ≥ watchNudgeCooldownMs? │
        │   user NOT currently driving?                │
        └────────────────────┬─────────────────────────┘
                       yes   │
                             ▼
        ┌──────────────────────────────────────────────┐
        │  ctx.agents.get(sessionId).followup({       │
        │    content: [{type: 'text', text: '继续'}],  │
        │    source: {kind: 'user'},                   │
        │  })                                          │
        │                                              │
        │  nudgesSent += 1;  lastNudgeAt = now         │
        └──────────────────────────────────────────────┘
```

## File layout

```
~/.dsh/doctor/
├── config.json                # last-resolved config (env overrides applied)
├── installed-marker           # { installedAt, version }
├── stopped-marker             # pause flag
├── restart-lock               # triage in progress
├── last-known-good            # JSON snapshot
├── safe-mode.patch            # current safe-mode override
├── watchdog.js                # standalone dep-free script
├── watchdog.pid               # current watchdog pid
├── platform/                  # service spec (LaunchAgent / systemd / .vbs)
│   ├── com.dsh.doctor.plist   # macOS
│   ├── dsh-doctor.service     # Linux
│   ├── dsh-doctor.xml         # Windows Task Scheduler
│   └── dsh-doctor.vbs         # Windows hidden-launcher
└── logs/
    ├── watchdog.log
    ├── watchdog.log.1
    ├── watchdog.log.2
    ├── doctor.log
    ├── doctor.log.1
    ├── doctor.log.2
    └── tool-errors.log
```

## Recovery invariants

- `watchdog.js` only signals the PID stored in `~/.dsh/profiles/web/.dsh-web.pid`.
  It never invokes `pkill` or `killall`. The in-process doctor writes the
  file at apply() with process.pid, and a stale entry is treated as
  already-dead by the kill branch.
- Sibling-file patch writes mean 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.
- The CLI doctor and the watchdog **coordinate** through the
  `restart-lock` file — whoever holds the lock is the one currently
  driving the recovery.
- The session watch **only** sends a `继续` user message through
  `agent.followup`. It does not modify model state, tool calls, or
  the waterfall.

## Tool error capture flow

```
       dsh host
         │
         │  any tool call
         ▼
   tools/pre-execute    ◀── pre flight (we don't act here)
         │
         ▼
   tools/execute        ◀── waterfall `next()` then post
         │   ├── before next(): nothing
         │   ├── result.isError === true
         │   └── after next(): classify → record → log
         ▼
   tools/post-execute   ◀── last-chance hook (also observes)
         │
         ▼
       result returned to caller
```

## Why the watchdog is dep-free

The watchdog has to keep working when:

- dsh cannot spawn a child because of a broken bundle.
- pnpm/Node is in a weird state because of a half-installed plugin.

So the watchdog is shipped as a generated, dependency-free Node script.
It only uses `node:fs/path/os/http/child_process/crypto`. If Node still
runs, the watchdog runs.

## Why the tool error capture and session watch are in-process

The `tools/*` and `session/event` cordis events are only fired inside
the dsh host process. A standalone watchdog cannot observe them. The
capture + watch run inside `apply(ctx, config)` and live as long as
the host lives. The standalone watchdog writes its own log
(`logs/watchdog.log`); the in-process capture writes
`logs/tool-errors.log`. The two never share state — that is intentional,
so a crash in the host does not corrupt the watchdog's log and vice versa.

## Why the session watch does not require dsh-agent / dsh-session as deps

The community `dsh-auto-continue` plugin (HsiangNianian) implements the
same feature with `import type` from `@deepseek-ai/dsh-agent` /
`@deepseek-ai/dsh-session`. That works for that plugin because it ships
as a single built bundle and resolves those packages from the dsh host's
node_modules at runtime through the same pnpm profile that the host
itself uses.

For dsh-doctor we took a more conservative path: `src/session-watch.ts`
declares **only the structural types it needs** (`DshAgent`,
`DshAgentsService`, `DshSession`, `DshSessionEvent`) and accesses the
cordis context via duck-typing (`(ctx as any).agents`,
`(ctx as any).on('session/event', ...)`). This means:

- The plugin **never** `require()`s `@deepseek-ai/dsh-agent` or
  `@deepseek-ai/dsh-session` at runtime.
- We do not list those packages as devDependencies, peerDependencies,
  or peerDependenciesMeta — we don't need them to typecheck because
  the types are local.
- The plugin works as long as the dsh host provides the standard
  `ctx.agents` service (every shipped dsh version does) and fires the
  `session/event` cordis event (every shipped dsh version does). If
  the host does not provide them, the watch degrades to a no-op and
  logs a warning — the other 9 tools and the standalone watchdog still
  work.

The trade-off is that if dsh ever renames `ctx.agents` or
`session/event`, the watch will silently no-op until a dsh-doctor
release catches up. We accepted this risk because the dsh host
internals (the names above) have been stable since rc.6 and the watch
is intentionally opt-out (`watchEnabled: false`).

## Relationship to other community plugins

- **`dsh-daemon`** (chenkai2) — independent of dsh-doctor. Both can be
  installed at the same time and provide layered protection. dsh-doctor
  explicitly does not call dsh-daemon.
- **`dsh-auto-continue`** (HsiangNianian) — overlaps with the session
  watch. dsh-doctor's v0.2.0 watch re-implements the core feature
  (idle detection + nudge) inside the dsh-doctor bundle, using the
  same `agent.followup` primitive. If you depend on
  `dsh-auto-continue`'s UI / notification bridge, keep it installed
  alongside dsh-doctor — they do not conflict.