AGENTS.md is silently truncated and instructions near the end ignored

This is worth treating as a migration blocker, not only a startup-warning bug.

When teams share AGENTS.md / CLAUDE.md-style files across tools, the last sections are often the guardrails: deploy checks, secret rules, browser limits, and "do not run this" notes. Silent truncation means the user can believe the harness migrated cleanly while the riskiest instructions are the ones that disappeared.

A warning would help. An inspectable assembled-instructions path would help more, because it lets migration tools and CI checks prove what Codex actually loaded before the first edit.

I have been using this checklist shape for Claude Code -> Codex imports:
https://bringyour.ai/codex-import-checklist

The specific row I would add for this issue is: verify AGENTS.md byte size against the active Codex limit, then record whether truncation was impossible, warned, or actually observed.

For anyone debugging this: the painful part is there's no easy way to see which instructions ended up past the cut, so a rule that's "being ignored" looks like the model misbehaving when it actually never received the text.

I put together a small open-source CLI for exactly this case. It measures AGENTS.md in the same unit Codex truncates by (the 32 KiB project_doc_max_bytes limit), finds the exact byte where the cut lands, and lists which sections survive, are partially cut, or are dropped — so you can confirm what actually reached the model:

$ dropped --target codex AGENTS.md
AGENTS.md  —  43.5 KiB / 32.0 KiB (codex, bytes)  ✂ TRUNCATED
  cut at byte 32768 (line 44, col 1380)

  ✓ Build & Run      6.1 KiB
  ✓ Code Style       6.1 KiB
  ✓ Architecture     6.1 KiB
  ✂ Dependencies     kept 1.4 KiB · dropped 4.6 KiB  ← cut lands here
  ✗ Logging          6.1 KiB dropped
  ✗ Release & Secrets Handling   857 B dropped

dropped --target codex --ci also exits non-zero, so you can fail CI if an AGENTS.md ever goes over the limit. MIT, single binary, no telemetry: https://github.com/phrypy/dropped

Happy to delete this if it's not welcome on the thread — just figured it'd help others hitting the silent-truncation case.

Actual behavior: No warning at all. Users assume Codex is unreliable or that AGENTS.md doesn't work properly, when in reality their instructions are being silently clipped.

Yep, that's been my belief for the past 2 months! I only accidentally discovered today that my 40KB AGENTS.md was being truncated to 32KB and silently omitting 20% of my instructions! Please fix this.

codex 0.144.4

The 32 KiB cap has been named in this thread, but I think three properties of how it is applied explain the reports better than the number itself. All from codex-rs/core/src/agents_md.rs:95-144 on main @ bb5054fe.

1. It is one shared budget across the whole AGENTS.md chain, not a per-file cap. remaining is initialised once at :106 and decremented per file at :142.

1. It is consumed root-first, so the most specific file is the one clipped. agents_md_paths builds cwd->root then reverses (:201, dirs.reverse()). The behaviour is already pinned by a test: agents_md_tests.rs:624-655 (total_byte_limit_truncates_later_project_docs) sets limit 7 with root "root" and nested "abcdef" and asserts loaded.text() == "root\n\nabc". In a monorepo a large root AGENTS.md starves the package-local one you are actually working under.

1. The cut is a raw byte truncate (data.truncate(remaining), :121) followed by String::from_utf8_lossy (:132), so a cut landing mid-codepoint yields U+FFFD, and there is no marker in the text. The model just sees a sentence that stops.

The only signal is a tracing::warn! at :125-129 that goes to the log file, never the UI. Codex already has the right channel for this and uses it for the sibling case: the global AGENTS.md provider returns structured warnings (codex-home/src/instructions/mod.rs:33-48), session/mod.rs:559-566 folds them into config.startup_warnings, and the TUI renders them at tui/src/lib.rs:537-546. Project-doc truncation never joins that stream, because read_agents_md returns io::Result<Option<LoadedAgentsMd>> with no warnings channel.

Two things that may help people here today. ~/.codex/AGENTS.md is exempt from the limit entirely (codex-home/src/instructions/mod.rs:24-67 does a plain read with no budget), so moving the tail there works, at the cost of it applying to every project. And the budget is per turn-environment rather than per session: load_project_instructions (agents_md.rs:53-80) calls read_agents_md once per environment with a fresh remaining. There is an existing TODO acknowledging that at agents_md_tests.rs:1195-1230.

To tell which case you are in: run with RUST_LOG=codex_core::agents_md=warn and look for "project doc exceeds remaining budget; truncating" with the path field in ~/.codex/log/codex-tui.log. If the path is a nested AGENTS.md it is case 2, and raising project_doc_max_bytes in config.toml should make the ignored instruction take effect.

On fixes, roughly three options with different costs. Routing a warning into startup_warnings is the smallest, but needs a dedupe since AgentsMdManager::refresh runs per turn-environment. Truncating at a line boundary with an explicit marker tells the model it was clipped, but changes model-visible text, so it invalidates prompt-cache prefixes and churns the snapshot tests at agents_md_tests.rs:606-621. Changing allocation so the nearest doc is funded first fixes the monorepo case with no new config, but reverses the behaviour pinned by the test above and changes instruction precedence order.

I cannot tell from here whether most reports are the monorepo case or a single oversized file, and that is probably worth establishing before picking.