Foreword

DeepSeek Harness (DSH) processes are prone to session log corruption when running concurrently, especially when dsh web and the CLI run at the same time, or when multiple instances share the same $DSH_HOME. This happens because each process maintains independent in-memory sequence numbers. A second writing process may commit a sequence number already confirmed by the first process, causing a seq gap in committed region error in the log and making the session history permanently unloadable. DSH currently lacks a cross-process locking mechanism, so direct writes can silently corrupt historical data. The following section introduces a plugin designed to solve this problem.

What It Is

dsh-session-guard is a DeepSeek Harness plugin maintained by po-et. Its core purpose is to add cross-process session-level advisory locks between DSH processes, preventing log corruption caused by concurrent writes. By forcing conflicting steps to fail and report an error, it ensures that the log remains intact when a conflict occurs, rather than being silently overwritten.

Core Features

The plugin provides the following features:
1. Per-session advisory locks: Provides an advisory locking mechanism for each session.
2. Prevention of concurrent write corruption: Intercepts and blocks two processes from writing to the same session log simultaneously.
3. Automatic lock takeover: When the process holding a lock crashes, the lock is automatically taken over by another process.
4. Heartbeat refresh mechanism: The lock-holding process must periodically send heartbeats to keep the lock valid.
5. Expiration mechanism: An unverified owner (for example, a process on another host) causes the lock to expire automatically if its heartbeat is not refreshed within 90 seconds.
6. Zero runtime dependencies: Apart from the required peer dependencies, the plugin does not depend on any other runtime libraries.

Installation and Enablement

The plugin has not yet been published to npm and must be installed directly via GitHub.

dsh plugin --profile web add github:po-et/dsh-session-guard

After installation, the plugin is loaded automatically. It requires @deepseek-ai/cordis ^4.0.1 as a peer dependency.

Typical Usage

After installation, the plugin’s behavior can be adjusted through configuration. All configuration options are optional and should be placed in the plugin line of the profile patch:

- id: session-guard
  name: "@po-et/dsh-session-guard"
  config:
    mode: enforce        # enforce (默认) 会强制冲突步骤失败；warn 仅记录日志
    heartbeatMs: 15000   # 持有锁的心跳刷新间隔（毫秒）
    staleAfterMs: 90000  # 未经验证的所有者无心跳后过期时间（毫秒）
    # lockDir: /custom   # 自定义锁目录（默认为 $DSH_HOME/session-locks）

Use Cases and Notes

  1. Advisory lock nature: The lock is advisory and only protects DSH processes that have loaded this plugin. If some processes do not have the plugin installed, they may still conflict with other processes. It is recommended to install this plugin in all profiles that run DSH.
  2. Protection scope: The plugin only intercepts active “write paths” (agent/session-start, agent/pre-step). It cannot intercept the cold-loading repair path (where DSH internally commits a synthetic interruption close tag before a step runs); this repair needs to be solved at the DSH core layer.
  3. Lock storage location: Lock files are stored by default in the $DSH_HOME/session-locks directory.
  4. Irreversibility: If the session log is already corrupted, this plugin cannot repair it. Use it together with dsh-session-rescue.
  5. License: MIT License.

Conclusion

By introducing advisory locks between DSH processes, dsh-session-guard turns silent corruption caused by concurrent writes into explicit error messages, thereby protecting session history from being destroyed. In environments that require stable DSH operation, this is a necessary safeguard.

For more details and source code, visit: https://github.com/po-et/dsh-session-guard