@seanyao/roll 2026.526.1 → 2026.528.1

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.526.1"
+VERSION="2026.528.1"
 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"
@@ -273,6 +279,7 @@ _ensure_config_entries() {
     "ai_openclaw:~/.openclaw/workspace|AGENTS.md|AGENTS.md"
     "ai_pi:~/.pi/agent|AGENTS.md|AGENTS.md"
     "ai_deepseek:~/.deepseek|AGENTS.md|AGENTS.md"
+    "ai_qwen:~/.qwen|AGENTS.md|AGENTS.md"
   )
 
   local added=0
@@ -489,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
@@ -781,7 +789,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"
+  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"
@@ -1927,6 +1935,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)"
@@ -3132,9 +3152,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).
@@ -3144,7 +3175,7 @@ _agent_argv() {
         interactive) _AGENT_ARGV=(pi "$prompt") ;;
         *)           _AGENT_ARGV=(pi -p "$prompt") ;;
       esac ;;
-    codex)
+    codex|openai)
       case "$mode" in
         interactive) _AGENT_ARGV=(codex "$prompt") ;;
         peer)        _AGENT_ARGV=(codex exec --json --output-last-message "$prompt") ;;
@@ -3155,15 +3186,19 @@ _agent_argv() {
         interactive) _AGENT_ARGV=(opencode "$prompt") ;;
         *)           _AGENT_ARGV=(opencode run "$prompt") ;;
       esac ;;
-    agy)
+    gemini|agy)
       # Antigravity (agy) replaces the deprecated Google Gemini CLI as of
       # late 2025. agy reuses ~/.gemini/ for config and reads GEMINI.md
       # natively, so the convention sync target is unchanged — only the
-      # invoked binary changes. Interactive-only (used by onboard flow).
+      # invoked binary changes.
       case "$mode" in
         interactive) _AGENT_ARGV=(agy -i "$prompt") ;;
-        *) return 1 ;;
+        text|peer)   _AGENT_ARGV=(agy "$prompt") ;;
+        *)           _AGENT_ARGV=(agy "$prompt") ;;
       esac ;;
+    qwen)
+      # qwen has the same argv shape in both modes (positional prompt).
+      _AGENT_ARGV=(qwen "$prompt") ;;
     *) return 1 ;;
   esac
 }
@@ -3201,7 +3236,7 @@ _agent_run_skill() {
   [[ -f "$skill_file" ]] || { err "Skill not found: ${skill}"; return 1; }
   local content; content=$(_skill_content "$skill_file")
   _agent_argv "$agent" text "$content" || {
-    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"
+    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|openai|codex|opencode|qwen|gemini>"
     return 1
   }
   "${_AGENT_ARGV[@]}"
@@ -3960,7 +3995,7 @@ EOF
 )"
 
   _agent_argv "$agent" text "$prompt" || {
-    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"
+    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|openai|codex|opencode|qwen|gemini>"
     trap - INT TERM
     return 1
   }
@@ -4346,8 +4381,14 @@ cmd_agent() {
   case "$subcmd" in
     use)
       local name="${1:-}"
-      [[ -z "$name" ]] && { err "Usage: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"; exit 1; }
-      command -v "$name" &>/dev/null || warn "$(msg agent.not_found_in_path_setting_anyway "$name")"
+      [[ -z "$name" ]] && { err "Usage: roll agent use <claude|kimi|deepseek|pi|openai|codex|opencode|qwen|gemini>"; exit 1; }
+      if [[ "$name" == openai ]]; then
+        command -v codex &>/dev/null || warn "openai agent requires the Codex CLI. Install: npm install -g @openai/codex"
+      elif [[ "$name" == gemini ]]; then
+        command -v agy &>/dev/null || command -v gemini &>/dev/null || warn "gemini agent requires the Google Gemini CLI. Install: npm install -g @antigravity/agy"
+      else
+        command -v "$name" &>/dev/null || warn "$(msg agent.not_found_in_path_setting_anyway "$name")"
+      fi
       # REFACTOR-040: write to .roll/local.yaml (per-machine state). Migrate
       # from legacy .roll.yaml in the project root on the spot — copy the
       # value over once, then delete the old file so the root stays clean.
@@ -4380,7 +4421,7 @@ cmd_agent() {
     list)
       echo ""; echo "  $(msg agent.available_agents)"; echo ""
       local current; current=$(_project_agent)
-      for a in claude kimi deepseek opencode codex pi; do
+      for a in claude kimi deepseek opencode codex openai pi qwen gemini; do
         if command -v "$a" &>/dev/null; then
           [[ "$a" == "$current" ]] && echo -e "    ${GREEN}✓ ${a}${NC}  (current)" \
                                    || echo -e "    ${GREEN}✓ ${a}${NC}"
@@ -4406,6 +4447,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
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -4756,6 +5188,90 @@ fi
 # _SHARED_ROOT overrides and silently leaked test runs.jsonl writes into prod.
 _LOOP_RUNS="${_SHARED_ROOT}/loop/runs.jsonl"
 : "${_LOOP_MUTE_FILE:=${_SHARED_ROOT}/loop/mute-${_LOOP_PROJ_SLUG}}"
+
+# ──────────────────────────────────────────────────────────────
+# US-LOOP-018: _loop_resolve_project_path + _loop_runtime_dir
+#
+# Two helpers that form the single source-of-truth for resolving
+# "where does this project's loop runtime data live?". All callers
+# (inner/outer runner templates, dashboard, GC, pause/resume, etc.)
+# must go through _loop_runtime_dir — never inline paths.
+#
+# Resolution order for _loop_resolve_project_path:
+#   1. macOS: launchd plist WorkingDirectory key (already used by
+#      _status_loop_overview — implicit registry, no new state file)
+#   2. Linux: crontab entry (grep for "cd \"<path>\"")  — best-effort
+#   3. Universal fallback: inner runner script grep for
+#      export ROLL_MAIN_PROJECT="..."  (inner scripts carry this;
+#      outer runner scripts do not — pi peer review correction)
+# ──────────────────────────────────────────────────────────────
+
+# _loop_resolve_project_path <slug>
+# Resolve a slug to its project directory path.
+# Returns 0 and prints path on success; returns 1 on failure.
+_loop_resolve_project_path() {
+  local slug="$1"
+
+  # 1. macOS: launchd plist WorkingDirectory (primary source)
+  if [[ "$(uname)" = "Darwin" ]]; then
+    local plist_dir="${HOME}/Library/LaunchAgents"
+    local plist="${plist_dir}/com.roll.loop.${slug}.plist"
+    if [[ -f "$plist" ]]; then
+      local proj; proj=$(awk '/<key>WorkingDirectory<\/key>/{f=1;next} f{gsub(/^[[:space:]]*<string>|<\/string>[[:space:]]*$/,"");print;exit}' "$plist" 2>/dev/null)
+      if [[ -n "$proj" ]]; then
+        echo "$proj"
+        return 0
+      fi
+    fi
+  fi
+
+  # 2. Linux: crontab entry (best-effort)
+  if command -v crontab >/dev/null 2>&1; then
+    local cron_line; cron_line=$(crontab -l 2>/dev/null | grep "run-${slug}.sh" | head -1)
+    if [[ -n "$cron_line" ]]; then
+      # Extract cd path: "cd \"<path>\" && ..."
+      local proj; proj=$(echo "$cron_line" | sed -n 's/.*cd[[:space:]]*"\([^"]*\)".*/\1/p')
+      if [[ -n "$proj" && -d "$proj" ]]; then
+        echo "$proj"
+        return 0
+      fi
+    fi
+  fi
+
+  # 3. Universal fallback: inner runner script ROLL_MAIN_PROJECT export
+  local inner_script="${_SHARED_ROOT:-${HOME}/.shared/roll}/loop/run-${slug}-inner.sh"
+  if [[ -f "$inner_script" ]]; then
+    local proj; proj=$(grep '^export ROLL_MAIN_PROJECT=' "$inner_script" 2>/dev/null | head -1 | sed 's/.*="\(.*\)"/\1/')
+    if [[ -n "$proj" ]]; then
+      echo "$proj"
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+# _loop_runtime_dir <slug>
+# Return the project's .roll/loop/ directory path.
+# Priority: ROLL_PROJECT_RUNTIME_DIR env → resolved project + .roll/loop
+# Returns 0 and prints path on success; returns 1 on failure.
+_loop_runtime_dir() {
+  local slug="$1"
+
+  # 1. Environment override (test sandbox)
+  if [[ -n "${ROLL_PROJECT_RUNTIME_DIR:-}" ]]; then
+    echo "${ROLL_PROJECT_RUNTIME_DIR}"
+    return 0
+  fi
+
+  # 2. Resolve project path and append .roll/loop
+  local proj; proj=$(_loop_resolve_project_path "$slug")
+  if [[ -z "$proj" ]]; then
+    return 1
+  fi
+  echo "${proj}/.roll/loop"
+}
+
 # FIX-087: parallel to FIX-065's _SHARED_ROOT auto-sandbox above. Without this,
 # tests that source bin/roll (directly via BATS or indirectly via a runner-inner
 # fork under /tmp / /var/folders/) wrote plists into the developer's real
@@ -4827,17 +5343,15 @@ _loop_derive_minute() {
   echo $(( (hash_dec + offset) % 55 + 1 ))
 }
 
-# US-LOOP-011: validate a (period, offset) pair against the allowed schedule spec.
-# Allowed periods are the divisors of 60: 60/30/20/15/12/10/6/5.
-# Offset must be within [0, period).
+# US-LOOP-032: validate a (period, offset) pair.  Period 1–1440.
+# offset_minute is deprecated (US-LOOP-032); still accepted for backward
+# compat but plist generation ignores it (uses StartInterval = period*60).
 _loop_schedule_valid() {
   local period="$1" offset="$2"
-  case "$period" in
-    60|30|20|15|12|10|6|5) ;;
-    *) return 1 ;;
-  esac
+  [[ "$period" =~ ^[0-9]+$ ]] || return 1
+  if (( period < 1 || period > 1440 )); then return 1; fi
   [[ "$offset" =~ ^[0-9]+$ ]] || return 1
-  if (( offset >= period )); then return 1; fi
+  if (( offset >= 60 )); then return 1; fi
   return 0
 }
 
@@ -4860,6 +5374,11 @@ _loop_schedule_spec() {
     local_offset=$(awk '/^loop_schedule:/{found=1;next} found && /^[[:space:]]+offset_minute:/{print $2; exit}' "$local_file")
     if [[ -n "$local_period" && -n "$local_offset" ]]; then
       if _loop_schedule_valid "$local_period" "$local_offset"; then
+        # US-LOOP-032: offset_minute is deprecated when period doesn't divide 60.
+        # Warn but don't fail.
+        if (( 60 % local_period != 0 )) && [[ "$local_offset" != "0" ]]; then
+          echo "roll: warning: offset_minute is deprecated (period=${local_period}, offset=${local_offset}). Use period_minutes only." >&2
+        fi
         echo "$local_period $local_offset"
         return 0
       fi
@@ -4868,11 +5387,11 @@ _loop_schedule_spec() {
       local alert_file="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/ALERT-${slug}.md"
       mkdir -p "$(dirname "$alert_file")" 2>/dev/null || true
       {
-        printf '## ⚠️ US-LOOP-011: Invalid loop_schedule\n\n'
+        printf '## ⚠️ US-LOOP-032: Invalid loop_schedule\n\n'
         printf '**Time**: %s\n' "$(date '+%Y-%m-%d %H:%M:%S')"
         printf '**Source**: %s\n\n' "${project_path}/.roll/local.yaml"
         printf '**Values**: period_minutes=%s, offset_minute=%s\n\n' "$local_period" "$local_offset"
-        printf '**Action**: period must be one of 60/30/20/15/12/10/6/5; offset must be 0–(period-1). Falling back to default (period=60).\n\n'
+        printf '**Action**: period must be 1–1440; offset must be 0–59. Falling back to default (period=60).\n\n'
         printf '%s\n' '---'
       } >> "$alert_file"
     fi
@@ -4892,30 +5411,39 @@ _loop_schedule_spec() {
   echo "60 $offset"
 }
 
-# US-LOOP-013: human-readable schedule description for display.
+# US-LOOP-032: human-readable schedule description.
 # Args: period offset [lang]
 #   lang: en (default) or zh
+# For periods that divide 60, shows clock-aligned slots (e.g. "every 30min (:00 :30)").
+# For non-divisor periods (US-LOOP-032), shows just the interval (e.g. "every 45min").
 _loop_schedule_desc() {
   local period="$1" offset="$2" lang="${3:-en}"
   if [[ "$period" -eq 60 ]]; then
     if [[ "$lang" == "zh" ]]; then
-      # msg_lang uses the explicit lang param, not ROLL_LANG env; strips trailing
-      # newline via command substitution so callers get a clean string.
       printf '%s' "$(msg_lang "$lang" agent.hourly_at_02d "$offset")"
     else
       printf "every hour :%02d" "$offset"
     fi
     return 0
   fi
-  local times="" slots=$((60 / period)) i m
-  for i in $(seq 0 $((slots - 1))); do
-    m=$((offset + i * period))
-    times="${times} :$(printf '%02d' "$m")"
-  done
-  if [[ "$lang" == "zh" ]]; then
-    printf '%s' "$(msg_lang "$lang" agent.every_d_min_s "$period" "${times# }")"
+  # US-LOOP-032: only show clock-aligned slots when period divides 60
+  if (( 60 % period == 0 )); then
+    local times="" slots=$((60 / period)) i m
+    for i in $(seq 0 $((slots - 1))); do
+      m=$((offset + i * period))
+      times="${times} :$(printf '%02d' "$m")"
+    done
+    if [[ "$lang" == "zh" ]]; then
+      printf '%s' "$(msg_lang "$lang" agent.every_d_min_s "$period" "${times# }")"
+    else
+      printf "every %dmin (%s)" "$period" "${times# }"
+    fi
   else
-    printf "every %dmin (%s)" "$period" "${times# }"
+    if [[ "$lang" == "zh" ]]; then
+      printf '每%d分鐘' "$period"
+    else
+      printf "every %dmin" "$period"
+    fi
   fi
 }
 
@@ -4928,7 +5456,16 @@ _loop_event() {
   local ts slug evfile json
   ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
   slug=$(_project_slug 2>/dev/null || basename "$PWD")
-  evfile="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/events-${slug}.ndjson"
+  # US-LOOP-020: prefer project-local .roll/loop/; fallback to shared root
+  # for transient slugs (worktree cleanup, orphan recovery) where
+  # _loop_runtime_dir cannot resolve a project path.
+  local _rt_dir
+  _rt_dir=$(_loop_runtime_dir "$slug" 2>/dev/null || echo "")
+  if [ -n "$_rt_dir" ]; then
+    evfile="${_rt_dir}/events.ndjson"
+  else
+    evfile="${_SHARED_ROOT:-$HOME/.shared/roll}/loop/events-${slug}.ndjson"
+  fi
   # FIX-065 tripwire: in a test context (BATS or temp cwd), refuse to write
   # into production ~/.shared/roll/. Catching this in code is the last line
   # of defense if some unusual path bypassed the auto-sandbox at source-time.
@@ -5095,35 +5632,18 @@ _write_launchd_plist() {
   # FIX-105: macOS 26.4 launchd silently refuses to fire StartCalendarInterval
   # entries that contain BOTH Hour and Minute keys. Daily services use
   # StartInterval=86400 instead.
-  # US-LOOP-012: when period < 60 and no hour, generate StartCalendarInterval
-  # <array> with one <dict> per trigger minute.
+  # US-LOOP-032: all loop services use StartInterval = period * 60 (was
+  # StartCalendarInterval with slot enumeration). Non-divisor periods are now
+  # supported.
   local schedule_xml
   if [[ -n "$hour" ]]; then
     schedule_xml="  <key>StartInterval</key>
   <integer>86400</integer>"
-  elif [[ "$period" == "60" ]]; then
-    schedule_xml="  <key>StartCalendarInterval</key>
-  <dict>
-    <key>Minute</key>
-    <integer>${offset}</integer>
-  </dict>"
   else
-    # US-LOOP-012: period < 60 → generate array of dicts
-    local entries=$(( 60 / period ))
-    local xml_lines="  <key>StartCalendarInterval</key>
-  <array>"
-    local i m
-    for ((i = 0; i < entries; i++)); do
-      m=$(( offset + i * period ))
-      xml_lines+="
-    <dict>
-      <key>Minute</key>
-      <integer>${m}</integer>
-    </dict>"
-    done
-    xml_lines+="
-  </array>"
-    schedule_xml="$xml_lines"
+    # US-LOOP-032: StartInterval in seconds = period_minutes * 60
+    local interval=$(( period * 60 ))
+    schedule_xml="  <key>StartInterval</key>
+  <integer>${interval}</integer>"
   fi
 
   local content
@@ -5180,6 +5700,10 @@ _write_loop_runner_script() {
   # Use stream-json + formatter: --verbose alone does nothing in -p mode;
   # stream-json enables realtime streaming; loop-fmt.py humanizes the events.
   local fmt_script="${ROLL_PKG_DIR}/lib/loop-fmt.py"
+  # US-LOOP-026: post-cycle single-shot usage writer for non-claude agents.
+  # pi -p text mode prints no usage, so we recover it from pi's session jsonl
+  # exactly once per cycle (loop-fmt passthrough is display-only).
+  local pi_emit_script="${ROLL_PKG_DIR}/lib/agent_usage/pi_emit.py"
   local roll_bin="${ROLL_PKG_DIR}/bin/roll"
   # FIX-041: loop cycle is autonomous — permission prompts and sandbox path
   # restrictions only cause the cycle to burn turns asking for approvals
@@ -5352,10 +5876,22 @@ _runs_append() {
   local _rid="loop-\${_cid%-*}"
   grep -qF "\"run_id\":\"\$_rid\"" "\$_runs_dst" 2>/dev/null && return 0
   mkdir -p "\$(dirname "\$_runs_dst")"
+  # FIX-123: clean stale .tmp files from dead PIDs on entry.
+  # A .tmp residue means a previous atomic write was interrupted.
+  # Only clean files whose PID (extracted from suffix) is dead.
+  local _tmp_dir; _tmp_dir="\$(dirname "\$_runs_dst")"
+  for _stale in "\$_tmp_dir"/runs.jsonl.tmp.*; do
+    [ -f "\$_stale" ] || continue
+    local _stale_pid="\${_stale##*.tmp.}"
+    kill -0 "\$_stale_pid" 2>/dev/null || rm -f "\$_stale"
+  done
   local _ts_now; _ts_now=\$(date -u +%Y-%m-%dT%H:%M:%SZ)
   local _start="\${CYCLE_START:-\$(date -u +%s)}"
   local _dur=\$(( \$(date -u +%s) - _start ))
   [ "\$_dur" -lt 0 ] && _dur=0
+  # FIX-123: atomic write — write to .tmp.$$ first, then cat >> to append,
+  # then remove. If interrupted between jq and rm, the next call cleans it.
+  local _tmp="\$_runs_dst.tmp.\$\$"
   jq -nc \\
     --arg ts "\$_ts_now" \\
     --arg project "${slug}" \\
@@ -5372,7 +5908,9 @@ _runs_append() {
       cycle_id:\$cycle_id,
       built:\$built, skipped:\$skipped, alerts:\$alerts,
       tcr_count:\$tcr_count, duration_sec:\$duration_sec, phases:\$phases}' \\
-    >> "\$_runs_dst" 2>/dev/null || true
+    > "\$_tmp" 2>/dev/null || { rm -f "\$_tmp"; return 0; }
+  cat "\$_tmp" >> "\$_runs_dst" 2>/dev/null || true
+  rm -f "\$_tmp"
 }
 _inner_cleanup() {
   local _rc=\$?
@@ -5661,6 +6199,25 @@ else
   _phase_end agent_invoke ok
 fi
 
+# US-LOOP-026: non-claude agents (pi/deepseek/kimi) print no usage in -p text
+# mode. Recover token+cost once per cycle from the agent's session jsonl and
+# append a single authoritative usage event. Done here (not in loop-fmt's
+# per-attempt passthrough) so retries can't write N duplicate events that the
+# dashboard's same-label SUM would inflate. Runs before the timeout-abort exit
+# so partial cycles still get whatever usage the session recorded. The events
+# path is resolved exactly like _loop_event (rt_dir first, shared fallback) so
+# pi_emit appends to the same file the reader consumes.
+if [ "\$(_project_agent)" != "claude" ] && [ -f "${pi_emit_script}" ]; then
+  _pi_rt=\$(_loop_runtime_dir "${slug}" 2>/dev/null || echo "")
+  if [ -n "\$_pi_rt" ]; then
+    _pi_evfile="\${_pi_rt}/events.ndjson"
+  else
+    _pi_evfile="\${_SHARED_ROOT:-\$HOME/.shared/roll}/loop/events-${slug}.ndjson"
+  fi
+  python3 "${pi_emit_script}" --cwd "\$WT" --cycle "\${CYCLE_ID}" \\
+    --slug "${slug}" --events "\$_pi_evfile" 2>/dev/null || true
+fi
+
 # FIX-057: timed out — skip publish; EXIT trap writes cycle_end blocked + ALERT.
 if [ "\$_CYCLE_TIMED_OUT" -eq 1 ]; then
   echo "[loop] cycle \${CYCLE_ID}: \${LOOP_CYCLE_TIMEOUT_SEC}s timeout — aborting cycle (worktree preserved at \$WT)"
@@ -5827,7 +6384,7 @@ if [ -z "\$ROLL_LOOP_FORCE" ]; then
   if [ "\$h" -lt ${active_start} ] || [ "\$h" -ge ${active_end} ]; then exit 0; fi
 fi
 # Pause check — 'roll loop pause' creates this marker to suspend scheduling
-PAUSE="\$HOME/.shared/roll/loop/PAUSE-${slug}"
+PAUSE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/PAUSE-${slug}"
 if [ -z "\$ROLL_LOOP_FORCE" ] && [ -f "\$PAUSE" ]; then exit 0; fi
 # FIX-037: orphan state detection & self-heal — if state.yaml says running
 # but no LOCK process or tmux session exists, the previous cycle was killed
@@ -5916,8 +6473,8 @@ if command -v tmux >/dev/null 2>&1; then
   # that triggered LaunchServices "where is <app>" prompts when the active
   # process name differed from its .app bundle name (e.g. MSTeams vs
   # Microsoft Teams.app).
-  if [ -z "\${ROLL_LOOP_NO_POPUP:-}" ] && [ -z "\${BATS_TEST_NUMBER:-}" ] && [ ! -f "\$HOME/.shared/roll/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ]; then
-    _attach_cmd="\$HOME/.shared/roll/loop/attach-\$SESSION.command"
+  if [ -z "\${ROLL_LOOP_NO_POPUP:-}" ] && [ -z "\${BATS_TEST_NUMBER:-}" ] && [ ! -f "\${_SHARED_ROOT:-\$HOME/.shared/roll}/loop/mute-${slug}" ] && [ "\$(uname)" = "Darwin" ]; then
+    _attach_cmd="\${_SHARED_ROOT:-\$HOME/.shared/roll}/loop/attach-\$SESSION.command"
     # Drop \`exec\` so the wrapping shell survives \`tmux attach\` exiting,
     # then \`read\` to hold the Terminal open until the user has had a
     # chance to scroll back through the cycle's output. Without this the
@@ -6115,7 +6672,7 @@ _agent_skill_cmd() {
   local agent; agent=$(_project_agent)
   local strip="awk 'NR==1 && /^---$/{skip=1;next} skip && /^---$/{skip=0;next} !skip{print}' '${skill_path}'"
   _agent_argv "$agent" plain "__PROMPT__" || {
-    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|codex|opencode>"
+    err "Unknown agent '${agent}'. Run: roll agent use <claude|kimi|deepseek|pi|openai|codex|opencode|qwen|gemini>"
     return 1
   }
   # Cron-installed skills (dream / brief / loop) run autonomously and need to
@@ -6152,12 +6709,13 @@ cmd_loop() {
     pause)   _loop_pause ;;
     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)" ;;
     *)  cat <<'HELP'
-Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mute|unmute|pause|resume|reset|notify|enforce-tcr|precheck-ci|branches>
+Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mute|unmute|pause|resume|reset|gc|branches>
 
   on            Install launchd scheduler (loop + dream + brief)
   off           Remove launchd scheduler
@@ -6175,15 +6733,19 @@ Usage: roll loop <on|off|now|test|status|monitor|runs|log|story|events|attach|mu
   pause         Pause scheduling (keep plist, skip execution)
   resume        Resume scheduling after pause
   reset         Clear loop state (start fresh on next fire)
+  gc [--dry-run] [--keep-days N]
+                Garbage-collect orphan slugs, tmp debris, expired backups
+  branches      List loop-related branches
+
+Internal (called by roll-loop SKILL):
   notify        Send macOS notification
   enforce-tcr   Verify TCR commit count for a completed story
   precheck-ci   Check HEAD CI status before scanning BACKLOG
-  branches      List loop-related branches
 
 Schedule is configured per-project in .roll/local.yaml:
 
   loop_schedule:
-    period_minutes: 30   # 60, 30, 20, 15, 12, 10, 6, or 5
+    period_minutes: 30   # 1-1440 (any minute interval)
     offset_minute: 7     # 0 – (period_minutes - 1)
 
 See guide/en/loop.md for full documentation.
@@ -6627,6 +7189,152 @@ _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
+
+  # Parse arguments
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --dry-run) dry_run=true; shift ;;
+      --keep-days) keep_days="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+
+  # Retention config: env > local.yaml > default
+  if [[ -n "${ROLL_LOOP_GC_RETENTION_DAYS:-}" ]]; then
+    keep_days="$ROLL_LOOP_GC_RETENTION_DAYS"
+  elif [[ -f .roll/local.yaml ]]; then
+    local yaml_val; yaml_val=$(_config_read_int "loop_gc.retention_days" "" 2>/dev/null || true)
+    [[ -n "$yaml_val" ]] && keep_days="$yaml_val"
+  fi
+
+  local loop_dir="${_SHARED_ROOT:-${HOME}/.shared/roll}/loop"
+  # Always use canonical LaunchAgents — auto-sandbox only redirects writes.
+  local plist_dir="${HOME}/Library/LaunchAgents"
+  local now_epoch; now_epoch=$(date +%s)
+  local gc_count=0
+
+  # ── Phase 1: orphan slug detection ──
+  local slug plist proj
+  for plist in "$plist_dir"/com.roll.loop.*.plist; do
+    [[ -f "$plist" ]] || continue
+    local fname; fname=$(basename "$plist" .plist)
+    # Extract slug: com.roll.loop.<slug> → <slug>
+    slug="${fname#com.roll.loop.}"
+    [[ -z "$slug" ]] && continue
+
+    # Resolve project path from plist WorkingDirectory key
+    # (inlined from _loop_resolve_project_path — US-LOOP-018)
+    proj=$(awk '/<key>WorkingDirectory<\/key>/{f=1;next} f{gsub(/^[[:space:]]*<string>|<\/string>[[:space:]]*$/,"");print;exit}' "$plist" 2>/dev/null)
+
+    if [[ -z "$proj" || ! -d "$proj" ]]; then
+      # Expired slug — project directory doesn't exist
+      local ts; ts=$(date +%Y%m%dT%H%M%S)
+      local archive_dir="${loop_dir}/archived/${slug}-${ts}"
+
+      if $dry_run; then
+        echo "[DRY-RUN] orphan slug: $slug (project not found)"
+        gc_count=$((gc_count + 1))
+        continue
+      fi
+
+      echo "gc: archiving orphan slug $slug"
+      mkdir -p "$archive_dir"
+
+      # Move runner scripts
+      for f in "${loop_dir}/run-${slug}.sh" \
+               "${loop_dir}/run-${slug}-inner.sh" \
+               "${loop_dir}/attach-roll-loop-${slug}.command"; do
+        [[ -f "$f" ]] && mv "$f" "$archive_dir/"
+      done
+
+      # Move plist (it's already unloaded since project dir is gone)
+      [[ -f "$plist" ]] && mv "$plist" "$archive_dir/"
+
+      gc_count=$((gc_count + 1))
+    fi
+  done
+
+  # ── Phase 2: tmp debris cleanup ──
+
+  # runs.jsonl.tmp.* — always safe to remove (FIX-123 cleans stale on entry,
+  # but files from cycles that hard-crashed without the FIX-123 trap may remain)
+  local f
+  for f in "$loop_dir"/runs.jsonl.tmp.*; do
+    [[ -f "$f" ]] || continue
+    if $dry_run; then
+      echo "[DRY-RUN] tmp debris: $(basename "$f")"
+    else
+      rm -f "$f"
+    fi
+    gc_count=$((gc_count + 1))
+  done
+
+  # backup-before-merge-*.tgz older than 5 days
+  local cutoff_5d; cutoff_5d=$((now_epoch - 5 * 86400))
+  for f in "$loop_dir"/backup-before-merge-*.tgz; do
+    [[ -f "$f" ]] || continue
+    local mtime; mtime=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
+    if [[ "$mtime" -lt "$cutoff_5d" ]]; then
+      if $dry_run; then
+        echo "[DRY-RUN] old backup: $(basename "$f")"
+      else
+        rm -f "$f"
+      fi
+      gc_count=$((gc_count + 1))
+    fi
+  done
+
+  # *.migrated-* older than 7 days
+  local cutoff_7d; cutoff_7d=$((now_epoch - 7 * 86400))
+  for f in "$loop_dir"/*.migrated-*; do
+    [[ -f "$f" ]] || continue
+    local mtime; mtime=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
+    if [[ "$mtime" -lt "$cutoff_7d" ]]; then
+      if $dry_run; then
+        echo "[DRY-RUN] old migrated: $(basename "$f")"
+      else
+        rm -f "$f"
+      fi
+      gc_count=$((gc_count + 1))
+    fi
+  done
+
+  if $dry_run; then
+    echo "gc: dry-run complete ($gc_count items would be cleaned)"
+  else
+    echo "gc: $gc_count items cleaned, keep-days=$keep_days"
+  fi
+}
+
 # Pretty-print a duration in seconds as "Xs" / "Ym" / "Yh Zm".
 # US-VIEW-019: compute slowest phase + % from a JSON line's phases object.
 # Returns "<abbr> <pct>%" (e.g. "claude 97%") or empty when no phases data.
@@ -7487,6 +8195,18 @@ _loop_pr_rebase_stale() {
   return 0
 }
 
+# _loop_pr_merge_self <num> <ci_state> <mergeable> <slug>
+#   Merge a loop_self PR directly when CI is green and PR is conflict-free.
+#   Does not rely on repo-level auto-merge (unreliable if not configured).
+#   Same pattern as the bot_review=APPROVED gate.
+_loop_pr_merge_self() {
+  local num="$1" ci_state="$2" mergeable="$3" slug="$4"
+  [ "$ci_state" = "success" ] && [ "$mergeable" = "MERGEABLE" ] || return 0
+  gh -R "$slug" pr merge "$num" --squash --delete-branch >/dev/null 2>&1 \
+    && info "PR #${num}: loop_self CI green — merged" \
+    || warn "PR #${num}: loop_self merge failed — left open"
+}
+
 # _loop_pr_inbox
 #   Walks open PRs and routes each by classification.
 #   Lenient on gh unavailability — returns 0 so the loop continues to BACKLOG.
@@ -7551,7 +8271,10 @@ _loop_pr_inbox() {
     verdict=$(_loop_pr_classify "$head_ref" "$human_review" "$ci_state" "$mergeable")
 
     case "$verdict" in
-      loop_self|blocked_human_request_changes|blocked_human_approved)
+      loop_self)
+        _loop_pr_merge_self "$num" "$ci_state" "$mergeable" "$slug"
+        ;;
+      blocked_human_request_changes|blocked_human_approved)
         : # skip — explained by verdict; nothing to do this cycle
         ;;
       stale)
@@ -8304,6 +9027,24 @@ _loop_publish_doc_pr() {
 #
 #   Lenient: returns 0 when gh is missing, slug is unresolvable, jq is
 #   missing, or runs.jsonl does not exist. Atomic rewrite via temp file.
+
+# FIX-123: clean stale runs.jsonl .tmp orphan files from dead pids.
+# Called at every runs.jsonl write entry point so orphans never accumulate.
+# Optional $1: directory to scan. Defaults to dirname of $_LOOP_RUNS.
+_loop_cleanup_stale_runs_tmp() {
+  local _dir="${1:-$(dirname "${_LOOP_RUNS:-${HOME}/.shared/roll/loop/runs.jsonl}")}"
+  [ -d "$_dir" ] || return 0
+  local _f _pid
+  for _f in "$_dir"/runs.jsonl.tmp.*; do
+    [ -f "$_f" ] || continue
+    _pid="${_f##*.tmp.}"
+    [ -z "$_pid" ] && continue
+    # shellcheck disable=SC2009
+    kill -0 "$_pid" 2>/dev/null && continue
+    rm -f "$_f"
+  done
+}
+
 _loop_backfill_merged() {
   local runs_path="${1:-${HOME}/.shared/roll/loop/runs.jsonl}"
   [ -f "$runs_path" ] || return 0
@@ -8311,7 +9052,9 @@ _loop_backfill_merged() {
   command -v jq >/dev/null 2>&1 || return 0
   local slug; _gh_resolve slug || return 0
 
+  _loop_cleanup_stale_runs_tmp "$(dirname "$runs_path")"
   local tmp="${runs_path}.tmp.$$"
+  trap "rm -f '$tmp'" EXIT
   : > "$tmp"
   local line status cycle_id branch view_json state merged_at merge_commit
   while IFS= read -r line; do
@@ -8342,6 +9085,7 @@ _loop_backfill_merged() {
       >> "$tmp" 2>/dev/null || printf '%s\n' "$line" >> "$tmp"
   done < "$runs_path"
   mv "$tmp" "$runs_path" 2>/dev/null || rm -f "$tmp"
+  trap - EXIT
   return 0
 }
 
@@ -9553,6 +10297,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}" ;;