Changelog
[3.1.1] - 2026-10-22
文档完善
- 新增
references/41-pm-merge-and-sync.md,接续 40 页的 PM 总管职责:以真实交接事件说明本地路径/slug 误参、同一 PR ready 与最终候选门禁、服务端更新 base 的树/blob 等价证据、内容绑定隐私例外与插桩假命中、保护在途材料的本地/云端收敛、有效未推送回执保留和 provider 中断恢复。 - 明确 mixed reset 会改 index 且不物化新增/修改/删除文件;主目录维护须单独授权、具名 owner 和字节验收,runtime 拒绝不绕过。内容审查承接不替代最终 checks 或隐私历史复检;单次容量观测不写成通用并发默认。
- SKILL 读取地图与根 README 版本/最近 8 条同步;Git、主目录、隐私及生命周期操作的权威继续由 git-workflow 维护,不新增平行 Skill 或机械门禁能力声明。
[3.1.0] - 2026-10-21
新增
- Codex App cross-thread coordination 参考(
references/40-codex-app-native-coordination.md):面向 PM 与被管 worker 同处 Codex App 但是彼此独立 thread、且宿主实际提供相应能力的场景; 只协调已存在的独立会话,不覆盖宿主 runtime 内部的 Subagent 调度。 覆盖全量盘点(list_threads需同时读取 pinnedThreads 与 threads)、生命周期状态与notLoaded/明确加载错误/额度失败/长任务运行中的区分、read_thread分层读取与分页、wait_threads批量等待语义(timedOut不等于失败、afterCursor抑重、commentary 不唤醒)、 跨会话动作边界(send_message_to_thread需用户授权、prompt 必须自包含)、 全局配置文件并发写入纪律(具名单写者、写前段/键清单快照、受控写入、写后逐项 diff 回读)、写域冲突裁决、派发形态选择、回报与静默纪律。 - 发送侧实测(2026-10-21,一次性 scratch 会话,验证后归档):
create_thread可创建独立 thread;授权后的send_message_to_thread送达目标侧并以工具输出条目出现,条目含发送方 source thread id 与完整消息文本,随后在目标侧触发新回合并可被wait_threads观察到完成。目标忙碌/notLoaded/已归档、超长或非文本消息、并发多目标顺序、跨 host 仍为NOT_VERIFIED。 - 重复任务识别矩阵:按实际 cwd/worktree、写域、任务卡、分支/PR 与产物身份交叉比对,不以标题或摘要判重;
只有路径/产物身份相同,或任务卡加 PR/分支/产物 SHA 至少两类实证指向同一交付物,才标
DUPLICATE_CONFIRMED并指定 canonical owner; 其余主题相似只能标SAME_TOPIC_UNCONFIRMED并保留双方。非 canonical owner 保留原身份与现场,不擅停、关闭、覆盖或删除在途会话;证据不足或 owner/授权不明时升级用户。 - SKILL.md 三处接入:适用边界新增 Codex App cross-thread 场景;模式选择表新增「Codex App cross-thread」一行; 按需读取地图新增对应条目。
改进
- SKILL.md 巡检与 Hard Fail 同步接入 Codex App cross-thread:跨会话消息须用户本人授权,不得仅凭标题相似停止或覆盖在途会话;
config.toml/hooks.json/providers.json等共享配置文件须具名单写者、写前快照与写后段/键逐项回读。
背景
- 源自 2026-10-21 一次真实跨会话治理:盘点多个在途会话并修复网关路由配置;
期间发生共享
~/.codex/config.toml的[hooks.state.*]信任记录丢失,导致部分会话工作区加载失败。 该事故直接促成“全局配置文件是共享写入点”一节;因果只对当次现场成立,隔离复现中magpie save/use未复现段丢失,不推广为普遍行为; 具体数量和字节仅保留在私有现场证据,不作为通用阈值。
[3.0.1] - 2026-10-15
改进
- 按用户决策退役并删除冻结兼容目录
skills/multi-agent-orchestration/:3.0.0 的"复制新目录+冻结旧目录"方案改为单一目录收敛,旧名不再以目录形式存在于仓库。 - 旧目录 gitignored 私人 config(7 个 provider/编排配置实体文件)迁入本目录并替换原软链;28 项历史 archive 物理并入本目录 archive/,历史不丢失。
- 修正改名时遗留的断链:
.claude/settings.local.json依赖安装 hook 路径(3.0.0 时即已指向不存在路径)、私人配置orchestration-personal.json的skill_root绝对路径、multica 更新清单条目。 - 收敛活引用:测试夹具目录/示例路径、脚本自称注释、example 配置
_read_by文案、references/14-pm-orchestrate.md适配注记统一改为新名。
修复
- SKILL.md「名称迁移与兼容」章节由冻结表述改为退役事实;wire schema 字面量(
multi-agent-orchestration.*.v1)、MAO_*/MULTI_AGENT_ORCHESTRATION_PERSONAL_CONFIG环境变量、状态/lease 目录路径保持不变,不创建第二状态树。
验证
test-spawn-worker-orca.sh304/304;message-contract、skill-name-migration、reviewer-scope-guard(44)、review-acceptance-gate(27)、blocker-recovery(51+33+44)、zcode-session-evidence 全过。test-remote-node-probe.sh1 例与test-spawn-worker-remote.sh4 例失败经 HEAD 原版对照确认为预存失败,与本次改动无耦合。
[3.0.0] - 2026-10-15
改进
- 权威 Skill 名称、目录和标题改为
multi-agent-orca/ Multi-Agent Orca,保留全部历史与许可证;旧名称只保留不参与 Skill 发现的冻结兼容运行时。 - 对齐当前 README、套件成员、CI、忽略规则及消费者;历史下载链接保持原发布名称。
新增
- 增加清单绑定的安装链接迁移工具,提供 plan/apply/verify/rollback;只新增经核对的新入口,保留旧链接和在途运行时,拒绝实体目录冲突、源/父目录/链接漂移并支持失败恢复。
技术优化
- 复制到新名称的测试数据去除旧本机用户名路径;worker-show 夹具统一使用 /workspace,隐私测试改用运行时用户目录保持泄露检测语义。旧冻结运行时及历史原件不改。
兼容
- 原 wire schema、环境变量、状态/锁路径与业务身份不变;原 helper 脚本不因名称变化修改。在途凭证与私人配置不进入迁移包。
[2.36.9] - 2026-10-12
新增
- 补录 zcode-gui 波次配套资产(多会话积压恢复):references 34(本地 Web 与官方远控浏览器派发过渡路径)/35(浏览器自动化操作映射)/37(worker 资源收尾)/39(稀疏 worktree 派发)。
- scripts 补录:checkout-plan.py(只读检出准入)、read-worker-result.sh、spawn-worker-checkout.sh、zcode-browser-driver.cjs 及配套测试。
- 方向注记:zcode-gui 专线分支已于 2026-10-12 清理冻结;本批为通用编排能力留档入库。
[2.36.8] - 2026-10-04
修复
- 将已独审的派发准入、业务产物内容验收、共享 worker 库存与具名任务内存 profile 整合到当前公开基线;保留既有 GUI 只读证据链和工程验证证据采集。
- 持续 Wave 在资源创建前检查原 PM 监测配置;配置就绪仍不代表自动独审、写回和续派已经完成。
新增
- 原失败 ZCode Task 的关闭恢复诊断与受约束恢复入口进入公开基线。当前原生身份缺口继续阻断真实恢复,诊断结果固定不能 retry;不重置原失败历史或业务预算。
技术优化
- 既有 Linux 路径兼容和权限断言修复与当前 GUI、验证证据及内存完整 spawn CI 串行组合;本版本不改变未发布 GUI 调度合同,也不降低全局默认内存预算。
- 诊断标题改写测试等待自有 Node 夹具安装信号处理器后再发送信号,消除 exec 已完成但模块未初始化的竞态;生产恢复与超时合同保持原样。
- 更新既有安装 guard 的合法完成回执夹具,显式声明活跃 Dispatch 状态并补 failed/unknown 拒绝消费者;不放宽生产完成权限。
待办事项
- 原生关闭 Session 的真实业务恢复、持续自治与完整 worker 实测容量继续由原任务验收;参考精简 PR251 仍需其 GUI 引用发布后单独验收。
[2.36.7] - 2026-10-03
新增
- 集成只读 GUI collector→adapter→observe、校验分块产物与 Git bundle 消费者七个既有已独审候选;保持默认投递/监督/权限与资源规则,READY仅是待PM审查证据。
- 新增三项缺省同目录消费者,核无依赖环境变量/显式路径时的完成、末条错误、错绑拒绝、DB字节不变与元数据无泄漏;CI串行真实执行GUI组件与消费者,明确保留可选旧稿负控及不适用缺依赖场景的跳过。
- 沿 PR261 收录 ZCode GUI 远端作者直发 PR 合同(
references/38-zcode-gui-remote-pr.md):官方 GUI 模型内核与开源 CLI 分离、localhost 优先与官方远控跨机同页面操作逻辑、Start Plan/150% 权益真人确认与 provider 实测分列;固化“作者自测→固定 head→不同 SID 独审→原 session 返修→fresh 身份/唯一性→safe-push→唯一 draft PR→PM 从 GitHub 只读核验”发布链,含通道故障 fresh 核查、禁传凭证/禁改账号/禁关 TLS 验证与官方登录真人依赖标注;已验来源具名 PR257/PR258(两作者不同 GUI SID 交叉独审 ACCEPT、未 merge),SKILL 按需读取地图挂最小入口。
文档完善
- 按需读取地图补齐已采用的操作合同;云端PR池与main加GUI长期功能线的任务/决策记录归TASKS和DECISIONS,不新增规划reference。
待办事项
- 原生ZCode恢复、GUI自动投递/持续监测/Orca正式监督及长期稳定性仍未验收;核心PR248与参考精简PR251分别处理冲突和未发布依赖。
- 浏览器 driver 脚本自动新投递与长时全自动稳定仍 NOT_VERIFIED(PR261 维护记录保留)。
[2.36.6] - 2026-10-02
新增
- 新增只读 ZCode 会话证据采集器
scripts/zcode-session-evidence.py(Python 3.9+ 标准库,零依赖):以 mode=ro URI + query_only + 单事务快照打开既有 SQLite,绝不创建或写原生 DB;必填--db/--session-id/--input-id,可选--include-final-text;精确绑定session_input.id + session_id并经promoted_message_id关联turn_usage.user_message_id,绑定或 turn 多匹配一律拒歧义;输出稳定 JSON,区分 input admitted/promoted/failed、turn 缺失/running/completed/error/cancelled 与完成证据——精确 turn completed 加 sequence 最新 assistant(原生parentID绑定)time.completed非空、无 error 且含非空 text,不从较早成功 assistant 拾取覆盖最新 error/未完成/无 text;providerId/modelId/mode 只取该 assistant 原生 message,缺项显式 unknown,不回落其他会话或默认套餐。 - 默认仅输出元数据与最终文本长度,只有
--include-final-text才携带最终 assistant 文本;任何模式下不输出 reasoning、tool 输入/输出、session_input.payload、认证参数、完整 DB 路径或其他会话数据,错误输出清楚 JSON 且非零退出,不抛泄密 traceback。冷 DB 不是实时活性权威,缺项绝不推导 idle 或完成。 - 新增回归
scripts/test-zcode-session-evidence.py:合成 SQLite fixture 走真实 CLI 子进程,覆盖两身份错绑、同 input 多 turn、admitted/failed/缺 turn、completed/最后 assistant error/未完成/无 text(含较早成功不得覆盖)、provider 缺项、schema/JSON 错误、text 显式开关、敏感内容不泄露、缺 DB 不创建与原 DB 字节不变。 - 新增用法与合同说明
references/zcode-session-evidence.md,并在 SKILL.md 按需读取地图挂链接。
修复
- 独审 REJECT R1(F1/F2):
session_input.status_reason原生自由文本不再进入输出,仅输出reasonPresent布尔(内容永不外发);同一 promoted 消息下候选 assistant 的最大 sequence 并列、缺失(NULL)或非数值时输出ASSISTANT_AMBIGUOUS拒歧义,绝不按行序任意挑选。补对抗性 status_reason(路径/凭证样例)与 sequence 并列(旧失败/新成功双向插入序)、NULL、非数值真实 CLI 回归,回归 23→27 项。
待办事项
- 本 PR 不实现 Orca 监督适配;真实大库性能与长期稳定性 NOT_VERIFIED,沿 GUI 任务监控方向另行立项。R1 修复后实现完成但 PM 审查/PR 验收尚待(IN_REVIEW)。
[2.34.6] - 2026-10-03
新增
- 工程验证证据的可选采集与复核入口,实际执行原任务合同的简单验证命令,记录退出码、有界日志与耗时;绑定原合同、提交和实际源码,变化后拒绝复用旧证据。
改进
- 复用现有交付后门的证据格式,减少手工转抄;采集结果继续由原独立审查和验收门消费,不生成审查通过或任务完成结论。
[2.34.5] - 2026-10-03
修复
- 记录关闭恢复的真实消费者身份缺口:原生ZCode改写title/argv,Orca公开终端未报告agentIdentity,当前版本组合不能由旧核验假设证明;恢复合同明确保持不就绪,既有关闭意图保留。
新增
- 已启动恢复意图的只读
diagnose入口,核原绑定、当前owner及模型并分类终端/进程证明缺口;固定不可retry结论,保留原verify和防重放要求,便于原PM对账。
[2.34.4] - 2026-10-03
修复
reauthorize在资源或授权写入前核精确live事实,拒绝failed/process_exited和未知目标,避免把关闭任务按旧launch裸重启。
新增
- ZCode原失败Task的关闭Session恢复与单次retry入口:先核历史attempt及退出事实,以空输入恢复精确原生Session并核模型,再采用真实新Dispatch的完成凭据与路由;原首次启动防重放保持。
- 恢复前后只读核原生持久Session的worktree、权限和provider/model/effort;不修改全局账户配置,不重置业务失败预算。真实DSH恢复与业务闭环需由原PM实际验收。
技术优化
- 完成凭据Shell测试改为跨平台读取实际文件mode,仍断言600且拒绝更宽权限;修复GNU stat的输出污染误报。
- 修正原首次启动桥的系统别名处理:仅macOS将
/tmp、/var转换到/private,Linux保留真实路径;符号链接拒绝及原防重放不变。 - 新恢复入口定向测试及不同上下文消费者复审通过,覆盖真实UUID透传、矛盾身份拒绝和中断采用恢复;首次失败与独审拒绝保留。实际原任务业务恢复与长期运行仍待验,不以模拟或只读模型证据替代。
[2.34.3] - 2026-10-03
修复
- 合法研究、设计、文书与报告可采用业务产物合同派发和验收,消除必须伪装为工程 diff 或 Git 提交的误拒;维护调查扩波仍须满足原价值要求。
改进
- 并发默认值提供同源只读输出;显式共享库存和项目较小上限可共同参与准入,未提供库存时明确只验证本波数量,消除文档与代码口径冲突。
新增
- 显式任务资源 profile 接入共享内存门,限定 MiniMax CLI 保留至少 3 GiB 预算和稳定观察窗;完整启动链复核原命令、安装、输入与工作树身份。旧默认资源策略保持。
- 只读生成实际文件清单与交付指纹;内容审查和真实命令验证两种模式均绑定独立角色、来源及逐项标准。支持非 Git 目录和常见文本、图片、PDF、Office 产物。
- 业务文件消费者与旧工程门禁回归接入既有 CI,门禁不代替业务内容、来源真实性或文件渲染审查。
技术优化
- 资源CI使用字节校验后的私有Node副本并隔离setup-python的库路径,保留生产文件权限与环境校验;缺少MiniMax安装时仅现场只读探针明确标记未验,其余隔离消费者继续执行。
验证
- 三单元限定独审通过;维护矩阵71条首次通过,第59消息套件超时后原代码单例及9项整套有限复验通过,首失败与未确认根因保留。真实安装绑定通过;现场资源稳定窗拒绝,未启动模型任务。
- 未新增高危或hard静态项,基线审计告警仍保留;本轮不声明长期自治、整worker RSS或跨PM原子预留通过。
[2.34.2] - 2026-10-02
修复
- 身份观测失败保留超时、不可用、IO和坏数据分类;只有成功观测到不符才报告身份漂移。所有失败继续阻断,不提高生产超时。
- 只读Orca smoke改用每轮私有测试身份,并与生产工作树路径映射一致,避免撞到历史测试树;既有占用拒绝和只读边界保留。
- 修正持续推进文案:单依赖链泊车或暂时无合法READY不停止整个项目监测;真人催促后的恢复明确记为人工恢复,不能追认为自动自愈。
- 修正既有监测回归的固定2.6秒等待,改为有上限地核三轮真实循环完成,再断言恢复/去重;不改变生产监测周期。
新增
- 准备门、Wave与监测fixture接入既有CI;监测未达轮次或计数异常明确失败。
- 显式continuous Wave在任何Orca调用前只读核验现有Codex heartbeat的原PM、精确任务源、启用状态和周期;不就绪时拒绝创建资源。旧单波入口保留兼容。
验证边界
- 新smoke回归使用私有Orca与进程祖先输入来隔离环境,仍执行真实spawn;定向通过不等于实机宿主身份或Orca完整生命周期通过。
- 配置准备通过只表示CONFIGURED_NOT_PROVEN_AUTONOMOUS;不产生授权、不创建定时任务,不证明实际自动独审/写回/续派或跨会话稳定性。验证证据与剩余Task-067/068见TASKS中的CONTINUATION-READINESS卡。
[2.34.1] - 2026-10-02
修复
- 识别 macOS 实际
System-wide memory free percentage输出,作为独立报告百分比;区分读取成功与解析有效,不将该百分比推成可用物理内存或压力级别。
改进
- 分开记录内核原生压力通知位和既有算法的合成压力来源。内核信号仅供观测,原 swap 阈值、预算、保留公式、slots 与退出语义保持。
验证
- 新遥测13项与原内存58项首轮通过;三个冻结现场样本解析成功且仍exit3/slots0,无vm_stat与只有新百分比时仍exit1。独立39组/78次CLI对照保持旧输出与退出语义,维护矩阵66项通过(两同字节套件复用首轮证据)。原始采集器错误、快照空格例外与旧静态告警保留;长期稳定性未验证。
[2.34.0] - 2026-10-02
新增
- backend、真实命令启动模式与Orca/direct通道统一解析为派发profile,实际spawn消费同一合同;从个人配置与命令参数记录并发、请求权限和来源,观测权限单独保留未知。
改进
- 已指定ZCode时,auto默认采用已配置的原生Orca supervised桥;缺失/禁用配置在资源副作用前拒绝,旧显式native参数保留,generic兼容须显式选择。MiniMax按原验证器区分batch与交互,不改命令或共享配置。
- 启动后的指引按模式生成唯一下一动作,不再统一建议发送任务;已校验的官方worker-show projection优先,composer残留、TUI idle和启动返回不冒称已开始或完成。
验证
- 新隔离默认原生入口实际使用CodingPlan/GLM-5.3/max完成文件任务,PM2/2、唯一worker_done/Delivery、自动release与ack通过;该链绑定首候选,修后head的兼容/回执消费者和独审另行记录。缺schema旧配置误拒与已完成回执遗漏spawn动作两反例沿原session修,原失败保留;完整Skill及长期稳定性仍NOT_VERIFIED。
[2.33.2] - 2026-10-02
修复
- MiniMax terminal-managed 的原生
exec按实际 CLI 参数识别批处理启动,保存准确终端身份后跳过 TUI 等待和重复任务输入;交互 CLI 保持就绪检查与唯一输入,批处理不能充当 supervised Task/Dispatch。
验证
- 真实执行bootstrap的控制器消费者证明旧实现执行一次后仍wait64、候选0且零二次send;Orca281、metadata33通过。独审另发现单引号展开与env exec误判,按真实Shell参数和退出码返修,原拒绝证据保留;完整回归及修复后独审由PM继续核对。
- 独立Orca原生MiniMax canary仅一次bootstrap,Run succeeded/exit0/shutdownComplete,实际M3.1Flash与probe.py一致,PM1/1通过、原生配置SHA未变、最终测试终端库存0。该canary运行在首轮候选,不能替代修复后命令语义复验或长期稳定性证明。
文档完善
- 明确 ZCode 原生 Orca 启动桥与通用终端入口的区别;保留原 Task、启动回执和残余资源,失败后先读取实际进度再恢复,不重发已有业务。
[2.33.1] - 2026-10-02
改进
- 新隔离ZCode worker的renderer和无command启动入口默认yolo,显式build/edit/plan保留;MiniMax batch默认原生full,显式smart/off保留。长程MiniMax继续使用交互CLI,权限读取既有原生配置;本机已full,不添加不存在的TUI启动参数或修改全局配置。
修复
- 兼容Orca官方worker-list的scope.run,避免已释放worker被误报为malformed page而保留provider lease。所有run/runId/run_id别名仍需一致、非空且匹配请求,分页和Dispatch唯一性继续失败关闭。
验证
- 实际ZCode交互CLI通过renderer默认命令启动,原生/mode明确读回yolo;无模型请求。MiniMax本机官方配置loader读回bypassPermissions,实际原生TUI的/permission显示Current · Full access且配置字节未变。参数消费者覆盖默认与显式收紧,Orca两个已释放worker的真实只读库存消费者通过,旧版对同库存复现拒绝。
- 原业务provider lease未由本轮直接结算;不得把只读库存兼容证明扩大为实际release已完成。不把历史build业务验收改记为yolo长程业务验证,不声称所有可选backend或长期指令稳定性已验。
[2.33.0] - 2026-10-01
新增
- 提供显式借用预建 long-lived 工作树的首次原生 ZCode 接入合同,绑定 Git/Orca 身份、快照、唯一 writer 与独占锁;保持默认拒绝已有树,失败和编排清理保留原分支、工作树与批准资产。
改进
- 显式选择 MiniMax Code 后默认通过 Orca terminal-managed 派发,统一显示工作树、分支和终端;Orca 不可用时失败关闭,保留
--no-orca-mode显式直连,不扩张日常 backend 池。
验证
- 冻结候选完成62项维护命令;53个借用fixture与独立消费者关闭旧helper替换、未知writer漏检问题。可信扫描原始high/hard信号保留,以真实消费者及PM限定能力复核说明上下文,正式Harness证据门通过;不声称长期指令稳定性已验。
- MiniMax默认Orca真实交互CLI完成独立probe文件任务,PM3/3测试与value postflight通过;同一会话16条assistant模型响应与16条HTTP200事件均为MiniMax-M3.1-Flash-Preview。原生usage精确组合绑定、日志同session/turn/model数量组复核,未证明逐responseId的HTTP直连或精确计费。
- 本轮Mcode/launcher及基线后代确认退出,默认残余shell逐项核对后正式close-all,终端库存为0;long-lived测试树与分支按合同保留证据。MiniMaxsupervised Task/Dispatch仍未支持。
- 本机借用入口完整cwd库存依赖未满足,真实borrowed-native启动/结算NOT_VERIFIED并泊车;不放宽未知拒绝,不把fixture通过推广到现有业务树。
[2.32.0] - 2026-10-01
新增
- 为用户指定的 ZCode CLI 提供显式原生 Orca supervised 路径:使用 1.4.218 起的首次 composer 等待与唯一 Task 投递,保持交互 CLI 和既有启动环境。
- 增加 owner-only、短时、单次启动请求桥及原生回执核对,绑定 Session Context、authority、工作树、runtime 与启动脚本;核对启动 created 与结算时 live ownership,尊重用户接管保护。
文档完善
- 补充原生启动、默认 ZCode 回退、模型操作、版本与权限边界;保留可选后端不进默认池、账号规则由本地私有 Skill 提供的合同。明确单worker的build/edit/plan/yolo配置与CLI审批接续,不改全局权限、不重发已投递Task。
验证
- 完整维护矩阵61/61命令通过,独立审查关闭重放与nonready两个阻塞;真实Orca原生同会话完成Flash阶段35项测试、切换GLM-5.3及3项定向反例、唯一worker_done succeeded与Delivery验收。release返回用户接管保护retained,随后ack通过;用户明确授权后两条测试终端关闭与退出确认,研究认证副本精确删除、日志与证据保留,本轮临时资源已收口。coordinator-owned自动关闭仍未验证;不将人工关闭当作自动release。
[2.31.3] - 2026-10-01
修复
- 正确消费原生 Orca 的未满足退出码:仅严格有效的
ok=true / satisfied=false配合退出1可同句柄有界重等;退出1却宣称就绪、其他非0退出及异常回执均停止,保留资源并保持零投递。
验证
- 增加原生 CLI handler 的隔离契约回放及真实 shell 退出码消费者回归,覆盖普通/supervised、错绑、多JSON、timeout/stale错误;不扩大为 ZCode Orca 或完整生命周期的真机验收。
- 公开文档仅维护私有账号 Skill 的版本感知调用合同;真实私有运行与安装证据由私有Skill维护,不在公开任务卡承载。
- ZCode同一原生tmux交互会话完成代码/256项回归及refs合同两阶段,RESULT ACCEPT、STATUS done、tracked diff为0、value postflight通过;原生记录确认实际
GLM-5.3-Flash与切换后的GLM-5.3请求完成、重试无异常。仍为prompt-only,目录枚举越scope已记录,机械scope、Orca TUI及精确计费未验证。
文档完善
- 补充私有账号 Skill 的版本感知派发前校验调用:具名观测/计划、现场重读、失败停止,瞬时通过不当持续身份锁;保留公开包仅由PM调用的边界。
- 明确已验ZCode tmux交互路径与尚未验证的Orca TUI就绪边界,避免将终端可写、composer或hook安装状态扩大为兼容成功。
[2.31.2] - 2026-10-01
修复
- Orca worker 启动仅在明确的
ok=true/wait.satisfied=true回执后投递;超时同句柄有界重等一次,异常或仍未就绪则失败并保留精确终端/工作树供恢复,supervised 仍只由 worker-start 注入任务。
验证
- MiniMax Code 的真实 Orca terminal-managed 文件任务已独立验收,PM 的3项测试通过;15条原生响应记录确认实际 minimax / MiniMax-M3.1-Flash-Preview,任务结束后终端关闭。
- ZCode tmux fallback 的个人 Coding Plan / GLM-5.3-Flash 文件任务已有13条 completed 记录、0 retry和3项测试通过,独立产物验收
ACCEPT(限tmux实际任务);临时研究副本删除、tmux关闭。Orca 两次 terminal_handle_stale 且0业务send,Orca/supervised/settlement及机械scope/hook仍NOT_VERIFIED;共享原件哈希仅进程内断言,独立before/after重放未验证。
[2.31.1] - 2026-10-01
新增
- 提供默认关闭的本地账号调度 Skill 调用合同;账号、额度和刷新卡实现保留于独立私人 Skill,公开包仅说明 PM 调用及失败停止边界,不自动执行账号切换。
修复
- 修正 Hermes 环境探针在已识别 Codex 宿主下误报失败,以及 tmux smoke 重建同一 fixture 时截空 policy 的问题;保留生产门禁与隔离 socket。
[2.31.0] - 2026-09-30
新增
- 重点新增独立 ZCode CLI(
zcode-cli)和 MiniMax Code CLI(minimax-code/mcode)的交互/batch 命令、身份检查与依赖入口;原生参数按本机帮助核对,不误套 Claude Code flags。 - 新增独立 Qoder CN(
qoder-cn)与千问办公 bundled coding(qwenwork-cn)按需入口;同名 qoderclicn 按实路径区分,千问配置目录显式绑定,原生办公 tools 单独说明。
改进
- 保留 CodeBuddy,移除 QoderWork backend/别名与旧 helper 的启动能力;拒绝旧 bundle/软链伪装成 Qoder CN。
- 明确能力支持不等于默认派发:以上可选 backend 不加入日常 Claude Code/Codex 池或 quota 默认链,只在用户指定时选择;新 worker 能力不增加 PM host。
- 新 CLI 未集成编排 hook,必须显式声明 prompt-only 降级;不自动接受未验证 dialog,模型/权限选项错误明确拒绝。
验证
- 原生 ZCode TUI 的个人 Coding Plan 模型列表与切换、GLM-5.3/Flash 各一次真实请求及服务端 Pro 套餐/额度已核对;记录 CLI 账号关联与 app-server 宿主权限区别、缺 reasoning 导致静默回落的行为。逐请求积分扣分和完整 Orca 生命周期仍未验证,见 ref 28 与 TASKS。
- CLI 帮助与隔离 argv、正反身份/策略用例及维护回归结果记录在 TASKS 的 OPTIONAL-CLI-BACKENDS 卡。帮助/隔离 stub 不能证明 provider 或 supervised 生命周期;未验证范围保持
NOT_VERIFIED。
[2.30.5] - 2026-09-29
新增(修正"远程终端没有真实推进")
spawn-worker-remote.sh spawn --prompt-file F:spawn 后把任务书经orca terminal send --terminal <handle> --environment <配对名>投进节点终端——节点侧 spawn 本就对 TUI 投过通用 preamble("详细指令将由 PM 后续投递"),本步补上真正的任务书,TUI 实时渲染、双机 Orca UI 可见真实推进。修正 v2.30.0-2.30.4 E2E 用claude -p内嵌任务的错误模式(-p全程缓冲输出,终端看不到任何推进,且绕开 terminal-managed 的 checkpoint 契约)。- 细节:句柄从节点 METADATA
.session.orca.terminal_handle经 ssh 读取;需 personal config 节点段新增可选orca_environment字段(Orca 配对名),缺失时打印手动补投命令而非静默跳过;send 失败重试一次(10s,吸收 TUI 就绪抖动);投递结果与任务书 sha256 记入 PM 软账prompt段。任务书要求:用 Edit 工具改文件(绕开 shell 追加白名单坑)、按 checkpoint 契约写 STATUS.json(建议基于templates/worker-prompt.md生成)。
文档完善(2026-09-30 独立审查)
- 在 TASKS.md 登记回执并发消费、远程 cleanup CLI 合同和跨主机路径三项复核任务。仅登记确认问题、证据与正反验收;未修复运行代码、未提升实现版本或声明完整运行通过。
后续文档维护检查点(2026-10-02)
- 收敛06/08/09/10与legacy driver的24,五份参考2910→467行;保留运行合同、旧诊断入口与按需读取路由,不修改脚本、配置或默认backend。
- 本地命令生成86项、参数/帮助9项及77处链接/锚点检查通过;上述检查基于当前本机运行基线,不代表本次文档提交包含所有后续功能实现或完成新版本发布。
- 新上下文Agent前向行为、真实模型任务与长期稳定性未重新验证。文档使用的后续指南/运行能力须与对应功能提交一并集成;本次仅为文档检查点。
[2.30.4] - 2026-09-29
新增(用户授权产品化)
spawn-worker-remote.sh spawn --trust-worktree(默认关闭):节点侧预置 Claude Code 工作区信任(~/.claude.jsonprojects 段hasTrustDialogAccepted=true,覆盖 remote_root 与可预测的 orca worktree 路径)。背景:headless 远程 worktree 无法弹 trust dialog,未信任时 permissions.allow 整体被忽略、acceptEdits也不放行 git/gh 等 Bash 步骤,worker 能改文件但无法交付(真机 E2E 实测卡点)。写入动作记入 PM 软账pm.trust_preinstalled供审计。
[2.30.3] - 2026-09-29
新增
spawn-worker-remote.sh spawn --remote-env KEY=VALUE(可重复):在节点侧 spawn-worker.sh 之前 export 的调优变量(unset 继承 provider env 之后注入),用于按节点设置如SPAWN_WORKER_MEM_BUDGET_BYTES——真机 E2E 实测 Air 当前可回收内存 ~2GiB 低于默认 3GiB/worker 预算,按节点调低预算即可放行 smoke 级 worker 而无须改全局默认。
[2.30.2] - 2026-09-29
修复
spawn-worker.sh的remote_receipt_consume调用改为显式--file形状(原位置参数传法 consume 解析器不识别,节点侧直接 exit 64——真机 E2E 首次完整 spawn 实测抓到;mock 测试未覆盖节点侧真实执行路径,本条附带调用形状契约测试防回归)。零副作用序保证兑现:该失败发生在 harness 门(任何 worktree/lease/terminal 副作用之前),receipt 由 PM 侧回收。
[2.30.1] - 2026-09-29
修复(真机 E2E 实测暴露)
remote-node-probe.py新增节点运行时三道前置门:bash 主版本 ≥4(spawn-worker.sh 依赖 bash5 数组语义——bash 3.2 在set -u下空数组展开即 unbound variable,Air 实测复现)、登录 shell 下git --version可用、python3 --version可用;任一不满足 exit 3 并给出修复提示(macOS 上 git/python3/rsync/brew 均可能是 Xcode shim,CLT license 未接受时整体不可用——Air 实测)。- bash≥4 门按「登录 shell
command -v bash→ /opt/homebrew/bin/bash → /usr/local/bin/bash」顺序解析绝对路径并写入 probe 输出runtime.bash_path(不要求节点改登录 PATH——Air 实测 /opt/homebrew/bin 在登录 PATH 中排在 /usr/bin 之后);spawn-worker-remote.sh远端调用改用该路径execspawn-worker.sh。 - receipt 传输从 rsync 改为
ssh cat >流式写入:macOS 的 rsync 是 Xcode shim 同受 license 状态影响,ssh cat 只依赖 ssh 通道;远端路径整体单引号包裹不踩 shell 词法。 remote_nodes机制文档补节点前置要求(bash≥4 / git / python3 / ssh 免密 / ORCA 可选)。
[2.30.0] - 2026-09-29
新增
- 远程节点 Worker 派发(M0:SSH 桥,
references/25-remote-node-dispatch.md,DEC-2026-09-29-REMOTE-NODE-DISPATCH):PM 用scripts/spawn-worker-remote.sh把 Worker 经 ssh 派到 personal configremote_nodes声明的远程节点——节点本机的 spawn-worker.sh 原样跑全套门禁,worker 读节点自己的 env/key(双机双 key 池并发 + 本机资源卸载)。配套:scripts/remote-dispatch-receipt.sh:一次性 dispatch receipt(nonce + TTL≤policy 上限 + 绑定 node/harness/chain/backend/branch/session + consumed 不可逆 chmod 400);spawn-worker.sh --remote-dispatch-receipt在 ps 祖先链不可证明的 ssh 环境以 receipt 载明的 harness/chain 走原版最小权限交集(authority 不放大;与--pm-harness互斥;harness-backend-policy.json remote_dispatch.enabled=false节点侧全局禁用)。无 receipt 时主链行为逐字节不变。scripts/remote-node-probe.py:节点容量/前置条件探测(load15/活跃会话/内存/磁盘容量门;fetch 后 origin/main 双端基线门;skill 副本版本门;claude 登录 shell 可用性;时钟偏差),退出码 0/3/4/65/64 与 spawn-worker-remote 一致。spawn-worker-remote.sh spawn|provision|status|cleanup:spawn(PM harness 预检 + 基线门 + PM 软账自限 max_workers + receipt 传输 + ssh 调节点 spawn,分支强制node-<节点>/前缀 +--base-ref origin/main+ 前置 unset provider env 清单);provision(节点缺项目路径时 clone + skill 随仓库校验 + 节点侧 orca-register-project 注册,spawn --provision自动补装);status(ssh 读 STATUS.json + gh 查 PR,软账状态回写);cleanup(PR/STATUS 终态前置 → 转发节点 pm-cleanup-worker → 删软账)。config/orchestration-personal.example.json新增remote_nodes模板段(占位符,真实节点只进 gitignored 本地配置);METADATA 新增remote_dispatch段(node/receipt_sha256/nonce/key_source_node)。
- 完成三证合同(远程 worker 完成权威):STATUS.json 终态 + 分支 push/PR 存在 + PM 侧 PR-fingerprint 验收;supervised 模式跑在远程节点在 M0 一律 NOT_VERIFIED(跨机 worker_done/Delivery 不依赖也不承诺)。
验证
- 新增
test-remote-dispatch-receipt.sh(27 断言:issue/consume/重放/过期/字段不匹配/TTL 上限/policy 开关/畸形 JSON/consume 全局变量)、test-remote-node-probe.sh(13 断言:ok/不可达 65/未配置 64/禁用 3/load 4/会话 4/基线 3/版本 3/缺 root 3/真实 fetch 通过,mock ssh 零网络)、test-spawn-worker-remote.sh(25 断言:mock ssh/rsync/gh 全链 spawn→软账→status→cleanup→provision,含 receipt 传输/远端命令构造/unset 前缀/自限 75/重复 64/非终态 cleanup 64)全绿。 - 既有回归:test-spawn-worker-flags 41/41、test-spawn-worker-metadata 31/31、test-harness-backend-policy 36/36、test-provider-lease 全过。skill-lint:Security Scan 0 critical / 0 high;Harness Failure Audit hard findings=1(pm-cleanup-worker.sh:305,origin/main 既有,非本次引入)。diff 级泄漏 grep 零命中。
- 真实节点端到端(真 ssh + 节点 ORCA worktree/terminal + PR 回流 + lease 释放)为
TASK-2026-09-29-REMOTE-NODE-M0-E2E,待 PR 合并后执行,当前 NOT_VERIFIED。
[2.29.1] - 2026-09-28
新增
pm-cleanup-worker.sh在 lifecycle 清理之前把 worker Session Context 的字段白名单摘要(branch/model/backend/PR/终态/RESULT 前 2000 字符)归档到$HOME/.hermes/plugin-data/session-pilot/workers/<session>.json,供 session-pilot 插件在 worktree 删除后继续显示收口状态。纯观测旁路:归档失败只输出PM_CLEANUP_ARCHIVE_WARN不阻塞清理;PM_CLEANUP_ARCHIVE_DIR=0显式关闭,测试用该变量隔离到临时目录。归档先于clean-worktree执行是硬约束(clean 会连.claude/agent-sessions/一起删除)。
验证
test-pm-cleanup-worker.sh新增归档断言(快照存在 + pr/final_status/branch 字段正确)并修正long-lived remote branch is retained断言的$(...)转义(旧代码在加载时立即求值导致恒假);48/48 通过。
[2.28.0] - 2026-09-24
改进
- Claude Code Worker 的默认启动命令显式使用
--permission-mode auto;provider 自动包装避免重复追加该参数。本地 hook 生效时,普通 Bash 命令交回 Claude Code 原生 auto 和 settings 判断。定向unittest等开发循环命令不再因编排层未列入精确 Shell 白名单而直接失败;正式交付仍须原样运行验证合同命令并记录退出码。 - 授权快照、PM receipt 与 METADATA 记录
shell_policy=claude_auto;其他 backend 和非 auto 模式继续使用exact_allowlist。安装授权、Orca 协议、tracked 删除及受保护 Git 操作仍由编排 hook 独立处理。 - 审查时补强 auto 模式下的受保护命令识别:带重定向、管道、环境变量前缀及
exec包装的 Git 操作仍会被检查;无法可靠解析的复合 Shell 语法失败关闭。
文档完善
- 明确 auto 模式不是 Shell 文件写范围的机械沙箱;PM 需复核真实 diff、测试和外部副作用,强范围需求继续使用精确白名单模式。
验证
test-dependency-install-guard.sh190/190、test-spawn-worker-metadata.sh31/31、test_worker_delivery_prompt.py9/9、provider 路由回归 29/29;Python 编译、Bash 语法、git diff --check通过。skill-lint Harness Failure Audit 0 finding,Security Scan 0 critical / 0 high。真实 Claude Code auto 分类器的在线批准行为为NOT_VERIFIED,不以 hook 放行冒充 CLI 最终批准。
[2.27.6] - 2026-09-21
新增
- 新增 receipt 绑定的 tracked 文件删除权限:spawn 在任何资源副作用前把任务显式
--allow-paths冻结为独立allowed_write_paths,同时写入 worker authorization snapshot、Git common-dir PM authority receipt 与 METADATA;reviewer 后续合成的 Session Context scope 不会泄漏为删除权限。 dependency-install-guard.py新增先于普通 Shell allowlist 的git rm高风险分类,只允许在 receipt 绑定的 worktree 根与分支上执行git rm -- <一个 canonical repo-relative tracked file>。路径必须与冻结数组精确相等,index 中必须是唯一 stage-0 普通文件或符号链接;scope glob、reauthorize --allow-cmd、-r/-f/--cached、多路径、目录/gitlink、pathspec、Shell 展开、绝对路径、git -C、pipe/redirect/多行与其他复合形式均不能扩权。- 将 authorization snapshot SHA-256 与真实 PM receipt 内容 SHA-256 分开记录;METADATA 不再把前者误标为 receipt hash,worker 启动门禁还会复核 receipt 在写入后、hook 启动前没有漂移。
改进
- Worker prompt 与 supervised Task 前缀要求逐字执行冻结的 verification command,不得自行添加
export/env/cd、flags、命令替换、pipe/redirect 或多行包装;命令不适用时请求 PM 修正权限。 - 明确
prompt_only_degraded的 Codex/ZCode 没有机械删除保护:高风险删除必须改用 hook-enabled backend,或由 PM 核对 receipt、路径与索引后执行,不得仅凭提示宣称已强制。 - metadata 数组序列化兼容 macOS Bash 3.2 的空 indexed array +
set -u行为,避免空删除范围在写 METADATA 时误报 unbound variable。
验证
test-dependency-install-guard.sh在 Homebrew Bash 与 macOS/bin/bash3.2 均为 170/170,覆盖普通文件、符号链接、worktree 已缺失但 index 仍跟踪的文件,以及无范围、receipt hash/worktree/branch 漂移、untracked、范围外、#路径、glob、目录、gitlink、pathspec、flags、多路径、绝对 git、git -C、shell/eval 包装(含递归深度上限失败关闭)、动态 executable、inline Git alias、复合/pipe/redirect/multiline 与拒绝前后 index/worktree 不变。test-spawn-worker-metadata.sh在两套 Bash 均为 31/31;test_worker_delivery_prompt.py为 9/9;Python 编译检查通过。
[2.27.5] - 2026-09-21
修复
- supervised 资源清理不再在无 Run、仅默认第一页的 WorkerList 上先执行
worker-release。清理链现在从 Session Context 读取精确 Run,以--limit 100遍历 opaque cursor,并用冻结的page.total与实际行数证明结果完整、要求目标 Dispatch 在同一 Run 中唯一出现;前置查询的缺页、total 漂移/超限、scope/run 漂移、空或循环游标、目标缺失/重复、非法响应和读取失败全部在 lifecycle、tmux session、terminal、worktree 与分支 mutation 前失败关闭。reclaimablerelease 后重读异常时,release 可能已发生,但后续 terminal、worktree 与分支 mutation 全部停止。 clean-worktree.sh只对完整预检后的reclaimable执行一次精确 release,并在 release 后重新读取完整 WorkerList;released不重复 release,retained/external_terminal继续要求 settled 状态与 metadata 句柄精确一致,close 后还必须由精确 handle 的结构化 show 回执证明connected=false且writable=false,否则保留 terminal 与文件现场。post-merge-cleanup.sh与pm-orchestrate account release复用同一 Run-scoped 分页查询,避免前置门禁或 provider lease 结算继续漏掉后页目标;pm-cleanup-worker.sh把远端分支删除移到 lifecycle/worktree/local cleanup 成功之后,WorkerList 预检拒绝时不再留下“远端已删、资源仍活”的部分状态。- supervised cleanup 现在把
jq作为硬依赖;缺少解析能力时不再把存在的 Session Context 降级成无生命周期信息。
文档完善
TASKS.md增加IN_PROGRESS状态和分层执行波次,修正 WorkerList 分页合同、Git tracked 文件删除设计、通信任务优先级、Hermes 观察证据计数与复合状态;后续 Agent 可直接从不可变起点、允许范围和定向验证命令接手。- SKILL 主文档与 Orca Worker/PM reference 明确完整分页、唯一 Dispatch、零 mutation 失败边界和 release 后重读合同;维护者矩阵纳入 WorkerList 专项故障注入。
验证
- 新增
test-clean-worktree-worker-list.sh,Homebrew Bash 与 macOS/bin/bash3.2 均为 211/211:覆盖首/后页命中、缺失/重复、total 缺口/漂移/超限、100 页上限、非法 page/scope/cursor、读取失败、缺 run_id、active/pending、--keep-worktree绕行、reclaimable 重读、retained external 精确句柄与断开读回,以及前置失败零 release/tmux/terminal/worktree mutation。 - 维护者完整矩阵 143 个命令通过;
test_pm_sender_binding.py为 15/15、post-merge cleanup 为 94/94、PM cleanup 为 46/46、control-plane smoke 通过。真实 Orca worker smoke 因环境缺少terminal.multiplex.v1以 rc=77 明确跳过。 - 真实 Orca runtime 当前未运行;本版本验证范围是版本匹配 CLI 合同、确定性 fake CLI、临时 Git 仓与维护矩阵,真实 provider/online lifecycle 仍为
NOT_VERIFIED。
[2.27.4] - 2026-09-20
修复
- 修复
spawn-worker-deps.sh无效DEPS_MODE诊断中变量与中文全角括号邻接,在set -u下被 Bash 误解析为另一变量名并提前崩溃的问题;新增稳定退出码与诊断回归。 - 修复 Hermes backend 策略测试同类变量插值问题,并把“当前进程祖先链无法完整证明”(rc=67)明确作为环境探针跳过条件;生产门禁仍按原合同 fail-closed。
- 修复旧通用 backend-policy 测试对宿主进程命名空间的隐式依赖:保留所有可读真实帧,只在测试夹具内把不可见的最外层边界补为中性 shell,使具名祖先链正反例在容器/CI 中可重复;生产检测逻辑不变。
- 修复内存预算显式 opt-out 的顺序错误:
SPAWN_WORKER_MEM_BUDGET_BYTES=0现在即使宿主遥测在沙箱/CI 中全部不可读也稳定返回disabled,可读数据仍按最佳努力保留;默认非零预算继续对不可探测环境 fail-closed。 - 修复
pm-orchestrate reauthorize未跟进 completion authority receipt 契约的回归:重授权现在从 Git common-dir 推导原始回执,交叉核对 session/worktree/branch/runtime 与受信 METADATA,在任何新终端副作用前拒绝缺失或漂移身份;register 只在该受限替换路径内轮换 terminal/Dispatch/completion receipt,普通注册仍禁止用可写 metadata 换权威。receipt 替换与 METADATA 写回组成有补偿回滚的事务:后者失败时恢复旧 receipt,再由 PM 回收新终端,避免仍存活的旧 Worker 被意外剥夺完成权限。 - 维护测试不再把受限 sandbox 的宿主遥测缺失误报为功能回归:真实机器 smoke 在可探测时验证额度,在不可探测时验证稳定
unprobeable、无slots的 fail-closed 合同。 - 为启动、依赖安装、provider lease 与 Worker prompt 回归补齐测试私有的进程/tmux 夹具,使其只验证各自合同,不依赖当前宿主命名空间或用户 tmux server;两个真实 tmux smoke 都改用独立 socket,在 sandbox 明确禁止创建时报告环境跳过,并严格检查私有资源清理错误,而不是吞掉退出码或伪造通过。
- 将 Hermes 专项
scripts/tests/test-harness-backend-policy.sh纳入维护者完整验证矩阵,避免只运行旧的通用策略测试而漏掉宿主签名回归。
文档完善
- 将本 Skill 的
TASKS.md、DECISIONS.md纳入版本控制,按READY / RESTART_REQUIRED / BLOCKED / PARKED / OBSERVE / COMPLETE重整任务状态、依赖、允许范围、验收命令和接手模板;PR #145/#147 等已合并事实不再保留为待处理状态。 - 把 Hermes 首次实战遗留拆成 Bash 版本诊断、首次交互安全设计、GitHub merge 恢复三张独立卡;只有版本诊断进入可领取维护池,另外两项继续停放,避免其他 Agent 从一张混合卡擅自扩大权限。
- 同步根 README 技能版本与最近更新区、Orca Worker/PM 参考页版本头,并把 ZCode driver safety 参考页接入
SKILL.md按需读取地图。
验证
- 维护者确定性矩阵连续运行至
autopilot facts 21/21全部通过;重授权专项为193 pass / 0 fail(含 receipt 已替换而 METADATA 写回失败的故障注入与旧权限恢复),内存预算为58 pass / 0 fail,依赖安装门禁为129 pass / 0 fail,Hermes 专项为23 pass / 0 fail / 1 environment skip。 quick_validate.py通过;Harness Failure Audit 为PASS;Security Scan 为0 critical / 0 high,其余命中为既有测试攻击样例、受控子进程/文件访问等审计项。smoke-orca-control-plane.sh通过;真实 tmux 两个 smoke 因 sandbox 禁止隔离 socket 明确跳过,真实 Orca worker smoke 因当前 runtime 缺terminal.multiplex.v1以 rc=77 跳过。真实 provider 全生命周期与全 Skill instruction stability 仍为NOT_VERIFIED,不得据此扩张结论。
边界
- 本版本只修复已确认回归并整理维护上下文,不实现 WorkerList 分页、
git rm权限、Cross-PM Handoff、Peer Comms、通信 E2E 或 ZCode RuntimeAdapter。
[2.27.3] - 2026-09-19
修复
spawn-worker.sh的--base-ref守卫字符类由[0-9a-f]扩为[0-9a-fA-F]:大写 sha(如96A304DF…)与大小写混合 sha 在任何 worktree/provider/terminal 副作用前同样以SPAWN_WORKER_BASE_REF_MUST_BE_REF: <值>拒绝并退出。事故:原守卫只匹配小写十六进制,PM 探针实证大写 sha rc=0 放行后被原样写入METADATA.base_ref,重现 v2.27.1 已堵的pm-cleanup-worker死锁(INTEGRATION_TARGET_MISMATCHargument=main vs metadata=sha 与PR_BASE_MISMATCHexpected=sha vs actual=main)。- 第二分支「真实 ref 名放行」语义不变:
refs/heads|<value>/refs/remotes/<value>/refs/tags/<value>大小写敏感,分支名恰为大写 hex 形态且真实存在时(fixtureDEADBEEF2)仍放行;该路径对应「校验」而非「拦截」。
文档
- SKILL.md §3.3 显式标注「字符类大小写敏感」与「分支名恰为大写 hex 形态且真实存在时仍放行」。
验证
test-spawn-worker-flags.sh新增三个用例:大写 40-hex(96A304DF…)拒绝且 rc=64 + 无 worktree/METADATA 副作用;大小写混合 40-hex(AbCdEf…)拒绝;临时 fixture 仓库建分支DEADBEEF2(9 位大写 hex)后传该名--base-ref,验证不触发SPAWN_WORKER_BASE_REF_MUST_BE_REF、继续后续流程(或既有早停)。
[2.27.2] - 2026-09-17
修复
- Supervised 完成权限绑定启动时 PM authority 与 live Dispatch 身份,保留 capability 摘要而非明文(completion authority 绑定并入 2.24.0+ 的 ask/check trusted-handle 门禁:--from/--terminal 必须等于环境或 METADATA 冻结的唯一 worker handle);preamble 原生反斜杠续行的 worker_done 现可被 Shell 门禁识别原样放行,拒绝 metadata 换权威、陈旧 runtime/process/run 和精确 Shell allowlist 绕过。
- 手动 register 必须传真实
--authority-receipt,spawn 自动传递;无有效 authority 时在 worker-start 前停止。完成校验失败后上报协议阻塞,不变形重试。 - agent-unconfigured 恢复从真实 Git common-dir 与安全 session 推导既有 PM receipt,核对身份后才注入或重绑;缺失、改址或错配时停止,不临时重建授权。
- PM run-bind 对畸形 JSON 和缺失/错误身份 fail-closed;两条清理路径按精确 OID 原子删除远端分支,远端并发推进时保留较新提交并报告待清理。
验证
- 增加完成权限生产/消费反例、绑定异常响应,以及真实临时 bare remote 的删除竞态用例;与既有 runtime 身份和资源结算保护一并回归。真实 provider supervised 完整生命周期仍为
NOT_VERIFIED,本地测试不代表已完成生产验收。
[2.27.1] - 2026-09-17
修复
spawn-worker.sh的--base-ref解析后、任何 worktree/provider/terminal/Dispatch 副作用之前新增 40-hex sha 拒绝门:若值匹配^[0-9a-f]{40}$,或 7—40 位纯十六进制且 git 能解析为 commit 但不是真实 ref(refs/heads/<v>/refs/remotes/<v>/refs/tags/<v>),打印SPAWN_WORKER_BASE_REF_MUST_BE_REF: <值>并以非零退出。引用名(main、origin/main、refs/heads/x)行为不变。事故:原样记录到METADATA.base_ref的 sha 会让pm-cleanup-worker在INTEGRATION_TARGET_MISMATCH(argument=main vs metadata=sha)与PR_BASE_MISMATCH(expected=sha vs actual=main)之间死锁。- SKILL.md §3.3 新增一句说明
--base-ref只接受引用名、不接受裸 sha。
验证
test-spawn-worker-flags.sh新增两个用例:传 40-hex 拒绝且退出前未创建 worktree/未写 METADATA;传main正常进入后续(沿用既有--dry-run早停机制)。
[2.27.0] - 2026-09-15
改进
- hermes PM 宿主授权面由 claude-code/codex 扩为全部受支持 worker backend(claude-code、codex、codebuddy、qoderwork-cn、zcode),用户明确授权;测试断言同步(hermes→codebuddy / hermes→qoderwork-cn 嵌套交集由 fail-closed 反转为放行)。
[2.26.0] - 2026-09-15
新增
- hermes 接入 PM 宿主白名单(用户明确授权,记录于
config/harness-backend-policy.jsonpolicy_notes):Hermes Agent 作为 PM 派发 claude-code/codex worker。宿主识别走路径级签名——进程帧含Hermes.appbundle 路径或.hermes/hermes-agent/安装目录才算 hermes,裸hermes词不作签名防止无关路径误命中;canonical_harness_backend收hermes别名。帧匹配逻辑提取为pm_harness_candidate_for_framehelper(行为保持),配套回归scripts/tests/test-harness-backend-policy.sh(签名匹配/白名单交集/deny-by-default/本机 Hermes 祖先链实测)。
[2.25.0] - 2026-09-14
新增
- sub2api 网关四条积分 lane(qwenworkai / lobsterai / autoclaw / codebuddy)接入额度 summary 生产链:
scripts/quota_summary_sub2api.py从网关/ui/api/quota聚合端点拉取并合并写入 summary 合同(只更新这四条 lane、其余 lane 原样保留;qw 每日 100 当日过期、lobster campaign 分项临期 → lane 记录带remaining_total/credit_items,PM 派简单批量任务前先看临期分项,把当日过期积分在过期前吃掉)。数据流与 lane 定义读取references/24-sub2api-quota-producer.md(纯知识文档,脚本不读取);配套测试tests/test-quota-summary-sub2api.py(4 用例)。
[2.24.0] - 2026-09-13
新增
- Supervised Task 强制前缀加入 Worker ask/resume 与自然检查点收件协议:阻塞问题超时、取消或断线后只恢复原 message ID;新文件前、每次 scoped test 后及
worker_done前排空 consuming check,处理整批后仅 ack 自有 Worker Delivery,consumer_fenced或dispatch_inactive时立即停止。 - PM wait 为完整 FIFO Delivery 生成顺序分类 receipt,明确 question、escalation、worker_done 的不同处置义务;reply 支持同一未知结果的
--retry-request精确恢复,并返回不夸大的持久回复 receipt。
修复
- Worker Shell 门禁不再允许以
peek/all/unread冒充已处理 guidance,也拒绝 resume 时附带新 options、无 wait 的 timeout/types 与无界 wait;只允许绑定自身 handle 的 Worker Delivery ack,coordinator handle ack、reply、release、stop 和 Task mutation 权限维持拒绝。 - PM wait 同时校验 result 与逐消息 Run,拒绝 alias 冲突、超过 50 条、空/非字符串 ID、缺少显式 null 的空批 Delivery 或 count 不一致。ack 除精确 Run 与 acknowledged Delivery ID 外,还完整校验同一响应交付的下一批、拒绝旧/新 Delivery 复用同一 ID,并单列 next Delivery receipt,避免确认上一批时遗漏下一批。reply 的 mutation 前预检改按 Orca 1.4.200 真实 question 行校验
dispatch:<dispatch> → run:<run>路由、message-id thread 与 JSON-string Task/Dispatch payload,再用 post-reply asker 绑定 worker terminal;post-reply 对所有出现的 aliases 保留显式 null 并要求 reply 使用独立 message ID。跨 Dispatch、复用 question ID 或任一路由/alias 漂移继续失败关闭。所有 receipt 均区分入队、可见、消费、回复、执行和业务完成,避免把队列动作误报为工作已执行。 - 修正上一版把
--retry-request当作业务自定义键的真实 CLI 不兼容:首次 send/reply 必须省略,恢复时只接受 Orca 对未知 mutation 回传的 UUID;transport retry 不再混入业务 payload 或请求摘要,避免原命令与恢复参数漂移。
验证
- 新增 stateful fake-Orca 回归,覆盖旧 Delivery 重放、50 条 FIFO 边界、逐消息 Run 漂移、显式 null 空批、ack 响应内下一批及畸形/同 ID 批次、真实 Orca question message row、post-reply 显式 null alias/复用 question ID、同 Orca UUID 幂等回复与换 UUID 重复回复;同步扩展真实 Task spec、sender argv、transport retry UUID 和 Shell 门禁正反例。fake 测试不替代真实跨 session 消息层或 provider 全生命周期验证。
- 在 Orca 1.4.200 的两个隔离 shell terminal 上完成真实消息层正例:ask timeout 保留原 message ID、PM Delivery 在 ack 前同批重放、重复同答案复用原 reply、resume 得到答案、guidance 在 Worker 自有 Delivery 中消费并 ack 后不再 unread。测试 Dispatch 已 fence、两个精确 terminal 已关闭;未启动 provider,不能据此声明 backend 全生命周期通过。
[2.23.9] - 2026-09-13
新增
- PM supervised
send增加显式--message-contract:以 Orca 原生消息承载经worker-show复验的 Run/Task/Dispatch/worker、sender、thread、correlation、expected action 与 typed evidence,不另建聊天层。 - 增加只读
inbox命令,固定使用check --peek观察当前 coordinator inbox,不重绑 Run、不改 metadata、不消费或 ack Delivery;receipt 只统计精确 Run/Task/Dispatch,可选再按 thread+correlation 双过滤。
修复
- 明确
durably_enqueued → delivered_visible → consumed → replied → action_started → business_completed六层证据边界;Dispatch send 只有在同一真实 relay 的 destination、dispatchId 与 messageId 均验证后才生成 enqueue receipt,不接受旁支或旧形状 message ID,也不把发送成功误读为已送达、已执行、已完成。原生 thread 改为承载 correlation,业务 thread 留在 payload,使原生无 payload reply 可在严格双过滤下关联;这种可见性仍不证明执行过 reply。 - 对消息类型、优先级、标识符、仓库相对 evidence path 和所有用户可控消息字段(含 inbox 的显式/记录 sender 与 worker handle)做敏感载荷检查;同一 retry ID 只允许完全相同的请求摘要,变化时在首次 Orca 调用前拒绝。runtime/sender 漂移、Task/Dispatch 错绑、缺消息 provenance、顶层或 payload lifecycle/sender/recipient/type 别名冲突、错 coordinator recipient 或非 live 发送目标继续失败关闭。
验证
- 新增 fake-Orca 参数级回归,使用当前真实 relay/check/reply schema 覆盖权威 worker-show 关系、message ID/请求摘要 receipt、relay 缺失/错目标/旁支 ID、原生 argv/payload、normal priority、相同与冲突 retry、旧 send 兼容、敏感字段零副作用拒绝、peek 不消费、空/缺 sender/错 sender/缺 provenance/跨 Dispatch/顶层与 payload 别名冲突 inbox、无 payload 原生 reply correlation bridge、stale runtime/sender 与异常 receipt。
[2.23.8] - 2026-09-13
修复
- Orca worktree 创建默认并固定使用
--setup skip,避免 repo Setup 在 Session Context、安装门禁和 scope hook 写入前执行依赖安装或其他环境变更。 - 新增
--orca-setup-mode审计入口;inherit/run在任何 worktree、provider、terminal 或 Dispatch 副作用前稳定拒绝,且明确不继承--allow-install-command的后置授权。 - Session metadata 记录实际
setup_mode;tmux 路径写入not_applicable,避免把未发生的 Orca Setup 冒充已验证事实。
验证
- 增加 helper 与完整入口正反例:核验正常路径真实 argv 为
--setup skip,inherit/run零 Orca mutation,单独安装授权不能绕过前置拒绝,并保持 supervised 成功路径和 tmux 语义不变。
[2.23.7] - 2026-09-13
改进
- 实际 supervised Task spec 补齐最小实施、scoped 验证、授权文件提交与唯一 Session Context RESULT 规则;review-only/no-change 不造空提交,路径绑定缺失或冲突时停止猜测,不扩 Shell、安装或 PR 权限。
- 各后端统一注入仅用于定位的 WORKER_SESSION_CONTEXT,并核对既有 guard 路径;合法 Codex prompt-only 降级且无 scope 的启动也能定位交付目录,不把路径注入冒充 guard 已启用。
- 补任务辅助命令的既有精确授权流程与根级 .venv opt-in 复用指引,说明软链忽略陷阱、共享 exclude 和源环境保护。
- 启动失败恢复以 request/Dispatch/资源归属回执为依据,撤下按空标题直接清终端的建议;区分原生与 external terminal 回收、未知结果恢复、信任弹窗授权和心跳/业务进度。
验证
- 新增真实 Task 构造/启动命令、Session Context 绑定、真实 guard hook 及 sender 契约正反例;tmux smoke 使用独立 socket 和无转发 Orca stub,验证兼容路径且不触真实 Orca 资源。代表性脚本证据不替代真实 provider 全生命周期证明。
- 跨 Claude/Codex、实施者/reviewer、有无 scope 的真实生成命令执行交付路径检查,并验证冲突绑定继续拒绝,避免仅测试具备 hook 的后端产生假覆盖。
[2.23.6] - 2026-09-13
修复
- PM 与 Wave 支持显式 sender,核验精确终端、当前 runtime 和 Run/coordinator,避免非 Orca PM 缺身份或误用已关闭终端。已有 session 绑定不被环境覆盖;只读入口不重绑或改写 metadata。
- Single Worker 在 quota/mem 通过后、lease/worktree/terminal 创建前准备 Run;预建 Wave 只读核验,不重复创建 Task。metadata 保留 runtime 身份,旧记录的迁移只证明当前绑定,不追认历史连续性。
- send/reply/Run 使用官方 --from,check/ack 使用 --terminal;release/retain 遵守仅 --dispatch 的官方合同并做前置身份核验。修正 --no-orca-mode 帮助,区分 tmux 控制路径和可能保留的只读宿主探测。
验证
- 增加 sender、关闭/漂移身份、早期零 Worker 资源、只读入口和实际 argv 回归;随行修正已有 metadata Git 权限事实与旧断言漂移,不改变生产权限。真实 backend 全生命周期与重启期间派发未由 fake CLI 测试证明。
- 邻接 settle、handoff、重新授权、runtime 与内存测试迁移完整 sender 回执,验证实际抵达目标分支,避免在身份前门提前退出造成假阳性;真实 Orca smoke 以只读代理验证无/错 sender 的拒绝,不用虚构 Wave 身份冒充正例。
[2.23.5] - 2026-09-13
修复
- Orca 同仓自动注册采用 Git common-dir 普通文件锁与锁内二次读取,避免多个 helper 基于同一过期快照重复注册;CLI 调用与锁等待均有界,不依赖外部 flock 命令。
- 注册请求前持久记录 pending,超时、回执丢失或身份复验失败后不再盲试 repo add;已有明确 repo.id 时必须匹配,未知标记与不安全锁文件保留并拒绝。
验证
- 增加真实多进程配合 fake CLI 的同仓竞态、独立仓并发、linked worktree、未知结果恢复、身份错配与锁安全回归;不代表 Orca UI/其他客户端也受此 helper 的锁约束,真实注册 mutation 与 provider 生命周期未验证。
[2.23.4] - 2026-09-13
技术优化
- 修正自动注册、PM 巡检和 reviewer 测试的退出码语义:只有预期的 grep 无匹配可计为零结果,读取、检测器或排序失败不得证明成功;增加故障注入回归。
- 后端授权测试改用隔离策略,同时验证默认拒绝与显式允许,不再依赖本机或发布配置中的个人授权,正式策略不变。
- 忙锁测试区分完整 CLI 观测开销与锁等待:保留真实持锁时 exit 75、state_lock_busy、零发送,直接核验非阻塞 flock,不以提高墙钟阈值冒充性能修复。
验证
- 五套定向测试通过;本次仅改测试,不代表真实 provider 生命周期或全 Skill 指令稳定性已经验证,也不包含另行审查的完成权限候选改动。
[2.23.2] - 2026-09-12
修复
- Wave receipt 冻结 runtime 身份,并通过 spawn/register 显式参数在派发链重复核对,发现重启或身份不可验证时停止相应派发;旧调用明确报告未验证,保留 consumer fencing 的最终判断。
- Provider wrapper 遵守显式单认证模式,settings/renderer 增加
--auth-type;默认双变量与空串兼容模式保留。拒绝双配置来源和 settings 相反键重载风险,不根据名称或 URL 自动改写认证选择。
验证
- 增加 runtime 身份漂移与认证有效环境的正反例;采用 fake Orca 与本地子进程探针。真实重启期间派发、Claude 配置重载及 provider 请求仍为
NOT_VERIFIED。
[2.23.1] - 2026-09-12
修复
- PR 审计对标准 unified diff 的 hunk 函数上下文注记做归一化,避免 Git 与 GitHub 渲染不同导致相同补丁无法 adopt。保留 hunk 行号与数量、文件路径、模式、内容空白和二进制载荷的差异;仓库、base/head OID、任务归属和唯一性条件维持原有校验。
- 补齐注记差异的真实 Git 仓 + fake gh 路由回归,以及范围、模式、路径、空白、内容和二进制差异的反向断言。
- diff 命令保留原始换行与非 UTF-8 字节,指纹仅按 LF 分行,防止正文中的 CR、Unicode 或垂直分隔符暴露伪 hunk/index 头并掩盖实际内容变化。
[2.23.0] - 2026-09-11
新增
- 增加 runtime/resource 只读观察与结算适配器,绑定 Run、Task、Dispatch、Worker generation、terminal、provider lease 和 Delivery;从原始命令证据重新推导唯一结算状态、缺失证据和恢复动作。
- PM reconcile 入口消费冻结 snapshot,重复执行幂等;不调用 RPC 或自动执行资源操作。
- provider lease 增加 runtime 绑定和可复验释放收据,为正常资源结算提供实际生产入口。
修复
- Task ready 与 Dispatch failed、terminal missing、abandon、历史 lease 文件缺失及 ack 单一信号均不能冒充完整结算;正常 worker_done 必须核对整批 Delivery 和精确 ack 目标。
文档完善
- 记录当前 Orca 字段来源与合成回归边界;生产 provider 及真实生命周期验证单独标记,不由本地协议测试推定。
[2.22.1] - 2026-09-07
新增
references/09-zcode-cli-worker.md新增 §11「发行版全景与上游 TUI 建模研究」:发现 npm 社区非官方终端客户端zcode-app-cli(kingsword09/zcode-cli,MIT,v3.11.2-21,--version输出带zcode-app-cli前缀;实现=从 ZCode Desktop 提取官方glm内核作 node 子进程、自带pi-tui交互层,凭证/agent 逻辑留在官方内核,README 自述 not affiliated with Z.ai),据此把 §1/§5.1 的"无 TUI"旧表述修订为按客户端区分(官方桌面捆绑 0.16.x 仍无 TUI,本 skill 现行 driver/app-server 路径不变,"官方无独立 CLI 分发"维持成立);收录上游 stablyai/orca PR #13965/#16227/#16228(未合并)对 zcode 的 TUI 建模:--version特征位发行版探测(其交互路径锚定的正是上述社区客户端)、agent-input(composer 粘贴 + 就绪三重门:进程 → composer input-ready → hook 上报 provider session)vsstartup-command(argv 一次性,fail-closed)注入分流、状态经 Claude 兼容 hook(7 事件含 PreToolUse,配置面~/.zcode/cli/config.jsonhooks.events)+ SQLite 会话库而非刮取 TUI;config.json多写者并发风险入册(本机.bak-pm/.bak-pm2/.bak-zcode-worker实证,任何写入须备份+原子写+校验);社区客户端 bin 名同为zcode,安装后须which -a zcode核对不遮蔽官方软链。§8 install-guard 的"无 PreToolUse hook 机制"历史依据标注待重验(上游证据显示 hook 存在,本机未验证,行为不变)。archive 草稿同步版本记录修订行。- 研究来源与未验证边界:上游 PR diff 通读 +
npm view zcode-app-cli+ repo README 阅读 + 本机zcode --version(0.16.5 裸号)/config 结构/ps 进程观测;社区客户端与 hook 能力均标注"未本机验证",验证项落在 TASKSTASK-2026-09-07-ZCODE-DISTRIBUTION-RESEARCH(安装属非官方第三方包,信任决策与安装授权均归用户)。
非目标(边界)
- 不改 zcode backend 行为:driver/app-server/headless 路径、install-guard 降级、身份门禁全部维持原状;发行版区分与研究结论仅入 reference,不产生新的自动探测或配置写入。
- 不安装 npm
zcode-app-cli、不修改~/.zcode/cli/config.json(多写者文件,且属用户环境副作用)。
验证
- docs-only 改动(reference + CHANGELOG + TASKS + archive 版本记录),无脚本/模板/配置/主文档变更,不在
references/19-maintainer-validation.md强制范围内;scripts/无任何解析 09 号文档的逻辑(grep 确认 references 仅作 help 文本指针),无测试联动。
[2.22.0] - 2026-09-06
新增
- Worker 默认执行权限放大(用户决策 2026-09-06:worker 隔离在专属分支 worktree 内,push+PR 是必要交付路径,常规读取不应因复合形式被拦)。
scripts/dependency-install-guard.py安全类从「裸命令白名单」升级为「分段校验」:命令按顶层;/&&/||/|切段,每段独立过段级白名单(安全读 + 安全交付),全部通过才放行。 - 段级白名单新增:
git push(本分支裸 push /-u origin HEAD/ refspec 到 feature 分支;拒--force/-f/--force-with-lease、拒 main/master 目标、拒:branch远端删除与+src:dst强推、拒--mirror/--tags/--delete/--receive-pack)、git rebase(拒--exec/-x执行逃逸)、git branch展示 flag、git remote -v、git ls-remote、git fetch(拒--upload-packfile:// 执行逃逸)、gh auth status、gh repo view、echo/which/type/jq/sort/uniq/cut/tr/basename/dirname/diff、command -v、node/npm/pnpm/yarn/bun/python3版本查询。 - 复合只读管道默认放行:
git status && git log --oneline -5、grep -rn X src | head -20、git log --format=%s | sort | uniq -c | sort -rn | head等(此前裸读命令放行但一加管道/分号即被拦,r4/r8/gov-03 实测 15+ 次误拦)。重定向仅允许/dev/null、&1/&2与临时目录(/tmp/、/private/tmp/、/var/folders/、$TMPDIR;拒绝..穿越);子 shell、输入重定向、heredoc、命令替换仍拒。 templates/worker-prompt.mdpush 政策改写:本分支 push 默认放行(force/主干/删除仍拒),identity 四件套绑定的 safe-push 仍是 OID 全链核验的强化替代;SKILL.md§3.3 新增「Worker 默认执行权限」条目;references/10-parallel-lessons.mdG31 方向 B 补 v2.22.0 落地注记。
修复
scripts/spawn-worker-metadata.sh:execution_authority.git_identity.raw_git_push_allowed由恒false改为true,与 guard 实际行为一致(此前 metadata 声称裸 push 被拒,与安全类语义脱节)。spawn-worker.sh在 identity 四件套缺失时输出SPAWN_WORKER_PUSH_PATH: raw-safe账本行,push 路径不再静默。scripts/dependency-install-guard.pyOrca 协议校验:check子命令补--terminal选项——preamble 教 worker 用orca orchestration check --terminal <handle>收协调消息,但该形式不在合法选项集内被 fail-closed 拦截(gov-03 实测 worker 连轮询 PM 消息都被拦)。
非目标(边界)
- 验证命令(
pnpm test/npm run build等)仍走 9dfb4a14 的合同绑定路径(--verify-cmd/--verification-contract→allowed_shell_commands精确串),不默认放行:保持派发合同对验证权威的单一来源。 gh api(通用读写 API)、gh repo sync(fork 分支强制覆盖)、安装类命令、xargs(读管道转任意执行)、awk(system 转义)、env 前缀命令、git -C仍 fail-closed,需精确--allow-shell-command/--allow-install-command。- 不改 identity 四件套语义:safe-push 绑定、author/committer 身份注入、OID 校验推送不变,仅不再是 push 的唯一通路。
验证
bash scripts/test-dependency-install-guard.sh:新增 35 个门禁用例(push 放行 4 + push 拒绝 7 + 复合读/重定向/版本查询/gh/jq/filter 链 17 + 穿越/upload-pack/逃逸加固 2 + 协议--terminal1 + 既有语义回归 4),全量 113/113 通过;metadata 断言同步raw_git_push_allowed == true。bash scripts/test-spawn-worker-verification.sh13/13、bash -n scripts/spawn-worker.sh通过(相邻合同不受影响)。- 真机事故复盘锚定:dsh-contract-copilot gov-01/03(2026-09-06)15 次被拦命令中,
git push三形态、gh repo sync、gh api修复后分别落入放行/继续拒绝的预期桶;ls 2>/dev/null; ...、grep | head复合读恢复可用。
[2.21.2] - 2026-09-06
新增
- SKILL §3.1 第 6 条 + §5「验证负载纪律(verification lane)」:worker 自验默认 scoped(单 spec / 定向用例 /
--bail 1);全量套件单一在飞、跨项目互斥——确需现场跑全量时先探测既有全量测试进程(如pgrep -fl 'vitest|pytest|jest|go test'),无法确认独占即退避或改 scoped(探测是尽力而为的现场信号,不建跨项目锁文件,宁可少并发不可误并发);PM 收口时的串行全量复跑是全量验证的默认归宿。验证输出一律重定向日志文件、只回传有界尾部(如tail -50)——长输出无界刷屏是会话侧 node 运行时 OOM 的喂食管。本纪律约束验证类别而不约束 worker 数量;与单进程堆顶(v2.20.0)、物理内存 lane(v2.21.0)互补:堆顶管单进程失血点,mem lane 管总量承诺,本纪律管验证执行的并发类别与输出体量。 templates/worker-prompt.mdVerification Floor 新增 scoped-first 解读与验证负载纪律条(全量探测独占 + 输出有界);既有 "typecheck, tests, and build" 底线按 scoped 优先解读。
非目标(边界)
- 不建跨项目验证互斥锁文件或全局注册表:与物理内存 lane 同哲学(现场探测、不建注册表),接受尽力而为的互斥精度,不做机械强制。
- 不改
scripts/dispatch-value-gate.py的 spec schema(dispatch-value-gate.v2不加字段):纪律落在 PM 派发合同撰写层与 worker 行为层,不动门禁脚本合同。 - 不改 §3.1 第 5 条的每波/全局活跃 worker 数策略:本纪律不限制 worker 派发数量。
验证
- 前向行为测试(无旧上下文 subagent 冷读修改后 SKILL §3.1/§5 与 worker-prompt Verification Floor,两场景:4 worker 并行派发含 2 个全量验收任务 / "让 worker 各自全量跑以加速收口"压力场景)——派发计划保留全部 worker 数量、自验 scoped、全量串行或归 PM 收口、输出有界、压力场景正确拒绝。
bash scripts/test-dispatch-value-gate.sh34/34、bash scripts/test-spawn-worker-verification.sh13/13 回归通过(本次未改脚本,确认相邻合同不受影响)。
[2.21.1] - 2026-09-06
修复
scripts/mem_budget_probe.pymemory_pressure 百分比兜底路径补齐钳位:available = total × pct/100后与 vm_stat 主路径一致地取min(available, total),病态快照(可用百分比 >100%)不再虚增可用内存(references/22 §3 声明的 [0, total] 钳位至此两条基准路径全覆盖)。- SKILL §5 OOM 识别信号脱敏:本机崩溃报告路径
~/Library/Logs/DiagnosticReports/node-*.ips改为抽象表述「系统崩溃报告目录(DiagnosticReports)中 node OOM 报告新增且时间吻合」,识别信号保留、随行 doc 资产不再含本机路径(DEC-141 边界)。
验证
scripts/test-mem-budget-probe.py53/53 通过:新增病态 fixture 用例(memory_pressure 可用百分比 150% 时availability_basis=memory_pressure_percent且钳位到物理总量),既有 52 项全量回归。bash -n scripts/spawn-worker.sh语法回归通过(本次未改其逻辑)。
[2.21.0] - 2026-09-06
新增
- 新增物理内存预算预检门
scripts/mem_budget_probe.py:读 hw.memsize 与 vm_stat / memory_pressure / vm.swapusage 现场快照,输出memory-budget.summary.v1JSON(可用安全内存、swap 压力信号、按 per-worker 预算折算的可派发额度);读取失败 exit 1 且不输出额度(fail-closed,绝不编造)。 - per-worker 预算默认 3 GiB(agent 本体约 1.2 GiB + 测试/构建余量约 2 GiB,与 v2.20.0 堆顶量级对齐);
SPAWN_WORKER_MEM_BUDGET_BYTES可调(非法值 fail-closed),=0显式关闭整道门。压力分级收紧:warn 把可承诺额度折半、critical 额度归零。 spawn-worker.sh在任何 worktree/terminal/lease/dispatch 副作用之前接线内存门:额度不足以专用退出码 4 拒绝并输出 可用/预算/缺口 诊断与SPAWN_WORKER_MEM_BUDGET_DENIED稳定标记;放行输出SPAWN_WORKER_MEM_BUDGET: available=… budget=… slots=…账本行;probe 读失败同样 fail-closed 拒绝(坏门永远不放行)。- SKILL §5 新增排队规则:额度不足不 spawn、本轮记
PARKED_FOR_MEMORY、下一轮巡检重试,同一任务连续 3 轮不足泊车并向用户报告(附 probe 输出);OOM 退避重拉前必须重跑 probe(每次 spawn 现场探测、不缓存)。 - SKILL §6 收口清单新增第 6 条:
STATUS=done但进程仍存活的 worker(含跨会话遗留)当轮即触发收口或上报,滞留进程持续挤占物理内存派发额度。 - 新增
references/22-mem-budget-lane.md(数据源、预算推导、排队状态机、与 OOM 退避交互、维护矩阵);维护矩阵references/19-maintainer-validation.md收录test-mem-budget-probe.py。
非目标(边界)
- 不建跨项目全局 worker 注册表/文件锁:现场物理探测天然覆盖跨项目占用。probe 只读、只做派发门槛,不做自动杀进程、自动降级、swap 清理等任何回收动作。quota lane 既有语义不变。
验证
- 新增
scripts/test-mem-budget-probe.py52/52 通过:vm_stat(16k/4k page size、行集差异、缺关键行/表头)、memory_pressure(关键词句式、百分比句式、垃圾输入)、vm.swapusage(M/G 后缀、零 swap)解析;swap 高压 warn 折半、critical 归零;全读失败 exit 1 且 payload 无额度字段;--jsonschema 字段稳定(key set 逐字段钉住);预算 env 覆盖与=0直通;真实机器 smoke 现场读源。E2E(fake Orca CLI,与真实 runtime 隔离):低内存 fixture 专用退出码 4 + 诊断 + 零 worktree/terminal 副作用 + 无 Session Context 残留;健康 fixture 放行并输出账本行;=0低内存直通。 - 既有矩阵回归:
test-spawn-worker-orca.sh104/104、test-spawn-worker-flags.sh31/31、test-spawn-worker-deps.sh18/18、test-spawn-worker-verification.sh13/13、bash -n scripts/spawn-worker.sh通过。
[2.20.0] - 2026-09-05
新增
spawn-worker.sh新增node_mem_cap_setup:worker 会话默认注入NODE_OPTIONS=--max-old-space-size=2048(SPAWN_WORKER_NODE_MAX_OLD_SPACE_MB可调,=0关闭;调用方已设NODE_OPTIONS时跳过不覆盖)。与 scope-guard 同款env前缀包装,tmux 与 Orca terminal 路径均生效。- SKILL §5 新增 Worker node OOM 识别与退避规则:退出码 134 / SIGABRT /
FatalProcessOutOfMemory判定后同任务不得立即重拉(下一轮巡检 + 全局并发 -1),连续 2 次 OOM 停止重拉、泊车并上报。
背景与动机
- 2026-09-05 事故复盘(badminton-lab 机器):多 worker 长输出场景下,会话内 node 进程(agent CLI / vitest worker)V8 堆无界增长触发
FatalProcessOutOfMemory → SIGABRT,PM 周期性重拉形成崩溃循环(单日 4 崩),并叠加整机内存挤压导致一次 shutdown_stall 强制重启。上游排查结论:Orca 本体(daemon/runtime)跨全部崩溃时刻存活,非宿主缺陷;止血责任在本编排层——堆上限让 worker 到限自身退出(sentinel 记 failed),退避规则阻断"更用力重试"的循环放大。
验证
bash -n语法通过;注入输出行SPAWN_WORKER_NODE_MEM_CAP进 PM 日志可审计;dry-run 路径不新增副作用(包装只改 COMMAND 字符串)。
[2.19.0] - 2026-09-05
新增
- 新增 zcode 额度 lane 的 summary 生产适配器
scripts/quota_summary_zcode.py:把本机 zcode-quota 监测器(~/bin/zcode-quota,个人脚本)的真实观测(BigModel coding plan 5h 窗口余量与重置时刻)转成quota-aware-routing.summary.v1的 zcode fuel lane,供既有quota_preflight.py/route_suggest.py消费。数据源优先级--stdin-obs(watch 钩子直连)> watch-log 尾读(默认 300s 新鲜度)>--json现场拉取;全部失败 exit 1 且不写文件(fail-closed,绝不编造 lane 数据)。 - 确立多生产方合并语义:只替换 zcode lane,其余 lane 与
generated_at原样保留——合并方不替其他生产方"续期",生产方停摆必须表现为整体 stale 被预检门拒绝,而不是被 zcode lane 的刷新掩盖;写入原子(tmp +os.replace),lane 记录带updated_at/source溯源附加键。 - 新增
references/21-zcode-quota-producer.md:公私边界(凭证解密逻辑永不进入公开仓库)、数据流、启用方式、fail-closed 行为表与第二期接线点(spawn 侧 provider 映射、429 恢复前置额度确认)。
技术优化
- 公开技能对 zcode 额度保持"中立合同消费方"定位:适配器只消费 zcode-quota 的输出(stdin/日志/CLI),不直接调用官方接口、不读取或解密
~/.zcode/v2/credentials.json。
验证
- 新增
scripts/test-quota-summary-zcode.py10/10 通过:覆盖数据源回退链(stdin 优先、日志过期回退现场拉取、全失败 exit 1 且文件原样)、合并语义(其他 lane 与 generated_at 保留、自定义 lane 名)、字段映射(remaining 钳位 [0,100]、epoch ms→ISO、可缺省 resets_at、跳过 tokens_pct 缺失行),以及与quota_preflight.py的联动(余量充足放行ok、判停线拒绝lane_below_stop_line)。 - 真实环境接入验证通过:zcode lane 合并进既有 route-summary(glm-api/minimax/codebuddy-hy4/autoclaw 四条 lane 原样保留);
zcode-quota --watch经ZCODE_QUOTA_SUMMARY_HOOK每 120s 自动刷新 zcode lane(source=stdin,含真实resets_at)。
待办事项
- 第二期接线(本期未动 spawn 行为):
spawn-worker.sh对--worker-backend zcode显式以provider=zcode走预检门(当前not_applicable放行);orca_rate_limit_recovery.py唤醒前确认 5h 窗口真实余量。 - 自动讨卡/用卡动作不进入编排链:自动用卡已被用户明确禁止;自动讨卡如需接入必须另设显式授权门。
[2.18.0] - 2026-09-05
新增
- 接通
dispatch-value-gate.v2的verification_commands到 spawn:新增--verification-contract + --verification-task-id,以唯一 task 为权威原样写入进程授权快照、Git common-dir authority receipt、METADATA 与精确 Shell allowlist;实现/可复用验证任务解析为空时在任何 Worker 副作用前拒绝。 - 正式消费项目
.claude/orchestration.config.json的verification.default/by_worker_type,新增--project-config、--worker-type与verification.required;嵌套 Python 项目可显式声明完整cd ... && python3 -m unittest ...命令,unknown type、畸形/空配置均失败关闭。 - 新增
--require-verification与根 Python 项目有界发现:仅根 Python manifest 与根tests/同时存在时注入固定 unittest discover,不递归搜索或猜测 pytest/tox/nox。
修复
- 修复 PM 已在任务合同声明验证命令、但派发时漏转抄,导致 Worker 首次自验普遍触发
SHELL_COMMAND_NOT_ALLOWLISTED的系统性断点。命令保持单一完整字符串,不开放全 Shell、通配、泛化cd或 hook 绕过。 - 空白、换行、重复、安装型验证命令和 CLI/合同双权威冲突现在均在 worktree、terminal、Task、Dispatch、provider lease 与任务注入前拒绝;安装授权继续使用独立显式通道。
- 独立复审补强 JSON 边界:项目配置或 dispatch 合同中的验证字符串只要包含 U+0000,即在 NUL 分隔解码前拒绝,不能再把一条恶意/畸形字符串拆成多条合法授权。项目模板移除与
verification.required:true必然冲突的 docs/research 空 profile;docs-only 任务仍按价值门禁止独立派发。
验证
- 新增
test-spawn-worker-verification.sh确定性矩阵,覆盖合同/项目配置正例、嵌套 Python 原样保真、unknown worker type、required-empty、畸形配置、重复/安装型命令、双权威冲突、Python 有界发现、merge gate 空命令及两类 U+0000 逃逸负例。 - 扩展依赖 Shell 门禁测试,直接证明示例嵌套 unittest 命令完整精确授权可首次通过,而少一个参数的近似命令仍被拒绝;Node/Make 默认注入、metadata 与 flag 回归保持通过。
- 验证命令合同 13/13、dependency/Shell guard 73/73、Node/Make/Python deps 18/18、flags 31/31、metadata 22/22、存量 supervised reauthorize 113/113 通过;维护矩阵其余测试与 Orca/fake control-plane smoke 通过。tmux smoke 首轮受当前真实 Orca 自动注册影响触发既有 isolation pre-gate,以
ORCA_CLI_COMMAND=/usr/bin/false隔离后复跑通过。 - 所有 Shell
bash -n、Skill quick validation 与 Git whitespace 检查通过;security scan 为 0 critical / 0 high。Harness failure audit 保留全 Skill 既有 6 条 hard finding(1 条清理脚本通用命中、5 条旧测试退出码模式),本次没有新增类别。
待办事项
- 本轮未启动真实 Orca Agent 验证
worker_done → Delivery外部生命周期,标记NOT_VERIFIED;存量 Worker 继续使用pm-orchestrate.sh reauthorize --allow-cmd重建不可变进程快照。
[2.17.0] - 2026-09-05
新增
- 新增 Orca-only
orca_rate_limit_recovery.py:以显式terminal_handle + incarnationId + provider + account_group清单跨项目巡检 Worker,区分RUNNING、RATE_LIMIT_RETRYING、RATE_LIMIT_IDLE、UNKNOWN;默认只读,只有--execute才对高置信 idle episode 通过 terminal 输入通道发送固定“继续”。 - 新增 provider/account group 分组错峰、
handle + incarnation + cursor + timestamp + evidenceepisode 幂等、私有 owner/symlink 防护状态、非阻塞锁、发送前 identity/cursor/idle 复核和发送后 identity 复核。发送结果只记WAKE_ACCEPTED,不冒充额度或业务恢复。
改进
- 从
pm-quota-stall.sh抽出共享provider_error_classifier.py,统一 auth/config/network/quota 优先级;混合 auth/config + 429、仅讨论/测试 429、陈旧 tail、断连/不可写、tmux/未知来源和 Orca 畸形/截断清单全部失败关闭或不发送。 - 主文档只保留入口与 Hard Fail;manifest、状态机、退出码、错峰、幂等和安全 runbook 放入
references/20-orca-rate-limit-recovery.md,并在 Wave Autopilot 中建立按需入口。
修复
- 独立审阅后收紧
tui-idle合同:除satisfied=true外还必须精确为status=running且exitCode=null;缺字段、已退出和非 running 均失败关闭。额度证据改为尾部锚定的实际错误行,说明句expected response/provider returns不再触发。 - 自然语言额度错误模板统一要求行首锚定;
Design note: quota exceeded...、The account hit your limit...等解释性句子即使包含额度短语也不再 actionable,优先接受漏报而不是误唤醒。 - Orca 已接受唤醒且后置 identity 复核成功、但
sent状态提交失败时,回执明确标记WAKE_ACCEPTED_STATE_COMMIT_FAILED,磁盘上的 WAL intent 继续阻止同 episode 重发。
验证
- 新增 fake-Orca 确定性矩阵,覆盖 dry-run 零发送、retrying/RUNNING 不发送、idle 只执行一次、新 evidence 可再处置、分组顺序与最小间隔、auth/config 混合、源码/测试日志讨论 429、断连/不可写/陈旧证据、截断/畸形/失败 Orca、tmux 来源与参数拒绝、敏感原文不出回执、identity 漂移、send/post-check 不确定后的 intent 幂等、状态 symlink/权限与锁竞争。
- fake-Orca 16/16、
pm-quota-stall39/39、night-watch31/31 通过;全部 Shellbash -n、Pythonpy_compile、Skill quick validation 与 Git whitespace 检查通过。真实 Orca 1.4.197 只读 smoke 验证 list/show/read/wait schema、UNKNOWN/no_actionable_quota_evidence、零 send 且不创建 state。 - Skill Lint security scan 为 0 critical / 0 high;本轮新增生产脚本只有已披露且
shell=False/参数数组调用的 subprocess medium,以及工具定位/私有状态路径所需的环境变量 low。Harness failure audit 未在本轮新增文件命中,仍保留全 Skill 既有 6 个 hard finding,不以命令变形规避。
待办事项
- 真实 GLM/MiniMax 429、真实 Orca 多项目批量
WAKE_ACCEPTED → cursor 前进 → 业务进展、Task-064 的真实 provider quota→available E2E 均为NOT_VERIFIED;本版本不实现 lane availability probe、自动切 provider、tmux、长期守护或 L3 scheduler。
[2.16.5] - 2026-09-05
文档完善
- 合并编排指南中两条重复的自动清理说明,明确
pm-closeout.sh → pm-cleanup-worker.sh是持有完整交付绑定的标准路径;post-merge-cleanup.sh仅用于已经合并但未走标准 closeout 的单一遗留 worker,不替代标准路径也不用于批量扫描。
[2.16.4] - 2026-09-05
改进
- 移除
multi-agent-orchestration主文档、法律场景 reference 和历史记录中对其他任务协调 Skill 的名称与职责跳转;任务来源只表述为“由项目既有任务源确定”,本 Skill 独立聚焦本地 Worker 执行编排。
[2.16.3] - 2026-09-05
改进
- 主文档按运行阶段收敛:
SKILL.md从候选版 579 行压缩为 208 行,只保留触发边界、模式选择、门禁顺序、最短执行闭环与 Hard Fail;详细派发/交付/review/修复合同迁入references/18-dispatch-acceptance-contracts.md,维护者模块边界与完整回归迁入references/19-maintainer-validation.md。 - 按需加载地图:将 Orca、Autopilot、backend、验收合同和维护测试映射到明确 reference,避免一个会话默认加载全部历史事故、操作参数和测试矩阵;现有脚本合同、门禁顺序与安全语义不变。
技术优化
test-dependency-install-guard.sh使用临时的禁用额度路由配置,隔离开发者本地orchestration-personal.json与过期 quota summary,确保 spawn 集成断言检验安装/Shell 门禁本身,而不是被更早的个人配额预检污染。
文档完善
- 同步指向
git-workflow的分支生命周期权威文档,明确编排层只负责触发 delivery-bound 清理,Git 层负责一次性/长期分支判定、批量 stale 审计和长期功能线关闭。
验证
- 两个 Skill 的 quick validation 与 Git
diff --check通过;安全扫描为 0 critical / 0 high;cleanup 37/37、closeout 120/120、dependency guard 67/67、spawn flags 30/30、metadata 21/21 通过。 - Harness Failure Audit 继续保留 5 个既有 hard finding(受精确交付证据约束的远端分支删除通用命中 1 个、旧测试退出码模式 4 个);Instruction Stability 因缺正式约束追踪合同与签名多轮证据保持
NOT_VERIFIED。真实 GitHub/Orca 外部链路继续沿用 v2.16.1 的NOT_VERIFIED边界,不因文档重构扩大结论。
[2.16.2] - 2026-09-05
修复
- 长期分支误清理保护:派发新增
--branch-lifecycle ephemeral-worker|long-lived,并把生命周期与base_ref持久化到 SessionMETADATA.json。清理优先读取元数据,调用方不得把long-lived降级为一次性分支;长期源分支固定保留远端 ref、本地 ref 与 Worktree。 - 合并目标与 Worker head 分离:
pm-cleanup-worker.sh新增--integration-target,要求 GitHub PRbaseRefName精确匹配。短 Worker 合入长期功能/集成分支时只删除 Worker head,integration target 永不成为本次清理对象;本地集成交付证明也改查实际远端目标,不再写死origin/main。
技术优化
test-pm-cleanup-worker.sh从 23 扩至 37 项,新增 PR base 错配、保护性升级、长期目标保留、长期源分支三类 Git 资源全保留及生命周期防降级回归;spawn flags 30/30、metadata 21/21、pm-closeout 120/120 全绿。
待办事项
- 真实 GitHub 仓库中“短 Worker PR → 长期集成分支 → 自动清理 Worker head”的外部链路仍为
NOT_VERIFIED;当前证据来自 fake-gh 与真实临时 Git 仓。 - Skill Lint 安全扫描为 0 critical / 0 high;Harness 静态审查仍因受精确交付证据约束的
git push --delete报通用HFA-011,并命中 4 个本轮未改旧测试的HRA-001,因此不声明全 Skill Harness 已验证,也不以命令变形规避扫描。候选缺少正式约束追踪合同与签名多轮证据,Instruction Stability 继续为NOT_VERIFIED。
[2.16.1] - 2026-09-05
新增
- 验收后自动清理:新增
pm-cleanup-worker.sh,pm-closeout.sh的remote-pr/local-after-pr成功路径默认以冻结 PR/head/tip、delivery commit、worktree 和 Session identity 调用执行;--keep-branch作为显式保留例外。 - 资源终态合同:统一输出
CLEANED、RETAINED_WITH_REASON、CLEANUP_PENDING。交付 commit 与清理债务分开记账,清理失败不盲重试 merge/push,但不能被静默隐藏为“完全完成”。
修复
- 只读
sed被误拦:Shell fail-closed 门禁补入受限数字范围读取sed -n '<range>p' <单文件>;写入w、执行e、替换、多文件及其他形式仍需精确 allowlist。该报错属于 spawn 授权策略遗漏,不是系统文件权限不足。 - squash 分支可删性:远端分支先核 exact tip 与 PR/delivery 事实;worktree 安全移除后,本地分支以 expected tip 为 old-value 精确删 ref,不依赖
git branch -d的可达性,也不使用无条件git branch -D。
技术优化
- 新增
test-pm-cleanup-worker.sh23 项,覆盖 dirty/非法 metadata/远端查询失败/PR-head mismatch/未知 PR 状态/dry-run/merged 全清理/open PR 保留远端等路径;dependency guard 67/67 覆盖受限sed正负例;test-pm-closeout.sh120/120,含默认 cleanup 参数与回执集成断言。
待办事项
- 真实 GitHub 仓库的 delivery → 远端分支 → Orca lifecycle/worktree → 本地 ref 全链自动清理仍为
NOT_VERIFIED;本次结论只覆盖 throwaway Git 与 fake-gh 确定性证据。 - 全量回归未形成全绿回执:既有
codex → zcodepolicy 与“zcode 默认禁用”的正文/测试冲突;真实 Orca smoke 在 terminal send 失败(其创建的两个精确 terminal 已关闭)。Instruction Stability 仍为NOT_VERIFIED;Skill Lint 对本功能受 exact tip/PR/delivery 约束的远端删除仍给出通用HFA-011,未用命令变形规避扫描。
[2.16.0] - 2026-09-05
新增(post-merge cleanup gate,合并后即时清理)
- 职责单一的
scripts/post-merge-cleanup.sh:PR 确认合并后当场回收一个 worker 分支的 worktree/本地/远端短分支。删除资格真值来自 git-workflow 分支清理规则,全部门禁机械判定、fail-closed:① 分支不是main/master/develop、--base或--protected-branch(名称或 glob,长期集成分支)匹配项;② 存在唯一state == MERGED的 PR 且其headRefOid与本地分支 tip 精确一致——squash/rebase merge 的唯一权威证据,head 漂移视为身份不明;③ 无开放 stacked child PR 以该分支为 base(gh 查询失败也拒绝);④ worktree 无未提交改动;⑤ session 生命周期可证结算——tmux 存活且无 supervised dispatch、terminal accounting 为 active/reclaimable/release_pending/release_unknown/unknown 一律拒绝;⑥ 远端状态必须ls-remote可验证。门禁不过输出POST_MERGE_CLEANUP_DEFERRED: reason=...(exit 2)保留现场。 - 生命周期顺序执行:execute 时先经
clean-worktree.sh --execute --delete-branch(worker-release → 关 terminal/lease → 删 worktree → 删本地分支),再git push origin --delete远端短分支(push 报错但 follow-upls-remote证明远端已删时按并发竞态幂等放行),最后机械零残留验证(本地 ref、worktree 注册与目录、tmux session、远端 ref);远端删除失败或任一残留以 exit 9 报告,绝不把部分成功冒充完成。执行前复核分支 tip 未移动(TOCTOU)。默认 dry-run 零副作用;即时清理是「已合并且无消费者」对 <24h 规则的显式例外,只处理显式传入的单个分支,不批量扫描。 clean-worktree.sh新增--force-delete-branch:squash/rebase merge 后分支 tip 不可达 main,安全git branch -d必拒;该开关允许在-d拒绝后升级-D,仅供持有独立 MERGED+head 证据的调用方(即 post-merge-cleanup.sh 门禁通过后)使用,不带开关时行为不变(拒绝并 exit 2,不再依赖 set -e 的裸失败)。- 文档同步:SKILL.md §8 新增 post-merge-cleanup 段并纳入验收测试清单与
gh依赖说明;references/14-pm-orchestrate.md§4.4 的「自动清理属于 Task-103」占位替换为实际工具指引。版本 2.15.1 → 2.16.0。
[2.15.1] - 2026-09-04
修复(reauthorize 已结算 task 的 TASK_REUSED 误判,Task-113)
- 有界区分真单活与结算残留:worker_done outcome=failed 正常结算(task 翻成 failed、Dispatch settled、Delivery release+ack)后跑
pm-orchestrate reauthorize,预检打印 task state=failed,但新 terminal 注册返回TASK_REUSED;旧实现(Task-081)把 TASK_REUSED 固定解释为「task 仍 dispatched(单活 fencing)」,回滚新终端并指引 PM「先 settle 再重跑」——task 早已结算,恢复链死循环。现注册返回 TASK_REUSED 时按 Step 0 预检状态三分:failed/settled(结算残留)先复核一次 task-list,确认仍是 failed/settled 才task-update ready并只重试一次注册,成功后照常改路由/关旧终端;dispatched维持原单活 fencing 回滚 + runbook #18 指引零变化;unknown/其他状态与「预检 failed/settled → 复核翻回 dispatched」的漂移一律回滚新终端 fail-closed 不复位。身份、coordinator 绑定、terminal ownership、Delivery/settlement、provider lease 与 scope guard 全部未放宽;新终端建立后任何中间失败仍先关新终端、保留旧终端(重复调用不累积终端)。 - 回归门禁扩容:
test-pm-reauthorize.sh9 案例 71 断言 → 14 案例 95 断言。新增 J(failed+settled+TASK_REUSED 复核一致 → 复位重试恢复、零终端泄漏)、J2(settled 状态字串同链路)、K(复位后重试仍 TASK_REUSED → 有界单次重试 + 回滚)、L(预检 failed → 复核翻回 dispatched 漂移 → fail-closed 不复位)、M(unknown + TASK_REUSED → 不猜测不复位)、N(结算恢复链重复调用不累积终端)。fake CLI 新增task_reused_once模式(仅当 task-update 复位后才放行重试,保证验证「复位 → 重试」因果链)与task-status-next一次性状态轮换(漂移注入)。红→绿实测:修复前 71 通过 / 24 失败(全部落在 J/J2/K/L/N),修复后 95/95 全绿;test-pm-orchestrate-handoff.sh31/31、bash -n pm-orchestrate.sh通过。 - 文档同步:
SKILL.md§4.5 reauthorize 段新增结算残留语义说明。版本 2.15.0 → 2.15.1。
[2.15.0] - 2026-09-04
新增
- PR 唯一性审计
pr-audit.v1:新增scripts/pr-audit.py与pm-orchestrate.sh pr-audit。按 canonical repo/Git common dir、base/head ref 与 OID、head repository、真实 diff 指纹相等以及独立Task:/Agent:trailer,把 open PR 分为 exact、suspected、unrelated;同 head 错 SHA、元数据相同但 diff 不同、同内容异分支、fork、事实未知和候选截断均失败关闭,stdout 保持单 JSON。 - PR-first 三态收口:
pm-closeout.sh新增local-after-pr(默认)、remote-pr、validate-only,以及两阶段显式授权:第一阶段绑定 repo/PR/head/SHA/operation,main mutation 前第二阶段再绑定最终 base/candidate/tree。只读预审发生在任何 push/create 之前,唯一 worker 自建 PR 可直接接管,zero 才允许授权式 push/create;调用方 body 中保留Task:/Agent:trailer 会在 mutation 前被拒。
修复
- 本地 main 事务边界:候选改为在 fresh main 隔离 clone 中对冻结 worker patch 做三方应用,不再整文件覆盖 main;从隔离 main 候选 safe-push,远端确认后才快进真实 clean main。scope 冲突、safe-push 失败、错误/dirty/进行中 Git 操作的 main worktree 均保持 main 不变。
- 保护规则与漂移失败关闭:改读 GitHub branch metadata 的类型化
.protected布尔值,同时覆盖 classic branch protection 与 rulesets;只有明确false才允许本地 main push,并在最终 push 前再次确认,403/404/畸形/中途翻转都降为非成功VALIDATE_ONLY。最终 main push/GitHub merge 前重跑唯一 PR 审计并复核 base/head/diff/checks/review;远端 mutation 前另拒绝原生 merge queue(留给 Task-070),合并用--match-head-commit,成功还需验证三字段、merge commit 已进入 main、第一父提交等于已审 base 且 tree 等于候选 tree。 - 分布式 commit point 状态:普通失败(exit 2–8)保持 main 零 mutation;create/merge/push/close 调用开始后若服务端可能已提交但回执、tree 或本地同步不确定,统一 exit 9 输出
OUTCOME_UNKNOWN、REVIEW_REQUIRED或LOCAL_PENDING,保留精确 PR/commit 供恢复,禁止把部分成功伪报成普通失败或盲重试。
技术优化
test-pr-audit.sh新增 18 项分类、GHE/凭证脱敏、diff mismatch、101 条截断和稳定错误合同测试;test-pm-closeout.sh扩至 118 项,覆盖原 36 项及 validate-only 零写入、自建 PR 接管、create/same-content race、同文件三方合并/冲突、classic/ruleset/merge-queue 保护分流、保护中途翻转、base TOCTOU、candidate-bound 重授权、post-commit outcome-unknown/local-pending、Git/PR diff 凭证脱敏、scope/pathspec、safe-push 失败、错误 main worktree、可靠 Git operation marker(active rebase 目录拒绝、staleREBASE_HEAD忽略)与最终 PR 集合漂移。
待办事项
- 真实 GitHub 非保护仓的
PR → 隔离 main push → 本地 main 快进 → PR close,以及保护仓的PR → 本地候选 → GitHub merge尚未在本次本地环境执行,标记NOT_VERIFIED;确定性 fake-gh/throwaway Git 证据不得替代真实外部验收。
[2.14.2] - 2026-09-03
修复(pm-monitor tmux 判活三态,Task-113)
- 判活误报根因修复:
pm-monitor.sh的check_tmux_session原来把三种失败折叠进同一个! tmux has-session→ dead 分支——① tmux 命令不在 PATH(rc=127,Monitor/受限环境常见)、② tmux 可用但控制面查询失败(socket 不可达 / Permission denied 等)、③ 目标 session 确实不存在。真实事故:Badminton Lab 本轮pm-monitor把可由tmux capture-pane/tmux has-session证明仍存活的bl112-glm53flash、bl113-glm53flash报为SESSION_GONE。现新增tmux_session_state分类函数输出三态:alive(控制面确认存在)、absent(查询成功且明确无此 session:can't find session/no server running,唯一允许发SESSION_GONE的状态)、unknown(命令缺失或查询失败,存活不可判定)。 - unknown 不再冒充 dead:控制面查询异常时输出可机器识别的
SESSION_UNKNOWN: <session> (branch <branch>) reason=<单行原因>+AGENT_NEEDS_INPUT,PM 据此知道是观察器自身故障而非 worker 死亡;同状态跨轮去重(状态机只在翻转时发事件);从 absent/unknown 恢复存活补发SESSION_RECOVERED供撤销告警。check_commit_staleness改为复用同一分类,只对确认 alive 的 session 追提交停滞告警,不用不确定的判活去骚扰可能仍存活的 worker。 - 新增确定性回归门禁
scripts/test-pm-monitor.sh:PATH shim fake tmux(模式/序列驱动,POSIX sh)+ 临时 Git 仓库,7 案例 23 断言覆盖 alive 不误报、可靠 absent 才 SESSION_GONE、socket 查询错误报 UNKNOWN、tmux 命令缺失报 UNKNOWN、同状态 3 轮去重、恢复事件;Case 4/5/6 对旧折叠实现必红(红 13 通过/10 失败 → 修复后 23/23 全绿),零外部依赖、零常驻进程。 - 文档同步:
SKILL.md§7 新增 pm-monitor 判活三态说明。版本 2.14.1 → 2.14.2。
[2.14.1] - 2026-09-03
修复
- Orca worktree 分支错配在任务注入前失败关闭:
spawn-worker.sh在 worktree 落盘后、任何 terminal、Session Context、authority receipt、Task 或worker-start副作用之前执行 isolation pre-gate,机械核对目录、实际分支与 HEAD。Orca 因同名分支自动创建-2后缀分支时立即输出SPAWN_WORKER_ISOLATION_PREGATE_FAILED并退出,保留 worktree 供 PM 精确处置,不再形成“spawn 报失败但 worker 已收到任务”的 partial dispatch。 - 收窄最终门禁职责:launch 后的
SPAWN_WORKER_GATE只保留必须等 terminal 创建后才能观察的 pane cwd 校验;branch 与 HEAD 身份由前置门禁独占,避免同一不变量在副作用前后产生不一致结论。
技术优化
- 新增真实入口回归:
test-spawn-worker-orca.sh用 fake Orca CLI 实际创建-2后缀 worktree,负例断言零 terminal/run/task/worker-start 调用、零 Session Context 落盘且 worktree 保留;正例断言 worker-start 注入与 supervised METADATA 合同完整。 - Reviewer 证据预算:固定 exact HEAD、diff 与受影响文件优先,外部 CI 仅在 verdict 必需时查询;环境或时序失败最多一次归因复跑,之后必须具名
NOT_VERIFIED或REJECT,PM 可发送 budget stop 收敛审查范围。
文档完善
SKILL.md增加 isolation pre-gate 硬约束与 Reviewer 证据预算;references/10-parallel-lessons.md新增 G40 partial dispatch 复盘和 G41 evidence budget 经验。
[2.14.0] - 2026-09-02
修复(验收失败恢复:internal_recoverable 不再被直接泊车)
- 验收失败单一机械分类合同(
acceptance-recovery.v1):新增scripts/acceptance-recovery.py。修复前编排合同把「任何门禁失败」直接映射为泊车——autopilot_runtime对checks == "fail"无条件hard_park,codex-heartbeat-cycle对hard_park一律decision=park且建议停止心跳,内部可恢复的验收失败(本项目自有资产即可修复)因此被错误泊车、波次无谓中断。现唯一分类权威是acceptance-recovery.py:internal_recoverable(PR checks 确定性失败/交付越界/验证证据缺失/review blockers/docs-only 验收修复)在修复预算未耗尽时动作必须是repair(首次)或re_review(之后),默认预算 2 次,耗尽才park;external_dependency(配额/上游/缺用户资产或授权)与safety_unknown(事实歧义/身份或 head 漂移不可证/安全高风险/runtime 损坏)立即park,表外信号 fail-closed 归safety_unknown。修复预算按「失败 episode」计数:进入 repair_acceptance 记一次,同一 episode 内重复 reconcile 不重复计数(修复在途 ≠ 新失败)。autopilot_runtime与codex-heartbeat-cycle都从该模块导入同一张表,禁止在别处再写分类分支。 - autopilot runtime 集成:
checks == "fail"经分类后预算内规划新的内部动作repair_acceptance(INTERNAL_ACTIONS新增;state 保持RUNNING不泊车,item 记repair_attempts,RUNTIME_ITEM_KEYS同步扩键,向后兼容旧状态文件);预算耗尽才hard_park,且_fail_action携带failure_class(默认safety_unknown)。checks == "unknown"维持hard_park(safety_unknown)。 - codex-heartbeat 集成:适配器
classify_internal新增repair_acceptance→decision=review且future_heartbeat_needed=true(不泊车、心跳继续);decision=park(停止心跳)从此只属于 hard_park(安全不明/外部依赖/修复预算耗尽)。回归测试新增 2 用例(repair_acceptance 两个 episode 均不泊车零 tick;预算耗尽 hard_park 仍泊车停心跳),套件 31→33 用例。 - docs-only acceptance repair 极窄通道(
acceptance-repair.v1):新增scripts/acceptance-repair-gate.py(preflight/postflight 双门禁)+templates/acceptance-repair.example.json,服务「已具名 PR 的验收只差文档修复」场景,dispatch-value-gate.v2 拒绝 docs-only 的规则不变。机械拒绝清单:缺字段/占位、target.head_sha非 40-hex、integration_target≠target.branch(只能集成回既有 PR 分支,合同不存在独立文档 PR 的表达字段)、blocker 缺失/重复、file_scope含非文档或 traversal 路径、过期、repair_attempts_used≥ 2(必须按分类合同泊车)、re_review 自审、registry 重复修复(同 pr+head_sha 或活跃 blocker 重叠)、owner 串行冲突(同 PR 单活跃 owner);postflight 另拒 head 漂移(git 模式要求 delivery head 是 pinned head 后代且 evidenceverified_head一致,patch 模式无法证明谱系一律拒绝)、范围外/非文档修改、零 diff、blocker 未全部解决或解决声明超出合同、验证命令未 exit 0、owner 不一致。 - reviewer 写范围纪律(角色分离验收波强制默认):
spawn-worker.sh新增--role implementer|reviewer与--review-repair-grant <授权来源>。reviewer 默认可写范围只有自身 Session Context;无授权却传--allow-paths在任何副作用前 fail-closed 拒绝 spawn(不静默收窄);config/*.local.yaml(安装 Skill 的本地运行配置)对 reviewer 永远不可写,授权也不例外。enforcement 分两层:spawn 在副作用前注入SCOPE_GUARD_ROLE/SCOPE_GUARD_SESSION_ROOT/SCOPE_GUARD_REVIEW_REPAIR_GRANT并写 METADATAruntime.role;scope-guard.py新增 reviewer 层(无授权只放行 Session Context 前缀;config/*.local.yaml 硬拒绝)。非 reviewer 角色行为完全不变(向后兼容)。 - 文档同步:
SKILL.md§3 新增「Reviewer 写范围纪律」「验收失败恢复分类」「acceptance repair 极窄通道」三节、§4.6 heartbeat 语义更新、§12 Hard Fail 新增 #13/#14;references/15-wave-autopilot.md§6 重写为先分类再处置 + 修复通道 + §6.1 reviewer 写范围,§7 反模式新增两条。版本 2.13.0 → 2.14.0。 - 测试:新增
scripts/test-blocker-recovery.sh(恢复合同统一回归入口)=test-acceptance-recovery.py(51 断言:三类分类表、预算语义、表外 fail-closed、module/CLI 同表)+test-acceptance-repair-gate.sh(33 断言:真实临时 Git 仓,preflight 19 + postflight 14 正反例)+test-reviewer-scope-guard.sh(19 断言:hook 层 session-context/配置硬拒绝/授权与向后兼容 + spawn 角色门 fail-closed)。已验证:test-blocker-recovery.sh 全绿(103 断言)、test-codex-heartbeat-cycle.py 33/33、test-dispatch-value-gate.sh 31/31、test-worker-value-postflight.sh 27/27。NOT_VERIFIED(待独立 reviewer 新会话补跑后裁决):test-autopilot-controller.py、test-spawn-worker-metadata.sh、test-spawn-worker-flags.sh——本 dispatch 的命令授权快照不含这三条,改动对应的运行时回归(case_v2_acceptance_failure_repairs_before_park等)已写入测试文件但未在本会话执行。
[2.13.0] - 2026-09-02
新增
- Codex 心跳有界循环适配器(
codex-heartbeat-cycle):新增scripts/codex-heartbeat-cycle.py,让 Codex App heartbeat 充当外部调度器驱动既有 L2 autopilot-controller,而不把 L2 包装成常驻 L3——每次心跳被唤醒只执行一次有限循环:读取显式常规文件 JSON 请求(钉扎 controller/适配器 path+sha256、repo/project/policy 身份、owner/fencing token、有界超时),经既有autopilot-controllerCLI(argv 数组、shell=False、有界超时、stdin=/dev/null)执行一次 status → reconcile,仅当 reconcile 给出 ready 的外部变更意图且通过 tick 前闸门(动作 allowlist、声明与机械验收反压阈值>2、配额拒绝、待定意图 planned/ready/token 一致、租约身份一致)时执行至多一次 tick,随后输出机器 JSON(decision=wait/review/dispatch/park/complete、精确 receipt、future_heartbeat_needed、fail-closed 原因)。硬边界:不循环、不 sleep、不派生后台进程、不注入 raw 终端输入、不改 TASKS、不按 token 丰度挑选价值任务;不确定的 tick(超时/非零退出/输出畸形)一律按结果不确定上报且绝不重试,tick 之后不再发起任何控制器调用;COMPLETE/硬泊车/重复拒绝时建议停止心跳。配确定性契约测试scripts/test-codex-heartbeat-cycle.py(31 用例:argv 安全、每次调用至多一次 tick、每个拒绝场景零 tick、有界超时、畸形输出 fail-closed、不确定后零重试零追加调用、示例模板驱动完整循环;零网络零真实 Orca/GitHub 变更)与请求模板templates/codex-heartbeat-cycle.example.json。SKILL.md§4.6 同步适配器边界。 - 角色分离验收门禁(
review-acceptance-gate.v1,fail-closed):新增scripts/review-acceptance-gate.py,把 MAO-PM-ROLE-SEPARATION 的角色分工从文字约定变成可执行验收契约——实现 worker 负责非平凡实现,独立 reviewer worker 负责深度 diff 审查与行为验证,PM 只拥有方向、价值合同、粗粒度巡检、冲突/风险升级、immutable-head 记账与最终收口。机械接受仅当:实现者与审查者具备互不相同、非占位的dispatch_id/session_id身份;delivery_head与reviewed_head为同一不可变 40-hex commit;审查结论为字面ACCEPT;verification_evidence为非空{command, exit_code}记录且全部 exit 0(纯文字叙述证据拒绝);review_consumer/review_expiry已具名;blocking_findings为空。自审、身份缺失/占位、head 漂移/非 40-hex、纯文字证据、缺验证/验证失败、占位消费者/到期处置一律拒绝。PM 实现/深度审查例外仅在worker_failure、conflicting_verdicts、security_or_high_risk_evidence、control_plane_recovery四种枚举reason_code下允许,必须附非空reason与authorized_by;带例外通过的收口输出ordinary_delivery: false,永远不得计为常规交付。配确定性契约测试scripts/test-review-acceptance-gate.sh(27 用例:正例、例外标记非常规交付、自审/同 dispatch/同 session、head 漂移、verdict 大小写、纯文字证据、失败验证、占位消费/到期、blocking findings、例外文书四反例、schema fail-closed、示例模板自洽断言,成败退出码与机器可读输出均断言)与示例templates/review-acceptance.example.json(过自身门禁)。SKILL.md§3 新增「角色分离验收门禁」节(强制默认 + 不声称能 policing 所有行为的边界声明)、§12 Hard Fail #12 与验收命令清单同步。既有dispatch-value-gate.py/worker-value-postflight.py未改动。
[2.12.2] - 2026-09-01
修复(验收纠偏 r3:堵住 docs-only 目录误报)
- postflight 先分类文档路径再匹配资产:2.12.1 及之前,
_postflight先按声明资产匹配实际变更路径,宽声明(如engineering_assets: ["skills/foo"])会把其下 docs-only diff(skills/foo/README.md)算作工程资产命中而放行,违反"文档不得是唯一变更"的核心规则。现实际文档路径永远无法满足matched_engineering_assets——即使位于声明的工程目录之下,也只能经doc_assets声明作为随行文档;未在doc_assets声明的实际文档路径保持 outside-contract。 - 文档路径语义单一来源:preflight 的
_is_document_path升为公共is_document_path(扩展名 +docs/目录同一张表),postflight 通过加载 gate 模块复用同一 helper,不再各自维护扩展名清单,防止两门禁语义漂移。 - 新增 3 条确定性回归(宽工程目录 + README-only diff 拒绝;宽目录 + 真实源码 + 已声明随行 README 通过且命中工程目录;未声明的实际文档路径保持 outside-contract),postflight 矩阵 23→27,preflight 31 用例不变,全绿。
[2.12.1] - 2026-09-01
修复(验收纠偏 r2)
value_identity改为机械必填:2.12.0 文档声明去重身份但代码允许缺失;现缺失/占位一律拒绝,新增缺失与占位两条回归。- postflight head 绑定(真 Git revision binding,测试实证):2.12.0 的 CHANGELOG 曾写"
verified_head与gate_target.head_sha漂移拒绝",属超前表述——该版 evidence 缺verified_head仍可通过,且 merge gate 正例比较的是BASE..BASE。本版起:每个被接受的 postflight 都必须含 40-hexverified_head;Git 模式用git rev-parse --verify <head>^{commit}解析--head并要求 evidence 一致;patch 模式新增显式--delivery-head <40-hex>(缺失/非 40-hex 拒绝)作为投递修订绑定;merge_gate额外要求解析/evidence head 等于gate_target.head_sha,正例改为 pinned target 自比(HEAD..HEAD)。新增缺失 head、stale evidence head、git head ≠ merge target、缺--delivery-head、非 40-hex delivery head 五条负回归。 - 新增
integration_pr派发政策:2.12.0 强制所有实现/验证资产走独立worker_pr,助长 PR 数膨胀。现实现/可复用验证资产可选worker_pr或integration_pr,选后者必填非占位integration_target(具名集成 PR/branch);merge_gate 仍仅no_worker_pr。示例模板的实现任务改为integration_pr+integration_target演示具名集成消费。 - 移除 SKILL.md docs-only 矛盾表述:原文先说 docs/research 不可派、随后又允许 docs-only 换取状态迁移,现统一为:文档只随同 implementation / reusable_verification / merge decision 的同一有价值变更交付(
doc_assets声明 + postflight 实证),docs-only/简单调查/纯文案清理不得获得独立 worker/worktree/PR。 - 测试矩阵:preflight 31 用例、postflight 23 场景(临时真实 Git 仓)全绿,成败退出码与机器可读输出均断言。
[2.12.0] - 2026-09-01
新增
- 派发价值合同 v2(
dispatch-value-gate.v2,fail-closed preflight):dispatch-value-gate.py现要求每个任务机械声明三种value_kind之一——implementation(改变行为的实现/修复)、reusable_verification(可复用确定性测试/fixture/基准/故障注入资产)、merge_gate(具名 PR/change + 40-hex head 的零 diff 合并决策)——并补齐problem_target、engineering_assets/doc_assets、verification_commands、worker_pr_policy(仅 merge_gate 允许no_worker_pr)、gate_target(pr+ 40-hexhead_sha)与波内去重身份value_identity(显式重复判 duplicate,同value_kind+同problem_target判 subsumed)。docs/research kind、无value_kind的通用调查、纯文档交付计划、占位资产一律拒绝;六字段消费者合同(consumer/decision_or_gate_changed/consume_by/expiry/observable_acceptance/resource_owner)与 explore/backpressure 门禁保留。行数、token、commit/PR 数不构成价值信号。示例模板改为双任务示例(实现 + merge gate),合同测试重写为 26 用例(含模板自洽性断言)。 - 交付后价值门禁
worker-value-postflight.py(新):读同一 spec,对--repo/--base/--head或--diffpatch 实证交付——至少一个声明的非文档工程资产真实变更、变更路径不超出声明资产(文档可随行但不得是唯一变更)、verification_commands在 evidence JSON 中有 exit 0 执行记录;零 diff 仅对声明merge_gate放行,报告输出 accept/reject 决策与决策消费者。(head/revision 绑定合同由 2.12.1 修正补齐,见该条目。)大 diff、绿色自测或 worker 活跃度不能挽救未消费/不可验证的任务。新增确定性契约测试test-worker-value-postflight.sh(临时真实 Git 仓库,成功/失败退出码与机器可读输出均断言)。SKILL.md§3 派发价值节同步两段门禁工作流,§12 验收清单新增 postflight 测试并扩展 Hard Fail #10;references/15-wave-autopilot.md§5 六字段文本审查表仍有效,机械合同以本版本与templates/dispatch-value-gate.example.json为准。
[2.11.0] - 2026-09-01
修复(P0:配额与恢复门禁强化)
- spawn-worker 配额预检门(P0-①):新增
scripts/quota_preflight.py(fail-closed 门禁,exit 3=拒绝),spawn-worker.sh对自动补选与显式--api-provider的 provider 一律在任何 worktree/terminal/lease/dispatch 副作用之前预检:summary 缺失/不可读/过期/lane 低于判停线(闭界)/lane 不健康/provider-lane 不匹配/claude-code 未解析出 provider 全部拒绝。绕过通道只有新增显式 flag--quota-preflight-override <非空授权来源>(写入 METADATAruntime.quota_preflight与 authority receipt,状态override:<原拒绝原因>);撤销了默认人工锁定直通。19 用例契约测试scripts/test-quota-preflight.py全绿。 - 删除 claude-code
--bare自动降级(P0-②):撤销 v1.20.2 Task-019 的CLAUDE_CODE_BARE_AUTO_DEGRADE——hook 不可证明(--bare/--safe-mode/--setting-sources排除 local/CLAUDE_CODE_SIMPLE=1/缺 claude token)时默认 fail-closed exit 64,不再静默降级 prompt-only(静默放弃机械安装门禁)。唯一降级通道是既有显式可审计的--allow-prompt-only-install-guard <授权来源>(codex/zcode 无 hook backend 的既有要求不变)。--no-claude-code-bare-auto-degradeflag 随之移除。 - 修复 renderer hook 契约(P0-② 集成断点收尾):P0-② 落地后
render-runtime-profile.sh仍对 claude-code provider env isolation 默认追加--bare,标准 render → spawn 路径被 install-guard fail-closed 拒绝,逼 PM 手工删字符串。现改为:settings/registry 两路默认渲染 hook-capable 命令(无--bare),wrapper、--setting-sources project,local、可选--no-mcp契约不变(GLM 同配置实测无--bare可正常运行)。bare 能力保留为显式 opt-in renderer flag--claude-bare(仅 claude-code provider isolation 路径合法,错用 exit 64),输出上下文 isolation 标签追加+bare(degraded/unhooked)标记;spawn-worker 仍要求显式--allow-prompt-only-install-guard,不恢复自动降级。新增确定性契约测试scripts/test-render-runtime-profile.sh(33 断言:两路默认无--bare、--no-mcp保留、opt-in degraded/unhooked 标记、错用 fail-closed、标准 render 输出机械提取 spawn-workerclaude_hook_disable_reason检查直通、bare opt-in 反向仍被拦截)。 - pm-orchestrate 新增
quota-park(P0-③):配额停滞恢复交接命令。固定顺序:liveness gate(active/不确定仅--force可过)→worker-stop精确 fence+stop 旧 dispatch → 释放 METADATA 记录的 provider lease(--resource-settled,依赖 Orca terminal liveness 证明)→ METADATA.recovery.quota_parkmarker。worktree/session/checkpoint 全程保留;任何失败路径不释放 lease、不写 marker,绝不双活。park 后同 worktree 重启需新 session id(receipt 每会话唯一),切 provider 允许,两者仍受 quota preflight 约束。新增scripts/test-pm-orchestrate-handoff.sh:正向/active 反向/stop 故障/lease 释放故障注入/--force/缺--reason/tmux 模式反向/park 后换 session 交接 8 场景 31 断言全绿。 - zcode 默认不在 Claude Code/Codex backend 白名单(P0-④):
config/harness-backend-policy.json的hosts.claude-code/hosts.codex移除zcode(额度 lane 独立、语义与订阅额度不同)。唯一启用通道 = 用户明确授权后显式编辑策略文件加回(git diff 可审计);canonical 映射与命令身份门禁保留。scripts/test-harness-backend-policy.sh同步断言 deny。
[2.10.3] - 2026-09-02
修复
- Orca 仓库未注册自动收口(Task-111,2026-09-01 custom-skills 实测事故):仓库是有效 Git 仓、Orca runtime 健康但 repo 未注册时,
orca worktree current --json只返回{ok:false,error:{code:"selector_not_found"}},Orca 模式被静默降级为 tmux;手工orca repo add后立即恢复。scripts/orca-runtime.sh的orca_runtime_current_project现在把失败原因暴露为ORCA_WORKTREE_CURRENT_ERROR(selector_not_found/path_mismatch/ 空=runtime 不可达·非 Git·不可解析),并新增orca_runtime_register_current_project:仅在错误码精确等于selector_not_found、canonical Git toplevel 可解析、orca status --json可达时执行一次orca repo add --path <toplevel> --json,复验worktree current精确返回该 toplevel + repo 身份才算成功。scripts/spawn-worker-orca.sh的detect_orca_mode接线:注册失败、合同非 ok 或复验不匹配一律打印诊断后回退既有 tmux 路径(fail-closed,早于 branch/worktree/provider 副作用);--dry-run只打印ORCA_RUN计划不执行 mutation。已注册仓库、--no-orca-mode、非 Git、runtime 不可达、其他错误码一律不注册;mutation/授权边界(只注册当前这一个 Git 仓库,不触碰其他 Orca 项目)固化到references/13-orca-cli-worker.md§3。
技术优化
- 新增
scripts/test-orca-auto-register.sh:41 用例确定性 mock 回归(fake orca CLI 经ORCA_CLI_COMMAND注入,不依赖也不改动真实 Orca 状态),覆盖 success(含 CLI 非零退出仍带错误合同)、already registered、runtime down(无 JSON / status 不可达)、non-Git、wrong error code、repo add failure、post-add path mismatch,以及--no-orca-mode/ DRY_RUN / path_mismatch 永不注册。
[2.10.2] - 2026-08-31
改进
- 裸调 worker-start 冷启动窗口坑沉淀(实测 2026-08-30):绕过
spawn-worker.sh直接worker-start --worktree current --agent claude存在约 60 秒启动确认窗口,Claude Code 冷启动超窗 → dispatch timeout、Task failed 并遗留孤儿终端(本机不可调,疑 Orca 对慢冷启动 agent 的兼容问题,可上游反馈)。SKILL.md supervised 经验清单与references/13-orca-cli-worker.md失败与恢复节新增完整恢复序列(清孤儿 → 复位 Task →--terminal复用重试 → 以 dispatch-show 判读部分生效的返回体),并明确两步路径(spawn-worker.sh 预建 terminal 等 TUI ready 再注册)是该场景的正确入口。
[2.10.1] - 2026-08-30
改进
- Orca 高频主路径纠偏(Task-110 / DEC-135):明确日常 worktree 与 terminal/session 统一优先由 Orca Orchestration 管理;纯终端 tmux 降为 Orca 不可用、用户明确要求或兼容性回归时的回退,不再作为当前优先 spike。
- PR 先行、本地集成分流:PM 收口先创建或接管唯一匹配 PR,冻结精确 base/head SHA、diff、checks 与 review,再在最新 main 上建立本地候选并复跑门禁;无保护且获授权时本地集成推入 main,有 branch protection/required checks 时本地只验收、最终仍走 GitHub merge。PR-first 只改变顺序,不扩张 push/merge/close 权限;现有
pm-closeout.sh行为未改,Task-097 完成前选择本地集成必须走手工分段流程。
文档完善
references/14-pm-orchestrate.md新增重复 PR 审计、LOCAL_INTEGRATE / REMOTE_PR_MERGE / VALIDATE_ONLY三态和 Monorepo 禁止直接 feature merge 的边界;明确 Task-097 自动门禁落地前仍需手工审计,不把文档合同误报成脚本能力。references/15-wave-autopilot.md同步 PR-first 本地/远端分流并承接守夜 v2 细节;references/10-parallel-lessons.md将早期 tmux 默认结论标为历史阶段,避免旧 reference 反向覆盖 Orca-first 当前规则。SKILL.md入口由 515 行收敛至 490 行。- Task-097 由
DRAFT升为READY并补齐范围、非目标、确定性/真实验收;Task-003 降为按需DRAFT,Task-064 保留环境实证轨道。
技术优化
- 清除发布目录中的忽略态
scripts/.DS_Store;test-pm-reauthorize.sh不再用|| true吞掉 fake terminal 清单过滤的真实错误,只把grep=1(过滤后为空)作为合法结果,其他退出码保持失败。
[2.10.0] - 2026-08-30
新增
- Wave Autopilot L2 持久 runtime core(Task-066):新增零第三方依赖的
autopilot-controller.py/autopilot_runtime.py,在 Git common dir 保存版本化 state、write-ahead event、PM lease 与递增 fencing token;提供init/acquire/renew/status/reconcile/tick,每次 tick 最多执行一个通过精确 target、digest、token 和 receipt 绑定的外部 mutation。status保持只读,event→state 与 lease→state 单步崩溃间隙可审计恢复,未来 schema、身份漂移、脏/重复/unknown 事实均失败关闭。 - 可信 facts collector:新增
autopilot-facts.py,将 immutable manifest 与 runtime request 分离;固定可执行文件/配置/证据 digest,只读采集 Orca、Git、GitHub、project 与 provider 事实。Dispatch/PR 动态 ID 只能由 ledger 提供或按 task、branch/base/head 唯一发现,歧义、陈旧 verification/writeback、check/review/head 漂移不得进入 mutation。
修复
- Task-093 正式收口:PM closeout 冻结 worker base/tip,把 worker 多提交的 Makefile 净补丁精确重放到每一轮最新
origin/main整文件;拒绝 mode/stage/fuzz/三方或语义冲突。main 在验证期间前移会重新合并并重跑同一 argv 门禁,三轮仍移动或验证改变 Git 状态时停止,不进入 push/PR。 - Autopilot 幂等与接管加固:已记录 receipt/started intent 在外部事实精确收敛前不会被暂态 observe/hard-park 覆盖;planned intent 接管后重新 fencing/revalidate,facts deadline 过期时先持久化
ready=false并以零 adapter 调用拒绝 tick,必须 fresh reconcile。merge 强制绑定当前 head 的 verification、gate/evidence digest、required checks/approvals,幂等键不包含会波动的实际审批数;mutation adapter 在首个可执行 intent 才按 canonical path + digest 永久封印。 - 恢复探针非法 JSON 失败关闭(Task-109):
recover-unconfigured-worker.sh不再把dispatch-show/terminal read的命令失败、损坏 JSON 或非法结构折叠成空事实;现在会在 terminal send/worker-start 前输出稳定RECOVER_REASON与 manual-required。合法无 Dispatch 和空 tail 保持原语义,恢复矩阵 56/56。
技术优化
test-autopilot-controller.py24/24 覆盖双 PM、接管、WAL/lease 崩溃间隙、进程锁、过期计划零调用、七类 mutation 收敛、lost receipt/timeout、adapter 封印、敏感字段拒绝和损坏/漂移失败关闭;test-autopilot-facts.py21/21 覆盖动态 Dispatch/PR 生命周期、多任务子集、只读命令、digest、freshness、歧义与进程组超时;test-pm-closeout.sh36/36 覆盖真实 throwaway Git 冲突与 main 移动。- 能力边界仍为
L2 / CROSS_SESSION_RECOVERABLEcontroller core。真实 Orca/GitHub mutation adapter 端到端、真实断电后的 fsync/rename 行为继续标记NOT_VERIFIED;Task-067 外部 scheduler 未实现,继续报告AUTOPILOT_L3_SCHEDULER_NOT_IMPLEMENTED。
[2.9.7] - 2026-08-30
修复
reauthorize 支持 dispatched 等待态 worker(Wave 10 T3,Task-081):原实现只适用 task 已 failed/blocked 的 worker——escalation 等待中(task 仍 dispatched)执行 reauthorize 被
TASK_REUSED拒绝且泄漏 2 个 terminal(2026-08-30 实测)。现新增 Step 0 预检:dispatched 且有未消费 escalation/question 消息时先 reply 消费等待(resume 文本即 reply body)再走既有重授权链;terminal 生命周期防泄漏——新终端建立后任何中间失败(复位/重注册/METADATA 改路由失败)先关新终端保留旧终端,幂等重复调用零累积;TASK_REUSED 硬限制场景输出 runbook #18 manual-recovery 指引 + settle 后重跑选项而非裸拒绝。新增test-pm-reauthorize.sh55 用例矩阵(dispatched±消息/failed/blocked/completed/幂等/新终端失败回滚),lifecycle 回归 10 用例全绿。route_suggest stale fail-closed(Wave 10 T1):额度快照超过 freshness 窗口或缺失
generated_at时不再基于过期 fuel 余量推荐 lane——输出降级stale_degraded/degraded且lane/provider为空,新增refresh_hint指示先刷新summary_path快照再派单;reservoir lane 保留推荐但 evidence 注明快照过期。spawn-worker route 兜底消费点同步适配非 ok 状态。测试矩阵覆盖 fresh/stale/missing generated_at/no-lanes 四态(22 单测 + 27 shell 测试,PM 合并树复跑通过)。触发事故:2026-08-29 FaroPDF 派单读到 3 小时陈旧快照,报 83% 实际 9%。
新增
- spawn-worker
--deps-mode依赖模式选择(Wave 10 T4,G31):新增auto|symlink|local三态(默认 auto 与既有行为完全兼容)。local:不软链主仓 node_modules,打印SPAWN_WORKER_DEPS_LOCAL提示(worker 首验前本地 install,授权走既有 install-guard 通道);auto智能升级:本次 spawn 显式传--allow-install-command(任务会改依赖)时自动选 local 并打印推断理由。断链 fail-closed 与 Python runtime-symlink 语义零变化。测试 18+27 全绿(PM 合并树复跑,含「显式 symlink 优先于 install 授权推断」用例)。触发事故:2026-08-30 FaroPDF 三连坑——软链拒 pnpm add / vite server.fs.allow 拒软链路径 / vitest 全挂,PM 每次 spawn 后被迫手工重建。 recover-unconfigured-worker.sh自动恢复(Wave 10b T5):spawn 后 terminal 里 agent 未起(agent_unconfigured/ no recognized agent 家族,实测约 20% 概率)时,一条命令完成原 PM 手工三步——读 Session ContextMETADATA.runtime.command重注入启动命令 → TUI 就绪 → 按 Task-092 基建register --reset-failed重绑 task;全程幂等(重复调用零新 terminal、零重复 register),不可恢复场景(terminal 已死/状态不明)显式manual-required指引而非静默重试。测试 30 用例四态矩阵(正常/幂等/terminal 死/manual-required)+ lifecycle 回归 10 用例全绿。触发事故:2026-08-30 五个 worker 中两度手工恢复,每次约 10 分钟。
[2.9.6] - 2026-08-30
改进
- 额度转可消费资产(Task-102/108,DEC-133):新增派发消费者合同(消费者、改变的决策/门禁、消费期、过期条件、可观察验收、资源 owner);
DRAFT不再自动派 docs-only,额度只在已成立任务之间路由,urgency=high不再允许扩张任务源或制造 quota-burn 工作。 - 验收背压与合理并发:默认全局/每波 worker ≤3、research/docs ≤1;PM 验收积压时停止扩波,探索窗口必须显式且限期。Autopilot 复盘改报消费者兑现、状态迁移、验收债务和进程净增量,不再用 PR 数或 value/filler 自评分证明价值。
- 外部进程生命周期:worker prompt 与收口 Hard Fail 增加服务/PID/进程组/端口 owner、端口关闭和零净增量证据;身份不明时失败关闭,禁止按进程名批量 kill 或误清用户既有服务。
- 派发价值机器门禁:新增零依赖
dispatch-value-gate.py、示例 spec 与确定性测试;机械拒绝非 READY、消费者六字段缺失、无状态迁移 docs/research、收敛并发/验收背压超限,以及启动外部资源却无 owner 的派单。worker prompt 将consume_by、expiry和observable_acceptance拆为独立字段。
[2.9.5] - 2026-08-30
修复
- 手工 register 自动恢复 supervised 路由(Task-092):
orca-supervised-register.sh在 worker/Dispatch 建立后,按精确 worktree id/path、terminal handle 与唯一 Session Context 自动补写完整.session.orca.supervised合同;无法唯一证明目标时输出ORCAREG_METADATA_BIND=manual-required,保留活跃 worker 且不重试启动。smoke-orca-control-plane.sh新增完整字段断言,reference 14 固化人工恢复和临时 terminal 活性证据边界。 - Autopilot 与引用单一权威:删除互相矛盾的旧 Wave Autopilot 副本,固定 reference 15 为 L1、reference 16 为 L2/L3 durability、reference 17 为模型能力档案;同步修复模板
references/12-issue-grouping.md断链和 SKILL frontmatter 版本漂移。 - 任务/决策编号纠偏:当前 Task-076/077 分别保留多层并行与 zcode,历史 Dispatch 自动补绑规范号改为 Task-106/107并保留可追溯别名;重复的 settle
DEC-034改为唯一DEC-130,新增 DEC-131 固定控制面权威。
技术优化
- Task-093 阶段性交付:
pm-closeout.sh移除eval,门禁改为 argv 执行;safe-push 路径和 Git identity 显式化;PR create/merge/view 错误不再吞掉,临时 body 只创建/传递一次。冲突 resolver 只处理 Git 确认 unmerged 的声明文档并主动 stage,字面冲突标记不再误报;Makefile 行级并集被明确拒绝。test-pm-closeout.sh在 throwaway Git 仓覆盖 20 项错误、成功与真实冲突路径,并纳入 SKILL 验收清单。Makefile 专用「基线整文件 + worker patch 重放」仍未实现,任务保持IN_PROGRESS。
文档完善
- 将文末 29 个非规范
TODO状态分诊为DRAFT/IN_PROGRESS/DONE,Task-066 在 durability schema、fencing/mutation 边界和故障注入合同齐备后晋级READY;移除 TASKS 尾部孤立残段。
[2.9.4] - 2026-08-29
修复
- route_suggest 自动补选不注入 provider env(实测抓出):补选只填 API_PROVIDER(lease 计数 + METADATA),worker 仍是裸
claude继承用户全局默认 provider——与 lease 计数的 lane 不一致,且实测 MiniMax 后端对继承配置报 400 modelCode 不存在。现在补选成功且命令为 backend 默认值(用户未显式--command)时,route_suggest_wrap_command用claude-provider-env.sh自动包装:注入config/<provider>.settings.json的 env +--model(取 settings 的env.ANTHROPIC_MODEL)+--permission-mode auto;settings 缺失/model 解析失败保持裸命令(fail-open 不阻断 spawn)。新增 stderr 标记行ROUTE_SUGGEST_ENV。端到端实测:L0 补选 minimax-M3 → worker 以 MiniMax-M3[1M] 真实完成文件创建任务。 - 测试 16→23 断言(wrap 四场景:注入/显式命令不包装/settings 缺失保持裸命令/非 claude-code 跳过 + 接线顺序断言);修复 helper 内
$model(全角标点在 set -u 下 unbound 的经典坑(memory 已有先例)。
[2.9.3] - 2026-08-29
新增
- 额度感知路由(quota-aware routing):PM 派单前按各模型 lane 的余量/窗口倒计时/健康常态评分推荐 provider,替代"任务卡写死 provider"的静态路由。
scripts/route_suggest.py(python3 零依赖纯决策器):中立契约 schemaquota-aware-routing.summary.v1(产出方不限:定时探针/网关/手写均可)、--tier/--scene/--task-card-path/--config参数、退出码约定(ok/locked_by_card/not_configured=0,degraded/all_lanes_stopped=1 供调用方降级)。评分语义:fuel 型 lane 按余量为主分 + 临期(resets_at 倒计时 < urgency_window 且余量高于判停线)加 0-50 分临期权重(urgency=high 提示 PM 扩大该 tier 本波任务量);reservoir 型(免费/积分、并发敏感)仅--scene匹配 reservoir_scenes 时入链且并发 cap=1;resets_at早于当前时刻标 pending_refresh 退静态序兜底;燃料 lane 全判停落 tier_policy.default。12 个单测覆盖降级/信号/评分全路径。 - spawn-worker 集成兜底:新增 sourced helper
scripts/spawn-worker-route-suggest.sh(函数 route_suggest_autofill_provider,接线锚点在 provider lease 消费 API_PROVIDER 之前);--api-provider缺省 + 个人配置quota_aware_routing.enabled且 backend 为 claude-code 时按ROUTE_SUGGEST_TIER(缺省 L1)自动补选,stderr 输出ROUTE_SUGGEST_AUTO行;route_suggest 任何失败(not_configured/degraded/崩溃)不改道不 fail,走既有默认链路;显式--api-provider永远优先(人工锁定 > 动态路由)。16 断言集成测试 + 现有 spawn-worker 系列 6/6 回归通过。 - 个人配置模板
quota_aware_routing段(config/orchestration-personal.example.json):enabled 默认 false(不配即无感)、summary_path 指向中立 schema v1 余量 JSON、lanes(fuel/reservoir + providers + concurrency_cap)、tier_policy(各 tier 候选链 + default 保底)、reservoir_scenes。模型池快照全在 gitignored 个人配置,skill 代码与文档零具体模型名。 references/17-model-capability-profile.md模型能力×任务匹配档案(2.9.5 统一编号;公开知识层):六大家族(GLM/MiniMax/DeepSeek/Kimi/Qwen/豆包)画像(档位/强项/弱项/典型任务正反例/部署形态中性描述/当期版本快照+"以你实际可用版本为准");fuel/reservoir 两类 lane 派单哲学;填 tier_policy 的五步指引;程序永不读取(纯知识文档,改它对运行时零风险)。- SKILL.md §9.1 额度感知路由小节:派单清单固化 route_suggest 必跑步骤、urgency=high 扩量语义、人工锁定优先、降级路径、能力档案指引。
[2.9.2.1] - 2026-08-29
- 守夜 v2 实战协议固化(Task-080):新模板
scripts/night-revive-timer.sh(7 参数 fail-closed+--repeat/--until打摆复活+nohup caffeinate -dis脱链)与templates/workers.tsv.example;SKILL.md §4.6 增四铁律(通道自测/双读核活法含游标推进法/硬死vs拥塞诊断树/task-list 完成权威)。 - §3.3 增第 5 条:DEC 编号预分配纪律(wave manifest 必须显式预分配号或禁止新增;2026-08-28 三波撞号教训)。
[2.9.2] - 2026-08-28
修复
- Task-076 自动补绑覆盖正常 spawn 派单路径(Task-077):2.9.1 的 dispatch-show 自检+三步自动补绑实现在
orca-supervised-register.sh,但orca-wave-preparereceipt 的 launch_contract 只要求传--orca-run-id/--orca-task-id/--orca-coordinator-handle三件套、未提主旗标--orca-supervised——PM 按此派单时三件套被 spawn 侧静默忽略(仅ORCA_SUPERVISED=1时消费),worker 走 terminal-managed 启动,Task 停 [ready]、dispatch-show 为空、SPAWN_WORKER_DISPATCH_BIND行不打印,PM 只能手动三步补绑(2026-08-28 Wave 20 双 worker 实测形态)。现在 launch 路径在 terminal 启动完成后,对已传入的--orca-task-id执行与 register 路径完全相同的自检+补绑并输出同款 DISPATCH_BIND 行;缺--orca-run-id的残缺组合在任何 terminal 副作用前失败关闭(exit 64);纯 terminal-managed(无 task)保持零变化。
同步
- 自检+三步补绑实现抽为公共函数
orchestration_dispatch_bind_selfcheck(orca-supervised-protocol.sh),register 路径(orca-supervised-register.sh)与 launch 路径(spawn-worker-launch.sh)共用同一份,输出合同(ORCAREG_ 前缀 stderr 日志 + KV)不变,杜绝双份漂移。 - launch 补绑成功后向 METADATA 写入与 supervised 分支同款的
session.orca.supervised块(run/task/coordinator/dispatch/bind),并输出SPAWN_WORKER_ORCA_PRECREATED_TASK_BOUND行;空 dispatch_id 下 pm-orchestrate 仍自动按 terminal-managed 路由,--with-sentinel的 dispatch-id 传递复用ORCA_SUPERVISED_DISPATCH_ID。 test-spawn-worker-launch.sh新增 5 个 Task-077 用例:健康路径不触发 mutation、dispatch-show 为空自动补绑 ok(含无--inject与单行注入与 METADATA 契约断言)、补绑失败 manual-required 不阻断、残缺组合副作用前 exit 64、纯 terminal-managed 零 dispatch 调用回归保护。- SKILL.md §3 硬约束补 launch 路径自检同权一行;frontmatter version 修正为 2.9.2(2.9.0/2.9.1 时漏更)。
[2.9.1] - 2026-08-27
修复
- spawn 后 Dispatch 绑定静默缺失的自动检测与补绑(Task-076):2026-08-27 三波实战(badminton-lab Wave17 bl-011-resume / Wave18 bl-012-contract / Wave19 双 worker)中,
orca-supervised-register.sh的 worker-start 成功拉起 TUI 并注入任务,但 Orca 不识别终端内 agent(agent_unconfigured/ no recognized agent 家族)导致 Dispatch 未绑——Task 停 [ready]、dispatch-show --task为空、worker_done 无通道,此前只能靠 PM 人肉发现并按 runbook #18 三步补绑。现在 worker-start 后主动dispatch-show --task核对;receipt 与 dispatch-show 均为空时自动执行补绑三步(无--inject的 dispatch 建绑定 → 从响应/preamble 提取真实 ctx id,多 id 歧义宁拒不猜 → 单行 terminal send 注入 worker_done/ask 精确命令形式,多行文本会在 TUI 提前回车),并以ORCAREG_DISPATCH_BIND=ok|manual-required汇报;manual-required不再以 exit 1 阻断 spawn(terminal/任务注入已生效),改为显式告警 + WARN 打印手动三步。 spawn-worker-launch.sh消费绑定结果:SPAWN 输出新增SPAWN_WORKER_DISPATCH_BIND: ok|manual-required行;METADATAsession.orca.supervised新增dispatch_bind字段,manual-required时仍写入 run/task/coordinator(PM 手动补绑的输入),空dispatch_id下 pm-orchestrate 自动按 terminal-managed 路由。
同步
- SKILL.md §3 硬约束与 §4.6 看门狗各补一行(DISPATCH_BIND 行纳入 spawn receipt/每跳巡检);
references/13§10 METADATA 契约示例补dispatch_bind字段。 test-spawn-worker-orca.sh新增 4 个 Task-076 用例(ORCA_CLI_COMMANDfake CLI 子进程跑 register):健康路径不触发补绑、dispatch-show 空自动补绑 ok(含无--inject与单行注入断言)、补绑失败 manual-required 不阻断、绑定成功但注入失败仍 manual-required;test-spawn-worker-launch.sh断言 METADATA 新契约并新增 manual-required 不阻断 + run/task 保留用例。
[2.9.0] - 2026-08-27
新增
- zcode 成为第五个 worker backend(Task-077 转正,DEC-129):ZCode 桌面端内嵌的官方 CLI(GLM 官方 Harness)可作为 worker 派发,消耗 BigModel Coding Plan 额度(与 GUI 同端点同凭证,官方活动期内享渠道加成)。因 zcode 无独立 TUI(
@zcode/tui未随桌面端打包),采用 driver 模式:新脚本scripts/zcode-worker-driver.py长驻zcode app-server子进程(stdio 私有协议,自动应答每 turn 的session/requestRuntimePreferences——15s 窗口超时即prompt_failed),PMsend的文本经session/send进程内注入(零重启纠偏),事件流渲染为可读行供 tmux/Orca 巡检;本地命令/status /stop /compact /quit。 - 身份门禁扩展:
canonical_harness_backend加zcode;validate-worker-command.py新增 trusted-driver 通道(--trusted-zcode-driver,唯一放行的 python 形态,realpath 锁定 skill 内脚本);harness-backend-policy.json的 claude-code/codex 派发集加 zcode(zcode 不做 PM host)。install-guard 走 prompt-only(同 codex,需--allow-prompt-only-install-guard)。 - render/check-dependencies 支持:
render-runtime-profile.sh --backend zcode(interactive=driver、batch=headless--mode yolo);check-dependencies.sh --backend zcode三层检测(PATH/bundle/~/.zcode/cli/config.jsonmodel+provider,缺失给修复指引)+--print-bundle-path zcode。 - 新测试
test-zcode-driver.sh(8 用例,stub app-server,CI 无需 ZCode.app):config fail-fast ×2、偏好自动应答、create 派发、stdin→session/send 转发、sessionId 捕获(真实嵌套结构result.session.sessionId)、事件渲染;策略矩阵补 zcode allow/deny(含 codebuddy/qoder PM 派 zcode 拒绝、evil-driver 拒绝)。 - 新文档
references/09-zcode-cli-worker.md(协议/凭证链路/限制/实战坑,真机验证记录);references/06速查表/对比矩阵/tmux 模板补 zcode;SKILL.md 四→五 backend 同步。
修复
- driver 时序缺陷(真机端到端暴露):create 完成前到达的 PM 消息由 queue+drain 缓冲不丢弃;
/quit等待 backlog flush(上限 10s)。
边界澄清
- G24 辨析:G24 及 SKILL §1「ZCode 类非 CLI harness 不做 PM」约束的是 ZCode GUI 会话扮演 PM;zcode CLI 作为 worker backend 是正交能力,两者并存不矛盾(DEC-129 记录)。
[2.8.1] - 2026-08-27
新增
- 新增
pm-quota-stall.sh与加固后的night-watch.sh(Task-064):用可移植的有界探针区分 quota、配置、认证、网络、timeout 与未知错误;只有同一 watcher 明确观察到quota → available才向调用方提供且 show 回执为同一可写 handle 的 terminal 注入一次唤醒。模型与 provider/account settings 权威文件必须显式提供,settings 内容指纹冻结且自动唤醒拒绝可变 setting-sources;首次即 available、所有非额度失败和 terminal show/send 失败均 fail-closed。 - 新增两组确定性回归,覆盖武装状态机、混合错误文本优先级、精确且可写 terminal 身份、settings 内容指纹、探针副作用约束、原子锁、时限与输入门禁。
修复
- 修复从符号链接 Skill 目录调用 spawn 时,
orca worktree create可能按脚本物理 cwd 绑定到错误仓库的问题(Task-073):create 现在 scoped 到已验证的PROJECT_DIRGit top,并在任何 Session Context/terminal 副作用前核对 repoId;畸形或错配只精确回滚可证明归属的 worktree/branch,无法证明时保留现场并明确报错。 - 修正 Autopilot 判活合同:运行时活性与业务进展分维度观察;cursor/CPU/时间戳静止不再单独等同假死,探测默认只读且不自动 interrupt/stop/release。
技术优化
- Wave manifest、quota JSON 和 Orca create 响应解析全部改为显式 fail-closed,Skill Harness failure audit 降至 0 finding;Harness 回归在“进程身份与同 worktree 另一 working agent 冲突”时验证正确失败关闭,不再把合法冲突环境误报成测试失败;公开参考与 Orca fixture 中的本机绝对用户路径替换为可移植示例路径。
验证
test-pm-quota-stall.sh39/39、test-night-watch.sh31/31、test-spawn-worker-orca.sh41/41 通过;Skill Harness failure audit 0 finding。真实 provider 429、真实 PM terminal 端到端唤醒,以及真实 Orca 中故意制造的破坏性跨仓 create 均未执行并标记NOT_VERIFIED。
[2.8.0] - 2026-08-26
新增
- Wave Autopilot 模式(Task-062,
DEC-125):references/15-wave-autopilot.md+ SKILL.md §4.6。用户显式授权后,PM 按项目任务源固定策略自动链式推进波次直到泊车。核心机制:监控三通道并用(Orca 推送 + recurring cron 看门狗 + Dispatch 状态轮询;完成权威是worker-show的 dispatch/worker 状态而非队列消息——实测 worker_done 推送可延迟 6.6h 不唤醒 PM);授权与组波/泊车策略权威留在项目上下文,skill 只定义机制与不变量;验收路径不因自动化放宽(最终树门禁复跑 + safe-push + PR squash);泊车 fail-closed、每波摘要不阻断。含验收期确定性缺陷的 fix-worker 派发模式(新分支名 +--base-ref origin/<原分支>避 worktree 撞车)与 8 条实测反模式清单。来源:badminton-lab Wave 4/5(PR #21—#25)完整生命周期实战。
[2.7.1] - 2026-08-26
改进
- 内部上下文同步:
references/10-parallel-lessons.md新增 G39(badminton-lab Wave 4)——同账号多 claude-code worker 的 5 小时限流同时触发;429 打断 turn 后 TUI 停在 idle,pm-orchestrate send投递 Dispatch inbox 叫不醒(ok:true≠ 被消费),须用orca terminal send --text ... --enter键盘注入唤醒;判活看peektranscript 时间戳与当前的差值而非 tail 文本。SKILL.md §7 增补对应唤醒指引一句。纯文档变更,无脚本改动,全部脚本bash -n通过。
[2.7.0] - 2026-08-25
新增
pm-orchestrate reauthorize子命令(Task-058):spawn 授权快照的运行时刷新一条命令化——合并--allow-cmd进授权文件、重写launch.sh内联 B64(guard 读进程环境快照,直接改授权文件对运行中 worker 无效)、把被提问/中止翻成 failed 的 Task 复位 ready、在同一 worktree 创建新终端并复用 Task 重注册(worker-start 重注入完整任务)、改写 METADATA 终端/Dispatch 路由、可选发送--resume-text续接说明、关闭旧终端。未提交的工作区改动全部保留。badminton-lab Wave 2 事故的 7 步手工抢救链路固化。spawn-worker.sh --python-runtime-symlink PATH(Task-061):Python 项目 PM 显式授权共享主仓.runtime(venv/models)。fail-closed:worktree 已有.runtime保留、源解释器缺失或为 0 字节占位拒绝启动、软链失败退出非零。clean-worktree.sh删除 worktree 前安全 unlink 该软链(防 untracked 软链让git worktree remove视为脏)。orca-supervised-register.sh --reset-failed(Task-060):worker-start被task_not_startable拒绝时复位 Task 到 ready 重试一次;不带旗标保持 fail-closed。
改进
inject_default_verify_commands增加 Makefile 兜底(Task-057):npm scripts 零注入时解析 Makefile^target:目标,白名单动词test / test-* / check / ci / lint注入make <target>;.PHONY/变量赋值/文件目标不匹配,npm-first 双清单项目不双注入。根因:Make 驱动的 Python 项目(无 package.json)此前零注入,worker 全部 make 门禁被SHELL_COMMAND_NOT_ALLOWLISTED拦截。orca-wave-prepare.shfail-closed 拒绝 spec 内含斜杠的 branch 名(Task-059):Orca worktree--name与safe_branch会把/规范成-,spec 写斜杠名会让 worker 隔离门禁误判 blocked(Wave 1 三 worker 同时跑偏);路径引用(如docs/plans)不误报。pm-orchestrate read接受--limit作为--lines别名(与orca terminal read参数名对齐)。- 内部上下文同步:
references/10-parallel-lessons.md新增 G34—G38(Make 零注入、B64 快照陷阱、Task failed 翻转、基线落后假删除、spec 斜杠分支名);references/14-pm-orchestrate.md增补 reauthorize 契约;references/03-checkpoint-files.md明确 supervised 下 STATUS 为辅助信号;templates/pm-spawn-postflight.md增补SPAWN_WORKER_VERIFY_INJECTED*回看;DECISIONS.md新增 DEC-124(刷新放命令层、不动 guard B64 优先级)。 - SKILL.md:§3.2 记录 Makefile 兜底与 python-runtime-symlink;§4.4 增加『spec 分支名一律连字符』『共享文档编号预分配(DEC/CHANGELOG 槽位)』与
--reset-failed;§4.5 增加 reauthorize 用法块;§6 明确 supervised 模式 STATUS 是辅助观察信号(完成权威是 Delivery,spec 不应要求周期性 STATUS 更新)。
验证
test-spawn-worker-deps.sh13/13 PASS(新增 Case 8-13:Makefile-only/混合/npm-first 三态 + 运行时软链有效/假解释器拒绝/已有保留)。- 全部改动脚本
bash -n通过;lint-wait-script.sh通过;斜杠 spec 拒绝三态实测(拒绝/放行/路径不误报)。
[2.6.3] - 2026-08-14
改进
inject_default_verify_commands默认注入清单由typecheck/lint/test/build扩展为typecheck/lint/test/test:e2e/build:test:e2e是 verification-gate 的功能完成线(编译过 ≠ 功能可用,FaroPDF 2026-08-05 QA-02 教训),项目package.json声明该 script 即默认进 worker verify 白名单;未声明的项目由grep -qx守卫自动跳过,行为不变。SKILL.md §3.2 同步。
验证
test-spawn-worker-deps.sh7/7 PASS(fixture 无test:e2escript,守卫正确跳过,验证不注入劣化路径)。
[2.6.2] - 2026-08-14
修复
- 修复带空格 worker command 的
--dry-run仍创建 Session Context 并写入launch.sh的副作用;预演现在只报告最终 wrapper 路径与命令,不创建目录、文件或执行权限。 - 保持非 dry-run 的
launch.sh内容、tmux/Orca transport 和 supervised 注册路径不变。
验证
test-spawn-worker-launch.sh从 11 个扩展到 16 个断言,新增 helper 与真实入口的 dry-run 零写入检查;完整生命周期、权限、Wave、settle、Sentinel、tmux 和 Orca 回归通过。
[2.6.1] - 2026-08-14
改进
- 完成 Task-048 的渐进解耦:把
spawn-worker.sh的 usage/flags、Orca runtime 与 terminal helpers、Session Context metadata、provider lease 和 tmux/Orca 共用启动边界拆成 5 个 sourced 模块;入口脚本由 1,944 行降至 1,131 行,保持既有 CLI、全局输入输出和生命周期顺序。 - 明确模块只承载单一职责、不得绕过入口门禁独立执行生产副作用;后续行为变化须另立任务,不与结构移动混合。
新增
- 新增 5 组直接合同测试,共 86 个断言,覆盖参数重复项与 toggle、Orca 回退/能力门禁、metadata schema、lease 临时失败与精确 transport 绑定、tmux/Orca launch 及 supervised receipt 注册。
验证
- 每个切片均运行完整回归;最终通过新增模块测试、dependency guard 58/58、Harness 26/26、worker command 15/15、依赖补偿 7/7、Wave 10/10、settle 10/10 + 14/14,以及 Sentinel、tmux、Orca runtime/control-plane 和 auto-bypass smoke。
[2.6.0] - 2026-08-14
新增
- 新增
orca-wave-prepare.sh与 Wave receipt:在任何 worker 启动前创建/绑定一个 Run、预建全部独立 Task,并固化 coordinator handle;并发 spawn 直接复用run_id/coordinator_handle/task_id,不再并发 rebinding 或重复建 Task。 - 新增统一 Task-spec 完成协议前缀,要求 worker 使用 live preamble 的真实 IDs 精确发送一次
worker_done;明确 commit、tests、STATUS、heartbeat 与 idle 都不能结算 Dispatch。 - 新增
test-settle-command.sh、test-orca-wave-lifecycle.sh与test-spawn-worker-deps.sh,覆盖生命周期 mutation 顺序、失败资源保留、精确 worktree 删除、持久审计、Wave 并发屏障和依赖补偿失败关闭。
修复
- 重写
settle为当前 Orca lifecycle:严格 known-dead 双信号门禁后先调worker-stop原子 fence+stop;stop 失败仅尝试一次worker-abandon兜底并禁止 destroy,避免旧版 abandon→stop 顺序和“stop 失败仍删除”风险。 --destroy在破坏性删除前校验 METADATA.project 与 worker 属于同一 Git common dir,先释放 provider lease,再由 Orca 删除精确 worktree,最后只对完全匹配路径执行 Git fallback;修复前缀匹配失效、Session Context 删除后丢 worktree ID 和审计随 worktree 消失的问题。- liveness gate 改为严格 allowlist:只有
observation.status=exited|missing且worker.state=succeeded|failed|stopped通过;缺字段、active 和未知未来状态默认拒绝。 - 依赖补偿对断裂
node_modulessymlink 或创建失败改为 spawn 非零退出,避免 worker 已启动但无法执行验证。
改进
- worker Shell 门禁新增 Orca 自报告语义白名单:只允许带真实 task/dispatch、subject/body/outcome 和有界 timeout 的
worker_done/heartbeat/escalation、ask与只读check;拒绝task-update、worker-stop、群发、缺 outcome 和 shell chaining。 - PM 的 supervised mutation/wait/accounting 命令先
run-use绑定当前终端并刷新 METADATA coordinator handle;wait/ack消费当前绑定 Run,不再传陈旧--run。 SKILL.md、Orca/PM references 与 postflight 模板区分业务验收和 lifecycle settlement,并按 supervised、terminal-managed、tmux 三种模式给出独立巡检与收口协议。
验证
- 新增回归分别达到 dependency guard 58/58、Wave lifecycle 10/10、settle liveness 10/10、settle command 14/14、worktree dependency 7/7;完整 smoke 与静态门禁结果见本版本任务验收记录。
[2.5.4] - 2026-08-14
新增
pm-orchestrate settle子命令(Task-047 v2,PR #84 review 修复版):supervised dispatch 死锁兜底——worker 进程死但未发worker_done时,按 Orca 官方 lifecycle fence+stop(worker-abandonfence dispatch、worker-stop停 terminal),不破坏 METADATA。默认安全(不删 worktree/files,PM 后续跑clean-worktree.sh --execute --force-remove-dirty);--destroy一站式清理(含 symlink unlink + dirty 检查 + git worktree remove + orca worktree rm + lease release + session_context 清)。--reason强制审计;liveness gate 用真字段.result.observation.status/.result.worker.state,任一缺失或仍 active → REFUSED(除非--force)。
修复
- PR #84 review BLOCKER 1:liveness gate 不再用
.result.workerSession(该字段在真 Orca 响应里不存在 → 永远 DEAD 等于无门槛,会误杀活 worker)。 - PR #84 review BLOCKER 2:不再删 METADATA(导致 dispatch/run_id 丢失,
worker-abandon变 unrecoverable leak),保留 METADATA 给 PM 后续清理。 - PR #84 review MAJOR 3:--destroy 路径先 unlink
node_modules软链([ -L ] && rm -f无尾斜杠),不跟随软链误删主仓。 - PR #84 review MAJOR 4:provider-lease release fail-loud(禁止
>/dev/null 2>&1吞错),失败 exit 非 0。 - PR #84 review MAJOR 5:--destroy 路径含 dirty 检查 + git worktree remove,与
clean-worktree.sh同步。 - PR #84 review MAJOR 6:references/13-orca-cli-worker.md §9 + references/14-pm-orchestrate.md 命令清单同步更新(之前文档与 v1 行为矛盾)。
改进
- PR #84 review MINOR 7:session_context 删除顺序正确(--destroy 末尾,且 fence+stop 已成功)。
- PR #84 review MINOR 8:liveness gate 兼容
set -euo pipefail(局部set +e +o pipefail),PARSE_ERROR fallback 可达。 - PR #84 review NIT 9:
--force/--reason是 settle-specific(cmd_settle 内部局部变量),不污染其他子命令;--reason用于审计。 - PR #84 review NIT 10:新增
scripts/test-settle-liveness.sh(9 fixture cases)+scripts/tests/fixtures/worker-show-*.json(真 Orca worker-show 完整包装 response)。
修复(PR #86 review-v2,对真 Orca CLI 验证后)
- BLOCKER B1:
settle_liveness_checkjq 路径缺.result前缀(fixture 预解包导致测试绿但生产无效——同 v1 BLOCKER 1 形状)。改.result.observation.status/.result.worker.state;fixture 改完整包装(含_meta/id/ok/result)。gate 逻辑改:拒绝active/input_accepted(活),允许missing/exited/succeeded(死/GC),双 ABSENT 保守拒绝(completed dispatch 的 observation 在 GC 后是missing非exited)。 - BLOCKER B2:
--force未在全局 args 解析(cmd_settle 内部解析是死代码,$@ 在 dispatch 时空)。全局加--force) FORCE=1,cmd_settle 读${FORCE:-0}。 - MAJOR M1:删无效 symlink
scripts/tests/fixtures/fixtures(残渣,指错绝对路径)。 - MAJOR M2:
--reason持久化到SETTLE_AUDIT.log(之前只 echo);usage "encouraged" 改 "required"。 - MAJOR M3:
worker-show/worker-stop调用用set +e保护(set -euo pipefail下失败击穿脚本,liveness REFUSED 和 WARN 分支不可达)。 - MAJOR M4:
settle_destroy_worktree注释改"故意偏离 clean-worktree 顺序"(git 先 vs orca 先,所有权语义不同)。 - MINOR m1:
wt_id空时 WARN(不静默跳过 orca worktree rm)。 - MINOR m2:usage "encouraged" 与强制矛盾修正(并入 M2)。
- NIT n1:测试用 env var 传 JSON(避免 eval 单引号脆弱)。
- NIT n2:fixture 加 README 说明(observation GC 语义 + 死锁未真测)。
[2.5.3] - 2026-08-14
改进
references/05-legal-domain-patterns.md§2.1 新增「诉讼 worker 的证据访问约定」(Task-049):澄清代码node_modules「隐式解析 → 必须软链」与诉讼证据「显式访问 → 绝对路径直读」的机制差异;规定 PM spawn 诉讼 worker 时 prompt 必须包含「主仓项目根 + 案件相对路径 + 产出写路径 + md 引证用相对名」四要素,并明确反模式(不软链证据目录、不硬编码绝对路径、不让 worker 假设完整路径)。文档示例全部用<占位符>表达,不绑定具体运行机器/案件,保证 Skill 跨用户可复用。
[2.5.2] - 2026-08-14
改进
- SKILL.md §3.3 新增「PM spawn 操作纪律」(Task-041~044,Wave-2 实战撞坑固化):spawn 后不重复 send 完整 prompt(与
worker-startlive preamble 重复,Task-042);run-create只调一次避免consumer_fenced(Task-043);supervised worker 不用pm-monitor/sentinel判完成(靠worker_done → Delivery,Task-041);spawn 前后独立 Bash 调用并行(Task-044)。
[2.5.1] - 2026-08-14
修复
- Orca supervised worker 无法自验(Task-045/046,G31):worktree 落在
~/orca/workspaces/(独立路径树,不在主仓父链)→npm run向上解析找不到主仓node_modules→tsc/vitest/eslint: command not found;VERIFY_COMMANDS默认空 →allowed_shell仅 3 条 → worker 跑不了验证门/推不了 PR。tmux worktree 靠在主仓子树(.claude/worktrees/)的路径巧合白嫖向上解析(G28),Orca 路径打破后塌方。
新增
scripts/spawn-worker-deps.sh(独立 source 文件,不加剧 spawn-worker.sh 膨胀):ensure_worktree_deps项目类型感知依赖补偿(Node 软链node_modules/ Rust cargo 共享 / Python venv 路径敏感标 blocked);inject_default_verify_commands按package.jsonscripts 注入默认npm run typecheck/lint/test/build到白名单(PM 显式--verify-cmd优先不覆盖)。spawn-worker.shsource deps + 两处调用(worktree 创建后ensure_worktree_deps、write_install_authorization前inject_default_verify_commands)。clean-worktree.sh删 worktree 前安全 unlinknode_modules软链([ -L ] && rm -f无尾斜杠,绝不跟随删主仓)。
改进
SKILL.md§3.2 +worker-prompt.md+ G31 lesson(references/09)说明依赖补偿 + 默认 verify 机制;G31 含「统一 Orca worktree 路径到主仓」的 A-否决查证(Orcaworktree create无--path,软链是唯一实际补偿)。
[2.5.0] - 2026-08-13
修复
- Harness 权限改为对完整可证明祖先链取白名单交集;弱宿主嵌套 Codex/Claude Code 仍只能保留弱权限,链路读取不完整时失败关闭。
- 新增 worker backend/启动命令身份绑定,拒绝标签伪装、命令链、不透明 wrapper 与任意命令替换;安装守卫的 prompt-only 降级不再能绕过 backend 身份门禁。
- Harness 的 Orca 证据统一使用版本匹配的
orca-runtime.sh,避免权限检测与 worker 控制选择不同 CLI。
新增
- 新增跨 worktree 的 provider 原子并发租约:按个人配置在副作用前占槽,启动后绑定精确 tmux session 或 Orca terminal,并在真实资源结算后释放。
- 租约存放于 Git common dir 的可信根,使用文件锁与原子写入;释放同时校验可信路径、session、资源句柄和运行时存活状态,未知状态失败关闭。
- 新增
test-worker-command-policy.sh与test-provider-lease.sh,覆盖四后端 renderer、wrapper、伪装命令、额度竞争、陈旧租约、越界路径和存活资源提前释放。
改进
- Orca worktree 创建显式继承项目 setup 策略;继续采用门禁优先的两阶段启动,不直接切换会在权限文件落盘前启动 Agent 的
worktree create --agent。 - 当前运行合同明确收口为 Claude Code、Codex、CodeBuddy、QoderWork CN 四个 backend;OpenCode/custom 等旧内容只保留为历史调研或独立诊断,不构成派发授权。
- 同步
SKILL.md、Orca reference、个人配置模板和根 README 的 v2.5.0 说明,传统 tmux 路径保持可用。
验证
- Harness 层级门禁 26/26、命令身份门禁 15/15、provider lease 原子与生命周期回归全部通过。
- 在 Orca 1.4.180 中使用本地无模型调用的假 Codex 完成真实 worktree/terminal/metadata/lease/close/clean 闭环;终端关闭后为
connected=false、writable=false,未消耗模型额度。
[2.4.0] - 2026-08-13
新增 — Harness 调用层级门禁
- 新增
config/harness-backend-policy.json和scripts/harness-backend-policy.sh:Claude Code/Codex PM 可派发 Claude Code、Codex、CodeBuddy、QoderWork CN;CodeBuddy 与 QoderWork CN PM 只能派发自身。 - 派发 backend 收口为上述四种;旧版兼容代码中出现的 OpenCode、custom 或未知 backend 均不再获得 spawn 权限,防止个人配置扩张授权面。
spawn-worker.sh在创建 worktree/terminal 之前从真实进程祖先识别 PM 宿主,并在 Orca 能唯一定位 working agent 时交叉校验;多 Agent 共用 worktree 时不让模糊 UI 信号覆盖进程证据,未知、真实冲突或不可证明身份仍失败关闭。--pm-harness仅作为预期身份断言,不能覆盖运行时证据或向上提权;授权结果写入METADATA.runtime.harness_authority。
测试
- 新增
test-harness-backend-policy.sh,覆盖 10 个允许组合、8 个拒绝组合、未知 backend、运行时识别及伪造宿主断言。 - 既有 Orca/tmux smoke 改用已配置 backend,确保层级门禁进入真实 spawn 回归而非只做静态文档约束。
[2.3.0] - 2026-08-12
修复 — Orca runtime 与 supervised 生命周期
- Orca auto-detect 改用
worktree current的实际项目路径,不再依赖真实会话可能缺失的TERM_PROGRAM/ORCA_WORKTREE_ID;新增scripts/orca-runtime.sh统一版本匹配 CLI。 - supervised 注册固定为共享 Run 下的
task-create → worker-start --terminal,worker-start 成为唯一任务注入器;注册失败返回非零并保留恢复证据,不再静默降级为“看似 supervised”。 - Sentinel 不再根据 STATUS/timeout 自动 stop、release 或关闭 supervised terminal;
worker_done、完整 Delivery、reuse/release/retain、ack 成为单一结算顺序。 clean-worktree.sh仅在 Dispatch 已 settled 且 terminal accounting 可证明安全时结算,active/unknown/release_pending/release_unknown 均失败关闭。pm-orchestrate.sh扩展为 supervised / terminal-managed / tmux 三模式,支持 Dispatch guidance、worker transcript、show、Delivery wait、reply、release、retain 和显式 ack。- supervised 注册保存并显式传递 coordinator handle,修复真实 Run 下的
consumer_fenced;external terminal 清理增加 settled 状态、ownership/reason 与精确句柄四重校验。 - Codex render 识别已固定相同 sandbox/approval 的本地安全 launcher,避免重复参数导致 CLI 启动失败;不匹配或不可证明时仍显式传参。
改进 — Orca-first 多 CLI 总控
- CodeBuddy、QoderWork 和 custom CLI 可保留在 Orca terminal-managed 层,由 UI 展示 worktree/branch/terminal,PM 用 terminal read/send/wait 巡检;未被 Orca 识别时不伪造 Task/Dispatch。
- trust/permission/external-import watcher 支持 Orca terminal read/send,不再因脱离 tmux 而失效。
worktree-status.sh和pm-monitor.sh统一使用实际 Orca CLI;文档重写为双层能力、运行时检测、共享 Run、UI 状态来源和恢复边界。- terminal-managed
read支持 Orca cursor 增量读取,并明确tui-idle只是 liveness/readiness,不能冒充任务完成信号。
安全与 Git
- 根
.gitignore新增**/config/*.bak*,阻止带真实凭证的 provider 配置备份进入普通 Git 历史。 - 核查确认既有 Orca 提交已经进入
origin/main,因此不重写公开历史,改用本版本前向修复 metadata/version 漂移与契约问题。 SKILL.md新增本地命令、worktree/terminal、Orca 状态写入、清理与 provider Token 的权限/副作用声明。SKILL.md从 1000+ 行压缩为核心路由与生命周期入口,backend、checkpoint、Sentinel 和历史踩坑继续按需下沉到既有 references,恢复 Progressive Disclosure。
测试
- 新增
smoke-orca-control-plane.sh,以本地 fake CLI 验证注册顺序、Dispatch 路由、worker-read、Delivery wait 不自动 ack 及 release/retain/ack 命令。 smoke-orca-worker.sh覆盖无宿主环境变量识别、opt-out、轻量模式边界与 supervised 单一注入。- 修正
claude --bare安装门禁回归断言,与既有“明确记录 prompt-only 降级”设计一致。 - 真实前向矩阵:Claude Code 与 Codex 在 Orca supervised 中完成
worker_done → Delivery → external terminal 结算 → ack;CodeBuddy 在 Orca terminal 中得到完整响应;QoderWork 验证 cursor history 与批处理响应;传统 tmux 下 Codex 完成响应,Claude 启动/收发链路通过但当次 provider 因 429 额度限制未完成模型响应。 - 六份 Claude provider settings 探针 5 份通过;MiniMax M2.7 返回 401,需更新本地凭证。
[2.2.0] - 2026-08-12
新增 — PM 控制 worker 统一入口(Task-034)
PM 90% 场景用 pm-orchestrate.sh 一个统一入口控制 worker(ORCA / tmux 双模式自动判断),不用手敲 orca terminal send 或 tmux send-keys。
scripts/pm-orchestrate.sh新脚本:子命令send / read / peek / wait- 读
<worktree>/.claude/agent-sessions/<session>/METADATA.json自动路由:session.orca.terminal_handle非空 → ORCA(orca terminal send/read/wait)- 否则 → tmux(
tmux send-keys/capture-pane,session 名 =<session>)
send超长(>500 字符 或含反引号/$/|/)自动走 SKILL §5.2 WORKER_PROMPT.md + 短 Read 指令(避免终端注入转义问题)peek=read --lines 15(PM 快速 peek 常用)waittmux 模式无原生 tui-idle,降级 sleep(建议用 sentinel.sh)
端到端验证(ORCA claude worker):send --text "请只回一句:pm-orchestrate send OK" → read --lines 100 显示 ❯ 请只回一句:pm-orchestrate send OK + ⏺ pm-orchestrate send OK,PM 一个命令管 worker ✓。
references/14-pm-orchestrate.md新 reference:双模式自动判断 + 子命令 + 与 sentinel/pm-monitor/CLI 兜底的关系 + 实战范例 + 已知限制- SKILL §7.1 ORCA PM 分支加 pm-orchestrate 段落(替代手敲 orca terminal send)
- SKILL §10 references + scripts 列表加 references/13 和 pm-orchestrate.sh
非 ORCA / tmux 不受影响(向后兼容,PM 不传也用 tmux 默认)。
[2.1.0] - 2026-08-12
新增 — ORCA 检测 + STATUS.json 分层互补(Task-032)
sentinel ORCA 模式 done 判定加双信号:STATUS=done 时先查 orca worktree ps 的 agent state,working 拒绝认终态(抗 worker LLM 谎报 done),done/idle 才 sync + exit。ORCA 检测(进程层客观)+ STATUS.json(任务层自报告)分层互补。实测:claude worker 跑 sleep 30(state=working)+ 谎报 done → sentinel 12s 内 5 次 SENTINEL_ORCA_STATUS_CONFLICT 拒绝误杀。
sentinel.sh:orca_agent_state()函数(查 worktree ps 的.worktreeId匹配 +agents[0].state);done 分支双信号判定
新增 — ORCA supervised 深度对接(Task-033)
spawn-worker --orca-supervised flag:ORCA 模式 spawn 后把 worker terminal 纳入 ORCA supervised 体系(run-create + task-create + worker-start --terminal),保留 provider env 隔离。worker 出现在 worker-list,绑定 task + worktree resource,可被 send/reply/inbox + gate 管理。
scripts/orca-supervised-register.sh新 helper:run-create + task-create + worker-start --terminal --worktree --task;输出 run_id/task_id/dispatch_id(KV)。worker-start 前 sleep 6s(runtime 注册延迟)+ 单次不 retry(retry 致 task_not_startable/failed)+ worker-list 兜底查 dispatch(应对 runtime_unavailable 但 server 端成功)spawn-worker.sh:--orca-supervised/--task-spec/--task-titleflag;ORCA 模式调 helper;METADATAsession.orca.supervised.{run_id,task_id,dispatch_id};SENTINEL_CMD 加--dispatch-idsentinel.sh:--dispatch-id参数 +sync_orca_supervised_release();done→worker-release, failed/timeout→worker-stopclean-worktree.sh:读 METADATA dispatch_id,清理时 worker-stop(在 orca worktree rm 前)references/13-orca-cli-worker.md§11:supervised 体系 / spawn 集成 / 全生命周期闭环 / helper 踩坑 / PM 巡检增益
端到端验证(真实 claude worker):spawn --orca-supervised → worker-list workerState=ready → sentinel done worker-release → clean --execute worker-stop + worktree rm,全链路通。
改进 — ORCA 模式 task-032/033 配套
- SKILL §6.5 加 supervised 深度对接 + 分层互补段落
- 非 ORCA / 不加
--orca-supervised零变化(向后兼容 v2.0)
[2.0.0] - 2026-08-12
新增 — ORCA CLI worker backend(DEC-114)
PM 在 ORCA 桌面端内嵌终端里调 spawn-worker.sh 时,auto-detect 走 ORCA worktree + ORCA terminal 路径,ORCA UI 直接反映 worker 生命周期(spawn 立即出卡 in-progress、sentinel 终态自动切 completed/in-review、stale 同步 in-review、clean-worktree 删 ORCA 跟踪)。
触发:TERM_PROGRAM=Orca + ORCA_WORKTREE_ID 非空 + worktree path 段 = PROJECT_DIR git toplevel + orca status --json 成功 + capability 含 terminal.multiplex.v1。命中走 ORCA;非 ORCA 终端 / 跨 repo / --no-orca-mode 走原 tmux 路径不变。详见 SKILL §6.5 + references/13-orca-cli-worker.md。
改动:
scripts/spawn-worker.sh:新增detect_orca_mode()/orca_worktree_create()/orca_terminal_create_and_send()三个 helper +--no-orca-modeflag + METADATAsession.orca子块(mode / worktree_id / worktree_path / terminal_handle / tui_ready_method / app_version / capabilities);ORCA 模式跳过 trust/permission/external-imports dialog 监控(ORCA 桌面端自管)scripts/sentinel.sh:新增--terminal-handle --worktree-id双路径(与--tmux-session二选一)+sync_orca_worktree_status()(done→completed / failed→in-review / timeout→in-review)scripts/pm-monitor.sh:新增orca_worktree_set_status()helper;CHECKPOINT_STALE+WORKER_STALE_NO_COMMIT两个 emit 后同步 ORCAin-reviewscripts/clean-worktree.sh:tmux kill 后加orca worktree rm --force同步清理 ORCA 跟踪(dry-run 友好)scripts/worktree-status.sh:加 ORCA 只读状态块(ORCA_WORKSPACE_STATUS/ORCA_CARD_STATUS/ORCA_COMMENT)references/13-orca-cli-worker.md:新建完整 Level 2 reference(9 节:边界 / 检测协议 / ORCA API 速查 / METADATA 锚点 / sentinel 双路径 / pm-monitor 同步点 / clean-worktree 清理 / 已知限制 / 实战范例)SKILL.md:§6.5 ORCA 终端模式新节 + §7.1 加 ORCA PM 分支 + §10 references 加 references/12
改进 — ensure-claude-path.sh 参数化为 ensure_in_path <bin>
候选目录追加 /Applications/Orca.app/Contents/Resources/bin,让 spawn-worker.sh ORCA 模式可直接 ensure_in_path orca 探测 ORCA CLI。保留 ensure_claude_in_path 作为 ensure_in_path claude 的别名,所有现有调用方零改动。
Known Limitations / Follow-up
- ORCA 模式与
--no-worktree轻量模式互斥(ORCA worktree 必须有 git 仓),命中轻量模式自动回落 tmux - ORCA app 未运行 /
orcaCLI 不在 PATH / 缺terminal.multiplex.v1capability → fail-loudexit 64(提示orca open或--no-orca-mode) --command必须是 agent CLI(claude/codex/opencode)ORCA 才自动识别为 agent session(references/12 §9 关键发现 1);用 shell 命令测试时 agent session 不显示,但 worktree 卡片 + workspace-status 仍正常- 端到端验证(2026-08-12)暴露并修复 4 个 jq 嵌套字段 bug:
worktree create/terminal create/terminal read/worktree show响应都嵌套在.result.<resource>(不是顶层)。共性模式记入 references/12 §9 关键发现 3 - 下一步探索:ORCA 有更高层的
orchestration worker-start/task-create/dispatch/gate-create/send体系(supervised worker + 任务 + decision gate + inter-agent 消息)。当前 skill 对接底层terminal create,后续评估切到orchestration worker-start层(references/12 §9 关键发现 4)
[1.20.5] - 2026-08-05
改进 — qoderclicn v1.0.45 + codebuddy v2.115.0 模型清单同步
CLI 升级后模型清单大变化,references/07 §4 + references/06 §0/§7.2/§5A + personal example + SKILL §2.4 全部同步实测(qoderclicn --list-models + codebuddy --help --model 权威输出)。
qoderclicn(1.0.24 → 1.0.45)
- 新旗舰
Qwen3.8-Max:qmodel_latestalias 仍解析 3.7-Max(没跟 3.8)→ 推荐用具体名-m Qwen3.8-Max - 新增
GLM-5.2/Kimi-K2.7-Code/MiniMax-M2.7(旧 aliasgm51model/kmodel映射过时) - 模型表从"alias key"改成"
--list-models实际名(推荐)+ 旧 alias(兼容过时)"双列 - 普通终端用:
~/.local/bin/qoderclicnsymlink(指向 .app bundle)+qoderclicn login,之后qoderclicn --list-models/-m Qwen3.8-Max
codebuddy(2.103.3 → 2.115.0)
--model权威列表:auto, hy3, glm-5.2, glm-5.1, glm-5v-turbo, minimax-m3, kimi-k3-1, kimi-k2.7, kimi-k2.6, deepseek-v4-flash, deepseek-v4-pro, custom-local:*(references/08 §4.1 主力已覆盖;新增kimi-k3-1/glm-5v-turbo/custom-local系列)- 用户偏好
hy3/deepseek-v4-flash仍在 ✓
personal example + SKILL §2.4
backend_model_routing.qoderwork-cn.default_models:["qmodel_latest",...]→["Qwen3.8-Max", "Qwen3.7-Max", "Qwen3.7-Plus", "DeepSeek-V4-Pro", "GLM-5.2", "Kimi-K2.7-Code"](具体名优先)- SKILL §2.4 qoderwork-cn 偏好同步 + "推荐具体名,旧 alias 过时"提示
Test
qoderclicn --list-models→ 10 模型(Qwen3.8-Max 新旗舰确认);qoderclicn --version→ 1.0.45codebuddy --version→ 2.115.0~/.local/bin/qoderclicnsymlink 普通终端 PATH 可达(which qoderclicn+--version确认)- 纯文档/配置同步,smoke 不涉及
[1.20.4] - 2026-08-05
改进 — CodeBuddy 拼写校正 + ref 08 结构精简
拼写校正(qodebuddy → CodeBuddy,腾讯产品名)
修正全 skill 共 59 处 qodebuddy(错误拼写)→ CodeBuddy(正确产品名,腾讯旗下)。文件系统客观路径不动(codebuddy CLI 二进制名、WorkBuddy.app app bundle、~/.codebuddy/ / ~/.workbuddy/ 配置目录、CODEBUDDY_* 环境变量)。
- references/08-codebuddy-cli-worker.md:40 处(全文 Python 批量替换)
- SKILL.md:7 处 + 4 处文件名引用
08-qodebuddy-cli-worker.md→08-codebuddy-cli-worker.md - references/06-agent-cli-reference.md:6 处(表格行、章节标题、注释)
- scripts/render-runtime-profile.sh:3 处注释
- scripts/spawn-worker.sh:1 处注释
- scripts/check-dependencies.sh:1 处提示信息
- config/orchestration-personal.example.json:1 处注释 + 文件名引用
ref 08 结构精简(945 → 858 行)
- 合并旧 §10(2026-07-05 五轮)+ 旧 §14(2026-07-08 三轮)→ 新 §10「spawn 实战坑点」:原两节讲同一批坑(权限/Enter/session 断流)的二次叙述,按"坑点类型"重组,两张速查表合一。新增 §10.6 session 断流、§10.7 原生
--worktree --tmux对比测方向、§10.8 合并速查表。删除旧 §10.7(§9 修订说明,合并后失效)和整个旧 §14。 - 删除旧 §6.6 / §6.7 历史实测段:snapshot-copy-into-worktree pattern 已固化为 SKILL.md §2.3 + DEC-037;render-runtime-profile 支持情况见
--help。保留 §6.6 精简指针段。 - 版本记录区压缩:8 条 2026-07-08 过程性微调("首次"~"第七次"逐条 smoke test 中间态)合并为 1 条关键节点。
- 交叉引用校准:L330 旧
§6.7引用改§5(MCP 关闭规则实际位置)。
待办清零 + qoderclicn trust dialog 修复(本次推进)
- ref 08 §3 主标题补齐 + L159 孤立 §2.6 消除(上面"待办事项"两条其实是同一问题):L159
### 2.6(孤立重复编号)→## 3. 命令行用法(§3 主标题,§3.1/§3.2 归属正确)。历史遗留待办清零。 - Task-031 trust_auto backend-specific 选项处理(
scripts/spawn-worker.sh):qoderclicn 2 选项 trust dialog(1=Trust folder / 2=Don't trust and exit,默认高亮 option 2 Don't trust)被旧 generic fallbackDown×3+Enter误选 option 2 = Don't trust → qoderclicn 立即 exit 42。修复:generic fallback 加WORKER_BACKENDcase,qoderwork-cn|qoderclicn发数字键"1"选 Trust folder(与permission_auto"2"同数字键模式,不依赖默认高亮);codebuddy(4 选项)等保留Down×3+Enter。 - qoderclicn 真机端到端验证(Task-031):spawn-worker 5 秒 exit +
SPAWN_WORKER_TRUST_AUTO: trust dialog detected (qoder 2-option), selecting option 1 Trust folder (key '1')+ qoderclicn 过 trust 进 REPL ready(pane:Thinking ▪ 准备好了,请告诉我需要做什么+Qwen3.7-Max Model · ctx 15%,无 "The current folder is not trusted. Exiting.")。qoderclicn backend 端到端可用 ✓。
Test
bash scripts/smoke-auto-bypass.sh→ 21/21 PASSbash scripts/smoke-sentinel.sh/smoke-tmux-worker.sh/lint-wait-script.sh→ 全 OKbash -n scripts/spawn-worker.sh scripts/render-runtime-profile.sh→ OK- qoderclicn 真机 throwaway(Task-031):5s spawn-worker exit + trust 处理 + REPL ready ✓
[1.20.3] - 2026-08-05
新增 — folia Wave-1 + W1/W2 dogfood 实战撞坑修复(Task-026 ~ Task-030)
本轮在 v1.20.2 setsid 修复基础上,针对 W1 (claude-code) + W2 (codebuddy) dogfood 撞坑沉淀的 G29 6 项实战问题(references/10-parallel-lessons.md)完成 5 项修复。Task-026 真机 throwaway 验证:codebuddy spawn-worker 主进程 22 秒 exit(v1.20.2 W2 撞坑 120s+ SIGTERM),节省 ~98 秒,< 60s 目标达成。
scripts/spawn-worker.sh(Task-026)
resolve_backend_defaults加codebuddy/qoderwork-cn/qoderclicn默认PERMISSION_AUTO=0(与claude-code同分支):acceptEdits 仍弹 dialog(references/08 §14.1),但同步监控空等浪费 + 撞 PM Bash 2min timeout(v1.20.2 W2 撞坑实测)。bg 段(permission_auto_bgsetsid)独立处理 dialog,不依赖 sync。trust_autobackend-specific max_wait:codebuddy/qoderwork-cn/qoderclicn默认 30→15s(acceptEdits 不弹 trust dialog,30s 空等浪费)。
scripts/render-runtime-profile.sh(Task-027)
resolve_settings_path函数:--settings/--provider-registry相对路径自动转绝对(fallback:render cwd →SCRIPT_DIR→SKILL_DIR/config/);绝对路径验证存在;URL 跳过。消除 W1 撞坑(config/*.json相对路径在 worktree cwd 找不到 + gitignore)。- 5 场景测试全过:相对路径 / basename / 绝对存在 / 绝对不存在(exit 64)/ 相对不存在(exit 64)。
scripts/dependency-install-guard.py(Task-028)
is_safe_lifecycle_command加date允许(拒绝-s/--set/--reference改系统时间):解决 W2 写STATUS.updated_at时date -u +"%Y-%m-%dT%H:%M:%SZ"被SHELL_COMMAND_NOT_ALLOWLED拦的撞坑。- 12/12 测试通过:W2 场景 allow + 安全(
-s/--set/--referencedeny)+ 回归(pwd/stat不变)。
templates/worker-prompt.md(Task-029 + Task-030)
- Bootstrap Isolation Gate 加 STATUS/RESULT path sanity 硬约束(Task-030):所有
STATUS.json/RESULT.md/PATCH_SUMMARY.md必须在$(pwd)/.claude/agent-sessions/<session-id>/下,写错位置 = done 信号无效。解决 W2 写skills/.../STATUS.json撞坑。 - Process step 8 加 Commit-Verify 硬约束(Task-029):commit 前必跑 Verify 全部 PASS;commit 后
git show --stat HEAD+git diff --stat HEAD~1..HEAD验证文件实际改了;LLM 幻觉 done = done 信号无效。引用 W264cd3d7撞坑(commit message 说改 4 文件但实际破坏 smoke + 错位置 STATUS)为实证。
Test — 多轮验证全绿
bash scripts/smoke-auto-bypass.sh→ 21/21 PASS(v1.18.3 + v1.18.4 + v1.20.2 + v1.20.3 + HRA-001 exit 64 断言)bash scripts/smoke-sentinel.sh→ SMOKE_SENTINEL_OKbash scripts/smoke-tmux-worker.sh→ SMOKE_TMUX_WORKER_OKbash scripts/lint-wait-script.sh→ LINT_WAIT_SCRIPT_OKdependency-install-guard.pyis_safe_lifecycle_command→ 12/12 PASS(Task-028)render-runtime-profile.shresolve_settings_path→ 5/5 PASS(Task-027)- 真机 throwaway codebuddy(Task-026):spawn-worker 主进程 22 秒 exit(< 60s 目标;v1.20.2 W2 撞坑 120s+ SIGTERM),
accept edits onready,session ALIVE
Known Limitations / Follow-up
- Task-026 qoderclicn throwaway 未真机验证:harness 自动拒绝 spawn qoderclicn 的二次执行(视为"launch-workbuddy daemon force-killed");codebuddy 验证通过 + 改动代码对
codebuddy/qoderwork-cn/qoderclicn三个 backend 一致 case pattern,逻辑上 qoderclicn 应有同等效果。下次派 worker 跑 qoderclicn 真机复测。 - TASKS.md(本地 gitignored):记录 v1.20.3 候选 DRAFT(
Task-026~Task-030)已全部完成,可清理或转历史。
Hotfix v1.20.3.1 — bg watcher 真机端到端修复(2026-08-05 当日)
严重 bug(v1.20.2 引入,v1.20.3 端到端真机验证发现):spawn-worker.sh 的 permission_auto_bg / external_imports_auto 后台 watcher 用 nohup / setsid(外部 binary)调用 spawn-worker.sh 的 bash 函数 —— 但 nohup / setsid 子进程找不到父 shell 函数定义,报 command not found,bg watcher 从未启动。v1.20.2 假设 setsid / nohup 能调用 bash 函数是错的(v1.18.3 旧版用 subshell ( ... & disown ) 模式继承函数能跑)。
- 修复:
scripts/spawn-worker.shPERMISSION_AUTO_BG + EXTERNAL_IMPORTS_AUTO 段改回 v1.18.3 subshell inherit function 模式(( func "$SESSION" & disown ) >/dev/null 2>&1 < /dev/null &)。已知限制:spawn-worker SIGTERM 时同进程组 bg 会死(v1.18.3 限制);mitigation = Task-026 让 spawn-worker 主进程 < 60s exit(v1.20.3 验证 19 秒),bg 有时间跑完(dialog 通常 30s 内弹)。 scripts/smoke-auto-bypass.sh的 v1.20.2 检查 #5(permission_auto_bg)/ #17(external_imports_auto)—— 原来匹配setsid / nohup字符串改为匹配 subshell inherit function 模式(v1.20.3.1 hotfix 实现形式)。
真机端到端验证(codebuddy + --permission-mode acceptEdits)
- spawn-worker 主进程 19 秒 exit(< 60s ✓)
- worker 跑
pwd命令:bg watcher 真启(PID detached subshell, PPID=1)+ 自动按2处理"Do you want to proceed?"dialog(session-allow)+ pwd 命令输出(端到端通过) bash scripts/smoke-auto-bypass.sh→ 21/21 PASS(hotfix + smoke check 更新)bash scripts/smoke-sentinel.sh/smoke-tmux-worker.sh/lint-wait-script.sh→ 全 OK
[1.20.2] - 2026-08-05
新增 — folia Wave-1 实战三修 + 本 skill 自身 dogfood 验证
本轮来自 folia Wave-1(2026-08-04/05,claude-code + codebuddy 5-worker)实战沉淀,覆盖 spawn / 监测 / prompt 投递 / 收口四个环节。Task-016/017 由本 skill 自身 dogfood(W1 worker 改 pm-sentinel-response.md)真机完成,验证 spawn-worker.sh 修复 + sentinel 事件驱动 + 超长 prompt 投递全链路。
spawn-worker.sh(Task-019/020/021)
- Task-019 — claude-code
--bare自动降级 prompt-only:render-runtime-profile.sh对 claude-code provider-isolation 默认加--bare(必需:skip keychain/OAuth/CLAUDE.md auto-discovery),但--bare触发 spawn-worker install-guard fail-closed(:520-528要 PM 手写--allow-prompt-only-install-guard)。新增claude_command_has_bare()检测:claude-code +--bare自动降级 prompt-only + 内置来源文本(CLAUDE_CODE_BARE_AUTO_DEGRADE=1,--no-claude-code-bare-auto-degradeopt-out),PM 不再手写降级。--safe-mode/--setting-sources排除 local / 缺 claude token 仍 fail-closed(非--bare不自动降级)。真机验证:dogfood W1 spawn 输出SPAWN_WORKER_BARE_AUTO_DEGRADE: claude-code --bare detected, install-guard auto prompt_only_degraded (source recorded),worker 正常启动(bannerglm-5.2[1M])。 - Task-020 —
external_imports_auto()监控 claude-code external imports dialog:CLAUDE.md@import触发 claude 首启弹 "Yes allow external imports" dialog(v1.18.4 默认关 trust/permission 不覆盖此类)。新增external_imports_auto()后台 watcher(120s,option 1 默认放行),claude-code 默认开(EXTERNAL_IMPORTS_AUTO=1,--no-external-imports-autoopt-out)。--bare模式下 CLAUDE.md 被 skip、dialog 通常不弹,watcher 作兜底无副作用。 - Task-021 —
permission_auto_bgsetsid + codebuddy Bash timeout 文档::1207( permission_auto_bg & disown ) &改setsid(macOS 无 setsid 时 fallbacknohup + disown),spawn-worker 被 SIGTERM 时 watcher 尽量存活。SKILL §6 补"codebuddy 同步监控逼近 PM Bash 2min timeout,建议 PM Bash timeout 调到 180s+"。
pm-sentinel-response.md(Task-016/017,W1 dogfood 完成)
- Task-016 — §2 显式归类 exit 137/143(SIGKILL/SIGTERM):exit code 表补 137/143 两行;新增 §2.5「Exit 137/143(signal kill)」分支(session 状态 × STATUS 终态组合诊断 + 137 OOM/harness 强杀/手动 kill + 143 温和);§4 降级段加指向 §2.5 的交叉引用。folia Wave-1 复盘:sentinel 被 signal 杀时 PM 缺明确分支。
- Task-017 — §1 step 2
tail -5改 grep 关键标记:长任务 sentinel 持续写SENTINEL_PENDING(5s/行)刷掉前面的 TERMINAL/TIMEOUT/UNKNOWN_STATUS。改grep -E "SENTINEL_(TERMINAL|TIMEOUT|UNKNOWN_STATUS|FAILED)" | tail -5+ 保留tail -5看上下文。
cron-monitor-prompt.md(Task-024)
- Task-024 — 自删改硬指令第 0 步:prompt 模板判定段加第 0 步硬指令(最高优先级):读所有 worker STATUS,全终态(done/failed/blocked/stopped)且无 pending PR/未合入 → 立即
CronDelete本 cron,不做巡检。folia Wave-1:3 worker 全 done 后 cron 仍触发一次兜底巡检,PM 手动 CronDelete。
SKILL.md 文档(Task-022/025)
- Task-022 — §5.2 超长 prompt 投递标准模式:Full Worker Prompt 填任务后超 2-4 KB + 特殊字符,直接
send-keys -l有转义/截断风险。标准模式:写{session_context}/WORKER_PROMPT.md+send-keys短读取指令("请 Read WORKER_PROMPT.md 并执行")。folia 3 worker + 本轮 W1 dogfood 均此模式,100% 投递成功。 - Task-025 — §3 第 11 步 webview 项目分流:Tauri/Electron/WKWebView 的 webview 不暴露 macOS a11y,orca/computer-use 读不了(
role:null)也写不了(click 不触发 React 事件)。web 交互必须走 Playwright e2e,orca 仅原生控件 + screencapture。folia(Tauri)#92 验证:orca 4 次 click 截图字节零变化。修正 TASKS 里 stale 的 §3.11 引用(实际是 §3 第 11 步)。
改进 — smoke HRA-001 修复(skill-lint 验收触发)
skill-lint harness_failure_audit 基线报 3 处 hard finding(HRA-001:测试 || true 丢被测命令退出码)。本轮全部修复:
smoke-sentinel.sh:167/170:usage 路径|| true改显式断言 exit 64(no-arg + --bogus 都 exit 64)+assert_contains。smoke-auto-bypass.sh:87/143:spawn-worker 无参|| true改显式保存 exit code + 断言 exit 64(#6 加新 check);smoke 总数 13 → 21(v1.18.4 + v1.20.2 段 + exit 64 断言)。smoke-provider-settings.sh:86:provider 调用|| true改保存 exit code,区分 ERROR(provider exit≠0 + 无 token)vs FAIL(exit 0 + 无 token),PASS 若 exit≠0 附诊断。⚠️ 本项未真机验证(provider 调用非确定,依赖网络/token),逻辑保留 capture-response-诊断语义。
入库 — G25-G28 FaroPDF Wave 1+2 实战沉淀(references/10-parallel-lessons.md)
G25-G28(2026-08-04 FaroPDF 5-worker:codebuddy W1 + claude-code W2-W5)此前已写进 10-parallel-lessons.md 工作区但未入 CHANGELOG,本轮正式入库:
- G25:spawn-worker backend token 检查(
--commandbasename 必须含 backend;bash launch.sh wrapper 会触发 fail-closed,改用 backend 二进制直起 +/tmp/empty-mcp.json文件避 tmux 引号吞)。 - G26:claude-code worker 派 subagent 不可用(glm 第三方 provider API 1211/500)→ 主进程 Grep 替代 + prompt 显式禁 subagent。
- G27:漏 commit 也犯 claude-code(不只 codebuddy)—— 收口必查
git log main..HEAD非空。 - G28:verify 用主仓 node_modules(worktree 向上解析,免 npm ci)+ 提效/降 token 汇总表。
Test — dogfood 链路全验证(本 skill 自身做 PM)
- Task-016/017 由 W1 worker(claude-code/glm-5.2[1M])在 worktree 完成:spawn(render + settings 绝对路径 +
--bare自动降级)→ 投递(§5.2 WORKER_PROMPT.md + 短指令)→ worker 自主执行(Isolation Gate + STATUS + 改文件 + Verify + commit755ffe3+ done)→ sentinel exit 0 唤醒 PM → 收口 apply。 bash scripts/smoke-auto-bypass.sh→ 21/21 PASS(v1.18.3 + v1.18.4 + v1.20.2 段 + HRA-001 exit 64 断言)。bash scripts/smoke-sentinel.sh→ SMOKE_SENTINEL_OK(含 HRA-001 exit 64 断言)。bash scripts/smoke-tmux-worker.sh→ SMOKE_TMUX_WORKER_OK。bash scripts/lint-wait-script.sh→ LINT_WAIT_SCRIPT_OK。
关联
- 来源:folia Wave-1(2026-08-04/05,5-worker / 2-backend)+ FaroPDF Wave 1+2(2026-08-04)实战沉淀。
- 关联章节:§2.1 防逃逸门禁、§3.8 spawn 后核验、§3 第 11 步 webview 分流、§5.2 超长 prompt 投递、§6 启动方式(setsid / Bash timeout)、§7.2/§7.3 sentinel + cron。
- 已知 follow-up:Task-019/020/021 的 codebuddy 端真机验证(本轮验证 claude-code 端;codebuddy 同步监控提速 + setsid 在 codebuddy spawn 的效果待 codebuddy Wave 验证)。
[1.20.1] - 2026-08-01
新增 — 非 CLI 主会话不宜扮演 PM 的适用边界
references/10-parallel-lessons.mdG24(新):记录 2026-08-01 FaroPDF 仓审计 Wave 实战教训。在 ZCode 这类非 CLI 的 harness 内嵌 agent会话里扮演 PM、调spawn-worker.sh+ tmux + sentinel 派只读审计 worker,编排层勉强跑通但三个 worker 全部SENTINEL_TIMEOUT+TMUX_KILLED、零产出。根因是 CLI 范式错配(非配置问题):skill 的 worker 启动(claude-provider-env.shwrapper)、权限路由(--permission-mode)、进程生命周期都依赖 CLI 能力,非 CLI agent 够不着这些层。三个具体卡点:① provider env 污染(tmux session 继承混合 env → 模型不存在,必须走 wrapper)② permission dialog 杀死只读 worker(acceptEdits不自动批准 Shell,审计跑grep/find逐条弹 dialog → 卡死 → 超时)③ 监测盲区(只挂 sentinel 不做定时 pane 巡检 → silent 卡死无人发现)。结论:多 worktree worker 编排应在 Claude Code CLI 会话做 PM;ZCode 类 harness 要并行改用自带 subagent/Agent 工具。- SKILL.md §1 边界:「不使用本 Skill」新增「PM 是非 CLI 的 harness 内嵌 agent(ZCode 等)」一条,指向 G24。
关联
- 来源:FaroPDF 仓审计 Wave 实战(3 个只读 worker:任务源 / 技术债 / 架构,GLM
glm-5.2[1M]provider)。链路逐段验证通过(worktree 隔离 / wrapper 统一 provider / scope-guard / worker 收 prompt 建清单),但卡在 permission dialog 层全军覆没。本条不否定 skill 在 CLI 环境的价值,只划清适用边界:PM 必须是能被 spawn、能配 permission、能跑 settings 路由的 CLI 会话。 - 关联章节:§2.1 防逃逸门禁、§3.8.1 spawn 后核验、§6 启动方式(wrapper)、§7 巡检与介入。
- 附带发现(不入 skill,记 FaroPDF 仓内处理):
.claude/-settings.json文件名带横杠且缺ANTHROPIC_MODEL字段为坏配置;GLM token 在诊断过程中二次泄露到会话日志(需 rotate)。
[1.20.0] - 2026-07-31
新增 — Issue 分组与合并 PR 判断
references/12-issue-grouping.md(新):补齐 SKILL.md §3「先分组」缺失的两个维度。原「先分组」只覆盖依赖链,本文给出三维度骨架:① 同根因合并(多 Issue → 一个 worker → 一个 PR)、② 依赖链顺序、③ 独立并行。每维度给触发信号 / 前置条件,配套软阈值(同根因合并建议合并后 diff < ~300 行、组内 ≤ 3 个)、决策树、反模式清单(默认一对一 / 硬塞不同类型 / 为凑数合并 / 大改动打包 / 跨模块强合等)。- 任务源:本地 task 卡 vs 云端 GitHub Issue:明确区分两类任务源的分组前预处理。本地结构化任务文件字段齐全、依赖显式;云端 Issue 他人提交、自由文本、依赖需从 body 推断,必须先
gh issue list/view读 body + labels + 最近 commits 做相关性分析,并配套分组 SOP 命令。覆盖原 Skill 任务源模型偏本地、未处理云端 Issue 的缺口。 templates/issue-batch-pr.md(新):维度①「同根因合并」时的多 Issue PR 描述模板。核心是「统一根因」段(让 reviewer 一眼看清为什么这几个 Issue 要一起改)+ 逐 Issue 修复点 +Closes #xx, #yy批量关闭 + 逐个 Issue 手动验证勾选。含与单 Issue PR 的区别速查、使用纪律(每个 Issue 必须单独验证、写不出统一根因说明可能不该合并)。
改进
- SKILL.md §3 标准流程:把第 2 步「先分组」从一句话扩成三维度判断(指向
references/11);新增第 1.5 步「识别任务源形态」,要求区分本地 task 卡和云端 Issue 并做不同预处理。强调拿不准时默认分开。 - SKILL.md §10 参考:references 列表加
12-issue-grouping.md,templates 列表加issue-batch-pr.md。 - frontmatter:version 1.19.0 → 1.20.0。
关联
- 来源:Folia 项目 issue 分组审查实测。发现 Skill 原「先分组」逻辑只处理依赖链,既没覆盖「多 Issue → 一个 PR」的打包合并场景,任务源模型也偏本地结构化任务,未处理云端他人提的 GitHub Issue。
- 范例:Folia
#75(标题输入英文生成多余****)+#76(标题行删除/方向键时光标漂移)判定为维度①同根因合并(均发生在标题行 WYSIWYG、涉及 heading 节点 IR/Selection、改动位置重叠、均为小修),#78(内置 Word 模板导出非预期颜色)单独处理(纯导出模块、与编辑器那组正交)。
[1.19.0] - 2026-07-13
新增 — 验证不授权安装依赖的可执行边界
- 新增
dependency-install-guard.py+ hook wrapper:PreToolUse 对直接 Shell 工具调用默认 fail-closed,窄生命周期命令或 spawn 的精确 allowlist 才放行;系统/语言包管理器、全局链接、项目本地安装与npx/npm exec/pnpm dlx等按需获取命令还须精确安装授权及来源。授权快照缺失/损坏、hook 输入异常均 fail-closed。 spawn-worker.sh新增安装与 Shell 精确授权参数;权威快照及 SHA-256 receipt 落到 Git common-dir,worktree 内 JSON 明确只是 mirror。hook 读 spawn 进程快照,并阻断文件工具改写 receipt/settings/mirror。settings 合并只移除旧 guard command,不丢同 entry 的其他 audit hooks。- 新增 Git identity 参数,把 author/committer 四个一次性环境变量绑定 worker 进程(不写共享 config),生成并精确放行
git-workflow/safe-push.sh;raw push 被 Shell gate 阻断,safe-push 把完整 PR range 身份证据绑定实际推送 OID。 - 未接入 PreToolUse 的 Codex / OpenCode / custom backend 默认拒绝 spawn;只有
--allow-prompt-only-install-guard '<来源>'显式接受降级并留痕时才放行。 - Claude Code
--bare/--safe-mode/CLAUDE_CODE_SIMPLE=1、排除 local settings 或不可证明的 wrapper 命令默认 fail-closed;CodeBuddy/Qoder backend 也须暴露对应 executable token。初始 METADATA 只记settings_wired...runtime_unproven,首次 hook 调用另写 PM-side attestation;显式降级写prompt_only_no_mechanical_enforcement,不虚报 hook 执行。 - 新增 49 项故障注入,覆盖命令绕行、按需获取工具、危险 Git/rg/awk 参数、授权快照防篡改、settings 多 hook 保留、PM receipt/runtime attestation、backend executable proof、显式降级、install-like verify 拒绝、worker 进程 Git identity 与 safe-push spawn 集成。
改进
- worker prompt、STATUS、RESULT 增加 allowed Shell、PM receipt、enforcement source 与 identity-bound safe-push 证据字段;缺依赖时先找已有二进制,仍缺则
status=blocked并记录 skipped verification,不得把验证要求解释成安装权限。 - 依赖参考文档与 PATH-less 检查移除自动安装/全局 symlink 暗示;安装命令只作为用户明确批准后的参考。
check-dependencies.sh增加python3只读检查并明确只报告、不授权安装。
关联
- 通用化来源:法律 AI 书项目 T159 / DEC-131。本仓只沉淀可执行机制,不复制项目决策正文;
multi-agent-orchestration的 ignored 本地 TASKS/DECISIONS 继续不入库。
[1.18.4] - 2026-07-11
Changed — spawn 启动期提速 + spawn 后异步纪律(2026-07-10 多 worker Wave 实战三连修)
scripts/spawn-worker.sh同步 dialog 监控默认值按 backend 分支化(T1):claude-code backend 实测--permission-mode auto --bare不弹 dialog,默认--no-trust-auto --no-permission-auto --no-permission-auto-bg(省 trust_auto 30s + permission_auto 60s = 90s 空等);其他 backend(codebuddy / qoderwork-cn / codex / opencode)默认全开。新增resolve_backend_defaults()函数 + 3 个*_OVERRIDE标志 + 主流程 PERMISSION_AUTO_BG 独立 gate(与 sync 解耦)。- 6 个
--*/--no-*flag 精细控制:--trust-auto/--permission-auto/--permission-auto-bg(显式 opt-in,升级后 dialog 行为变化兜底);--no-trust-auto/--no-permission-auto(v1.18.3 兼容,分别同时关 trust+permission / sync+bg);--no-permission-auto-bg(只关 bg watcher)。--no-permission-auto保留 v1.18.3 "both off" 语义。 SKILL.md新增 §3.8(T2+T3):§3.8.1spawn 后 30 秒内必跑的 4 条核验命令(tmux has-session / capture-pane / METADATA.json / STATUS.json with timeout 120);§3.8.2并行 spawn 投递纪律(一开始就并行 spawn,不先串行验证流程);§3.8.3反模式清单(TaskOutput block=true / tmux attach / while sleep 不带 timeout 等);§3.8.4v1.18.4 backend 分支化同步 dialog 监控默认值说明。注:原计划 §3.7 已被 commit a33f057 用作"派发 SOP 必带 skill 路径清单"(当前以## Project Skills形式存在),故 renumber 到 §3.8。SKILL.md §6行 593 后补 4 条核验 snippet:spawn 后立即跑 4 条命令 + 反向引用 §3.8.1。SKILL.md §3.5末尾加 v1.18.4 注:claude-code backend 默认全关反向引用 §3.8.4。SKILL.mdfrontmatter:version 1.18.2 → 1.18.4(v1.18.3 由 commit 4d168a1 部分入仓但 frontmatter 未更新)。- 新增
templates/pm-spawn-postflight.md:4 条核验命令扩展版 cheatsheet(何时用 / 反例 / 多 worker 并行 spawn 提示)。 references/10-parallel-lessons.md加 G23:spawn 阶段并行投递纪律与已有 G22(wave 内任务颗粒度)形成两层闭环。
受影响的 PM 行为
- 单次 claude-code backend spawn 主进程退出时间从 v1.18.3 实测 2-4 min 降到 v1.18.4 秒级返回。
- PM 派活后禁止用
TaskOutput block=true等spawn-worker.sh退出,必须跑 §3.8.1 的 4 条核验命令。 - 多 worker Wave 一开始就并行 spawn(每个 worker 走
bg spawn-worker.sh+bg sentinel.sh各一次 fg Bash 调用),不先串行验证流程再补并行。
Test
bash scripts/smoke-auto-bypass.sh→ 13/13 PASS(v1.18.3 7 项 + v1.18.4 6 项)。
Background
- 来源:2026-07-10 某客户委托项目多 worker Wave 实战(3 个不同 skill backend 的 worker,全 claude-code backend),PM 派发阶段(spawn 3 worker + 投 prompt)实测耗 20+ min,用户反馈「着实影响并行推进任务」。TASKS.md L116-118 登记三条 follow-up,合并 v1.18.4。详见 DEC-112(gitignore 本地)。
[1.18.3] - 2026-07-08
Changed — spawn-worker.sh auto-bypass permission dialog(踩坑 7 真正修复)
v1.18.2 文档化了 "acceptEdits -y 仍弹 dialog" 但未改默认行为,PM 仍需 spawn 后 tmux attach 手按 2。v1.18.3 真正自动化:
permission_auto()关键修复:旧版用tmux send-keys -t "$session" Down Enter(按箭头 + Enter 选 option 2),PM 2026-07-08 wave-1 实测在某些 TUI 状态不稳。v1.18.3 改用tmux send-keys -t "$session" "2"(直接发数字键),稳定 work。permission_auto_bg()新加:后台 watcher 通过( permission_auto_bg "$SESSION" & disown ) &启 disown,spawn-worker.sh 退出不影响 watcher。watcher 默认 7200s(与 sentinel --max-wait 对齐),覆盖同步 60s 窗口外的 dialog(worker 启动后 60-7200s 期间任何 tool 调用都自动按 2)。可用 env varSPAWN_PERMISSION_BG_MAX_WAIT/SPAWN_PERMISSION_BG_POLL(默认 5s)调整。- 新 flag
--no-permission-auto(v1.18.3 精细 opt-out):只关 permission_auto + permission_auto_bg(不影响 trust_auto)。与--no-trust-auto(同时关 trust + permission)区分,给精细控制。 - 新 smoke
scripts/smoke-auto-bypass.sh:v1.18.3 新增验证脚本,跑 7 项 check(permission_auto 函数定义、数字键2、permission_auto_bg 函数、--no-permission-auto flag 解析、调用点 disown、usage 输出、头部 v1.18.3 标记)。 - SKILL.md:
- §3.5 改写为"spawn 后 auto-bypass(v1.18.3)—— PM 不需要手按 dialog"。
- 新增 §3.5.1"auto-bypass 实现细节":v1.18.3 修复点、permission_auto_bg 行为、opt-out flag、smoke 验证。
- scripts/spawn-worker.sh 头部注释:trust + permission dialog 兜底章节改写,明确 v1.18.3 auto-bypass 三层保护(trust_auto / permission_auto / permission_auto_bg),PM 默认不需要 attach tmux 盯。
受影响的 spawn-worker.sh 行为
- 默认情况下,PM 派活后不需要任何手按(trust_auto + permission_auto + permission_auto_bg 三层自动)。仅当 worker 在 1-2 分钟还没写 STATUS.json 时,再
tmux attach手动 inspect(说明 dialog 真卡住)。 - 仍用
--no-trust-autoopt-out 同时关 trust + permission(向后兼容)。 - 新增
--no-permission-auto精细 opt-out(v1.18.3)。
Test
bash scripts/smoke-auto-bypass.sh→ 7/7 PASS(v1.18.3 验证)。
Background
- v1.18.3 由 PM 主动接管,原因是 wave-3 派 worker G 时撞 WorkBuddy 平台
sg.tgalileo.com端点临时 hang(axios 旧 connection 不释放),worker 反复死锁失败。PM 按 §2.1 防逃逸门禁例外"修复 PM 自己生成的 orchestration 文档/配置"直接改 spawn-worker.sh(worker 任务范围明确 + 范围小)。worker G 在 workbuddy 平台恢复后再跑相同任务应能复现。
[1.18.2] - 2026-07-08
Added
- CodeBuddy tmux spawn 实测改进(
references/08-workbuddy-cli-worker.md§14):基于三轮不同形态的 spawn 任务(多步文本编辑 / SVG 生成 / CLI 研究调研)补强 §10(2026-07-05 五轮实测)。三个具体卡点 + 顺跑配置:- 权限机制坑(§14.1):
acceptEdits -y组合下,acceptEdits 只 accept edits,读 worktree 外路径 / 特殊路径(tmux socket、跨 worktree 符号链接)仍弹权限对话框;-y(--dangerously-skip-permissions)被 acceptEdits 覆盖、没真正跳过读权限;--add-dir <项目根>只预授权文件目录、不覆盖工具调用层。后果:多步任务(Read 多文件 + Bash 多次)权限循环卡死,单步少路径任务勉强过。顺跑:多步任务一律--permission-mode bypassPermissions(§10.1 launch.sh),acceptEdits只适合单步 / 少路径。 - Enter 提交坑(§14.2):
tmux send-keys -t <session> "prompt" Enter的Enter没提交 prompt(pane 显示 prompt 完整在>输入框但没执行)——codebuddy TUI 稳定行为,与 glm worker 同坑。顺跑投递配方:send-keys -l投文本 + 单独send-keys Enter(或C-m更稳)+ sleep 12-15s + 兜底补一发 Enter。 - session 断流坑(§14.3):权限确认对话框(选 don't-ask / session-allow)后,prompt 流程被打断,codebuddy 回
>空等、不自动续原 prompt。顺跑:重发 prompt(§14.2 配方)或codebuddy -cresume;最佳策略=bypassPermissions 从根上绕开权限框。 - 原生替代方向(§14.4):CodeBuddy 原生支持
--worktree --tmux(§7.3),可替代 spawn-worker.sh + launch.sh 手工组合;记为 long-term 优化方向,待对比测(权限框透传 / pm-monitor 识别 / worktree 收口三项未测),未测前不替换 spawn-worker.sh 路径。 - SKILL.md frontmatter version 1.18.1→1.18.2。
- 权限机制坑(§14.1):
- 原则跨项目通用(不绑定具体项目 / 章节 / AGENTS / DEC),案例匿名化。
[1.18.1] - 2026-07-08
Added
- G22 多维度任务的颗粒度纪律(
references/10-parallel-lessons.md):单 worker 改多章 × 多维度时注意力被高优维度(Critical / Important)占满、末位维度(如"标题删重")静默漏掉。沉淀三条通用改进:①多维度任务 prompt 用 checklist 强制逐维度(每维度独立 commit / 勾选,worker 必须覆盖完所有维度才算完成);②大批量改后必派 wave2 复查 worker(只读 review)抓漏;③精细深查(箭头落点 / 字体逐核 / 像素对齐)拆单维度 worker处理深度。主因非模型能力,是任务粒度 + prompt 结构。原则跨项目通用,不绑定具体项目或章节。 - SKILL.md §3.1 Wave 模式段加一段交叉引用,指向 G22;frontmatter version 1.18.0→1.18.1。
[1.18.0] - 2026-07-07
BREAKING — 删除全部 headless / batch 模式(DEC-044)
render-runtime-profile.sh移除--mode/--prompt-file:删除参数、校验、append_redirection/shell_wrap辅助函数。5 个 backend(claude-code / codex / opencode / codebuddy / qoderwork-cn)只保留 interactive 分支,输出删WORKER_MODE。传--mode/--prompt-file现在显式报错并指向 DEC-044 + 迁移指引(短任务用同宿主 Subagent)。- 理由(用户原话):「我们使用 TMUX 就是要去进行交互式的 worker 监控。如果是
-p模式的话,它更适合那种短程的任务,那种任务其实使用 subagent 也能完成,所以我们要删掉这个模式,避免 agent 错误调用这样一种模式」。headless 一发跑完 = 放弃 tmux 监控可纠偏;而它适合的短任务本就该走 Subagent。分工由此清晰:短任务 → Subagent;需编排/监控 → tmux 交互 worker。 - SKILL.md:§2 执行模式表 + §6 启动方式删除 Claude Code 批处理 bullet、
< redirect 必须 bash -lc、claude -p autocompact thrash两条警示,换成「所有 worker 一律交互式」说明;Codex/OpenCode bullet 改为交互式命令。§2 表加「同宿主 Subagent」替代 headless 的说明。 - references/06/07/08:顶部加「batch 已于 v1.18.0 移除(DEC-044)」横幅,正文 batch 段保留作历史参考。
- supersede:DEC-033(batch 部分)、DEC-040(batch flag 修正)、DEC-042(「保留 batch 兜底」结论)的 batch 相关部分;交互式默认值与 DEC-042 长任务交互 canonical pattern 保留并扩展到短任务。
- 不变:
smoke-provider-settings.sh仍用claude -p做一次性 provider 验证(测试工具非派 worker,故意保留)。
Added — 轻量模式 --no-worktree(DEC-045)
spawn-worker.sh --no-worktree:非默认的轻量隔离模式。worker tmux session cwd 直接指向目标文件夹,不建 git worktree / branch / base ref。两种触发:(a) 用户显式--no-worktree;(b)--project检测为非 git work tree 时自动切换(打印SPAWN_WORKER_LIGHTWEIGHT_AUTO,非静默降级)。METADATA.json加isolation_mode字段("worktree"|"lightweight");轻量模式branch / base_ref / base_sha留空。- Isolation Gate 分支化:worktree 模式验 cwd + branch;轻量模式只验 cwd(非 git 不验 branch)。info/exclude 写入加 git 存在性 guard(非 git 跳过)。
- worker-prompt.md:Context 加
{{isolation_mode}};Isolation Gate / Commit Cadence / Git-PR 段加轻量分支(非 git 文件夹跳过 commit/PR,交付物直接落盘 + RESULT.md 清单)。 - 适用场景:一个 PM session 派多个 worker 各管一个独立文件夹、目标不是 git 仓、或不需要 git 级隔离。隔离 = 文件夹分离(硬约束:worker 必须占互不重叠的文件夹;越界靠
--allow-pathsscope-guard 兜底)。SKILL.md 新增 §2.1.1 + §6 轻量 spawn 示例 + §11 轻量 smoke benchmark。
Changed
- 版本号 frontmatter:SKILL.md
version从1.17.6修正为1.18.0(此前 1.17.7/1.17.8 patch 未同步 frontmatter,一并修正)。
[1.17.8] - 2026-07-06
Fixed
- 第三方 provider worker 串到 Fable 5 / OAuth 的 env 路由 bug(DEC-043):
render-runtime-profile.sh在 provider-isolation 路径(wrapper)的claude_parts追加--bare。--bare(minimal mode)禁 keychain reads / OAuth / plugin sync / CLAUDE.md auto-discovery,使 Anthropic auth 严格走 wrapper 设的ANTHROPIC_API_KEY(来自 provider registry/settings),不再读 keychain 残留 sk-ant。修前:deepseek/glm worker 启动弹"是否使用此 API key"(sk-ant),选 No 后串 Fable 5 而非目标 provider;MCP 信任框也每次弹。修后实测:claude 直显"deepseek-v4-pro · API Usage Billing",无 keychain/MCP 框。inherit-style worker(不走 wrapper)不受影响。
[1.17.7] - 2026-07-05
Added
config/orchestration-personal.json个人偏好初始化:基于config/orchestration-personal.example.json模板创建本地个人配置。host=claude-code,main_force.task_routing走 deepseek-v4-pro(高端)/ deepseek-v4-flash(简单+多模态);codex_policy.policy=explicit_only+strict_mode=true(CodeX 默认锁死,仅用户原话命中trigger_phrases才解封);backend_model_routing.codebuddy.default_models = ["deepseek-v4-pro", "deepseek-v4-flash"](workbuddy/codebuddy CLI 只启用这两个模型档位,不引入 kimi/minimax/sonnet/opus 等其它模型);backend_model_routing.qoderwork-cn.default_models = ["deepseek-v4-pro", "deepseek-v4-flash", "qmodel_latest", "qmodel"](QoderWork CN 启用 Deepseek 两档 + Qwen3.7-Max / Qwen3.7-Plus),其中 Qwen 两个档位通过discount_window(22:00-08:00 Asia/Shanghai,含跨午夜)标注为「二折优惠时段优先」。文件受.gitignore的**/config/*.json规则保护,不入库。
Changed
- codebuddy backend 模型白名单收敛:个人偏好中
backend_model_routing.codebuddy.default_models仅保留deepseek-v4-pro和deepseek-v4-flash。kimi-k2.6/kimi-k2.7/minimax-m3/sonnet/opus/auto等档位不启用——后续如需扩展,再追加到default_models数组。 - qoderwork-cn backend 模型白名单收敛:个人偏好中
backend_model_routing.qoderwork-cn.default_models收敛为["deepseek-v4-pro", "deepseek-v4-flash", "qmodel_latest", "qmodel"],与 codebuddy 共享 Deepseek 两档;Qwen3.7-Max(qmodel_latest)和 Qwen3.7-Plus(qmodel)在discount_window(22:00-08:00)享受二折优惠,PM 派 qoderwork-cn worker 时若当前时间落在折扣窗口,应优先路由到qmodel_latest/qmodel;窗口外则回落 Deepseek 两档。 - 新增
discount_window字段:在backend_model_routing.qoderwork-cn下声明折扣时段start=22:00 / end=08:00 / timezone=Asia/Shanghai / cross_midnight=true,并列出models_in_window(Qwen 两档)与models_outside_window(Deepseek 两档),rate_note="二折(约 20% 原价)"。当前render-runtime-profile.sh尚未解析该字段,PM 需手动判断时段后再选 model。 - CodeX 路由硬规则收紧:在 SKILL.md §2.4
codex_policy.policy = "explicit_only"基础上,新增strict_mode=true+trigger_phrases+fallback_when_blocked+pm_must_log_on_unlock字段。PM 必须看到用户原话命中trigger_phrases(如「用 Codex / 调用 Codex / 跑 Codex / use codex / run codex / spawn codex」等)才解封;任何弱暗示(「更适合 Codex / Codex 额度还行 / 试试 Codex」)不算解封。CodeX 被 block 时回落 DeepSeek 两档,不替换为其它高额度模型。解封时必须在 Wave 计划 +STATUS.json.pm_notes记录用户原话、wave_id、worker_id 与 codex profile/model,便于审计。
Reason
- 来源:用户明确「Workbody 这个 Agent 的 CLI 只选用 Deepseek V4 Pro 和 Deepseek V4 Flash 两个模型」,并补充「qoderwork-cn 也只调用 Deepseek V4 Pro / Deepseek V4 Flash / Qwen3.7-Max / Qwen3.7-Plus,其中后两个更推荐在晚上 10 点到早上 8 点之间调用,因为会打二折」,「除非我明确要求,尽量不要调用 CodeX」。落地为个人偏好
backend_model_routing.codebuddy+backend_model_routing.qoderwork-cn+codex_policy,并通过discount_window把折扣时段、trigger_phrases把 CodeX 解封条件显式标注,让 PM 派 worker 时能直接看到「此时段是否用 Qwen 两档最划算」与「CodeX 默认锁死、必须看到原话才解封」。
[1.17.6] - 2026-07-05
Added
--add-dir透传(codebuddy 跨目录访问):render-runtime-profile.sh新增--add-dir <dir>参数(可重复),codebuddy backend 追加到cb_parts。spawn-worker.sh同步新增--add-dir <dir>参数,写入METADATA.json的add_dirs字段。用途:PM 派 worker 时若任务文件/素材在 worktree 外,spawn-worker.sh --add-dir /tmp --add-dir ../shared-assets。permission_auto()兜底 runtime "Do you want to proceed" prompt:spawn-worker.sh新增permission_auto()函数,启动 tmux 后轮询 pane 内容(最长 60s,2s 间隔),匹配「Do you want to proceed」文本后自动选 option 2「Yes, and don't ask again for session」(Down+Enter=session-allow)。与trust_auto共用--no-trust-autoopt-out。只自动选 session-allow,不选 bypass(安全:session-allow 仍记录,且只对当前 session)。
Fixed
- runtime "Do you want to proceed" prompt 无自动处理:上一轮(v1.17.5)的
trust_auto只处理了首启 trust folder dialog,但 codebuddy 读取 worktree 外文件时的「跨目录安全门」是另一层 prompt。PM 派 headless worker 时若任务文件在 worktree 外(如/tmp),worker 会卡在 "Do you want to proceed?" 弹窗。新增permission_auto()兜底此场景。
Reason
- 来源:2026-07-05 PM 用 codebuddy worker 实战,即使带了
-y,读取/tmp任务文件时仍弹 "Do you want to proceed" 弹窗。-y/--dangerously-skip-permissions跳工具权限,但不覆盖 codebuddy 的「跨目录访问」安全门。官方文档的解是--add-dir(settings 或 CLI flag),而 permission_auto 作为兜底自动选 session-allow。
[1.17.5] - 2026-07-05
Fixed
- codebuddy/qoder 交互式 worker 缺 -y / --dangerously-skip-permissions(问题 2 运行时部分):
render-runtime-profile.sh的 codebuddy case-y逻辑从「batch 恒加 / 交互式仅显式 --dangerously-skip-permissions」改为「交互式也默认加,仅 --no-skip-permissions opt-out」。qoderwork-cn case 同改为默认加 --dangerously-skip-permissions。理由:spawn-worker.sh 派 tmux session 本质 headless(无人在终端应答 runtime permission prompt),DEC-040 F1/F3 只修了 batch 模式,交互式 gap 还在。 - codebuddy 首启 trust folder dialog 无自动处理(问题 1):
spawn-worker.sh新增 trust-auto:启动 tmux 后轮询 pane 内容,匹配 codebuddy trust dialog 文本(Trust folder / Trust folder and all subdirectories),自动选 option 3(Down×3+Enter),避免子目录二次 prompt。提供--no-trust-autoopt-out。 - codebuddy PATH 检测假阴性(问题 3 补充):
check-dependencies.sh新增--print-bundle-path codebuddy|qoderwork-cn,直接输出 .app bundle 二进制绝对路径。spawn-worker.sh --help加 Troubleshooting 段,提示用 check-dependencies 多源检测或取绝对路径传给 --command/--bin。
Reason
- 来源:2026-07-05 PM 用
spawn-worker.sh --backend codebuddy派 worker,连续撞 3 个手动 prompt:首启 trust folder dialog → 子目录访问 dialog → which codebuddy 找不到。CHANGELOG v1.16.6/1.17.1/1.17.2 历史上修过 batch 模式 flag 和 PATH-less 检测,但交互式 headless worker 的自动 -y + trust-auto 两个 gap 一直没补。
[1.17.4] - 2026-07-03
Added
scripts/qoderclicn-interactive-spawn.sh:长任务(10+ tool call)专用 helper。qoderclicn在 batch-p模式下走 SDK/bare 模式 → GUI 主进程 (pid 65090) 的 HeadlessSession → 1-2s 内gemini.exitHeadlessMode主动 idle-exit(实测日志~/.qoderworkcn/logs/runs/...-p65090/process.exiting ... uptime_ms=1176)。DEC-042 决策:长任务改走 interactive 模式 + tmuxsend-keys投递 prompt(无-p),实测 5 个 tool call(pwd/date/echo/uname/ls)全跑通 + worker 仍在>ready。Helper 自带:- argv-form tmux
new-session触发(路径空格不丢) - trust-folder 自动
1 + Enter接受(可关:--no-trust-auto) - TUI ready 检测(看
Type your message或>) - prompt 12KB/16KB 分段(
send-keys/paste-buffer) - thinking/tool_use 出现确认(60s)
- argv-form tmux
references/07 §8 新增「长任务专用 helper」指引:PM 用法 + helper 适用场景 + 与 batch
-p对照。
Reason
- 来源:2026-07-03 doc-curator-iter Wave 1 W2 中途死的根因诊断。investigator 14 行 A/B 测试定位 F1+F3 (DEC-040) 解决了 batch flag + model key,但 worker 仍 1-2s exit 不进 agent loop;进一步排查确认是 SDK/bare 模式的 HeadlessSession 设计问题,不是 flag 错。Reference §6.2 已写明 batch 仅限短任务,但 PM 派 W2 时 10+ tool call 仍走 batch 故踩坑。
- 决策:保留 batch
-p作为「短任务兜底」(≤3 tool call),新增 interactive helper 作「长任务 canonical」。spawn-worker.sh后续加--mode interactive集成(本次仅 helper + 文档)。
[1.17.3] - 2026-07-03
Security
- 凭证卫生审查(skill-lint 验收触发):
config/*.settings.json(deepseek / glm / minimax)含真实 API key,虽已被.gitignore的**/config/*.json拦住不进 git 追踪(Hard Fail #5 未触发),但真实 live key 明文躺在工作区仍是外带风险。这三把 key 需在各 provider 后台轮换(DeepSeek / BigModel-GLM / MiniMax),并确认打包与 ClawHub 同步都尊重**/config/*.json排除。长期方案:真实 token 只放环境变量,settings 文件留占位。
Fixed
.gitignore补**/.claude/agent-sessions/:SKILL.md §4.1 要求 agent-sessions 巡检产物不进 commit,但仓库.gitignore此前无对应规则,git add -A会误提交(含本地绝对路径的SENTINEL_OUT.log)。补规则并删除遗留样例.claude/agent-sessions/orch-pref/。- personal.json「不入库」表述统一:
config/orchestration-personal.json与.example.json的_comment/_path_user原写「随 skill 走,在仓库内」,与 §2.4「gitignore 不入库」矛盾(实际行为是 gitignored)。统一为「在 skill config/ 目录内,但被 .gitignore 排除、不入库」。 - personal.json 路径一致性:§3.3 用户级 vs 项目级叠加表原写
~/.claude/orchestration-personal.json(旧 home 路径),与 §2.4 现行config/orchestration-personal.json不一致,已统一为 config/ 路径。 - §2.4 TODO stale 字段:
main_force.models→main_force.task_routing(schema 已重命名),coddex拼写 →codex。 - registry example 反混淆注释:
claude-provider-registry.example.json的_comment原直接给出真实 endpoint 对照(open.bigmodel.cn / api.deepseek.com / api.minimaxi.com),使别名脱敏形同虚设,已删除改为占位说明。 - 清理
.DS_Store。
Reason
- 触发:对本 skill 做 skill-lint 发布前验收,命中 1 个凭证暴露风险 + 4 个文档/元数据一致性问题。凭证按「默认按严重处理」,其余为发布一致性修复。
[1.17.2] - 2026-07-03
Fixed
- codebuddy / qoderclicn batch mode 启动参数(CLI flag 误用导致 Wave 1 worker 出货失败):派 Wave 1(
doc-curator-iter-2026-07-03)实测两个 worker 都立即退出 / 卡住,investigator worker 14 行 A/B 测试定位到 render-runtime-profile.sh 生成命令时 2 个 flag 错配 + 个人配置 1 个 model key 错误:- F1:codebuddy batch 默认
--permission-mode acceptEdits与-y冲突,CLI 自己报错要求codebuddy -p -y "<prompt>"或--permission-mode bypassPermissions。改为 batch 默认bypassPermissions(交互式不动)。 - F3:qoderclicn batch 模式必须显式
--dangerously-skip-permissions(--permission-mode auto在 headless 不 bypass)。自动加在MODE=batch路径里(SKIP_PERMISSIONS=1已存在的语义不变)。 - F2:
config/orchestration-personal.jsonbackend_model_routing.qoderclicn.default_models把qoder-3.7MAX/qoder-3.7PLUS(CLI 不接受)换成[qmodel_latest, qmodel](CLI 1.0.34 实证可用 key 之一)。tier_note同步标注实际对应Qwen3.7-Max/Qwen3.7-Plus。
- F1:codebuddy batch 默认
- 诊断先于修复(meta 流程):用 investigator worker 14 行 A/B 测试(A/B 改 1-2 个 flag 看哪个 fix pass)+
/tmp/cli-diagnostic-report.md沉淀证据 + CLI 实测拒绝消息。最小 3 行改 + 单 commit,不直接凭印象 patch。
Reason
- 触发:本次 Wave 1 派发失败时 PM 一度怀疑 GUI 登录态 / trust folder / path 转义。Diagnoser 14 行 A/B 实验逐一排除(GUI app 全部运行中、登录态齐备、空目录 trust folder 也通过、ARG_MAX 1MB ≫ 提示词 6KB、shell 转义正确)。定位到 F1+F3 是 render-profile 默认值错,F2 是 personal.json model 名字错。
- 决策:source 修默认值而非文档「PM 用对 flag」。理由:默认值下 CLI 默认跑通是「先入坑后纠错」的逆向发现,文档「PM 用 -p -y」很多用户不知道;与其让每个 PM 犯错不如让 render-profile 默认发对命令。
[1.17.1] - 2026-07-03
Fixed
- codebuddy / qoderclicn 假阴性检测(PATH-less 已知 .app bundle 多源检测):先前
check-dependencies.sh --backend codebuddy/--backend qoderwork-cn只跑command -v codebuddy+command -v qoderclicn,desktop 端已装但未建 symlink 时(如/usr/local/bin/codebuddy)会假阴性报 MISSING/WARN 但不给出 actionable fix,PM 误判 worker CLI 不可用。新增check_app_bundle_binary()多源检测:先查PATH,再依次查已知 .app bundle 绝对路径(codebuddy:/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy; qoderclicn: CN 版/Applications/QoderWork CN.app/Contents/Resources/bin/qoderclicn+ 国际版/Applications/QoderWork.app/Contents/Resources/bin/qodercli),找到 bundle 时给DEPENDENCY_WARN+ actionable fix(spawn-worker.sh --command直接传绝对路径 /sudo ln -s永久 symlink),都找不到时显式提示装桌面端。两条 backend case 同步加进 usage() 帮助文本。 - references/07-qoderwork-cli-worker.md §2.1:新增「PATH-less 检测」一节,指引 PM 在新机器派 worker 前跑
check-dependencies.sh --backend qoderwork-cn --strict;附 spawn-worker 传绝对路径 /sudo ln -s两条 fix。 - references/08-workbuddy-cli-worker.md §2.2:同 §2.1 形态,codebuddy 版本。
- 新
--backend选项启用:usage 文本加codebuddy | qoderwork-cn。
Reason
- 触发:用户 2026-07-03 派 Wave 1 时实测——
which codebuddy+which qoderclicn都报not found,PM 一度以为 desktop 端没装;后续 ls 发现.app bundle内二进制其实在,是 symlink 没建。规则:「binary 实际在 app bundle」也算 worker 可用(spawn 传绝对路径即可),不应被漏报。 - 决策:不自动
sudo ln -s创建 symlink(高风险操作、PM/用户应显式确认),改为报告 + 给两条 fix 让 PM 选;check_app_bundle_binary()设计为静默存在性检查(前置于它的check_optional_cmd已决定 OK/WARN),避免重复 report。
[1.17.0] - 2026-07-03
Added
- cron + sentinel 标准组合监测模式(§7.3):sentinel(§7.2)是主监测,但有 3 个盲区——(a) worker 硬卡死不写 STATUS 时 sentinel 轮询到
--max-wait超时(exit 124);(b) worker 用非标准 STATUS 文件名(如issue-XXX-status.json)时 sentinel 监听STATUS.json轮询空文件到超时;(c) sentinel 自身被 SIGKILL/SIGTERM 或 harness 未 re-invoke 时静默消失。新增 §7.3 把"sentinel(秒级抓 done)+ cron(兜底:漏合入 + 硬卡死双信号检测 + sentinel 失效)"写成标准两层组合,而非二选一。PM 派 worker 后必挂两层。 - cron 兜底频次硬推荐:短任务 ~22min、长流水线 10-15min,避开
:00/:30整点(API 拥堵 + 速率限制)。给出错峰 cron 表达式(3,13,23,33,43,53 * * * *每 10 分钟 /7,29,51 * * * *每 22 分钟)。不低于 10 分钟(过频抵消 token efficiency)。 - 双信号卡死检测:判 worker 卡死必须 STATUS.updated_at + 文件 mtime 都超阈值(长流水线 20min)且 pane 尾部有死循环证据,缺一不可;避免把正常 long thinking 误判为死循环。只满足时间信号时发
tmux send-keys心跳探针,下一轮再判。 templates/cron-monitor-prompt.md:可复用 cron prompt 模板(worker session + STATUS 路径 + git 分支 + sentinel id + stale 阈值 + 收尾自删 + 无动作一句话汇报),含占位符表 + cron 表达式建议表 + 收尾纪律。
Reason
- 来源:用户 2026-07-03 反馈"cron 兜底频次 30 分钟太低,起码 10 分钟",并提议改进 skill 兜底频次。排查发现 SKILL.md §7 原本没有 cron 兜底频次的硬性数字(30 分钟是 PM 按 cache 经济性自设,偏稀疏),但 skill 内部 TASKS #69/#70 早已登记"把 cron+sentinel 标准组合 + 10-15min 频次写进 §7 + 建 cron 模板"两条待办,本次一并实施。
- 决策:sentinel 事件驱动零 idle token 是主监测不可废;cron 兜底抓 sentinel 三个盲区 + 卡死双信号检测,是 graceful 降级而非替代。频次按任务粒度(长流水线 10-15min)平衡 catch-up 速度与 re-invoke token 成本。详见 DEC-038。
[1.16.7] - 2026-07-02
Added
- 个人 backend 路由偏好配置机制(用户级,可被任何人自定义):
- 新增
config/orchestration-personal.example.json模板,字段:main_force(主力 host + model 轮换)、codex_policy(explicit_only/allowed)、backend_model_routing(qoderclicn/codebuddy的默认 model 列表)、notes。任何用户可复制为~/.claude/orchestration-personal.json后按个人可用 provider / model / 平台额度修改。 - SKILL.md §2.4 新增「个人路由偏好」小节:PM 派 worker 前先读
~/.claude/orchestration-personal.json(缺失回落 example);字段定义 + 缺省回落表;与 §2.2 / §2.3 / §3.3 的优先级关系。 - SKILL.md §2.2 加「Backend → 默认模型速查表」:Claude Code 默认
glm-5.2/MiniMax-M3轮换;qoderclicn默认qoder-3.7MAX/qoder-3.7PLUS;codebuddy默认deepseek-v4-pro/deepseek-v4-flash;Codex 默认explicit_only(仅用户明确要求时启用)。 - SKILL.md §3.3 增「用户级 vs 项目级」叠加表,明确
~/.claude/orchestration-personal.json与.claude/orchestration.config.json不冲突,字段命名刻意不重叠。 references/06-agent-cli-reference.md§0 总览表加「默认 model(个人偏好)」列。
- 新增
Known Limitations
render-runtime-profile.sh暂未自动读 personal config:本次只做配置 + 文档 + PM 手动遵循。后续增强(解析main_force.models→ 默认--model、codex_policy.policy→ Codex backend gate、backend_model_routing.<backend>.default_models→ 跨工具 default)需要开新 worker 单独做,避免无人监督下改脚本引入新不确定性。
Reason
- 来源:用户确认主力 = Claude Code host + GLM-5.2 / MiniMax-M3 轮换;Codex 智能高但额度贵,仅在用户明确要求时启用;
qoderclicn/codebuddy跨工具 backend 在主力不够或用户明确指定时才派;每个 backend 的默认 model 也是个人偏好(不是 skill 级硬编码)。 - 决策:把"个人偏好"做成跟个人 dotfile 一样不进仓库(
~/.claude/orchestration-personal.json),skill 内只留 example 模板 + 文档;机制可被其他用户复制和修改。Codexexplicit_only作为软推荐(个人偏好层面),不强写进 skill 硬规则。
[1.16.6] - 2026-06-26
Added
- ref 08 §6.7 复测更新(codebuddy 多模型 eval):writing-reviewer v0.10.7 cross-model eval 中,codebuddy backend 并发跑 kimi-k2.6 / deepseek-v4-flash / deepseek-v4-pro(同 ch08 baseline 71 hard FAIL),三个 worker pass-1 全部 71→51,backend 在多模型 fan-out 下端到端可用。
- snapshot-copy-into-worktree pattern(backend 无关关键修复):eval skill 快照在主仓库 untracked → fresh worktree 看不到;codebuddy trust-folder 又禁止跨目录读。修复:spawn 时把冻结 snapshot 拷进 worktree,worker 用 worktree-local 相对路径读,同时消除跨目录访问 / trust 限制 / path 漂移三类问题。详见 DEC-037。
codebuddy-spawn.shhelper:research/verification/writing-reviewer-skill-version-eval-260622/codebuddy-spawn.sh,一条命令完成 worktree add + snapshot 拷贝 + session context + tmux(codebuddy 交互 + MCP off)。codebuddy/qoder spawn 暂用此手动 helper。- codebuddy MCP-off 标准flag:正文修订任务用
--strict-mcp-config --mcp-config /tmp/empty-mcp.json({"mcpServers":{}})关 MCP,减前言 + 避免 WorkBuddy MCP 连接器 GUI 授权弹窗。 render-runtime-profile.sh --no-mcp开关:Claude Code worker 传--no-mcp自动注入--strict-mcp-config --mcp-config '{"mcpServers":{}}',跳过 "new MCP servers found" 审批弹窗(实测有效)。- eval worker 权限约定(worktree 隔离 → 最高权限):eval/test worker 都在独立 worktree 里跑、安全隔离,统一用最高权限免任何手动点击——Claude Code
--permission-mode bypassPermissions(或--dangerously-skip-permissions,经 render-runtime-profile 的--permission-mode传入)、codebuddy-y(--dangerously-skip-permissions)、qoderclicn--dangerously-skip-permissions。配合--no-mcp,spawn 后直达 REPL,零点击。
Known Limitations
render-runtime-profile.sh仍不支持 codebuddy / qoderclicn backend:只支持 claude-code(registry/settings)/ codex / opencode。codebuddy/qoder worker 暂走手动 helper 或原生--worktree --tmux。TODO:把这两个 backend 加进 render-runtime-profile,统一 spawn 路径。
[1.16.5] - 2026-06-23
Added
- Claude provider/model registry 模式:新增
config/claude-provider-registry.example.json,按 MyAgents 的 provider intent 思路,把多个 provider 的base_url、auth_token_env/api_key_env、auth_type和models放入一个本地 registry。真实 registry 仍放 ignored local 文件,真实 key 优先用环境变量承载。 claude-provider-env.sh支持 registry:新增--provider-registry PATH --api-provider ID --model MODEL_ALIAS,启动时解析 provider base URL、auth token 和模型别名,构造本次 worker 的有效 env。render-runtime-profile.sh支持 registry:新增--provider-registry,在渲染阶段把 model alias 解析成真实 provider model,并传给claude --model;旧--settings路径保留兼容。
Changed
- 文档改为 registry-first:
SKILL.md、references/01-model-selection-matrix.md、references/06-agent-cli-reference.md、references/10-parallel-lessons.md改为推荐 registry + provider id + model alias,旧的每模型一个 settings 文件标为兼容路径。
Reason
- 来源:用户确认不同模型来源有不同 Base URL、API key 和模型清单,希望参照 MyAgents 运行时动态选择 provider/model 的方式,减少为每个模型维护独立 settings JSON。
- 决策:保留两种模式。registry 模式作为默认推荐,settings 模式作为已有流程和排障兼容。这样 Agent 后续只需要指定
api_provider与model alias,由 wrapper 动态生成 Claude Code worker 环境。
[1.16.4] - 2026-06-23
Added
- Claude Code provider env isolation wrapper:新增
scripts/claude-provider-env.sh,借鉴 MyAgents 的 runtime snapshot/env 构造思路,在启动第三方 provider worker 前清理继承的 Claude/Anthropic provider 路由变量,从目标 settings JSON 导入 env,补齐ANTHROPIC_AUTH_TOKEN/ANTHROPIC_API_KEY,设置CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST=1,并给claude注入--setting-sources project,local。 - runtime metadata env isolation 字段:
spawn-worker.sh新增--env-isolation,写入METADATA.json的runtime.env_isolation,方便 PM 复盘某个 worker 是否走了 wrapper、OAuth 清理或继承环境。
Changed
render-runtime-profile.sh默认包 wrapper:claude-code + --settings + --model现在默认生成bash scripts/claude-provider-env.sh ... -- claude ...命令;排障时可显式--no-provider-env-isolation绕过。- batch render 自动 shell-wrap:
render-runtime-profile.sh --mode batch生成的 Claude/Codex/OpenCode 命令会自动包bash -lc,避免<重定向或$(cat prompt)在spawn-worker.sh的 tmux command 中不展开。 - Provider smoke 与文档同步:
smoke-provider-settings.sh改为走 wrapper;SKILL.md、references/01-model-selection-matrix.md、references/06-agent-cli-reference.md、references/10-parallel-lessons.md更新为 settings +--model+ wrapper 三件套口径。 - Provider settings 模板补全:example settings 增加
ANTHROPIC_API_KEY和 haiku/opus/sonnet_MODEL_NAME字段;真实 settings 仍保持本地 ignored。
Reason
- 来源:用户指出另一个项目 MyAgents 在运行时可以动态选择 provider/model,并且可能屏蔽了用户级 Claude settings。对照 MyAgents 发现关键不是 SDK 本身,而是一次会话启动前的有效配置快照、settings-sourced provider env 屏蔽和子进程 env 显式构造。
- 本次把该模式移植到 Claude Code CLI worker 层,解决用户级
~/.claude/settings.json指向 MiniMax 时,任务指定 GLM/DeepSeek/MiniMax 等 provider 仍可能被全局配置污染的问题。
[1.16.3] - 2026-06-23
Fixed
- Claude Code 第三方 provider 启动命令强制显式模型:
render-runtime-profile.sh在claude-code + --settings但缺少--model时直接报错,避免用户级~/.claude/settings.json或继承环境中的ANTHROPIC_MODEL覆盖 provider profile。 - Provider settings 模板补全当前模型字段:
config/claude-provider-settings.example.json新增ANTHROPIC_MODEL、ANTHROPIC_MODEL_NAME、ANTHROPIC_DEFAULT_FABLE_MODEL和ANTHROPIC_DEFAULT_FABLE_MODEL_NAME,与现有 haiku/opus/sonnet 映射共同描述 provider 模型。 - 启动文档修正:
SKILL.md、references/06-agent-cli-reference.md、references/10-parallel-lessons.md不再建议只用claude --settings <settings>;第三方 provider worker 标准命令改为claude --settings <settings> --model <provider-model> ...,并要求 PM 核对启动 banner。 - Provider settings 排障口径:补充 401/403、429/529、banner 模型错位、MCP 卡启动的判断规则。
Reason
- 来源:法律 AI 书
writing-reviewerskill-version eval 中,PM 以 GLM 5.2 settings 启动 worker,交互界面仍显示MiniMax-M3[1m]。诊断发现用户级~/.claude/settings.json配置了ANTHROPIC_MODEL=MiniMax-M3[1m],而本地 provider settings 只配置 base URL、token 和默认模型映射,没有配置当前会话模型。 - 实测结果:只传
--settings glm-5.2.settings.json时 banner 显示 MiniMax;补--model glm-5.2[1M]后 banner 显示 GLM;在 settings 内补ANTHROPIC_MODEL后,即使漏传--model,banner 也不再被用户级 MiniMax 默认覆盖。 - 同轮诊断还确认 GLM 5.1 / 5.2 最小请求均返回
open.bigmodel.cn的 529,MiniMax 最小请求正常。这说明 GLM 当时的失败是目标 provider 网关拥塞 / 限流,不是 Claude Code 本地 settings 解析失败或余额不足。
[1.16.2] - 2026-06-15
Fixed (文档层)
SKILL.md §6 启动方式加 2 段醒目警示,来源 FaroPDF v0.2 Wave 1 spawn ISS-071 worker 实战([DEC-033]):<redirect 必须用bash -lc包:spawn-worker.sh:305tmux new-session -d -s "$SESSION" -c "$WORKTREE" "$COMMAND"直接 exec command 不通过 shell,shell metacharacter 不展开。错误:--command 'claude -p < /tmp/x.md';正确:--command "bash -lc 'claude -p < /tmp/x.md'"。- claude
-pbatch 模式 autocompact thrash 风险:大 prompt(> 5KB)+ 大 codebase context 会触发 claude 内部Autocompact is thrashing3 次后自动终止,worker 永远不到达终态。规避:拆小 prompt < 3KB / 用交互式 claude + tmux send-keys / 窄 scope worker。
Reason
- 2026-06-15 FaroPDF v0.2 推进期间,PM 按 §3.1 启动 Wave 1(3 worker ISS-071/067/070 并行)。spawn ISS-071 一个验证链路,遇到 2 个 skill 层 bug:
--command 'claude -p < /tmp/iss-071-prompt.md'启动后 worker 立即退出,sentinel 等 7211s 后 SENTINEL_TIMEOUT。- 修复 Bug 1 后 worker 真启动 + 写 STATUS.json bootstrap,4 分钟后 claude 进程 autocompact thrash 自动停止,sentinel 持续轮询。
- PM 决策取消 Wave 1,改单 session 直推 ISS-071。详见项目侧
FaroPDF/docs/DECISIONS.mdDEC-104 + skill 侧 [DEC-033]。 - 本次只改文档警示,不动
spawn-worker.sh脚本(自动检测 shell metachar 留 follow-up,避免覆盖用户的非 bash shell 选择)。
Follow-up (TASKS 已登记)
spawn-worker.shopt-in--shell-wrapflag 自动包bash -lc(待证据足够时升级)templates/worker-prompt.md加专门小节说明 claude -p 模式限制 + 替代方案- memory
project-multi-agent-state补 Wave 1 / Bug A&B 经验
[1.16.1] - 2026-06-05
Fixed
scripts/sentinel.shsynonym 兜底:case 分支接受 worker 实际写的 synonym 终态。成功终态done|completed|finished|complete→ exit 0;失败终态failed|blocked|stopped|aborted|cancelled→ exit 2。SENTINEL_UNKNOWN_STATUS仍保留*)诊断 log,但不再让 worker 写 synonym 时死锁轮询到--max-wait。
Changed
templates/worker-prompt.mdProcess §9:新增"Canonical terminal status (mandatory)"步骤,明确 worker 终态必须用status="done"exactly;defensively sentinel 也认completed/finished/complete,但 worker 不得依赖 synonym。引用项目侧 DEC-060 / skill 侧 [DEC-032]。
Reason
- 来源:v1.16.0 sentinel bash 模式首次在 FaroPDF Wave 6 真用(2 worker 并行),两位 worker 写
status="completed"/status="finished"逃过 sentinel case 分支的done严格判断,sentinel 持续空转,PM 收不到 harness task-notification,直到用户手动问"进度"才暴露。Spike 阶段只测了done/failed严格用法,没覆盖 LLM 写 synonym 的漂移。 - 验证:Wave 6 实战触发,PM 收口时 kill 2 sentinel(exit 143)+ 写双侧 patch 后已修复。Wave 7+ 工人按 worker-prompt.md §9 写
status="done",sentinel 事件驱动链路恢复。 - 项目侧对应:FaroPDF 仓
docs/DECISIONS.mdDEC-060(PR #48 / 2026-06-05)记录了实战触发 + 修复方案;本条 CHANGELOG 是 skill 侧 [DEC-032] 的实际交付记录。
[1.16.0] - 2026-06-05
Added
- Sentinel bash 模式(Task #9):每个 worker 配一个
scripts/sentinel.sh进程,PM 用run_in_background=true启,harness 在 sentinel exit 时通过 task-notification 自动 re-invoke PM,实现事件驱动 PM 唤醒,零 idle token 消耗。 scripts/sentinel.sh:轮询STATUS.json终态(done | failed | blocked | stopped),命中后 capture tmux pane tail、tmux kill-session、exit。退出码 0/2/64/124 与wait-worker.sh对齐。复用redact_sensitive_stream内联(不抽公共库)。templates/pm-sentinel-response.md:PM 收到 sentinel task-notification 后的标准动作清单,按 exit code 分支(0=done, 2=failed/blocked/stopped, 124=timeout, 64=usage error),含范围检查、graceful 降级到pm-monitor.sh路径。references/04-sentinel-design.md:设计文档,复述 2026-06-05 3 phase spike 结果,解释为什么 Sentinel 模式与 DEC-030 假设不同(数量线性 / 单进程单 STATUS / 进程语义清晰 / graceful 降级)。scripts/smoke-sentinel.sh:端到端 smoke test,覆盖 done 路径(sentinel exit 0 + tmux killed + pane tail captured + redaction 工作)和 timeout 路径(sentinel exit 124 + max-wait 触发)。
Changed
scripts/spawn-worker.sh:新增--with-sentinel、--sentinel-poll-interval、--sentinel-max-wait、--keep-tmux-on-terminal标志。--with-sentinel启用时输出SPAWN_WORKER_SENTINEL_CMD: ...和SPAWN_WORKER_RECOMMENDED_NEXT: ...提示 PM 在下一次 Bash 调用里run_in_background=true启 sentinel。不在 spawn-worker 内部启 sentinel(职责分离 + 避免 auto mode 拒多 background)。scripts/lint-wait-script.sh:默认 lint 集合加入sentinel.sh,复用现有bash -n+ substring expansion 检查。SKILL.md§6 工具面:列出sentinel.sh;§7.1 增加脚注指向 §7.2("§7.2 是本规则的限定条件下可工作变体");新增 §7.2 Sentinel bash 模式章节,描述 PM 端两次 Bash 调用模式、事件命名空间、降级路径、调优建议。SKILL.mdfrontmatter:version bump1.15.1→1.16.0。DECISIONS.md:新增[DEC-031] - 2026-06-05 - Sentinel bash 模式 (Task #9 实施),限定条件下 supersede DEC-030,明确 sentinel 数 = 未完结 worker 数(线性而非 N×N)、单进程单 STATUS、graceful 降级是默认行为。DEC-030 文本保留(历史判断)。
Reason
- 来源:Wave 4/5 实际痛点——PM 用
pm-monitor.sh --log-file巡检是 polling-based,事件驱动不闭环,PM 必须靠用户输入或低频轮询才能感知 worker 终态。Wave 5 收口时把 Task #9 标"designed, not implemented"。 - 验证:2026-06-05 30 分钟 Spike 在 Claude Code 实测
run_in_background=trueBash 任务,3 phases 全部通过——harness 不区分 exit code(0/1/124 都 re-invoke),多次并发 notification 同 turn 批处理,单 background 拒率 spike 实测 1/6,graceful 降级是默认行为。 - 结论:在限定条件下(sentinel 数线性、单进程单 STATUS、graceful 降级),
run_in_background=trueBash 任务可以作为可靠的 PM 唤醒机制。Wave 6 启动时启用。
Out of Scope(避免在本次 PR 蔓延)
- Codex / OpenCode worker 的 sentinel 集成:暂未实测,Codex 走
templates/codex-heartbeat-wait.md - 多 sentinel 对单 worker 去重:PM 行为层处理
- 重写
pm-monitor.sh(Task #6 单独 PR)
[1.15.1] - 2026-06-05
Changed
- Claude Code background wait caveat:修正
run-in-background描述,明确 background Bash 只负责后台运行等待器,不保证把 worker 终态消息推回 PM / agent session。 - multi-worker monitoring:多 worker / Wave 默认使用
pm-monitor.sh --log-file+ 显式低频巡检,不再建议为每个 worker 启 background wait 并期待宿主自动回调。
Reason
- 来源:用户在 Claude Code 中实测发现,background Bash 没有可靠触发 agent session;开启多个独立 worker 时可能没有任何消息返回。
- 结论:完成通知必须回到结构化 checkpoint、事件日志和显式巡检;background job 只能作为日志写入器或人工可查看后台进程。
[1.15.0] - 2026-06-05
Added
- optional project config template:新增
templates/project-config.json,声明 trunk、任务源、worktree/session 默认路径、按 worker type 拆分的验证命令、provider slot、非敏感配置复制清单和 hook 边界。
Changed
- SKILL.md config discipline:标准流程增加项目配置读取规则,明确配置只提供默认值,不替代 PM 判断。
- Goal/worker templates:增加 project config 字段,要求 PM 写明采用了哪些配置字段、忽略了哪些字段以及安全检查结果。
Reason
- 来源:TASKS 中仍有“评估项目级配置文件”待办,且用户关注脚本是否过度设计。
- 结论:采用轻量模板,不新增脚本、不自动读取、不自动复制配置、不自动执行 hook;
.env、真实 settings、token/key/cert 等继续默认禁止。
[1.14.1] - 2026-06-05
Changed
- script surface governance:明确默认工具面只包含 dependency check、runtime profile render、spawn worker 和 PM monitor;status/clean/wait/test/terminal split 均按场景使用,避免 PM 被脚本数量牵引。
- provider slot planning:超过 4 个 worker 时,改为显式声明
backend + settings/profile path + provider + model + max concurrency,而不是脚本自动猜测用哪个 settings.json。 - templates:worker prompt、checkpoint、Goal Contract 和 Wave Summary 增加 settings/profile path,让每个 worker 的额度来源可审计但不暴露 settings 内容。
Reason
- 来源:用户担心脚本数量过多、出现过度设计,并追问超过 4 个 worker 时到底如何分配 settings.json。
- 结论:不新增自动 scheduler。现阶段应把 provider pool 做成 PM 可审计的显式 slot 表;如果只有一个可用 settings/profile,则并发 cap 降到 3-4,剩余任务进入下一 Wave。
[1.14.0] - 2026-06-05
Added
- runtime dependency matrix:新增
references/02-runtime-dependencies.md,按 core、tmux/worktree、PR/GitHub、worker backend、Codex heartbeat、terminal split 和验证工具拆分依赖。 - dependency checker:新增
scripts/check-dependencies.sh,可检查核心依赖、backend CLI、gh和终端分屏工具;脚本只报告状态,不安装软件、不启动 worker。
Changed
- SKILL.md dependency section:将依赖说明从单张系统依赖表升级为分层依赖说明,明确
claude、codex、opencode、gh不是所有模式的硬依赖。 - smoke test:
smoke-tmux-worker.sh纳入 dependency checker 基础回归。
Reason
- 来源:用户指出使用本 Skill 可能还有常规依赖需要安装,当前文档没有写清楚。
- 结论:依赖应按执行模式拆分,避免把所有可选 backend 都误解为必装,同时给 PM 一个启动前的本地检查入口。
[1.13.0] - 2026-06-05
Added
- runtime profile command helper:新增
scripts/render-runtime-profile.sh,按claude-code、claude-oauth、codex、opencode、custombackend 生成 worker command、prompt context 和 spawn metadata,减少 PM 手写 provider/profile 命令。 - Agent Teams troubleshooting:新增
references/11-agent-teams-troubleshooting.md,覆盖 agent/team 不可见、错误 cwd、官方 worktree 状态映射、checkpoint 缺失、PR 收口和必须停止的场景。
Changed
- spawn flow:SKILL.md 启动示例改为先用
render-runtime-profile.sh生成 runtime 字段,再传给spawn-worker.sh,保持启动命令生成与 worktree/session gate 分离。 - smoke test:
smoke-tmux-worker.sh覆盖 runtime profile helper 的 custom、Claude Code 和 Codex 输出。
Reason
- 来源:用户要求继续推进 TASKS 中可落地的优化项。
- 结论:Agent Teams 排障指南和 runtime profile helper 都能本地落地并提升稳定性;Agent Teams feature flag、真实 Claude 原生
--worktree --tmux后端和跨 PM/worker smoke 仍需要真实宿主环境验证。
[1.12.0] - 2026-06-05
Added
- Goal-Driven Multi-Wave Loop:SKILL.md 新增 PM 级 Orchestration Goal Loop,支持在成功条件满足前自动收口当前 Wave、读取任务源、选择下一批安全任务并启动下一 Wave。
- Goal Contract 模板:新增
templates/orchestration-goal.md,要求 PM 在连续推进前写清任务源、成功条件、自主级别、并发/预算上限、继续条件和停止条件。 - Goal Loop 状态映射:
checkpoint-status.json增加orchestration_goal字段;worker-prompt.md增加 Goal ID / Loop Iteration,并明确 worker 不得自行领取其他任务。
Changed
- Wave summary:新增 Goal ID、loop iteration、continue/stop decision、remaining tasks 和 next Wave 字段,让每轮自动继续都有可审计记录。
- Skill 路由:明确 Claude Code / Codex
/goal可作为 PM loop 的宿主续跑能力,但不替代 worktree、tmux、checkpoint、review 和 merge 门禁。
Reason
- 来源:用户希望多 Agent 编排不止“一次运行一个 Wave”,而是在 PR 验收、验证和任务源状态正常时,能自动继续下一 Wave,直到目标范围内任务耗尽或触发停机条件。
- 结论:连续推进应放在 PM 层,不放给 worker;worker 保持窄任务边界,PM 负责任务池、Wave 收口、继续/停止判断和合并门禁。
[1.11.0] - 2026-06-04
Added
- Wave-Based Orchestration:SKILL.md 新增 Wave 一等调度概念,要求 PM 在每轮启动前记录
wave_id、worker 清单、base ref、共享风险、provider/model/slot、收口顺序和下一轮进入条件。 - 跨 provider 并发池:明确超过 3-4 个 worker 时不应压在单一 API provider 上,应跨 runtime profile/API 来源分流,并在 Wave 收口时评估模型/provider 表现。
- worker 类型与验证底线:worker prompt 新增
ui-wiring、contract-extension、tauri-command、docs/research等类型,明确 Tauri/Rust worker 的cargo check --offline验证底线和 skipped verification 记录要求。 - Wave checkpoint 字段与 summary 模板:
checkpoint-status.json新增wave、worker_class、provider/model/slot 和model_evaluation字段;新增templates/wave-summary.md。 - 多信号进展巡检:
pm-monitor.sh新增--wave-id、--progress-stale-threshold、WORKER_SILENT_PROGRESS、WORKER_NO_PROGRESS和WORKER_FINISHED_NO_PHASE_DONE,结合 STATUS、commit、file mtime 和 dirty state 判断 worker 是否真有进展。 - wait script lint:新增
scripts/lint-wait-script.sh,用于检查 wait/monitor/custom wait 脚本的bash -n和${VAR:0:N}substring 闭合错误。 - worktree metadata:
spawn-worker.sh在 Session Context 写入METADATA.json,记录 base、session、runtime profile、provider slot、验证命令和 PR 占位;worktree-status.sh/clean-worktree.sh会展示该摘要。
Changed
- worker prompt:加入 Wave 信息、provider slot、Decision ID race 规则、worker type rules 和验证底线。
- spawn gate:
spawn-worker.sh、worktree-status.sh和clean-worktree.sh使用物理路径解析,避免 macOS/var//private/var别名导致 cwd gate 误失败。 - worktree-status.sh:单 worker 只读总览增加 wave/provider/model/type 输出。
- smoke test:
smoke-tmux-worker.sh通过spawn-worker.sh创建 worker,覆盖 metadata 写入、总览展示和清理前摘要。 - parallel-lessons.md:补充 Wave worker 类型、Vitest/Vite 二进制资源兼容、DEC 编号 race 和 provider 并发池实战记录。
Reason
- 来源:用户要求评估 TASKS 中多个优化/升级建议,并把合理项升级为
multi-agent-orchestration的正式机制。 - 结论:Wave、provider 并发池、多信号巡检、worker 类型、验证底线和 DEC race 属于高复用执行协议;Agent Teams 发布状态、终端 split-panes、底层 adapter、Snap mode 等仍留作后续研究。
[1.10.0] - 2026-06-04
Added
- worker 生命周期脚本:新增
spawn-worker.sh、worktree-status.sh、clean-worktree.sh和smoke-tmux-worker.sh,把 worktree/session 创建、单 worker 状态总览、安全清理和端到端 smoke test 固化为可执行入口。 - commit stale 事件:
pm-monitor.sh新增--commit-stale-threshold和WORKER_STALE_NO_COMMIT,用于提示 session 存活但分支长时间没有阶段性提交的 worker。 - Codex heartbeat 模板:新增
templates/codex-heartbeat-wait.md,明确 Codex App 用wait-worker.sh --once做轻量唤醒,创建/修改 automation 时必须使用automation_update工具。 - Worker commit cadence:worker prompt 要求长任务每 30-60 分钟或阶段完成后生成可 review commit,并刷新
STATUS.json的 Git 字段。
Changed
- wait-worker.sh 输出脱敏:tmux pane tail 和 RESULT tail 默认过滤 token/key/secret/auth/password 等敏感行,并替换常见 secret token 片段。
- SKILL.md 压缩启动章节:将长启动示例收束为
spawn-worker.sh+ 常用 command 索引,保留防逃逸门禁和最小验证规则。 - checkpoint Git 字段:
templates/checkpoint-status.json增加git.last_commit_at和git.commits_since_base,pm-monitor.sh/worktree-status.sh同步显示。 - 脚本 shebang:核心脚本统一使用
/usr/bin/env bash;pm-monitor.sh增加 bash 4+ 版本门禁,避免 macOS 系统/bin/bash3.2 运行关联数组失败。 - UTC 时间解析:
pm-monitor.sh和wait-worker.sh在 macOS 上按 UTC 解析updated_at的Z后缀,避免刚写入的 checkpoint 被误报 stale。
Reason
- 来源:用户希望把 “tmux 独立 session 防逃逸” 做成可执行、可验证、可 smoke 的完整协议,并适配 Codex 的后台等待/heartbeat 方式。
- 目标:让 PM 不再依赖手写命令和主观自律;启动、等待、监控、状态、清理和回归验证都有明确脚本入口。
[1.9.9] - 2026-06-03
Added
- wait-worker.sh tmux 诊断尾部输出:新增
--tmux-session、--pane-tail-lines、--include-pane-on和--stale-threshold。默认只在 checkpoint 缺失、过期或终态时读取 tmux pane tail。 - 状态源分层规则:SKILL.md §7.1 明确
STATUS.json/RESULT.md/PATCH_SUMMARY.md是主协议,tmux capture-pane只作诊断窗口,不作为完成标准。
Reason
- 来源:用户提出既然 background Bash 在运行,是否可以直接读取 tmux worker 输出。
- 结论:可以读,但要作为诊断兜底而非主状态源,避免屏幕输出截断、清屏、敏感信息和上下文膨胀影响 PM 判断。
[1.9.8] - 2026-06-03
Added
- scripts/wait-worker.sh:新增单 worker 等待器,可持续等待或
--once快速检查.claude/agent-sessions/<session>/STATUS.json,在done/failed/blocked/stopped时输出 RESULT/PATCH_SUMMARY 路径并退出。 - §7.1 主动等待与宿主唤醒:明确
wait-worker.sh不替代pm-monitor.sh;Claude Code 可接 Bash background/run-in-background,Codex App 则用当前 thread 的 heartbeat automation 调用wait-worker.sh --once实现主动唤醒。
Reason
- 来源:用户希望 Claude Code 的 Bash
run_in_background等待体验也能适配 Codex。 - 结论:Codex CLI 没有同名自动通知机制;Codex 适配应通过“通用等待脚本 + Codex heartbeat/thread wakeup”完成,避免把核心 monitor 绑定到单一宿主。
[1.9.7] - 2026-06-03
Added
- 防逃逸门禁:当用户或项目明确要求 tmux / 独立 session / 开 worker 时,PM 在业务实现前必须创建 worktree/branch、启动 session、验证 cwd/branch、派发 worker prompt 并确认
STATUS.json,否则报告阻塞,不得静默降级为 PM 直接实现或普通 Subagent。 - Worker Isolation Gate:
templates/worker-prompt.md要求 worker 在读任务或实现前确认 cwd、branch 和 worktree;不匹配时写 blockedSTATUS.json并停止。 - STATUS orchestration_gate 字段:
templates/checkpoint-status.json新增 session/cwd/branch/worktree/degraded/escape 结构化门禁字段,pm-monitor.sh会输出ORCHESTRATION_GATE_FAILED。
Fixed
- pm-monitor.sh 本地未 push 分支误退出:远端分支不存在时先查 merged PR;若本地分支仍存在,输出
BRANCH_NOT_PUSHED并保持 monitor 运行。 - SESSION_GONE 去重:tmux session 消失事件只在状态变化时输出,避免低频巡检日志重复刷屏。
Reason
- 来源:用户反馈其他模型在 Claude Code 中反复没有按 tmux 独立 session 推进,需要把“不要逃逸”从建议性描述升级成可检查门禁。
- 目标:让 PM、worker 和 monitor 三层都能暴露逃逸:PM 不能绕过启动门禁,worker 不能在错误目录继续实现,monitor 能报告 gate 失败和本地分支未 push。
[1.9.6] - 2026-06-03
Changed
- SKILL.md §6 tmux / Claude Code worker 例子:去掉
--max-turns 20的限制示例,加注"不要设--max-turns;PM 重点是检测 worker 真在运转而不是限制 turn 数"。 - scripts/pm-monitor.sh BRANCH 状态区分:远端 branch 不存在时,区分两种情况:
- 本地 branch HEAD == main HEAD →
BRANCH_NOT_PUSHED: $branch (waiting for worker to commit and push)(新事件) - 本地 branch HEAD != main HEAD →
BRANCH_MERGED: $branch(保留原行为) - 解决"branch 还没 push 被误判为 merged"导致 monitor 立刻退出的问题。
- 本地 branch HEAD == main HEAD →
Reason
- 来源:FaroPDF v0.1 Wave 2 启 worker 后 PM 监控失灵的根因分析。
- 主要根因:
- worker prompt 没强调"启动后立即写 STATUS.json 心跳",导致 max-turns 触发时没 STATUS.json,PM 无从判断 worker 真在运转。
- SKILL 自带 pm-monitor.sh 的 BRANCH_MERGED 判断只看
origin/$branch是否存在,忽略了"branch 还没 push"的常见 case,导致 monitor 立刻退出。 - SKILL 例子给的
--max-turns 20让我误以为应该设上限,实际应让 worker 跑自然结束。
[1.9.5] - 2026-06-03
Added
- §8.0 PM 在 Worker 提 PR 后的持续同步(精简版):
- 提 PR 之后立即跑
gh pr view <N> --json mergeable,mergeStateStatus,baseRefName;冲突走git-workflow决策表。 - PM 在主目录 commit docs / DEC 之后立即
git push origin main,避免本地与 origin/main drift(squash merge 引入的"内容相同但 history 不同"会让 git 误判冲突)。
- 提 PR 之后立即跑
Reason
- 来源:FaroPDF v0.1 Wave 1 真实合并 PR #18 / #19 前的根因复盘。
- 主要根因:PM 没在 worker 提 PR 后立即跑 mergeable 检查;PM 本地 main commit DEC 后没立即 push。
[1.9.4] - 2026-06-03
Added
parallel-lessons.md新增 G17:任务编号从ISS-NNN改为Task-NNN(与 project-init v1.1.1 对齐)。说明新约定、迁移规则,以及历史 lesson(如 G15 的FaroPDF ISS-018)和 commit history 保持原样不改写。
[1.9.3] - 2026-06-03
Changed
- 将 checkpoint 可复制模板从
references/03-checkpoint-files.md移到templates/,包括checkpoint-status.json、checkpoint-result.md和checkpoint-patch-summary.md。 - 新增
templates/worker-prompt.md,将 worker prompt 拆成 Bootstrap-only 和 Full worker 两段,并按 Context / Background / Mission / Scope / Deliverables / Process / Verification / Autonomy / Out of Scope / PM Correction 组织。 - 精简
SKILL.md与references/03-checkpoint-files.md:正文只保留规则、字段经济性和模板路径,避免 Skill 主体继续膨胀。
[1.9.2] - 2026-06-03
Changed
- 将
STATUS.json升级为 v2 schema,补充task_source、current_action、next_action、scope、runtime、git、pm_action_required、blocker、risks和last_pm_correction等 PM 决策字段。 - 明确
STATUS.json的经济性边界:只记录 PM 自动监控和 review 决策必需的结构化信号,不记录 token、完整环境变量、settings 内容或长日志。 - 增强
pm-monitor.sh:新增--once、--interval、--stale-threshold、--log-file,支持一次性巡检、低频后台巡检和事件日志落盘。 pm-monitor.sh现在会从 checkpoint 输出CHECKPOINT_STALE、AGENT_NEEDS_INPUT、CHECKPOINT_TEST_FAILURE、CHECKPOINT_PR等事件,减少 PM 前台轮询需求。- 补充经济型巡检规则:脚本负责事件输出和日志,是否自动唤起 PM 取决于宿主环境;无唤醒能力时用
--once或低频读取 log tail。
[1.9.1] - 2026-06-03
Changed
- 将新 worker 的 checkpoint 目录从
.agent-context/调整为.claude/agent-sessions/<session-id>/,复用项目既有.claude/协作空间;pm-monitor.sh仍兼容读取旧.agent-context/。 - 明确 Claude Code 官方 Agent Teams 的状态源在
~/.claude/teams/<team>/与~/.claude/tasks/<team>/,不要在项目内自造.claude/teams/冒充官方 team。 - 明确 worktree、分支和 session context 默认由 PM 创建;只有 Claude Code 官方 Agent Teams / agent view 明确使用自身
--worktree能力时,才允许 worker 侧创建隔离环境,PM 仍需验收。 - 将 PM review correction 固化为收口流程:PM review 失败时优先把具体修正发回原 worker,worker 追加修复 commit、更新验证和 PR,PM 再复核。
- 补充环境差异规则:Claude Code provider settings、Claude OAuth/订阅、Codex/OpenAI 和 OpenCode profile 必须分开声明,不默认清理或继承环境变量。
[1.9.0] - 2026-06-02
Changed
- 将 PM 从具体产品中解耦:当前 Codex、Claude Code 或其他主会话都可以担任 PM。
- 将 worker backend 抽象为 Claude Code、Codex、OpenCode、shell 和可选 ACP adapter,支持从 Claude Code 启动 Codex/OpenCode worker,或从 Codex 启动 Claude Code/OpenCode worker。
- 补充 runtime profile / 额度路由规则,明确 Claude Code worker 默认走第三方 API provider settings,订阅/OAuth 只作为显式例外。
- 补充 Claude Code 第三方 API provider settings 模式:通过
--settings /path/to/provider.settings.json加载ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN和默认模型环境变量。 - 将 Claude Code worker 默认额度模式调整为第三方 API provider settings,并新增
references/claude-provider-settings.example.json模板。 - 将 Claude Code tmux worker 默认启动方式调整为交互式后台终端 session;
-p仅作为批处理 prompt 的可选模式。 - 将 provider settings 示例调整为 Minimax Anthropic-compatible API 结构,保持 token、base URL、三类默认模型、timeout、thinking tokens 和行为开关一并配置。
- 增加结构化 checkpoint 三件套:
.agent-context/STATUS.json、RESULT.md、PATCH_SUMMARY.md,并新增模板参考文档。 - 更新
pm-monitor.sh,支持从分支自动定位 worktree、监听 checkpoint 文件变化,并可选通过--claude-agents-cwd读取 Claude 官方后台 session 状态。 - 补充 Claude Code 官方 agent view / background session 入口:
claude agents、claude agents --json、--worktree、--tmux,以及版本支持时的claude --bg和/bg,作为 tmux 之外的 Claude 专用后台会话模式。 - 补充 OpenCode worker 支持:默认用
opencode run --format json --model <provider/model>,并将opencode acp记录为可选 ACP server 候选。 - 补充 custom CLI worker 模板,支持其他可一行命令启动、可在指定 worktree 中运行的 Agent。
- 将 ACP 定位为可选后端:协议层结构化,但默认仍以
tmux + worktree + checkpoint 文件 + git 状态作为稳定执行层。 - 更新 Worker Prompt 模板,加入 PM Host、Worker Backend、Runtime Profile 和
.agent-context/STATUS.json/RESULT.md/PATCH_SUMMARY.mdcheckpoint 协议。 - 明确用户指定当前会话担任 PM agent 时,PM 默认不直接写业务代码;实现优先委派给 worktree worker、独立 session、Agent Teams 或 Subagent,PM 负责巡检、纠偏、review 和收口。
- 基于 FaroPDF ISS-018 实战补充流程约束:高延迟 provider 可两段式 bootstrap;
.agent-context/只作本地 checkpoint,不进入 Git/PR;worker 不应等待 PM 下一步;STATUS 每次写入必须刷新updated_at;窄范围实现默认 low/medium effort。
[1.8.2] - 2026-06-01
Changed
- 收口发布包参考文档,只保留模型/执行模式矩阵、实战坑点和法律项目拆解样例。
- 精简法律场景参考,移除未落地的未来模板路径和外部 catalog 设想,明确其只作为本地执行层拆分样例。
Removed
- 移除已落地或过时的历史平台调研、Agent Teams 优化积压和 Auto PM 蓝图文档,避免与当前 SKILL.md 实现机制重复或冲突。
[1.8.1] - 2026-05-20
Changed
- 同步任务协调层边界说明和参考文档,保持本 Skill 聚焦本地执行编排。
[1.8.0] - 2026-05-20
Changed
- 重命名 Skill:
multi-agent-workflow→multi-agent-orchestration,标题改为 Multi-Agent Orchestration,以突出“本地多 Agent 执行编排”而非普通流程说明。 - 同步更新 SKILL.md description 和开篇说明,统一使用“执行编排”表述。
- 同步更新相关任务协调边界引用。
[1.7.0] - 2026-05-20
Changed
- 重命名 Skill:
parallel-agent-workflow→multi-agent-workflow,标题改为 Multi-Agent Workflow,以匹配当前“多 Agent 本地执行编排”的职责边界。 - 优化 SKILL.md frontmatter description,补充正向触发场景和负向边界。
- 补充脚本依赖说明,明确
pm-monitor.sh与terminal-split.sh的系统依赖和可选终端依赖。 - 同步更新相关任务协调边界引用。
[1.6.0] - 2026-05-19
Changed
- 精简
SKILL.md为执行入口、命名规则、启动方式、巡检和收口规则;复杂细节转交references/和scripts/。 - 明确任务源由项目配置或项目上下文决定,不在 Skill 中写死固定文件路径。
- 保留
pm-monitor.sh的自动 PM 巡检能力,包括 Agent Teams inbox、tasks、Git SHA、PR 状态和 tmux session 多维监控。 - 保留
terminal-split.sh的多终端分屏能力,包括 iTerm2、Kitty、WezTerm、Warp、Ghostty、Zed 和 Terminal.app。
[1.5.0] - 2026-05-17
Added
- 新增从项目任务源形成本地执行计划的通用规则:提取 Issue ID、状态、推进建议、文件/组件、依赖和验收标准。
- 新增 待办事项分组策略:按文件/组件重叠、依赖链、并行安全度和 PR 审查边界决定多个 Issue 是否放入同一 worktree/session。
- 新增 L1/L2/L3 路由说明,明确不是一个 Issue 必然对应一个 session。
Changed
multi-agent-orchestration继续只拥有本地执行层;分组计划只服务本轮执行,不成为新的任务状态源。
[1.4.0] - 2026-05-17
Changed
- 明确本 Skill 只负责本地 Agent 会话、并行执行、PM 巡检和 worktree 隔离,不拥有任务主状态。
- 标准流程改为从项目任务源接任务;任务读取、外部 Agent 邮件触发和跨平台归属遵循项目既有规则。
- 将
git-task-orchestrator定位改为历史蓝图,不再作为当前协作入口,也不迁入其旧 worktree/session 方案。
[1.3.0] - 2026-05-09
Added
- 任务列表管理:复用 Agent Teams 的 tasks 目录结构(JSON 任务项 + .lock 文件锁 + .highwatermark 增量读取)
- 文件锁机制:agent 认领任务时用
flock()防止并发冲突 - 高水位标记:agent 增量读取任务列表,已完成任务自动删除并更新 highwatermark
- pm-monitor.sh v4.1:新增
--tasks-dir参数、check_task_states()函数、TASK_STATUS/TASK_COMPLETED 事件 - 权限继承自动化:启动时自动从主仓库复制
.claude/settings.json到每个 worktree - Context 恢复:团队协议持久化到 worktree 的
CLAUDE.md,claude --continue后协议不丢失
Changed
- §6.1 创建 Worktree 增加权限自动复制步骤
- §6.2 初始化增加共享任务列表创建
- §6.3 启动 Agent 增加 CLAUDE.md 持久化步骤
- §6.6 清理增加 tasks 目录清理
- pm-monitor.sh 支持
--tasks-dir参数
[1.2.0] - 2026-05-09
Changed
- [重大] tmux 模式统一使用 Agent Teams 文件通信协议:tmux 仅作为进程管理层,通信层复用
~/.claude/teams/的 inbox + tasks 机制 - tmux 模式从"降级模式"重命名为"扩展模式",体现架构对等性
- pm-monitor.sh v4:新增
--team-dir参数,支持 inbox health_report 轮询(6 个新事件类型),保留 git SHA 轮询作为第二维度 - 运行时干预改为 inbox 命令消息 + 短 send-keys 提醒(替代长文本 send-keys)
- 监控巡检改为读取 PM inbox health_report(首选),capture-pane 降为回退方案
Added
- Agent Teams 通信协议 prompt 模板(health_report 发送、命令检查、agent 间 inbox 通信)
- 团队目录初始化步骤(config.json + inbox 文件创建)
- health_report 消息类型(status/phase/progress/last_commit_sha/context_pct/issues)
- inbox 命令协议(continue/stop/check_review_feedback/rebase/commit_and_push)
- pm-monitor.sh 过时检测(5 分钟无 health_report 自动告警)
- 自动 PM 蓝图中的 tmux 扩展模式通信架构
- parallel-lessons.md 文件通信协议操作手册
[1.1.0] - 2026-05-08
Changed
- [重大] 默认使用 Agent Teams(Teammate 模式):在 Claude Code 环境下,重任务优先使用官方 Agent Teams,tmux 降级为非 Claude Code 环境的备选方案
- 任务规模路由从二元(Subagent / tmux)升级为三元(Subagent / Agent Teams / tmux)
- 执行模式对比从二元表扩展为三元表(Subagent / Agent Teams / tmux Session)
- 监控方式从 tmux capture-pane 扩展为 Agent Teams 共享任务列表 + 邮箱系统
- 通信通道增加 Agent Teams 邮箱系统(双向通信,替代单向 send-keys)
- 新增环境检测逻辑(自动选择 Agent Teams 或 tmux 降级)
- 实战经验文档按 Agent Teams / tmux 降级 / 通用三类重组
Added
- SKILL.md §3 前置条件拆分为 Agent Teams 和 tmux 两组
- SKILL.md §4 环境检测与模式选择
- SKILL.md §5 Agent Teams 标准流程(规划/Worktree/启动 Teammates/监控/干预/审查/合并)
- SKILL.md §6 tmux 降级模式(保留完整流程)
- Agent Teams 详细技术调研
[1.0.0] - 2026-05-07
新增
- SKILL.md 核心技能定义,覆盖并行 Agent 完整生命周期
- terminal-split.sh 跨终端分屏脚本(支持 iTerm2/Kitty/WezTerm/Warp/Ghostty/Zed/Terminal.app)
- pm-monitor.sh 参数化 PM Monitor(基于 git SHA 变化,自动停止)
- 模型选择矩阵(L0/L1/L2 路由 + 运行时升降级)
- 执行模式选择(Subagent vs tmux + 混合模式)
- PM 巡检循环蓝图(健康/任务/PR 三维巡检)
- 实战经验教训文档(tmux 陷阱、合并冲突、IME 干扰)
- 与 git-task-orchestrator 的边界定义和协作路由
- 法律实务任务拆解模板(诉讼/非诉/尽调/合同审查)作为扩展参考
- 多 Agent 平台技术调研(Claude Code/OpenClaw/Codex/Hermes 对比 + Skills 生态评测)作为扩展参考