DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(agent-notes): consolidate superseded decisions

Browse Source
This commit is contained in:
Turtle
2026-07-25 16:43:07 +08:00
parent 4f5cda16c5
commit 3feb05fef8
97 changed files with 279 additions and 1432 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write
2026-07-19-windows-atomic-write-dacl-preservation.md: 013119508da9be426c417797cf7a0ec14e276814
2026-07-19-windows-atomic-write-dacl-preservation.zh.md: 8ae82884c3b80409d07d3bbcfc8c273e8b227dc8
2026-07-19-windows-atomic-write-dacl-preservation.md: be9f82174300a7d605c6a6e63878728f08cb37be
2026-07-19-windows-atomic-write-dacl-preservation.zh.md: fc6ec5232c992f3a230ee0de89439c869b8b46f9

12
.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.md
View File

@@ -6,13 +6,13 @@ English | [中文](2026-07-19-windows-atomic-write-dacl-preservation.zh.md)
## Problem
On Windows, creating the staging directory and temp file under the target's parent and relying only on inherited DACLs is sufficient for a new file, but not for replacing an existing file whose explicit or protected DACL is narrower than its parent: content is written under the broader parent DACL, and rename carries that staging descriptor onto the replacement.
Atomic writes protect POSIX staging directories with `0o700` and temp files with `0o600`, but Windows mode bits expose only a synthetic read-only view of the actual DACL. Creating staging under the target's parent and relying on inheritance is sufficient for a new file, but not for replacing an existing file whose explicit or protected DACL is narrower than its parent: content is written under the broader parent DACL, and rename carries that staging descriptor onto the replacement.
## Decision
`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target access policy and other replacement metadata. Its ACL merge may reserialize auto-inheritance state or duplicate equivalent ACEs, so self-relative descriptor buffers are not a stable equality contract. New files have no prior descriptor to preserve and continue to inherit the destination directory's DACL.
`dsh-fs-local` reads an existing target's DACL with `GetFileSecurityW`, applies it to the empty temp file with inheritance protected before writing content, and publishes the closed temp with `ReplaceFileW`. The protected staging descriptor prevents the temp directory's inherited entries from broadening access; `ReplaceFileW` preserves the original target access policy and other replacement metadata. Its ACL merge may reserialize auto-inheritance state or duplicate equivalent ACEs, so self-relative descriptor buffers are not a stable equality contract. New Windows files have no prior descriptor to preserve and continue to inherit the destination directory's DACL; their staging directory therefore lives beside the target. POSIX keeps the owner-only staging modes and preserves an existing target mode.
Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement's ordered, de-duplicated ACE policy. Host-independent binding tests cover Win32 error translation and every native call boundary.
Native Windows coverage protects a target DACL, inspects the written staging file, and compares the final replacement's ordered, de-duplicated ACE policy. Host-independent binding tests cover Win32 error translation and every native call boundary. Mode-bit assertions remain POSIX-only; new-file DACL inheritance is an operating-system contract rather than a machine-specific account allowlist.
## Alternatives considered
@@ -22,6 +22,10 @@ Native Windows coverage protects a target DACL, inspects the written staging fil
**Install an owner-only DACL for every write.** Rejected because it would discard deliberate project sharing. Copying the target DACL preserves the deployment's existing access policy instead of inventing one.
**Assert inherited accounts with `Get-Acl` or `icacls`.** Rejected because such a test verifies machine policy rather than package behavior, and localized well-known account names make the output unstable across hosts.
**Skip the existing `chmod` calls on Windows.** Rejected because Node maps these writable modes to benign no-ops; platform guards add branches without changing DACL behavior.
## Consequences
Replacing a Windows file now requires permission to read the target DACL and set the temp DACL; failure is loud before content is written. The package carries Koffi for the narrow Win32 calls, loaded only on Windows replacement paths. New-file behavior remains directory-inherited, and POSIX mode behavior is unchanged.
Replacing a Windows file now requires permission to read the target DACL and set the temp DACL; failure is loud before content is written. The package carries Koffi for the narrow Win32 calls, loaded only on Windows replacement paths. A new Windows file inherits broad directory access when the directory is broad by design, while POSIX temp content stays owner-only; a read-only Windows target still fails publication before synthetic mode replay could matter.

12
.agents/notes/implemented/bug-fix/2026-07-19-windows-atomic-write-dacl-preservation.zh.md
View File

@@ -6,13 +6,13 @@ Status: implemented
## 问题
在 Windows 上，在目标文件的父目录下创建暂存目录和临时文件，并且只依赖继承的 DACL，足以满足新建文件的需要，但无法安全替换显式或受保护 DACL 比父目录更严格的现有文件：内容会在权限更宽松的父目录 DACL 下写入，而重命名又会把这个暂存安全描述符带到替换后的文件上。
原子写入在 POSIX 上以 `0o700` 保护暂存目录、以 `0o600` 保护临时文件，但 Windows mode 位只呈现实际 DACL 的合成只读视图。在目标文件的父目录下创建暂存目录和临时文件，并且只依赖继承的 DACL，足以满足新建文件的需要，但无法安全替换显式或受保护 DACL 比父目录更严格的现有文件：内容会在权限更宽松的父目录 DACL 下写入，而重命名又会把这个暂存安全描述符带到替换后的文件上。
## 决策
`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定契约。新建文件没有既有描述符需要保留，因此仍继承目标目录的 DACL。
`dsh-fs-local` 通过 `GetFileSecurityW` 读取现有目标文件的 DACL，在写入内容前将其以禁止继承的形式应用到空临时文件，并通过 `ReplaceFileW` 发布已关闭的临时文件。受保护的暂存安全描述符可防止暂存目录中的继承条目扩大访问权限；`ReplaceFileW` 会保留原目标文件的访问策略及其他替换元数据。其 ACL 合并过程可能重新序列化自动继承状态或复制等价 ACE，因此不能把自相对安全描述符缓冲区的逐字节相等作为稳定契约。新的 Windows 文件没有既有描述符需要保留，因此仍继承目标目录的 DACL；其暂存目录也因此位于目标文件旁。POSIX 继续使用仅所有者可访问的暂存 mode，并保留现有目标文件的 mode。
Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。
Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成的暂存文件，并对比最终替换文件中保持顺序且去重后的 ACE 策略。与宿主平台无关的绑定测试覆盖 Win32 错误转换以及每个原生调用边界。mode 位断言仍仅适用于 POSIX；新文件的 DACL 继承由操作系统契约规定，不应通过特定机器的账户允许列表来断言。
## 备选方案
@@ -22,6 +22,10 @@ Windows 原生覆盖率测试会保护目标文件的 DACL、检查写入完成
**每次写入都设置仅所有者可访问的 DACL。** 不予采用，因为这会破坏项目有意设置的共享权限。复制目标文件的 DACL 可以保留部署中已有的访问策略，无需另行创设策略。
**使用 `Get-Acl` 或 `icacls` 断言继承账户。** 不予采用，因为这类测试验证的是机器策略，而不是包行为；系统内置账户名会本地化，使输出在不同宿主上不稳定。
**在 Windows 上跳过现有 `chmod` 调用。** 不予采用，因为 Node 会把这些可写 mode 映射为无害的空操作；平台条件判断只会增加分支，不会改变 DACL 行为。
## 影响
替换 Windows 文件现在要求调用方有权读取目标 DACL 并设置临时文件 DACL；如果权限不足，系统会在写入内容前明确失败。该包（package）引入 Koffi 以执行少量 Win32 调用，并且只在 Windows 替换路径上加载。新建文件仍按目录继承，POSIX mode 行为保持不变。
替换 Windows 文件现在要求调用方有权读取目标 DACL 并设置临时文件 DACL；如果权限不足，系统会在写入内容前明确失败。该包（package）引入 Koffi 以执行少量 Win32 调用，并且只在 Windows 替换路径上加载。新的 Windows 文件会在目录按设计开放较宽访问权限时继承该权限，而 POSIX 临时内容仍仅允许所有者访问；只读 Windows 目标文件仍会在发布时失败，早于重放合成 mode 可能产生影响的时点。