Missing core MCP tools do not trigger self-repair

Context

On 2026-08-20, one Codex seat ran for roughly twelve hours—from the app-server process beginning around 11:35 until its 23:32 restart—through reviews, implementation, a merged PR, and multiple compactions while both native institutional MCP surfaces were absent.

The evidence separates native attachment from server health:

The first mandatory mailbox check in AGENTS.md §mailbox_check_protocol could not be executed, but the seat normalized that as a missing capability and continued instead of treating it as infrastructure degradation.

This is recurrent, not hypothetical. Memory Core session e0ec27a1-dfc7-45fe-9987-9203a8fa28ee records an independent 2026-08-15 harness running an entire session without Memory Core until the operator noticed. A July Codex incident, session da81297b-a8f2-4208-9948-5605a11c9560, likewise had healthy remote servers/config but no native callable registry.

The Problem

The institutional rules name the positive path but not the negative transition:

1. session starts;
2. agent must call native list_messages({status:'unread'});
3. when that tool is absent or errors, no compact rule states that this observation is the trigger for /self-repair.

The current self-repair protocol also conflates three different states:

• native attachment absent while the repo-local MCP client is healthy;
• local Agent OS containers unhealthy where the seat may have Docker authority;
• a real cloud deployment where the seat has no container access and can only inspect/escalate.

That ambiguity made the wrong fallback look reasonable. Compaction preserved the rationalization instead of re-running the missing core check.

The Architectural Reality

This repair spans three load classes and must keep them separate.

1. Always-loaded trigger — AGENTS.md. The file is currently 24,380 / 24,576 bytes, leaving 196 bytes under the hard 24 KiB harness ceiling. The fix must replace/compress the existing mailbox sentence, not add a new section.
2. Conditionally loaded depth — self-repair skill payload. Deployment topology, authority, client/native classification, and escalation belong in the existing reference atlas. The 6-line SKILL.md router already has the correct MCP-infrastructure trigger and should not grow.
3. Codex salience after lifecycle resets — existing context hook. A SessionStart hook for startup|resume|compact can re-inject one bounded preflight sentence through .codex/hooks/codex-context.mjs. Current Codex hooks execute command handlers only; a repo-client probe cannot certify native attachment, because that exact probe was green during this incident. The hook is a reminder, not a health oracle.

Self-repair remains real work. Only the interrupted product/review lane waits for classification or handoff:

• local Docker authority may legitimately lead to inspect/restart/recreate/rebuild;
• cloud/no-container authority leads to bounded evidence plus escalation through an available channel;
• an unavailable Memory Core means A2A itself may be unavailable, so escalation cannot assume the broken channel.

The Fix

1. Replace the existing mailbox trigger in AGENTS.md with a byte-budget-neutral form that makes the negative path explicit: native list_messages missing/error → invoke /self-repair before continuing the interrupted lane. Absence must never be interpreted as an empty inbox.
2. Extend .agents/skills/self-repair/references/self-repair-protocol.md with an early attachment classifier:
   • native absent + repo client green → harness attachment/config/environment lane;
   • repo client red + local Docker authority → container/service lane;
   • repo client red + no runtime authority → inspect what is reachable, then escalate/block.
3. Add a bounded SessionStart registration for startup|resume|compact in .codex/hooks.json, reusing codex-context.mjs.
4. Make codex-context.mjs emit the compact core-preflight context for SessionStart without writing UserPromptSubmit prompt provenance or minting a turn-presence interval.
5. Extend the existing Codex context-hook unit spec and substrate-size gate. Do not add a new hook module.

Contract Ledger

Decision Record impact

Aligned with ADR 0007 and ADR 0008. This applies their compact-trigger → conditional-atlas shape and does not amend either decision.

Acceptance Criteria

• The always-loaded mailbox rule explicitly maps native list_messages absence/error to /self-repair.
• AGENTS.md remains at or below 24,576 bytes; the always-loaded delta is minimal or negative.
• The self-repair atlas distinguishes native attachment failure from server failure before any restart prescription.
• The self-repair atlas routes local Docker authority separately from cloud/no-container authority.
• Repair actions remain permitted while the interrupted lane is paused; cloud restoration is not falsely required when only escalation is authorized.
• Codex SessionStart on startup, resume, and compact injects one bounded core-preflight reminder.
• The hook does not claim native health, call the repo client as an attachment oracle, or create UserPromptSubmit prompt/turn-presence artifacts.
• Existing UserPromptSubmit and Stop-hook behavior remains unchanged.
• Focused hook tests, skill-manifest lint, and the substrate-size check pass.
• A client-green/native-missing falsifier proves the classifier chooses harness attachment repair.
• No mcp_servers.<id>.required = true admission lock is introduced; the session must remain available for self-repair.

Out of Scope

• Repairing Memory Core's current backup-maintenance degradation.
• Changing Agent OS container topology, cloud RBAC, or deployment ownership.
• Turning repo-client health into native attachment evidence.
• Adding a generic hook-to-MCP-registry API.
• Requiring every optional MCP server for every Neo task.
• Expanding the top-level self-repair router or adding a new skill.

Avoided Traps

• More always-loaded prose. The trigger must fit inside the existing 24 KiB contract.
• Failing thread admission. required = true prevents the affected agent from entering repair mode.
• Client-green means attached. Falsified directly: both clients were green while native namespaces were absent.
• Blind Docker restart. Wrong for harness attachment and unauthorized in many cloud deployments.
• Hook as health oracle. Current command hooks cannot observe the model's native callable registry.
• “No ordinary work.” Self-repair is work; only the interrupted lane is paused.

Pre-Flight / Structure Map

• npm run --silent ai:structure-map -- --root .agents/skills/self-repair --files --loc → router 6 LOC; protocol 28 LOC.
• npm run --silent ai:structure-map -- --root .codex/hooks --files --loc → codex-context.mjs 158 LOC; existing sibling codex-lane-state-stop.mjs 434 LOC.
• No new file placement is prescribed; supported targeted roots establish the two existing owning surfaces.

Related

Related: #17220 · #10559 · #16766

Live latest-open sweep: checked the 20 newest open issues at 2026-08-20T22:18:58.945Z; no equivalent ticket. The latest all-state A2A slice contained no overlapping claim. KB semantic search was treated as stale/supporting only; exact live GitHub and local corpus searches found no duplicate.

Origin Session ID: 0f8b5b8e-3f01-45c8-889e-1c2fd90b0584

Handoff Retrieval Hints: query_raw_memories("native MCP absent client green self repair") · sessions e0ec27a1-dfc7-45fe-9987-9203a8fa28ee, da81297b-a8f2-4208-9948-5605a11c9560 · exact anchors AGENTS.md §mailbox_check_protocol, .codex/hooks/codex-context.mjs, self-repair-protocol.md.