@seanyao/roll 4.714.2 → 4.717.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,26 @@ 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.

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,8 +388,11 @@ 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.
+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 the first builder cycle, `roll loop go` also has a fallback check for
 leftover uncommitted Roll bootstrap artifacts such as `AGENTS.md`, `.claude/`,
@@ -419,9 +496,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 +736,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 +1577,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/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，

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 会明确失败，不会悄悄启用第二套配置模型。
 
 ## 另见