# Codex Operational Warning Health

CTM treats Codex startup diagnostics as source problems, not rendering noise.
The raw Terminal view stays raw: CTM does not hide or rewrite provider output.
Low-value warnings are already collapsed in Review and Conversation renderers,
but Terminal remains the escape hatch for exact debugging.

## Warning Classes

Codex warning floods usually come from two independent launch inputs:

- **Invalid generated skill metadata.** Codex validates every enabled plugin
  skill before the session starts. A generated `SKILL.md` with missing
  frontmatter or a `description` over 1024 characters causes repeated
  `Skipped loading ... invalid SKILL.md` warnings.
- **Unhealthy MCP servers.** Enabled MCP servers are initialized by Codex at
  startup. OAuth-backed remote MCPs such as Slack or enterprise gateway tools
  can be enabled but expired or not logged in, which produces startup warnings
  before the agent can do useful work.
- **Wrong OpenAI transport.** CTM can run with `OPENAI_API_KEY` and
  `OPENAI_BASE_URL` in its own environment for setup and background LLM jobs.
  Interactive Codex sessions should use Codex's own auth and a stable HTTPS
  OpenAI transport unless the operator explicitly overrides the provider.

Wall-E is special: it is CTM's local memory/context server. CTM never disables
Wall-E automatically. If Wall-E fails to initialize, the failure remains visible
and is recorded in session diagnostics.

## Launch-Time Repair

Before spawning a Codex session, CTM runs `codex-launch-health`:

1. Scan the generated Codex plugin cache under `~/.codex/plugins/cache`.
2. Repair only safe skill metadata issues:
   - parseable YAML frontmatter,
   - present `description`,
   - description length above the Codex limit.
3. Preserve the original file as `SKILL.md.ctm-bak` before rewriting.
4. Leave unrepairable files alone and record a diagnostic.

This repair is intentionally narrow. CTM does not rewrite user-authored skills
or infer missing frontmatter.

Generated plugin cache paths can change when Codex refreshes a plugin bundle.
The repair scheduler therefore only backs off after a real clean or repaired
scan. A launch with repair disabled does not count as a completed scan, and a
repairable write failure uses a short retry interval so the next Codex launch
can recover after transient filesystem or sync issues clear.

Set `CTM_CODEX_SKILL_REPAIR=0` to disable this repair path.

## Codex Auth Guard

Before spawning Codex, CTM strips inherited `OPENAI_API_KEY` and
`OPENAI_BASE_URL` from interactive Codex child processes so CTM's provider env
cannot override the user's normal Codex login/config path.

CTM previously prepended this provider override by default:

```text
-c model_provider="ctm-openai-https"
-c model_providers.ctm-openai-https.base_url="https://api.openai.com/v1"
-c model_providers.ctm-openai-https.requires_openai_auth=true
-c model_providers.ctm-openai-https.supports_websockets=false
```

That override forces Codex onto the public OpenAI Responses API endpoint and can
break ChatGPT/Codex subscription auth with `api.responses.write` scope errors.
It is now opt-in only for operators who intentionally want API-provider
transport:

```text
CTM_CODEX_HTTP_TRANSPORT=1
```

The override is launch-local and does not mutate `~/.codex/config.toml`. Set
`CTM_KEEP_OPENAI_ENV_FOR_CODEX=1` only when you intentionally want Codex to
inherit CTM's OpenAI environment.

## MCP Failure Feedback Loop

CTM observes raw Codex output for MCP startup/auth failures and stores a compact
failure record in the CTM settings table. On later Codex launches, CTM can add
session-local Codex config overrides for optional remote MCPs that recently
failed auth:

```text
-c mcp_servers.slack.enabled=false
-c mcp_servers.ask-data-ai.enabled=false
```

The override is per launch. It does not mutate `~/.codex/config.toml`, and it
expires after a short cooldown so a reconnect can take effect without manual DB
cleanup. Protected/local MCPs, including `wall-e`, are never disabled this way.

Set `CTM_CODEX_MCP_AUTO_DISABLE=0` to disable launch-local MCP overrides.

## UI Contract

- **Terminal:** exact provider stream; no warning folding or suppression.
- **Conversation/Review:** operational warnings collapse into a warning group
  so the real answer remains easy to read.
- **Diagnostics:** launch repairs and MCP failures are recorded per CTM session
  for debugging.

This preserves debuggability while fixing the recurring startup causes that make
the terminal unusable.
