feat(sandbox): 统一 OS 沙箱与 Windows workspace-write 后端

[coder-hhx]

Closes #506
Closes #520

Summary

将基础 OS 沙箱与 Windows workspace-write 后端合并为一个面向 main 的 PR，并修复模型驱动 shell 的可恢复 Bash 绕过问题。

根因是 chat 的 Bash 在启用 resumable session 时走 shell_session_start，旧链路没有传递 sandbox policy，Rust 最终以 sandbox_spec=None 启动普通 shell。RANDOM、&&、Git Bash 和 D:/... 路径本身都不是绕过技巧；缺失的策略参数才是漏洞。

现在一次性 Bash、resumable Bash 和 ManagedProcess 共用同一个平台 spawn funnel。resumable session 初始启动和后续 ProcessWait 都保持同一隔离进程，响应返回实际生效的机制，便于审计。

本 PR supersedes #505 和 #518；两个旧 PR 已关闭。

Coverage Matrix

Entry point	Policy propagation	Result
Desktop Chat / Agent Dev	useSendChatTurn -> runAgentConversationTurn -> builtin registry	sandbox / sandboxOffline reaches every shell tool
Worktree subagent	child registry rebuild inherits policy and uses child worktree as fence root	Bash and ManagedProcess remain fenced
Readonly subagent	execution-time allowlist excludes shell and mutation tools	no Bash surface
Gateway direct request	protobuf/JSON command_safety_mode -> desktop listener -> turn	mode preserved
Gateway queued request	queue snapshot and dequeue/replay preserve the mode	mode preserved
Cron Auto Prompt	registry now receives the system command safety mode	model-driven prompt shell is covered

Explicit user-authored cron scripts and hooks remain outside this model-driven Bash contract and retain their existing explicit-script semantics.

Change Scope

• Shared command safety mapping is centralized in sandboxPolicy.ts.
• shell_run, shell_session_start, and managed_process_start always send explicit sandbox and sandbox_allow_network booleans.
• Rust IPC arguments are required; omitted policy data fails at the command boundary instead of silently becoming unsandboxed.
• macOS uses Seatbelt (sandbox-exec); Linux uses bubblewrap (bwrap).
• Windows uses a restricted token (networked write fence) and AppContainer (offline, kernel network denial) without elevation.
• Linux bwrap is resolved to an absolute system path; workspace PATH entries are never used as the wrapper.
• McpManager stdio create/update/enable is refused while the OS sandbox is on.

Screenshots / Preview

Default command mode

Command mode menu

Sandbox mode selected

Windows composer with workspace-write sandbox

Windows 下拉截图已撤下：旧图仍显示 sandboxOffline 不可用，且文案承诺 ~/.ssh 不可读。AppContainer 落地后这两点都过时了，需在真 Windows 主机上重拍（含 sandboxDescNoReadMask）。

Verification

• GUI MCP / shell targeted Node tests — passed
• Rust cargo test --lib sandbox — 29 passed, including Darwin temp-parent layout, bwrap PATH pinning, and Unix workspace-write E2E
• git diff --check — passed

Windows FFI is compile-checked and covered by pure-logic tests, but a real Windows host/Tauri launcher E2E is still required before release.

Pre-submit Checklist

• Requirement issues linked: [Feature] 沙箱模式:命令执行方式选择器 + OS 级沙箱隔离 #506 and [Feature] 沙箱模式:Windows 免管理员 workspace-write 写围栏(受限令牌后端) #520
• Current and base sandbox branches merged into feature/sandbox-unified
• Old PRs feat(sandbox): 对话框内命令执行方式选择器 + OS 级沙箱执行 #505 and feat(sandbox): Windows 免管理员 workspace-write 沙箱后端 #518 closed
• User-facing screenshots included (Windows dropdown pending recapture on a real host)
• Gateway, queue, Cron, worktree, readonly, one-shot, resumable, and ManagedProcess paths audited
• No secrets or personal data included

[xiaozhou26]

对 c125b582 做了一轮针对沙箱边界的审查，以下问题均已对照源码核实。按严重度分组。

---

一、沙箱围栏可被绕过

1. 模型可经 MCP 工具拿到无围栏的进程 spawn 原语 — crates/agent-gui/src-tauri/src/commands/integration/mcp.rs:102

build_stdio_command 最终走到裸 Command::new(program)，不带任何 SandboxSpec。而 createMcpManagerTools 在 builtinRegistry.ts:234-240 是无条件注册的，且不接收 params.sandbox。模型调用 mcp_manager 的 action:"test" 时可传入自由格式的 command/args（mcpManagerTools.ts:118-119）——这条路径不写配置、不持久化，因此 runtimeScope !== "chat" 的守卫不生效。

更关键的是 runAgentConversationTurn.ts:606 的 ask 升级只在 safetyMode === "ask" 时触发，所以选了 sandbox / sandboxOffline 的用户不会收到任何提示。净效果是：选择最严格的模式围住了 shell 工具，却留下一个同样通用的进程 spawn 入口——在 sandboxOffline 下尤其矛盾，该模式的全部意义就是内核级断网。

2. cron bash 任务完全不受沙箱约束，且重启后仍在 — crates/agent-gui/src-tauri/src/services/automation/scheduler.rs:519

run_shell_script 转发给 run_shell_script_with_envs 时尾部两参写死 &[], None（shell_runner.rs:880-887），即 sandbox_options 恒为 None。cron 工具在 builtinRegistry.ts:230 同样未接收 params.sandbox，也无 ask 升级。

用户为了约束一个不可信任务而选择 sandbox，结果 shell 被围住、cron 没有：模型创建一个 bash 任务，调度器在 :519 以无沙箱方式触发，脚本对整个文件系统和网络拥有完整用户权限。持久化让它比一次性逃逸更严重——任务会跨应用重启存活，在沙箱会话早已结束后继续触发。

3. 沙箱开关完全由渲染进程的两个 bool 决定，后端无独立下限 — crates/agent-gui/src-tauri/src/commands/runtime/shell.rs:36

sandbox.then_some(SandboxOptions { allow_network: sandbox_allow_network }) 直接采信前端传值，后端从不回查已持久化的 settings.system.commandSafetyMode 来建立最低标准。任何使 sandbox=false 抵达该命令的路径都能完全绕过围栏。

仓库里已有正确范式可循：ssh_local_forward 在服务端重新解析持久化配置，而不是信任调用方。考虑到 CLAUDE.md 明确"桌面端是工具唯一执行处"，沙箱下限应当落在 Rust 侧，从而不论请求源自哪个 host 都能强制生效。commands/runtime/process.rs:23-25 是同一形态。

---

二、fail-open：失效路径未按 fail-closed 收敛

4. Windows capability() 无运行时探测，模块自身的 fail-closed 守卫在该平台恒不可达 — crates/agent-gui/src-tauri/src/runtime/sandbox.rs:611

其余平台都做真实探测：macOS 在 :421-439 stat /usr/bin/sandbox-exec，Linux 在 :503-547 实际 exec bwrap。Windows 直接返回硬编码的 supported: true, network_control: true, reason: None。

理解注释的论证是两个后端免依赖免提权、恒可用。但若 CreateRestrictedToken 或 AppContainer profile 在 spawn 时失败（组策略、EDR hook、受限 SKU），:404-410 的守卫因为 capability().supported 从来不为 false 而永不触发。叠加 shell_runner.rs:708-716 把 NTSTATUS 加载器失败（0xC0000142/0xC0000135/0xC0000022）归类为"可用"，一个在施加任何限制前就死掉的 launcher 仍会被标记为候选正常——命令随后无约束执行，而 ShellRunResponse.sandbox（shell_runner.rs:1011）照常上报 restricted-token，UI 照常显示沙箱徽标。这与同文件 :8 自述的原则直接冲突："沙箱被请求而平台机制不可用时直接报错，绝不静默降级为无沙箱执行"。

5. validate_workspace 用 starts_with 比较可能带 verbatim 前缀的路径，Windows 下会静默失效 — crates/agent-gui/src-tauri/src/runtime/sandbox.rs:329

canonical_or_self（:316）是 canonicalize(path).unwrap_or_else(|_| path.to_path_buf())：路径存在时返回 \\?\C:\...，不存在时返回原始路径。而 Path::starts_with 是纯词法的组件比较，不做前缀归一。

于是当 write_root 存在但某个敏感目录不存在（或反之，例如机器上有 ~/.ssh 而无 ~/.aws），两侧操作数携带不同前缀形态，dir.starts_with(&root) 即使目录真的在工作区内也会返回 false。按 :319-326 的文档注释，这个函数的全部目的就是拒绝把工作区设为 home 或 /，以免 write_root 的后置 re-allow 重新暴露凭据。比较一旦 fail-open，该守卫被跳过，沙箱会对 ~/.ssh、~/.aws 和 ~/.liveagent（内含 config.sqlite，存放 provider API key）重新放行读写。:727-758 的单测只用了 Unix 形态路径，因此 CI 覆盖不到。

6. 未识别的安全模式静默降级为 auto（最宽松的非 ask 值），且会被写回磁盘 — crates/agent-gui/src-tauri/src/commands/config/settings/system.rs:477

.filter(|v| matches!(*v, "ask"|"auto"|"sandbox"|"sandboxOffline")).unwrap_or("auto") 没有错误分支也没有日志。system_value_with_defaults 会在保存路径上执行它（:497-506），而保存实现是删除全部 system key 再重新插入（:511-538），本 PR 又把 SYSTEM_COMMAND_SAFETY_MODE_KEY 加进了该 key 列表——所以这不只是读取期的默认值，而是破坏性地持久化。

任何未来新增的模式值、任何回退到旧版本、任何手改配置的笔误，都会解析成宽松的 auto 而非显式失败。对于一个全部意义在于约束的设置，未识别值应当向严格侧（ask）收敛，与 sandbox.rs:8 自述的 fail-closed 原则保持一致。

---

三、UI 安全承诺与 Windows 联网后端实现不符

7. 两种语言的文案都承诺"~/.ssh 等敏感目录不可读"，但 Windows 联网后端（restricted-token）没有实现任何读掩蔽 — crates/agent-ui/src/i18n/translations/zhCNCommon.ts:250

macOS 用 (deny file-read* (subpath …))（sandbox.rs:469-472），Linux 用 --tmpfs 掩蔽（:577-581），文案在这两个平台成立。但 Windows 的 WRITE_RESTRICTED 令牌在读/执行上完全跳过 restricting-SID 检查（windows_sandbox.rs:12-14,133,292），ensure_write_ace 只签发 GRANT_ACCESS 且明确从不移除 ACE（:20, :719-791）——windows_sandbox.rs:33-34 本身就把读掩蔽标注为"联网后端缺失项"。

问题在于文案把一个已知缺口转成了肯定的安全承诺：Windows 用户读到该描述，据此认为凭据受保护，于是在 sandbox 模式下运行不可信的模型生成代码。这段代码可以随意读取 ~/.ssh/id_rsa、%USERPROFILE%\.aws\credentials 和 ~/.liveagent/config.sqlite（provider API key），而这恰恰是联网后端，可直接外传。建议在读掩蔽补齐前，让该文案随平台/后端分叉。

---

四、Windows 后端实现细节

8. __sandbox_exec launcher 未复用 validate_workspace，且写 ACE 只授不撤 — crates/agent-gui/src-tauri/src/runtime/windows_sandbox.rs:890

validate_workspace 只在 wrap 路径的 sandbox.rs:404-411 调用；re-exec 出来的 launcher 进程经 win::execute（:866-891）到达 ensure_write_ace（:719-791）时并不重做该校验。同一个 write_root 在两个入口点上前置条件不一致，属于 fail-closed 的不对称，且会随任一侧演进而继续漂移。

另外 ensure_write_ace 通过 SetNamedSecurityInfoW 授予 FILE_GENERIC_READ|WRITE|EXECUTE|DELETE，带 OBJECT_INHERIT_ACE | CONTAINER_INHERIT_ACE（:752-755），而全文件没有任何 REVOKE_ACCESS / DeleteAce。结果是每个在 sandbox 模式下用过的工作区都会永久累积一条可继承 ACE，对应一个不再映射到任何活跃主体的合成 S-1-5-21 SID，此后该目录下新建的每个文件都会继承它。用户会在文件夹权限里看到无法解析的 SID，且卸载 LiveAgent 不会清理。

---

五、设计问题（非缺陷，供讨论）

9. 安全模式优先级链缺少 max-strictness 钳制 — crates/agent-gui/src/pages/chat/runtime/useSendChatTurn.ts:342

overrides ?? gatewayBridgeRequest ?? settings.system.commandSafetyMode 是首个非空值胜出。注释写明远端 WebUI 选定的模式经此生效是有意设计（P1#1），这点理解。

但链路上没有任何一处与本地设置做严格度比较。WebUI 经 gatewaySocketShared.ts:473 把自己快照里的值送上 proto ChatRequest.command_safety_mode，于是一个刻意选择了 sandboxOffline 的桌面用户，其选择会被任何浏览器会话的陈旧快照静默降级为 auto。鉴于 CLAUDE.md 的核心不变式是"桌面端是工具唯一执行处"，这里是远端取值在决定本地进程的约束强度。是否考虑改成取远端与本地中更严格的一方？这样既保留远端收紧的能力，又不允许远端放松。

---

审查覆盖沙箱边界相关改动；未逐行审查 UI 文案与文档的其余部分。若某条判断有误请指出。

[github-actions]

PR governance checks passed. Awaiting human review.

[su-fen]

跟进审查结论，已在 96c124bf 修完当时列出的全部问题。

P1

1. macOS TMPDIR=/tmp 写围栏塌缩 — writable_temp_dirs 不再对任意 TMPDIR 做 parent()。只有 Darwin /var/folders/<xx>/<rand>/T（含 /private/var/folders/.../T）才提升到父级；/、$HOME 以及会包住敏感目录的临时根直接丢弃，避免 Seatbelt last-match-wins 把整盘（含 ~/.ssh）重新放行。
2. McpManager create/update/enable 仍能种无沙箱 stdio 进程 — assertRuntimeSpawnAllowed 现在也拦配置写入。沙箱开启时拒绝 stdio 的 create / update / enable；http/sse 与 disable/delete 不受影响。下一轮 registry 不能再靠模型写入的 stdio server 绕过围栏。
3. Linux 相对名 bwrap 走 PATH — 探测和 wrap 都解析绝对路径：优先 /usr/bin/bwrap、/usr/local/bin/bwrap，再只搜绝对 PATH 目录，并跳过工作区（node_modules/.bin、.venv/bin 等）。工作区内的同名二进制永远不会当包装器。

P2

4. 选择器 null 能力仍承诺「~/.ssh 不可读」 — capability === null 改为保守按「无读掩蔽」处理。WebUI 一直拿不到桌面 mechanism，因此会走 sandboxDescNoReadMask，不再给出过强承诺。
5. Bash 工具描述在 Windows 联网沙箱仍声称凭据目录被掩蔽 — 仅在非 Windows、或 Windows 断网（AppContainer）时才写 credential dirs are masked。

P3

6. Windows 下拉截图过时 — 已删除 docs/images/sandbox-mode/windows-selector-dropdown.png（图上仍是 sandboxOffline 禁用 + 旧断网文案 + 读掩蔽承诺）。composer 截图保留。真 Windows 主机 E2E 时需要重拍下拉（offline 可用 + sandboxDescNoReadMask）。

验证

• cargo test --lib sandbox：29 passed（含 Darwin temp parent、bwrap PATH、Unix workspace-write E2E）
• mcp-manager-tools / shell-tools Node 测试：60 passed

Windows 受限令牌 / AppContainer / CreateProcess* 仍缺真机 E2E，这一条审查时就标了，不在这次代码修复范围内。

[su-fen]

跟进 Windows 沙箱里 PowerShell 启动即死（日志写 BCrypt.dll 加载失败、exit_code=-532462766），已在 5fd878d7 修。

这不是本机 pwsh 坏了。启动器的 CreateProcessAsUserW 已经成功；崩在 WRITE_RESTRICTED 第二遍写检查，拦住了 CNG/CAPI 初始化时对用户证书库的写入。CAPI 返回 NTE_PROVIDER_DLL_FAIL，PowerShell/.NET 再包装成 CLR 0xE0434352（即 -532462766），日志就写成「BCrypt.dll 加载失败」——DLL 映射其实是成功的。同令牌下 cmd.exe 能活，是因为它不走这条初始化。这和 Git Bash 的 0xC0000142（default DACL / msys 内核对象）不是同一类问题。

改动

1. 窄 CNG 用户写面 — 启动器在 CreateProcess* 前用同一个 fence_sid 给 HKCU\...\SystemCertificates / Cryptography 以及 %APPDATA%\Microsoft\Crypto|Protect、%LOCALAPPDATA%\Microsoft\CryptnetUrlCache 盖可继承写 ACE。不放开整个 HKCU / AppData，也不 stamp HKLM（需管理员）。单项失败只告警，不把整个沙箱判死。
2. 探测回退 — 0xE0434352 / 0x8009001D 视为启动即死。pwsh 仍崩则跳到下一候选；cmd 不走 CNG，作为兜底。此前探测只认 NTSTATUS loader 三码，会把已经崩溃的 pwsh 当成可用。
3. 拒绝 Store/MSIX WindowsApps\pwsh.exe — 受限令牌下 CreateProcessAsUserW 对打包二进制返回 5，和 BCrypt 无关，不能当沙箱 shell。

验证

• cargo test --lib -- runtime::sandbox:: runtime::shell_runner::tests::sandbox_probe：28 passed（含 CNG 写面范围、WindowsApps 路径、CLR -532462766 探测裁决）
• Windows CreateProcess* / 真机 pwsh 仍缺 E2E。请在 Windows 沙箱里跑一条 exit 0：预期 pwsh 能活过 CNG init；若某台机器还必须写 HKLM 证书库，应看到探测跳过并落到 cmd，而不是再把 0xE0434352 回给用户。

[su-fen]

已推送修复提交 561af38e（fix(sandbox): preserve workspace access across Windows modes）。

根因

断网 AppContainer 之前直接向工作区写入 package SID ACE。该 ACL 会与普通联网 Low-IL 沙箱的访问模型冲突，导致后续 Bash / ManagedProcess 甚至无法列目录，而不只是“禁止写入”。

修复

• 断网模式改为使用“每工作区唯一”的自定义 capability SID，不授予任何网络 capability；AppContainer / WFP 仍负责断网。
• 启动时精确撤销旧 AppContainer package SID ACE，自动迁移已经被旧实现写入 ACL 的工作区。
• 普通“沙箱”模式继续使用非 restricted 的 Low-IL duplicated primary token，保留网络访问。
• 只有“沙箱·断网”模式阻断网络；两种模式均可按策略读写工作区。
• 同步覆盖 Bash、PowerShell、ManagedProcess、shell session/runner 等执行路径，并补充模式切换与旧 ACL 迁移回归测试。

验证

• cargo check -p liveagent --tests：通过。
• Windows 沙箱定向真机测试：15/15 通过。
• 真实工作区 D:\code\project\test-project\001：
  • 普通沙箱下 cmd、Git Bash、PowerShell 均可读写，HTTPS 返回 200。
  • 断网沙箱仍可读写工作区，DNS/外网失败，curl exit 6。
  • 从断网切回普通沙箱后读写与联网仍正常。
• git diff --check：通过。
• cargo test -p liveagent --lib：894 passed / 22 failed。失败集中在现有 Windows/Linux 路径假设、hook shell 选择和全套并行运行时的 MSYS 命名空间冲突；随后重新运行 Windows 定向套件仍为 15/15 通过，因此这里不将整库测试描述为全绿。