oh-my-codex 0.16.4 发布门禁全解析：release-readiness 证据链、15 个 PR 清单与源码级佐证

本文以 oh-my-codex 仓库中 0.16.4 版本的发布就绪报告 release-readiness-0.16.4.md 为主体，完整继承其判定结论（Verdict）、发布面（Release surface）、PR 清单与 14 项验证门禁证据，并结合 RELEASE_PROTOCOL.md 协议与仓库源码（Ralph 完成审计、Codex hook 特性开关探测、版本同步脚本、HUD state-root 可视化、通知分发器等）逐项展开，帮助你掌握一个 npm + Cargo 双栈项目在"证据驱动发布"流程中的完整门禁设计与工程落地方式。

一、0.16.4 发布结论：COMPLETE 的判定依据

0.16.4 是 2026-05-11 从标签 v0.16.4（commit 0f77c608）发布的可靠性增强版本。就绪报告给出的最终判定为 COMPLETE，其成立依赖一组同时满足的事实：

• dev 分支与 main 分支的 CI 均为绿色（分别为 CI run 25647833872 和 25647985176）；
• 标签触发的 Release 工作流（run 25648158495）通过；
• GitHub release 已附带原生资产（43 个 native assets），且经 gh release view v0.16.4 确认为非 draft、非 prerelease；
• npm 侧 npm view oh-my-codex version 在发布工作流完成后返回 0.16.4。

一个关键细节是：这份就绪文档本身是"发布后仅文档"（post-publish docs-only）的证据提交。它记录在不可变的发布标签之后，标签本身仍停留在 0f77c608。这一做法并非特例，而是 RELEASE_PROTOCOL.md 第 6 节"Post-publish corrections"的明确要求：发布后若发现证据缺失或不完整，不得移动已发布的 npm 溯源标签，而是将修正后的发布配套文档提交到 dev、再经常规 CI 提升到 main。就绪报告"Known gaps / pending gates"一节因此写明：对已发布的 v0.16.4 标签无任何遗留缺口，且本次更新是刻意的 post-publish docs-only 证据提交。

npm 发布走的是仓库发布工作流的 trusted-publishing 路径，全程未使用本地 npm 凭据——这也是该报告 Notes 一节特意强调的一点：发布凭据与本地开发者环境隔离，溯源（provenance）可审计。

二、Release surface：0.16.4 的四条改动主线

就绪报告将本次发布的全部改动归纳为四条主线，这是理解 15 个 PR 如何归类的骨架：

1. 批准执行/计划（Approved execution/planning）：批准上下文引用（approved context refs）、规范化 PRD 别名、收紧的 context-pack 诊断、可见 hint 的血缘回退（visible hint lineage fallback）、多行 launch-hint 匹配、私有 context-pack 条目元数据，以及 Team 扩容（scale-up）过程中对已批准 handoff 的保留。
2. Hook/setup/notify：setup 中遗留 hook 状态去重、受支持的 Codex hooks 特性开关（feature flag）迁移、clear 重置后 hook 仍然保留、过期 PostCompact 接线（wiring）检测、递归 notify 分发器防护。
3. Runtime/workflow 完成度：boxed Team 的 state-root 优先级、HUD state-root 可视化、plugin 模式下的 skill 发现、plugin MCP 清理、Ralph 完成审计证据、Ultragoal 最终清理/评审证明要求。
4. Release metadata：Node/Cargo 元数据、lockfile、changelog、release body、release notes 与就绪配套文档全部对齐到 0.16.4。

对应的完整发布说明见 release-notes-0.16.4.md，其中将本次版本定位为"post-0.16.3 可靠性发布"，四条主线分别对应 Highlights 中的四个条目；CHANGELOG.md 中的 ## [0.16.4] - 2026-05-11 小节也回指了这份就绪文档，形成 changelog → release notes → readiness 三层文档互相印证。

三、PR 清单：15 个合入 PR 与四条主线的映射

就绪报告逐条列出了 compare range 内的全部合入 PR，这是 RELEASE_PROTOCOL 第 1 步"冻结发布范围"的直接产物——先用 git merge-base --is-ancestor "$PREV" "$CANDIDATE" 验证前一标签是候选提交的祖先，再从精确的 compare range 生成 PR 清单，避免"凭最后一次修掉的 blocker 写发布说明"：

PR	标题	所属主线
#2222	feat(ralph): add approved context refs	批准执行/计划
#2223	fix: accept canonical approved PRD aliases	批准执行/计划
#2224	fix: tighten context pack handoff diagnostics	批准执行/计划
#2226	Fix setup legacy hook-state dedupe	Hook/setup/notify
#2229	Fix Codex hooks feature flag	Hook/setup/notify
#2241	fix(planning): keep lineage fallback on visible hints	批准执行/计划
#2242	fix(team): preserve approved handoffs during scale-up	批准执行/计划
#2243	fix: preserve multiline approved launch-hint matching	批准执行/计划
#2245	feat(planning): read private context-pack entry metadata	批准执行/计划
#2248	Keep OMX hooks active after clear resets	Hook/setup/notify
#2251	Detect stale PostCompact hook wiring	Hook/setup/notify
#2256	Prevent recursive OMX notify dispatcher wrapping	Hook/setup/notify
#2259	Fix OMX HUD state-root visualization	Runtime 完成度
#2262	Guard Ralph completion on audit evidence	Runtime 完成度
#2263	Avoid stale Codex hook flags across CLI releases	Hook/setup/notify

按主线计数：批准执行/计划 7 个、Hook/setup/notify 5 个、Runtime 完成度 3 个，加上 release-review 阶段的 Ultragoal 证明要求与元数据对齐改动，与 Release surface 一节完全吻合。

四、14 项验证门禁：证据表格与逐项解读

就绪报告核心是一张验证证据表。以下完整保留其 14 项门禁及结果说明，并补充协议层面的解读：

门禁	结果
Compare range ancestry（祖先校验）	PASS — git merge-base --is-ancestor v0.16.3 HEAD
Version metadata sync（版本元数据同步）	PASS — package.json、package-lockfile、Cargo workspace、Cargo lockfile 全部对齐 0.16.4
Code review	PASS — $code-review 终检批准了 release-body 证据措辞与 Ralph 完成审计加固；架构师复审清除了 symlink/path 工件处理与 runtime 工件清理
Local build/lint/no-unused	PASS — npm run build、npm run lint、npm run check:no-unused
Targeted release tests	PASS — node --test dist/cli/__tests__/version-sync-contract.test.js 及发布相关的 setup/planning/Team/Ralph/Ultragoal/hook 测试套件
Rust tests	PASS — cargo test
Package dry run	PASS — npm pack --dry-run
Release body generation	PASS — 本地打 tag 前生成 /tmp/RELEASE_BODY.v0.16.4.generated.md，sha256 为 a8e0d181...bb3c23；Release 工作流 25648158495 另行生成并附上了 GitHub release body
Diff hygiene	PASS — git diff --check
Dev CI	PASS — dev 分支 commit 0f77c608 的 CI run 25647833872，2026-05-11 打 tag 前完成
Main CI	PASS — main 分支 commit 0f77c608 的 CI run 25647985176，2026-05-11 打 tag 前完成
Release workflow	PASS — 标签 v0.16.4 触发的 Release run 25648158495，2026-05-11 完成
GitHub release	PASS — 非 draft、非 prerelease，附带 43 个原生资产
npm	PASS — 工作流发布后 npm view oh-my-codex version 返回 0.16.4

这 14 项门禁覆盖了 RELEASE_PROTOCOL.md 第 4 节"Release-readiness gate"规定的四类必备记录（compare range、PR 清单、本地门禁、CI run ID）与第 5 节发布序列的验证动作（release 非 draft/prerelease、原生资产与 manifest 挂载、npm 版本确认）。协议第 7 节"Stop condition"进一步定义了发布完成的充要条件：main 与标签指向预期提交、Release 工作流绿色、npm 版本正确、release body 准确概括整个 compare range、就绪文档含 CI 与发布证明——0.16.4 的"COMPLETE"判定即是对这五项的逐项确认。

版本元数据同步门禁的源码实现

"Version metadata sync"这条门禁由 check-version-sync.ts 脚本支撑。它解析 package.json 与 Cargo.toml 的 [workspace.package].version，校验两者相等；并强制 crates/omx-api、crates/omx-explore、crates/omx-runtime-core、crates/omx-mux、crates/omx-runtime、crates/omx-sparkshell 六个 crate 全部使用 version.workspace = true，杜绝子 crate 版本漂移。若传入 --tag 参数，还会校验标签格式必须是 v<package.json 版本>。任何一项不符即 exit 1，这解释了为何就绪表中该门禁能一条命令覆盖"package、lockfile、Cargo workspace、Cargo lockfile 对齐 0.16.4"的结论。

五、关键改动深潜：从 PR 标题到源码证据

以下结合仓库当前源码，对 0.16.4 中技术性最强的四条主线做纵深印证。

5.1 Ralph 完成审计证据（#2262）

#2262 "Guard Ralph completion on audit evidence" 将 Ralph 工作流的"完成"从状态字面量升级为必须持有审计证据。实现位于 completion-audit.ts，核心函数 evaluateRalphCompletionAuditEvidence(state, cwd) 的判定链为：

1. 候选来源：优先从 state 中读取 completion_audit / completionAudit / completion_audit_evidence 等键；若 state 中只有路径键（如 completion_audit_path），则读工作区内的 JSON 工件文件，来源标记为 state 或 artifact，两者皆无则为 missing。
2. 路径安全边界（Code review 中架构师复审清除的 "symlink/path artifact handling" 即对应此段）：拒绝绝对路径；解析后必须位于 cwd 之内；扩展名必须是 .json；再用 realpathSync 对工作区根与工件路径双重解引用并再次做目录包含性检查，防止符号链接把审计工件指向工作区外。
3. 内容三要素：passed === true 的裁决；非空的 checklist（prompt_to_artifact_checklist / requirements_checklist 等别名）；非空的验证证据（verification_evidence / commands / tests 等别名）。任一缺失分别返回 completion_audit_not_passing、missing_completion_checklist、missing_verification_evidence 原因码，只有三者齐备才返回 complete: true。

该函数在 cli/index.ts、codex-native-hook.ts 与 state/operations.ts 三处被调用，意味着 Ralph 无论从 CLI、原生 hook 还是状态操作路径判定完成，都必须过同一道审计闸门。配套的单元测试 completion-audit.test.ts 覆盖了 /etc/hosts 绝对路径拒绝、非 JSON 扩展名拒绝、符号链接逃逸拒绝等场景。

5.2 Codex hook 特性开关迁移（#2229、#2263）

#2229 与 #2263 解决同一问题的两面：新版 Codex CLI 将生命周期 hook 的特性开关从 [features].codex_hooks 更名为 [features].hooks，setup 生成的配置必须在跨 CLI 版本时保持兼容。实现位于 codex-feature-flags.ts：

• CODEX_HOOK_FEATURE_FLAGS 定义两个合法名字，DEFAULT_CODEX_HOOK_FEATURE_FLAG 为当前规范名 "hooks"；
• parseCodexFeatureNames 逐行解析 features list 输出（正则 ^([A-Za-z0-9_]+)\s+）得到特性名集合；
• resolveCodexHookFeatureFlag 的决策顺序为：特性列表中出现 hooks 即用 hooks；否则出现 codex_hooks 即用旧名；若特性列表不可用，则用 parseCodexCliVersion 解析 CLI 版本并与 [0, 130, 0] 比较——达到该下限即认为应使用新名 hooks；都不满足时回退到调用方传入的 fallback 或默认值。
• 最终配置行由 formatCodexHookFeatureFlagLine 生成为 hooks = true 或 codex_hooks = true。

这与发布说明中的兼容性承诺一致：旧版 Codex 安装仍走 legacy codex_hooks 回退路径，当前生成的配置在 CLI 声明支持时优先 [features].hooks = true。测试文件 codex-hooks.test.ts 中可见 PostCompact 等六个事件名（PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、PostCompact、Stop）的接线断言，对应 #2251 的"过期 PostCompact 接线检测"——生成器会校验受管 hook 条目是否仍与当前模板匹配，从而发现旧版本残留的过期 wiring。

5.3 HUD state-root 可视化（#2259）

#2259 修复的是 HUD 渲染 state-root 来源时展示错误的问题。当前 hud/index.ts 与 hud/reconcile.ts 中，rootSource 字段按固定优先级解析环境变量来源：OMX_TEAM_STATE_ROOT → team-env，OMX_ROOT → omx-root-env，OMX_STATE_ROOT → omx-state-root-env，均缺失则为 cwd-default。类型定义见 hud/tmux.ts 的 HudRuntimeRootSource 联合类型，HUD 进程会在 hud/state.ts 记录这些被会话/team 状态根覆盖继承的环境变量。这使"boxed Team state-root 优先级"（Release surface 主线三的第一项）在界面上变得可观测：用户可以直接看到当前 HUD 渲染的是哪个 root、来源是哪个环境变量，而非隐性地读错状态。

5.4 递归 notify 分发器防护（#2256）

#2256 "Prevent recursive OMX notify dispatcher wrapping" 针对的是分发器把自己再次包进用户 notify 命令的递归链。实现位于 notify-dispatcher.ts：分发器元数据中带有 managedBy 字段（NotifyDispatcherMetadata），OMX 写入的 wrapper 因此可自我识别、拒绝二次包裹。同一文件还包含防止 Codex Desktop 批量回放 turn-ended 回调造成通知风暴的合并机制：默认同回合最小分发间隔 DEFAULT_TURN_DISPATCH_MIN_INTERVAL_MS = 10_000（刻意设得大于一次重载 hook 调用的耗时），过期事件阈值 5 分钟，且按 thread_id / session_id 等标识（readPayloadIdentity）保留各线程独立的分发节奏。分发状态持久化由 45 秒过期锁（DISPATCH_LOCK_STALE_MS）保护，测试见 dispatcher.test.ts。

5.5 批准执行上下文（#2222–#2245、#2242）

计划侧的多项修复集中于"批准证据不丢失"：approved-launch-hint-lineage-matrix.test.ts 用矩阵化测试固化了"多行 launch-hint 匹配"与"可见 hint 血缘回退"的解析行为，确保 #2243 的多行匹配与 #2241 的血缘回退在各种换行、缩进组合下不丢 readiness 证据；#2222/#2245 引入的 approved context refs 与私有 context-pack 条目元数据，则由 planning/artifacts.ts 等模块读取并在 handoff 时透传；#2242 则保证 Team 扩容（scale-up）重建状态时已批准的 handoff 不被丢弃。就绪报告将这几项统一归入"tightened context-pack diagnostics"，其可验证依据即上述测试套件在 Targeted release tests 门禁中的通过。

六、可复制的门禁清单：其他项目如何借鉴

从 0.16.4 的完整证据链可以抽象出一套可直接复用的发布门禁流程，全部动作均可从当前仓库核对：

1. 先冻结范围再写文档：git merge-base --is-ancestor 验证祖先关系，git log --format='%h %s' "$PREV..$CANDIDATE" | grep -Eo '#[0-9]+' | sort -u 生成 PR 编号清单，发布说明必须逐条覆盖或显式排除（见 RELEASE_PROTOCOL.md 第 1 节）。
2. 四件套文档齐备：CHANGELOG.md、docs/release-notes-<version>.md、docs/qa/release-readiness-<version>.md、RELEASE_BODY.md 缺一不可；release body 模板必须含 ## Contributors，用 generate-release-body.js 在打 tag 前本地生成并人工核对贡献者名单（0.16.4 即记录了生成文件的 sha256 作为防篡改证据）。
3. 本地门禁 + 双分支 CI：build/lint/no-unused、版本同步契约测试、cargo test、npm pack --dry-run、git diff --check 全部通过，且 dev 与 main 在同一候选 commit 上 CI 均为绿色后才打 tag。
4. 发布后只补文档、不动标签：证据补录走 post-publish docs-only 提交（本文档自身即是范例），绝不移动已发布 npm 溯源标签。

七、适用前提与限制

• 本文所有门禁、脚本与源码结论基于 oh-my-codex 当前仓库内容；0.16.4 对应 commit 0f77c608，仓库当前 HEAD 的版本已演进到更高（package.json 当前为后续开发版本），后续版本的 readiness 文档（如 release-readiness-0.17.0.md）结构与本文一致，可作对照。
• CI run ID、sha256 值、npm/GitHub 发布状态均为就绪文档在 2026-05-11 时点的快照记录，属于该次发布的历史事实；复现"当前"发布状态应以仓库最新 CI 为准。
• RELEASE_PROTOCOL 中的示例命令（如 gh pr list）依赖本机已认证 CLI 环境；本文仅说明其用途，不构成对任何外部服务的依赖描述。