Problem: Codex sandbox error helper_unknown_error: setup refresh had errors (write permission/ACL) —— Trove problem library

What you will run into

Codex suddenly reports helper_unknown_error: setup refresh had errors while running shell commands; even with workspace_write permission, writing files under the project directory keeps failing;

after the failure the agent can only fall back to an escalated execution path (needs human approval).

New machines + directories copied from an old machine, cross-machine/cross-user shared directories, and WSL UNC paths trigger this most easily.

Why this happens

Codex runs a "setup refresh" at startup: it checks and fills write permissions (ACL/ACE) on the configured write roots; on failure the whole thing reports setup refresh had errors (shown as helper_unknown_error in the UI). Typical triggers:

The startup setup refresh is an ACL/ACE permission self-check and write-back for the configured write roots: the client verifies the current user can write them, and any check failure surfaces as setup refresh had errors.

Windows ACLs record ownership by SID. If the directory owner is a SID from another machine or a deleted user, the current user is not the owner.

Such a user cannot modify the ACL even with read/write access, because modifying ACLs requires ownership or privilege. Folders copied from another machine are the classic source.

UNC/WSL paths (\wsl.localhost\...) failing at GetSecurityInfo are a separate chain (reproduced locally).

Deterministic takeaway: first separate "no permission" from "ACL not modifiable". icacls <dir> shows the owner and the effective ACL; for copied dirs, take ownership with takeown /f <dir> /r before changing ACLs.

For UNC/WSL write roots, use in-WSL paths (/root/...) instead of Windows-side paths.

Fixed diagnostic: an error at the permission-check stage plus a copied directory means a SID ownership problem — takeown first.

Step by step

1. Check the sandbox log to locate it — Diagnose

Faster than guessing: C:\Users\<user>\.codex\.sandbox\sandbox.<date>.log (old path C:\Users\<user>\.codex.sandbox\...). Search for setup refresh had errors / write ACE to see which path and what error.

2. Change the owner (most common fix) — Required

Command-line equivalent:

takeown /f <dir> /r /d y

Or in the GUI: Explorer -> directory Properties -> Security -> Advanced -> Change owner -> current user, ticking "Replace owner on subcontainers and objects".

3. Add ACL (when the owner is right but permissions are still missing) — Required

icacls <dir> /grant <user>:(OI)(CI)F /T

4. Verify recovery — Required

Open a new Codex session to trigger setup refresh; the log showing errors=[] means recovered - idempotent, no reinstall/reset needed.

How to confirm it works

The sandbox log shows the recovery marker (measured output shape):

sandbox.<date>.log
-> setup refresh completed with errors: [] (errors=[])
-> setup binary completed

Write operations to the project directory work normally in the Codex session; no more escalation approval needed.

Other environments

Symptom

Codex reports helper_unknown_error: setup refresh had errors while running shell; even with workspace_write permission, writing files under the project directory keeps failing; afterwards the agent tries an escalated execution path (needs human approval) and only continues after approval. Common on new machines + directories copied from an old machine, cross-machine/cross-user shared directories, and WSL UNC paths.

Cause

Codex runs a "setup refresh" at startup: it checks and fills ACL/ACE write permissions on the configured write roots; on failure the whole thing reports setup refresh had errors (shown as helper_unknown_error). Typical triggers:

1. The directory owner is another machine's / a deleted user's SID (folder copied directly from an old machine) - the current user isn't the owner and can't modify that directory's ACL -> ACE check fails;
2. GetSecurityInfo fails on UNC/WSL paths (\\wsl.localhost\...) (measured variant on this machine, error code 1).

Solution

1. Check the sandbox log first (faster than guessing): C:\Users\<user>\.codex\.sandbox\sandbox.<date>.log (old path C:\Users\<user>\.codex.sandbox\sandbox.<date>.log). Search setup refresh had errors / write ACE to see the exact path and error.
2. Change the owner (most common fix): Explorer -> directory Properties -> Security -> Advanced -> Change owner -> current user, ticking "Replace owner on subcontainers and objects"; command-line equivalent: takeown /f <dir> /r /d y.
3. Add ACL (when the owner is right but permissions are still missing): icacls <dir> /grant <user>:(OI)(CI)F /T.
4. Verify recovery: open a new Codex session to trigger setup refresh; the log showing errors=[] means recovered - idempotent, no reinstall/reset needed.