fc

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "truststore",
# ]
# ///

import argparse
import json
import os
import re
import subprocess
import sys
import threading
import time
import traceback
from collections import defaultdict
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime
from pathlib import Path

import truststore

# Verify TLS against the OS trust store. TLS-inspecting proxies install their
# root CA there, and certifi's bundle does not have it.
truststore.inject_into_ssl()

CONFIG_DIR = Path.home() / ".config" / "fast-commit"
CONFIG_PATH = CONFIG_DIR / ".env"
LOGS_DIR = CONFIG_DIR / "logs"
AUDIT_LOG = CONFIG_DIR / "audit.jsonl"

# Session log file - created once per run
_session_log = None


def get_session_log():
    """Get or create session log file for this execution."""
    global _session_log
    if _session_log is None:
        LOGS_DIR.mkdir(parents=True, exist_ok=True)
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        _session_log = LOGS_DIR / f"session_{timestamp}.log"
        _session_log.write_text(f"=== fastc session started: {datetime.now().isoformat()} ===\n")
    return _session_log


def log(level, message, context=None):
    """Log a message to the session log file."""
    log_file = get_session_log()
    timestamp = datetime.now().strftime("%H:%M:%S")
    line = f"[{timestamp}] {level}: {message}"
    if context:
        context_str = ", ".join(f"{k}={v}" for k, v in context.items())
        line += f" | {context_str}"
    with open(log_file, "a") as f:
        f.write(line + "\n")



def log_git_state():
    """Log current git state to session log."""
    try:
        branch_result = subprocess.run(
            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
            capture_output=True, timeout=5
        )
        branch = branch_result.stdout.decode().strip() if branch_result.returncode == 0 else "unknown"
        log("INFO", "git branch", {"branch": branch})

        status_result = subprocess.run(
            ["git", "status", "--short"],
            capture_output=True, timeout=5
        )
        if status_result.returncode == 0:
            status = status_result.stdout.decode().strip()
            if status:
                lines = status.splitlines()
                log("INFO", "git status", {"files": len(lines)})
    except Exception as e:
        log("INFO", "git state capture failed", {"error": str(e)})


# ---------------------------------------------------------------------------
# Color + output helpers
# ---------------------------------------------------------------------------

_USE_COLOR = sys.stdout.isatty() and sys.stderr.isatty() and "NO_COLOR" not in os.environ


def _c(code, text):
    """Apply ANSI color if supported."""
    if not _USE_COLOR:
        return text
    return f"\033[{code}m{text}\033[0m"


def _green(t): return _c("32", t)
def _red(t): return _c("31", t)
def _yellow(t): return _c("33", t)
def _dim(t): return _c("2", t)
def _cyan(t): return _c("36", t)


TICK = _green("✓")
CROSS = _red("✗")
WARN_SYM = _yellow("⚠")
SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]

_output_lock = threading.Lock()


class Timings:
    """Track wall-clock time per phase and aggregate LLM request stats.

    Used both for live progress (in-flight count, ETA) and for the end-of-run
    breakdown so the user can see exactly where time went.
    """

    def __init__(self):
        self._lock = threading.Lock()
        self._phases = {}         # name -> accumulated wall seconds
        self._phase_start = {}    # name -> monotonic start
        self._llm_total = 0.0     # sum of individual LLM durations (for parallel efficiency)
        self._llm_count = 0
        self._llm_inflight = 0
        self._llm_durations = []  # rolling history for ETA
        self._start = time.monotonic()

    def phase_start(self, name):
        with self._lock:
            self._phase_start[name] = time.monotonic()

    def phase_end(self, name):
        with self._lock:
            if name in self._phase_start:
                self._phases[name] = self._phases.get(name, 0.0) + (
                    time.monotonic() - self._phase_start.pop(name)
                )

    def request_started(self):
        with self._lock:
            self._llm_inflight += 1

    def request_finished(self, duration):
        with self._lock:
            self._llm_inflight = max(0, self._llm_inflight - 1)
            self._llm_total += duration
            self._llm_count += 1
            self._llm_durations.append(duration)

    def snapshot(self):
        with self._lock:
            return {
                "inflight": self._llm_inflight,
                "llm_total": self._llm_total,
                "llm_count": self._llm_count,
                "durations": list(self._llm_durations),
                "elapsed": time.monotonic() - self._start,
            }

    def summary_line(self):
        with self._lock:
            # Deterministic ordering: phases in the order we started them.
            parts = [f"{name} {t:.1f}s" for name, t in self._phases.items()]
            total = time.monotonic() - self._start
            parts.append(f"total {total:.1f}s")
            if self._llm_count:
                parts.append(
                    f"llm {self._llm_total:.1f}s/{self._llm_count} req"
                )
            return " · ".join(parts)


_timings = Timings()


class Spinner:
    """Thread-based terminal spinner. All output must go through this object
    so that the spinner line is cleared before any print.

    Supports a dynamic message callback so phase 2 can show live progress
    (n/N, in-flight count, ETA) without polling from the main thread.
    """

    def __init__(self):
        self._msg = ""
        self._dynamic = None
        self._phase_start = time.monotonic()
        self._last_line_len = 0
        self._stop = threading.Event()
        self._thread = threading.Thread(target=self._run, daemon=True)
        self._thread.start()

    def _render_text(self):
        if self._dynamic is not None:
            try:
                return self._dynamic()
            except Exception:
                return self._msg
        return self._msg

    def _run(self):
        i = 0
        while not self._stop.wait(0.1):
            with _output_lock:
                frame = _cyan(SPINNER_FRAMES[i % len(SPINNER_FRAMES)])
                elapsed = time.monotonic() - self._phase_start
                body = self._render_text()
                suffix = _dim(f" {elapsed:.1f}s")
                line = f"{frame} {body}{suffix}"
                # Pad over whatever we printed last frame so trailing
                # characters from longer messages don't linger.
                pad = max(0, self._last_line_len - len(line))
                sys.stdout.write("\r" + line + (" " * pad))
                sys.stdout.flush()
                self._last_line_len = len(line)
            i += 1

    def set(self, message):
        """Update the spinner message and restart the per-phase elapsed timer."""
        self._msg = message
        self._dynamic = None
        self._phase_start = time.monotonic()

    def set_dynamic(self, fn):
        """Provide a callable whose return value is rendered every frame."""
        self._dynamic = fn
        self._phase_start = time.monotonic()

    def _clear(self):
        """Clear spinner line. Must be called with _output_lock held."""
        if self._last_line_len:
            sys.stdout.write("\r" + " " * self._last_line_len + "\r")
            sys.stdout.flush()
            self._last_line_len = 0

    def println(self, message, file=None):
        """Print a line, temporarily pausing the spinner."""
        with _output_lock:
            self._clear()
            print(message, file=file or sys.stdout)

    def ok(self, message):
        self.println(f"{TICK} {message}")

    def fail(self, message):
        self.println(f"{CROSS} {message}", file=sys.stderr)

    def warn(self, message):
        self.println(f"{WARN_SYM} {message}", file=sys.stderr)

    def stop(self):
        if self._stop.is_set():
            return
        self._stop.set()
        self._thread.join()
        with _output_lock:
            self._clear()


_spinner: "Spinner | None" = None


def sprint(message, file=None):
    """Print a message, clearing the spinner line first if one is active."""
    if _spinner:
        _spinner.println(message, file=file)
    else:
        print(message, file=file or sys.stdout)


# ---------------------------------------------------------------------------
# Error / warning helpers
# ---------------------------------------------------------------------------

def warn(message, context=None):
    """Print warning to user and log it."""
    if _spinner:
        _spinner.warn(message)
    else:
        print(f"{WARN_SYM} {message}", file=sys.stderr)
    log("WARN", message, context)


def record_error(message, context=None):
    """Record error details to session log with full context."""
    log("ERROR", message, context)
    exc_info = traceback.format_exc()
    if exc_info and exc_info.strip() != "NoneType: None":
        log_file = get_session_log()
        with open(log_file, "a") as f:
            f.write(f"Stack trace:\n{exc_info}\n")
    log_git_state()
    sprint(f"  session log: {get_session_log()}", file=sys.stderr)


_audit_repo = None


_audit_dir_created = False


def audit(event, data=None):
    """Append a structured entry to the persistent audit log."""
    global _audit_repo, _audit_dir_created
    if not _audit_dir_created:
        AUDIT_LOG.parent.mkdir(parents=True, exist_ok=True)
        _audit_dir_created = True
    if _audit_repo is None:
        repo_result = subprocess.run(
            ["git", "rev-parse", "--show-toplevel"],
            capture_output=True, timeout=5,
        )
        _audit_repo = repo_result.stdout.decode().strip() if repo_result.returncode == 0 else "unknown"
    entry = {
        "ts": datetime.now().isoformat(),
        "repo": _audit_repo,
        "event": event,
    }
    if data:
        entry["data"] = data
    with open(AUDIT_LOG, "a") as f:
        f.write(json.dumps(entry) + "\n")


def exit_with_error(message, context=None):
    """Print error, record to disk, and exit."""
    if _spinner:
        _spinner.fail(f"error: {message}")
        _spinner.stop()
    else:
        print(f"error: {message}", file=sys.stderr)
    record_error(message, context)
    audit("error", {"message": message})
    sys.exit(1)


# ---------------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------------

# Files to exclude from diff analysis (don't help with commit messages)
EXCLUDED_PATTERNS = [
    # JS/Node lockfiles
    "pnpm-lock.yaml",
    "package-lock.json",
    "yarn.lock",
    "bun.lockb",
    # Other language lockfiles
    "Cargo.lock",
    "poetry.lock",
    "Pipfile.lock",
    "go.sum",
    "composer.lock",
    "Gemfile.lock",
    # Minified/generated files
    "*.min.js",
    "*.min.css",
    "*.map",
]

PROVIDER_OPENROUTER = "openrouter"
PROVIDER_CLAUDE = "claude"
PROVIDERS = (PROVIDER_OPENROUTER, PROVIDER_CLAUDE)

# Used when the config sets no CLAUDE_MODEL. Haiku is the cheapest model that
# handles this task, and the claude provider spends a seat's Agent SDK credit
# rather than metered API billing.
CLAUDE_DEFAULT_MODEL = "haiku"

SCOPE_GUIDANCE = (
    "Scope MUST reflect the project or module, NOT the leaf filename. "
    "Derive it from the file paths: in monorepos where top-level dirs are containers "
    "(apps/, packages/, libs/, services/, crates/, cmd/, tools/), use the project name "
    "(2nd path component) as scope. Otherwise use the first meaningful directory. "
    "Examples: apps/grupeta/src/auth.ts -> (grupeta), packages/shared/utils.ts -> (shared), "
    "src/api/handler.go -> (api), infra/terraform/main.tf -> (infra). "
    "For mixed projects, pick the most specific common ancestor. "
    "Always include a scope — omit only for truly root-level config files."
)

# The same rules without the worked examples, which produced identical scopes
# on a smaller prompt.
SCOPE_GUIDANCE_TERSE = (
    "Scope is the project or module taken from the file path, never the filename. "
    "Under a container dir (apps/ packages/ libs/ services/ crates/ cmd/ tools/) use the "
    "2nd path component, otherwise the first directory. "
    "Omit the scope only for truly root-level config files."
)

DESCRIPTION_GUIDANCE = (
    "The description is the commit body. It must explain WHAT changed and WHY, not just restate the subject. "
    "Cover: what behavior/logic changed, why the change was needed, and any non-obvious consequences. "
    "Use 1-4 concise sentences. Never leave it empty or repeat the subject line."
)

PHASE1_PROMPT = """Group changed files into logical atomic commits by analyzing file paths and change types.
Output JSON array: [{"files":["path/to/file"],"hint":"what changed"}]
Use REAL file paths from the list below. Output ONLY valid JSON, no markdown."""


def _build_prompts(scope_guidance, description_guidance):
    return {
        "system": f"""Group git diff into atomic commits. Every file MUST appear in exactly one commit.
Output JSON array: [{{"files":["path/to/file"],"message":"type(scope): subject","description":"commit body"}}]
Types: feat|fix|refactor|chore|docs|style|test|perf. Subject: imperative, <=50 chars, no period.
{scope_guidance}
{description_guidance}
Use REAL file paths from the diff and REAL commit messages. Output ONLY valid JSON, no markdown.""",
        "phase2": f"""Generate ONE commit message for this diff.
Output JSON object: {{"message":"type(scope): subject","description":"commit body"}}
Types: feat|fix|refactor|chore|docs|style|test|perf. Subject: imperative, <=50 chars, no period.
{scope_guidance}
{description_guidance}
Output ONLY valid JSON, no markdown.""",
        # No description field at all. Used where the phase 1 hint already
        # describes the group, so there is nothing to pay a model to write.
        "phase2_subject": f"""Generate ONE commit subject for this diff.
Output JSON object: {{"message":"type(scope): subject"}}
Types: feat|fix|refactor|chore|docs|style|test|perf. Subject: imperative, <=50 chars, no period.
{scope_guidance}
Output ONLY valid JSON, no markdown.""",
        "retry": f"""Previous output was rejected. Use REAL file paths from the diff and REAL commit messages.
Every file MUST appear in exactly one commit.
{scope_guidance}
{description_guidance}
Output ONLY valid JSON array:
[{{"files":["real/path.go"],"message":"feat(scope): real subject","description":"what changed and why"}}]""",
    }


PROMPTS = {
    PROVIDER_OPENROUTER: _build_prompts(SCOPE_GUIDANCE, DESCRIPTION_GUIDANCE),
    PROVIDER_CLAUDE: _build_prompts(SCOPE_GUIDANCE_TERSE, DESCRIPTION_GUIDANCE),
}

# Directories that are monorepo containers — scope should be the child (project name)
CONTAINER_DIRS = {"apps", "packages", "libs", "services", "crates", "cmd", "tools"}


def _dir_scope(path):
    """Extract monorepo-aware scope from a file path.

    In monorepos where the first directory is a container (apps/, packages/, etc.),
    the scope is the project name (2nd component). Otherwise it's the first directory.
    """
    parts = path.split("/")
    if len(parts) > 2 and parts[0] in CONTAINER_DIRS:
        return parts[1]
    if len(parts) > 1:
        return parts[0]
    return ""


def _smart_path_label(path):
    """Return a grounded label for a file path, suitable for commit messages.

    Instead of just the leaf filename, includes enough path context to be meaningful.
    """
    parts = path.split("/")
    if len(parts) <= 2:
        return path
    if parts[0] in CONTAINER_DIRS and len(parts) > 2:
        return f"{parts[1]}/{parts[-1]}"
    return f"{parts[0]}/{parts[-1]}"


def compute_path_context(file_paths):
    """Compute a path context hint for the LLM from staged file paths.

    Returns a string like:
      PATH CONTEXT: All files under "apps/grupeta/". Projects: grupeta.
    or for multi-project changes:
      PATH CONTEXT: Projects: grupeta, shared. Dirs: apps/grupeta/, packages/shared/.
    """
    if not file_paths:
        return ""
    paths = list(file_paths)
    scopes = defaultdict(set)
    for p in paths:
        parts = p.split("/")
        if len(parts) > 2 and parts[0] in CONTAINER_DIRS:
            scopes[parts[1]].add("/".join(parts[:2]))
        elif len(parts) > 1:
            scopes[parts[0]].add(parts[0])

    if not scopes:
        return ""

    projects = sorted(scopes.keys())
    if len(projects) == 1:
        proj = projects[0]
        dirs = sorted(scopes[proj])
        return f"PATH CONTEXT: All files under \"{dirs[0]}/\". Project: {proj}.\n"

    all_dirs = sorted(d for ds in scopes.values() for d in ds)
    return f"PATH CONTEXT: Projects: {', '.join(projects)}. Dirs: {', '.join(d + '/' for d in all_dirs)}.\n"


# ---------------------------------------------------------------------------
# Config + git helpers
# ---------------------------------------------------------------------------

def resolve_provider(requested, config):
    """Force the claude provider in repos whose remotes match CLAUDE_ONLY_REMOTES."""
    patterns = [p.strip() for p in config.get("CLAUDE_ONLY_REMOTES", "").split(",") if p.strip()]
    remotes, _, _ = run(["git", "remote", "-v"])
    match = next((p for p in patterns if p in remotes), None)
    if match is None:
        return requested or PROVIDER_OPENROUTER
    if requested == PROVIDER_OPENROUTER:
        exit_with_error(
            f"remote matches CLAUDE_ONLY_REMOTES ({match}): only --provider claude is allowed",
            {"pattern": match}
        )
    return PROVIDER_CLAUDE


def load_config(requested):
    if not CONFIG_PATH.exists():
        exit_with_error(
            f"config not found at {CONFIG_PATH}. Create it with OPENROUTER_API_KEY and MODEL",
            {"config_path": str(CONFIG_PATH)}
        )
    config = {}
    for line in CONFIG_PATH.read_text().splitlines():
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        key, _, value = line.partition("=")
        config[key.strip()] = value.strip().strip("\"'")

    provider = resolve_provider(requested, config)
    config["PROVIDER"] = provider
    if provider == PROVIDER_OPENROUTER:
        if "OPENROUTER_API_KEY" not in config:
            exit_with_error("OPENROUTER_API_KEY not set in config", {"config_path": str(CONFIG_PATH)})
        if "MODEL" not in config:
            exit_with_error("MODEL not set in config", {"config_path": str(CONFIG_PATH)})
    else:
        # MODEL is the one field the rest of the script reads for the model
        # name, so the claude model lands there too.
        config["MODEL"] = config.get("CLAUDE_MODEL", CLAUDE_DEFAULT_MODEL)
    return config


def run(cmd, check=False, timeout=60):
    try:
        result = subprocess.run(cmd, capture_output=True, timeout=timeout)
    except subprocess.TimeoutExpired:
        exit_with_error(
            f"command timed out after {timeout}s: {' '.join(cmd)}",
            {"command": " ".join(cmd), "timeout": timeout}
        )
    stdout = result.stdout.decode("utf-8", errors="replace")
    stderr = result.stderr.decode("utf-8", errors="replace")
    if check and result.returncode != 0:
        exit_with_error(
            f"command failed: {' '.join(cmd)}",
            {"command": " ".join(cmd), "stderr": stderr.strip(), "returncode": result.returncode}
        )
    return stdout, stderr, result.returncode


_PATHSPEC_EXCLUDES = [":(exclude)**/" + p for p in EXCLUDED_PATTERNS]


def build_pathspec_excludes():
    """Build git pathspec exclude args for lockfiles etc."""
    return _PATHSPEC_EXCLUDES


def _top(path):
    """Wrap a repo-root-relative path with :(top) so git resolves it from
    the repo root regardless of CWD."""
    return f":(top){path}"


_DIFF_NOISE_PREFIXES = ("index ", "similarity index ", "dissimilarity index ")


def strip_diff_noise(diff):
    """Remove noise lines from diff to save tokens."""
    return "\n".join(
        line for line in diff.splitlines()
        if not line.startswith(_DIFF_NOISE_PREFIXES)
    )


_DIFF_META_PREFIXES = ("rename ", "new file", "deleted file", "old mode", "new mode")


def strip_diff_context(diff):
    """Drop unified-diff context lines and the redundant ---/+++ header pair.

    Keeps the `diff --git` line, so file identity survives, plus hunk headers,
    every changed line and the rename/create/delete metadata. Only the copy
    sent to a model goes through this; everything that parses a diff for file
    paths or operations reads the original.

    Header and hunk body are tracked separately because a removed line can
    itself start with `---`, which is common in YAML and markdown. Inside a
    hunk every line is content, so there is nothing to disambiguate.
    """
    kept = []
    in_hunk = False
    for line in diff.splitlines():
        if line.startswith("diff --git"):
            in_hunk = False
            kept.append(line)
        elif line.startswith("@@"):
            in_hunk = True
            kept.append(line)
        elif not in_hunk:
            if line.startswith(_DIFF_META_PREFIXES):
                kept.append(line)
        elif line.startswith(("+", "-")):
            kept.append(line)
    return "\n".join(kept)


def get_diff():
    """Get diff for analysis, excluding lockfiles from LLM context.

    Only considers files in the current working directory and below.
    """
    excludes = build_pathspec_excludes()
    staged, _, _ = run(["git", "diff", "--cached", "--name-only", "--", "."])
    if staged.strip():
        diff, _, _ = run(["git", "diff", "--cached", "--minimal", "--", "."] + excludes)
        diff = strip_diff_noise(diff)
        if diff:
            return diff, "staged"
        # Staged files were all lockfiles/excluded — fall through to check unstaged
    diff, _, _ = run(["git", "diff", "--minimal", "--", "."])
    if not diff.strip():
        untracked, _, _ = run(["git", "ls-files", "--others", "--exclude-standard", "."])
        if not untracked.strip():
            return "", "none"
    run(["git", "add", "-A", "."], check=True)
    diff, _, _ = run(["git", "diff", "--cached", "--minimal", "--", "."] + excludes)
    return strip_diff_noise(diff), "all"


MAX_DIFF_CHARS = 20000
MAX_LINES_PER_HUNK = 15
MAX_HUNKS_PER_FILE = 5
# Below this many files, use the single-shot fast path (one LLM call) instead
# of the two-phase grouping pipeline. Single-shot is dramatically faster because
# it avoids a full round-trip before any parallel work can start.
LARGE_DIFF_FILES = 60
MAX_OUTPUT_TOKENS = 8192
# Cap on concurrent phase-2 LLM requests. Over HTTP these are pure I/O, so the
# cap exists only to protect OpenRouter from a single user hammering it. Each
# claude call is instead a CLI process holding ~450MB, so that cap is a memory
# budget and has to be far lower.
PHASE2_MAX_PARALLEL = {
    PROVIDER_OPENROUTER: 32,
    PROVIDER_CLAUDE: 4,
}
# Warn the user if a single LLM request takes longer than this many seconds.
SLOW_LLM_THRESHOLD_S = 15.0
# Beyond this many files, skip LLM entirely and use bulk commit
BULK_FILE_THRESHOLD = 200
# Maximum characters for phase 1 file summary before fallback
MAX_PHASE1_CHARS = 50000
# LLM retry attempts when files are missed
MAX_LLM_RETRIES = 3

BINARY_EXTENSIONS = {
    '.zip', '.tar', '.gz', '.bz2', '.xz', '.7z', '.rar',
    '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.avif',
    '.woff', '.woff2', '.ttf', '.eot', '.otf',
    '.pdf', '.doc', '.docx', '.xls', '.xlsx',
    '.exe', '.dll', '.so', '.dylib', '.o', '.a',
    '.pyc', '.class', '.jar',
    '.db', '.sqlite', '.sqlite3', '.bin', '.dat',
    '.mp3', '.mp4', '.avi', '.mov', '.wav',
    '.lockb',
}

# Budget for compressed diff (chars). ~100K tokens at ~4 chars/token.
MAX_COMPRESSED_CHARS = 400000


def is_binary_path(path):
    """Check if path has a known binary extension."""
    dot = path.rfind(".")
    return dot >= 0 and path[dot:].lower() in BINARY_EXTENSIONS


def extract_diff_path(header):
    """Extract file path from 'diff --git a/X b/Y' header."""
    if " b/" in header:
        return header.split(" b/", 1)[1]
    return ""


_LOCKFILE_SUFFIXES = tuple(p[1:] for p in EXCLUDED_PATTERNS if p.startswith("*"))
_LOCKFILE_NAMES = frozenset(p for p in EXCLUDED_PATTERNS if not p.startswith("*"))


def is_lockfile(path):
    """Check if a file path matches any lockfile pattern."""
    basename = path.rsplit("/", 1)[-1]
    if basename in _LOCKFILE_NAMES:
        return True
    return path.endswith(_LOCKFILE_SUFFIXES)


_GIT_ESCAPE_MAP = {
    '\\': ord('\\'), '"': ord('"'), 'n': ord('\n'), 't': ord('\t'),
    'a': ord('\a'), 'b': ord('\b'), 'f': ord('\f'), 'v': ord('\v'),
    'r': ord('\r'),
}


def git_unquote(path):
    """Decode git's C-style quoted path."""
    if not (path.startswith('"') and path.endswith('"')):
        return path
    inner = path[1:-1]
    result = bytearray()
    i = 0
    while i < len(inner):
        if inner[i] == '\\' and i + 1 < len(inner):
            c = inner[i + 1]
            if c in '01234567' and i + 3 < len(inner):
                result.append(int(inner[i + 1:i + 4], 8))
                i += 4
            elif c in _GIT_ESCAPE_MAP:
                result.append(_GIT_ESCAPE_MAP[c])
                i += 2
            else:
                result.extend(inner[i].encode('utf-8'))
                i += 1
        else:
            result.extend(inner[i].encode('utf-8'))
            i += 1
    return result.decode('utf-8')


def get_staged_files_for_commit():
    """Get actual staged files that can be committed (excluding lockfiles).

    Only includes files in the current working directory and below.
    Returns dict mapping path -> {old_path, is_deleted}
    """
    name_status, _, _ = run(["git", "diff", "--cached", "--name-status", "-M", "--", "."])
    files = {}
    for line in name_status.strip().splitlines():
        if not line:
            continue
        parts = line.split("\t")
        if len(parts) < 2:
            continue
        status = parts[0]
        if status.startswith("R") and len(parts) >= 3:  # Rename: R100\told\tnew
            old_path = git_unquote(parts[1])
            new_path = git_unquote(parts[2])
            if not is_lockfile(new_path):
                files[new_path] = {"old": old_path, "deleted": False}
        elif status == "D":  # Deleted
            path = git_unquote(parts[1])
            if not is_lockfile(path):
                files[path] = {"old": path, "deleted": True}
        else:  # Added, Modified, etc
            path = git_unquote(parts[1])
            if not is_lockfile(path):
                files[path] = {"old": path, "deleted": False}
    return files


def normalize_llm_files(llm_files, staged_files):
    """Map LLM file paths to actual staged paths."""
    if not isinstance(llm_files, list):
        return []
    old_to_new = {info["old"]: path for path, info in staged_files.items()}
    normalized = set()
    dropped = []
    for f in llm_files:
        if not isinstance(f, str):
            continue
        f = f.lstrip("/")
        if f.startswith("a/") or f.startswith("b/"):
            f = f[2:]
        if f in staged_files:
            normalized.add(f)
        elif f in old_to_new:
            normalized.add(old_to_new[f])
        else:
            dropped.append(f)
    if dropped:
        log("INFO", "LLM referenced unknown files", {"dropped": dropped})
    return list(normalized)


def is_file_deleted(path, staged_files):
    """Check if a file is marked as deleted in staged files."""
    info = staged_files.get(path)
    return info.get("deleted", False) if info else False


def is_echoing_keys(commit):
    """Check if commit has literal key strings instead of real values."""
    if not isinstance(commit, dict):
        return True
    files = commit.get("files")
    message = commit.get("message")
    description = commit.get("description")

    if files is None:
        return True
    if isinstance(files, str) and files in ("files", "[]", "", "file"):
        return True
    if isinstance(files, list) and len(files) == 0:
        return True

    if message is None:
        return True
    if isinstance(message, str) and message.lower() in ("message", "", "commit message", "msg"):
        return True

    if isinstance(description, str) and description.lower() == "description":
        return True

    return False


_VALID_TYPES = {"feat", "fix", "refactor", "chore", "docs", "style", "test", "perf"}


def _clean_commit_message(message):
    """Clean up LLM-generated commit message for quality."""
    message = message.strip().rstrip(".")
    # Truncate to 72 chars (git convention for subject line)
    if len(message) > 72:
        message = message[:69] + "..."
    return message


_SCOPE_RE = re.compile(r'^(\w+)(?:\(([^)]*)\))?:\s*(.*)')


def _ensure_grounded_scope(commit):
    """If the LLM produced a message with no scope, derive one from file paths."""
    msg = commit.get("message", "")
    m = _SCOPE_RE.match(msg)
    if not m:
        return commit
    type_, scope, subject = m.groups()
    if scope:
        return commit
    files = commit.get("files", [])
    if not files:
        return commit
    scopes = set()
    for f in files:
        s = _dir_scope(f)
        if s:
            scopes.add(s)
    if len(scopes) == 1:
        scope = scopes.pop()
        commit["message"] = f"{type_}({scope}): {subject}"
    return commit


def validate_and_fix_commits(commits, staged_files):
    """Validate LLM output and fix issues.

    Returns (fixed_commits, missing_files_set).
    missing_files_set is empty when all staged files are covered.
    """
    # Detect key-echoing pattern (model failure)
    echo_count = sum(1 for c in commits if is_echoing_keys(c))
    if echo_count > 0 and echo_count == len(commits):
        exit_with_error(
            f"LLM returned malformed commits (echoing keys: {echo_count}/{len(commits)})",
            {"commits_sample": commits[:3]}
        )

    all_staged = set(staged_files.keys())
    covered_files = set()
    fixed_commits = []

    for commit in commits:
        if not isinstance(commit, dict):
            warn(f"skipping non-dict commit: {commit}")
            continue
        if "files" not in commit or "message" not in commit:
            warn(f"skipping malformed commit: {commit}")
            continue

        normalized = normalize_llm_files(commit["files"], staged_files)
        if not normalized:
            warn(f"skipping commit with no valid files: {commit.get('message', '<missing>')}")
            continue

        covered_files.update(normalized)
        fixed = {
            "files": normalized,
            "message": _clean_commit_message(commit["message"]),
            "description": commit.get("description", ""),
        }
        fixed_commits.append(_ensure_grounded_scope(fixed))

    if not fixed_commits:
        # No valid commits at all - create a fallback single commit
        warn("LLM failed to group files, creating single commit")
        return [{
            "files": list(all_staged),
            "message": "chore: update files",
            "description": "",
        }], set()

    missing_files = all_staged - covered_files
    return fixed_commits, missing_files


def get_diff_for_files(files):
    """Get the diff for specific files only (fresh from git).

    Kept for callers that don't have a parsed diff cache to hand. The
    hot path in phase 2 uses ``slice_diff_by_file`` against an in-memory
    cache built via ``parse_diff_by_file``.
    """
    diff, _, _ = run(["git", "diff", "--cached", "--minimal", "--"] + [_top(f) for f in files])
    return strip_diff_noise(diff)


def parse_diff_by_file(diff):
    """Split a unified diff into a dict of {file_path: section_text}.

    Each section includes its ``diff --git`` header so downstream code can
    treat it as a self-contained mini-diff.
    """
    sections = {}
    current_path = None
    current_lines = []
    for line in diff.splitlines():
        if line.startswith("diff --git"):
            if current_path is not None:
                sections[current_path] = "\n".join(current_lines)
            current_path = extract_diff_path(line)
            current_lines = [line]
        elif current_path is not None:
            current_lines.append(line)
    if current_path is not None:
        sections[current_path] = "\n".join(current_lines)
    return sections


def slice_diff_by_file(diff_by_file, files):
    """Return a concatenated diff for ``files`` from the parsed cache."""
    return "\n".join(diff_by_file[f] for f in files if f in diff_by_file)


def compress_diff(diff, max_chars=None):
    """Compress diff while preserving semantic information.

    Respects a total character budget, skips binary files, and enforces
    per-file limits so the result fits within LLM context windows.
    """
    if max_chars is None:
        max_chars = MAX_COMPRESSED_CHARS

    excludes = build_pathspec_excludes()
    stat, _, _ = run(["git", "diff", "--cached", "--stat", "--", "."] + excludes)

    parts = [f"DIFF STAT:\n{stat}"]

    header_chars = sum(len(p) for p in parts) + 50
    remaining = max_chars - header_chars
    if remaining <= 0:
        return "\n".join(parts)

    # Parse diff into per-file sections
    file_sections = []
    current_header = None
    current_lines = []
    for line in diff.splitlines():
        if line.startswith("diff --git"):
            if current_header:
                file_sections.append((current_header, current_lines))
            current_header = line
            current_lines = []
        elif current_header:
            current_lines.append(line)
    if current_header:
        file_sections.append((current_header, current_lines))

    if not file_sections:
        return "\n".join(parts)

    parts.append("COMPRESSED PATCHES:")
    total_chars = 0
    files_truncated = 0

    n_files = len(file_sections)
    for file_idx, (file_header, lines) in enumerate(file_sections):
        if total_chars >= remaining:
            files_truncated += 1
            continue

        path = extract_diff_path(file_header)

        # Skip binary files
        is_binary = any("Binary files" in l for l in lines[:5])
        if is_binary or is_binary_path(path):
            summary = f"{file_header}\n[binary file]"
            parts.append(summary)
            total_chars += len(summary)
            continue

        files_left = n_files - file_idx
        per_file_budget = (remaining - total_chars) // max(files_left, 1)

        file_parts = [file_header]
        file_chars = len(file_header)
        hunk_count = 0
        hunk_lines = 0
        hunk_truncated = False

        for line in lines:
            if file_chars >= per_file_budget:
                file_parts.append("[... file truncated]")
                break

            if line.startswith("@@") and " @@" in line:
                hunk_count += 1
                hunk_lines = 0
                hunk_truncated = False
                if hunk_count <= MAX_HUNKS_PER_FILE:
                    file_parts.append(line)
                    file_chars += len(line)
            elif hunk_count <= MAX_HUNKS_PER_FILE:
                if line.startswith("---") or line.startswith("+++"):
                    file_parts.append(line)
                    file_chars += len(line)
                elif line.startswith("rename ") or line.startswith("new file") or line.startswith("deleted file"):
                    file_parts.append(line)
                    file_chars += len(line)
                elif hunk_lines < MAX_LINES_PER_HUNK:
                    if line.startswith("+") or line.startswith("-"):
                        file_parts.append(line)
                        file_chars += len(line)
                        hunk_lines += 1
                    elif line.startswith(" ") and hunk_lines < MAX_LINES_PER_HUNK // 2:
                        file_parts.append(line)
                        file_chars += len(line)
                        hunk_lines += 1
                elif not hunk_truncated:
                    file_parts.append("[... hunk truncated]")
                    hunk_truncated = True

        if hunk_count > MAX_HUNKS_PER_FILE:
            file_parts.append(f"[... {hunk_count - MAX_HUNKS_PER_FILE} more hunks truncated]")

        parts.extend(file_parts)
        total_chars += file_chars

    if files_truncated > 0:
        parts.append(f"[... {files_truncated} more files truncated]")

    return "\n".join(parts)


def prepare_diff_for_llm(config, diff, max_chars=None):
    """Shrink a diff down to what a model needs to read."""
    if config["PROVIDER"] == PROVIDER_CLAUDE:
        diff = strip_diff_context(diff)
    if len(diff) <= MAX_DIFF_CHARS:
        return diff
    return compress_diff(diff, max_chars=max_chars)


RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
MAX_RETRIES = 3


class ContextLengthExceeded(Exception):
    """Raised when LLM context length is exceeded."""


def try_repair_json(content):
    """Attempt to repair truncated or malformed JSON arrays/objects."""
    content = content.strip()

    # Strip leading garbage - find first [ or {
    start_idx = -1
    for i, c in enumerate(content):
        if c in '[{':
            start_idx = i
            break
    if start_idx > 0:
        content = content[start_idx:]

    # Strip trailing garbage - find last ] or }
    end_idx = -1
    for i in range(len(content) - 1, -1, -1):
        if content[i] in ']}':
            end_idx = i
            break
    if end_idx >= 0 and end_idx < len(content) - 1:
        content = content[:end_idx + 1]

    try:
        return json.loads(content)
    except json.JSONDecodeError:
        pass

    repairs = [
        '"}]',
        '"]}}]',
        '"}]}]',
        '"]',
        '"}',
        '}]',
        ']',
        '}',
        '"]}',
        '"],"hint":""}]',
    ]

    for repair in repairs:
        try:
            result = json.loads(content + repair)
            warn(f"repaired truncated JSON (appended: {repair})")
            return result
        except json.JSONDecodeError:
            continue

    for end_char in ['},', '],', '}', ']', '",']:
        idx = content.rfind(end_char)
        if idx > 0:
            truncated = content[:idx + len(end_char)]
            for close in [']', ']}', '}]', ']}]', '"]}', '"],"hint":""}]']:
                try:
                    result = json.loads(truncated + close)
                    warn("repaired truncated JSON by removing incomplete element")
                    return result
                except json.JSONDecodeError:
                    continue

    return None


class _LLMTransportError(Exception):
    """A provider failure worth retrying."""


LLM_WALL_CLOCK_TIMEOUT_S = 90


def _call_openrouter(config, system_prompt, user_content, start):
    """POST to OpenRouter and read the SSE stream.

    Returns (content, finish_reason, ttfb).
    """
    import requests

    use_structured = config.get("STRUCTURED_OUTPUT", "true").lower() == "true"
    request_body = {
        "model": config["MODEL"],
        "messages": [
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_content},
        ],
        "temperature": 0,
        "max_tokens": MAX_OUTPUT_TOKENS,
        "stream": True,
    }
    if use_structured:
        request_body["response_format"] = {"type": "json_object"}

    resp = None
    try:
        try:
            resp = requests.post(
                "https://openrouter.ai/api/v1/chat/completions",
                headers={
                    "Authorization": f"Bearer {config['OPENROUTER_API_KEY']}",
                    "Content-Type": "application/json",
                    "Accept": "text/event-stream",
                },
                json=request_body,
                timeout=(10, LLM_WALL_CLOCK_TIMEOUT_S),
                stream=True,
            )
        except requests.exceptions.RequestException as e:
            raise _LLMTransportError(str(e)) from e

        if resp.status_code != 200:
            text = resp.text
            if resp.status_code == 400 and "context length" in text.lower():
                log("INFO", "LLM context length exceeded", {"response": text[:300]})
                raise ContextLengthExceeded(text[:500])
            if resp.status_code in RETRYABLE_STATUS_CODES:
                raise _LLMTransportError(f"API returned {resp.status_code}")
            exit_with_error(
                f"LLM API returned {resp.status_code}",
                {"status_code": resp.status_code, "response": text[:500], "model": config["MODEL"]}
            )

        ttfb = None
        finish_reason = ""
        parts = []
        try:
            for raw_line in resp.iter_lines(decode_unicode=True):
                if not raw_line or raw_line.startswith(":"):
                    continue
                if not raw_line.startswith("data:"):
                    continue
                data = raw_line[5:].lstrip()
                if data == "[DONE]":
                    break
                if ttfb is None:
                    ttfb = time.monotonic() - start
                try:
                    chunk = json.loads(data)
                except json.JSONDecodeError:
                    continue
                choices = chunk.get("choices") or []
                if not choices:
                    continue
                delta = choices[0].get("delta") or {}
                piece = delta.get("content")
                if piece:
                    parts.append(piece)
                fr = choices[0].get("finish_reason")
                if fr:
                    finish_reason = fr
                if time.monotonic() - start > LLM_WALL_CLOCK_TIMEOUT_S:
                    raise _LLMTransportError(f"no response within {LLM_WALL_CLOCK_TIMEOUT_S}s")
        except requests.exceptions.RequestException as e:
            raise _LLMTransportError(str(e)) from e
        return "".join(parts), finish_reason, ttfb
    finally:
        if resp is not None:
            resp.close()


# --safe-mode drops CLAUDE.md, skills, plugins, hooks and MCP servers, none of
# which this prompt wants, and leaves subscription auth working. --bare goes
# further but forces ANTHROPIC_API_KEY, which defeats the point of running
# through the CLI at all.
CLAUDE_CLI_ARGS = [
    "-p",
    "--safe-mode",
    "--strict-mcp-config",
    "--tools", "",
    "--no-session-persistence",
    "--output-format", "json",
]


def _call_claude_cli(config, system_prompt, user_content, start):
    """Run the Claude Code CLI non-interactively.

    Returns (content, finish_reason, ttfb).
    """
    cmd = ["claude", *CLAUDE_CLI_ARGS, "--model", config["MODEL"],
           "--system-prompt", system_prompt]
    try:
        result = subprocess.run(
            cmd,
            input=user_content.encode(),
            capture_output=True,
            timeout=LLM_WALL_CLOCK_TIMEOUT_S,
        )
    except subprocess.TimeoutExpired as e:
        raise _LLMTransportError(f"claude cli timed out after {LLM_WALL_CLOCK_TIMEOUT_S}s") from e
    except FileNotFoundError:
        exit_with_error(
            "claude cli not found on PATH",
            {"provider": PROVIDER_CLAUDE}
        )

    stdout = result.stdout.decode("utf-8", errors="replace")
    stderr = result.stderr.decode("utf-8", errors="replace")
    # The CLI reports its own failures as a JSON envelope on stdout, so parse
    # before deciding what went wrong. stderr is usually empty.
    try:
        envelope = json.loads(stdout)
    except json.JSONDecodeError:
        detail = (stderr or stdout).strip()[:300]
        raise _LLMTransportError(f"claude cli exited {result.returncode}: {detail}")

    if result.returncode != 0 or envelope.get("is_error"):
        detail = str(envelope.get("result") or stderr).strip()[:300]
        if "prompt is too long" in detail.lower():
            log("INFO", "LLM context length exceeded", {"detail": detail})
            raise ContextLengthExceeded(detail)
        status = envelope.get("api_error_status")
        if status and status not in RETRYABLE_STATUS_CODES:
            exit_with_error(
                f"claude cli failed: {detail}",
                {"api_error_status": status, "model": config["MODEL"]}
            )
        raise _LLMTransportError(detail or f"claude cli exited {result.returncode}")

    ttft_ms = envelope.get("ttft_ms")
    ttfb = ttft_ms / 1000 if ttft_ms else None
    # The rest of this module speaks OpenAI's name for truncation.
    finish_reason = "length" if envelope.get("stop_reason") == "max_tokens" else ""
    return envelope.get("result", ""), finish_reason, ttfb


PROVIDER_CALLERS = {
    PROVIDER_OPENROUTER: _call_openrouter,
    PROVIDER_CLAUDE: _call_claude_cli,
}


def call_llm_raw(config, system_prompt, user_content, task_label=None):
    """Make an LLM call and return parsed JSON.

    Records TTFB where the provider reports it and warns when a single
    request is unusually slow. ``task_label`` is used in warning messages
    and logs so it's obvious which group is slow.
    """
    call_provider = PROVIDER_CALLERS[config["PROVIDER"]]
    label = task_label or "llm"
    content = ""
    finish_reason = ""

    for attempt in range(MAX_RETRIES):
        start = time.monotonic()
        _timings.request_started()
        try:
            content, finish_reason, ttfb = call_provider(
                config, system_prompt, user_content, start
            )
            duration = time.monotonic() - start
            _timings.request_finished(duration)
            log("INFO", "llm done", {
                "task": label,
                "ttfb_ms": int((ttfb or duration) * 1000),
                "duration_ms": int(duration * 1000),
                "chars": len(content),
            })
            if duration >= SLOW_LLM_THRESHOLD_S:
                warn(f"slow LLM response: {label} took {duration:.1f}s")
            break
        except _LLMTransportError as e:
            _timings.request_finished(time.monotonic() - start)
            if attempt < MAX_RETRIES - 1:
                wait_time = 2 ** attempt
                warn(f"LLM request failed: {e}, retrying in {wait_time}s (attempt {attempt + 1}/{MAX_RETRIES})")
                time.sleep(wait_time)
                continue
            exit_with_error(
                f"LLM API request failed after {MAX_RETRIES} attempts: {e}",
                {"model": config["MODEL"], "attempts": MAX_RETRIES}
            )

    content = content.strip()
    if content.startswith("```"):
        content = "\n".join(content.split("\n")[1:])
    if content.endswith("```"):
        content = "\n".join(content.split("\n")[:-1])
    content = content.strip()

    if finish_reason == "length":
        warn("LLM response was truncated due to length limit")
    if not content:
        record_error("LLM returned empty response", {"model": config["MODEL"]})
        return []

    try:
        return json.loads(content)
    except json.JSONDecodeError:
        pass

    repaired = try_repair_json(content)
    if repaired is not None:
        return repaired

    record_error(
        "LLM returned unparseable JSON",
        {"content": content[:1000], "model": config["MODEL"]}
    )
    return []


def is_malformed_response(result):
    """Check if response is clearly malformed (key echoing or invalid structure)."""
    if not isinstance(result, list):
        return True
    if not result:
        return True
    echo_count = sum(1 for r in result if is_echoing_keys(r))
    return echo_count > len(result) // 2


def normalize_llm_result(result):
    """Normalize LLM result to a list of commits."""
    if isinstance(result, list):
        return result
    if isinstance(result, dict):
        if "commits" in result:
            return result["commits"]
        if "groups" in result:
            return result["groups"]
        if "files" in result and "message" in result:
            return [result]
    return []


def call_llm(config, diff, missing_hint=None, staged_files=None):
    """Single-phase: send diff and get commits.

    missing_hint: set of file paths the LLM missed on a previous attempt.
    staged_files: dict of staged file paths (used for path context).
    """
    prompts = PROMPTS[config["PROVIDER"]]
    content = prepare_diff_for_llm(config, diff)
    path_ctx = compute_path_context(staged_files.keys()) if staged_files else ""
    if path_ctx:
        content = path_ctx + "\n" + content
    if missing_hint:
        hint_line = "IMPORTANT: You previously missed these files — they MUST be included: " + ", ".join(sorted(missing_hint))
        content = hint_line + "\n\n" + content
    log("INFO", "sending diff to LLM", {"chars": len(content), "compressed": len(diff) > MAX_DIFF_CHARS})
    result = call_llm_raw(config, prompts["system"], content, task_label="single-shot")
    result = normalize_llm_result(result)

    if is_malformed_response(result):
        warn("response looks malformed, retrying with stronger prompt")
        retry_content = compress_diff(diff) if len(diff) > MAX_DIFF_CHARS // 2 else content
        result = call_llm_raw(config, prompts["retry"], retry_content, task_label="single-shot-retry")
        result = normalize_llm_result(result)

    return result


def detect_directory_moves(staged_files):
    """Detect directory-level rename/move operations."""
    transforms = defaultdict(list)

    for path, info in staged_files.items():
        old_path = info.get("old", path)
        if old_path == path or info.get("deleted"):
            continue

        old_parts = old_path.split("/")
        new_parts = path.split("/")

        common_suffix_len = 0
        for i in range(1, min(len(old_parts), len(new_parts)) + 1):
            if old_parts[-i] == new_parts[-i]:
                common_suffix_len = i
            else:
                break

        if common_suffix_len > 0:
            old_prefix = "/".join(old_parts[:-common_suffix_len])
            new_prefix = "/".join(new_parts[:-common_suffix_len])
        else:
            old_prefix = "/".join(old_parts[:-1])
            new_prefix = "/".join(new_parts[:-1])

        transforms[(old_prefix, new_prefix)].append(path)

    return {
        new_prefix: (old_prefix, files)
        for (old_prefix, new_prefix), files in transforms.items()
        if len(files) >= 3
    }


def summarize_file_operations(staged_files):
    """Analyze staged files and return high-level operation summaries."""
    operations = []
    handled_files = set()

    dir_moves = detect_directory_moves(staged_files)
    for new_prefix, (old_prefix, files) in sorted(dir_moves.items(), key=lambda x: -len(x[1])):
        files = [f for f in files if f not in handled_files]
        if len(files) < 3:
            continue

        handled_files.update(files)
        old_name = old_prefix.split("/")[-1] if old_prefix else "files"
        new_name = new_prefix.split("/")[-1] if new_prefix else "root"

        if old_prefix and new_prefix:
            if old_name == new_name:
                msg = f"refactor: move {old_prefix}/ to {new_prefix}/"
            else:
                msg = f"refactor: rename {old_prefix}/ to {new_prefix}/"
        elif new_prefix:
            msg = f"refactor: move files into {new_prefix}/"
        else:
            msg = f"refactor: move {old_prefix}/ to root"

        operations.append({
            "files": files,
            "message": msg,
            "description": f"{len(files)} files moved"
        })

    remaining = {p: info for p, info in staged_files.items() if p not in handled_files}

    by_op_and_dir = defaultdict(lambda: defaultdict(list))
    for path, info in remaining.items():
        if info.get("deleted"):
            op = "delete"
        elif info.get("old") != path:
            op = "rename"
        else:
            op = "change"

        dir_key = _dir_scope(path) or "root"
        by_op_and_dir[op][dir_key].append(path)

    op_templates = [
        ("delete",  "chore({scope}): remove {dir}/",            "chore({scope}): remove {file}",            "deleted"),
        ("change",  "chore({scope}): update {dir}/",             "chore({scope}): update {file}",            "changed"),
        ("rename",  "refactor({scope}): rename files in {dir}/", "refactor({scope}): rename {file}",         "renamed"),
    ]
    for op_key, bulk_tmpl, single_tmpl, verb in op_templates:
        for dir_key, files in by_op_and_dir[op_key].items():
            scope = dir_key if dir_key != "root" else ""
            if len(files) >= 3:
                msg = bulk_tmpl.format(scope=scope, dir=dir_key) if scope else bulk_tmpl.replace("({scope})", "").format(dir=dir_key)
                operations.append({
                    "files": files,
                    "message": msg,
                    "description": f"{len(files)} files {verb}"
                })
                handled_files.update(files)
            else:
                for f in files:
                    label = _smart_path_label(f)
                    msg = single_tmpl.format(scope=scope, file=label) if scope else single_tmpl.replace("({scope})", "").format(file=label)
                    operations.append({
                        "files": [f],
                        "message": msg,
                        "description": ""
                    })
                    handled_files.add(f)

    return operations


def group_files_by_directory(staged_files):
    """Smart grouping that detects directory-level operations."""
    operations = summarize_file_operations(staged_files)
    if operations:
        return operations
    return [{
        "files": list(staged_files.keys()),
        "message": "chore: update files",
        "description": f"{len(staged_files)} files changed"
    }]


def _smart_fallback_commits(normalized, staged_files):
    """Generate commits from smart file analysis when LLM fails."""
    group_staged = {f: staged_files[f] for f in normalized if f in staged_files}
    smart_ops = summarize_file_operations(group_staged)
    if smart_ops:
        return [{"files": op["files"], "message": op["message"], "description": op.get("description", "")} for op in smart_ops]
    if normalized:
        return [{"files": list(normalized), "message": "chore: update files", "description": ""}]
    return []


def _phase2_plan(config, n_files, hint):
    """Pick the phase 2 prompt, plus the body to use if the model writes none.

    A one-file group gets the subject-only prompt on claude. Writing the body
    is most of the cost of a call there, and phase 1 already described the
    group, so its hint becomes the body instead.
    """
    prompts = PROMPTS[config["PROVIDER"]]
    if config["PROVIDER"] == PROVIDER_CLAUDE and n_files == 1:
        return prompts["phase2_subject"], hint
    return prompts["phase2"], ""


def call_llm_two_phase(config, diff, staged_files, missing_hint=None):
    """Two-phase approach for large diffs with many files.

    ``diff`` is the already-computed unified diff; we parse it once into a
    per-file cache so phase-2 group slicing is an in-memory dict lookup
    instead of re-running ``git diff`` per group.
    """
    excludes = build_pathspec_excludes()
    name_status, _, _ = run(["git", "diff", "--cached", "--name-status", "-M", "--", "."] + excludes)
    stat, _, _ = run(["git", "diff", "--cached", "--stat", "--", "."] + excludes)
    diff_by_file = parse_diff_by_file(diff)

    path_ctx = compute_path_context(staged_files.keys())
    phase1_content = f"{path_ctx}FILE CHANGES:\n{name_status}\nSTATISTICS:\n{stat}"
    if missing_hint:
        hint_line = "IMPORTANT: You previously missed these files — include ALL of them: " + ", ".join(sorted(missing_hint))
        phase1_content = hint_line + "\n\n" + phase1_content

    if len(phase1_content) > MAX_PHASE1_CHARS:
        warn(f"file summary too large ({len(phase1_content)} chars), grouping by directory instead")
        log("INFO", "skipping LLM phase 1 due to size", {"chars": len(phase1_content)})
        groups = group_files_by_directory(staged_files)
    else:
        log("INFO", "phase 1: sending file summary to LLM", {"chars": len(phase1_content)})
        if _spinner:
            _spinner.set(f"Grouping files ({len(staged_files)})")
        try:
            groups = call_llm_raw(config, PHASE1_PROMPT, phase1_content, task_label="phase1-grouping")
        except ContextLengthExceeded:
            warn("LLM context length exceeded, falling back to directory grouping")
            groups = group_files_by_directory(staged_files)

    if isinstance(groups, dict):
        groups = groups.get("groups", groups.get("commits", []))

    if not isinstance(groups, list):
        warn(f"phase 1 returned non-list ({type(groups).__name__}), using smart grouping")
        groups = group_files_by_directory(staged_files)

    if not groups:
        groups = group_files_by_directory(staged_files)

    # Separate groups that already have messages from those needing LLM
    commits = []
    llm_tasks = []  # (index, normalized_files)

    for i, group in enumerate(groups):
        if not isinstance(group, dict):
            continue
        files = group.get("files", [])
        if not files:
            continue

        if group.get("message"):
            normalized = normalize_llm_files(files, staged_files) if isinstance(files[0], str) else files
            if normalized:
                commits.append((i, {
                    "files": normalized,
                    "message": group["message"],
                    "description": group.get("description", ""),
                }))
            continue

        normalized = normalize_llm_files(files, staged_files)
        if not normalized:
            continue

        group_diff = slice_diff_by_file(diff_by_file, normalized)
        if not group_diff.strip():
            # Fall back to shelling out if the file wasn't in the parsed
            # cache (e.g. encoding edge cases). Rare.
            group_diff = get_diff_for_files(normalized)
        if not group_diff.strip():
            continue

        content = prepare_diff_for_llm(config, group_diff, max_chars=30000)
        group_ctx = compute_path_context(normalized)
        if group_ctx:
            content = group_ctx + "\n" + content
        hint = group.get("hint") if isinstance(group.get("hint"), str) else ""
        prompt, fallback_description = _phase2_plan(config, len(normalized), hint)
        llm_tasks.append((i, normalized, content, prompt, fallback_description))

    # Run all phase 2 LLM calls in parallel
    if llm_tasks:
        total_tasks = len(llm_tasks)
        done_count = [0]
        log("INFO", "phase 2: sending groups to LLM in parallel", {"groups": total_tasks})

        def _phase2_msg():
            snap = _timings.snapshot()
            done = done_count[0]
            inflight = snap["inflight"]
            recent = snap["durations"][-10:]
            avg = sum(recent) / len(recent) if recent else 0.0
            remaining = total_tasks - done
            if avg and inflight and remaining > 0:
                eta = avg * remaining / max(inflight, 1)
                eta_str = f" · ~{eta:.0f}s left"
            else:
                eta_str = ""
            slowest = f" · slowest {max(recent):.0f}s" if recent else ""
            return (
                f"Writing commit messages {done}/{total_tasks}"
                f" · {inflight} in flight{eta_str}{slowest}"
            )

        if _spinner:
            _spinner.set_dynamic(_phase2_msg)

        def _phase2_call(task):
            idx, normalized, content, prompt, fallback_description = task
            log("INFO", "phase 2: sending diff to LLM", {"group": idx + 1, "chars": len(content), "files": len(normalized)})
            try:
                result = call_llm_raw(
                    config, prompt, content, task_label=f"group {idx + 1}"
                )
            except ContextLengthExceeded:
                return (idx, "context_exceeded", normalized, fallback_description)
            return (idx, result, normalized, fallback_description)

        max_parallel = PHASE2_MAX_PARALLEL[config["PROVIDER"]]
        with ThreadPoolExecutor(max_workers=min(total_tasks, max_parallel)) as executor:
            futures = {executor.submit(_phase2_call, t): t for t in llm_tasks}
            for future in as_completed(futures):
                done_count[0] += 1
                idx, result, normalized, fallback_description = future.result()

                if result == "context_exceeded":
                    warn(f"context length exceeded for group {idx + 1}, using smart analysis")
                    commits.extend((idx, c) for c in _smart_fallback_commits(normalized, staged_files))
                    continue

                if isinstance(result, list) and len(result) > 0:
                    result = result[0]
                if not isinstance(result, dict):
                    warn(f"phase 2 returned non-dict for group {idx + 1}, using smart analysis")
                    commits.extend((idx, c) for c in _smart_fallback_commits(normalized, staged_files))
                    continue

                message = result.get("message")
                if not message or message.lower() in ("message", ""):
                    warn(f"phase 2 missing message for group {idx + 1}, using smart analysis")
                    fallback = _smart_fallback_commits(normalized, staged_files)
                    if fallback:
                        commits.extend((idx, c) for c in fallback)
                        continue
                    message = f"chore: update {len(normalized)} files"

                description = result.get("description", "")
                if description.lower() == "description":
                    description = ""
                if not description:
                    description = fallback_description

                commits.append((idx, _ensure_grounded_scope({"files": normalized, "message": _clean_commit_message(message), "description": description})))

    # Sort by original group index to preserve logical ordering
    commits.sort(key=lambda x: x[0])
    return [c for _, c in commits]


def get_lockfiles_in_staging():
    """Get list of lockfiles that are staged in the current directory and below."""
    staged, _, _ = run(["git", "diff", "--cached", "--name-only", "--", "."])
    return [git_unquote(f) for f in staged.strip().splitlines() if f and is_lockfile(git_unquote(f))]


# ---------------------------------------------------------------------------
# Display helpers
# ---------------------------------------------------------------------------

def _fmt_files(files, limit=4):
    """Format a file list compactly for display."""
    shown = sorted(files)[:limit]
    result = ", ".join(_dim(f) for f in shown)
    if len(files) > limit:
        result += _dim(f" +{len(files) - limit} more")
    return result


def _print_commit_plan(commits, lockfiles):
    """Print a numbered plan of all commits about to be made."""
    all_entries = list(commits)
    if lockfiles:
        all_entries.append({
            "message": "chore: update lockfiles",
            "description": "",
            "files": lockfiles,
        })

    sprint("")
    sprint(_dim("  Planned commits:"))
    sprint(_dim("  " + "─" * 58))
    for i, c in enumerate(all_entries, 1):
        msg = c["message"]
        desc = c.get("description", "")
        files = c.get("files", [])
        sprint(f"  {_dim(f'{i:2d}')}  {msg}")
        if desc:
            sprint(f"       {_dim(desc)}")
        sprint(f"       {_fmt_files(files)}")
    sprint(_dim("  " + "─" * 58))
    sprint("")


# ---------------------------------------------------------------------------
# Housekeeping
# ---------------------------------------------------------------------------

KEEP_LOGS = 50


def _prune_old_logs():
    """Delete session log files beyond the most recent KEEP_LOGS."""
    if not LOGS_DIR.exists():
        return
    logs = sorted(LOGS_DIR.glob("session_*.log"))
    for old in logs[:-KEEP_LOGS]:
        try:
            old.unlink()
        except OSError:
            pass


# ---------------------------------------------------------------------------
# Main — extracted phases
# ---------------------------------------------------------------------------

def generate_commit_plan(config, args, diff, staged_files):
    """Generate commit plan via LLM or bulk analysis. Returns list of commits."""
    file_count = len(staged_files)

    if args.bulk or file_count > BULK_FILE_THRESHOLD:
        mode = "--bulk flag" if args.bulk else f"{file_count} files"
        _spinner.set(f"Grouping files ({mode})...")
        commits = group_files_by_directory(staged_files)
        _spinner.ok(f"Planned {len(commits)} commit{'s' if len(commits) != 1 else ''} (bulk)")
        return commits

    missing_hint = None
    commits = None

    for attempt in range(1, MAX_LLM_RETRIES + 1):
        if file_count > LARGE_DIFF_FILES:
            _spinner.set(f"Grouping files ({file_count})")
            raw_commits = call_llm_two_phase(config, diff, staged_files, missing_hint=missing_hint)
        else:
            label = f"Analysing {file_count} files"
            if attempt > 1:
                label += f" (retry {attempt}/{MAX_LLM_RETRIES})"
            _spinner.set(f"{label}...")
            try:
                raw_commits = call_llm(config, diff, missing_hint=missing_hint, staged_files=staged_files)
            except ContextLengthExceeded:
                warn("diff too large, using bulk mode")
                return group_files_by_directory(staged_files)

        commits, missing = validate_and_fix_commits(raw_commits, staged_files)

        if not missing:
            break

        log("INFO", "LLM missed files", {"attempt": attempt, "missed": sorted(missing)})

        if attempt < MAX_LLM_RETRIES:
            missing_hint = missing
            warn(f"LLM missed {len(missing)} file(s), retrying ({attempt}/{MAX_LLM_RETRIES})...")
        else:
            warn(f"LLM missed files after {MAX_LLM_RETRIES} attempts, falling back to bulk mode")
            log("INFO", "falling back to bulk mode after LLM retry exhaustion", {"missed": sorted(missing)})
            return group_files_by_directory(staged_files)

    n = len(commits)
    _spinner.ok(f"Planned {n} commit{'s' if n != 1 else ''}")
    return commits


def stage_files_for_commit(files, staged_files):
    """Stage files for a single commit. Returns list of successfully staged paths."""
    deleted = [f for f in files if is_file_deleted(f, staged_files)]
    to_add = [f for f in files if not is_file_deleted(f, staged_files)]
    added_files = []

    if to_add:
        _, stderr, code = run(["git", "add", "--"] + [_top(f) for f in to_add])
        if code == 0:
            added_files.extend(to_add)
            old_paths = [_top(staged_files[f]["old"]) for f in to_add
                         if staged_files.get(f, {}).get("old", f) != f]
            if old_paths:
                run(["git", "rm", "--cached", "--"] + old_paths)
        else:
            for f in to_add:
                _, stderr2, code2 = run(["git", "add", "--", _top(f)])
                if code2 != 0 and "ignored" in stderr2.lower():
                    _, stderr2, code2 = run(["git", "add", "-f", "--", _top(f)])
                if code2 == 0:
                    added_files.append(f)
                    old_path = staged_files.get(f, {}).get("old", f)
                    if old_path != f:
                        run(["git", "rm", "--cached", "--", _top(old_path)])
                else:
                    warn(f"could not stage {f}: {stderr2.strip()}")

    if deleted:
        _, stderr, code = run(["git", "rm", "--cached", "--"] + [_top(f) for f in deleted])
        if code == 0:
            added_files.extend(deleted)
        else:
            for f in deleted:
                _, stderr2, code2 = run(["git", "rm", "--cached", "--", _top(f)])
                if code2 == 0:
                    added_files.append(f)
                else:
                    warn(f"could not stage {f}: {stderr2.strip()}")

    return added_files


def execute_commits(commits, lockfiles, staged_files, no_verify):
    """Execute the commit plan. Returns list of failed commit messages."""
    run(["git", "reset", "HEAD", "--", "."], check=True)

    commit_args = ["git", "commit"]
    if no_verify:
        commit_args.append("--no-verify")

    failed_commits = []
    total = len(commits)

    for idx, commit in enumerate(commits, 1):
        files = commit["files"]
        message = commit["message"]
        description = commit.get("description", "")

        short_msg = message if len(message) <= 45 else message[:42] + "..."
        _spinner.set(f"Committing {idx}/{total}: {short_msg}")

        added_files = stage_files_for_commit(files, staged_files)

        skipped_files = [f for f in files if f not in added_files]
        if skipped_files:
            audit("stage_skip", {"message": message, "skipped": skipped_files})

        if not added_files:
            _spinner.warn(f"skipping (no files staged): {message}")
            audit("commit_skip", {"message": message, "files": files})
            continue

        staged_check, _, _ = run(["git", "diff", "--cached", "--name-only"])
        if not staged_check.strip():
            warn(f"nothing staged after git add, skipping: {message}")
            audit("commit_skip", {"message": message, "files": added_files, "reason": "nothing_staged"})
            continue

        commit_cmd = commit_args + ["-m", message]
        if description:
            commit_cmd += ["-m", description]
        stdout, stderr, code = run(commit_cmd)

        if code != 0:
            error_detail = stderr.strip() or stdout.strip()
            audit("commit_fail", {"message": message, "files": added_files, "stderr": stderr.strip(), "stdout": stdout.strip()})
            record_error(f"commit failed: {error_detail}", {"message": message, "files": added_files})
            _spinner.fail(f"FAILED: {message}")
            if error_detail:
                for line in error_detail.splitlines():
                    sprint(f"       {_dim(line)}", file=sys.stderr)
            if "hook" in (stderr + stdout).lower():
                sprint(f"       {_dim('hint: use --no-verify to bypass hooks')}", file=sys.stderr)
            failed_commits.append(message)
            continue

        audit("commit_ok", {"message": message, "files": added_files})
        log("INFO", "committed", {"message": message, "files": len(added_files)})
        _spinner.ok(message)

    if lockfiles:
        _spinner.set("Committing lockfiles...")
        run(["git", "add", "--"] + [_top(f) for f in lockfiles], check=True)
        staged_check, _, _ = run(["git", "diff", "--cached", "--name-only"])
        if staged_check.strip():
            _, stderr, code = run(commit_args + ["-m", "chore: update lockfiles"])
            if code != 0:
                if "hook" in stderr.lower():
                    exit_with_error(
                        "lockfile commit blocked by git hook. Use --no-verify to bypass",
                        {"lockfiles": lockfiles, "stderr": stderr}
                    )
                exit_with_error(
                    f"lockfile commit failed: {stderr}",
                    {"lockfiles": lockfiles, "stderr": stderr}
                )
            log("INFO", "committed lockfiles", {"count": len(lockfiles)})
            _spinner.ok("chore: update lockfiles")

    return failed_commits


def audit_remaining(staged_files, lockfiles, failed_commits):
    """Check for files that should have been committed but weren't."""
    remaining_staged, _, _ = run(["git", "diff", "--cached", "--name-only", "--", "."])
    remaining_unstaged, _, _ = run(["git", "diff", "--name-only", "--", "."])
    remaining_untracked, _, _ = run(["git", "ls-files", "--others", "--exclude-standard", "."])
    remaining = {
        "staged": [git_unquote(f) for f in remaining_staged.strip().splitlines() if f],
        "unstaged": [git_unquote(f) for f in remaining_unstaged.strip().splitlines() if f],
        "untracked": [git_unquote(f) for f in remaining_untracked.strip().splitlines() if f],
    }
    has_remaining = any(remaining.values())
    audit("finish", {"remaining": remaining, "clean": not has_remaining, "failed_commits": failed_commits})

    run_scope = set(staged_files.keys()) | set(lockfiles)
    all_remaining = set(remaining["staged"]) | set(remaining["unstaged"]) | set(remaining["untracked"])
    missed_from_run = all_remaining & run_scope
    if missed_from_run:
        warn(f"{len(missed_from_run)} files from this run still uncommitted (check {AUDIT_LOG})")


def push_to_remote():
    """Push commits to remote."""
    _spinner.set("Pushing...")
    _, stderr, code = run(["git", "push"], timeout=120)
    if code != 0:
        if "rejected" in stderr.lower() or "non-fast-forward" in stderr.lower():
            exit_with_error(
                "push rejected: remote has changes. Run 'git pull' first to sync",
                {"stderr": stderr}
            )
        if "no upstream" in stderr.lower() or "no configured push destination" in stderr.lower():
            exit_with_error(
                "push failed: no upstream branch. Run 'git push -u origin <branch>' first",
                {"stderr": stderr}
            )
        exit_with_error("push failed", {"stderr": stderr})
    log("INFO", "pushed to remote")
    _spinner.ok("Pushed")


def main():
    global _spinner

    parser = argparse.ArgumentParser(description="Fast commit with LLM-generated messages")
    parser.add_argument("--no-verify", action="store_true", help="bypass pre-commit hooks")
    parser.add_argument("--dry-run", action="store_true", help="preview commits without executing")
    parser.add_argument("--no-push", action="store_true", help="skip automatic push")
    parser.add_argument("--bulk", action="store_true", help="skip LLM, use smart file tree analysis (for large batches)")
    parser.add_argument("--provider", choices=PROVIDERS,
                        help="where to send prompts (default: openrouter, or claude in CLAUDE_ONLY_REMOTES repos)")
    args = parser.parse_args()

    log("INFO", "session started", {"dry_run": args.dry_run, "no_verify": args.no_verify, "no_push": args.no_push, "bulk": args.bulk, "provider": args.provider})
    log_git_state()
    _prune_old_logs()

    config = load_config(args.provider)
    log("INFO", "using model", {"provider": config["PROVIDER"], "model": config["MODEL"]})

    _, _, rc = run(["git", "rev-parse", "--git-dir"])
    if rc != 0:
        exit_with_error("not a git repository")

    _spinner = Spinner()
    try:
        _timings.phase_start("stage")
        _spinner.set(f"[{config['MODEL']}] Staging changes")
        diff, source = get_diff()
        if not diff:
            if source == "all":
                run(["git", "reset", "HEAD", "--", "."])
            _timings.phase_end("stage")
            sprint("nothing to commit")
            return

        staged_files = get_staged_files_for_commit()
        if not staged_files:
            if source == "all":
                run(["git", "reset", "HEAD", "--", "."])
            _timings.phase_end("stage")
            sprint("nothing to commit")
            return

        lockfiles = get_lockfiles_in_staging()
        file_count = len(staged_files)
        _spinner.ok(f"Staged {file_count} file{'s' if file_count != 1 else ''}")
        _timings.phase_end("stage")

        audit("start", {
            "source": source,
            "file_count": file_count,
            "files": sorted(staged_files.keys()),
            "lockfiles": lockfiles,
        })

        _timings.phase_start("plan")
        commits = generate_commit_plan(config, args, diff, staged_files)
        _timings.phase_end("plan")
        if not commits:
            exit_with_error("no valid commits generated", {"file_count": file_count})

        _print_commit_plan(commits, lockfiles)

        if args.dry_run:
            if source == "all":
                run(["git", "reset", "HEAD", "--", "."])
            audit("dry_run", {"commits": len(commits)})
            return

        _timings.phase_start("commit")
        failed_commits = execute_commits(commits, lockfiles, staged_files, args.no_verify)
        _timings.phase_end("commit")

        if failed_commits:
            warn(f"{len(failed_commits)} commit(s) failed: {', '.join(failed_commits)}")

        audit_remaining(staged_files, lockfiles, failed_commits)

        if args.no_push:
            sprint("done (push skipped)")
            return

        _timings.phase_start("push")
        push_to_remote()
        _timings.phase_end("push")
        log("INFO", "session completed successfully")
    finally:
        _spinner.stop()
        log("INFO", "timings", {"summary": _timings.summary_line()})
        sprint(_dim(f"  {_timings.summary_line()}"))


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        if _spinner:
            _spinner.stop()
        print("\ninterrupted", file=sys.stderr)
        sys.exit(130)