@seanyao/roll 4.714.2 → 4.718.2

package/docs/architecture.md

@@ -221,6 +221,8 @@ building ──attest earned──► publishable ──push+PR──► awaitin
   - 完全跳过预检：`loop_safety.skip_network_check: true`（FIX-1025）——当你确认所配置的服务可直连、不希望被任何固定主机探测拦住时使用。
   - English: the precheck defaults to `github.com:443`. For a domestic-only workflow, point it at a host you actually need via `loop_safety.probe_url`, or opt out entirely with `loop_safety.skip_network_check: true` — so a dropped VPN never halts loop/release when every configured provider is directly reachable.
 - Warm session 复用：`loop_safety.session_reuse: true` 只表达复用意图；必须同时设置 `loop_safety.resume_scope: same-story` 才会在同一 story 重试时复用 codex session。缺省、非法值或未设置 `resume_scope` 都按 `off` 处理，跨卡复用保持禁用。
+- Builder 硬轮换：`loop_safety.builder_no_consecutive_repeat`（默认开）保证任意连续两个 cycle 的 builder agent 不相同——上一个 cycle 的 builder 被从本次 execute 池中硬排除。池缩到只剩上一个 builder 时**失败即声（ALERT + pending）**，绝不静默重复、绝不空转；轮换真正发生时记 `builder:rotation` 事件可审计。设 `builder_no_consecutive_repeat: false` 关闭；仅约束 builder（Evaluator 独立性靠 fresh session，不靠排除品牌）。
+  - English: `loop_safety.builder_no_consecutive_repeat` (default on) forbids two consecutive cycles from sharing a Builder — the previous cycle's builder is hard-excluded from the execute pool. If that empties the pool it fails loud (ALERT + pending), never repeating silently; a real rotation records a `builder:rotation` audit event. Set `false` to disable. Builder-only (Evaluator independence comes from fresh sessions, not brand exclusion).
 
 策略是规则源——它不直接执行动作，而是被其他上下文读取并遵循。
 
@@ -359,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/INDEX.md

@@ -9,6 +9,7 @@
 | AGENTS.md | Roll Project — Internal Conventions | convention | 2026-05-28 |
 | CONTRIBUTING.md | Contributing to Roll | convention | 2026-05-23 |
 | guide/en/ai-agents.md | Roll — AI Agent Support | guide | 2026-06-30 |
+| guide/en/browser-operations.md | Roll — Browser Operations (managed + interactive lanes) | guide | 2026-07-15 |
 | guide/en/acceptance-evidence.md | Acceptance Evidence — roll attest / Evidence lifecycle | guide | 2026-07-02 |
 | guide/en/changelog.md | Roll — Changelog | guide | 2026-05-21 |
 | guide/en/configuration.md | Roll — Configuration | guide | 2026-07-02 |
@@ -39,6 +40,7 @@
 | guide/en/testing.md | Roll — Testing Workflow | guide | 2026-05-23 |
 | guide/en/testing/quality-rubric.md | Test Quality Rubric | guide | 2026-05-23 |
 | guide/zh/ai-agents.md | Roll — AI Agent 支持 | guide | 2026-06-30 |
+| guide/zh/browser-operations.md | Roll — 浏览器操作（受管通道 + 交互通道） | guide | 2026-07-15 |
 | guide/zh/changelog.md | Roll — Changelog (中文) | guide | 2026-05-21 |
 | guide/zh/configuration.md | Roll — 配置 | guide | 2026-07-02 |
 | guide/zh/conventions.md | Roll — 约定与 AGENTS.md | guide | 2026-07-02 |

package/guide/en/acceptance-evidence.md

@@ -53,6 +53,12 @@ the archive rebuild; they are a convenience/archive view, not the delivery-truth
 `roll attest` also runs standalone — without an intent map every AC renders as
 🟧 Claimed, honestly.
 
+Captured artifacts render by their actual media type, not the capture lane that
+produced them. Image files (`png`, `jpg`, `jpeg`, `webp`, or `gif`, including a
+recognised image signature without an extension) render as images; text output
+such as `.txt` or `.log` is escaped and shown inline in a readable `<pre>`
+block. A terminal capture may therefore appear in either form.
+
 ## Gate policy
 
 The attest gate is **hard by default**. A delivered story with ACs but no fresh,
@@ -108,6 +114,66 @@ renderer forces it down to 🟧 Claimed and lists it under **Discrepancies**.
 evidence; it is explicitly not the same as an agent-confirmed `pass`. Verbal
 completion ("I confirmed it works") is exactly what this rules out.
 
+## Outward behavior verification
+
+Some ACs describe behavior Roll cannot prove locally — a real
+`npm i -g github:owner/repo`, a published CLI's first run, a live OAuth
+callback. A build or `npm pack` succeeding does **not** prove any of these; a
+simulation is not the outward promise. Marking such an AC "manual-only" and
+letting it render green is the same as substituting *not run* for *passed*.
+
+When a story or fix documents an external install / publish / login channel, the
+relevant AC must declare **one** explicit verification path in its Evaluation
+contract — Roll never infers "outward" from prose:
+
+```yaml
+expected_evidence:
+  - kind: external-smoke                     # real command in an isolated env
+    target: npm i -g github:owner/repo#<commit> && repo --version
+    proves: the documented git-install channel installs and starts clean
+    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                     # human sign-off when no smoke can cover it
+    proves: the production OAuth callback round-trips
+    outward:
+      mode: owner-attested
+      reason: needs a real third-party account; no safe automated path exists
+      approvalRef: https://github.com/owner/repo/issues/1343
+```
+
+The attest report renders an **Outward verification** banner and table near the
+top. Only a real smoke pass (or a valid, unexpired owner attestation) is green:
+
+| Resolved state | Report line | Green? |
+|----------------|-------------|--------|
+| `verified` | `VERIFIED (external smoke)` / `VERIFIED (owner-attested)` | yes |
+| `verified-in-simulation` | `verified-in-simulation — simulation only, NOT accepted` | **no** |
+| `unverified-external` | `UNVERIFIED — external smoke not run` (or `owner attestation pending`) | **no** |
+| `failed-external` | `FAILED — external smoke` | **no** |
+
+A single non-`verified` outward AC turns the banner red — the delivery cannot
+overstate its outward behavior. `npm pack`–style simulation evidence is kept and
+labeled `verified-in-simulation`, but it never substitutes for a real smoke.
+
+### Release / nightly smoke setup
+
+External smoke runs in an **isolated** environment — a fresh temporary
+`HOME`/`PREFIX`/working directory — and executes only the exact command template
+declared in the spec, with controlled variables. Its artifact records exit code,
+version, and a redacted stdout/stderr summary; credentials are never written.
+
+Point the runner at an environment with `ROLL_SMOKE_ENV=release` (or `ci` /
+`nightly`); a declaration whose `environment` does not match the current one is
+reported `unverified`, never silently skipped. **No real publish or account
+action is ever automatic**: nothing that pushes a package, mutates a remote
+account, or spends money runs without a declared authority (an `external-smoke`
+command you wrote into the spec, or an `owner-attested` approval reference). If no
+matching smoke environment exists, the AC stays `unverified` and the report stays
+non-green — it is never auto-promoted to a manual pass.
+
 ## Declaring visual evidence at design time
 
 `roll story validate` checks, at design time, that a spec is *born* with a
@@ -217,6 +283,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/ai-agents.md

@@ -23,7 +23,7 @@ migration input, but it is no longer the primary authoring surface for agent
 semantics. Use:
 
 ```bash
-roll agent                      # show Machine Scope, Project Scope, roles, pool, and legacy inputs
+roll agent                      # show Machine Scope, effective Project Scope, and installed pool
 roll agent migrate --dry-run    # preview conversion from legacy files
 roll agent migrate              # write roll-agents/v1 files
 roll agent list                 # show installed agents
@@ -170,13 +170,13 @@ roll supervisor health --json      # machine-readable classifications
 roll supervisor next               # next card + agent health summary
 ```
 
-## Legacy Compatibility
+## Migration from Older Agent Config
 
-Older projects may still contain `.roll/local.yaml agent`, `.roll/pairing.yaml`,
-or v3 route slots in `.roll/agents.yaml`. `roll agent` shows them under
-`Legacy compatibility`, and `roll agent migrate` converts their useful data into
-the scoped model. They remain readable compatibility inputs, not the primary
-agent-management model.
+Older projects may contain `.roll/local.yaml agent`, `.roll/pairing.yaml`, or v3
+route slots in `.roll/agents.yaml`. These are not runtime inputs. Run
+`roll agent migrate --dry-run` to preview their one-time conversion, then
+`roll agent migrate` to write scoped bindings. A loop that encounters v3 route
+slots fails loudly instead of silently using a second configuration model.
 
 ## See Also