steponeerror · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/GLOSSARY.md b/GLOSSARY.md
@@ -151,6 +151,13 @@
 - **失败归因图**:DeFA 式失败传播依赖图(STANDARD 原语 P22,缺)——多步 agent 误差沿依赖图分离定位到步/工具。锚:ops/agent/STANDARD.md 原语层(P22)
 - **finding 出口三件套**:巡检 finding(ANCHOR_SWEEP 读数 ok 且 finding>0)的三个出口(#184,spec #180 Q6)——gh issue(needs-triage 标签人裁终局,标准模板四件:来源步/锚:期望vs实得/证据指针/处置面)/告警 webhook(apprise CLI,env IP_RADAR_ALERT_URLS 与 backend _alerts.push 同 env 同形=双消费面;未配置=skip 留痕轮仍成功)/RETRO 摘要行(retro 工件 anchor_sweep 字段,G_RETRO 机检与 08 工件回算一致)。出口永不败轮(失败=失败信封记入 08-anchor-sweep-exits.json+信封 pipeline.finding_exits);dry-run 开关 OPS_SWEEP_DRY_RUN(默认关=真发;测试/golden 恒 1);replay 恒零外发(回声律同款)。**「出口只写不动作」红线**(票面钉死):从 finding 出发仅两写口——gh issue create 与 apprise 推送;无任何调权/停源/写数据面/源管理 API/规则库写口可达,由依赖面闭集结构性断言钉死(export 闭集恰三函数/spawn 目标恰 apprise/禁面符号零在场)。锚:ops/agent/pipeline/finding-exit.mjs、tools/measurement.mjs(ghIssueCreate)、tools/registry.mjs(GH_WRITE_SUBCOMMANDS)、票 #184
 - **emit 守卫**:外发崩溃窗防重发机制(#184)——出口工件先记 phase=emitting 再外发、终记 emitted;同轮重入见 emitting/emitted 一律不重发(崩溃窗内外发状态不可知,宁少算交人工核对:issue 重复开可人关,漏发下轮补);工件缺席=首程照发。与「回声防线」的分工:回声防线管轮间重放不产新产物,emit 守卫管同轮恢复不重复外发。锚:ops/agent/pipeline/finding-exit.mjs(runFindingExits)
+- **conversation**:会话——不可变 transcript 记录的宿主与提交面;运营轮宿主 = root conversation,子代理 = 自有 conversation(不共享主轮上下文)。Pi Durable 域词(ADR 0012)。锚:docs/adr/0012(嵌套 docs 仓)
+- **task**:持久任务——相位化的工作单元,提交后由框架驱动至终态、进程崩溃可续;ops 管线轮(健康十态/发现六步)整体相位化为 task,失败三元组(重试/降级/终态)落 task 终态语义。Pi Durable 域词(ADR 0012)。锚:docs/adr/0012(嵌套 docs 仓)
+- **checkpoint**:task 相位的持久快照——崩溃恢复的最小续跑点;v2 起替代手搓轮次状态文件(该词条记旧管线)。Pi Durable 域词(ADR 0012)。锚:docs/adr/0012(嵌套 docs 仓)
+- **replay:safe**:工具崩溃恢复重放的安全声明(缺省 unsafe)——声明该工具重放不产生重复副作用,责任在工具作者;带外部写副作用的工具不得声明。Pi Durable 域词(ADR 0012)。锚:docs/adr/0012(嵌套 docs 仓)
+- **轮次**:运营 agent 的一次完整任务运行(健康轮/发现轮同此基义;复合词轮次信封/轮次状态机沿用)——Pi Durable 迁移定稿(ADR 0012):一轮 = 对 root conversation 的一次 submit(发现轮例外:一轮 = 一 ownerless 会话,tasks/discover-round.mjs:16-24 决策——旧发现轮每模型步全新 Agent 上下文、跨轮零渗漏旧律保持)。锚:docs/adr/0012(嵌套 docs 仓)、docs/superpowers/specs/2026-10-28-ops-agent-pidurable-migration-design.md(术语映射)
+- **台账**:运营轮历史的留痕真源——旧管线自维护 ledger.md/queue.md;Pi Durable 迁移定稿(ADR 0012)= storage 里的 transcript+task 记录,ledger.md 降级为兼容输出面,不再作真源(RETRO 兼容行照写,见 ops/agent-v2/ENVELOPE.md),对下游的兼容输出(月轮评估)由 T5 承接;UI 别名「台账→历史」(ADR 0006)不变。锚:docs/adr/0012(嵌套 docs 仓)
+- **熔断**:通道失败的开断机制,细则与五通道闭集见「跨轮熔断」——Pi Durable 迁移定稿(ADR 0012):仍为自有 breaker.json 文件、读写逻辑随迁,不 hook/memo 化;与预算四界同属自持执法面。锚:docs/adr/0012(嵌套 docs 仓)、ops/agent/tools/breaker.mjs
 
 ## It's working if
 

diff --git a/ops/agent-v2/ENVELOPE.md b/ops/agent-v2/ENVELOPE.md
@@ -0,0 +1,33 @@
+# ENVELOPE.md — 轮次信封契约(冻结面)
+
+票 #229 T5 任务书②裁定。本文件冻结 cron 入口 stdout 的信封形状与 usage 口径;动此面前先过回放闸门(golden + shadow 对拍),否则视为破坏位等价红线。
+
+## stdout 契约(cron 面,`run-health.mjs` / `run-discover.mjs` 同律)
+
+- stdout **末行 = 单行 JSON 旧形信封**,是 stdout 上唯一 JSON;wrapper 进度信息一律走 stderr(`[v2-health]` / `[v2-discover]` / `[stage]` / `[tool]` / `[admission]` 行)。
+- 旧形 = 与 `ops/agent/pipeline.mjs` 信封逐字段同族;形状由对拍测试钉死(round-ctx `composeEnvelope` 逐字副本 + discover 第二副本,golden/shadow 双闸),cron 消费方(脚本、看门狗)零改动。
+
+| 面 | 成功 | 失败/拒跑 |
+|---|---|---|
+| 形状 | `{ok:true, round, pkg, usage, queue_writes, verify, pipeline}` | `{ok:false, round, error:{code,message}, pkg?}` |
+| health | `round:"health"`,`pipeline:{round_id, resumed_from, replayed_of, stages, finding_exits?}` | 拒跑 `code:"budget_monthly"`;运行期失败码闭集同旧(ERROR_CODES) |
+| discover | `round:"discover"`,六步 stages | 同上 |
+
+失败信封差异注:旧 pipeline 轮失败信封含 `pipeline` 字段(composeEnvelope 失败分支),v2 失败信封无——已声明差异面(见 SHADOW-RUNBOOK §已知差异);`error.code` 语义同闭集九词。
+
+- exit 码表(两 launcher 同律):`0`=completed;`1`=failed/refused/parked;`2`=用法错;`3`=运行期异常(launcher 自身崩溃,非轮内失败)。
+- `--to-phase`(health 专属,旧 replay `--to` 镜像):停笔相位完成后终态 completed,信封 stages 止于该相位;默认 CLOSE 全链。
+
+## usage 口径裁定(定案②)
+
+**信封与台账的 usage = 轮累计事件流口径**:轮内全部模型事件(含子任务、缓存命中)累加,轮结束一次性结算。取数机制按入口分面:发现轮 = 会话 UsageDoc 快照求和(`discover-round.mjs roundUsage`);健康轮 = 逐子任务 result 求和(`health-round.mjs` WAIT_MODEL 收口);entry 骨架 = `harness.usage()` 差分。三面共同点 = 轮累计事件流口径(与旧管线同义);pi-durable 的 UsageDoc 对 entry 面仅作 harness 内部观察面。
+
+已知计量边界差(与旧管线对拍时,见 SHADOW-RUNBOOK §已知差异):v2 的 `in` 含 cache_read 且 `total` 再计一次缓存面,故 faux 同轮 v2 数字 ≥ 旧面;**cost 细胞不受影响**(价目表按 token 类分别计价,faux 恒 0,真实轮 cost 独立求和),台账 usage 三计数(in/out/total)在 shadow 对拍中归一,cost 逐字比。
+
+## 台账兼容行(月度准入消费面)
+
+成功轮台账行由 RETRO 步写(与旧管线同点、同形):`| 日期 | 轮次 | model | in=N out=N total=N cost=0.00000000 | pipeline:<round_id> |`。月度准入(`monthSpendOfLedgerText`)与前端 `opsLedger.ts` 解析面零改动——v2 轮天然流出兼容行,`tests/cron-launchers.test.mjs` 与 `tests/shadow-health-parity.test.mjs` 双钉。
+
+## queue.md 兼容面(发现轮;终审补声明)
+
+spec 定案 4 裁「ledger/queue 不再自维护,对下游兼容输出由 T5 保证」:v2 发现轮 ENQUEUE 步零复制 `steps.runStage` 仍写 `queue.md` PROPOSE 行(同点同形,golden 对拍硬断言钉住)——与台账同属对下游兼容输出面,消费方(人工审阅队列)零改动。健康轮不写 queue(旧同律)。
diff --git a/ops/agent-v2/SHADOW-RUNBOOK.md b/ops/agent-v2/SHADOW-RUNBOOK.md
@@ -0,0 +1,55 @@
+# SHADOW-RUNBOOK.md — shadow 期运行手册(票 #229 T5 任务书④)
+
+spec 定案 2 安全轨的运维面:旧管线原地不动,v2 在 `ops/agent-v2/` shadow 跑满一月轮周期,golden + 新旧产出对拍一致才切流。**切流时点由用户裁决,本手册不自动切。**
+
+## 观察面(每轮 cron 后)
+
+```bash
+# 对拍闸门(罐装世界,零网络,~1min):旧 replay vs v2 checkpoint 任务
+node ops/agent-v2/shadow-diff.mjs <YYYY-MM-DD-HHMM-health>   # 退出 0=全 SAME
+# 全量测试套(46 测,含 parity + cron-launchers + E2E + SIGKILL resume + 重试/跨库/exit 码面)
+cd ops/agent-v2 && node --test 'tests/*.test.mjs'
+```
+
+双轨 cron 形态(shadow 期):旧 `pipeline.mjs` cron 照跑(生产真源);v2 侧双轮型——健康轮 `run-health.mjs` 每日一轮、发现轮 `run-discover.mjs` 按旧发现轮节拍(周频/手触),各 `--db` 独库(缺省 `docs/ops/agent-v2.sqlite`),轮 id 独立命名,台账/queue 各自世界——**shadow 期 v2 不写生产台账与 queue、不进生产轮目录**。操作面差异:发现轮 real 面强制 `--model provider/modelId` 显式(旧管线自动 resolve;模型清单见 models.mjs),健康轮缺省自动 resolve 同旧。
+
+## SAME 门槛
+
+- `shadow-diff.mjs` 退出 0(可比工件闭集 + 台账行,归一化窄面见其头注)。
+- 全量测试套 46/46 绿。
+- **golden 全集新旧逐条一致(票 #232,切流硬门槛)**:当前分支覆盖 1 例(discover full faux)+罐装健康截段(shadow-diff);全集(neg/boundary/health_full_faux 等 ~10 例)补齐前不得切流。
+- 连续一个完整月轮周期内:零 infra 信封(v2 侧)、零对拍 DIFF、SIGKILL/断电恢复演练至少一次通过(`tests/resume.test.mjs` + 人工 kill 面板)。
+
+## 已知差异面(声明,非缺陷)
+
+| 差异 | 性质 | 处置 |
+|---|---|---|
+| v2 健康轮无 state.json(真源=SQLite checkpoint+工件;仅发现轮落 state.json 兼容旧面) | 实现细节 | 不入对拍面 |
+| `.v2-claim.json`(v2 健康轮轮目录认领件;跨库撞轮守卫) | v2 专属守卫落件 | 不入对拍面(shadow-diff NEW 侧白名单已列入) |
+| 09-budget.json 旧 CLOSE 也落件(非 v2 专属);真实差异=对拍载具双侧停笔 RETRO 故均不落 | 载具结构 | CLOSE 面落件由 `tests/cron-launchers.test.mjs` 钉(09-budget 存在性断言) |
+| 台账 usage 计数(in/out/total)计量边界差 | 两套 harness 合法差 | 对拍归一;cost 细胞逐字比(ENVELOPE.md §usage) |
+| 对拍载具停笔 RETRO(旧 replay 不入 CLOSE) | 载具结构 | CLOSE 面由 `tests/cron-launchers.test.mjs` 钉(G_CLOSE/09-budget/信封) |
+| PROBE/VERIFY 不入罐装对拍(真探测面,零网络红线) | 载具结构 | 两侧均为零复制 `steps.runStage` 同码路;生产 v2 轮真跑 |
+
+## 影子世界置备(shadow 期轮跑前置)
+
+shadow 期 v2 侧 `DOCS_ROOT` 指影子根(与生产 `docs/ops` 分置),防误指生产写脏。置备=从生产 rsync 一份再清轮次状态:
+
+```bash
+mkdir -p <影子根>/docs && rsync -a docs/ops/ <影子根>/docs/ops/
+rm -rf <影子根>/docs/ops/rounds/ <影子根>/docs/ops/ledger.md <影子根>/docs/ops/queue.md  # 轮次目录/台账/队列清空——v2 侧从零起卷
+# precedents/ rules/ items/ 保留(判例/规则/条目库是轮次输入面,随卷携带)
+```
+
+v2 侧 cron 起轮时显式带 `DOCS_ROOT=<影子根>/docs`(与 `--db` 影子库同理);指向生产根属配置事故——认领件/台账/queue 会写脏生产树。
+
+## 回退
+
+v2 无生产流量 → 回退=停 v2 cron 即可,零数据迁移。SQLite 库/轮目录留在原地供事后审计(证据永不灭失)。
+
+## 切流(用户裁决后)
+
+1. 前置:上表 SAME 门槛全满足,用户明示切流。
+2. 切换 cron:旧 `pipeline.mjs` cron 下线,`run-health.mjs` 接同一轮 id 序列与生产台账世界(`DOCS_ROOT`/`LEDGER_FILE` 指生产)。
+3. 首两周双观察:v2 信封/台账行抽查 + 月度准入读数对拍(月帽口径 ENVELOPE.md)。
+4. 观察期满后旧管线代码退役(单独 PR,先归档后删)。
diff --git a/ops/agent-v2/breaker.mjs b/ops/agent-v2/breaker.mjs
@@ -0,0 +1,19 @@
+// breaker.mjs — v2 熔断面零复制 re-export(票 #227/#228 并批;两票 seam 同源不同面):
+// T3(#227)持写侧——发现轮通道工具 defineTool 化后,通道调用照旧律 record verdict
+// (成功/失败计通道计数,阈值触发熔断;实际接线=tools/discovery-tools.mjs
+// mkDiscoveryHost 适配器 finish 内 breaker.record,host 零复制 import 旧管线);
+// T4(#228)只接 CLOSE 相位快照**读面**(readBreakerKnobs→09-budget.json 观察面,
+// 只读零写,回声律:不造文件),写侧不归它。
+// 零复制判例同 budget.mjs(票 #226):旧文件只依赖 node 内建,直接 re-export,单一真源,
+// 执法/快照语义一字不改(五通道闭集/counted codes/阈值冷却旋钮/原子写/fail-closed
+// reset/events ring ≤20 全在旧文件,升级/对拍都以它为准)。
+// 本 seam re-export 面(两票接口契约,勿另起炉灶):
+//   BREAKER_CHANNELS(五通道闭集:fetch_url/gh_search/rss_parse/web_read/web_search)
+//   BREAKER_COUNTED_CODES(channel_auth/channel_missing/quota)
+//   BREAKER_STATE_VOCAB、readBreakerKnobs(env)(OPS_BREAKER_THRESHOLD/OPS_BREAKER_COOLDOWN_S)
+//   emptyBreakerState、parseBreakerState、verdictFor、grantProbe、applyResult
+//   breakerSnapshot、mkBreaker({file,env,round,ledgerFile,knobs,log})
+//     → { file, knobs, verdict(name), record(name,{ok,code}), snapshot() }
+// 状态文件 = breakerFileOf(ctx)(discovery-host.mjs 单源)= DOCS_ROOT/ops/breaker.json。
+// 旧管线文件属主:ops/agent/ 零改动红线(票 #225/#226/#228)——本文件只 re-export,不 fork。
+export * from "../agent/tools/breaker.mjs";
diff --git a/ops/agent-v2/budget.mjs b/ops/agent-v2/budget.mjs
@@ -0,0 +1,12 @@
+// budget.mjs — v2 预算面零复制 re-export(票 #226;spec 定案 3:budget.mjs **原样**搬进 v2 入口
+// 调用,不改 extension/hook 化;跑稳后另议)。
+// 零复制可行性已核:旧管线 ops/agent/pipeline/budget.mjs 只 import node 内建
+// (fs/path/child_process/util/url/crypto),零旧管线内部耦合 → 直接 re-export,
+// 与 models.mjs(定案 7)同一模式,单一真源;执法语义一字不改(拒跑文案/容差/宁少算口径
+// 全在旧文件,升级/对拍都以它为准)。若将来旧文件长出内部耦合致无法直 import,才允许
+// 整文件拷贝并在文件头注 why+出处,票面须写明(本票未触发该兜底)。
+// 接线(budget-guard.mjs/entry.mjs,定案 3 双点):步前准入(月度 kill switch)+ 环内
+// 检查(四界 attempt 前/结算后/步边界)——不 hook/memo 化,与旧管线 pipeline.mjs 检查点
+// 同构;同参哈希面(dupKey/dupRecord)由此 seam 供 T3/T4 工具宿主注入(同旧 tools.mjs 面)。
+// 旧管线文件属主:ops/agent/ 零改动红线(票 #225/#226)——本文件只 re-export,不 fork。
+export * from "../agent/pipeline/budget.mjs";