Persist AGENTS.md snapshots and restore them verbatim once per compaction

What variant of Codex are you using?

Codex desktop app on macOS. This is a feature proposal for the shared context/compaction machinery, also relevant to CLI sessions.

What feature would you like to see?

Persist the original text of loaded AGENTS.md instructions as session-owned snapshots, and restore the applicable snapshots verbatim exactly once at each compaction boundary.

The goal is to keep repository instructions stable across long sessions without relying on the model's summary to reconstruct them.

Proposed behavior

1. Capture at initial loading. Store each instruction file's original text separately from ordinary conversation history, together with its source path, scope, precedence/order, and content digest. Support multiple applicable files and preserve existing instruction discovery, scope, and precedence semantics.
2. Pin the session's snapshots. Later filesystem edits must not silently replace the attached versions. Provide an explicit user action to refresh them, with the changed files and versions visible. Refreshed snapshots take effect at the next compaction; immediate activation can explicitly trigger compaction.
3. Use compaction as the sole automatic reinjection point after initial loading. Build the replacement context from the compacted working history and one verbatim copy of each applicable snapshot. Ordinary turns continue using that context; they do not append another instruction copy.
4. Restore before execution resumes. Complete restoration before the next model invocation, including when automatic compaction occurs mid-turn. A delayed hook must not leave a continuation running without the restored instructions.
5. Preserve provenance and prevent duplication. Keep snapshots distinguishable from the work summary. Summarized interpretations must not replace their source text or change its instruction priority. Repeated compactions must not accumulate old instruction copies.
6. Make capacity failures explicit. If applicable snapshots cannot fit within the supported instruction/context budget, report that condition rather than silently truncating or summarizing them.

Acceptance criteria

• After repeated manual and automatic compactions, applicable attached instruction text remains byte-for-byte identical to its pinned snapshot.
• Multiple root/nested instruction files retain their scope and ordering.
• Filesystem changes alone do not alter the session's pinned content; explicit refresh has a visible activation boundary.
• Session resume preserves snapshots and their identities.
• The first continuation after compaction contains the restored instructions exactly once, with no intervening model/tool decision using incomplete context.

Additional information

In a long desktop session, an explicit repository branch-naming rule was violated, and the continuation summary carried an incorrect interpretation of the naming requirement. This motivated the request, but it does not establish that compaction removed the original instructions or caused the initial mistake.

The current implementation already has initial-context reinjection paths in compact.rs. This proposal asks for an explicit, testable contract for durable AGENTS.md snapshots, version refresh, and exactly-once restoration across those paths. It could build on the existing machinery.

The guarantee is preservation and availability of instruction text, not guaranteed model compliance. The scope is AGENTS.md instruction preservation; broader context-specific instruction routing can be considered separately.

Related proposals:

• #25083 — Do Not Compact areas.
• #29816 — Additive compaction guidance.
• #25884 — Loaded AGENTS.md instructions applied inconsistently later in a session.

This proposal makes the session snapshot lifecycle and the compaction-only restoration boundary explicit, rather than leaving preservation to a summarization prompt.

Start with codex-rs/core/src/compact.rs and trace the existing initial-context reinjection paths. Map where session-owned snapshots, refresh boundaries, compaction, continuation execution, and resume state would be represented. Done means the acceptance criteria hold across repeated manual and automatic compactions, including exact-once restoration, preserved ordering and provenance, explicit capacity failures, and no incomplete continuation.