@seanyao/roll 2026.529.2 → 2026.529.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v2026.529.4
+
+### Fixed
+
+- 非 Claude agent 跑 loop 不再黑屏 `[loop]`
+
+### Added
+
+- `roll-doc` 现在追踪数据流和调用链 `[loop]`
+
+## v2026.529.3
+
+### Fixed
+
+- loop 用 kimi 跑不再必崩 `[loop]`
+- 切 agent 后 loop 不再用旧的 `[loop]`
+- loop 不再因提交卡住整轮白做 `[loop]`
+
 ## v2026.529.2
 
 ### Added

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.529.2"
+VERSION="2026.529.4"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -3389,7 +3389,7 @@ _agent_argv() {
       fi
       case "$mode" in
         interactive) _AGENT_ARGV=("$_kimi_bin" "$prompt") ;;
-        *)           _AGENT_ARGV=("$_kimi_bin" --quiet -p "$prompt") ;;
+        *)           _AGENT_ARGV=("$_kimi_bin" -p "$prompt") ;;  # FIX-133: kimi-code 无 --quiet,-p 自带 auto 审批
       esac ;;
     deepseek)
       # deepseek has the same argv shape in both modes (positional prompt).
@@ -5954,6 +5954,10 @@ _write_runner_script() {
 _write_loop_runner_script() {
   local script_path="$1" project_path="$2" cmd="$3" log_path="$4"
   local active_start="${5:-10}" active_end="${6:-18}"
+  # FIX-134: skill md path. When set, the inner script rebuilds the agent
+  # command at runtime from the routed cycle agent; when empty it falls back to
+  # the baked command (backwards compatible with callers that omit it).
+  local skill_path="${7:-}"
   # FIX-054: terminal preference detection removed. Popup is hard-coded to
   # macOS Terminal.app; the 7th positional arg, if any, is ignored for
   # backwards compatibility with existing callers.
@@ -5985,6 +5989,15 @@ _write_loop_runner_script() {
     agent_cmd="${agent_cmd/--output-format stream-json/--output-format stream-json --add-dir \"\$WT\"}"
   fi
   local slug; slug=$(_project_slug "$project_path")
+  # FIX-134: emit a runtime command-builder line when skill_path is known, so
+  # the cycle agent is resolved live (routing-aware). Otherwise leave _CYCLE_CMD
+  # empty and the inner script uses the baked fallback command below.
+  local cycle_cmd_line
+  if [[ -n "$skill_path" ]]; then
+    cycle_cmd_line="_CYCLE_CMD=\$(_loop_cycle_agent_cmd \"${skill_path}\" \"\$CYCLE_AGENT\" \"\$WT\" 2>/dev/null || true)"
+  else
+    cycle_cmd_line="_CYCLE_CMD="
+  fi
   cat > "$inner_path" << INNER
 #!/bin/bash -l
 set -o pipefail
@@ -6018,6 +6031,10 @@ printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
 # readers see "still alive in <phase>" during long-running silences (e.g.
 # agent_invoke 5-45 min). CURRENT_PHASE is maintained by _phase_begin/_phase_end.
 HEARTBEAT_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.heartbeat-${slug}"
+# FIX-136: file-based phase tracking so forked heartbeat child can see phase changes.
+# CURRENT_PHASE is inherited at fork time — changes after fork are invisible to child.
+# Writing phase state to a file decouples the heartbeat from fork-time snapshot.
+HEARTBEAT_PHASE_FILE="\${_SHARED_ROOT:-\${HOME}/.shared/roll}/loop/.phase-${slug}"
 CURRENT_PHASE=""
 # bash 3.2 (macOS /bin/bash) lacks associative arrays — use namespaced
 # variables via 'printf -v' + indirect '\${!VAR}' expansion instead.
@@ -6029,6 +6046,8 @@ _phase_begin() {
   local _name="\$1"
   printf -v "_PHASE_START_\${_name}" '%s' "\$(date +%s)"
   CURRENT_PHASE="\$_name"
+  # FIX-136: write phase+start_ts to file so forked heartbeat child can read it
+  printf '%s %s' "\$_name" "\$(date +%s)" > "\$HEARTBEAT_PHASE_FILE"
   _loop_event phase_start "\$_name" "" "" || true
 }
 _phase_end() {
@@ -6040,17 +6059,21 @@ _phase_end() {
   printf -v "_PHASE_DUR_\${_name}" '%s' "\$_dur"
   case " \$_PHASE_NAMES_DONE " in *" \$_name "*) ;; *) _PHASE_NAMES_DONE="\${_PHASE_NAMES_DONE} \$_name" ;; esac
   CURRENT_PHASE=""
+  # FIX-136: clear phase file so heartbeat knows no active phase
+  echo -n > "\$HEARTBEAT_PHASE_FILE" 2>/dev/null || true
   _loop_event phase_end "\$_name" "\${_dur}s" "\$_outcome" || true
 }
 _heartbeat_writer() {
   while true; do
     echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"
-    if [ -n "\$CURRENT_PHASE" ]; then
-      local _start_var="_PHASE_START_\${CURRENT_PHASE}"
-      local _phase_start="\${!_start_var:-}"
-      if [ -n "\$_phase_start" ]; then
-        local _el=\$(( \$(date +%s) - _phase_start ))
-        _loop_event phase_tick "\$CURRENT_PHASE" "\${_el}s elapsed" "" 2>/dev/null || true
+    # FIX-136: read phase from file — CURRENT_PHASE is inherited at fork and
+    # never updated. The parent writes phase+start_ts on _phase_begin, clears
+    # on _phase_end. No phase file = no active phase = skip tick.
+    if [ -f "\$HEARTBEAT_PHASE_FILE" ]; then
+      read -r _hb_phase _hb_start_ts < "\$HEARTBEAT_PHASE_FILE" 2>/dev/null || true
+      if [ -n "\$_hb_phase" ] && [ -n "\$_hb_start_ts" ]; then
+        local _el=\$(( \$(date +%s) - _hb_start_ts ))
+        _loop_event phase_tick "\$_hb_phase" "\${_el}s elapsed" "" 2>/dev/null || true
       fi
     fi
     sleep 60
@@ -6291,7 +6314,7 @@ _runs_append "failed" 0 "[]" "\$_phases_t" 2>/dev/null || true
     _keep="\${ROLL_CYCLE_LOG_KEEP:-50}"
     ( cd "\$_log_dir" && ls -t *.log 2>/dev/null | tail -n +\$((_keep + 1)) | xargs -r rm -f ) 2>/dev/null || true
   fi
-  rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"
+  rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE" "\$HEARTBEAT_PHASE_FILE"
   exit "\$_rc"
 }
 trap '_inner_cleanup' EXIT
@@ -6455,6 +6478,11 @@ export LOOP_SHARED_ROOT="\${_SHARED_ROOT:-\$HOME/.shared/roll}"
 export ROLL_LOOP_AGENT="\${CYCLE_AGENT:-\$(_project_agent)}"
 export ROLL_LOOP_ROUTED_STORY ROLL_LOOP_ROUTED_AGENT ROLL_LOOP_ROUTED_RULE
 _phase_begin agent_invoke
+# FIX-136: non-claude agents (pi/deepseek/kimi) buffer stdout when piped.
+# Force a pseudo-TTY via script(1) so loop-fmt.py's passthrough receives
+# output in real time — without this, tmux is black for the entire phase.
+_AGENT_PTY_PREFIX=""
+[ "\$ROLL_LOOP_AGENT" != "claude" ] && _AGENT_PTY_PREFIX="script -q /dev/null"
 for _attempt in 1 2 3; do
   # FIX-068: defensive reset before each attempt — _CYCLE_TIMED_OUT carries
   # the SIGTERM result of the previous attempt and would otherwise force an
@@ -6476,10 +6504,15 @@ for _attempt in 1 2 3; do
       pkill -KILL -f "\$WT" 2>/dev/null
     } ) &
   _WATCHDOG_PID=\$!
+  ${cycle_cmd_line}
+  # FIX-134: prefer the runtime-rebuilt command (routing-aware); fall back to
+  # the baked command (project agent at \`roll loop on\` time) when empty.
   if [ -f "\$FMT" ]; then
-    ( cd "\$WT" && ${agent_cmd} ) | python3 "\$FMT"
+    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval \$_AGENT_PTY_PREFIX "\$_CYCLE_CMD" ) | python3 "\$FMT"
+    else ( cd "\$WT" && \$_AGENT_PTY_PREFIX ${agent_cmd} ) | python3 "\$FMT"; fi
   else
-    ( cd "\$WT" && ${agent_cmd} )
+    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval \$_AGENT_PTY_PREFIX "\$_CYCLE_CMD" )
+    else ( cd "\$WT" && \$_AGENT_PTY_PREFIX ${agent_cmd} ); fi
   fi
   _exit=\$?
   kill "\$_WATCHDOG_PID" 2>/dev/null
@@ -6939,7 +6972,7 @@ _install_launchd_plists() {
     local cmd; cmd=$(_agent_skill_cmd "${sd}/${skill}/SKILL.md" 2>/dev/null || echo "roll loop now")
 
     if [[ "$svc" == "loop" ]]; then
-      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end"
+      _write_loop_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log" "$active_start" "$active_end" "${sd}/${skill}/SKILL.md"
     else
       _write_runner_script "$runner" "$project_path" "cd \"${project_path}\" && ${cmd}" "$log"
     fi
@@ -6984,7 +7017,9 @@ _install_launchd_plists() {
 
 _agent_skill_cmd() {
   local skill_path="$1"
-  local agent; agent=$(_project_agent)
+  # FIX-134: accept an explicit agent (loop routing passes the resolved cycle
+  # agent); default to the project agent for non-routed callers.
+  local agent="${2:-$(_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|openai|codex|opencode|qwen|gemini>"
@@ -7005,6 +7040,23 @@ _agent_skill_cmd() {
   echo "${out} \"\$(${strip})\""
 }
 
+# FIX-134: build the full per-cycle agent command at RUNTIME, routing-aware.
+# The loop inner script calls this with the resolved cycle agent (CYCLE_AGENT =
+# ROLL_LOOP_ROUTED_AGENT or project agent) so routing actually switches the
+# executed binary — instead of running a constant baked at `roll loop on` time.
+# Reproduces the claude-only verbose / stream-json / add-dir enhancements that
+# _write_loop_runner_script previously baked into the runner.
+_loop_cycle_agent_cmd() {
+  local skill_path="$1" agent="${2:-$(_project_agent)}" wt="${3:-$WT}"
+  [ -n "$skill_path" ] || return 1
+  local cmd; cmd=$(_agent_skill_cmd "$skill_path" "$agent") || return 1
+  cmd="${cmd/claude -p/claude -p --verbose --dangerously-skip-permissions --output-format stream-json}"
+  if [[ "$cmd" == *"--output-format stream-json"* ]]; then
+    cmd="${cmd/--output-format stream-json/--output-format stream-json --add-dir \"$wt\"}"
+  fi
+  printf '%s' "$cmd"
+}
+
 cmd_loop() {
   local subcmd="${1:-status}"; shift || true
   case "$subcmd" in

package/package.json

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

package/skills/roll-doc/SKILL.md

@@ -7,7 +7,7 @@ description: "Legacy project documentation automation. Scans all docs, builds/up
 
 # roll-doc
 
-Four-phase legacy documentation automation: scan → index → gap analysis → fill.
+Four-phase legacy documentation automation (plus deep-read Phase 3b): scan → index → gap analysis → fill (directory-level) → deep read (cross-directory topics).
 
 Works on any project root. No manual mode switching — reads the project state and decides what to do.
 
@@ -162,6 +162,125 @@ Only include lines for directories that already exist in the project.
 
 Do not fabricate details — infer only from source files actually read.
 
+## Phase 3b — Deep Read
+
+Deep-read phase that builds a full project symbol table (without truncation) and auto-detects
+cross-directory topics that directory-level Phase 3 alone cannot discover.
+
+**Trigger conditions** — Phase 3b runs when either is true:
+- Phase 2 found any gap (module or special gap)
+- The project exhibits code characteristics that Phase 3a cannot capture:
+  cross-directory import chains spanning ≥ 3 directories, state enums referenced by
+  multiple files, external URL/endpoint calls, or CI pipeline configuration files
+
+Pure documentation-only projects (no source code gaps, no code characteristics) skip Phase 3b.
+
+### Step 1 — Build Symbol Table
+
+Read every source file **in full** (no truncation). The existing Phase 3 "up to 20 source files"
+limit does not apply — Phase 3b builds a complete project symbol table for downstream topic
+detection to reason across files without missing logic.
+
+**Exclusion directories** (same as Phase 1):
+
+```
+node_modules/   .git/   dist/   build/   .shared/   .roll/dream/   .roll/briefs/
+```
+
+**Symbol table fields:**
+
+| Field | Content |
+|-------|---------|
+| `exports` | class / interface / type / function / const declarations, per file |
+| `imports` | source file → target file mapping (dependency graph edges) |
+| `enums` | enum declarations with enumerated values, per file |
+| `external_urls` | `fetch(...)` / `axios` / `http.*` calls, `API_ENDPOINT` / `*_URL` / `*_HOST` constants, hardcoded `https?://` strings (exclude comments and test fixtures) |
+| `configs` | CI workflow YAML files, build config paths, test framework config file paths |
+
+**`--dry-run` behavior:** print symbol table summary counts per category (e.g. "exports: 42, imports: 156, enums: 7, external_urls: 4, configs: 3") plus top-N examples per category. Write nothing to disk.
+
+**`--force` behavior:** unchanged — `--force` only affects draft generation (Phase 3/3b output files).
+The symbol table itself is rebuilt from scratch on every run regardless of flags.
+
+### Step 2 — Topic Detection
+
+Using the symbol table from Step 1, detect cross-directory topics. Each topic type has a
+detection rule and a target output file. Skip any topic whose target file already exists
+(unless `--force`). Skip any topic whose detection rule finds no matches.
+
+| Topic | Detection Rule | Output |
+|-------|---------------|--------|
+| 数据流 / 调用链 | Entry files (`bin/`, `cmd/`, `main.*`, `index.*`) → trace import chain to leaf nodes; require ≥ 1 chain spanning ≥ 3 directories | `docs/data-flows.md` |
+| 状态机 | Enums matching `*State` / `*Status` referenced by ≥ 2 source files | `docs/state-machines.md` |
+| 外部集成 | `external_urls` entries from symbol table (exclude comment/test-fixture matches) | `docs/integrations.md` |
+| 部署管线 | `.github/workflows/*.yml` / `.gitlab-ci.yml` / `circle.yml` / `Jenkinsfile` present, with deploy URL patterns detected | `docs/deployment.md` |
+| Agent 入口 (AGENTS.md) | Project root has no `AGENTS.md` AND `src/` (or equivalent source root) has ≥ 3 subdirectories | `AGENTS.md` |
+| 高引用目录 | Directory imported by ≥ 5 other source files, even if directory itself has < 3 source files | `<dir>/README.md` |
+
+#### Data Flow / Import Chain Tracing
+
+**Entry point selection:** start from entry files — any file matching patterns:
+`bin/*`, `cmd/**/*`, `main.*` (e.g. `main.ts`, `main.py`), `index.*` (e.g. `index.ts`, `index.jsx`),
+`App.*`, `server.*`. Exclude `node_modules/`, `dist/`, `build/`, test files (`*.test.*`, `*.spec.*`, `tests/`).
+
+**Chain construction:**
+1. For each entry file, read its imports from the symbol table's `imports` field.
+2. Recursively follow each imported file to its own imports, building a directed call graph.
+3. Stop at leaf nodes — files that import nothing or whose imports all point to:
+   - External packages (node_modules / stdlib / third-party)
+   - Already-visited nodes (cycle termination)
+4. Each distinct path from an entry file to a leaf is one call chain.
+
+**Threshold (cross-directory filter):**
+A call chain is valid for inclusion only if it spans **≥ 3 distinct source directories**.
+Count based on the unique parent directories of files in the chain:
+  `src/cli/main.ts → src/commands/build.ts → lib/utils/fs.ts` = 3 directories ✅
+  `src/cli/main.ts → src/cli/config.ts → lib/utils/fs.ts` = 2 directories ❌
+If no chain meets the ≥ 3 directory threshold, skip generation entirely (no empty `docs/data-flows.md`).
+
+**Output document structure** (`docs/data-flows.md`):
+
+```markdown
+> **Draft** — auto-generated by roll-doc on YYYY-MM-DD. Review before treating as authoritative.
+
+# Data Flows
+
+## Flow: {short descriptive name from entry file purpose}
+
+**Entry point:** `{entry_file}:{line}`
+**Directories spanned:** N ({comma-separated list})
+
+### Complete Call Chain
+
+{entry_file}
+  → import {symbol} from "{file}" ({line})
+    → import {symbol} from "{file}" ({line})
+      → ... (leaf node)
+
+### Files Involved
+
+| Step | File:Line | Function / Method |
+|------|-----------|-------------------|
+| 1 | `path/to/file:12` | `functionName` |
+| 2 | `path/to/file:34` | `otherFunction` |
+| ... | ... | ... |
+```
+
+- Sort flows by number of directories spanned, descending (widest cross-cutting flow first).
+- If an entry file produces multiple distinct call chains, list each one as a separate flow entry.
+- `file:line` annotations must come from actual symbol table records — do not fabricate.
+
+**Idempotency:** skip (do not overwrite) if `docs/data-flows.md` already exists, unless `--force`.
+
+### Step 3 — Source Annotations
+
+Every topic document generated in Step 2 must cite `file:line` for each claim (function call,
+endpoint URL, state transition, CI job, import path). Annotations must come from actual
+symbol table records — do not fabricate line numbers. Follows the same "Do not fabricate"
+rule as Phase 3.
+
+---
+
 ## Phase 4 — Report
 
 After all phases complete, output a summary:
@@ -181,6 +300,12 @@ Phase 3 — Fill
   N drafts generated: [list of paths]
   N skipped (already exist; use --force to regenerate)
 
+Phase 3b — Deep Read
+  Symbol table: exports(N) imports(N) enums(N) external_urls(N) configs(N)
+  N topic documents generated: [list of paths and types]
+  N topics skipped (no matches or already exist; use --force to regenerate)
+  (if no topics generated: "no subject-level drafts generated")
+
 📋 Review priority (largest / most active modules first):
   1. src/commands/README.md — 8 source files
   2. docs/CONVENTIONS.md — 6 patterns detected