@seanyao/roll 3.618.3 → 3.620.1

package/CHANGELOG.md

@@ -2,12 +2,88 @@
 
 ## Unreleased
 
+## v3.620.1 — 2026-06-20
+
+### 修复
+
+- **发版页和档案页都改成只看「下一版」的真相**：档案页的发版栏现在自动显示真实的最新版本号、每次发版同步刷新，不再卡在旧版本；发布页的「待发布」也只列上一个发布版本之后新合入的卡（就是下次要带的内容），而不是几百张全量未完成卡；配套的一致性检查面板改成自解释，一行告诉你能不能发版、每项查什么、怎么修。(FIX-368 / FIX-372) `[release-management]`
+
+- **文件夹形式的卡片跑验收报告不再被「别的卡号」抢走清单**：就算卡里的小标题里提到了其他卡号，验收报告也只认这张卡自己的全部验收项，正常完整显示。(FIX-374) `[acceptance-evidence]`
+
+- **发版前自动拦住「漏写发版说明 / 文档对不上」**：`roll release` 的一致性闸新增三道确定性检查——① 自上一个发布以来合入的每张卡，必须有 ✅ Done 行并带合并号（这一维原来形同虚设，绿了也没在验）；② 每张卡要么在 CHANGELOG 里有条目、要么在卡里显式写明「不入发版说明」的理由，否则拦住发版（防止用户可见的改动无声上线）；③ 站点不能再链向不存在的指南页。判断更重的「文档是否还和实现一致」审计，同步沉淀进 `$roll-doc-audit` 技能（先审一致性、再补文档），闸守底线、技能查细节。(FIX-375) `[release-management]`
+
+### 新功能
+
+- **loop 观察窗看长周期更省心**：默认的 `roll loop watch` 窗口现在直接显示当前阶段、静默时长、TCR 次数和最近一次有意义的进展，长周期一眼就能看懂；新增 `--events` 和 `--raw-events` 两档，可直接跟踪事件流，不用再自己 tail 原始日志；`roll loop go` 和定时 loop 的 tmux 监视窗也和手动观察走同一个统一入口；TCR 提交按当前周期的观测时间排序，不再把开工前的旧提交错当成本周期的新进展；帮助文字与中英文档都说明了默认、紧凑事件、原始事件三档查看层级以及只读与 Ctrl-C 退出。(US-LOOP-043 / US-LOOP-045 / US-LOOP-046 / US-LOOP-047 / US-LOOP-048) `[loop-engine]`
+
+- **主动询问外部工具权限，并在档案页标清可用性**：roll 现在会在 `roll init` 或启动时主动问你要不要授予截图权限、安装 Chromium 这类外部工具依赖，拒绝会说明具体影响，并在 Agents 档案页上逐项显示每个工具能不能用。(US-EVID-018) `[acceptance-evidence]`
+
+### 变更
+
+- **下架未成熟的"生产巡检"和"每日简报"两块能力面**：`$roll-sentinel`（随机抽样巡检）和 `$roll-brief` / `roll brief`（owner 每日简报）不再作为 Roll 的核心能力宣传——它们成熟度不够，且和外部控制台 / Delivery Dossier / `roll status` / 真相信号这条已经成熟的可观测链路重复。现在第三个闭环（Loop C）讲的是"可观测与维护"：用 `roll status`、`roll dossier`、`$roll-debug`/`$roll-doc-audit`/`$roll-doctor`、`$roll-.dream` 代码健康扫描和真相信号来发现问题、把修正写回 backlog。代码、技能目录、命令面、站点与中英文档已同步；新增一道回归闸，防止这两块能力面悄悄回流到活跃文档/站点/帮助/技能目录里（历史归档、迁移文档、旧版幻灯片不受影响）。(FIX-356 / 356a-d) `[skill-ecosystem]`
+
+- **`$roll-doc` 更名为 `$roll-doc-audit` 并同步用户表面**：站点 Skills、技能图谱、`roll-doc-skill.html` 公共旧链接、guide/README 风格说明和 CLI skills panel 都改成"文档/产品一致性审计"心智；旧 diagram URL 保留跳转到 `roll-doc-audit-skill.html`，避免已分享链接断掉。`[skill-ecosystem]`
+
+- **loop 能在卡做大时自己再拆**：交付前的自检判定"太大"、或独立评审判定"范围过大"时，loop 会调 `roll loop self-downgrade` 把原卡挂起（🚫 Hold）、按缺口拆出子卡并接着干，子卡只继承原卡的入边依赖、不指向被挂起的伞卡（避免死锁）；同一条拆分链最多自动拆两次，第三次拒绝并告警等人处理。评审触发的再拆还要先过"异构共识"——拉 2+ 不同厂商的 agent 复核拆分方案，全同意才落，有异议就暂停告警（人在环上，不在环里）。(US-AGENT-042 / US-AGENT-041) `[autonomous-evolution]`
+
+- **暖会话复用收窄到同一卡重试**：默认仍关闭；即使开启，也只会在同一张卡重试时恢复先前会话，跨卡继续冷启动，避免把上一张卡的旧上下文带偏当前交付。(FIX-369 / FIX-370 / FIX-371) `[loop-engine]`
+
+- **Dream 代码结构扫描改走确定性 TS/AST pre-scan**：`roll dream run-once` 现在会在 agent 前生成 `.roll/dream/structure-scan.json`，用 TypeScript 引用图、AST fingerprint 和 AST env 解析给死代码、不可达分支、重复结构、单实现抽象和 env 文档缺口提供机器证据；agent 消费该 artifact，不再靠 grep 式临场判断兜底，文档类扫描保持原流程。(US-LOOP-080) `[loop-engine]`
+
+- **web 控制台新增机器级 Tools 页**：一处看全所有内置工具（bash / browser / git / github / network / fs / mcp）、各自的能力与默认护栏（超时 / 沙箱 / 重试 / 每周期上限），和 Agents、Skills 同级，挂在 `MACHINE › …` 面包屑上。中英文 Overview 指南与 Tools & policy 指南都已指向这个新页面。(US-TOOL-016 / US-TOOL-017 / US-TOOL-018) `[tools-layer]`
+
+- **web 控制台改版：新的 Now 默认页 + 实时 loop 观察窗**：控制台打开后默认进「Now」运营视图（取代旧的 Overview），项目标签重排成 Now·Backlog·Loop·Release·Casting·Charter；Now 仪表盘重做后能正确反映当前是否有周期在跑（没有就明说「当前没有周期在跑」，不再把已完成的旧卡误标为进行中），并实时显示 loop 正在跑哪张卡、流到哪一步，On-Deck 与 Needs-you 列表的卡可直接点进各自卡页、Needs-you 显示真实总数并按失败/挂起分色，Live Stream 与 Loop Heartbeat 区域更大更易读；#loop 观察窗能实时看到每个周期的七段进度带、段内活动与闸门事件，报告与账本都按同一份活动流展示，处处口径一致。(US-DOSSIER-043 / US-DOSSIER-044 / FIX-373 / US-LOOP-078) `[delivery-dossier]`
+
+## v3.619.1 — 2026-06-19
+
+### 修复
+
+- **`roll release` 可反复执行并自愈中断**：release 分支或 PR 已存在时不再失败，而是复用已有分支/PR 并跳过已完成步骤；auto-merge 已开启或 PR 已合并时幂等跳过；配合已有的 GraphQL EOF 重试 + REST 回退，一次网络抖动不再毁掉发版。(FIX-330) `[release]`
+
+- **多智能体评审更扛抖动**：`roll peer` 和 `roll loop go --review auto` 现在会按排序依次尝试多个异构 reviewer，单个 agent 超时或崩溃时自动换下一个，不再因为一次失败就误判为无可用 reviewer 或终止终审。(FIX-336) `[pairing]`
+
+- **审计并清理 v2→v3 "假 Done" 死 bash 引用**:系统扫描技能合约与文档中已退役的 `source "$(command -v roll)"` 和 `_loop_*` bash 调用,确认 US-AGENT-008/009 的 self-downgrade 能力在 v3 缺失并退回状态;技能审计新增 `dead-bash-ref` 回归闸,`roll skills audit --strict` 不再允许新的死 bash 引用进入 skill 合约。(FIX-364) `[feedback-truth-alignment]`
+
+### 新功能
+
+- **工具层类型契约落进 spec**:新增 ToolId/ToolDeclaration/ToolInvocation/ToolResult/ToolPolicy/ToolCost 等共享类型,并让 CycleCost 可挂载 toolCosts,为后续 registry、policy 和 adapter 层提供同一套类型词汇。(US-TOOL-001) `[tools-layer]`
+
+- **工具注册表核心落地**:新增 core/tools ToolRegistry 与 Tool 接口,统一 register/invoke/shutdown/snapshotCosts 路径,把 policy、预算、事件、retry 和成本累计都收进可测试的核心层。(US-TOOL-002) `[tools-layer]`
+
+- **工具策略从 policy.yaml 解析**:新增 ToolPolicyEngine,从 `.roll/policy.yaml` 的 `tools:` section 解析 enabled、timeout、retry、预算和 sandbox 字段,未知字段只告警不拒绝。(US-TOOL-003) `[tools-layer]`
+
+- **Bash 工具适配器落地**:新增 infra BashTool,通过 argv-only exec seam 执行命令,支持 cwd allowlist、timeout、输出截断、advisory blockedCommands、secret redaction 和 `.roll/tool-dumps/` dump。(US-TOOL-004) `[tools-layer]`
+
+- **Browser 工具适配器落地**:新增 infra BrowserTool,同一 adapter family 提供 `browser.screenshot`、`browser.console`、`browser.dom-query`,支持 allowedOrigins/headlessOnly sandbox、headless/GUI lane、honest skip 和共享队列。(US-TOOL-005) `[tools-layer]`
+
+- **Git 工具适配器落地**:新增 infra GitTool,同一 adapter family 提供 `git.commit`、`git.status`、`git.push`、`git.merge`,复用现有 git wrapper 保持命令语义不变,并让 `git.status` 支持成功静默事件。(US-TOOL-006) `[tools-layer]`
+
+- **GitHub 工具适配器落地**:新增 infra GitHubTool,同一 adapter family 提供 `github.pr`、`github.ci`,复用现有 gh CLI wrapper 处理 PR 创建/状态/合并与 CI 状态/重跑,保持 GitHub 调用语义不变。(US-TOOL-007) `[tools-layer]`
+
+- **Filesystem 工具适配器落地**:新增 infra FsTool,同一 adapter family 提供 `filesystem.stat`、`filesystem.read`、`filesystem.write`,按 allowedPaths 管控路径,支持相对路径按项目根解析、读截断和写入前 redaction。(US-TOOL-008) `[tools-layer]`
+
+- **Network 工具适配器落地**:新增 infra NetworkTool,提供 `network.fetch`,支持 timeout、policy retry、allowedOrigins、network blocked、redirect follow 和 HTTP proxy 环境变量,让 HTTP 探测走统一工具治理路径。(US-TOOL-009) `[tools-layer]`
+
+- **MCP 工具适配器落地**:新增 infra McpTool,提供 `mcp.call`,支持 `.roll/mcp-servers.json` 与 `policy.yaml tools.mcp.servers` 配置、lazy connection reuse、dispose 断开、policy disabled 拒绝和 server unavailable 诚实错误分类。(US-TOOL-010) `[tools-layer]`
+
+- **工具调用事件与成本观测收紧**:ToolRegistry 的 `tool:result` 事件改为只发布脱敏结果事实,失败结果即使 `emitsEvents:false` 也会留痕;CLI 无 cycleId 的工具调用不计入 per-cycle ToolCost,cycle:end 可携带工具成本快照。(US-TOOL-011) `[tools-layer]`
+
+- **CLI 展示工具调用时间线与成本摘要**:`roll loop status`、`roll cycle` 和 attest report 现在会从事件流/CycleCost 展示工具调用摘要、失败 errorCode 与工具成本 breakdown,并保留原生币种显示,避免把人民币成本误标成美元。(US-TOOL-012) `[tools-layer]`
+
+- **网页 Loop 账本展示工具调用轨迹**:Truth Console 的 Loop cycle 行现在在成本列旁露出工具摘要,展开后展示每次工具调用、失败 errorCode 和按原生币种标注的工具成本,截图证据可直接证明 USD 与 CNY/RMB 不会混标。(US-TOOL-013) `[tools-layer]`
+
+- **既有 infra 调用迁移到工具治理路径**:process exec、git/gh wrapper 和默认 web screenshot 现在会经 infra tool delegation seam 执行,保留原命令语义的同时向 events.ndjson 追加脱敏 tool invoke/result 事件。(US-TOOL-014) `[tools-layer]`
+
+- **工具层文档和状态命令落地**:新增英文/中文 Tools guide 与 `roll tool status`,用户可以查看注册工具、有效 policy 状态、CLI/Dashboard 工具用量入口和原生币种成本边界。(US-TOOL-015) `[tools-layer]`
+
 ## v3.618.3 — 2026-06-18
 
 ### 修复
 
 - **showcase 在全局安装下 agent probe 崩溃**:`rollBin()` 定位到全局包的 `conventions/` 而找不到本地 `roll.js`，子进程直接崩掉判所有 agent 不可用；现加回退：本地不存在时走 PATH 的 `roll`。`[showcase]`
 
+- **退役未成熟的生产巡检与 owner 简报**:从活跃 skill 目录、skill 面板、站点 skill 地图和核心 patrol 代码中移除 `roll-sentinel` 和 `roll-brief`，停止将其作为当前核心能力呈现；通用 sentinel 概念(截屏/PAUSE/默认值)原样保留。(FIX-356b) `[skills]`
+
 ## v3.618.2 — 2026-06-18
 
 ### 改进

package/README.md

@@ -45,7 +45,7 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 |---------|-------------|
 | **Autonomy · daily use** | |
 | `roll loop <on\|off\|now\|status\|watch\|runs\|log\|story\|events\|eval\|signals\|alert\|fmt\|pr-inbox\|mute\|unmute\|pause\|resume\|reset\|gc>` | Manage the autonomous BACKLOG executor (incl. per-cycle result scoring) |
-| `roll loop watch [-n <lines>] [--verbose\|--raw] [--attach]` | Read-only, concise, real-time view of THIS project's loop — auto-tails `.roll/loop/live.log` through the renderer (cycle / story / results / ALERT / cost / heartbeat). It never writes to or signals a running cycle; Ctrl-C ends the view, not the loop. `--attach` joins the loop's tmux observe window read-only |
+| `roll loop watch [-n <lines>] [--events\|--raw-events] [--verbose\|--raw] [--attach]` | Read-only live observation. Use default first for owner-facing status (phase / quiet / TCR / last signal), `--events` for compact event debugging, and `--raw-events` only for audit/debug JSON. Ctrl-C ends the view, not the loop; `--attach` joins the tmux observe window read-only |
 | `roll loop go [--epic <e>\|--cards <ids>] [--budget <usd>] [--for <duration>] [--review <auto\|hetero\|self\|off>]` | Run goal mode manually until the scoped work completes, pauses, or hits a budget/usage/timebox guardrail; it can run while the scheduler is off, and a paused loop should be resumed first; final review defaults to `auto` |
 | `roll loop goal` | Show persisted goal scope, review mode, usage, limits, safety gate, and last decision |
 | `roll backlog [sync\|block\|defer\|lint\|…]` | View, manage, and sync (from GitHub Issues) pending tasks |
@@ -63,9 +63,11 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 | `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 |
+| `roll dream run-once` | Run the nightly Dream scan now; code-structure findings are seeded by a deterministic TS/AST pre-scan artifact before the agent writes the report |
 | `roll pair [init\|status\|score]` | Cross-agent pairing: heterogeneous peer re-checks and scores deliveries |
 | `roll cycles [--since 1d\|3d\|7d\|all]` | The cycle ledger — one line per cycle, failures never swallowed |
 | `roll cycle <id>` | One cycle's full trace tape (cycle→story→build→peer→ci→pr→end) |
+| web `#loop` cycle rows | The same ledger expands to the shared ActivitySignal stream and writes `.roll/loop/cycle-<id>.signals.jsonl` for replay |
 | `roll peer [--reviewer <agent>] (--prompt <text>\|--file <path>)` | One-shot structured external-provider review; records `.roll/peer/runs.jsonl` |
 | **Config & machine** | |
 | `roll ls [--json] [--stale-days <n>]` | List the cross-project registry (`~/.roll/projects.json`): name · tag · verdict · path; missing/stale rows flagged, never dropped |
@@ -75,6 +77,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 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 |
@@ -114,7 +117,7 @@ Published as a single npm package `@seanyao/roll`: `dist/` (the CLI bundled to o
 | | |
 |---|---|
 | **Start here** | [Getting started](guide/en/getting-started.md) · [Overview & architecture](guide/en/overview.md) · [Engineering methodology](guide/en/methodology.md) |
-| **Daily driving** | [The loop (autonomous executor)](guide/en/loop.md) · [Configuration](guide/en/configuration.md) · [Pricing & cost](guide/en/pricing.md) · [FAQ](guide/en/faq.md) |
+| **Daily driving** | [The loop (autonomous executor)](guide/en/loop.md) · [Tools & policy](guide/en/tools.md) · [Configuration](guide/en/configuration.md) · [Pricing & cost](guide/en/pricing.md) · [FAQ](guide/en/faq.md) |
 | **Quality machinery** | [Acceptance evidence (`roll attest`)](guide/en/acceptance-evidence.md) · [Evidence lifecycle](guide/en/acceptance-evidence.md#lifecycle-in-three-stages) · [Consistency & release gate](guide/en/consistency.md) · [Cross-agent pairing](guide/en/pairing.md) · [Peer review](guide/en/peer.md) · [Test isolation](guide/en/test-isolation.md) |
 | **Under the hood** | [Architecture: layers · domain · invariants](docs/architecture.md) · [Verification system](docs/verification.md) · [Manifesto](docs/manifesto.md) |