fix(planning): make auto model defaults runtime-aware; surface empty harness completions distinctly

[AbirAbbas]

Incident

A caller invoked swe-planner.plan with ai_provider="codex" explicitly and no
model overrides, in an environment where only OPENROUTER_API_KEY was set (no
Anthropic/OpenAI keys, no SWE_DEFAULT_* vars). Two independent failures
collapsed into one opaque error:

1. Cross-runtime model-id leakage. The planning-model default cascade
   (_default_planning_model()) resolved from env keys alone, ignoring the
   caller's pinned runtime. With only an OpenRouter key present it returned the
   OpenRouter auto-default model id — so the codex CLI was spawned with an
   openrouter/…-prefixed model its OpenAI backend cannot resolve. Every
   attempt completed in ~1s with a null/empty message.

2. Opaque empty completions. The pipeline surfaced only the generic
   "Product manager failed to produce a valid PRD" — indistinguishable from a
   genuine schema-quality failure (a weak model emitting unparseable output).
   One message, two very different root causes.

What changed

Runtime-aware auto default (fix(planning)) — _default_planning_model()
now takes the resolved runtime and delegates to the already-runtime-aware
resolve_runtime_models() cascade for the high-tier pm role. plan() threads
the resolved ai_provider into it. The auto default is gated on runtime:

• codex → a codex-native model (never an openrouter/…-prefixed id)
• open_code → the OpenRouter auto default (OpenRouter-only env) or the
  open_code base default otherwise
• claude_code → the historical sonnet default

Explicitly passed models and deployer env (SWE_DEFAULT_MODEL / AI_MODEL /
HARNESS_MODEL, SWE_MODEL_HIGH) still win verbatim — only the auto
default became runtime-aware.

Distinct empty-completion error (fix(runtime)) — new
EmptyHarnessCompletionError + check_empty_harness_completion(), wired into
the PM, architect, tech-lead and sprint-planner reasoners between the
fatal-error check and the parsed is None check. An empty completion (no parsed
object and no text — the signature of a provider/model mismatch or bad auth)
now raises an error naming the provider and model, e.g.:

PM harness returned an empty completion (provider=codex,
model=openrouter/deepseek/deepseek-v4-flash) — check provider auth/model
compatibility

The generic "failed to produce a valid …" message is kept only for genuinely
non-empty-but-unparseable output, and now also includes provider+model context.

The check is gated on failure_type. The SDK's terminal schema-validation
path returns result=None with failure_type=SCHEMA, which has exactly the
empty-completion shape (no parsed object, no text) but a completely different
cause — the agent did produce output, e.g. a malformed prd.json written via
the Write tool with no closing prose, which simply failed to validate. Telling
that operator to "check provider auth/model compatibility" points at the wrong
thing, so a schema classification is a no-op and the schema-invalid message
propagates. Every other classification (none/crash/timeout/api_error/
no_output) still raises, and results with no failure_type attribute at all
keep the previous behavior, so older SDKs are unaffected. The comparison is on
the token rather than an imported symbol because FailureType is not
re-exported from any public agentfield module.

Compatibility

This changes behavior for deployments that pin a non-Claude runtime and set no
model env var. The old cascade consulted _openrouter_only_env(), which
returns False as soon as SWE_DEFAULT_RUNTIME is set to anything — so those
deployments fell through to sonnet regardless of which runtime they pinned:

Config (no SWE_DEFAULT_MODEL / AI_MODEL / HARNESS_MODEL / SWE_MODEL_HIGH)	Before	After
SWE_DEFAULT_RUNTIME=open_code	sonnet	open_code base default
SWE_DEFAULT_RUNTIME=codex, OPENAI_API_KEY set	sonnet	gpt-5.3-codex
SWE_DEFAULT_RUNTIME=codex, no OPENAI_API_KEY	sonnet	gpt-5.5
SWE_DEFAULT_RUNTIME=opencode (alias)	sonnet	open_code base default

Everything else resolves exactly as before: no SWE_DEFAULT_RUNTIME (both the
OpenRouter-only auto-selection branch and the Claude branch),
SWE_DEFAULT_RUNTIME=claude_code, an invalid SWE_DEFAULT_RUNTIME, and any
configuration that sets a model env var.

⚠️ Deployment note. The concrete case worth calling out:
SWE_DEFAULT_RUNTIME=open_code with only an ANTHROPIC_API_KEY previously
got sonnet for planning, which worked because the opencode proxy could serve
it. Those deployments will now get
openrouter/deepseek/deepseek-v4-flash-0731, which requires an
OPENROUTER_API_KEY. This is intentional — it makes the planning models
consistent with the coding loop, which already resolved through
resolve_runtime_models() and was therefore already using the OpenRouter
default in the same environment. But it is a real change: such a deployment must
add an OPENROUTER_API_KEY, or pin planning explicitly via SWE_MODEL_HIGH /
SWE_DEFAULT_MODEL.

Validation Contract

Contract behavior	Test
OpenRouter-only env + runtime codex → auto default is NOT openrouter/-prefixed (codex-native)	test_default_planning_model_matrix[openrouter_only-codex], test_codex_default_is_never_openrouter_prefixed
OpenRouter-only env + runtime open_code → OpenRouter auto default preserved	test_default_planning_model_matrix[openrouter_only-open_code]
runtime claude_code → sonnet default preserved	test_default_planning_model_matrix[*-claude_code]
Pinning a non-Claude runtime never falls back to the sonnet Claude alias	test_non_claude_runtime_default_is_not_the_claude_alias
An explicit open_code runtime resolves open_code's own base default	test_default_planning_model_matrix[anthropic-open_code]
SWE_DEFAULT_MODEL / explicit arg wins in all cases	test_default_planning_model_matrix[swe_default_model-*], existing test_plan_explicit_args_override_env, test_plan_swe_default_model_overrides_openrouter_auto
Empty harness completion → error containing provider+model, distinct from schema-invalid message	TestCheckEmptyHarnessCompletion::*, test_run_product_manager_empty_completion_surfaces_provider_and_model
failure_type=schema has the empty-completion shape but does NOT raise it	TestCheckEmptyHarnessCompletion::test_schema_failure_is_noop (SDK enum, plain string, upper-case, and str(enum) spellings)
Every other failure_type still raises	TestCheckEmptyHarnessCompletion::test_non_schema_failure_types_still_raise
A result with no failure_type attribute keeps the previous behavior	TestCheckEmptyHarnessCompletion::test_result_without_failure_type_keeps_previous_behavior
A valid-but-falsy parsed object counts as a completion	TestCheckEmptyHarnessCompletion::test_falsy_but_present_parsed_output_is_noop

Also covered: runtime-alias normalization, the omitted-runtime env fallback, and
that non-empty-but-unparseable output is a no-op for the empty-completion check
(so the generic schema-invalid path still fires).

The open_code base-default expectation is read off _RUNTIME_BASE_MODELS
rather than duplicated as a literal — the literal had already gone stale against
main's default-model roll, so the assertion would have failed on merge while the
resolver was behaving correctly.

Test results

Both runs on Python 3.12 with AGENTFIELD_SERVER set, matching CI:

• Branch head: make check (full pytest suite + compileall) — 1168 passed,
  1 skipped.
• Merged with main: make check — 1181 passed, 1 skipped. This is what CI
  evaluates for a PR, and it is the run that catches the stale-literal drift.
• ruff check on the changed files reports the same findings as before the
  change (no new ones); the repo has no ruff gate in CI.
• Go CI job untouched — the diff contains no go/ files.

🤖 Generated with Claude Code