feat: 最小 headless 环境引导自检 — bootstrap 结构化键 + gate 终态告警 + 文档口径 (#55)

[tizerluo]

Closes #55

背景

0.16.9 官方 runtime 在最小 headless 环境（无完整 ~/.zcode 配置）下，ZCODE_MODEL / ZCODE_BASE_URL / ANTHROPIC_API_KEY 注入不被读取（bundle 无读取点；0.16.5 时代日志回溯同样如此——有完整配置的机器上是配置文件兜底掩盖了这一点），模型选择完全来自配置文件。本 PR 按 #55 三个待办 + 评论区「模型可观测性」交付，全部基于本机可复现的实测夹具。

夹具事实（官方 3.14.4 bundle + 空 HOME + 入口旁 provider/zcode-builtin.json 实测）

• --prompt 路径：exit 1、stdout 空、stderr 单行 Error: Model creation failed (traceId: …)（.deb 构建变体后缀 : Select a model before continuing）→ 稳定特征 Model creation failed
• builtin 文件缺失：stderr 无法定位 CLI ZCode Built-in Provider Config：<候选路径>
• app-server 路径：session/create 成功（settings.model.available: []）但 turn 静默停滞（≥100s 无事件无 stderr）→ ACP 路径无错误文本可匹配，空模型目录是唯一确定性本地信号

交付

① 方向决策：只读探测 + 指引（不写用户配置文件）——写 ~/.zcode 侵入性大、defaultModelSelection 在空注册表服务器的充分性未证实、enc:v1 凭证不可伪造。env 注入逻辑一行不动。

② 文档口径：README 新增「最小 headless 环境的模型引导」节（env 边界的诚实口径：不声称任何版本的 env 注入在最小环境有效；两条模型选择路径；builtin 文件前置；ACP 空目录行为），三处旧口径同步修订（env 覆盖示例边界注 / 复测「完整桌面配置机器」限定 / 版本表脚注）。agent-help 两处事实性错误文案（「必须用环境变量配置」）条件化。

③ 引导自检：shared/provider_error.py 新增 parse_bootstrap_error（两类特征 → kind），mcp-server 内嵌副本同步；_run_zcode_headless 在 provider 分类判 unknown 后查询（限流/配额/1308 优先级不变，混合文本测试钉死），命中时错误文本前置指引 + result 顶层无条件附 "bootstrap": {"kind": …}（三 tool，对齐 refusal 先例）。review-gate 消费该键走 refusal 同型终态（gave_up + 告警评论 + comment_failed 补发分支），评论文案区分「环境问题非代码问题」，<details> 里的宿主候选路径在渲染期替换为占位符（本地 state 保留原文）。

④ 模型可观测性最小诚实版：--print-injected-env 增加模型解析面——层 1 v2/config.json enabled provider / 层 2 v2/provider_config.json 的 defaultModelSelection + providerOrder 首位 / 固定免责行（runtime 不回报实际使用值）。只读，缺失/损坏容错。

ACP 侧：session/new 未传 model 且 create 快照模型目录为空时 stderr 告警（行为不变；实测该场景 turn 会静默停滞）。_resolve_session_model / session/new 的 settings 非 dict 形态防御补齐。

测试

560 → 591（+31）：混合夹具分类互斥（BG4b/c）、stderr_matches 扩展正向钉子（BG3b）、防误杀反例（BG3）、gate 终态/补发/脱敏端到端、副本对拍（PB 系列）、agent-help 哨兵防宿主耦合（C12m）、ACP settings 三态防御（C4m/C4n）。关键断言均做变异验证（删守卫/删扩展/删脱敏 → 对应测试红）。ruff 全绿。

范围外（另立 issue 如需要）

bridge 自动写配置文件（须 opt-in + 备份 + 空注册表单变量验证）；legacy cli/config.json 读取；--json 不含 model id 的上游问题。