@ckanner/flywheel 0.31.0 → 0.32.0

package/docs/reviews/2026-08-24-v0.18-review-fixplan.md

@@ -0,0 +1,265 @@
+# Flywheel 全量评审结论与修复规划（2026-08-24）
+
+> 状态：待人工对齐。本文档是 2026-08-24 全量评审的产出：外部来源核实、SKILL.md 规范符合性审查、
+> 十铁律×代码逐条裁决、全部问题清单（统一编号）与分阶段修复方案。
+> 评审方法：DESIGN.md v0.17 全文 + 全部 internal/ 源码精读 + 双子代理独立审计 +
+> `make quality-gate` 实跑（20 包 100% 覆盖率全绿）+ 外部链接逐条核实（web_search + 原文读取）。
+> 结论先行：**十铁律七条满分三条带注记成立，零条被违反；AGENTS.md 硬契约全部实证成立；
+> 无 P1 缺陷；系统架构足以支撑目标，剩余风险集中在三处未证伪的外部假设。**
+
+---
+
+## 1. 外部来源核实结论（附录 A 相关）
+
+### 1.1 已核实为真的来源
+
+| 来源 | 判定 | 要点 |
+|---|---|---|
+| Osmani《Loop Engineering》 | ✅ | 五构件 = Automations/Worktrees/Skills/Plugins/Sub-agents + 第六项外部 State 层；与 Flywheel 是类比映射 |
+| Anthropic《Effective Harnesses》 | ✅ | one-shotting / 过早完成 / 浅层验证三大失败模式逐字属实 |
+| Anthropic《Multi-agent research》 | ✅ | 委托契约要素与 4×/15× token 数据属实 |
+| Cursor《Scaling agents》 | ✅ | planner/worker/judge、扁平协调证伪、按角色选模型均有原文 |
+| Ralph（ghuntley） | ✅ | bash while + 新上下文成立；"文件系统状态"是归纳用语 |
+| **pi**（earendil-works/pi） | ✅ | `-p/--mode json/--no-session/--thinking max` 逐项核对 CLI Reference；JSONL 事件流 + usage 分项确认。仓库已从 badlogic/pi-mono 迁移 |
+| **kimi code** | ✅ | stream-json / resume / goal 退出码 0/3/6 / #1911（open）均属实 |
+
+### 1.2 本次新增应补入附录 A 的来源
+
+1. **Warp Agent Skills**：<https://docs.warp.dev/agents/capabilities/skills/> ——第三个实现 Agent Skills
+   标准的 harness（此前漏调研）。关键事实：
+   - 必填 frontmatter 只有 `name` + `description`；
+   - 参数不用 `arguments:` 字段，用正文 `$ARGUMENTS`/`$N` 占位符；
+   - 扫描目录推荐 `.agents/skills/`（项目级）与 `~/.agents/skills/`（全局）——**直接佐证 Flywheel 共享安装点的选型**。
+2. **agentskills.io 官方规范**：<https://agentskills.io/specification> ——字段权威定论：
+   `name`(必填,≤64,须与目录同名) / `description`(必填,≤1024) /
+   `license` / `compatibility`(≤500) / `metadata`(string→string map) / `allowed-tools`（可选）。
+   提供 `skills-ref validate` 校验器。
+3. **kimi code Skills 官方文档**：<https://moonshotai.github.io/kimi-code/en/customization/skills>
+4. **pi Skills 官方文档**：<https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md>
+
+### 1.3 由官方文档定案的事实（修正此前的判断）
+
+- **`whenToUse`/`arguments` 归属**：两者不在 agentskills.io 规范中，但 **kimi code 官方明确定义**
+  （whenToUse 还接受 when-to-use/when_to_use 变体；模型依据 `description` + `whenToUse`
+  决定自动调用）。AGENTS.md 称其为"kimi code 扩展、自动调用依赖"——**对 kimi 而言正确**，
+  但需补一句边界："非 agentskills.io 标准字段；其他 harness（Warp/Claude Code）不消费"。
+- **`${KIMI_SKILL_DIR}`**：kimi 官方变量（当前 skill 所在目录），SKILL.md 中的用法正确。
+- **共享安装点**：kimi（User 级扫 `~/.agents/skills/`，官方注"shared across tools"）、
+  pi（全局扫 `~/.agents/skills/`）、Warp（推荐目录即它）三方一致。install-skills 选型正确。
+- **调用语法**：`/skill:<name>` 是 **kimi code 的调用形态**（官方示例 `/skill:review-pr #1234`），
+  pi 也注册 `/skill:name` 命令；但 Warp 是 `/<name>`，Claude Code 经 Skill 工具加载。
+  README"调用形式为 /skill:<name>（Agent Skills 标准）"应改为"kimi code / pi 的调用形态"。
+- **kimi 目录型 SKILL.md 必填字段只有 name + description**（缺任一解析失败）；
+  type 默认 prompt；arguments 支持**字符串数组或空白分隔字符串**两种形态。
+
+---
+
+## 2. SKILL.md 全量规范符合性审查（10 个文件 × 3 套规范）
+
+### 2.1 字段矩阵结论
+
+| 字段 | agentskills.io | kimi code | pi | Warp | Flywheel 现状 | 判定 |
+|---|---|---|---|---|---|---|
+| name | 必填,≤64,=目录名 | 目录型必填 | 必填(放宽目录名匹配) | 必填 | 10 个全部合规（kebab-case、=目录名） | ✅ |
+| description | 必填,≤1024 | 目录型必填 | 必填,≤1024 | 必填 | 全部非空、含触发关键词（英文 Use when…） | ✅ |
+| metadata.version | 合法用法(map 自由键) | 未定义(忽略) | metadata 透传 | 未定义 | 全部 "1.0.0"，内部门禁强制 | ✅ |
+| compatibility | 可选,≤500 | 未定义 | 可选 | 未定义 | 全部 ≤500 字符（v0.17 已加引号修 YAML） | ✅ |
+| whenToUse | **不在规范** | **官方字段**,自动调用依据 | 未定义(忽略) | 未定义 | 全部非空中文 | ✅(kimi)/无害(其他) |
+| arguments | **不在规范** | 官方字段,但**仅支持字符串数组或空白串** | 未定义 | 不用(正文占位符) | **对象形态 `{name,description,required}`——没有任何 harness 文档支持** | ⚠️ T3 |
+| `${KIMI_SKILL_DIR}` | — | 官方变量 | — | — | 9 个按钮 skill 使用正确；锚文件回退链完整 | ✅ |
+
+### 2.2 逐文件内容审查发现
+
+全部 10 个文件的"只是按钮"纪律执行到位：无 loop 逻辑、参数校验 + CLI 调用 + 结果翻译三段式一致；
+flywheel-new 的问答纪律（意图问人/事实自查）、冻结点声明、git add+commit 硬规则齐全；
+intake/garden 的"候选不是任务""只产提案"人机分界清晰。发现的问题：
+
+- **T3｜`arguments` 对象形态无规范支撑**（10 个文件全中）。
+  kimi 只认字符串数组/空白串（`arguments: target mode`）；对象 `{name,…,required}`
+  大概率被静默忽略——而正文也确实没用 `$slug`/`$0` 占位符，等于声明了参数却从未接线
+  （kimi 行为兜底：无占位符时实参以 `\n\nARGUMENTS: <text>` 追加正文，功能不断但不优雅）。
+  **修复**：arguments 改字符串数组；exec/review/verify/intake 四个带可选参数的 skill
+  在正文命令示例中接入 `$1`/`$ARGUMENTS`。
+- **T4｜调用语法归属**（README/DESIGN §13）：见 §1.3 最后一条。
+- **T6｜flywheel-new 缺"验收命令试跑"硬规则**：生成器没被要求实际执行生成的 L1 命令，
+  契约质量完全依赖生成会话的水平（系统上限 = 契约质量的上游瓶颈）。
+  **修复**：SKILL.md 流程第 3 步加硬规则——每条 acceptance 命令提交前必须在目标仓库
+  实际执行一次，允许失败但必须把命令+退出码+输出摘要写进 spec 附表作证据；
+  无法执行的命令（环境缺失）必须显式标记 `unverified` 并提醒人审关注。
+- **可选 T7**：CI 增加 `skills-ref validate ./skills/*`（agentskills.io 官方校验器），
+  与现有 skillsembed 门禁互补（标准符合性 vs 内部约定）。
+
+---
+
+## 3. 十铁律 × 代码逐条裁决（摘要）
+
+| # | 铁律 | 裁决 | 关键证据 |
+|---|---|---|---|
+| 1 | 编排器不是 agent | ✅ | 全部决策点机械可查（run.go:585/circuitbreaker.go:136/errs.go:79）；判断外置 Plan/Review/Judge/inbox |
+| 2 | 状态落盘，交接走文件/git | ✅ | state.json(CAS)+retro+reports+metrics.jsonl；Plan 会话句柄入盘、冷启动协议闭环（steps.go:882-915） |
+| 3 | 单元=全新上下文 | ✅ | Execute/Review/Judge 每次 `pi --no-session` 新会话；Plan 长驻是 §4.1 明文例外且有机械冷启动协议 |
+| 4 | oracle 先行，LLM 在后 | ✅ | processPacket 阶段机 + `--only review` 双入口强制 l1PassTrue（run.go:1253-1256） |
+| 5 | 做判分离 | ⚠️ | 评审输入无 transcript/done-report 正文；异厂商组合成立。降级路径（非 git）自报清单带标签泄漏；diff 文本是 executor 可写面（注入残余风险，业界共识为 best-effort，见 §6） |
+| 6 | 契约显式字段化+版本 | ✅ | schema additionalProperties:false + LOAD 时 fail-fast + 跨字段规则；版本号三处齐备 |
+| 7 | 会话级模型隔离 | ✅ | 单 spawn 单模型；降级换模型发生在会话之间；Plan 会话钉死 model+channel 才 resume（#15） |
+| 8 | 分级+升级路径 | ✅ | routes 表 + hard 升级 K3 + 三级 escalation + spin 止损；最坏 bounded 到 inbox |
+| 9 | 成本可观测+熔断可配 | ⚠️ | 记录恒开✓ 三档✓；但 C1（CacheWrite 漏计价）实违本条的准确性；kimi Plan usage null 是明文豁免 |
+| 10 | 缓存一等指标 | ⚠️ | DeepSeek 侧稳定前置/易变尾部✓ 逐 provider 命中率✓；review prompt 中段时间戳违反字面纪律（影响≈0）；kimi 侧不可观（同豁免）；KIMI_NOW resume 刷新打折跨 resume 收益（A5③） |
+
+**AGENTS.md 硬契约实证**（全部成立）：state.json 写权收敛于 internal/state.Save
+（machine/cli-stop/modules 三入口，modules 带 pid 守卫防 mid-run 抬 revision）；
+九错误码与 §6 逐字一致；覆盖率门禁实跑全绿；ledger 单一信源成立（defectinjection
+应用层有一个洞 → C3）；skills 真 YAML 门禁存在（skillsembed_test.go:16-93）；
+输出契约 root.go 实现一致；SIGTERM kill switch 双入口注册。
+
+---
+
+## 4. 问题总清单（统一编号）
+
+> 编号规则：A=设计级（改设计/流程），C=代码缺陷级，T=文档/skill 级。
+> 每条给出：证据 → 影响 → 修复方案 → 验收标准。
+
+### 设计级
+
+**A1｜planStep 产出零校验；planner 可弱化验收且无留痕**（最高优先）
+- 证据：steps.go:955（成功判定仅 exit==0）；escalatePacket 仅 `PlanRevisions < 1` 限次；
+  DC2 只约束 verification-gap 必须"加强"。
+- 影响：executor 连败 → return-to-planner → planner 改弱 acceptance → L1 绿 → 单元通过，
+  全程无机械痕迹。注：这不是铁律 1 违反（计划质量归 Plan 是法律授权），缺的是**机械留痕**
+  把该环节拉回可监督范围。
+- 方案：plan 成功路径（常规 run.go:1011 reloadPackets 与 escalatePacket 两处）在 reload 前
+  对旧 PacketList 快照每 packet 的 acceptance 指纹（sha256(L1 commands+expect) 序列化），
+  reload 后 diff；acceptance 变化 → retro 行 + `state.budget.warnings` 告警 + Log
+  （不阻止——范围裁决权归 Plan，铁律 1；留痕供人审 status 时看见）。
+  纯函数 `diffAcceptanceSignatures(old, fresh)` 放 machine 包。
+- 验收：单测两分支（修订改弱/未动）各断言 retro 行与 warning；quality-gate 绿。
+  DESIGN §4.1 增补"已知风险"段落记载该风险与本缓解。
+
+**A2｜DESIGN §4.1 与实现的规划职责不符**
+- 证据：packets 全由 flywheel-new 一次性生成；planStep 遇无 packet milestone 直接报错（steps.go:897）。
+- 方案：§4.1 改写为两段式事实："初始规划 = flywheel-new 生成 + 人审冻结（§12）；
+  运行中 Plan Loop = 修订器/加强器（escalation 与 verification-gap 触发）"。
+- 验收：DESIGN 通读无"Plan Loop 签发 packet 序列"的运行期表述残留。
+
+**A3｜单 judge 与所引证据相抵触**
+- 证据：里程碑 Judge pass/fail 直接决定关闭（run.go:1055-1086）；2025 年研究：单 judge
+  受 position bias/self-preference/verbosity bias 系统性影响，单 judge 与 ground truth
+  一致率约 87.6%，bias-aware panel 达 98.1%（Verdict-Bench/Jury,
+  ijisae.org/index.php/IJISAE/article/view/8407；position bias 系统研究
+  aclanthology.org/2025.ijcnlp-long.18/；self-preference DBG
+  aclanthology.org/2025.emnlp-main.86/）。
+- 方案（分层落地）：
+  - **立即（低成本）**：强化裁决出口契约——ParseReviewVerdict 增加 score 非空与
+    reasons ≥1 条校验，缺失按 unparseable 走重试；BuildJudgePrompt/BuildReviewPrompt
+    要求 verdict.reasons 每条必须引用可复核证据（命令名+退出码 / 文件:行号）。
+  - **首跑后评估**：里程碑 Judge 双模型面板（K3 主判 + V4 Pro 异厂商复核，
+    分歧→inbox），config 开关 `judge.panel` 默认关；引 Jury 论文的 diversity+校准聚合。
+- 验收：prompts 单测覆盖新校验分支；DESIGN §4.3 已知风险段更新引用。
+
+**A4｜凭证卫生表述强于实际保证**
+- 证据：childenv.go:9-12 白名单含 HOME/XDG_*——gate 命令跑 executor 写的代码，
+  可达 ~/.pi/agent/auth.json、~/.kimi-code。
+- 定性：与 v0.10 信任模型一致，非 bug；但 §9 表述易被读成防恶意。
+- 方案：§9 加一段边界声明："凭证卫生 = 防事故性继承（白名单不含任何 API key）；
+  不防恶意进程读 HOME 下 auth store——那是容器化重评（§11.7）的触发条件之一"。
+- 验收：DESIGN §9 更新；无代码改动。
+
+**A5｜小项**
+- ① LastProgressAt 只写不读（§6"用于发现断链"半缺失）。
+  方案：status 子命令增加停滞判定（last-progress 距今 > watchdog.wall-timeout → 显式
+  "疑似停滞/断链"提示）；§6 措辞同步（cron 短进程模式下断链发现主通道是 pid 陈旧 + 进程不存在）。
+- ② kimi Plan token 不可观测：维持 v0.15 豁免，DESIGN 已记录，不动。
+- ③ KIMI_NOW resume 刷新（kimi #446/#498）打折长驻会话跨 resume 缓存：
+  §8-4 加一句事实注记即可。
+- ④ L2/L3 闸门失败直奔 inbox 无回 Plan 路径：实现替设计补的空白，回写 §4.4
+  （保守处理是有意选择：L2/L3 失败多为环境/契约级问题，重试烧钱无益）。
+
+### 代码级
+
+| ID | 级别 | 问题 | 证据 | 修复方案 | 验收 |
+|---|---|---|---|---|---|
+| C1 | P2 | 兜底成本估算漏 CacheWrite（铁律 9 准确性） | machine/context.go:141 EstimateCostUSD 少传 CacheWrite（metrics 层本就支持按 input 价计费） | 补传 `CacheWrite: usage.CacheWrite`；同步更新对应单测期望值 | 单测：无 cost 流 + CacheWrite>0 → 估算含缓存写入计价；coverage 100% 保持 |
+| C2 | P2 | 评审者看不到 untracked 新文件内容（违反 §4.3"真实 git diff"承诺；greenfield 首批任务正中靶心） | verify.go:295 GetDiffText 仅 `git diff base -- .` | 对 changed-but-untracked 且未被 exclude 的文件逐个追加 new-file 内容段（仿 `diff --git`头 + 全文），受 DiffTextCap 总量约束；二进制文件以 `[binary]` 占位 | verify 单测：worktree 新建文件 → GetDiffText 含内容；exclude 生效；超 cap 截断标记 |
+| C3 | P2 | 缺陷注入账本守卫精确相等可绕过（`reports/x` ≠ `reports/`） | defectinjection.go:177-186 | 改为复用 ledger.IsLedgerTaskPath 语义（传入 taskDir 相对路径判断），消灭两套匹配逻辑 | defectinjection 单测：patch 触 reports/x.json → uninjectable；coverage 保持 |
+| C4 | P3 | execute 失败路径空转签名退化为自报/空集 | run.go:608 | execute 失败时若 worktree 存在，编排器亲自 GetChangedFiles(uCwd, baseRef) 作权威集；不可得再落自报兜底 | machine 单测：连续两次同错误码失败 + 权威 diff 相似 → spin |
+| C5 | P3 | kimi resume_hint 格式漂移静默退化为每轮冷启动 | drivers/kimi.go:64 | planStep 冷启动分支已有日志；补一处：sessionID=="" 且 stored 存在时 Log"未能从上次流中捕获 session id" | drivers 单测断言日志回调收到提示 |
+| C6 | P3 | pi 错误事件只保留最后一条 | drivers/pi.go:92 | ErrorMessage 改为追加（`; ` join，去重），或保留首条+计数 | drivers 单测：双错误事件 → 两条都在 |
+| C7 | P3 | jitter 显式配 0 不可达 | errs.go:174 | **决定：不修**（Node destructuring 语义忠实移植；确定性测试经 Random 注入已可达）。补注释说明即可 | 注释合并进既有测试 |
+| C8 | P3 | done-report 多余键放行 | donereport.Parse | 校验键集合恰好等于 done-report-format 声明的 4 键（多余键列入 Errors） | donereport 单测：多一键 → !OK |
+| C9 | P3 | Save CAS 读-写 TOCTOU 微窗口 | state.go:221 | **决定：接受不修**。pid 单实例下唯一并发写者是人手编辑；窗口毫秒级、后果轻。注释已说明 CAS 目的 | — |
+| C10 | P3 | ForeignDirtyFiles 不处理 porcelain rename（`R old -> new`）与引号路径 | verify.go:173-188 | 解析 porcelain XY 格式：rename 条目拆两路径；引号路径去引号+反转义（或保守：整行跳过 rename 态只报目标路径） | verify 单测构造 rename/status 输出 |
+| C11 | P4 | 手工把 milestone.gate 写成非对象时 judge 结论落入孤立 map | steps.go:808-812（coverage_steps_test.go:532 自首） | judgeStep 内 gmap 类型断言失败时记 warning 并跳过 judge 结论写入（或拒绝字符串 gate） | machine 单测一例 |
+
+### 文档 / skill 级
+
+| ID | 级别 | 问题 | 修复方案 |
+|---|---|---|---|
+| T1 | P3 | drills/*.md 可重复入口指向已删除的 Node 测试（node --test tests/drill-*.test.js、core/*.js 路径） | 入口改为 Go 测试真名（`go test ./internal/drivers -run …`、`go test ./internal/defectinjection …`）；core/*.js 引用改 internal 包路径 |
+| T2 | P3 | frontmatter 归属表述不精确（AGENTS.md、skillsembed_test.go:16-18,60 注释） | 按 §1.3 定案改写：非 agentskills.io 标准字段 + kimi code 官方定义（附文档 URL）+ 自动调用依据 + 其他 harness 不消费 |
+| T3 | P3 | SKILL.md arguments 对象形态无规范支撑且正文无占位符 | 见 §2.2 |
+| T4 | P3 | `/skill:<name>` 被表述为"Agent Skills 标准" | README/DESIGN §13 改注："kimi code 与 pi 的调用形态；Warp 为 /<name>；Claude Code 经 Skill 工具" |
+| T5 | P3 | 附录 A 缺 Warp / agentskills.io / kimi·pi skills 官方文档四个来源 | 按 §1.2 增补（Warp 归 Harness 调研组，其余归方法与规范组） |
+| T6 | P2 | flywheel-new 缺"验收命令提交前试跑"硬规则（契约质量上游瓶颈） | 见 §2.2 |
+| T7 | 可选 | CI 增加 `skills-ref validate`（agentskills.io 官方校验器） | make quality-gate 追加一步或 CI workflow 追加 step |
+
+### 明确不修清单（含理由）
+
+- ARG_MAX/prompt 作为 argv 上限风险：DiffTextCap 100KB + CacheScopeCap 50KB + packet 体，
+  总 prompt ~200KB 量级 << macOS ~1MB argv 限制。不加管道化传输。
+- C7 jitter、C9 TOCTOU：见上表。
+- kimi Plan usage 不可观：v0.15 用户裁决豁免。
+
+---
+
+## 5. 分阶段修复计划
+
+> 每阶段以 `make quality-gate` 全绿收口；不 commit（等用户批准）。
+
+### Phase 0｜文档与规范订正（无代码风险，~半天）
+T1、T2、T4、T5 + A2、A4、A5③④ 的 DESIGN 改写。
+验收：文档通读一致性；无代码行为变化（go build/test 不动仍绿）。
+
+### Phase 1｜P2 代码三连修（~半天-1 天）
+C1 → C2 → C3，各自带回归测试。
+验收：新增单测全绿；quality-gate 全绿；drill 手工冒烟（临时 repo 建 untracked 文件跑
+`--only review` 看 prompt 含新文件内容）。
+
+### Phase 2｜设计补强与小修（1-2 天）
+A1 机械留痕（含 DESIGN §4.1 已知风险段）→ A3 立即版（verdict 出口契约强化）→
+A5① status 停滞提示 → T3/T6 skill 修订 → C4/C5/C6/C8/C10/C11 小修批量。
+验收：各项对应单测；skillsembed 门禁对新 frontmatter 仍绿；
+`flywheel skills list/read` 冒烟。
+
+### Phase 3｜首跑准备（与 Phase 2 可并行推进）
+1. OpenCode Go ToS 决策记录（无人值守条款灰区签字画押；v0.19 起无降级链——封号即中断，需人工改 `flywheel.config.json` 渠道绑定后重跑）。
+2. 真实 403 报文实测预案：拿到超额账号当天按 drills/403-fallback.md 方法打一轮，
+   模式表集中在 errs.go patterns 一处可即调。
+3. mimir 任务生成时执行 T6 新规（每条 L1 命令试跑留证）。
+4. 缺陷注入 patch/test-cmd 配置模板随首批 packet 一起产出。
+5. 全部就绪后 `/skill:flywheel-run docs/mimir-s4-0` 首跑，按 HANDOFF §下一步观察。
+
+---
+
+## 6. 业界最佳实践对照（本次修复方案的依据）
+
+| 议题 | 业界参照 | Flywheel 现状与采纳 |
+|---|---|---|
+| LLM judge 可靠性 | Verdict-Bench/Jury（单 judge 一致率 87.6% → bias-aware panel 98.1%）；position bias 系统研究（IJCNLP 2025）；self-preference DBG（EMNLP 2025） | 已做对：异厂商 judge + rubric 显式打分 + L1 先行；采纳：A3 出口契约强化 + 双模型面板（v0.18 完整版） |
+| 评审者面对不可信 diff | OWASP LLM01 / Prompt Injection Prevention Cheat Sheet（防御纵深、指令数据分离、最小权限）；Anthropic security-review 官方自述 "not hardened against prompt injection, trusted PRs only"；GitInject, arXiv:2606.09935（AI CI 流水线注入实证） | 铁律 4（oracle 先行）正是 OWASP 分层+最小权限的正确实例；残余风险按业界口径定性为 best-effort 写进 DESIGN §4.3；不引入重型注入分类器（成本不成比例） |
+| Planner 监督 | Cursor planner/judge 分相；Anthropic multi-agent 委托契约 | A1 留痕 = 把"委托契约变更"纳入可审计面，方向与 multi-agent observability 结论一致 |
+| Skill 生态兼容性 | agentskills.io 规范 + kimi code / pi / Warp 三家官方文档交叉验证 | 共享安装点选型获三家共同佐证；T3/T4 修正后完全兼容 |
+| 变异测试演进路径 | DESIGN §4.3 已预留 Stryker 方向 | 维持：缺陷注入抽检是变异测试的确定性子集，先实战再演进 |
+
+---
+
+## 7. 裁决结果（2026-08-24，用户已裁决）
+
+| # | 待裁决项 | 结果 |
+|---|---|---|
+| 1 | Phase 顺序 | ✅ 按计划（文档 → P2 → 补强 → 首跑准备） |
+| 2 | A3 双 judge 面板 | ✅ **现在就做完整版**（config `judge-panel`：K3 主判 + V4 Pro 复核；一致按共识、分歧 → inbox），出口契约强化一并落地 |
+| 3 | T7 skills-ref validate | 以等价 Go 实现落入门禁（skillsembed 扩展 agentskills.io 标准约束），不引入外部工具依赖 |
+| 4 | C7/C9"明确不修" | ❌ 推翻——**两者都修**：C7 jitter `*float64` 指针化（nil=默认 0.1，显式 0=无 jitter）；C9 CAS 加 flock 文件锁闭 TOCTOU |
+| 5 | 文档入库 | ✅ 本文档随修复分支提交 |
+
+交付方式：全部修完后出 PR 供人审，**不首跑**。

package/docs/reviews/2026-09-12-pr4-pr5-review.md

@@ -0,0 +1,70 @@
+# PR #4 / PR #5 评审台账（2026-09-10 ~ 09-12）
+
+> 状态：已全部修复并合并（PR #4 = `13e7970`，PR #5 = `9c47f5f`）。
+> 本台账按 v0.18 先例（`2026-08-24-v0.18-review-fixplan.md`）落盘两轮评审的完整
+> 发现→修复映射与实证证据，避免评审结论只存在于会话记忆。
+
+## 第一轮：PR #4 全量评审（2026-09-10）
+
+**对象**：`feat/execute-glm-5.3-flash` 对 main 的 7 个原始 commit（omp/zcode 双
+harness、智谱渠道迁移、v0.20 桌面可见性、v0.21 文档同步）。
+
+### P1（阻塞合并，均已修）
+
+| # | 发现 | 证据 | 修复 |
+|---|---|---|---|
+| 1 | InvokeHarness omp 分支丢 Thinking——每次编排器 omp spawn 发 `--thinking ""`，omp 不报错静默按缺省档跑，架空 §7 统一 max 档与 §10-2 fail-loud | 临时探针测试实录 argv `--thinking []`；本机 omp `--help` 枚举确认空值非法 | 分支照抄 pi（binding 值 + max 兜底）；dispatch 测试锁 argv（e4277e9） |
+| 2 | CI 红（Linux）：zcode 注册测试断言 darwin-only 行为无平台守卫；verify 的 `NotZero(DurationMS)` 在快速 runner 上亚毫秒取整为 0 | CI run 33159549827 三处 FAIL | `zcodeDesktopGOOS` 注入缝 + forceDarwin（同时修复 Linux 覆盖率不可达）；计时改 `sleep 0.05`（e4277e9） |
+
+### P2（均已修）
+
+| # | 发现 | 修复 |
+|---|---|---|
+| 3 | RunOmp 不传 `parsed.Settled`（pi 传）——三 driver Result 语义不一致的潜伏缺陷 | 补齐 + 陈旧头注释纠正 + agent_end 回归断言（e4277e9） |
+| 4 | zcode usage 从 total 派生 input 而不用上报值（探针 fixture 两算不符：550 vs 500），且漏 TotalTokens | 上报值权威、派生仅缺报 fallback 且 clamp ≥0（e4277e9） |
+
+### P3（均已修或如实化）
+
+模板 drivers 值歧义（→ real 二值语义）、zcode 可选臂不可达（→ 模板注记 + DESIGN
+如实化）、僵尸进程（→ `go cmd.Wait()`）、§7 zcode thinking 声明与实现漂移（→ 如
+实化）、DESIGN 现状级残留三处（→ 历史参照标注/划掉/实证遗留补录）。
+
+### 自查新增发现（修复中抓到）
+
+- `TestInvokeHarnessDispatchesZcode` 无隔离闸，在 macOS 开发机**真实拉起
+  ZCode.app**（恰为 opener 覆盖率的意外来源）→ disableDesktop + 专用假二进制测试。
+- **watchdog `idleTimer` 裸写数据竞争**（预存，Go 迁移遗留；stash 验证非本轮引入）
+  → 持锁赋值，全仓 `-race` 清零（5b67c8b 单独成 commit 便于追溯）。
+
+### 验证
+
+macOS 门禁 100% 逐函数覆盖；Linux 容器（golang:1.27 非 root）全量绿；`-race` 全仓
+零告警；CI 加 darwin+ubuntu 双矩阵（c670d13）。
+
+## 第二轮：PR #4/#5 合并前终审（2026-09-12）
+
+**对象**：两 PR 完整 diff + 堆叠关系。
+
+| 级别 | 发现 | 修复（039a135） |
+|---|---|---|
+| P2 | RunCodex 未固定沙箱/审批——继承用户全局 `~/.codex/config.toml`；默认配置机器上 headless exec 挂审批等待（编排器行为不得依赖用户环境状态） | 显式 `-s danger-full-access -c approval_policy=never`（v0.10 本机直跑信任模型）+ args 断言 |
+| P3 | `FLY_ZCODE_BIN` 一个 env 双语义（app-server launcher + 桌面注册二进制） | 拆分 `FLY_ZCODE_SERVER_BIN` / `FLY_ZCODE_BIN`（v0.20 原义保留） |
+| P3 | zcode `mode:"yolo"` 传入 create 但初始 projection 显示 build | 如实化进 DESIGN §10-5/6 首跑清单（不修，待首跑验证） |
+
+核查通过项：prompts 对 harness 零耦合；machine/cli 无硬编码 harness 名；pricing
+前缀剥离正确；env-key null 三渠道守卫语义一致；watchdog 钩子锁纪律 race 干净；
+schema 改动最小化。
+
+### v0.22 实施期 live 实证（评审依赖的证据）
+
+- zcode app-server 协议逆向：NDJSON 信封、`session/create` 按会话 model+
+  thoughtLevel（GLM [low,high,max]、5.3 默认 max）、流式事件、`session/read` 拉终态
+  （text/usage/reasoning）。开发中抓掉三个协议 bug：字符串事件 id 打破
+  json.Number 解码、应答载荷在 `result` 字段、`turn.failed` 嵌套错误。
+- 真实 zcode app-server live 冒烟：`Settled=true, Text="ok"`，8.2s，usage 全套。
+- GPT-6-Astra live 冒烟（codex 0.151→0.154 升级后）："ok"，cached 12160。
+- zcode 一次性模式实测局限（驱动 RPC 化的依据）：无 `--model`（Unknown option）、
+  stdout 全程静默（51s 任务第 50.7s 才输出）→ idle 看门狗会误杀长任务。
+- 桌面可见性：zcode `--open-workspace` 注册导入复验有效；Codex exec 线程原生进
+  `~/.codex/state_5.sqlite` threads 表 + `open -b com.openai.codex <dir>` 项目注册
+  验证（侧边栏即时呈现待 app 重启复核——遗留项）。

package/docs/reviews/README.md

@@ -0,0 +1,12 @@
+# Historical reviews
+
+[Documentation](../README.md) · [中文文档](../README.zh-CN.md)
+
+Findings describe the source reviewed at the time. They are not a current
+open-issues list; consult the maintained design and subsequent validation
+records before applying an old recommendation.
+
+| Date | Review |
+| --- | --- |
+| 2026-09-12 | [PR #4 / #5 review](2026-09-12-pr4-pr5-review.md) |
+| 2026-08-24 | [v0.18 review and repair plan](2026-08-24-v0.18-review-fixplan.md) |

package/docs/validation/2026-11-01-npm-installation.md

@@ -0,0 +1,105 @@
+# npm 安装与发行：验证记录
+
+日期：2026-11-01（America/New_York）。实施基线为 `39638bd96e6fcb6cc681bc7c1f90b7b082620936`，分支为 `feat/npm-agent-installer`，六包目标版本为 `0.27.0`。本文记录提交前的实际本地验证；PR、双平台 CI、合并和 npm 发布结果分别以 GitHub Checks／合并记录及 npm registry 为准。源码合并不等于已经发布。
+
+范围见 [N01–N07 计划](../plans/2026-11-01-npm-installation.md)，用户入口见 [npm 安装与首任务教程](../zh-CN/getting-started.md)。前轮 [DSH 集成](2026-11-01-results.md) 和 [profiles／预检](2026-11-01-profiles-preflight.md) 的记录继续保留。
+
+## 1. 实际执行结果
+
+本地环境为 Linux amd64、Go 1.27.3、Node.js 24.22.1。测试使用真实 npm、Git、Go／Node 子进程、文件系统和本地 HTTP registry；DSH 注册与模型 SDK 使用明确的 fixture。没有调用付费模型，也没有操作用户 Mac profile。
+
+| 检查 | 结果 | 证据 |
+|---|---|---|
+| `make quality-gate` | PASS：vet、gofmt、全部 Go 测试 | [输出](evidence/npm-quality-gate.txt) |
+| 逐函数 Go 覆盖率 | **419 个函数全部 100%；6,219 个 statement，未覆盖 0** | [逐函数输出](evidence/npm-function-coverage.txt) |
+| 七个核心包 `go test -race` | PASS：machine、verify、watchdog、drivers、cli、modules、diagnostic | [输出](evidence/npm-race.txt) |
+| `npm test` | **52/52**：runtime、installer、release | [输出](evidence/npm-contract-tests.txt) |
+| 六包构建 | PASS：四个平台原生包、DSH 插件和入口包，实际包内 manifest 与 SHA-512 校验 | [输出](evidence/npm-build.txt) |
+| `npm run test:install` | **6/6**：同一批实际候选包从隔离 npm registry 安装后执行 | [输出](evidence/npm-install-tests.txt) |
+| DSH 插件 `npm run check` | **38/38**，含 React DOM、控制协议与进程生命周期 | [输出](evidence/npm-dsh-plugin-tests.txt) |
+| Go → Node worker → SDK 桥接 | PASS，fake SDK，不发送模型任务 | [输出](evidence/npm-dsh-bridge.txt) |
+
+本地执行身份为 root，chmod 故障注入需要移除 DAC 绕过能力，所以 Go 门禁及 race 使用 `setpriv --bounding-set=-dac_override,-dac_read_search --inh-caps=-all --ambient-caps=-all`；没有删去失败断言、放宽覆盖率或将真实进程测试改成 mock。全局配置新增的 16 并发首次创建用例也单独通过 race 检查。
+
+100% 指项目既定的 Go **statement coverage**，且逐函数检查；它不代表所有分支、JavaScript 代码、真实账号或模型质量均已覆盖。此次 npm 门禁补足了此前只测源码／本地构建、没有完整验证安装后调用链的缺口。
+
+## 2. 一条命令安装实际验证了什么
+
+主命令为 `npx -y @ckanner/flywheel@latest install`。集成测试通过真实 `npm exec --package @ckanner/flywheel@0.27.0` 获取候选，再由安装器执行精确同版本全局安装；不是直接运行 checkout 中的安装脚本。测试目录包含空格和字面 `$()`，HOME、prefix、cache、项目目录独立。
+
+- npm 解析同版原生平台包与 DSH worker；安装后的 `flywheel version`、全局 worker bin、公开 worker export 和默认 worker 定位有效。
+- 10 个内嵌 skills 安装到 Agent 目录；全局初始配置、8 个阶段绑定及模板可读取。
+- 包内自带 `docs/examples/create-first-task.sh`，无需 clone 即可创建教程任务，并验证 packet 与未启动状态。
+- 正式 DSH CLI 的 `plugin --profile desktop add/list` 参数、精确版本和失败返回已通过 fixture 核对；未把这个 fixture 写成真实桌面注册证据。
+- 安装生成的稳定 launcher 和 receipt 可被安装后的插件解析；显式自定义 binary 优先，损坏的记录／不匹配的 launcher 不会静默回落。
+- 重复安装保留用户配置；DSH 注册失败保留可查询的部分结果并可重试；`--no-dsh` 明确跳过注册；用户修改过的 skill 完整保留，安装不能假报成功。
+- 安装后的 npm shim 收到 TERM，将取消传入真实 Go watchdog；等待其受管命令写入清理标记并确认退出。正常文本或迟到 exit 0 不能覆盖取消。
+
+安装成功 `ok:true` 与任务就绪 `ready:true` 分开。测试故意令 Kimi 不可用以验证 `ok:true, ready:false`；不把缺少 harness 或账号信息隐藏为安装成功后的可运行保证。安装不替换既有 DSH、Kimi／Codex harness，也不代替登录。
+
+## 3. Review 修复与保留的边界
+
+本轮实现与独立只读 review 修复了这些具体问题，并保留对应回归：
+
+1. npm wrapper 同步等待时无法可靠转发取消；改为异步子进程，等待 Go 的清理结果，不另起一套模型生命周期。
+2. 安装命令 leader 退出后仍可能有后代运行；保留进程组探测、TERM／KILL 和有界收尾，超时、取消或未确认清理不能报告成功。
+3. 单凭 managed marker 无法判断 skill 是否被用户修改；使用包含路径、类型、mode、大小、hash 的完整快照，升级前后复核，失败回滚或保留备份，冲突不覆盖。该操作不宣称十个目录组成跨目录事务或断电原子性。
+4. 首次配置检查与写入之间可能覆盖新出现的用户文件；完整写入同目录 0600 临时文件，再用 no-replace hard link 发布，已有文件或悬空链接完整保留。
+5. `npm view` 成功但缺少 integrity 不能证明版本不存在；只有结构化 E404 能进入首次发布路径，空／null integrity 拒绝，缺少 latest tag 单独处理。
+6. npm 的 `130/143` 等异常退出码不能因 registry 已接受字节而当作成功；取消后停止发行，不继续后续包。
+7. 安装完成、异步释放锁期间收到 SIGTERM 时，最终报告不能仍为 `ok:true`；统一将取消设为失败，同时保留已有清理错误。真实 installer 子进程的 unlock 窗口回归覆盖正常释放与释放失败。
+
+最终全套 npm 回归也暴露了测试 fixture 的 PID 文件创建窗口：空文件被 `Number("")` 读成 0，`kill(0, 0)` 查询测试自己的进程组，从而误报 worker 存活。受控实验确认该场景真实 worker 已清理。现统一等待完整正整数 PID、原子发布 fixture PID，并预置空文件覆盖窗口；保留真实 PID 退出断言，不通过放宽存活要求消除失败。修复后完整 `npm test` 52/52 通过。
+
+README、完整安装教程、首任务使用方法、插件 README／PROTOCOL、设计、AGENTS、CHANGELOG 和全部 10 个 skills 已同步。文档经过内部链接、shell 语法和 JSON 示例校验；skills 仍只负责输入校验、CLI 调用和结果解释。
+
+## 4. 发行验收链路
+
+普通 CI 构建一次六包候选，Ubuntu／macOS 下载同一 artifact 后安装验证。正式发行要求精确 tag 指向 clean HEAD，构建记录源 commit／tree／快照与实际 tarball SHA-512；验证任务通过后才进入发布。
+
+六包先发布到候选 dist-tag，已有版本必须与验证过的字节完全一致。公开 npm registry 的精确版本安装测试通过后，按依赖在先、入口包在后的顺序移动 latest，并再次验证六包版本和标签。npm 不支持六包 dist-tag 原子事务，因此失败可以按已确认的状态重试，但不承诺多包瞬时切换，也不允许回退更新的 latest。
+
+本地 dirty 开发候选仅用于测试，发布器拒绝直接发布。GitHub 发布 workflow 会从已提交的精确 tag 重建并重新验证，本文本地输出不能冒充该远端候选的通过证据。
+
+## 5. Codex Pro 最新复核
+
+截至 **2026-11-02 01:57:41 UTC**，GitHub `main`、独立 Git 拉取及 npm `latest` 仍对应 [`21fd7acccf1f5989b14fecdc1957559eea6914f8`](https://github.com/ckanner/dsh-subagent-codex-pro/commit/21fd7acccf1f5989b14fecdc1957559eea6914f8)／[`0.7.0`](https://registry.npmjs.org/dsh-subagent-codex-pro/0.7.0)。此次重新执行 typecheck 与测试，**106 pass、6 skip、0 fail**；跳过项含真实模型与本机缺少 Codex 的 preflight，不能算作 live 成功。
+
+[本轮离线探针](evidence/codex-pro-070-probes.txt)仍复现有效配置回执缺失可接受、坏 usage 通知后仍标 complete、默认 full access、公共 run 子路径未导出。完整公开收据、权限和进程所有权的接入要求见 [adapter 交接文档](../archive/codex-pro-adapter-handoff.md)。Flywheel 保留独立 `codex exec` 通路，没有把 DSH LLM provider 标签当成 external-subagent 接入。
+
+## 6. 尚需实际设备／账号证据
+
+用户 Mac 的 DSH 桌面插件加载与渲染、GUI PATH、Seatbelt、既有订阅授权、真实 Flash／GPT／Kimi／Codex 响应以及真实任务停止／恢复，仍需在对应环境验收。macOS CI 和本地 fixture 不替代这些结果。本轮没有模型质量、价格或吞吐量测量，不声称新的性能排名或成本节省比例。
+
+## 7. PR #15 合并后的启动登记竞态修复
+
+记录日期：2026-11-02 UTC。本节是后续修复的独立记录，上面第 1 节的测试数量与输出仍属于 PR #15 的安装实现，不重新归因于本次改动。
+
+### 触发证据
+
+[PR #15](https://github.com/ckanner/flywheel/pull/15) 的 [CI 41376341709](https://github.com/ckanner/flywheel/actions/runs/41376341709) 在 Ubuntu／macOS 全部通过，随后合并到 `4985f1bfddf5d99bd87aab9ff5c5e28bf5f0db4a`，tree 为 `aa0330c1d5f23f653c6dc4bec60cd5a4134d84d6`。
+
+该合并提交的 [CI 41376926465](https://github.com/ckanner/flywheel/actions/runs/41376926465) 中，macOS 全部通过；Ubuntu 的 Go quality gate、插件、跨进程桥接、npm 单测和真实 npm 安装均通过，但 [race 步骤](https://github.com/ckanner/flywheel/actions/runs/41376926465/job/125059462912) 的 `TestGateKillSwitchStopsDescendantsAndRemainingCommands` 在 **3.01 秒**报告 `cancelled gate did not reach quiescence`。之后的原生构建与 artifact 步骤被跳过，不能把这次 postmerge CI 写成全绿。
+
+### 根因与最小修复
+
+原 `watchdog.Run` 在 `cmd.Start()` 返回后才把 child 加入 registry。真实子进程可以更早开始执行、安装 TERM trap 并输出 ready；此时 `KillActiveChildren` 若先取得快照，就可能漏掉这个已经运行、尚未登记的子进程。
+
+新增回归用真实 shell 和可替换的 Start 调用，在“子进程已经运行、Start 包装函数尚未返回”的边界设置屏障，再执行一次 kill snapshot。旧顺序在受控复现中确定性失败，输出与 3.01 秒超时见[修复前日志](evidence/watchdog-startup-before.txt)。这不是通过延长等待或反复重跑消除的失败。
+
+修复由 `startRegistered` 使用同一个 `regMu` 临界区完成真实 Start、PID 设置和 registry 发布；kill 回调在进入临界区前准备好，成功与失败均通过 `defer` 释放锁。快照因此只能在启动前取得，或等待这次启动与登记完成。`KillActiveChildren` 仍在释放 registry 锁后发送信号和等待；之后新启动的调用不归属于旧快照。
+
+正常 machine SIGTERM 路径会先取消 run context，已有额外兜底。本次修复补足的是独立 `KillActiveChildren` 对已启动进程的快照契约，不代表用户每次正常停止都必然遗留进程。
+
+生产改动仅在 `internal/watchdog/watchdog.go`，新增 `internal/watchdog/startup_test.go` 验证真实启动窗口及 Start 失败后的解锁。原 `internal/verify/reliability_test.go`、原 3 秒等待期限和生命周期断言完全未改；独立 review 还检查了锁序、kill 回调发布以及测试屏障的清理顺序。
+
+### 本次修复验证
+
+| 检查 | 结果 | 证据 |
+|---|---|---|
+| 旧顺序的确定性复现 | FAIL：kill snapshot 漏掉已运行但尚未登记的子进程，3.01 秒触发等待失败 | [修复前](evidence/watchdog-startup-before.txt) |
+| 定向 race 回归 | PASS：启动窗口、Start 失败解锁、later-call 所有权与原 CI 失败用例 | [修复后](evidence/watchdog-startup-after.txt) |
+| 最终 `make quality-gate` | PASS：vet、gofmt、完整 Go 测试及既定逐函数 **100% statement coverage** | [完整门禁](evidence/watchdog-startup-quality-gate.txt) |
+| 最终七包 `go test -race` | PASS：machine、verify、watchdog、drivers、cli、modules、diagnostic | [race 输出](evidence/watchdog-startup-race.txt) |
+
+最终两项验证使用与前述本地门禁相同的 Go 工具链和 DAC 限制方式。此处仅记录本地修复验证；本修复 PR 的远端 CI、合并和后续 npm 发布必须另看实际 GitHub／registry 结果。没有新模型调用或用户 Mac 验收。

package/docs/validation/2026-11-01-profiles-preflight.md

@@ -0,0 +1,67 @@
+# 模型 profiles 与安装预检：验证记录
+
+日期：2026-11-01。基线：已合并的 `1c515ca0c694047d1f6c7d7c3d52853cc9bf9c2d`，实施分支 `feat/model-profiles-and-preflight`。本文保存本轮提交前的本地验收证据；远端双平台 CI 和合并结果以该 PR 的 Checks／合并记录为准，不由本地结果推断。源码合并不等于 npm 发布。
+
+设计见 [v0.26](../design.md)，范围见 [P01–P05 计划](../plans/2026-11-01-model-profiles-preflight.md)，使用见[配置指南](../zh-CN/configuration.md)与[Mac 安装教程](../zh-CN/getting-started.md)。前轮 DSH 集成与持久化行为的历史记录保留在[原验证记录](2026-11-01-results.md)。
+
+## 1. 最终本地门禁
+
+运行环境为 Linux amd64、Go 1.27.3、Node.js 24.22.1。所有检查使用本地 Git、真实进程、DOM 或模拟协议，不调用付费模型；没有修改外部插件仓库或用户 Mac。
+
+| 检查 | 结果 | 证据 |
+|---|---|---|
+| `make quality-gate` | PASS：vet、gofmt、全部 Go 测试 | [完整输出](evidence/profiles-quality-gate.txt) |
+| 逐函数覆盖门禁 | **410 个函数全部 100%；6,036 个 statement，未覆盖 0** | [逐函数输出](evidence/profiles-function-coverage.txt) |
+| 核心七包 `go test -race` | PASS：machine、verify、watchdog、drivers、cli、modules、diagnostic | [输出](evidence/profiles-race.txt) |
+| DSH 插件 `npm run check` | PASS：**35/35**，含真实 React DOM 与进程取消回归 | [输出](evidence/profiles-dsh-plugin-tests.txt) |
+| Go → Node worker → fake SDK | PASS：provider 独立、doctor 权限／目录／坏帧／关闭边界 | [输出](evidence/profiles-dsh-bridge.txt) |
+| 真实 Node control → 新 Go 二进制 | PASS：4 场景，符号链接／空格／特殊字面字符路径与诊断失败 | [机器记录](evidence/profiles-control-smoke.json) |
+| skills | 内嵌 YAML／字段约束、模板输出和 CLI 集成测试通过 | 已纳入 Go 门禁 |
+
+CLI 新增真实子进程信号测试：config inspect、doctor、control config、control doctor 收到 SIGTERM 后，等待受管命令执行 TERM cleanup 并退出，再返回失败；不是信号直接杀死 CLI，也没有创建 state。Node 控制测试另启动独立 worker 进程组，用超过六秒的实际清理过程证明 host 不会沿用旧 500ms／不足六秒的宽限过早杀死 Go 所有者；忽略 TERM 的诊断进程仍在 20 秒后强制终止，迟到成功不覆盖取消。
+
+测试环境的执行身份为 root，已有 chmod 故障注入需要去掉 DAC 绕过能力。因此本地使用 `setpriv --bounding-set=-dac_override,-dac_read_search --inh-caps=-all --ambient-caps=-all` 启动 Go 测试。没有删除原失败断言或放松覆盖率，普通 CI 用户不需要这层环境适配。
+
+100% 是本项目的逐函数 Go **statement coverage**，不是分支覆盖、JavaScript 覆盖率或真实模型质量的证明。新增断言检查可见行为、错误传播、隔离和收尾，不只检查配置拼接。
+
+## 2. 本轮确认的行为
+
+### 配置与实际调用
+
+- profile 在加载时展开，引用只在同一完整文件内解析；阶段显式覆盖不污染其他阶段。
+- harness/model/channel 的必需值、未知引用、错拼字段、非法 role、错误类型与 provider 冲突在调用前拒绝；已有 inline 缺省及合法零值保留。
+- 配置优先级不因坏 JSON、不可读或失效链接而回落，空 taskDir 不会误读进程所在目录的任务配置。
+- Provider 在 Plan、Execute、Review、Judge、第二意见、Intake、Garden 全部贯通；每次后备渠道切换重新解析，跨到非 DSH 后端不残留 DSH Provider。
+- metrics 保留账号 channel 与实际 provider 两个维度，unknown usage/cost 不变成零；渠道别名不被当作账号切换证明。
+
+### 预检与桌面
+
+- config inspect 与 doctor 使用只读配置加载；普通 status 的停滞判断也改用只读加载，避免查看进度时物化全局配置。
+- Git 根发现、命令版本、SDK 探测共享有界上下文；预先取消不启动任何进程，中途取消不继续后续 SDK。
+- task scope 只包含必需阶段与实际路由；取消仍保留完整正确的范围标记。无 packet 可做提前预检，但正式启动仍需合法 packet。
+- probe 只确认 adapter 接受配置、目录、完整沙箱、审批策略和正常 SDK 收尾；明确断言零 `session/prompt`、零 `session/wait`，usage/cost 为 null。
+- 配置错误、版本和 SDK 错误不回显原始字段值或凭据；账号授权、额度、实际模型目录与推理能力保持 unknown。
+- 面板复用 Go 控制协议；合法 doctor 失败可逐项查看，错误身份／协议／超时继续拒绝。路径切换后迟到成功、失败和 finally 不污染新视图。
+- 所有 packet 可见，完成／停止／暂停／升级与未知成本分别呈现，原始 JSON 默认折叠。
+
+## 3. 自审与文档
+
+本轮 review 修复并保留回归的具体问题：
+
+1. 新预检的 Git 根发现最初未受超时约束，现统一使用 watchdog/context。
+2. 诊断被取消时，Go 默认信号退出与 Node 500ms 强杀可能截断清理；现由 CLI signal context 和 host 20 秒收尾窗口共同处理。
+3. 取消后未遍历的绑定可能误保留 `inScope:true`，现先计算全体范围。
+4. 旧 status 读取可能创建全局配置，现使用 LoadReadOnly。
+5. 严格配置解析保留旧 `invalid JSON` 错误前缀；原测试中把 harness 名写进 drivers 的 fixture 改为明确 real，仍验证缺环境变量时 fail-loud AUTH。
+
+[PR #14 的首轮 CI](https://github.com/ckanner/flywheel/actions/runs/41369336819) 在 Ubuntu 完整通过；macOS 暴露了新 CLI fixture 的路径假设：测试期望 `/var/...`，而控制协议正确返回解析后的 `/private/var/...`。后续修复只将 fixture 的期望路径规范化，并新增 `TestDiagnosticCLIUsesPhysicalTaskIdentity`：通过真实仓库符号链接调用 config／doctor，检查响应中的 taskDir、cwd 和嵌套诊断身份一致且不创建 state。生产路径语义、失败断言和覆盖率门禁保持不变。修复后的定向回归和完整 `make quality-gate` 再次通过，独立只读复审未发现阻断问题。最终双平台结果以 PR 最新提交的 Checks 为准。
+
+README、设计、Mac 教程、配置指南、插件 README／PROTOCOL 和 new/run/status 三项 skills 已同步。skills 仍是校验、CLI 调用和结果解释，不实现第二套调度、重试或状态写入。
+
+外部 Codex Pro 交接文档重新固定到 `21fd7ac...`／0.7.0，区分已经修复的启动 deadline、内部 usage／receipt，以及仍阻断公开消费的有效配置、权限、完整收据和进程所有权问题。该外仓只读审计，没有在 Flywheel 内通过非公开 import 或嵌套父模型冒充接入；独立 Codex CLI 路径继续可用。
+
+## 4. 仍需实机证据
+
+当前实现可以离线构建和测试；以下事实未在本轮用户 Mac 上确认：DSH 实际桌面安装／渲染、Seatbelt 成功探针、GUI PATH 与账号可见性、真实 Flash/GPT/Kimi/Codex 响应、订阅限额和中断恢复。React DOM、交叉编译和 macOS CI 不能替代这些证据。
+
+没有本轮真实模型性能／价格测量，所以不声称节省百分比或模型质量排名。SDK 初始化可能访问模型目录并写入 SDK 自己的会话／缓存；“只读预检”指不修改 Flywheel 配置和任务状态，不表示整个文件系统绝对无写入。