[建议 / Feature] Documented exit-code & JSON failure contract for headless --prompt turns

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复提议 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

其他 / 不确定 · Other / Not sure

涉及的 Agent 框架 · Agent framework

不涉及框架 · Not framework-specific

使用场景 · Use case

We run zcode --prompt headlessly ~150×/day (CI, schedulers, agent fleets). A headless caller currently has no documented contract for what an exit code means or what failure output looks like, so it cannot reliably distinguish "completed" from "failed" without scraping stderr.

What we verified on v0.16.5: config errors exit 1; a failed turn prints Error: Turn execution failed (traceId: ...) and also exits 1 (reproduced with an isolated HOME + invalid API key). --json exists ("Print machine-readable JSON where supported") but we found no documentation of what it guarantees on failure.

During a 7-day incident our schedulers burned ~400 dead turns partly because our tooling had no contract to code against (we also captured no exit codes ourselves — our bug, since fixed). A documented contract would have made the correct alarm trivial to build.

Related (not a duplicate): #29 asks for a scriptable single-turn mode to exist; this asks for that mode's failure semantics to be documented and machine-readable.

建议方案 · Proposal

For -p / headless mode:

1. Document the exit-code taxonomy: which codes map to config errors, auth expiry, and turn failure.
2. Guarantee --json failure output: top-level status, errorClass, and the existing traceId — so callers never parse human-readable stderr.

预期价值 · Expected value

Headless/CI callers can build correct failure alarms in minutes instead of reverse-engineering behavior; fewer silent multi-day outages for automated users.

你认为的优先级 · Your perceived priority

中 · Medium

你使用的 ZCode 版本 / 环境 · ZCode version / environment

zcode 0.16.5 / macOS 15.6 (Apple Silicon) / Z.AI Coding Plan (GLM)

补充材料 · Additional context

Repro sketch (safe, isolated): copy a working config to a scratch HOME, corrupt only the API key value, run HOME=<scratch> zcode -p "Say OK" → observe Error: Turn execution failed (traceId: ...) with exit code 1. Can provide full transcript + redacted logs if useful.

Start by reproducing the reported zcode -p behavior with an isolated HOME and invalid API key, then inspect the existing --json help or documentation referenced by the CLI. Document the agreed exit-code taxonomy and define the failure JSON fields only after maintainers confirm the contract; done means headless callers can distinguish success and failure without parsing stderr.