# Bug + fix: Windows 大工作区首次 workspace-write 授权同步遍历 ACL 整树，事件循环冻结数分钟

[Ranecc]

Bug + fix: Windows 大工作区首次 workspace-write 授权同步遍历 ACL 整树，事件循环冻结数分钟

Summary

Windows 下，大工作区的首次 workspace-write 命令会冻结整个服务器数分钟。冻结期间所有 RPC（session.create、终端 spawn、工具调用）全部超时——Web UI 表现为"AI 每次跑终端命令都卡死"。

我定位到了根因，并准备好了带确定性回归测试的完整非阻塞修复。由于官方不接收外部 PR（per CONTRIBUTING.md），故发布在此提请团队关注。完整实现与测试在独立仓库：https://github.com/Ranecc/topolyte-windows-acl （Cordis 插件 @topolyte/windows-acl，基于官方 @deepseek-ai/dsh-sandbox-windows-acl 包，bundle-patch 挂载，无需 fork）。

Root cause

首次 workspace-write provision 时，LocalSandboxProvider.materializeAclGrant 在 confine()（用户可见请求路径）上同步调用 grant.add(workspaceRoot, true)（standing grant）。

grantWrite → SetNamedSecurityInfoW 带 OI|CI 继承标志，触发 Windows 的 eager 可继承 ACE 传播：内核同步递归整棵子树。大树上耗时数分钟，且运行在 harness 事件循环上，整个服务器（所有 session、HTTP、RPC）冻结。

官方代码已承认此成本：

• packages/sandbox/sandbox-windows-acl/src/acl.ts："it would otherwise re-propagate the identical ACE across the whole tree (eager inheritance; minutes on large workspaces)"
• 现有缓解（hasExactGrant 精确匹配跳过）只让第二次 provision 变 O(1)，第一次仍阻塞——第一次必然触发全树传播，无法绕过。

Fix

把昂贵的 eager ACE 传播移出事件循环。核心三件事：

1. 首次 grantWrite(workspaceRoot, true) 放进独立子进程（spawn 而非 spawnSync），成功后再记录 standing grant：

// grant-cli.ts —— argv: [node, grant-cli.js, <workspaceRoot>]
import { AclWriteGrant, workspaceWriteSid } from '@deepseek-ai/dsh-sandbox-windows-acl'

const GRANT_SIGNATURE = 'windows-acl-grant'
const GRANT_FAILURE_EXIT = 127

async function main(): Promise<number> {
  const workspace = process.argv[2]
  if (workspace === undefined || workspace.length === 0) {
    process.stderr.write(`${GRANT_SIGNATURE}: missing workspace path\n`)
    return GRANT_FAILURE_EXIT
  }
  // Standing grant: 跨 session 复用缓存；短命 helper 无需 dispose()——进程退出即回收 SID。
  AclWriteGrant.create(workspaceWriteSid(workspace)).add(workspace, true)
  return 0
}

main().then(
  (exitCode) => { process.exitCode = exitCode },
  (error: unknown) => {
    process.stderr.write(`${GRANT_SIGNATURE}: ${error instanceof Error ? error.message : String(error)}\n`)
    process.exitCode = GRANT_FAILURE_EXIT
  },
)

2. confine() 保持同步但 fail-closed：kick off，绝不 await 整树遍历：

private kickOffWorkspaceGrant(workspaceRoot: string): void {
  if (this.workspaceGrants.has(workspaceRoot)) return          // 已 standing：O(1)
  if (this.workspaceGrantInflight.has(workspaceRoot)) return  // 在途：合并
  const pending = this.materializeWorkspaceGrantAsync(workspaceRoot).finally(() => {
    this.workspaceGrantInflight.delete(workspaceRoot)
  })
  this.workspaceGrantInflight.set(workspaceRoot, pending)
  pending.catch((error) => {
    this.ctx.logger.warn(`windows-acl: out-of-band grant failed for ${workspaceRoot}: ${String(error)}`)
  })
}

private async materializeWorkspaceGrantAsync(workspaceRoot: string): Promise<void> {
  // spawn, not spawnSync —— 遍历在子进程里，绝不阻塞事件循环
  await spawnGrant(this.grantCliInvocation(workspaceRoot), workspaceRoot)
  this.workspaceGrants.set(workspaceRoot, AclWriteGrant.create(workspaceWriteSid(workspaceRoot)))
}

standing ACE 落地前，受限子进程的工作区写被拒（access is denied）——fail-closed，绝不冻结；一旦落地，exact-ACE skip 让之后每次 provision 变 O(1)。子进程用 stdio: 'ignore' + 监听 exit，无僵尸进程；多进程前端由官方 acl.ts 的 withPathLock（LockFileEx per-path 锁）兜底。

3. 暴露 prewarm 配置，部署可在启动时为已知工作区预热，缩短首条命令前的 fail-closed 窗口：

- insert:
    - id: sandbox
      name: '@topolyte/windows-acl'
      config:
        prewarm:
          - <workspaceRoot>

Verification

端到端（icacls 断言）：standing 工作区 ACE 带外物化（SetNamedSecurityInfoW 由子进程落地）；temp ACE 在 teardown 撤销；工作区 ACE 跨 provider 保留。e2e 脚本：scripts/e2e-acl.ts。

Benchmark（劫持官方 grant.ts/workspace-sid.ts 源码实测，非推测）：

场景	文件数	首次（阻塞）	后续（O(1) skip）
真实工作区（首次授权）	4,332	2,773.7ms（冻结）	1.2ms
大 monorepo（DSH 本体）	182,053	首次随整树放大（fork 实测 >120s）	1.2ms

两个关键数据点：

• 同一目录从首次 2,773.7ms（整树 eager 传播）到二次 1.2ms（exact-ACE skip）——约 2,300 倍差距，正是用户可感知的冻结。
• skip 与树大小无关（4,332 vs 182,053 文件都是 1.2ms），因为 hasExactGrant 只读目录自身 DACL 头；而首次成本随整树放大，数万文件的 monorepo 上同步遍历超过两分钟。

单测：@topolyte/windows-acl 仓库内 vitest 套件通过（含异步授权合并、temp 隔离、错误路径）；插件继承官方 SandboxProvider 基类，不破坏官方契约。

[denial123789]

I verified the reported current-path behavior against rc.7 (99f6f02). LocalSandboxProvider.materializeAclGrant() synchronously creates the deterministic workspace SID and calls grant.add(workspaceRoot, true) before returning runner argv. The Windows ACL package documents that the inheritable ACE apply propagates eagerly through descendants, while its exact-root-ACE check makes later same-path provisions fast. This explains the combined signature: command not started yet, unrelated Web/RPC work stalled, then a dramatic same-path second-call improvement. An out-of-process design is promising, but it changes the confinement state machine: no child may start before the grant is confirmed, concurrent calls need canonical-path deduplication, and the Agent/UI need explicit preparing/ready/failure states plus bounded retry behavior. I wrote a source map, operator evidence bundle, external-plugin audit boundary, and ten repair invariants here: https://sandbaseai.github.io/deepseek-harness-handbook/windows-acl-first-run.html

[Ranecc]

Thanks — this is exactly the verification the issue needed, and it matches
what I measured: rc.7 creates the deterministic workspace SID and calls
grant.add(workspaceRoot, true) inside confine(); the eager
inheritable-ACE propagation explains the unrelated Web/RPC work stalling; the
exact-root-ACE check explains the dramatic same-path second-call improvement.

Mechanically, why this freezes: SetNamedSecurityInfoW with OI|CI inheritance
makes the kernel eagerly re-apply the ACE to every live descendant — one call,
linear in file count, synchronous, on the event loop. The exact-root-ACE skip
is not an optimization but a guard against re-running that O(n) walk; when it
misses, it re-walks (roughly 1 in 10–20 on my synthetic trees) — another
on-loop freeze on the official path; with the plugin it lands in the
grant-cli child, so server responsiveness is unchanged. For my own
quantification I also swept synthetic trees (1k–30k files): the official first
provision froze the server ~7.6s at 30k files, versus the plugin's largest
event-loop gap being the child-spawn cold start. The full numbers and the
benchmark script live in the repo if useful.

You're right that an out-of-process design is a state-machine change, not just
a scheduling tweak. I aligned the plugin against your ten repair invariants —
each maps to an implementation point plus a passing test:

1. Event loop responds — the eager inheritable-ACE walk runs in a grant-cli
   child (spawn, not spawnSync); confine() is fully synchronous and never
   awaits it. Test asserts unrelated confinement returns immediately (wall-clock
   bound) while one workspace's grant is pending.

2. No child may start before the grant is confirmed — materializeAclGrant
   checks the lifecycle state after kicking off the out-of-band grant and
   REFUSES to start the command with SandboxUnavailableError while the grant
   is preparing or failed; only ready proceeds. No silent half-authorized
   run, ever. (My first cut was "start the child, deny writes until the grant
   lands" — your invariant #2 is what made me make the refusal strict.)

3. One in-flight grant per path — keys are canonicalized
   (realpathSync.native, per the official workspaceWriteSid contract), so
   trailing separators / . segments / case all converge onto one key, one SID,
   and one failure counter. Concurrent first calls coalesce onto one helper
   spawn (3 concurrent ensures -> 1 spawn, asserted).

4. Failures stay closed — a failed grant leaves no record, so the workspace
   stays refuse-until-confirmed; the failure is logged, never thrown to the
   fire-and-forget caller.

5. Ready state is explicit — workspaceGrantState(root) returns
   'preparing' | 'ready' | 'failed', so agents/executors can branch on the
   state instead of guessing.

6. Moved path gets a new SID — the SID derives from the canonical path:
   re-spelling converges to one key/SID, renaming derives a new one (one extra
   propagation, never a collision with the old grant).

7. Shutdown observes the helper — the provider's async disposer awaits every
   in-flight helper before revoking temp ACEs (test: dispose stays pending
   until the helper settles).

8. Agent gets bounded retry — maxGrantRetries (default 3) pins a failing
   workspace to failed; automatic retries stop and commands stay refused
   until retryWorkspaceGrant() resets the counter. 0 disables retries, not
   the first attempt (tested). Your operator-evidence bundle is what pushed me
   to make this an explicit public API rather than an internal counter.

9. Temp grants stay revocable — per-session/workspace private temp with a
   distinct SID, revoked and the directory removed on dispose.

10. Windows test measures latency — the suite asserts wall-clock bounds on the
    refusal/return paths while a grant is pending.

I read your source map, operator evidence bundle, and the external-plugin audit
boundary in the handbook — the audit boundary in particular is why the helper
takes the workspace path as an argv (never derives it from the provider's own
state) and why grant-cli is a standalone exported entry, not a function inside
the provider.

The repo is https://github.com/Ranecc/topolyte-windows-acl (no-fork install on
the official harness via bundle patch; build + unit tests green on Windows).
End-to-end on a real box: the provider loads on a real Context, the
grant-cli child materializes the standing workspace ACE (verified via
icacls), and a WRITE_RESTRICTED child probes the actual semantics — writes
inside the workspace and the private temp succeed, writes outside and under
read-only are denied with EPERM, teardown revokes the temp ACE and keeps the
workspace standing grant. 12/12 checks pass.

If any invariant reads differently from what I implemented, I'd genuinely like
the detail — the plugin lives or dies on that state machine.

[argszero]

按 rc.8（141eb6fef8）源码核对，根因与修复方向都成立，补充三点：

1. 根因精确确认 + 家族连接。 packages/sandbox/sandbox-windows-acl/src/acl.ts:215-244：grantWrite 的 SetNamedSecurityInfoW apply 在 hasExactGrant 精确匹配时跳过——注释明说"否则会整树重传相同 ACE（eager inheritance; minutes on large workspaces）"；grant.ts:23 同款注释。你的数据（4,332 文件 2,773ms → 1.2ms；182,053 文件首次 >120s）把这个注释变成了实测。这是 windows-acl 家族的第三个"分散原生资源语义"实例：前有 #3193（default-DACL 只修新对象不修 CreateProcess 路径检查）、#3466（spawn 失败路径句柄所有权无系统化规则），这个是同步调用在事件循环上执行分钟级内核传播——同根：原生副作用（DACL 传播 / 句柄 / 令牌）游离在异步生命周期管理之外。

2. denial123789 的 4 个状态机问题中，"无子进程可在 grant 确认前启动"这一点值得再深化一个语义。 fail-closed 窗口期（grant 落地前工作区写被拒）不只是"命令失败"——workspace-write 的授权语义被拆成两段：能力判定（SID 存在 + 已 standing）与实际可达（ACE 已传播）。你的设计中 workspaceGrants.has() 是"已确认"标记，但 confine() 在 kick-off 后立即放行——若子进程在 grant 完成前尝试写工作区，得到的是 access is denied，这在模型视角看起来像"权限被拒"而非"正在初始化"。建议：fail-closed 的拒绝信息应明确区分"grant in-flight"与"grant 不存在"（如 distinct error code 或 reason），让上层 Agent 能识别这是暂时状态而非永久权限问题——这是你 prewarm 配置之外的第二个缩短"语义困惑窗口"的手段。

3. withPathLock 兜底的一个边界。 你的设计依赖官方 acl.ts 的 withPathLock（LockFileEx per-path）防多进程并发——这正确覆盖了同路径并发。但注意 grantWrite 的锁范围是单路径（acl.ts:232 withPathLock(api, path, ...)）：父子目录并发授权（如 workspaceRoot 与 workspaceRoot/sub 两个不同 provider 实例）会各自拿锁、各自 merge——eager 传播本身是幂等的（同 ACE 重复落地无害），但两把锁之间没有全局顺序，极端情况下 D 继承传播与 E 直接授权交错。实际影响很小（ACE 幂等 + Windows 合并语义），但值得在实现里注明"per-path 锁是并发下限，不是父子一致性保证"。

修复形态整体认可：子进程承载分钟级内核调用 + 事件循环保持响应 + 精确 ACE skip 保留 O(1) 二次路径，是这个包"原生资源语义外移"的正确方向。等你把修复整理成可审查的补丁（或 PR 通道重开）时，我可以帮忙过一遍状态机边界用例。