@seanyao/roll 4.706.1 → 4.708.2

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。
 
@@ -261,7 +266,7 @@ no-TCR/gave-up、成功交付、成本档位和角色能力标签排序。运行
 Roll 的运行模式只有两个：`guided` 和 `autonomous`。它们不是两套 agent 配置，而是同一套 backlog、truth、route profile、execution profile、attest evidence、Evaluator 和 release gates 之上的两种触发方式。
 
 - `guided`：owner 通过 `roll supervisor status/next/why` 理解状态和下一步，再显式运行 `roll loop go --cards <id>` 等命令。guided 模式不会静默启动长时间 Story 执行。
-- `autonomous`：`roll loop on` 安装 scheduler；scheduler 可以在 pause、budget、route、evidence、Evaluator 和 release gates 内领取合格 Todo。`roll loop pause` / `roll loop off` 回到 guided；`roll loop resume` / `roll loop on` 显式切回 autonomous。
+- `autonomous`：`roll loop on` 安装 scheduler；scheduler 可以在 pause、budget、route、evidence、Evaluator 和 release gates 内领取合格 Todo。`roll loop pause` / `roll loop off` 回到 guided；`roll loop off --all` 是本机所有 `com.roll.*` LaunchAgent 的急停；`roll loop resume` / `roll loop on` 显式切回 autonomous。
 - 持久化来源只使用已有 loop/supervisor 状态：launchd plist、PAUSE/DORMANT marker、events/runs/backlog。不得新增独立 `mode.yaml` 之类的第二真相。
 
 ### BC9 · Supervisor 与执行剖面（v4）

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,9 +102,11 @@ 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
 

package/guide/en/loop.md

@@ -206,6 +206,7 @@ roll loop on          # Install launchd scheduler (loop + pr + dream)
 roll loop off         # Remove launchd scheduler
 
 roll loop now         # Run one cycle immediately (same as launchd fires)
+roll loop now --cards US-1,FIX-2  # Run one immediate cycle scoped to selected cards
 roll loop test        # Quick smoke test: verify tmux/popup/stream chain works
 
 roll loop status      # Show scheduler state and current loop state
@@ -275,6 +276,8 @@ gates still decide eligibility.
 `roll loop go` is a manual goal session, not a launchd scheduler tick. While it
 runs, Roll holds `.roll/loop/go.lock`; scheduled ticks yield when they see that
 lock, record `goal:tick_skipped`, and do not start another `roll loop run-once`.
+`roll loop now --cards <ids>` uses the same card allow-list for its one-shot
+runner, so a manual tick cannot silently pick a different backlog card.
 
 Goal mode can run when the scheduler is off because it starts its own session
 and does not depend on launchd. For paused projects, run `roll loop resume`
@@ -298,6 +301,12 @@ dirty, the goal pauses with `bootstrap_artifacts_unconfirmed` and prints the
 files to confirm. Commit or clean them, then run `roll loop go` again. This
 preflight does not start a cycle and does not count as no-progress.
 
+For the Roll repository itself, `roll loop go`, `roll loop resume`, and
+`roll loop now` print the runner binary and version before starting autonomous
+work. They fail loud with `runner_stale_for_repo` if the repo-local
+`@seanyao/roll` package version is newer than the running runner; install or
+publish the local build before resuming autonomous work.
+
 `roll loop go` enforces safety only at cycle boundaries. `--budget <usd>` uses
 the effective run cost ledger and moves the goal to `budget_limited` when the
 budget is reached. An idle or aborted cycle that ran no agent counts as a known
@@ -390,10 +399,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,9 +87,10 @@ roll attest audit --json
 
 ## 红线
 
-**零证据**的 AC 永远不能是 `pass`：渲染层强制降级为 🟧 仅声明，并列入
-**Discrepancies（证据缺口）**附录。"我确认它能跑"这类口头完成，正是被这条
-红线挡住的东西。
+**零证据**的 AC 永远不能是 `pass` 或 `pass-with-evidence`：渲染层强制降级为
+🟧 仅声明，并列入 **Discrepancies（证据缺口）**附录。`pass-with-evidence`
+表示 harness 基于硬盘上强证据做出的确认，明确不同于 agent 亲自确认的 `pass`。
+"我确认它能跑"这类口头完成，正是被这条红线挡住的东西。
 
 ## 设计期声明可视证据
 

package/guide/zh/loop.md

@@ -176,6 +176,7 @@ roll loop on          # 安装 launchd 调度器（loop + pr + dream 三个服
 roll loop off         # 卸载 launchd 调度器
 
 roll loop now         # 立即执行一次循环（与 launchd 触发的流程完全一致）
+roll loop now --cards US-1,FIX-2  # 立即执行一次循环，但只允许指定卡片
 roll loop test        # 快速冒烟测试：验证 tmux/弹窗/流式输出链路是否正常
 
 roll loop status      # 显示调度器状态和当前 loop 状态
@@ -244,6 +245,8 @@ Hold、Cut、未满足依赖、skip-list、open PR、已合并交付和 pending-
 `roll loop go` 是手动 goal session，不是 launchd 定时 tick。运行期间 Roll 会持有
 `.roll/loop/go.lock`；定时 tick 看到该锁就让路，记录 `goal:tick_skipped`，不会再启动
 另一个 `roll loop run-once`。
+`roll loop now --cards <ids>` 对它触发的单次 runner 使用同一份卡片 allow-list，
+所以手动 tick 不能静默改选其他 backlog 卡。
 
 goal mode 在 scheduler off 时也能运行，因为它自己启动会话，不依赖 launchd。loop 处于
 paused 状态时不建议直接启动：`PAUSE-<slug>` 标记仍会在 cycle 边界生效，所以应先执行
@@ -271,6 +274,11 @@ Roll-owned 文件提交并推送；如果历史版本或手工路径仍然只留
 `bootstrap_artifacts_unconfirmed` 暂停，并打印待确认文件。提交或清理后，再重新运行
 `roll loop go`。这个 preflight 不会启动 cycle，也不会累加 no-progress。
 
+在 Roll 仓自身里，`roll loop go`、`roll loop resume` 和 `roll loop now`
+开工前都会打印当前 runner 的 binary 与版本。repo-local `@seanyao/roll`
+包版本高于正在运行的 runner 时，它们会以 `runner_stale_for_repo`
+fail-loud；先安装或发布本地构建，再恢复自治施工。
+
 每次安全闸触发都会记录 `goal:gate_tripped`，`roll loop goal` 会显示最近一次安全闸读数。
 
 ### `roll loop goal` 字段含义
@@ -343,9 +351,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.706.1",
+  "version": "4.708.2",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {