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):

Key	Default	Meaning
staleMs	7200000 (2h)	Heartbeat expiry before a session is considered stale
stateDirName	.dsh-file-claim	Registry + pending area directory under the workspace root
guard	true	Set false to disable the pre-execute write guard
guardCommit	false	Opt-in: also deny git commit that explicitly stages paths actively claimed by another session
heartbeatMs	600000 (10min)	Fallback heartbeat interval

- insert:
    - id: dsh-file-claim
      name: dsh-file-claim
      config:
        staleMs: 3600000        # 1h
        guardCommit: true       # also guard explicit git commits

The claim registry and pending area live in // — recommend adding it to .gitignore. State survives restarts; nothing ever touches .git/.