dsh-single-instance-guard

The DSH JSONL session-persistence backend mandates a single live writer per session, yet the framework ships no cross-process guard. When a desktop wrapper spins up its own dsh server while a separate dsh web process is also running, and both resolve to the same DSH_HOME, they end up appending batches with stale sequence cursors. The session logs corrupt silently—no error, no warning—until you scroll through history and notice the timeline is incoherent.

dsh-single-instance-guard converts that silent corruption into an immediate, loud startup failure. At boot the plugin atomically creates .dsh-server.lock via O_EXCL, recording the pid, start timestamp, and hostname. If a lock already exists it probes the pid of the holder: a live holder triggers an abort with a clear bilingual error message; a stale lock (dead pid or unparsable file) is safely removed and acquisition is retried once, so the normal single-instance path is completely unaffected. On clean exit the lock file is deleted only after confirming this process still owns it, preventing accidental removal of the lock belonging to another instance.

The plugin targets setups where multiple dsh instances can share one data root—desktop apps embedding a web view, CI jobs that launch two servers in parallel, or a developer workstation with overlapping instance tags. It ships as a zero-runtime-dependency patch-layer profile bundle, requires no changes to the session backend, and enforces the single-writer guarantee as a hard runtime invariant.