shellbrain 0.1.25__tar.gz → 0.1.27__tar.gz

{shellbrain-0.1.25 → shellbrain-0.1.27}/PKG-INFO

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

shellbrain-0.1.27/app/migrations/versions/20260422_0015_problem_runs.py

@@ -0,0 +1,101 @@
+"""Add explicit problem-run token metrics."""
+
+from alembic import op
+
+from app.periphery.db.models.views import (
+    USAGE_PROBLEM_READ_ROI_LEGACY_SQL,
+    USAGE_PROBLEM_RUN_TOKENS_SQL,
+    USAGE_PROBLEM_TOKENS_LEGACY_SQL,
+    USAGE_READ_BEFORE_SOLVE_ROI_LEGACY_SQL,
+)
+
+revision = "20260422_0015"
+down_revision = "20260422_0014"
+branch_labels = None
+depends_on = None
+
+
+def _unsuffixed_proxy_sql(sql: str) -> str:
+    """Return the pre-legacy view name for downgrade compatibility."""
+
+    return (
+        sql.replace("usage_read_before_solve_roi_legacy", "usage_read_before_solve_roi")
+        .replace("usage_problem_read_roi_legacy", "usage_problem_read_roi")
+        .replace("usage_problem_tokens_legacy", "usage_problem_tokens")
+    )
+
+
+def upgrade() -> None:
+    """Create problem-run windows and rename memory-derived token proxies."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS usage_read_before_solve_roi;
+        DROP VIEW IF EXISTS usage_problem_read_roi;
+        DROP VIEW IF EXISTS usage_problem_tokens;
+
+        CREATE TABLE problem_runs (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          thread_id TEXT,
+          host_app TEXT,
+          host_session_key TEXT,
+          episode_id TEXT REFERENCES episodes(id) ON DELETE SET NULL,
+          status TEXT NOT NULL,
+          opened_at TIMESTAMPTZ NOT NULL,
+          closed_at TIMESTAMPTZ,
+          opened_by TEXT NOT NULL,
+          closed_by TEXT,
+          problem_memory_id TEXT REFERENCES memories(id) ON DELETE SET NULL,
+          solution_memory_id TEXT REFERENCES memories(id) ON DELETE SET NULL,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          CONSTRAINT ck_problem_runs_status CHECK (status IN ('open', 'closed', 'abandoned')),
+          CONSTRAINT ck_problem_runs_opened_by CHECK (opened_by IN ('worker', 'librarian', 'manual', 'system')),
+          CONSTRAINT ck_problem_runs_closed_by CHECK (closed_by IS NULL OR closed_by IN ('worker', 'librarian', 'manual', 'system')),
+          CONSTRAINT ck_problem_runs_closed_after_opened CHECK (closed_at IS NULL OR closed_at >= opened_at),
+          CONSTRAINT ck_problem_runs_status_closed_at CHECK (
+            (
+              status = 'open'
+              AND closed_at IS NULL
+            ) OR (
+              status IN ('closed', 'abandoned')
+              AND closed_at IS NOT NULL
+            )
+          )
+        );
+
+        CREATE INDEX idx_problem_runs_repo_thread_window
+          ON problem_runs(repo_id, thread_id, opened_at, closed_at);
+        CREATE INDEX idx_problem_runs_repo_host_session_window
+          ON problem_runs(repo_id, host_app, host_session_key, opened_at, closed_at);
+        CREATE INDEX idx_problem_runs_repo_status_opened_at
+          ON problem_runs(repo_id, status, opened_at);
+        CREATE INDEX idx_problem_runs_problem_memory
+          ON problem_runs(problem_memory_id);
+        CREATE INDEX idx_problem_runs_solution_memory
+          ON problem_runs(solution_memory_id);
+        """
+    )
+    op.execute(USAGE_PROBLEM_TOKENS_LEGACY_SQL)
+    op.execute(USAGE_PROBLEM_READ_ROI_LEGACY_SQL)
+    op.execute(USAGE_READ_BEFORE_SOLVE_ROI_LEGACY_SQL)
+    op.execute(USAGE_PROBLEM_RUN_TOKENS_SQL)
+
+
+def downgrade() -> None:
+    """Drop problem-run metrics and restore the previous proxy view names."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS usage_problem_run_tokens;
+        DROP TABLE IF EXISTS problem_runs;
+
+        DROP VIEW IF EXISTS usage_read_before_solve_roi_legacy;
+        DROP VIEW IF EXISTS usage_problem_read_roi_legacy;
+        DROP VIEW IF EXISTS usage_problem_tokens_legacy;
+        """
+    )
+    op.execute(_unsuffixed_proxy_sql(USAGE_PROBLEM_TOKENS_LEGACY_SQL))
+    op.execute(_unsuffixed_proxy_sql(USAGE_PROBLEM_READ_ROI_LEGACY_SQL))
+    op.execute(_unsuffixed_proxy_sql(USAGE_READ_BEFORE_SOLVE_ROI_LEGACY_SQL))

{shellbrain-0.1.25 → shellbrain-0.1.27}/app/periphery/cli/main.py

@@ -60,7 +60,7 @@ _TOP_LEVEL_HELP = dedent(
     Examples:
       shellbrain init
       shellbrain upgrade
-      shellbrain metrics --days 30
+      shellbrain metrics
       shellbrain read --json '{"query":"Have we seen this migration lock timeout before?","kinds":["problem","solution","failed_tactic"]}'
       shellbrain read --json '{"query":"What repo constraints or user preferences matter for this auth refactor?","kinds":["fact","preference","change"]}'
       shellbrain events --json '{"limit":10}'
@@ -260,12 +260,10 @@ _BACKFILL_TOKEN_USAGE_HELP = dedent(
 
 _METRICS_HELP = dedent(
     """\
-    Generate one lightweight repo-scoped metrics snapshot, write local artifacts, and open a static dashboard.
+    Generate lightweight metrics snapshots, write local artifacts, and open one browser dashboard that switches repos with arrow keys.
 
-    Examples:
+    Example:
       shellbrain metrics
-      shellbrain metrics --days 30
-      shellbrain metrics --days 14 --no-open
     """
 )
 
@@ -386,23 +384,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     metrics_parser = subparsers.add_parser(
         "metrics",
-        help="Open a lightweight repo-scoped metrics dashboard.",
-        description="Generate one local metrics snapshot and open a static Shellbrain dashboard.",
+        help="Browse Shellbrain metrics across repos.",
+        description="Generate local metrics snapshots and open one browser dashboard for all repos.",
         epilog=_METRICS_HELP,
         formatter_class=_HelpFormatter,
     )
-    _add_repo_context_arguments(metrics_parser, suppress_default=True)
-    metrics_parser.add_argument(
-        "--days",
-        type=int,
-        default=30,
-        help="Number of trailing days to include in the snapshot. Defaults to 30.",
-    )
-    metrics_parser.add_argument(
-        "--no-open",
-        action="store_true",
-        help="Generate artifacts without opening the dashboard in the browser.",
-    )
 
     create_parser = subparsers.add_parser(
         "create",
@@ -877,51 +863,54 @@ def _run_admin_command(args: argparse.Namespace) -> int:
 
 
 def _run_metrics_command(args: argparse.Namespace) -> int:
-    """Generate one repo-scoped metrics snapshot and local dashboard artifacts."""
+    """Generate metrics snapshots and artifacts for one or many repos."""
 
     try:
         from app.boot.admin_db import get_optional_admin_db_dsn
         from app.boot.db import get_optional_db_dsn
         from app.periphery.db.engine import get_engine
-        from app.periphery.metrics.artifacts import write_metrics_artifacts
+        from app.periphery.metrics.artifacts import write_metrics_artifacts, write_metrics_index_artifact
         from app.periphery.metrics.browser import open_metrics_dashboard
-        from app.periphery.metrics.render_html import render_metrics_dashboard
-        from app.periphery.metrics.service import build_metrics_snapshot
+        from app.periphery.metrics.render_html import render_metrics_browser_dashboard, render_metrics_dashboard
+        from app.periphery.metrics.service import build_metrics_snapshot, list_metrics_repo_ids
+
+        if bool(getattr(args, "repo_id", None) or getattr(args, "repo_root", None) or getattr(args, "no_sync", False)):
+            raise ValueError("`shellbrain metrics` does not accept options. Run `shellbrain metrics`.")
 
-        repo_context = resolve_repo_context(
-            repo_root_arg=getattr(args, "repo_root", None),
-            repo_id_arg=getattr(args, "repo_id", None),
-        )
         _warn_or_fail_on_unsafe_app_role()
-        _ensure_repo_registration_for_operation(
-            repo_context=repo_context,
-            repo_id_override=getattr(args, "repo_id", None),
-        )
         dsn = get_optional_db_dsn() or get_optional_admin_db_dsn()
         if not dsn:
             raise RuntimeError("Shellbrain database is not configured. Run `shellbrain init` first.")
-        snapshot = build_metrics_snapshot(
-            engine=get_engine(dsn),
-            repo_id=repo_context.repo_id,
-            days=int(args.days),
+        engine = get_engine(dsn)
+
+        target_repo_ids = list_metrics_repo_ids(engine=engine)
+        if not target_repo_ids:
+            print("No tracked repos found in metrics telemetry yet.")
+            return 0
+
+        entries: list[dict[str, Any]] = []
+        window_days = 30
+        for repo_id in target_repo_ids:
+            snapshot = build_metrics_snapshot(
+                engine=engine,
+                repo_id=repo_id,
+                days=window_days,
+            )
+            html = render_metrics_dashboard(snapshot)
+            paths = write_metrics_artifacts(repo_id=repo_id, snapshot=snapshot, html=html)
+            entries.append({"snapshot": snapshot, "paths": paths})
+
+        overview_path = write_metrics_index_artifact(
+            html=render_metrics_browser_dashboard([entry["snapshot"] for entry in entries])
         )
-        html = render_metrics_dashboard(snapshot)
-        paths = write_metrics_artifacts(repo_id=repo_context.repo_id, snapshot=snapshot, html=html)
-        opened_dashboard = False
-        if not bool(getattr(args, "no_open", False)):
-            opened_dashboard = bool(open_metrics_dashboard(paths["html_path"]))
-        print(f"Generated Shellbrain metrics for {repo_context.repo_id}")
-        print(f"Status: {snapshot['status']} ({snapshot['confidence']} confidence)")
-        print(f"JSON: {paths['json_path']}")
-        print(f"Markdown: {paths['md_path']}")
-        print(f"Dashboard: {paths['html_path']}")
+        opened_dashboard = bool(open_metrics_dashboard(overview_path))
+        print(f"Generated Shellbrain metrics for {len(entries)} repos")
+        print(f"Window: last {window_days} days")
         print("Artifacts: updated in place")
-        if bool(getattr(args, "no_open", False)):
-            print("Browser: skipped")
-        elif opened_dashboard:
-            print("Browser: opened dashboard")
+        if opened_dashboard:
+            print("Browser: opened dashboard; use left/right arrow keys in the browser to switch repos")
         else:
-            print("Browser: could not open automatically")
+            print(f"Browser: could not open automatically; open {overview_path}")
         return 0
     except (RuntimeError, ValueError) as exc:
         print(str(exc), file=sys.stderr)

shellbrain-0.1.27/app/periphery/db/models/problem_runs.py

@@ -0,0 +1,60 @@
+"""SQLAlchemy Core table for explicit problem-run telemetry windows."""
+
+from sqlalchemy import CheckConstraint, Column, ForeignKey, Index, String, Table, text
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+_PROBLEM_RUN_STATUSES = "'open', 'closed', 'abandoned'"
+_PROBLEM_RUN_ACTORS = "'worker', 'librarian', 'manual', 'system'"
+
+
+problem_runs = Table(
+    "problem_runs",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("thread_id", String),
+    Column("host_app", String),
+    Column("host_session_key", String),
+    Column("episode_id", String, ForeignKey("episodes.id", ondelete="SET NULL")),
+    Column("status", String, nullable=False),
+    Column("opened_at", TIMESTAMP(timezone=True), nullable=False),
+    Column("closed_at", TIMESTAMP(timezone=True)),
+    Column("opened_by", String, nullable=False),
+    Column("closed_by", String),
+    Column("problem_memory_id", String, ForeignKey("memories.id", ondelete="SET NULL")),
+    Column("solution_memory_id", String, ForeignKey("memories.id", ondelete="SET NULL")),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("NOW()")),
+    Column("updated_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("NOW()")),
+    CheckConstraint(f"status IN ({_PROBLEM_RUN_STATUSES})", name="ck_problem_runs_status"),
+    CheckConstraint(f"opened_by IN ({_PROBLEM_RUN_ACTORS})", name="ck_problem_runs_opened_by"),
+    CheckConstraint(f"closed_by IS NULL OR closed_by IN ({_PROBLEM_RUN_ACTORS})", name="ck_problem_runs_closed_by"),
+    CheckConstraint("closed_at IS NULL OR closed_at >= opened_at", name="ck_problem_runs_closed_after_opened"),
+    CheckConstraint(
+        """
+        (
+          status = 'open'
+          AND closed_at IS NULL
+        ) OR (
+          status IN ('closed', 'abandoned')
+          AND closed_at IS NOT NULL
+        )
+        """,
+        name="ck_problem_runs_status_closed_at",
+    ),
+)
+
+Index("idx_problem_runs_repo_thread_window", problem_runs.c.repo_id, problem_runs.c.thread_id, problem_runs.c.opened_at, problem_runs.c.closed_at)
+Index(
+    "idx_problem_runs_repo_host_session_window",
+    problem_runs.c.repo_id,
+    problem_runs.c.host_app,
+    problem_runs.c.host_session_key,
+    problem_runs.c.opened_at,
+    problem_runs.c.closed_at,
+)
+Index("idx_problem_runs_repo_status_opened_at", problem_runs.c.repo_id, problem_runs.c.status, problem_runs.c.opened_at)
+Index("idx_problem_runs_problem_memory", problem_runs.c.problem_memory_id)
+Index("idx_problem_runs_solution_memory", problem_runs.c.solution_memory_id)

{shellbrain-0.1.25 → shellbrain-0.1.27}/app/periphery/db/models/registry.py

@@ -8,12 +8,13 @@ from app.periphery.db.models import (
     experiences,
     instance_metadata,
     memories,
+    problem_runs,
     telemetry,
     utility,
 )
 from app.periphery.db.models.metadata import metadata
 
 
-_ = (associations, concepts, episodes, evidence, experiences, instance_metadata, memories, telemetry, utility)
+_ = (associations, concepts, episodes, evidence, experiences, instance_metadata, memories, problem_runs, telemetry, utility)
 
 target_metadata = metadata

{shellbrain-0.1.25 → shellbrain-0.1.27}/app/periphery/db/models/views.py

@@ -616,6 +616,218 @@ GROUP BY repo_id, solve_window, read_cohort;
 """
 
 
+USAGE_PROBLEM_TOKENS_LEGACY_SQL = USAGE_PROBLEM_TOKENS_SQL.replace(
+    "CREATE OR REPLACE VIEW usage_problem_tokens AS",
+    "CREATE OR REPLACE VIEW usage_problem_tokens_legacy AS",
+)
+USAGE_PROBLEM_READ_ROI_LEGACY_SQL = (
+    USAGE_PROBLEM_READ_ROI_SQL.replace(
+        "CREATE OR REPLACE VIEW usage_problem_read_roi AS",
+        "CREATE OR REPLACE VIEW usage_problem_read_roi_legacy AS",
+    )
+    .replace("FROM usage_problem_tokens upt", "FROM usage_problem_tokens_legacy upt")
+)
+USAGE_READ_BEFORE_SOLVE_ROI_LEGACY_SQL = (
+    USAGE_READ_BEFORE_SOLVE_ROI_SQL.replace(
+        "CREATE OR REPLACE VIEW usage_read_before_solve_roi AS",
+        "CREATE OR REPLACE VIEW usage_read_before_solve_roi_legacy AS",
+    )
+    .replace("FROM usage_problem_read_roi", "FROM usage_problem_read_roi_legacy")
+)
+
+
+USAGE_PROBLEM_RUN_TOKENS_SQL = """
+CREATE OR REPLACE VIEW usage_problem_run_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'
+  )
+),
+eligible_runs AS (
+  SELECT *
+  FROM problem_runs
+  WHERE status IN ('closed', 'abandoned')
+    AND closed_at IS NOT NULL
+),
+run_usage AS (
+  SELECT
+    prun.id AS problem_run_id,
+    COUNT(mu.id)::INTEGER AS usage_row_count,
+    COUNT(mu.id) FILTER (WHERE mu.capture_quality = 'exact')::INTEGER AS exact_usage_row_count,
+    COUNT(mu.id) FILTER (WHERE mu.capture_quality = 'estimated')::INTEGER AS estimated_usage_row_count,
+    COALESCE(SUM(mu.input_tokens), 0)::BIGINT AS input_tokens,
+    COALESCE(SUM(mu.output_tokens), 0)::BIGINT AS output_tokens,
+    COALESCE(SUM(mu.reasoning_output_tokens), 0)::BIGINT AS reasoning_output_tokens,
+    COALESCE(SUM(mu.cached_input_tokens_total), 0)::BIGINT AS cached_input_tokens_total,
+    COALESCE(SUM(mu.cache_read_input_tokens), 0)::BIGINT AS cache_read_input_tokens,
+    COALESCE(SUM(mu.cache_creation_input_tokens), 0)::BIGINT AS cache_creation_input_tokens,
+    COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)::BIGINT AS foreground_worker_input_tokens,
+    COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)::BIGINT AS foreground_worker_output_tokens,
+    (
+      COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)
+      + COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)
+    )::BIGINT AS foreground_worker_fresh_work_tokens,
+    (
+      COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)
+      + COALESCE(SUM(mu.cached_input_tokens_total) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)
+      + COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role IN ('foreground', 'worker')), 0)
+    )::BIGINT AS foreground_worker_all_tokens_including_cache,
+    COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role = 'librarian'), 0)::BIGINT AS librarian_input_tokens,
+    COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role = 'librarian'), 0)::BIGINT AS librarian_output_tokens,
+    (
+      COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role = 'librarian'), 0)
+      + COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role = 'librarian'), 0)
+    )::BIGINT AS librarian_fresh_work_tokens,
+    (
+      COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role = 'librarian'), 0)
+      + COALESCE(SUM(mu.cached_input_tokens_total) FILTER (WHERE mu.agent_role = 'librarian'), 0)
+      + COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role = 'librarian'), 0)
+    )::BIGINT AS librarian_all_tokens_including_cache,
+    COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)::BIGINT AS other_role_input_tokens,
+    COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)::BIGINT AS other_role_output_tokens,
+    (
+      COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)
+      + COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)
+    )::BIGINT AS other_role_fresh_work_tokens,
+    (
+      COALESCE(SUM(mu.input_tokens) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)
+      + COALESCE(SUM(mu.cached_input_tokens_total) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)
+      + COALESCE(SUM(mu.output_tokens) FILTER (WHERE mu.agent_role NOT IN ('foreground', 'worker', 'librarian')), 0)
+    )::BIGINT AS other_role_all_tokens_including_cache
+  FROM eligible_runs prun
+  LEFT JOIN preferred_rows mu
+    ON mu.repo_id = prun.repo_id
+   AND mu.occurred_at >= prun.opened_at
+   AND mu.occurred_at <= prun.closed_at
+   AND (
+      (
+        prun.host_app IS NOT NULL
+        AND prun.host_session_key IS NOT NULL
+        AND mu.host_app = prun.host_app
+        AND mu.host_session_key = prun.host_session_key
+      )
+      OR (
+        (prun.host_app IS NULL OR prun.host_session_key IS NULL)
+        AND prun.thread_id IS NOT NULL
+        AND mu.thread_id = prun.thread_id
+      )
+   )
+  GROUP BY prun.id
+),
+run_reads AS (
+  SELECT
+    prun.id AS problem_run_id,
+    COUNT(oi.id)::INTEGER AS shellbrain_read_count,
+    COALESCE(SUM(ris.pack_token_estimate), 0)::BIGINT AS shellbrain_pack_tokens,
+    COALESCE(SUM(ris.concept_token_estimate), 0)::BIGINT AS shellbrain_concept_tokens
+  FROM eligible_runs prun
+  LEFT JOIN operation_invocations oi
+    ON oi.repo_id = prun.repo_id
+   AND oi.command = 'read'
+   AND oi.outcome = 'ok'
+   AND oi.created_at >= prun.opened_at
+   AND oi.created_at <= prun.closed_at
+   AND (
+      (
+        prun.host_app IS NOT NULL
+        AND prun.host_session_key IS NOT NULL
+        AND oi.selected_host_app = prun.host_app
+        AND oi.selected_host_session_key = prun.host_session_key
+      )
+      OR (
+        (prun.host_app IS NULL OR prun.host_session_key IS NULL)
+        AND prun.thread_id IS NOT NULL
+        AND oi.selected_thread_id = prun.thread_id
+      )
+   )
+  LEFT JOIN read_invocation_summaries ris ON ris.invocation_id = oi.id
+  GROUP BY prun.id
+)
+SELECT
+  prun.id AS problem_run_id,
+  prun.repo_id,
+  prun.thread_id,
+  prun.host_app,
+  prun.host_session_key,
+  prun.status,
+  prun.opened_at,
+  prun.closed_at,
+  EXTRACT(EPOCH FROM (prun.closed_at - prun.opened_at))::DOUBLE PRECISION AS duration_seconds,
+  prun.problem_memory_id,
+  prun.solution_memory_id,
+  ru.usage_row_count,
+  ru.exact_usage_row_count,
+  ru.estimated_usage_row_count,
+  ru.input_tokens,
+  ru.output_tokens,
+  ru.reasoning_output_tokens,
+  ru.cached_input_tokens_total,
+  ru.cache_read_input_tokens,
+  ru.cache_creation_input_tokens,
+  (
+    ru.input_tokens
+    + ru.output_tokens
+  )::BIGINT AS fresh_work_tokens,
+  (
+    ru.input_tokens
+    + ru.cached_input_tokens_total
+    + ru.output_tokens
+  )::BIGINT AS all_tokens_including_cache,
+  ru.foreground_worker_input_tokens,
+  ru.foreground_worker_output_tokens,
+  ru.foreground_worker_fresh_work_tokens,
+  ru.foreground_worker_all_tokens_including_cache,
+  ru.librarian_input_tokens,
+  ru.librarian_output_tokens,
+  ru.librarian_fresh_work_tokens,
+  ru.librarian_all_tokens_including_cache,
+  ru.other_role_input_tokens,
+  ru.other_role_output_tokens,
+  ru.other_role_fresh_work_tokens,
+  ru.other_role_all_tokens_including_cache,
+  rr.shellbrain_read_count,
+  rr.shellbrain_pack_tokens,
+  rr.shellbrain_concept_tokens
+FROM eligible_runs prun
+JOIN run_usage ru ON ru.problem_run_id = prun.id
+JOIN run_reads rr ON rr.problem_run_id = prun.id;
+"""
+
+
 USAGE_TOKEN_CAPTURE_HEALTH_SQL = """
 CREATE OR REPLACE VIEW usage_token_capture_health AS
 WITH synced_sessions AS (

{shellbrain-0.1.25 → shellbrain-0.1.27}/app/periphery/metrics/artifacts.py

@@ -14,12 +14,18 @@ from app.boot.home import get_shellbrain_home
 _NON_ALNUM = re.compile(r"[^a-z0-9]+")
 
 
+def get_metrics_root_dir() -> Path:
+    """Return the machine-owned root directory for metrics browser artifacts."""
+
+    return get_shellbrain_home() / "reports" / "metrics"
+
+
 def get_metrics_artifact_dir(*, repo_id: str) -> Path:
     """Return the machine-owned artifact directory for one repo's metrics outputs."""
 
     normalized = _NON_ALNUM.sub("-", repo_id.lower()).strip("-") or "repo"
     digest = hashlib.sha1(repo_id.encode("utf-8")).hexdigest()[:8]
-    return get_shellbrain_home() / "reports" / "metrics" / f"{normalized}-{digest}"
+    return get_metrics_root_dir() / f"{normalized}-{digest}"
 
 
 def write_metrics_artifacts(*, repo_id: str, snapshot: dict[str, Any], html: str) -> dict[str, Path]:
@@ -42,3 +48,14 @@ def write_metrics_artifacts(*, repo_id: str, snapshot: dict[str, Any], html: str
         "md_path": md_path,
         "html_path": html_path,
     }
+
+
+def write_metrics_index_artifact(*, html: str) -> Path:
+    """Write the combined browser dashboard for all repo metrics snapshots."""
+
+    artifact_dir = get_metrics_root_dir()
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+
+    html_path = artifact_dir / "index.html"
+    html_path.write_text(html, encoding="utf-8")
+    return html_path