dsh-witness

Part of the DSH plugin suite — six Apache-2.0 plugins for DeepSeek Harness. · DSH 插件套件之一：六个 Apache-2.0 插件。

Crash-surviving background jobs for DeepSeek Harness, where the filesystem is the source of truth. Cross-restart adoption, autopsy reports, sandboxed execution, event sourcing — battle-tested on Windows 11 NTFS, with sandbox backends for Linux and macOS.

给 DeepSeek Harness 的崩溃存活后台任务：文件系统即真相源。跨重启收养、尸检报告、沙箱执行、事件溯源——Windows 11 NTFS 实测；沙箱后端覆盖 Linux 与 macOS。

为什么存在 / Why this exists

Harness 内核自带的后台 jobs 是 fire-and-forget 工具执行（能读输出、能杀，不能对话、不能跨崩溃收养）。真实世界里的长程会话踩过这些公开的坑：

真相源：任务目录解剖 / The truth source

每个任务一个目录，状态就是目录结构的函数：

jobs/
└── pwsh-1/                      # 一个任务 = 一个目录
    ├── state/
    │   ├── running              # 五态标记（任一时刻恰一个为主）
    │   ├── stopping
    │   ├── orphaned             # 崩溃残留（收养判定现场）
    │   ├── adopted              # 新会话已收养
    │   └── done                 # 终态（内容 = 退出码）
    ├── lock                     # O_EXCL 协调锁，内容 = pid:startSec
    ├── spec.json                # 任务规格（kind/label/startedAt）
    ├── out.log                  # 输出（游标续读）
    ├── exit.txt                 # 退出协议（EXIT:<code>）
    ├── autopsy.json             # 尸检报告（终态时生成）
    └── events/                  # 事件溯源
        ├── 0001-started.jsonl
        ├── 0002-output.jsonl
        └── 0003-done.jsonl

三证据收养判定：lock 内容（pid:startSec）+ 进程存活 + 进程启动时间比对（防 PID 复用）。任何时刻 kill -9，重启后新实例扫目录即可收养或结案。

你能得到什么 / What you get

• 跨重启收养——状态机活在目录结构里。任何 force-kill 后，新的 registry 实例用三证据收养或终结每个任务。
• 尸检报告——每个终态任务拿到 autopsy.json（死因、主证据、判决、死因代码 D-01…D-09）+ output 摘要事件。
• 沙箱执行——Windows NTFS ACL 限制在任务 spawn 之前应用：证据文件的覆盖/追加/改名/删除/伪造全被挡；守卫句柄删除 lock 作为完成信号；留痕检测（lock 内容+ACL 结构校验）把自救伪造标记为 tampered（EXIT:-999）。
• 游标续读输出——read(id) 只返回新字节；游标跨重启持久，长输出不重不漏。
• 并发收养安全——50 个独立进程竞争终结同一个孤儿，恰好产生一个终态（幂等 finalize + 原子状态标记）。
• wait/close 生命周期——轮询到终态；干净停掉监控定时器。

快速开始 / Quick start

dsh plugin --profile <name> add "github:Wang-Lin-Chang/dsh-witness#v0.2.0"

仓库提交了编译产物（lib/），git 安装无需构建步骤。

import { WitnessJobRegistry } from 'dsh-witness'

const reg = new WitnessJobRegistry(ctx, {
  jobsRoot: './data/witness-jobs',        // 真相源：每任务一个目录
  indexDbPath: './data/witness-index.db', // 可重建索引缓存
  adoptMonitorMs: 30000,                  // 收养扫描间隔
})

const id = reg.start({ kind: 'pwsh', label: 'long-task', command: 'Start-Sleep 60; Write-Output done' })
const snap = await reg.wait(id, 120000)   // → completed | failed | tampered
const output = reg.read(id)               // 游标式增量读
reg.close()                               // 停监控定时器

验收证据 / Acceptance evidence

test/witness-final-test.ts —— 12 场景 / 34 断言，连跑稳定全绿。实测环境：Windows 11 Pro · Node 25.8 · PowerShell 5.1。

自己跑：node --experimental-strip-types test/witness-final-test.ts

与官方 jobs 的关系 / vs. the built-in jobs

跨平台后端 / Platform backends

Witness 核心（目录真相源、三证据收养、尸检、事件溯源）是平台无关的；沙箱层按平台选配方，三平台同级：

诚实边界 / Honest boundaries

• 平台实测面：Windows 实测于 Windows 11 NTFS + PowerShell 5.1 + Node 25.8（本仓实验账本 EXP-1~EXP-8）；Linux 后端实测于 GitHub Actions ubuntu-latest（34/34 ×3）；macOS 后端实测于 GitHub Actions macos-latest（macOS 26.5.2 arm64，34/34 ×3）。每个后端的实测环境与边界以各自仓库的 README/EXPERIMENTS 为准。
• 离线适用面：架构上无网络依赖（目录真相源 + 本地 SQLite，无云服务、无远程协调）；数天级断网长跑未实测，不声称。
• 任意代码自救超出 ACL 层能力——任务加载原生代码（P/Invoke）可以以文件属主身份自救 ACL。留痕检测把这种伪造变成可见的 tampered 判决而不是默默信任；任意代码层的完全限制是受限 token 的活（见官方 Harness 沙箱配方）。
• 任务永远可以毁掉自己的输出——那只会伤到它自己，并且证据链全程可见。

开发 / Development

npm run build   # tsc 编译 src → lib
npm test        # 运行 12 项验收（node --experimental-strip-types）

要求：Node ≥ 22.5（node:sqlite，实测 25.8）、Windows PowerShell 5.1。

License

Apache-2.0