dsh-winstage-sandbox

WinStageSandbox — Windows 暂存—候选—选择性提交沙箱

按《Agent 沙箱暂存—提交架构设计手册 v3.0》实现，面向 Windows + DeepSeek Harness。

核心思路：把"隔离"和"暂存"合并成同一件事——沙箱唯一可写根是暂存树， 真实工作区始终不被写入；沙箱内产生的变化冻结为候选，用户批准后才逐文件提交。

---

安装（DSH 插件）

# npm（已发布时）
dsh plugin --profile web add dsh-winstage-sandbox
# 或直接从 GitHub 安装（无需 npm）
dsh plugin --profile web add github:gygygfg/dsh-winstage-sandbox

• 前置：Windows 10/11；启动时会做环境监测（非 Windows 或本会话无法建立受限令牌 ⇒ 拒绝启动，逃生口 WINSTAGE_SKIP_ENV_GATE=1）。
• 开关：设置页可开关。关闭时文件面立即退回平台 SandboxedFileSystem，命令面在装配期 交还平台 pwsh-sandbox（运行中切换需重启宿主）。详见 docs/插件启动-环境监测与开关保证.md。
• shim：发行包只带 C 源码；需要透明模式先在本机 node tools/fetch-toolchain.mjs 再 node tools/build-shim.mjs。
• 发布/收录说明见 PUBLISHING.md。

---

1. 快速开始

cd C:\Users\Administrator\Desktop\dsh-winstage-sandbox

# ★ 一键跑完全部测试（推荐从这里开始）
.\autotest.cmd                    # 全部套件 + 生成 JSON 报告
.\autotest.cmd --skip-audit       # 只跑离线确定性测试（不需要未受限会话）
.\autotest.cmd --verbose          # 失败时打印完整输出

# 其他入口
.\verify.cmd                      # 25 套件离线测试的轻量版（无报告；清单 = OFFLINE_SUITES）
.\diag.cmd                        # 绑定表契约 + 完整 init（需未受限会话）

1.1 自动测试运行器 autotest.cmd / autotest.mjs

一次运行 25 个离线套件 + 4 个沙箱套件 + 1 段沙箱审计，分三段，并写出机器可读报告：

⚠ 清单口径以代码为准：OFFLINE_SUITES 是唯一权威，verify.cmd 的循环列表必须与之逐字一致。 这件事从第三轮起由 tests/suite-wiring.mjs 机器检查（此前两张清单曾静默地顺序漂移）。

退出码：0 无失败（含因机制边界跳过 C 段）｜1 存在失败｜2 环境错误。

三种总判定：

• PASS —— 全部通过
• PASS-OFFLINE-ONLY —— 离线全通过，但 C 段因当前会话受限、无法建立嵌套沙箱而跳过。 这是机制边界不是失败，报告中会在 guaranteesNotProvided 里写明"未提供的保证"。
• FAIL —— 存在失败套件

报告写到 .t/test-report.json，含每个套件的状态、耗时、断言计数、原始输出路径， 以及按手册第 17 章要求的 guaranteesNotProvided（仍未提供的保证）。

失败时自动打印最后一个失败套件的末尾输出以及 audit 的 fail 明细，便于直接定位。

为什么 autotest 是 Node 而不是 .ps1：本机执行策略为 RemoteSigned 且脚本未签名， .ps1 需要 -ExecutionPolicy Bypass，而 Bypass 子进程在本环境被拒。 用 Node 编写没有执行策略摩擦，也便于复用模块判断"本会话能否建立嵌套沙箱"。

为什么需要 .cmd 包装：受限令牌下 spawnSync 默认的 stdio: 'pipe' 走命名管道， 客户端打开请求需要受限 SID 未被授予的写权限，子进程创建直接 EPERM。 运行器改用文件描述符重定向捕获输出，完全绕开命名管道。 这正是 run.cmd 存在的原因，已作为文档化残余边界 R10 记录。

1.2 元测试：运行器本身必须能检出失败

tests/meta-runner.mjs 用"人为失败的子进程"反证运行器的判定逻辑。 一个永远不会报失败的运行器比没有运行器更糟 —— 它给出虚假的绿色。 （本项目已经踩过一次"假通过"的坑：缺陷 11，见 docs/实测证据记录.md。）

1.3 手动调用

# 初始化暂存区
.\run.cmd src\cli.mjs init    --workspace .\.t\ws

# 在 Windows 受限令牌沙箱内执行命令（写操作落进暂存树）
.\run.cmd src\cli.mjs exec    --workspace .\.t\ws -- powershell -NoProfile -Command "ni new.txt"

# 查看状态 / 待审 / diff
.\run.cmd src\cli.mjs status  --workspace .\.t\ws
.\run.cmd src\cli.mjs review  --workspace .\.t\ws
.\run.cmd src\cli.mjs diff    --workspace .\.t\ws

# 选择性提交（只应用部分路径）
.\run.cmd src\cli.mjs apply   --workspace .\.t\ws --paths new.txt

# 从沙箱内部发起真实攻击探针
.\run.cmd src\cli.mjs audit   --workspace .\.t\ws

1.4 自动测试服务（请求即测试，完成后返回输出）

不想守着终端时，可以起一个常驻服务，收到请求就跑测试并返回结果。

# 启动服务（默认 127.0.0.1:8737，随机令牌会打印在控制台）
.\testservice.cmd
.\testservice.cmd --port 8800 --token mytoken      # 指定端口与令牌

# 用客户端触发（推荐，省得记 curl 语法）
node src\testclient.mjs --url http://127.0.0.1:8737 --token <令牌>
node src\testclient.mjs --token <令牌> --only selftest,audit
node src\testclient.mjs --token <令牌> --async        # 立即返回 jobId
node src\testclient.mjs --token <令牌> --watch <jobId>
node src\testclient.mjs --token <令牌> --log <jobId>

API

请求体（JSON，可选）：{ "workspace": ".t/ws", "skipAudit": false, "only": ["selftest"] } 同名参数也可走 query string（?wait=0 等效于异步）。

实测示例

POST /run {}
→ overall = PASS-OFFLINE-ONLY
  套件 8 通过 / 0 失败 / 1 跳过   断言 222 ok / 0 bad   1203 ms
  [PASS                  ] selftest            217 ms  48 ok / 0 bad
  ...
  [SKIPPED-NESTING-LIMIT ] audit               113 ms   2 ok / 0 bad  coverage=13%

安全边界（R13–R16，不是可选项）

这个服务按请求执行本机测试套件，本质上是本机代码执行入口。因此：

为什么必须串行：手册第 17.2 节要求套件隔离配置、注册表、cwd、缓存、端口与持久状态。 并发跑两轮测试会让它们争用同一份 .t 工作区，产生"偶发失败"这类最难查的问题。

为什么用 Node 内置 http：零依赖，且与测试同栈 —— 服务与 CLI 直接复用 src/testrunner.mjs 的同一份套件清单与判定逻辑，避免"CLI 说通过、服务说失败"的漂移。

注意：Start-Process 和 start /b 在本沙箱下都无法让服务常驻（进程随父 shell 退出）， 请在前台运行 testservice.cmd，或用后台作业方式启动。

---

2. 架构

┌─────────────────────────────────────────────────────────────────────┐
│ 逻辑视图（对 AI 唯一可见的世界）                                     │
│   read_file / write_file / edit_file / delete_file / list_files      │
│   / search_files            → src/tools.mjs   （进程内层：同一投影）  │
├─────────────────────────────────────────────────────────────────────┤
│ 统一工作区服务 Workspace Service                    → src/workspace.mjs│
│   基线快照 · 逻辑状态(暂存/删除/损坏) · 目录合成 · 路径映射           │
│   候选冻结(before+after) · 选择性应用 · 陈旧基线保护                  │
│                                     ↓ src/store.mjs                  │
│   内容寻址 blob 存储（自动去重，候选两侧不可变）                      │
├─────────────────────────────────────────────────────────────────────┤
│ 受信启动器（Windows 原生隔离）                     → src/executor.mjs │
│   WRITE_RESTRICTED 受限令牌（限制 SID 交集=唯一可写根）               │
│   + Low 完整性标签（no-write-up 兜底）                               │
│   + deny FILE_DELETE_CHILD（关闭父目录删除权旁路）                   │
│   + Job Object KILL_ON_JOB_CLOSE（进程树回收）                       │
│   + 环境变量从允许清单重建（绝不 merge 父环境）                      │
│   + 显式 lpEnvironment（绕开依赖包 lpEnvironment=NULL 的限制）       │
├─────────────────────────────────────────────────────────────────────┤
│ 能力探测 CapabilityProbe                            → src/capability.mjs│
│   真实 Win32 调用实测 · 环境指纹缓存 · 档位选择 · fail-closed         │
├─────────────────────────────────────────────────────────────────────┤
│ 审计（沙箱内攻击探针）                                 → src/audit.mjs │
└─────────────────────────────────────────────────────────────────────┘

文件清单

---

3. 手册不变量 → 实现位置 → 自测证据

自测结果：48 / 48 通过。 详细报告：.t/selftest-report.json。

自测抓出的前 3 个真实缺陷（安全相关，全部已修）

按手册第 17 章纪律，失败用例暴露的是实现缺陷而非测试问题：

1. 遮蔽顺序写反（安全相关）：maskOf() 先查遮蔽表、后用 isInside() 判豁免， 而 isInside() 内部会 canonical 化 → 工作区内指向宿主敏感目录的 junction 被误判为"在工作区内"而获得豁免。修复：先 canonical 解析，只有解析后仍在 工作区内才谈豁免。（手册 #16.6 / #16.8）
2. 边界判定混淆词法与 canonical：relative() 用 canonical 判定， 导致 junction 逃逸时直接抛异常，遮蔽表没有机会给出 SANDBOX_PATH_MASKED。 修复：新增 lexicalInside()，边界判定用词法，逃逸交给遮蔽判定。（手册 #16.7）
3. 存在性查询以异常表达"不可见"：exists() 经 relative() 抛 PATH_OUTSIDE_WORKSPACE，而不是返回不可见。修复：存在性用词法判定， 解析后逃逸返回 source: 'masked' 且不暴露解析目标。

其余 13 个缺陷（编号 4–16）见下面 §4 的完整清单。

---

4. 当前实测状态（诚实声明）

关键结论：同一份代码在受限会话内无法建立沙箱、在未受限会话内可以。 这从两侧实测证明了"Windows 进程隔离不可嵌套"。

★ 验收结论（第 12 轮，未受限 PowerShell）

汇总: {"pass":19,"fail":0,"residual":3,"informational":2,"not-run":0}
覆盖度: 100%  判定: pass-with-residuals

3 个 ⚠ 是如实声明的残余边界 R1（本后端限制写/删但不限制读取），不是失败， 但不得声明为硬边界（手册 #16.10）。

[实测] 隔离不可嵌套：受限会话内令牌缺 TOKEN_ADJUST_DEFAULT / TOKEN_ADJUST_SESSIONID， CreateRestrictedToken 失败；在未受限会话内同一调用成功。 因此沙箱必须由未受限宿主进程建立，在已受限会话内必须 fail-closed。

完整证据与"仍未提供的保证"见 docs/实测证据记录.md §C.1.1 与 §D。

实测暴露的 16 个真实缺陷（已全部修复）

十一条方法论教训：

• 缺陷 4：归因纪律。 审计原先把"沙箱建立失败"一律解释成"嵌套不可用"， 于是一个代码缺陷被伪装成环境限制。若不核对，它会被永久归因给令牌。
• 缺陷 5：不要凭记忆写结构体布局。 该错误连过两轮审计，因为受限会话跑不到那一步。
• 缺陷 6+7：命令能不能起来，必须被独立测试。
• 缺陷 8+9：编排层必须能被离线测试。
• 缺陷 11（最严重）：空结果不是拒绝。 它让审计报出了一组完全错误的结论—— 10 项"读取被拒绝"全是假通过。这比"探测失败"危险得多，因为它伪装成证据。 也正是它让缺陷 13、14、15 在此前永远无法被发现。
• 缺陷 12：工具选择错误。 用 shell 往返文本处理非 ASCII 源码是自伤行为。
• 缺陷 13：补参数别漏配套标志。 一路走到第 8 轮才暴露。
• 缺陷 14：自检必须是只读的。 "把自身挂进 Job 再查询"改变了运行期状态， 反而制造了它本要预防的故障（手册第 17.2 节同一道理）。
• 缺陷 15：替身失真比没有替身更危险。 我给假 child 伪造了真实库并不存在的 wait()， 于是离线测试全绿、真实环境立刻炸。替身必须逐字段对齐真实 API， 宁可让它复杂，也不要让它比真实对象"更好用"（与手册第 15.5 节同类错误）。

失败点逐层后移的时间线（1 批处理 → 2/4 绑定表 → 3 Job 长度 → 5 结构体偏移 → 6/7 命令解析 → 11/12 结论可信性 → 13 创建参数 → 14 Job 配额 → 15 结果收集 API）说明： 把"假通过"改成"明确失败 + 可定位诊断"是整个工作的转折点。

现在有 6 组不依赖 Win32 的确定性测试，一条命令即可全跑：

.\verify.cmd     # 25 套件（清单 = OFFLINE_SUITES）；权威表与断言数口径见 §8.2

⚠️ 上表是第二轮之前的旧口径，已被 §8.2 的权威表取代：executor-stub 72 → 84、audit-parse 23 → 43、 appcontainer-layout 27 → 34、e2e-flow 16 → 21、command-selftest（§7）22 → 24， 并新增 paths-masks 37 / registry-guard 125 / workspace-regressions 10。 旧文"verify.cmd 现为 11 套件 / 452 断言；autotest --skip-audit 为 12 套件 / 474 ok"是第二轮时点口径， 第三轮起 verify.cmd 覆盖 20 个离线套件（含网络策略 / 进程缓解 / 资源上限 / WFP 布局 / 两个治理套件）， 本轮 C3 追加 policy-never-consistency ⇒ 21 个；此后「补丁工具包 ＋ 源码封印」轮 ⇒ 23、 缺陷③轮 ⇒ 24、缺陷①b轮 ⇒ 25（断言数已由 finisher 全量复跑填入：2034 标记 / RESULT: ALL PASS —— 见 §8.2）。

详见 docs/实测证据记录.md §C.2。

---

5. 档位与实现状态

5.1 各 Windows 原语的实现状态（诚实区分"已实现/已探测/未实现"）

本项目的目标里点名了 5 类 Windows 原生能力。必须逐类说清到底做到哪一步， 不能让"档位表里出现过 AppContainer"被读成"AppContainer 已经能用"：

因此：

• T0 的隔离已 [实测] 生效，T0 也已接进执行器；但默认档位仍然是 T1。 准确说法（逐条，别再互相矛盾）： ① T0 已经接线：显式请求 tier: 'T0' 时，src/executor.mjs:3380-3382（selectLaunchMode('T0') → 'appcontainer'）、 :1544-1547（写入 launchMode）、:1669-1704（装配 createAppContainerLauncher，失败即 SANDBOX_UNAVAILABLE、不静默回退 T1）、:2181-2192（T0 启动分支）真的会走 AppContainer 路径； ② 但默认选不到 T0：执行器默认 this.tier = options.tier || 'T1'（src/executor.mjs:1304）， 只有调用方显式点名 T0 才会用； ③ 能力报告的档位建议 selectTier() 的 T0 闸门逐字仍是 report.appContainerIsolation?.proven === true（src/capability.mjs:1436，四条同时成立见 :1462）， 而 proven 需要跑一次真实隔离探针 —— 没有探针结果时 T0 一律 fail-closed。 因此"默认路径跑在 T1"是档位默认值 + selectTier() 闸门两件事的结果， 不是"T0 没接线"；反过来，proven=true 也不等于"沙箱已经默认用上隔离"。
• AppContainer 布局已用合成缓冲区离线钉死（34 项），这是从缺陷 5（Job 结构体偏移错 4 字节） 与缺陷 13（漏 CREATE_UNICODE_ENVIRONMENT）总结出的做法：先把布局测对，再谈运行。
• 网络面：策略层已存在，真实强制仍是 [未实测]。src/netpolicy.mjs + src/wfp.mjs 的 OFFLINE 判定是 fail-closed（能力不足即 refused，绝不 enforced:true），但本机未安装任何真实 WFP 过滤器 ⇒ 沙箱内实际仍可开 socket，"已断网"的说法依旧不成立（R2）。详见 §9.1。 （补：T0 自己的网络阻断只是"不声明能力"的默认值——一旦声明 internetClient 网络即通， 所以能力集必须由策略层白名单化，不能由调用方随手传。）
• 旧结论更正：早先由本表读出的"AppContainer 探测 E_ACCESSDENIED ⇒ 隔离为零 / 进不了容器" 已被推翻 —— 那是判据错误（拿 TokenUser 比包 SID，而 AppContainer 令牌的 TokenUser 本来就是用户 SID，包身份在 TokenAppContainerSid(31)，且包 SID 不在 TokenGroups 里）。 详见 §8 与 .t/sbx3/dev/03-FIX-B报告.md。

5.2 档位表

档位由 selectTier() 依据真实 Win32 调用结果选择，不据文档推断。

---

6. 已知残余边界

完整清单见 docs/Windows功能开启清单.md 第 13 节（R1–R12）。最关键几条：

• R1 读取面不收敛：本后端限制写/删，不限制读。读取面收敛只能靠 AppContainer （T0 已实现、隔离 [实测] 生效、且已接进执行器，但默认档位是 T1 —— 见 §5.1/§5.2） 或工具层硬拒绝清单。
• R2 网络面不收敛：网络策略层已存在且 OFFLINE 档位 fail-closed，但本机未安装真实过滤器 （[未实测]）⇒ 沙箱内实际仍可开 socket。见 §5.1、§9.1。
• R6 嵌套隔离不可用：已受限进程无法再建受限令牌 → 沙箱必须由未受限宿主进程建立。
• R7 环境块需运行时注入：依赖包的受限 spawn 固定传 lpEnvironment=NULL（继承父环境， 违反手册 #8.3）；本实现替换绑定表注入显式环境块，并在结构不符时 fail-closed 拒绝启动， 绝不静默退回继承父环境。

---

7. DSH 集成：暂存审批悬浮窗

把本沙箱接进 DeepSeek Harness，使 DSH 自己的 write/edit 工具也落暂存树， 并在输入框上方给出「待审文件 + 逐文件 diff + 批准/拒绝」的悬浮窗：

• 装配与数据通路（为什么用 review.json + /winstage 命令而不是新的 Remote 命名空间）、 实测证据、已知崩溃风险（在线切换该 bundle 会让宿主进程退出，改配置后请重启）、 残余边界（shell 写入不经过暂存等）：见 docs/DSH集成.md。
• 三套可重复跑的离线自测：.t/review-selftest.mjs（26 项）、 .t/staging-fs-selftest.mjs（31 项）、.t/command-selftest.mjs（22 项）。
• /winstage [list|diff|approve|reject|refresh] 是人工侧的批准入口；命令不产生模型消息。

7.1 第二实例 + 真实浏览器实测（2026-09-28）

在独立的第二个 DSH 实例（另一端口、独立 DSH_HOME）上装了本插件，用真实浏览器（CDP） 把面板看得见、点得动逐条验过。结论摘要，证据见 需求与验收 / 基线报告 / 修复报告 / 发现台账：

• 面板确实出现（headless + 有头双证据，截图在 .t/dsh2/browser/）； 「批准所选」后 review.json 变化且文件真的落盘，「暂时收起」后消失。
• 修掉 7 个缺陷，其中两个是"看不见就永远查不出来"的： ① loader 行名用子路径 specifier ⇒ client 半永不下发（面板永远不出现，刷新无效）； ② 命令定义写成 input: { placeholder } 而校验器要 hint ⇒ 注册抛错 ⇒ /winstage* 一条都没注册 ⇒ 面板的批准/拒绝静默失效。
• 两条硬规则（改 composition 前必读）：host 行必须用裸包名、fs 行必须保留子路径； 且 profile 覆盖层必须重述该行 config 的所有键（config 是整体替换、不是深合并， 漏写的键静默消失）。
• 环境事实：本 Agent 沙箱内起不了 Chromium（Mojo 要命名管道），浏览器验收必须在 沙箱外的终端启动浏览器再用 CDP 操作 —— Runbook 见 .t/dsh2/S5-浏览器Runbook.md。

本节写于当时，其中一条已经作废（整理轮更正）：原文写"改动尚未提交 git（本环境 PATH 上没有 git）"，而本机确有 git 2.55，且 dsh-plugin/ 下的 cordis.patch.yml、 host-plugin.mjs、client.js、staging-fs.mjs、fs-entry.mjs 已随后续 "整理仓库并纳入插件与测试"入版本库。整理轮（测试套件入库）又把此前一直未跟踪的 tests/*.mjs、tools/*.mjs、src/ 与 dsh-plugin/ 的漏项、patches/ 一并入库， 详见 §11 与 .gitignore 头部的两条设计原则。

---

8. 第二轮修复（FIX