Introduction

DeepSeek Harness (DSH) is a long-lived process. It sometimes needs to be restarted to reload plugins, apply configuration changes, or recover from a hung state. However, the internal agent cannot restart DSH itself: it cannot observe the result, cannot see the live work in progress, and if the restart fails, no one is responsible for diagnosing it. The solution is a “handoff”: DSH writes a request, an external operations agent reads it, runs the restart process, and writes the result back after the restart.

Plugin Overview

This plugin is a host plugin for DSH that passes reset requests to an external operations agent through a versioned JSON protocol. It follows the flow: “pre-check snapshot -> restart -> health check -> recovery”. It is maintained by nicecx.

Core Features

  • Host plugin: Allows external reset of DSH.
  • JSON protocol (v1): Used for request and result files.
  • Flow: Pre-check snapshot, health check, recovery.
  • Safety: Maturity gate (GATE) to ensure safe restarts.
  • Tools: reset_handoff, reset_status.
  • Degradation: Graceful degradation support.

Installation and Enablement

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

Usage

Tools and Commands

  • reset_handoff(reason, scope?): Submits a reset request. It does not restart DSH in-process.
  • reset_status(): Queries the latest request and result (read-only).

Protocol and Execution

The plugin and the executor are decoupled. They share a protocol through two JSON files under ~/.dsh/reset-handoff/ (can be overridden via DSH_RESET_HANDOFF_DIR):
* request.json: Written by DSH.
* result.json: Written by the executor.

A reference executor (pure Python) is located in hermes/reset_agent.py.
* Run python3 reset_agent.py to execute the five-step flow.
* Run python3 reset_agent.py --dry-run to print the flow without performing a restart.

Notes

  • Dependency check: Plugin dependencies must be verified before restart.
  • Health check: Perform a health check before restart and observe after restart.
  • Graceful degradation: The plugin must degrade gracefully.
  • No self-termination: Never create self-termination / unconditional restart jobs.
  • External restart: The external executor must restart the dsh web service (for example, macOS launchd).

Conclusion

By moving the restart logic outside the DSH process, this plugin resolves the deadlock of “restarting DSH itself”. It uses a versioned JSON protocol to ensure observability and recoverability of the operation.