Nwflower/dsh-file-claim
File claim / protection for concurrent DeepSeek Harness (DSH) sessions working the same workspace: claim/relea
dsh-file-claim provides file claim/protection for concurrent DeepSeek Harness sessions working the same workspace: claim_files declares exclusive ownership of paths before editing, and write/edit operations on files claimed by other sessions are denied; release_files hands ownership back. Heartbeats refresh automatically via agent lifecycle events, a crashed or hard-killed session's claims are cleared immediately on the next activity, and a stale-claim expiry (2h) plus --force takeover handle edge cases. Instead of blocking a session whose target files are claimed, the async pending merge area lets a session write its edited content plus the git HEAD base into a pending area; when the owner releases, the entry is auto-merged via a git 3-way merge (current × base × pending) when conflict-free. It solves the three classic parallel-session failures: two sessions overwriting the same file, crashed sessions leaving stale state, and sessions unable to coordinate on who edits what.
Install
dsh plugin --profile web add dsh-file-claimnpm package dsh-file-claim 0.1.7 (registry-verified 2026-08-24). Install: dsh plugin --profile web add dsh-file-claim (README shows dsh plugin add dsh-file-claim; add with --profile web targets the web profile). Write in parallel, never overwrite: turns a proven coordination protocol into native DSH tools, lifecycle events, and a write guard. Node >= 18. MIT. English README with 简体中文 edition.
Compatibility
DeepSeek Harness web profile, Node >= 18. claim/release: a session declares exclusive ownership of file paths before editing them; duplicates merge idempotently, directory claims cover descendants, and '.' claims the whole workspace. Heartbeat + stale takeover + orphan self-heal: heartbeats refresh automatically via agent lifecycle events; a crashed/hard-killed session's claims are cleared immediately on the next activity (per-process pid check) and swept by the heartbeat interval; staleMs expiry (2h, for records without a pid) and --force takeover remain as the slow fallback. Async pending merge area: instead of blocking, a session writes its edited content plus the git HEAD base into a pending area; when the owner releases, the entry is auto-merged via a git 3-way merge (current × base × pending) when conflict-free, or applied manually. Writes to files claimed by others are denied by the write guard.
Details
- Repo: Nwflower/dsh-file-claim
- Category: Files & Data
- Stars: 6
- Version: npm package dsh-file-claim 0.1.7 (registry-verified 2026-08-24)
- Last push: 2026-09-02
- First seen: 2026-08-14
Recent updates
The current English README documents: features (claim/release, heartbeat + stale takeover + orphan self-heal, async pending merge area with git 3-way merge), install, quick start, usage examples, tools, commands, write guard, configuration, audit log, pending merge area, enforcement boundary, FAQ, and related projects.
FAQ
- What happens if a session crashes while holding claims?
- Claims are cleared immediately on the next activity (per-process pid check) and swept by the heartbeat interval; staleMs expiry (2h for records without a pid) and --force takeover are the slow fallback.
- Can a session edit a file another session claimed?
- No — the write guard denies writes to files claimed by others. The async pending merge area lets the session stage its edit plus the git HEAD base and auto-merges via a git 3-way merge when conflict-free.
- How do claims expire?
- Heartbeats refresh automatically via agent lifecycle events; without a pid, records expire after staleMs (2h).
Alternatives
DDSG-X/dsh-workspace-dir · xiaoyuyu6420/dsh-backup · lanyun077/dsh-project