fix(codex): share the user's global AGENTS.md into the managed Codex runtime home

[TopGrd]

Summary

Codex sessions launched inside Orca silently ignore the user's global ~/.codex/AGENTS.md. Orca points CODEX_HOME at its managed runtime home and mirrors skills/, hooks/, plugins/, plugin-state/, profile-v2/, themes/, and prompts/ back to ~/.codex — but not AGENTS.md, which is where Codex reads global user instructions from. This PR adds AGENTS.md to CODEX_SYSTEM_RESOURCE_ENTRIES so managed Codex sessions honor the user's global instructions again, plus a regression test and a docstring for the sync entry point.

Reproduction (A/B, macOS, Orca 1.4.124, codex-cli 0.143.0). With a global ~/.codex/AGENTS.md present, run in an empty directory (no project AGENTS.md):

codex exec --skip-git-repo-check "Does your context include a global AGENTS.md with user instructions? If yes, quote its first sentence verbatim; if none, answer: none"

Environment	Result
Orca terminal (inherits Orca's CODEX_HOME)	none
Same command with CODEX_HOME=~/.codex	quotes the user's AGENTS.md first sentence verbatim

Manually symlinking ~/.codex/AGENTS.md into the managed home flips the first case to the correct result, confirming the missing share is the entire cause.

Screenshots

No visual change.

Testing

• pnpm lint — fails on a clean main checkout with a pre-existing error unrelated to this PR (src/main/ipc/notification-authorization-status.ts:76 switch-exhaustiveness-check); oxlint on the two files touched here reports no issues
• pnpm typecheck — passed (all three tsconfigs)
• pnpm test — the suites covering this change pass: codex-home-paths.test.ts 7/7 and runtime-home-service.test.ts 83/83. The full runner aborts in my sandbox at ensure-native-runtime (Orca's patched node-pty build unavailable there) before vitest starts — deferring the full suite to CI
• pnpm build:desktop — passed; build:native blocked by the same sandbox limitation as above
• Added a regression test (mirrors the global AGENTS.md into the managed runtime home) that fails without the fix

AI Review Report

Reviewed the change against the existing link-or-copy semantics of linkSystemCodexResource:

• A pre-existing user-created AGENTS.md in the runtime home is not overwritten (existsSync short-circuit); an already-correct symlink is a no-op (targetAlreadyPointsToSource); deleting ~/.codex/AGENTS.md later removes only entries the sync can prove it owns (link-target match or copy marker).
• Cross-platform: macOS/Linux get a plain file symlink (junction only applies to directories); on Windows, file symlinks can fail outside developer mode and fall back to the ownership-marked copy path (cpSync handles files), refreshing on later syncs — identical to how the existing file entry profile-v2 behaves. Paths are built with path.join; no shell, shortcuts, labels, or renderer code involved.
• Behavior change flagged and accepted: managed Codex sessions start honoring the user's global instructions (that is the fix). Anyone who intentionally wants different instructions for Orca-managed sessions can place their own AGENTS.md in the runtime home — it is respected and never overwritten.

Security Audit

• No command execution, no new input parsing, no IPC or network surface changes.
• Shares only the instructions file. auth.json / config.toml / hooks.json remain private to the managed home — the auth isolation discussed in [Bug]: Orca's private CODEX_HOME causes a Codex auth-revocation war with the user's ~/.codex #5370 is untouched.
• Symlink source and target both live in user-owned locations (~/.codex and Orca's userData dir). The sync removes only provably-owned entries, so it cannot clobber unrelated user files.
• AGENTS.md is user-authored instructions by design; sharing the user's own file into the user's own managed home introduces no new trust boundary.

Notes

• Users who already worked around this by manually symlinking AGENTS.md into the managed home are unaffected: the sync detects the identical link target and no-ops.
• Remote/SSH and WSL homes follow whatever propagation path the existing entries (e.g. skills) already use; this PR only extends the entry list consumed by that shared mechanism.

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

The list of system Codex resource entries synced into the managed Codex home now includes AGENTS.md, with comments describing that it is sourced from the system Codex home's AGENTS.md and shared into managed home runtimes. A corresponding test was added that creates a system AGENTS.md file, invokes the sync function, and verifies that the resulting runtime AGENTS.md has matching content and is linked (via symbolic link or junction) to the system source file when linking is supported.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately describes the main change: sharing the user's global AGENTS.md into the managed Codex runtime home, which is the primary fix in this PR.
Description check	✅ Passed	The description is comprehensive and covers all required template sections: Summary explains the issue and fix clearly, Screenshots notes no visual change, Testing details all checks performed and regression test added, AI Review Report addresses cross-platform compatibility thoroughly (macOS/Linux/Windows symlink behavior, path handling), Security Audit covers all relevant security aspects, and Notes address platform-specific considerations.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}