@seanyao/roll 2026.529.3 → 2026.529.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2026.529.4
+
+### Fixed
+
+- 非 Claude agent 跑 loop 不再黑屏 `[loop]`
+
+### Added
+
+- `roll-doc` 现在追踪数据流和调用链 `[loop]`
+
 ## v2026.529.3
 
 ### Fixed

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.3"
+VERSION="2026.529.4"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -6031,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.
@@ -6042,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() {
@@ -6053,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
@@ -6304,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
@@ -6468,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
@@ -6493,11 +6508,11 @@ for _attempt in 1 2 3; do
   # 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
-    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval "\$_CYCLE_CMD" ) | python3 "\$FMT"
-    else ( cd "\$WT" && ${agent_cmd} ) | python3 "\$FMT"; fi
+    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
-    if [ -n "\$_CYCLE_CMD" ]; then ( cd "\$WT" && eval "\$_CYCLE_CMD" )
-    else ( cd "\$WT" && ${agent_cmd} ); fi
+    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

package/package.json

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

package/skills/roll-doc/SKILL.md

@@ -217,6 +217,61 @@ detection rule and a target output file. Skip any topic whose target file alread
 | 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,