evolcore 0.0.25 → 0.0.26

package/kits/docs/evolcore/codex-windows-sandbox.md

@@ -1,146 +1,146 @@
-# Windows 上的 Codex Sandbox 权限排障
-
-本文适用于 EvolCore 在 Windows 上调用 Codex 时，任务在启动阶段因 sandbox 权限失败的情况。目标运行方式是：Codex Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行；只有 Codex sandbox 的安装或修复过程临时通过 UAC 提权。
-
-不要为了绕过 sandbox 错误而长期以管理员身份运行全部组件。这样不仅扩大权限，还可能使高完整性 daemon 创建的命名管道拒绝普通权限 `ec` CLI 连接。
-
-## 典型错误
-
-### `.sandbox-bin` 无法锁定
-
-```text
-helper_sandbox_lock_failed: lock sandbox bin dir C:\Users\<user>\.codex\.sandbox-bin failed:
-SetNamedSecurityInfoW sandbox dir failed: 5
-```
-
-错误码 5 是 Windows `ACCESS_DENIED`。常见原因是 `.sandbox-bin` 归 `BUILTIN\Administrators` 所有，而当前普通用户只有 `Modify`，没有修改 DACL 所需的 `WRITE_DAC`。Codex 的日常 sandbox refresh 不会请求 UAC，因此无法自行修复这个状态。
-
-### `unelevated` 无法执行 deny-read
-
-```text
-windows unelevated restricted-token sandbox cannot enforce deny-read restrictions directly;
-refusing to run unsandboxed
-```
-
-这不是同一个错误。EvolCore 会为托管 Agent 注入 deny-read 限制；Windows 的 `unelevated` backend 无法实施这些限制并会 fail closed。因此不要把下面的配置当作修复：
-
-```toml
-[windows]
-sandbox = "unelevated"
-```
-
-需要 deny-read 时应继续使用：
-
-```toml
-[windows]
-sandbox = "elevated"
-```
-
-这里的 `elevated` 指 sandbox provisioning 能通过 UAC 建立受限账户和 ACL，不表示 Desktop 或 EvolCore 必须一直以管理员运行。
-
-## 先确认错误属于哪一层
-
-在普通 PowerShell 中执行：
-
-```powershell
-codex --version
-codex doctor --json
-whoami /groups
-
-$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
-Get-Item -LiteralPath $sandboxBin -Force |
-  Select-Object FullName, Attributes, LinkType
-Get-Acl -LiteralPath $sandboxBin |
-  Select-Object Owner, AreAccessRulesProtected, Sddl
-```
-
-同时检查：
-
-```powershell
-Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_error.json')
-Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_marker.json')
-Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\sandbox.*.log') -Tail 80
-```
-
-注意以下边界：
-
-| 现象 | 所属层 | 处理方向 |
-|------|--------|----------|
-| `helper_sandbox_lock_failed` / `SetNamedSecurityInfoW ... 5` | Codex sandbox ACL | 重新 provisioning 或修复 `.sandbox-bin` owner |
-| `unelevated ... cannot enforce deny-read` | Codex sandbox 模式 | 使用 `windows.sandbox = "elevated"` |
-| `connect EPERM \\.\pipe\daemon-*` | EvolCore IPC | 让 daemon 与 CLI 使用相同用户和完整性级别 |
-| sandbox 已启动，随后出现 `POLICY_DENIED` | EvolCore 角色/权限策略 | 检查任务发起者角色和 permission mode |
-
-共享同一个项目目录或同一个 `CODEX_HOME` 本身不是错误。关键是宿主进程的完整性级别一致，以及 sandbox 基础 ACL 已正确 provisioning。
-
-## 推荐修复：重新执行 elevated provisioning
-
-1. 结束正在启动的 Codex Agent 任务，保留 Codex Desktop 和 EvolCore 的普通权限运行方式。
-2. 将 Codex Desktop 与独立安装的 Codex CLI 更新到兼容版本，避免两个版本交替刷新同一 `CODEX_HOME`。
-3. 在 Codex Desktop 的 Windows Sandbox 设置中执行 setup/repair，选择 elevated backend，并接受一次 UAC 提示。对应的 app-server 操作为 `windowsSandbox/setupStart`，模式为 `elevated`；普通用户不应自行拼接内部 RPC。
-4. provisioning 完成后关闭管理员窗口。后续 Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行。
-5. 在普通 PowerShell 中执行验证命令。
-
-```powershell
-codex doctor --json
-codex sandbox -- cmd /c whoami
-```
-
-验收结果应满足：
-
-- `codex doctor` 中 sandbox backend 为 `elevated`，provisioning 为 `complete`，没有 `helper_sandbox_lock_failed`。
-- `codex sandbox -- cmd /c whoami` 成功，身份是专用 sandbox 用户（例如 `CodexSandboxOffline` 或 `CodexSandboxOnline`），而不是当前桌面用户。
-- 普通权限 EvolCore 任务可以进入模型执行阶段。
-
-如果 setup/repair 仍反复失败，优先使用 Codex 的修复或重新安装流程。不要先清空整个 `.codex`，其中包含会话、认证和其他用户数据。
-
-## 已验证的定向 workaround
-
-仅当官方 repair 无法完成、错误明确为 `.sandbox-bin` owner/DACL 不一致时使用。此方法只修复目录 owner，不递归改文件权限，也不删除或放宽现有 DACL。
-
-先在普通 PowerShell 中确认目标是实体目录而非重解析点：
-
-```powershell
-$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
-$item = Get-Item -LiteralPath $sandboxBin -Force
-if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
-  throw "$sandboxBin is a reparse point; stop and inspect it manually"
-}
-Get-Acl -LiteralPath $sandboxBin | Format-List Owner, Sddl
-```
-
-然后只为下面一次操作打开管理员 PowerShell：
-
-```powershell
-$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
-$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
-$acl = Get-Acl -LiteralPath $sandboxBin
-$acl.SetOwner([Security.Principal.NTAccount]::new($currentUser))
-Set-Acl -LiteralPath $sandboxBin -AclObject $acl
-```
-
-关闭管理员 PowerShell，在普通 PowerShell 中重新运行：
-
-```powershell
-codex sandbox -- cmd /c whoami
-codex doctor --json
-```
-
-本 workaround 已验证可以让普通权限 refresh 越过 `SetNamedSecurityInfoW ... 5`，但它不是替代官方 provisioning 的长期安装流程。Codex 更新或 repair 可能重新设置 owner；若问题复发，应保留 `doctor` 输出和 sandbox 日志并反馈给 Codex，而不是持续扩大 ACL。
-
-## 禁止采用的规避方式
-
-- 不要给 `Everyone`、`Users` 或 `CodexSandboxUsers` 授予 `FullControl`、`WRITE_DAC` 或 `WRITE_OWNER`。
-- 不要删除 `.codex` 父目录上的 deny ACL；这些规则可能正是 deny-read 隔离的一部分。
-- 不要关闭 sandbox 或使用危险绕过参数来运行不受信任的 Agent 任务。
-- 不要让 EvolCore daemon 长期管理员运行而 CLI 保持普通权限；这会造成命名管道 `EPERM`。
-- 不要仅凭 `ec status` 中 PID 存活判断系统健康；还要确认 IPC 和实际 Agent 任务都能运行。
-
-## EvolCore 侧最终验证
-
-```powershell
-ec status
-ec agent reload <agent-aid> --format json
-```
-
-然后从一个普通 AID 向目标 Agent 发送最小测试任务。观察 daemon 日志时，正确顺序应是：sandbox 初始化成功、Codex thread 启动、任务进入工具/模型执行。若此后出现 `POLICY_DENIED`，说明 sandbox 已恢复，下一步应修复 EvolCore 的角色或任务权限，而不是继续修改 Windows ACL。
+# Windows 上的 Codex Sandbox 权限排障
+
+本文适用于 EvolCore 在 Windows 上调用 Codex 时，任务在启动阶段因 sandbox 权限失败的情况。目标运行方式是：Codex Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行；只有 Codex sandbox 的安装或修复过程临时通过 UAC 提权。
+
+不要为了绕过 sandbox 错误而长期以管理员身份运行全部组件。这样不仅扩大权限，还可能使高完整性 daemon 创建的命名管道拒绝普通权限 `ec` CLI 连接。
+
+## 典型错误
+
+### `.sandbox-bin` 无法锁定
+
+```text
+helper_sandbox_lock_failed: lock sandbox bin dir C:\Users\<user>\.codex\.sandbox-bin failed:
+SetNamedSecurityInfoW sandbox dir failed: 5
+```
+
+错误码 5 是 Windows `ACCESS_DENIED`。常见原因是 `.sandbox-bin` 归 `BUILTIN\Administrators` 所有，而当前普通用户只有 `Modify`，没有修改 DACL 所需的 `WRITE_DAC`。Codex 的日常 sandbox refresh 不会请求 UAC，因此无法自行修复这个状态。
+
+### `unelevated` 无法执行 deny-read
+
+```text
+windows unelevated restricted-token sandbox cannot enforce deny-read restrictions directly;
+refusing to run unsandboxed
+```
+
+这不是同一个错误。EvolCore 会为托管 Agent 注入 deny-read 限制；Windows 的 `unelevated` backend 无法实施这些限制并会 fail closed。因此不要把下面的配置当作修复：
+
+```toml
+[windows]
+sandbox = "unelevated"
+```
+
+需要 deny-read 时应继续使用：
+
+```toml
+[windows]
+sandbox = "elevated"
+```
+
+这里的 `elevated` 指 sandbox provisioning 能通过 UAC 建立受限账户和 ACL，不表示 Desktop 或 EvolCore 必须一直以管理员运行。
+
+## 先确认错误属于哪一层
+
+在普通 PowerShell 中执行：
+
+```powershell
+codex --version
+codex doctor --json
+whoami /groups
+
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+Get-Item -LiteralPath $sandboxBin -Force |
+  Select-Object FullName, Attributes, LinkType
+Get-Acl -LiteralPath $sandboxBin |
+  Select-Object Owner, AreAccessRulesProtected, Sddl
+```
+
+同时检查：
+
+```powershell
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_error.json')
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_marker.json')
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\sandbox.*.log') -Tail 80
+```
+
+注意以下边界：
+
+| 现象 | 所属层 | 处理方向 |
+|------|--------|----------|
+| `helper_sandbox_lock_failed` / `SetNamedSecurityInfoW ... 5` | Codex sandbox ACL | 重新 provisioning 或修复 `.sandbox-bin` owner |
+| `unelevated ... cannot enforce deny-read` | Codex sandbox 模式 | 使用 `windows.sandbox = "elevated"` |
+| `connect EPERM \\.\pipe\daemon-*` | EvolCore IPC | 让 daemon 与 CLI 使用相同用户和完整性级别 |
+| sandbox 已启动，随后出现 `POLICY_DENIED` | EvolCore 角色/权限策略 | 检查任务发起者角色和 permission mode |
+
+共享同一个项目目录或同一个 `CODEX_HOME` 本身不是错误。关键是宿主进程的完整性级别一致，以及 sandbox 基础 ACL 已正确 provisioning。
+
+## 推荐修复：重新执行 elevated provisioning
+
+1. 结束正在启动的 Codex Agent 任务，保留 Codex Desktop 和 EvolCore 的普通权限运行方式。
+2. 将 Codex Desktop 与独立安装的 Codex CLI 更新到兼容版本，避免两个版本交替刷新同一 `CODEX_HOME`。
+3. 在 Codex Desktop 的 Windows Sandbox 设置中执行 setup/repair，选择 elevated backend，并接受一次 UAC 提示。对应的 app-server 操作为 `windowsSandbox/setupStart`，模式为 `elevated`；普通用户不应自行拼接内部 RPC。
+4. provisioning 完成后关闭管理员窗口。后续 Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行。
+5. 在普通 PowerShell 中执行验证命令。
+
+```powershell
+codex doctor --json
+codex sandbox -- cmd /c whoami
+```
+
+验收结果应满足：
+
+- `codex doctor` 中 sandbox backend 为 `elevated`，provisioning 为 `complete`，没有 `helper_sandbox_lock_failed`。
+- `codex sandbox -- cmd /c whoami` 成功，身份是专用 sandbox 用户（例如 `CodexSandboxOffline` 或 `CodexSandboxOnline`），而不是当前桌面用户。
+- 普通权限 EvolCore 任务可以进入模型执行阶段。
+
+如果 setup/repair 仍反复失败，优先使用 Codex 的修复或重新安装流程。不要先清空整个 `.codex`，其中包含会话、认证和其他用户数据。
+
+## 已验证的定向 workaround
+
+仅当官方 repair 无法完成、错误明确为 `.sandbox-bin` owner/DACL 不一致时使用。此方法只修复目录 owner，不递归改文件权限，也不删除或放宽现有 DACL。
+
+先在普通 PowerShell 中确认目标是实体目录而非重解析点：
+
+```powershell
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+$item = Get-Item -LiteralPath $sandboxBin -Force
+if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
+  throw "$sandboxBin is a reparse point; stop and inspect it manually"
+}
+Get-Acl -LiteralPath $sandboxBin | Format-List Owner, Sddl
+```
+
+然后只为下面一次操作打开管理员 PowerShell：
+
+```powershell
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+$acl = Get-Acl -LiteralPath $sandboxBin
+$acl.SetOwner([Security.Principal.NTAccount]::new($currentUser))
+Set-Acl -LiteralPath $sandboxBin -AclObject $acl
+```
+
+关闭管理员 PowerShell，在普通 PowerShell 中重新运行：
+
+```powershell
+codex sandbox -- cmd /c whoami
+codex doctor --json
+```
+
+本 workaround 已验证可以让普通权限 refresh 越过 `SetNamedSecurityInfoW ... 5`，但它不是替代官方 provisioning 的长期安装流程。Codex 更新或 repair 可能重新设置 owner；若问题复发，应保留 `doctor` 输出和 sandbox 日志并反馈给 Codex，而不是持续扩大 ACL。
+
+## 禁止采用的规避方式
+
+- 不要给 `Everyone`、`Users` 或 `CodexSandboxUsers` 授予 `FullControl`、`WRITE_DAC` 或 `WRITE_OWNER`。
+- 不要删除 `.codex` 父目录上的 deny ACL；这些规则可能正是 deny-read 隔离的一部分。
+- 不要关闭 sandbox 或使用危险绕过参数来运行不受信任的 Agent 任务。
+- 不要让 EvolCore daemon 长期管理员运行而 CLI 保持普通权限；这会造成命名管道 `EPERM`。
+- 不要仅凭 `ec status` 中 PID 存活判断系统健康；还要确认 IPC 和实际 Agent 任务都能运行。
+
+## EvolCore 侧最终验证
+
+```powershell
+ec status
+ec agent reload <agent-aid> --format json
+```
+
+然后从一个普通 AID 向目标 Agent 发送最小测试任务。观察 daemon 日志时，正确顺序应是：sandbox 初始化成功、Codex thread 启动、任务进入工具/模型执行。若此后出现 `POLICY_DENIED`，说明 sandbox 已恢复，下一步应修复 EvolCore 的角色或任务权限，而不是继续修改 Windows ACL。