@seanyao/roll 2026.527.1 → 2026.528.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v2026.528.2
+
+### Added
+
+- **loop 换机器跑不会再拿过期 backlog** — 每轮自动拉最新项目元数据 `[loop]`
+- **CI 红了 loop 不再干等** — 先试着自己修，修不好再找人 `[loop]`
+
+### Fixed
+
+- **`roll loop log` 现在真的能看了** — 每轮 cycle 的留档修好了 `[loop]`
+- **loop 跑完的终端窗口不再瞬间清空** — 关闭前能看到本轮摘要 `[loop]`
+
+## v2026.528.1
+
+### Added
+
+- **`roll test` — 测试隔离运行，不再误伤本机 loop 服务** `[loop]`
+
+### Fixed
+
+- **Kimi CLI 升级改名为 kimi-code 后，roll 现在能正常识别** `[loop]`
+
 ## v2026.527.1
 
 ### Added

package/README.md

@@ -69,6 +69,7 @@ roll loop on        # let AI work through the backlog (optional)
 | Configuration (env vars) | [guide/en/configuration.md](guide/en/configuration.md) | [guide/zh/configuration.md](guide/zh/configuration.md) |
 | Skill selection guide | [guide/en/skills.md](guide/en/skills.md) | [guide/zh/skills.md](guide/zh/skills.md) |
 | Slides (deck generator) | [guide/en/slides.md](guide/en/slides.md) | [guide/zh/slides.md](guide/zh/slides.md) |
+| Test isolation (`roll test` + Tart VM) | [guide/en/test-isolation.md](guide/en/test-isolation.md) | [guide/zh/test-isolation.md](guide/zh/test-isolation.md) |
 | Cross-machine sync | [guide/en/loop.md#cross-machine-sync](guide/en/loop.md#cross-machine-sync) | [guide/zh/loop.md#跨机器同步](guide/zh/loop.md#%E8%B7%A8%E6%9C%BA%E5%99%A8%E5%90%8C%E6%AD%A5) |
 | Pricing (cost visibility) | [guide/en/pricing.md](guide/en/pricing.md) | [guide/zh/pricing.md](guide/zh/pricing.md) |
 | FAQ (troubleshooting) | [guide/en/faq.md](guide/en/faq.md) | [guide/zh/faq.md](guide/zh/faq.md) |

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.527.1"
+VERSION="2026.528.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -70,6 +70,11 @@ ai_tool_name() {
   # Antigravity (agy) reuses ~/.gemini/ from the deprecated Gemini CLI for
   # its config dir, so a literal `gemini` basename now identifies agy.
   [[ "$bn" == "gemini" ]] && bn="agy"
+  # FIX-126: Kimi upstream renamed its CLI to kimi-code and its config dir
+  # to ~/.kimi-code/; map both old and new basenames to the canonical
+  # "kimi" agent identifier so downstream argv / config / sync paths stay
+  # uniform across the upgrade.
+  [[ "$bn" == "kimi-code" ]] && bn="kimi"
   echo "$bn"
 }
 
@@ -266,6 +271,7 @@ _ensure_config_entries() {
     "ai_claude:~/.claude|CLAUDE.md|CLAUDE.md"
     "ai_agy:~/.gemini|GEMINI.md|GEMINI.md"
     "ai_kimi:~/.kimi|AGENTS.md|AGENTS.md"
+    "ai_kimi_code:~/.kimi-code|AGENTS.md|AGENTS.md"
     "ai_codex:~/.codex|AGENTS.md|AGENTS.md"
     "ai_cursor:~/.cursor|.cursor-rules|.cursor-rules"
     "ai_trae:~/.trae|user_rules.md|project_rules.md"
@@ -490,6 +496,7 @@ _install_local() {
 ai_claude: ~/.claude|CLAUDE.md|CLAUDE.md
 ai_gemini: ~/.gemini|GEMINI.md|GEMINI.md
 ai_kimi: ~/.kimi|AGENTS.md|AGENTS.md
+ai_kimi_code: ~/.kimi-code|AGENTS.md|AGENTS.md
 ai_codex: ~/.codex|AGENTS.md|AGENTS.md
 ai_cursor: ~/.cursor|.cursor-rules|.cursor-rules
 ai_trae: ~/.trae|user_rules.md|project_rules.md
@@ -740,6 +747,22 @@ _setup_snapshot() {
 # _ROLL_SETUP_STATE. Caller passes the watch dir(s) plus the command + args.
 # stdout/stderr of the inner command are suppressed (same as the previous
 # pattern in cmd_setup) to keep the v2 UI render the only user-visible output.
+# US-INFRA-008: ensure core.hooksPath is set to 'hooks' so TCR pre-commit gate
+# is never silently bypassed in new clones, worktrees, or automated environments.
+# Idempotent: already set to a non-default value → leave it (user knows better).
+# Not a git repo → silently skip.
+_ensure_hooks_path() {
+  local repo_path="${1:-$PWD}"
+  # Must be a git repo
+  git -C "$repo_path" rev-parse --git-dir >/dev/null 2>&1 || return 0
+  local current; current=$(git -C "$repo_path" config core.hooksPath 2>/dev/null || echo "")
+  # Only set when unset or pointing at the git default (.git/hooks)
+  if [[ -z "$current" || "$current" == ".git/hooks" ]]; then
+    git -C "$repo_path" config core.hooksPath hooks 2>/dev/null || true
+  fi
+  return 0
+}
+
 _run_setup_step() {
   local watch="$1"; shift
   local before after
@@ -782,7 +805,7 @@ cmd_setup() {
     esac
   }
 
-  local _ai_dirs="$HOME/.claude:$HOME/.gemini:$HOME/.kimi:$HOME/.codex:$HOME/.cursor:$HOME/.trae:$HOME/.config/opencode:$HOME/.openclaw:$HOME/.pi:$HOME/.deepseek:$HOME/.qwen"
+  local _ai_dirs="$HOME/.claude:$HOME/.gemini:$HOME/.kimi:$HOME/.kimi-code:$HOME/.codex:$HOME/.cursor:$HOME/.trae:$HOME/.config/opencode:$HOME/.openclaw:$HOME/.pi:$HOME/.deepseek:$HOME/.qwen"
 
   _run_setup_step "$ROLL_HOME" _install_local "$force"
   _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Install templates & conventions to ~/.roll"
@@ -796,6 +819,10 @@ cmd_setup() {
   _run_setup_step "$ROLL_HOME/.peer-state" _peer_ensure_state_dir
   _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Initialize peer-review state directory"
 
+  # US-INFRA-008: configure git hooks path so TCR pre-commit gate works in this repo
+  _run_setup_step "$PWD" _ensure_hooks_path
+  _record "$(_state_to_marker "$_ROLL_SETUP_STATE")" "Configure git hooks path"
+
   if command -v tmux >/dev/null 2>&1; then
     _record skip "Ensure tmux is installed (already present)"
   else
@@ -1928,6 +1955,18 @@ PY
     return 0
   fi
 
+  # FIX-125: cycle-context tripwire. Apply phase below runs launchctl unload
+  # and rm against ${HOME}/Library/LaunchAgents/<plist> (bin/roll:1957-1958).
+  # From inside a loop cycle this would mutate the host's launchd domain
+  # using another project's identity. Doc-only offboards (no plists) stay
+  # allowed so cycles can still call offboard for non-launchd cleanup.
+  if [ "${#plists[@]}" -gt 0 ] && _loop_in_cycle; then
+    err "Refusing to unload launchd plists from inside a loop cycle (FIX-125)."
+    echo "  Run 'roll offboard --confirm' from a terminal outside the cycle," >&2
+    echo "  or pause the loop first: 'roll loop pause'." >&2
+    return 1
+  fi
+
   # Apply. Guard every loop with a count check — `set -u` upstream makes
   # naked `"${arr[@]}"` over an empty array a hard error on bash 5.0.
   echo "$(msg offboard.applying_offboard)"
@@ -2700,7 +2739,7 @@ _peer_dispatch_in_tmux() {
   {
     printf '#!/bin/bash -l\n'
     # FIX-050: portable PATH assembly (was hardcoded /opt/homebrew/bin)
-    printf 'for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "$HOME/.local/bin"; do\n'
+    printf 'for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "$HOME/.local/bin" "$HOME/.kimi-code/bin"; do\n'
     printf '  case ":$PATH:" in *":$_d:"*) ;; *) [ -d "$_d" ] && PATH="$_d:$PATH" ;; esac\n'
     printf 'done; export PATH\n'
     printf '%s > %q 2> %q || true\n' "$cmd_str" "$out_file" "$err_file"
@@ -3133,9 +3172,20 @@ _agent_argv() {
         *)           _AGENT_ARGV=(claude -p "$prompt") ;;
       esac ;;
     kimi)
+      # FIX-126: Kimi upstream renamed binary from kimi-cli → kimi-code.
+      # Prefer the new name when present; fall back through legacy names
+      # so users mid-upgrade keep working until they reinstall.
+      local _kimi_bin
+      if command -v kimi-code >/dev/null 2>&1; then
+        _kimi_bin=kimi-code
+      elif command -v kimi-cli >/dev/null 2>&1; then
+        _kimi_bin=kimi-cli
+      else
+        _kimi_bin=kimi
+      fi
       case "$mode" in
-        interactive) _AGENT_ARGV=(kimi "$prompt") ;;
-        *)           _AGENT_ARGV=(kimi --quiet -p "$prompt") ;;
+        interactive) _AGENT_ARGV=("$_kimi_bin" "$prompt") ;;
+        *)           _AGENT_ARGV=("$_kimi_bin" --quiet -p "$prompt") ;;
       esac ;;
     deepseek)
       # deepseek has the same argv shape in both modes (positional prompt).
@@ -4417,6 +4467,397 @@ cmd_agent() {
   esac
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# ISOLATION — pluggable adapter for running tests in an isolated environment
+# (US-ISO-001). Phase 1 supports two providers: `none` (default — direct host
+# execution) and `tart` (US-ISO-002 — macOS VM). The dispatcher reads
+# .roll/local.yaml's `test_isolation.type` and routes to
+# `_isolation_<type>_<method>`. See .roll/features/engineering-infrastructure/
+# dev-vm-isolation-plan.md for the full interface contract.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_ISOLATION_SUPPORTED_TYPES="none tart"
+
+# Read test_isolation.type from .roll/local.yaml. Falls back to "none" when
+# the file or key is missing. Uses python3+yaml for nested-key parsing,
+# matching the parser used by cmd_offboard.
+_isolation_get_type() {
+  local val=""
+  if [[ -f .roll/local.yaml ]] && command -v python3 >/dev/null 2>&1; then
+    val=$(python3 - <<'PY' 2>/dev/null
+import sys
+try:
+    import yaml
+except ImportError:
+    sys.exit(0)
+try:
+    data = yaml.safe_load(open(".roll/local.yaml")) or {}
+except Exception:
+    sys.exit(0)
+section = data.get("test_isolation")
+if isinstance(section, dict):
+    t = section.get("type")
+    if isinstance(t, str) and t:
+        print(t)
+PY
+    )
+  fi
+  if [[ -z "$val" ]]; then
+    val="none"
+  fi
+  printf '%s\n' "$val"
+}
+
+# Dispatch an isolation-adapter method to the configured provider.
+# Usage: _isolation_dispatch <method> [args...]
+# Methods: init / provision / exec / status / reset / destroy
+_isolation_dispatch() {
+  local method="$1"; shift || true
+  if [[ -z "$method" ]]; then
+    err "isolation: missing method"
+    echo "  usage: _isolation_dispatch <init|provision|exec|status|reset|destroy> [args...]" >&2
+    return 1
+  fi
+
+  # Resolve provider; emit a fallback-INFO line only when the config file is
+  # missing (so an explicit `type: none` stays quiet). Goes to stderr so the
+  # actual dispatch output (e.g. exec stdout) stays clean.
+  local type; type=$(_isolation_get_type)
+  if [[ "$type" = "none" ]] && [[ ! -f .roll/local.yaml ]]; then
+    info "isolation: no test_isolation config, falling back to type=none (host)" >&2
+  fi
+
+  # Reject unknown types up front so the error names the provider, not the
+  # missing function — this is the difference between "you typed it wrong"
+  # and "the adapter is broken".
+  local supported_ok=0 t
+  for t in $_ISOLATION_SUPPORTED_TYPES; do
+    [[ "$type" = "$t" ]] && supported_ok=1
+  done
+  if (( ! supported_ok )); then
+    err "isolation: unknown type '$type' in .roll/local.yaml"
+    echo "  supported types: ${_ISOLATION_SUPPORTED_TYPES// /, }" >&2
+    return 1
+  fi
+
+  local fn="_isolation_${type}_${method}"
+  if ! declare -F "$fn" >/dev/null 2>&1; then
+    err "isolation: provider '$type' has no '${method}' implementation"
+    return 1
+  fi
+  "$fn" "$@"
+}
+
+# ── `none` adapter (default — direct host execution) ──────────────────────
+# init / provision / destroy are no-ops; exec runs the command in the host
+# shell unchanged; status is always 'ready'; reset is a benign no-op
+# (US-ISO-004 will print an explanatory message when invoked via roll test).
+_isolation_none_init()      { return 0; }
+_isolation_none_provision() { return 0; }
+_isolation_none_exec()      { "$@"; }
+_isolation_none_status()    { echo "ready"; return 0; }
+_isolation_none_reset() {
+  # US-ISO-004 AC: type=none has nothing to reset; print explanation but
+  # exit 0 (not a failure — host execution is already as clean as it gets).
+  info "isolation type 'none' has nothing to reset (host execution is stateless)" >&2
+  return 0
+}
+_isolation_none_destroy()   { return 0; }
+
+# ─── reset lock (US-ISO-004) ──────────────────────────────────────────────
+# A single lockfile under .roll/ prevents two `roll test --reset` runs from
+# racing, and forces concurrent `roll test` test-execution paths to bail
+# fast rather than blocking on a half-rebuilt VM. --where is read-only and
+# deliberately bypasses the lock.
+_isolation_reset_lock_path() {
+  echo ".roll/.iso-reset.lock"
+}
+
+_isolation_reset_lock_held() {
+  [[ -f "$(_isolation_reset_lock_path)" ]]
+}
+
+# Returns 0 if the caller now holds the lock; 1 if someone else does.
+_isolation_reset_acquire_lock() {
+  local lock; lock=$(_isolation_reset_lock_path)
+  if [[ -f "$lock" ]]; then
+    return 1
+  fi
+  mkdir -p "$(dirname "$lock")"
+  echo "$$" > "$lock"
+  return 0
+}
+
+_isolation_reset_release_lock() {
+  rm -f "$(_isolation_reset_lock_path)"
+}
+
+# ── `tart` adapter (US-ISO-002 — macOS Apple Silicon VM via Tart) ─────────
+# Test override hooks (used by unit tests; default values keep prod stable):
+#   _TART_VM_NAME      — VM identifier (default: roll-dev-test)
+#   _TART_BASE_IMAGE   — OCI base image (default: cirruslabs macos-tahoe-base)
+#   _TART_SSH_USER     — SSH user inside the VM (default: admin)
+
+_isolation_tart_vm_name()    { printf '%s\n' "${_TART_VM_NAME:-roll-dev-test}"; }
+_isolation_tart_base_image() { printf '%s\n' "${_TART_BASE_IMAGE:-ghcr.io/cirruslabs/macos-tahoe-base:latest}"; }
+_isolation_tart_ssh_user()   { printf '%s\n' "${_TART_SSH_USER:-admin}"; }
+
+_isolation_tart_check_platform() {
+  if [[ "$(uname)" != "Darwin" ]] || [[ "$(uname -m)" != "arm64" ]]; then
+    err "Tart 仅支持 Apple Silicon macOS"
+    err "Tart only supports Apple Silicon macOS"
+    return 1
+  fi
+  return 0
+}
+
+_isolation_tart_check_binary() {
+  if ! command -v tart >/dev/null 2>&1; then
+    err "tart binary not found"
+    err "  install via: brew install cirruslabs/cli/tart"
+    return 1
+  fi
+  return 0
+}
+
+# Returns 0 with the VM name on stdout when the VM is in `tart list`,
+# returns 1 silently otherwise. Caller decides what to do.
+_isolation_tart_vm_present() {
+  local name; name=$(_isolation_tart_vm_name)
+  tart list 2>/dev/null | awk -v n="$name" '$1 == n { found=1 } END { exit !found }'
+}
+
+# Returns the VM's IP on stdout when reachable; exit non-zero when the VM
+# is stopped or `tart ip` fails for any other reason.
+_isolation_tart_ip() {
+  local name; name=$(_isolation_tart_vm_name)
+  local ip; ip=$(tart ip "$name" 2>/dev/null) || return 1
+  [[ "$ip" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]] || return 1
+  printf '%s\n' "$ip"
+}
+
+# Status state machine — see dev-vm-isolation-plan.md §4.
+# Returns one of: not-installed | stopped | running | ready
+_isolation_tart_status() {
+  _isolation_tart_check_platform >/dev/null 2>&1 || { echo "not-installed"; return 0; }
+  command -v tart >/dev/null 2>&1 || { echo "not-installed"; return 0; }
+  _isolation_tart_vm_present || { echo "not-installed"; return 0; }
+  local ip
+  if ! ip=$(_isolation_tart_ip); then
+    echo "stopped"
+    return 0
+  fi
+  # VM up. Is it provisioned? A trivial SSH probe is the cheapest check.
+  local user; user=$(_isolation_tart_ssh_user)
+  if ssh -o BatchMode=yes -o ConnectTimeout=3 -o StrictHostKeyChecking=no \
+         "${user}@${ip}" "true" >/dev/null 2>&1; then
+    echo "ready"
+  else
+    echo "running"
+  fi
+  return 0
+}
+
+# init: ensure the base image is cloned into our VM slot. Idempotent —
+# `tart clone` is skipped when the VM already exists.
+_isolation_tart_init() {
+  _isolation_tart_check_platform || return 1
+  _isolation_tart_check_binary || return 1
+  local name; name=$(_isolation_tart_vm_name)
+  if _isolation_tart_vm_present; then
+    return 0
+  fi
+  local img; img=$(_isolation_tart_base_image)
+  tart clone "$img" "$name"
+}
+
+# provision: ensure runtime deps are installed inside the VM. Idempotent —
+# brew install no-ops for already-installed packages. Requires the VM to
+# be running with SSH responsive (caller's responsibility, usually exec).
+_isolation_tart_provision() {
+  _isolation_tart_check_platform || return 1
+  _isolation_tart_check_binary || return 1
+  local ip; ip=$(_isolation_tart_ip) || { err "tart provision: VM not running"; return 1; }
+  local user; user=$(_isolation_tart_ssh_user)
+  ssh -o BatchMode=yes -o StrictHostKeyChecking=no \
+      "${user}@${ip}" "brew list bats >/dev/null 2>&1 || brew install bats-core; \
+                       brew list node >/dev/null 2>&1 || brew install node; \
+                       brew list bash >/dev/null 2>&1 || brew install bash"
+}
+
+# exec: run the command inside the VM. Auto-starts the VM if it's stopped.
+# Mounts the host worktree at /Volumes/My Shared Files/roll (Tart virtiofs).
+_isolation_tart_exec() {
+  _isolation_tart_check_platform || return 1
+  _isolation_tart_check_binary || return 1
+  local name; name=$(_isolation_tart_vm_name)
+  local ip
+  if ! ip=$(_isolation_tart_ip); then
+    # VM stopped — start it in the background with the repo mounted.
+    local repo_root; repo_root="$(pwd -P)"
+    tart run --dir="roll:${repo_root}" "$name" >/dev/null 2>&1 &
+    # Wait up to ~30s for IP to come up.
+    local i=0
+    while (( i < 30 )); do
+      if ip=$(_isolation_tart_ip); then break; fi
+      sleep 1
+      i=$((i + 1))
+    done
+    [[ -n "${ip:-}" ]] || { err "tart exec: VM failed to start in 30s"; return 1; }
+  fi
+  local user; user=$(_isolation_tart_ssh_user)
+  ssh -o BatchMode=yes -o StrictHostKeyChecking=no "${user}@${ip}" "$@"
+}
+
+# reset: stop, delete, re-clone from base image, then re-provision.
+# Target: ≤90s (caller's perception); actual depends on tart clone speed.
+# Clone is called directly (not via init) so the sequence is unconditional —
+# tart's own "VM exists" check still no-ops re-clone if delete didn't take.
+_isolation_tart_reset() {
+  _isolation_tart_check_platform || return 1
+  _isolation_tart_check_binary || return 1
+  local name; name=$(_isolation_tart_vm_name)
+  local img; img=$(_isolation_tart_base_image)
+  tart stop "$name" 2>/dev/null || true
+  tart delete "$name" 2>/dev/null || true
+  tart clone "$img" "$name" || return 1
+  _isolation_tart_provision || true   # provision may fail mid-reset; surface
+                                       # via subsequent status check.
+}
+
+# destroy: stop + delete. Doesn't rebuild.
+_isolation_tart_destroy() {
+  _isolation_tart_check_platform || return 1
+  _isolation_tart_check_binary || return 1
+  local name; name=$(_isolation_tart_vm_name)
+  tart stop "$name" 2>/dev/null || true
+  tart delete "$name" 2>/dev/null || true
+  return 0
+}
+
+# ─── cmd_test ────────────────────────────────────────────────────────────
+# US-ISO-003: `roll test` — runs the project's test suite through the
+# isolation dispatcher. The configured `test_isolation.type` determines
+# where the tests execute (host shell vs Tart VM). When type=tart and
+# the VM fails to start, the failure surfaces non-zero — no silent
+# fallback to host, since that would lie about where the tests ran.
+
+# Print where the test suite will execute. Format is machine-readable
+# (one token, optionally with a colon-separated detail) so scripts can
+# parse it: `host`, `tart:<ip>`, `tart:stopped`, `tart:not-installed`, …
+_cmd_test_where() {
+  local type; type=$(_isolation_get_type)
+  case "$type" in
+    none)
+      echo "host"
+      ;;
+    tart)
+      local st; st=$(_isolation_tart_status)
+      case "$st" in
+        ready|running)
+          local ip
+          if ip=$(_isolation_tart_ip 2>/dev/null); then
+            echo "tart:${ip}"
+          else
+            echo "tart:${st}"
+          fi
+          ;;
+        *)
+          echo "tart:${st}"
+          ;;
+      esac
+      ;;
+    *)
+      echo "unknown:${type}"
+      ;;
+  esac
+}
+
+cmd_test() {
+  # US-ISO-005: `--help` / `-h` anywhere in pre-`--` args shows help and
+  # exits 0, so `roll test --reset --help` is a help lookup, not a reset.
+  # Args appearing after `--` are forwarded verbatim and not intercepted.
+  local _a
+  for _a in "$@"; do
+    case "$_a" in
+      --) break ;;
+      --help|-h) set -- --help; break ;;
+    esac
+  done
+  case "${1:-}" in
+    --help|-h)
+      cat <<'EOF'
+Usage: roll test [--where | --reset] [--] [<extra-args>...]
+
+Runs the project's test suite through the isolation adapter chosen in
+.roll/local.yaml:
+
+  test_isolation:
+    type: none   (default)   Direct host execution — same shell as `npm test`.
+    type: tart               Inside the Apple-Silicon `roll-dev-test` Tart VM,
+                             so tests can't reach the host's launchd / shared
+                             roll state. Tart isn't auto-installed; run
+                             `brew install cirruslabs/cli/tart` first.
+
+Flags:
+  --where        Print where tests will run, then exit (e.g. `host`,
+                 `tart:192.168.64.5`, `tart:stopped`).
+  --reset        Rebuild the isolation environment to a clean baseline.
+                 type=tart: stop → delete → clone → provision (~90s).
+                 type=none: prints a note and exits 0 (host is stateless).
+                 Holds a lockfile under .roll/.iso-reset.lock; concurrent
+                 `roll test` invocations fast-fail with a clear error.
+  --help, -h     Show this help.
+
+Examples:
+  roll test                    Run the suite in whatever the config says.
+  roll test -- --tier=fast     Forward arguments to npm test.
+  roll test --where            Don't run; just report routing.
+  roll test --reset            Rebuild the VM (or host no-op).
+
+When type=tart and the VM can't be reached, the command exits non-zero
+rather than silently falling back to host execution.
+EOF
+      return 0
+      ;;
+    --where)
+      _cmd_test_where
+      return 0
+      ;;
+    --reset)
+      # Refuse if another reset is in progress — fast-fail beats blocking
+      # on a half-rebuilt VM (US-ISO-004 AC).
+      if _isolation_reset_lock_held; then
+        err "roll test --reset: another reset is already in progress"
+        echo "  lock: $(_isolation_reset_lock_path) (delete manually if stale)" >&2
+        return 1
+      fi
+      _isolation_reset_acquire_lock || {
+        err "roll test --reset: failed to acquire reset lock"
+        return 1
+      }
+      # Make sure the lock comes off no matter how dispatch exits.
+      trap '_isolation_reset_release_lock' RETURN
+      _isolation_dispatch reset
+      return $?
+      ;;
+    --)
+      shift
+      ;;
+  esac
+
+  # Test-execution path. If a reset is in progress, bail rather than racing
+  # into a half-rebuilt VM — user can `roll test --where` to inspect state.
+  if _isolation_reset_lock_held; then
+    err "roll test: a reset is in progress (lock: $(_isolation_reset_lock_path))"
+    echo "  re-run once the reset completes, or delete the lockfile if stale" >&2
+    return 1
+  fi
+
+  # Pass remaining args through to npm test inside the configured adapter.
+  _isolation_dispatch exec npm test "$@"
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # LOOP — autonomous BACKLOG executor management
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -5142,6 +5583,8 @@ _detect_path_prepend() {
   [[ -d /usr/local/bin ]] && dirs+=("/usr/local/bin")
   [[ -d /opt/local/bin ]] && dirs+=("/opt/local/bin")
   [[ -d "$HOME/.local/bin" ]] && dirs+=("$HOME/.local/bin")
+  # FIX-129: kimi-code installs to ~/.kimi-code/bin (not brew/local), launchd misses it
+  [[ -d "$HOME/.kimi-code/bin" ]] && dirs+=("$HOME/.kimi-code/bin")
   dirs+=("/usr/bin" "/bin" "/usr/sbin" "/sbin")
   for d in "${dirs[@]}"; do
     case ":$seen:" in *":$d:"*) continue ;; esac
@@ -5307,7 +5750,7 @@ set -o pipefail
 # FIX-050: portable PATH assembly — launchd/cron deliver a bare PATH that
 # misses brew-installed tools (tmux, claude, node, …). Iterate candidate
 # dirs; only prepend when present and not already in PATH. Idempotent.
-for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin"; do
+for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin" "\$HOME/.kimi-code/bin"; do
   case ":\$PATH:" in *":\$_d:"*) ;; *) [ -d "\$_d" ] && PATH="\$_d:\$PATH" ;; esac
 done
 export PATH
@@ -5640,6 +6083,10 @@ _phase_begin startup
 _phase_end startup ok
 _phase_begin preflight
 cd "${project_path}" 2>/dev/null || true
+# US-INFRA-008: ensure git hooks are wired so TCR pre-commit gate can't be bypassed
+_ensure_hooks_path "${project_path}" 2>/dev/null || true
+# US-LOOP-056: sync .roll/ meta from roll-meta remote before backlog scan
+_loop_sync_meta "${project_path}" || true
 # FIX-104: GC stale merged temp branches at cycle entry — before worktree setup
 # and before any early-exit gate (pre-run abort, CI red precheck). The post-claude
 # call site doesn't cover those paths, so merged branches accumulated on origin.
@@ -5951,7 +6398,7 @@ INNER
 # FIX-050: portable PATH assembly before any brew-tool lookup (tmux, caffeinate
 # on some systems, claude). Mirrors the inner script's bootstrap so even when
 # launchd's plist EnvironmentVariables is stale, the runner self-repairs.
-for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin"; do
+for _d in /opt/homebrew/bin /usr/local/bin /opt/local/bin "\$HOME/.local/bin" "\$HOME/.kimi-code/bin"; do
   case ":\$PATH:" in *":\$_d:"*) ;; *) [ -d "\$_d" ] && PATH="\$_d:\$PATH" ;; esac
 done
 export PATH
@@ -6038,10 +6485,24 @@ if command -v tmux >/dev/null 2>&1; then
   tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^roll-loop-${slug}\$" | while read _s; do
     tmux kill-session -t "\$_s" 2>/dev/null || true
   done
-  tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
-  CYCLE_LOG_RAW="${project_path}/.roll/cycle-logs/.pipe-\$\$.raw"
+  # FIX-132: syntax-check the inner script before spawning the tmux session.
+  # A heredoc quoting regression or mid-cycle regeneration can silently produce
+  # a syntactically broken script; catching it here prevents the session from
+  # starting in a corrupted state and logging a misleading "exited 0, retrying".
+  if ! bash -n "\$INNER_SCRIPT" 2>>"\$LOG"; then
+    echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] ABORT: inner script failed syntax check — cycle skipped (see log: \$LOG)" >> "\$LOG"
+    exit 1
+  fi
+  # FIX-130: export ROLL_CYCLE_LOG_RAW BEFORE spawning the tmux session so
+  # the inner script inherits it (env vars are inherited at spawn time, not
+  # retroactively — exporting after new-session means inner never sees it and
+  # _inner_cleanup skips log archiving, leaving only orphan .pipe-*.raw files).
   mkdir -p "${project_path}/.roll/cycle-logs"
+  # Clean orphan .pipe-*.raw files from previous crashed cycles
+  find "${project_path}/.roll/cycle-logs" -name '.pipe-*.raw' -delete 2>/dev/null || true
+  CYCLE_LOG_RAW="${project_path}/.roll/cycle-logs/.pipe-\$\$.raw"
   export ROLL_CYCLE_LOG_RAW="\$CYCLE_LOG_RAW"
+  tmux new-session -d -s "\$SESSION" -x 200 -y 50 "bash \"\$INNER_SCRIPT\""
   tmux pipe-pane -t "\$SESSION" "tee -a \"\$LOG\" >> \"\$ROLL_CYCLE_LOG_RAW\""
   # Auto-attach popup: when not muted, spawn a Terminal.app window attached
   # to the tmux session so the user can watch the loop work in real time.
@@ -6060,7 +6521,9 @@ if command -v tmux >/dev/null 2>&1; then
     # window closes the instant the tmux session ends (cycle_end kills
     # the session) and the entire scrollback disappears with it; the
     # cron-<slug>.log file still has the full transcript as a fallback.
-    printf '#!/bin/bash\\ntmux attach -t %s\\necho\\necho "================================================================"\\necho "  cycle ended. log: ~/.shared/roll/loop/cron-%s.log"\\necho "  press enter to close this window."\\necho "================================================================"\\nread _\\n' \\
+    # FIX-131: after tmux session ends, open the cron log with less so the
+    # user can scroll through the full cycle output instead of seeing nothing.
+    printf '#!/bin/bash\\ntmux attach -t %s 2>/dev/null\\nLOGFILE=~/.shared/roll/loop/cron-%s.log\\necho\\nif [ -f "\$LOGFILE" ]; then\\n  echo "================================================================"\\n  echo "  Cycle ended  —  showing log (arrows to scroll, q to close)"\\n  echo "================================================================"\\n  less -R +G "\$LOGFILE"\\nelse\\n  echo "================================================================"\\n  echo "  Cycle ended. Log not found: \$LOGFILE"\\n  echo "  press enter to close."\\n  echo "================================================================"\\n  read _\\nfi\\n' \\
       "\$SESSION" "${slug}" > "\$_attach_cmd" 2>/dev/null || true
     chmod +x "\$_attach_cmd" 2>/dev/null || true
     open -g -a Terminal "\$_attach_cmd" >/dev/null 2>&1 || true
@@ -6289,10 +6752,11 @@ cmd_loop() {
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
     gc)      shift; _loop_gc "$@" ;;
-    notify)       _notify "${1:-roll}" "${2:-}" ;;
-    enforce-tcr)  _loop_enforce_tcr "${1:-}" "${2:-}" ;;
-    precheck-ci)  _loop_precheck_ci ;;
-    branches)     _loop_branches "$(pwd -P)" ;;
+    notify)               _notify "${1:-roll}" "${2:-}" ;;
+    enforce-tcr)          _loop_enforce_tcr "${1:-}" "${2:-}" ;;
+    precheck-ci)          _loop_precheck_ci ;;
+    hotfix-head-context)  _loop_hotfix_head_context "${1:-}" ;;
+    branches)             _loop_branches "$(pwd -P)" ;;
     *)  cat <<'HELP'
 Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mute|unmute|pause|resume|reset|gc|branches>
 
@@ -6768,11 +7232,33 @@ _loop_attach() {
   exec tmux attach -t "$session"
 }
 
+# FIX-125: detect whether we are running inside a loop cycle. Cycle context
+# is signalled by env vars exported by the cycle runner (ROLL_LOOP_AGENT,
+# bin/roll:5736) or by the outer cycle script (ROLL_CYCLE_LOG_RAW,
+# bin/roll:6044). Used by callers that touch canonical ${HOME}/Library/LaunchAgents
+# directly (_loop_gc, cmd_offboard) to refuse host-loop mutations from inside
+# a cycle. Read-only ops are unaffected.
+_loop_in_cycle() {
+  [[ -n "${ROLL_LOOP_AGENT:-}" || -n "${ROLL_CYCLE_LOG_RAW:-}" ]]
+}
+
 # US-LOOP-021: garbage-collect orphan slugs, tmp debris, and expired backups.
 # Usage: _loop_gc [--dry-run] [--keep-days N]
 # Keeps backups/migrated files within N days (default 30).
 # Retention order: ROLL_LOOP_GC_RETENTION_DAYS env > .roll/local.yaml loop_gc.retention_days > 30.
 _loop_gc() {
+  # FIX-125: refuse from inside a loop cycle. Phase 1 below scans/mutates
+  # ${HOME}/Library/LaunchAgents directly (bin/roll:6814,6847) — running it
+  # from a cycle would let one project's tick remove another project's plist
+  # under the host's launchd domain. Read-only ops (status, runs) are
+  # unaffected; only the GC mutator is gated.
+  if _loop_in_cycle; then
+    echo "roll loop gc: refusing — cycle-context tripwire (FIX-125)" >&2
+    echo "  This command scans ~/Library/LaunchAgents directly. Running it" >&2
+    echo "  from inside a loop cycle is a known host-state corruption path." >&2
+    return 1
+  fi
+
   local dry_run=false
   local keep_days=30
 
@@ -7298,6 +7784,66 @@ _ci_wait() {
 }
 
 # Pre-run CI health check — call before picking up new stories.
+# US-LOOP-056: sync .roll/ (roll-meta private submodule) before each cycle so
+# the cycle always runs against the latest backlog. Fail-soft: any error emits
+# a meta_sync event and returns 0 so the cycle continues with stale/existing meta.
+#
+# Statuses emitted via _loop_event meta_sync:
+#   ok      – fetch + reset --hard succeeded
+#   stale   – fetch failed; existing .roll/ used as fallback
+#   skipped – no git remote configured (not a roll-meta managed project)
+#
+# Env override: ROLL_LOOP_META_SYNC_TIMEOUT (default 15) controls fetch timeout.
+_loop_sync_meta() {
+  local project_path="$1"
+  local roll_meta="${project_path}/.roll"
+  local timeout_sec="${ROLL_LOOP_META_SYNC_TIMEOUT:-15}"
+  local cid="${CYCLE_ID:-unknown}"
+  local slug="${_LOOP_PROJ_SLUG:-$(_project_slug 2>/dev/null || echo unknown)}"
+  local shared_dir="${_SHARED_ROOT:-$HOME/.shared/roll}/loop"
+  local fail_counter="${shared_dir}/meta-sync-fail-${slug}"
+
+  # Detect remote via the canonical probe point. If .roll/ has no .git or no
+  # remote configured, treat as "not managed" and skip silently.
+  local remote_url
+  remote_url=$(git -C "$roll_meta" remote get-url origin 2>/dev/null || echo "")
+  if [ -z "$remote_url" ]; then
+    return 0
+  fi
+
+  # Attempt fetch with timeout
+  local _fetch_ok=0
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$timeout_sec" git -C "$roll_meta" fetch --quiet 2>/dev/null && _fetch_ok=1
+  else
+    git -C "$roll_meta" fetch --quiet 2>/dev/null && _fetch_ok=1
+  fi
+
+  if [ "$_fetch_ok" -eq 1 ]; then
+    if git -C "$roll_meta" reset --hard origin/main --quiet 2>/dev/null; then
+      _loop_event meta_sync "$cid" "ok" "" 2>/dev/null || true
+      # US-LOOP-057: reset consecutive failure counter on success
+      rm -f "$fail_counter" 2>/dev/null || true
+      return 0
+    fi
+  fi
+
+  # Fetch or reset failed — stale .roll/ used; cycle continues
+  _loop_event meta_sync "$cid" "stale" "fetch/reset failed" 2>/dev/null || true
+
+  # US-LOOP-057: increment failure counter; write ALERT after 3 consecutive failures
+  mkdir -p "$shared_dir" 2>/dev/null || true
+  local count=0
+  [ -f "$fail_counter" ] && count=$(cat "$fail_counter" 2>/dev/null || echo 0)
+  count=$(( count + 1 ))
+  printf '%s\n' "$count" > "$fail_counter"
+  if [ "$count" -ge 3 ]; then
+    printf '[%s] roll-meta sync consecutive failures: %d times. Check SSH key / network.\n  Last error: fetch/reset failed for %s\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$count" "$remote_url" >> "${shared_dir}/ALERT-${slug}.md" 2>/dev/null || true
+  fi
+  return 0
+}
+
 # Refuses to build on a red base (HEAD CI failed). Lenient on unknown states
 # (gh missing, repo unparseable, no runs yet) — the post-build _loop_enforce_ci
 # is the strict gate.
@@ -7330,6 +7876,38 @@ _loop_precheck_ci() {
     run_states=$(echo "$runs" \
       | jq -r '[.[] | "\(.status // "?")/\(.conclusion // "null")"] | unique | join(", ")' \
       2>/dev/null || echo "?")
+
+    # US-LOOP-046/048: check whether hot-fix path is allowed before aborting.
+    # ROLL_LOOP_NO_HEAL=1 or ROLL_LOOP_HEAL_MAX=0 → fall through to original abort.
+    local _heal_max="${ROLL_LOOP_HEAL_MAX:-2}"
+    if [[ "${ROLL_LOOP_NO_HEAL:-}" != "1" ]] && [[ "$_heal_max" -gt 0 ]]; then
+      local _state_file="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/state-${_LOOP_PROJ_SLUG:-$(basename "$PWD")}.yaml"
+      local _heal_key="heal_count_head_${commit:0:8}"
+      local _count=0
+      [[ -f "$_state_file" ]] && _count=$(grep "^${_heal_key}:" "$_state_file" 2>/dev/null | awk '{print $2}' || echo 0)
+      _count=$(( ${_count:-0} + 0 ))  # coerce to int
+      if [[ "$_count" -lt "$_heal_max" ]]; then
+        # Increment counter and signal hot-fix path to the agent
+        _count=$(( _count + 1 ))
+        mkdir -p "$(dirname "$_state_file")" 2>/dev/null || true
+        if [[ -f "$_state_file" ]]; then
+          # Update existing key or append
+          if grep -q "^${_heal_key}:" "$_state_file" 2>/dev/null; then
+            local _tmp; _tmp=$(mktemp)
+            grep -v "^${_heal_key}:" "$_state_file" > "$_tmp" 2>/dev/null || true
+            printf '%s: %d\n' "$_heal_key" "$_count" >> "$_tmp"
+            mv "$_tmp" "$_state_file"
+          else
+            printf '%s: %d\n' "$_heal_key" "$_count" >> "$_state_file"
+          fi
+        else
+          printf '%s: %d\n' "$_heal_key" "$_count" > "$_state_file"
+        fi
+        # Exit 2 signals the agent: CI is red, hot-fix path is available
+        return 2
+      fi
+    fi
+
     err "$(msg loop.pre_run_ci_check_head_ci ${short})"
     mkdir -p "$(dirname "$_LOOP_ALERT")"
     cat > "$_LOOP_ALERT" << EOF
@@ -7352,6 +7930,62 @@ EOF
   return 0
 }
 
+# US-LOOP-047: hot-fix context factory for HEAD CI failures.
+# Captures failing run logs + recent commit diff, writes to /tmp/roll-heal-head-<sha>.log
+# Returns 0 and prints the log path on success; 1 if context could not be gathered.
+_loop_hotfix_head_context() {
+  local commit="${1:-$(git rev-parse HEAD 2>/dev/null)}"
+  [[ -z "$commit" ]] && return 1
+  local short="${commit:0:8}"
+  local outfile="/tmp/roll-heal-head-${short}.log"
+  local slug; _gh_resolve slug || slug="unknown"
+
+  {
+    printf '=== CI Hot-fix Context: HEAD %s ===\n\n' "$short"
+    printf '--- Recent commits ---\n'
+    git log --oneline -5 2>/dev/null || true
+    printf '\n--- Diff of last commit ---\n'
+    git show --stat HEAD 2>/dev/null | head -40 || true
+    printf '\n--- CI failure logs (head 200 lines) ---\n'
+    local run_id
+    run_id=$(gh -R "$slug" run list --commit "$commit" \
+      --json databaseId,conclusion -L 5 2>/dev/null \
+      | jq -r '.[] | select(.conclusion=="failure") | .databaseId' 2>/dev/null | head -1)
+    if [[ -n "$run_id" ]]; then
+      gh -R "$slug" run view --log-failed "$run_id" 2>/dev/null | head -200 || true
+    else
+      printf '(no failed run found for commit %s)\n' "$short"
+    fi
+  } > "$outfile" 2>/dev/null
+  printf '%s\n' "$outfile"
+  return 0
+}
+
+# US-LOOP-050: PR hot-fix entry point.
+# Checks out the PR branch, captures CI failure logs, and prepares context
+# for a roll-fix invocation on the PR branch.
+# Usage: _loop_hot_fix_pr <pr_number>
+_loop_hot_fix_pr() {
+  local pr_num="$1"
+  [[ -z "$pr_num" ]] && return 1
+  local slug; _gh_resolve slug || return 1
+  local outfile="/tmp/roll-heal-pr-${pr_num}.log"
+  local run_id
+  run_id=$(gh -R "$slug" run list --json databaseId,conclusion,headBranch -L 20 2>/dev/null \
+    | jq -r --argjson pr "\"$pr_num\"" \
+      '.[] | select(.conclusion=="failure") | .databaseId' 2>/dev/null | head -1)
+  {
+    printf '=== PR #%s CI Hot-fix Context ===\n\n' "$pr_num"
+    if [[ -n "$run_id" ]]; then
+      gh -R "$slug" run view --log-failed "$run_id" 2>/dev/null | head -200 || true
+    else
+      printf '(no failed run found for PR #%s)\n' "$pr_num"
+    fi
+  } > "$outfile" 2>/dev/null
+  printf '%s\n' "$outfile"
+  return 0
+}
+
 # _loop_diagnose_open_prs <slug>
 #   Appended to ALERT when CI is red on HEAD.
 #   For each open PR targeting main: lists CI failing tests + changed files,
@@ -7586,7 +8220,14 @@ _loop_pr_classify() {
   local mergeable="${4:-}"
 
   case "$head_ref" in
-    loop/*) echo "loop_self"; return 0 ;;
+    loop/*)
+      # US-LOOP-049: loop/* PRs with CI failure get their own classification
+      # so _loop_pr_inbox can route them to the PR hot-fix path.
+      if [[ "$ci_state" == "failure" ]]; then
+        echo "loop_self_ci_red"; return 0
+      fi
+      echo "loop_self"; return 0
+      ;;
   esac
 
   case "$human_review" in
@@ -9854,6 +10495,7 @@ main() {
     doctor)        cmd_doctor "$@" ;;
     review-pr)     cmd_review_pr "$@" ;;
     slides)        cmd_slides "$@" ;;
+    test)          cmd_test "$@" ;;
     prices)        cmd_prices "$@" ;;
     changelog)     cmd_changelog "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.527.1",
+  "version": "2026.528.2",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-design/SKILL.md

@@ -121,7 +121,7 @@ Document structure (two-layer separation):
 3. **FIX / IDEA detail files use ID-prefixed filenames**: `.roll/features/<epic>/FIX-097.md`, not `.roll/features/<epic>/some-descriptive-slug.md`. Reason: a single FIX is one card, not a long-lived feature; the ID is the most stable handle, descriptive slugs date quickly and break links. US can keep feature-slug naming (US lives inside a multi-Story feature file). Quick lookup: `ls .roll/features/<epic>/FIX-*.md` finds all bugs in that area without grepping content.
 4. .roll/backlog.md only contains index rows (one row per US), **do not write** AC / Files / Notes
 5. Domain model files go in `.roll/domain/` — create on first greenfield design, update incrementally
-6. **Do not** write to `~/.kimi/` or any global config directory
+6. **Do not** write to `~/.kimi/`, `~/.kimi-code/`, or any global config directory
 
 **File path resolution order:**
 1. Determine Feature ownership (based on the requirement domain: compiler / ingest / qa / ...)

package/skills/roll-loop/SKILL.md

@@ -125,16 +125,26 @@ readers. The rule mirrors the gate in Step 2.
 ### Step 1.5 — Pre-run CI Health Check
 
 Call `roll loop precheck-ci` before scanning BACKLOG. This is a **defensive gate**
-against building on a broken base — if the most recent commit on the branch
-has red CI, the loop must not stack new commits on top (which would create the
-exact stuck-red state FIX-026 traces to).
-
-- HEAD CI green / pending / no-run-yet → proceed to Step 2.
-- HEAD CI red → write ALERT, **do not pick up any stories this cycle**,
-  exit cleanly. The next cycle will retry; the human must fix CI manually
-  (typically by reverting or pushing a green commit) before the loop resumes.
-- `gh` missing or repo unparseable → graceful skip (`roll loop precheck-ci`
-  returns 0); the post-build `_loop_enforce_ci` remains the strict gate.
+against building on a broken base. Check the **exit code** and route accordingly:
+
+| Exit code | Meaning | Action |
+|-----------|---------|--------|
+| `0` | CI green / pending / unknown | Proceed to Step 1.6 (PR Inbox) and Step 2 (BACKLOG scan) |
+| `1` | CI red AND heal exhausted or `ROLL_LOOP_NO_HEAL=1` | ALERT already written; exit cleanly this cycle |
+| `2` | CI red AND heal attempt allowed (US-LOOP-046) | **Hot-fix path** — skip BACKLOG, fix CI instead (see below) |
+
+`gh` missing or repo unparseable → `precheck-ci` returns `0`; graceful skip.
+
+**Hot-fix path (exit code 2) — US-LOOP-046:**
+
+Do NOT pick any BACKLOG stories this cycle. Instead:
+
+1. Capture context: `roll loop hotfix-head-context` → prints path to context log
+2. Invoke `Skill("roll-fix")` with brief:
+   `"CI red on HEAD. Failing run logs at <context-log-path>. Diagnose root cause, fix via TCR, commit, push. Do NOT change BACKLOG status."`
+3. After `roll-fix` completes, re-run `roll ci --wait` to verify the fix
+4. If CI is still red: run `roll loop precheck-ci` again; if it returns `1` (heal exhausted),
+   exit cleanly — ALERT was already written by the precheck
 
 ### Step 1.6 — PR Inbox (US-AUTO-034)