@seanyao/roll 2026.515.1 → 2026.516.1

package/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - **New**: `roll brief` / `roll dream` 生成文档后自动提交推送 — 每次晨报和夜检不再需要手动 commit `[loop]`
 - **New**: 双语 FAQ 指南 — 10 个自治交付常见场景（loop 卡住、PR 冲突、agent 切换、权限问题等），每条含原因和原理，EN + ZH 对照 `[docs]`
+- **Fixed**: loop 孤儿状态自愈 — cycle 启动时检测 state.yaml 残留 running，若无活跃进程则自动重置为 idle，防止 loop 因中断永久卡死 `[loop]`
 - **New**: 可选的事件驱动 PR 评审模板 — `cp templates/workflows/pr-review-event.yml .github/workflows/`，PR 开即触发 AI 评审，不装也行（loop 每轮兜底） `[pr]`
 - **New**: loop PR inbox 从"分类但空转"升级到"分类+执行" — eligible PR 自动调 AI 评审，stale PR 自动 rebase，fork 和冲突写 ALERT；bot 已评审的 PR 自动让步 `[loop]`
 - **New**: `roll review-pr <number>` — agent-agnostic AI 代码评审，任意 agent（Claude/Kimi/DeepSeek 等）均可评审任意 git 平台的 PR；PR body 加 `[skip-ai-review]` 可跳过 `[pr]`

package/README.md

@@ -11,6 +11,7 @@
 
 **[中文版 README](README_CN.md)**
 
+[![Website](https://img.shields.io/badge/Website-seanyao.github.io%2FRoll-blue)](https://seanyao.github.io/Roll/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@seanyao/roll.svg)](https://www.npmjs.com/package/@seanyao/roll)
 [![CI](https://github.com/seanyao/roll/actions/workflows/ci.yml/badge.svg)](https://github.com/seanyao/roll/actions/workflows/ci.yml)

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.515.1"
+VERSION="2026.516.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -1131,60 +1131,6 @@ _ensure_features_dir() {
   _ROLL_MERGE_SUMMARY+=("created|docs/features/")
 }
 
-# ─── Helper: write starter .gitignore (no-op if exists) ──────────────────────
-_write_gitignore() {
-  [[ -f "$1" ]] && return
-  cat > "$1" << 'EOF'
-node_modules/
-dist/
-build/
-.env
-*.local
-.DS_Store
-*.log
-EOF
-}
-
-# ─── Helper: write starter .env.example (no-op if exists) ────────────────────
-_write_env_example() {
-  [[ -f "$1" ]] && return
-  cat > "$1" << 'EOF'
-# Environment Variables — copy to .env and fill in values
-
-# Application
-# NODE_ENV=development
-# PORT=3000
-
-# Database
-# DATABASE_URL=postgresql://user:pass@localhost:5432/db
-
-# Auth
-# JWT_SECRET=your-secret-key
-EOF
-}
-
-# ─── Helper: detect project type from existing AGENTS.md ─────────────────────
-detect_project_type() {
-  local agents_file="$1/AGENTS.md"
-  [[ -f "$agents_file" ]] || { echo "unknown"; return; }
-
-  local content
-  content="$(cat "$agents_file")"
-
-  if echo "$content" | grep -qi "Fullstack Web"; then
-    echo "fullstack"
-  elif echo "$content" | grep -qi "Backend Service"; then
-    echo "backend-service"
-  elif echo "$content" | grep -qi "Frontend Only"; then
-    echo "frontend-only"
-  elif echo "$content" | grep -qi "CLI Tool"; then
-    echo "cli"
-  else
-    # AGENTS.md exists but has no type marker — fall back to file-based scan
-    scan_project_type_from_files "$1"
-  fi
-}
-
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: status
 # Show current state of conventions
@@ -1478,7 +1424,7 @@ _peer_auto_attach() {
   [ "$(uname)" = "Darwin" ] || return 0
   [ -f "$_LOOP_MUTE_FILE" ] && return 0
   local terminal_pref
-  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  terminal_pref=$(config_get "loop_attach_terminal" "")
   if [[ -z "$terminal_pref" ]]; then
     case "${TERM_PROGRAM:-}" in
       ghostty)   terminal_pref="ghostty" ;;
@@ -2111,6 +2057,14 @@ _LAUNCHD_DIR="${HOME}/Library/LaunchAgents"
 # hash of the full path, ensuring uniqueness across sibling dirs with same name.
 _project_slug() {
   local path="$1"
+  # 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.
+  local _common
+  _common=$(git -C "$path" rev-parse --git-common-dir 2>/dev/null)
+  if [[ -n "$_common" && "$_common" == *"/.git" ]]; then
+    path="${_common%/.git}"
+  fi
   local base; base=$(basename "$path")
   local hash
   if command -v md5 &>/dev/null; then
@@ -2125,17 +2079,10 @@ _project_slug() {
 _config_read_int() {
   local key="$1" default="$2"
   local val
-  val=$(grep "^${key}:" "$ROLL_CONFIG" 2>/dev/null | awk '{print $2}' | tr -d '"' | head -1)
+  val=$(config_get "$key" "")
   if [[ "$val" =~ ^[0-9]+$ ]]; then echo "$val"; else echo "$default"; fi
 }
 
-_config_read_string() {
-  local key="$1" default="$2"
-  local val
-  val=$(grep "^${key}:" "$ROLL_CONFIG" 2>/dev/null | awk '{print $2}' | tr -d '"' | head -1)
-  if [[ -n "$val" ]]; then echo "$val"; else echo "$default"; fi
-}
-
 # Derive a minute in [1,55] from project path hash + offset so different projects
 # and different services within a project don't fire at the same time.
 # Offsets used: loop=0, dream=2, brief=4 → always three distinct values (2<55).
@@ -2248,7 +2195,15 @@ if [ -f "\$INNER_LOCK" ]; then
   rm -f "\$INNER_LOCK"
 fi
 printf '%s:%s\n' "\$\$" "\$(date -u +%s)" > "\$INNER_LOCK"
-trap 'rm -f "\$INNER_LOCK"' EXIT
+# FIX-038: background heartbeat writer — outer script uses this as primary liveness signal
+# to detect stale execution without relying on PID reuse heuristics.
+HEARTBEAT_FILE="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+_heartbeat_writer() {
+  while true; do echo "\$(date -u +%s)" > "\$HEARTBEAT_FILE"; sleep 60; done
+}
+_heartbeat_writer &
+_HEARTBEAT_PID=\$!
+trap 'kill "\${_HEARTBEAT_PID}" 2>/dev/null; rm -f "\$INNER_LOCK" "\$HEARTBEAT_FILE"' EXIT
 
 # US-AUTO-037: pull in worktree helpers (US-AUTO-036). Sourcing bin/roll is
 # safe — its main() only runs when invoked directly (BASH_SOURCE == \$0).
@@ -2306,26 +2261,34 @@ _claude_cleanup_stale_worktrees "${project_path}" || true
 # When \`gh\` is unavailable, fall back to the legacy ff-merge path.
 if [ "\$_USE_WORKTREE" = "1" ]; then
   if [ "\$_exit" -eq 0 ]; then
-    if ( cd "\$WT" && _loop_is_doc_only_change ); 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
+    # Idle cycle — no commits ahead of origin/main means nothing was built;
+    # skip publish and reclaim the worktree immediately.
+    _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"
-      echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
-    elif [ "\$_publish_status" -eq 2 ]; then
-      if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+      echo "[loop] cycle \${CYCLE_ID}: idle (no new commits); worktree cleaned"
+    else
+      if ( cd "\$WT" && _loop_is_doc_only_change ); 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
         _worktree_cleanup "\$WT" "\$BRANCH"
-        echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
+        echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
+      elif [ "\$_publish_status" -eq 2 ]; then
+        if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+          _worktree_cleanup "\$WT" "\$BRANCH"
+          echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
+        else
+          _worktree_alert "cycle \${CYCLE_ID}: gh unavailable AND merge_back failed; worktree preserved at \$WT"
+          echo "[loop] cycle \${CYCLE_ID}: gh+merge_back both failed; worktree preserved at \$WT"
+        fi
       else
-        _worktree_alert "cycle \${CYCLE_ID}: gh unavailable AND merge_back failed; worktree preserved at \$WT"
-        echo "[loop] cycle \${CYCLE_ID}: gh+merge_back both failed; worktree preserved at \$WT"
+        _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
+        echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
       fi
-    else
-      _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
-      echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
     fi
   else
     _worktree_alert "cycle \${CYCLE_ID}: claude exited \$_exit; worktree preserved at \$WT (branch \$BRANCH)"
@@ -2340,6 +2303,8 @@ INNER
 
   cat > "$script_path" << SCRIPT
 #!/bin/bash -l
+# caffeinate: prevent idle sleep from killing claude during cycles
+caffeinate -i -w \$\$ &
 # Active-window check — skipped when ROLL_LOOP_FORCE is set (manual 'roll loop now')
 if [ -z "\$ROLL_LOOP_FORCE" ]; then
   h=\$(printf '%d' "\$(date +%H)")
@@ -2348,6 +2313,50 @@ fi
 # Pause check — 'roll loop pause' creates this marker to suspend scheduling
 PAUSE="\$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
+# (e.g. SIGKILL / sleep / terminal close). Heal state to idle so the next
+# cycle can proceed normally; write ALERT for transparency.
+# FIX-038: heartbeat is the primary liveness signal (avoids PID reuse race);
+# LOCK pid check is secondary fallback for backward compatibility.
+HEARTBEAT_TIMEOUT="\${ROLL_HEARTBEAT_TIMEOUT:-1800}"
+STATE_FILE="${HOME}/.shared/roll/loop/state.yaml"
+if [ -f "\$STATE_FILE" ]; then
+  _state=\$(grep '^status:' "\$STATE_FILE" | awk '{print \$2}' 2>/dev/null || echo "")
+  if [ "\$_state" = "running" ]; then
+    _still_active=false
+    # FIX-038: heartbeat is primary signal
+    _heartbeat_file="${HOME}/.shared/roll/loop/.heartbeat-${slug}"
+    if [ -f "\$_heartbeat_file" ]; then
+      _hb_ts=\$(cat "\$_heartbeat_file" 2>/dev/null || echo "0")
+      _now=\$(date -u +%s)
+      _hb_age=\$(( _now - _hb_ts ))
+      if [ "\$_hb_age" -lt "\$HEARTBEAT_TIMEOUT" ]; then
+        _still_active=true
+      fi
+    fi
+    # Fallback: LOCK pid check (for cycles without heartbeat, e.g. pre-FIX-038)
+    if [ "\$_still_active" = false ]; then
+      _lock_file="\$(dirname "\$0")/.LOCK-\$(basename "\$0" .sh | sed 's/^run-//')"
+      if [ -f "\$_lock_file" ]; then
+        _lock_pid=\$(head -1 "\$_lock_file" 2>/dev/null || echo "")
+        [ -n "\$_lock_pid" ] && kill -0 "\$_lock_pid" 2>/dev/null && _still_active=true
+      fi
+    fi
+    # Final: tmux session check
+    if [ "\$_still_active" = false ]; then
+      command -v tmux >/dev/null 2>&1 && tmux has-session -t "roll-loop-\$(basename "\$0" .sh | sed 's/^run-//')" 2>/dev/null && _still_active=true
+    fi
+    if [ "\$_still_active" = false ]; then
+      echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-037: orphan state detected (status=running, heartbeat stale or missing) — healing to idle" >> "\$LOG"
+      echo "status: idle" > "\${STATE_FILE}.tmp" && mv "\${STATE_FILE}.tmp" "\$STATE_FILE"
+      rm -f "\$_lock_file" 2>/dev/null || true
+      _alert_file="\$(dirname "\$0")/ALERT.md"
+      echo "\$(date '+%Y-%m-%dT%H:%M:%S%z') | FIX-037 auto-heal | Orphan state detected and cleared (status=running → idle)" >> "\$_alert_file" 2>/dev/null || true
+      echo "[\$(date '+%Y-%m-%dT%H:%M:%S%z')] FIX-037: healed to idle, ALERT written" >> "\$LOG"
+    fi
+  fi
+fi
 LOCK="\$(dirname "\$0")/.LOCK-\$(basename "\$0" .sh | sed 's/^run-//')"
 SESSION="roll-loop-\$(basename "\$0" .sh | sed 's/^run-//')"
 INNER_SCRIPT="${inner_path}"
@@ -2449,7 +2458,7 @@ _install_launchd_plists() {
 
   # Terminal preference: config wins, then TERM_PROGRAM env, then "Terminal"
   local terminal_pref
-  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  terminal_pref=$(config_get "loop_attach_terminal" "")
   if [[ -z "$terminal_pref" ]]; then
     case "${TERM_PROGRAM:-}" in
       ghostty)    terminal_pref="ghostty" ;;
@@ -2679,7 +2688,7 @@ _loop_test() {
 
   # Detect terminal pref same way _install_launchd_plists does
   local terminal_pref
-  terminal_pref=$(_config_read_string "loop_attach_terminal" "")
+  terminal_pref=$(config_get "loop_attach_terminal" "")
   if [[ -z "$terminal_pref" ]]; then
     case "${TERM_PROGRAM:-}" in
       ghostty)    terminal_pref="ghostty" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.515.1",
+  "version": "2026.516.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"
@@ -27,7 +27,6 @@
     "conventions/",
     "lib/",
     "skills/",
-    "tools/",
     "template/",
     "README.md",
     "CHANGELOG.md"

package/tools/roll-fetch/SKILL.md

@@ -1,182 +0,0 @@
----
-hidden: true
-name: roll-fetch
-description: Web page fetching and crawling for AI agents. Extract content from URLs for research, documentation, and competitive analysis.
----
-
-# Roll Fetch - Web Content Extraction
-
-Extract content from web pages for research and analysis.
-
-## When to Use
-
-- Product research (competitor analysis)
-- Technical documentation gathering
-- Code examples and best practices
-- Full site crawling for backup/analysis
-
-## Environment Setup
-
-Configure API keys per machine:
-
-```bash
-# Required for Tavily
-export TAVILY_API_KEY=tvly-dev-...
-
-# Optional for cloud browser fallback
-export BROWSER_USE_API_KEY=bu-...
-```
-
-Or create `.env` file in project root:
-```
-TAVILY_API_KEY=tvly-dev-...
-BROWSER_USE_API_KEY=bu-...
-```
-
-## Methods
-
-### 1. Tavily API (Recommended)
-
-Best quality extraction, requires `TAVILY_API_KEY`.
-
-```bash
-# Using Tavily CLI or API
-curl -X POST https://api.tavily.com/extract \
-  -H "Content-Type: application/json" \
-  -d '{
-    "urls": ["https://example.com"],
-    "api_key": "your_tavily_api_key"
-  }'
-```
-
-**Pros**: AI-optimized extraction, handles complex layouts
-**Cons**: Requires API key, rate limited
-
-### 2. LLM Native Fetch (Default)
-
-Use your built-in URL fetching capability directly.
-
-**When to use**: When Tavily is unavailable or for quick checks.
-
-**Note**: Most modern AI agents (Kimi, Codex, Claude) have native URL fetching. Use `FetchURL` tool or equivalent.
-
-### 3. Browser Automation (Fallback)
-
-Local browser automation for stubborn pages using **[browser-use](https://github.com/browser-use/browser-use)**.
-
-**How to Choose:**
-
-| If | Then Use | Why |
-|----|---------|-----|
-| `BROWSER_USE_API_KEY` in env | **Cloud** | Managed browsers, less setup |
-| No API key, but `browser-use` installed | **Local** | Free, no external dependency |
-| Neither | Skip to manual extraction | Tell user "Need browser automation setup" |
-
-**Option A: Local (Free, No API Key)**
-```python
-from browser_use import Agent, Browser, BrowserConfig
-import asyncio
-
-async def fetch_page(url):
-    # Pure local, no API key needed
-    browser = Browser(config=BrowserConfig(headless=True))
-    await browser.start()
-    page = await browser.get_current_page()
-    await page.goto(url)
-    content = await page.content()
-    await browser.stop()
-    return content
-
-# Run
-content = asyncio.run(fetch_page("https://example.com"))
-```
-
-**Option B: Cloud API**
-```python
-from browser_use import Agent
-
-agent = Agent(
-    task=f"Extract the main content from {url} and return as markdown",
-    llm="moonshot"  # or openai, anthropic
-)
-result = await agent.run()
-```
-
-**Setup** (Local):
-```bash
-pip install browser-use
-playwright install chromium
-```
-
-## Usage
-
-### CLI Usage (via smart-web-fetch.js)
-
-```bash
-# Auto mode (Tavily → Native → Browser)
-node smart-web-fetch.js fetch https://example.com
-
-# Explicit method
-node smart-web-fetch.js fetch https://example.com tavily
-node smart-web-fetch.js fetch https://example.com native
-node smart-web-fetch.js fetch https://example.com browser
-
-# Search
-node smart-web-fetch.js search "Python async" 5
-```
-
-### Programmatic Usage
-
-```javascript
-const { smartFetch, smartSearch } = require('./smart-web-fetch.js');
-
-// Fetch a page
-const result = await smartFetch('https://example.com');
-console.log(result.content);
-
-// Search
-const searchResult = await smartSearch('OpenAI GPT-5', 5);
-console.log(searchResult.results);
-```
-
-### Single Page Fetch
-
-```
-User: "Fetch https://docs.example.com/api"
-→ Use smart-web-fetch.js with auto mode
-→ Return clean markdown content
-```
-
-### Full Site Crawl
-
-```
-User: "Crawl https://docs.example.com"
-→ Use smart-web-fetch.js recursively
-→ Extract all internal links
-→ Recursively fetch up to max depth (default: 2)
-→ Save each page as separate markdown file
-```
-
-## Output Format
-
-Always return clean Markdown:
-- Extract main content only (remove nav, ads, footers)
-- Preserve code blocks and tables
-- Include source URL as header
-
-## Quality Check
-
-Validate extracted content:
-- Min length: 500 chars (reject if shorter)
-- Check for captcha/error messages
-- Verify main content structure (headings, paragraphs)
-
-## Examples
-
-| Task | Method | Command |
-|------|--------|---------|
-| Quick article | Auto | `node smart-web-fetch.js fetch https://blog.example.com` |
-| API docs | Tavily | `node smart-web-fetch.js fetch https://docs.example.com tavily` |
-| SPA site | Browser | `node smart-web-fetch.js fetch https://spa.example.com browser` |
-| Search | Tavily | `node smart-web-fetch.js search "Python async" 5` |
-| Fallback test | Native | `node smart-web-fetch.js fetch https://example.com native` |

package/tools/roll-fetch/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "smart-web-fetch",
-  "version": "1.0.0",
-  "description": "Intelligent web fetching with automatic Tavily → Scrapling fallback",
-  "main": "smart-web-fetch.js",
-  "bin": {
-    "smart-web-fetch": "./smart-web-fetch.js"
-  },
-  "scripts": {
-    "test": "node smart-web-fetch.js fetch https://example.com"
-  },
-  "keywords": ["web-scraping", "tavily", "scrapling", "fallback"],
-  "author": "R0_lobster",
-  "license": "MIT"
-}

package/tools/roll-fetch/smart-web-fetch.js

@@ -1,558 +0,0 @@
-#!/usr/bin/env node
-/**
- * Smart Web Fetch Skill - Simplified 3-Layer Strategy
- * 三层策略: Tavily → LLM Native → Browser
- * 移除 mcporter, 直接 HTTP 调用, Key 从环境变量获取
- */
-
-const { execSync } = require('child_process');
-const https = require('https');
-
-// Configuration
-const TAVILY_TIMEOUT = 30000;
-const BROWSER_TIMEOUT = 90000;
-const MIN_CONTENT_LENGTH = 200;
-const MAX_RETRIES = 2;
-
-// Blocked content keywords
-const BLOCKED_KEYWORDS = [
-  // Chinese
-  '验证', 'captcha', '请登录', '环境异常', '登录后', '需要验证',
-  '请完成验证', '安全检查', '访问受限', 'blocked', 'access denied',
-  '拖动滑块', '完成拼图', '点击验证', '继续访问', '登录查看',
-  '验证后即可', '异常访问', '安全验证', '人机验证',
-  // English
-  'verify', 'verification', 'complete the verification', 'captcha required',
-  'please log in', 'sign in to', 'access denied', 'blocked',
-  'security check', 'human verification', 'prove you\'re human'
-];
-
-/**
- * Check if content is blocked or low quality
- */
-function isBlockedOrLowQuality(content, source = 'unknown') {
-  if (!content || content.length < MIN_CONTENT_LENGTH) {
-    return { blocked: true, reason: 'Content too short or empty', severity: 'high' };
-  }
-  
-  const lowerContent = content.toLowerCase();
-  const foundKeywords = [];
-  
-  for (const keyword of BLOCKED_KEYWORDS) {
-    if (lowerContent.includes(keyword.toLowerCase())) {
-      foundKeywords.push(keyword);
-    }
-  }
-  
-  if (foundKeywords.length > 0) {
-    const isLikelyBlocked = foundKeywords.some(k => 
-      ['验证', 'captcha', '环境异常', '请登录', '拖动滑块'].includes(k)
-    );
-    return { 
-      blocked: isLikelyBlocked, 
-      reason: `Detected keywords: ${foundKeywords.slice(0, 3).join(', ')}`,
-      severity: isLikelyBlocked ? 'high' : 'medium'
-    };
-  }
-  
-  return { blocked: false };
-}
-
-/**
- * Calculate content quality score
- */
-function calculateQualityScore(content) {
-  if (!content) return 0;
-  
-  let score = 0;
-  const length = content.length;
-  
-  // Length score (0-30)
-  score += Math.min(Math.log10(length) * 10, 30);
-  
-  // Content density (0-25)
-  const wordCount = content.split(/\s+/).length;
-  const avgWordLength = content.length / wordCount;
-  if (avgWordLength > 3 && avgWordLength < 15) score += 15;
-  if (content.match(/[。\.]/g)?.length > 5) score += 10;
-  
-  // Structure indicators (0-25)
-  if (content.includes('#') || content.includes('##')) score += 8;
-  if (content.includes('###')) score += 5;
-  if (content.includes('- ') || content.includes('* ')) score += 6;
-  if (content.includes('```')) score += 6;
-  
-  // Rich content indicators (0-20)
-  if (content.match(/\[.*?\]\(.*?\)/)) score += 5;
-  if (content.match(/\!\[.*?\]\(.*?\)/)) score += 5;
-  if (content.match(/\*\*.*?\*\*/)) score += 5;
-  if (content.match(/`.*?`/)) score += 5;
-  
-  return Math.min(score / 100, 1.0);
-}
-
-/**
- * Level 1: Tavily API (HTTP direct call)
- */
-function tryTavily(url, retries = 0) {
-  console.error(`[SmartFetch] Level 1: Trying Tavily for: ${url}`);
-  
-  const apiKey = process.env.TAVILY_API_KEY;
-  if (!apiKey) {
-    return { 
-      success: false, 
-      tool: 'tavily', 
-      error: 'TAVILY_API_KEY not set in environment',
-      needs_fallback: true
-    };
-  }
-  
-  return new Promise((resolve) => {
-    const postData = JSON.stringify({
-      urls: [url],
-      api_key: apiKey,
-      extract_depth: 'advanced',
-      include_images: false
-    });
-    
-    const options = {
-      hostname: 'api.tavily.com',
-      path: '/extract',
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(postData)
-      },
-      timeout: TAVILY_TIMEOUT
-    };
-    
-    const req = https.request(options, (res) => {
-      let data = '';
-      
-      res.on('data', chunk => data += chunk);
-      
-      res.on('end', () => {
-        try {
-          const response = JSON.parse(data);
-          
-          if (response.results && response.results[0]) {
-            const result = response.results[0];
-            const content = result.raw_content || result.content || '';
-            
-            if (content.length > MIN_CONTENT_LENGTH) {
-              resolve({
-                success: true,
-                tool: 'tavily',
-                content: content,
-                title: result.title || '',
-                url: result.url || url
-              });
-            } else {
-              resolve({ 
-                success: false, 
-                tool: 'tavily', 
-                error: 'Content too short',
-                needs_fallback: true
-              });
-            }
-          } else if (response.error) {
-            resolve({ 
-              success: false, 
-              tool: 'tavily', 
-              error: response.error,
-              needs_fallback: true
-            });
-          } else {
-            resolve({ 
-              success: false, 
-              tool: 'tavily', 
-              error: 'No results',
-              needs_fallback: true
-            });
-          }
-        } catch (e) {
-          resolve({ 
-            success: false, 
-            tool: 'tavily', 
-            error: `Parse error: ${e.message}`,
-            needs_fallback: true
-          });
-        }
-      });
-    });
-    
-    req.on('error', (err) => {
-      if (retries < MAX_RETRIES) {
-        console.error(`[SmartFetch] Tavily error, retrying... (${retries + 1}/${MAX_RETRIES})`);
-        resolve(tryTavily(url, retries + 1));
-      } else {
-        resolve({ 
-          success: false, 
-          tool: 'tavily', 
-          error: err.message,
-          needs_fallback: true
-        });
-      }
-    });
-    
-    req.on('timeout', () => {
-      req.destroy();
-      if (retries < MAX_RETRIES) {
-        console.error(`[SmartFetch] Tavily timeout, retrying... (${retries + 1}/${MAX_RETRIES})`);
-        resolve(tryTavily(url, retries + 1));
-      } else {
-        resolve({ 
-          success: false, 
-          tool: 'tavily', 
-          error: 'Timeout',
-          needs_fallback: true
-        });
-      }
-    });
-    
-    req.write(postData);
-    req.end();
-  });
-}
-
-/**
- * Level 2: LLM Native Fetch (return instruction for caller)
- */
-function tryLLMNative(url) {
-  console.error(`[SmartFetch] Level 2: LLM Native Fetch for: ${url}`);
-  
-  return {
-    success: false,
-    tool: 'llm_native',
-    error: 'LLM Native fetch requires caller to use FetchURL tool',
-    instruction: `Use FetchURL tool to fetch "${url}" and return the content`,
-    needs_fallback: true,
-    native_fetch: true,
-    url: url
-  };
-}
-
-/**
- * Check if browser-use is installed locally
- */
-function isBrowserUseInstalled() {
-  try {
-    execSync('/opt/homebrew/bin/python3.11 -c "import browser_use"', { 
-      encoding: 'utf-8',
-      timeout: 5000,
-      stdio: 'pipe'
-    });
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-/**
- * Level 3: Browser Automation (Local first, then Cloud)
- */
-async function tryBrowser(url) {
-  console.error(`[SmartFetch] Level 3: Trying Browser automation for: ${url}`);
-  
-  // Try local browser-use first
-  if (isBrowserUseInstalled()) {
-    console.error('[SmartFetch] Using local browser-use...');
-    
-    try {
-      const result = execSync(
-        `/opt/homebrew/bin/python3.11 -c "
-import asyncio
-import sys
-from browser_use import Browser, BrowserConfig
-
-async def fetch():
-    browser = Browser(config=BrowserConfig(headless=True))
-    await browser.start()
-    try:
-        page = await browser.get_current_page()
-        await page.goto('${url}', wait_until='networkidle')
-        content = await page.content()
-        title = await page.title()
-        print(f'TITLE:{title}')
-        print('---CONTENT---')
-        print(content)
-    finally:
-        await browser.stop()
-
-asyncio.run(fetch())
-        "`,
-        { 
-          encoding: 'utf-8', 
-          timeout: BROWSER_TIMEOUT,
-          stdio: ['pipe', 'pipe', 'pipe']
-        }
-      );
-      
-      // Parse output
-      const lines = result.split('\n');
-      let title = '';
-      let content = result;
-      
-      for (const line of lines) {
-        if (line.startsWith('TITLE:')) {
-          title = line.substring(6);
-        } else if (line === '---CONTENT---') {
-          const idx = lines.indexOf(line);
-          content = lines.slice(idx + 1).join('\n');
-          break;
-        }
-      }
-      
-      // Convert HTML to text (simple)
-      const textContent = content
-        .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
-        .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
-        .replace(/<[^>]+>/g, ' ')
-        .replace(/\s+/g, ' ')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&amp;/g, '&')
-        .replace(/&quot;/g, '"')
-        .trim();
-      
-      if (textContent.length > MIN_CONTENT_LENGTH) {
-        return {
-          success: true,
-          tool: 'browser_local',
-          content: textContent,
-          title: title,
-          url: url
-        };
-      }
-      
-      return { 
-        success: false, 
-        tool: 'browser_local', 
-        error: 'Content too short' 
-      };
-      
-    } catch (error) {
-      console.error(`[SmartFetch] Local browser failed: ${error.message.split('\n')[0]}`);
-      // Fall through to cloud
-    }
-  } else {
-    console.error('[SmartFetch] Local browser-use not installed, trying cloud...');
-  }
-  
-  // Try Cloud browser-use (if API key available)
-  const cloudApiKey = process.env.BROWSER_USE_API_KEY;
-  if (!cloudApiKey) {
-    return { 
-      success: false, 
-      tool: 'browser', 
-      error: 'Browser automation failed. Local browser-use not installed, and BROWSER_USE_API_KEY not set for cloud.'
-    };
-  }
-  
-  // Cloud browser-use would be implemented here
-  // For now, return error with setup instructions
-  return {
-    success: false,
-    tool: 'browser_cloud',
-    error: 'Cloud browser-use not yet implemented. Please install local browser-use: pip install browser-use && playwright install chromium'
-  };
-}
-
-/**
- * Smart fetch with 3-layer fallback
- * Strategy: Tavily → LLM Native → Browser
- */
-async function smartFetch(url, options = {}) {
-  const method = options.method || 'auto';
-  const skipQualityCheck = options.skipQualityCheck || false;
-  
-  console.error(`[SmartFetch] Starting fetch for: ${url} (method: ${method})`);
-  
-  // Explicit method selection
-  if (method !== 'auto') {
-    switch (method) {
-      case 'tavily': return await tryTavily(url);
-      case 'native': return tryLLMNative(url);
-      case 'browser': return await tryBrowser(url);
-      default: return { success: false, error: 'Unknown method' };
-    }
-  }
-  
-  // Auto mode: 3-layer cascade
-  
-  // Level 1: Tavily
-  const tavilyResult = await tryTavily(url);
-  
-  if (tavilyResult.success) {
-    const quality = isBlockedOrLowQuality(tavilyResult.content, 'tavily');
-    
-    if (skipQualityCheck || !quality.blocked) {
-      const score = calculateQualityScore(tavilyResult.content);
-      console.error(`[SmartFetch] ✓ Tavily succeeded (quality: ${score.toFixed(2)})`);
-      
-      return {
-        ...tavilyResult,
-        fallback_used: false,
-        quality_score: score,
-        quality_check: 'passed'
-      };
-    }
-    
-    console.error(`[SmartFetch] Tavily content blocked: ${quality.reason}`);
-  } else {
-    console.error(`[SmartFetch] Tavily failed: ${tavilyResult.error}`);
-    
-    // If Tavily key not set, skip to next level
-    if (!tavilyResult.needs_fallback) {
-      return tavilyResult;
-    }
-  }
-  
-  // Level 2: LLM Native Fetch
-  console.error('[SmartFetch] Falling back to LLM Native...');
-  const nativeResult = tryLLMNative(url);
-  
-  // Return instruction for caller to handle
-  return {
-    ...nativeResult,
-    fallback_used: true,
-    fallback_chain: ['tavily']
-  };
-  
-  // Note: Browser (Level 3) is called by the agent if native fetch fails
-}
-
-/**
- * Smart search with Tavily (HTTP direct)
- */
-function smartSearch(query, maxResults = 5) {
-  console.error(`[SmartFetch] Searching: ${query}`);
-  
-  const apiKey = process.env.TAVILY_API_KEY;
-  if (!apiKey) {
-    return { 
-      success: false, 
-      error: 'TAVILY_API_KEY not set in environment'
-    };
-  }
-  
-  return new Promise((resolve) => {
-    const postData = JSON.stringify({
-      query: query,
-      api_key: apiKey,
-      max_results: maxResults,
-      search_depth: 'advanced',
-      include_answer: true
-    });
-    
-    const options = {
-      hostname: 'api.tavily.com',
-      path: '/search',
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(postData)
-      },
-      timeout: TAVILY_TIMEOUT
-    };
-    
-    const req = https.request(options, (res) => {
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => {
-        try {
-          const response = JSON.parse(data);
-          resolve({
-            success: true,
-            query: query,
-            results: response.results || [],
-            answer: response.answer || ''
-          });
-        } catch (e) {
-          resolve({ success: false, error: `Parse error: ${e.message}` });
-        }
-      });
-    });
-    
-    req.on('error', (err) => {
-      resolve({ success: false, error: err.message });
-    });
-    
-    req.on('timeout', () => {
-      req.destroy();
-      resolve({ success: false, error: 'Timeout' });
-    });
-    
-    req.write(postData);
-    req.end();
-  });
-}
-
-// CLI interface
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const command = args[0];
-  
-  if (command === 'fetch') {
-    const url = args[1];
-    const method = args[2] || 'auto';
-    
-    if (!url) {
-      console.log(JSON.stringify({ error: 'URL required' }));
-      process.exit(1);
-    }
-    
-    smartFetch(url, { method }).then(result => {
-      console.log(JSON.stringify(result, null, 2));
-    }).catch(err => {
-      console.log(JSON.stringify({ error: err.message }));
-      process.exit(1);
-    });
-  }
-  
-  else if (command === 'search') {
-    const query = args[1];
-    const maxResults = parseInt(args[2]) || 5;
-    
-    if (!query) {
-      console.log(JSON.stringify({ error: 'Query required' }));
-      process.exit(1);
-    }
-    
-    smartSearch(query, maxResults).then(result => {
-      console.log(JSON.stringify(result, null, 2));
-    });
-  }
-  
-  else {
-    console.log(`
-Smart Web Fetch Skill - 3-Layer Strategy
-
-Usage:
-  smart-web-fetch fetch <url> [method]
-  smart-web-fetch search <query> [max_results]
-
-Methods: auto (default), tavily, native, browser
-
-3-Layer Strategy:
-  1. Tavily        - AI extraction, best quality (needs TAVILY_API_KEY)
-  2. LLM Native    - Use FetchURL tool (for agents with native capability)
-  3. Browser       - Local browser-use (fallback for stubborn pages)
-
-Environment Variables:
-  TAVILY_API_KEY       - Required for Tavily API
-  BROWSER_USE_API_KEY  - Optional for cloud browser (local preferred)
-
-Examples:
-  smart-web-fetch fetch https://example.com
-  smart-web-fetch fetch https://example.com tavily
-  smart-web-fetch search "OpenAI GPT-5" 10
-
-Install local browser:
-  pip install browser-use
-  playwright install chromium
-`);
-  }
-}
-
-module.exports = { smartFetch, smartSearch, tryTavily, tryLLMNative, tryBrowser };