Preface

The JSONL session persistence backend for DeepSeek Harness (DSH) follows an “one active writer per session” strategy and does not inherently provide cross-process protection. If two dsh servers share the same DSH_HOME (for example, a desktop wrapper starts a server on its own, or two dsh web processes are run simultaneously), they may append batches using stale sequence cursors, which can corrupt session logs. The typical error message is corrupt session log: seq gap in committed region.

The dsh-single-instance-guard plugin is intended to turn this silent corruption into an explicit startup failure by preventing concurrent startup through an exclusive lock.

Plugin Overview

This plugin is a zero-dependency plugin for DeepSeek Harness, maintained by Tang-mm95 and licensed under the MIT license. Its core function is to atomically acquire an exclusive lock on the DSH_HOME data directory during startup. If another dsh server is detected to be using the directory, the plugin aborts the startup process.

Core Features

  1. Atomic exclusive locking: Creates a .dsh-server.lock file under <DSH_HOME>. The file content includes { pid, startedAt, hostname }. The O_EXCL flag is used to ensure atomicity of the creation operation.
  2. Concurrency detection and interruption: When a conflict is detected, the plugin first probes whether the process holding the lock is still alive. If the holder is alive, the current startup is aborted and a bilingual error is displayed. If the holder no longer exists, the lock is removed and the operation is retried once.
  3. Automatic cleanup: Upon process exit, the lock file is removed automatically only if it still belongs to that process.
  4. Zero dependencies: The plugin does not rely on any third-party libraries.

Installation and Configuration

It can be installed via the CLI or configured manually.

CLI Installation

dsh plugin --profile <profile> add dsh-single-instance-guard

Manual Configuration

Add the following lines to the profile’s cordis.patch.yml. This configuration must be placed before session-related bundles:

- insert:
    - id: single-instance-guard
      name: 'dsh-single-instance-guard'

How It Works

The plugin first resolves DSH_HOME (priority order: $DSH_HOME or ~/.dsh). It then attempts to create the .dsh-server.lock file.

  1. Success: The file is created successfully, and the plugin holds the lock.
  2. Conflict: The file already exists. The plugin reads its content and checks whether the corresponding PID is still alive. If the process is alive, the plugin reports an error and exits. If the PID does not exist or the file format cannot be parsed, it is treated as a stale lock, then removed and retried once.
  3. Exit: When the process terminates, the plugin checks whether the PID in the file still matches the current process. If it does, the lock file is removed.

Applicable Scenarios and Notes

This plugin is suitable for environments where it is required that only one dsh server runs under the same DSH_HOME directory.

Note the following limitations:
* Minimal race condition: When two processes simultaneously discover and try to delete the same stale lock, there is a very small race window. However, the atomic O_EXCL write mechanism ensures that only one process ultimately acquires the lock, while the other process fails correctly on retry.
* Path protection: The plugin only protects concurrent servers using the same DSH_HOME path. If two dsh instances point to the same session file through different paths, the plugin cannot protect against that scenario.
* Environment requirements: Node.js >= 18 is required.

Summary

By introducing this plugin, corruption of session logs caused by concurrent startup can be avoided in a DSH environment. The relevant source code and documentation can be found in its GitHub repository.