From e9785a446afee2c8dfce8374867855642f265c81 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 12 Jul 2026 14:56:02 +0800 Subject: [PATCH 1/2] docs(windows): add explicit ProjFS install command to WINDOWS-GUIDE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Enable-WindowsOptionalFeature command to setup table in §1 - Add manual install code block + verify command to §5 (large trees) - Update both English and Chinese versions --- docs/WINDOWS-GUIDE-zh.md | 11 +++++++++-- docs/WINDOWS-GUIDE.md | 11 +++++++++-- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/WINDOWS-GUIDE-zh.md b/docs/WINDOWS-GUIDE-zh.md index 4403d19..e863d47 100644 --- a/docs/WINDOWS-GUIDE-zh.md +++ b/docs/WINDOWS-GUIDE-zh.md @@ -32,7 +32,7 @@ finsafe setup-windows | 组件 | 何时需要 | 说明 | |------|----------|------| | **finsafe-winhelper** 服务 | `network: none` / allowlist（WFP 围栏）、托管舰队 | 缺失时 `doctor` 会告警 | -| **ProjFS**（`Client-ProjFS`） | 可选：AppContainer + 大体积 `venv` / `node_modules` 投影 | 可能重启一次（退出码 **3010**）。典型 Hermes / `network: host` **不需要** | +| **ProjFS**（`Client-ProjFS`） | 可选：AppContainer + 大体积 `venv` / `node_modules` 投影 | 可能重启一次（退出码 **3010**）。典型 Hermes / `network: host` **不需要**。手动安装：`Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS`（管理员） | --- @@ -134,7 +134,14 @@ AppContainer 必须在 FinSAFE 使用的每个文件系统根（`work_dir`、`re 1. **收窄路径** — 只列真正需要的目录 2. **RestrictedToken** — 仅需写白名单的 host 网络 agent -3. **ProjFS 投影** — AppContainer 下的大体积运行时树（`setup-windows`；仅当退出码 **3010** / `restart_required` 时重启） +3. **ProjFS 投影** — AppContainer 下的大体积运行时树（`setup-windows`；仅当退出码 **3010** / `restart_required` 时重启）。手动安装 ProjFS： + + ```powershell + # 需要管理员权限 + Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS + ``` + + 用 `finsafe probe --json | ConvertFrom-Json | Select-Object -ExpandProperty projfs` 验证。 详细表格、环境变量（`FINSAFE_WINSAFE_INHERIT_ROOT_*`）与中断标注恢复：[POLICY-QUICKREF-zh.md § Windows AppContainer 大目录](POLICY-QUICKREF-zh.md)。 diff --git a/docs/WINDOWS-GUIDE.md b/docs/WINDOWS-GUIDE.md index 2aec007..a716771 100644 --- a/docs/WINDOWS-GUIDE.md +++ b/docs/WINDOWS-GUIDE.md @@ -32,7 +32,7 @@ finsafe setup-windows | Piece | Required for | Notes | |-------|----------------|-------| | **finsafe-winhelper** service | `network: none` / allowlist (WFP fence), managed fleet | `doctor` warns if missing | -| **ProjFS** (`Client-ProjFS`) | Optional: AppContainer + large `venv` / `node_modules` projection | May reboot once (exit **3010**). **Not** required for typical Hermes / `network: host` | +| **ProjFS** (`Client-ProjFS`) | Optional: AppContainer + large `venv` / `node_modules` projection | May reboot once (exit **3010**). **Not** required for typical Hermes / `network: host`. Install manually: `Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS` (Admin) | --- @@ -134,7 +134,14 @@ Prefer: 1. **Narrow paths** — only directories the workload needs 2. **RestrictedToken** for host-network agents that only need write allowlisting -3. **ProjFS projection** for large runtime trees under AppContainer (`setup-windows`; reboot only if exit **3010** / `restart_required`) +3. **ProjFS projection** for large runtime trees under AppContainer (`setup-windows`; reboot only if exit **3010** / `restart_required`). To enable ProjFS manually: + + ```powershell + # Requires Administrator + Enable-WindowsOptionalFeature -Online -FeatureName Client-ProjFS + ``` + + Verify with `finsafe probe --json | ConvertFrom-Json | Select-Object -ExpandProperty projfs`. Deep table, env vars (`FINSAFE_WINSAFE_INHERIT_ROOT_*`), and interrupted-label recovery: [POLICY-QUICKREF.md § Windows AppContainer: large roots](POLICY-QUICKREF.md). From 1cde70b72ec75959c32095ff5c14b11f1fb21ff9 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 31 Jul 2026 22:44:09 +0800 Subject: [PATCH 2/2] docs(windows): note git-bash/MSYS2 (Cygwin) incompatibility with RestrictedToken backend Adds a trade-off note to WINDOWS-GUIDE (EN + ZH): the sandbox targets native Windows binaries; MSYS2/Cygwin runtimes (git-bash) cannot initialize under RestrictedToken (CreateFileMapping of user-SID shared-memory object denied), so Hermes tools routed through git-bash (write_file/terminal/execute_code) fail inside the sandbox. References upstream issue #29. --- docs/WINDOWS-GUIDE-zh.md | 12 ++++++++++++ docs/WINDOWS-GUIDE.md | 15 +++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/docs/WINDOWS-GUIDE-zh.md b/docs/WINDOWS-GUIDE-zh.md index e863d47..546023a 100644 --- a/docs/WINDOWS-GUIDE-zh.md +++ b/docs/WINDOWS-GUIDE-zh.md @@ -119,6 +119,18 @@ finsafe --policy .\hermes-windows-oneshot-appcontainer.yaml run -- hermes --vers - 真实终端里的交互式 broker → `finsafe self-confine`（ConPTY） - Agent 专项说明 → [agent-sandbox-guide-zh.md § Windows agents](agent-sandbox-guide-zh.md) +> **关于 git-bash / MSYS2（Cygwin）Agent 的说明：** Windows 沙箱面向**原生 +> Windows 二进制**设计。MSYS2/Cygwin 运行时（如 git-bash）与 `RestrictedToken` +> 后端**不兼容**：受限令牌拒绝了 MSYS2 运行时初始化所需的、以用户 SID 命名的 +> 共享内存对象（`CreateFileMapping`），git-bash 因此中止（`Win32 error 5` / +> `STATUS_DLL_INIT_FAILED`），所有经由它执行的工具都会失败。Hermes 的 +> `write_file` / `terminal` / `execute_code` 工具都通过 git-bash +> （`HERMES_GIT_BASH_PATH`）执行，因此 RestrictedToken 沙箱中的 Hermes 无法 +> 执行文件/工具操作 — 尽管用 `cmd.exe` 直接写入相同的 `read_write_paths` 是 +> 成功的。如果需要在沙箱内完整执行 Hermes 工具，请关注上游修复 +> ([finogeeks/finsafe#29](https://github.com/finogeeks/finsafe/issues/29))， +> 或让 Hermes 工具改用原生 Windows 入口（cmd.exe / PowerShell）而非 git-bash。 + --- ## 5. 仅 AppContainer：大目录与 ProjFS diff --git a/docs/WINDOWS-GUIDE.md b/docs/WINDOWS-GUIDE.md index a716771..3987654 100644 --- a/docs/WINDOWS-GUIDE.md +++ b/docs/WINDOWS-GUIDE.md @@ -119,6 +119,21 @@ finsafe --policy .\hermes-windows-oneshot-appcontainer.yaml run -- hermes --vers - Interactive brokers in a real terminal → `finsafe self-confine` (ConPTY) - Agent-focused notes → [agent-sandbox-guide.md § Windows agents](agent-sandbox-guide.md) +> **Note on git-bash / MSYS2 (Cygwin) agents:** the Windows sandbox is designed for +> **native Windows binaries**. MSYS2/Cygwin runtimes such as git-bash are **not** +> compatible with the `RestrictedToken` backend: the restricted token denies the +> `CreateFileMapping` of the user-SID-named shared-memory object that the MSYS2 +> runtime needs to initialize, so git-bash aborts (`Win32 error 5` / +> `STATUS_DLL_INIT_FAILED`) and every tool that shells out through it fails. +> Hermes' `write_file` / `terminal` / `execute_code` tools route through git-bash +> (`HERMES_GIT_BASH_PATH`), so a Hermes agent confined under RestrictedToken +> cannot perform file/tool operations even though direct `cmd.exe` writes to the +> same `read_write_paths` succeed. If you need full Hermes tool execution under +> the sandbox, keep an eye on the upstream fix +> ([finogeeks/finsafe#29](https://github.com/finogeeks/finsafe/issues/29)) or run +> Hermes tools through a native Windows entry point (cmd.exe / PowerShell) +> instead of git-bash. + --- ## 5. AppContainer-only: large trees and ProjFS