eggpool 0.3.2__tar.gz → 0.3.3__tar.gz

{eggpool-0.3.2 → eggpool-0.3.3}/AGENTS.md

@@ -100,6 +100,7 @@ Use the hierarchy in `errors.py`. Chain exceptions with `raise ... from err` or
 - **Streaming finalizer shielding**: streaming `_build_stream_generator` finalization runs under `asyncio.shield(asyncio.wait_for(..., timeout=10))` so ASGI task cancellation cannot kill the finalizer while it holds the DB lock. Leaks that escape this path are caught by the periodic `stale_request_finalizer` background task (`app._finalize_stale_requests`, runs every 60s) which force-finalizes any request that has been `pending` longer than `upstream.read_timeout_s`.
 - **Startup crash recovery**: `_crash_recovery` runs at every startup and recovers ALL pending requests and ALL active reservations with no time threshold. A process restart is a definitive boundary, so leaked state from the previous process is unconditionally cleaned up. If `Crash recovery: marked N stale requests` appears in logs, the safety net caught leaks from the previous run.
 - **Pricing resolution pipeline**: prices flow TOML override → upstream metadata → external catalog (OpenRouter / OpenCode Zen via the alias registry). `ResolvedPricing` records `source_detail` (`operator_override` / `provider_metadata` / `openrouter` / `opencode_zen`) and `source_confidence` (`exact_external_id` / `curated_alias` / `provider_metadata`). Cost rows are then labelled `derived` (every category trusted), `partial` (some categories filled by per-category fallback), `estimated` (no trusted rates), or `unknown` (no token usage). `partial_count` is a new exactness value exposed via `/api/stats/summary`, `/api/stats/accounts`, and `/api/stats/models`. The dashboard renders a per-row cost-exactness badge and a high-spend estimated warning banner (>$10 estimated) on the Accounts page.
+- **Provider-reported cost precedence**: when an upstream includes a billing field (e.g. `usage.cost`, `usage.cost_usd`, `usage.cost_microdollars`, `usage.billing.cost_usd`), `eggpool.proxy.cost_reporting.extract_provider_reported_cost()` parses it and the `RequestFinalizer` records it on the `requests` row as `provider_cost_microdollars` (with `provider_cost_source` storing the field path). That value takes precedence over locally computed rates — the cost precedence ladder is `provider_reported > derived/partial/exact > estimated (reservation fallback) > unknown (zero)`. Locally calculated cost is still persisted to `local_cost_microdollars` / `local_cost_exactness` for diagnostics, never overrides provider-reported. The new `provider_reported_count` and `provider_reported_cost_microdollars` fields are exposed via `/api/stats/summary`, `/api/stats/accounts`, and `/api/stats/models` and surface in the dashboard's exactness badge and Total-cost card. Migration `0033_request_provider_local_cost.sql` adds the four nullable audit columns. The parser is allowlisted (no arbitrary nested keys) and is defensive — `TypeError`/`ValueError`/`AttributeError`/`RecursionError` yield `None`, so finalization never breaks on a malformed response body.
 - **`eggpool stats recompute-costs [--dry-run|--apply] [--limit N]`**: walks the requests table in started_at DESC order, recomputes cost from the current price snapshots, and reports / applies the change. Default is `--dry-run`. Use after upgrading the resolver to fix inflated totals on cached-token-heavy models (e.g. MiMo 2.5). Implemented in `src/eggpool/cost_recompute.py` and reuses the live `CostCalculator` so the new values match what the finalizer would write today.
 - **Migration 0030 (`model_pricing_aliases`) + 0031 (`price_snapshot_provenance`)**: 0030 introduces the alias registry that maps upstream model IDs (e.g. `mimo-v2.5`) onto external catalog IDs (e.g. `xiaomi/mimo-v2.5`) with an `exact`/`curated_alias`/`ambiguous_skip` confidence enum. 0031 adds `source_detail`, `source_confidence`, `catalog_source` columns to `model_price_snapshots` so the dashboard can attribute prices back to the resolver that produced them. Seed data lives in `seed_default_aliases()` (`src/eggpool/catalog/pricing_aliases.py`) and runs idempotently at startup via `CatalogService.attach_pricing_resolvers()`.
 - **Migration 0032 (`usage_rollups`)**: introduces the rollup table for buffered analytics. Counter fields are designed for additive upserts (`INSERT ... ON CONFLICT DO UPDATE SET col = col + excluded.col`). Latency min/max use `CASE/WHEN` to converge monotonically within each bucket. The `UsageRollupRepository` provides `upsert_many()`, `query_timeseries()`, `query_summary()`, and `cleanup_old_rollups()`.

{eggpool-0.3.2 → eggpool-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eggpool
-Version: 0.3.2
+Version: 0.3.3
 Summary: A lightweight proxy that aggregates multiple LLM provider accounts behind one OpenAI-compatible endpoint
 Project-URL: Homepage, https://github.com/eggstack/eggpool
 Project-URL: Repository, https://github.com/eggstack/eggpool
@@ -375,11 +375,22 @@ dashboard's public/auth setting.
   no error_detail). Auth-gated.
 - **Cost/cache/reasoning exactness** (extended fields on `/api/stats/accounts`
   and `/api/stats/models`): per-account and per-model `exact_count`,
-  `partial_count`, `derived_count`, `estimated_count`, `cache_read_ratio`,
-  `cache_write_ratio`, `reasoning_output_ratio`, `estimated_cost_fraction`,
-  `avg_cost_per_request`, `avg_cost_per_1k_tokens`. Lets you see which
-  accounts/models/providers report exact usage versus partially-priced
-  versus locally estimated cost.
+  `partial_count`, `derived_count`, `estimated_count`, `provider_reported_count`,
+  `cache_read_ratio`, `cache_write_ratio`, `reasoning_output_ratio`,
+  `estimated_cost_fraction`, `avg_cost_per_request`, `avg_cost_per_1k_tokens`.
+  Lets you see which accounts/models/providers report exact usage versus
+  partially-priced versus locally estimated cost versus upstream-billed cost.
+- **Provider-reported cost precedence**: when an upstream provider includes a
+  billing field in its response (`usage.cost_microdollars`, `usage.cost_usd`,
+  `usage.billing.cost_usd`, OpenCode Go's `usage.cost`/`usage.total_cost`),
+  that value is recorded on the `requests` row in `provider_cost_microdollars`
+  (with `provider_cost_source` recording the field path) and the request
+  exactness is labelled `provider_reported`. Provider-reported cost is the
+  most-trusted tier in the cost precedence ladder — it precedes locally
+  derived rates (per-token pricing) and reservation-derived estimates
+  (`estimated`), and is never overridden by them. Locally calculated values
+  are still stored in `local_cost_microdollars` and `local_cost_exactness`
+  for diagnostics comparison.
 - **Pricing provenance** (`/api/stats/pricing-provenance`): per-`(model,
   provider)` snapshot breakdown of `source_detail` (operator override vs.
   upstream metadata vs. OpenRouter catalog vs. curated alias) and

{eggpool-0.3.2 → eggpool-0.3.3}/README.md

@@ -331,11 +331,22 @@ dashboard's public/auth setting.
   no error_detail). Auth-gated.
 - **Cost/cache/reasoning exactness** (extended fields on `/api/stats/accounts`
   and `/api/stats/models`): per-account and per-model `exact_count`,
-  `partial_count`, `derived_count`, `estimated_count`, `cache_read_ratio`,
-  `cache_write_ratio`, `reasoning_output_ratio`, `estimated_cost_fraction`,
-  `avg_cost_per_request`, `avg_cost_per_1k_tokens`. Lets you see which
-  accounts/models/providers report exact usage versus partially-priced
-  versus locally estimated cost.
+  `partial_count`, `derived_count`, `estimated_count`, `provider_reported_count`,
+  `cache_read_ratio`, `cache_write_ratio`, `reasoning_output_ratio`,
+  `estimated_cost_fraction`, `avg_cost_per_request`, `avg_cost_per_1k_tokens`.
+  Lets you see which accounts/models/providers report exact usage versus
+  partially-priced versus locally estimated cost versus upstream-billed cost.
+- **Provider-reported cost precedence**: when an upstream provider includes a
+  billing field in its response (`usage.cost_microdollars`, `usage.cost_usd`,
+  `usage.billing.cost_usd`, OpenCode Go's `usage.cost`/`usage.total_cost`),
+  that value is recorded on the `requests` row in `provider_cost_microdollars`
+  (with `provider_cost_source` recording the field path) and the request
+  exactness is labelled `provider_reported`. Provider-reported cost is the
+  most-trusted tier in the cost precedence ladder — it precedes locally
+  derived rates (per-token pricing) and reservation-derived estimates
+  (`estimated`), and is never overridden by them. Locally calculated values
+  are still stored in `local_cost_microdollars` and `local_cost_exactness`
+  for diagnostics comparison.
 - **Pricing provenance** (`/api/stats/pricing-provenance`): per-`(model,
   provider)` snapshot breakdown of `source_detail` (operator override vs.
   upstream metadata vs. OpenRouter catalog vs. curated alias) and

{eggpool-0.3.2 → eggpool-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eggpool"
-version = "0.3.2"
+version = "0.3.3"
 description = "A lightweight proxy that aggregates multiple LLM provider accounts behind one OpenAI-compatible endpoint"
 readme = "README.md"
 requires-python = ">=3.11"

{eggpool-0.3.2 → eggpool-0.3.3}/scripts/check_database.py

@@ -61,7 +61,7 @@ class InvariantQueryError(CheckerError):
 #: Highest migration number this checker knows how to inspect.
 #: If the database is older or newer than this, the checker
 #: returns exit code 2 with a clear message.
-EXPECTED_SCHEMA_VERSION = 32
+EXPECTED_SCHEMA_VERSION = 33
 
 #: Required tables for the production EggPool schema.
 REQUIRED_TABLES: frozenset[str] = frozenset(

{eggpool-0.3.2 → eggpool-0.3.3}/src/eggpool/api/stats.py

@@ -45,13 +45,30 @@ async def handle_summary(request: Request, period: str | None = "24h") -> Respon
 
 
 async def handle_account_stats(
-    request: Request, period: str | None = "24h"
+    request: Request,
+    period: str | None = "24h",
+    include_disabled: bool = True,
 ) -> Response:
-    """GET /api/stats/accounts."""
+    """GET /api/stats/accounts.
+
+    ``include_disabled`` defaults to True so existing API consumers
+    continue to see soft-deleted (``enabled = 0``) accounts — their
+    historical request/cost rows must still be attributable to the
+    account that produced them. Pass ``?include_disabled=0`` to hide
+    them, mirroring the dashboard's "Show disabled accounts" toggle.
+    """
     time_range = resolve_time_range(period)
     stats = request.app.state.stats
-    accounts = await stats.get_account_stats(time_range)
-    return JSONResponse(content={"period": time_range.label, "accounts": accounts})
+    accounts = await stats.get_account_stats(
+        time_range, include_disabled=include_disabled
+    )
+    return JSONResponse(
+        content={
+            "period": time_range.label,
+            "include_disabled": include_disabled,
+            "accounts": accounts,
+        }
+    )
 
 
 async def handle_model_stats(

{eggpool-0.3.2 → eggpool-0.3.3}/src/eggpool/catalog/catalog_resolvers.py

@@ -231,9 +231,13 @@ class OpenRouterCatalogResolver:
             if not isinstance(model_id_obj, str) or not model_id_obj:
                 continue
             pricing_obj: object = raw_dict.get("pricing") or {}
-            entry = OpenRouterCatalogResolver._parse_entry(
-                model_id_obj, pricing_obj, raw_dict
-            )
+            try:
+                entry = OpenRouterCatalogResolver._parse_entry(
+                    model_id_obj, pricing_obj, raw_dict
+                )
+            except (ValueError, TypeError) as exc:
+                logger.warning("Skipping catalog entry %r: %s", model_id_obj, exc)
+                continue
             entries[model_id_obj] = entry
         return entries
 

{eggpool-0.3.2 → eggpool-0.3.3}/src/eggpool/catalog/pricing.py

@@ -65,7 +65,7 @@ def _extract_decimal(value: object) -> Decimal | None:
     if not number.is_finite():
         raise ValueError("price must be finite")
     if number < 0:
-        raise ValueError("price must be non-negative")
+        return None
     return number
 
 

{eggpool-0.3.2 → eggpool-0.3.3}/src/eggpool/dashboard/render.py

@@ -162,8 +162,12 @@ _CARD_TOOLTIPS: dict[str, str] = {
         "Fraction of requests in the selected period that ended in an error."
     ),
     "Total cost": (
-        "Total recorded request cost in the selected period, using the current "
-        "cost exactness pipeline."
+        "Total recorded request cost in the selected period. When the upstream "
+        "provider reports a cost (e.g. OpenCode Go's usage.cost field), that "
+        "value takes precedence over locally computed rates; otherwise eggpool "
+        "falls back to per-token rates from the catalog. Reservation-derived "
+        "estimates are advisory and never inflate the totals when more "
+        "trustworthy data is available."
     ),
     "Utilization imbalance": (
         "Coefficient of variation across active accounts. Higher values mean "
@@ -575,18 +579,27 @@ def _render_nav(
         ("runtime", "/runtime", "Runtime"),
     ]
     parts = ['<nav class="topnav">']
-    # Wrap the page links in a hamburger <details> on phone viewports.
-    # The CSS layer shows the <summary> as a Menu chip below 480px and
-    # reveals `.topnav-links` when open; on wider viewports the summary
-    # is hidden and the links are always visible inline. Theme selector
-    # and refresh button stay outside the disclosure so they remain
-    # reachable on every viewport size.
-    parts.append('<details class="topnav-hamburger">')
+    # Mobile burger button + collapsible menu panel. The CSS layer hides
+    # the burger and reveals `.topnav-menu` inline on viewports ≥761px;
+    # on narrower viewports the burger is shown and the menu only opens
+    # when JS toggles `.topnav-open` on the nav (see
+    # `dashboard.js#initNavToggle`). Theme selector and refresh button
+    # stay outside the menu so they remain reachable on every viewport
+    # size.
     parts.append(
-        '<summary data-tooltip="Open page menu" '
-        'aria-label="Open page menu">Menu</summary>'
+        '<button class="topnav-burger" type="button" '
+        'data-tooltip="Open page menu" '
+        'aria-label="Open page menu" '
+        'aria-expanded="false" aria-controls="topnav-menu">'
+        '<svg class="topnav-burger-icon" viewBox="0 0 22 16" '
+        'width="22" height="16" aria-hidden="true" focusable="false">'
+        '<rect class="bar bar-1" x="0" y="0" width="22" height="2" rx="1"/>'
+        '<rect class="bar bar-2" x="0" y="7" width="22" height="2" rx="1"/>'
+        '<rect class="bar bar-3" x="0" y="14" width="22" height="2" rx="1"/>'
+        "</svg>"
+        "</button>"
     )
-    parts.append('<div class="topnav-links">')
+    parts.append('<div class="topnav-menu" id="topnav-menu">')
     for key, href, label in items:
         cls = "active" if key == active_nav else ""
         parts.append(
@@ -595,7 +608,6 @@ def _render_nav(
             f"{_html_escape(label)}</a>"
         )
     parts.append("</div>")
-    parts.append("</details>")
 
     # Theme selector dropdown
     themes: list[str] = available_themes or []
@@ -664,6 +676,92 @@ def _render_period_selector(current: str, current_theme: str = "") -> str:
     )
 
 
+def _render_account_filters(
+    period: str,
+    current_theme: str,
+    show_disabled: bool,
+) -> str:
+    """Render a single GET-form filter bar for the Accounts page.
+
+    Bundles the period selector and the ``show_disabled`` toggle into
+    one form so either change preserves the other via hidden inputs.
+    Disabled rows are hidden by default so the page matches the
+    operator's mental model after ``eggpool logout``; the toggle is
+    opt-in and lives server-side in the URL (``?show_disabled=1``) so
+    it survives refresh, is bookmarkable, and works without JS.
+    """
+    period_options = [
+        ("1h", "Last hour"),
+        ("24h", "Last 24 hours"),
+        ("7d", "Last 7 days"),
+        ("30d", "Last 30 days"),
+    ]
+    period_items: list[str] = []
+    for value, label in period_options:
+        selected = ' selected="selected"' if value == period else ""
+        period_items.append(
+            f'<option value="{escape(value)}"{selected}>{escape(label)}</option>'
+        )
+    period_selector = "".join(period_items)
+
+    show_options = [
+        ("0", "Hide disabled accounts"),
+        ("1", "Show disabled accounts"),
+    ]
+    show_items: list[str] = []
+    show_value = "1" if show_disabled else "0"
+    for value, label in show_options:
+        selected = ' selected="selected"' if value == show_value else ""
+        show_items.append(
+            f'<option value="{escape(value)}"{selected}>{escape(label)}</option>'
+        )
+    show_selector = "".join(show_items)
+
+    theme_hidden = (
+        f'<input type="hidden" name="theme" value="{escape_attr(current_theme)}">'
+        if current_theme
+        else ""
+    )
+    return (
+        f'<form method="get" class="period-selector account-filters" '
+        f'data-period-selector aria-label="Account filters">'
+        f'<label for="period">Period: </label>'
+        f'<select id="period" name="period" data-auto-submit="1">'
+        f"{period_selector}"
+        f"</select>"
+        f'<label for="show_disabled">Disabled: </label>'
+        f'<select id="show_disabled" name="show_disabled" '
+        f'data-auto-submit="1">'
+        f"{show_selector}"
+        f"</select>"
+        f"{theme_hidden}"
+        f"</form>"
+    )
+
+
+def _render_accounts_empty_state(
+    show_disabled: bool,
+    disabled_count: int,
+) -> str:
+    """Render the empty-state hint for the Accounts page.
+
+    When the operator has filtered disabled rows out and there are no
+    enabled rows left, offer a one-click opt-in to the historical view
+    instead of the generic "No accounts configured." message. The link
+    is plain anchor navigation, so it works without JS.
+    """
+    if show_disabled or disabled_count <= 0:
+        return '<p class="empty">No accounts configured.</p>'
+    plural = "s" if disabled_count != 1 else ""
+    return (
+        '<p class="empty">'
+        "No enabled accounts. "
+        f"{disabled_count} disabled account{plural} hidden — "
+        '<a href="?show_disabled=1">show them</a>.'
+        "</p>"
+    )
+
+
 _HIGH_SPEND_ESTIMATED_DOLLARS = 10.0
 
 
@@ -736,16 +834,19 @@ def _render_pricing_exactness_badge(
     partial: int,
     estimated: int,
     unknown_exc: int,
+    provider_reported: int = 0,
 ) -> str:
     """Render a compact exactness badge.
 
     The badge is colored by the worst-case exactness observed: green when
-    every row is ``exact`` or ``derived``, yellow when any ``partial``
-    row exists, red when ``estimated`` or ``unknown`` dominates. Used
-    on the Accounts / Models tables so operators can spot rows whose
-    cost numbers are advisory at a glance.
+    every row is ``exact``, ``derived``, or ``provider_reported``, yellow
+    when any ``partial`` row exists, red when ``estimated`` or ``unknown``
+    dominates. Used on the Accounts / Models tables so operators can spot
+    rows whose cost numbers are advisory at a glance. ``provider_reported``
+    is the most-trusted category because it reflects the upstream's own
+    billing record.
     """
-    total = exact + derived + partial + estimated + unknown_exc
+    total = exact + derived + partial + estimated + unknown_exc + provider_reported
     if total == 0:
         return '<span class="exactness-badge empty">—</span>'
     if estimated == total or unknown_exc == total:
@@ -754,7 +855,10 @@ def _render_pricing_exactness_badge(
         css_class = "exactness-badge partial-mix"
     else:
         css_class = "exactness-badge derived"
-    summary = f"e:{exact},d:{derived},p:{partial},~:{estimated},?:{unknown_exc}"
+    summary = (
+        f"u:{provider_reported},e:{exact},d:{derived},"
+        f"p:{partial},~:{estimated},?:{unknown_exc}"
+    )
     return f'<span class="{css_class}" title="{escape(summary)}">{summary}</span>'
 
 
@@ -1333,6 +1437,7 @@ def render_overview(
     derived = int(summary.get("derived_count", 0))
     estimated = int(summary.get("estimated_count", 0))
     unknown_exc = int(summary.get("unknown_count", 0))
+    provider_reported = int(summary.get("provider_reported_count", 0))
     bytes_in = format_bytes(summary.get("total_bytes_received", 0))
     bytes_out = format_bytes(summary.get("total_bytes_emitted", 0))
 
@@ -1367,7 +1472,14 @@ def render_overview(
                 _render_metric_card(
                     title="Total cost",
                     metric=cost,
-                    sub=f"in {in_tok} · out {out_tok} · total {total_tok}",
+                    sub=(
+                        f"in {in_tok} · out {out_tok} · total {total_tok}"
+                        + (
+                            f" · {provider_reported:,} provider-billed"
+                            if provider_reported > 0
+                            else ""
+                        )
+                    ),
                 ),
                 _render_metric_card(
                     title="Utilization imbalance",
@@ -1412,8 +1524,9 @@ def render_overview(
                     title="Exactness",
                     metric=f"{exact:,}",
                     sub=(
-                        f"exact · {derived:,} derived · {estimated:,} est · "
-                        f"{unknown_exc:,} unk"
+                        f"exact · {derived:,} derived · "
+                        f"{provider_reported:,} upstream · "
+                        f"{estimated:,} est · {unknown_exc:,} unk"
                     ),
                 ),
             ]
@@ -1581,12 +1694,14 @@ def _render_account_table(accounts: list[dict[str, Any]]) -> str:
         partial_count = int(row.get("partial_count", 0) or 0)
         estimated = int(row.get("estimated_count", 0) or 0)
         unknown_exc = int(row.get("unknown_count", 0) or 0)
+        provider_reported = int(row.get("provider_reported_count", 0) or 0)
         exactness = _render_pricing_exactness_badge(
             exact=exact,
             derived=derived,
             partial=partial_count,
             estimated=estimated,
             unknown_exc=unknown_exc,
+            provider_reported=provider_reported,
         )
         est_cost_fraction = row.get("estimated_cost_fraction")
         est_cost_pct = (
@@ -1688,14 +1803,33 @@ def render_accounts(
     available_themes: list[str] | None = None,
     current_theme: str = "",
     update_info: Any | None = None,
+    *,
+    show_disabled: bool = False,
+    disabled_count: int = 0,
 ) -> str:
-    """Render the accounts page."""
+    """Render the accounts page.
+
+    ``show_disabled`` controls whether soft-deleted accounts (those
+    ``sync_from_config`` marked ``enabled = 0`` after ``eggpool logout``)
+    are listed. Defaults to False so the page matches the operator's
+    mental model after logout.
+
+    ``disabled_count`` is the total disabled-row count, used only when
+    ``accounts`` is empty AND ``show_disabled`` is False: the empty
+    state becomes a one-click "N disabled — show them?" hint instead
+    of the generic "No accounts configured." message.
+    """
+    table_html = (
+        _render_accounts_empty_state(show_disabled, disabled_count)
+        if not accounts
+        else _render_account_table(accounts)
+    )
     body = f"""
 <h2>Accounts</h2>
-{_render_period_selector(period, current_theme)}
+{_render_account_filters(period, current_theme, show_disabled)}
 {_render_pricing_warnings(accounts)}
 <section class="panel">
-  {_render_account_table(accounts)}
+  {table_html}
 </section>
 """
     return _render_layout(
@@ -1763,12 +1897,14 @@ def render_models(
             partial_count = int(row.get("partial_count", 0) or 0)
             estimated = int(row.get("estimated_count", 0) or 0)
             unknown_exc = int(row.get("unknown_count", 0) or 0)
+            provider_reported = int(row.get("provider_reported_count", 0) or 0)
             exactness = _render_pricing_exactness_badge(
                 exact=exact,
                 derived=derived,
                 partial=partial_count,
                 estimated=estimated,
                 unknown_exc=unknown_exc,
+                provider_reported=provider_reported,
             )
             est_cost_fraction = row.get("estimated_cost_fraction")
             est_cost_pct = (

{eggpool-0.3.2 → eggpool-0.3.3}/src/eggpool/dashboard/routes.py

@@ -31,6 +31,7 @@ from eggpool.dashboard.render import (
 )
 from eggpool.errors import ConfigError
 from eggpool.stats import TimeRange, resolve_time_range
+from eggpool.stats.queries import fetch_disabled_account_count
 
 if TYPE_CHECKING:
     from fastapi.responses import Response  # noqa: TCH004
@@ -252,13 +253,35 @@ async def handle_overview(
 
 
 async def handle_accounts(
-    request: Request, period: str | None = "24h", theme: str | None = None
+    request: Request,
+    period: str | None = "24h",
+    theme: str | None = None,
+    show_disabled: bool = False,
 ) -> Response:
-    """Render the accounts page."""
+    """Render the accounts page.
+
+    ``show_disabled`` defaults to False so the page matches the
+    operator's mental model after ``eggpool logout``: disabled rows
+    are hidden by default. Pass ``?show_disabled=1`` to opt in to the
+    historical view (soft-deleted accounts still appear with
+    ``Enabled = no``).  When the operator filters disabled rows out and
+    the empty result set hides disabled tombstones, the renderer shows
+    a one-click "N disabled — show them?" hint instead of the generic
+    "No accounts configured." empty state.
+    """
     _get_dashboard_config(request)
     time_range = resolve_time_range(period)
     stats = request.app.state.stats
-    accounts = await stats.get_account_stats(time_range, use_cache=True)
+
+    # Always fetch the disabled count so the empty state can offer the
+    # one-click opt-in even when no rows are currently visible.
+    disabled_count = 0
+    if not show_disabled:
+        disabled_count = await fetch_disabled_account_count(request.app.state.stats_db)
+
+    accounts = await stats.get_account_stats(
+        time_range, include_disabled=show_disabled, use_cache=True
+    )
     theme_css, _, current_theme, available = _get_theme_data(request, theme)
     return HTMLResponse(
         content=render_accounts(
@@ -268,6 +291,8 @@ async def handle_accounts(
             available_themes=available,
             current_theme=current_theme,
             update_info=_get_update_info(request),
+            show_disabled=show_disabled,
+            disabled_count=disabled_count,
         )
     )