claude-dev-env 2.16.0 → 2.18.0

package/hooks/diagnostic/hook_log_extractor.py

@@ -1,875 +0,0 @@
-#!/usr/bin/env python3
-"""Extract hook-firing records from per-session JSONL transcripts into Neon.
-
-Reads JSONL transcripts at ``PROJECTS_TRANSCRIPT_ROOT`` and ingests only
-``attachment`` records whose inner ``attachment.type`` is one of the
-five variants enumerated in ``OUTCOME_BY_ATTACHMENT_TYPE``
-(``hook_success``, ``hook_blocking_error``, ``hook_non_blocking_error``,
-``hook_system_message``, ``hook_additional_context``). Unknown
-``hook_``-prefixed variants are skipped until
-``OUTCOME_BY_ATTACHMENT_TYPE`` is extended to cover them. Each ingested
-record becomes one row in the ``hook_events`` table. Idempotence is
-enforced at the database layer via a UNIQUE constraint on
-``(source_jsonl_path, source_line_number)`` combined with
-``ON CONFLICT DO NOTHING``. Per-file byte offsets in
-``OFFSET_STATE_FILE`` skip re-reading unchanged bytes.
-
-Offline graceful behavior: ``psycopg.OperationalError`` or any
-connect-time failure appends one ISO-8601 line to
-``OFFLINE_WARNING_LOG`` and exits 0, so the Stop hook never blocks
-session end on a missing network.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import datetime
-import errno
-import glob
-import io
-import json
-import os
-import re
-import sys
-import tempfile
-import time
-from pathlib import Path
-from typing import IO, Iterator, Optional, Sequence
-
-if os.name == "nt":
-    try:
-        import msvcrt
-    except ImportError:
-        msvcrt = None
-    fcntl = None
-else:
-    try:
-        import fcntl
-    except ImportError:
-        fcntl = None
-    msvcrt = None
-
-if str(Path(__file__).resolve().parent.parent) not in sys.path:
-    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-
-try:
-    import psycopg
-except ImportError:
-    psycopg = None
-
-from hooks_constants.hook_log_extractor_constants import (
-    ATTACHMENT_TYPE_HOOK_ADDITIONAL_CONTEXT,
-    ATTACHMENT_TYPE_HOOK_BLOCKING_ERROR,
-    ATTACHMENT_TYPE_HOOK_SUCCESS,
-    ATTACHMENT_TYPE_HOOK_SYSTEM_MESSAGE,
-    ATTACHMENT_TYPE_PREFIX,
-    BYTE_OFFSET_KEY,
-    CATEGORY_PATH_MINIMUM_PARTS,
-    COMMAND_EXCERPT_MAX_CHARACTERS,
-    CONNECT_TIMEOUT_SECONDS,
-    EMPTY_STRING,
-    EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING,
-    EXIT_CODE_SUCCESS,
-    EXIT_CODE_UNKNOWN_QUERY,
-    HOOK_CATEGORY_UNCATEGORIZED,
-    HOOK_EVENTS_INSERT_SQL,
-    HOOK_EVENTS_TRUNCATE_SQL,
-    HOOK_NAME_TOOL_SEPARATOR,
-    HOOKS_DIRECTORY_TOKEN,
-    INSERT_BATCH_SIZE,
-    INVALID_QUERY_NAME_MESSAGE_PREFIX,
-    JSONL_FILE_GLOB,
-    KNOWN_HOOK_CATEGORIES,
-    LEGACY_OFFSETS_FORMAT_WARNING_LABEL,
-    LINE_NUMBER_KEY,
-    LOCK_MAXIMUM_RETRY_COUNT,
-    LOCK_RETRY_SLEEP_SECONDS,
-    MISSING_NEON_DATABASE_URL_WARNING_LABEL,
-    MISSING_PSYCOPG_WARNING_LABEL,
-    NEON_DATABASE_URL_ENVIRONMENT_VARIABLE,
-    NEWLINE_JOINER,
-    OFFLINE_WARNING_LOG,
-    OFFSETS_JSON_INDENT,
-    OUTCOME_BY_ATTACHMENT_TYPE,
-    QUERIES_DIRECTORY_NAME,
-    QUERY_NAME_PATTERN,
-    QUERY_NO_ROWS_RETURNED_MESSAGE,
-    SCRIPT_PATH_PYTHON_PREFIXES,
-    SQL_FILE_EXTENSION,
-    STDERR_EXCERPT_MAX_CHARACTERS,
-    STDOUT_EXCERPT_MAX_CHARACTERS,
-    SUMMARY_COLUMN_HEADINGS,
-    SUMMARY_ZERO_BLOCKED_EVENTS_MESSAGE,
-    SUMMARY_TABLE_COLUMN_GAP,
-    TOP_BLOCKED_COMMAND_PREVIEW_MAX_CHARACTERS,
-    TOP_BLOCKERS_LAST_24_HOURS_SQL,
-    TOP_LEVEL_ATTACHMENT_TYPE,
-    UNKNOWN_QUERY_MESSAGE_PREFIX,
-)
-
-
-class MissingNeonDatabaseUrlError(RuntimeError):
-    """Raised when the Neon connection URL environment variable is unset."""
-
-
-class MissingPsycopgDependencyError(RuntimeError):
-    """Raised when the psycopg driver is not installed in the interpreter."""
-
-
-def derive_category(script_path: Optional[str]) -> str:
-    """Return the category parent-directory name for a script path."""
-    if not script_path:
-        return HOOK_CATEGORY_UNCATEGORIZED
-    normalized_path = script_path.replace("\\", "/")
-    for each_prefix in SCRIPT_PATH_PYTHON_PREFIXES:
-        if normalized_path.startswith(each_prefix):
-            normalized_path = normalized_path[len(each_prefix) :]
-            break
-    hooks_directory_token_index = normalized_path.rfind(HOOKS_DIRECTORY_TOKEN)
-    if hooks_directory_token_index == -1:
-        return HOOK_CATEGORY_UNCATEGORIZED
-    remainder_after_hooks_segment = normalized_path[
-        hooks_directory_token_index + len(HOOKS_DIRECTORY_TOKEN) :
-    ]
-    all_remainder_parts = remainder_after_hooks_segment.split("/")
-    if len(all_remainder_parts) < CATEGORY_PATH_MINIMUM_PARTS:
-        return HOOK_CATEGORY_UNCATEGORIZED
-    candidate_category = all_remainder_parts[0]
-    if candidate_category in KNOWN_HOOK_CATEGORIES:
-        return candidate_category
-    return HOOK_CATEGORY_UNCATEGORIZED
-
-
-def derive_outcome(attachment_type: str) -> str:
-    """Map an attachment.type value to its outcome label."""
-    return OUTCOME_BY_ATTACHMENT_TYPE[attachment_type]
-
-
-def extract_script_path(attachment: dict[str, object]) -> Optional[str]:
-    """Return the script path embedded in a hook attachment, if any."""
-    attachment_type = attachment.get("type", EMPTY_STRING)
-    if attachment_type == ATTACHMENT_TYPE_HOOK_SUCCESS:
-        return _strip_python_prefix(attachment.get("command"))
-    if attachment_type == ATTACHMENT_TYPE_HOOK_BLOCKING_ERROR:
-        blocking_error_block = attachment.get("blockingError") or {}
-        if isinstance(blocking_error_block, dict):
-            return _strip_python_prefix(blocking_error_block.get("command"))
-    return None
-
-
-def _strip_python_prefix(command_string: Optional[str]) -> Optional[str]:
-    if not command_string:
-        return None
-    for each_prefix in SCRIPT_PATH_PYTHON_PREFIXES:
-        if command_string.startswith(each_prefix):
-            return command_string[len(each_prefix) :]
-    return command_string
-
-
-def extract_tool_name(hook_name: Optional[str]) -> Optional[str]:
-    """Return the tool name after the colon in a hook name, if present."""
-    if not hook_name:
-        return None
-    if HOOK_NAME_TOOL_SEPARATOR not in hook_name:
-        return None
-    return hook_name.split(HOOK_NAME_TOOL_SEPARATOR, 1)[1]
-
-
-def truncate_command_excerpt(command_text: Optional[str]) -> Optional[str]:
-    """Truncate a command string to the configured excerpt budget."""
-    return _truncate_to_length(command_text, COMMAND_EXCERPT_MAX_CHARACTERS)
-
-
-def truncate_stdout_excerpt(stdout_text: Optional[str]) -> Optional[str]:
-    """Truncate a stdout string to the configured excerpt budget."""
-    return _truncate_to_length(stdout_text, STDOUT_EXCERPT_MAX_CHARACTERS)
-
-
-def truncate_stderr_excerpt(stderr_text: Optional[str]) -> Optional[str]:
-    """Truncate a stderr string to the configured excerpt budget."""
-    return _truncate_to_length(stderr_text, STDERR_EXCERPT_MAX_CHARACTERS)
-
-
-def _truncate_to_length(
-    text_or_none: Optional[str], maximum_length: int
-) -> Optional[str]:
-    if text_or_none is None:
-        return None
-    if len(text_or_none) <= maximum_length:
-        return text_or_none
-    return text_or_none[:maximum_length]
-
-
-def _normalize_content_to_text(content_or_none: object) -> Optional[str]:
-    if content_or_none is None:
-        return None
-    if isinstance(content_or_none, str):
-        return content_or_none
-    if isinstance(content_or_none, list):
-        all_string_items = [
-            each_entry for each_entry in content_or_none if isinstance(each_entry, str)
-        ]
-        return NEWLINE_JOINER.join(all_string_items) if all_string_items else None
-    return str(content_or_none)
-
-
-def build_row_from_attachment(
-    parsed_record: dict[str, object],
-    source_jsonl_path: str,
-    source_line_number: int,
-) -> dict[str, object]:
-    """Build a hook_events row dict from one parsed JSONL record."""
-    attachment_block = parsed_record.get("attachment") or {}
-    attachment_type = attachment_block.get("type", EMPTY_STRING)
-    outcome_label = derive_outcome(attachment_type)
-    script_path_or_none = extract_script_path(attachment_block)
-    hook_category_label = derive_category(script_path_or_none)
-    hook_name_string = attachment_block.get("hookName")
-    hook_event_string = attachment_block.get("hookEvent", EMPTY_STRING)
-    tool_use_id_or_none = attachment_block.get("toolUseID")
-    tool_name_or_none = extract_tool_name(hook_name_string)
-
-    command_text_or_none = attachment_block.get("command")
-    stdout_text_or_none: Optional[str] = attachment_block.get("stdout")
-    stderr_text_or_none: Optional[str] = attachment_block.get("stderr")
-    exit_code_or_none = attachment_block.get("exitCode")
-    duration_milliseconds_or_none = attachment_block.get("durationMs")
-
-    if attachment_type == ATTACHMENT_TYPE_HOOK_BLOCKING_ERROR:
-        blocking_error_block = attachment_block.get("blockingError") or {}
-        if isinstance(blocking_error_block, dict):
-            command_text_or_none = blocking_error_block.get("command")
-            blocking_error_message = blocking_error_block.get("blockingError")
-            if blocking_error_message:
-                stderr_text_or_none = blocking_error_message
-    elif attachment_type == ATTACHMENT_TYPE_HOOK_SYSTEM_MESSAGE:
-        stdout_text_or_none = _normalize_content_to_text(
-            attachment_block.get("content")
-        )
-    elif attachment_type == ATTACHMENT_TYPE_HOOK_ADDITIONAL_CONTEXT:
-        stdout_text_or_none = _normalize_content_to_text(
-            attachment_block.get("content")
-        )
-
-    return {
-        "event_timestamp": parsed_record.get("timestamp"),
-        "session_id": parsed_record.get("sessionId", EMPTY_STRING),
-        "cwd": parsed_record.get("cwd"),
-        "git_branch": parsed_record.get("gitBranch"),
-        "hook_event": hook_event_string,
-        "hook_name": hook_name_string or EMPTY_STRING,
-        "hook_category": hook_category_label,
-        "script_path": script_path_or_none,
-        "tool_name": tool_name_or_none,
-        "tool_use_id": tool_use_id_or_none,
-        "outcome": outcome_label,
-        "exit_code": exit_code_or_none,
-        "duration_ms": duration_milliseconds_or_none,
-        "command_excerpt": truncate_command_excerpt(command_text_or_none),
-        "stdout_excerpt": truncate_stdout_excerpt(stdout_text_or_none),
-        "stderr_excerpt": truncate_stderr_excerpt(stderr_text_or_none),
-        "source_jsonl_path": source_jsonl_path,
-        "source_line_number": source_line_number,
-    }
-
-
-class AttachmentRecordIterator:
-    """Iterates hook attachment records and tracks bytes actually consumed.
-
-    ``final_line_number`` reflects the number of lines read from the file
-    (including malformed and non-attachment lines), not just the line
-    number of the last yielded record. ``final_byte_offset`` reflects the
-    byte position after the last successfully-read line (or
-    ``start_offset`` when the file did not exist). ``drained`` is True
-    once iteration reached EOF. Callers persist ``final_byte_offset``
-    and ``final_line_number`` whenever ``drained`` is True so resumption
-    starts from the exact position after the last bytes the iterator
-    consumed.
-    """
-
-    def __init__(
-        self,
-        jsonl_file_path: str,
-        start_offset: int,
-        start_line_number: int = 0,
-    ) -> None:
-        self._jsonl_file_path = jsonl_file_path
-        self._start_offset = start_offset
-        self._start_line_number = start_line_number
-        self.final_line_number = start_line_number
-        self.final_byte_offset = start_offset
-        self.drained = False
-
-    def __iter__(self) -> Iterator[tuple[dict[str, object], int, int]]:
-        try:
-            jsonl_file_handle = io.open(self._jsonl_file_path, "rb")  # noqa: SIM115
-        except (FileNotFoundError, OSError):
-            self.final_line_number = self._start_line_number
-            self.final_byte_offset = self._start_offset
-            self.drained = True
-            return
-        with jsonl_file_handle:
-            if self._start_offset > 0:
-                jsonl_file_handle.seek(self._start_offset)
-            current_line_number = self._start_line_number
-            current_byte_offset = jsonl_file_handle.tell()
-            self.final_byte_offset = current_byte_offset
-            while True:
-                raw_bytes = jsonl_file_handle.readline()
-                if not raw_bytes:
-                    self.final_line_number = current_line_number
-                    self.final_byte_offset = current_byte_offset
-                    self.drained = True
-                    return
-                current_line_number += 1
-                current_byte_offset += len(raw_bytes)
-                self.final_line_number = current_line_number
-                self.final_byte_offset = current_byte_offset
-                try:
-                    parsed_record = json.loads(raw_bytes.decode("utf-8"))
-                except (UnicodeDecodeError, json.JSONDecodeError):
-                    continue
-                if not isinstance(parsed_record, dict):
-                    continue
-                if parsed_record.get("type") != TOP_LEVEL_ATTACHMENT_TYPE:
-                    continue
-                attachment_block = parsed_record.get("attachment") or {}
-                if not isinstance(attachment_block, dict):
-                    continue
-                attachment_type = attachment_block.get("type", EMPTY_STRING)
-                if not isinstance(attachment_type, str):
-                    continue
-                if not attachment_type.startswith(ATTACHMENT_TYPE_PREFIX):
-                    continue
-                if attachment_type not in OUTCOME_BY_ATTACHMENT_TYPE:
-                    continue
-                yield parsed_record, current_line_number, current_byte_offset
-
-
-def iter_attachment_records_from_file(
-    jsonl_file_path: str,
-    start_offset: int,
-    start_line_number: int = 0,
-) -> AttachmentRecordIterator:
-    """Return an iterator over hook attachment records in a JSONL file.
-
-    The returned object supports iteration and exposes
-    ``final_line_number`` after iteration completes. ``final_line_number``
-    is the total number of lines consumed (malformed and non-attachment
-    lines included), which differs from the line number of the last
-    yielded record when non-attachment lines trail the last attachment.
-    """
-    return AttachmentRecordIterator(
-        jsonl_file_path=jsonl_file_path,
-        start_offset=start_offset,
-        start_line_number=start_line_number,
-    )
-
-
-def load_offsets(state_file_path: str) -> dict[str, dict[str, int]]:
-    """Load per-file ``{byte_offset, line_number}`` entries from disk.
-
-    Returns an empty dict when the state file is missing or contains
-    malformed JSON. Legacy bare-integer entries trigger a single
-    offline-warning line and are treated as invalid so the caller
-    re-extracts from the start of each file.
-    """
-    if not os.path.exists(state_file_path):
-        return {}
-    try:
-        with io.open(state_file_path, "r", encoding="utf-8") as state_file_handle:
-            loaded_content = json.load(state_file_handle)
-    except json.JSONDecodeError:
-        return {}
-    if not isinstance(loaded_content, dict):
-        return {}
-    migrated_offsets: dict[str, dict[str, int]] = {}
-    has_legacy_entries = False
-    for each_path, each_entry in loaded_content.items():
-        path_string = str(each_path)
-        if isinstance(each_entry, dict):
-            byte_offset_value = each_entry.get(BYTE_OFFSET_KEY)
-            line_number_value = each_entry.get(LINE_NUMBER_KEY)
-            if isinstance(byte_offset_value, int) and isinstance(
-                line_number_value, int
-            ):
-                migrated_offsets[path_string] = {
-                    BYTE_OFFSET_KEY: byte_offset_value,
-                    LINE_NUMBER_KEY: line_number_value,
-                }
-                continue
-        has_legacy_entries = True
-    if has_legacy_entries:
-        _append_legacy_offsets_warning_line()
-    return migrated_offsets
-
-
-def save_offsets(
-    state_file_path: str,
-    offset_by_jsonl_path: dict[str, dict[str, int]],
-) -> None:
-    """Persist per-file offset entries atomically via tempfile + os.replace."""
-    state_file_parent = os.path.dirname(state_file_path)
-    if state_file_parent:
-        os.makedirs(state_file_parent, exist_ok=True)
-    with tempfile.NamedTemporaryFile(
-        mode="w",
-        encoding="utf-8",
-        dir=state_file_parent or None,
-        delete=False,
-    ) as temporary_file_handle:
-        temporary_file_path = temporary_file_handle.name
-        try:
-            json.dump(
-                offset_by_jsonl_path,
-                temporary_file_handle,
-                indent=OFFSETS_JSON_INDENT,
-                sort_keys=True,
-            )
-            temporary_file_handle.flush()
-            os.fsync(temporary_file_handle.fileno())
-        except Exception:
-            temporary_file_handle.close()
-            try:
-                os.unlink(temporary_file_path)
-            except OSError:
-                pass
-            raise
-    try:
-        os.replace(temporary_file_path, state_file_path)
-    except Exception:
-        try:
-            os.unlink(temporary_file_path)
-        except OSError:
-            pass
-        raise
-
-
-@contextlib.contextmanager
-def _acquire_offsets_lock(state_file_path: str) -> Iterator[None]:
-    """Hold a cross-platform advisory lock around an offsets read-modify-write.
-
-    Serializes concurrent extractor runs so two Claude Code sessions
-    closing at once cannot clobber each other's offset updates. Uses
-    ``msvcrt.locking`` on Windows and ``fcntl.flock`` on POSIX; falls
-    back to no locking on platforms where neither module is available.
-
-    The sidecar path ``state_file_path + ".lock"`` is intentional,
-    permanent infrastructure. It is a byte-range-lockable companion to
-    the offsets file and is deliberately never unlinked. Attempting to
-    unlink it after release would open a TOCTOU window on Windows,
-    where another process may still hold it open. The stable sidecar
-    is the safer choice; reused on every run, its presence in the
-    state directory is expected and carries no other meaning.
-    """
-    lock_file_path = state_file_path + ".lock"
-    lock_parent_directory = os.path.dirname(lock_file_path)
-    if lock_parent_directory:
-        os.makedirs(lock_parent_directory, exist_ok=True)
-    with io.open(lock_file_path, "a+", encoding="utf-8") as lock_file_handle:
-        _lock_file_handle_blocking(lock_file_handle)
-        try:
-            yield
-        finally:
-            _unlock_file_handle(lock_file_handle)
-
-
-def _lock_file_handle_blocking(lock_file_handle: IO[str]) -> None:
-    """Acquire an exclusive byte-range lock with a bounded retry budget.
-
-    Both the Windows (``msvcrt.locking``) and POSIX (``fcntl.flock``)
-    branches deliberately fail fast: Windows uses ``LK_NBLCK`` instead
-    of ``LK_LOCK`` so the kernel never blocks ~10s internally, and
-    POSIX pairs ``LOCK_EX`` with ``LOCK_NB`` so ``EWOULDBLOCK`` bubbles
-    up immediately. The Python ``time.sleep(LOCK_RETRY_SLEEP_SECONDS)``
-    between attempts is the sole pacing mechanism, keeping the total
-    retry budget within the intended ``LOCK_MAXIMUM_RETRY_COUNT *
-    LOCK_RETRY_SLEEP_SECONDS`` window so the caller never exceeds the
-    30s Stop hook timeout under sustained contention.
-    """
-    if msvcrt is not None:
-        lock_byte_count = 1
-        for _each_attempt_index in range(LOCK_MAXIMUM_RETRY_COUNT):
-            try:
-                msvcrt.locking(
-                    lock_file_handle.fileno(), msvcrt.LK_NBLCK, lock_byte_count
-                )
-                return
-            except OSError as lock_exception:
-                if lock_exception.errno != errno.EACCES:
-                    raise
-                time.sleep(LOCK_RETRY_SLEEP_SECONDS)
-        raise OSError(
-            errno.EACCES,
-            "offsets lock retry budget exhausted",
-        )
-    if fcntl is not None:
-        for _each_attempt_index in range(LOCK_MAXIMUM_RETRY_COUNT):
-            try:
-                fcntl.flock(
-                    lock_file_handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB
-                )
-                return
-            except OSError as lock_exception:
-                if lock_exception.errno not in (errno.EAGAIN, errno.EWOULDBLOCK):
-                    raise
-                time.sleep(LOCK_RETRY_SLEEP_SECONDS)
-        raise OSError(
-            errno.EWOULDBLOCK,
-            "offsets lock retry budget exhausted",
-        )
-
-
-def _unlock_file_handle(lock_file_handle: IO[str]) -> None:
-    if msvcrt is not None:
-        lock_byte_count = 1
-        try:
-            msvcrt.locking(
-                lock_file_handle.fileno(), msvcrt.LK_UNLCK, lock_byte_count
-            )
-        except OSError:
-            return
-        return
-    if fcntl is not None:
-        fcntl.flock(lock_file_handle.fileno(), fcntl.LOCK_UN)
-
-
-def is_operational_error(exception_instance: BaseException) -> bool:
-    """Return True when an exception should trigger the offline fallback."""
-    if isinstance(
-        exception_instance,
-        (MissingNeonDatabaseUrlError, MissingPsycopgDependencyError),
-    ):
-        return True
-    class_name = type(exception_instance).__name__
-    return class_name in {"OperationalError", "InterfaceError", "TimeoutError"}
-
-
-def connect_to_neon() -> object:
-    """Open a psycopg connection using the Neon database URL env var.
-
-    Raises ``MissingNeonDatabaseUrlError`` when the URL env var is unset
-    and ``MissingPsycopgDependencyError`` when psycopg is not installed.
-    Both are treated as offline by ``is_operational_error`` so the Stop
-    hook never blocks session end on a missing environment.
-    """
-    if psycopg is None:
-        raise MissingPsycopgDependencyError(MISSING_PSYCOPG_WARNING_LABEL)
-    raw_database_url = os.environ.get(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE)
-    database_url = raw_database_url.strip() if raw_database_url is not None else None
-    if not database_url:
-        raise MissingNeonDatabaseUrlError(MISSING_NEON_DATABASE_URL_WARNING_LABEL)
-    return psycopg.connect(database_url, connect_timeout=CONNECT_TIMEOUT_SECONDS)
-
-
-def insert_rows_batch(
-    neon_connection: object,
-    all_rows: Sequence[dict[str, object]],
-) -> None:
-    """Insert a batch of hook_events rows with ON CONFLICT DO NOTHING."""
-    if not all_rows:
-        return
-    with neon_connection.cursor() as neon_cursor:
-        neon_cursor.executemany(HOOK_EVENTS_INSERT_SQL, list(all_rows))
-    neon_connection.commit()
-
-
-def _append_offline_warning_line(exception_instance: BaseException) -> None:
-    """Append an offline-marker line to the warning log; swallow disk errors.
-
-    The Stop hook contract requires that the offline-graceful path
-    always exits with ``EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING`` so
-    session shutdown never stalls on a failed extractor. A read-only
-    filesystem, missing parent path, or EACCES on the warning log file
-    itself must not propagate to the caller.
-    """
-    try:
-        warning_log_parent = os.path.dirname(OFFLINE_WARNING_LOG)
-        if warning_log_parent:
-            os.makedirs(warning_log_parent, exist_ok=True)
-        timestamp_iso = datetime.datetime.now(datetime.timezone.utc).isoformat()
-        exception_class_name = type(exception_instance).__name__
-        warning_line_text = f"{timestamp_iso}\toffline\t{exception_class_name}"
-        with io.open(OFFLINE_WARNING_LOG, "a", encoding="utf-8") as warning_log_handle:
-            warning_log_handle.write(warning_line_text + "\n")
-    except OSError:
-        return
-
-
-def _append_legacy_offsets_warning_line() -> None:
-    try:
-        warning_log_parent = os.path.dirname(OFFLINE_WARNING_LOG)
-        if warning_log_parent:
-            os.makedirs(warning_log_parent, exist_ok=True)
-        timestamp_iso = datetime.datetime.now(datetime.timezone.utc).isoformat()
-        warning_line_text = (
-            f"{timestamp_iso}\tmigration\t{LEGACY_OFFSETS_FORMAT_WARNING_LABEL}"
-        )
-        with io.open(OFFLINE_WARNING_LOG, "a", encoding="utf-8") as warning_log_handle:
-            warning_log_handle.write(warning_line_text + "\n")
-    except OSError:
-        return
-
-
-def run_full_extraction(
-    transcripts_root: str,
-    state_file_path: str,
-    full_rebuild: bool,
-) -> int:
-    """Execute one extraction pass (incremental by default).
-
-    The offsets lock is held only around the initial offsets load and
-    around each offsets write (where the latest on-disk offsets are
-    re-read and merged with this process's pending updates via a
-    per-file max). DB I/O and JSONL iteration run without the lock so
-    concurrent Stop hooks do not serialize on each other's slow work.
-
-    Returns process exit code (0 on success, 0 on offline fallback).
-    """
-    try:
-        neon_connection = connect_to_neon()
-    except Exception as connect_exception:
-        if is_operational_error(connect_exception):
-            _append_offline_warning_line(connect_exception)
-            return EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING
-        raise
-
-    try:
-        starting_offset_by_jsonl_path = _load_starting_offsets(
-            neon_connection=neon_connection,
-            state_file_path=state_file_path,
-            full_rebuild=full_rebuild,
-        )
-
-        all_jsonl_file_paths = _discover_jsonl_files(transcripts_root)
-        for each_jsonl_file_path in all_jsonl_file_paths:
-            previous_entry = starting_offset_by_jsonl_path.get(each_jsonl_file_path)
-            start_offset = (
-                previous_entry[BYTE_OFFSET_KEY]
-                if previous_entry is not None
-                else 0
-            )
-            start_line_number = (
-                previous_entry[LINE_NUMBER_KEY]
-                if previous_entry is not None
-                else 0
-            )
-            batch_buffer: list[dict[str, object]] = []
-            attachment_iterator = iter_attachment_records_from_file(
-                each_jsonl_file_path,
-                start_offset=start_offset,
-                start_line_number=start_line_number,
-            )
-            for (
-                parsed_record,
-                line_number,
-                byte_offset_after,
-            ) in attachment_iterator:
-                built_row = build_row_from_attachment(
-                    parsed_record=parsed_record,
-                    source_jsonl_path=each_jsonl_file_path,
-                    source_line_number=line_number,
-                )
-                batch_buffer.append(built_row)
-                if len(batch_buffer) >= INSERT_BATCH_SIZE:
-                    insert_rows_batch(neon_connection, batch_buffer)
-                    batch_buffer.clear()
-                    _merge_and_save_offsets_under_lock(
-                        state_file_path=state_file_path,
-                        pending_updates={
-                            each_jsonl_file_path: {
-                                BYTE_OFFSET_KEY: byte_offset_after,
-                                LINE_NUMBER_KEY: attachment_iterator.final_line_number,
-                            },
-                        },
-                    )
-            if batch_buffer:
-                insert_rows_batch(neon_connection, batch_buffer)
-            if attachment_iterator.drained:
-                _merge_and_save_offsets_under_lock(
-                    state_file_path=state_file_path,
-                    pending_updates={
-                        each_jsonl_file_path: {
-                            BYTE_OFFSET_KEY: attachment_iterator.final_byte_offset,
-                            LINE_NUMBER_KEY: attachment_iterator.final_line_number,
-                        },
-                    },
-                )
-    finally:
-        try:
-            neon_connection.close()
-        except Exception:
-            pass
-    return EXIT_CODE_SUCCESS
-
-
-def _load_starting_offsets(
-    neon_connection: object,
-    state_file_path: str,
-    full_rebuild: bool,
-) -> dict[str, dict[str, int]]:
-    with _acquire_offsets_lock(state_file_path):
-        if full_rebuild:
-            with neon_connection.cursor() as neon_cursor:
-                neon_cursor.execute(HOOK_EVENTS_TRUNCATE_SQL)
-            neon_connection.commit()
-            save_offsets(state_file_path, {})
-            return {}
-        return load_offsets(state_file_path)
-
-
-def _merge_and_save_offsets_under_lock(
-    state_file_path: str,
-    pending_updates: dict[str, dict[str, int]],
-) -> None:
-    with _acquire_offsets_lock(state_file_path):
-        latest_on_disk_offsets = load_offsets(state_file_path)
-        merged_offsets = _merge_offsets_taking_max(
-            latest_on_disk_offsets, pending_updates
-        )
-        save_offsets(state_file_path, merged_offsets)
-
-
-def _merge_offsets_taking_max(
-    disk_offsets: dict[str, dict[str, int]],
-    pending_updates: dict[str, dict[str, int]],
-) -> dict[str, dict[str, int]]:
-    merged: dict[str, dict[str, int]] = dict(disk_offsets)
-    for each_path, each_pending_entry in pending_updates.items():
-        existing_entry = merged.get(each_path)
-        if existing_entry is None:
-            merged[each_path] = dict(each_pending_entry)
-            continue
-        merged[each_path] = {
-            BYTE_OFFSET_KEY: max(
-                existing_entry[BYTE_OFFSET_KEY],
-                each_pending_entry[BYTE_OFFSET_KEY],
-            ),
-            LINE_NUMBER_KEY: max(
-                existing_entry[LINE_NUMBER_KEY],
-                each_pending_entry[LINE_NUMBER_KEY],
-            ),
-        }
-    return merged
-
-
-def _discover_jsonl_files(transcripts_root: str) -> list[str]:
-    recursive_glob_pattern = os.path.join(transcripts_root, "**", JSONL_FILE_GLOB)
-    top_level_glob_pattern = os.path.join(transcripts_root, JSONL_FILE_GLOB)
-    all_discovered_paths = set(glob.glob(recursive_glob_pattern, recursive=True))
-    all_discovered_paths.update(glob.glob(top_level_glob_pattern))
-    return sorted(all_discovered_paths)
-
-
-def run_summary() -> int:
-    """Print the top-10 over-blockers summary and return exit code."""
-    try:
-        neon_connection = connect_to_neon()
-    except Exception as connect_exception:
-        if is_operational_error(connect_exception):
-            _append_offline_warning_line(connect_exception)
-            return EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING
-        raise
-    try:
-        with neon_connection.cursor() as neon_cursor:
-            neon_cursor.execute(TOP_BLOCKERS_LAST_24_HOURS_SQL)
-            all_result_rows = neon_cursor.fetchall()
-    finally:
-        try:
-            neon_connection.close()
-        except Exception:
-            pass
-    if not all_result_rows:
-        print(SUMMARY_ZERO_BLOCKED_EVENTS_MESSAGE)
-        return EXIT_CODE_SUCCESS
-    _print_summary_table(all_result_rows)
-    return EXIT_CODE_SUCCESS
-
-
-def _print_summary_table(all_result_rows: Sequence[tuple[object, ...]]) -> None:
-    all_preview_rows: list[tuple[str, str, str, str]] = []
-    for each_result_row in all_result_rows:
-        (
-            hook_name_string,
-            hook_category_string,
-            block_count_integer,
-            top_command_preview,
-        ) = each_result_row
-        truncated_preview = (top_command_preview or EMPTY_STRING)[
-            :TOP_BLOCKED_COMMAND_PREVIEW_MAX_CHARACTERS
-        ]
-        all_preview_rows.append(
-            (
-                str(hook_name_string),
-                str(hook_category_string),
-                str(block_count_integer),
-                truncated_preview,
-            ),
-        )
-    all_display_rows = [SUMMARY_COLUMN_HEADINGS, *all_preview_rows]
-    all_column_widths = [
-        max(len(each_row[each_column_index]) for each_row in all_display_rows)
-        for each_column_index in range(len(SUMMARY_COLUMN_HEADINGS))
-    ]
-    for each_display_row in all_display_rows:
-        formatted_columns = [
-            each_cell.ljust(all_column_widths[each_column_index])
-            for each_column_index, each_cell in enumerate(each_display_row)
-        ]
-        print(SUMMARY_TABLE_COLUMN_GAP.join(formatted_columns))
-
-
-def run_query(named_query: str) -> int:
-    """Execute a pre-baked SQL file under ``queries/`` and print results."""
-    if not re.fullmatch(QUERY_NAME_PATTERN, named_query):
-        print(
-            f"{INVALID_QUERY_NAME_MESSAGE_PREFIX}{named_query}",
-            file=sys.stderr,
-        )
-        return EXIT_CODE_UNKNOWN_QUERY
-    queries_directory = Path(__file__).resolve().parent / QUERIES_DIRECTORY_NAME
-    query_file_path = queries_directory / f"{named_query}{SQL_FILE_EXTENSION}"
-    if not query_file_path.exists():
-        print(f"{UNKNOWN_QUERY_MESSAGE_PREFIX}{named_query}", file=sys.stderr)
-        return EXIT_CODE_UNKNOWN_QUERY
-    query_text = query_file_path.read_text(encoding="utf-8")
-    try:
-        neon_connection = connect_to_neon()
-    except Exception as connect_exception:
-        if is_operational_error(connect_exception):
-            _append_offline_warning_line(connect_exception)
-            return EXIT_CODE_EXTRACTOR_ENVIRONMENT_MISSING
-        raise
-    try:
-        with neon_connection.cursor() as neon_cursor:
-            neon_cursor.execute(query_text)
-            all_result_rows = neon_cursor.fetchall()
-            all_column_names = [
-                each_description[0]
-                for each_description in (neon_cursor.description or [])
-            ]
-    finally:
-        try:
-            neon_connection.close()
-        except Exception:
-            pass
-    if not all_result_rows:
-        print(QUERY_NO_ROWS_RETURNED_MESSAGE)
-        return EXIT_CODE_SUCCESS
-    print(SUMMARY_TABLE_COLUMN_GAP.join(all_column_names))
-    for each_result_row in all_result_rows:
-        print(
-            SUMMARY_TABLE_COLUMN_GAP.join(
-                str(each_cell) for each_cell in each_result_row
-            )
-        )
-    return EXIT_CODE_SUCCESS
-
-
-def main() -> int:
-    """Disabled extractor entry point: exit success with no work."""
-    return EXIT_CODE_SUCCESS
-
-
-if __name__ == "__main__":
-    sys.exit(main())