DSH Workspace Snapshot Fork

简体中文

dsh-workspace-snapshot-fork is a third-party plugin that extends DeepSeek Harness's built-in session forking. In addition to copying the session history through the selected completed turn, it creates an independent workspace for the new session and restores the files recorded at that fork point. The source session's workspace remains unchanged.

Alpha release: Windows support has been tested with the DSH Web profile. Linux and macOS are not yet verified.

How it works

Each completed turn receives an immutable Git-backed workspace checkpoint. When the user forks that turn in the DSH Web UI, the plugin copies the session-log prefix and materializes the matching files in a new workspace.

Source workspace	Fork behavior
Plain directory	Materializes the checkpoint from a private snapshot repository.
Git repository root with a commit	Creates a new worktree and dsh/workspace-fork/<id> branch in the source repository, then restores the checkpoint files. History, remotes, hooks, and repository configuration remain available.
Directory nested inside a Git repository	Uses the private snapshot behavior.
Git repository without an initial commit	Uses the private snapshot behavior.

Historical uncommitted changes appear as ordinary changes in a Git child worktree. The parent directory is never changed.

Requirements and compatibility

• DeepSeek Harness Web profile
• Node.js ^22.19.0 or >=24.0.0
• Git available on PATH

Platform	Status
Windows	Supported and tested
Ubuntu/Linux	Not yet verified
macOS	Not yet verified

This release supports the DSH 0.1.1-rc.x line. DeepSeek Harness is in developer preview, so upgrade compatibility is not assumed.

Install

Install this release into the web profile:

dsh plugin --profile web add "github:Yu-Zhuang1/dsh-workspace-snapshot-fork#v0.1.0-alpha.1"

For a DSH source checkout, prefix the same command with pnpm:

pnpm dsh plugin --profile web add "github:Yu-Zhuang1/dsh-workspace-snapshot-fork#v0.1.0-alpha.1"

Restart DSH after installing or updating the package. This bundle targets the Web profile only; the shipped headless profile has no session-fork RPC or workspace registry.

Configuration

The default bundle configuration is:

mode: workspace
storageRoot: <DSH_HOME>/workspace-snapshot-fork/snapshots
childRoot: <DSH_HOME>/workspace-snapshot-fork/workspaces
exclude: [.git, node_modules, .env, .env.*, .DS_Store]

DSH_HOME defaults to ~/.dsh. To override the configuration for the Web profile, edit $DSH_HOME/profiles/web/cordis.patch.yml and add the complete entry below:

- id: workspace-snapshot-fork
  config:
    mode: workspace
    storageRoot: !!js dshHomePath('workspace-snapshot-fork/snapshots')
    childRoot: !!js dshHomePath('workspace-snapshot-fork/workspaces')
    exclude: [.git, node_modules, .env, .env.*, .DS_Store]

DSH replaces the complete config value rather than merging individual fields, so retain every field when overriding it.

Native mode

Set mode: native in the complete profile entry to delegate new forks to DSH unchanged. Native mode records no new workspace checkpoints, but archive cleanup still releases existing checkpoints. DSH watches the profile patch and applies a valid mode change while the Web process is running.

After switching back to workspace, only subsequently completed turns receive checkpoints. Native-mode turns are not captured retroactively.

Security

The plugin uses its own snapshot index and deliberately does not treat the source repository's .gitignore as a security policy. A file ignored by source Git is captured unless it matches this plugin's exclude list.

• Add every project-specific credential, secret, large generated directory, and private data path to exclude.
• Removing .env or .env.* from the list may store credentials in local snapshots.
• Snapshots are local Git objects and are not encrypted by this plugin.
• The exclusion list is complete replacement configuration, not an addition to hidden defaults.

Read SECURITY.md before using this plugin on sensitive workspaces.

Retention and cleanup

Archiving a session removes its checkpoint map. A snapshot ref is removed only after no unarchived session map references it. Forked child sessions inherit the selected parent prefix's checkpoint maps, so they can continue forking inherited turns after the parent is archived.

Successful child workspaces, Git worktrees, and dsh/workspace-fork/* branches are not deleted automatically. Review their uncommitted files, then clean up a Git child with:

git -C <source-repository> worktree remove <child-workspace>
git -C <source-repository> branch --delete dsh/workspace-fork/<id>

Use --force only when you intentionally want to discard uncommitted child files. Plain child directories are also user-owned after a successful fork.

Uninstall

dsh plugin --profile web remove dsh-workspace-snapshot-fork

For a DSH source checkout, prefix the command with pnpm. Uninstalling stops future checkpoints and workspace-aware forks; it does not delete existing snapshots or child workspaces. Remove any plugin override from $DSH_HOME/profiles/web/cordis.patch.yml after uninstalling.

Known limitations

• Web profile only; there is no headless fork adapter.
• DSH fork integration is version-sensitive; verify the plugin after upgrading DSH.
• Existing successful child worktrees and branches require manual cleanup.
• Unarchiving a session does not restore checkpoints discarded when it was archived.
• Checkpoints are created only for turns completed while mode: workspace is active.

Development

The package has no runtime npm dependencies. Tests invoke local Git and create only temporary directories.

npm run check
npm test
npm pack --dry-run

Acknowledgments

We thank Kefei Chen for the work on Git-based workspace state monitoring and restoration in the AgentRewind/replay project. The related implementation experience provided a reference for this plugin's workspace-state synchronization.

License

MIT