Skip to content

docs(windows): add git-bash/MSYS2 (Cygwin) incompatibility note to WINDOWS-GUIDE #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
0xReSan wants to merge 2 commits into from
Closed

docs(windows): add git-bash/MSYS2 (Cygwin) incompatibility note to WINDOWS-GUIDE #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e9785a4
docs(windows): add explicit ProjFS install command to WINDOWS-GUIDE
xulis Jul 12, 2026
1cde70b
docs(windows): note git-bash/MSYS2 (Cygwin) incompatibility with Rest…
xulis Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions docs/WINDOWS-GUIDE-zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`（管理员） |

---

Expand Down Expand Up @@ -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
Expand All @@ -134,7 +146,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)。

Expand Down
26 changes: 24 additions & 2 deletions docs/WINDOWS-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) |

---

Expand Down Expand Up @@ -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
Expand All @@ -134,7 +149,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).

Expand Down