feat(cli): add `codex debug agents-md` subcommand to inspect AGENTS.md discovery

What variant of Codex are you using?

CLI

What feature would you like to see?

Add codex debug agents-md — a new codex debug subcommand that reports the exact AGENTS.md discovery result for the current cwd, without spawning a session. Analogous to codex debug prompt-input / codex debug models, but scoped to AGENTS.md/instruction assembly.

The problem

Today, if AGENTS.md behavior looks wrong, the only user-facing way to inspect what actually loaded is codex debug prompt-input "test" — which dumps a 50KB+ JSON blob mixing sandbox prose, skills manifest, environment context, and (buried inside a user message) the resolved # AGENTS.md instructions for <path> block. That is a reverse-engineering exercise, not an observability primitive.

Every AGENTS.md-discovery bug filed in the last quarter — #28903 (ancestor dirs), #29535 (relative-link resolution), #24855 (wrong workspace/cwd on resume), #11757 (stale rehydrate from another workspace), #25884 (loaded but inconsistently applied), #22785 (SSH permission-denied) — requires the user to grep raw JSON to answer questions Codex already knows the answer to at load time:

• Which project root did discovery pick (marker file, path)?
• Which AGENTS.md files were walked, in which order, from root ? cwd?
• What bytes did each contribute? What was truncated against project_doc_max_bytes?
• Was AGENTS.override.md present at any level? Did it override anything?
• Which project_root_markers list was in effect (default .git vs user override)?
• Were any files skipped due to I/O errors, symlink cycles, or size caps?

Users, plugin authors, and issue triagers all need this. Right now they either read codex-rs/core/src/agents_md.rs or file a bug that a maintainer resolves with "please share debug prompt-input output."

Proposed shape

$ codex debug agents-md
project_root:            C:\D\oriz\repos\frk\omniroute  (marker: .git)
project_root_markers:    [".git"]  (source: default)
project_doc_max_bytes:   32768
project_doc_fallback_filenames: []

Discovered files (root ? cwd):
  1. C:\D\oriz\repos\frk\omniroute\AGENTS.md        36405 B  ?  TRUNCATED to 32768 B (remaining budget)
  Total loaded: 32768 B / 32768 B (100%)

Not discovered:
  - C:\D\oriz\AGENTS.md                              (above project root, not walked)
  - AGENTS.override.md                               (not present at any level)

User-scope instructions:
  - ~/.codex/AGENTS.md                              4210 B   ?  loaded (user-scope)

Add --json for CI/harness consumers (matches #16037's ask for machine-readable status).

Why a new subcommand and not extend /status

/status is session-scoped and inside the TUI. codex debug agents-md is:

1. Pre-session — answer "what will Codex load?" before starting a chat.
2. Deterministic — no model in the loop, no cache state, no thread history.
3. Scriptable — CI can gate on AGENTS.md drift (e.g. "assert this repo's AGENTS.md still resolves to 3 files totaling < 20KB").
4. Debuggable — reproduces the pure discovery function in isolation, so a bug reporter can attach one command's output instead of a redacted prompt-input dump.

Implementation notes

• Discovery logic already exists as read_agents_md / agents_md_paths in codex-rs/core/src/agents_md.rs. This subcommand wires that up to the codex debug CLI dispatcher — same pattern as debug prompt-input.
• No model calls, no network. Pure filesystem + config walk.
• Should honor -c project_root_markers='[".hg",".git"]' overrides via the shared -c flag so users can preview marker changes without editing ~/.codex/config.toml.
• On the --json shape: mirror debug models' style (top-level object with project_root, markers, discovered[], not_discovered[], user_scope[], total_bytes, truncated: bool).

Related issues / prior art

• #17401 — "@include directive for composable AGENTS.md files" — the comment thread explicitly requests "emit resolved include graph: source file, resolved path, bytes/tokens, and whether it was inlined or left as a reference" (unitedideas, caioribeiroclw-pixel, olijboyd). This subcommand is the minimum viable form of that.
• #16037 — machine-readable /status --json.
• #23279 — analogous codex models command (shipped as codex debug models).
• #17498 (closed) — "/status shows Agents.md: <none> even when AGENTS.md exists" — exactly the kind of report that a debug agents-md command lets a user self-diagnose in one line.
• #22785 (SSH permission-denied), #28903 (ancestor dirs), #29535 (relative links), #24855, #11757, #25884 — every one of these would have been faster to file and faster to close with debug agents-md output attached.

Version tested

codex-cli 0.142.4 (Windows x64). Verified by running codex debug prompt-input "hi" from C:\D\oriz\repos\frk\omniroute and grepping the JSON for the AGENTS.md block — that block exists but is not the primary tool for the job.