@seanyao/roll 2026.517.2 → 2026.517.4

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.517.2"
+VERSION="2026.517.4"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -872,167 +872,6 @@ cmd_init() {
   fi
 }
 
-
-# ─── Helper: merge global preamble + template into output ────────────────────
-merge_convention() {
-  local filename="$1"
-  local tpl_dir="$2"
-  local out_dir="$3"
-  local display="${4:-$filename}"
-  local global_file="$ROLL_GLOBAL/$filename"
-  local tpl_file="$tpl_dir/$filename"
-  local out_file="$out_dir/$filename"
-
-  if [[ ! -f "$tpl_file" ]]; then
-    return
-  fi
-
-  local merged
-  merged="$(cat "$global_file" 2>/dev/null || true)"
-  merged+=$'\n\n'
-  merged+="---"
-  merged+=$'\n\n'
-  merged+="$(cat "$tpl_file")"
-
-  if [[ -f "$out_file" ]]; then
-    if diff -q <(echo "$merged") "$out_file" &>/dev/null; then
-      _ROLL_MERGE_SUMMARY+=("unchanged|$display")
-      return  # identical, nothing to do
-    fi
-    warn "File exists: $display  文件已存在: $display"
-    echo -n "  [o] Overwrite  [k] Keep  [M] Merge (default): "
-    read -r answer
-    answer="${answer:-M}"
-    case "$answer" in
-      o|O)
-        echo "$merged" > "$out_file"
-        ok "Overwritten: $display  已覆盖: $display"
-        _ROLL_MERGE_SUMMARY+=("overwritten|$display")
-        return
-        ;;
-      k|K)
-        info "Kept: $display  已保留: $display"
-        _ROLL_MERGE_SUMMARY+=("kept|$display")
-        return
-        ;;
-      m|M|"")
-        # Merge: for each ## section in template:
-        #   - if missing in output → append
-        #   - if present but content differs → show diff, prompt [u/k]
-        #   - if present and identical → skip
-
-        # Helper: extract a section's body (lines after heading until next ## or EOF)
-        # Usage: _extract_section "$file" "$heading"
-        _extract_section() {
-          local file="$1"
-          local heading="$2"
-          local in_section=false
-          local body=""
-          while IFS= read -r ln; do
-            if [[ "$ln" == "$heading" ]]; then
-              in_section=true
-              continue
-            fi
-            if [[ "$in_section" == "true" ]]; then
-              if [[ "$ln" =~ ^##\  ]]; then
-                break
-              fi
-              body+="$ln"$'\n'
-            fi
-          done < "$file"
-          printf '%s' "$body"
-        }
-
-        local current_heading=""
-        local current_body=""
-
-        # _process_section: check/append/update a completed section
-        _process_section() {
-          local heading="$1"
-          local body="$2"
-          local out="$3"
-          if ! grep -qF "$heading" "$out" 2>/dev/null; then
-            # Section missing → append
-            printf '\n%s\n%s' "$heading" "$body" >> "$out"
-          else
-            # Section exists → compare content
-            local existing
-            existing="$(_extract_section "$out" "$heading")"
-            if [[ "$body" != "$existing" ]]; then
-              echo ""
-              warn "Section \"$heading\" exists but content differs:"
-              diff <(printf '%s' "$existing") <(printf '%s' "$body") || true
-              echo -n "  [u] update with template  [k] keep mine (default): "
-              local sec_ans
-              read -r sec_ans
-              sec_ans="${sec_ans:-k}"
-              if [[ "$sec_ans" == "u" || "$sec_ans" == "U" ]]; then
-                # Replace existing section with template section
-                local tmp_out
-                tmp_out="$(mktemp)"
-                local skip=false
-                while IFS= read -r fline; do
-                  if [[ "$fline" == "$heading" ]]; then
-                    skip=true
-                    printf '%s\n%s' "$heading" "$body" >> "$tmp_out"
-                    continue
-                  fi
-                  if [[ "$skip" == "true" ]]; then
-                    if [[ "$fline" =~ ^##\  ]]; then
-                      skip=false
-                      printf '%s\n' "$fline" >> "$tmp_out"
-                    fi
-                    continue
-                  fi
-                  printf '%s\n' "$fline" >> "$tmp_out"
-                done < "$out"
-                mv "$tmp_out" "$out"
-              fi
-            fi
-          fi
-        }
-
-        # Parse template sections, reading from file (not herestring) to keep stdin free
-        # for interactive user prompts inside _process_section
-        local tpl_sections=()
-        local tpl_bodies=()
-        local cur_h="" cur_b=""
-        while IFS= read -r line; do
-          if [[ "$line" =~ ^##\  ]]; then
-            if [[ -n "$cur_h" ]]; then
-              tpl_sections+=("$cur_h")
-              tpl_bodies+=("$cur_b")
-            fi
-            cur_h="$line"
-            cur_b=""
-          elif [[ -n "$cur_h" ]]; then
-            cur_b+="$line"$'\n'
-          fi
-        done < "$tpl_file"
-        # Capture last section
-        if [[ -n "$cur_h" ]]; then
-          tpl_sections+=("$cur_h")
-          tpl_bodies+=("$cur_b")
-        fi
-
-        # Now process sections (stdin is free for user input)
-        local i
-        for (( i=0; i<${#tpl_sections[@]}; i++ )); do
-          _process_section "${tpl_sections[$i]}" "${tpl_bodies[$i]}" "$out_file"
-        done
-
-        ok "Merged: $display  已合并: $display"
-        _ROLL_MERGE_SUMMARY+=("merged|$display")
-        return
-        ;;
-    esac
-  fi
-
-  echo "$merged" > "$out_file"
-  ok "Created: $display  已创建: $display"
-  _ROLL_MERGE_SUMMARY+=("created|$display")
-}
-
 # ─── Helper: print a tidy summary of merge actions ───────────────────────────
 print_merge_summary() {
   if [[ ${#_ROLL_MERGE_SUMMARY[@]} -eq 0 ]]; then
@@ -2073,7 +1912,7 @@ _LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
 # Returns a filesystem-safe slug combining the project basename and a 6-char
 # hash of the full path, ensuring uniqueness across sibling dirs with same name.
 _project_slug() {
-  local path="$1"
+  local path="${1:-$(pwd -P 2>/dev/null || pwd)}"
   # FIX-034: when inside a git worktree, git-common-dir returns the main tree's
   # absolute .git path; resolve to the main tree so worktree and main-tree runs
   # produce the same slug.
@@ -2115,6 +1954,55 @@ _loop_derive_minute() {
   echo $(( (hash_dec + offset) % 55 + 1 ))
 }
 
+# US-LOOP-001: structured event emission for cycle observability.
+# Writes a tab-separated line to stdout (for tmux/attach display) and appends
+# a JSON line to the per-project NDJSON event file under _SHARED_ROOT/loop/.
+# Args: <stage> <label> <detail> <outcome>
+_loop_event() {
+  local stage="$1" label="$2" detail="$3" outcome="$4"
+  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"
+  mkdir -p "$(dirname "$evfile")"
+
+  # stdout: tab-separated for tmux display
+  printf '%s\t%s\t%s\t%s\t%s\n' "$ts" "$stage" "$label" "$detail" "$outcome"
+
+  # JSON line appended to NDJSON file; serialized with flock (Linux) or
+  # lockf (macOS/BSD) — fall back to unguarded append when neither is available.
+  json=$(printf '{"ts":"%s","stage":"%s","label":"%s","detail":"%s","outcome":"%s"}\n' \
+    "$ts" "$stage" "$label" "$detail" "$outcome")
+  if command -v flock >/dev/null 2>&1; then
+    (
+      flock -x 9
+      printf '%s\n' "$json" >> "$evfile"
+    ) 9>>"${evfile}.lock"
+  elif command -v lockf >/dev/null 2>&1; then
+    lockf -s "${evfile}.lock" sh -c "printf '%s\n' $(printf '%q' "$json") >> $(printf '%q' "$evfile")"
+  else
+    printf '%s\n' "$json" >> "$evfile"
+  fi
+
+  # File rotation: if >10MB, rotate keeping last 5
+  _loop_event_rotate "$evfile"
+}
+
+_loop_event_rotate() {
+  local f="$1"
+  local size
+  size=$(stat -f%z "$f" 2>/dev/null || stat -c%s "$f" 2>/dev/null || echo 0)
+  if [ "$size" -gt 10485760 ]; then
+    # rotate: .4→remove, .3→.4, .2→.3, .1→.2, current→.1
+    rm -f "${f}.4"
+    for i in 3 2 1; do
+      [ -f "${f}.$i" ] && mv "${f}.$i" "${f}.$((i+1))"
+    done
+    mv "$f" "${f}.1"
+    touch "$f"
+  fi
+}
+
 _launchd_label() {
   local service="$1" project_path="$2"
   printf 'com.roll.%s.%s' "$service" "$(_project_slug "$project_path")"
@@ -2194,6 +2082,13 @@ _write_loop_runner_script() {
   # _install_launchd_plists prepend it). The runner now manages cwd itself
   # — pointing at the worktree when isolation succeeds, project_path otherwise.
   local claude_cmd; claude_cmd="${cmd_verbose#cd \"*\" && }"
+  # FIX-048: Claude Code resolves project root from the worktree's .git file to
+  # the main repo, placing worktree absolute paths outside its sandbox. Inject
+  # --add-dir "$WT" so the worktree directory is explicitly allowed. Only applies
+  # to claude (the --output-format stream-json flag is exclusive to claude runs).
+  if [[ "$claude_cmd" == *"--output-format stream-json"* ]]; then
+    claude_cmd="${claude_cmd/--output-format stream-json/--output-format stream-json --add-dir \"\$WT\"}"
+  fi
   local slug; slug=$(_project_slug "$project_path")
   cat > "$inner_path" << INNER
 #!/bin/bash -l
@@ -2237,6 +2132,7 @@ set +e
 # On any failure (no remote, no main, etc.) fall back to running in the
 # project's main tree (degraded — no isolation, like pre-037 behavior).
 CYCLE_ID="\$(date -u +%Y%m%d-%H%M%S)-\$\$"
+CYCLE_START=\$(date -u +%s)
 WT="\$(_worktree_path "${slug}" "cycle-\${CYCLE_ID}")"
 BRANCH="loop/cycle-\${CYCLE_ID}"
 _USE_WORKTREE=0
@@ -2253,6 +2149,11 @@ for _orphan_wt in "\${_SHARED_ROOT}/worktrees/${slug}-cycle-"*; do
   _orphan_commits=\$(cd "\$_orphan_wt" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
   if [ "\$_orphan_commits" -gt 0 ]; then
     echo "[loop] FIX-040: recovering orphan worktree \$_orphan_wt (branch \$_orphan_branch, \${_orphan_commits} commits)"
+    # FIX-045: rebase onto origin/main before publishing — avoids BEHIND state on GitHub
+    if ! ( cd "\$_orphan_wt" && git fetch origin main 2>/dev/null && git rebase origin/main 2>/dev/null ); then
+      echo "[loop] FIX-045: orphan \$_orphan_branch rebase failed — skipping recovery (conflict or network error)"
+      continue
+    fi
     _orphan_ok=0
     if ( cd "\$_orphan_wt" && _loop_is_doc_only_change ); then
       ( cd "\$_orphan_wt" && _loop_publish_doc_pr "\$_orphan_branch" "doc: recover orphan \${_orphan_branch}" ) && _orphan_ok=1
@@ -2278,6 +2179,7 @@ if _worktree_fetch_origin main \\
   _USE_WORKTREE=1
   _worktree_submodule_init "\$WT" 2>/dev/null || true
   echo "[loop] cycle \${CYCLE_ID}: worktree \$WT on \$BRANCH"
+  _loop_event cycle_start "\${CYCLE_ID}" "" "" || true
 else
   # P3 fix: skip the cycle entirely when worktree isolation fails.
   # --dangerously-skip-permissions is only safe paired with worktree isolation;
@@ -2302,6 +2204,25 @@ for _attempt in 1 2 3; do
   fi
 done
 
+# FIX-044: capture cycle data from worktree before cleanup removes it
+_cycle_tcr=0
+_cycle_status="idle"
+_cycle_built="[]"
+if [ "\$_USE_WORKTREE" = "1" ]; then
+  if [ "\$_exit" -ne 0 ]; then
+    _cycle_status="failed"
+  else
+    _cycle_commits_pre=\$(cd "\$WT" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
+    if [ "\$_cycle_commits_pre" -gt 0 ]; then
+      _cycle_status="built"
+      _cycle_tcr=\$(cd "\$WT" && git log --oneline origin/main..HEAD -- 2>/dev/null | grep -c ' tcr:' || echo 0)
+      if command -v jq >/dev/null 2>&1; then
+        _cycle_built=\$(cd "\$WT" && git diff origin/main -- BACKLOG.md 2>/dev/null | grep '✅ Done' | grep -oE '\[[A-Z]+-[0-9]+\]' | sed 's/^.//;s/.\$//' | jq -R -s 'split("\n") | map(select(length>0))' 2>/dev/null || echo "[]")
+      fi
+    fi
+  fi
+fi
+
 # US-AUTO-038: diff snapshot vs current and delete any claude/* branches this
 # session pushed to origin. Runs regardless of claude's exit code (cleanup is
 # orthogonal to success/failure) and is silent on non-GitHub / unreachable.
@@ -2320,16 +2241,26 @@ if [ "\$_USE_WORKTREE" = "1" ]; then
     _cycle_commits=\$(cd "\$WT" && git rev-list --count origin/main..HEAD 2>/dev/null || echo 0)
     if [ "\$_cycle_commits" -eq 0 ]; then
       _worktree_cleanup "\$WT" "\$BRANCH"
+      _loop_event idle "\${CYCLE_ID}" "" "" || true
       echo "[loop] cycle \${CYCLE_ID}: idle (no new commits); worktree cleaned"
     else
-      if ( cd "\$WT" && _loop_is_doc_only_change ); then
+      _is_doc_only=0
+      ( cd "\$WT" && _loop_is_doc_only_change ) && _is_doc_only=1
+      if [ "\$_is_doc_only" -eq 1 ]; then
         ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
       else
         ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" )
       fi
       _publish_status=\$?
       if [ "\$_publish_status" -eq 0 ]; then
+        # FIX-047: CI green ≠ delivered — wait for actual PR merge before cycle complete
+        if [ "\$_is_doc_only" -eq 0 ]; then
+          if ! ( cd "\$WT" && _loop_wait_pr_merge "\$BRANCH" ); then
+            _worktree_alert "cycle \${CYCLE_ID}: FIX-047: PR not merged within timeout — code may not be in main (BRANCH=\${BRANCH})"
+          fi
+        fi
         _worktree_cleanup "\$WT" "\$BRANCH"
+        _loop_event cycle_end "\${CYCLE_ID}" "" "done" || true
         echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
       elif [ "\$_publish_status" -eq 2 ]; then
         if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
@@ -2374,6 +2305,32 @@ fi
 
 # US-AUTO-040: fallback GC — delete remote loop/cycle-* branches already merged to main.
 _loop_cleanup_stale_cycle_branches "${project_path}" || true
+
+# FIX-044 / Step 5: Write loop cycle run summary to runs.jsonl
+# Deterministic — runs in shell regardless of whether agent executes SKILL.md Step 5.
+# Idempotent: skips if a record for this run_id already exists (agent may also write).
+_runs_dst="${HOME}/.shared/roll/loop/runs.jsonl"
+mkdir -p "\$(dirname "\$_runs_dst")"
+_cycle_end=\$(date -u +%s)
+_cycle_dur=\$(( _cycle_end - CYCLE_START ))
+_ts=\$(date -u +%Y-%m-%dT%H:%M:%SZ)
+_run_id="loop-\${CYCLE_ID%-*}"
+if command -v jq >/dev/null 2>&1 && ! grep -qF "\"run_id\":\"\$_run_id\"" "\$_runs_dst" 2>/dev/null; then
+  jq -nc \\
+    --arg ts "\$_ts" \\
+    --arg project "${slug}" \\
+    --arg run_id "\$_run_id" \\
+    --arg status "\$_cycle_status" \\
+    --argjson built "\$_cycle_built" \\
+    --argjson skipped '[]' \\
+    --argjson alerts '[]' \\
+    --argjson tcr_count "\$_cycle_tcr" \\
+    --argjson duration_sec "\$_cycle_dur" \\
+    '{ts:\$ts, project:\$project, run_id:\$run_id, status:\$status,
+      built:\$built, skipped:\$skipped, alerts:\$alerts,
+      tcr_count:\$tcr_count, duration_sec:\$duration_sec}' \\
+    >> "\$_runs_dst" 2>/dev/null || true
+fi
 INNER
   chmod +x "$inner_path"
 
@@ -2626,14 +2583,17 @@ cmd_loop() {
     status)  _loop_status ;;
     monitor) _loop_monitor "${1:-3}" ;;
     runs)    _loop_runs "$@" ;;
+    events)  _loop_event_log "${1:-20}" ;;
     attach)  _loop_attach ;;
     mute)    _loop_mute ;;
     unmute)  _loop_unmute ;;
     pause)   _loop_pause ;;
     resume)  _loop_resume ;;
     reset)   _loop_reset ;;
-    notify)  _notify "${1:-roll}" "${2:-}" ;;
-    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|attach|mute|unmute|pause|resume|reset|notify>"; exit 1 ;;
+    notify)       _notify "${1:-roll}" "${2:-}" ;;
+    enforce-tcr)  _loop_enforce_tcr "${1:-}" "${2:-}" ;;
+    precheck-ci)  _loop_precheck_ci ;;
+    *) err "Usage: roll loop <on|off|now|test|status|monitor|runs|events|attach|mute|unmute|pause|resume|reset|notify|enforce-tcr|precheck-ci>"; exit 1 ;;
   esac
 }
 
@@ -3152,6 +3112,20 @@ _gh_repo_slug() {
   printf "%s\n" "$url"
 }
 
+# Returns 0 if gh CLI is installed and executable, 1 otherwise.
+_gh_available() { command -v gh >/dev/null 2>&1; }
+
+# Resolve the GitHub owner/repo slug and set <outvar> to it.
+# Returns 0 on success. Returns 1 (no output) if gh is unavailable or the
+# remote is not a GitHub URL — caller decides how to handle failure.
+_gh_resolve() {
+  local _outvar="$1"
+  _gh_available || return 1
+  local _slug
+  _slug=$(_gh_repo_slug 2>/dev/null) || return 1
+  printf -v "$_outvar" '%s' "$_slug"
+}
+
 # Poll gh run list until current commit's CI completes.
 # Returns 0 on success (or when gh binary missing — graceful skip).
 # Returns 1 on CI failure, timeout, or any gh call failure.
@@ -3160,7 +3134,7 @@ _ci_wait() {
   local interval=15
   local elapsed=0
 
-  command -v gh &>/dev/null || { warn "gh not installed — skipping CI gate  gh 未安装，跳过 CI 检查"; return 0; }
+  _gh_available || { warn "gh not installed — skipping CI gate  gh 未安装，跳过 CI 检查"; return 0; }
 
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
   local short; short=$(git rev-parse --short HEAD 2>/dev/null)
@@ -3182,6 +3156,17 @@ _ci_wait() {
     }
 
     if [[ -z "$runs" || "$runs" == "[]" ]]; then
+      # FIX-046: CI only fires on pull_request events — without a PR, runs will never appear.
+      # Check if an open PR exists; if not, skip the gate gracefully.
+      local _branch; _branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+      if [[ -n "$_branch" ]]; then
+        local _pr_json; _pr_json=$(gh -R "$repo_slug" pr list --head "$_branch" --state open --json number 2>/dev/null || echo "1")
+        local _pr_count; _pr_count=$(echo "$_pr_json" | jq 'length' 2>/dev/null || echo "1")
+        if [[ "$_pr_count" == "0" ]]; then
+          warn "No open PR for ${_branch} — CI not triggered; skipping CI gate  当前分支无 PR，CI 未触发，跳过"
+          return 0
+        fi
+      fi
       (( elapsed == 0 )) && echo "  No CI runs found yet, waiting...  尚无 CI 记录，等待触发..."
       sleep "$interval"
       elapsed=$(( elapsed + interval ))
@@ -3221,10 +3206,9 @@ _ci_wait() {
 # Returns 0: ok to proceed (green / pending / unknown / no gh).
 # Returns 1: HEAD CI is definitively red → ALERT written, do not build.
 _loop_precheck_ci() {
-  command -v gh &>/dev/null || return 0
+  local slug; _gh_resolve slug || return 0
 
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || return 0
-  local slug; slug=$(_gh_repo_slug) || return 0
 
   local runs
   runs=$(gh -R "$slug" run list --commit "$commit" --json conclusion 2>/dev/null) || return 0
@@ -3317,8 +3301,12 @@ _loop_diagnose_open_prs() {
 # When gh unavailable: returns 0 (graceful skip).
 _loop_enforce_ci() {
   local story_id="$1"
-
-  _ci_wait 300 && return 0
+  local _ci_result
+  if _ci_wait 300; then
+    _loop_event ci "$story_id" "" "ok" 2>/dev/null || true
+    return 0
+  fi
+  _loop_event ci "$story_id" "" "red" 2>/dev/null || true
 
   mkdir -p "$(dirname "$_LOOP_ALERT")"
   cat > "$_LOOP_ALERT" << EOF
@@ -3355,13 +3343,22 @@ _loop_self_heal_ci() {
   [[ -z "$story_id" ]] && return 1
   [[ "${ROLL_LOOP_NO_HEAL:-0}" == "1" ]] && return 1
   local max="${ROLL_LOOP_HEAL_MAX:-2}"
-  local dir; dir=$(_loop_heal_dir)
-  local counter="${dir}/${story_id}.count"
-  mkdir -p "$dir"
-  local current; current=$(<"$counter") 2>/dev/null || current=0
-  [[ "$current" =~ ^[0-9]+$ ]] || current=0
+  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  local current=0
+  if [[ -f "$state" ]]; then
+    local raw; raw=$(grep '^heal_count:' "$state" 2>/dev/null | awk '{print $2}')
+    [[ "$raw" =~ ^[0-9]+$ ]] && current="$raw"
+  fi
   [[ "$current" -ge "$max" ]] && return 1
-  echo $((current + 1)) > "$counter"
+  local new=$((current + 1))
+  mkdir -p "$(dirname "$state")"
+  if grep -q '^heal_count:' "$state" 2>/dev/null; then
+    local tmp; tmp=$(mktemp)
+    sed "s/^heal_count:.*/heal_count: ${new}/" "$state" > "$tmp"
+    mv "$tmp" "$state"
+  else
+    echo "heal_count: ${new}" >> "$state"
+  fi
   return 0
 }
 
@@ -3370,7 +3367,11 @@ _loop_self_heal_ci() {
 _loop_clear_heal_state() {
   local story_id="$1"
   [[ -z "$story_id" ]] && return 0
-  rm -f "$(_loop_heal_dir)/${story_id}.count" 2>/dev/null
+  local state="${_LOOP_STATE:-${HOME}/.shared/roll/loop/state.yaml}"
+  [[ ! -f "$state" ]] && return 0
+  local tmp; tmp=$(mktemp)
+  grep -v '^heal_count:' "$state" > "$tmp"
+  mv "$tmp" "$state"
   return 0
 }
 
@@ -3643,7 +3644,7 @@ _loop_pr_rebase_stale() {
   local pr="$1" head_ref="$2"
   [ -n "$pr" ] && [ -n "$head_ref" ] || return 0
 
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || return 0
+  local slug; _gh_resolve slug || return 0
 
   local pr_json
   pr_json=$(gh -R "$slug" pr view "$pr" --json headRepository,headRepositoryOwner,isCrossRepository 2>/dev/null) || return 0
@@ -3677,9 +3678,7 @@ _loop_pr_rebase_stale() {
 #   Walks open PRs and routes each by classification.
 #   Lenient on gh unavailability — returns 0 so the loop continues to BACKLOG.
 _loop_pr_inbox() {
-  command -v gh >/dev/null 2>&1 || return 0
-
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || return 0
+  local slug; _gh_resolve slug || return 0
   local prs_json
   prs_json=$(gh -R "$slug" pr list --state open \
     --json number,headRefName,author,title \
@@ -4116,15 +4115,10 @@ _loop_cleanup_stale_cycle_branches() {
 _loop_publish_pr() {
   local branch="$1"
   local title="${2:-loop cycle ${branch#loop/}}"
-  if ! command -v gh >/dev/null 2>&1; then
-    _worktree_alert "_loop_publish_pr: gh not installed; cannot publish PR for ${branch}"
-    return 2
-  fi
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
-  if [ -z "$slug" ]; then
-    _worktree_alert "_loop_publish_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
+  local slug; _gh_resolve slug || {
+    _worktree_alert "_loop_publish_pr: gh not installed or origin is not a github repo; cannot publish PR for ${branch}"
     return 2
-  fi
+  }
   local _push_err
   _push_err=$(git push origin "$branch" 2>&1) || {
     _worktree_alert "_loop_publish_pr: push origin ${branch} failed: ${_push_err}"
@@ -4145,10 +4139,34 @@ _loop_publish_pr() {
   fi
   gh -R "$slug" pr merge "$branch" --auto --squash --delete-branch >/dev/null 2>&1 \
     || _worktree_alert "_loop_publish_pr: gh pr merge --auto failed for ${branch} (PR ${pr_url} left open)"
+  _loop_event pr "$branch" "$pr_url" "ok" 2>/dev/null || true
   echo "$pr_url"
   return 0
 }
 
+# _loop_wait_pr_merge <branch>
+#   FIX-047: poll GitHub until PR for <branch> is merged (confirms delivery).
+#   Returns 0: merged. Returns 1: CLOSED or timeout.
+#   Gracefully skips (returns 0) when gh is unavailable or slug unparseable.
+#   Timeout: ROLL_PR_MERGE_TIMEOUT (default 600s).
+_loop_wait_pr_merge() {
+  local branch="$1"
+  local timeout="${ROLL_PR_MERGE_TIMEOUT:-600}"
+  local interval=30
+  local elapsed=0
+  local slug; _gh_resolve slug || return 0
+  while (( elapsed < timeout )); do
+    local state; state=$(gh -R "$slug" pr view "$branch" --json state -q .state 2>/dev/null || echo "UNKNOWN")
+    case "$state" in
+      MERGED) return 0 ;;
+      CLOSED) return 1 ;;
+    esac
+    sleep "$interval"
+    elapsed=$(( elapsed + interval ))
+  done
+  return 1
+}
+
 # _loop_is_doc_only_change
 #   Returns 0 if every file changed since origin/main is doc-only
 #   (BACKLOG.md, CHANGELOG.md, PROPOSALS.md, docs/, .claude/).
@@ -4167,15 +4185,10 @@ _loop_is_doc_only_change() {
 _loop_publish_doc_pr() {
   local branch="$1"
   local title="${2:-doc update ${branch#loop/}}"
-  if ! command -v gh >/dev/null 2>&1; then
-    _worktree_alert "_loop_publish_doc_pr: gh not installed; cannot publish PR for ${branch}"
+  local slug; _gh_resolve slug || {
+    _worktree_alert "_loop_publish_doc_pr: gh not installed or origin is not a github repo; cannot publish PR for ${branch}"
     return 2
-  fi
-  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
-  if [ -z "$slug" ]; then
-    _worktree_alert "_loop_publish_doc_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
-    return 2
-  fi
+  }
   if ! git push origin "$branch" --quiet 2>/dev/null; then
     _worktree_alert "_loop_publish_doc_pr: push origin ${branch} failed"
     return 1
@@ -4336,11 +4349,57 @@ _loop_monitor() {
       echo -e "    ${YELLOW}(no log yet)${NC}"
     fi
 
+    # Event stream (US-LOOP-001): last 10 events from NDJSON event file
+    local slug; slug=$(_project_slug "$project_path")
+    local evfile="${_SHARED_ROOT}/loop/events-${slug}.ndjson"
+    echo ""
+    echo -e "  ─────────────────────────────────────────────────────"
+    echo -e "  ${BOLD}Cycle Events  事件流${NC}  (last 10)"
+    if [[ -f "$evfile" && -s "$evfile" ]]; then
+      tail -n 10 "$evfile" | python3 -c "
+import sys, json
+for line in sys.stdin:
+    try:
+        e = json.loads(line)
+        stage = e.get('stage','')
+        label = e.get('label','')
+        detail = e.get('detail','')
+        outcome = e.get('outcome','')
+        ts = e.get('ts','')
+        print(f'    {ts}  {stage:<14}  {label:<22}  {detail}  {outcome}')
+    except: pass
+" 2>/dev/null || tail -n 10 "$evfile" | sed 's/^/    /'
+    else
+      echo -e "    ${YELLOW}(no events yet — events are emitted after the first cycle)${NC}"
+    fi
+
     echo ""
     sleep "$interval"
   done
 }
 
+# _loop_event_log: show last N events from the project's NDJSON event file.
+# Used by: roll loop events [N]
+_loop_event_log() {
+  local n="${1:-20}"
+  local project_path; project_path=$(pwd -P)
+  local slug; slug=$(_project_slug "$project_path")
+  local evfile="${_SHARED_ROOT}/loop/events-${slug}.ndjson"
+  if [ ! -f "$evfile" ]; then
+    echo "[monitor] No event log found for project: $slug"
+    return 1
+  fi
+  # Show last N events, formatted
+  tail -n "$n" "$evfile" | python3 -c "
+import sys, json
+for line in sys.stdin:
+    try:
+        e = json.loads(line)
+        print(f\"  {e.get('ts','')}  {e.get('stage',''):12s}  {e.get('label',''):20s}  {e.get('detail','')}  {e.get('outcome','')}\")
+    except: pass
+"
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # BRIEF — owner-facing project digest
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -4507,7 +4566,7 @@ cmd_ci() {
     return
   fi
 
-  command -v gh &>/dev/null || { warn "gh not installed  gh 未安装"; return 0; }
+  _gh_available || { warn "gh not installed  gh 未安装"; return 0; }
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { err "Not a git repo  非 git 仓库"; return 1; }
   local runs
   runs=$(gh run list --commit "$commit" --json status,conclusion,name 2>/dev/null) || { warn "gh run list failed"; return 0; }
@@ -4812,7 +4871,7 @@ _dash_ac_completion() {
 # ④ DoD CI signal — query gh for HEAD's most-recent run conclusion.
 # Returns: success | pending | failure | none
 _dash_ci_status() {
-  command -v gh &>/dev/null || { echo "none"; return; }
+  _gh_available || { echo "none"; return; }
   local commit; commit=$(git rev-parse HEAD 2>/dev/null) || { echo "none"; return; }
   local slug; slug=$(_gh_repo_slug 2>/dev/null) || true
   local out