upgrade_codebase.py

#!/usr/bin/env python3
"""
Enterprise Code Upgrader v3
============================
Recursively upgrades all source files in a directory to enterprise quality
using Claude, maintaining a SINGLE conversation across all files so the AI
builds context as it goes.

v3 improvements over v2:
  - Syntax validation after every upgrade (Python: ast.parse, JS: node --check)
  - Retry with re-prompt on parse failure or syntax error (up to 2 retries)
  - External state tracking via .upgrade-state.json (no marker injection)
  - Richer conversation intro (sends established patterns + file manifest)
  - Progress persistence — resume exactly where you left off after crash
  - Output size sanity check (rejects responses <50% or >300% of original)

Two backends:
  1. Anthropic API        (--backend api)    — ANTHROPIC_API_KEY env var + pip install anthropic
  2. Claude Code CLI      (--backend cli)    — uses `claude` CLI with session persistence
  3. OpenCode CLI         (--backend opencode) — uses `opencode run` with JSONL streaming

Usage:
  python upgrade_codebase.py "C:/Users/subha/projects/penora/backend"
  python upgrade_codebase.py . --include "**/*.py" --backend cli --commit-every 5
  python upgrade_codebase.py . --include "**/*.ts" --backend opencode -m anthropic/claude-sonnet-4-20250514
  python upgrade_codebase.py . --include "**/*.ts" --dry-run
"""

from __future__ import annotations

import argparse
import ast
import json
import os
import re
import subprocess
import sys
import time
import logging
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path
from typing import Any, Final, Optional

# =============================================================================
# Logging
# =============================================================================

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s  %(levelname)-7s  %(message)s",
    datefmt="%H:%M:%S",
)
log = logging.getLogger("upgrader")

# =============================================================================
# Constants
# =============================================================================

EXTENSION_MAP: Final[dict[str, str]] = {
    ".py": "python", ".js": "javascript", ".ts": "typescript",
    ".tsx": "tsx", ".jsx": "jsx", ".java": "java", ".kt": "kotlin",
    ".go": "go", ".rs": "rust", ".rb": "ruby", ".php": "php",
    ".cs": "csharp", ".cpp": "cpp", ".c": "c", ".h": "c",
    ".vue": "vue", ".svelte": "svelte", ".html": "html",
    ".css": "css", ".scss": "scss", ".sql": "sql",
    ".sh": "bash", ".ps1": "powershell", ".yaml": "yaml",
    ".yml": "yaml", ".json": "json", ".toml": "toml",
    ".md": "markdown", ".dart": "dart", ".swift": "swift",
}

MAX_FILE_SIZE_KB: Final[int] = 200
SMALL_FILE_THRESHOLD: Final[int] = 500

# Output size sanity bounds (ratio vs original)
MIN_OUTPUT_RATIO: Final[float] = 0.3   # Reject if <30% of original
MAX_OUTPUT_RATIO: Final[float] = 20.0  # Reject if >2000% of original

# Retry
MAX_UPGRADE_RETRIES: Final[int] = 2

# Tiered batching: smaller files → more per prompt
BATCH_TIERS: Final[list[tuple[int, int]]] = [
    (100, 10),
    (200,  5),
    (300,  3),
    (500,  2),
]

DEFAULT_EXCLUDES: Final[list[str]] = [
    "node_modules/**", "venv/**", ".venv/**", "__pycache__/**",
    ".git/**", ".upgrade-logs/**", ".upgrade-debug/**",
    "upgraded/**", "dist/**", "build/**", ".next/**",
    "*.min.js", "*.min.css", "package-lock.json", "yarn.lock",
    "poetry.lock", "Pipfile.lock", "*.pyc", "*.pyo",
    ".env", ".env.*", "*.lock",
]

STATE_FILE: Final[str] = ".upgrade-state.json"


# =============================================================================
# Upgrade State (replaces marker injection)
# =============================================================================

@dataclass
class UpgradeState:
    """Tracks which files have been upgraded.  Persisted to .upgrade-state.json.

    This replaces the old approach of injecting '# ENTERPRISE-UPGRADED' comments
    into source files — which pollutes the code with non-functional markers.
    """

    completed: dict[str, dict[str, Any]] = field(default_factory=dict)
    """Map of relative path → {timestamp, changes, original_lines, upgraded_lines}"""

    failed: dict[str, str] = field(default_factory=dict)
    """Map of relative path → error message"""

    started_at: str = ""
    last_updated: str = ""

    @classmethod
    def load(cls, project_root: Path) -> UpgradeState:
        state_path = project_root / STATE_FILE
        if state_path.exists():
            try:
                data = json.loads(state_path.read_text(encoding="utf-8"))
                return cls(
                    completed=data.get("completed", {}),
                    failed=data.get("failed", {}),
                    started_at=data.get("started_at", ""),
                    last_updated=data.get("last_updated", ""),
                )
            except Exception as e:
                log.warning("Could not load state file: %s", e)
        return cls(started_at=datetime.now().isoformat())

    def save(self, project_root: Path) -> None:
        self.last_updated = datetime.now().isoformat()
        state_path = project_root / STATE_FILE
        state_path.write_text(
            json.dumps({
                "completed": self.completed,
                "failed": self.failed,
                "started_at": self.started_at,
                "last_updated": self.last_updated,
            }, indent=2),
            encoding="utf-8",
        )

    def mark_completed(
        self, rel_path: str, changes: str | None,
        original_lines: int, upgraded_lines: int,
    ) -> None:
        self.completed[rel_path] = {
            "timestamp": datetime.now().isoformat(),
            "changes": changes,
            "original_lines": original_lines,
            "upgraded_lines": upgraded_lines,
        }
        self.failed.pop(rel_path, None)

    def mark_failed(self, rel_path: str, error: str) -> None:
        self.failed[rel_path] = error

    def is_done(self, rel_path: str) -> bool:
        return rel_path in self.completed


# =============================================================================
# Syntax Validation
# =============================================================================

class SyntaxValidator:
    """Validates that upgraded code is syntactically correct.

    This is the #1 improvement over v2 — without this, a bad LLM response
    gets written to disk and committed, breaking the build.
    """

    @staticmethod
    def validate(code: str, language: str, filepath: str = "<unknown>") -> tuple[bool, str]:
        """Validate syntax.  Returns (ok, error_message)."""
        if language == "python":
            return SyntaxValidator._validate_python(code, filepath)
        if language in ("javascript", "typescript", "jsx", "tsx"):
            return SyntaxValidator._validate_js(code, filepath)
        # For other languages, skip validation (still better than nothing)
        return True, ""

    @staticmethod
    def _validate_python(code: str, filepath: str) -> tuple[bool, str]:
        try:
            ast.parse(code, filename=filepath)
            return True, ""
        except SyntaxError as e:
            return False, f"Python syntax error at line {e.lineno}: {e.msg}"

    @staticmethod
    def _validate_js(code: str, filepath: str) -> tuple[bool, str]:
        """Validate JS/TS by writing to a temp file and running node --check."""
        import tempfile
        ext = Path(filepath).suffix or ".js"
        try:
            with tempfile.NamedTemporaryFile(
                mode="w", suffix=ext, delete=False, encoding="utf-8",
            ) as f:
                f.write(code)
                tmp_path = f.name

            # node --check only works for .js/.mjs — for .ts/.tsx we skip
            if ext in (".ts", ".tsx"):
                return True, ""  # Can't validate TS without tsc

            result = subprocess.run(
                ["node", "--check", tmp_path],
                capture_output=True, text=True, timeout=10,
            )
            if result.returncode == 0:
                return True, ""
            return False, f"JS syntax error: {result.stderr[:300]}"
        except FileNotFoundError:
            # node not installed — skip
            return True, ""
        except Exception as e:
            return True, ""  # Don't block on validation infrastructure failure
        finally:
            try:
                os.unlink(tmp_path)
            except Exception:
                pass


# =============================================================================
# Output Sanity Checks
# =============================================================================

def _check_output_sanity(
    original_code: str,
    upgraded_code: str,
    filepath: str,
) -> tuple[bool, str]:
    """Check that the upgraded code is reasonable relative to the original.

    Rejects outputs that are suspiciously small (truncated) or absurdly large
    (LLM hallucinated extra content).
    """
    orig_lines = len(original_code.splitlines())
    new_lines = len(upgraded_code.splitlines())

    if orig_lines == 0:
        return True, ""

    # Reject placeholder/stub outputs (e.g. "# See code field above")
    if new_lines <= 5 and orig_lines > 10:
        return False, (
            f"Output is a stub ({new_lines} lines for {orig_lines}-line original). "
            f"Model likely returned a placeholder instead of real code."
        )

    ratio = new_lines / orig_lines

    # Small files often grow dramatically during enterprise upgrade — be lenient
    effective_max = MAX_OUTPUT_RATIO * 3 if orig_lines < 200 else MAX_OUTPUT_RATIO

    if ratio < MIN_OUTPUT_RATIO:
        return False, (
            f"Output too small: {new_lines} lines vs {orig_lines} original "
            f"(ratio {ratio:.1f}, min {MIN_OUTPUT_RATIO}). Likely truncated."
        )

    if ratio > effective_max:
        return False, (
            f"Output too large: {new_lines} lines vs {orig_lines} original "
            f"(ratio {ratio:.1f}, max {effective_max:.1f}). Likely hallucinated."
        )

    # Log warning for significant shrinkage (>25%)
    if ratio < 0.75:
        log.warning(
            "    !!! Significant shrinkage: %d -> %d lines (%.1f%%). Verify code didn't lose logic.",
            orig_lines, new_lines, ratio * 100
        )

    # Check that the output isn't just the prompt echoed back
    if "### Changes Made" in upgraded_code or "### Upgraded Code" in upgraded_code:
        return False, "Output contains response formatting markers — parse error"

    return True, ""


# =============================================================================
# File Discovery
# =============================================================================

def discover_files(
    project_root: Path,
    include_patterns: list[str],
    exclude_patterns: list[str],
    state: UpgradeState,
    skip_done: bool,
) -> list[Path]:
    """Recursively glob the project for matching files."""
    from fnmatch import fnmatch

    code_extensions = set(EXTENSION_MAP.keys())
    matched: list[Path] = []

    for pattern in include_patterns:
        for path in project_root.glob(pattern):
            if not path.is_file():
                continue
            if path.suffix.lower() not in code_extensions:
                continue

            rel = path.relative_to(project_root).as_posix()

            # Fast directory skip to prevent nested node_modules from sneaking through
            parts = rel.split("/")
            if any(bad in parts for bad in ("node_modules", ".git", "venv", ".venv", "__pycache__", "dist", "build", ".next", "upgraded", ".upgrade-logs", ".upgrade-debug")):
                continue

            # Standard regex/glob matching for other patterns
            if any(fnmatch(rel, ex) for ex in exclude_patterns) or any(fnmatch(rel, f"*/{ex}") for ex in exclude_patterns):
                continue
            if path.stat().st_size > MAX_FILE_SIZE_KB * 1024:
                log.warning("Skipping (too large): %s", rel)
                continue
            if skip_done and state.is_done(rel):
                log.info("Skipping (already done): %s", rel)
                continue

            matched.append(path)

    return sorted(set(matched))


def count_lines(path: Path) -> int:
    try:
        return len(path.read_text(encoding="utf-8", errors="replace").splitlines())
    except Exception:
        return 9999


def build_compact_intro(
    project_root: Path,
    state: UpgradeState,
    run_results: list[tuple[str, bool, str | None]],
    system_prompt_file: str,
) -> str:
    """Build a compacted intro message for session restart.

    When context approaches the model's limit, we start a fresh session with:
    1. GitHub summaries (full prior upgrade context from .upgrade-state.json)
    2. Summary of this run's progress
    3. Last 5 file upgrade results (detailed)
    4. Instruction to continue

    This preserves the essential context while freeing up ~900k tokens.
    """
    system_prompt = Path(system_prompt_file).read_text(encoding="utf-8", errors="replace")

    # 1. GitHub summaries from state
    summaries = []
    completed = state.completed
    for rel, info in sorted(completed.items()):
        reason = info.get("reason", "upgraded")
        orig = info.get("original_lines", 0)
        upgraded = info.get("upgraded_lines", 0)
        summaries.append(f"- `{rel}`: {orig} -> {upgraded} lines ({reason})")

    summary_block = "\n".join(summaries) if summaries else "No prior upgrades recorded."

    # 2. This run's progress
    total_run = len(run_results)
    succeeded = sum(1 for _, ok, _ in run_results if ok)
    failed = total_run - succeeded
    run_progress = (
        f"\n**Current Run Progress:** {succeeded}/{total_run} succeeded, {failed} failed so far.\n"
    )

    # 3. Last 5 file results (detailed)
    last_5 = run_results[-5:] if len(run_results) >= 5 else run_results
    last_5_block = ""
    if last_5:
        last_5_block = "\n**Most Recent Files (last 5 processed):**\n"
        for rel, ok, changes in last_5:
            status = "SUCCESS" if ok else "FAILED"
            change_summary = changes[:200] if changes else "no details"
            last_5_block += f"\n### {rel} [{status}]\n{change_summary}\n"

    # 4. The compact prompt
    return (
        f"## Session Restart — Context Compaction\n\n"
        f"The previous conversation was compacted to free up context space. "
        f"Here is everything you need to continue the enterprise code upgrade.\n\n"
        f"---\n\n"
        f"### System Prompt (Enterprise Upgrade Patterns)\n\n"
        f"{system_prompt}\n\n"
        f"---\n\n"
        f"### Prior Upgrade Summaries (from .upgrade-state.json)\n\n"
        f"These are all the files that were upgraded in previous runs. "
        f"Use these as reference for the patterns and style expected.\n\n"
        f"{summary_block}\n\n"
        f"---\n\n"
        f"{run_progress}"
        f"{last_5_block}"
        f"---\n\n"
        f"**Continue upgrading the remaining files using the same enterprise patterns.** "
        f"Apply the same transformations you see in the summaries above: constants classes, "
        f"typed configs, frozen dataclasses, structured logging, error hierarchies, "
        f"service facades, protocol-based DI, and backward-compatible delegators.\n\n"
        f"The file content will be provided in the next messages. "
        f"Work through them one at a time, returning the full upgraded code in a markdown code block."
    )


# =============================================================================
# Prompt Builders
# =============================================================================

def build_single_prompt(
    file_path: Path, project_root: Path, explore: bool = False,
    max_reads: int = 5, context_tokens: int = 0, context_limit: int = 1_000_000,
    explore_cutoff: int = 500_000,
) -> str:
    rel_path = file_path.relative_to(project_root).as_posix()
    ext = EXTENSION_MAP.get(file_path.suffix.lower(), file_path.suffix.lstrip("."))
    content = file_path.read_text(encoding="utf-8", errors="replace")
    if explore:
        ctx_k = context_tokens // 1000
        limit_k = context_limit // 1000
        cutoff_k = explore_cutoff // 1000
        remaining_k = max(0, cutoff_k - ctx_k)
        explore_note = (
            f"You have Read access to the project — but you can only Read **{max_reads} files** for this upgrade. "
            f"After that your Read access is revoked.\n"
            f"Context: **{ctx_k}k / {limit_k}k tokens** used. "
            f"Read access is permanently revoked at **{cutoff_k}k tokens** ({remaining_k}k remaining). "
            f"Choose wisely: prioritize imports, shared types, and base classes. "
            f"Skip files you can infer from context or naming.\n\n"
        )
    else:
        explore_note = (
            "**You do NOT need to read other files — the complete source is provided below. "
            "Work ONLY with what is in this message unless you have a strong reason to check "
            "a related file (e.g. an import you don't understand). "
            "Reading other files adds overhead and slows down the upgrade.**\n\n"
        )
    line_count = len(content.splitlines())
    return (
        f"Upgrade this file to enterprise quality.\n\n"
        f"{explore_note}"
        f"Apply EVERY applicable pattern from your system prompt — constants class, "
        f"typed exception hierarchy, frozen config dataclass, singleton factory, "
        f"context managers, structured logging, the works. "
        f"Don't hold back. If the file has placeholder implementations, replace them "
        f"with real implementations. If it's a single class doing 5 things, split it. "
        f"If it uses Dict[str, Any], define proper TypedDicts.\n\n"
        f"The output should be a COMPLETE production-quality rewrite — "
        f"not a patch, not incremental fixes. Think of this as writing the file "
        f"from scratch with the same public API but enterprise internals.\n\n"
        f"**Output format (required):**\n\n"
        f"### Changes Made\n"
        f"Write a concise bullet-point summary of the specific changes you made. "
        f"Be concrete: mention new classes, functions, patterns applied, magic numbers replaced, "
        f"error handling added, etc. This summary will be used as the git commit message.\n\n"
        f"### Upgraded Code\n"
        f"Write the COMPLETE upgraded file in a single markdown code block with the "
        f"correct language tag. Do NOT split into multiple code blocks.\n\n"
        f"## `{rel_path}` ({line_count} lines)\n\n"
        f"```{ext}\n{content}\n```"
    )


def build_plan_prompt(
    file_path: Path, project_root: Path, explore: bool = False,
    max_reads: int = 5, context_tokens: int = 0, context_limit: int = 1_000_000,
    explore_cutoff: int = 500_000,
) -> str:
    """Hybrid mode pass 1 — produce a detailed improvement plan, no code yet."""
    rel_path = file_path.relative_to(project_root).as_posix()
    ext = EXTENSION_MAP.get(file_path.suffix.lower(), file_path.suffix.lstrip("."))
    content = file_path.read_text(encoding="utf-8", errors="replace")
    if explore:
        ctx_k = context_tokens // 1000
        limit_k = context_limit // 1000
        cutoff_k = explore_cutoff // 1000
        remaining_k = max(0, cutoff_k - ctx_k)
        explore_note = (
            f"You have Read access to the project — but you can only Read **{max_reads} files** for this planning pass. "
            f"After that your Read access is revoked.\n"
            f"Context: **{ctx_k}k / {limit_k}k tokens** used. "
            f"Read access is permanently revoked at **{cutoff_k}k tokens** ({remaining_k}k remaining). "
            f"Choose wisely: prioritize imports, shared types, and base classes. "
            f"Skip files you can infer from context or naming.\n\n"
        )
    else:
        explore_note = (
            "**You do NOT need to read other files — the complete source is provided below. "
            "Work ONLY with what is in this message unless you have a strong reason to check "
            "a related file (e.g. an import you don't understand). "
            "Reading other files adds overhead and slows down the upgrade.**\n\n"
        )
    return (
        f"Analyze this file and produce a detailed enterprise upgrade plan.\n\n"
        f"{explore_note}"
        f"List EVERY specific change needed (error handling, typing, architecture, patterns, "
        f"security, performance). Be concrete and file-specific. "
        f"Do NOT write any code yet — only the numbered plan.\n\n"
        f"## File: `{rel_path}`\n\n"
        f"```{ext}\n{content}\n```"
    )


def build_execute_prompt(file_path, project_root, plan, error=None):
    rel_path = file_path.relative_to(project_root).as_posix()
    ext = EXTENSION_MAP.get(file_path.suffix.lower(), file_path.suffix.lstrip("."))
    content = file_path.read_text(encoding="utf-8", errors="replace")
    error_note = f"\n\n**Previous attempt failed:** {error}\n" if error else ""
    return (
        f"Now execute this upgrade plan for `{rel_path}`.{error_note}\n\n"
        f"**The complete source file is embedded below** — you do NOT need any tools, "
        f"file access, or Read calls. Everything you need is in this message.\n\n"
        f"Write the COMPLETE file — a full production-quality rewrite based on the plan.\n\n"
        f"## Plan\n{plan}\n\n"
        f"## Current File ({len(content.splitlines())} lines)\n```{ext}\n{content}\n```"
    )


def build_retry_prompt(file_path, project_root, error):
    rel_path = file_path.relative_to(project_root).as_posix()
    ext = EXTENSION_MAP.get(file_path.suffix.lower(), file_path.suffix.lstrip("."))
    content = file_path.read_text(encoding="utf-8", errors="replace")
    return (
        f"Your previous upgrade of `{rel_path}` failed: **{error}**\n\n"
        f"The complete source file is embedded below — you do NOT need any tools or file access. "
        f"Try again. Output the COMPLETE upgraded file.\n\n"
        f"**Output format (required):**\n\n"
        f"### Changes Made\n"
        f"Brief summary of what you changed in this retry.\n\n"
        f"### Upgraded Code\n"
        f"The COMPLETE upgraded file in a single code block.\n\n"
        f"```{ext}\n{content}\n```"
    )


def build_batch_prompt(files: list[Path], project_root: Path) -> str:
    parts = [
        "Upgrade ALL of the following files to enterprise quality. "
        "Do NOT use the Read tool — work with the file contents provided.\n\n"
        "You may:\n"
        "- Skip trivial files by returning `<SKIP>` for their code.\n"
        "- Create new companion files (extracted types, utils, constants) via `new_files`.\n"
        "- Mark files that are now redundant/replaced via `deprecated_files`.\n\n"
        "Return each file separately using the exact format below for EACH file:\n\n"
        "### Changes Made for `<file_path>`\n<changes or reason for skipping>\n\n"
        "### Upgraded Code for `<file_path>`\n```<ext>\n<full code OR <SKIP>>\n```\n\n"
        "---\n\nHere are the files to upgrade:\n"
    ]
    for fp in files:
        rel = fp.relative_to(project_root).as_posix()
        ext = EXTENSION_MAP.get(fp.suffix.lower(), fp.suffix.lstrip("."))
        content = fp.read_text(encoding="utf-8", errors="replace")
        parts.append(f"\n## `{rel}`\n\n```{ext}\n{content}\n```\n")
    return "\n".join(parts)


# =============================================================================
# Response Parsers
# =============================================================================

def parse_single_response(text: str) -> tuple[str | None, str | None]:
    """Extract (changes_summary, upgraded_code) from a single-file response."""
    changes_match = re.search(
        r"###?\s*Changes\s*Made[^\n]*\n(.*?)(?=###?\s*Upgraded\s*Code|```)",
        text, re.DOTALL | re.IGNORECASE,
    )
    changes = changes_match.group(1).strip() if changes_match else None

    code_blocks = re.findall(r"```\w*\n(.*?)```", text, re.DOTALL)
    if not code_blocks:
        return changes, None

    code = max(code_blocks, key=len).strip()
    return changes, code


def parse_batch_response(
    text: str, files: list[Path], project_root: Path,
) -> dict[Path, tuple[str | None, str | None]]:
    """Parse a batch response containing multiple files."""
    results: dict[Path, tuple[str | None, str | None]] = {}

    for fp in files:
        rel = fp.relative_to(project_root).as_posix()
        fname = fp.name

        pattern = re.compile(
            rf"###?\s*Changes\s*Made\s*(?:for\s*)?[`'\"]?{re.escape(rel)}|"
            rf"###?\s*Changes\s*Made\s*(?:for\s*)?[`'\"]?{re.escape(fname)}",
            re.IGNORECASE,
        )
        match = pattern.search(text)

        if match:
            start = match.start()
            next_section = re.search(
                r"\n---\n|###?\s*Changes\s*Made\s*(?:for\s*)?[`'\"]?(?!"
                + re.escape(rel) + r")",
                text[match.end():], re.IGNORECASE,
            )
            end = match.end() + next_section.start() if next_section else len(text)
            section = text[start:end]

            changes_m = re.search(
                r"###?\s*Changes.*?\n(.*?)(?=###?\s*Upgraded|```)",
                section, re.DOTALL | re.IGNORECASE,
            )
            changes = changes_m.group(1).strip() if changes_m else None

            code_blocks = re.findall(r"```\w*\n(.*?)```", section, re.DOTALL)
            code = max(code_blocks, key=len).strip() if code_blocks else None

            results[fp] = (changes, code)
        else:
            results[fp] = (None, None)

    return results


# =============================================================================
# Conversation Backends
# =============================================================================

class ConversationState:
    """Maintains the full message history for API backend.

    Uses adaptive thinking and automatic session rotation when context
    fills up — starts a fresh conversation instead of degrading quality.
    """

    # Context window: 1M for opus/sonnet, 200K for everything else
    LARGE_CONTEXT_TOKENS: Final[int] = 1_000_000
    LARGE_CONTEXT_MODELS: Final[tuple[str, ...]] = ("opus", "sonnet", "qwen3.6-plus-free")
    DEFAULT_CONTEXT_TOKENS: Final[int] = 200_000

    # Rotate session when context hits this % full
    ROTATION_THRESHOLD: Final[float] = 0.90

    def __init__(self, system_prompt: str, model: str, effort: str = "high"):
        self.system_prompt = system_prompt
        self.model = model
        self.effort = "high" if effort == "max" else effort
        self.messages: list[dict[str, str]] = []

        # Token tracking
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.last_input_tokens = 0      # Source of truth for context usage
        self.session_count = 1

        self._client: Any = None

    @property
    def context_limit(self) -> int:
        """Context window size based on model.  1M for opus/sonnet, 200K for all else."""
        if any(tag in (self.model or "") for tag in self.LARGE_CONTEXT_MODELS):
            return self.LARGE_CONTEXT_TOKENS
        return self.DEFAULT_CONTEXT_TOKENS

    @property
    def client(self) -> Any:
        if self._client is None:
            try:
                import anthropic
            except ImportError:
                log.error("Install: pip install anthropic")
                sys.exit(1)
            api_key = os.environ.get("ANTHROPIC_API_KEY")
            if not api_key:
                log.error("Set ANTHROPIC_API_KEY environment variable.")
                sys.exit(1)
            self._client = anthropic.Anthropic(api_key=api_key)
        return self._client

    def send(self, user_message: str, max_tokens: int = 128000, **kwargs: Any) -> str:
        self.messages.append({"role": "user", "content": user_message})

        # Check if we need to rotate BEFORE sending (based on last call's input tokens)
        if self._should_rotate():
            self._rotate_session()

        log.info(
            "    API call (model=%s, effort=%s, %d messages, session #%d) ...",
            self.model, self.effort, len(self.messages), self.session_count,
        )

        response = self.client.messages.create(
            model=self.model,
            max_tokens=max_tokens,
            system=self.system_prompt,
            messages=self.messages,
            thinking={"type": "adaptive", "effort": self.effort},
        )

        # Extract text, skipping thinking blocks
        text = ""
        for block in response.content:
            if block.type == "text":
                text += block.text

        self.messages.append({"role": "assistant", "content": text})

        # Track tokens — input_tokens IS the context usage (entire history)
        self.last_input_tokens = response.usage.input_tokens
        self.total_input_tokens += response.usage.input_tokens
        self.total_output_tokens += response.usage.output_tokens

        pct = (self.last_input_tokens / self.context_limit) * 100
        log.info(
            "    Context: %s / %s tokens (%.0f%%)",
            f"{self.last_input_tokens:,}",
            f"{self.context_limit:,}",
            pct,
        )

        return text

    def _should_rotate(self) -> bool:
        """Check if context usage warrants starting a fresh session."""
        if self.last_input_tokens == 0:
            return False  # First call, no data yet
        return self.last_input_tokens >= self.context_limit * self.ROTATION_THRESHOLD

    def _rotate_session(self) -> None:
        """Start a fresh conversation, preserving only cumulative stats."""
        old_count = len(self.messages)
        old_pct = (self.last_input_tokens / self.context_limit) * 100

        self.messages.clear()
        self.last_input_tokens = 0
        self.session_count += 1

        log.warning(
            "    ⟳ SESSION ROTATED → #%d (was %.0f%% full, %d messages cleared). "
            "New session starts with fresh context + system prompt.",
            self.session_count, old_pct, old_count,
        )

    def parse_single(self, raw: str) -> tuple[str | None, str | None, list, list]:
        """Parse a single-file response (API always uses markdown format)."""
        changes, code = parse_single_response(raw)
        return changes, code, [], []

    def parse_batch(
        self, raw: str, files: list[Path], project_root: Path,
    ) -> dict[Path, tuple[str | None, str | None, list, list]]:
        """Parse a batch response (API always uses markdown format)."""
        parsed = parse_batch_response(raw, files, project_root)
        return {fp: (changes, code, [], []) for fp, (changes, code) in parsed.items()}

    @property
    def token_usage_str(self) -> str:
        total = self.total_input_tokens + self.total_output_tokens
        pct = (self.last_input_tokens / self.context_limit * 100) if self.last_input_tokens else 0
        parts = [
            f"Tokens: {total:,} (in: {self.total_input_tokens:,}, out: {self.total_output_tokens:,})",
            f"Context: {pct:.0f}% of {self.context_limit // 1000}K",
            f"Sessions: {self.session_count}",
        ]
        return " | ".join(parts)


class CLISession:
    """Manages a persistent Claude Code CLI session using --session-id.

    Key improvements over v2 (-c flag):
      - Fixed session ID (UUID) instead of -c (continue most recent).
        -c is fragile: if someone runs `claude` manually between our calls,
        -c continues THEIR conversation.  --session-id is deterministic.
      - --bare: skips hooks, LSP, plugins, auto-memory.  ~2s faster cold start
        per call, and avoids side effects from project hooks.
      - --effort max: forces maximum reasoning depth.  Without this, Claude
        sometimes phones it in on "boring" files (config, utils).
      - --dangerously-skip-permissions: hard bypass of ALL permission checks.
        We use this instead of --permission-mode bypassPermissions because:
          1. permission-mode is a session-level setting that can be overridden
             by per-tool configs in .claude/settings.json or CLAUDE.md hooks.
          2. If ANY permission prompt fires during autonomous batch processing,
             the subprocess hangs forever (stdin is a pipe, not a terminal),
             hits the 600s timeout, and that file is lost.
          3. --tools "Read" restricts Claude to read-only anyway, so the
             permission bypass has no practical risk — Claude can't edit,
             delete, or execute anything.  WE write files after validation.
      - --fallback-model: auto-falls back to Sonnet if Opus is overloaded,
        instead of failing the entire batch.
      - --json-schema: enforces structured output so we get {changes, code}
        instead of hoping the markdown format is parseable.
      - --name: names the session for easy identification in /resume.
      - --max-budget-usd: optional budget cap for large runs.
    """

    # JSON schema for structured output — eliminates regex parsing
    OUTPUT_SCHEMA: Final[str] = json.dumps({
        "type": "object",
        "properties": {
            "skipped": {
                "type": "boolean",
                "description": "Set to true ONLY if the file is truly trivial/not improvable. If true, you can omit the code.",
            },
            "changes": {
                "type": "string",
                "description": "Bullet-point summary of changes made, or reason for skipping",
            },
            "code": {
                "type": "string",
                "description": "The complete upgraded file content",
            },
            "new_files": {
                "type": "array",
                "description": "New companion files to create (e.g. extracted types, constants, utils). Only include if genuinely useful.",
                "items": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string", "description": "Relative path from project root"},
                        "code": {"type": "string", "description": "Complete file content"},
                    },
                    "required": ["path", "code"],
                },
            },
            "deprecated_files": {
                "type": "array",
                "description": "Files that should be deleted/replaced. They will be renamed to DEPRECATED_<filename> instead of deleted.",
                "items": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string", "description": "Relative path from project root"},
                        "reason": {"type": "string", "description": "Why this file is deprecated and what replaced it"},
                    },
                    "required": ["path", "reason"],
                },
            },
        },
        "required": ["changes"],
    })

    # Batch schema — array of file results
    BATCH_OUTPUT_SCHEMA: Final[str] = json.dumps({
        "type": "object",
        "properties": {
            "files": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "path": {"type": "string"},
                        "skipped": {"type": "boolean"},
                        "changes": {"type": "string"},
                        "code": {"type": "string"},
                        "new_files": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "path": {"type": "string"},
                                    "code": {"type": "string"},
                                },
                                "required": ["path", "code"],
                            },
                        },
                        "deprecated_files": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "path": {"type": "string"},
                                    "reason": {"type": "string"},
                                },
                                "required": ["path", "reason"],
                            },
                        },
                    },
                    "required": ["path", "changes"],
                },
            },
        },
        "required": ["files"],
    })

    # Context window: 1M for opus, 200K for everything else.
    # Source of truth: input_tokens from the JSON response = actual context usage.
    LARGE_CONTEXT_TOKENS: Final[int] = 1_000_000
    DEFAULT_CONTEXT_TOKENS: Final[int] = 200_000

    # Rotate to a new session when context hits this % full
    ROTATION_THRESHOLD: Final[float] = 0.90

    # Auto-disable Read tool when context exceeds this (tokens).
    # Prevents explore from consuming the entire context window.
    EXPLORE_CONTEXT_LIMIT: Final[int] = 500_000

    # Warn (but don't rotate yet) at this threshold
    WARNING_THRESHOLD: Final[float] = 0.75

    @staticmethod
    def _resolve_claude_exe() -> tuple[str, list[str]]:
        """Find the best claude executable on this system.

        Returns (exe_path, cmd_prefix) where the full command is cmd_prefix + [exe_path, ...args].

        Priority on Windows:
        1. claude.exe from the desktop app (AppData/Roaming/Claude/claude-code/<ver>/)
        2. node.exe + cli.js — avoids cmd.exe re-parsing of JSON schema arguments
        3. Bare "claude" fallback (Unix or if nothing else found)
        """
        import shutil as _shutil
        import os as _os
        import sys as _sys

        if _sys.platform == "win32":
            # Desktop app installs claude.exe at a versioned path — find newest version
            app_base = _os.path.join(_os.environ.get("APPDATA", ""), "Claude", "claude-code")
            if _os.path.isdir(app_base):
                candidates = []
                for ver_dir in _os.listdir(app_base):
                    exe = _os.path.join(app_base, ver_dir, "claude.exe")
                    if _os.path.isfile(exe):
                        candidates.append((ver_dir, exe))
                if candidates:
                    candidates.sort(key=lambda x: x[0], reverse=True)
                    return candidates[0][1], []

            # npm/pnpm install: .cmd wrappers can't be called directly via CreateProcess
            # and cmd /c mangles JSON in --json-schema.
            # Instead, find node.exe and call cli.js directly — same as what .cmd does.
            node_exe = _shutil.which("node")
            npm_prefix = _os.path.join(_os.environ.get("APPDATA", ""), "npm")
            cli_js = _os.path.join(npm_prefix, "node_modules", "@anthropic-ai", "claude-code", "cli.js")
            if node_exe and _os.path.isfile(cli_js):
                return cli_js, [node_exe]

        # Unix / fallback
        return _shutil.which("claude") or "claude", []

    def __init__(
        self,
        system_prompt_file: str,
        project_dir: str,
        model: str | None = None,
        fallback_model: str | None = None,
        planning_model: str | None = None,
        max_budget_usd: float | None = None,
        effort: str = "max",
        use_json_schema: bool = True,
        no_persist: bool = False,
        max_reads: int = 5,
    ):
        import uuid as _uuid

        self.system_prompt_file = system_prompt_file
        self.project_dir = project_dir
        self.model = model
        self.fallback_model = fallback_model
        self.max_reads = max_reads
        self.planning_model = planning_model
        self.max_budget_usd = max_budget_usd
        self.effort = effort
        self.use_json_schema = use_json_schema
        self.no_persist = no_persist

        # Resolve the claude executable.
        # On Windows, prefer claude.exe from the desktop app install over the
        # npm/pnpm .cmd wrappers — .exe runs directly without cmd.exe /c.
        self._claude_exe, self._claude_prefix = self._resolve_claude_exe()

        # Fixed session ID for the entire run — deterministic continuation
        self.session_id = str(_uuid.uuid4())
        self.actual_session_id: str | None = None   # Real ID returned by CLI after first call
        self.session_started = False
        self.call_count = 0

        # Token tracking — extracted from --output-format json responses
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.total_cost_usd = 0.0
        self.last_input_tokens = 0      # Most recent call's input (= current context size)
        self.last_duration_ms = 0
        self.session_count = 1          # Incremented on each rotation

        # Session name includes project dir + timestamp for identification
        project_name = Path(project_dir).name
        timestamp = datetime.now().strftime("%H:%M")
        self.session_name = f"upgrader: {project_name} @ {timestamp}"

        log.info("CLI session ID: %s", self.session_id)
        log.info("CLI session name: %s", self.session_name)

    def send(
        self,
        prompt: str,
        max_turns: int = 5,
        max_tokens: int = 128000,
        *,
        is_batch: bool = False,
        planning: bool = False,   # True = high effort planning pass; False = normal/low execution
        explore: bool = False,    # True = give agent Read tool; False = no tools (text only)
    ) -> str:
        """Send a prompt and return the response.

        Always uses --output-format json internally to extract usage metadata.
        The actual content is extracted from the JSON wrapper before returning.

        Automatically rotates to a new session when context reaches 90% full
        (based on input_tokens from the previous call — the actual context size).
        """
        # Check if we need to rotate BEFORE sending
        if self._should_rotate():
            self._rotate_session()

        # Choose effort level: planning pass uses high, execution pass uses configured effort.
        # "max" effort is Opus-only; cap at "high" for all other models.
        active_model = self.planning_model if (planning and self.planning_model) else self.model
        if planning:
            effort = "high"
        elif self.effort == "max" and not (active_model and "opus" in active_model):
            effort = "high"  # "max" is Opus-only, cap Sonnet/others at "high"
        else:
            effort = self.effort
        cmd = self._claude_prefix + [
            self._claude_exe,
            "-p",                                       # Print mode (non-interactive)
            "--dangerously-skip-permissions",            # Hard bypass ALL permission checks
            "--effort", effort,
        ]

        # Context-based cutoff: if context already exceeds EXPLORE_CONTEXT_LIMIT,
        # revoke explore even if requested to prevent runaway context growth.
        if explore and self.last_input_tokens >= self.EXPLORE_CONTEXT_LIMIT:
            log.info("    Context %dk > %dk — explore disabled for this call",
                     self.last_input_tokens // 1000, self.EXPLORE_CONTEXT_LIMIT // 1000)
            explore = False

        # --max-turns limits the agentic loop (each tool call = 1 turn).
        # Only applied when explore is on to cap file reads.
        # When explore is off, no limit — trust the agent to follow prompt instructions.
        if explore:
            cmd.extend(["--max-turns", str(self.max_reads + 1)])

        if self.no_persist:
            cmd.extend(["--no-session-persistence"])
        elif not self.session_started:
            # First call: create the session with our generated ID
            cmd.extend(["--session-id", self.session_id])
        else:
            # Subsequent calls: resume the ACTUAL session ID returned by CLI.
            # --resume <id> is more reliable than -c (which picks up any recent session).
            resume_id = self.actual_session_id or self.session_id
            cmd.extend(["--resume", resume_id])

        if not self.session_started or self.no_persist:
            cmd.extend(["--system-prompt-file", self.system_prompt_file])
            if not self.no_persist:
                cmd.extend(["--name", self.session_name])

        # Use planning model for planning passes (hybrid mode), otherwise default model
        if active_model:
            cmd.extend(["--model", active_model])

        if self.fallback_model:
            cmd.extend(["--fallback-model", self.fallback_model])

        if self.max_budget_usd:
            cmd.extend(["--max-budget-usd", str(self.max_budget_usd)])

        # Always use JSON output to get usage metadata.
        cmd.extend(["--output-format", "json"])
        if self.use_json_schema:
            schema = self.BATCH_OUTPUT_SCHEMA if is_batch else self.OUTPUT_SCHEMA
            cmd.extend(["--json-schema", schema])

        self.call_count += 1
        log.info(
            "    CLI call #%d (session=%s…) ...",
            self.call_count, self.session_id[:8],
        )
        log.debug("    cmd: %s", " ".join(cmd[:10]) + " ...")

        # Use Popen so we can capture partial stdout even on timeout
        proc = subprocess.Popen(
            cmd,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            cwd=self.project_dir,
            encoding="utf-8",
            errors="replace",
        )
        try:
            raw_stdout, raw_stderr = proc.communicate(input=prompt, timeout=1200)
        except subprocess.TimeoutExpired:
            proc.kill()
            raw_stdout, raw_stderr = proc.communicate()
            log.error("    CLI call timed out after 1200s — partial output: %d chars", len(raw_stdout))
            if raw_stdout.strip():
                # Save whatever the model managed to produce before the timeout
                from pathlib import Path as _Path
                debug_dir = _Path(self.project_dir) / ".upgrade-debug"
                debug_dir.mkdir(exist_ok=True)
                (_Path(self.project_dir) / ".upgrade-debug" / f"timeout_call{self.call_count}_raw.txt").write_text(
                    raw_stdout, encoding="utf-8"
                )
                log.warning("    Partial output saved to .upgrade-debug/timeout_call%d_raw.txt", self.call_count)
            if not self.session_started:
                self._regenerate_session_id()
            return ""

        if proc.returncode != 0:
            stderr = raw_stderr[:500]
            log.error(
                "    CLI error (rc=%d): %s",
                proc.returncode, stderr,
            )
            if "already in use" in stderr and not self.session_started:
                log.info("    Switching to --resume for existing session")
                self.session_started = True
                self.actual_session_id = self.session_id
            return ""

        # Mark session as started only after a successful call
        self.session_started = True

        # Parse the JSON wrapper to extract usage metadata + content
        return self._extract_response(raw_stdout)

    def _extract_response(self, raw_stdout: str) -> str:
        """Extract content and usage metadata from JSON output.

        The CLI with --output-format json returns something like:
            {
              "type": "result",
              "result": "...",          ← the actual content
              "session_id": "...",
              "cost_usd": 0.05,
              "duration_ms": 1234,
              "usage": {
                "input_tokens": 50000,
                "output_tokens": 3000
              }
            }

        We extract usage for tracking and return the content string.
        If --json-schema was active, the "result" field contains
        structured JSON that the parse_single/parse_batch methods handle.
        """
        if not raw_stdout or not raw_stdout.strip():
            return ""

        try:
            data = json.loads(raw_stdout)
        except json.JSONDecodeError:
            # Not JSON — return raw (shouldn't happen with --output-format json)
            log.debug("    Response is not JSON, returning raw")
            return raw_stdout

        # Extract usage metadata
        usage = data.get("usage") or {}
        input_tokens = usage.get("input_tokens", 0)
        cache_creation = usage.get("cache_creation_input_tokens", 0)
        cache_read = usage.get("cache_read_input_tokens", 0)
        # Total context = non-cached + newly cached + cache-hit tokens
        context_tokens = input_tokens + cache_creation + cache_read
        output_tokens = usage.get("output_tokens", 0)
        cost = data.get("cost_usd", 0.0)
        duration = data.get("duration_ms", 0)

        self.total_input_tokens += context_tokens
        self.total_output_tokens += output_tokens
        self.total_cost_usd += cost
        self.last_input_tokens = context_tokens
        self.last_duration_ms = duration

        # Log usage for this call
        if context_tokens or output_tokens:
            log.info(
                "    Tokens: %s in / %s out (cost: $%.4f, %dms)",
                f"{context_tokens:,}", f"{output_tokens:,}",
                cost, duration,
            )

        # Log tool usage (num_turns > 1 means the agent used tools)
        num_turns = data.get("num_turns", 1)
        if num_turns > 1:
            log.info("    Agent used %d tool calls before responding", num_turns - 1)

        # Capture the actual session ID returned so we can use --resume precisely
        returned_session_id = data.get("session_id")
        if returned_session_id and not self.actual_session_id:
            self.actual_session_id = returned_session_id
            log.debug("    Captured CLI session_id: %s...", returned_session_id[:8])

        # Log context utilization and warn if approaching rotation
        self._log_context_status(context_tokens)

        # Extract the actual content.
        # When --json-schema is used, Claude CLI 2.x places the structured
        # response in `structured_output`, not `result`.
        # When plain text mode, it's in `result`.
        if self.use_json_schema:
            content = data.get("structured_output") or data.get("result") or ""
        else:
            content = data.get("result") or data.get("structured_output") or ""

        if not content:
            subtype = data.get("subtype", "")
            stop_reason = data.get("stop_reason", "")
            if subtype == "error_max_turns":
                log.warning(
                    "    Hit max-turns limit (agent used tools instead of responding). "
                    "stop_reason=%s", stop_reason,
                )
            else:
                log.warning(
                    "    Empty content! subtype=%s stop_reason=%s keys=%s",
                    subtype, stop_reason, list(data.keys()),
                )
            # Save raw response to debug dir for inspection
            import tempfile
            debug_path = Path(self.project_dir) / ".upgrade-debug" / f"raw_response_{self.call_count}.json"
            debug_path.parent.mkdir(exist_ok=True)
            debug_path.write_text(raw_stdout[:8000], encoding="utf-8")
            log.warning("    Raw response saved to: %s", debug_path)
            return ""

        if isinstance(content, str):
            return content
        # If result is already a dict/list (some CLI versions), re-serialize
        return json.dumps(content)

    # Models with 1M context windows
    LARGE_CONTEXT_MODELS: Final[tuple[str, ...]] = ("opus", "sonnet", "qwen3.6-plus-free")

    @property
    def context_limit(self) -> int:
        """Context window size.  1M for opus/sonnet, 200K for everything else.

        In hybrid mode the planning model may have a larger window than the
        execution model.  We use the *largest* window among models in play
        because the CLI automatically compresses/truncates context to fit
        each model's limit per call — rotation is about when to start fresh
        to keep quality high, and the biggest window sets that ceiling.
        """
        models = [m for m in (self.model, self.planning_model) if m]
        if any(tag in m for m in models for tag in self.LARGE_CONTEXT_MODELS):
            return self.LARGE_CONTEXT_TOKENS
        return self.DEFAULT_CONTEXT_TOKENS

    def _regenerate_session_id(self) -> None:
        """Generate a fresh session ID after a tainted one (e.g. timeout)."""
        import uuid as _uuid
        old = self.session_id[:8]
        self.session_id = str(_uuid.uuid4())
        self.actual_session_id = None
        log.info("    Session ID regenerated (%s… → %s…)", old, self.session_id[:8])

    def _should_rotate(self) -> bool:
        """Check if context usage warrants starting a new session."""
        if self.last_input_tokens == 0 or self.no_persist:
            return False  # No data yet, or stateless mode (every call is fresh)
        return self.last_input_tokens >= self.context_limit * self.ROTATION_THRESHOLD

    def _rotate_session(self) -> None:
        """Start a new CLI session with a fresh context window.

        Generates a new session ID so the next call creates a new conversation.
        The system prompt will be re-sent automatically (session_started resets).
        Cross-file context is lost, but the system prompt carries the patterns.
        """
        import uuid as _uuid

        old_id = self.session_id[:8]
        old_pct = (self.last_input_tokens / self.context_limit) * 100

        self.session_id = str(_uuid.uuid4())
        self.session_started = False
        self.last_input_tokens = 0
        self.session_count += 1

        # Update session name with new timestamp
        project_name = Path(self.project_dir).name
        timestamp = datetime.now().strftime("%H:%M")
        self.session_name = f"upgrader: {project_name} #{self.session_count} @ {timestamp}"

        log.warning(
            "    ⟳ SESSION ROTATED → #%d (was %.0f%% full, old=%s…, new=%s…). "
            "New session starts with fresh context.",
            self.session_count, old_pct, old_id, self.session_id[:8],
        )

    def _log_context_status(self, input_tokens: int) -> None:
        """Log context utilization after each call."""
        limit = self.context_limit
        if not input_tokens:
            return

        pct = (input_tokens / limit) * 100
        log.info(
            "    Context: %s / %s tokens (%.0f%%)",
            f"{input_tokens:,}", f"{limit:,}", pct,
        )

        if pct >= self.ROTATION_THRESHOLD * 100:
            log.warning(
                "    ⚠ Context %.0f%% full — will rotate on next call",
                pct,
            )
        elif pct >= self.WARNING_THRESHOLD * 100:
            log.warning(
                "    Context %.0f%% full — approaching rotation threshold",
                pct,
            )

    @property
    def token_usage_str(self) -> str:
        total = self.total_input_tokens + self.total_output_tokens
        limit = self.context_limit
        pct = (self.last_input_tokens / limit * 100) if self.last_input_tokens else 0
        parts = [
            f"Tokens: {total:,} (in: {self.total_input_tokens:,}, out: {self.total_output_tokens:,})",
        ]
        if self.total_cost_usd > 0:
            parts.append(f"Cost: ${self.total_cost_usd:.4f}")
        parts.append(f"Context: {pct:.0f}% of {limit // 1000}K")
        parts.append(f"Sessions: {self.session_count}")
        return " | ".join(parts)

    def parse_single(self, raw: str) -> tuple[str | None, str | None, list, list]:
        """Parse a single-file response.

        Returns (changes, code, new_files, deprecated_files).
        new_files = [{path, code}, ...]
        deprecated_files = [{path, reason}, ...]
        """
        if not raw:
            return None, None, [], []

        if self.use_json_schema:
            return self._parse_json_single(raw)

        # Fallback: markdown regex — no new_files/deprecated_files in this mode
        changes, code = parse_single_response(raw)
        return changes, code, [], []

    def parse_batch(
        self, raw: str, files: list[Path], project_root: Path,
    ) -> dict[Path, tuple[str | None, str | None]]:
        """Parse a batch response."""
        if not raw:
            return {fp: (None, None) for fp in files}

        if self.use_json_schema:
            return self._parse_json_batch(raw, files, project_root)

        return parse_batch_response(raw, files, project_root)

    @staticmethod
    def _parse_json_single(raw: str | dict) -> tuple[str | None, str | None, list, list]:
        """Parse structured JSON response for a single file.

        Returns (changes, code, new_files, deprecated_files).
        `raw` may be a JSON string or a dict (structured_output from CLI 2.x).
        """
        try:
            if isinstance(raw, dict):
                data = raw
            else:
                data = json.loads(raw)
                if "result" in data and isinstance(data["result"], (dict, str)):
                    inner = data["result"]
                    data = json.loads(inner) if isinstance(inner, str) else inner
                elif "structured_output" in data and isinstance(data["structured_output"], dict):
                    data = data["structured_output"]

            skipped = data.get("skipped", False)
            changes = data.get("changes")
            code = data.get("code")
            new_files = data.get("new_files") or []
            deprecated_files = data.get("deprecated_files") or []

            if skipped or code == "<SKIP>":
                code = "<SKIP>"

            return changes, code, new_files, deprecated_files
        except (json.JSONDecodeError, TypeError, KeyError) as e:
            log.warning("    JSON parse failed, falling back to regex: %s", e)
            changes, code = parse_single_response(raw if isinstance(raw, str) else json.dumps(raw))
            return changes, code, [], []

    @staticmethod
    def _parse_json_batch(
        raw: str, files: list[Path], project_root: Path,
    ) -> dict[Path, tuple[str | None, str | None, list, list]]:
        """Parse structured JSON batch response.

        Returns mapping of Path -> (changes, code, new_files, deprecated_files).
        """
        try:
            data = json.loads(raw) if isinstance(raw, str) else raw
            if "result" in data:
                data = json.loads(data["result"]) if isinstance(data["result"], str) else data["result"]
            if "structured_output" in data and isinstance(data["structured_output"], dict):
                data = data["structured_output"]

            file_results = data.get("files", [])

            # Build a lookup by path
            path_map: dict[str, dict[str, Any]] = {}
            for entry in file_results:
                p = entry.get("path", "")
                path_map[p] = entry
                path_map[Path(p).name] = entry

            results: dict[Path, tuple[str | None, str | None, list, list]] = {}
            for fp in files:
                rel = fp.relative_to(project_root).as_posix()
                fname = fp.name

                entry = path_map.get(rel) or path_map.get(fname)
                if entry:
                    skipped = entry.get("skipped", False)
                    changes = entry.get("changes")
                    code = entry.get("code")
                    new_files = entry.get("new_files") or []
                    deprecated_files = entry.get("deprecated_files") or []
                    if skipped or code == "<SKIP>":
                        code = "<SKIP>"
                    results[fp] = (changes, code, new_files, deprecated_files)
                else:
                    results[fp] = (None, None, [], [])

            return results
        except (json.JSONDecodeError, TypeError, KeyError) as e:
            log.warning("    JSON batch parse failed, falling back to regex: %s", e)
            return parse_batch_response(raw, files, project_root)


# =============================================================================
# OpenCode CLI Backend
# =============================================================================

class OpenCodeSession:
    """Manages a persistent OpenCode session using `opencode run --format json`.

    OpenCode differences from Claude Code CLI:
      - Command: `opencode run` (not `claude -p`)
      - Output: JSONL event stream (one JSON object per line), not a single JSON wrapper
      - No --json-schema flag — responses are free-form text, parsed via regex
      - No --dangerously-skip-permissions — `opencode run` auto-approves by default
      - No --fallback-model — retry logic handles overloads
      - No --max-budget-usd — no budget capping
      - --variant flag available for reasoning effort (low/medium/high/max)
      - Session persistence via --continue/-c and --session/-s
      - Model format: provider/model (e.g. anthropic/claude-sonnet-4-20250514)

    JSONL event types we care about:
      text:         {"type":"text","sessionID":"ses_xxx","part":{"type":"text","text":"..."}}
      step_finish:  {"type":"step_finish","sessionID":"ses_xxx","part":{"reason":"stop","cost":0.001,"tokens":{"input":671,"output":8,"cache":{"read":21415,"write":0}}}}
      error:        {"type":"error","sessionID":"ses_xxx","error":{"name":"APIError","data":{"message":"..."}}}
    """

    def __init__(
        self,
        system_prompt_file: str,
        project_dir: str,
        model: str | None = None,
        planning_model: str | None = None,
        effort: str = "high",
        max_reads: int = 5,
    ):
        import shutil as _shutil

        self.system_prompt_file = system_prompt_file
        self.project_dir = project_dir
        self.model = model
        self.planning_model = planning_model
        self.max_reads = max_reads
        self.effort = effort

        # Resolve opencode executable
        self._opencode_exe = _shutil.which("opencode") or "opencode"

        # Session tracking
        self.session_id: str | None = None
        self.call_count = 0

        # Token tracking
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.total_cost_usd = 0.0
        self.last_input_tokens = 0
        self.last_duration_ms = 0
        self.session_count = 1

        log.info("OpenCode session initialized (exe: %s)", self._opencode_exe)
        if model:
            log.info("OpenCode model: %s", model)

    def send(
        self,
        prompt: str,
        max_turns: int = 5,
        max_tokens: int = 128000,
        *,
        is_batch: bool = False,
        planning: bool = False,
        explore: bool = False,
    ) -> str:
        """Send a prompt via `opencode run` and return the response.

        Parses JSONL event stream to extract text content and usage metadata.
        """
        active_model = self.planning_model if (planning and self.planning_model) else self.model

        cmd = [self._opencode_exe, "run"]

        if active_model:
            cmd.extend(["-m", active_model])

        if self.session_id:
            cmd.extend(["-c"])  # continue last session

        if explore:
            # OpenCode doesn't have --max-turns on `run`, but we can limit via agent config.
            # For now, just let it run — the prompt instructs limited reads.
            pass

        # --variant maps to provider-specific reasoning effort
        effort_map = {"low": "minimal", "medium": "low", "high": "high", "max": "max"}
        variant = effort_map.get(self.effort, "high")
        if planning:
            variant = "high"
        cmd.extend(["--variant", variant])

        cmd.extend(["--format", "json"])

        self.call_count += 1
        log.info("    OpenCode call #%d ...", self.call_count)
        log.debug("    cmd: %s", " ".join(cmd[:8]) + " ...")

        proc = subprocess.Popen(
            cmd,
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            cwd=self.project_dir,
            encoding="utf-8",
            errors="replace",
        )
        try:
            raw_stdout, raw_stderr = proc.communicate(input=prompt, timeout=1200)
        except subprocess.TimeoutExpired:
            proc.kill()
            raw_stdout, raw_stderr = proc.communicate()
            log.error("    OpenCode call timed out after 1200s — partial output: %d chars", len(raw_stdout))
            if raw_stdout.strip():
                debug_dir = Path(self.project_dir) / ".upgrade-debug"
                debug_dir.mkdir(exist_ok=True)
                (debug_dir / f"timeout_call{self.call_count}_raw.txt").write_text(
                    raw_stdout, encoding="utf-8"
                )
                log.warning("    Partial output saved to .upgrade-debug/timeout_call%d_raw.txt", self.call_count)
            self.session_id = None  # Force fresh session after timeout
            return ""

        if proc.returncode != 0:
            stderr = raw_stderr[:500]
            log.error("    OpenCode error (rc=%d): %s", proc.returncode, stderr)
            return ""

        return self._extract_response(raw_stdout)

    def _extract_response(self, raw_stdout: str) -> str:
        """Parse JSONL event stream from OpenCode.

        Each line is a separate JSON event:
          text         → accumulate part.text into result
          step_finish  → extract session_id, tokens, cost
          error        → mark failure
        """
        if not raw_stdout or not raw_stdout.strip():
            return ""

        result_text = ""
        session_id = None

        for line in raw_stdout.splitlines():
            line = line.strip()
            if not line:
                continue
            try:
                event = json.loads(line)
            except json.JSONDecodeError:
                continue

            event_type = event.get("type")

            if event_type == "text":
                result_text += event.get("part", {}).get("text", "")

            elif event_type == "step_finish":
                session_id = event.get("sessionID")
                tokens = event.get("part", {}).get("tokens", {})
                input_t = tokens.get("input", 0)
                output_t = tokens.get("output", 0)
                cache = tokens.get("cache", {})
                cache_read = cache.get("read", 0)
                cache_write = cache.get("write", 0)
                context_tokens = input_t + cache_read + cache_write

                self.total_input_tokens += context_tokens
                self.total_output_tokens += output_t
                self.last_input_tokens = context_tokens
                self.last_duration_ms = event.get("part", {}).get("duration_ms", 0)

                cost = event.get("part", {}).get("cost", 0.0)
                self.total_cost_usd += cost

                if context_tokens or output_t:
                    log.info(
                        "    Tokens: %s in / %s out (cost: $%.4f)",
                        f"{context_tokens:,}", f"{output_t:,}", cost,
                    )

            elif event_type == "error":
                err_data = event.get("error", {}).get("data", {})
                err_msg = err_data.get("message", "Unknown error")
                err_name = event.get("error", {}).get("name", "Unknown")
                log.error("    OpenCode error: [%s] %s", err_name, err_msg)
                # Still return any text we accumulated before the error
                if result_text:
                    log.warning("    Returning partial text (%d chars) despite error", len(result_text))
                    return result_text
                return ""

        # Capture session ID for continuation
        if session_id and not self.session_id:
            self.session_id = session_id
            log.debug("    Captured OpenCode session_id: %s", session_id[:15])

        return result_text

    @property
    def context_limit(self) -> int:
        """Estimate context window. OpenCode doesn't expose this per-model,
        so we use a conservative 200K default."""
        return 200_000

    @property
    def token_usage_str(self) -> str:
        total = self.total_input_tokens + self.total_output_tokens
        limit = self.context_limit
        pct = (self.last_input_tokens / limit * 100) if self.last_input_tokens else 0
        parts = [
            f"Tokens: {total:,} (in: {self.total_input_tokens:,}, out: {self.total_output_tokens:,})",
        ]
        if self.total_cost_usd > 0:
            parts.append(f"Cost: ${self.total_cost_usd:.4f}")
        parts.append(f"Context: {pct:.0f}% of {limit // 1000}K")
        parts.append(f"Sessions: {self.session_count}")
        return " | ".join(parts)

    def parse_single(self, raw: str) -> tuple[str | None, str | None, list, list]:
        """Parse a single-file response (always regex — no JSON schema in OpenCode)."""
        if not raw:
            return None, None, [], []
        changes, code = parse_single_response(raw)
        return changes, code, [], []

    def parse_batch(
        self, raw: str, files: list[Path], project_root: Path,
    ) -> dict[Path, tuple[str | None, str | None]]:
        """Parse a batch response (always regex)."""
        if not raw:
            return {fp: (None, None) for fp in files}
        return parse_batch_response(raw, files, project_root)


# =============================================================================
# Git Operations
# =============================================================================

def git_is_repo(project_root: Path) -> bool:
    """Check if the directory is inside a git repository."""
    try:
        subprocess.run(
            ["git", "rev-parse", "--is-inside-work-tree"],
            cwd=str(project_root), check=True,
            capture_output=True, text=True,
        )
        return True
    except (subprocess.CalledProcessError, FileNotFoundError):
        return False


def git_current_branch(project_root: Path) -> str:
    """Get the name of the current git branch."""
    result = subprocess.run(
        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
        cwd=str(project_root), capture_output=True, text=True,
    )
    return result.stdout.strip() if result.returncode == 0 else "unknown"


def git_has_clean_tree(project_root: Path) -> bool:
    """Check if the working tree is clean (no uncommitted changes)."""
    result = subprocess.run(
        ["git", "status", "--porcelain"],
        cwd=str(project_root), capture_output=True, text=True,
    )
    return result.returncode == 0 and not result.stdout.strip()


def git_setup_branch(
    project_root: Path,
    branch_name: str | None = None,
    from_branch: str | None = None,
) -> tuple[str, str]:
    """Create and checkout an upgrade branch.

    Args:
        project_root: Repository root.
        branch_name: Branch name (auto-generated if None).
        from_branch: Branch to create from (defaults to current HEAD).

    Returns:
        (original_branch, new_branch) — so we can switch back later.

    Raises:
        RuntimeError: If branch creation fails.
    """
    original = git_current_branch(project_root)

    if branch_name is None:
        timestamp = datetime.now().strftime("%Y%m%d-%H%M")
        branch_name = f"upgrade/enterprise-{timestamp}"

    try:
        # If from_branch specified, create from that branch instead of HEAD
        if from_branch:
            # Fetch to ensure we have latest
            subprocess.run(
                ["git", "fetch", "origin", from_branch],
                cwd=str(project_root), capture_output=True, text=True,
            )
            subprocess.run(
                ["git", "checkout", "-b", branch_name, f"origin/{from_branch}"],
                cwd=str(project_root), check=True,
                capture_output=True, text=True,
            )
            log.info("Created branch: %s (from origin/%s)", branch_name, from_branch)
        else:
            # Create and checkout new branch from current HEAD
            subprocess.run(
                ["git", "checkout", "-b", branch_name],
                cwd=str(project_root), check=True,
                capture_output=True, text=True,
            )
            log.info("Created branch: %s (from %s)", branch_name, original)
        return original, branch_name

    except subprocess.CalledProcessError as exc:
        stderr = exc.stderr.strip()
        # Branch already exists — just check it out instead of failing
        if "already exists" in stderr:
            subprocess.run(
                ["git", "checkout", branch_name],
                cwd=str(project_root), check=True,
                capture_output=True, text=True,
            )
            log.info("Resumed existing branch: %s (from %s)", branch_name, original)
            return original, branch_name
        raise RuntimeError(f"Failed to create branch '{branch_name}': {stderr}")


def git_commit_batch(
    project_root: Path, files: list[Path], message: str,
) -> bool:
    """Stage files and commit."""
    try:
        for fp in files:
            subprocess.run(
                ["git", "add", fp.relative_to(project_root).as_posix()],
                cwd=str(project_root), check=True,
                capture_output=True, text=True,
            )
        subprocess.run(
            ["git", "commit", "-m", message],
            cwd=str(project_root), check=True,
            capture_output=True, text=True,
        )
        log.info("  Committed %d file(s)", len(files))
        return True
    except subprocess.CalledProcessError as exc:
        log.warning("  Git commit failed: %s", exc.stderr.strip())
        return False


def git_push_branch(project_root: Path, branch_name: str) -> bool:
    """Push the branch to origin."""
    try:
        subprocess.run(
            ["git", "push", "-u", "origin", branch_name],
            cwd=str(project_root), check=True,
            capture_output=True, text=True,
        )
        log.info("Pushed branch: %s", branch_name)
        return True
    except subprocess.CalledProcessError as exc:
        log.warning("Push failed: %s", exc.stderr.strip())
        return False


def git_switch_back(project_root: Path, original_branch: str) -> None:
    """Switch back to the original branch after completion."""
    try:
        subprocess.run(
            ["git", "checkout", original_branch],
            cwd=str(project_root), check=True,
            capture_output=True, text=True,
        )
        log.info("Switched back to: %s", original_branch)
    except subprocess.CalledProcessError as exc:
        log.warning(
            "Could not switch back to %s: %s", original_branch, exc.stderr.strip()
        )


# =============================================================================
# Core Upgrade Logic
# =============================================================================

def upgrade_single(
    file_path: Path,
    project_root: Path,
    conversation: ConversationState | CLISession | OpenCodeSession,
    state: UpgradeState,
    *,
    dry_run: bool,
    hybrid: bool,
    explore: bool = False,
    no_explore_cutoff: bool = False,
    output_dir: Path | None,
    progress: dict | None = None,
) -> tuple[bool, str | None]:
    """Upgrade one file with validation and retry.

    Returns (success, changes_summary).
    """
    rel = file_path.relative_to(project_root).as_posix()
    lang = EXTENSION_MAP.get(file_path.suffix.lower(), "")
    original_code = file_path.read_text(encoding="utf-8", errors="replace")
    original_lines = len(original_code.splitlines())

    log.info("  Upgrading: %s (%d lines)", rel, original_lines)

    last_error: str | None = None
    saved_plan: str | None = None  # Reused across retries in hybrid mode

    for attempt in range(MAX_UPGRADE_RETRIES + 1):
        start = time.time()
        
        if hybrid:
            if attempt == 0:
                log.info("    [Hybrid] Pass 1: Planning (high effort)")
                mr = getattr(conversation, 'max_reads', 5)
                ctx = getattr(conversation, 'last_input_tokens', 0)
                ctx_limit = getattr(conversation, 'context_limit', 1_000_000)
                cutoff = 999_999_999 if no_explore_cutoff else getattr(conversation, 'EXPLORE_CONTEXT_LIMIT', 500_000)
                plan_prompt = build_plan_prompt(
                    file_path, project_root, explore=explore, max_reads=mr,
                    context_tokens=ctx, context_limit=ctx_limit, explore_cutoff=cutoff,
                )
                plan = conversation.send(plan_prompt, planning=True, explore=explore)
                if not plan:
                    last_error = "Failed to generate plan"
                    continue
                # For debug tracking
                _save_debug(project_root, file_path, "=== HYBRID PLAN ===\n" + plan)
                
                # Show actual effort (send() will cap "max" to "high" for non-opus)
                model = getattr(conversation, 'model', '') or ''
                cfg_effort = getattr(conversation, 'effort', 'max')
                actual_effort = "high" if cfg_effort == "max" and "opus" not in model else cfg_effort
                log.info("    [Hybrid] Pass 2: Executing (%s effort)", actual_effort)
                # Save plan for retries so we don't re-plan on execution failure
                saved_plan = plan
                prompt = build_execute_prompt(file_path, project_root, plan)
            else:
                log.info("    Retry %d/%d for %s: %s", attempt, MAX_UPGRADE_RETRIES, rel, last_error)
                # Reuse the original plan — don't waste a planning call
                prompt = build_execute_prompt(file_path, project_root, saved_plan, error=last_error or "Unknown error")

            raw = conversation.send(prompt, planning=False)
        else:
            if attempt == 0:
                mr = getattr(conversation, 'max_reads', 5)
                ctx = getattr(conversation, 'last_input_tokens', 0)
                ctx_limit = getattr(conversation, 'context_limit', 1_000_000)
                cutoff = 999_999_999 if no_explore_cutoff else getattr(conversation, 'EXPLORE_CONTEXT_LIMIT', 500_000)
                prompt = build_single_prompt(
                    file_path, project_root, explore=explore, max_reads=mr,
                    context_tokens=ctx, context_limit=ctx_limit, explore_cutoff=cutoff,
                )
            else:
                log.info("    Retry %d/%d for %s: %s", attempt, MAX_UPGRADE_RETRIES, rel, last_error)
                prompt = build_retry_prompt(file_path, project_root, last_error or "Unknown error")
            raw = conversation.send(prompt, planning=False, explore=(explore and attempt == 0))

        # Update progress tracker for abort cleanup
        if progress is not None:
            progress["raw"] = raw
            progress["attempt"] = attempt

        elapsed = time.time() - start
        log.info("    Response in %.1fs (%d chars)", elapsed, len(raw))

        if not raw:
            last_error = "Empty response from AI"
            if progress is not None:
                progress["error"] = last_error
            continue

        changes, code, new_files, deprecated_files = conversation.parse_single(raw)

        if code == "<SKIP>":
            log.info("    Skipped by AI: %s", changes or "trivial/unimprovable")
            state.mark_completed(rel, f"Skipped: {changes or 'trivial'}", original_lines, original_lines)
            state.save(project_root)
            return True, f"Skipped: {changes or 'trivial'}"

        if not code:
            # Check if the AI says the file is already upgraded / no changes needed
            skip_indicators = [
                "already enterprise", "no changes needed", "already upgrad",
                "already enterprise-grade", "nothing to change", "already at",
                "meets all the criteria", "requires no further", "is already",
            ]
            is_short = len(raw) <= 2000
            has_skip_text = any(indicator in raw.lower() for indicator in skip_indicators)
            if is_short and has_skip_text:
                log.info("    AI says file is already upgraded: %s (%d chars, short=%s, skip_text=%s)", rel, len(raw), is_short, has_skip_text)
                state.mark_completed(rel, "Already enterprise-grade (AI confirmed)", original_lines, original_lines)
                state.save(project_root)
                return True, "Already enterprise-grade"

            last_error = "Could not extract code block from response"
            if progress is not None:
                progress["error"] = last_error
            _save_debug(project_root, file_path, raw)
            continue

        # Sanity check output size
        ok, err = _check_output_sanity(original_code, code, rel)
        if not ok:
            last_error = err
            if progress is not None:
                progress["error"] = last_error
            log.warning("    Sanity check failed: %s", err)
            continue

        # Syntax validation
        ok, err = SyntaxValidator.validate(code, lang, rel)
        if not ok:
            last_error = f"Syntax error in upgraded code: {err}"
            if progress is not None:
                progress["error"] = last_error
            log.warning("    %s", last_error)
            continue

        # All checks passed — write the file
        upgraded_lines = len(code.splitlines())

        # Always persist the raw response so content can be recovered manually
        _save_debug(project_root, file_path, raw)

        if dry_run:
            dest = (output_dir or project_root / "upgraded") / file_path.relative_to(project_root)
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_text(code, encoding="utf-8")
            log.info("    Saved (dry-run): %s", dest)
        else:
            file_path.write_text(code, encoding="utf-8")
            log.info("    Overwritten: %s (%d → %d lines)", rel, original_lines, upgraded_lines)

        # Handle new files the AI wants to create
        _apply_new_files(new_files, project_root, dry_run, output_dir)

        # Handle files the AI wants to deprecate
        _apply_deprecations(deprecated_files, project_root, dry_run)

        # Update state
        state.mark_completed(rel, changes, original_lines, upgraded_lines)
        state.save(project_root)

        # Save change log
        _save_changelog(project_root, rel, changes)

        return True, changes

    # All retries exhausted
    log.error("    FAILED after %d attempts: %s — %s", MAX_UPGRADE_RETRIES + 1, rel, last_error)
    state.mark_failed(rel, last_error or "Unknown error")
    state.save(project_root)
    _save_debug(project_root, file_path, raw if raw else "(no response)")
    return False, None


def upgrade_batch(
    files: list[Path],
    project_root: Path,
    conversation: ConversationState | CLISession | OpenCodeSession,
    state: UpgradeState,
    *,
    dry_run: bool,
    hybrid: bool,
    explore: bool = False,
    no_explore_cutoff: bool = False,
    output_dir: Path | None,
    progress: dict | None = None,
) -> list[tuple[Path, bool, str | None]]:
    """Upgrade a batch of small files. Falls back to individual on parse failure."""
    rels = [f.relative_to(project_root).as_posix() for f in files]
    log.info("  Batch: %s", ", ".join(rels))

    prompt = build_batch_prompt(files, project_root)

    start = time.time()
    raw = conversation.send(prompt, max_tokens=128000, is_batch=True)
    elapsed = time.time() - start
    log.info("    Batch response in %.1fs (%d chars)", elapsed, len(raw))

    if not raw:
        return [(fp, False, None) for fp in files]

    parsed = conversation.parse_batch(raw, files, project_root)
    results: list[tuple[Path, bool, str | None]] = []

    for fp in files:
        rel = fp.relative_to(project_root).as_posix()
        lang = EXTENSION_MAP.get(fp.suffix.lower(), "")
        original_code = fp.read_text(encoding="utf-8", errors="replace")
        changes, code, new_files, deprecated_files = parsed.get(fp, (None, None, [], []))

        if code == "<SKIP>":
            log.info("    Skipped by AI: %s (%s)", rel, changes or "trivial")
            original_lines = len(original_code.splitlines())
            state.mark_completed(rel, f"Skipped: {changes or 'trivial'}", original_lines, original_lines)
            state.save(project_root)
            results.append((fp, True, f"Skipped: {changes or 'trivial'}"))
            continue

        if not code:
            log.warning("    Could not extract %s from batch — falling back to individual", rel)
            ok, ch = upgrade_single(
                fp, project_root, conversation, state,
                dry_run=dry_run, hybrid=hybrid, explore=explore, no_explore_cutoff=no_explore_cutoff, output_dir=output_dir,
                progress=progress,
            )
            results.append((fp, ok, ch))
            continue

        # Validate
        ok, err = _check_output_sanity(original_code, code, rel)
        if not ok:
            log.warning("    Sanity check failed for %s: %s — falling back", rel, err)
            ok2, ch = upgrade_single(
                fp, project_root, conversation, state,
                dry_run=dry_run, hybrid=hybrid, explore=explore, no_explore_cutoff=no_explore_cutoff, output_dir=output_dir,
                progress=progress,
            )
            results.append((fp, ok2, ch))
            continue

        ok, err = SyntaxValidator.validate(code, lang, rel)
        if not ok:
            log.warning("    Syntax error in %s: %s — falling back", rel, err)
            ok2, ch = upgrade_single(
                fp, project_root, conversation, state,
                dry_run=dry_run, hybrid=hybrid, explore=explore, no_explore_cutoff=no_explore_cutoff, output_dir=output_dir,
                progress=progress,
            )
            results.append((fp, ok2, ch))
            continue

        # Write
        original_lines = len(original_code.splitlines())
        upgraded_lines = len(code.splitlines())

        # Always persist raw response for manual recovery
        _save_debug(project_root, fp, raw)

        if dry_run:
            dest = (output_dir or project_root / "upgraded") / fp.relative_to(project_root)
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_text(code, encoding="utf-8")
        else:
            fp.write_text(code, encoding="utf-8")

        state.mark_completed(rel, changes, original_lines, upgraded_lines)
        state.save(project_root)
        _save_changelog(project_root, rel, changes)

        # Handle new files and deprecations from batch response
        _apply_new_files(new_files, project_root, dry_run, output_dir)
        _apply_deprecations(deprecated_files, project_root, dry_run)

        results.append((fp, True, changes))
        log.info("    ✓ %s (%d → %d lines)", rel, original_lines, upgraded_lines)

    return results


# =============================================================================
# Helpers
# =============================================================================

def _apply_new_files(
    new_files: list[dict],
    project_root: Path,
    dry_run: bool,
    output_dir: Path | None,
) -> None:
    """Create new companion files requested by the AI."""
    for nf in new_files:
        path_str = nf.get("path", "").strip()
        code = nf.get("code", "").strip()
        if not path_str or not code:
            continue
        dest_rel = Path(path_str)
        if dry_run:
            dest = (output_dir or project_root / "upgraded") / dest_rel
        else:
            dest = project_root / dest_rel
        dest.parent.mkdir(parents=True, exist_ok=True)
        dest.write_text(code, encoding="utf-8")
        log.info("    ➕ Created new file: %s", path_str)


def _apply_deprecations(
    deprecated_files: list[dict],
    project_root: Path,
    dry_run: bool,
) -> None:
    """Rename deprecated files to DEPRECATED_<filename> and prepend explanation comment."""
    for df in deprecated_files:
        path_str = df.get("path", "").strip()
        reason = df.get("reason", "Replaced during enterprise upgrade.").strip()
        if not path_str:
            continue
        src = project_root / path_str
        if not src.exists():
            log.warning("    deprecate: %s not found, skipping", path_str)
            continue
        if dry_run:
            log.info("    [dry-run] Would deprecate: %s (%s)", path_str, reason)
            continue
        # Build destination: same directory, DEPRECATED_ prefix on the filename
        deprecated_name = "DEPRECATED_" + src.name
        dest = src.parent / deprecated_name
        # Prepend deprecation comment based on language
        ext = src.suffix.lower()
        original_content = src.read_text(encoding="utf-8", errors="replace")
        if ext in (".py",):
            header = '"""\nDEPRECATED \u2014 This file has been superseded and should not be used in new code.\n\nReason: ' + reason + '\n"""\n'
        elif ext in (".js", ".ts", ".tsx", ".jsx", ".java", ".cs", ".go", ".rs", ".cpp", ".c", ".h", ".swift", ".kt"):
            header = "/**\n * DEPRECATED \u2014 This file has been superseded and should not be used in new code.\n *\n * Reason: " + reason + "\n */\n"
        else:
            header = f"# DEPRECATED: {reason}\n"
        dest.write_text(header + original_content, encoding="utf-8")
        src.unlink()
        log.info("    \U0001F7E1 Deprecated: %s -> %s", path_str, deprecated_name)


def _save_debug(project_root: Path, file_path: Path, raw: str) -> None:
    debug_dir = project_root / ".upgrade-debug"
    debug_dir.mkdir(exist_ok=True)
    safe = file_path.stem
    (debug_dir / f"{safe}_raw.txt").write_text(raw, encoding="utf-8")


def _save_changelog(project_root: Path, rel: str, changes: str | None) -> None:
    log_dir = project_root / ".upgrade-logs"
    log_dir.mkdir(exist_ok=True)
    safe = rel.replace("/", "__").replace("\\", "__")
    (log_dir / f"{safe}_changes.md").write_text(
        f"# {rel}\n\n{changes or '(no summary)'}\n", encoding="utf-8",
    )


# =============================================================================
# Main
# =============================================================================

def main() -> None:
    parser = argparse.ArgumentParser(
        description="Enterprise Code Upgrader v3",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )

    parser.add_argument("project_path", help="Project root directory")
    parser.add_argument("--include", nargs="+", default=["**/*.*"])
    parser.add_argument("--exclude", nargs="*", default=[])
    parser.add_argument(
        "--backend", choices=["api", "cli", "opencode"], default="cli",
        help="'cli' (Claude Code CLI, default — free with Pro/Max), "
             "'opencode' (OpenCode CLI — open source, any model), "
             "or 'api' (Anthropic API, separate billing)",
    )
    parser.add_argument("--model", default=None)
    parser.add_argument("--system-prompt", default=None)
    parser.add_argument("--dry-run", action="store_true")
    parser.add_argument("--output-dir", default=None)
    parser.add_argument("--commit-every", type=int, default=1)
    parser.add_argument("--no-commit", action="store_true")
    parser.add_argument("--no-batch", action="store_true")
    parser.add_argument("--batch-size", type=int, default=3)
    parser.add_argument("--delay", type=float, default=2.0)
    parser.add_argument("--skip-done", action="store_true")
    parser.add_argument("--reset-state", action="store_true", help="Clear upgrade state and start fresh")
    parser.add_argument(
        "--fallback-model", default=None,
        help="CLI backend: auto-fallback model when primary is overloaded (e.g. 'sonnet')",
    )
    parser.add_argument(
        "--max-budget", type=float, default=None,
        help="CLI backend: max USD to spend on API calls",
    )
    parser.add_argument(
        "--effort", default="max", choices=["low", "medium", "high", "max"],
        help="CLI backend: reasoning effort level (default: max). "
             "OpenCode backend: mapped to --variant (default: high).",
    )
    parser.add_argument(
        "--no-json-schema", action="store_true",
        help="CLI backend: disable --json-schema structured output (use markdown parsing instead). "
             "OpenCode backend: always uses regex parsing (no JSON schema support).",
    )
    parser.add_argument(
        "--no-persist", action="store_true",
        help="CLI backend: don't save sessions to disk after completion.",
    )
    parser.add_argument(
        "--hybrid", action="store_true",
        help="CLI backend: two-pass upgrade — planning pass then execution pass. "
             "Use with --planning-model to use a different model for planning "
             "(e.g. --planning-model opus --model sonnet). "
             "Doubles the number of CLI calls per file.",
    )
    parser.add_argument(
        "--planning-model", default=None,
        help="CLI backend: model for the planning pass in --hybrid mode "
             "(e.g. 'opus'). Defaults to the same model as --model.",
    )
    parser.add_argument(
        "--explore", action="store_true",
        help="Allow the AI to Read related project files for context before upgrading. "
             "In --hybrid mode only the planning pass explores; the execution pass never does. "
             "Off by default (the AI works only with the file content provided). "
             "Note: Read restrictions are prompt-level only — we trust the AI to follow them.",
    )
    parser.add_argument(
        "--no-explore-cutoff", action="store_true",
        help="Disable the auto-disable of Read access when context exceeds 500k tokens. "
             "By default, Read is revoked at 500k to prevent runaway context growth. "
             "Only relevant when --explore is on.",
    )
    parser.add_argument(
        "--no-auto-compact", action="store_true",
        help="Disable automatic session compaction at 900k tokens. "
             "By default, when context approaches the model's limit, the script "
             "starts a fresh session with a compacted summary to avoid overflow errors.",
    )
    parser.add_argument(
        "--max-reads", type=int, default=5,
        help="Max files the AI can Read per file upgrade when --explore is on (default: 5). "
             "This is a prompt-level hint only (not enforced at the tool level). "
             "Auto-disables Read when session context exceeds 500k tokens (unless --no-explore-cutoff).",
    )

    # Git branching strategy
    branch_group = parser.add_mutually_exclusive_group()
    branch_group.add_argument(
        "--branch", nargs="?", const="auto", default="auto", metavar="NAME",
        help="Create an upgrade branch (default). Auto-generates name like "
             "'upgrade/enterprise-20250324-1430'. Pass a name to override. "
             "After completion, optionally push with --push.",
    )
    branch_group.add_argument(
        "--from-branch", metavar="BRANCH",
        help="Create the upgrade branch from an existing branch instead of HEAD. "
             "Useful for building on top of a previous upgrade run "
             "(e.g. --from-branch upgrade/enterprise-20260404-1958).",
    )
    branch_group.add_argument(
        "--direct", action="store_true",
        help="Commit directly to the current branch (skip branch creation). "
             "Use when you've already created a branch manually or want to "
             "commit straight to main. NOT recommended for production repos.",
    )
    parser.add_argument(
        "--push", action="store_true",
        help="Push the upgrade branch to origin after completion. "
             "You can then create a PR from GitHub/GitLab UI. "
             "Ignored when --direct or --no-commit is set.",
    )

    args = parser.parse_args()

    project_root = Path(args.project_path).resolve()
    if not project_root.is_dir():
        log.error("Not a directory: %s", project_root)
        sys.exit(1)

    # State management
    if args.reset_state:
        state_path = project_root / STATE_FILE
        if state_path.exists():
            state_path.unlink()
            log.info("State file reset.")

    state = UpgradeState.load(project_root)
    excludes = DEFAULT_EXCLUDES + args.exclude

    # Discover files
    files = discover_files(project_root, args.include, excludes, state, args.skip_done)

    if not files:
        log.info("No files to process.")
        return

    # Categorize
    file_lines = {f: count_lines(f) for f in files}
    large_files = [f for f in files if file_lines[f] > SMALL_FILE_THRESHOLD]

    tiered_batches: list[list[Path]] = []
    if not args.no_batch:
        tier_buckets: dict[int, list[Path]] = {ml: [] for ml, _ in BATCH_TIERS}
        for f in files:
            fl = file_lines[f]
            if fl > SMALL_FILE_THRESHOLD:
                continue
            for ml, _ in BATCH_TIERS:
                if fl <= ml:
                    tier_buckets[ml].append(f)
                    break
        for ml, per_prompt in BATCH_TIERS:
            bucket = tier_buckets[ml]
            for i in range(0, len(bucket), per_prompt):
                tiered_batches.append(bucket[i:i + per_prompt])

    small_solo = [f for f in files if file_lines[f] <= SMALL_FILE_THRESHOLD] if args.no_batch else []
    total_batchable = sum(len(b) for b in tiered_batches)

    # Load system prompt
    script_dir = Path(__file__).parent
    sp_path = Path(args.system_prompt) if args.system_prompt else script_dir / "system_prompt.md"
    if not sp_path.exists():
        log.error("System prompt not found: %s", sp_path)
        sys.exit(1)
    system_prompt = sp_path.read_text(encoding="utf-8")

    total_lines = sum(file_lines.values())

    # Display plan
    model_display = args.model or ("opus" if args.backend == "cli" else "claude-opus-4-6" if args.backend == "api" else "opencode/qwen3.6-plus-free")
    print(f"\n{'='*60}")
    print(f"  Enterprise Code Upgrader v3")
    print(f"  Backend:     {args.backend.upper()}")
    print(f"  Model:       {model_display}")
    if args.backend == "cli":
        print(f"  Effort:      {args.effort} (adaptive thinking)")
        fb_display = args.fallback_model or ("none" if model_display in ("sonnet", "claude-sonnet-4-6") else "sonnet")
        print(f"  Fallback:    {fb_display}")
        print(f"  JSON schema: {'off' if args.no_json_schema else 'on (structured output)'}")
        print(f"  Sessions:    {'stateless (no clutter)' if args.no_persist else 'persistent (cross-file context)'}")
        if getattr(args, 'hybrid', False):
            pm = getattr(args, 'planning_model', None)
            if pm:
                print(f"  Mode:        hybrid (plan with {pm} -> execute with {model_display})")
            else:
                print(f"  Mode:        hybrid (plan -> execute two-pass)")
        if getattr(args, 'explore', False):
            mr = getattr(args, 'max_reads', 5)
            if getattr(args, 'hybrid', False):
                print(f"  Explore:     on (planning pass only, max {mr} reads/file, cutoff at 500k tokens)")
            else:
                print(f"  Explore:     on (max {mr} reads/file, cutoff at 500k tokens)")
        if args.max_budget:
            print(f"  Budget cap:  ${args.max_budget:.2f}")
    elif args.backend == "opencode":
        effort_display = args.effort if args.effort != "max" else "high (max->high for OpenCode)"
        print(f"  Effort:      {effort_display} (--variant)")
        print(f"  JSON schema: off (regex parsing -- OpenCode doesn't support --json-schema)")
        print(f"  Permissions: auto-approved (opencode run default)")
        if getattr(args, 'hybrid', False):
            pm = getattr(args, 'planning_model', None)
            if pm:
                print(f"  Mode:        hybrid (plan with {pm} -> execute with {model_display})")
            else:
                print(f"  Mode:        hybrid (plan -> execute two-pass)")
    else:
        print(f"  Effort:      {args.effort} (adaptive thinking)")
    print(f"  Files:       {len(files)} ({len(large_files)} large, {total_batchable} batchable)")
    print(f"  Total lines: {total_lines:,}")
    print(f"  Previously:  {len(state.completed)} done, {len(state.failed)} failed")
    print(f"  Validation:  syntax check + size sanity + retry (max {MAX_UPGRADE_RETRIES})")
    print(f"  Dry-run:     {args.dry_run}")
    if not args.no_commit and not args.dry_run:
        if args.direct:
            current = git_current_branch(project_root) if git_is_repo(project_root) else "N/A"
            print(f"  Git:         direct to '{current}' (no branch)")
        else:
            print(f"  Git:         new branch -> review -> merge")
        if args.push:
            print(f"  Push:        auto-push after completion")
    print(f"{'='*60}\n")

    for f in files:
        fl = file_lines[f]
        tag = "solo" if fl > SMALL_FILE_THRESHOLD or args.no_batch else "batch"
        log.info("  [%s] %s (%d lines)", tag, f.relative_to(project_root).as_posix(), fl)

    confirm = input("\nProceed? [Y/n] ").strip().lower()
    if confirm and confirm != "y":
        print("Aborted.")
        return

    # -- Git branch setup --------------------------------------------------
    original_branch: str | None = None
    upgrade_branch: str | None = None

    if not args.no_commit and not args.dry_run and git_is_repo(project_root):
        if not git_has_clean_tree(project_root):
            log.warning(
                "Working tree has uncommitted changes. Commit or stash them first."
            )
            bail = input("Continue anyway? [y/N] ").strip().lower()
            if bail != "y":
                print("Aborted.")
                return

        if not args.direct:
            # Create upgrade branch (default behavior)
            branch_name = None if args.branch == "auto" else args.branch
            try:
                original_branch, upgrade_branch = git_setup_branch(
                    project_root, branch_name, from_branch=args.from_branch,
                )
            except RuntimeError as e:
                log.error("Branch setup failed: %s", e)
                sys.exit(1)
        else:
            current = git_current_branch(project_root)
            log.info("Direct mode: committing to current branch '%s'", current)

    output_dir = Path(args.output_dir) if args.output_dir else None
    model = args.model or "claude-opus-4-6"

    if args.backend == "cli":
        main_model = args.model or "opus"
        # Avoid fallback == main model (CLI rejects it).
        # Default fallback to "sonnet" only when main model isn't sonnet.
        if args.fallback_model:
            fallback = args.fallback_model if args.fallback_model != main_model else None
        else:
            fallback = None if main_model in ("sonnet", "claude-sonnet-4-6") else "sonnet"

        conversation: ConversationState | CLISession | OpenCodeSession = CLISession(
            system_prompt_file=str(sp_path),
            project_dir=str(project_root),
            model=main_model,
            fallback_model=fallback,
            planning_model=getattr(args, 'planning_model', None),
            max_budget_usd=args.max_budget,
            effort=args.effort,
            use_json_schema=not args.no_json_schema,
            no_persist=args.no_persist,
            max_reads=getattr(args, 'max_reads', 5),
        )
    elif args.backend == "opencode":
        # OpenCode: model must be provider/model format
        oc_model = args.model or "opencode/qwen3.6-plus-free"
        # OpenCode doesn't support --json-schema, so force regex parsing
        conversation = OpenCodeSession(
            system_prompt_file=str(sp_path),
            project_dir=str(project_root),
            model=oc_model,
            planning_model=getattr(args, 'planning_model', None),
            effort="high" if args.effort == "max" else args.effort,  # cap max→high
            max_reads=getattr(args, 'max_reads', 5),
        )
    else:
        conversation = ConversationState(system_prompt, model, effort=args.effort)

    # Conversation intro
    log.info("Starting conversation...")
    file_manifest = "\n".join(
        f"  - {f.relative_to(project_root).as_posix()} ({file_lines[f]} lines)"
        for f in files[:30]
    )
    if len(files) > 30:
        file_manifest += f"\n  ... and {len(files) - 30} more"

    # Load prior upgrade summaries from .upgrade-logs/ to give the agent context
    # on what patterns were already applied to other files in the project.
    prior_summaries = ""
    logs_dir = project_root / ".upgrade-logs"
    if logs_dir.exists():
        log_files = sorted(logs_dir.glob("*_changes.md"))
        examples = []
        for lf in log_files:
            try:
                summary = lf.read_text(encoding="utf-8", errors="replace").strip()
                if summary:
                    examples.append(summary)
            except OSError:
                pass
        if examples:
            prior_summaries = (
                "\n\n## Prior Upgrades (for reference — match these patterns)\n\n"
                "These files were already upgraded in a previous session. "
                "Study the patterns applied and be consistent:\n\n"
                + "\n\n---\n\n".join(examples)
                + "\n\n---\n\n"
            )
            log.info("  Loaded %d prior upgrade summaries for context", len(examples))

    # Check for a previous abort marker — the next agent run will see this
    abort_context = ""
    abort_marker = project_root / ".upgrade-abort.md"
    if abort_marker.exists():
        try:
            abort_text = abort_marker.read_text(encoding="utf-8", errors="replace").strip()
            if abort_text:
                abort_context = (
                    "\n\n## Previous Run Was Interrupted\n\n"
                    "The previous upgrade run was interrupted (Ctrl+C). "
                    "Here is the abort report that was generated:\n\n"
                    f"{abort_text}\n\n"
                    "This run is a fresh start — use --skip-done to skip already-completed files.\n"
                )
        except OSError:
            pass

    intro = (
        "I'm going to send you files from my codebase one by one to upgrade to "
        "enterprise quality. For each file, I want a COMPLETE rewrite — not patches, "
        "not incremental fixes. Write the file from scratch with the same public API "
        "but enterprise-grade internals.\n\n"
        "Here is what 'enterprise quality' means for this codebase. Apply ALL of these "
        "patterns to EVERY file:\n\n"
        "1. **Constants class** at the top with all magic numbers/strings as Final fields\n"
        "2. **Custom exception hierarchy** — base error → specific errors, all carrying details dict\n"
        "3. **Frozen config dataclass** with from_settings() classmethod, replacing scattered config reads\n"
        "4. **Singleton factory** — module-level get_foo_service() function\n"
        "5. **Separated concerns** — if a class does 3+ things, split into focused classes\n"
        "6. **TypedDict/dataclass for all dicts** — kill every Dict[str, Any]\n"
        "7. **Protocol classes** for dependency injection where constructors hard-code deps\n"
        "8. **Context manager support** (async with) for anything holding resources\n"
        "9. **Structured logging** with context (extra={...}), replacing all print()\n"
        "10. **Backward-compatible wrappers** — keep old function signatures as thin delegators\n\n"
        "If a file has placeholder implementations (return True, pass, return 0.5), "
        "replace them with REAL implementations. If it's a skeleton, flesh it out fully.\n\n"
        "Each response should include: a summary of changes, then the complete file in a "
        "code fence. The file should be noticeably larger and more thorough than the original.\n\n"
        f"Project: {project_root.name}\n"
        f"Files to process: {len(files)}\n\n"
        f"File manifest:\n{file_manifest}\n"
        f"{prior_summaries}\n"
        f"{abort_context}\n"
        "Let's start."
    )
    conversation.send(intro)
    log.info("  Conversation initialized.")

    # Clear the abort marker since we're starting a fresh run
    if abort_marker.exists():
        abort_marker.unlink()
        log.info("  Cleared previous abort marker (.upgrade-abort.md)")

    # Process
    success_count = 0
    fail_count = 0
    pending_commit: list[tuple[Path, str | None]] = []
    file_counter = 0
    # Track the file being actively processed when Ctrl+C hits (mutable dict for closure)
    progress: dict = {
        "file": None,       # Path | None
        "raw": "",          # last raw AI response
        "attempt": 0,       # current retry attempt
        "error": "",        # last error message
    }

    def abort_cleanup() -> None:
        """Graceful abort on Ctrl+C — commit pending, switch back, save state."""
        log.warning("\n\nInterrupted! Performing graceful abort...")
        # Commit any pending changes first
        if pending_commit and not args.no_commit and not args.dry_run:
            log.warning("Committing %d pending file(s) before abort...", len(pending_commit))
            do_commit(pending_commit)
        # Save state
        state.save(project_root)
        # Write a continuation marker for the next agent run
        abort_marker = project_root / ".upgrade-abort.md"
        completed_count = len(state.completed)
        failed_count = len(state.failed)
        last_file = file_counter if file_counter <= len(files) else len(files)
        next_file = files[last_file].relative_to(project_root).as_posix() if last_file < len(files) else "none (all sent)"

        # Build the interrupted file session section
        interrupted_session = ""
        in_progress_file = progress["file"]
        if in_progress_file:
            rel_in_progress = in_progress_file.relative_to(project_root).as_posix()
            orig_lines = len(in_progress_file.read_text(encoding="utf-8", errors="replace").splitlines())
            interrupted_session = (
                f"## ⚠️ File Being Processed When Interrupted\n\n"
                f"**File:** `{rel_in_progress}` ({orig_lines} lines)\n"
                f"**Attempt:** {progress['attempt'] + 1} of {MAX_UPGRADE_RETRIES + 1}\n"
            )
            if progress["error"]:
                interrupted_session += f"**Last error:** {progress['error']}\n\n"
            if progress["raw"]:
                raw_len = len(progress["raw"])
                # Save raw response to debug dir for recovery
                debug_dir = project_root / ".upgrade-debug"
                debug_dir.mkdir(exist_ok=True)
                (debug_dir / f"{in_progress_file.stem}_aborted_raw.txt").write_text(
                    progress["raw"], encoding="utf-8"
                )
                # Extract only the unfinished portion after the last completed code block
                fences = list(re.finditer(r'```', progress["raw"]))
                closing_fences = [f for i, f in enumerate(fences) if i % 2 == 1]
                if closing_fences:
                    unfinished = progress["raw"][closing_fences[-1].end():].strip()
                else:
                    unfinished = progress["raw"].strip()
                if unfinished:
                    truncated = unfinished[:3000]
                    ellipsis = "\n...(truncated, full response in .upgrade-debug/)" if len(unfinished) > 3000 else ""
                    interrupted_session += (
                        f"**Unfinished AI response ({raw_len} chars, extracted below):**\n\n"
                        f"```\n{truncated}{ellipsis}\n```\n\n"
                        f"Full raw response saved to: `.upgrade-debug/{in_progress_file.stem}_aborted_raw.txt`\n\n"
                    )
            interrupted_session += (
                f"**What this means:** The AI was working on this file when you pressed Ctrl+C. "
                f"The response may be partial, invalid, or the file may have been written but not validated. "
                f"Re-run with `--skip-done` — this file will be retried from scratch since it was not marked completed.\n\n"
            )

        abort_marker.write_text(
            f"# Previous Run Interrupted\n\n"
            f"**Status:** Aborted by user (Ctrl+C) after processing {last_file}/{len(files)} files.\n\n"
            f"**Completed so far:** {completed_count} files upgraded.\n"
            f"**Failed so far:** {failed_count} files.\n"
            f"**Last file processed:** {next_file}\n\n"
            f"{interrupted_session}"
            f"**What to do next:**\n"
            f"1. Re-run the upgrade command with `--skip-done` to resume from where this run stopped.\n"
            f"2. The state file (`.upgrade-state.json`) already tracks all completed and failed files.\n"
            f"3. All upgraded code has been written to disk and committed (if `--no-commit` was not set).\n"
            f"4. The working tree was switched back to the original branch.\n\n"
            f"**Pending files that were NOT processed:**\n"
            + "\n".join(f"- `{f.relative_to(project_root).as_posix()}`" for f in files[last_file:])
            + "\n",
            encoding="utf-8",
        )
        # Switch back to original branch
        if upgrade_branch and original_branch and not args.no_commit and not args.dry_run:
            log.warning("Switching back to: %s", original_branch)
            try:
                git_switch_back(project_root, original_branch)
            except Exception as e:
                log.error("Failed to switch back: %s", e)
                log.error("You are still on branch: %s — run: git checkout %s", upgrade_branch, original_branch)
        log.warning("Abort complete. State saved. Next run: use --skip-done to resume from file: %s", next_file)
        sys.exit(130)

    import signal
    signal.signal(signal.SIGINT, lambda sig, frame: abort_cleanup())

    # Track run results for compact intro
    run_results: list[tuple[str, bool, str | None]] = []

    def check_auto_compact() -> None:
        """Auto-compact session when context exceeds 900k tokens."""
        nonlocal conversation
        if getattr(args, 'no_auto_compact', False):
            return
        if not isinstance(conversation, (CLISession, OpenCodeSession)):
            return
        threshold = 900_000
        ctx = getattr(conversation, 'total_input_tokens', 0)
        if ctx < threshold:
            return
        log.info("Context at %s tokens (threshold %s) → starting fresh session with compacted intro",
                 f"{ctx:,}", f"{threshold:,}")
        # Build compact intro
        sp_path = Path(args.system_prompt) if args.system_prompt else project_root / "system_prompt.py"
        compact_msg = build_compact_intro(project_root, state, run_results, str(sp_path))
        # Create new session
        if isinstance(conversation, OpenCodeSession):
            conversation = OpenCodeSession(
                system_prompt_file=str(sp_path),
                project_dir=str(project_root),
                model=conversation.model,
                planning_model=conversation.planning_model,
                effort=conversation.effort,
                max_reads=conversation.max_reads,
            )
        else:
            conversation = CLISession(
                system_prompt_file=str(sp_path),
                project_dir=str(project_root),
                model=conversation.model,
                fallback_model=conversation.fallback_model,
                planning_model=conversation.planning_model,
                max_budget_usd=conversation.max_budget_usd,
                effort=conversation.effort,
                use_json_schema=conversation.use_json_schema,
                no_persist=conversation.no_persist,
                max_reads=conversation.max_reads,
            )
        # Send compact intro to new session
        conversation.send(compact_msg)
        log.info("Fresh session initialized with compacted intro.")

    def do_commit(pending: list[tuple[Path, str | None]]) -> None:
        if not pending or args.no_commit or args.dry_run:
            return
        paths = [p for p, _ in pending]
        summaries = [c or "enterprise upgrade" for _, c in pending]
        rels = [p.relative_to(project_root).as_posix() for p in paths]

        # Build commit title with file path and line counts
        if len(rels) == 1:
            r = rels[0]
            orig = file_lines.get(paths[0], 0)
            new = len(paths[0].read_text(encoding="utf-8", errors="replace").splitlines())
            msg = f"ent-upgrade: {r} ({orig} → {new} lines)\n\n"
        else:
            file_list = ", ".join(rels[:4])
            if len(rels) > 4:
                file_list += f" +{len(rels) - 4} more"
            msg = f"ent-upgrade: {file_list}\n\n"

        for r, s in zip(rels, summaries):
            msg += f"## {r}\n{s}\n\n"
        git_commit_batch(project_root, paths, msg)
        # Auto-push after each commit if --push is enabled
        if args.push and upgrade_branch:
            git_push_branch(project_root, upgrade_branch)

    # Large files
    for fp in large_files:
        file_counter += 1
        check_auto_compact()
        progress["file"] = fp
        progress["raw"] = ""
        progress["attempt"] = 0
        progress["error"] = ""
        log.info("━" * 60)
        log.info("[%d/%d]", file_counter, len(files))

        ok, changes = upgrade_single(
            fp, project_root, conversation, state,
            dry_run=args.dry_run, hybrid=getattr(args, 'hybrid', False),
            explore=getattr(args, 'explore', False), no_explore_cutoff=getattr(args, 'no_explore_cutoff', False), output_dir=output_dir,
            progress=progress,
        )
        rel = fp.relative_to(project_root).as_posix()
        run_results.append((rel, ok, changes))
        progress["file"] = None
        if ok:
            success_count += 1
            pending_commit.append((fp, changes))
        else:
            fail_count += 1

        if len(pending_commit) >= args.commit_every:
            do_commit(pending_commit)
            pending_commit.clear()

        if file_counter < len(files):
            time.sleep(args.delay)

    # Batched small files
    for batch in tiered_batches:
        file_counter += len(batch)
        check_auto_compact()
        progress["file"] = None
        log.info("━" * 60)
        log.info("[%d/%d] (batch of %d)", file_counter, len(files), len(batch))

        results = upgrade_batch(
            batch, project_root, conversation, state,
            dry_run=args.dry_run, hybrid=getattr(args, 'hybrid', False),
            explore=getattr(args, 'explore', False), no_explore_cutoff=getattr(args, 'no_explore_cutoff', False), output_dir=output_dir,
            progress=progress,
        )
        for fp, ok, changes in results:
            rel = fp.relative_to(project_root).as_posix()
            run_results.append((rel, ok, changes))
            if ok:
                success_count += 1
                pending_commit.append((fp, changes))
            else:
                fail_count += 1

        if len(pending_commit) >= args.commit_every:
            do_commit(pending_commit)
            pending_commit.clear()

        if file_counter < len(files):
            time.sleep(args.delay)

    # Solo small files (--no-batch)
    for fp in small_solo:
        file_counter += 1
        check_auto_compact()
        progress["file"] = fp
        progress["raw"] = ""
        progress["attempt"] = 0
        progress["error"] = ""
        log.info("━" * 60)
        log.info("[%d/%d]", file_counter, len(files))

        ok, changes = upgrade_single(
            fp, project_root, conversation, state,
            dry_run=args.dry_run, hybrid=getattr(args, 'hybrid', False),
            explore=getattr(args, 'explore', False), no_explore_cutoff=getattr(args, 'no_explore_cutoff', False), output_dir=output_dir,
            progress=progress,
        )
        rel = fp.relative_to(project_root).as_posix()
        run_results.append((rel, ok, changes))
        progress["file"] = None
        if ok:
            success_count += 1
            pending_commit.append((fp, changes))
        else:
            fail_count += 1

        if len(pending_commit) >= args.commit_every:
            do_commit(pending_commit)
            pending_commit.clear()

        if file_counter < len(files):
            time.sleep(args.delay)

    # Batched small files
    for batch in tiered_batches:
        file_counter += len(batch)
        progress["file"] = None
        log.info("━" * 60)
        log.info("[%d/%d] (batch of %d)", file_counter, len(files), len(batch))

        results = upgrade_batch(
            batch, project_root, conversation, state,
            dry_run=args.dry_run, hybrid=getattr(args, 'hybrid', False),
            explore=getattr(args, 'explore', False), no_explore_cutoff=getattr(args, 'no_explore_cutoff', False), output_dir=output_dir,
            progress=progress,
        )
        for fp, ok, changes in results:
            if ok:
                success_count += 1
                pending_commit.append((fp, changes))
            else:
                fail_count += 1

        if len(pending_commit) >= args.commit_every:
            do_commit(pending_commit)
            pending_commit.clear()

        if file_counter < len(files):
            time.sleep(args.delay)

    # Solo small files (--no-batch)
    for fp in small_solo:
        file_counter += 1
        progress["file"] = fp
        progress["raw"] = ""
        progress["attempt"] = 0
        progress["error"] = ""
        log.info("━" * 60)
        log.info("[%d/%d]", file_counter, len(files))

        ok, changes = upgrade_single(
            fp, project_root, conversation, state,
            dry_run=args.dry_run, hybrid=getattr(args, 'hybrid', False),
            explore=getattr(args, 'explore', False), no_explore_cutoff=getattr(args, 'no_explore_cutoff', False), output_dir=output_dir,
        )
        progress["file"] = None
        if ok:
            success_count += 1
            pending_commit.append((fp, changes))
        else:
            fail_count += 1

        if len(pending_commit) >= args.commit_every:
            do_commit(pending_commit)
            pending_commit.clear()

        if file_counter < len(files):
            time.sleep(args.delay)

    if pending_commit:
        do_commit(pending_commit)

    # -- Git post-processing: push + switch back ---------------------------
    pushed = False
    if upgrade_branch and not args.no_commit and not args.dry_run:
        if args.push:
            pushed = git_push_branch(project_root, upgrade_branch)

        # Switch back to original branch
        if original_branch:
            git_switch_back(project_root, original_branch)

    # Summary
    print(f"\n{'='*60}")
    print(f"  DONE - {success_count}/{len(files)} upgraded, {fail_count} failed")
    if hasattr(conversation, "token_usage_str"):
        print(f"  {conversation.token_usage_str}")
    print(f"  State:  {project_root / STATE_FILE}")
    print(f"  Logs:   {project_root / '.upgrade-logs'}")
    if args.dry_run:
        print(f"  Output: {output_dir or project_root / 'upgraded'}")
    if upgrade_branch:
        print(f"  Branch: {upgrade_branch}" + (" (pushed)" if pushed else " (local only)"))
        if not pushed:
            print(f"  Push:   git push -u origin {upgrade_branch}")
        print(f"  Merge:  git checkout {original_branch or 'main'} && git merge {upgrade_branch}")
        print(f"  Or PR:  create pull request from {upgrade_branch} -> {original_branch or 'main'}")
    print(f"{'='*60}\n")


if __name__ == "__main__":
    main()