fix(codex): add writable roots only when the sandbox allows them

[fkaethner-lang]

What & why

Gate the Codex --add-dir argument on the effective sandbox permissions instead of appending it to every launch. A Codex agent spawned outside auto mode exited immediately with:

Error adding directories: Ignoring --add-dir ... because the effective permissions do not allow additional writable roots

The launcher was treating --add-dir as harmless outside writable sandboxes, but Codex rejects it when additional writable roots are not allowed.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Docs
• Build / CI

Evidence

Before

The demo shows main appending --add-dir even without a writable sandbox; the "Codex would reject" line is a script annotation quoting the real Codex error, not a live Codex run. Produced by demo-codex-add-dir.cjs, which loads the real modules through test/load-ts.cjs; run it with node demo-codex-add-dir.cjs <repo>.

After

The same demo shows --add-dir omitted for read-only launches and kept for -s workspace-write. The focused test goes from 1 pass / 14 fail on main to 15 pass / 0 fail on this branch; the main failures mostly come from the new helper not existing there, so the demo is the primary before evidence.

How I tested it

• OS: Windows 11
• Steps:
  • node demo-codex-add-dir.cjs <repo>
  • node --test test/codex-add-dir.test.cjs
  • npm run test:focused: no new failures vs. the Windows baseline.
  • Node and web typechecks pass.
  • Local Windows build: the agent starts without a writable sandbox; with -s workspace-write, it receives exactly the agent directory and the hive root.

Notes for review

codexSandboxAllowsExtraRoots(args) resolves -s, --sandbox, and --sandbox=..., with the last sandbox value winning, and recognizes full-auto/full-bypass launches. ensureAgent receives the launch arguments used for that decision, so the hive adds --add-dir only for workspace-write or danger-full-access; without a writable sandbox, writes still go through approval. Rebased on origin/main at a7452eea (v0.5.3-30): the Windows 11 baseline has 849 tests, 22 failing, including the unrelated upstream model-catalog drift.

This PR and the auto-mode-all-providers PR are independent and safe to merge in either order (combined: 59/59 relevant tests, including a merge-order test).

Checklist

• Before and after evidence is attached above, under both headings.
• npm run typecheck passes.
• npm run test:focused passes (no new failures vs. the Windows baseline; see How I tested it)
• npm run build succeeds (not run on this branch; a local Windows build containing this change was built and used)
• This PR is one change. Unrelated fixes belong in their own PR.
• I read the diff myself before opening this, and there is no debug output,
  commented-out code, or unrelated formatting churn in it. (Reviewed with AI assistance; see the evidence above.)
• Any new UI derives from DESIGN.md / tokens.ts — no ad-hoc colors,
  spacing, or fonts. (no UI / no art in this PR)
• If I added art, it's my own or compatibly licensed, and listed in
  ATTRIBUTION.md. (no UI / no art in this PR)

🤖 Generated with Claude Code

[github-actions]

✅ Evidence received. Before and after are both attached. Thanks — this is what makes a PR reviewable in one pass.

[mjaggard]

Thank you for addressing the read-only launch failure and for including Windows validation. I compared this with #705 because both changes touch Codex’s additional writable roots, and I think they cover complementary failure modes.

This PR makes a useful distinction between sandboxes that can accept additional writable roots and those that cannot. #705 does not implement that read-only gate, so it should not be considered a replacement for this change.

For the remote-resume failure in #642, however, #705 addresses a further restriction. With -a never -s workspace-write, this PR correctly retains --add-dir, but the existing transport path still produces --remote … resume … -a never -s workspace-write --add-dir …. Codex rejects permission overrides when resuming remotely, and rejects --add-dir with --remote even for writable sandboxes. #705 selects local --no-daemon execution for incompatible launches, retaining the session ID, requested permissions and writable roots; compatible launches retain managed remote access.

I applied this PR’s patch to #705 in an isolated worktree: it applied cleanly, and all 25 tests across the two Codex suites passed. This is a combined code/test check, not an end-to-end mobile or existing-session resume test.

My recommendation would therefore be to retain both changes rather than close #705 as a duplicate: this PR addresses which roots to grant, while #705 addresses which transport can accept the resulting launch. The trade-off in #705 is that incompatible launches lose mobile remote access; it does not silently remove permissions or required roots to keep remote mode enabled.