@deepseek-ai/dsh-session-registry-file

存活会话注册表 seam 的文件后端实现：整套介质就是 Harness home 下的一个加锁保护的 JSON 文件。挂载它即发布 ctx.sessionRegistry；file 暴露注册表文件的绝对路径（<root>/sessions.json）。

存活状态与崩溃安全

存活状态在读取时由记录的 pid 经 kill(pid, 0) 推导：ESRCH 表示已消亡，EPERM 表示存活于另一个用户之下，其他任何 errno 都向外抛出，而不会被当成一个答案来解读。因此，未运行 disposer 就被杀掉的进程留下的记录，会被下一次 list() 剪除并重写——不需要 daemon，不需要心跳，也不会有永久残留的幽灵记录。bootId 用于区分被复用的 pid，因此注销不会删除属于另一个 incarnation 的同名记录。

并发

两层机制都是必需的，任何一层都无法替代另一层。

跨进程：每个读改写周期都持有 proper-lockfile 咨询锁。无锁的全文件重发布会在并发启动器下丢失记录，这正是 storage-hub JSON 后端（文档声明 last-write-wins、单宿主进程）无法承担该介质的原因。
进程内：调用在内部链上排队。咨询锁按进程跟踪，因此同进程的重叠调用者会争用其有限的重试预算而非排队；并发调用超过十来个时预算耗尽，注册会被拒绝。调用方以 fire-and-forget 方式发布，这样的拒绝会静默地把一个存活会话从列表中丢掉。

写入采用临时文件加原子 rename（不做 fsync：崩溃丢失的列表会被下一个进程的读取重建，崩溃持久性在这里没有收益），根目录 0o700，文件 0o600。

持久化格式

sessions.json 携带一个 version 戳，在预发布立场下固定为 0：版本不同将被拒绝而非迁移。由于介质是共享且用户可见的，读取会校验每个字段。单条不可用的行会被丢弃而其同伴保留；无法解析的文本或异版本文件读作空——另一个 harness 版本写入的一条损坏记录，不得隐藏所有其他存活会话。上述任一情况都会把介质标记为受损，下一次写入将重新发布并修复它。

配置

键	类型	默认值	含义
`root`	string	必填——无默认值（回退到 cwd 会使注册表散落各处）	存放 `sessions.json` 的目录；按需以 `0o700` 创建
`lockStaleMs`	natural	`10000`	持有的锁超过该毫秒数即视为被遗弃并被回收
`lockRetries`	natural	`10`	锁争用时在明确失败前的重试次数

模型体验

无。本包不注册工具、不注入提示词、不追加会话事件；它只为 CLI 列表界面存储宿主侧进程记录。

KV 缓存影响

与在途请求无关：注册表从不触碰请求前缀，因此这里不会使提供方缓存复用失效。

已知限制与后续工作

陈旧窗口内被复用的 pid 会被信任——bootId 能区分本进程所写记录的 incarnation，但外来记录的 pid 若已被操作系统重新分配给无关的存活进程，在其属主移除之前会一直被报告为存活。

3.3 KiB Raw Blame History Unescape Escape