dsh-single-instance-guard

一个零依赖的 DeepSeek Harness 插件：启动时对 DSH_HOME 数据目录加独占锁，发现已有存活的 dsh 实例时大声报错并中止启动。

English

为什么需要它

JSONL 会话持久化后端明确要求"一个会话同一时刻只有一个写进程"，且没有跨进程防护。两个 dsh 服务共用同一个 DSH_HOME（例如桌面封装自己另起服务、或两个 dsh web 进程）会用过期的序列游标并发追加日志，损坏会话历史：

history unavailable for session "…": Error: corrupt session log: seq gap in committed region …

完整诊断、只读巡检工具与手动修复步骤见这份报告。

本插件把"静默损坏"变成"启动即大声失败"。

安装

发布到 npm 后：

dsh plugin --profile <profile> add dsh-single-instance-guard

手动方式（任意 dsh 安装）：把下面这行加到 profile 的 cordis.patch.yml，并放在会话相关 bundle 之前：

- insert:
    - id: single-instance-guard
      name: 'dsh-single-instance-guard'

本插件同时是一个 profile bundle，manifest 自带同样的补丁，CLI 会把它作为补丁层安装。

工作原理

1. 原子创建 <DSH_HOME>/.dsh-server.lock（O_EXCL），内容为 { pid, startedAt, hostname }。
2. 冲突时探测持有者 pid 是否存活：存活则中止启动并给出清晰的中英双语错误；锁已过期（pid 已死或文件损坏）则删除并重试一次。
3. 进程退出时仅当锁仍归本进程所有时才删除。

DSH_HOME 的解析与 dsh 一致：优先 $DSH_HOME，默认 ~/.dsh。使用不同数据目录的服务之间不会冲突。

已知限制

• 两个进程同时发现同一把过期锁时，删除+重试路径存在极小竞态窗口；但 O_EXCL 原子写入保证最终只有一个胜者，败者会在重试时正确失败。
• 锁只防"多个服务共用同一个 DSH_HOME"；不防（也不支持）两个 dsh 实例通过不同 root 指向同一会话文件。

开发

npm test   # node --test

许可证

MIT