@seanyao/roll 4.703.2 → 4.707.1

package/docs/architecture.md

@@ -131,6 +131,11 @@ no-TCR/gave-up、成功交付、成本档位和角色能力标签排序。运行
 [--json]` 暴露 route trace：候选池、ranked score/reasons、warnings、skipped 候选及原因、策略、
 近期使用输入、最终 agent 和 source 配置路径。
 
+**Rig lifecycle**：quota、auth、network 和 agent stall 是运行级状态，不回写
+`agents.yaml`。loop 把不可用 rig 写入 runtime lifecycle 文件并发出 `rig:suspended` /
+`rig:recovered` 事件；挂起 rig 按恢复窗口轻量探活，恢复后自动回到候选池。若当前池全挂起，
+cycle 写 `loop:pending`，只做恢复探测，不启动 Builder、不把卡记失败、不触发全局熔断。
+
 **反规则**：不因历史表现自动改写角色绑定。不做失败后的静默跨 agent 重试。指标可以*建议*
 策略变更，但绝不绕过 human-on-the-loop。
 

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

@@ -40,8 +40,8 @@ the archive rebuild; they are a convenience/archive view, not the delivery-truth
    into `ROLL_EVIDENCE_DIR`; visual lanes write screenshots into
    `ROLL_SCREENSHOTS_DIR` when the surface requires inspection. The agent keeps
    `ac-map.json` in the story card root, mapping each AC to the evidence files
-   that support it, with a status per AC: `pass` · `readonly` · `partial` ·
-   `claimed` · `missing`.
+   that support it, with a status per AC: `pass` · `pass-with-evidence` ·
+   `readonly` · `partial` · `claimed` · `missing`.
 3. Close with the hard attest gate. The runner calls
    `roll attest <story-id> --run-dir "$ROLL_RUN_DIR"` at the end of delivery.
    `roll attest` sweeps the hard facts (TCR commits, latest CI run, optional
@@ -75,7 +75,10 @@ when any of these facts are true:
   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;
+- an AC remains `needs-confirmation`, which means the harness draft still needs
+  Builder review;
+- a positive AC (`pass`, `pass-with-evidence`, `readonly`, or `partial`) 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`
@@ -99,14 +102,21 @@ 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
-down to 🟧 Claimed and lists it under **Discrepancies**. Verbal completion
-("I confirmed it works") is exactly what this rules out.
+An AC with **zero evidence** can never claim `pass` or `pass-with-evidence`: the
+renderer forces it down to 🟧 Claimed and lists it under **Discrepancies**.
+`pass-with-evidence` is a harness-confirmed status backed by strong on-disk
+evidence; it is explicitly not the same as an agent-confirmed `pass`. Verbal
+completion ("I confirmed it works") is exactly what this rules out.
 
 ## Declaring visual evidence at design time
 
 `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
@@ -179,6 +189,19 @@ at startup:
   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. |

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

@@ -390,10 +390,13 @@ defaults:
 candidate pool, runtime health notes, and any legacy compatibility inputs. Use
 `roll agent migrate --dry-run` to preview conversion from old agent files.
 
-Runtime health is not static policy. Auth, network, VPN, account, or missing
-binary failures skip a candidate for the current resolution and are recorded as
-runtime facts. If no candidate remains, loop pauses and writes an ALERT instead
-of silently rewriting the pool.
+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
+runtime facts; Roll does not rewrite `agents.yaml`. Suspended rigs are probed on
+the recovery interval and return to the pool automatically when reachable. If no
+candidate remains, the cycle records `loop:pending` and only runs recovery probes
+instead of starting a Builder, charging the card's failure budget, or silently
+rewriting the pool.
 
 For open casting, `health-aware` ranks the same visible pool across Builder,
 Designer, Evaluator, and Peer Reviewer roles. `roll supervisor route --role

package/guide/zh/acceptance-evidence.md

@@ -35,7 +35,7 @@ HTML。那些归档页想看时用 归档重建 按需渲染，它们是便捷/
 2. 过程采集。`roll test` 把命令输出和摘要写入 `ROLL_EVIDENCE_DIR`；需要视觉
    验收的端面把截图写入 `ROLL_SCREENSHOTS_DIR`。agent 在故事卡根目录维护
    `ac-map.json`，把每条 AC 映射到支撑证据，并标注状态：`pass` ·
-   `readonly` · `partial` · `claimed` · `missing`。
+   `pass-with-evidence` · `readonly` · `partial` · `claimed` · `missing`。
 3. 收尾硬闸。交付结束时 runner 调用
    `roll attest <story-id> --run-dir "$ROLL_RUN_DIR"`。`roll attest` 清扫硬事实
    （TCR commits、最新 CI、可选部署探针、test-pass 凭证），渲染验收 Review Page，把
@@ -65,7 +65,8 @@ soft 模式会记录缺口并发出同一类审计信号，但不阻塞本轮交
 - `ac-map.json` 引用的路径无法在本次 story run 或卡片归档下解析，除非是本仓允许的
   GitHub PR/commit/check URL；
 - AC 仍是 `claimed`，表示 Builder 只有完成声明，没有 pass/fail 证据；
-- positive AC 没有真实证据引用；
+- AC 仍是 `needs-confirmation`，表示 harness 草稿还没被 Builder 处理；
+- positive AC（`pass`、`pass-with-evidence`、`readonly` 或 `partial`）没有真实证据引用；
 - 无豁免的可视卡没有截图，也没有记录化的机器采集 skip；
 - 声明了 `deliverable_url`、`deliverable_cmd` 或 `physical_terminal`，但对应
   surface 没有真实采集；
@@ -86,14 +87,19 @@ roll attest audit --json
 
 ## 红线
 
-**零证据**的 AC 永远不能是 `pass`：渲染层强制降级为 🟧 仅声明，并列入
-**Discrepancies（证据缺口）**附录。"我确认它能跑"这类口头完成，正是被这条
-红线挡住的东西。
+**零证据**的 AC 永远不能是 `pass` 或 `pass-with-evidence`：渲染层强制降级为
+🟧 仅声明，并列入 **Discrepancies（证据缺口）**附录。`pass-with-evidence`
+表示 harness 基于硬盘上强证据做出的确认，明确不同于 agent 亲自确认的 `pass`。
+"我确认它能跑"这类口头完成，正是被这条红线挡住的东西。
 
 ## 设计期声明可视证据
 
 `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"：
@@ -153,6 +159,15 @@ evidence、已有证据暴露 rendering/layout 风险；升级原因必须记录
 - `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 或截图通道设置，不需要手写。 |

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

@@ -343,9 +343,10 @@ defaults:
 以及 legacy compatibility 输入。用 `roll agent migrate --dry-run` 预览旧 agent
 文件迁移。
 
-运行时健康不是静态策略。auth、网络、VPN、账号或 binary 缺失只会让候选在本次
-resolution 中被跳过，并记录为运行时事实。若没有候选可用，loop 会 PAUSE + ALERT，
-而不是悄悄改写静态 pool。
+运行时健康不是静态策略。quota、auth、网络、VPN、账号、stall 或 binary 缺失只会
+挂起运行态 rig，并记录为运行时事实；Roll 不回写 `agents.yaml`。挂起 rig 按恢复窗口
+轻量探活，恢复后自动回到候选池。若没有候选可用，cycle 记录 `loop:pending`，只做
+恢复探测，不启动 Builder、不记入卡的失败账，也不悄悄改写静态 pool。
 
 ### Agent 工具链健康检查（US-V4-022）
 

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.703.2",
+  "version": "4.707.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",

package/scripts/postinstall-roll-capture.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+try {
+  await import("../dist/postinstall.mjs");
+} catch (error) {
+  // The source checkout may not have been bundled yet. Published tarballs carry
+  // dist/postinstall.mjs; either way npm install must never fail here.
+  const reason = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`postinstall skipped: ${reason}\n`);
+}