Warn when unparseable agent definitions are silently skipped

[wgnrai]

Problem

When an agent definition (agent.yaml) contains a YAML authoring error (e.g. an unquoted colon in a description, or a bad indent), _get_agents_list_from_dir() catches the exception and silently continues. The agent simply vanishes from discovery — there is no log line at all. The only symptom surfaces much later, far from the cause: dispatching that profile fails with a distant "profile not found" error.

We hit this in production: four project agents were silently missing from the callable list for days before the root cause (a YAML typo) was found.

Solution

Two purely additive warnings, no behavior change:

1. Parse-failure warning in _get_agents_list_from_dir(): when an agent definition fails to load/validate, log a warning naming the agent directory, its containing dir, its origin (default/user/project/plugin), and the exception. Skipping still happens exactly as before.

2. Registered-but-undiscovered cross-check (_warn_undiscovered_project_agents()): in get_available_agents_dict(), cross-check slugs registered in the project's agents.json against discovered agents and warn once (per project, per process) about any registered slug that was not discovered — pointing at likely agent.yaml parse errors. The cross-check reads both known agents.json shapes (manifest {"agents": [{"slug": ...}]} and flat {"<slug>": {"enabled": ...}}).

A warn-once dedupe set keeps the cross-check from spamming, since get_available_agents_dict() is a hot path.

Testing

Scratch break-tests against a fresh worktree of main:

• Dir with one broken yaml (unquoted colon in description) + one good agent → warning fires naming the broken agent dir + error; good agent still discovered normally.
• Project with agents.json registering a ghost slug (no corresponding agent dir) + one real agent → exactly one warning naming the ghost slug; real agent unaffected; second call emits no additional warning (dedupe works).
• import helpers.subagents sanity check passes.
• Existing test files (tests/test_subagent_metadata_merge.py, tests/test_subagent_profiles.py): identical pass/fail set on patched vs. pristine main (the 6 pre-existing failures in test_subagent_profiles.py dispatch tests are unrelated and unchanged by this patch).

Backwards compatibility

Purely additive warning logs. No API, signature, or behavior changes — agents are still skipped exactly as before, only now visibly.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.