@seanyao/roll 4.714.2 → 4.717.2

package/guide/zh/faq.md

@@ -557,6 +557,46 @@ roll loop reset
 更细的操作话题（pause/resume、切换 agent、gh scope 等）见
 [loop.md](loop.md) 和 [configuration.md](configuration.md)。
 
+### C5b. `roll loop on` 报 launchd bootstrap 错误怎么办？
+
+**简答：** 此时排程未激活。优先修复 launchd；实在修不好再使用 owner
+明示确认的进程 fallback。
+
+**原因：** macOS launchd 有时会以 `Bootstrap failed: 5: Input/output error`
+（或类似域错误）拒绝 bootstrap。Roll 会重试一次、用 `launchctl print`
+验证挂载，若仍失败就以非零码退出，不会假装调度器已启用。
+
+**先修 launchd：**
+
+```bash
+UID=$(id -u)
+LABEL=$(launchctl list | awk '$3 ~ /^com\.roll\.loop\./ {print $3; exit}')
+# 如果 launchctl list 没有输出，请使用错误信息里的精确 label。
+launchctl bootout gui/$UID/$LABEL
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/$LABEL.plist
+launchctl print gui/$UID/$LABEL
+roll loop on
+roll loop status
+```
+
+**如果 launchd 无法修复：**
+
+```bash
+roll loop fallback start --confirm
+roll loop fallback status
+```
+
+fallback 不是 launchd 的等价替代，不会跨过重启/登出。重启或重新登录后
+必须重新确认：
+
+```bash
+roll loop fallback stop
+roll loop fallback start --confirm
+```
+
+脱敏、无需 root 的现场验证流程见
+[从 launchd bootstrap 失败中恢复](loop.md#从-launchd-bootstrap-失败中恢复)。
+
 ### C7. 改了 loop_schedule 但 loop 还是按旧频次跑
 
 **症状：** 更新了 `.roll/local.yaml` 的 `loop_schedule`，但 `roll loop status`
@@ -772,3 +812,25 @@ gh issue create --title "Safari 上登录失败" --body "复现步骤: ..."
 这些控制只影响用户可见表面。Agent 契约、代码、git 元数据和 schema 保持英文；
 与 owner 的对话跟随当前任务里 owner 使用的语言。发版前可运行
 `roll doctor language` 审计文档、约定、skills 与生成表面的语言漂移。
+
+### C12. `roll browser interactive` 有什么限制？
+
+**短答：** 它是一个面向本地 Chrome 调试端点的前台、owner 运行、单次操作工具——
+不是后台自动化，也不是远程浏览器。
+
+**细节：** `roll browser interactive` 要求：
+
+- 已连接的 TTY 和每次操作的显式 owner 批准。
+- 你自己用 loopback 调试端口启动的 Chrome，例如 `127.0.0.1` 上的
+  `--remote-debugging-port=9222`。
+
+它**永远不会**：
+
+- 从后台调度器或 CI 作业中运行。
+- 连接远程或非 loopback 端点。
+- 导出 cookie、storage 或 network bodies。
+- 自动启动 Chrome。
+- 独自让 CI 通过——结果仅用于 **owner-run manual-attest**。
+
+租约最多 15 分钟，操作结束后立即释放。无人值守诊断请用受管通道
+（`roll browser run`）。

package/guide/zh/loop.md

@@ -31,7 +31,7 @@ Loop 在名为 **`roll-loop-<project-slug>`** 的 **tmux session** 里运行。
 
 | 指标 | 目标 | 防应试口径 | `null` 含义 |
 |------|------|------------|-------------|
-| 自主运行时长 | ≥72 小时 | 有效自主日需要至少 6 次非 idle 尝试；backlog 空的日期只停表，不计为未达标时间。 | 暂无足够合格运行历史，或窗口内 backlog 为空。 |
+| 自主运行时长 | ≥72 小时 | `current` 是声明的 14 天窗口内合格每日小时之和，而不是最近一段未中断时长。有效自主日需要至少 6 次非 idle 尝试；backlog 空的日期只停表，不计为未达标时间。 | 暂无足够合格运行历史，或窗口内 backlog 为空。 |
 | 交付率 | ≥60% | 交付按 merge truth 统计，不按 cycle 自报退出码。 | 暂无可作为分母的交付样本。 |
 | 修复税 | <1x | 分母仅统计 US 卡；FIX 工作不能改善自己的比值。 | 窗口内没有 US 卡分母。 |
 | 归因错误 | =0 | `unknown` 不猜成 env、harness 或 card；缺失 envelope 保持可见。 | 暂无归因样本。 |
@@ -97,6 +97,77 @@ Loop 通过 **launchd**（macOS）调度。默认每小时在一个根据项目
 验证任务确实存活。如果 launchd 仍拒绝任务，命令会以非零码退出，并打印准确的
 域、标签、plist 路径和可直接执行的诊断命令；bootstrap 失败不会再伪装成已启用。
 
+### 从 launchd bootstrap 失败中恢复
+
+`roll loop on` 失败后，排程处于**未激活**状态。`~/Library/LaunchAgents/`
+里的 plist 文件存在并**不**代表自主排程已启用——只有 `launchctl list`
+显示对应 label 已加载，loop 才是真正就绪的。请用 `roll loop status` 查看
+当前生效后端（`launchd`、`process-fallback` 或 `none`）。
+
+**优先修复 launchd。** 错误输出已经打印了精确命令，通用形式使用
+`launchctl list` 返回的 label：
+
+```bash
+UID=$(id -u)
+LABEL=$(launchctl list | awk '$3 ~ /^com\.roll\.loop\./ {print $3; exit}')
+# 如果 launchctl list 没有输出，请使用 roll loop on 错误信息里的精确 label。
+launchctl bootout gui/$UID/$LABEL
+launchctl bootstrap gui/$UID ~/Library/LaunchAgents/$LABEL.plist
+launchctl print gui/$UID/$LABEL
+roll loop status
+```
+
+如果 `launchctl bootstrap` 成功且 `print` 显示任务存活，再次运行
+`roll loop on` 以重新生成当前 runner 并确认调度。
+
+**如果 launchd 实在无法修复**，Roll 提供一个需要 owner 明示确认的进程
+fallback，只有显式确认时才会启动：
+
+```bash
+roll loop fallback start --confirm
+roll loop fallback status
+roll loop fallback stop        # 不再需要时停止
+```
+
+该 fallback **不是** launchd 的等价替代：它不会跨过重启或登出会话。
+重启或重新登录后，必须先停止旧 lease 再重新确认：
+
+```bash
+roll loop fallback stop
+roll loop fallback start --confirm
+```
+
+优先修复 launchd；仅在 launchd 不可用时使用 fallback。
+
+#### macOS 现场验证流程（Bootstrap failed: 5）
+
+当 `roll loop on` 报 `Bootstrap failed: 5: Input/output error` 这类错误时，
+记录一份已脱敏、无需 root 的诊断包：
+
+```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 lane）:"
+  launchctl list | grep com.roll\. || true
+  echo "---"
+  echo "磁盘上的 plist:"
+  ls -1 ~/Library/LaunchAgents/com.roll.loop.*.plist 2>/dev/null || true
+} > "$OUT"
+# 分享前脱敏：把真实 home 路径替换为 ~。
+sed -i.bak "s|$HOME|~|g" "$OUT" && rm -f "$OUT".bak
+```
+
+该流程只使用用户级（`gui/<uid>`）launchctl 命令，不需要 `sudo`，也不依赖
+`launchctl dumpstate` 等仅限 root 的诊断。
+
 ## 配置调度（Configuring the schedule）
 
 不用再手工编辑 `~/.roll/config.yaml` 和 `.roll/local.yaml` 再祈祷 launchd plist 能 reload 上。改用 `roll config` 命令族：每次写入都落到正确的 yaml 文件，**并且**自动重生 runner、重 bootstrap launchd plist、立刻在 `roll loop status` 反映——没有手工 reload 这一步。
@@ -235,7 +306,7 @@ roll loop gc --keep-days 14   # 覆盖保留天数（也可用 .roll/local.yaml
 roll loop events      # 显示最近 20 条 cycle 事件
 roll loop events 50   # 显示最近 50 条
 
-roll agent                           # 查看 scope、role、agent pool 与 legacy 输入
+roll agent                           # 查看 scope、有效项目能力与 agent pool
 roll agent list                      # 查看本机已装的 agent
 ```
 
@@ -275,8 +346,10 @@ paused 状态时不建议直接启动：`PAUSE-<slug>` 标记仍会在 cycle 边
 预算与运行上限每次 `roll loop go` 都是显式的。`--budget`、`--max-cycles`、`--for`
 只对本次调用生效；省略某项即代表本轮不设该限制——Roll 绝不从上一次会话持久化的
 goal 静默沿用预算或上限，因此一条不带 flag 的 `roll loop go` 既不会被几天前设的
-上限封顶，也不会被它卡死。范围（`--epic`/`--cards`）与 `--review` 在省略时仍沿用，
-因为它们是 goal 的身份，而不是每次运行的安全旋钮。
+上限封顶，也不会被它卡死。范围（`--epic`/`--cards`）与 `--review` 只会在 goal 尚未
+结束时于省略 flag 后沿用。goal 已 `complete` 时，下一次 `roll loop go` 会将它归档到
+`.roll/loop/goal-archive/`、记录 `goal:archived`，并完全按本次 flags 新建 goal；不带
+scope flag 则覆盖全部合格 backlog 卡，绝不会静默沿用已完成 goal 的范围。
 
 `roll loop go` 的安全闸只在 cycle 边界生效。`--budget <usd>` 使用有效成本账本；
 达到预算时 goal 进入 `budget_limited`。未执行 agent 的 idle 或 aborted 周期记为
@@ -365,9 +438,11 @@ defaults:
         strategy: health-aware
 ```
 
-`roll agent` 会显示 Machine Scope、Project Scope、已解析角色、候选池、运行时健康说明，
-以及 legacy compatibility 输入。用 `roll agent migrate --dry-run` 预览旧 agent
-文件迁移。
+`roll agent` 会显示 Machine Scope 和有效 Project Scope，包括继承后的 agent 与已配置的
+route model；它不会预测下一次角色分配。dispatch 会在 spawn 时依据运行时健康和
+least-recent 状态决策。需要诊断快照时使用
+`roll supervisor route --role builder|evaluator`。用 `roll agent migrate --dry-run`
+预览一次性迁移；正常执行不会读取旧 agent 配置。
 
 运行时健康不是静态策略。quota、auth、网络、VPN、账号、stall 或 binary 缺失只会
 挂起运行态 rig，并记录为运行时事实；Roll 不回写 `agents.yaml`。挂起 rig 按恢复窗口
@@ -564,6 +639,10 @@ Gate 或 owner 需要介入，因为普通接力没有干净完成。`terminus`
 
 `roll loop status` 输出一个紧凑的仪表盘，包含每个 cycle 的行记录和每日汇总。
 
+当当前所有可派工卡都需要物理终端截图且 macOS 已锁屏时，状态行会显示“等待屏幕解锁”。
+这属于等待态，不是 idle 失败：下一次探测到解锁的 tick 会清除提示并正常派工，且不会消耗
+no-progress 熔断次数。
+
 ### Token 列
 
 每条 cycle 行的 token 用量以 4 分量格式显示：
@@ -1270,3 +1349,7 @@ Since Phase 2.0, loop state lives inside the project at `<project>/.roll/loop/`.
 plist——旧版本退役的形态(ci/alert/brief)曾以僵尸身份指着已删除的引擎存活数周。
 `roll doctor` 列出本机全部 `com.roll.*` 任务及其目标目录与加载状态;目标目录
 已不存在的 lane 标红 STALE。
+
+bootstrap 失败后留在磁盘上的 plist，或者手动 `bootout` 后残留的 plist，
+**不**等于 loop 已激活。请始终依据 `roll loop status`（有效后端）和
+`launchctl list` 来判断，而不是仅看 `.plist` 文件是否存在。

package/guide/zh/pairing.md

@@ -15,7 +15,7 @@ Roll 把评审指派看成 scoped Agent 模型里的 `evaluate` 角色：
 
 ```bash
 roll agent                         # 查看 story.evaluate
-roll agent migrate --dry-run       # 如有旧 pairing.yaml，预览迁移
+roll agent migrate --dry-run       # 预览旧 agent 配置的一次性迁移
 ```
 
 新项目应在 `.roll/agents.yaml` 里声明 evaluator pool：
@@ -34,9 +34,8 @@ defaults:
         strategy: health-aware
 ```
 
-`.roll/pairing.yaml` 仍是 legacy compatibility 输入；两者同时存在时优先使用 scoped
-`evaluate` role。静态配置列公平候选，auth/network/VPN/account 等运行时失败只在本次
-resolution 中跳过候选。
+`.roll/pairing.yaml` 不再是运行时输入；scoped `evaluate` role 是结对候选的唯一来源。
+静态配置列公平候选，auth/network/VPN/account 等运行时失败只在本次 resolution 中跳过候选。
 
 ## 看它做了什么 —— 可观测性
 

package/guide/zh/tools.md

@@ -79,6 +79,17 @@ tools:
 
 未知字段会告警但不会拒绝整个 policy 文件，方便新旧版本之间前向兼容。
 
+## Owner Chrome：手动交互通道
+
+`roll browser interactive` 是一次性的、owner 手动运行边界：它只会连接已经开启的 loopback Chrome DevTools 端点，执行一个 typed 低风险动作。每次运行都必须附着 TTY，并重新输入 `y` 批准；提示会列出故事、批准的 origin、动作摘要、最长 15 分钟的过期时间和“禁止凭据导出”。
+
+```text
+roll browser interactive --story US-BROW-008b --origin https://app.example.test \
+  --action navigate --url https://app.example.test/account
+```
+
+它只连接 origin 与 `--origin` 匹配的 tab，并会在批准过期、取消、错误或进程退出时断开 DevTools。Roll 不会启动或关闭 owner 的 Chrome。封闭动作词表只有 `navigate`、`click`、`fill` 和 `press_key`；cookie、storage 和 network body 没有 CLI 或 adapter 表面。交互成功只是手动证据，不会让 CI 通过，也不会变成后台自动化。
+
 ## CLI
 
 用 `roll doctor tools status` 查看当前项目已注册工具、输入契约、依赖就绪度和合成后的有效 policy 状态。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.714.2",
+  "version": "4.717.2",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {
@@ -8,6 +8,7 @@
     "lint:story-ids": "node scripts/lint-story-ids.mjs",
     "lint:role-taxonomy": "node scripts/audit-role-taxonomy.mjs",
     "test:e2e": "pnpm -r build && pnpm --filter @roll/cli exec vitest run test/critical-flows.e2e.test.ts",
+    "test:browser-live": "pnpm -r build && ROLL_BROWSER_LIVE=1 pnpm --filter @roll/cli exec vitest run --config vitest.live.config.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",

package/skills/roll-build/SKILL.md

@@ -34,7 +34,7 @@ same TCR, evidence, Evaluator, and release gates apply in both modes.
 2. Read backlog/spec and decide if the story fits one cycle.
 3. Split into small TCR actions; per Action route objective work to the 4-stage TCR loop and judgment-dependent work to a 3-stage criteria+Evaluator loop, then define verification.
 4. Run test-first implementation, self-review, evidence, and write-back.
-5. Commit on green, open PR, and leave remote evidence.
+5. Commit green TCR work, then hand off publishing and remote evidence to the Runner.
 
 ## Hard Gates
 
@@ -42,6 +42,7 @@ same TCR, evidence, Evaluator, and release gates apply in both modes.
 - No WIP commits or bypassed verification.
 - In the test-gated loop the tests are the weakest link: an isolated Test Adequacy reviewer (Phase 6 Agent 4) audits the tests against the AC, seeing only AC + test files — never the implementation diff or builder reasoning. Self-review of one's own tests (Phase 2) is necessary but not isolation.
 - Self-review, attest, and E2E evidence remain required. The Review Score is produced by the runner's fresh-session peer Reviewer — the agent does NOT self-score.
+- Inside a `roll-loop` cycle, never run `git push` or `gh pr create`; the Runner owns branch publication and PR creation after the gates pass.
 - Docs/code/product alignment is a DoD gate: user-visible behavior, command, output-copy, site, or delivery-view changes update the touched README/docs/guide/site/help in the same delivery.
 - Done ≡ merged to `main`. After publish the cycle is `awaiting_merge`; the Delivery Reconciler (no daemon) self-drives the merge and reconciles truth from `main` — manual merges are first-class (`delivered_external`). Never pre-flip a card to Done on an open PR.
 

package/skills/roll-build/references/full-contract.md

@@ -579,15 +579,17 @@ the full diff as a single-pass fallback — do not skip review entirely.
 🟢 Suggestions / ✅ All clear → Proceed to Phase 7
 ```
 
-### Phase 7: Commit & Push (branch + PR — NEVER direct to main)
+### Phase 7: Commit & Publish Handoff
 
-`main` is PR-protected. Push the worktree's branch and open a PR — never
-`git push origin main`. (When invoked by `roll-loop`, the runner already
-created the worktree + branch and opens the PR; this is the manual-path
-equivalent.)
+`main` is PR-protected. In a standalone guided session, push the worktree's
+branch and open a PR — never `git push origin main`. Inside a `roll-loop`
+cycle, stop after the green commits and evidence: the Runner publishes the
+branch and opens the PR after its gates pass. Do not run `git push` or
+`gh pr create` inside the Builder session.
 
 ```bash
-# All TCR micro-commits are already made on the worktree's branch (step A3.1).
+# Standalone guided session only. All TCR micro-commits are already made on
+# the worktree's branch (step A3.1).
 git log --oneline -{n}                 # Review TCR commits
 git push -u origin <branch>            # the dispatch/<id> branch from step A3.1
 gh pr create --title "{story-id}: …" --body "…"
@@ -761,12 +763,13 @@ delivered. Consequences you can rely on:
   PR-state (L1) / patch-id (L2) and flips the cycle to `delivered` — manual /
   external merges included (`delivered_external` is first-class).
 
-So on the manual path, flip the row to Done **after** the PR merges; under
-`roll-loop` the cycle ends at publish (`awaiting_merge`) and the reconciler
+So on the manual path, flip the row to Done **after** the PR merges. Under
+`roll-loop`, the Builder must not edit shared `.roll` completion status at
+all: the cycle ends at publish (`awaiting_merge`) and the reconciler
 self-drives the merge (`gh pr merge --squash` on green CI) and flips the row
 once the merge lands on `main` — do not pre-flip on a still-open PR.
 
-Both locations must be updated — neither can be skipped:
+On the manual path, both locations must be updated — neither can be skipped:
 
 **① Update .roll/backlog.md index row (Status column):**
 
@@ -777,7 +780,7 @@ Both locations must be updated — neither can be skipped:
 | [US-{ID}](.roll/features/<epic>/US-{ID}/spec.md) | {Title} | ✅ Done · [evidence](.roll/features/<epic>/US-{ID}/latest/US-{ID}-report.html) |
 ```
 
-Change the Status from `📋 Todo` or `🔨 In Progress` (whichever the row currently shows) to `✅ Done`. When invoked by `roll-loop`, the row will already be `🔨 In Progress` — that is the expected starting state, and the transition is the same Edit operation.
+Change the Status from `📋 Todo` or `🔨 In Progress` (whichever the row currently shows) to `✅ Done`.
 For Fly mode: first append an index row under the appropriate Epic > Feature group, then mark it done.
 
 **② Update `.roll/features/<epic>/<story>/spec.md`:**
@@ -804,7 +807,9 @@ For Fly mode: first append an index row under the appropriate Epic > Feature gro
 If the US section does not yet exist, create the full section (AC / Files / Dependencies).
 
 **Before committing, run `$roll-.changelog`** to stage CHANGELOG.md — then include
-it in the completion commit so no separate changelog commit is created.
+it in the completion commit so no separate changelog commit is created. This
+manual-path section does not apply inside `roll-loop`; its Runner owns
+metadata reconciliation after merge.
 
 ```bash
 # 1. Stage changelog (roll-.changelog stages CHANGELOG.md only, does not commit)
@@ -857,11 +862,10 @@ Before creating any file or directory:
 0. **Worktree-first, PR-at-end (ALWAYS)**
    Before writing any code, work in a dedicated git worktree on its own
    branch (`git worktree add ../wt-<id> -b <branch>`), never in the shared
-   checkout — so concurrent cycles / sessions never collide. Finish by
-   pushing the branch and opening a PR; `main` is PR-protected — NEVER
-   `git push origin main`. (Under `roll-loop` the runner creates the
-   worktree + branch and opens the PR; this rule is the manual-path
-   equivalent and must hold either way.)
+   checkout — so concurrent cycles / sessions never collide. In a standalone
+   session, finish by pushing the branch and opening a PR; `main` is
+   PR-protected — NEVER `git push origin main`. Under `roll-loop`, finish
+   green commits and evidence only: the Runner creates the PR.
 
 1. **No local-only "done" — Done ≡ merged (FIX-322/323)**
    Work is not complete until it reaches: