@seanyao/roll 4.714.2 → 4.718.2

package/guide/en/faq.md

@@ -619,6 +619,47 @@ when the work is ambiguous or the environment is broken — never guesses.**
 For deeper operational topics (pause/resume, agent switching, gh scopes), see
 [loop.md](loop.md) and [configuration.md](configuration.md).
 
+### C5b. What do I do when `roll loop on` fails with a launchd bootstrap error?
+
+**Short answer:** The loop is unarmed. Repair launchd first; use the
+owner-confirmed process fallback only if launchd cannot be fixed.
+
+**Why this happens:** macOS launchd sometimes rejects the bootstrap with
+`Bootstrap failed: 5: Input/output error` (or a similar domain error). Roll
+retries once, verifies the mount with `launchctl print`, and exits non-zero
+rather than pretending the scheduler is active.
+
+**Fix launchd first:**
+
+```bash
+UID=$(id -u)
+LABEL=$(launchctl list | awk '$3 ~ /^com\.roll\.loop\./ {print $3; exit}')
+# If launchctl list returns nothing, use the exact label from the error output.
+launchctl bootout gui/$UID/$LABEL
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/$LABEL.plist
+launchctl print gui/$UID/$LABEL
+roll loop on
+roll loop status
+```
+
+**If launchd cannot be repaired:**
+
+```bash
+roll loop fallback start --confirm
+roll loop fallback status
+```
+
+The fallback is not a launchd replacement — it does not survive reboot/login.
+After a reboot or logout you must re-confirm:
+
+```bash
+roll loop fallback stop
+roll loop fallback start --confirm
+```
+
+See [Recovering from a launchd bootstrap failure](loop.md#recovering-from-a-launchd-bootstrap-failure)
+for a sanitized, non-root verification procedure.
+
 ### C7. I changed loop_schedule but loop still runs at the old frequency
 
 **Symptoms:** You updated `.roll/local.yaml` `loop_schedule`, but
@@ -854,3 +895,65 @@ These controls apply to user-facing surfaces only. Agent contracts, code, git
 metadata, and schemas remain English. Owner conversation follows the language
 used by the owner in the current task. Run `roll doctor language` to audit docs,
 conventions, skills, and generated surfaces before release.
+
+### C12. What are the limits of `roll browser interactive`?
+
+**Short answer:** It is a foreground, owner-run, single-operation tool against a
+local Chrome debug endpoint — not a background automation or remote browser.
+
+**Details:** `roll browser interactive` requires:
+
+- An attached TTY and explicit owner approval for every operation.
+- A Chrome you started yourself with a loopback debug port such as
+  `--remote-debugging-port=9222` on `127.0.0.1`.
+
+It will **never**:
+
+- Run from a background scheduler or CI job.
+- Connect to a remote or non-loopback endpoint.
+- Export cookies, storage, or network bodies.
+- Start Chrome automatically.
+- Make CI pass on its own — the result is for **owner-run manual-attest** only.
+
+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

@@ -35,7 +35,7 @@ metadata, and delivery truth. The four targets are:
 
 | Metric | Target | Anti-gaming rule | `null` means |
 |--------|--------|------------------|--------------|
-| Autonomy | >=72h autonomous runtime | An effective autonomous day needs at least 6 non-idle attempts; backlog-empty days pause the clock and do not count as missed time. | There is not enough qualifying run history yet, or the backlog was empty for the window. |
+| Autonomy | >=72h autonomous runtime | `current` is the sum of eligible daily hours across the declared 14-day window, not the latest uninterrupted segment. An effective autonomous day needs at least 6 non-idle attempts; backlog-empty days pause the clock and do not count as missed time. | There is not enough qualifying run history yet, or the backlog was empty for the window. |
 | Delivery rate | >=60% | Delivery is counted from merge truth, not self-reported cycle exits. | No eligible delivery denominator exists yet. |
 | Fix tax | <1x | The denominator is US cards only; FIX work is not allowed to improve its own ratio. | There is no US-card denominator in the window. |
 | Attribution errors | =0 | `unknown` is not guessed into env, harness, or card; missing envelopes stay visible. | No attribution sample exists yet. |
@@ -109,6 +109,80 @@ commands; it never leaves a failed bootstrap looking enabled.
 Active window: 0–24 (always on — the shipped default)
 ```
 
+### Recovering from a launchd bootstrap failure
+
+A failed `roll loop on` is **unarmed**. The presence of a plist file in
+`~/Library/LaunchAgents/` does **not** mean autonomous scheduling is active —
+only `launchctl list` showing the loaded label means the loop is armed. Run
+`roll loop status` to see the effective backend (`launchd`,
+`process-fallback`, or `none`).
+
+**Repair launchd first.** The error output already prints the exact commands;
+the generic form uses the label reported by `launchctl list`:
+
+```bash
+UID=$(id -u)
+LABEL=$(launchctl list | awk '$3 ~ /^com\.roll\.loop\./ {print $3; exit}')
+# If launchctl list returns nothing, use the exact label from the roll loop on error output.
+launchctl bootout gui/$UID/$LABEL
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/$LABEL.plist
+launchctl print gui/$UID/$LABEL
+roll loop status
+```
+
+If `launchctl bootstrap` succeeds and `print` shows the job, run `roll loop on`
+again to regenerate the current runner and confirm the schedule.
+
+**If launchd cannot be repaired**, Roll provides an owner-confirmed process
+fallback that is started only when you explicitly confirm it:
+
+```bash
+roll loop fallback start --confirm
+roll loop fallback status
+roll loop fallback stop        # when you no longer need it
+```
+
+The fallback is **not** a launchd replacement. It does not survive reboot or
+login session exit. After a reboot or logout you must stop any stale lease and
+re-confirm:
+
+```bash
+roll loop fallback stop
+roll loop fallback start --confirm
+```
+
+Prefer repairing launchd; use the fallback only when launchd is unavailable.
+
+#### macOS live verification procedure (Bootstrap failed: 5)
+
+When `roll loop on` fails with a `Bootstrap failed: 5: Input/output error`
+class error, capture a sanitized, non-root diagnostic bundle:
+
+```bash
+mkdir -p .roll/loop
+TS=$(date +%Y%m%d-%H%M%S)
+OUT=.roll/loop/launchd-verify-$TS.log
+{
+  echo "roll version: $(roll version)"
+  echo "uid: $(id -u)"
+  echo "---"
+  echo "roll loop status:"
+  roll loop status
+  echo "---"
+  echo "launchctl list (roll lanes):"
+  launchctl list | grep com.roll\. || true
+  echo "---"
+  echo "plists on disk:"
+  ls -1 ~/Library/LaunchAgents/com.roll.loop.*.plist 2>/dev/null || true
+} > "$OUT"
+# Sanitize before sharing: replace the literal home path with ~.
+sed -i.bak "s|$HOME|~|g" "$OUT" && rm -f "$OUT".bak
+```
+
+This procedure uses only user-level (`gui/<uid>`) launchctl commands. It does
+not require `sudo` and does not claim root-only diagnostics such as
+`launchctl dumpstate` are available.
+
 By default the active window is the full day (`loop_active_start=0`,
 `loop_active_end=24`), so loop fires on every scheduled tick. Narrow it to a
 working window with `roll config loop-window` — e.g. `roll config loop-window
@@ -267,7 +341,7 @@ roll loop gc --keep-days 14   # Override retention (also: loop_gc.retention_days
 roll loop events      # Show last 20 cycle events
 roll loop events 50   # Show last 50 events
 
-roll agent                           # Show scopes, roles, agent pool, and legacy inputs
+roll agent                           # Show scopes, effective project capability, and agent pool
 roll agent list                      # Show agents installed on this machine
 ```
 
@@ -314,16 +388,38 @@ Budget and run limits are explicit per `roll loop go`. `--budget`,
 limit for this run — Roll never silently inherits a budget or cap from a prior
 session's persisted goal, so a flagless `roll loop go` can neither be capped nor
 bricked by a limit you set days ago. Scope (`--epic`/`--cards`) and `--review`
-still persist when unspecified, because they are the goal's identity, not a
-per-run safety knob.
-
-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.
+persist only while the goal is unfinished. When a goal is `complete`, the next
+`roll loop go` archives it under `.roll/loop/goal-archive/`, records
+`goal:archived`, and starts a distinct goal from that invocation's flags. With
+no scope flag, the new goal covers all eligible backlog cards; it never reuses
+the completed goal's scope.
+
+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
@@ -419,9 +515,12 @@ defaults:
         strategy: health-aware
 ```
 
-`roll agent` shows the effective Machine Scope, Project Scope, resolved roles,
-candidate pool, runtime health notes, and any legacy compatibility inputs. Use
-`roll agent migrate --dry-run` to preview conversion from old agent files.
+`roll agent` shows the Machine Scope and the effective Project Scope, including
+inherited agents and configured route models. It does not predict the next role
+assignment: dispatch resolves runtime health and least-recent state at spawn.
+Use `roll supervisor route --role builder|evaluator` for a diagnostic runtime
+snapshot. Use `roll agent migrate --dry-run` to preview a one-time conversion
+from old agent files; old agent config is not read during normal execution.
 
 Runtime health is not static policy. Quota, auth, network, VPN, account, stall,
 or missing binary failures suspend only the runtime rig and are recorded as
@@ -656,6 +755,11 @@ ending point. Use the Gate and attest result for pass/fail.
 
 `roll loop status` prints a compact dashboard with per-cycle rows and daily rollup totals.
 
+When every currently eligible card needs a physical terminal capture and macOS
+is locked, the status line says `waiting for screen unlock`. This is a wait
+state, not an idle failure: the next unlocked tick clears the message and
+dispatches normally, without consuming the no-progress breaker.
+
 ### Token column
 
 Each cycle row shows token usage in a 4-component format:
@@ -1492,3 +1596,7 @@ retired shapes from older versions (ci/alert/brief) once survived for weeks as
 zombies pointing at deleted engines. `roll doctor` lists every `com.roll.*`
 job on the machine with its target directory and load state; a lane whose
 WorkingDirectory no longer exists is marked STALE in red.
+
+A plist left on disk after a bootstrap failure or a manual `bootout` is **not**
+the same as an armed loop. Always trust `roll loop status` (effective scheduler
+backend) and `launchctl list` over the mere presence of a `.plist` file.

package/guide/en/pairing.md

@@ -19,7 +19,7 @@ Project Scope `evaluate` binding.
 
 ```bash
 roll agent                         # inspect story.evaluate
-roll agent migrate --dry-run       # convert legacy pairing.yaml if present
+roll agent migrate --dry-run       # preview one-time migration of old agent config
 ```
 
 New projects should author the evaluator pool in `.roll/agents.yaml`:
@@ -38,10 +38,9 @@ defaults:
         strategy: health-aware
 ```
 
-`.roll/pairing.yaml` remains a legacy compatibility input. When both files are
-present, the scoped `evaluate` role is preferred. Static config lists fair
-candidates; runtime auth/network/VPN/account failures skip candidates only for
-the current resolution.
+`.roll/pairing.yaml` is not a runtime input. The scoped `evaluate` role is the
+only source for pairing candidates. Static config lists fair candidates; runtime
+auth/network/VPN/account failures skip candidates only for the current resolution.
 
 ## Seeing what it does — observability
 

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/en/tools.md

@@ -79,6 +79,17 @@ Supported fields:
 
 Unknown fields warn but do not reject the policy file, so newer Roll versions can add fields without breaking older project configs.
 
+## Owner Chrome: manual interactive lane
+
+`roll browser interactive` is a manual, owner-run boundary for one typed low-risk action against an already-open, loopback Chrome DevTools endpoint. It requires an attached TTY and a fresh `y` approval for every invocation. The prompt names the story, approved origin, action summary, 15-minute maximum expiry, and credential-export denial.
+
+```text
+roll browser interactive --story US-BROW-008b --origin https://app.example.test \
+  --action navigate --url https://app.example.test/account
+```
+
+It connects only to a tab whose origin matches `--origin`, then disconnects DevTools on approval expiry, cancellation, errors, or process exit. Roll never launches or closes the owner's Chrome. The closed action vocabulary is `navigate`, `click`, `fill`, and `press_key`; cookies, storage, and network bodies have no CLI or adapter surface. A successful interactive result is manual evidence only: it does not make CI pass and cannot become background automation.
+
 ## CLI
 
 Use `roll doctor tools status` to inspect the registered tools, input contracts, requirement readiness, and the effective policy state for the current project.

package/guide/zh/acceptance-evidence.md

@@ -45,6 +45,11 @@ HTML。那些归档页想看时用 归档重建 按需渲染，它们是便捷/
 
 `roll attest` 也可独立运行——没有意图映射时，每条 AC 诚实渲染为 🟧 仅声明。
 
+抓到的产物按**实际媒体类型**渲染，不按产生它的采集通道决定。图片文件（`png`、`jpg`、
+`jpeg`、`webp` 或 `gif`，包括无扩展名但能识别出图片签名的产物）显示为图片；`.txt`、
+`.log` 等文本输出会先转义，再以内联、可读的 `<pre>` 块显示。因此，终端采集可能以任一
+形式出现。
+
 ## 闸口策略
 
 验收闸**默认是 hard**。带 AC 的 story 若交付完成却没有新鲜且内容充足的报告，
@@ -92,6 +97,60 @@ roll attest audit --json
 表示 harness 基于硬盘上强证据做出的确认，明确不同于 agent 亲自确认的 `pass`。
 "我确认它能跑"这类口头完成，正是被这条红线挡住的东西。
 
+## 外部行为验证
+
+有些 AC 描述的是 Roll 在本地无法证明的行为——真实的
+`npm i -g github:owner/repo`、发布后 CLI 的首次启动、线上 OAuth 回调。构建成功
+或 `npm pack` 通过并**不能**证明这些；模拟不是外部承诺本身。把这类 AC 标为
+manual-only 再呈绿色，等同于用"未执行"替代"通过"。
+
+当一张故事或修复记录了外部安装 / 发布 / 登录渠道时，相关 AC 必须在 Evaluation
+契约里显式声明**一种**验证路径——Roll 从不从散文里猜"什么算外部"：
+
+```yaml
+expected_evidence:
+  - kind: external-smoke                     # 隔离环境里的真实命令
+    target: npm i -g github:owner/repo#<commit> && repo --version
+    proves: 文档里的 git 安装渠道能在全新目录真实安装并启动
+    outward:
+      mode: external-smoke
+      command: npm i -g github:owner/repo#<commit> && repo --version
+      environment: release                   # ci | nightly | release
+      timeout_sec: 180
+  - kind: owner-attested                     # smoke 无法覆盖时的人工签字
+    proves: 生产环境 OAuth 回调可往返
+    outward:
+      mode: owner-attested
+      reason: 需要真实第三方账号，没有安全的自动路径
+      approvalRef: https://github.com/owner/repo/issues/1343
+```
+
+attest 报告会在靠上位置渲染一个**外部行为验证**横幅与表格。只有真实 smoke 通过
+（或有效、未过期的 owner 认证）才是绿色：
+
+| 解析状态 | 报告文案 | 绿色？ |
+|----------|----------|--------|
+| `verified` | `VERIFIED (external smoke)` / `VERIFIED (owner-attested)` | 是 |
+| `verified-in-simulation` | `verified-in-simulation — simulation only, NOT accepted` | **否** |
+| `unverified-external` | `UNVERIFIED — external smoke not run`（或 `owner attestation pending`） | **否** |
+| `failed-external` | `FAILED — external smoke` | **否** |
+
+只要有一个外部 AC 不是 `verified`，横幅即转红——交付不能夸大自己的外部行为。
+`npm pack` 之类的模拟证据会保留并标注 `verified-in-simulation`，但绝不替代真实 smoke。
+
+### 发版 / nightly smoke 环境搭建
+
+外部 smoke 在**隔离**环境里运行——全新的临时 `HOME`/`PREFIX`/工作目录，只执行
+spec 中显式声明的命令模板与受控变量。产物记录 exit code、版本、脱敏后的
+stdout/stderr 摘要；凭据从不落盘。
+
+用 `ROLL_SMOKE_ENV=release`（或 `ci` / `nightly`）把运行器指向对应环境；声明的
+`environment` 与当前环境不匹配时会被报为 `unverified`，绝不静默跳过。**任何真实
+发布或账号操作永不自动执行**：凡是推送包、改动远端账号或产生费用的动作，没有声明
+的授权（你写进 spec 的 `external-smoke` 命令，或一条 `owner-attested` 批准引用）
+就不会跑。若没有匹配的 smoke 环境，AC 保持 `unverified`、报告保持非绿——绝不会被
+自动升级成手工通过。
+
 ## 设计期声明可视证据
 
 `roll story validate` 在设计期就检查一张卡是否**生而诚实**——带可视证据 AC，
@@ -180,6 +239,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/ai-agents.md

@@ -20,7 +20,7 @@ Story 的角色，Story 或 Skill 可以在需要时进一步收窄绑定。
 agent 语义的主配置面。常用命令：
 
 ```bash
-roll agent                      # 查看 Machine Scope、Project Scope、角色、pool、legacy 输入
+roll agent                      # 查看 Machine Scope、有效 Project Scope 与已安装 pool
 roll agent migrate --dry-run    # 预览 legacy 文件迁移
 roll agent migrate              # 写入 roll-agents/v1 文件
 roll agent list                 # 查看本机已安装 agent
@@ -156,12 +156,12 @@ roll supervisor health --json      # 机器可读的分类结果
 roll supervisor next               # 下一张卡 + agent health 摘要
 ```
 
-## Legacy 兼容
+## 旧 Agent 配置迁移
 
 旧项目可能还会有 `.roll/local.yaml agent`、`.roll/pairing.yaml`，或者
-`.roll/agents.yaml` 里的 v3 route slots。`roll agent` 会把它们显示在
-`Legacy compatibility` 区块，`roll agent migrate` 会把仍有用的数据迁进 scoped
-模型。它们仍可读取，但不再是主要 agent 管理模型。
+`.roll/agents.yaml` 里的 v3 route slots。它们不再是运行时输入。先用
+`roll agent migrate --dry-run` 预览一次性迁移，再用 `roll agent migrate`
+写入 scoped binding。loop 遇到 v3 route slots 会明确失败，不会悄悄启用第二套配置模型。
 
 ## 另见