@seanyao/roll 3.621.1 → 3.624.2

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 ## Unreleased
 
+## v3.624.2 — 2026-06-24
+
+### 稳定性
+
+- **内置工具补齐 JSON Schema 契约并在调用前校验输入**：所有 builtin tools 现在声明真实 `inputSchema` / `outputSchema`，普通调用和既有委派调用都会在执行前拒绝结构非法的输入并返回 `invalid_input`；`roll tool status` 和机器级 Tools 页同步显示参数契约，便于 agent 内省与排障。(US-TOOL-022) `[tools-layer]`
+
+- **工具依赖现在有真实 readiness gate**：内置工具会按声明的 requirement 检测 Git/GitHub/系统命令等依赖，缺少非可选依赖时不再假装可用，而是拦截或给出可操作提示；`roll doctor` 同步展示这些依赖状态。(US-TOOL-020) `[tools-layer]`
+
+- **Tools 页显示依赖链和可用性**：机器级 Tools 页面为每个 tool 展示 input/output 契约、requirement 链、live readiness 和修复提示，工具边界与环境问题更容易排查。(US-TOOL-021) `[tools-layer]`
+
+- **实时控制台项目切换更可信**：live 模式下项目切换器会按 registry/slug 分发对应项目快照，非当前项目不会误用当前帧；删除或不可达项目不再表现为可切换的真项目。(US-OBS-023) `[delivery-dossier]`
+
+- **可观测 daemon 有正式生命周期命令**：新增 `roll daemon start|stop|status` 管理本机只读观测进程，进程 PID、启动/停止和状态输出都有测试覆盖。(US-OBS-024) `[delivery-dossier]`
+
+- **实时控制台文档补齐**：架构文档和新增 live-console 指南记录了 `roll cycle watch`、三流权威边界、静态导出与未来 live serve 的关系，以及证据按构造产生的方向。(US-OBS-025) `[documentation]`
+
+- **单 cycle 实时窗口可回放 activity 流**：`roll cycle watch` 能围绕一个 cycle 展示标准 activity 事件，把生命周期、TCR、gate、stdout 和工具调用投影到同一条实时观察线。(US-OBS-027) `[delivery-dossier]`
+
+- **pi/kimi 工具调用信号被规范化并持久化**：normalizer 补齐工具调用粒度，cycle 信号写入 `signals.jsonl`，后续 dossier、watch 和证据草稿都能消费同一份活动流。(US-OBS-028) `[delivery-dossier]`
+
+- **TruthSnapshot 覆盖所有控制台面板**：casting、charter、skills、git hooks、live feed 等原本 off-schema 的面板进入结构化 snapshot，页面不再绕开同一真相选择器。(US-OBS-029) `[delivery-dossier]`
+
+- **档案页新增 snapshot 适应度闸**：控制台渲染如果读取 snapshot 之外的数据会被测试拦住，防止未来再出现页面局部真相口径漂移。(US-OBS-030) `[delivery-dossier]`
+
+- **ac-map 证据草稿从 activity 流生成**：loop 会结合 activity signals 与 diff 起草 AC→证据映射、报告和截图引用，默认保守不自动通过，但让缺证据问题更早、更具体地暴露。(US-OBS-031) `[acceptance-evidence]`
+
+- **验收报告软链缺失时不再误判空壳**：无人值守 loop 现在能从真实 run 目录找到验收报告和 ac-map，`attest:gate` 的失败原因也会指向真实路径，不再显示 `<epic>` 占位。(FIX-400) `[acceptance-evidence]`
+
+- **成功交付的 builder 收尾不再误触发登录暂停**：builder exit 0 的交付总结即使提到 login、credential 或鉴权，也不会被误判成 auth block；真正的登录失败和网络失败仍照常归因。(FIX-401) `[loop-engine]`
+
+- **失败 cycle 救援不再冲掉 backlog Done**：`rescue_leaked` 清理泄漏 main 提交时会保留已写入但尚未提交的 `.roll/backlog.md` 状态，避免已合并卡回到 Todo 后被重做。(FIX-402) `[loop-engine]`
+
+- **peer reviewer/scorer 不再漏掉 agent 文件凭据**：reasonix 等 agent 的 profile env 现在由真实 spawn 层统一注入，peer review、Review Score 和 ac-map 补救路径都会拿到 `~/.reasonix/.env` 里的密钥；tmux cycle 窗口也追加透传 agent secret env 名，避免 env-only 配置在无人值守 loop 里丢失。(FIX-403) `[loop-engine]`
+
+- **agent 缺密钥会在 spawn 前明确阻塞**：builder、reviewer、Review Score scorer 和 ac-map 补救在真正启动 agent 前会检查必需 credential env；env 与 agent 文件凭据都缺失时写出点名 agent 和变量名的 `agent:blocked` / ALERT，不再等到 mid-cycle 才掉成模糊 auth block。可用的其它 scorer/reviewer 仍会继续接手。(FIX-404) `[loop-engine]`
+
+- **agent 名册收敛到 6 个一等成员**：`claude`、`kimi`、`codex`、`pi`、`antigravity (agy)`、`reasonix` 成为唯一可列出/探测/派发的 agent roster；`openai`、`deepseek` 继续作为 provider/model alias 保留，不再作为独立 agent 冒出。(US-AGENT-043) `[agents]`
+
+- **agent 名册改为单一真相源派生**：`AGENTS` 现在承载一等 agent 身份、显示名、PATH 探测 bin、默认模型和能力标记；registry、`roll agent list`、doctor/setup 探测和 spawn profile 覆盖都从同一组 6 个身份派生，减少后续名册漂移。(US-AGENT-044) `[agents]`
+
+- **交付真相重建不再丢无 PR 号的 story-only merge**：多个只含 story id、没有 `(#PR)` 的合并提交现在按 commit SHA 保留，不会因 `prNumber=0` 互相覆盖；release gate 可稳定识别这类已合主干的卡。(FIX-924) `[feedback-truth-alignment]`
+
+- **旧 agent 配置开始显式迁移/拒绝**：`openai`、`deepseek` 作为 provider alias 会静默迁移到 `codex`、`pi`；`cursor`、`trae`、`qwen`、`opencode`、`openclaw` 等已删除 agent 在 `roll agent use/set` 和 doctor/setup 面上不再静默回退，而是明确过滤或报错。(US-AGENT-045) `[agents]`
+
+- **文档/站点/技能收口到 6 agent**：docs、guide（中英）、skills 中作为 agent 提及的 `cursor`、`trae`、`opencode`、`openclaw` 及 `openai`/`deepseek`/`qwen` 独立 agent 条目已移除；model/provider 提及不动（`deepseek-v4-pro` 等 model id、`openai` 等 provider alias 保留）。(US-AGENT-046) `[agents]`
+
+- **agent roster 适应度闸与 Rig 类型**：新增结构化 roster gate，CI 测试会校验 core/CLI/spawn/runner-label 等 roster 面都保持六 agent，并用合成 `qwen` 回流证明会红；`Rig` 明确建模 `agent × model`，阻止 `deepseek` 这类 model/provider 被当作 agent 指派。(US-AGENT-047) `[agents]`
+
+- **项目切换器不再显示已删除项目**：档案页项目列表的 reachable 过滤移动到 `collectDossierState` 读侧，`truth.json`、静态首页和机器页都消费同一份已过滤项目行；删除目录后的 stale registry 行不会再渲染成 phantom switcher 项。(US-OBS-019) `[delivery-dossier]`
+
+- **交付真相重建补齐无 PR 号 story-only merge 的跨阶段去重**：`ensureDeliveriesFresh` 两阶段 git log 合并现在按 `pr:<n>` / `sha:<commit>` 去重，避免某个 `prNumber=0` 事实挡掉后续已合主干的 story-only squash commit。(FIX-925) `[feedback-truth-alignment]`
+
+- **release gate 接受无 PR 号交付的 merge SHA 证据**：Done 行现在可用 `merged <sha>` 作为可验证 merge ref；truth-live 在 PR 号缺失时校验 merge commit，避免 story-only squash merge 被迫伪造 PR ref。(FIX-926) `[feedback-truth-alignment]`
+
+- **loop 已合并卡不再回流**：合进 main 的卡会被稳定识别为已交付，不再反复被选回待办。(FIX-399 / FIX-923) `[feedback-truth-alignment]`
+
+- **评审评分池不再太早放弃**：异构 reviewer 都不可用时，会继续尝试同厂可用候选，减少无谓失败。(FIX-911) `[loop-engine]`
+
+- **发版闸不再放过假 Done**：待发布卡会核对真实交付记录，backlog 写错会直接拦住。(FIX-391) `[feedback-truth-alignment]`
+
+- **缺验收件的已完成工作不再沉底**：loop 会开待复评 draft PR，并把卡标成待复评等待补件。(FIX-909) `[loop-engine]`
+
+- **ac-map 补救草稿不再只有引用没有证据文件**：loop 自动生成验收映射草稿时，会同步写出提交、改动文件和测试信号文本，方便复评者逐条确认；草稿状态仍需被确认后才可过 attest 闸。(FIX-912) `[acceptance-evidence]`
+
+- **切换 agent 槽位后档案页自动刷新**：`roll agent use` / `roll agent set` 写入槽位后会 best-effort 重建静态档案聚合，Casting/Agents 视图不用等下一次手动 `roll index` 才更新；刷新失败只 WARN，不回滚已写槽位。(FIX-378) `[delivery-dossier]`
+
+## v3.624.1 — 2026-06-24
+
+### 新功能
+
+- **实时控制台底座上线**：档案页可以从静态快照走向实时刷新。(US-OBS-020 / US-OBS-021) `[delivery-dossier]`
+
+### 修复
+
+- **取分阶段失败归因细分 + unparseable 一次再问救回**：之前取分链路的 `runScorePairing` 把所有 reviewer 失败一律当 null 吞掉——auth 超时、网络不通、进程崩溃、回复了但格式跑偏——四种原因全被静默丢弃，池子耗尽后闸判「缺分数」→ cycle 失败。现在每种失败都发出 `pair:score-failure` 可观测事件（unparseable/timeout/auth-block/exit-error），不再沉默。最冤的「reviewer 答了但格式跑偏」加了一次严格格式重申再问（`你上次回复缺/错了 SCORE/VERDICT/RATIONALE 行，请严格只回这三行`），答了白答的 pi 之类的 reviewer 现在有机会被救回。parse 绝不放松——只接受严格三行协议；闸逻辑逐行不动，救援分须自然满足全部独立性过滤。(FIX-910) `[loop-engine]`
+
+- **loop 交付真相不再漏认已合并卡**：手动合并和外部合并也会被识别，已合卡不再被反复重选。(FIX-389a / FIX-390 / FIX-903 / FIX-904 / FIX-905 / FIX-906) `[feedback-truth-alignment]`
+
+- **loop 挂死或缺验收件时不再丢工作**：周期空挂会硬超时，CI 已绿但缺报告的工作会进入待复评，不再触发假熔断。(FIX-907 / FIX-908 / FIX-913) `[loop-engine]`
+
+- **loop 评审和在飞对账更稳**：评审会带仓库上下文和反馈重试，GitHub 探测失败时也不再误重选在飞卡。(FIX-386 / FIX-387 / FIX-397) `[loop-engine]`
+
+- **`roll loop watch` 状态行不再掉成 unknown**：长时间窗口也能显示真实故事和 agent。(FIX-382) `[loop-engine]`
+
+- **builder 进程 cwd/PWD 钉到 cycle worktree,不再漏写共享 checkout**：pi/kimi 等经 PTY 包装的 agent 现在同时用真实 `cwd` 和 `PWD` 指向 cycle worktree,并清理继承的 `GIT_*` 状态,避免 CLI 依据父进程 `PWD` 写进主 checkout；不再注入 `GIT_DIR`/`GIT_WORK_TREE`,避免污染共享 `.git/config` 的 `core.worktree`。(FIX-914) `[loop-engine]`
+
+- **chromium/playwright 依赖加固——钉版本、init 预装、离线优雅提示**：之前三处用 `playwright@latest`（未钉版本），`latest` 可能拉到新版导致浏览器版本漂移、偶发截图失败；chromium 在第一次需要截图的 cycle 当场下载（~100-200MB），网抖则该 cycle 截图失败。现在 `screenshot.ts` 和 `browser.ts` 统一使用钉定版本 `playwright@1.52.0`，缓存命中一致不重装；`roll init` 和 loop 首启时静默预装 chromium（已缓存秒返、失败不阻塞）；离线/网络错误时 skip 消息区分「headless Chromium unavailable (offline or network error)」；Tools 页 browser tool 可用性联动 chromium 安装状态。(FIX-394) `[acceptance-evidence]`
+
+- **终端交付命令在 headless loop 不再假死、命令 stdout 升格为可过闸证据**：之前带 `deliverable_cmd`（终端命令）的卡在无人值守 launchd loop 中因无 GUI session 无法截图，attest 门判败堵死整条 loop。现在终端 lane 镜像 web lane 的 headless 回退——命令执行成功但无 GUI 时自动把 stdout 文本升格为 `taken:true` 终端证据，attest 门可正常通过，不再依赖 epic 级 `screenshot_exempt` 豁免。修复也拓宽了回退条件：原先只匹配 "no GUI session"，现覆盖所有 headless 跳过（含 "not macOS" 等），条件是命令已成功运行。(FIX-392) `[acceptance-evidence]`
+
+### 稳定性
+
+- **无人值守 loop 上一轮没跑完时不再并发起新轮，不会堆积拖慢机器**：调度脚本生成器加了「在飞守卫」——上一个 cycle 还在跑时，新的 launchd tick 自动让路而不是硬起一轮，根治了「cycle 超过调度间隔→并发堆积→CPU thrash→更慢→更多并发」的死亡螺旋。生成器同时默认设好 headless 截图环境，无人值守 loop 不再弹 macOS 屏幕录制授权框。(FIX-393) `[loop-engine]`
+
 ## v3.621.1 — 2026-06-21
 
 ### 修复

package/README.md

@@ -51,7 +51,9 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 | `roll backlog [sync\|block\|defer\|lint\|…]` | View, manage, and sync (from GitHub Issues) pending tasks |
 | `roll loop alert [list\|ack\|resolve\|log]` | View / clear loop alerts |
 | `roll status` | Verdict-first truth summary read from the ONE snapshot — LOOP · CYCLE · RELEASE · STORY, with the STORY line's attest-coverage % (`done ≡ merged ∧ attested`) — then convention/AI-client sync health |
+| `roll pulse [--json]` | Today's delivery pulse: cycles in window, merged count, attested count, plus an ASCII sparkline from the story spectrum. Bilingual EN/中. `--json` for machine-readable output |
 | `roll doctor [skills]` | Environment + install diagnosis (agents, skill catalog, plists, launchd lanes) |
+| `roll daemon <start\|stop\|status>` | Opt-in read-only observability daemon for the live console; defaults to `127.0.0.1:7077`, records `.roll/loop/daemon.pid`, and is never auto-started by the loop |
 | `roll tune [reset]` | Suggest-only self-tuning from loop trends — read-only, never auto-applies |
 | **Cards & evidence** | |
 | `roll idea "<one-sentence description>"` | Capture a card: auto-classify, number, lint, infer epic, mint the full story folder — the one user entry for adding cards |
@@ -60,6 +62,7 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 | `roll init` | Set up Roll in this project (agent-driven onboarding for legacy code) |
 | `roll offboard` | Remove Roll from this project |
 | `roll test [--where] [--reset]` | Run the test suite (routes through the isolation adapter; unknown types fail loud) |
+| `roll daemon <start\|stop\|status>` | Manage the read-only observability daemon (OPT-IN only; never auto-started) |
 | `roll ci [--wait]` | Show or wait for current commit's CI status |
 | `roll release [--dry-run]` | The ONE release flow: bump → changelog fold → package gate → commit-push → consistency gate → PR → auto-merge → tag push (gate runs before merge; drives the merge via GitHub auto-merge) |
 | `roll showcase [--card <ID>]` | The golden-path standard E2E in an isolated sandbox: reset the card, cast a heterogeneous real-agent trio (kimi/claude/pi), deliver via the loop, capture CLI+web screenshots, assemble the evidence chain, emit a pass/fail verdict |
@@ -77,7 +80,7 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 | `roll doctor skills [--strict] [--json]` | Strict skills audit (skills · violations · hub lines + the four invocation groups — the SAME yardstick the web Skills page reads) |
 | `roll setup skills` | Sync the `guide/skills.md` skill catalog |
 | `roll doc [--lang en\|zh] [name]` | View the Charter / language guide markdown in the terminal (`--lang` falls back to the configured language) |
-| `roll tool status` | Show registered tools and their effective `.roll/policy.yaml` state |
+| `roll tool status` | Show registered tools, effective `.roll/policy.yaml` state, input contracts, and requirement readiness |
 | `roll prices [refresh]` | Model price table (cost accounting source) |
 | `roll setup [skills\|-f]` | First-time install, skill catalog generation, or re-sync conventions to all AI clients |
 | `roll update` | Upgrade to latest + re-sync |