Foreword

In DeepSeek Harness (DSH), multiple sessions may simultaneously work on the same workspace. Without explicit coordination, two sessions might edit the same file, causing overwrites; a crashed session could leave behind stale occupancy states; and another session attempting to modify an occupied file would have to wait or guess.

dsh-file-claim addresses this problem: it provides file claim/protection for concurrent DSH sessions, including claim/release, heartbeat-expiry takeover, and an asynchronous pending merge area (git 3-way merge). Below, we introduce its positioning, core capabilities, installation methods, and typical usage.

What Is This

dsh-file-claim is a DSH Host plugin maintained by Nwflower, licensed under MIT.

It encapsulates file occupancy declaration, release, status query, and pending merge capabilities into tools, and leverages DSH lifecycle events to refresh heartbeats and release claims from departing sessions.

Core Features

Claim / Release

  • claim_files: Sessions declare exclusive ownership of file/directory paths before editing.
  • Repeated claims are merged idempotently.
  • Directory claims cover subpaths.
  • Claiming '.' represents the entire workspace.
  • release_files: Releases the claim; after the owner releases, the pending area can merge according to rules.

Heartbeat and Stale Takeover

  • agent/created / agent/status events refresh the heartbeat.
  • agent/disposed automatically releases all claims from departing sessions.
  • Claims from crashed/killed sessions are cleaned up on next activity and swept by heartbeat intervals.
  • staleMs expiry and --force takeover serve as slow fallbacks; staleMs defaults to 2 hours and applies when no PID record is available.

Async Pending Merge Area

  • For files occupied by other sessions, writes go to the pending area instead of directly blocking.
  • After the owner releases, if there are no conflicts, automatic merging occurs via git 3-way merge.
  • Conflicts are manually merged using pending_apply.
  • Helper tools include pending_show to view entries and pending_drop to discard entries.

Write Guard

  • The tools/pre-execute guard denies writes to files with active claims from other sessions.
  • On denial, it prompts with wait / take over when stale / pend options.
  • Optional commit guard.
  • This guard is a cooperative tool-layer guardrail, marked as fail-open, and matches the de facto standard for this category.

Audit and Lightweight Operation

  • Claim/release/takeover/pending changes are appended as JSON lines for traceability and post-crash reconciliation.
  • The plugin is a pure Host plugin with zero dependencies, no Browser side, no build step, and only uses node: builtins, making it Windows-friendly.

Installation and Activation

First, ensure the environment meets:

  • DSH with node >= 18
  • git in PATH; git is only used for 3-way merging

Then run the installation command:

dsh plugin add dsh-file-claim

After installation, the plugin provides the following tools: claim_files, release_files, who_claims, claim_status, pending_write, pending_apply, pending_show, pending_drop.

Typical Usage

Claim First, Edit, Then Release

First declare ownership:

claim_files({ paths: ["README.md"] })

Then perform the write/edit. When done, release:

release_files({ paths: ["README.md"] })

After these steps, this session’s claim is released, and related entries in the pending area enter the merge process.

View Claim Status

Check who has claimed a path:

who_claims({ paths: ["README.md"] })

View registry, claims, pending area, and audit:

claim_status()

Writing to Files Occupied by Other Sessions

Writing to a file claimed by another session will be DENIED, with prompts to wait, take over when stale, or pend.

To place edits into the pending area first:

pending_write({ path: "README.md", content: "..." })

After the owner releases, automatic git 3-way merge occurs if no conflicts; to resolve conflicts, run:

pending_apply

You can also view or discard pending entries:

pending_show
pending_drop

Taking Over Stale Claims

If another session’s claim is found to be stale, you can take over:

claim_files({ paths: ["README.md"], force: true })

Use Cases and Notes

Suitable for:

  • Multiple DSH sessions concurrently editing the same workspace.
  • Reducing the frequency of concurrent overwrites to the same file.
  • Allowing writes to occupied files to go to the pending area instead of just waiting.
  • Using JSON line audit to trace claim/release/takeover/pending changes.

Notes:

  • The plugin runs with the current dsh process permissions; review the source code and license before installation.
  • The write guard is a cooperative tool-layer guardrail marked as fail-open; it’s for collaborative constraints and should not be treated as a strong isolation boundary.
  • staleMs defaults to 2 hours, and --force takeover is a slow fallback.
  • git is only used for 3-way merging; automatic merging relies on this process.
  • The plugin has no Browser side, no build step, and zero dependencies; deployment mainly involves DSH, node, git, and source code review.

Conclusion

dsh-file-claim brings file claim, release, pending merge, and audit for concurrent DSH sessions into a single set of tools, making the “claim first, edit, then release” process an executable collaborative workflow.

Plugin Name: dsh-file-claim

Repository: https://github.com/Nwflower/dsh-file-claim

You can look up the directory page by the plugin name dsh-file-claim.