@seanyao/roll 4.702.4 → 4.706.1

package/docs/verification.md

@@ -73,6 +73,26 @@ diff <(v2.0-bash <cmd>) <(v3-ts <cmd>)
 - **回收**：`roll loop gc` 按阈值清理陈旧 run（保最近 N 次 + M 天内，二者满足其一即留；只删「又旧又超额」的尾部）。阈值 `--keep-latest`（默认 10）/`--keep-days`（默认 30），`--dry-run` 预演。
 - **读取兼容**：迁移窗口内旧布局 `.roll/verification/<ID>/` 仍可读（attest gate、ac-map、报告解析都先查卡夹再回落旧树）；存量迁移与兼容代码移除由 US-META-002 收尾。
 
+## 证据可见性模型（US-PHYSICAL-008）
+
+截图/图片类证据涉及隐私，因此在 `git add` 之前必须确认目标仓库的远程可见性：
+
+| 布局 | 目标仓库 | 判定策略 | 图片证据 |
+|------|----------|----------|----------|
+| 独立 roll-meta | `.roll` 自身所在的私有仓 | `gh api repos/<slug>` 或 `git ls-remote`；判定为 private 则放行 | 私有仓放行 |
+| 公开产品仓 + 独立 roll-meta | 产品仓本身不接收 `.roll` 证据；证据进私有 roll-meta | 同 roll-meta | 私有仓放行 |
+| in-repo `.roll` | 产品主仓（`.roll` 随代码一起 tracked） | 检查主仓 remote 可见性 | public / 未知 一律拒绝 |
+
+保守规则：判定失败（无 remote、`gh` 不可用、API 失败、非 GitHub 且无法推断可见性）一律按 **public** 处理，拒绝图片证据并触发 ALERT。
+
+逃生口：owner 可在 `.roll/local.yaml` 中显式声明
+
+```yaml
+evidence_public_waiver: true
+```
+
+放行公开仓的图片证据，同时留下审计痕迹。in-repo 项目首次成功判定后会把 `evidence_visibility` + `evidence_remote` 写入同一文件；remote URL 变化时自动重判。
+
 ## 门
 
 | 门 | 条件 | 频率 |

package/guide/en/acceptance-evidence.md

@@ -67,6 +67,36 @@ loop_safety:
 Soft mode records the gap and raises the same audit signal, but it does not
 block the delivery cycle. Treat it as temporary compatibility, not the default.
 
+The merge gate reads structured evidence, not prose. A delivery can be refused
+when any of these facts are true:
+
+- `attest render` exits non-zero;
+- `ac-map.json` references a path that does not resolve under the story run or
+  card archive, except allowed GitHub PR/commit/check URLs for this repository;
+- an AC remains `claimed`, which means the Builder asserted completion without
+  pass/fail evidence;
+- a positive AC has no real evidence reference;
+- a non-exempt visual card has no captured screenshot or recorded machine
+  capture skip;
+- a declared `deliverable_url`, `deliverable_cmd`, or `physical_terminal`
+  surface was not really captured;
+- an AC is `fail`, which means a check ran and went red.
+
+The PR body carries a `Roll-Evidence` trailer that points reviewers to the
+story-scoped evidence. Treat that trailer as the entry point for human review:
+open the Acceptance Review Page, then follow the AC map and referenced files.
+
+Use the audit command before release or when a Done row looks suspicious:
+
+```bash
+roll attest audit
+roll attest audit --json
+```
+
+It scans Done stories for missing reports, missing or empty `ac-map.json`,
+dangling evidence references, and `evidence_debt` rows. A clean audit exits 0;
+any issue exits 1 and lists the story IDs and missing references.
+
 ## The red line
 
 An AC with **zero evidence** can never claim `pass`: the renderer forces it
@@ -77,6 +107,11 @@ down to 🟧 Claimed and lists it under **Discrepancies**. Verbal completion
 
 `roll story validate` checks, at design time, that a spec is *born* with a
 visual-evidence AC (and, for a web surface, a declared product page to capture).
+If the spec has a visual-evidence AC but no declared surface
+(`deliverable_url`, `deliverable_cmd`, `physical_terminal`, or
+`screenshot_exempt`), validation prints a soft must-declare warning and still
+exits 0. Runtime gates carry the same must-declare signal as a diagnostic only;
+they do not block or mark the delivery skipped for that reason alone.
 Two rules decide what the validator recognises:
 
 - **The `[visual-evidence]` marker is authoritative.** An AC item that opens with
@@ -96,7 +131,10 @@ Two rules decide what the validator recognises:
   - a declared `physical_terminal:` ⇒ **terminal** with a stricter contract — the
     report must contain a real macOS `Terminal.app` screenshot captured from
     screen pixels. Headless stdout, transcript-rendered images, and HTML replays
-    are rejected for this contract;
+    are rejected for this contract. `roll attest` also asks the
+    `physical.screenshot` provider for this evidence when available, copies the
+    returned PNG into the story run, and shows the status chain
+    `requested -> taken/skipped/failed/timeout -> attached/not-attached`;
   - else a declared `deliverable_cmd:` ⇒ **terminal** — a CLI deliverable that
     rides the terminal-capture lane;
   - else the AC text decides (web / terminal / ambiguous).
@@ -142,6 +180,23 @@ at startup:
   repeated `roll doctor` / setup checks do not keep re-triggering the macOS
   prompt; if permission was just granted, restart Terminal.app before trusting
   the cache.
+- `Roll Capture.app` / `physical.screenshot` — the provider path for physical
+  screenshot requests. If readiness is unavailable, `roll attest` records an
+  honest skip with the setup reason instead of blocking report generation; if
+  the provider times out, the report surfaces timeout as its own failure reason.
+  On macOS npm installs, Roll tries to install the app from the latest
+  `seanyao/roll-capture` Release into `~/Applications`; `roll setup` can retry
+  that repair unless `--no-capture-install` is set.
+
+  **Capture default strategy (US-PHYSICAL-006):** Physical screenshot requests
+  default to **window-level** capture — they only capture the tested application's
+  window (Terminal.app for terminal/CLI evidence, Google Chrome for web evidence),
+  not the full screen. Full-screen capture requires an explicit
+  `capture_fullscreen: true` frontmatter declaration in the card spec. This
+  privacy-first design prevents evidence chains from including irrelevant on-screen
+  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.
 - `Playwright Chromium` — optional headless web capture for `roll attest` and
   archive screenshots. Install with `npx playwright install chromium`.
 

package/guide/en/configuration.md

@@ -21,6 +21,7 @@ shared conventions.
 | `ROLL_LOOP_GC_RETENTION_DAYS` | `30` | Override the GC retention period for `roll loop gc`. Takes precedence over `loop_gc.retention_days` in `.roll/local.yaml`. |
 | `ROLL_FEED_BUDGET_BYTES` | `16384` | Byte budget for the context feed handed to the inner agent each cycle. Set it to a positive integer to dial the feed to the inner agent's capacity; non-numeric or non-positive values fall back to the default. |
 | `ROLL_AGENT_NUDGE` | `1` (on) | Compatibility agent preference switch. The scoped role binding is the primary selector; set this to `0` (or `off`/`false`/`no`) to disable legacy history preference. |
+| `ROLL_SKIP_CAPTURE_INSTALL` | unset | Set to `1` to skip the best-effort macOS `Roll Capture.app` install during npm postinstall and setup repair. |
 | `ROLL_RUN_DIR` | unset | Canonical acceptance-evidence run directory. The loop runner sets it before agent spawn; `roll attest --run-dir` and standalone `roll attest` can also consume it. |
 | `ROLL_EVIDENCE_DIR` | derived from `ROLL_RUN_DIR` | Directory for raw command/test artifacts inside the open evidence frame. Normally set by the runner or `roll test`, not by hand. |
 | `ROLL_SCREENSHOTS_DIR` | derived from `ROLL_RUN_DIR` | Directory for visual proof inside the open evidence frame. Normally set by the runner or capture lane, not by hand. |
@@ -86,6 +87,20 @@ loop_safety:
 Use `attest_gate: soft` only for an explicit migration window. Soft mode keeps
 the audit trail and alert, but it does not block the delivery cycle.
 
+Automatic card picking also has an advisory semantic ranking layer. It is on by
+default and can be disabled explicitly:
+
+```yaml
+pick:
+  semantic_ranking: off
+```
+
+When enabled, Roll asks the default agent to rank the current candidate backlog
+only when the backlog/candidate hash changes, caches the result in
+`.roll/loop/pick-ranking.json`, and then still applies the normal picker gates.
+If the agent times out or returns bad JSON, Roll records `harness_failure` and
+falls back to the deterministic order.
+
 ## Verifying
 
 `roll status` prints the resolved paths so you can confirm overrides took

package/guide/en/installation.md

@@ -22,7 +22,18 @@ curl -fsSL https://seanyao.github.io/roll/install | ROLL_VERSION=v3.610.1 bash
 npm install -g @seanyao/roll
 ```
 
-Requires Node.js 16+.
+Requires Node.js 22+.
+
+On macOS, the npm package runs a best-effort postinstall that downloads
+`Roll-Capture.app.zip` from the latest `seanyao/roll-capture` GitHub Release,
+validates the asset, and installs `Roll Capture.app` into `~/Applications`.
+Open the app once and grant Screen Recording permission before relying on
+physical screenshots. CI, headless sessions, non-macOS hosts, offline failures,
+sudo/root shells, and `ROLL_SKIP_CAPTURE_INSTALL=1` skip the app install without
+failing npm. If npm ran under sudo/root, run `roll setup` again as a regular user
+so Roll installs the app into that user's `~/Applications`, not `/var/root`.
+GitHub download requests respect `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` when the
+current Node runtime exposes the matching fetch dispatcher.
 
 After installation via either method, run setup to sync conventions and skills into your AI tools:
 
@@ -30,6 +41,10 @@ After installation via either method, run setup to sync conventions and skills i
 roll setup
 ```
 
+`roll setup --no-capture-install` keeps setup from attempting the same Roll
+Capture.app repair. `roll doctor tools` reports whether the app, permission
+proxy, and inbox are ready.
+
 ## Verify
 
 ```bash

package/guide/en/loop.md

@@ -22,6 +22,76 @@ agent bindings.
 Loop runs inside a **tmux session** named `roll-loop-<project-slug>`.
 When not muted, a terminal window pops up automatically so you can watch in real time.
 
+## North Star Readings
+
+`roll status` starts with a one-line North Star summary so the owner can see the
+system trend before reading the rest of the health panel. The row is the compact
+form of `roll north`: autonomy, delivery rate, fix tax, and attribution errors.
+Each value is followed by a status dot; run `roll north` when you need the
+target, trend, and reason text.
+
+`roll north [--json]` reads the last 14 days of runs, events, backlog, card
+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. |
+| 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. |
+
+Machine consumers should use `roll north --json`, which emits
+`roll.north.v1` with the same current values, targets, reasons, and daily
+series used by the terminal panel.
+
+## Failure Attribution and Pauses
+
+Every failed cycle is assigned one of four classes:
+
+| Class | Meaning | Owner action |
+|-------|---------|--------------|
+| `env` | Machine, checkout, auth, network, sandbox, or worktree condition. | Repair the named environment problem, then resume dispatch. |
+| `harness` | A Roll component failed, such as score parsing, attest render, publish, or rescue. | Inspect the component and open a focused FIX when needed. |
+| `card` | The Builder reached the story and failed during actual card work. | Investigate the story, split it, or change routing after reading evidence. |
+| `unknown` | There is not enough envelope evidence to charge a card honestly. | Add a deterministic failure envelope before blaming the card. |
+
+Root-cause counting is by `root_cause_key`, not by card. Repeated `env`,
+`harness`, or `unknown` causes pause dispatch and write a diagnostic snapshot
+under `.roll/loop/diagnostics/`. When the terminal says dispatch is paused,
+open that snapshot first: it includes the class, root cause, recent events, and
+playbook. Fix the named machine or Roll component, then run `roll loop resume`.
+
+If earlier env/harness failures pushed a card into the skip list, rebuild that
+state from the durable evidence:
+
+```bash
+roll loop pardon-skip-list --dry-run
+roll loop pardon-skip-list
+roll loop pardon-skip-list --include-unknown  # also pardons unknown/no-evidence rows
+```
+
+Use `--include-unknown` only after reading the rows; older zero-usage `gave_up`
+entries may be real card failures.
+
+## Builder Isolation and Rescue
+
+During Builder execution the main checkout is physically write-protected. The
+Builder works in its cycle worktree; the shared checkout is treated as a sensor,
+not a scratchpad. Roll releases the write protection when the cycle exits.
+
+If dirty or ahead changes appear in the main checkout anyway, Roll quarantines
+them before continuing:
+
+- dirty files become a `rescue/leaked-*` ref that can be restored with the
+  manifest's `git stash apply <ref>` command;
+- ahead commits become a `rescue/leaked-*` branch that can be restored with the
+  manifest's `git cherry-pick <ref>` command;
+- the manifest is written under `.roll/loop/quarantine/` and records the cycle,
+  story, phase, files, ref, and exact restore command.
+
+Claim the rescued work from the manifest, then reset or resume the loop from a
+clean main checkout.
+
 ## Scheduling
 
 Loop is scheduled via **launchd** (macOS). By default, every hour at a
@@ -193,6 +263,13 @@ roll agent                           # Show scopes, roles, agent pool, and legac
 roll agent list                      # Show agents installed on this machine
 ```
 
+When semantic pick ranking is enabled, `roll loop watch --events` includes a
+`pick:ranked` line such as `picked US-123 (rank 1/5: unblocks the release lane)`.
+`roll supervisor next` and `roll supervisor next --json` show the latest top
+three ranking suggestions and reasons. The ranking is advisory only; Hold, Cut,
+unsatisfied dependencies, skip-list, open PR, merged-delivery, and pending-publish
+gates still decide eligibility.
+
 ### Goal Mode vs Scheduled Mode
 
 `roll loop go` is a manual goal session, not a launchd scheduler tick. While it
@@ -1013,6 +1090,60 @@ This keeps `git worktree list` clean and prevents `.claude/worktrees/` from
 accumulating old entries over time. Active worktrees (branches ahead of `main`)
 are left untouched.
 
+## Main Checkout Guard
+
+During the Builder process, Roll makes the shared main checkout read-only at the
+filesystem boundary while leaving the cycle worktree writable. If a previous
+cycle left product files dirty or local commits ahead of `origin/main`, Roll
+moves that pollution to a `rescue/leaked-*` ref plus a
+`.roll/loop/quarantine/*.json` manifest, restores main to the trusted state, and
+continues the cycle.
+
+The event stream records `sandbox:write_protected` and `sandbox:quarantined`.
+`roll loop watch --events`, `roll loop cycle <id> --activity`, and supervisor output
+surface those facts. Each quarantine manifest includes the ref, file list, and a
+one-line restore command for owner/supervisor recovery.
+
+## Post-cycle Environment Cleanup
+
+Before the cycle worktree is removed, loop runs a declarative environment
+cleanup step. It targets only transient toolchain/scratch artifacts produced
+inside the worktree — e.g. `.scratch`, `tmp`, `node_modules/.cache`, `.vite`,
+`__pycache__`, `.build` — and leaves source files and uncommitted work alone.
+
+Each rule emits a `cycle:cleanup` event to `events.ndjson`, so the cleanup is
+observable and auditable. Cleanup failures are downgraded to warning events,
+also summarized in `ALERT.md` under the independent `harness:env_cleanup` root
+cause, and never block the next cycle.
+
+You can override or extend the default rules by creating
+`.roll/loop/cleanup-manifest.yaml`:
+
+```yaml
+rules:
+  - name: my-scratch
+    kind: rm
+    paths:
+      - .my-tmp
+      - "**/roll-cleanup.log"
+  - name: my-cache
+    kind: isolate
+    paths:
+      - .my-cache
+```
+
+`kind: rm` deletes the path; `kind: isolate` moves it into a cycle-local
+`.roll-cleanup/<cycle-id>/<rule>/` directory inside the worktree (so it is
+removed along with the worktree).
+
+Supported path forms are deliberately small: literal relative paths such as
+`.my-tmp` and recursive suffix matches of the form `prefix/**/literal-suffix`,
+including `**/roll-cleanup.log` or `src/**/__pycache__`. Shell globs are not
+expanded; a `*` inside the recursive suffix, such as `**/*.log`, makes that rule
+invalid, emits a warning, and skips the rule. Use `rules: []` or
+`enabled: false` to disable cleanup explicitly. The default manifest is used
+only when no override file is present.
+
 ## Cycle phases
 
 Every cycle is sliced into seven named phases. Each phase emits a `phase_start`
@@ -1027,7 +1158,7 @@ so the tmux viewer never looks frozen.
 | 3 | `worktree_setup` | fetch origin + worktree create + meta sync | 2 – 10 s |
 | 4 | `agent_invoke` | Agent executes with up to 3 retries | 5 – 45 min |
 | 5 | `publish_push` | push branch + open PR (or doc-only merge) | 5 – 30 s |
-| 6 | `cleanup` | emit PR final state + worktree teardown | < 1 s |
+| 6 | `cleanup` | env cleanup + emit PR final state + worktree teardown | < 1 s |
 
 > **US-AUTO-044**: the main loop exits after opening the PR and **no longer waits for merge**. Merge / rebase / close is handled asynchronously by the dedicated PR Loop (`com.roll.pr.<slug>`, every 5 min); a story with an open PR is skipped by the eligibility gate, so it is neither re-opened nor falsely marked Done.
 

package/guide/en/methodology.md

@@ -590,7 +590,7 @@ It is off by default. Enabling it requires an explicit `roll loop on`.
 
 ### 9.2 Components
 
-**`roll-loop`** — Runs on a configurable schedule via macOS launchd (Linux: crontab). Scans BACKLOG for `📋 Todo` items and routes them: `US-XXX → $roll-build`, `FIX-XXX → $roll-fix`, `REFACTOR-XXX → $roll-build`. Caps items per run to limit blast radius. Rebuilds the generated morning report page from events/runs as it goes. Built-in TCR enforcement: after a story completes, checks for `tcr:` micro-commits — if zero are found, reverts the story to Todo with an ALERT, preventing agents from skipping the TCR rhythm.
+**`roll-loop`** — Runs on a configurable schedule via macOS launchd (Linux: crontab). Scans BACKLOG for `📋 Todo` items and routes them: `US-XXX → $roll-build`, `FIX-XXX → $roll-fix`, `REFACTOR-XXX → $roll-build`. Caps items per run to limit blast radius. Rebuilds the Loop Digest from windowed `events.ndjson` / `runs.jsonl` facts as it goes; contradictory digest data is marked degraded and emits an ALERT instead of being reported as normal. Built-in TCR enforcement: after a story completes, checks for `tcr:` micro-commits — if zero are found, reverts the story to Todo with an ALERT, preventing agents from skipping the TCR rhythm.
 
 **`roll-.dream`** — Runs nightly (03:00 local) via macOS launchd (Linux: crontab). Scans the codebase for dead code, architectural drift against `.roll/domain/`, pruning candidates, and emerging patterns. Outputs `REFACTOR-XXX` entries to BACKLOG and a log to `.roll/dream/YYYY-MM-DD.md`.
 

package/guide/zh/acceptance-evidence.md

@@ -59,6 +59,31 @@ loop_safety:
 soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交付。它是临时兼容口，
 不是默认行为。
 
+合并闸读取结构化证据，不读口头说明。出现以下事实时，交付可能被拒合：
+
+- `attest render` 退出码非零；
+- `ac-map.json` 引用的路径无法在本次 story run 或卡片归档下解析，除非是本仓允许的
+  GitHub PR/commit/check URL；
+- AC 仍是 `claimed`，表示 Builder 只有完成声明，没有 pass/fail 证据；
+- positive AC 没有真实证据引用；
+- 无豁免的可视卡没有截图，也没有记录化的机器采集 skip；
+- 声明了 `deliverable_url`、`deliverable_cmd` 或 `physical_terminal`，但对应
+  surface 没有真实采集；
+- AC 是 `fail`，表示检查执行过并变红。
+
+PR body 会带 `Roll-Evidence` trailer，指向这张 Story 的证据入口。人工评审从这里开始：
+打开验收 Review Page，再沿 AC map 和引用文件检查。
+
+发版前或发现 Done 行可疑时，运行审计命令：
+
+```bash
+roll attest audit
+roll attest audit --json
+```
+
+它会扫描 Done stories，查缺失报告、缺失或空的 `ac-map.json`、悬空证据引用和
+`evidence_debt` 行。无问题退出 0；发现问题退出 1，并列出 story ID 与缺失引用。
+
 ## 红线
 
 **零证据**的 AC 永远不能是 `pass`：渲染层强制降级为 🟧 仅声明，并列入
@@ -68,7 +93,11 @@ soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交
 ## 设计期声明可视证据
 
 `roll story validate` 在设计期就检查一张卡是否**生而诚实**——带可视证据 AC，
-且 web 面要声明可截的产品页。校验器靠两条规则识别：
+且 web 面要声明可截的产品页。若卡有可视证据 AC，但没有声明任何交付面
+（`deliverable_url`、`deliverable_cmd`、`physical_terminal` 或
+`screenshot_exempt`），validate 只打印 must-declare 软警告，仍以 0 退出。
+运行时 gate 也只把同一信号作为诊断携带，不会仅因此阻断或把交付标成 skipped。
+校验器靠两条规则识别：
 
 - **`[visual-evidence]` 标记即定论。** 以字面 `[visual-evidence]` 标记开头的 AC
   条目**本身**就是可视证据 AC，无论后面写什么词——不必再额外写"截图 / screenshot"：
@@ -84,7 +113,10 @@ soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交
     产品页,就该截 web 图；
   - 声明了 `physical_terminal:` ⇒ **terminal**，但合同更严格——报告必须包含从 macOS
     `Terminal.app` 真实屏幕像素截下来的图。headless stdout、transcript 渲染图、
-    HTML replay 图都不能满足这个合同；
+    HTML replay 图都不能满足这个合同。`roll attest` 会在可用时请求
+    `physical.screenshot` provider，把返回的 PNG 复制进本 story 的 run 目录，
+    并在报告里展示 `requested -> taken/skipped/failed/timeout -> attached/not-attached`
+    状态链；
   - 否则声明了 `deliverable_cmd:` ⇒ **terminal**——走终端截屏通道的 CLI 交付；
   - 否则由 AC 文本判定（web / terminal / 含糊）。
 
@@ -122,6 +154,18 @@ evidence、已有证据暴露 rendering/layout 风险；升级原因必须记录
   复现图都不算截图证据。交互式 `Terminal.app` 授权探针一旦成功，会缓存在
   `ROLL_HOME` 下，后续 `roll doctor` / setup 检查不会反复触发 macOS 权限弹窗；
   如果刚刚授权，先重启 Terminal.app 再信任缓存。
+- `Roll Capture.app` / `physical.screenshot` —— 物理截图请求的 provider 通道。
+  就绪度不可用时，`roll attest` 记录带设置原因的 honest skip，不阻断报告生成；
+  provider 超时时，报告把 timeout 作为独立失败原因展示。
+  macOS npm 安装会尝试从 `seanyao/roll-capture` 最新 Release 安装 app 到
+  `~/Applications`；`roll setup` 可重试这条修复路径，除非传入
+  `--no-capture-install`。
+
+  **截图默认策略 (US-PHYSICAL-006)：** 物理截图请求默认使用**窗口级**截取——
+  只截被测应用的窗口（终端/CLI 证据截 Terminal.app，网页证据截 Google Chrome），
+  不再默认全屏。全屏截图必须在卡片 spec 中显式声明 `capture_fullscreen: true`。
+  这个隐私优先的设计防止证据链夹带屏幕上无关的隐私内容（聊天记录、邮件、其他项目）。
+  如果目标窗口找不到，Roll Capture.app 会返回带有原因的降级记录——不允许静默扩大截取范围。
 - `Playwright Chromium` —— 可选的 headless web 截图工具，用于 `roll attest`
   和归档截图。安装命令是 `npx playwright install chromium`。
 

package/guide/zh/configuration.md

@@ -20,6 +20,7 @@ Roll 在启动时解析三个环境变量。在运行 `roll` 之前覆盖任意
 | `ROLL_LOOP_GC_RETENTION_DAYS` | `30` | 覆盖 `roll loop gc` 的保留天数。优先级高于 `.roll/local.yaml` 中的 `loop_gc.retention_days`。 |
 | `ROLL_FEED_BUDGET_BYTES` | `16384` | 每个周期交给内层 agent 的上下文 feed 字节预算。设为正整数即可调节容量；非数字或非正数回落默认值。 |
 | `ROLL_AGENT_NUDGE` | `1`（开启） | 兼容期的 agent 偏好开关。新模型优先通过 scoped role binding 选择候选；设为 `0`（或 `off`/`false`/`no`）关闭历史偏好。 |
+| `ROLL_SKIP_CAPTURE_INSTALL` | 未设置 | 设为 `1` 时，跳过 npm postinstall 和 setup 修复里的 macOS `Roll Capture.app` 尽力安装。 |
 | `ROLL_RUN_DIR` | 未设置 | 验收证据 run 目录的标准入口。loop runner 在 agent 启动前设置；`roll attest --run-dir` 与独立 `roll attest` 也会读取它。 |
 | `ROLL_EVIDENCE_DIR` | 从 `ROLL_RUN_DIR` 派生 | 已打开证据框中的原始命令/测试产物目录。通常由 runner 或 `roll test` 设置，不需要手写。 |
 | `ROLL_SCREENSHOTS_DIR` | 从 `ROLL_RUN_DIR` 派生 | 已打开证据框中的视觉证据目录。通常由 runner 或截图通道设置，不需要手写。 |
@@ -76,6 +77,17 @@ loop_safety:
 只有显式迁移窗口才应使用 `attest_gate: soft`。soft 模式保留审计记录和告警，
 但不阻塞本轮交付。
 
+自动选卡还有一层 advisory 语义排序。它默认开启，也可以显式关闭：
+
+```yaml
+pick:
+  semantic_ranking: off
+```
+
+开启后，Roll 只在 backlog / candidate hash 变化时让默认 agent 排序一次，并把结果
+缓存到 `.roll/loop/pick-ranking.json`；最终仍由既有 picker gates 决定能不能选。
+如果 agent 超时或返回坏 JSON，Roll 记录 `harness_failure` 并回落到确定性顺序。
+
 ## 验证
 
 `roll status` 会打印解析后的路径，便于确认覆盖是否生效；

package/guide/zh/installation.md

@@ -22,7 +22,16 @@ curl -fsSL https://seanyao.github.io/roll/install | ROLL_VERSION=v3.610.1 bash
 npm install -g @seanyao/roll
 ```
 
-需要 Node.js 16+。
+需要 Node.js 22+。
+
+macOS 上，npm 包会在 postinstall 中尽力从 `seanyao/roll-capture` 最新 GitHub
+Release 下载 `Roll-Capture.app.zip`，校验后安装 `Roll Capture.app` 到
+`~/Applications`。使用物理截图前，请打开一次应用并授予 Screen Recording 权限。
+CI、headless、非 macOS、sudo/root shell、离线失败以及
+`ROLL_SKIP_CAPTURE_INSTALL=1` 都会跳过 app 安装，且不会让 npm 安装失败。若 npm
+是在 sudo/root 下运行，请再以普通用户跑 `roll setup` 安装，避免装进
+`/var/root`。当前 Node runtime 暴露对应 fetch dispatcher 时，GitHub 下载请求会遵守
+`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`。
 
 无论哪种方式安装，完成后运行 setup 将约定和技能同步到你的 AI 工具：
 
@@ -30,6 +39,9 @@ npm install -g @seanyao/roll
 roll setup
 ```
 
+`roll setup --no-capture-install` 会禁止 setup 尝试同一套 Roll Capture.app 修复。
+`roll doctor tools` 会报告 app、权限代理和 inbox 是否就绪。
+
 ## 验证
 
 ```bash

package/guide/zh/loop.md

@@ -20,6 +20,67 @@ autonomous，不改变 agent binding。
 Loop 在名为 **`roll-loop-<project-slug>`** 的 **tmux session** 里运行。
 未静音时，终端窗口会自动弹出，你可以实时旁观 AI 干活。
 
+## 北极星读数
+
+`roll status` 顶部先显示一行北极星摘要，让 owner 在读完整健康面板前先看到系统趋势。
+这行是 `roll north` 的压缩版：自主运行时长、交付率、修复税、归因错误。每个值后面
+有状态点；需要目标、趋势和原因时运行 `roll north`。
+
+`roll north [--json]` 读取最近 14 天的 runs、events、backlog、卡片元数据与交付真相。
+四项目标如下：
+
+| 指标 | 目标 | 防应试口径 | `null` 含义 |
+|------|------|------------|-------------|
+| 自主运行时长 | ≥72 小时 | 有效自主日需要至少 6 次非 idle 尝试；backlog 空的日期只停表，不计为未达标时间。 | 暂无足够合格运行历史，或窗口内 backlog 为空。 |
+| 交付率 | ≥60% | 交付按 merge truth 统计，不按 cycle 自报退出码。 | 暂无可作为分母的交付样本。 |
+| 修复税 | <1x | 分母仅统计 US 卡；FIX 工作不能改善自己的比值。 | 窗口内没有 US 卡分母。 |
+| 归因错误 | =0 | `unknown` 不猜成 env、harness 或 card；缺失 envelope 保持可见。 | 暂无归因样本。 |
+
+脚本消费用 `roll north --json`，它输出 `roll.north.v1`，字段与终端面板使用的当前值、
+目标、原因和每日序列一致。
+
+## 失败归因与暂停
+
+每个失败 cycle 都归到四类之一：
+
+| 类别 | 含义 | owner 动作 |
+|------|------|------------|
+| `env` | 机器、checkout、auth、network、sandbox 或 worktree 条件。 | 修复点名的环境问题，再恢复派工。 |
+| `harness` | Roll 组件失败，例如 score 解析、attest render、publish 或 rescue。 | 检查对应组件，必要时开聚焦 FIX。 |
+| `card` | Builder 已进入 story，并在真实卡片工作中失败。 | 读证据后调查 story、拆卡或调整路由。 |
+| `unknown` | 没有足够 envelope 证据诚实归因给卡片。 | 先补确定性失败 envelope，再考虑归因。 |
+
+根因计数按 `root_cause_key`，不是按卡片。同一个 `env`、`harness` 或 `unknown`
+根因反复出现时，Roll 会暂停派工，并在 `.roll/loop/diagnostics/` 写诊断快照。
+终端提示派工暂停时，先打开快照：里面有归因类别、根因、最近事件和 playbook。
+修复点名的机器或 Roll 组件后，再运行 `roll loop resume`。
+
+如果早先的 env/harness 失败把卡片错误推入 skip list，可以从持久证据重建：
+
+```bash
+roll loop pardon-skip-list --dry-run
+roll loop pardon-skip-list
+roll loop pardon-skip-list --include-unknown  # 同时平反 unknown/no-evidence 行
+```
+
+`--include-unknown` 只应在读过记录后使用；较早的零用量 `gave_up` 行可能是真实 card 失败。
+
+## Builder 隔离与救援区
+
+Builder 执行期间，主 checkout 会被物理写保护。Builder 在自己的 cycle worktree 中工作；
+共享 checkout 是传感器，不是草稿区。cycle 退出时 Roll 会释放写保护。
+
+如果 dirty 或 ahead 改动仍然出现在主 checkout，Roll 会先隔离再继续：
+
+- dirty 文件写成 `rescue/leaked-*` ref，可按 manifest 里的
+  `git stash apply <ref>` 还原；
+- ahead commits 写成 `rescue/leaked-*` 分支，可按 manifest 里的
+  `git cherry-pick <ref>` 还原；
+- manifest 写在 `.roll/loop/quarantine/`，记录 cycle、story、phase、文件列表、
+  ref 和精确还原命令。
+
+按 manifest 认领隔离内容，然后把主 checkout 恢复干净，再恢复 loop。
+
 ## 调度配置
 
 Loop 通过 **launchd**（macOS）调度。默认每小时在一个根据项目路径推导出的分钟触发
@@ -172,6 +233,12 @@ roll agent                           # 查看 scope、role、agent pool 与 lega
 roll agent list                      # 查看本机已装的 agent
 ```
 
+开启语义选卡排序时，`roll loop watch --events` 会显示 `pick:ranked` 行，例如
+`picked US-123 (rank 1/5: unblocks the release lane)`。`roll supervisor next` 和
+`roll supervisor next --json` 会展示最近一次 top3 排序建议与理由。该排序只作建议；
+Hold、Cut、未满足依赖、skip-list、open PR、已合并交付和 pending-publish gate 仍决定
+卡片是否可选。
+
 ### Goal Mode 与定时模式
 
 `roll loop go` 是手动 goal session，不是 launchd 定时 tick。运行期间 Roll 会持有
@@ -897,6 +964,54 @@ API key secret — 你配置的 agent 对应的那个。
 这样可以保持 `git worktree list` 干净，防止 `.claude/worktrees/` 随时间积累。
 分支仍领先于 `main` 的活跃 worktree 不受影响。
 
+## 主 checkout 保护
+
+Builder 进程运行期间，Roll 会在文件系统边界把共享主 checkout 设为只读，
+同时保持 cycle worktree 可写。如果上一轮 cycle 把产品文件留脏，或让本地
+`main` 领先 `origin/main`，Roll 会把污染物移入 `rescue/leaked-*` ref 和
+`.roll/loop/quarantine/*.json` 清单，随后把主 checkout 恢复到可信状态并继续
+本轮 cycle。
+
+事件流会记录 `sandbox:write_protected` 和 `sandbox:quarantined`。
+`roll loop watch --events`、`roll loop cycle <id> --activity` 和 supervisor 输出都会
+展示这些事实。每个 quarantine 清单都包含 ref、文件列表，以及供 owner /
+supervisor 认领恢复的一行命令。
+
+## Cycle 结束后环境清理
+
+在拆除 cycle worktree 之前，loop 会先执行一次声明式的环境清理。它只清理
+worktree 内部产生的临时/工具链缓存产物——例如 `.scratch`、`tmp`、
+`node_modules/.cache`、`.vite`、`__pycache__`、`.build`——不会触碰源码和
+未提交的改动。
+
+每条规则都会向 `events.ndjson` 写入一条 `cycle:cleanup` 事件，因此清理过程
+可观测、可审计。清理失败会降级为 warning 事件，同时汇总写入 `ALERT.md`，
+并按独立的 `harness:env_cleanup` 根因计数；它不会阻塞下一轮 cycle。
+
+你可以通过 `.roll/loop/cleanup-manifest.yaml` 覆盖或扩展默认规则：
+
+```yaml
+rules:
+  - name: my-scratch
+    kind: rm
+    paths:
+      - .my-tmp
+      - "**/roll-cleanup.log"
+  - name: my-cache
+    kind: isolate
+    paths:
+      - .my-cache
+```
+
+`kind: rm` 删除目标；`kind: isolate` 把目标移进 worktree 内的
+`.roll-cleanup/<cycle-id>/<rule>/`（随 worktree 一起被删除）。
+
+支持的路径形态刻意很小：字面相对路径，例如 `.my-tmp`；以及
+`prefix/**/literal-suffix` 形式的递归后缀匹配，例如 `**/roll-cleanup.log`
+或 `src/**/__pycache__`。不会展开 shell glob；递归后缀里包含 `*`（例如
+`**/*.log`）会让该规则无效，记录 warning，并跳过该规则。用 `rules: []`
+或 `enabled: false` 可以显式关闭 cleanup。只有没有覆盖文件时才使用默认清单。
+
 ## 阶段计时（Cycle phases）
 
 每轮 cycle 在内部切成七个命名阶段。每个阶段进入时 emit `phase_start`，
@@ -910,7 +1025,7 @@ PR 等合并）每 30–60s 还会 emit 一次 `phase_tick` 心跳，tmux 不再
 | 3 | `worktree_setup` | fetch origin + 建 worktree + 同步 meta | 2 – 10 秒 |
 | 4 | `agent_invoke` | 调起 agent（最多三次重试） | 5 – 45 分钟 |
 | 5 | `publish_push` | push 分支 + 建 PR（doc-only 直接合） | 5 – 30 秒 |
-| 6 | `cleanup` | 落 PR 终态 + 拆 worktree | < 1 秒 |
+| 6 | `cleanup` | 环境清理 + 落 PR 终态 + 拆 worktree | < 1 秒 |
 
 > **US-AUTO-044**:主 loop 开完 PR 即退,**不再等合并**。合并 / rebase / 关 PR 交给专职 PR Loop（`com.roll.pr.<slug>`,每 5 分钟）异步处理;有 open PR 的 story 由资格闸跳过,不会重复开,也不会假 Done。
 

package/lib/i18n/init.sh

@@ -46,8 +46,8 @@ _i18n_set en init.plan_validation_failed_see_errors_above "Plan validation faile
 _i18n_set zh init.plan_validation_failed_see_errors_above "校验失败。"
 _i18n_set en init.applying_onboard_plan "Applying onboard plan..."
 _i18n_set zh init.applying_onboard_plan "正在应用 onboard 计划..."
-_i18n_set en init.added_roll_to_gitignore "Added .roll/ to .gitignore"
-_i18n_set zh init.added_roll_to_gitignore "已将 .roll/ 加入 .gitignore"
+_i18n_set en init.added_roll_to_gitignore "Added Roll runtime ignores to .gitignore"
+_i18n_set zh init.added_roll_to_gitignore "已将 Roll 运行时忽略项加入 .gitignore"
 _i18n_set en init.syncing_conventions_to_ai_tools "Syncing conventions to AI tools..."
 _i18n_set zh init.syncing_conventions_to_ai_tools "正在同步约定到 AI 工具..."
 _i18n_set en init.onboard_apply_complete_onboard "Onboard apply complete.  Onboard"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.702.4",
+  "version": "4.706.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {
@@ -10,6 +10,7 @@
     "test:e2e": "pnpm -r build && pnpm --filter @roll/cli exec vitest run test/critical-flows.e2e.test.ts",
     "test:cov": "pnpm -r exec vitest run --coverage.enabled --coverage.provider=v8 --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=text",
     "bundle": "node scripts/bundle.mjs",
+    "postinstall": "node scripts/postinstall-roll-capture.mjs",
     "prepack": "pnpm -r build && pnpm bundle"
   },
   "keywords": [
@@ -35,6 +36,7 @@
     "docs/",
     "guide/",
     "lib/",
+    "scripts/postinstall-roll-capture.mjs",
     "skills/",
     "template/",
     "README.md",