OmX 0.16.1 发布解读：explore 有界执行、会话级运行时权威与 Team 审批移交的全面加固

0.16.1 是 OmX（oh-my-codex）在 0.16.0 之后的一次大范围加固版本，核心目标是让"探索（explore）更安全、运行时状态更可靠、团队移交不丢信息"。本文基于官方发布说明 docs/release-notes-0.16.1.md，结合仓库源码逐项解读 explore 有界执行机制、会话级运行时权威、Team approved-handoff 修复路径、Codex goal-mode 持久性、插件与跨平台启动修复以及 CI 发布完整性，帮助你在升级到 0.16.1 时理解每个修复背后的工作原理与验证方式。

版本概览：一次 25 个 PR 的 post-0.16.0 加固列车

0.16.1 从 v0.16.0 演进而来，共合并 25 个 PR，外加最终的 release-review 阻塞修复（explore 本地 fast-path 与 CI 依赖安装）。按发布说明划分，这批改动集中在六个方向：

• Explore 安全与有界执行：Codex-backed explore 在语义回退前先做有界约束；进程风暴在触发宿主机 OOM 之前被上限拦截；symlink 本地 fast-path 文件读取不再泄漏到仓库之外；超大本地文本搜索读取回退到有界处理。
• 运行时与会话权威：会话级（session-scoped）运行时状态成为活跃权威，终端工作流结束后清理陈旧的根级 skill-active/HUD 状态，项目级 Codex goal 状态保持持久。
• Team 审批移交加固：审批通过的 Team 执行保留歧义绑定（ambiguous bindings）、绑定传输（binding transport）、选定移交（selected handoffs）、无效 context-pack 诊断、非就绪（nonready）仅修复行为、DAG 回退状态、只读 context-pack 状态可见性。
• Goal-mode 与 interview 流程：规划移交引导向 goal-mode 跟进，处理被阻塞的 ultragoal Codex goal 移交，deep-interview 路由将事实与判断分离。
• 插件、启动与平台修复：插件 MCP 启动行为更清晰、插件 skill 缓存刷新可用、托管 helper 使用当前 JS 运行时、Windows OMX 根启动路径修复、Darwin 启动回退 worktree 断言路径稳定、一次性启动 worktree 状态保持持久。
• CI 与发布完整性：CI 关键路径延迟降低但保留发布门禁，Node 任务无条件 npm ci 证明 lockfile 安装完整性，Node/Cargo/插件元数据版本同步校验，原生发布产物通过 tag 工作流构建。

从源码结构看，这批改动横跨 crates/omx-explore（Rust 探索 harness）、src/state（会话状态）、src/team（团队执行）以及 src/ralplan、src/runtime 等多个模块，下面逐主题深入。

Explore 有界执行：从"先跑再说"到"先限再跑"

0.16.1 在 explore 安全上的改动可以归纳为一句话：任何一次 explore 执行都必须在时间、进程数、输出量、命令集合和路径范围五个维度上同时受到约束。这些约束的实现主体是 Rust 编写的 explore harness，源码见 crates/omx-explore/src/main.rs。

五维有界模型

harness 通过环境变量暴露全部边界配置，并带有默认值（见 main.rs）：

边界维度	环境变量	默认值	超限行为
单次执行超时	OMX_EXPLORE_CODEX_TIMEOUT_MS	180000（180 秒）	终止整个进程树，返回退出码 124
单次运行进程数上限	OMX_EXPLORE_PROCESS_LIMIT	96	终止进程树，返回退出码 125
子进程输出上限	OMX_EXPLORE_CODEX_OUTPUT_LIMIT_BYTES	8388608（8 MiB）	终止进程树，返回退出码 126
codex 二进制路径	OMX_EXPLORE_CODEX_BIN	从 PATH 解析 codex	使用自定义二进制
仓库根目录	OMX_EXPLORE_ROOT	由调用方传入	用于路径逃逸校验

超时、进程数、输出量三个边界的超限结果被建模为 TimedCommandOutput 枚举的 TimedOut / ProcessLimitExceeded / OutputLimitExceeded 三个变体（main.rs），并且三者都在 run_command_with_timeout 的主循环里被同时轮询（main.rs）：每 100ms 通过 /proc 遍历统计子进程树规模（Linux 实现见 main.rs），一旦超过 96 立即终止；stdout/stderr 通过独立线程的 read_pipe_bounded 做有界读取，超过 8 MiB 立刻报错（main.rs）。超时后先 SIGTERM、宽限 500ms 再 SIGKILL 的进程组终止逻辑，确保了 wrapper 退出后遗留的孙进程也被清剿，不会留下脱离的 shell（main.rs）。

spark 模型 + 语义回退的两段式执行

0.16.1 中"有界执行先于语义回退"指的是：每次 explore 先用低成本 spark 模型尝试（--model-spark），只有 spark 失败（非零退出）后才切换到 --model-fallback 模型（main.rs）。回退事件会以 fallback-attempt=model from=.. to=.. reason=spark_attempt_failed 的形式输出到 stderr，并在成功输出前附带 markdown 提示，明确告知"成本/行为边界已改变"（main.rs）。这保证了用户永远知道结果来自哪个模型、成本边界在哪。

命令白名单与受限 PATH

探索进程的 PATH 被替换为临时 allowlist 目录（main.rs），其中只放入白名单命令的 wrapper 脚本，白名单本身为：

const ALLOWED_DIRECT_COMMANDS: &[&str] = &[
    "rg", "grep", "ls", "find", "wc", "cat", "head", "tail", "pwd", "printf",
];

（见 main.rs）。wrapper 把每个命令转发回 harness 自身的 --internal-allowlist-direct 或 --internal-allowlist-shell 内部路径做二次校验：rg 禁止 --pre 与 stdin -，grep 必须有 pattern 与文件操作数，find 禁止 -exec/-delete/-fprint 等执行/删除/写文件动作，cat/head/tail/wc 禁止 stdin，tail 禁止 -f/-F/--retry 跟随模式（main.rs）。shell wrapper 还拒绝包含 &&、||、;、|、>、<、反引号、$( 等片段的命令（main.rs）。

路径逃逸防护与 symlink 修复

发布说明特别强调"symlinked local fast-path file reads no longer leak outside the repo"。这对应 validate_repo_paths 的双重路径校验（main.rs）：每个文件操作数既要通过文本层面的 starts_with(repo_root) 检查，还要通过 canonicalize_existing_prefix 解析后的规范路径检查——文本上看似在仓库内、但经过 symlink 实际指向仓库外的路径，会在规范路径检查中被拦截并报错 path ... resolves outside the omx explore repository root。升级说明中"本地 fast-path 读取不再跟随 symlink，symlink 路径回退到 harness 路径"与"超大文本搜索跳过 fast-path、交给有界回退处理"正是这一层的落地行为。

子进程环境净化与只读提示注入

harness 还会从子进程环境中剥除 BASH_ENV、ENV、PROMPT_COMMAND、NODE_OPTIONS、SHELLOPTS、BASHOPTS、GREP_OPTIONS、GREP_COLORS 等可能被劫持的变量（main.rs 与 main.rs），并在组合后的 prompt 中注入强约束："Operate strictly in read-only mode... Do not write, delete, rename, or modify files. Do not run git commands that alter working state. Always return markdown only."（main.rs）。

平台边界：Windows 与命令面迁移

需要特别说明两个适用前提：

1. Windows 上内置 harness 不可用：因为 allowlist 运行时依赖 POSIX sh/bash wrapper，在 Windows 上会直接报错，提示设置 OMX_EXPLORE_BIN 指定兼容的自定义 harness、改用 omx sparkshell 或运行 omx doctor 查看就绪详情（main.rs）。
2. omx explore 命令面已硬弃用：在 0.16.1 所处的代码状态中，src/cli/explore.ts 里 omx explore 的直接命令面已被移除，任何旧式调用（如 omx explore --prompt）都会抛出 EXPLORE_DEPRECATION_MESSAGE 并提示迁移路径（src/cli/explore.ts）——简单只读仓库查找请使用 Codex 常规仓库检查工具/子代理，需要显式 shell 原生只读证据时使用 omx sparkshell -- <command>。同时 src/hooks/explore-routing.ts 提供了 prompt 级别的探索路由判定（USE_OMX_EXPLORE_CMD 环境变量开关 + 简单探索 prompt 模式识别），用于在会话层面把只读探索类请求路由到正确表面。

会话级运行时权威：让状态归属回到会话

0.16.1 的核心原则之一是"session-scoped runtime state is now the active authority"（会话级运行时状态现在是活跃权威）。这解决了多会话并存时根级（root）状态与当前会话状态互相污染的问题。

skill-active 状态的会话化

在 src/state/skill-active.ts 中，状态文件同时存在根级路径与会话级路径两条线：getSkillActiveStatePaths 会同时返回 rootPath（如 .omx/state/skill-active.json 语义下的根文件）与会话专属的 sessionPath（如 .omx/state/sessions/<sessionId>/skill-active.json），所有写入都通过"session-copy"事务同时落到两个路径（skill-active.ts），并且主路径必须是 session-scoped，否则直接抛错（skill-active.ts）。这就保证了：终端的 ralplan/Ralph 工作流结束后，即使根级残留了陈旧的 skill-active 状态，当前会话的活跃判定也不会被它带偏。

测试证据

src/cli/tests/session-scoped-runtime.test.ts 用一整组用例固化这些不变量，其中与 0.16.1 直接相关的包括：

• "ignores stale root workflow state for session-scoped active decisions"（workflow-transition.test.ts）：根级陈旧工作流状态不影响会话级活跃判定；
• "preserves active Team skill entries while cancelling Ralph"（session-scoped-runtime.test.ts）：取消 Ralph 时保留活跃 Team skill 条目；
• "rejects symlinked session authority directories"（session-scoped-runtime.test.ts）：会话权威目录的 symlink 被拒绝，防止路径劫持；
• "prefers session-scoped canonical state over root state"（skill-active.test.ts）：会话级规范状态优先于根状态。

Team 审批移交：不丢绑定、不丢状态

0.16.1 的 Team 相关修复集中在"审批通过后移交"的可靠性上。发布说明列举的五类不变量分别是：

• 保留歧义绑定（ambiguous bindings）：审批通过后不再因歧义而丢弃绑定；
• 保留绑定传输（binding transport）：绑定在移交链路上原样传输；
• 保留选定移交（selected handoffs）：在存在不完整草稿时，已选定的审批移交不被挤掉；
• 无效 context-pack 角色诊断：context-pack 角色无效时的诊断信息在审批移交中保留可见；
• 非就绪（nonready）审批移交仅允许修复：未就绪的移交不会误入正常执行路径；
• DAG 回退状态与移交状态对齐：Team DAG 回退不再与移交状态错位；
• 只读 context-pack 状态可见性：只读场景下也能看到 context-pack 的移交状态。

这些修复对应发布说明中列出的 PR #2169（Keep nonready approved handoffs repair-only）、#2170（Preserve invalid context-pack role diagnostics）、#2171（Close remaining approved handoff fallback gaps）、#2172（Keep Team DAG fallbacks aligned with handoff status）以及提交 e1711433（Preserve ambiguous approved Team bindings）、c6f5d46a（Preserve team-exec approved binding transport）、3e8767bb（Keep selected approved Team handoffs amid incomplete drafts）、8c8d2ed5（Add read-only context-pack handoff status）。涉及的核心实现位于 src/team（共 96 个文件）的审批与移交链路，以及 docs/contracts/team-delivery-state-contract.md 定义的交付状态契约。

Goal-mode 与 interview 流程：让移交指向正确的下一步

• 规划移交引导到 goal-mode：PR #2138 让 planning 阶段的移交更倾向于导向 goal-mode 的后续跟进，避免闭环在一次性任务上；
• 被阻塞的 ultragoal Codex goal 移交：PR #2140 处理 ultragoal 场景下 Codex goal 移交被阻塞的情况，相关目标工作流逻辑位于 src/ultragoal 与 src/goal-workflows；
• deep-interview 事实/判断分离：PR #2159 改进 deep-interview 的"事实路由"，将可验证事实与主观判断分流，相关配置与实现见 src/config/deep-interview.ts 与 src/question/deep-interview.ts；
• 项目级 goal 状态持久：PR #2151 保证项目级（project-scoped）Codex 会话中 goal 状态不丢失，确保跨会话恢复时目标仍然在场。

插件、启动与平台修复：跨平台一致性的细节账

0.16.1 在插件与启动链路上的修复，每一条都对应明确的源码位置：

• 插件 MCP 启动真相澄清（PR #2122）：插件 MCP 的启动行为描述与真实行为对齐，MCP 注册与启动逻辑见 src/config/mcp-registry.ts 与 src/mcp/bootstrap.ts；
• 插件 skill 缓存刷新修复（PR #2152）：缓存刷新不再残留陈旧 skill，插件目录布局见 plugins/oh-my-codex/skills，缓存逻辑对应 src/catalog 与 src/config/omx-first-party-mcp.ts；
• 托管 helper 使用当前 JS 运行时（PR #2153）：托管 helpers 不再绑定旧运行时，而是解析当前 node 执行环境；
• Windows OMX 根启动路径修复（PR #2157）与 Darwin 启动回退 worktree 根断言路径稳定（PR #2178）：启动回退（launch-fallback）路径在 Windows/Darwin 上保持一致，避免路径断言差异导致的误报；
• 一次性/单飞启动 worktree 状态持久（PR #2134）：solo/disposable 启动场景下 worktree 状态不被误清理；
• 配置级 xhigh 推理覆写（PR #2131）：为 agents 增加配置级 xhigh 推理强度覆写，可结合 src/agents 的 agent 定义使用；
• UI 设计反 slop 信号（PR #2168）：为 UI 设计流程增加反 slop 信号，相关方法论沉淀在 skills/design/SKILL.md。

CI 与发布完整性：让"能构建"变成"可证明"

0.16.1 在 CI 上做的是减法与加法的组合：

• 降低关键路径延迟（PR #2158）：CI critical-path 延迟降低，但发布门禁原样保留；
• 无条件 npm ci：CI 不再恢复/跳过缓存的 node_modules，每个 Node 任务都运行 npm ci 以证明 lockfile 安装完整性——这是发布说明明确列出的升级注意点；
• 版本同步校验：Node/Cargo/插件元数据的版本一致性通过脚本校验，对应仓库中的 src/scripts/check-version-sync.ts；
• 原生产物随 tag 工作流构建：native release artifacts 通过 release tag 工作流构建并发布，配合 src/scripts/verify-native-release-assets.ts 做原生资产冒烟验证。

升级与验证：0.16.1 的完整验收记录

升级注意点（行为变化）

1. omx explore 本地 fast-path 文件读取不再跟随 symlink，symlink 路径回退到 harness 路径——如果依赖 symlink 文件做探索，行为会变化；
2. 本地 explore 文本搜索在 fast-path 中跳过超大文件，交给有界回退处理更广泛的搜索；
3. CI 不再使用缓存的 node_modules，每次执行 npm ci。

验证记录

• Dev CI（9e4d118b）通过；Main CI（cfc29185）通过；
• 发布 tag 工作流（v0.16.1）通过，覆盖版本同步、原生产物发布、原生资产冒烟验证、packed 全局安装冒烟测试、npm 包发布；
• 本地发布前门禁包括 Rust workspace 测试、TypeScript 构建、lint/no-unused 检查、定向 Node 测试以及 npm pack --dry-run。

总结：从 0.16.1 看到的加固方法论

回顾整个 0.16.1，OmX 的加固思路非常清晰：给每个可能失控的环节提前划好边界（explore 的时间/进程/输出上限）、给每份状态明确归属（session-scoped 权威）、给每次移交保留全部信息（Team approved-handoff 不变量）、给每次发布可复现的证明（npm ci + 版本同步 + tag 工作流）。对于使用 OmX 的开发者，升级到 0.16.1 后建议：把 OMX_EXPLORE_CODEX_TIMEOUT_MS、OMX_EXPLORE_PROCESS_LIMIT、OMX_EXPLORE_CODEX_OUTPUT_LIMIT_BYTES 视为可调的有界执行参数按需配置；关注 ralplan/Ralph 终结后 HUD 与 skill-active 状态是否随会话正确收敛；并在多会话并行场景下验证 Team 审批移交的绑定与状态完整性。