@seanyao/roll 4.717.2 → 4.719.1

package/docs/architecture.md

@@ -361,6 +361,18 @@ Backlog-clearing 模式下，Supervisor 的默认 scope 是所有 live 且非 Ho
 
 这套 runbook 是 `roll supervisor next/why/live` 的产品标准：CLI 输出应能解释当前卡、当前 cast、为什么继续、为什么停止，以及下一步需要谁做什么。
 
+#### 分支/worktree canary 与安全恢复 / Branch-worktree canary & safe recovery (FIX-1273)
+
+The branch/worktree leak canary (US-LOOP-096) counts every ephemeral branch + every dir under `.roll/loop/worktrees` and PAUSEs the loop over threshold (`ROLL_BRANCH_CANARY_MAX`, default 8). It counts inactive worktrees deliberately preserved for unpublished commits or dirty recovery too — so historical pressure can pause the loop even when nothing is genuinely leaking.
+
+- 触发即枚举 / Auditable trip：canary 触发时,PAUSE marker、ALERT 与 `branch_canary_tripped` 事件枚举出被计数的**每一条** ephemeral branch 与 loop worktree,并附上各 worktree 的审计处置 (disposition),而不是一个裸数字。
+- 唯一权威是审计 / Audit is the sole authority：`roll worktree cleanup` 从 `roll worktree audit` 派生动作,**只**移除审计判定为 inactive + merged + clean 的 `disposable_candidate`。它绝不因为 worktree "旧" 或 "被计数" 就删除,也绝不把 canary 计数翻译成批量删除。
+- 先演练后执行 / Dry-run first：`roll worktree cleanup --dry-run`(默认)打印被计数的 refs/dirs、审计处置、以及把总数拉回阈值以下所需的**最小**候选集;它绝不改动 git 状态。
+- 应用即复核 / Apply revalidates：`roll worktree cleanup --apply` 在**每一次**移除前立刻重跑审计,要求 path + head + inactive + no-tracked-dirt + merged-ancestry + `disposable_candidate` 全部一致,才通过 git 移除该 worktree 并 prune 注册、发出 `worktree_cleanup_applied` 事件。changed head / 新脏 / 缺失 path / 并发激活一律 fail-closed(发 `worktree_cleanup_refused`),绝不改删其它 preserved worktree 作替补。
+- 恢复要显式 / Explicit resume：成功清理后,unpublished / dirty / active / external worktree 依旧保留在 canary 账上;操作者确认压力已清除后,显式执行 `roll loop resume` 让 loop 重新派卡。
+
+Preserved（unpublished / dirty / active / external）worktree 永远不会被 cleanup 移除;它们仍计入 canary,是 Truth preflight 里 “preserved worktree” 这一停摆信号的一部分。
+
 #### Retired terms and breaking boundary
 
 `Prime Agent` is a retired active term. `Planner` is a retired active term. `planned` is a retired execution profile, and `planner-contract.md` is a retired active artifact. Historical archives may preserve those words as immutable evidence, but active runtime docs, help, UI, tests, and skills use Supervisor / Designer / Builder / Evaluator.

package/guide/en/acceptance-evidence.md

@@ -268,6 +268,33 @@ at startup:
   content (chat, email, other projects). If the target window is not found, Roll
   Capture.app returns a documented fallback with the reason recorded in the
   response and evidence ledger — no silent expansion of capture scope.
+
+### Capture v2 gateway — per-source readiness (US-PHYSICAL-010..013)
+
+Roll's capture host speaks two protocols. `roll capture status` reports readiness
+**per source**, so it never claims a blanket "v2 ready" when a lane is still v1:
+
+- **rendered (`playwright-rendered`)** — served **in-process** by Roll via headless
+  Playwright: a declared web surface is rendered to a PNG and turned into a
+  `roll.capture.v2` receipt with a `sha256` digest. It advertises v2 **only when
+  Chromium is installed**; otherwise status shows it `unavailable` with an
+  actionable reason (never a fabricated capability).
+- **physical (`roll-capture-window`)** — the native `Roll Capture.app`, honestly
+  **v1** today (the file-drop protocol). Physical v2 is a separate follow-on
+  (US-PHYSICAL-014); status labels it `v1` rather than over-claiming v2.
+
+Wiring it up:
+
+- `roll capture refresh` probes the real machine and writes an honest
+  `capabilities.json` (rendered → v2 when the renderer is present; physical → v1).
+- `roll capture status` then shows `v2 playwright-rendered — ready` alongside
+  `v2 roll-capture-window — unavailable` (legacy), instead of one blanket line.
+- `roll capture migrate` enables `best_effort` only when the rendered v2 lane is
+  genuinely served; otherwise it retains the current policy with an explicit
+  reason. With `best_effort` on, a declared surface is dispatched through the
+  in-process rendered lane, producing a taken v2 receipt on the CaptureSet; a
+  login / foreign-redirect / disallowed target is recorded as `skipped`, never a
+  fabricated taken.
 - `Playwright Chromium` — optional headless web capture for `roll attest` and
   archive screenshots. Install with `npx playwright install chromium`.
 
@@ -283,6 +310,144 @@ The machine Agents page (`.roll/features/agents.html`) includes the same tool
 status block so a reviewer can see whether evidence capture depends on
 machine setup rather than story code.
 
+## Best-effort capture, evidence health, and repair
+
+Visual evidence is a **best-effort** delivery capability: every declared visual
+surface is attempted through every eligible capture lane, and a capture-service
+outage is never misread as a product regression. Delivery correctness and
+visual-evidence health are kept as **separate facts**.
+
+### Source labels
+
+Every accepted image carries the lane that produced it:
+
+- **Roll Capture · physical** — a physical screenshot of your real terminal or
+  app window, taken by Roll Capture.app. It proves what was on screen; it never
+  claims a URL it cannot observe.
+- **Playwright · rendered** — a rendered receipt whose `finalUrl` equals the
+  declared surface after approved redirect normalization. A target-bound rendered
+  receipt is eligible visual evidence — distinct from a diagnostic screenshot.
+
+A target-bound rendered receipt can satisfy a visual AC on its own. A physical
+Roll Capture image is one eligible source for a visual AC; a target-bound
+rendered receipt is another, equally valid one.
+
+### The four visual states
+
+| State | Meaning | Gate action |
+|-------|---------|-------------|
+| `verified` | at least one valid, target-bound image (physical or rendered) | publish normally |
+| `degraded-infrastructure` | every configured lane was attempted; only host/provider/tooling failures occurred | publish, visibly marked degraded; **do not rebuild** — repairable by an evidence-only rerun |
+| `invalid-target` | a lane reached login, an unapproved redirect, the wrong target, a corrupt image, or a forged receipt | block as an evidence failure; repair the target/configuration |
+| `absent-contract` | no declared surface, no planned attempt, or the planner was bypassed | block as a design/execution failure |
+
+`degraded-infrastructure` is intentionally not a green screenshot claim. It
+separates code delivery from a broken evidence machine so the same completed
+story is never repeatedly rebuilt.
+
+### Privacy boundaries
+
+- Receipts never include credentials, cookies, DOM dumps, or network bodies.
+- Window capture is window-scoped by default; a missing target produces a typed
+  failure, never a silent expansion to full-screen.
+- `ROLL_NO_SCREENCAP=1` bans only the Runner's direct native `screencapture` /
+  AppleScript path. It does not disable the Roll Capture gateway request or the
+  Playwright rendered attempt.
+
+### Controlled local-window capture
+
+When a physical web receipt needs a browser window but no safe window exists,
+use the restricted local lane:
+
+```bash
+roll capture local-window --story FIX-005 --url http://127.0.0.1:4173/team
+```
+
+For a synthetic local UI that needs a visible state change before capture, add a
+restricted `--prepare` JSON list:
+
+```bash
+roll capture local-window --story FIX-1435 --url http://127.0.0.1:4173/ \
+  --prepare '[{"kind":"click","selector":"#synthetic-checkbox"},{"kind":"wait","ms":300},{"kind":"scroll","selector":"#synthetic-result"}]'
+```
+
+`--prepare` permits only bounded `click`, `fill`, `wait`, and `scroll` actions.
+Unknown fields or action kinds, arbitrary JavaScript, navigation, and excessive
+lists or waits are rejected before Chrome launches. A temporary Playwright
+connection attaches only to the disposable loopback Chrome, resolves exactly
+the already-discovered page and its one exact original target frame, and verifies
+that frame remains at that exact URL after every action. The connection then
+detaches without closing the capture window. `click` resolves a visible element
+through the browser UI path, so controlled React inputs receive their normal
+event path. A prepare failure sends no capture request. `fill` accepts only
+non-password `input` and `textarea` controls; contenteditable targets are
+rejected.
+
+This is not general browser automation: it cannot use an owner profile or open
+remote URLs. The prepare API exposes no cookie or storage read/write/import/
+export operation and does not inject credentials; ordinary local application UI
+interactions still behave normally. `fill` rejects password controls and must
+be used only for non-sensitive synthetic local values; never place credentials
+or personal data in a command line.
+
+It accepts only loopback HTTP(S) pages. Roll starts a disposable Chrome profile
+and a nonce-titled local wrapper window, asks Roll Capture.app for that exact
+window title, then closes the wrapper, Chrome, and profile. It never opens a
+remote URL, connects to an owner Chrome profile, or falls back to a full-screen
+capture. The JSON result includes the physical receipt and exact selector.
+
+The real local controlled-input regression is opt-in because it opens a visible
+disposable Chrome window; it serves only a temporary synthetic React page and
+fails loud when the desktop Chrome host is unavailable:
+
+```bash
+ROLL_BROWSER_LIVE=1 pnpm test:controlled-capture-live
+```
+
+### Evidence-only repair
+
+A `degraded-infrastructure` delivery can be repaired without reopening the build:
+
+```bash
+roll capture repair <story-id>
+```
+
+This re-runs **only** the capture lanes and re-resolves evidence health. It never
+touches the TCR / build cycle and never reopens the completed delivery. It
+refuses (and still does not rebuild) for a failed delivery or any non-degraded
+state. A `verified` result publishes the newly captured image; a still-degraded
+result stays publishable and marked degraded.
+
+### Enabling best-effort capture
+
+The default for new visual stories is `best_effort`. Existing projects keep their
+recorded policy until an explicit, capability-aware, reversible migration enables
+it:
+
+```bash
+roll capture migrate            # enable best_effort ONLY when the v2 gateway AND renderer are ready
+roll capture migrate --dry-run  # preview without writing
+roll capture migrate --revert   # restore the previously recorded policy
+```
+
+The migration is idempotent. It enables `best_effort` only when **both** the v2
+Roll Capture gateway and the browser renderer are ready; otherwise it retains the
+existing policy with an explicit reason (`provider_v2_unavailable` /
+`renderer_unavailable`) — never a guessed fallback. It never force-flips an
+existing project.
+
+### Readiness
+
+`roll doctor` (and `roll capture status`, and `roll loop status --capture`)
+report the v2 gateway readiness, the renderer readiness, and the effective
+capture policy — each with an actionable reason:
+
+```bash
+roll doctor              # includes a "Capture policy readiness" section
+roll capture status      # the same readiness, standalone (add --json for machines)
+roll loop status --capture
+```
+
 ## Review Score fold
 
 When `.roll/notes/` carries the story's Review Score entry, the report ends

package/guide/en/browser-operations.md

@@ -547,16 +547,21 @@ Managed browser diagnostics and interactive owner-run results are
 **diagnostic-only / manual-attest only**. Every run report repeats it:
 *diagnostic success is not visual acceptance evidence*. A diagnostic screenshot
 or interactive result is classified as a diagnostic artifact, not a visual-AC
-artifact, so it can never fake a story's visual acceptance. When a story needs
-visual acceptance, use **Roll Capture** — a physical screenshot of your real
-terminal/app — which alone satisfies that requirement. See
-[Acceptance evidence](acceptance-evidence.md).
+artifact, so it can never fake a story's visual acceptance.
+
+Under best-effort capture, a visual AC is satisfied by any valid, target-bound
+image — a **Roll Capture · physical** screenshot of your real terminal/app, or a
+**Playwright · rendered** receipt whose `finalUrl` equals the declared surface.
+Both are eligible; a target-bound rendered receipt is not the same as a
+diagnostic screenshot. A physical image never claims a `finalUrl` it cannot
+observe. See [Acceptance evidence](acceptance-evidence.md).
 
 When `roll attest` receives a physical capture response, it writes a validated
 CaptureBridge link to `.roll/browser-operations/events.ndjson`. Doctor, truth,
 and dossier surfaces read that durable fact: a verified `roll.capture.v1`
-physical capture can satisfy a visual AC, while Playwright and DevTools
-diagnostics remain ineligible. With no persisted link, capture truth stays
+physical capture satisfies a visual AC, and so does a target-bound
+`roll.capture.v2` rendered receipt; only unbound Playwright and DevTools
+*diagnostics* remain ineligible. With no persisted link, capture truth stays
 honestly unknown and the dossier does not invent a capture event.
 
 ---

package/guide/en/faq.md

@@ -918,3 +918,42 @@ It will **never**:
 The lease lasts at most 15 minutes and is released immediately after the
 operation. For unattended diagnostics, use the managed lane (`roll browser run`)
 instead.
+
+### C13. A story is marked evidence-degraded — do I need to rebuild it?
+
+**Short answer:** No. `degraded-infrastructure` means the code delivery passed
+but the capture machine was broken (host / provider / tooling). Rebuilding the
+story would fix nothing. Repair the evidence only:
+
+```bash
+roll capture repair <story-id>
+```
+
+**Details:** `roll capture repair` re-runs **only** the capture lanes and
+re-resolves evidence health. It never reopens the build or the TCR cycle, and the
+delivery verdict is carried through unchanged. It refuses (still without
+rebuilding) for a failed delivery or any non-degraded state.
+
+Check why capture is unavailable first:
+
+```bash
+roll doctor                 # "Capture policy readiness" section
+roll capture status         # gateway + renderer readiness and effective policy
+roll loop status --capture
+```
+
+If the v2 gateway reads `provider_v2_unavailable`, install/update Roll Capture.app
+so it advertises `roll.capture.v2`. If the renderer is unavailable, run
+`npx playwright install chromium`. A visual AC is satisfied by either a
+**Roll Capture · physical** image or a target-bound **Playwright · rendered**
+receipt — it does not require a physical image when a rendered receipt is bound
+to the surface.
+
+### C14. `roll capture migrate` says "retained" — why didn't it enable best_effort?
+
+The migration is capability-aware and never guesses. It enables `best_effort`
+only when **both** the v2 gateway and the renderer are ready. Otherwise it
+retains your existing policy with an explicit reason: `provider_v2_unavailable`
+(the capture host does not advertise v2) or `renderer_unavailable` (Playwright
+Chromium is not installed). Fix the reported capability, then re-run — the
+migration is idempotent, and `roll capture migrate --revert` reverses it.

package/guide/en/loop.md

@@ -394,13 +394,32 @@ persist only while the goal is unfinished. When a goal is `complete`, the next
 no scope flag, the new goal covers all eligible backlog cards; it never reuses
 the completed goal's scope.
 
-Before the first builder cycle, `roll loop go` also has a fallback check for
-leftover uncommitted Roll bootstrap artifacts such as `AGENTS.md`, `.claude/`,
-or `.roll/` metadata. Current `roll init` should already commit and push those
-Roll-owned files; if a historical or manual path still leaves only those files
-dirty, the goal pauses with `bootstrap_artifacts_unconfirmed` and prints the
-files to confirm. Commit or clean them, then run `roll loop go` again. This
-preflight does not start a cycle and does not count as no-progress.
+Before each builder cycle, `roll loop go` classifies the **complete**
+`git status` set of the main checkout (never a truncated slice) against the
+runner's per-cycle **pending-delivery evidence manifests**. Each manifest
+records the exact evidence paths and their SHA-256 hashes for a still-open
+delivery PR, written atomically under `.roll/loop/evidence-manifests/`.
+
+- **Verified** — a `.roll/**` file whose current content hashes to a value
+  recorded in a manifest. These are runner-owned artifacts (the dossier,
+  report, and screenshots of an open PR); they emit `bootstrap_artifacts_verified`
+  and never pause an unrelated eligible card.
+- **Unconfirmed** — any other `.roll/**` file (an unknown path, a hash
+  mismatch, a malformed/stale manifest, a symlink escape, or a directory).
+- **External** — any non-`.roll/**` (product-file) dirt.
+
+If the only dirt is verified evidence, the preflight proceeds. If unconfirmed
+`.roll` pollution is the only remaining dirt, the goal pauses with
+`bootstrap_artifacts_unconfirmed`, naming the exact files (verified evidence is
+never named) so you can confirm ownership: commit them to the product repo or
+`.roll/roll-meta`, ignore them by policy, or clean them and re-run. Product-file
+dirt is surfaced (not hidden) and left to the cycle. This preflight does not
+start a cycle and does not count as no-progress.
+
+Acceptance is manifest-and-hash only: there is **no** `--ignore-dirty` or
+"trust all evidence" bypass. A generic `.roll/**` path or a large status list
+can never make the gate permissive; anything the runner did not record and
+still hash-match fails closed.
 
 For the Roll repository itself, `roll loop go`, `roll loop resume`, and
 `roll loop now` print the runner binary and version before starting autonomous

package/guide/en/testing.md

@@ -75,6 +75,29 @@ pnpm test:cov           # full suite with v8 coverage
 proof the commit gate checks (see below). A doc-only change has no affected
 tests and exits 0. Pre-push / CI / release always run the full `pnpm -r test`.
 
+### Runner compatibility & the conservative fallback
+
+`roll test` resolves the gate command from the **target project** rather than
+assuming one flag, so it stays compatible with the project's installed test
+runner (FIX-1274):
+
+- Roll's own wrapper keeps its `--affected` token.
+- A plain Vitest project uses the version-supported `--changed` changed-test
+  mode. Roll never passes `--affected` to Vitest — Vitest's CLI rejects it as an
+  unknown option, which would otherwise strand the commit.
+- When no safe changed mode can be verified (undetectable/too-old Vitest, a
+  non-Vitest runner), or when a `--changed` run matches **zero** tests, roll
+  runs the project's **full** test command instead. The fallback is always
+  *stricter* than the affected-only gate — never a partial or empty pass.
+
+**Proof guarantee:** `.roll/last-test-pass` is written **only after** a supported
+command actually executes and returns zero, recording the tested tree hash, the
+executed command, the selected mode, and a timestamp. A failed, unknown-option,
+or zero-test run never mints a proof, so a proof always represents a real green
+test run bound to the exact committed tree. An unresolvable project (a
+`package.json` with no `scripts.test`) fails loud with a structured diagnostic
+and a safe next step instead of silently passing.
+
 ## Test Quality Rubric
 
 `guide/en/testing/quality-rubric.md` (referenced from `$roll-.dream` Scan 7)

package/guide/zh/acceptance-evidence.md

@@ -227,6 +227,27 @@ evidence、已有证据暴露 rendering/layout 风险；升级原因必须记录
   不再默认全屏。全屏截图必须在卡片 spec 中显式声明 `capture_fullscreen: true`。
   这个隐私优先的设计防止证据链夹带屏幕上无关的隐私内容（聊天记录、邮件、其他项目）。
   如果目标窗口找不到，Roll Capture.app 会返回带有原因的降级记录——不允许静默扩大截取范围。
+
+### 截图 v2 网关 —— 按来源就绪度 (US-PHYSICAL-010..013)
+
+Roll 的截图主机支持两种协议。`roll capture status` 现在**按来源**分别报告就绪度,
+不再在某条通道还是 v1 时笼统谎报"v2 就绪":
+
+- **渲染态 (`playwright-rendered`)** —— 由 Roll **进程内**用无头 Playwright 提供:
+  声明的网页界面渲染成 PNG,转成带 `sha256` 摘要的 `roll.capture.v2` 收据。**仅在装了
+  Chromium 时**才广播 v2;否则状态显示 `unavailable` 并给出可执行原因(绝不伪造能力)。
+- **物理态 (`roll-capture-window`)** —— 原生 `Roll Capture.app`,今天诚实标为 **v1**
+  (文件投递协议)。物理 v2 是单独的后续卡(US-PHYSICAL-014);状态标 `v1` 而非谎称 v2。
+
+接线方式:
+
+- `roll capture refresh` 探测本机真实能力,写出诚实的 `capabilities.json`(渲染器在→
+  渲染通道 v2;物理→v1)。
+- `roll capture status` 随后按来源显示 `v2 playwright-rendered — ready` 与
+  `v2 roll-capture-window — unavailable`(legacy),不再是一条笼统结论。
+- `roll capture migrate` 仅当渲染态 v2 通道真正 served 时才开启 `best_effort`,否则保留
+  当前策略并说明原因。开启后,声明界面经进程内渲染通道派发,产出归入 CaptureSet 的
+  taken v2 收据;登录 / 跳转 / 非法目标记为 `skipped`,绝不伪造 taken。
 - `Playwright Chromium` —— 可选的 headless web 截图工具，用于 `roll attest`
   和归档截图。安装命令是 `npx playwright install chromium`。
 
@@ -239,6 +260,120 @@ Terminal.app Screen Recording 就绪度时，用 `roll doctor --tools`。`roll i
 机器级 Agents 页面（`.roll/features/agents.html`）也显示同一块工具状态，方便
 审阅者区分证据采集问题来自机器配置，而不是 story 代码。
 
+## Best-effort 截图、证据健康与修复
+
+视觉证据是一种 **best-effort（尽力而为）** 的交付能力：每个声明的视觉面都会经由
+每条合格截图通道尝试采集，截图服务的故障绝不会被误判为产品回归。交付正确性与
+视觉证据健康是**两件独立的事实**。
+
+### 来源标签
+
+每张被接受的图像都带有产出它的通道：
+
+- **Roll Capture · physical（物理）**——由 Roll Capture.app 对你真实终端或应用
+  窗口拍摄的物理截图。它证明屏幕上呈现了什么；它绝不声称自己无法观测到的 URL。
+- **Playwright · rendered（渲染）**——`finalUrl` 经批准的重定向归一化后等于声明
+  目标面的渲染回执。绑定目标的渲染回执是合格的视觉证据——不同于诊断截图。
+
+绑定目标的渲染回执可以独立满足视觉 AC。物理 Roll Capture 图像是满足视觉 AC 的一种
+合格来源；绑定目标的渲染回执是另一种同样合格的来源。
+
+### 四种视觉状态
+
+| 状态 | 含义 | 闸动作 |
+|------|------|--------|
+| `verified` | 至少一张有效且绑定目标的图像（物理或渲染） | 正常发布 |
+| `degraded-infrastructure` | 每条配置通道都已尝试；只发生宿主/供应方/工具类故障 | 发布并显式标记降级；**不重建**——可由仅证据重跑修复 |
+| `invalid-target` | 某条通道到达登录页、未批准重定向、错误目标、损坏图像或伪造回执 | 作为证据失败拦截；修复目标/配置 |
+| `absent-contract` | 无声明面、无计划尝试，或规划器被绕过 | 作为设计/执行失败拦截 |
+
+`degraded-infrastructure` 有意不等于绿色截图结论。它把代码交付与损坏的证据机器
+分开，使同一个已完成的故事不会被反复重建。
+
+### 隐私边界
+
+- 回执绝不包含凭据、cookie、DOM 转储或网络响应体。
+- 窗口捕获默认限定窗口范围；目标缺失产生带类型的失败，绝不静默扩大为全屏。
+- `ROLL_NO_SCREENCAP=1` 只禁用 Runner 直接的原生 `screencapture` / AppleScript
+  路径，不会关闭 Roll Capture 网关请求或 Playwright 渲染尝试。
+
+### 受控本地窗口截图
+
+物理网页证据需要浏览器窗口、但当前没有安全目标窗口时，使用受限的本地通道：
+
+```bash
+roll capture local-window --story FIX-005 --url http://127.0.0.1:4173/team
+```
+
+合成本地 UI 需要在截图前产生可见状态变化时，可加受限的 `--prepare` JSON 列表：
+
+```bash
+roll capture local-window --story FIX-1435 --url http://127.0.0.1:4173/ \
+  --prepare '[{"kind":"click","selector":"#synthetic-checkbox"},{"kind":"wait","ms":300},{"kind":"scroll","selector":"#synthetic-result"}]'
+```
+
+`--prepare` 只允许有上限的 `click`、`fill`、`wait` 与 `scroll`。未知字段或动作种类、
+任意 JavaScript、导航、超量动作或等待都会在 Chrome 启动前被拒绝。临时 Playwright 连接只会
+附着到一次性 loopback Chrome，精确定位已发现页面及其唯一的原始目标 frame，并在每一步后
+校验该 frame 仍处于同一精确 URL。连接随后只断开，不会关闭待截图窗口。`click` 通过浏览器
+UI 路径定位可见元素，使受控 React 输入走正常事件路径。准备动作失败时不会发送截图请求。
+`fill` 只接受非 password 的 `input` 与 `textarea`，contenteditable 目标会被拒绝。
+
+这不是通用浏览器自动化：它不能使用 owner profile，也不能打开远程 URL。prepare API 不
+暴露 cookie 或 storage 的读写、导入或导出操作，也不会注入凭据；目标本地应用本身的正常
+UI 交互仍按原样运行。`fill` 会拒绝 password 控件，且只能填写不敏感的本地合成值；绝不能
+在命令行传入凭据或个人信息。
+
+它只接受 loopback HTTP(S) 页面。Roll 会启动一次性 Chrome profile 和带 nonce 标题
+的本地 wrapper 窗口，要求 Roll Capture.app 只截该精确标题窗口，随后关闭 wrapper、
+Chrome 与 profile。它不会打开远程 URL、连接 owner Chrome profile，也不会回退为全屏
+截图。JSON 结果会给出物理回执与精确 selector。
+
+真实本地受控输入回归为显式选启，因为它会打开可见的一次性 Chrome 窗口；它只提供临时合成
+React 页面，桌面 Chrome 宿主不可用时会失败并明确说明：
+
+```bash
+ROLL_BROWSER_LIVE=1 pnpm test:controlled-capture-live
+```
+
+### 仅证据修复
+
+`degraded-infrastructure` 交付可以在不重开构建的情况下修复：
+
+```bash
+roll capture repair <story-id>
+```
+
+它**只**重跑截图通道并重新解析证据健康，绝不触碰 TCR / 构建周期，绝不重开已完成
+的交付。对失败交付或任何非降级状态，它会拒绝（同样不重建）。结果为 `verified`
+时发布新采集的图像；仍为降级时保持可发布并标记降级。
+
+### 启用 best-effort 截图
+
+新视觉故事的默认值是 `best_effort`。既有项目保留其已记录的策略，直到一次显式、
+能力感知、可回退的迁移显式启用它：
+
+```bash
+roll capture migrate            # 仅在 v2 网关与渲染器都就绪时启用 best_effort
+roll capture migrate --dry-run  # 只预览不写入
+roll capture migrate --revert   # 恢复此前记录的策略
+```
+
+迁移是幂等的。只有在 v2 Roll Capture 网关**和**浏览器渲染器**都**就绪时才启用
+`best_effort`；否则保留既有策略并给出显式原因（`provider_v2_unavailable` /
+`renderer_unavailable`）——绝不猜测回落，绝不强制翻转既有项目。
+
+### 就绪度
+
+`roll doctor`（以及 `roll capture status` 与 `roll loop status --capture`）会报告
+v2 网关就绪度、渲染器就绪度与有效截图策略——每项都带可执行原因：
+
+```bash
+roll doctor              # 含 “Capture policy readiness / 截图策略就绪度” 一节
+roll capture status      # 同样的就绪度，独立呈现（机器读取加 --json）
+roll loop status --capture
+```
+
 ## Review Score 折叠区
 
 `.roll/notes/` 里存在该 story 的评审分条目时，报告底部出现折叠的

package/guide/zh/browser-operations.md

@@ -16,8 +16,10 @@ Roll 可以驱动一个**受管、隔离的 Chrome（经真实的 `chrome-devtoo
 - 它们**不是安装器**。Roll 绝不往你的产品仓 `package.json` 加依赖，也绝不擅自
   开启你自己（owner）Chrome 的远程调试。`setup` 只在你确认后写入一份机器级配置。
 - 它们的产物**不是视觉验收证据**。受管诊断截图或交互式 owner 运行结果只能证明
-  页面动作成功，不能满足故事的视觉验收（visual AC）。只有 **Roll Capture**
-  （对你真实终端/应用的物理截图）才满足视觉验收——见[验收证据](acceptance-evidence.md)。
+  页面动作成功，不能满足故事的视觉验收（visual AC）。在 best-effort 截图下，
+  视觉 AC 由任一有效且绑定目标的图像满足：**Roll Capture · 物理**（对真实终端/
+  应用的物理截图），或 **Playwright · 渲染**（`finalUrl` 等于声明目标面的渲染回执）；
+  两者都合格，绑定目标的渲染回执不同于诊断截图——见[验收证据](acceptance-evidence.md)。
 
 ---
 
@@ -490,14 +492,18 @@ This interactive result does not make CI pass and is not background automation.
 
 受管浏览器诊断与交互式 owner 运行结果**仅为诊断 / 仅为 manual-attest**。每次
 run 报告都重复这句：*诊断通过不等于视觉验收证据*。诊断截图或交互结果会被归类
-为诊断产物，而非视觉验收产物，因此绝不可能伪造故事的视觉验收。故事需要视觉
-验收时，请用 **Roll Capture**——对真实终端/应用的物理截图——只有它满足该要求。
-见[验收证据](acceptance-evidence.md)。
+为诊断产物，而非视觉验收产物，因此绝不可能伪造故事的视觉验收。
+
+在 best-effort 截图下，视觉 AC 由任一有效且绑定目标的图像满足：
+**Roll Capture · 物理**（对真实终端/应用的物理截图），或 **Playwright · 渲染**
+（`finalUrl` 等于声明目标面的渲染回执）；两者都合格。物理图像绝不声称它无法观测到的
+`finalUrl`。见[验收证据](acceptance-evidence.md)。
 
 当 `roll attest` 收到物理捕获响应时，会把已验证的 CaptureBridge link 写入
 `.roll/browser-operations/events.ndjson`。doctor、truth 与 dossier 都读取这条持久化
-事实：通过验证的 `roll.capture.v1` 物理捕获可以满足视觉 AC，而 Playwright 与 DevTools
-诊断仍不具资格。没有已落盘的 link 时，capture truth 诚实保持 unknown，dossier 也不会
+事实：通过验证的 `roll.capture.v1` 物理捕获可以满足视觉 AC，绑定目标的
+`roll.capture.v2` 渲染回执同样可以；只有未绑定目标的 Playwright 与 DevTools*诊断*仍
+不具资格。没有已落盘的 link 时，capture truth 诚实保持 unknown，dossier 也不会
 凭空生成捕获事件。
 
 ---

package/guide/zh/faq.md

@@ -834,3 +834,37 @@ gh issue create --title "Safari 上登录失败" --body "复现步骤: ..."
 
 租约最多 15 分钟，操作结束后立即释放。无人值守诊断请用受管通道
 （`roll browser run`）。
+
+### C13. 某个故事被标记为证据降级——需要重建吗？
+
+**简答：** 不需要。`degraded-infrastructure` 表示代码交付已通过，只是截图机器
+出了故障（宿主 / 供应方 / 工具）。重建故事解决不了任何问题。只修复证据即可：
+
+```bash
+roll capture repair <story-id>
+```
+
+**细节：** `roll capture repair` **只**重跑截图通道并重新解析证据健康，绝不重开
+构建或 TCR 周期，交付结论原样带过。对失败交付或任何非降级状态，它会拒绝（同样
+不重建）。
+
+先查清截图为何不可用：
+
+```bash
+roll doctor                 # “Capture policy readiness / 截图策略就绪度” 一节
+roll capture status         # 网关 + 渲染器就绪度与有效策略
+roll loop status --capture
+```
+
+若 v2 网关显示 `provider_v2_unavailable`，请安装/更新 Roll Capture.app 使其
+advertise `roll.capture.v2`；若渲染器不可用，运行 `npx playwright install
+chromium`。视觉 AC 由 **Roll Capture · physical** 图像或绑定目标的
+**Playwright · rendered** 回执任一满足——当渲染回执已绑定该目标面时，并不要求
+必须有物理图像。
+
+### C14. `roll capture migrate` 显示 “retained”——为什么没启用 best_effort？
+
+迁移是能力感知的，绝不猜测。只有在 v2 网关**和**渲染器**都**就绪时才启用
+`best_effort`；否则保留既有策略并给出显式原因：`provider_v2_unavailable`（截图
+宿主未 advertise v2）或 `renderer_unavailable`（未安装 Playwright Chromium）。
+修好所报能力后重跑即可——迁移是幂等的，`roll capture migrate --revert` 可回退。

package/guide/zh/loop.md

@@ -359,11 +359,27 @@ unknown，这类行仍按保守侧停止，不当作 0。用量闸检查 5 小
 不会让会话无限停摆；超时后 Roll 记录 `usage_wait_timeout` 审计事件并让 goal 保持暂停。
 `--for <duration>` 是墙钟时间盒：当前 cycle 收尾后，goal 以 `timebox` 原因暂停。
 
-启动第一个 builder cycle 前，`roll loop go` 还会兜底检查遗留未提交的 Roll bootstrap 产物，
-例如 `AGENTS.md`、`.claude/` 或 `.roll/` 元数据。新版 `roll init` 应该已经把这些
-Roll-owned 文件提交并推送；如果历史版本或手工路径仍然只留下这些脏文件，goal 会以
-`bootstrap_artifacts_unconfirmed` 暂停，并打印待确认文件。提交或清理后，再重新运行
-`roll loop go`。这个 preflight 不会启动 cycle，也不会累加 no-progress。
+每个 builder cycle 前，`roll loop go` 会对主 checkout 的**完整** `git status`
+列表（绝不截断）与 runner 的**待交付证据 manifest** 逐条比对。每个 manifest 按 cycle
+记录一个仍在开启的交付 PR 的确切证据路径及其 SHA-256 哈希，原子写入
+`.roll/loop/evidence-manifests/`。
+
+- **verified（已核实）**——当前内容哈希命中某个 manifest 记录的 `.roll/**` 文件。
+  它们是 runner 生成的产物（开启 PR 的 dossier、报告、截图），会发出
+  `bootstrap_artifacts_verified`，绝不会暂停一张无关的可执行卡。
+- **unconfirmed（未确认）**——其余任何 `.roll/**` 文件（未知路径、哈希不匹配、
+  manifest 损坏/过期、symlink 逃逸或目录）。
+- **external（外部）**——任何非 `.roll/**`（产品文件）脏改动。
+
+如果脏改动只有 verified 证据，preflight 直接放行；如果只剩 unconfirmed 的 `.roll`
+污染，goal 以 `bootstrap_artifacts_unconfirmed` 暂停并打印确切文件（verified 证据不会
+被列出），便于你确认归属：提交到产品仓或 `.roll/roll-meta`、按策略 ignore、或清理后
+重跑。产品文件脏改动会被显式暴露（不再被隐藏），交给 cycle 处理。这个 preflight 不会
+启动 cycle，也不会累加 no-progress。
+
+放行只认 manifest + 哈希：设计上**没有** `--ignore-dirty` 或“trust all evidence”
+绕过开关。泛泛的 `.roll/**` 路径或很长的 status 列表都无法让闸变宽松；凡是 runner 没有
+记录且当前哈希不匹配的，一律 fail closed。
 
 在 Roll 仓自身里，`roll loop go`、`roll loop resume` 和 `roll loop now`
 开工前都会打印当前 runner 的 binary 与版本。repo-local `@seanyao/roll`

package/guide/zh/testing.md

@@ -70,6 +70,24 @@ pnpm test:cov           # 全套 + v8 覆盖率
 通过证明（见下）。纯文档改动无受影响测试，exit 0。pre-push / CI / release
 一律跑全套 `pnpm -r test`。
 
+### 运行器兼容性与保守回退
+
+`roll test` 从**目标项目**解析闸命令，而不是假定某一个固定 flag，因此始终与
+项目里已安装的测试运行器兼容（FIX-1274）：
+
+- Roll 自己的 wrapper 继续用 `--affected`。
+- 普通 Vitest 项目改用该版本支持的 `--changed` changed-test 模式。Roll 绝不把
+  `--affected` 传给 Vitest——Vitest CLI 会把它当未知选项拒绝，否则会卡死提交。
+- 当无法确认安全的 changed 模式（Vitest 版本探测不到/过旧、非 Vitest 运行器），
+  或 `--changed` 匹配到**零个**测试时，roll 改跑项目的**全量**测试命令。回退永远
+  比 affected 闸**更严格**——绝不放过部分或空测试。
+
+**证明保证**：`.roll/last-test-pass` **只在**受支持的命令真正执行且返回 0 后写入，
+记录被测树哈希、实际执行的命令、所选模式和时间戳。失败、未知选项、零测试的运行
+都不会生成证明，因此一份证明永远代表一次真实的绿色测试运行，且绑定到确切的提交树。
+无法解析的项目（`package.json` 没有 `scripts.test`）会带结构化诊断和安全的下一步
+明确报错，而不是静默通过。
+
 ## 测试质量评分卷（rubric）
 
 `guide/zh/testing/quality-rubric.md`（由 `$roll-.dream` Scan 7 消费）列出