Preface

The design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” During use, it is common to encounter sessions that have been moved, or sessions created before the workspace directory existed. In such cases, these sessions are marked as “ungrouped” and are no longer automatically re-adopted after WorkspaceRegistry is initialized, leaving them permanently in the ungrouped list.

dsh-session-reattach aims to fill this gap. It does not modify the session files themselves; it simply validates the session’s current working directory (cwd) and rewrites its ownership record into the correct workspace.

Plugin Positioning

This is a DSH host plugin designed to resolve the reattachment problem for historical sessions. It reattaches orphaned sessions into the matching workspace group based on cwd.

Core Features

  • Only modifies ownership records: The plugin only modifies the ownership record in workspace.json and does not touch session files such as session.l.zstd.
  • Dry-run by default: For safety, it only validates and reports by default, and does not perform writes until write mode is explicitly enabled.
  • Multiple entry points: It supports both drag-and-drop operations in the sidebar and command-line input.
  • Zero runtime dependencies: It does not depend on any DSH internal packages or third-party libraries.

Installation and Enablement

This plugin only supports the web profile.

  1. Run the installation command:
    dsh plugin --profile web add dsh-session-reattach
  1. After installation, you must restart dsh web. Host plugins are assembled at startup, and the plugin will not take effect until you restart.

Usage

Command Line

The plugin provides three command entry points, all dry-run by default:

  • /reattach: Reports which sessions would be reattached, which sessions cannot be reattached and why, without writing.
  • /reattach apply: Performs the reattachment write operations.
  • /reattach apply subagents: Reattaches sessions and also processes subagent sessions (subagents are skipped by default).

Drag-and-Drop

In the sidebar, expand “Ungrouped” and press and hold a session row to start dragging. Only groups whose directory exactly matches the cwd display a dashed drop target; other groups display a not-allowed cursor. Drag the session into a matching group and release to reattach it.

Reattachment Rules

The plugin uses fs.realpath to normalize the session cwd and workspace paths before comparing them. Ownership is assigned only when the paths match exactly. Before reattaching, it first clears the session’s old slot from other workspaces to avoid double-ownership errors.

Notes

  • Default safety policy: All reattachment operations do not write by default. You must explicitly pass false or use the apply argument.
  • Web profile restriction: Only the web profile is supported; you must restart dsh web after installation.
  • Path consistency: Reattachment requires that cwd exists and is valid. If the directory has been deleted, renamed, or is inaccessible, the session will be skipped.
  • Subagent handling: Subagent sessions are skipped by default unless apply subagents is explicitly specified.
  • File safety: The plugin does not modify session files themselves, only ownership records, so it will not cause data loss or content tampering.

Summary

dsh-session-reattach is a lightweight repair tool specifically designed to address session ownership misplacement in DSH caused by historical issues. Through drag-and-drop or commands, you can quickly reattach orphaned sessions to the correct workspace and keep the sidebar structure clean.