[kuun993]

Fixes #2.

What was wrong

Selecting a real dsh model on the pi engine failed every turn with pi RPC process exited unexpectedly. Two independent defects.

1. The api vocabulary was passed through untranslated. modelsDocument() wrote dsh's api string into pi's models.json verbatim. Codex and Kimi each translate that value into their own vocabulary first (CODEX_WIRE_APIS, KIMI_PROVIDER_TYPES); pi was the only engine that didn't. pi resolves api against its own registry of implementations, so a spelling outside its nine-entry Api union is refused outright.

Verified against the pinned @earendil-works/pi-coding-agent@0.84.3 by driving pi --mode rpc with three models.json variants (base URL deliberately example.invalid, so "refused at load" and "really tried to connect" are distinguishable):

api value	pi's answer
"anthropic"	stopReason: "error" → No API provider registered for api: anthropic
"anthropic-messages"	Connection error. + 3 auto-retries — accepted, really dialled
"totally-bogus-api" (control)	No API provider registered for api: totally-bogus-api — identical to case 1

The vocabulary belongs to whichever provider plugin owns that settings section. dsh's own llm-pi-ai routes happen to spell things pi's way, which is why verbatim pass-through looked right until a third-party provider spelled the same wire differently (anthropic).

2. The driver never read pi's own error. PiMessage didn't declare stopReason/errorMessage and nothing in src/ read them, so pi's precise sentence was discarded and the step ended through the RPC client's generic onExit message — which is why #2 had to be reverse-engineered from source. A run whose every turn failed but that then settled cleanly was also reported as a completed empty turn.

The fix

resolvePiApi judges the protocol (absent / supported / unsupported), and the models.json writer now takes a PiSupportedHandover whose api is a required pi spelling — so "what lands on disk is always something pi accepts" is a compile-time obligation instead of a runtime check. A known alias (anthropic → anthropic-messages) is translated; anything else fails the step with PI_UNSUPPORTED_API, naming provider, model and offending value.

It deliberately does not drop the handover the way a protocol-less one is dropped: dropping would leave pi quietly running its own default model while the user believes their dsh selection took effect — the silent degradation this driver exists not to produce.

pi's turn verdict is recorded per turn and reported after the loop (PI_TURN_ERROR), deliberately not thrown on the first errored turn_end, because pi retries by itself and a later turn can succeed. That premise is empirical — a retrying run emits one errored turn per attempt — and the new spec pins it.

Verification

• typecheck, build, and test:coverage all pass locally, per-file 100% maintained: 68 files / 1298 tests.
• All three compat lines pass on the same build: 015 → 1296 passed / 2 skipped, 017 and 020 → 1298 passed.
• End-to-end against the real pinned pi binary: the plugin wrote api: "anthropic-messages", pi accepted it and dialled the endpoint — 0 occurrences of No API provider registered.
• Docs updated in the same change (docs/engine-pi.md §2/§5/§8/§9, docs/driver-core.md, docs/architecture.md), per the repo's documentation rule.

Not covered

The handover path is verified against the real pi binary, but not against a real endpoint — anthropic-messages being accepted proves the protocol is right, not that the reporter's endpoint answers. Confirming that needs their modlens-zai-coding-cn setup.

Also note this repo's first CI run happens on this PR.