@deepseek-ai/dsh-sandbox-windows-acl 0.1.7-rc.2 → 0.2.0-rc.2

package/README.i18n.yaml

@@ -25,10 +25,10 @@
   zh: 30bc370a5281bf0d
 /deepseek-ai-dsh-sandbox-windows-acl/use-this-package/what-confinement-gives-you:
   en: 289e65bddf20dd79
-  zh: 44b9fcedf944546a
+  zh: 7ff72ed64c4b4d1c
 /deepseek-ai-dsh-sandbox-windows-acl/use-this-package/failures-and-recovery:
-  en: f93372e784cda63e
-  zh: f8371114f3481550
+  en: 7fc0707debb1e67c
+  zh: e3b5529bf82f868e
 /deepseek-ai-dsh-sandbox-windows-acl/understand-the-implementation:
   en: c2cde86c85c2c619
   zh: a29a114e591f9d3f
@@ -51,14 +51,14 @@
   en: 7850da9522bf984b
   zh: a9f2273a85bafcf9
 /deepseek-ai-dsh-sandbox-windows-acl/model-experience:
-  en: c94416e26fec28cd
-  zh: a16f435e8afbdf30
+  en: bbb19594a2c2e4d4
+  zh: 075a65d9b9182aad
 /deepseek-ai-dsh-sandbox-windows-acl/model-experience/kv-cache-effect:
-  en: 796af37d6f6add68
-  zh: 1e0dc5a58e5456be
+  en: 817eb1b7de13872e
+  zh: 06fe175e41e7459b
 /deepseek-ai-dsh-sandbox-windows-acl/known-limitations-and-deferred-work:
-  en: 2b6b967c62766d47
-  zh: 0faf9ec390504967
+  en: 046831a864786b2a
+  zh: 4a261fbab3396ea4
 /deepseek-ai-dsh-sandbox-windows-acl/known-limitations-and-deferred-work/dev-note:
   en: cc273320f6a1beaf
   zh: 5c57a312ddc50651

package/README.md

@@ -75,6 +75,14 @@ Temp isolation is per live session/workspace pair: sessions sharing a workspace
 
 `init()` throws on any Win32 failure — the child is never spawned unrestricted. A runner that fails before executing the command prints `windows-acl-run: <detail>` to stderr and exits 127, which the seam's runner-failure rules classify as a broken sandbox rather than a denial. Cleanup is best-effort by design: `dispose()` attempts every temp revocation and aggregates failures into an `AggregateError`.
 
+A denial this backend cannot explain is diagnosed by the `diagnose-windows-sandbox-acl` skill bundled in `assets/`. `registerAclDiagnosisSkill` contributes it when `dsh-sandbox-local` uses its built-in Windows runner and a skill registry is available. Registration extracts resources for external PowerShell, including in ASAR and SEA deployments; fiber disposal unregisters the provider and removes its copy. Missing assets fail registration.
+
+One run diagnoses and repairs. The script has no modes: it reads the requested path and every ancestor, adds the signed-in user's full-control allow ACE to chain directories that lack effective `WRITE_DAC` or `WRITE_OWNER`, and removes explicit package allow ACEs at their sources, ancestor first, verifying each change by re-reading it. Repairs preserve denies, owner, inheritance and SACL, and back up each changed DACL. An object is modified only when it is `-AllowRoot` or strictly inside it, so a workspace root can repair itself; reparse paths and managed application trees are refused, and a repair needs effective `WRITE_DAC`. Failed repairs restore attempted changes in reverse order and exit nonzero. Follow the [bundled skill](assets/diagnose-windows-sandbox-acl/SKILL.md) for the single command, original-operation verification and recovery.
+
+Every run prints `REPORT` JSON records of observations, actions, reasons and verification, then a final `RECAP` line carrying the verdicts, changes, verifications, refusals and scans, and a summary with the counts, recovery commands and `nextAction`; unknown observations remain unknown. The same run writes every record to `-Out\acl-report-*.jsonl`, because tool output keeps only its tail. `-Out` also receives two recovery files per change: the DACL the object owned before that change and the independent script that restores it. Action completion records API execution; verification records the observed result. The [recovery decisions](../../../.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.md#acl-diagnosis-and-recovery) explain resource ownership and rollback limits.
+
+Inspection visits the requested object and each ancestor through the filesystem root. Each ACL observation's `path` identifies the inspected object; the classification's `details.packageObjects` lists objects carrying package allow ACEs without establishing the cause of the original failure. Each package removal is verified per object by comparing the recorded own ACEs with the re-read DACL, so a deny that shares the removed allow's SID remains visible in the verification details.
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -156,14 +164,16 @@ Start with the subsystem reference for the shared vocabulary, then the provider
 <a id="model-experience"></a>
 ## Model Experience
 
-Indirectly, through [`dsh-bash-sandbox`](../../shell/bash-sandbox/README.md), [`dsh-pwsh-sandbox`](../../shell/pwsh-sandbox/README.md), and their tools, which render this backend's partial-enforcement and denial facts (the confined stderr the tool layer classifies through `denialSignatures`) while the [`dsh-sandbox`](../sandbox/README.md) seam owns the `SANDBOX_UNAVAILABLE` text and `sandbox-local` owns runner selection.
+Indirectly, through [`dsh-bash-sandbox`](../../shell/bash-sandbox/README.md), [`dsh-pwsh-sandbox`](../../shell/pwsh-sandbox/README.md), and their tools, which render this backend's partial-enforcement and denial facts (the confined stderr the tool layer classifies through `denialSignatures`) while the [`dsh-sandbox`](../sandbox/README.md) seam owns the `SANDBOX_UNAVAILABLE` text and `sandbox-local` owns runner selection. On Windows this package also contributes one catalog entry, the bundled `diagnose-windows-sandbox-acl` skill, which is where the model learns to diagnose a denial the tool layer can only report.
 
 #### KV Cache effect
 
-None directly; the denial surface belongs to the tool layer.
+One extra catalog entry on Windows: the skill's description enters context with the catalog, and the body enters only when invoked. Resource extraction happens at registration and does not add script contents to model context. The denial surface itself stays in the tool layer.
 
 ## Known Limitations and Deferred Work
 
+- **Diagnosis preserves integrity labels** — it cannot fix Low-labeled executables affecting programs launched outside DSH. It also cannot repair a caller's missing `WRITE_DAC`; extracted and recovery scripts are user-writable and are not supported elevated entrypoints. Resource directories can remain after an unclean shutdown.
+
 <a id="known-limitations-and-deferred-work"></a>
 
 
@@ -178,6 +188,7 @@ These limits define when the backend is a poor fit or needs special operational
 - **Read-side confinement and network policy are out of scope** — `WRITE_RESTRICTED` intersects write accesses only; pair this backend with a read-side policy for stronger confinement.
 - **Reads stop at objects another AppContainer-based tool has ACL'd with a package SID** — a file whose DACL carries an ACE for a package SID (`S-1-15-2-…`) is inaccessible to a Low-integrity token on this host, even when the same DACL grants the user full control and Everyone read (observed: adding that single ACE to a fresh file reproduces the denial, granting Everyone read does not lift it, and the same bytes copied elsewhere stay readable). The kernel rule behind it is unconfirmed and not this package's to change; tools that sandbox themselves with AppContainers stamp such ACEs, so a tree they touched becomes unreadable to this backend's child. Removing the foreign ACE (or re-installing the affected tree) restores access.
 - **Wide-directory and FAT-volume warnings are deferred; the FAT-class residue is unverified** — the UI-side warnings are not implemented, a FAT volume as a grant root fails loudly, and a FAT-class target outside the granted roots stores no security descriptor; its effective integrity label is assigned by the system rather than recorded on the object, so the label layer's behavior there is untested. FAT stays legacy residue.
+- **The bundled diagnosis skill needs an unconfined caller** — both the classification and the repairs read or write security descriptors a confined child cannot reach, so the session must escalate that one call; with no approval channel the escalation fails closed and the path stays undiagnosed.
 - **PowerShell language mode differs by confined mode** — under `read-only`, PowerShell cannot create its AppLocker probe files in temp and conservatively starts in ConstrainedLanguage (`Add-Type`, non-core .NET static calls, COM, and reflection fail); the shipped `workspace-write` path lets the probe complete, so pwsh stays in FullLanguage unless host-wide WDAC/AppLocker policy says otherwise, while a direct `AclSandbox` with `tempDir: null` has no such guarantee. This split is PowerShell startup behavior, not part of the ACL write boundary.
 
 <a id="dev-note"></a>

package/README.zh.md

@@ -71,10 +71,20 @@ rmSync(tempDir, { recursive: true, force: true })
 
 临时隔离按每个活跃的会话/工作区对进行：共享工作区的会话共享其写权限，但无法写入彼此的临时目录。新的提供方总会选择新的临时路径和 SID，因此崩溃残留既无法阻止恢复的会话，也无法向其授权。
 
+<a id="failures-and-recovery"></a>
+
 ### 失败与恢复
 
 `init()` 在任何 Win32 失败时抛出——子进程绝不会不受限制地 spawn。执行命令前失败的 runner 会向 stderr 打印 `windows-acl-run: <detail>` 并以 127 退出，seam 的 runner 失败规则将其归类为损坏的沙箱，而非拒绝。清理按设计尽力而为：`dispose()` 会尝试全部临时撤销并把失败聚合为 `AggregateError`。
 
+此后端无法解释的拒绝交给 `assets/` 中随包发布的 `diagnose-windows-sandbox-acl` 技能诊断。当 `dsh-sandbox-local` 使用内置 Windows runner 且技能注册表可用时，`registerAclDiagnosisSkill` 会注册它。注册时提取供外部 PowerShell 使用的资源，ASAR 和 SEA 部署也适用；fiber 释放时注销提供者并删除副本。缺少资源会导致注册失败。
+
+一次运行同时完成诊断与修复。脚本没有模式开关：它读取请求路径及每一级祖先，为链路上缺少有效 `WRITE_DAC` 或 `WRITE_OWNER` 的目录补上当前用户的完全控制允许 ACE，并从祖先开始在其来源移除显式包允许 ACE，每处改动都通过重新读取来验证。修复保留拒绝条目、所有者、继承和 SACL，并备份每个被修改的 DACL。仅当对象就是 `-AllowRoot` 或严格位于其内部时才会被修改，因此工作区根目录可以自我修复；重解析路径和受管理的应用目录会被拒绝，修复需要有效的 `WRITE_DAC`。修复失败时按相反顺序恢复尝试修改的内容，并以非零状态退出。单条命令、原始操作验证及恢复流程见[内置技能](assets/diagnose-windows-sandbox-acl/SKILL.md)。
+
+每次执行都会打印包含观察、操作、原因和验证结果的 `REPORT` JSON 记录，最后给出一行 `RECAP`（判定、改动、验证、拒绝与扫描结果）以及含计数、恢复命令和 `nextAction` 的摘要；未知观察保持未知。同一次执行还会把全部记录写入 `-Out\acl-report-*.jsonl`，因为工具输出只保留末尾部分。`-Out` 同时为每次改动写入两个恢复文件：该对象在本次改动前拥有的 DACL，以及用于恢复它的独立脚本。操作完成记录 API 执行情况，验证记录实际观察到的结果。[恢复决策](../../../.agents/notes/implemented/feature/2026-08-08-windows-acl-restricted-token-sandbox.zh.md#acl-diagnosis-and-recovery) 说明资源归属和回滚限制。
+
+检查会从请求对象逐级访问祖先，直到文件系统根目录。每条 ACL 观察的 `path` 标识实际检查的对象；分类结果的 `details.packageObjects` 列出包含包允许 ACE 的对象，但不能据此确认原始失败的原因。每次包 ACE 移除都按对象验证：把记录下来的自身 ACE 与重新读取的 DACL 比对，因此与被移除允许项共用 SID 的拒绝条目仍会出现在验证详情中。
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -156,14 +166,16 @@ seam 先把确定性工作区 SID 的 ACE 常驻物化（每个工作区每服
 <a id="model-experience"></a>
 ## 模型体验
 
-间接地通过 [`dsh-bash-sandbox`](../../shell/bash-sandbox/README.zh.md)、[`dsh-pwsh-sandbox`](../../shell/pwsh-sandbox/README.zh.md) 及其工具呈现；它们渲染此后端的部分强制执行与拒绝事实（工具层通过 `denialSignatures` 分类的受限 stderr），而 [`dsh-sandbox`](../sandbox/README.zh.md) seam 拥有 `SANDBOX_UNAVAILABLE` 文本、`sandbox-local` 拥有 runner 选择。
+间接地通过 [`dsh-bash-sandbox`](../../shell/bash-sandbox/README.zh.md)、[`dsh-pwsh-sandbox`](../../shell/pwsh-sandbox/README.zh.md) 及其工具呈现；它们渲染此后端的部分强制执行与拒绝事实（工具层通过 `denialSignatures` 分类的受限 stderr），而 [`dsh-sandbox`](../sandbox/README.zh.md) seam 拥有 `SANDBOX_UNAVAILABLE` 文本、`sandbox-local` 拥有 runner 选择。在 Windows 上本包还贡献一个目录条目——随包发布的 `diagnose-windows-sandbox-acl` 技能，模型正是从它学会诊断工具层只能上报的拒绝。
 
 #### KV Cache 影响
 
-无直接影响；拒绝面属于工具层。
+Windows 上多一个目录条目：技能描述随目录进入上下文，正文只在调用时进入。资源在注册时提取，不会把脚本内容加入模型上下文。拒绝面本身仍属于工具层。
 
 ## 已知限制与延期工作
 
+- **诊断保留完整性标签**——它无法修复 Low 标签的可执行文件影响用户在 DSH 外启动程序的问题，也无法修复调用者缺少 `WRITE_DAC` 的情况；提取的脚本和恢复脚本均可由用户写入，不支持作为提权入口。非正常退出后可能残留资源目录。
+
 <a id="known-limitations-and-deferred-work"></a>
 
 
@@ -178,6 +190,7 @@ seam 先把确定性工作区 SID 的 ACE 常驻物化（每个工作区每服
 - **读侧隔离与网络策略不在范围内**——`WRITE_RESTRICTED` 只交叉检查写访问；将此后端与读侧策略配对以获得更强隔离。
 - **读取会被其他基于 AppContainer 的工具以包 SID 授权过的对象挡住。** 在本机上，当文件的 DACL 携带针对包 SID（`S-1-15-2-…`）的 ACE 时，Low 完整性的令牌无法访问它——即使同一份 DACL 同时向用户授予完全控制、向 Everyone 授予读取（已观测：只给新文件加这一条 ACE 即可复现拒绝，补授 Everyone 读取无法解除，而同样内容复制到别处仍可读）。其背后的内核规则尚未确证，也不由本包掌控；以 AppContainer 自我隔离的工具正是会写入这类 ACE，因此被它们标记过的目录树对本后端的子进程将不可读。移除外来 ACE（或重新安装受影响的目录树）即可恢复访问。
 - **宽目录与 FAT 卷警告已推迟；FAT 类残留未经验证。** UI 侧警告尚未实现，FAT 卷作为授权根会大声失败，而授权根之外的 FAT 类目标不存储安全描述符；其有效完整性标签由系统分配而非记录在对象上，因此标签层在该处的行为未经测试。FAT 仍被视为遗留残留。
+- **随包发布的诊断技能需要不受限的调用者。** 无论分类还是修复，都要读写受限子进程够不到的安全描述符，因此会话必须为那一次调用升权；没有审批通道时升权 fail-closed，该路径保持未诊断。
 - **PowerShell 语言模式因受限模式而异。** 在 `read-only` 下，PowerShell 无法在临时目录中创建 AppLocker 探针文件，因此会保守地以 ConstrainedLanguage 启动（`Add-Type`、非核心 .NET 静态调用、COM 与反射失败）；交付的 `workspace-write` 路径可让探针完成，因此除非主机范围的 WDAC/AppLocker 策略另有规定，否则 pwsh 保持 FullLanguage，而直接使用 `AclSandbox` 并配置 `tempDir: null` 时则没有这一保证。这一区别属于 PowerShell 启动行为，不是 ACL 写入边界的一部分。
 
 <a id="dev-note"></a>

package/assets/diagnose-windows-sandbox-acl/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: diagnose-windows-sandbox-acl
+description: 'Use on Windows for unexpected DSH sandbox access denials: workspace writes or listing fail, or an ordinarily readable path cannot be read. One bundled command inspects the path and every ancestor and repairs the ACL problems it proves in that same run. Expected confinement denials need no ACL repair.'
+---
+
+# Diagnose Windows sandbox ACL failures
+
+**Write every approval request in plain words, in the user's language.** The prompt is all the user reads before widening access, so it must stand alone: which folder the script touches, that it adds the signed-in user's full-control entry where a right is missing and removes foreign package entries, that file contents and owners are unchanged, and that the printed recovery command undoes each change. Keep error codes, `WRITE_DAC`/`WRITE_OWNER`, `S-1-15-2-*` SIDs, `icacls`, ACL, ACE, verdict names and switches out of the request: write Windows file permissions, not ACL or ACE. Ask once, for one command.
+
+## One command diagnoses and repairs
+
+The script has no modes. `-Path`, `-AllowRoot` and `-Out` read the path and every ancestor and repair what the observations prove, in the same run:
+
+- directories on that chain that lack effective `WRITE_DAC` or `WRITE_OWNER` receive a full-control allow ACE for the signed-in user, because DSH cannot provision its workspace grant without them;
+- explicit AppContainer package allow ACEs (`S-1-15-2-*`, except the well-known groups ending in 1 or 2) are removed at their sources, ancestor first, which also removes those packages' access;
+- a directory the sandbox cannot provision — the state its provisioning error reports on the workspace root — or the authorized root itself also has its subtree searched for those ACEs in the same run, so a deeper entry needs no second request. That bounded walk reports `truncated` and unreadable directories; if truncated, pass the still-failing deeper path once more.
+
+Every change is backed up, then verified by re-reading it. `-AllowRoot` bounds all of it: an object is changed only when it is that directory or strictly inside it, so a workspace root can repair itself. Never split this into a diagnostic call and a repair call, never ask twice for one repair, and never pass a mode switch that does not exist.
+
+```powershell
+& '<skill-directory>\scripts\diagnose-windows-sandbox-acl.ps1' -Path '<failing-path>' -AllowRoot '<authorized-directory>' -Out '<recovery-directory>'
+exit $LASTEXITCODE
+```
+
+Substitute full, quoted paths. Keep `-Out` persistent and user-owned, preferably beside the failing workspace; never use the skill resource directory, which is deleted when the skill unloads. Pass one path per invocation.
+
+## Run it
+
+Repeat the failing operation once confined. The script writes permissions, which the confined token cannot do — run it there and it would report the sandbox's own restriction as a missing right — so request approval for that one command and run it unconfined. A confined run of the script is never useful. Unconfined does not elevate the Windows token.
+
+Diagnose unexpected denials of workspace writes, listing, or plainly readable paths; explain expected ones instead: writes outside the workspace, any write in `read-only`, piped grandchild `spawn EPERM`, ConstrainedLanguage errors. If approval is refused or unavailable, report the path as undiagnosed and stop.
+
+## Read the output
+
+Every record reaches stdout, the `acl-report-*.jsonl` file under `-Out`, and the final `RECAP` line, which carries the verdicts, changes, verifications, refusals and scans. Tool output keeps only its tail, so read the recap first, and read specific records from the report when it is not enough. Trust `verification` records, never `completed` actions. Decide from `details.nextAction`:
+
+| `nextAction` | Meaning |
+|---|---|
+| `verify_original_confined_operation` | Repairs verified; repeat the original operation confined. |
+| `stop` | Nothing repaired, or a refusal ended the run. Report and stop. |
+| `restore_pending_then_stop` | Rollback unverified. Run the printed recovery commands in order, then stop. |
+
+A deny ACE's presence alone does not establish causation, and the script never removes one; DSH's `S-1-4-*` grants and the Everyone `DeleteSubdirectoriesAndFiles` deny are expected, not conflicts. A deny that blocks the repair ends the run without a repair (`REPAIR_REFUSED`, or `GRANT_FAILED`) after restoring what it attempted. Each change leaves two files in `-Out` (`acl-backup-<id>.json` and its `.ps1`), and the run prints the matching `ROLLBACK` command.
+
+## After a repair, and when it stops
+
+Repeat the original failed operation confined. A verified repair is not undone because the original operation fails for a further reason: continue from the new observations, and if a deeper path is still denied, run the same one command there — again one call, one approval.
+
+**Stop after any failed or refused repair, or failed verification.** The script already restored that invocation's changes; do not repeat it or start another repair, and never remove a deny ACE by hand.
+
+**A stopped run still owes the user a decision.** Name the blocking object and the right or ACE it lacks, what changed and what was rolled back, the recovery commands in order, and the report path. Only the user can lift confinement, so ask them to switch this session to **full access** (Chinese UI: 完全权限) temporarily, and say what that opens: keep working under it, or ask you to keep investigating this file-permission problem, since the report already records the mechanism and the evidence. Then ask them to send this session as feedback, quoting the report records that matter, so the unhandled scenario reaches us — only what reaches this conversation travels with it. For example:
+
+> 这个工作区被 Windows 文件权限挡住了：`<对象>` 上 `<缺哪个权限 / 哪条权限项>`。你可以把本会话切到「完全权限」(full access) 临时继续工作；切完之后既能直接干活，也可以让我继续排查这个文件权限问题（报告里已经有机制和证据）。也麻烦把这个会话作为反馈发出去，好让我们补上这个场景。
+>
+> This workspace is blocked by Windows file permissions: `<object>` `<missing right / offending entry>`. Switch this session to full access (完全权限) to keep working meanwhile; then either continue your work or have me keep investigating this file-permission problem from the report. Please also send this session as feedback so we can cover the case.
+
+## Never
+
+- edit ACLs by hand, change an owner, erase a deny, or replace child permissions recursively;
+- run the script elevated, through UAC or `runas`;
+- widen `-AllowRoot` to reach an ancestor, or repeat a denied or failed call.
+
+Report in the user's language: analyzed paths, changes, verification, recovery commands, next step. Label an authorized unconfined run as such, not as a sandbox repair.

package/assets/diagnose-windows-sandbox-acl/scripts/diagnose-windows-sandbox-acl.ps1

@@ -0,0 +1,798 @@
+<#
+.SYNOPSIS
+    Diagnose the DSH sandbox ACL failures on Windows and repair them in one run.
+
+.DESCRIPTION
+    A denial inside the DSH sandbox is worth diagnosing only when it contradicts
+    what the active mode promises: writes inside the workspace, or reads that the
+    signed-in user should plainly have. One invocation reads each requested path
+    and every ancestor, then repairs what it can in the same run:
+
+      * every directory on that chain inside -AllowRoot that lacks effective
+        WRITE_DAC or WRITE_OWNER gets a FullControl allow ACE for the current
+        user, so the sandbox can provision the grant it needs; and
+      * every explicit AppContainer package allow ACE (S-1-15-2-*, excluding the
+        well-known groups ending in 1 or 2) is removed at its source, ancestor
+        first, which also removes that package's access to the tree.
+
+    A directory the caller cannot provision is the state the sandbox reports on the
+    workspace root, while the conflicting entry often sits deeper; the authorized root
+    is examined for the same reason. For either case the same run also collects explicit
+    package allow ACEs under the requested directory, so they do not need a second call.
+    The walk is bounded, enters no reparse point or managed application tree, and reports
+    truncation and unreadable directories instead of claiming a complete walk.
+
+    Every observation, change, verification and recovery command is printed as it
+    happens, so one run shows the caller the complete set of actions.
+
+    -AllowRoot bounds every change: an object is modified only when it is that
+    directory or strictly inside it, so a caller can repair its own workspace
+    root. Reparse paths and managed application trees are refused. Each modified
+    object is backed up first, with an independent recovery script, and every DACL
+    write is verified by re-reading it. A failed repair restores all attempted
+    DACL changes from this invocation in reverse order and stops.
+
+    The script never creates, deletes, or writes the contents of any file. Its
+    only writes are the recovery artifacts under -Out and the DACLs it repairs.
+
+.PARAMETER Path
+    One or more failing paths. Each is diagnosed and repaired together with its ancestors.
+
+.PARAMETER AllowRoot
+    Required. Every modified object must be this directory or strictly inside it.
+
+.PARAMETER Out
+    Required for a repair. Receives one recovery record and one recovery script
+    per change, so an object repaired twice keeps both recovery points.
+
+.PARAMETER Restore
+    Restore the DACL recovery record for exactly one -Path instead of repairing.
+    Requires -AllowRoot and WRITE_DAC, preserves owner and SACL.
+
+.EXAMPLE
+    pwsh -File diagnose-windows-sandbox-acl.ps1 -Path '<failing path>' -AllowRoot '<authorized directory>' -Out '<recovery directory>'
+
+.EXAMPLE
+    pwsh -File diagnose-windows-sandbox-acl.ps1 -Path '<failing path>' -AllowRoot '<authorized directory>' -Restore '<recovery record>'
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][string[]]$Path,
+  [string]$AllowRoot,
+  [string]$Out,
+  [string]$Restore
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# These two well-known groups name all packages, not one conflicting package.
+$PACKAGE_SID = '^S-1-15-2-(?![12]$)'
+$LOW_LABEL_SID = 'S-1-16-4096'
+# Upper bound on the directories one subtree scan may visit, so a huge workspace
+# cannot turn one approved repair into an unbounded walk. Truncation is reported.
+$SCAN_LIMIT = 2000
+
+function Write-Line { param([string]$Text) Write-Output $Text }
+
+# Reports bypass the success pipeline so diagnostics cannot become a function's
+# return value. Each JSON record occupies one stdout line, including paths/errors.
+function Write-Report {
+  param([string]$Kind, [string]$Operation, [string]$Target, [string]$Status, [string]$Reason, $Details = @{})
+  $record = [ordered]@{ kind = $Kind; operation = $Operation; path = $Target; status = $Status; reason = $Reason; details = $Details }
+  if ($Kind -eq 'observation' -and $Status -in @('unknown', 'unreadable', 'partial')) { $script:observationFailures++ }
+  $script:reports.Add($record)
+  $json = $record | ConvertTo-Json -Depth 12 -Compress
+  # The complete record set also lands in the report file: tool output is truncated to its
+  # tail, so a long run's early records survive only there.
+  if ($null -ne $script:reportWriter) {
+    try { $script:reportWriter.WriteLine($json); $script:reportWriter.Flush() }
+    catch [System.IO.IOException] {
+      # stdout keeps only its tail, so this file is the complete record: a write failure
+      # has to reach the caller, on stderr, instead of leaving a silently incomplete file.
+      [Console]::Error.WriteLine('REPORT_IO_FAILED {0}: {1}' -f $script:reportPath, $_.Exception.Message)
+      try { $script:reportWriter.Dispose() } catch { }
+      $script:reportWriter = $null
+    }
+  }
+  [Console]::Out.WriteLine('REPORT ' + $json)
+}
+function Invoke-ReportedOperation {
+  param([string]$Operation, [string]$Target, [string]$Reason, [string]$Effect, [scriptblock]$Action)
+  $entry = [ordered]@{ id = $script:operations.Count + 1; operation = $Operation; path = $Target; effect = $Effect; status = 'started' }
+  $script:operations.Add($entry)
+  if ($Effect -eq 'acl' -and $Operation -ne 'restore_dacl' -and $script:recoveries.Count -gt 0) {
+    $script:recoveries[-1].attempted = $true
+  }
+  Write-Report action $Operation $Target started $Reason @{ id = $entry.id; effect = $Effect }
+  try {
+    $result = & $Action
+    $entry.status = 'completed'
+    Write-Report action $Operation $Target completed $Reason @{ id = $entry.id; effect = $Effect }
+    return $result
+  } catch {
+    $entry.status = 'failed'
+    Write-Report action $Operation $Target failed $Reason @{
+      id = $entry.id; effect = $Effect; error = (Get-HResultChain $_.Exception)
+      state = $(if ($Effect -eq 'none') { 'No mutation requested by this operation.' } else { 'The operation may have partially changed state; completion is unconfirmed.' })
+    }
+    throw
+  }
+}
+
+function Write-Decision {
+  param([string]$Operation, [string]$Target, [string]$Status, [string]$Reason)
+  Write-Report decision $Operation $Target $Status $Reason
+}
+
+# Unwrap nested exceptions: PowerShell wraps Win32 failures, and only the inner
+# exception carries the real HRESULT the caller needs to classify the failure.
+function Get-HResultChain {
+  param([System.Exception]$Exception)
+  $chain = @()
+  $e = $Exception
+  while ($null -ne $e) {
+    $chain += ('{0}=0x{1:X8}/win32={2}: {3}' -f $e.GetType().Name, $e.HResult, ($e.HResult -band 0xFFFF), $e.Message)
+    $e = $e.InnerException
+  }
+  return ($chain -join ' <- ')
+}
+
+function Get-CurrentIdentity {
+  return [System.Security.Principal.WindowsIdentity]::GetCurrent()
+}
+
+# Integrity level affects the symptom: the same foreign
+# ACE fails a grant when the caller is below Medium and merely blocks the child
+# when the caller is not.
+# The integrity level lives in the token's group list, which .NET filters out of
+# WindowsIdentity.Groups, so read it through GetTokenInformation. Add-Type compiles
+# in-process on PowerShell 7. Never spawn whoami.exe for this: inside a below-Medium
+# token that process fails to initialize (STATUS_DLL_INIT_FAILED, 0xc0000142) and
+# raises an application-error dialog on the user's desktop.
+function Initialize-NativeApi {
+    if (-not ('Dsh.TokenInfo' -as [type])) {
+      Add-Type -Namespace Dsh -Name TokenInfo -MemberDefinition @'
+[StructLayout(LayoutKind.Sequential)]
+public struct SID_AND_ATTRIBUTES { public IntPtr Sid; public uint Attributes; }
+[StructLayout(LayoutKind.Sequential)]
+public struct TOKEN_MANDATORY_LABEL { public SID_AND_ATTRIBUTES Label; }
+[DllImport("advapi32.dll", SetLastError = true)]
+public static extern bool GetTokenInformation(IntPtr token, int infoClass, IntPtr info, uint length, out uint returned);
+[DllImport("advapi32.dll", SetLastError = true)]
+public static extern IntPtr GetSidSubAuthority(IntPtr sid, uint index);
+[DllImport("advapi32.dll", SetLastError = true)]
+public static extern IntPtr GetSidSubAuthorityCount(IntPtr sid);
+[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+private static extern Microsoft.Win32.SafeHandles.SafeFileHandle CreateFileW(
+  string path, uint access, uint share, IntPtr security, uint disposition, uint flags, IntPtr template);
+// OPEN_EXISTING never creates or changes contents. Windows evaluates the caller's
+// effective access, including group attributes, denies, ownership and inheritance.
+public static bool HasAccess(string path, uint access) {
+  using (var handle = CreateFileW(path, access, 7, IntPtr.Zero, 3, 0x02200000, IntPtr.Zero)) {
+    if (!handle.IsInvalid) { return true; }
+    int error = Marshal.GetLastWin32Error();
+    if (error == 5) { return false; }
+    throw new System.ComponentModel.Win32Exception(error, "CreateFileW access check: " + path);
+  }
+}
+[DllImport("advapi32.dll", CharSet = CharSet.Unicode)]
+private static extern uint SetNamedSecurityInfoW(string path, int type, uint information,
+  IntPtr owner, IntPtr group, byte[] dacl, IntPtr sacl);
+public static void SetDacl(string path, string sddl) {
+  var descriptor = new System.Security.AccessControl.RawSecurityDescriptor(sddl);
+  byte[] dacl = null;
+  if (descriptor.DiscretionaryAcl != null) {
+    dacl = new byte[descriptor.DiscretionaryAcl.BinaryLength];
+    descriptor.DiscretionaryAcl.GetBinaryForm(dacl, 0);
+  }
+  bool isProtected = (descriptor.ControlFlags & System.Security.AccessControl.ControlFlags.DiscretionaryAclProtected) != 0;
+  // Only the DACL and its inheritance protection are written: never owner, group or SACL.
+  uint result = SetNamedSecurityInfoW(path, 1, 4u | (isProtected ? 0x80000000u : 0x20000000u),
+    IntPtr.Zero, IntPtr.Zero, dacl, IntPtr.Zero);
+  if (result != 0) { throw new System.ComponentModel.Win32Exception((int)result, "Write DACL: " + path); }
+}
+public static int Level(IntPtr token) {
+  uint length;
+  GetTokenInformation(token, 25, IntPtr.Zero, 0, out length);
+  if (length == 0) { throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "Read integrity information length"); }
+  IntPtr buffer = Marshal.AllocHGlobal((int)length);
+  try {
+    if (!GetTokenInformation(token, 25, buffer, length, out length)) { throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error(), "Read integrity information"); }
+    IntPtr sid = Marshal.PtrToStructure<TOKEN_MANDATORY_LABEL>(buffer).Label.Sid;
+    byte count = Marshal.ReadByte(GetSidSubAuthorityCount(sid));
+    return Marshal.ReadInt32(GetSidSubAuthority(sid, (uint)(count - 1)));
+  } finally { Marshal.FreeHGlobal(buffer); }
+}
+'@
+    }
+}
+
+function Get-IntegritySid {
+  try {
+    $level = [Dsh.TokenInfo]::Level([System.Security.Principal.WindowsIdentity]::GetCurrent().Token)
+    switch ($level) {
+      0 { return 'S-1-16-0 (Untrusted)' }
+      4096 { return 'S-1-16-4096 (Low)' }
+      8192 { return 'S-1-16-8192 (Medium)' }
+      12288 { return 'S-1-16-12288 (High)' }
+      16384 { return 'S-1-16-16384 (System)' }
+      default { return "S-1-16-$level (unrecognized level)" }
+    }
+  } catch {
+    Write-Report observation integrity '' unknown 'The token integrity level could not be read; do not infer that the caller is elevated or confined.' @{ error = (Get-HResultChain $_.Exception) }
+    return 'unknown'
+  }
+}
+
+function Get-NormalizedPath {
+  param([string]$Value)
+  $full = [System.IO.Path]::GetFullPath($Value)
+  $root = [System.IO.Path]::GetPathRoot($full)
+  if ($full.Length -le $root.Length) { return $root }
+  return $full.TrimEnd('\', '/')
+}
+
+function Test-DangerousRoot {
+  param([string]$FullPath)
+  $trimmed = (Get-NormalizedPath $FullPath).TrimEnd('\')
+  if ($trimmed -match '^[A-Za-z]:$') { return 'drive root' }
+  if ($trimmed -ieq ([System.IO.Path]::GetFullPath($env:USERPROFILE).TrimEnd('\'))) { return 'user profile root' }
+  if ($trimmed -ieq ([System.IO.Path]::GetFullPath($env:WINDIR).TrimEnd('\'))) { return 'Windows directory' }
+  foreach ($entry in @(
+    @{ directory = $env:LOCALAPPDATA; child = 'Packages' },
+    @{ directory = $env:ProgramFiles; child = 'WindowsApps' },
+    @{ directory = $env:ProgramW6432; child = 'WindowsApps' }
+  )) {
+    if (-not $entry.directory) { continue }
+    $protected = Get-NormalizedPath (Join-Path $entry.directory $entry.child)
+    if ($trimmed -ieq $protected -or (Test-UnderRoot $trimmed $protected)) { return 'managed application directory' }
+  }
+  return $null
+}
+
+function Test-UnderRoot {
+  param([string]$FullPath, [string]$Root, [switch]$AllowEqual)
+  $r = Get-NormalizedPath $Root
+  $c = Get-NormalizedPath $FullPath
+  if ($AllowEqual -and $c -ieq $r) { return $true }
+  return $c -ine $r -and $c.StartsWith($r.TrimEnd('\') + '\', [System.StringComparison]::OrdinalIgnoreCase)
+}
+
+function Get-RepairRefusal {
+  param([string]$FullPath, [string]$Root, [switch]$AllowEqual)
+  if (-not (Test-UnderRoot -FullPath $FullPath -Root $Root -AllowEqual:$AllowEqual)) { return "$FullPath is outside -AllowRoot" }
+  $danger = Test-DangerousRoot -FullPath $FullPath
+  if ($danger) { return "$FullPath is a $danger" }
+  # Checking every component also covers a junction used as AllowRoot itself.
+  foreach ($component in (Get-Ancestors -FullPath $FullPath)) {
+    $item = Get-Item -LiteralPath $component -Force
+    if (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) {
+      return "$FullPath traverses a reparse point: $component"
+    }
+  }
+  return $null
+}
+
+# A caller that cannot provision a directory also cannot confine a child anywhere
+# under it, so one approved run examines that subtree for explicit package allow
+# ACEs instead of leaving them for a second call. Directories only: DSH grants and
+# traverses directories, and no reparse point or managed application tree is entered.
+function Get-SubtreePackageSources {
+  param([string]$Root, [int]$Limit)
+  $sources = @()
+  $visited = 0
+  $enqueued = 0
+  $failed = 0
+  $truncated = $false
+  $queue = [System.Collections.Generic.Queue[string]]::new()
+  # Unreadable directories are skipped, never guessed at: the caller reports the count.
+  try {
+    foreach ($child in [System.IO.Directory]::EnumerateDirectories($Root)) {
+      if ($enqueued -ge $Limit) { $truncated = $true; break }
+      $queue.Enqueue($child); $enqueued++
+    }
+  } catch [System.UnauthorizedAccessException] { $failed++ }
+  catch [System.IO.IOException] { $failed++ }
+  while ($queue.Count -gt 0) {
+    if ($visited -ge $Limit) { $truncated = $true; break }
+    $current = $queue.Dequeue()
+    $visited++
+    if (Test-DangerousRoot -FullPath $current) { continue }
+    $item = Get-Item -LiteralPath $current -Force -ErrorAction SilentlyContinue
+    if ($null -eq $item) { $failed++; continue }
+    if (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { continue }
+    try {
+      $acl = Get-Acl -LiteralPath $current
+      foreach ($rule in $acl.GetAccessRules($true, $false, [System.Security.Principal.SecurityIdentifier])) {
+        if ($rule.AccessControlType -eq 'Allow' -and $rule.IdentityReference.Value -match $PACKAGE_SID) { $sources += $current; break }
+      }
+    } catch [System.UnauthorizedAccessException] { $failed++ }
+    catch [System.IO.IOException] { $failed++ }
+    try {
+      foreach ($child in [System.IO.Directory]::EnumerateDirectories($current)) {
+        if ($enqueued -ge $Limit) { $truncated = $true; break }
+        $queue.Enqueue($child); $enqueued++
+      }
+    } catch [System.UnauthorizedAccessException] { $failed++ }
+    catch [System.IO.IOException] { $failed++ }
+  }
+  return [ordered]@{ sources = @($sources); visited = $visited; truncated = $truncated; failed = $failed }
+}
+
+function Get-OwnDaclSddl {
+  param([string]$Sddl)
+  # Inherited ACEs follow their parent: repeating them in a saved DACL forces them
+  # back onto the object on restore and stops matching once the parent re-derives
+  # them. Keep the observed control flags so the result still carries the
+  # object's inheritance protection, and keep every ACE the object owns.
+  $flags = [regex]::Match($Sddl, '^D:([A-Z]*)').Groups[1].Value
+  $aces = @([regex]::Matches($Sddl, '\([^()]*\)') | ForEach-Object { $_.Value } | Where-Object { ($_ -split ';')[1] -notmatch 'ID' })
+  return 'D:{0}{1}' -f $flags, ($aces -join '')
+}
+
+function Get-AceSet {
+  param([string]$Sddl)
+  return @([regex]::Matches($Sddl, '\([^()]*\)') | ForEach-Object { $_.Value } | Sort-Object)
+}
+
+function Save-AclBackup {
+  param([string]$FullPath, [string]$Directory, [string]$Root)
+  $fullDirectory = [System.IO.Path]::GetFullPath($Directory)
+  if (-not (Test-Path -LiteralPath $fullDirectory)) {
+    Invoke-ReportedOperation create_backup_directory $fullDirectory 'The requested recovery directory does not exist; create it before writing backup files.' files {
+      New-Item -ItemType Directory -Path $fullDirectory | Out-Null
+    }
+  }
+  $record = Join-Path $fullDirectory ('acl-backup-{0}.json' -f ([guid]::NewGuid().ToString('N')))
+  # The skill's extracted directory expires with its registration. Recovery must
+  # remain runnable from the recovery directory after that registration is gone.
+  $restoreScript = $record + '.ps1'
+  $command = "pwsh -NoProfile -File '{0}' -Path '{1}' -AllowRoot '{2}' -Restore '{3}'" -f
+    $restoreScript.Replace("'", "''"), $FullPath.Replace("'", "''"), ([System.IO.Path]::GetFullPath($Root)).Replace("'", "''"), $record.Replace("'", "''")
+  Write-Report decision backup $FullPath selected 'The recovery record and an independent recovery script are written before the ACL change.' @{ files = @($record, $restoreScript) }
+  Invoke-ReportedOperation backup $FullPath 'Save the original DACL and an independent recovery command before changing permissions.' files {
+    $backupAcl = Get-Acl -LiteralPath $FullPath
+    $observed = $backupAcl.GetSecurityDescriptorSddlForm([System.Security.AccessControl.AccessControlSections]::Access)
+    @{
+      Path = $FullPath
+      Dacl = Get-OwnDaclSddl -Sddl $observed
+      Protected = $backupAcl.AreAccessRulesProtected
+      Observed = $observed
+    } | ConvertTo-Json | Set-Content -LiteralPath $record -Encoding utf8
+    Copy-Item -LiteralPath $PSCommandPath -Destination $restoreScript
+  }
+  $script:recoveries.Add(@{ path = $FullPath; record = $record; script = $restoreScript; command = $command; attempted = $false; restored = $false })
+  Write-Report observation recovery $FullPath available 'These files can restore the saved DACL; no rollback has been executed.' $script:recoveries[-1]
+  Write-Line ('BACKUP {0} -> {1}' -f $FullPath, $record)
+  Write-Line ('ROLLBACK {0}' -f $command)
+}
+function Restore-SavedDacl {
+  param([string]$FullPath, [string]$Record, [string]$Root)
+  $refusal = Get-RepairRefusal -FullPath $FullPath -Root $Root -AllowEqual
+  if ($refusal) { throw [System.ArgumentException]::new("RESTORE_REFUSED $refusal") }
+  $saved = Invoke-ReportedOperation read_recovery $Record 'Read the recovery record and verify it belongs to the requested path before restoring its DACL.' none {
+    Get-Content -LiteralPath $Record -Raw | ConvertFrom-Json
+  }
+  if ($saved.Path -isnot [string] -or $saved.Path -ine $FullPath -or $saved.Dacl -isnot [string]) {
+    throw [System.ArgumentException]::new('RESTORE_REFUSED backup does not describe the requested path')
+  }
+  if (-not [Dsh.TokenInfo]::HasAccess($FullPath, 0x40000)) { throw 'RESTORE_REFUSED the caller lacks WRITE_DAC' }
+  Invoke-ReportedOperation restore_dacl $FullPath 'Restore the requested backup DACL and inheritance protection, preserving owner and SACL.' acl {
+    [Dsh.TokenInfo]::SetDacl($FullPath, $saved.Dacl)
+  }
+  $restoredAcl = Invoke-ReportedOperation read_restored_dacl $FullPath 'Read the restored DACL to compare it with the saved record.' none {
+    Get-Acl -LiteralPath $FullPath
+  }
+  # Inherited entries follow the parent, so the same object can render a different
+  # full DACL before and after a correct restore. Compare the own ACEs and the
+  # protection state, which the restore owns.
+  $restoredProtected = $restoredAcl.AreAccessRulesProtected
+  $actual = Get-OwnDaclSddl -Sddl $restoredAcl.GetSecurityDescriptorSddlForm([System.Security.AccessControl.AccessControlSections]::Access)
+  $expectedAces = Get-AceSet -Sddl $saved.Dacl
+  $actualAces = Get-AceSet -Sddl $actual
+  $restored = (@($expectedAces) -join "`n") -eq (@($actualAces) -join "`n") -and $restoredProtected -eq [bool]$saved.Protected
+  Write-Report verification restore $FullPath $(if ($restored) { 'verified' } else { 'failed' }) 'Compare the restored own ACEs and protection state with the recovery record.' @{ expectedAces = @($expectedAces); actualAces = @($actualAces); protected = $restoredProtected; expectedProtected = [bool]$saved.Protected }
+  if (-not $restored) { throw 'RESTORE_FAILED the restored DACL differs from the backup' }
+  $script:restored++
+  Write-Line ('RESTORED {0}' -f $FullPath)
+}
+
+function Get-ObjectFacts {
+  param([string]$FullPath, [string]$MeSid, [switch]$CompactRecord)
+  $facts = [ordered]@{
+    Object = $FullPath
+    Readable = $false
+    Error = ''
+    PackageAces = @()
+    OtherAppContainerSids = @()
+    Owner = ''
+    OwnerIsMe = $false
+    MyRights = ''
+    HasWriteDac = $null
+    HasWriteOwner = $null
+    Aces = @()
+    Errors = @()
+    LowLabel = $null
+    AclLines = @()
+  }
+  try {
+    # Get-Acl reads the security descriptor directly. On .NET Core the
+    # FileSystemInfo.GetAccessControl() form is an extension method, which
+    # PowerShell cannot invoke with instance syntax.
+    $acl = Get-Acl -LiteralPath $FullPath
+    $facts.Readable = $true
+  } catch {
+    $facts.Error = Get-HResultChain -Exception $_.Exception
+    Write-Report observation inspect_acl $FullPath unreadable 'The ACL read failed; permissions and the cause of denial remain unknown.' @{ error = $facts.Error }
+    return $facts
+  }
+  foreach ($rule in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {
+    $sid = $rule.IdentityReference.Value
+    $facts.Aces += [ordered]@{
+      sid = $sid; type = [string]$rule.AccessControlType; rights = [string]$rule.FileSystemRights
+      inherited = $rule.IsInherited; inheritance = [string]$rule.InheritanceFlags; propagation = [string]$rule.PropagationFlags
+    }
+    if ($sid -match $PACKAGE_SID -and $rule.AccessControlType -eq 'Allow') {
+      $facts.PackageAces += ('SID={0} INHERITED={1} INHERITABLE={2} RIGHTS={3}' -f $sid, $rule.IsInherited, $rule.InheritanceFlags, $rule.FileSystemRights)
+    } elseif ($sid -match '^S-1-15-' -and $sid -notmatch $PACKAGE_SID) {
+      $facts.OtherAppContainerSids += $sid
+    }
+    if ($sid -eq $MeSid -and $rule.AccessControlType -eq 'Allow') {
+      $facts.MyRights = ($facts.MyRights + ';' + [string]$rule.FileSystemRights).Trim(';')
+    }
+  }
+  try {
+    $facts.Owner = $acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
+    $facts.OwnerIsMe = ($facts.Owner -eq $MeSid)
+  } catch {
+    $facts.Owner = 'unreadable'
+    $facts.Errors += @{ operation = 'read_owner'; error = (Get-HResultChain $_.Exception) }
+  }
+  foreach ($check in @(@{ field = 'HasWriteDac'; mask = 0x40000 }, @{ field = 'HasWriteOwner'; mask = 0x80000 })) {
+    try { $facts[$check.field] = [Dsh.TokenInfo]::HasAccess($FullPath, $check.mask) }
+    catch { $facts.Errors += @{ operation = $check.field; error = (Get-HResultChain $_.Exception) } }
+  }
+  # The mandatory label lives in the SACL. Reading the SACL needs a privilege while
+  # icacls prints the label without one, but icacls renders it by name, which is
+  # localized: try the integrity SID first and keep the English name as a fallback.
+  try {
+    $facts.AclLines = @(icacls $FullPath 2>&1 | ForEach-Object { [string]$_ })
+    if ($LASTEXITCODE -ne 0) { throw "icacls exit ${LASTEXITCODE}: $($facts.AclLines -join "`n")" }
+    $text = $facts.AclLines -join "`n"
+    # An unrecognized localized label is unknown, not evidence of a Low label.
+    if ($text -match $LOW_LABEL_SID -or $text -match 'Mandatory Label\\Low Mandatory Level') { $facts.LowLabel = $true }
+  } catch {
+    $facts.Errors += @{ operation = 'icacls'; error = (Get-HResultChain $_.Exception) }
+  }
+  Write-Report observation inspect_acl $FullPath $(if ($facts.Errors.Count) { 'partial' } else { 'read' }) 'Read the ACL and check effective WRITE_DAC and WRITE_OWNER; observed ACEs alone do not identify which rule caused a denial.' @{
+    owner = $facts.Owner; writeDac = $facts.HasWriteDac; writeOwner = $facts.HasWriteOwner
+    # A re-read after a change repeats an ACL this run already recorded: keep the
+    # full ACE list in memory, but do not print it twice.
+    aces = $(if ($CompactRecord) { @() } else { $facts.Aces }); acesOmitted = [bool]$CompactRecord
+    lowLabel = $facts.LowLabel; errors = $facts.Errors
+  }
+  return $facts
+}
+
+function Get-Ancestors {
+  param([string]$FullPath)
+  $list = @()
+  $current = Get-NormalizedPath $FullPath
+  while ($true) {
+    $list += $current
+    $parent = [System.IO.Path]::GetDirectoryName($current)
+    if ([string]::IsNullOrEmpty($parent) -or $parent -eq $current) { break }
+    $current = $parent
+  }
+  return $list
+}
+
+# --- main ---------------------------------------------------------------
+
+$operations = [System.Collections.Generic.List[object]]::new()
+$recoveries = [System.Collections.Generic.List[object]]::new()
+$reports = [System.Collections.Generic.List[object]]::new()
+$reportPath = $null
+$reportWriter = $null
+$requestedPaths = @()
+$rollbackStatus = 'not-needed'
+$fixed = 0
+$granted = 0
+$refused = 0
+$restored = 0
+$exitCode = 0
+$observationFailures = 0
+$scanTruncated = $false
+$currentPath = ''
+$mode = if ($Restore) { 'restore' } else { 'repair' }
+
+try {
+  $requestedPaths = @($Path | ForEach-Object { [System.IO.Path]::GetFullPath($_) })
+  Write-Report invocation $mode '' started 'Inspect the requested paths, then repair the ACL problems this run can prove, before anything else is attempted.' @{
+    paths = $Path; allowRoot = $AllowRoot; outputDirectory = $Out; recoveryRecord = $Restore
+  }
+  if (-not $AllowRoot) { throw [System.ArgumentException]::new('Every modification requires -AllowRoot') }
+  if (-not $Restore -and -not $Out) { throw [System.ArgumentException]::new('A repair requires -Out for its recovery artifacts') }
+  if ($Restore -and $Path.Count -ne 1) { throw [System.ArgumentException]::new('-Restore requires exactly one -Path') }
+  if ($Out) {
+    Invoke-ReportedOperation prepare_report $Out 'Create the recovery directory and a new JSONL report that keeps every record, because tool output is truncated to its tail.' files {
+      $directory = [System.IO.Path]::GetFullPath($Out)
+      [System.IO.Directory]::CreateDirectory($directory) | Out-Null
+      $script:reportPath = Join-Path $directory ('acl-report-{0}.jsonl' -f [guid]::NewGuid().ToString('N'))
+      $stream = [System.IO.File]::Open($script:reportPath, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write)
+      $script:reportWriter = [System.IO.StreamWriter]::new($stream, [System.Text.UTF8Encoding]::new($false))
+      foreach ($record in $script:reports) { $script:reportWriter.WriteLine(($record | ConvertTo-Json -Depth 12 -Compress)) }
+    }
+  }
+  $identity = Get-CurrentIdentity
+  $meSid = $identity.User.Value
+  Invoke-ReportedOperation initialize '' 'Load read-only access checks and DACL-only writes before inspecting permissions.' none { Initialize-NativeApi }
+  $integrity = Get-IntegritySid
+  Write-Line ('CALLER SID={0} INTEGRITY={1}' -f $meSid, $integrity)
+  Write-Report observation caller '' read 'The caller token determines effective access; unconfined execution does not imply elevation.' @{ sid = $meSid; integrity = $integrity }
+  :paths foreach ($requested in $Path) {
+    $currentPath = $requested
+    $full = Get-NormalizedPath $requested
+    $currentPath = $full
+    Write-Line ('PATH={0}' -f $full)
+    if (-not (Test-Path -LiteralPath $full)) {
+      Write-Line '  MISSING'
+      Write-Line 'VERDICT=NOT_THIS_CLASS'
+      Write-Decision $mode $full skipped 'The requested path does not exist; no ACL was read or changed for it.'
+      $refused++
+      break paths
+    }
+
+    $factsByPath = @{}
+    $inspectOrder = @()
+    $packageTargets = @()
+    $targetFacts = $null
+    foreach ($ancestor in (Get-Ancestors -FullPath $full)) {
+      if (-not (Test-Path -LiteralPath $ancestor)) { continue }
+      $facts = Get-ObjectFacts -FullPath $ancestor -MeSid $meSid
+      $factsByPath[$facts.Object] = $facts
+      $inspectOrder += $facts.Object
+      if ($ancestor -eq $full) { $targetFacts = $facts }
+      Write-Line ('  OBJECT={0} READABLE={1}{2}' -f $facts.Object, $facts.Readable, $(if ($facts.Readable) { '' } else { ' ERROR=' + $facts.Error }))
+      if ($facts.Readable) {
+        Write-Line ('    OWNER={0} IS_CURRENT_USER={1} MY_RIGHTS=[{2}] WRITE_DAC={3} WRITE_OWNER={4} LOW_LABEL={5}' -f $facts.Owner, $facts.OwnerIsMe, $facts.MyRights, $facts.HasWriteDac, $facts.HasWriteOwner, $facts.LowLabel)
+        foreach ($ace in $facts.PackageAces) { Write-Line ('    PACKAGE_ACE {0}' -f $ace) }
+        foreach ($sid in ($facts.OtherAppContainerSids | Sort-Object -Unique)) { Write-Line ('    OTHER_S1_15 SID={0} (reported only)' -f $sid) }
+      }
+      if ($facts.PackageAces.Count -gt 0) { $packageTargets += $facts.Object }
+    }
+
+    # The precondition is judged on the requested path itself. Ancestors above the
+    # tree DSH grants are not part of that grant, so their ownership and rights would
+    # otherwise mark every healthy path as a precondition failure.
+    if ($null -eq $targetFacts) { throw "The requested path disappeared before its ACL could be inspected: $full" }
+    $unreadable = -not $targetFacts.Readable
+    $needsPrecondition = (-not $unreadable) -and
+      ((-not $targetFacts.HasWriteDac) -or (-not $targetFacts.HasWriteOwner))
+
+    # A directory the caller cannot provision is the workspace root half the time: the sandbox
+    # reports its own failure there while the conflicting entry sits deeper. Examine that
+    # subtree before the verdict so the classification and its packageObjects describe what
+    # this run will actually repair.
+    $ownsRoot = $full -ieq (Get-NormalizedPath $AllowRoot)
+    if (-not $Restore -and $targetFacts.Errors.Count -eq 0 -and [System.IO.Directory]::Exists($full) -and ($needsPrecondition -or $ownsRoot)) {
+      $scan = Get-SubtreePackageSources -Root $full -Limit $SCAN_LIMIT
+      foreach ($object in $scan.sources) {
+        if ($packageTargets -notcontains $object) { $packageTargets += $object }
+        if (-not $factsByPath.ContainsKey($object)) {
+          $scanned = Get-ObjectFacts -FullPath $object -MeSid $meSid
+          $factsByPath[$scanned.Object] = $scanned
+        }
+      }
+      Write-Report observation subtree_scan $full $(if ($scan.failed -gt 0) { 'partial' } else { 'read' }) 'The caller cannot provision this directory, or it is the authorized root, so explicit package allow ACEs under it were collected in the same run; no reparse point or managed application tree is entered.' @{
+        visited = $scan.visited; packageSources = @($scan.sources); truncated = [bool]$scan.truncated; unreadable = [int]$scan.failed
+      }
+      Write-Line ('SCAN {0} VISITED={1} PACKAGE_SOURCES={2}{3}{4}' -f $full, $scan.visited, @($scan.sources).Count, $(if ($scan.truncated) { ' TRUNCATED' } else { '' }), $(if ($scan.failed -gt 0) { " UNREADABLE=$($scan.failed)" } else { '' }))
+      if ($scan.truncated) { $script:scanTruncated = $true }
+    }
+
+    if ($targetFacts.Errors.Count -gt 0) {
+      $verdict = 'INCOMPLETE'
+      $reason = 'Some observations failed; missing evidence is not evidence that a right is absent or a repair is safe.'
+    } elseif ($packageTargets.Count -gt 0) {
+      $blocked = @($packageTargets | Where-Object { -not $factsByPath[$_].HasWriteDac })
+      $verdict = if ($needsPrecondition -or $blocked.Count -gt 0) { 'BOTH' } else { 'CULPRIT' }
+      $reason = 'Package allow ACEs were observed. Required access checks determine whether the caller can perform the requested repair; other causes remain possible.'
+    } elseif ($unreadable) {
+      $verdict = 'UNREADABLE'
+      $reason = 'The requested ACL could not be read; its entries and the cause of denial are unknown.'
+    } elseif ($needsPrecondition) {
+      $verdict = 'PRECONDITION'
+      $reason = 'The caller cannot open the requested object with both WRITE_DAC and WRITE_OWNER. The reported allow and deny ACEs are evidence, not an attribution to one rule.'
+    } else {
+      $verdict = 'NOT_THIS_CLASS'
+      $reason = 'No package allow ACE was observed and both required rights are available. Other ACL restrictions and causes of the original failure are not ruled out.'
+    }
+    Write-Line ('VERDICT={0}' -f $verdict)
+    Write-Report decision classify $full $verdict $reason @{ writeDac = $targetFacts.HasWriteDac; writeOwner = $targetFacts.HasWriteOwner; packageObjects = @($packageTargets) }
+
+    if ($Restore) {
+      Restore-SavedDacl -FullPath $full -Record $Restore -Root $AllowRoot
+      continue
+    }
+    if ($targetFacts.Errors.Count -gt 0) {
+      Write-Decision $mode $full refused 'Required observations are incomplete; no repair was attempted for this path.'
+      $refused++
+      break paths
+    }
+
+    # Nothing is changed while a package source or a grant target is out of reach: a
+    # repair that cannot finish would leave the tree half repaired before refusing.
+    foreach ($packagePath in $packageTargets) {
+      $refusal = Get-RepairRefusal -FullPath $packagePath -Root $AllowRoot -AllowEqual
+      if ($refusal) { Write-Line ('REPAIR_REFUSED {0}' -f $refusal); Write-Decision $mode $packagePath refused $refusal; $refused++; break paths }
+      if ($factsByPath[$packagePath].Errors.Count -gt 0) {
+        Write-Decision $mode $packagePath refused 'The ACL observations are incomplete; collateral changes could not be verified.'
+        $refused++
+        break paths
+      }
+    }
+
+    # Missing WRITE_DAC or WRITE_OWNER on a directory in the chain is what stops DSH
+    # from provisioning the workspace grant. One approved run repairs every such
+    # directory, including the authorized root itself.
+    $grantTargets = @($inspectOrder | Where-Object {
+      [System.IO.Directory]::Exists($_) -and $factsByPath[$_].Readable -and $factsByPath[$_].Errors.Count -eq 0 -and
+      ((-not $factsByPath[$_].HasWriteDac) -or (-not $factsByPath[$_].HasWriteOwner)) -and
+      -not (Get-RepairRefusal -FullPath $_ -Root $AllowRoot -AllowEqual)
+    })
+    # Writing a DACL needs WRITE_DAC: refuse a target that lacks it before anything is
+    # changed, instead of failing mid-repair and marking a recovery for an object that
+    # the rollback then cannot restore either.
+    foreach ($object in $grantTargets) {
+      if (-not $factsByPath[$object].HasWriteDac) {
+        Write-Line ('REPAIR_REFUSED {0} needs WRITE_DAC; stop for permission-policy review' -f $object)
+        Write-Decision $mode $object refused 'Effective WRITE_DAC is absent; adding the grant requires that right.'
+        $refused++
+        break paths
+      }
+    }
+    if ($grantTargets.Count -gt 0) {
+      Write-Report decision grant_targets $full selected 'These directories lack effective WRITE_DAC or WRITE_OWNER; each is backed up, then receives a FullControl allow ACE for the current user.' @{ paths = @($grantTargets) }
+    }
+    foreach ($object in $grantTargets) {
+      $grantBefore = $factsByPath[$object]
+      Save-AclBackup -FullPath $object -Directory $Out -Root $AllowRoot
+      $grantAcl = Get-Acl -LiteralPath $object
+      $grantAcl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new(
+        [System.Security.Principal.SecurityIdentifier]::new($meSid),
+        [System.Security.AccessControl.FileSystemRights]::FullControl,
+        [System.Security.AccessControl.AccessControlType]::Allow))
+      Invoke-ReportedOperation grant_dacl $object "WRITE_DAC or WRITE_OWNER is missing; add a FullControl allow ACE for $meSid while preserving deny ACEs, owner and SACL." acl {
+        [Dsh.TokenInfo]::SetDacl($object, $grantAcl.GetSecurityDescriptorSddlForm([System.Security.AccessControl.AccessControlSections]::Access))
+      }
+      $grantAfter = Get-ObjectFacts -FullPath $object -MeSid $meSid -CompactRecord
+      $factsByPath[$object] = $grantAfter
+      $verified = $grantAfter.Readable -and $grantAfter.Errors.Count -eq 0 -and $grantAfter.HasWriteDac -and $grantAfter.HasWriteOwner
+      Write-Report verification grant $object $(if ($verified) { 'verified' } else { 'failed' }) 'The DACL write completed; recheck effective access before claiming that provisioning can succeed. On failure, restore this invocation and stop.' @{
+        before = @{ writeDac = $grantBefore.HasWriteDac; writeOwner = $grantBefore.HasWriteOwner }
+        after = @{ writeDac = $grantAfter.HasWriteDac; writeOwner = $grantAfter.HasWriteOwner }
+        recovery = $recoveries[-1].command
+      }
+      if ($verified) {
+        Write-Line ('GRANTED {0} SID={1}' -f $object, $meSid); $granted++
+      } else {
+        Write-Line ('GRANT_FAILED {0}; effective WRITE_DAC and WRITE_OWNER were not both confirmed; restore this invocation and stop' -f $object)
+        $refused++
+        break paths
+      }
+    }
+
+    $sources = @($packageTargets | Where-Object {
+      @($factsByPath[$_].Aces | Where-Object { $_.type -eq 'Allow' -and $_.sid -match $PACKAGE_SID -and -not $_.inherited }).Count -gt 0
+    })
+    # Ancestor first, for chain and scan-discovered sources alike.
+    $sources = @($sources | Sort-Object -Property @{ Expression = { $_.Split([char]92).Count } }, @{ Expression = { $_ } })
+    foreach ($source in $sources) {
+      if (-not $factsByPath[$source].HasWriteDac) {
+        Write-Line ('REPAIR_REFUSED {0} needs WRITE_DAC; stop for permission-policy review' -f $source)
+        Write-Decision $mode $source refused 'Effective WRITE_DAC is absent; removing a package allow ACE requires that right.'
+        $refused++
+        break paths
+      }
+    }
+    if ($sources.Count -gt 0) {
+      Write-Report decision remove_package_sources $full selected 'Remove explicit package allow ACEs from their sources, ancestor first, leaving inheritance enabled so inherited copies follow their repaired source.' @{
+        sources = @($sources); affectedPaths = @($packageTargets)
+      }
+    }
+    foreach ($source in $sources) {
+      Save-AclBackup -FullPath $source -Directory $Out -Root $AllowRoot
+      $sids = @($factsByPath[$source].Aces | Where-Object { $_.type -eq 'Allow' -and $_.sid -match $PACKAGE_SID -and -not $_.inherited } | ForEach-Object { $_.sid } | Sort-Object -Unique)
+      foreach ($sid in $sids) {
+        Invoke-ReportedOperation remove_package_allow $source "Remove the observed package allow ACE for $sid; preserve deny ACEs and all other principals." acl {
+          $output = @(icacls $source /remove:g "*$sid" 2>&1)
+          if ($LASTEXITCODE -ne 0) { throw "icacls removal exit $($LASTEXITCODE): $($output -join [char]10)" }
+        }
+      }
+    }
+
+    # A package deny can share the removed allow's SID; only allow ACEs were removed.
+    foreach ($packagePath in $packageTargets) {
+      $fixBefore = $factsByPath[$packagePath]
+      $fixAfter = Get-ObjectFacts -FullPath $packagePath -MeSid $meSid -CompactRecord
+      # Compare the object's own ACEs as sorted sets: listing order and inherited
+      # entries follow the parent, so neither proves a collateral change.
+      $rowOf = { param($ace) '{0}|{1}|{2}|{3}|{4}' -f $ace.type, $ace.sid, $ace.rights, $ace.inheritance, $ace.propagation }
+      $ownAfter = @($fixAfter.Aces | Where-Object { -not $_.inherited } | ForEach-Object { & $rowOf $_ } | Sort-Object)
+      $expectedOwn = @($fixBefore.Aces | Where-Object { -not $_.inherited -and -not ($_.type -eq 'Allow' -and $_.sid -match $PACKAGE_SID) } | ForEach-Object { & $rowOf $_ } | Sort-Object)
+      $collateral = (@($expectedOwn) -join [char]10) -eq (@($ownAfter) -join [char]10)
+      $verified = $fixAfter.Readable -and $fixAfter.Errors.Count -eq 0 -and $fixAfter.PackageAces.Count -eq 0 -and $collateral
+      Write-Report verification fix $packagePath $(if ($verified) { 'verified' } else { 'failed' }) 'The removal command completed; verify that package allow ACEs disappeared and other own ACEs remained unchanged. On failure, restore this invocation and stop.' @{
+        remainingPackageAces = $fixAfter.PackageAces; otherEntriesUnchanged = $collateral
+      }
+      if ($verified) {
+        $removedSids = @($fixBefore.Aces | Where-Object { $_.type -eq 'Allow' -and $_.sid -match $PACKAGE_SID -and -not $_.inherited } | ForEach-Object { $_.sid } | Sort-Object -Unique)
+        foreach ($sid in $removedSids) {
+          Write-Line ('FIXED {0} SID={1}' -f $packagePath, $sid); $fixed++
+        }
+      } else {
+        Write-Line ('FIX_FAILED {0} collateral_change={1}' -f $packagePath, (-not $collateral))
+        $refused++
+        break paths
+      }
+    }
+
+    if ($packageTargets.Count -eq 0 -and $grantTargets.Count -eq 0) {
+      Write-Decision $mode $full skipped 'No package allow ACE and no missing WRITE_DAC or WRITE_OWNER was observed on the inspected objects; no ACL change was needed.'
+    }
+  }
+} catch {
+  $exitCode = if ($_.Exception -is [System.ArgumentException]) { 2 } else { 1 }
+  Write-Report error $mode $currentPath stopped 'Execution stopped after an exception. An interrupted write may have changed state; attempted repairs will be restored before the final summary.' @{ error = (Get-HResultChain $_.Exception); location = $_.InvocationInfo.PositionMessage }
+} finally {
+  if ($refused -gt 0 -and $exitCode -eq 0) { $exitCode = 2 }
+  if ($exitCode -ne 0 -and -not $Restore) {
+    for ($i = $recoveries.Count - 1; $i -ge 0; $i--) {
+      $recovery = $recoveries[$i]
+      if (-not $recovery.attempted) { continue }
+      Write-Decision rollback $recovery.path selected 'The repair failed; restore every attempted DACL change from this invocation in reverse order before stopping.'
+      try {
+        Restore-SavedDacl -FullPath $recovery.path -Record $recovery.record -Root $AllowRoot
+        $recovery.restored = $true
+        $rollbackStatus = 'verified'
+      } catch {
+        $rollbackStatus = 'failed'
+        Write-Report error rollback $recovery.path stopped 'Recovery was not verified. Stop repairs and retain the pending recovery commands in reverse order.' @{ error = (Get-HResultChain $_.Exception) }
+        break
+      }
+    }
+  }
+  $pending = @($recoveries | Where-Object { $_.attempted -and -not $_.restored } | ForEach-Object { $_.command })
+  [array]::Reverse($pending)
+  $repaired = ($fixed + $granted) -gt 0
+  $nextAction = if ($rollbackStatus -eq 'failed') { 'restore_pending_then_stop' } elseif ($exitCode -ne 0 -or $observationFailures -gt 0) { 'stop' } elseif ($repaired) { 'verify_original_confined_operation' } else { 'stop' }
+  # The tool keeps only the tail of stdout. Recapitulate the decisions here so the
+  # records a reader needs survive truncation; the report file holds every record.
+  $recap = [ordered]@{
+    verdicts = @($reports | Where-Object { $_.operation -eq 'classify' } | ForEach-Object {
+      @{ path = $_.path; verdict = $_.status; writeDac = $_.details['writeDac']; writeOwner = $_.details['writeOwner']; packageObjects = $_.details['packageObjects'] }
+    })
+    changes = @($reports | Where-Object { $_.kind -eq 'action' -and $_.details['effect'] -eq 'acl' -and $_.status -eq 'completed' } | ForEach-Object { @{ operation = $_.operation; path = $_.path } })
+    verifications = @($reports | Where-Object { $_.kind -eq 'verification' } | ForEach-Object { @{ operation = $_.operation; path = $_.path; status = $_.status } })
+    refusals = @($reports | Where-Object { $_.kind -eq 'decision' -and $_.status -eq 'refused' } | ForEach-Object { @{ path = $_.path; reason = $_.reason } })
+    scans = @($reports | Where-Object { $_.operation -eq 'subtree_scan' } | ForEach-Object {
+      @{ path = $_.path; visited = $_.details['visited']; packageSources = @($_.details['packageSources']); truncated = $_.details['truncated']; unreadable = $_.details['unreadable'] }
+    })
+    report = $reportPath
+  }
+  $status = if ($exitCode -ne 0) { 'failed' } elseif ($observationFailures -gt 0) { 'partial' } else { 'completed' }
+  Write-Report summary $mode $currentPath $status 'Operation completion records API execution; verification records the observed result. Only rerunning the original confined operation can confirm its failure is resolved.' @{
+    exitCode = $exitCode; fixed = $fixed; granted = $granted; refused = $refused; restored = $restored
+    operations = @($operations.ToArray()); recoveries = @($recoveries.ToArray()); automaticRollback = $true; observationFailures = $observationFailures
+    rollback = $rollbackStatus; rollbackCommands = $pending; nextAction = $nextAction; scanTruncated = $scanTruncated; report = $reportPath
+  }
+  # Last on stdout, after the summary record: whatever the tool truncates, the tail
+  # still carries the decisions, the report path and the counts.
+  Write-Line ('RECAP ' + ($recap | ConvertTo-Json -Depth 8 -Compress))
+  if ($reportPath) { Write-Line ('REPORT_FILE {0}' -f $reportPath) }
+  Write-Line ('SUMMARY FIXED={0} GRANTED={1} REFUSED={2} RESTORED={3}' -f $fixed, $granted, $refused, $restored)
+  if ($reportWriter) { $reportWriter.Dispose() }
+}
+exit $exitCode

package/lib/index.js

@@ -1,2 +1,2 @@
-import { a as assertTempRootOutsideWorkspace, i as AclWriteGrant, n as tempWriteSid, r as workspaceWriteSid, t as AclSandbox } from "./types-DxezulnA.js";
-export { AclSandbox, AclWriteGrant, assertTempRootOutsideWorkspace, tempWriteSid, workspaceWriteSid };
+import { a as workspaceWriteSid, i as tempWriteSid, n as ACL_DIAGNOSIS_SKILL, o as AclWriteGrant, r as registerAclDiagnosisSkill, s as assertTempRootOutsideWorkspace, t as AclSandbox } from "./types-Cl_DXjhk.js";
+export { ACL_DIAGNOSIS_SKILL, AclSandbox, AclWriteGrant, assertTempRootOutsideWorkspace, registerAclDiagnosisSkill, tempWriteSid, workspaceWriteSid };

package/lib/runner.js

@@ -1,4 +1,4 @@
-import { a as assertTempRootOutsideWorkspace, n as tempWriteSid, o as win32, r as workspaceWriteSid, t as AclSandbox } from "./types-DxezulnA.js";
+import { a as workspaceWriteSid, c as win32, i as tempWriteSid, s as assertTempRootOutsideWorkspace, t as AclSandbox } from "./types-Cl_DXjhk.js";
 import { closeSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { SUBPROCESS_CONTROL_ENV, SUBPROCESS_CONTROL_FD } from "@deepseek-ai/dsh-subprocess/control";

package/lib/types/acl-skill.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Registers the bundled Windows sandbox ACL diagnosis skill.
+ *
+ * The provider owns a private filesystem copy of its resources so external
+ * PowerShell can execute them even when the package lives inside ASAR or SEA.
+ * Disposing the registration removes both the provider and its resource copy.
+ *
+ * @module @deepseek-ai/dsh-sandbox-windows-acl
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Bundled skill that diagnoses Windows sandbox ACL failures. */
+export declare const ACL_DIAGNOSIS_SKILL = "diagnose-windows-sandbox-acl";
+/**
+ * Register the bundled diagnosis skill with a private resource directory owned by this fiber.
+ * Missing or invalid packaged assets fail registration; disposal removes the directory.
+ * @param ctx - Context carrying the skill registry.
+ */
+export declare function registerAclDiagnosisSkill(ctx: Context): void;
+//# sourceMappingURL=acl-skill.d.ts.map

package/lib/types/index.d.ts

@@ -45,6 +45,7 @@
 export { AclWriteGrant } from './grant.ts';
 export { assertTempRootOutsideWorkspace } from './path-boundary.ts';
 export { tempWriteSid, workspaceWriteSid } from './workspace-sid.ts';
+export { ACL_DIAGNOSIS_SKILL, registerAclDiagnosisSkill } from './acl-skill.ts';
 /** Construction options: the workspace/temp allowlists and their distinct SID identities. */
 export interface AclSandboxOptions {
     /** Directories the confined child may write into (must exist and be caller-owned). */

package/lib/{types-DxezulnA.js → types-Cl_DXjhk.js}

@@ -1,8 +1,13 @@
-import { existsSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ERROR_INSUFFICIENT_BUFFER, Win32Error, allocPtrSlot, allocUint32, decodePtr, decodeUint32, drainPipe, extendWin32ProcessBindings, isNullPtr, isNullPtr as isNullPtr$1, spawnInheritedJobProcess, spawnPipedProcess, throwLastError, throwLastError as throwLastError$1, throwWin32, waitForProcessExit } from "@deepseek-ai/dsh-win32-process";
 import { createHash } from "node:crypto";
 import { createLazyRequire } from "@deepseek-ai/dsh-lazy-require";
+import { readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+import { parse } from "yaml";
 //#region lib/types/win32-abi.js
 /** ACL/token-specific Win32 constants. */
 /** OpenProcess access required to query the current process token. */
@@ -1052,6 +1057,88 @@ function tempWriteSid(tempDir) {
 	return `S-1-4-${digest.readUInt32LE(0) % (2 ** 30 - 1) + 1}-${digest.readUInt32LE(4) % (2 ** 30 - 1) + 1}-1`;
 }
 //#endregion
+//#region lib/types/acl-skill.js
+/**
+* Registers the bundled Windows sandbox ACL diagnosis skill.
+*
+* The provider owns a private filesystem copy of its resources so external
+* PowerShell can execute them even when the package lives inside ASAR or SEA.
+* Disposing the registration removes both the provider and its resource copy.
+*
+* @module @deepseek-ai/dsh-sandbox-windows-acl
+*/
+/** Bundled skill that diagnoses Windows sandbox ACL failures. */
+const ACL_DIAGNOSIS_SKILL = "diagnose-windows-sandbox-acl";
+/** Provider name this module registers the skill under. */
+const PROVIDER = "dsh-windows-acl";
+function parseSkill(raw, path) {
+	const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw);
+	if (frontmatter?.[1] === void 0) throw new Error(`dsh-sandbox-windows-acl: ${path} has no YAML frontmatter`);
+	const metadata = parse(frontmatter[1]);
+	const description = typeof metadata === "object" && metadata !== null && "description" in metadata ? metadata.description : void 0;
+	if (typeof description !== "string" || description.length === 0) throw new Error(`dsh-sandbox-windows-acl: ${path} has no description`);
+	return {
+		description,
+		content: raw.slice(frontmatter[0].length).trim()
+	};
+}
+/**
+* Register the bundled diagnosis skill with a private resource directory owned by this fiber.
+* Missing or invalid packaged assets fail registration; disposal removes the directory.
+* @param ctx - Context carrying the skill registry.
+*/
+function registerAclDiagnosisSkill(ctx) {
+	const packaged = fileURLToPath(new URL(`../assets/${ACL_DIAGNOSIS_SKILL}/`, import.meta.url));
+	ctx.effect(function* () {
+		const directory = mkdtempSync(join(tmpdir(), "dsh-acl-skill-"));
+		yield async () => {
+			await rm(directory, {
+				recursive: true,
+				force: true
+			});
+		};
+		mkdirSync(join(directory, "scripts"));
+		for (const path of ["SKILL.md", "scripts/diagnose-windows-sandbox-acl.ps1"]) writeFileSync(join(directory, path), readFileSync(join(packaged, path)), {
+			flag: "wx",
+			mode: 384
+		});
+		const locator = join(directory, "SKILL.md");
+		const { description } = parseSkill(readFileSync(locator, "utf8"), locator);
+		const candidate = {
+			name: ACL_DIAGNOSIS_SKILL,
+			description,
+			invocation: {
+				modelInvocable: true,
+				userInvocable: true
+			},
+			provider: PROVIDER,
+			source: "bundled",
+			rank: BUNDLED_SKILL_RANK,
+			resourceBase: {
+				kind: "directory",
+				path: directory
+			},
+			locator
+		};
+		const provider = {
+			name: PROVIDER,
+			list: () => Promise.resolve([candidate]),
+			async get(entry, options) {
+				const { rank: _rank, locator: entryPath, ...summary } = entry;
+				const raw = await readFile(entryPath, {
+					encoding: "utf8",
+					signal: options.signal
+				});
+				return {
+					...summary,
+					content: parseSkill(raw, entryPath).content
+				};
+			}
+		};
+		yield ctx.skills.registerProvider(() => provider);
+	}, "Windows ACL diagnosis skill resources");
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Windows ACL write-restriction sandbox backend for the DeepSeek Harness
@@ -1321,4 +1408,4 @@ var AclSandbox = class {
 	}
 };
 //#endregion
-export { assertTempRootOutsideWorkspace as a, AclWriteGrant as i, tempWriteSid as n, win32 as o, workspaceWriteSid as r, AclSandbox as t };
+export { workspaceWriteSid as a, win32 as c, tempWriteSid as i, ACL_DIAGNOSIS_SKILL as n, AclWriteGrant as o, registerAclDiagnosisSkill as r, assertTempRootOutsideWorkspace as s, AclSandbox as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-sandbox-windows-acl",
   "description": "Windows ACL write-restriction sandbox backend (restricted-token spawn with capability-SID write allowlist) for the DeepSeek Harness sandbox seam",
-  "version": "0.1.7-rc.2",
+  "version": "0.2.0-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -29,23 +29,29 @@
     "lib/index.js",
     "lib/runner.js",
     "lib/types-*.js",
+    "assets",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-subprocess": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-skill": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.2.0-rc.2"
   },
   "dependencies": {
-    "koffi": "^3.1.0",
-    "@deepseek-ai/dsh-win32-process": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-lazy-require": "0.1.7-rc.2"
+    "koffi": "3.1.1",
+    "yaml": "^2.4.2",
+    "@deepseek-ai/dsh-lazy-require": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-win32-process": "0.2.0-rc.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-pwsh-local": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-sandbox-local": "0.1.7-rc.2",
+    "@deepseek-ai/cordis-plugin-include": "~1.0.9",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
+    "@deepseek-ai/dsh-pwsh-local": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox-local": "0.2.0-rc.2",
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh-subprocess": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-skill": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-subprocess": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-subprocess-local": "0.2.0-rc.2"
   }
 }