@seanyao/roll 4.630.2 → 4.702.2

package/guide/en/loop.md

@@ -0,0 +1,1324 @@
+# roll loop — Autonomous BACKLOG Executor
+
+`roll loop` schedules and manages the autonomous execution of BACKLOG stories.
+When enabled, it wakes up on a configurable schedule (within your active
+window), picks the top pending story, and executes it — committing changes in
+TCR micro-steps.
+
+`roll loop on` is the explicit switch into **autonomous** mode. `roll loop off`
+or `roll loop pause` returns the project to **guided** operation, where the
+owner asks `roll supervisor next/why` and starts any long-running Story work
+explicitly. `roll loop resume` switches back to autonomous without changing
+agent bindings.
+
+## How It Works
+
+1. Reads `BACKLOG.md`, picks the highest-priority `📋 Todo` item.
+2. Marks it `🔨 In Progress` and commits.
+3. Invokes `$roll-build <story-id>` or `$roll-fix <bug-id>`.
+4. On success: marks `✅ Done`, commits, appends to `runs.jsonl`.
+5. On failure: reverts to `📋 Todo`, writes an `ALERT.md` entry.
+
+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.
+
+## Scheduling
+
+Loop is scheduled via **launchd** (macOS). By default, every hour at a
+project-derived minute (different projects get different offsets to avoid
+collisions).
+
+```
+Active window: 0–24 (always on — the shipped default)
+```
+
+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
+10-18` for 10am – 6pm. Outside the configured window, loop silently exits
+without doing anything.
+
+## Configuring the schedule
+
+Instead of hand-editing `~/.roll/config.yaml` and `.roll/local.yaml` and then
+hoping the launchd plist picks up your change, use the `roll config` command
+family. Each write lands in the right yaml file **and** automatically
+regenerates the runner, re-bootstraps the launchd plist, and is reflected
+immediately by `roll loop status` — no manual reload step.
+
+| Command | What it sets |
+|---------|--------------|
+| `roll config loop-window <start>-<end>` | loop active window hours (`loop_active_start` + `loop_active_end`) |
+| `roll config loop-schedule <period>[/<offset>]` | fire interval (`loop_schedule.period_minutes` + `offset_minute`) |
+| `roll config dream-time <HH:MM>` | dream daily fire time (`loop_dream_hour` + `loop_dream_minute`) |
+
+```bash
+roll config loop-window 9-18        # active 9am – 6pm; start < end, both in [0,24]
+roll config loop-schedule 30        # fire every 30 minutes (period in [1,1440])
+roll config loop-schedule 30/7      # every 30 minutes, offset :07 (offset in [0, period-1])
+roll config dream-time 03:20        # dream fires at exactly 03:20; HH in [0,23], MM in [0,59]
+```
+
+**Reading the current value.** Run any facade with no value to print the
+effective combination and where it comes from:
+
+```bash
+roll config loop-window             # loop-window: 0-24 (from default)
+roll config dream-time              # dream-time: 03:20 (from ~/.roll/config.yaml)
+```
+
+**Range validation.** Out-of-range or non-numeric input is rejected with a
+locale-selected error and exit code 2. For example, with `ROLL_LANG=en`,
+`roll config loop-window 9-25` prints `loop-window end must be <= 24`.
+
+**`--global` vs `--project`.** Writes default to `--project` (`.roll/local.yaml`,
+this project only). Pass `--global` to write `~/.roll/config.yaml` as the
+default for every project that has no project-level override.
+
+```bash
+roll config dream-time 03:20             # this project (.roll/local.yaml)
+roll config dream-time 03:20 --global    # all projects (~/.roll/config.yaml)
+```
+
+**Auto-reload.** After writing a schedule key, `roll config` re-installs the
+launchd plists for loop / pr / dream so the change fires on the next
+window. If reload fails (e.g. in a sandbox), the yaml is still the source of
+truth — run `roll loop on` to apply it by hand. See `roll config --help` for
+the full key list and ranges.
+
+### Per-project frequency
+
+Set the fire interval with one command:
+
+```bash
+roll config loop-schedule 30        # every 30 minutes (period 1–1440, any interval)
+roll config loop-schedule 45        # every 45 minutes (no longer restricted to divisors of 60)
+```
+
+This writes a `loop_schedule` block to `.roll/local.yaml`:
+
+```yaml
+loop_schedule:
+  period_minutes: 30   # 1-1440 (any minute interval)
+  offset_minute: 7     # 0–(period-1) (deprecated; for backward compat only)
+```
+
+- `period_minutes` — how often loop fires. Any value 1–1440.
+- `offset_minute` — (deprecated since US-LOOP-032) no longer affects timing.
+  Kept for backward compat.
+
+If no `.roll/local.yaml` or no `loop_schedule` block is present, Roll falls
+back to the global value (set with `roll config loop-schedule … --global`), or
+derives a per-project default from the project path hash.
+
+`roll loop status` and `roll loop on` display the actual schedule frequency
+so you can verify it at a glance. An invalid value (e.g. `period_minutes: 0` or
+`1441`) is rejected at write time with exit code 2.
+
+### Global defaults (backward-compatible)
+
+For a single global default across all projects, write with `--global`:
+
+```bash
+roll config loop-window 10-18 --global   # active window for every project
+roll config loop-schedule 60 --global    # default interval for every project
+```
+
+(Agent selection is no longer a global config key. It is resolved from Machine
+Scope and Project Scope agent files. See [Autonomous Role Resolution](#autonomous-role-resolution).)
+
+Project-level `.roll/local.yaml` always takes priority over the global default.
+
+## Subcommands
+
+```bash
+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 test        # Quick smoke test: verify tmux/popup/stream chain works
+
+roll loop status      # Show scheduler state and current loop state
+roll loop watch       # Default owner view: phase, quiet time, TCR count, last signal, plus live activity
+roll loop watch -n 50 # Look back 50 lines before following (default 200; 'all' = whole log)
+roll loop watch --events      # Compact developer event stream from .roll/loop/events.ndjson
+roll loop watch --raw-events  # Raw JSON event stream for audit/debug only
+roll loop watch --verbose  # Also show the raw agent transcript (default folds it away)
+roll loop watch --attach   # Read-only attach to the loop's tmux observe window (tmux attach -r)
+roll loop go          # Run goal mode manually for all backlog until complete/pause/guardrail
+roll loop go --epic <name>              # Limit the goal to one epic
+roll loop go --cards US-1,FIX-2         # Limit the goal to selected cards
+roll loop go --budget 10                # Stop conservatively when goal cost reaches $10
+roll loop go --usage-threshold 0.85     # Pause when five-hour or weekly usage reaches this ratio
+roll loop go --no-wait                  # On usage limit, pause and return instead of waiting for reset
+roll loop go --for 5h                   # Stop after the current cycle once the timebox is reached
+roll loop go --max-cycles 3             # Stop after this many cycles
+roll loop go --review <auto|hetero|self|off>  # Set the final review policy
+roll loop goal        # Show persisted goal status, scope, review mode, usage, limits, and safety gate
+
+roll loop runs        # Show last 10 run summaries (story IDs, TCR count, duration, slowest phase)
+roll loop runs 20     # Show last 20 runs
+roll loop runs --all  # Show all projects' run history
+roll loop runs --detail <cycle_id>  # Phase Breakdown panel for a single cycle
+
+roll loop story <ID>  # Per-story rollup: cycles, span, duration, tokens, cost, PRs
+roll loop story <ID> --json  # Machine-readable form for scripting
+
+roll loop eval       # Objective result-eval trend over the last 14 scored cycles
+roll loop eval 30    # Widen the window to the last 30 scored cycles
+roll loop signals    # Surface repeated low-score patterns as improvement signals
+roll loop signals --streak 4  # Require 4 consecutive low cycles before firing
+
+roll loop watch       # Recommended daily live view
+tmux attach -t roll-loop-<project-slug>  # Read-only tmux observe window; use when you want the pane
+roll loop mute        # Suppress auto-attach popup (loop still runs in tmux)
+roll loop unmute      # Re-enable auto-attach popup
+
+roll loop pause       # Pause scheduling (keep plist, skip execution)
+roll loop resume      # Resume scheduling after pause
+
+roll loop reset       # Clear loop state (start fresh on next fire)
+
+roll loop gc                  # GC orphan slugs, tmp debris, expired backups (default: keep 30 days)
+roll loop gc --dry-run        # Preview what would be removed without deleting
+roll loop gc --keep-days 14   # Override retention (also: loop_gc.retention_days in .roll/local.yaml)
+                              # See guide/en/loop-data-layout.md for the full gc manual
+
+# loop-related branches: `git ls-remote --heads origin 'loop/*'` (the `branches` subcommand is retired)
+
+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 list                      # Show agents installed on this machine
+```
+
+### Goal Mode vs Scheduled Mode
+
+`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`.
+
+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`
+first: the `PAUSE-<slug>` marker is still respected at cycle boundaries.
+
+### Goal Mode Safety Gates
+
+Budget and run limits are explicit per `roll loop go`. `--budget`,
+`--max-cycles`, and `--for` apply to THIS invocation only; omitting one means no
+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.
+
+`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
+$0, not as an unknown-cost row. Only a row where an agent actually executed but
+left no parseable usage is recorded as unknown; those still stop conservatively
+rather than being counted as zero. Usage headroom is checked against five-hour
+and weekly windows; by default Roll pauses at 85% and waits for the reset
+window, while `--no-wait` leaves the goal paused for the owner. The recovery
+wait is bounded — a hung usage API cannot stall the session forever; on timeout
+Roll records a `usage_wait_timeout` audit event and leaves the goal paused.
+`--for <duration>` is a wall-clock box: the in-flight cycle finishes, then the
+goal pauses with reason `timebox`.
+
+Each safety trip records `goal:gate_tripped`, and `roll loop goal` shows the
+last safety gate reading.
+
+### `roll loop goal` Fields
+
+`roll loop goal` is the read face for `.roll/loop/goal.yaml` plus the latest
+goal events. The key fields are:
+
+| Field | Meaning |
+|-------|---------|
+| `Status` | `active`, `paused`, `budget_limited`, or `complete`. |
+| `Scope` | All backlog, one epic, or an explicit card list. |
+| `Review` | Completion review policy: `auto`, `hetero`, `self`, or `off`. |
+| `Usage` | Goal cycle count, effective cost, and unknown-cost-row count. |
+| `Limits` | Explicit `--budget`, `--max-cycles`, and `--for` settings. |
+| `Safety gate` | The latest budget, usage, or timebox trip and its reading. |
+| `Last decision` | Why the goal continued, paused, became budget-limited, or completed. |
+
+When `auto` final review degrades to same-provider review, the status view
+shows the recorded degradation reason from `goal:review_degraded`. When a goal
+cannot complete, `Last decision` carries the unmet truth or review reason.
+
+### Goal Mode Final Review
+
+`roll loop go` persists its goal state in `.roll/loop/goal.yaml` and runs a
+final review gate before a goal can become `complete`. The default policy is
+`--review auto`: Roll tries heterogeneous reviewers in ranked order, and records
+`goal:review_degraded` when it must fall back to self review because every
+heterogeneous candidate failed or because only one provider is installed.
+
+Final review uses the same structured adapter as `-peer` skill. The
+`goal:final_review` event records reviewer agent, provider, command family,
+verdict, findings, timeout/error state, duration, and transcript/evidence
+paths when available. A transient review crash rotates to the next ranked
+candidate; if every candidate fails Roll records the real error reason on the
+`ERROR` verdict and raises an ALERT, instead of collapsing into a reasonless
+generic error.
+
+Use `--review hetero` when completion must fail closed unless a heterogeneous
+reviewer is installed. Use `--review self` to allow same-provider review. Use
+`--review off` only as an explicit operator waiver; Roll skips the gate but
+still records a `goal:final_review` event with `verdict: SKIPPED`.
+
+## Autonomous Role Resolution
+
+Loop resolves agents through the scoped Agent model:
+
+```text
+Scope -> Role -> Binding -> Agent -> optional Model
+```
+
+Machine Scope lives in `~/.roll/agents.yaml`; Project Scope lives in
+`.roll/agents.yaml`. A loop cycle resolves `story.execute` for the Builder and
+`story.evaluate` for review/score, using inherited machine declarations when the
+project says `inherits: machine`.
+
+```yaml
+schema: roll-agents/v1
+scope: project
+inherits: machine
+defaults:
+  story:
+    roles:
+      execute:
+        kind: select
+        from: [kimi, codex, pi]
+        require: [execute]
+        strategy: first-available
+      evaluate:
+        kind: select
+        from: [claude, codex, kimi, pi, agy, reasonix]
+        require: [evaluate]
+        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.
+
+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.
+
+For open casting, `health-aware` ranks the same visible pool across Builder,
+Designer, Evaluator, and Peer Reviewer roles. `roll supervisor route --role
+builder --story <id> [--json]` exposes the trace: candidates, ranked scores,
+warnings, skipped runtime facts, selected agent, source binding, recent-use
+input, and capability/health ranking.
+
+### Agent toolchain health check (US-V4-022)
+
+Before scheduling, Supervisor also classifies agent toolchain health signals
+from the durable event stream. It distinguishes auth blocks, network blocks,
+setup/skill-root pollution, and worktree permission failures. Pollution signals
+are routed to the delta team as a FIX rather than misclassified as auth failures.
+Use `roll supervisor health` for the dedicated board, or read the summary from
+`roll supervisor next` / `roll supervisor why`.
+
+### Agent self-downgrade (too_big verdict)
+
+The picked agent runs a **pre-flight self-check** (in `roll-build` / `roll-fix`
+SKILL.md). When it decides the story is over capacity it emits:
+
+```yaml
+verdict: too_big
+reason: est_min=20 > pi.max=8
+```
+
+并触发 self-downgrade 流程：调 `roll-design --from-story <id>` 把故事拆成
+chain_depth + 1 的子故事写回 BACKLOG，原故事翻 🚫 Hold，cycle 干净退出。
+下一轮 loop 接力第一个更小的子故事。
+
+The chain is capped at **2 auto re-splits**. The third would be refused and a
+`StorySplitCapHit` ALERT is written, forcing human triage instead of letting
+the chain grow indefinitely.
+
+## Execution profiles (standard / verified / designed)
+
+Role resolution above chooses the concrete Agent and optional Model for the
+`execute` and `evaluate` roles. Separately, Roll chooses an **execution profile** per
+Story — the cheapest *sufficient* role pipeline for that Story's risk and ROI.
+You do not declare it; it is selected once at cycle start from the story's risk
+signals and recorded in an `execution:profile` event. These are **not
+user-facing "team shapes"** — they are risk/ROI tiers:
+
+- **`standard` = execute only** — low-risk, local scope, clear acceptance, low
+  evidence risk (a copy fix, a small parser bug, an internal rename).
+- **`verified` = execute → evaluate** — user-visible behavior, screenshot/visual
+  evidence required, or a history of weak/missing evidence. An independent
+  `evaluate` role (fresh session) judges the delivery; blocking review, score, and
+  attest stay three separate dimensions.
+- **`designed` = Designer -> Builder -> Evaluator** — the risk is doing the *wrong*
+  work: unclear requirements, cross-module change, or truth/release/routing/state
+  semantics. A design artifact is written before `execute`; `evaluate` maps
+  design-contract-vs-delivered. evaluate → execute repair rounds are strictly bounded
+  (max rounds, repeated-finding signature, budget, timeout) and escalate on a
+  bound trip.
+
+Roles hand off through artifacts only (design contract, builder evidence,
+eval-report) — never a shared raw session. Project-level coordination across
+Stories (ordering, conflicts, budget, release readiness) belongs to the
+**Supervisor** (`roll supervisor`), not to any single Story's execution.
+
+When the owner asks to clear the backlog, Supervisor uses a backlog-clearing
+standard rather than a fix-only queue. The default scope is every live non-Hold
+`FIX-*`, `US-*`, and `REFACTOR-*` row. Before starting another card it reconciles
+backlog truth, open PRs, CI/evaluator gates, recent cycle endings, manual-merge
+PRs, and `.roll` meta state. Each card gets a fresh Builder and, when its
+execution profile requires it, an independent Evaluator/Scorer from the current
+Agent roster. Repeated failure, zero TCR, missing evidence, parser failure,
+auth/permission blocks, or `[roll:manual-merge]` PRs stop scheduling until the
+owner action shown by `roll supervisor status/next/why` is resolved.
+
+## Cycle Role Visibility
+
+A v4 cycle is a multi-agent collaboration: a Builder writes the code, one or
+more Peer Reviewers re-check the risky diff, an Evaluator/Scorer judges the
+delivery, and the Attest Gate decides whether the result is admissible. The
+underlying truth lives in `events.ndjson` and the peer/evidence artifacts, but
+you should never have to grep those by hand to answer the first-run question:
+**who was Builder and who was Evaluator?**
+
+Three surfaces answer that question.
+
+### `roll loop cycle <id> --roles`
+
+```bash
+roll loop cycle <id> --roles          # human-readable execution cast for one cycle
+roll loop cycle <id> --roles --json   # the same facts as cycle-role-summary.v1 JSON
+```
+
+The roles view renders the full role chain — Builder, Peer Review,
+Evaluator / Score, and Gates — for a single cycle:
+
+```text
+# Cycle Role Summary — 20260629-112437-39253
+
+Story: US-TASK-001
+Execution profile: standard
+
+## Builder
+- pi / deepseek-v4-pro
+  - log: .roll/loop/cycle-logs/20260629-112437-39253.agent.log
+
+## Peer Review
+- reasonix: accepted verdict=refine findings=0
+- kimi: returned reviewed, no structured verdict accepted
+- codex: returned reviewed, no structured verdict accepted
+
+## Evaluator / Score
+- reasonix: accepted score=10 verdict=good
+- agy: failed unparseable (control characters before SCORE)
+- kimi: selected, no accepted score
+
+## Gates
+- peer: consulted
+- attest: produced
+```
+
+The command reads the cached summary artifact first and rebuilds from
+`events.ndjson` when it is missing or corrupt, so it works for both fresh and
+archived cycles.
+
+### The `summary.md` / `summary.json` artifacts
+
+Every cycle writes the same role cast to disk so a delivery report or a teammate
+can read it without re-running the CLI:
+
+```text
+.roll/loop/cycle-logs/<cycle-id>/summary.md     # the markdown shown above
+.roll/loop/cycle-logs/<cycle-id>/summary.json   # cycle-role-summary.v1, machine-readable
+```
+
+`summary.json` carries one `CycleRoleAttempt` per agent participation, each with
+its role, agent, model, session id, stage, state, and (when relevant) verdict,
+score, findings, parse-failure cause, and artifact path.
+
+### The Execution Cast report block
+
+The story attest report embeds an **Execution Cast** block (🎭) that projects
+the same summary into the delivery view, so the role chain travels with the
+evidence. When no role summary exists the block degrades gracefully to "Role
+summary unavailable". Accepted artifacts are linked directly — e.g. the
+`accepted evaluator artifact` link points at the scorer output the gate actually
+used.
+
+### Selected vs returned vs accepted
+
+The per-agent `state` is the key to reading the cast correctly. The states form
+a ladder, and **being selected or returning output is not the same as being
+accepted by the gate**:
+
+| State | Meaning |
+|-------|---------|
+| `selected` | The agent was chosen for the stage but produced no accepted result. |
+| `started` | The agent began the stage. |
+| `returned` | The reviewer returned output, but no structured verdict was accepted. |
+| `parsed` | Structured output was parsed. |
+| `accepted` | The gate accepted this attempt — the verdict/score that counts. |
+| `rejected` / `failed` | Rejected, errored, or produced unparseable output. |
+| `not_required` / `not_available` | The role was not needed (e.g. `standard` profile) or had no candidate. |
+
+**Only one evaluator/scorer is gate-accepted, even when several agents were
+consulted.** A cycle may select reasonix, kimi, and codex for review and ask
+reasonix and agy to score, but exactly one score is `accepted` and stamped into
+the Attest Gate. The others show as `returned`, `selected`, or `failed` — they
+are recorded for transparency, not because they all gate the delivery. When you
+need the verdict that actually decided the cycle, read the `accepted` row (and
+the `accepted evaluator` artifact link), not whichever agent happens to be
+listed first.
+
+When a reviewer or scorer produced unparseable output, its row is `failed` with
+a `cause` (e.g. `unparseable`) and a `raw artifact:` pointer to the captured
+attempt under `.roll/loop/peer/` — see
+[Troubleshooting unparseable score/review](../../docs/live-console.md#故障排查).
+
+## Collaboration View
+
+US-OBS-032 writes the role cast (`summary.md` / `summary.json`), US-OBS-033
+exposes that cast with `roll loop cycle <id> --roles`, and the collaboration view is
+the upper layer over CycleRoleSummary. It turns the same facts into a protocol
+relay: who designed, who built, who reviewed, who evaluated, and where the
+baton ended.
+
+Use these entry points:
+
+```bash
+roll loop cycle <id> --collab          # one cycle as a protocol relay
+roll loop cycle <id> --collab --json   # collab-view.v1 JSON
+roll supervisor live --collab     # live multi-cycle collaboration stream
+roll supervisor live --collab --once
+roll loop cycle --legend               # Layer A protocol legend
+```
+
+Read the protocol as:
+
+```text
+Supervisor/Designer -> Builder -> independent Peer Reviewer/Evaluator -> Gate
+```
+
+The Supervisor can intervene at three levels. `observe/advise` means the
+Supervisor is watching, asking for evidence, or routing owner attention without
+changing the Builder's work. `design/split` means the Supervisor turns unclear
+scope into a design artifact or smaller follow-up actions. `Builder override`
+is explicit and exceptional: the Supervisor chooses or replaces the Builder
+binding, and that decision must remain visible in the cast.
+
+Role independence is session-based, not brand-based: separate fresh sessions
+and artifact handoff are the rule. The same agent brand can serve more than
+one role only when each role runs in its own session and hands off through
+artifacts: a design contract, diff, review, score, AC map, or report.
+A shared transcript is not an independent review. Agent diversity is useful
+evidence and a ranking signal, especially when capability or shortcoming
+profiles are visible in role summaries, but it is not a default hard exclusion
+rule; capability, availability, and the required role contract still decide.
+
+`handoff`, `escalation`, and `terminus` are separate reading keys. A handoff is
+the normal baton pass between roles, such as Builder -> Peer Reviewer with a diff and evidence.
+Escalation is a visible break in the normal path: the Supervisor, Gate, or owner
+needs attention because the ordinary relay could not finish cleanly. The
+`terminus` says where the baton ended, not whether the Story passed or failed:
+`walked_full`, `escalated`, `split`, and `supervisor_fix` describe the relay's
+ending point. Use the Gate and attest result for pass/fail.
+
+## Status Dashboard
+
+`roll loop status` prints a compact dashboard with per-cycle rows and daily rollup totals.
+
+### Token column
+
+Each cycle row shows token usage in a 4-component format:
+
+```
+·  19:18    13m    164/498.2K↑ 12.7M↓/63.3K   opus-4-7   $11.07   US-VIEW-012
+             ↑      in   cw↑     cr↓    out
+```
+
+| Segment | Meaning |
+|---------|---------|
+| `164` (before first `/`) | Base input tokens |
+| `498.2K↑` | Cache write tokens (billed at write rate) |
+| `12.7M↓` | Cache read tokens (billed at read rate, much cheaper) |
+| `63.3K` (after last `/`) | Output tokens |
+
+When a cycle has no cache data (older cycles or non-Opus models), the column
+falls back to the two-part `in/out` format.
+
+**Per-agent coverage.** Token/cost capture depends on a per-agent usage plugin.
+
+| Agent | Token/cost in dashboard |
+|-------|-------------------------|
+| Claude | ✅ supported |
+| pi (DeepSeek) | ✅ supported |
+| OpenAI (codex) | ✅ supported |
+| Gemini | ✅ supported |
+| Kimi | ✅ supported |
+
+Agents without a plugin fall back to a `—/—` placeholder. Adding a new agent is
+a small per-agent plugin (`lib/agent_usage/<agent>.py`) — it does not happen
+automatically. See `lib/agent_usage/README.md` for the five-step howto.
+
+### Rollup rows
+
+Below the cycle list, daily totals break out all four components:
+
+```
+input tokens       164
+cache writes    498.2K
+cache reads      12.7M
+output tokens    63.3K
+```
+
+This lets you verify that the displayed per-cycle cost (e.g. `$11.07`) matches
+your Anthropic invoice — 86 % of the cost in that example comes from cache.
+
+## Per-Story Rollup
+
+`roll loop status` shows the rolling window (default 3 days). When you want the
+**full lifetime** of a single story — every cycle that ever ran on it, including
+cycles that have aged out of the dashboard window — use `roll loop story`.
+
+```bash
+roll loop story US-LOOP-004           # Compact panel for one story
+roll loop story us-loop-004           # Case-insensitive
+roll loop story US-LOOP-004 --days 90 # Widen the event-stream lookback
+roll loop story US-LOOP-004 --json    # Emit JSON for scripting / dashboards
+```
+
+The panel reports the totals you'd otherwise have to hand-add across multiple
+`status` runs:
+
+```
+── US-LOOP-004 · 把每轮 cycle 成本/token/耗时写进事件流 ──
+  cycles    3  (✓ 2  ✗ 1  ⏵ 0)
+  span      2026-05-18 14:22  →  2026-05-19 09:11
+  duration  1h 47m   tokens  in 412k  out 18.3k  cache w 1.2M  r 7.8M
+  cost      $4.92    model  claude-opus-4-7
+  PRs       #128 ✓   #131 ✓   #134 ✗
+  recent    20260518-142233-91  ✓  $2.10
+            20260518-203045-12  ✗  $1.71
+            20260519-091112-44  ✓  $1.11
+```
+
+**How history is preserved:** the loop runner rotates `events-<slug>.ndjson` at 10 MB,
+keeping `.1` … `.4` archives. `roll loop status` and `roll loop story` both read
+the head plus all rotated files, so cycles never disappear once they're on disk.
+
+**Exit codes:** `0` when at least one cycle is found, `2` when no cycles match
+the story id in the lookback window. The `--json` form follows the same exit
+code contract so scripts can detect missing data.
+
+## Cycle Result Eval
+
+Every cycle is scored *objectively* at finish against a fixed multi-dimensional
+rubric, with **zero extra tokens** — the score is computed from facts the loop
+already has (merge state, CI verdict, TCR count, duration, alerts, orphans). The
+result is written into that cycle's `runs.jsonl` record under a `result_eval`
+block:
+
+```json
+{ "version": 1, "score": 8, "dims": { "outcome": 1.0, "correctness": 1.0,
+  "scope_fidelity": 1.0, "quality": 1.0, "efficiency": 0.6, "cleanliness": 1.0 } }
+```
+
+> **Result-eval is NOT skill self-scoring.** Skill self-scoring (the agent's
+> *subjective* review of one skill run, written into `.roll/notes/*.md`) and
+> result-eval (this *objective* per-cycle result score, computed from facts) are
+> two different signals. They are reported on separate dashboard lines and never
+> merged.
+
+### The rubric (six dimensions)
+
+Each dimension is scored on `0.0`–`1.0`, or `unknown` when its facts are absent.
+Unknown dimensions are excluded from the roll-up and the remaining weights are
+renormalised, so a missing fact never silently scores `0`.
+
+| Dimension | Weight | Meaning | 1.0 when… |
+|-----------|--------|---------|-----------|
+| `outcome` | 3 | Did the cycle merge into `main`? | merged · `0.0` not merged |
+| `correctness` | 2 | Is the produced PR's CI green? | green · `0.0` red |
+| `scope_fidelity` | 2 | Did it complete the story it was routed to? | completed · `0.0` idle / off-scope |
+| `quality` | 1 | Tests added, no immediate rework? | TCR ≥ 1, no rework FIX · `0.5` rework landed · `0.0` no tests |
+| `efficiency` | 1 | Duration vs the story's `est_min` budget | within budget · grades down past it |
+| `cleanliness` | 1 | No orphan worktrees/branches and no ALERTs | clean · `0.0` orphans / alerts |
+
+The dimensions roll up into a single **1–10 cycle score**:
+
+```
+weighted    = Σ(score_i × weight_i for known dims) / Σ(weight_i for known dims)
+cycle_score = round(1 + weighted × 9)        # 0.0 → 1, 1.0 → 10
+```
+
+Weights are a centralised constant in `lib/loop_result_eval.py` — tunable there,
+but deliberately not a high-frequency user knob.
+
+### Reading the trend — `roll loop eval [N]`
+
+`roll loop eval` aggregates the `result_eval` of the last `N` scored cycles
+(default 14) and prints mean / minimum cycle score, each dimension's hit-rate,
+and a trend arrow. Older records without a `result_eval` block are skipped; with
+fewer than 3 scored cycles it prints an `(n/a) need 3` notice.
+
+```
+$ roll loop eval
+Loop result-eval — last 14 cycles
+循环结果评分 — 最近 14 轮
+
+  mean   6.8 / 10   ↓
+  min    4 / 10
+  n      4
+
+  dimension hit-rate / 各维度命中率
+    outcome          75%
+    correctness      67%
+    scope_fidelity   75%
+    quality          75%
+    efficiency       50%
+    cleanliness      100%
+```
+
+The `roll loop status` dashboard also carries a one-line result-eval summary,
+shown **separately** from the Review Score line so the two are never
+confused:
+
+```
+result-eval: mean 6.8↓ / min 4 / out 75% ci 67% scope 75% qual 75% eff 50% clean 100% (last 14)
+```
+
+### Self-evolution signals — `roll loop signals`
+
+When a dimension stays low (`0.0`) for `N` cycles in a row (default 3,
+`--streak` to change), the loop surfaces it as an **improvement signal**: it
+appends a *candidate* backlog draft — an `IDEA` or `FIX`, marked `📋 待人确认`
+— to `.roll/signals/candidates.md`, and `roll loop signals` (and the
+`roll loop status` dashboard) reports it. Signals are deduped per pattern, so a
+standing issue is raised once, not every cycle.
+
+A signal is advisory only. It never edits the real backlog, never activates a
+story, and never changes code — it only exposes what keeps going wrong so a
+human can decide. The cycle-finish hook runs the detector once per cycle;
+`roll loop signals` runs it on demand.
+
+| Dimension stuck low | Surfaced as | Reading |
+|---------------------|-------------|---------|
+| `outcome` | FIX | cycles keep failing to merge into main |
+| `correctness` | FIX | produced PRs keep failing CI |
+| `scope_fidelity` | IDEA | cycles keep going idle or off-scope |
+| `quality` | FIX | cycles keep landing without test activity |
+| `efficiency` | IDEA | cycles keep blowing past their `est_min` budget |
+| `cleanliness` | FIX | cycles keep leaving orphans / raising ALERTs |
+
+## TerminalOutcome vocabulary
+
+User-facing cycle projections use TerminalOutcome values, not legacy summary
+text. The stable vocabulary is:
+
+`delivered`, `published_pending_merge`, `failed`, `blocked`,
+`aborted_no_delivery`, `aborted_with_delivery`, `orphan_timeout`,
+`idle_no_work`, `unknown`.
+
+Older `runs.jsonl` records may contain free-form result strings. Readers
+convert them through the truth adapter before rendering dashboards, archives,
+or summaries.
+
+## Visibility (tmux + popup)
+
+Every loop run lives in a detached tmux session.
+When you're not muted, a terminal window opens automatically.
+
+Use `roll loop watch` first for daily observation. It combines the live agent
+feed with the structured event stream into a concise status layer. Use
+`roll loop watch --events` when debugging event ordering or phase/TCR facts.
+Use `roll loop watch --raw-events` only when you need the unchanged audit JSON.
+All watch modes are read-only; Ctrl-C stops only the view.
+
+```bash
+roll loop watch                          # default status layer
+roll loop watch --events                 # compact events
+roll loop watch --raw-events             # raw audit stream
+tmux attach -t roll-loop-<project-slug>  # join the running observe pane at any time
+# Ctrl-B D            # detach (loop continues)
+
+roll loop mute        # 🔇 stop popup (mute file: ~/.shared/roll/mute)
+roll loop unmute      # 🔔 re-enable popup
+```
+
+The `mute` file is shared across all projects and all autonomous activity
+(loop + peer review). One switch controls everything.
+
+### Environment drift & session lifecycle
+
+The tmux session is long-lived, but a cycle's **network environment always
+follows the invoker**, not the session: the proxy family
+(`HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`/`NO_PROXY` + lowercase) is re-injected
+from the caller every time a cycle window opens. Agent secret env names declared
+by runner profiles, such as Reasonix's `DEEPSEEK_API_KEY`, are also forwarded by
+name; file-backed profile credentials such as `~/.reasonix/.env` are loaded by
+the spawn layer. So turning a local proxy on or off between cycles just works —
+a session created under a proxy that has since died can no longer starve every
+agent into `Connection error` (FIX-230), and env-only agent credentials do not
+depend on the stale tmux session. Each cycle also logs its effective proxy env as
+an `env:` line in `.roll/loop/cron.log`, so an environment-shaped failure is
+readable straight from the log. Other variables still come from the session
+created at `roll loop on` time; if you rotate something exotic, `roll loop off &&
+roll loop on` rebuilds the session fresh.
+
+### Edit fold
+
+When the live tmux stream shows the agent editing the same file several times
+in a row, Roll no longer repeats the identical long path on N separate lines
+(which used to look like a hang). Instead it folds consecutive same-file edits
+into a single line and refreshes it in place:
+
+```text
+✏ <basename> | <hint> ×N
+```
+
+- **Trigger** — two or more *adjacent* `Edit` / `Write` calls targeting the
+  same `file_path`. The path is shown as `os.path.basename(file_path)`, never
+  the full path. A single edit shows no `×N` counter.
+- **`<hint>`** — a ≤20-char feature derived from the edit input so you can tell
+  *what* is changing, not just count:
+  - `replace_all=true` → the literal `replace-all`.
+  - otherwise the first non-blank token of `new_string`'s first line, with
+    leading whitespace and comment markers (`#`, `//`, `/*`, `*`, `--`, `;`)
+    stripped.
+  - tokens longer than 20 characters are truncated to `token[:20] + "…"`
+    (counted by unicode char, so 中文 / emoji are not byte-split).
+  - an empty / all-whitespace `new_string` yields no hint, and the ` | <hint>`
+    segment is omitted entirely.
+- **Cross-file flush** — switching to a different file (or any other event:
+  `Bash`, `Skill`, an error, or cycle end) first flushes the previous file's
+  final streak line so it stays in the scrollback, then starts a fresh line for
+  the new file. Edits never fold across a non-edit line.
+
+Three examples (ANSI-stripped):
+
+```text
+# single edit
+✏ auth.ts | export
+
+# folded ×N (7 edits of the same file)
+✏ auth.ts | export ×7
+
+# cross-file switch — two lines, the first flushed before the second starts
+✏ auth.ts | export ×3
+✏ router.ts | replace-all
+```
+
+## Cycle exit summary
+
+When a cycle ends and the tmux session detaches, the macOS `.command` window
+no longer leaves you staring at a bare `press enter to close` line. Just before
+that prompt, the window renders a compact recap block so you can see what the
+cycle did without scrolling back through tmux scrollback or opening the cron
+log:
+
+```text
+─── Cycle 20260530-2301-94839 Summary ───
+  outcome: delivered · story: US-LOOP-040 · tcr commits: 4
+  ci: green
+  todo remaining: 7
+  phases (top 5 by time):
+    build                   612s
+    ci                       94s
+    pr                       31s
+  press enter to close.
+```
+
+The summary covers five signals:
+
+1. **Result** — the cycle outcome from `runs.jsonl`, rendered as
+   TerminalOutcome in the summary:
+   `delivered`, `published_pending_merge`, `failed`, `blocked`,
+   `aborted_no_delivery`, `aborted_with_delivery`, `orphan_timeout`,
+   `idle_no_work`, or `unknown`.
+2. **CI / build status** — the latest `ci` event outcome: `green`, `red`,
+   `heal-attempting`, or `ci: n/a` when the cycle never ran CI.
+3. **Todo remaining** — count of `📋 Todo` lines still in `.roll/backlog.md`.
+4. **Phase breakdown** — the top 5 cycle phases by elapsed time.
+5. **Failure / alert highlights** — failed/aborted runs, red CI, active alerts,
+   and suspected zero-diff cycles are flagged with a `✗` (failure) or `⚠`
+   (warning) prefix and, on a colour terminal, red / yellow highlighting. A
+   fully green cycle prints in the default colour with no prefix.
+
+The `press enter to close` prompt is preserved — the summary is printed *above*
+it, nothing about the close interaction changes.
+
+### Turning off colour
+
+ANSI colour is only emitted when the output is a real terminal. Pipes,
+redirects and captured output stay plain text. To force colour off on a TTY,
+set `NO_COLOR=1` (per [no-color.org](https://no-color.org)):
+
+```bash
+NO_COLOR=1 roll loop now
+```
+
+### Troubleshooting: no summary appears
+
+If the cycle exited early (aborted/idle) or `runs.jsonl` had not yet flushed,
+the window prints a single placeholder line instead, and the `press enter`
+prompt still works:
+
+```text
+(summary unavailable — see log: ~/.shared/roll/loop/cron-<slug>.log)
+```
+
+Summary rendering is always a silent best-effort step: if `python3` is missing
+or the data is corrupt, the cycle skips the recap and falls straight through to
+`press enter to close` — it never changes the `.command` exit code or blocks
+the window from closing.
+
+## Concurrency Safety
+
+Loop has two layers:
+
+- **LOCK file** (`<project>/.roll/loop/.LOCK-<slug>`): only one loop per project runs at a time.
+  If loop is already running, a new fire exits immediately.
+- **🔨 In Progress status**: stories being worked by humans or other agents are skipped.
+
+You can always run `$roll-build US-XXX` to take over a story manually.
+Loop sees the `🔨 In Progress` marker and skips it.
+
+## Failure Handling
+
+| Condition | What happens |
+|-----------|-------------|
+| API error | Retry up to 3×, 30s backoff |
+| Role candidate unavailable | Skip for current resolution, record runtime health |
+| No role candidate available | Pause loop, write ALERT.md |
+| TCR: 0 commits | Revert story to 📋 Todo, write ALERT.md |
+| HEAD CI red | Hot-fix attempt (see below), or ALERT if exhausted |
+
+ALERT entries surface in `roll loop status`, `roll loop alert`, and cycle/story evidence views.
+
+## CI Self-Healing (US-LOOP-046..050)
+
+When loop detects that HEAD CI is red before picking a story, it no longer
+immediately writes an ALERT and stops. Instead it tries to fix CI autonomously.
+
+**How it works:**
+
+1. `roll loop precheck-ci` runs before each BACKLOG scan.
+2. If CI is green → cycle proceeds normally.
+3. If CI is red AND heal is allowed:
+   - Loop captures the failing CI log + commit diff via `roll loop hotfix-head-context`.
+   - Invokes `roll-fix` with that context as a brief.
+   - Waits for CI to go green.
+   - If still red after `ROLL_LOOP_HEAL_MAX` attempts (default 2): writes ALERT and stops.
+4. If CI is red AND heal is exhausted or `ROLL_LOOP_NO_HEAL=1`: writes ALERT (existing behavior).
+
+**Loop's own PRs (`loop/*`) that turn red after a cycle exits** are detected
+(US-LOOP-049) and **background-healed** (US-LOOP-062a): classified as
+`loop_self_ci_red`, the PR Loop routes them to `roll loop pr-heal-run`, which checks
+out the PR branch and hands the failing-CI context to the project's agent
+(`_project_agent`) — bounded by a per-PR heal budget (`ROLL_LOOP_HEAL_MAX`,
+default 2) and a per-PR lock that prevents duplicate concurrent heals. The heal
+runs in the background so the PR tick continues. When heal is disabled
+(`ROLL_LOOP_NO_HEAL=1`) or the budget is exhausted, it writes a deduped
+`[TYPE:loop-pr-ci-red]` ALERT instead of silently skipping.
+
+**Environment variables:**
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `ROLL_LOOP_NO_HEAL=1` | unset | Disables all CI hot-fix attempts; reverts to fail-fast |
+| `ROLL_LOOP_HEAL_MAX` | `2` | Maximum consecutive hot-fix attempts before ALERT |
+
+## PR Inbox & Review
+
+Each loop cycle processes open PRs before picking new stories.
+
+**Review skill:**
+
+PR review is dispatched through the `roll-review-pr` skill. It fetches the PR
+title, body, and diff via `gh`, renders a review prompt, and routes it to the
+project's configured agent (Claude, Kimi, DeepSeek, etc.). The agent outputs a
+structured verdict:
+
+| Verdict | Action |
+|---------|--------|
+| `APPROVE` | `gh pr review --approve` |
+| `REQUEST_CHANGES` | `gh pr review --request-changes` with reason |
+| `UNCERTAIN` | Writes an ALERT — human decides |
+
+**Escape hatch:** Add `[skip-ai-review]` anywhere in the PR body to
+auto-approve without invoking the agent.
+
+**How the loop uses it:** `roll loop pr-inbox` classifies each open PR and routes
+`eligible` PRs to the `roll-review-pr` skill. Loop's own PRs (`loop/*` branches)
+are skipped to avoid same-source bias.
+
+**Stale PR rebase:** PRs classified as `stale` (CI failed or branch behind/conflicting)
+are automatically rebased onto `origin/main` by the runner's stale-PR rebase. A circuit
+breaker limits rebase attempts to 3 within 24 hours — after that, an ALERT is raised.
+Fork PRs are skipped (no write access) with an ALERT.
+
+**Bot review detection:** If a GitHub Actions bot has already reviewed the PR
+(e.g. via the optional GHA workflow), `roll loop pr-inbox` defers:
+- Bot `APPROVED` → skip, let auto-merge proceed
+- Bot `CHANGES_REQUESTED` → write ALERT (loop PR rejected by GHA reviewer)
+
+**Active merge of approved PRs (US-LOOP-062b):** when a PR is human-approved,
+CI-green, and mergeable, the PR Loop merges it directly (`gh pr merge --squash`)
+through the runner's approved-PR merge rather than waiting for repo-level auto-merge
+(which may be disabled). Merge failure is non-fatal — the PR is left open and
+retried on the next tick.
+
+### Optional: Event-driven PR review (GHA)
+
+Without extra setup, `roll loop pr-inbox` reviews eligible PRs each loop cycle
+(up to ~1 hour delay). For seconds-fast feedback on GitHub-hosted repos,
+install the event-driven workflow:
+
+```bash
+cp templates/workflows/pr-review-event.yml .github/workflows/
+```
+
+This triggers the `roll-review-pr` skill on every PR open/update. Fork PRs and PRs
+with `[skip-ai-review]` in the body are automatically skipped. The template
+requires only one API key secret — the one matching your configured agent.
+
+The two modes coexist: the GHA workflow provides instant feedback, and
+`roll loop pr-inbox` acts as a safety net if the workflow is not installed.
+
+## Session Cleanup
+
+At the end of every cycle, loop automatically prunes stale local worktrees:
+
+- Any directory under `.claude/worktrees/` whose branch has been fully merged
+  into `main` is removed (`git worktree remove --force` + `git branch -D`).
+- `git worktree prune` runs afterward to clear stale metadata.
+
+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.
+
+## Cycle phases
+
+Every cycle is sliced into seven named phases. Each phase emits a `phase_start`
+event when entered and a `phase_end` event with duration + outcome when it
+exits. Long-silent phases (claude, PR-merge wait) emit a `phase_tick` heartbeat
+so the tmux viewer never looks frozen.
+
+| # | Phase | When it runs | Typical duration |
+|---|-------|--------------|------------------|
+| 1 | `startup` | env / lock / heartbeat setup | < 1 s |
+| 2 | `preflight` | meta sync + stale-branch GC + orphan-worktree recovery | 0 s — 30 s |
+| 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 |
+
+> **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.
+
+Idle / failed / aborted cycles only emit the phases they actually entered.
+At cycle exit, the inner runner prints a phase breakdown panel sorted by
+duration descending, e.g.:
+
+```
+─── Cycle 20260523-114502-12345 Phase Breakdown ───
+  agent_invoke           723s  ( 96.2%)  ████████████████████
+  publish_wait_merge       19s  (  2.5%)  █
+  worktree_setup            4s  (  0.5%)
+  publish_push              2s  (  0.3%)
+  preflight                 2s  (  0.3%)
+  cleanup                   1s  (  0.1%)
+  startup                   1s  (  0.1%)
+  ──────────────────────────────────────
+  Total                   752s
+```
+
+Each phase duration is also persisted to `runs.jsonl` in a new top-level
+`phases` object (see [State Files](#state-files) below). `roll loop runs`
+appends `slowest=<phase> <pct>%` to each built row so you can see which step
+dominated without opening the cycle. For the full breakdown, use:
+
+```bash
+roll loop runs --detail 20260523-114502-12345
+```
+
+## Cycle Log Archive
+
+Every cycle's full agent output is archived to `.roll/cycle-logs/<cycle-id>.log`
+as an ANSI-stripped plain-text file — readable with `less`, `cat`, or any editor.
+
+- **Per-cycle archive**: one `.log` file per cycle, saved to `.roll/cycle-logs/`
+- **ANSI-stripped**: color codes and control characters removed, clean plain text
+- **Retention**: keeps the 50 most recent cycles, older ones are auto-rotated
+- **Works muted or not**: logs are saved even when `roll loop mute` is on
+
+```bash
+roll loop log                # View the most recent cycle's full log
+roll loop log <cycle-id>     # View a specific cycle (e.g. 20260525-231803-39799)
+roll loop log <prefix>       # Prefix match (e.g. 20260525 matches all May 25 cycles)
+```
+
+Cycle logs are stored inside `.roll/` (the project's meta directory) and are
+gitignored — they won't pollute your repo.
+
+## Cross-Machine Sync
+
+When you run loop on multiple machines for the same project, Roll can sync cycle
+records to a shared git repo. Every machine writes its own events file, and the
+dashboard reads all of them — you get a unified view of every cycle across every
+machine.
+
+### Setup
+
+Add a `roll_records_remote` field to `~/.roll/config.yaml`:
+
+```yaml
+roll_records_remote: "git@github.com:you/roll-loop-records.git"
+```
+
+**Private repo strongly recommended.** Cycle records contain prompt text, file
+paths, and other potentially sensitive information. Treat the records repo the
+same way you treat application logs — private, access-controlled, never public.
+
+If `roll_records_remote` is not configured, cross-machine sync is entirely
+skipped — no records leave your machine.
+
+### How it works
+
+- Each machine generates a unique machine-id (UUID v4) on first run, cached at
+  `~/.shared/roll/machine-id`.
+- Every cycle completion pushes an append-only `.ndjson` file to
+  `<slug>/events/<machine-id>.ndjson` in the records repo. Each machine only
+  writes to its own file — no merge conflicts.
+- Before rendering the dashboard, Roll runs `git pull --ff-only` on a local
+  clone at `~/.shared/roll/sync/`, reads every `*.ndjson` file, and merges
+  them sorted by timestamp with `run_id` deduplication.
+- Push and pull are best-effort background operations — if the remote is
+  unreachable, the cycle continues normally and the dashboard shows only
+  local data.
+
+### Dashboard sync indicator
+
+The dashboard footer shows one of three states:
+
+| Indicator | Meaning |
+|-----------|---------|
+| `sync: ok (2m ago)` | Remote reachable, records merged successfully |
+| `sync: offline` | Remote unreachable (network issue, auth expired) — showing local data only |
+| `sync: not configured` | `roll_records_remote` not set — sync is off, this is expected |
+
+### Fork caveat
+
+Roll derives the project slug from `git remote get-url origin`. If you change
+`origin` to point to a fork, the slug changes — records from the original repo
+and the fork will land in different directories in the records repo. This is
+intentional (different repos, different identities), but if you're temporarily
+working from a fork, be aware that the dashboard won't show the upstream's
+cycle history.
+
+## Loop Meta Sync
+
+At the start of every cycle, roll automatically pulls the latest project metadata
+(`.roll/` directory — backlog, conventions, skills) from its git remote before
+scanning for stories.
+
+**How it works**
+
+1. Detects whether `.roll/` has a configured `origin` remote.
+   If not, the step is silently skipped (no side-effects for standard roll installs).
+2. Runs `git fetch && git reset --hard origin/main` with a 15-second timeout.
+3. On success: emits a `meta_sync ok` event; cycle proceeds with fresh backlog.
+4. On failure: emits a `meta_sync stale` event; cycle continues with the existing
+   `.roll/` contents (stale is better than no-op).
+
+**After 3 consecutive failures** the loop writes an ALERT prompting you to check
+your SSH key or network connectivity.
+
+**Manual sync**
+
+```bash
+git -C .roll fetch && git -C .roll reset --hard origin/main
+```
+
+**FAQ: the loop runs but the dashboard shows an empty backlog**
+
+This usually means `.roll/` is out of date:
+- On a new machine: clone roll-meta manually into `.roll/` and configure the origin remote.
+- After reinstalling the OS: same as above — SSH key may also need re-authorization.
+- To confirm: `git -C .roll remote get-url origin` — if empty, no sync is attempted.
+
+## Remote Monitoring
+
+When you're away from your machine you can still watch the loop — backlog
+progress, Dream health, CI state — from a phone or any browser, without a local
+`roll` command. It works in two layers: a **data layer** (your machine pushes a
+status snapshot to the roll-meta repo) and a **prompt layer** (you paste a watch
+prompt into Claude Code, which reads roll-meta + the GitHub API).
+
+### Configure `roll_meta_dir`
+
+Tell roll where your roll-meta checkout lives, in `~/.roll/config.yaml`:
+
+```yaml
+# ~/.roll/config.yaml
+roll_meta_dir: ~/projects/roll-meta
+```
+
+`~` is expanded. The key is optional — if it's unset, nothing changes and no
+snapshot is pushed. If the path doesn't exist, roll prints one WARNING to the
+cron log and skips the push (the cycle is never affected).
+
+### How the automatic push works
+
+Once `roll_meta_dir` is configured, the loop pushes a fresh snapshot after
+**every** cycle — including idle cycles where no story ran, so the snapshot
+doubles as a heartbeat. The cycle runner calls
+`${roll_meta_dir}/ops/push-loop-status.sh` in the background right after the
+`cycle_end` event. The script writes `status/loop.md` and commits + pushes it to
+roll-meta. Output goes to `~/.shared/roll/push-status.log` (rotated at 1MB, 2
+copies kept).
+
+Because the loop runs on its normal schedule, `status/loop.md` stays **≤35min
+fresh** — the watch prompt always sees recent data. The push is best-effort: a
+network error, git conflict, or a >60s timeout is logged to push-status.log, the
+process is killed if it hangs, and the cycle continues. No ALERT, no retry.
+
+### Manual push
+
+You can push a snapshot by hand at any time:
+
+```bash
+bash .roll/ops/push-loop-status.sh .roll
+```
+
+(`.roll` is your project's roll-meta checkout.) This is also how you confirm the
+push pipeline works before relying on the automatic hook.
+
+### Watching from a phone or browser
+
+Open `.roll/prompts/remote-watch.md`, copy its contents, and paste them into
+Claude Code (web, mobile, or a remote IDE). The prompt does a full health check
+on first run, then polls every 15 minutes and raises an ALERT immediately on
+conditions like CI failing twice in a row or `status/loop.md` going >60min
+stale. It only reads — it never modifies `seanyao/roll`.
+
+### Troubleshooting: `status/loop.md` is stale
+
+If the snapshot's timestamp is far older than 35 minutes:
+
+1. Check `~/.shared/roll/push-status.log` — it records every push attempt and
+   any timeout or git error.
+2. Confirm `roll_meta_dir` is set and the path exists
+   (`roll config get roll_meta_dir`).
+3. Confirm `${roll_meta_dir}/ops/push-loop-status.sh` exists and is executable.
+4. Run the manual push above and watch for errors.
+
+---
+
+远程不在本机时，依然可以从手机或任意浏览器查看 loop —— backlog 进度、Dream 健康、
+CI 状态 —— 无需本地 `roll` 命令。它分两层：**数据层**（本机把状态快照 push 到
+roll-meta 仓库）和 **prompt 层**（把巡检 prompt 粘贴进 Claude Code，读 roll-meta +
+GitHub API）。
+
+### 配置 `roll_meta_dir`
+
+在 `~/.roll/config.yaml` 里告诉 roll 你的 roll-meta 检出在哪：
+
+```yaml
+# ~/.roll/config.yaml
+roll_meta_dir: ~/projects/roll-meta
+```
+
+`~` 会被展开。这个键是可选的——不配就什么都不变，也不会推快照。路径不存在时，roll 向
+cron 日志打一条 WARNING 并跳过推送（绝不影响 cycle）。
+
+### 自动 push 的工作原理
+
+配好 `roll_meta_dir` 后，loop 在**每一次** cycle 结束后推一份新快照——包括没跑故事
+的 idle cycle，所以快照同时充当心跳。cycle runner 在 `cycle_end` 事件之后，于后台调
+用 `${roll_meta_dir}/ops/push-loop-status.sh`。脚本写出 `status/loop.md` 并提交 +
+push 到 roll-meta。输出写到 `~/.shared/roll/push-status.log`（1MB 轮转，保留 2 份）。
+
+因为 loop 按固定节奏运行，`status/loop.md` 始终保持 **≤35min 新鲜**——巡检 prompt 总
+能看到近期数据。推送是 best-effort：网络错误、git 冲突或 >60s 超时都记进
+push-status.log，进程卡住会被 kill，cycle 继续。不设 ALERT，不重试。
+
+### 手动 push
+
+随时可以手动推一份快照：
+
+```bash
+bash .roll/ops/push-loop-status.sh .roll
+```
+
+（`.roll` 是你项目的 roll-meta 检出。）这也是在依赖自动 hook 前确认推送链路是否正常
+的方法。
+
+### 在手机或浏览器上巡检
+
+打开 `.roll/prompts/remote-watch.md`，复制全文，粘贴进 Claude Code（网页、手机或远端
+IDE）。该 prompt 首次执行做一次全量体检，之后每 15min 轮询一次，遇到「CI 连续两次失
+败」或「`status/loop.md` 超过 60min 未更新」等条件立即告警。它只读——绝不修改
+`seanyao/roll`。
+
+### 排障：`status/loop.md` 不更新
+
+若快照时间戳远早于 35 分钟：
+
+1. 看 `~/.shared/roll/push-status.log`——它记录每次推送尝试以及任何超时或 git 错误。
+2. 确认 `roll_meta_dir` 已配置且路径存在（`roll config get roll_meta_dir`）。
+3. 确认 `${roll_meta_dir}/ops/push-loop-status.sh` 存在且可执行。
+4. 跑一次上面的手动 push，观察是否报错。
+
+## State Files
+
+Since Phase 2.0, a project's loop state lives **inside the project** at
+`<project>/.roll/loop/`. Only machine-level binding files (launchd runners,
+attach scripts) and the global mute switch stay in `~/.shared/roll/`. See
+[Loop Data Layout](loop-data-layout.md) for the full layout, migration, and
+`roll loop gc`.
+
+自 Phase 2.0 起，项目的 loop 状态搬进了**项目目录** `<project>/.roll/loop/`。只有机
+器级绑定文件（launchd runner、attach 脚本）和全局静音开关留在 `~/.shared/roll/`。完
+整布局、迁移与 `roll loop gc` 见 [Loop 数据布局](loop-data-layout.md)。
+
+| File | Content |
+|------|---------|
+| `<project>/.roll/loop/state-<slug>.yaml` | Current/last run: status, story, agent, run_id |
+| `<project>/.roll/loop/runs.jsonl` | Append-only run history (one JSON line per cycle); each record carries a `result_eval` block (see [Cycle Result Eval](#cycle-result-eval)) |
+| `<project>/.roll/loop/events.ndjson` | Per-cycle event stream (phase_start/phase_end, …) |
+| `.roll/signals/candidates.md` | Candidate backlog drafts from self-evolution signals (`📋 待人确认`, never auto-activated) |
+| `<project>/.roll/loop/ALERT-<slug>.md` | Accumulated alerts (failures, TCR violations) |
+| `<project>/.roll/loop/PAUSE-<slug>` | Pause marker (created by `roll loop pause`) |
+| `~/.shared/roll/mute` | Global auto-attach mute marker (shared across projects) |
+
+## Degraded modes & observation
+
+- **Offline**: when a cycle fails while the network is unreachable, the loop
+  degrades to **local-only delivery** — TCR commits and green tests stay on the
+  branch, a locale-selected notice is printed, the consecutive-failure counter
+  is NOT ticked (offline never accumulates into an auto-PAUSE), and the
+  scheduler keeps breathing. The next online cycle's push/PR catches up
+  naturally.
+- **Live window for every agent**: non-claude agents (pi, kimi, codex, …) run
+  under a pseudo-terminal on macOS so their output streams line-by-line into
+  the observation window instead of buffering until exit; claude streams over
+  its own protocol unchanged.
+
+## Launchd lanes
+
+Roll owns exactly three launchd jobs per project slug: `com.roll.loop.<slug>`
+(the cycle scheduler), `com.roll.dream.<slug>` (nightly scan) and
+`com.roll.pr.<slug>` (PR inbox). `roll loop on` installs them; `roll loop off`
+uninstalls them AND sweeps any other `com.roll.*.<slug>` plist it finds —
+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.