shellbrain 0.1.22__tar.gz → 0.1.24__tar.gz

{shellbrain-0.1.22 → shellbrain-0.1.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.22
+Version: 0.1.24
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

shellbrain-0.1.24/app/boot/migrations.py

@@ -0,0 +1,115 @@
+"""Packaged Alembic bootstrap helpers for installed-shellbrain database migrations."""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+import importlib.metadata
+
+from alembic import command
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+from alembic.script.revision import ResolutionError
+
+from app.boot.admin_db import get_admin_db_dsn, get_backup_dir, get_backup_mirror_dir, get_instance_mode_default
+from app.boot.db import get_optional_db_dsn
+from app.periphery.admin.destructive_guard import backup_and_verify_before_destructive_action
+from app.periphery.admin.instance_guard import ensure_instance_metadata, fetch_instance_metadata
+from app.periphery.admin.privileges import reconcile_app_role_privileges
+
+
+class DatabaseRevisionAheadOfInstalledPackageError(RuntimeError):
+    """Raised when the target database revision is newer than the installed package knows about."""
+
+
+def upgrade_database(revision: str = "head") -> None:
+    """Apply packaged Alembic migrations to the configured database."""
+
+    config = Config()
+    admin_dsn = get_admin_db_dsn()
+    with as_file(files("app").joinpath("migrations")) as migrations_path:
+        config.set_main_option("script_location", str(migrations_path))
+        script = ScriptDirectory.from_config(config)
+        if _database_has_shellbrain_objects(admin_dsn):
+            _assert_database_revision_is_known(admin_dsn=admin_dsn, script=script)
+            backup_and_verify_before_destructive_action(
+                admin_dsn=admin_dsn,
+                backup_root=get_backup_dir(),
+                mirror_root=get_backup_mirror_dir(),
+            )
+        config.set_main_option("sqlalchemy.url", admin_dsn)
+        command.upgrade(config, revision)
+    if fetch_instance_metadata(admin_dsn) is None:
+        ensure_instance_metadata(
+            admin_dsn,
+            instance_mode=get_instance_mode_default(),
+            created_by="app.admin.migrate",
+            notes="Stamped by packaged migration runner.",
+        )
+    app_dsn = get_optional_db_dsn()
+    if app_dsn:
+        reconcile_app_role_privileges(admin_dsn=admin_dsn, app_dsn=app_dsn)
+
+
+def _database_has_shellbrain_objects(admin_dsn: str) -> bool:
+    """Return whether the target database already contains Shellbrain-managed tables."""
+
+    import psycopg
+
+    with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT EXISTS (
+                  SELECT 1
+                  FROM information_schema.tables
+                  WHERE table_schema = 'public'
+                    AND table_name IN ('memories', 'episodes', 'episode_events', 'operation_invocations')
+                )
+                """
+            )
+            return bool(cur.fetchone()[0])
+
+
+def _assert_database_revision_is_known(*, admin_dsn: str, script: ScriptDirectory) -> None:
+    """Fail early with a user-facing error when the database revision is newer than this package."""
+
+    current_revision = _fetch_database_revision(admin_dsn)
+    if current_revision is None:
+        return
+    try:
+        script.get_revision(current_revision)
+    except ResolutionError as exc:
+        installed_version = _installed_shellbrain_version()
+        raise DatabaseRevisionAheadOfInstalledPackageError(
+            "Installed Shellbrain package "
+            f"({installed_version}) cannot manage database revision {current_revision}. "
+            "This database was likely migrated by a newer Shellbrain release than the one currently installed. "
+            "Upgrade Shellbrain to a build that includes this revision, then rerun `shellbrain init` or "
+            "`shellbrain admin migrate`."
+        ) from exc
+
+
+def _fetch_database_revision(admin_dsn: str) -> str | None:
+    """Return the current alembic revision when present."""
+
+    import psycopg
+
+    try:
+        with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT version_num FROM alembic_version")
+                row = cur.fetchone()
+    except psycopg.Error:
+        return None
+    if row is None or row[0] is None:
+        return None
+    return str(row[0])
+
+
+def _installed_shellbrain_version() -> str:
+    """Return the installed Shellbrain package version when available."""
+
+    try:
+        return importlib.metadata.version("shellbrain")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"

{shellbrain-0.1.22 → shellbrain-0.1.24}/app/core/entities/telemetry.py

@@ -66,6 +66,12 @@ class ReadSummaryRecord:
     implicit_related_count: int
     total_returned: int
     zero_results: bool
+    pack_char_count: int | None
+    pack_token_estimate: int | None
+    pack_token_estimate_method: str | None
+    direct_token_estimate: int | None
+    explicit_related_token_estimate: int | None
+    implicit_related_token_estimate: int | None
     created_at: datetime
 
 
@@ -150,3 +156,30 @@ class EpisodeSyncToolTypeRecord:
     sync_run_id: str
     tool_type: str
     event_count: int
+
+
+@dataclass(frozen=True)
+class ModelUsageRecord:
+    """One normalized host model-usage event tied to a repo session."""
+
+    id: str
+    repo_id: str
+    thread_id: str | None
+    episode_id: str | None
+    host_app: str
+    host_session_key: str
+    host_usage_key: str
+    source_kind: str
+    occurred_at: datetime
+    agent_role: str
+    provider: str | None
+    model_id: str | None
+    input_tokens: int | None
+    output_tokens: int | None
+    reasoning_output_tokens: int | None
+    cached_input_tokens_total: int | None
+    cache_read_input_tokens: int | None
+    cache_creation_input_tokens: int | None
+    capture_quality: str
+    raw_usage_json: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime | None = None

{shellbrain-0.1.22 → shellbrain-0.1.24}/app/core/interfaces/repos.py

@@ -12,6 +12,7 @@ from app.core.entities.memory import Memory
 from app.core.entities.telemetry import (
     EpisodeSyncRunRecord,
     EpisodeSyncToolTypeRecord,
+    ModelUsageRecord,
     OperationInvocationRecord,
     ReadResultItemRecord,
     ReadSummaryRecord,
@@ -275,6 +276,10 @@ class ITelemetryRepo(ABC):
     ) -> None:
         """This method appends one sync-run row and its per-tool aggregates."""
 
+    @abstractmethod
+    def insert_model_usage(self, records: Sequence[ModelUsageRecord]) -> None:
+        """This method appends normalized model-usage rows idempotently."""
+
     @abstractmethod
     def update_operation_polling(self, invocation_id: str, *, attempted: bool, started: bool) -> None:
         """This method patches the poller-start flags for one existing invocation row."""

shellbrain-0.1.24/app/core/use_cases/record_model_usage_telemetry.py

@@ -0,0 +1,20 @@
+"""Thin orchestration for normalized model-usage telemetry writes."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from app.core.entities.telemetry import ModelUsageRecord
+from app.core.interfaces.unit_of_work import IUnitOfWork
+
+
+def record_model_usage_telemetry(
+    *,
+    uow: IUnitOfWork,
+    records: Sequence[ModelUsageRecord],
+) -> None:
+    """Persist normalized model-usage rows without affecting callers."""
+
+    if not records:
+        return
+    uow.telemetry.insert_model_usage(tuple(records))

shellbrain-0.1.24/app/migrations/versions/20260414_0010_model_usage_telemetry.py

@@ -0,0 +1,83 @@
+"""Add model-usage telemetry storage and derived views."""
+
+from alembic import op
+
+from app.periphery.db.models.views import (
+    USAGE_COMMAND_DAILY_SQL,
+    USAGE_MEMORY_RETRIEVAL_SQL,
+    USAGE_PROBLEM_TOKENS_SQL,
+    USAGE_SESSION_PROTOCOL_SQL,
+    USAGE_SESSION_TOKENS_SQL,
+    USAGE_SYNC_HEALTH_SQL,
+    USAGE_TOKEN_CAPTURE_HEALTH_SQL,
+    USAGE_WRITE_EFFECTS_SQL,
+)
+
+revision = "20260414_0010"
+down_revision = "20260410_0009"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create model-usage telemetry storage and derived views."""
+
+    op.execute(
+        """
+        CREATE TABLE model_usage (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          thread_id TEXT,
+          episode_id TEXT,
+          host_app TEXT NOT NULL,
+          host_session_key TEXT NOT NULL,
+          host_usage_key TEXT NOT NULL,
+          source_kind TEXT NOT NULL,
+          occurred_at TIMESTAMPTZ NOT NULL,
+          agent_role TEXT NOT NULL DEFAULT 'foreground',
+          provider TEXT,
+          model_id TEXT,
+          input_tokens BIGINT,
+          output_tokens BIGINT,
+          reasoning_output_tokens BIGINT,
+          cached_input_tokens_total BIGINT,
+          cache_read_input_tokens BIGINT,
+          cache_creation_input_tokens BIGINT,
+          capture_quality TEXT NOT NULL DEFAULT 'exact',
+          raw_usage_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          CONSTRAINT uq_model_usage_host_session_usage UNIQUE (host_app, host_session_key, host_usage_key)
+        );
+        CREATE INDEX idx_model_usage_repo_thread_occurred_at
+          ON model_usage(repo_id, thread_id, occurred_at);
+        CREATE INDEX idx_model_usage_repo_host_session_occurred_at
+          ON model_usage(repo_id, host_app, host_session_key, occurred_at);
+        """
+    )
+    op.execute(USAGE_COMMAND_DAILY_SQL)
+    op.execute(USAGE_MEMORY_RETRIEVAL_SQL)
+    op.execute(USAGE_WRITE_EFFECTS_SQL)
+    op.execute(USAGE_SYNC_HEALTH_SQL)
+    op.execute(USAGE_SESSION_PROTOCOL_SQL)
+    op.execute(USAGE_SESSION_TOKENS_SQL)
+    op.execute(USAGE_PROBLEM_TOKENS_SQL)
+    op.execute(USAGE_TOKEN_CAPTURE_HEALTH_SQL)
+
+
+def downgrade() -> None:
+    """Drop model-usage telemetry views and table."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS usage_token_capture_health;
+        DROP VIEW IF EXISTS usage_problem_tokens;
+        DROP VIEW IF EXISTS usage_session_tokens;
+        DROP VIEW IF EXISTS usage_session_protocol;
+        DROP VIEW IF EXISTS usage_sync_health;
+        DROP VIEW IF EXISTS usage_write_effects;
+        DROP VIEW IF EXISTS usage_memory_retrieval;
+        DROP VIEW IF EXISTS usage_command_daily;
+
+        DROP TABLE IF EXISTS model_usage;
+        """
+    )

shellbrain-0.1.24/app/migrations/versions/20260414_0011_usage_problem_tokens_multi_solution_metrics.py

@@ -0,0 +1,147 @@
+"""Expand usage_problem_tokens with latest-solution metrics."""
+
+from alembic import op
+
+from app.periphery.db.models.views import USAGE_PROBLEM_TOKENS_SQL
+
+revision = "20260414_0011"
+down_revision = "20260414_0010"
+branch_labels = None
+depends_on = None
+
+
+PREVIOUS_USAGE_PROBLEM_TOKENS_SQL = """
+CREATE OR REPLACE VIEW usage_problem_tokens AS
+WITH session_quality AS (
+  SELECT
+    repo_id,
+    host_app,
+    host_session_key,
+    BOOL_OR(capture_quality = 'exact') AS has_exact_rows,
+    BOOL_OR(
+      capture_quality = 'exact'
+      AND (
+        COALESCE(input_tokens, 0) > 0
+        OR COALESCE(output_tokens, 0) > 0
+        OR COALESCE(cached_input_tokens_total, 0) > 0
+        OR COALESCE(reasoning_output_tokens, 0) > 0
+      )
+    ) AS has_nonzero_exact_rows,
+    BOOL_OR(capture_quality = 'estimated') AS has_estimated_rows
+  FROM model_usage
+  GROUP BY repo_id, host_app, host_session_key
+),
+preferred_rows AS (
+  SELECT mu.*
+  FROM model_usage mu
+  JOIN session_quality sq
+    ON sq.repo_id = mu.repo_id
+   AND sq.host_app = mu.host_app
+   AND sq.host_session_key = mu.host_session_key
+  WHERE (
+    sq.has_nonzero_exact_rows
+    AND mu.capture_quality = 'exact'
+  ) OR (
+    NOT sq.has_nonzero_exact_rows
+    AND mu.capture_quality = 'estimated'
+  ) OR (
+    NOT sq.has_nonzero_exact_rows
+    AND NOT sq.has_estimated_rows
+    AND sq.has_exact_rows
+    AND mu.capture_quality = 'exact'
+  )
+),
+problem_threads AS (
+  SELECT
+    p.id AS problem_id,
+    p.repo_id,
+    p.created_at AS problem_created_at,
+    (
+      ARRAY_AGG(ep.thread_id ORDER BY ee.created_at ASC, ee.seq ASC)
+      FILTER (WHERE ep.thread_id IS NOT NULL)
+    )[1] AS thread_id
+  FROM memories p
+  JOIN memory_evidence me ON me.memory_id = p.id
+  JOIN evidence_refs er ON er.id = me.evidence_id
+  JOIN episode_events ee ON ee.id = COALESCE(er.episode_event_id, er.ref)
+  JOIN episodes ep ON ep.id = ee.episode_id
+  WHERE p.kind = 'problem'
+  GROUP BY p.id, p.repo_id, p.created_at
+),
+first_solutions AS (
+  SELECT
+    pa.problem_id,
+    s.id AS solution_id,
+    s.created_at AS solution_created_at,
+    ROW_NUMBER() OVER (
+      PARTITION BY pa.problem_id
+      ORDER BY s.created_at ASC, s.id ASC
+    ) AS row_num
+  FROM problem_attempts pa
+  JOIN memories s ON s.id = pa.attempt_id
+  WHERE pa.role = 'solution'
+    AND s.kind = 'solution'
+),
+problem_windows AS (
+  SELECT
+    pt.repo_id,
+    pt.problem_id,
+    pt.thread_id,
+    pt.problem_created_at,
+    fs.solution_id,
+    fs.solution_created_at
+  FROM problem_threads pt
+  JOIN first_solutions fs
+    ON fs.problem_id = pt.problem_id
+   AND fs.row_num = 1
+  WHERE pt.thread_id IS NOT NULL
+)
+SELECT
+  pw.repo_id,
+  pw.problem_id,
+  pw.solution_id,
+  pw.thread_id,
+  pw.problem_created_at,
+  pw.solution_created_at,
+  COUNT(pr.id)::INTEGER AS usage_row_count,
+  COALESCE(SUM(pr.input_tokens), 0)::BIGINT AS input_tokens,
+  COALESCE(SUM(pr.output_tokens), 0)::BIGINT AS output_tokens,
+  COALESCE(SUM(pr.reasoning_output_tokens), 0)::BIGINT AS reasoning_output_tokens,
+  COALESCE(SUM(pr.cached_input_tokens_total), 0)::BIGINT AS cached_input_tokens_total,
+  COALESCE(SUM(pr.cache_read_input_tokens), 0)::BIGINT AS cache_read_input_tokens,
+  COALESCE(SUM(pr.cache_creation_input_tokens), 0)::BIGINT AS cache_creation_input_tokens,
+  (
+    COALESCE(SUM(pr.input_tokens), 0)
+    + COALESCE(SUM(pr.output_tokens), 0)
+  )::BIGINT AS fresh_work_tokens,
+  (
+    COALESCE(SUM(pr.input_tokens), 0)
+    + COALESCE(SUM(pr.cached_input_tokens_total), 0)
+    + COALESCE(SUM(pr.output_tokens), 0)
+  )::BIGINT AS all_tokens_including_cache
+FROM problem_windows pw
+LEFT JOIN preferred_rows pr
+  ON pr.repo_id = pw.repo_id
+ AND pr.thread_id = pw.thread_id
+ AND pr.occurred_at >= pw.problem_created_at
+ AND pr.occurred_at <= pw.solution_created_at
+GROUP BY
+  pw.repo_id,
+  pw.problem_id,
+  pw.solution_id,
+  pw.thread_id,
+  pw.problem_created_at,
+  pw.solution_created_at;
+"""
+
+
+def upgrade() -> None:
+    """Replace usage_problem_tokens with first- and latest-solution metrics."""
+
+    op.execute(USAGE_PROBLEM_TOKENS_SQL)
+
+
+def downgrade() -> None:
+    """Restore the prior usage_problem_tokens definition."""
+
+    op.execute(PREVIOUS_USAGE_PROBLEM_TOKENS_SQL)

shellbrain-0.1.24/app/migrations/versions/20260415_0012_read_pack_cost_and_read_roi.py

@@ -0,0 +1,58 @@
+"""Add read-pack cost telemetry and read-before-solve ROI views."""
+
+from alembic import op
+
+from app.periphery.db.models.views import (
+    USAGE_PROBLEM_READ_ROI_SQL,
+    USAGE_READ_BEFORE_SOLVE_ROI_SQL,
+)
+
+revision = "20260415_0012"
+down_revision = "20260414_0011"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add read-pack estimate columns, a read-focused partial index, and ROI views."""
+
+    op.execute(
+        """
+        ALTER TABLE read_invocation_summaries
+          ADD COLUMN pack_char_count INTEGER,
+          ADD COLUMN pack_token_estimate INTEGER,
+          ADD COLUMN pack_token_estimate_method TEXT,
+          ADD COLUMN direct_token_estimate INTEGER,
+          ADD COLUMN explicit_related_token_estimate INTEGER,
+          ADD COLUMN implicit_related_token_estimate INTEGER;
+
+        CREATE INDEX idx_operation_invocations_successful_read_thread_created_at
+          ON operation_invocations(repo_id, selected_thread_id, created_at)
+          WHERE command = 'read'
+            AND outcome = 'ok'
+            AND selected_thread_id IS NOT NULL;
+        """
+    )
+    op.execute(USAGE_PROBLEM_READ_ROI_SQL)
+    op.execute(USAGE_READ_BEFORE_SOLVE_ROI_SQL)
+
+
+def downgrade() -> None:
+    """Drop read ROI views, partial index, and read-pack estimate columns."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS usage_read_before_solve_roi;
+        DROP VIEW IF EXISTS usage_problem_read_roi;
+
+        DROP INDEX IF EXISTS idx_operation_invocations_successful_read_thread_created_at;
+
+        ALTER TABLE read_invocation_summaries
+          DROP COLUMN IF EXISTS implicit_related_token_estimate,
+          DROP COLUMN IF EXISTS explicit_related_token_estimate,
+          DROP COLUMN IF EXISTS direct_token_estimate,
+          DROP COLUMN IF EXISTS pack_token_estimate_method,
+          DROP COLUMN IF EXISTS pack_token_estimate,
+          DROP COLUMN IF EXISTS pack_char_count;
+        """
+    )

{shellbrain-0.1.22 → shellbrain-0.1.24}/app/periphery/admin/doctor.py

@@ -54,6 +54,18 @@ def build_doctor_report(
     disk = shutil.disk_usage(home_root if home_root.exists() else home_root.parent)
     repo_report = _build_repo_report(repo_root=repo_root)
     host_integrations = inspect_host_assets()
+    cursor_statusline = getattr(
+        host_integrations,
+        "cursor_statusline",
+        {
+            "installed": False,
+            "managed": False,
+            "malformed": False,
+            "path": None,
+            "command_executable": None,
+            "executable_exists": None,
+        },
+    )
     runtime_warnings = _runtime_warnings(machine_config)
 
     report: dict[str, Any] = {
@@ -88,6 +100,7 @@ def build_doctor_report(
             "claude_startup_guidance": host_integrations.claude_startup_guidance,
             "claude_skill": host_integrations.claude_skill,
             "cursor_skill": host_integrations.cursor_skill,
+            "cursor_statusline": cursor_statusline,
             "claude_global_hook": host_integrations.claude_global_hook,
         },
         "repo": repo_report,

{shellbrain-0.1.22 → shellbrain-0.1.24}/app/periphery/admin/init.py

@@ -469,10 +469,13 @@ def _reconcile_database(config: MachineConfig) -> tuple[bool, MachineConfig]:
 def _apply_schema_migrations(config: MachineConfig) -> bool:
     """Apply packaged schema migrations to the configured Shellbrain database."""
 
-    from app.boot.migrations import upgrade_database
+    from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError, upgrade_database
 
     before_revision = _fetch_schema_revision(config.database.admin_dsn)
-    upgrade_database()
+    try:
+        upgrade_database()
+    except DatabaseRevisionAheadOfInstalledPackageError as exc:
+        raise InitConflictError(str(exc)) from exc
     after_revision = _fetch_schema_revision(config.database.admin_dsn)
     return before_revision != after_revision
 

shellbrain-0.1.24/app/periphery/admin/model_usage_backfill.py

@@ -0,0 +1,123 @@
+"""Retroactive token-usage backfill from Shellbrain-linked host transcripts."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
+
+from app.boot.use_cases import get_uow_factory
+from app.core.entities.telemetry import ModelUsageRecord
+from app.core.use_cases.record_model_usage_telemetry import record_model_usage_telemetry
+from app.periphery.episodes.model_usage import collect_model_usage_records_for_session
+
+
+@dataclass(frozen=True)
+class BackfillSummary:
+    """Small structured summary for token-usage backfill runs."""
+
+    sessions_examined: int
+    sessions_with_records: int
+    sessions_skipped: int
+    sessions_failed: int
+    records_attempted: int
+    host_counts: dict[str, int]
+    errors: list[dict[str, str]]
+
+    def to_payload(self) -> dict[str, object]:
+        """Render the summary into JSON-safe primitives."""
+
+        return {
+            "sessions_examined": self.sessions_examined,
+            "sessions_with_records": self.sessions_with_records,
+            "sessions_skipped": self.sessions_skipped,
+            "sessions_failed": self.sessions_failed,
+            "records_attempted": self.records_attempted,
+            "host_counts": self.host_counts,
+            "errors": self.errors,
+        }
+
+
+def backfill_model_usage(*, engine: Engine) -> BackfillSummary:
+    """Backfill normalized model usage for all Shellbrain-linked historical sessions."""
+
+    rows = _load_linked_sessions(engine=engine)
+    host_counts: Counter[str] = Counter()
+    errors: list[dict[str, str]] = []
+    sessions_with_records = 0
+    sessions_skipped = 0
+    sessions_failed = 0
+    records_attempted = 0
+    uow_factory = get_uow_factory()
+
+    for row in rows:
+        transcript_path = Path(str(row["transcript_path"]))
+        try:
+            records = collect_model_usage_records_for_session(
+                repo_id=str(row["repo_id"]),
+                host_app=str(row["host_app"]),
+                host_session_key=str(row["host_session_key"]),
+                thread_id=str(row["thread_id"]) if row["thread_id"] is not None else None,
+                episode_id=str(row["episode_id"]) if row["episode_id"] is not None else None,
+                transcript_path=transcript_path,
+            )
+        except Exception as exc:
+            sessions_failed += 1
+            errors.append(
+                {
+                    "host_app": str(row["host_app"]),
+                    "host_session_key": str(row["host_session_key"]),
+                    "message": str(exc),
+                }
+            )
+            continue
+
+        if not records:
+            sessions_skipped += 1
+            continue
+        _persist_records(uow_factory=uow_factory, records=records)
+        sessions_with_records += 1
+        records_attempted += len(records)
+        host_counts[str(row["host_app"])] += len(records)
+
+    return BackfillSummary(
+        sessions_examined=len(rows),
+        sessions_with_records=sessions_with_records,
+        sessions_skipped=sessions_skipped,
+        sessions_failed=sessions_failed,
+        records_attempted=records_attempted,
+        host_counts=dict(sorted(host_counts.items())),
+        errors=errors,
+    )
+
+
+def _persist_records(*, uow_factory, records: list[ModelUsageRecord]) -> None:
+    """Persist a batch of model-usage rows in one transaction."""
+
+    with uow_factory() as uow:
+        record_model_usage_telemetry(uow=uow, records=tuple(records))
+
+
+def _load_linked_sessions(*, engine: Engine) -> list[dict[str, object]]:
+    """Return the latest Shellbrain-linked sync record per repo/host/session."""
+
+    statement = text(
+        """
+        SELECT DISTINCT ON (repo_id, host_app, host_session_key)
+          repo_id,
+          host_app,
+          host_session_key,
+          thread_id,
+          episode_id,
+          transcript_path
+        FROM episode_sync_runs
+        WHERE episode_id IS NOT NULL
+          AND transcript_path IS NOT NULL
+        ORDER BY repo_id, host_app, host_session_key, created_at DESC, id DESC
+        """
+    )
+    with engine.connect() as conn:
+        return [dict(row) for row in conn.execute(statement).mappings().all()]