shellbrain 0.1.22__tar.gz → 0.1.23__tar.gz

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

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

{shellbrain-0.1.22 → shellbrain-0.1.23}/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.23}/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.23/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.23/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.23/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.23/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.23}/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.23/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()]

{shellbrain-0.1.22 → shellbrain-0.1.23}/app/periphery/cli/handlers.py

@@ -26,6 +26,7 @@ from app.core.use_cases.manage_session_state import SessionStateManager
 from app.core.use_cases.create_memory import execute_create_memory
 from app.core.use_cases.read_memory import execute_read_memory
 from app.core.use_cases.record_episode_sync_telemetry import record_episode_sync_telemetry
+from app.core.use_cases.record_model_usage_telemetry import record_model_usage_telemetry
 from app.core.use_cases.record_operation_telemetry import record_operation_telemetry
 from app.core.use_cases.sync_episode import sync_episode
 from app.core.use_cases.update_memory import execute_update_memory
@@ -46,6 +47,7 @@ from app.periphery.cli.schema_validation import (
     validate_update_schema,
 )
 from app.periphery.episodes.normalization import normalize_host_transcript
+from app.periphery.episodes.model_usage import collect_model_usage_records_for_session
 from app.periphery.identity.resolver import (
     discover_untrusted_events_candidate,
     resolve_caller_identity,
@@ -305,6 +307,7 @@ def handle_events(
     selection_summary = SessionSelectionSummary()
     sync_run = None
     sync_tool_types = ()
+    model_usage_records = ()
     try:
         agent_request, errors = validate_events_schema(payload)
         if errors:
@@ -392,6 +395,19 @@ def handle_events(
                         system_event_count=int(sync_result["system_event_count"]),
                         tool_type_counts=dict(sync_result["tool_type_counts"]),
                     )
+                    try:
+                        model_usage_records = tuple(
+                            collect_model_usage_records_for_session(
+                                repo_id=request.repo_id,
+                                host_app=str(source.host_app),
+                                host_session_key=str(source.host_session_key),
+                                thread_id=str(sync_result["thread_id"]),
+                                episode_id=str(sync_result["episode_id"]),
+                                transcript_path=Path(str(sync_result["transcript_path"])),
+                            )
+                        )
+                    except Exception:
+                        model_usage_records = ()
                 except Exception as exc:
                     error_stage = "sync"
                     result = _error_response([ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=str(exc))])
@@ -436,6 +452,7 @@ def handle_events(
         selection_summary=selection_summary,
         sync_run=sync_run,
         sync_tool_types=sync_tool_types,
+        model_usage_records=model_usage_records,
         total_latency_ms=int((perf_counter() - started_at) * 1000),
     )
     return result
@@ -653,6 +670,7 @@ def _persist_operation_telemetry_best_effort(
     selection_summary: SessionSelectionSummary | None = None,
     sync_run=None,
     sync_tool_types=(),
+    model_usage_records=(),
     total_latency_ms: int | None = None,
 ) -> None:
     """Persist invocation telemetry in a second best-effort transaction."""
@@ -716,6 +734,11 @@ def _persist_operation_telemetry_best_effort(
                     run=sync_run,
                     tool_types=sync_tool_types,
                 )
+            if model_usage_records:
+                record_model_usage_telemetry(
+                    uow=telemetry_uow,
+                    records=tuple(model_usage_records),
+                )
     except Exception:
         return
 

{shellbrain-0.1.22 → shellbrain-0.1.23}/app/periphery/cli/main.py

@@ -230,6 +230,15 @@ _ANALYTICS_HELP = dedent(
     """
 )
 
+_BACKFILL_TOKEN_USAGE_HELP = dedent(
+    """\
+    Backfill normalized model-token telemetry from Shellbrain-linked host session files.
+
+    Example:
+      shellbrain admin backfill-token-usage
+    """
+)
+
 _METRICS_HELP = dedent(
     """\
     Generate one lightweight repo-scoped metrics snapshot, write local artifacts, and open a static dashboard.
@@ -470,6 +479,13 @@ def build_parser() -> argparse.ArgumentParser:
         default=2,
         help="Number of trailing days to include in the report. Defaults to 2.",
     )
+    admin_subparsers.add_parser(
+        "backfill-token-usage",
+        help="Backfill normalized token usage from linked host session files.",
+        description="Backfill normalized token usage from Shellbrain-linked host session files.",
+        epilog=_BACKFILL_TOKEN_USAGE_HELP,
+        formatter_class=_HelpFormatter,
+    )
     install_hook_parser = admin_subparsers.add_parser(
         "install-claude-hook",
         help="Install the repo-local Claude hook used for trusted caller identity.",
@@ -771,6 +787,14 @@ def _run_admin_command(args: argparse.Namespace) -> int:
         print(json.dumps(report, indent=2, sort_keys=True))
         return 0
 
+    if args.admin_command == "backfill-token-usage":
+        from app.boot.db import get_engine_instance
+        from app.periphery.admin.model_usage_backfill import backfill_model_usage
+
+        summary = backfill_model_usage(engine=get_engine_instance())
+        print(json.dumps(summary.to_payload(), indent=2, sort_keys=True))
+        return 0
+
     repo_root = _resolve_admin_repo_root(getattr(args, "repo_root", None))
     if args.admin_command == "install-claude-hook":
         from app.periphery.identity.claude_hook_install import install_claude_hook