Nwflower/dsh-file-claim ↗★ 6

dsh-file-claim

Write in parallel, never overwrite — file claim / protection for concurrent DeepSeek Harness (DSH) sessions working the same workspace: claim/release, heartbeat stale takeover, and an async pending merge area (git 3-way merge) 适合多会话同时操作同一工作区、需要防止文件被覆盖的协作任务。

패키지
dsh-file-claim
호환성
미검증
버전
0.2.0
라이선스
MIT
최근 업데이트
2026. 9. 2.

설치

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:Nwflower/dsh-file-claim

Usage Examples

Two sessions, one workspace. Session A owns README.md; session B wants to edit it too:

// Session A
claim_files({ paths: ["README.md"], note: "rewriting the docs" })
write  ...  README.md          // allowed: own claim
release_files({ paths: ["README.md"] })

// Session B — meanwhile
who_claims({ paths: ["README.md"] })          // → claimed by A
write ... README.md                           // → DENIED with a hint
pending_write({ path: "README.md", content: "..." })  // async, no blocking
// When A releases, the entry is auto 3-way merged (or surfaced for manual pending_apply)

Recover from a crashed session. Session A dies mid-work; its claims expire after staleMs (2h default), then:

claim_status()                      # → A shows [stale]
claim_files({ paths: ["README.md"], force: true })   # take over

Configuration

Passed as plugin config in the bundle (cordis.patch.yml):

KeyDefaultMeaning
staleMs7200000 (2h)Heartbeat expiry before a session is considered stale
guardtrueSet false to disable the pre-execute write guard
guardCommitfalseOpt-in: also deny git commit that explicitly stages paths actively claimed by another session
heartbeatMs600000 (10min)Fallback heartbeat interval
- insert:
    - id: dsh-file-claim
      name: dsh-file-claim
      config:
        staleMs: 3600000        # 1h
        guardCommit: true       # also guard explicit git commits

Since 0.2.0, state is stored as workspace sidecar files — the lock travels with the protected file (the claude-code-file-locks .agentlock idiom, adopted because DSH reserves no in-workspace directory convention):

README.md.dshclaim                 claim sidecar (JSON: version, path, tag, note, startedAt, lastSeenAt, pid)
README.md.dshpending/              pending-merge sidecar (content / base / meta.json), next to the target
.dsh-file-claim.audit.jsonl        workspace-global audit log (append-only, at the root)
.dsh-file-claim.lock               transient cross-process mutex (exists only during a mutation)

Recommend adding these to .gitignore:

*.dshclaim
*.dshpending/
.dsh-file-claim.audit.jsonl
.dsh-file-claim.lock

When a workspace still carries the ≤0.1.7 flat .dsh-file-claim/ directory (or an unpublished 0.2.0 .dsh/dsh-file-claim/), the first tool/command call migrates it to sidecars (the old directory is kept — delete it manually once verified; its registry.json is renamed registry.json.migrated as the idempotency marker). The write guard also reads the old registry until that first call, so protection is seamless across the upgrade. State survives restarts; nothing ever touches .git/.