dsh-reset-handoff

DSH never restarts itself. A host plugin that hands reset requests to an external ops agent over a versioned JSON protocol — preflight-snapshot → restart → health-check → recover — then delivers the result back to the requesting session after reboot.

Why

A long-lived DeepSeek Harness (DSH) instance needs to restart for many reasons: reload plugins/config, apply settings, recover from a wedged state. But the agent inside DSH should not restart DSH itself:

• restarting kills the very process that issued it, so the agent has no chance to see the outcome;
• the agent cannot see what business is running (other live sessions, the relay channels, pending jobs);
• if the reboot fails, nobody is left to diagnose and recover.

The safe pattern is a handoff: DSH writes a request, a separate, independent ops agent (here: Hermes Agent) reads it, runs the restart with preflight/health/recovery, and writes a result that DSH reads back after it comes up.

How it works

[DSH]  agent calls reset_handoff(reason)
         │  writes request.json (JSON protocol)
         │  (optional) triggers the external executor
         ▼
[ext]  ops agent reads request.json
         │  1. preflight — snapshot live sessions, relay state, pending jobs
         │  2. GATE     — pre-restart maturity gate (see below)
         │  3. restart  — restart the dsh web service (macOS launchd)
         │  4. health   — poll http://127.0.0.1:3080 until 200 (with timeout)
         │  5. recover  — verify relay/auth-proxy self-heal, list interrupted sessions
         │  6. result   — write result.json (status done/failed + per-stage detail)
         ▼
[DSH]  after reboot, the plugin reads result.json and delivers a readable
         summary back into the requesting session (followup), so the agent
         that asked can resume its interrupted work.

Pre-restart maturity gate

The reference executor refuses to restart unless it is safe to do so. It checks:

1. No pending approvals/questions — relay pending.json has an empty pending list (a restart would otherwise drop the approval stack).
2. Enough free disk — at least MIN_FREE_DISK_MB (default 500 MB).
3. Cooldown — at least RESTART_COOLDOWN_SEC (default 60 s) since the previous restart, to break crash loops.

If any condition fails, the executor writes result.json with status: "failed", restart: { ok: false, gated: true }, and a gate array listing each failed condition with its detail — and does not restart. The requesting agent (or user) sees the exact reason and decides when it is safe to retry.

Tools

Tool	Purpose
reset_handoff(reason, scope?)	Submit a reset request to the external ops agent. Never restarts DSH in-process.
reset_status()	Query the latest request and its result (read-only).

Both tools are registered host-wide, so every session's agent can call them when a reset is needed.

Protocol (v1)

The plugin and the executor are decoupled — they only share two JSON files under ~/.dsh/reset-handoff/ (override with DSH_RESET_HANDOFF_DIR):

request.json (written by DSH):

{
  "schema": "dsh-reset-handoff/request",
  "version": 1,
  "id": "<uuid>",
  "requestedAt": "2026-08-30T12:00:00+08:00",
  "reason": "重新加载插件配置",
  "sessionId": "<requesting session id>",
  "requester": "dsh-reset-handoff",
  "scope": { "restartDshWeb": true, "healthCheck": true, "recoverInterrupted": true }
}

result.json (written by the executor):

{
  "schema": "dsh-reset-handoff/result",
  "version": 1,
  "requestId": "<uuid>",
  "status": "done",
  "startedAt": "...",
  "finishedAt": "...",
  "preflight": { "liveSessions": ["..."], "relay": { }, "hermesJobs": ["..."] },
  "restart": { "ok": true },
  "health": { "ok": true, "checks": [ { "name": "dsh-web http :3080", "ok": true, "detail": "200" } ] },
  "recovery": { "resumed": ["..."], "report": "..." }
}

Any executor that reads/writes these two files can drive the reset — Hermes, a custom script, a cloud function. The protocol is the contract.

Install

dsh plugin --profile <profile> add github:<owner>/dsh-reset-handoff

Optional executor trigger: configure triggerCommand so reset_handoff also wakes the external agent (default: none — the executor may poll request.json instead). See cordis.patch.yml for the config shape.

Executor (Hermes example)

A reference executor is included under hermes/reset_agent.py (pure Python, no deps). It is meant to live inside a Hermes profile (reset-agent) and be triggered by hermes cron run <job>:

python3 reset_agent.py            # run the five-step flow
python3 reset_agent.py --dry-run  # print the flow, don't restart

Requirements

• DeepSeek Harness with the web profile (host plugin).
• The external executor must be able to restart the dsh web service (macOS launchctl kickstart -k com.dsh.web, or equivalent for your OS/init).

License

MIT