karajan-code 1.35.0 → 1.36.1

package/README.md

@@ -58,31 +58,143 @@ npm install -g karajan-code
 
 That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages it). No config files to copy. `kj init` auto-detects your installed agents.
 
-## Quick start
+## Three ways to use Karajan
 
-```bash
-# Run a task — Karajan handles the rest
-kj run "Create a utility function that validates Spanish DNI numbers, with tests"
-```
+Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.
 
-[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — HU certification, triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+### 1. CLI — Direct from terminal
 
-Karajan will:
-1. Triage the task complexity and activate the right roles
-2. Write tests first (TDD)
-3. Implement code to pass those tests
-4. Run SonarQube analysis (auto-starts Docker if needed)
-5. Review the code (Solomon evaluates every rejection)
-6. Iterate until approved or escalate to you
+Run Karajan directly. You see the full pipeline output in real time.
 
 ```bash
-# More examples
+kj run "Create a utility function that validates Spanish DNI numbers, with tests"
 kj code "Add input validation to the signup form"     # Coder only
 kj review "Check the authentication changes"           # Review current diff
 kj audit "Full health analysis of this codebase"       # Read-only audit
 kj plan "Refactor the database layer"                  # Plan without coding
 ```
 
+### 2. MCP — Inside your AI agent
+
+This is the primary use case. Karajan runs as an MCP server inside Claude Code, Codex, or Gemini. You ask your AI agent to do something, and it delegates the heavy lifting to Karajan's pipeline.
+
+```
+You → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
+```
+
+The MCP server auto-registers during `npm install`. Your AI agent sees 20 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
+
+**The problem**: when Karajan runs inside an AI agent, you lose visibility. The agent shows you the final result, but not the pipeline stages, iterations, or Solomon decisions happening in real time.
+
+### 3. kj-tail — Monitor from a separate terminal
+
+**This is the companion tool.** Open a second terminal in the **same project directory** where your AI agent is working, and run:
+
+```bash
+kj-tail
+```
+
+You'll see the live pipeline output — stages, results, iterations, errors — as they happen. Same view as running `kj run` directly.
+
+```
+kj-tail                  # Follow pipeline in real time (default)
+kj-tail -v               # Verbose: include agent heartbeats and budget
+kj-tail -t               # Show timestamps
+kj-tail -s               # Snapshot: show current log and exit
+kj-tail -n 50            # Show last 50 lines then follow
+kj-tail --help           # Full options
+```
+
+> **Important**: `kj-tail` must run from the same directory where the AI agent is executing. It reads `<project>/.kj/run.log`, which is created when Karajan starts a pipeline via MCP.
+
+**Typical workflow:**
+
+```
+┌─────────────────────────┐    ┌─────────────────────────┐
+│  Terminal 1              │    │  Terminal 2              │
+│                          │    │                          │
+│  $ claude                │    │  $ kj-tail               │
+│  > implement the next    │    │                          │
+│    priority task         │    │  ├─ 📋 Triage: medium    │
+│                          │    │  ├─ 🔬 Researcher ✅     │
+│  (Claude calls kj_run   │    │  ├─ 🧠 Planner ✅        │
+│   via MCP — you see      │    │  ├─ 🔨 Coder ✅          │
+│   only the final result) │    │  ├─ 🔍 Sonar: OK        │
+│                          │    │  ├─ 👁️ Reviewer ❌       │
+│                          │    │  ├─ ⚖️ Solomon: 2 cond.  │
+│                          │    │  ├─ 🔨 Coder (iter 2) ✅ │
+│                          │    │  ├─ ✅ Review: APPROVED   │
+│                          │    │  ├─ 🧪 Tester: passed    │
+│                          │    │  └─ 🏁 Result: APPROVED  │
+└─────────────────────────┘    └─────────────────────────┘
+```
+
+**Full pipeline example** — a complex task with all roles:
+
+```
+┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
+│                                                                              │
+│  $ claude                                                                    │
+│                                                                              │
+│  > Build a REST API for a booking system. Requirements:                      │
+│  > - Express + TypeScript with Zod validation on every endpoint              │
+│  > - Endpoints: POST /bookings, GET /bookings/:id, PATCH /bookings/:id/cancel│
+│  > - A booking has: id, guestName, roomType (standard|suite|penthouse),      │
+│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
+│  > - Validate: checkOut must be after checkIn, no past dates,                │
+│  >   roomType must be a valid enum value                                     │
+│  > - Cancel returns 409 if already cancelled                                 │
+│  > - Use TDD. Run it through Karajan with architect and planner enabled,     │
+│  >   paranoid review mode. Coder claude, reviewer codex.                     │
+│                                                                              │
+│  Claude calls kj_run via MCP with:                                           │
+│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
+│                                                                              │
+│  kj-tail v1.36.1 — .kj/run.log                                              │
+│                                                                              │
+│  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
+│  ├─ ⚙️ Preflight passed — all checks OK                                     │
+│  ├─ 🔬 Researcher: 8 files analyzed, 3 patterns, 5 constraints              │
+│  ├─ 🏗️ Architect: 3-layer design (routes → service → validators)            │
+│  ├─ 🧠 Planner: 6 steps — tests first, then routes, service, validators     │
+│  │                                                                           │
+│  ▶ Iteration 1/5                                                             │
+│  ├─ 🔨 Coder (claude): implemented 3 endpoints + 18 tests                   │
+│  ├─ 📋 TDD: PASS (3 src, 2 test files)                                      │
+│  ├─ 🔍 Sonar: Quality gate OK — 0 blockers                                  │
+│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
+│  │   "Missing 404 for GET nonexistent booking"                               │
+│  │   "Cancel endpoint lacks idempotency test"                                │
+│  ├─ ⚖️ Solomon: approve_with_conditions (2 conditions)                      │
+│  │   "Add 404 response and test for GET /bookings/:id with unknown id"       │
+│  │   "Add test: cancel already-cancelled booking returns 409, not 500"       │
+│  │                                                                           │
+│  ▶ Iteration 2/5                                                             │
+│  ├─ 🔨 Coder (claude): fixed — 22 tests now                                 │
+│  ├─ 📋 TDD: PASS                                                            │
+│  ├─ 🔍 Sonar: OK                                                            │
+│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
+│  ├─ 🧪 Tester: passed — coverage 94%, 22 tests                              │
+│  ├─ 🔒 Security: passed — 0 critical, 1 low (helmet recommended)            │
+│  ├─ 📊 Audit: CERTIFIED (with 3 advisory warnings)                          │
+│  │                                                                           │
+│  🏁 Result: APPROVED                                                         │
+│     🔬 Research: 8 files, 3 patterns identified                              │
+│     🗺 Plan: 6 steps (tests first)                                           │
+│     🧪 Coverage: 94%, 22 tests                                               │
+│     🔒 Security: passed                                                      │
+│     🔍 Sonar: OK                                                             │
+│     💰 Budget: $0.42 (claude: $0.38, codex: $0.04)                           │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+
 ## The pipeline
 
 ```
@@ -123,16 +235,20 @@ Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects i
 
 ## MCP server — 20 tools
 
-Karajan is designed to be used as an MCP server inside your AI agent. After install, it auto-registers in Claude and Codex:
+After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
 ```bash
-# Already done by npm install, but manual config if needed:
-# Add to ~/.claude.json → "mcpServers":
+# Claude: add to ~/.claude.json → "mcpServers":
 # { "karajan-mcp": { "command": "karajan-mcp" } }
+
+# Codex: add to ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
+# command = "karajan-mcp"
 ```
 
 **20 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`.
 
+Use `kj-tail` in a separate terminal to see what the pipeline is doing in real time (see [Three ways to use Karajan](#three-ways-to-use-karajan)).
+
 ## The role architecture
 
 Every role in Karajan is defined by a markdown file — a plain document that describes how the agent should behave, what to check, and what good output looks like.
@@ -152,6 +268,7 @@ Use `kj roles show <role>` to inspect any template.
 Karajan auto-detects and auto-configures everything it can:
 
 - **TDD**: Detects test framework (vitest, jest, mocha) → auto-enables TDD
+- **Bootstrap gate**: Validates all prerequisites (git repo, remote, config, agents, SonarQube) before any tool runs. Fails hard with actionable fix instructions — never silently degrades
 - **SonarQube**: Auto-starts Docker container, generates config if missing
 - **Pipeline complexity**: Triage classifies task → trivial tasks skip reviewer loop
 - **Provider outages**: Retries on 500/502/503/504 with backoff (same as rate limits)
@@ -163,9 +280,9 @@ No per-project configuration required. If you want to customize, config is layer
 
 Because it should be.
 
-Karajan has **1847 tests** across 149 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
+Karajan has **1966 tests** across 157 files. It runs on Node.js without a build step. You can read the source, understand it, fork it, and modify it without a TypeScript compiler between you and the code.
 
-This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. **52 releases in 23 days** — that velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
+This is a deliberate choice, not a limitation. The tests are the type safety. The legibility is a feature. **55 releases in 26 days** — that velocity is possible precisely because vanilla JS with good tests lets you move fast without fear.
 
 ## Recommended companions
 

package/bin/kj-tail

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
-# kj-tail — Colorized, filtered tail for Karajan run logs
-# Usage: kj-tail [project-dir] [-v|--verbose]
+# kj-tail — Real-time pipeline monitor for Karajan Code
+# Follows the run log and displays colorized, filtered output.
 
 set -euo pipefail
 
-# Colors
+VERSION="1.36.0"
+
+# ── Colors ──────────────────────────────────────────────
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[0;33m'
@@ -13,58 +15,309 @@ CYAN='\033[0;36m'
 MAGENTA='\033[0;35m'
 GRAY='\033[0;90m'
 BOLD='\033[1m'
+DIM='\033[2m'
 RESET='\033[0m'
 
+# ── Defaults ────────────────────────────────────────────
 VERBOSE=false
+SHOW_AGENT_OUTPUT=false
+SHOW_TIMESTAMPS=false
+FOLLOW=true
+NUM_LINES=0
 PROJECT_DIR=""
 
-for arg in "$@"; do
-  case "$arg" in
-    -v|--verbose) VERBOSE=true ;;
-    *) PROJECT_DIR="$arg" ;;
+# ── Help ────────────────────────────────────────────────
+show_help() {
+  cat <<EOF
+${BOLD}kj-tail${RESET} — Real-time pipeline monitor for Karajan Code
+
+${BOLD}USAGE${RESET}
+  kj-tail [options] [project-dir]
+
+${BOLD}DESCRIPTION${RESET}
+  Follows the Karajan run log (<project>/.kj/run.log) and displays
+  colorized, filtered output. By default shows the same pipeline
+  progress view as 'kj run': stages, results, iterations, and errors.
+
+  Run this in a separate terminal while kj executes via MCP/CLI.
+
+${BOLD}OPTIONS${RESET}
+  -v, --verbose       Show agent heartbeats, budget, and metadata
+  -a, --agent-output  Show raw agent output lines (very noisy)
+  -t, --timestamps    Show timestamps on each line
+  -n, --lines <N>     Show last N lines then follow (default: follow only new)
+  -s, --snapshot      Show current log (no follow) — like 'cat' with colors
+  -h, --help          Show this help
+  --version           Show version
+
+${BOLD}EXAMPLES${RESET}
+  kj-tail                  # Follow current directory's run log
+  kj-tail /path/to/project # Follow a specific project's log
+  kj-tail -v               # Verbose: include heartbeats and budget
+  kj-tail -a               # Show everything including agent output
+  kj-tail -n 50            # Show last 50 lines then follow
+  kj-tail -s               # Snapshot: show full log and exit
+  kj-tail -t               # Show timestamps
+
+${BOLD}LOG LOCATION${RESET}
+  <project-dir>/.kj/run.log
+  Created automatically when kj_run, kj_code, or kj_review starts.
+
+EOF
+  exit 0
+}
+
+# ── Parse args ──────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help) show_help ;;
+    --version) echo "kj-tail $VERSION"; exit 0 ;;
+    -v|--verbose) VERBOSE=true; shift ;;
+    -a|--agent-output) SHOW_AGENT_OUTPUT=true; VERBOSE=true; shift ;;
+    -t|--timestamps) SHOW_TIMESTAMPS=true; shift ;;
+    -s|--snapshot) FOLLOW=false; shift ;;
+    -n|--lines)
+      shift
+      NUM_LINES="${1:-50}"
+      shift
+      ;;
+    -*)
+      echo -e "${RED}Unknown option: $1${RESET}" >&2
+      echo "Run 'kj-tail --help' for usage." >&2
+      exit 1
+      ;;
+    *) PROJECT_DIR="$1"; shift ;;
   esac
 done
 
 PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
 LOG_FILE="${PROJECT_DIR}/.kj/run.log"
 
+# ── Locate log ──────────────────────────────────────────
 if [[ ! -f "$LOG_FILE" ]]; then
-  echo -e "${RED}No run.log found at ${LOG_FILE}${RESET}"
-  echo "Usage: kj-tail [project-dir] [-v|--verbose]"
+  echo -e "${RED}No run log found at ${LOG_FILE}${RESET}"
+  echo ""
+  echo "The run log is created when Karajan starts a pipeline."
+  echo "Make sure you're in the project directory, or pass it as argument:"
+  echo ""
+  echo "  kj-tail /path/to/project"
+  echo ""
   exit 1
 fi
 
-echo -e "${BOLD}${CYAN}Karajan tail${RESET} ${GRAY}— ${LOG_FILE}${RESET}"
-echo -e "${GRAY}Ctrl+C to stop. Use -v to include agent output.${RESET}"
-echo ""
+# ── Filter & colorize ──────────────────────────────────
+filter_line() {
+  local line="$1"
+  local ts=""
+  local clean="$line"
 
-tail -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
-  # Strip timestamp (HH:MM:SS.mmm)
-  clean="${line#[0-9][0-9]:[0-9][0-9]:[0-9][0-9].[0-9][0-9][0-9] }"
-
-  # Strip [agent:output] tag — it's the default, no need to show it
-  clean="${clean/\[agent:output\] /}"
-
-  # Colorize by content
-  if [[ "$clean" == *"[coder:start]"* ]] || [[ "$clean" == *"[coder:done]"* ]] || [[ "$clean" == *"[coder]"* ]]; then
-    echo -e "${GREEN}${clean}${RESET}"
-  elif [[ "$clean" == *"[reviewer"* ]]; then
-    echo -e "${YELLOW}${clean}${RESET}"
-  elif [[ "$clean" == *"[sonar"* ]]; then
-    echo -e "${BLUE}${clean}${RESET}"
-  elif [[ "$clean" == *"[solomon"* ]]; then
-    echo -e "${MAGENTA}${clean}${RESET}"
-  elif [[ "$clean" == *"[iteration"* ]] || [[ "$clean" == *"[session"* ]] || [[ "$clean" == *"[kj_run]"* ]] || [[ "$clean" == *"[kj_code]"* ]]; then
-    echo -e "${BOLD}${CYAN}${clean}${RESET}"
-  elif [[ "$clean" == *"fail"* ]] || [[ "$clean" == *"error"* ]] || [[ "$clean" == *"FAIL"* ]] || [[ "$clean" == *"ERROR"* ]]; then
-    echo -e "${RED}${clean}${RESET}"
-  elif [[ "$clean" == *"[agent:heartbeat]"* ]]; then
-    echo -e "${GRAY}${clean}${RESET}"
-  elif [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]]; then
-    echo -e "${YELLOW}${clean}${RESET}"
-  elif [[ "$clean" == "---"* ]]; then
-    echo -e "${BOLD}${clean}${RESET}"
-  else
-    echo "$clean"
+  # Extract and optionally strip timestamp (HH:MM:SS.mmm)
+  if [[ "$clean" =~ ^([0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3})\ (.*) ]]; then
+    ts="${BASH_REMATCH[1]}"
+    clean="${BASH_REMATCH[2]}"
   fi
-done
+
+  # Skip noise in default mode
+  if [[ "$VERBOSE" == "false" ]]; then
+    # Skip agent heartbeats
+    [[ "$clean" == *"[agent:heartbeat]"* ]] && return
+    [[ "$clean" == *"heartbeat"* ]] && return
+    # Skip budget lines
+    [[ "$clean" == *"Budget:"* ]] && return
+    # Skip agent raw output
+    [[ "$clean" == *"[agent:output]"* ]] && return
+    # Skip internal metadata
+    [[ "$clean" == *"[agent:start]"* ]] && return
+    [[ "$clean" == *"[agent:end]"* ]] && return
+    # Skip noisy JSON dumps (system init, tool lists, etc.)
+    [[ "${#clean}" -gt 500 ]] && return
+  fi
+
+  if [[ "$SHOW_AGENT_OUTPUT" == "false" ]]; then
+    # Skip raw agent output (often JSON/stream data)
+    [[ "$clean" == "{"* ]] && [[ "$clean" == *"}" ]] && return
+    [[ "$clean" == *'"type":'* ]] && [[ "${#clean}" -gt 200 ]] && return
+  fi
+
+  # Build prefix
+  local prefix=""
+  if [[ "$SHOW_TIMESTAMPS" == "true" ]] && [[ -n "$ts" ]]; then
+    prefix="${DIM}${ts}${RESET} "
+  fi
+
+  # ── Colorize by content ──────────────────────────────
+  # Session markers
+  if [[ "$clean" == "---"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}${clean}${RESET}"
+    return
+  fi
+
+  # Stage: started/finished
+  if [[ "$clean" == *"started"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}▶ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"finished"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}✓ ${clean}${RESET}"
+    return
+  fi
+
+  # Iterations
+  if [[ "$clean" == *"[iteration]"* ]] || [[ "$clean" == *"Iteration "* ]]; then
+    echo -e "${prefix}${BOLD}${clean}${RESET}"
+    return
+  fi
+
+  # Coder
+  if [[ "$clean" == *"[coder"* ]] || [[ "$clean" == *"Coder"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 🔨 ${clean}${RESET}"
+    return
+  fi
+
+  # Reviewer
+  if [[ "$clean" == *"APPROVED"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ ✅ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"REJECTED"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ❌ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"[reviewer"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 👁️  ${clean}${RESET}"
+    return
+  fi
+
+  # Solomon
+  if [[ "$clean" == *"[solomon"* ]] || [[ "$clean" == *"Solomon"* ]]; then
+    echo -e "${prefix}${MAGENTA}  ├─ ⚖️  ${clean}${RESET}"
+    return
+  fi
+
+  # Sonar
+  if [[ "$clean" == *"[sonar"* ]] || [[ "$clean" == *"SonarQube"* ]] || [[ "$clean" == *"Quality gate"* ]]; then
+    echo -e "${prefix}${BLUE}  ├─ 🔍 ${clean}${RESET}"
+    return
+  fi
+
+  # Tester
+  if [[ "$clean" == *"[tester"* ]] || [[ "$clean" == *"Tester"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧪 ${clean}${RESET}"
+    return
+  fi
+
+  # Security
+  if [[ "$clean" == *"[security"* ]] || [[ "$clean" == *"Security"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔒 ${clean}${RESET}"
+    return
+  fi
+
+  # Researcher
+  if [[ "$clean" == *"[researcher"* ]] || [[ "$clean" == *"Researcher"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔬 ${clean}${RESET}"
+    return
+  fi
+
+  # Architect
+  if [[ "$clean" == *"[architect"* ]] || [[ "$clean" == *"Architect"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🏗️  ${clean}${RESET}"
+    return
+  fi
+
+  # Planner
+  if [[ "$clean" == *"[planner"* ]] || [[ "$clean" == *"Planner"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧠 ${clean}${RESET}"
+    return
+  fi
+
+  # Triage
+  if [[ "$clean" == *"[triage"* ]] || [[ "$clean" == *"Triage"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Audit
+  if [[ "$clean" == *"[audit"* ]] || [[ "$clean" == *"Audit"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📊 ${clean}${RESET}"
+    return
+  fi
+
+  # Preflight
+  if [[ "$clean" == *"[preflight"* ]] || [[ "$clean" == *"Preflight"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ ⚙️  ${clean}${RESET}"
+    return
+  fi
+
+  # TDD
+  if [[ "$clean" == *"TDD"* ]] || [[ "$clean" == *"tdd"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Errors / failures
+  if [[ "$clean" == *"fail"*  || "$clean" == *"FAIL"* || "$clean" == *"error"* || "$clean" == *"ERROR"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ⚠️  ${clean}${RESET}"
+    return
+  fi
+
+  # Standby / rate limit
+  if [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]] || [[ "$clean" == *"rate limit"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ ⏸️  ${clean}${RESET}"
+    return
+  fi
+
+  # Model fallback
+  if [[ "$clean" == *"not supported"* ]] || [[ "$clean" == *"retrying with"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 🔄 ${clean}${RESET}"
+    return
+  fi
+
+  # Result line
+  if [[ "$clean" == *"Result:"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}🏁 ${clean}${RESET}"
+    return
+  fi
+
+  # Budget (verbose only — already filtered above)
+  if [[ "$clean" == *"Budget:"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ 💰 ${clean}${RESET}"
+    return
+  fi
+
+  # Agent heartbeat (verbose only)
+  if [[ "$clean" == *"heartbeat"* ]] || [[ "$clean" == *"active —"* ]] || [[ "$clean" == *"elapsed"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ • ${clean}${RESET}"
+    return
+  fi
+
+  # Default
+  echo -e "${prefix}  ├─ ${clean}"
+}
+
+# ── Header ──────────────────────────────────────────────
+echo -e "${BOLD}${CYAN}kj-tail${RESET} ${DIM}v${VERSION} — ${LOG_FILE}${RESET}"
+if [[ "$FOLLOW" == "true" ]]; then
+  echo -e "${GRAY}Ctrl+C to stop${RESET}${VERBOSE:+ ${DIM}(verbose)${RESET}}"
+fi
+echo ""
+
+# ── Run ─────────────────────────────────────────────────
+if [[ "$FOLLOW" == "false" ]]; then
+  # Snapshot mode: show full log and exit
+  while IFS= read -r line; do
+    filter_line "$line"
+  done < "$LOG_FILE"
+  exit 0
+fi
+
+if [[ "$NUM_LINES" -gt 0 ]]; then
+  # Show last N lines then follow
+  tail -n "$NUM_LINES" -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+else
+  # Follow only new lines
+  tail -n 0 -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+fi