eggpool 0.5.2__tar.gz → 0.5.4__tar.gz

eggpool-0.5.4/AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS.md
+
+## Skills
+
+Project-specific skills are in `.opencode/skills/`:
+
+- `architecture` — design principles, request lifecycle, invariants, error hierarchy
+- `deployment` — production deployment, systemd, operational scripts
+- `development` — linting, testing, pre-commit checks, code style
+
+## Quick Start
+
+- Package manager: **uv** (not pip). Install deps: `uv sync --extra dev`
+- CI installs with `uv sync --frozen --extra dev` (locks match `uv.lock` exactly)
+- Entry point: `src/eggpool/cli.py` → `eggpool` console script
+- Config: `config.toml` + `.env` for API keys
+
+## Pre-commit Checks (run before every commit)
+
+```bash
+uv run ruff format --check src/ tests/ scripts/
+uv run ruff check src/ tests/ scripts/
+uv run pyright src/ scripts/
+uv run pytest
+```
+
+All four must pass with zero errors.
+
+## Focused Verification
+
+Run specific test subsets without waiting for the full suite:
+
+```bash
+# Request-path correctness only (routing, transcoding, finalization)
+uv run pytest -m request_path -v
+
+# Dashboard and cache-page tests only
+uv run pytest -m dashboard -v
+
+# Performance baseline tests only
+uv run pytest -m performance -v
+
+# Single test file
+uv run pytest tests/unit/test_contract.py -v
+
+# Single test by name
+uv run pytest -k "test_routing_plan_fallback" -v
+
+# Hot-path request-path closure tests (Phases 1–5 + corrective polish + final polish)
+uv run pytest tests/unit/test_proxy_request_hotpath_modes.py tests/unit/test_hotpath_corrective_polish.py tests/unit/test_runtime_dispatch_spans_dashboard.py -v
+
+# Lint auto-fix
+uv run ruff check --fix src/
+
+# Type check with errors only
+uv run pyright src/ scripts/ 2>&1 | head -20
+```
+
+CI sets `PYTHONHASHSEED=0` and `TZ=UTC`; reproduce locally for deterministic results.
+
+## Code Style
+
+- Python 3.11+ with `from __future__ import annotations` in ALL files
+- Type hints on all function signatures and return types
+- Ruff: E, F, W, I, N, UP, B, A, SIM, TCH rules
+- Pyright strict mode — covers `src/` AND `scripts/` (not tests)
+- Line length: 88 chars
+- Use `NoReturn` for functions that never return (e.g., `sys.exit`)
+
+## Testing
+
+- pytest with `asyncio_mode = "strict"` (from `pyproject.toml`)
+- respx for HTTPX upstream mocking
+- Tests in `tests/unit/`, `tests/integration/`, `tests/contract/`, `tests/perf/`
+- Provider contract tests: `uv run pytest tests/unit/test_contract.py tests/unit/test_contract_urls.py -v`
+
+## File Organization
+
+- Source: `src/eggpool/`
+- Tests: `tests/` (mirrors src structure)
+- Config: `config.example.toml`, `.env.example`
+- DB schema: `src/eggpool/db/schema/`
+- Scripts: `scripts/` (operational, also type-checked by pyright)
+- Deployment: `deploy/`
+- Shared assets: `src/eggpool/_share/` (bundled config examples for pipx installs)
+
+## Architecture Index
+
+> Full design details are in `architecture/README.md` and the `architecture` skill.
+
+- **Request lifecycle**: `RequestCoordinator` orchestrates endpoint → routing → persistence → dispatch → finalization.
+- **Multi-provider architecture**: provider-suffixed model IDs (`model-id/provider-id`), `ProviderClientPool`, `OutboundClientManager`.
+- **Provider contracts**: `compose_provider_url()` is the single source of truth for upstream URLs.
+- **Protocol transcoding**: transparent request/response format conversion between OpenAI and Anthropic protocols. Implemented in `src/eggpool/transcoder/` and `src/eggpool/request/coordinator.py`.
+- **Database invariants**: SQLite WAL, single-connection serialization, `async with db.transaction():` for all DML.
+- **Quota and routing**: tier-based routing via `routing_priority`, `QuotaFairScorer`, upstream-authoritative suppression, same-tier fairness rotor.
+- **Error hierarchy**: `AggregatorError` → `UpstreamError` → specific subclasses. `CapabilityError` for thinking/reasoning capability mismatches. `TranscodeLossError` (HTTP 400) for loss-policy reject. `ProtocolMismatchError` for endpoint/model-protocol mismatches.
+- **Process model**: supervisor + Granian worker (`workers=1`), PID file lifecycle, daemon mode (default for `eggpool serve`; `--verbose` for foreground). Default `runtime_threads=2`, `database_worker_threads=2` (separate read-only stats connection). Startup logs `Granian profile: workers=1 runtime_threads=N database_worker_threads=M access_log=...`.
+- **Dashboard**: server-rendered HTML, Chart.js v4, grouped timeseries, CSS tooltips. Dashboard HTML pages use a 30s in-memory cache (`DashboardTelemetry`) for heavy aggregate queries. Telemetry exposes p50/p95 render times and slowest route under `/api/stats/runtime`.
+- **Model capabilities**: protocol-neutral `ThinkingCapability` / `ModelCapabilities` with deterministic merge. Config overrides at `[model_capabilities."<id>".thinking]` and per-provider scoped.
+- **Catalog refresh**: non-destructive by default; destructive withdrawal gated on `authoritative=True AND allow_withdrawals=True`. `static_models` is the source of truth for provider-specific protocol.
+- **Cache & request-shaping diagnostics**: dashboard `/cache` page renders provider cache counters, request segmentation, compression (observe-mode analysis and safe-mode details collapsed by default), policy overrides, native cache preservation, EggPool cache annotations, tuning suggestions, and routing isolation. The `/runtime` page shows only a lightweight Cache & request shaping relocation panel. `QuotaFairScorer` does NOT consume cache, compression, synthetic-cache, or tuning fields — routing stays load-based (request count + token count + active count + health). `tests/unit/test_routing_guardrails.py` pins the invariant. The top `/cache` summary carries six operator-facing cards: Request changes, Provider cache counters, EggPool cache annotations, Safety guardrail, Tuning suggestions, Routing isolation. Quiet default renders show `Clean` / `Isolated` (not raw `reporting_only` or `—`); raw modes survive in subtext/details. Provider cache counters and EggPool cache annotations are separate cards and are explicitly NOT conflated — missing provider cache counters are not cache misses. The advanced diagnostics disclosure is server-decided by `CacheAdvancedState` (`src/eggpool/dashboard/render.py`) and auto-opens for compression warnings / failed fallbacks / stable-prefix mismatches, policy warnings, EggPool annotation warnings or applied count, segmentation parse failures, tuning recommendations or overrides, routing guardrail violations, and transcoding loss warnings. `tests/unit/test_dashboard_cache_page.py` pins the corrected semantics.
+- **Rollup correctness invariants**: `usage_rollups.bucket_start` is `YYYY-MM-DD HH:MM:SS` UTC (matches `format_dt`) — legacy `T...Z` rows are normalized by migration `0047_normalize_rollup_bucket_start.sql`. Cache read share uses the bounded denominator `cache_read / (input + cache_read + cache_write)`, returns `None` when zero. Rollup-backed summaries are gated by `_rollup_is_fresh` so a stalled coalescer cannot under-report the in-flight hour. `fresh_tokens = input + output` and `accounted_tokens = input + output + cache_read + cache_write` are added to the summary payload. Runtime diagnostics expose `rollup_freshness.staleness_seconds` under `/api/stats/runtime`.
+- **Model info sources**: `src/eggpool/model_info/` enriches model metadata from multiple sources (OpenRouter, Artificial Analysis, HuggingFace, provider catalog) with dedup, identity resolution, and scheduler-driven refresh.
+- **Background tasks**: `src/eggpool/background/` manages retention cleanup, periodic tasks, and startup crash recovery via `TaskSupervisor`. `TaskSupervisor.register(...)` covers daemon-style long-lived coroutines; `TaskSupervisor.register_periodic(...)` covers supervisor-owned periodic scheduling around a one-shot tick factory and records `mode`, `last_tick_started_at`, `last_tick_completed_at`, `last_tick_duration_ms`, `next_run_at`, `overdue_seconds`, `success_count`, `failure_count`, `consecutive_failure_count`, and `last_error_class` so healthy sleeping loops no longer render as ``overdue`` (the legacy `last_started_at + interval_s` math is gone — see `plans/background-task-overdue-remediation.md`). First-tick semantics: default callers sleep `interval_s` before the first tick; `initial_delay_s` overrides the first-tick delay; `run_immediately=True` fires the first tick without delay. `run_immediately` and `initial_delay_s` are mutually exclusive (`ValueError` if both supplied). Overdue detection uses a 25%-of-interval grace band (clamped to 5-60 s). Background task summary (`registered` / `running` / `failed` / `overdue` / `last_error_count`) is exposed under `/api/stats/runtime` via `background_task_summary`. The lifespan shutdown path stops the supervisor first (`stop_all()`) so no new ticks arrive, then performs the final `metrics_coalescer.flush(reason="shutdown")` to drain buffered analytics. `MetricsWriteCoalescer.flush()` is cancellation-safe: if the flush task is cancelled mid-DB-write, the buffer snapshot is merged back so no events are silently dropped. Legacy `_finalize_stale_requests`, `_prune_health_disabled_models_loop`, and `_catalog_refresh_loop` `while True` wrappers are retained as `# pyright: ignore[reportUnusedFunction]` legacy entry points so existing tests still drive the seam-decomposed helpers (`_finalize_stale_requests_once`, `_prune_health_disabled_models_once`, `_catalog_refresh_once`).
+- **Health management**: `src/eggpool/health/` implements `HealthManager` circuit breaker and per-account health tracking for routing eligibility.
+- **Retry classification**: `src/eggpool/retry/` classifies upstream errors for failover and retry decisions.
+- **Security**: `src/eggpool/security/` handles header redaction middleware and security utilities.
+- **Integrations**: `src/eggpool/integrations/` generates external tool configs (OpenCode, Claude Code, Aider, Codex, etc.).
+- **Safe compression and advanced overrides**: `src/eggpool/transcoder/compression/` implements observe/safe compression, policy resolution, advisory tuning, and the deterministic markers used for operator visibility.
+- **Replay fixtures**: `tests/fixtures/cache_compression/` holds sanitized JSON fixtures (content-private, never enter routing). `tests/helpers/cache_compression_replay.py` is the harness. Treat them as developer regression assets, not operator surfaces.
+- **Performance optimization (Phases 0–5)**: correctness-preserving hot-path pass. Phase 0 reuses transcode preflight via `PreparedTranscode` (`src/eggpool/transcoder/prepared.py`) with debug observability on `PreparedTranscodeDiagnostics` (`available`, `reused`, `recompute_reason`). Phase 0.5 skips segmentation when no compression/cache/observability features are active (`should_segment_request` in `src/eggpool/transcoder/segmentation_guard.py`) — gating is driven by the resolved effective compression policy, not the raw global config. Phase 0.6 computes routing in a single `RoutingPlan` pass (`Router.build_routing_plan()` in `src/eggpool/routing/router.py`) instead of double-calling `get_eligible_account_names()` + `select_accounts_for_failover()` — this is the authoritative selection path with no fallback to the legacy `select_accounts()`. Phase 0.7 adds configurable `[routing.trace]` mode (`all`/`sampled`/`off`) with deterministic request-id sampling at write time. Benchmarks: `tests/perf/`.
+- **Hot-path dispatch and compression optimization (Phases 1–5)**: Phase 1 adds fine-grained dispatch spans via `DispatchSpanRecorder` (200-sample window) with ~22 `SPAN_*` constants in `runtime_dispatch.py`; spans available via `/api/stats/runtime` `dispatch_spans`. Phase 2 removes duplicate safe-mode work: safe-mode observation is derived from a single `apply_safe_compression()` pass (`SafeModeObservation` duck-types `CompressionObservation`), so the separate `analyze_compression()` call is skipped in safe mode. Phase 3 uses `_copy_with_replacements()` path-level copy-on-write in safe compression; no-op requests forward the original payload without deep-copy. Phase 4 uses single-pass `_build_result()` aggregation in segmentation, avoids representative text allocation for zero-signal segments, and precomputes `estimated_reservation_tokens`, `estimated_context_input_tokens`, and `thinking_requirement` on `ProxyRequestContext`. Phase 5 narrows `_select_lock` to correctness-critical work only and reduces routing trace pressure via `[routing.trace].mode`.
+- **Hot-path corrective polish**: closure pass over the Phase 1–5 landing. Selection lock wait/held spans (`SPAN_SELECTION_LOCK_WAIT`, `SPAN_SELECTION_LOCKED`) record exactly one sample per attempt via explicit `record_ns()` calls after the lock exits — there is no `_maybe_span` placeholder for the lock, so the wait/locked p50/p95 metrics are not polluted by near-zero or double-sampled values. `CompressionResult` carries applier-derived `candidate_count`, `eligible_candidate_count`, `suppressed_candidate_count`, and `applied_transform_count` so safe-mode observation counts meaningful candidates (not just applied transforms) without a second observe pass. `SafeModeObservation.to_summary_json()` always emits `source: "safe_apply"` and keeps `transform_counts` as applied-transform counts. Safe-mode `apply_safe_compression()` runs in a single pass: no-op returns the original payload object by identity, applied runs return a path-level copy-on-write payload that copies only the dict/list ancestors on each mutated path and shares unchanged subtrees by reference (this is *not* a full deep copy). `_copy_with_replacements()` is pinned by direct unit tests for: no-op identity, single dict path, single list path, multiple shared-prefix replacements, multiple disjoint branches, duplicate-path last-wins, invalid-path fail-closed, and chained transforms. The runtime dashboard renders a `Dispatch spans` panel that lists the actionable spans (`coordinator_pre_upstream_ms`, `segmentation_ms`, `compression_analyze_ms`, `compression_apply_ms`, `selection_lock_wait_ms`, `selection_locked_ms`, `routing_trace_write_ms`) with p50/p95/max plus `sample_count`, and absent spans render as "not observed in recent window" instead of `0 ms`.
+- **Hot-path final polish**: request-path-level closure over Phases 1–5 + corrective polish. `tests/unit/test_proxy_request_hotpath_modes.py` exercises the full `handle_proxy_request()` pipeline (segmentation → safe apply / observe analyze / disabled short-circuit → `ProxyRequestContext` → coordinator dispatch) and pins each mode's helper calls and recorded spans. Safe mode calls `apply_safe_compression` exactly once and `analyze_compression` zero times; observe mode calls `analyze_compression` exactly once and `apply_safe_compression` zero times; disabled mode calls none of them and emits no compression spans. `tests/unit/test_runtime_dispatch_spans_dashboard.py` runs the JSON snapshot path through `RuntimeMetricsService` and the dashboard through `render_runtime()` end-to-end, asserting the `dispatch_spans` shape and the runtime panel's "not observed in recent window" empty state. Stale "in-place on a deep-copied payload" wording was removed from `src/eggpool/transcoder/compression/apply.py`; the corrected contract is the same path-level copy-on-write behavior already documented above. Verified locally: `uv run pytest tests/unit/test_proxy_request_hotpath_modes.py tests/unit/test_hotpath_corrective_polish.py tests/unit/test_runtime_dispatch_spans_dashboard.py -v`, `uv run pytest -m request_path -v`, `uv run pytest -m dashboard -v`, full `uv run pytest`, `uv run ruff check src tests scripts`, `uv run ruff format --check src tests scripts`, and `uv run pyright src scripts`.
+
+## Gotchas
+
+- Configuration changes require a service restart; live reload is intentionally not supported
+- No pre-commit hooks are configured in this repo; CI runs ruff, pyright, and pytest via GitHub Actions
+- `static_models` is the source of truth for provider-specific protocol — `FAMILY_PROTOCOLS` is a global fallback. Providers that serve models on a non-default protocol **must** ship `[[providers.<id>.static_models]]` rows with the correct `protocol`, otherwise live `/v1/models` fetch resolves via family prefix and the protocol check clears it to `None`, producing `ModelUnavailableError` instead of `ProtocolMismatchError`.
+- Upstream-authoritative suppression: local quota estimates are advisory by default (`local_quota_mode = "score_only"`). Only upstream-observed failures (429/402/5xx/auth) and explicit operator disablement suppress routing.
+- **Routing is load-based, not cost-based**: the `QuotaFairScorer` (`src/eggpool/quota/scorer.py`) computes utilization from request count and token count, never from `cost_microdollars`. Cost is unreliable across upstreams (zero reported, unit confusion, heuristics drift) and the metrics we actually balance on are requests served and tokens processed. `cost_*` fields remain on `PersistedWindowSnapshot` and the `requests` table for audit / dashboard display only.
+- **Pricing safeguard invariants**: ambiguous bare upstream pricing metadata defaults to dollars-per-million unless explicit token evidence or unambiguous field names prove otherwise; nested `pricing.cache_*` fields inherit the surrounding pricing-cluster unit regime; implausible snapshot rates are rejected before persistence; and `RequestFinalizer` never persists a positive local `estimated` cost as canonical spend when `choose_bounded_estimated_cost()` selects a lower plausible local value. Historical cleanup goes through `eggpool stats repair-costs` (dry-run first), not ad hoc SQL updates.
+- **Reservation-fallback canonicalization** (plans/2026-07-03-...): `selected.estimated_microdollars` is a routing budget, not a bill. The finalizer routes positive local `estimated` cost through `choose_bounded_estimated_cost()` (`src/eggpool/catalog/pricing.py`); when both values are plausible, the lower one wins and nothing later in finalization floors that choice back to the reservation. The reservation ceiling is bounded by `_QUOTA_RESERVATION_COST_CEILING_MICRODOLLARS` ($2.50), well below `MAX_REQUEST_COST_MICRODOLLARS` ($250), so a regression cannot use the reservation as canonical billing. `CostCalculator` validates the **raw, pre-clamp** cost-per-token against `_MAX_TRUSTED_COST_PER_TOKEN_MICRODOLLARS` in both partial and derived paths so an inflated snapshot can no longer hide behind the per-request clamp. `QuotaEstimator.record_usage()` refuses to seed the EWMA on a first observation whose per-token rate exceeds the estimated ceiling, so a unit-misclassification sample cannot permanently poison future reservations. The dashboard's `_render_reservation_fallback_warning` and `reservation_fallback_rows` / `reservation_fallback_excess_microdollars` summary fields surface the failure class so it remains visible after the bug is fixed.
+- **Reservation estimates do NOT floor canonical cost**: reservation estimates are routing budgets and audit fields — they do NOT floor canonical request cost. Precedence: (1) provider-reported cost wins; (2) trusted local `exact`/`derived`/`partial` costs win; (3) local `estimated` and reservation-only estimates both go through `choose_bounded_estimated_cost()` (`src/eggpool/catalog/pricing.py`), which picks the lower plausible value with the reservation as fallback only when the local estimate is implausible. Nothing after `choose_bounded_estimated_cost()` in the finalizer may unconditionally raise canonical cost back to the reservation. Regression fixture: MiniMax provider with `model_id="MiniMax-M3"`, local estimated `21_848` μ$ vs reservation `5_411_079` μ$ — canonical must be `21_848`, not the reservation. See `tests/unit/test_request_finalizer.py::test_estimated_local_cost_beats_higher_reservation_floor_regression`.
+- **Model-info dashboard visibility is never silent**: dashboard failure paths in `_get_model_info_summary_state` / `handle_model_detail` (`src/eggpool/dashboard/routes.py`) always log the traceback and surface a degraded-state notice in the rendered HTML. The renderer never hides missing model-info; if the subsystem is broken operators see it on the `/models` page and in `eggpool.dashboard.routes` logs. The same contract holds for the detail page.
+- **Model-info canonical lookup is case-insensitive at every layer**: `ModelInfoRepository.get_canonical` (`COLLATE NOCASE`) and `get_canonical_many` (`lower(model_id) IN (...)` with `casefold` normalization) agree, and `get_canonical_many` keys the returned dict by the requested id so dashboard callers can use either casing.
+- **Model-info alias and observation lookup is case-insensitive**: `get_aliases_for_model`, `list_alias_rows_for_model`, and the new `list_compact_observations_for_model` (Phase 4 of the OpenRouter enrichment plan) all use `WHERE lower(model_id) = lower(?)` so configured aliases and persisted observations remain reachable across provider casing drift (`MiniMax-M3` vs `minimax-m3`). Stored `model_id` casing is preserved in returned rows.
+- **Alias candidate selection is deterministic**: `resolve_openrouter_record()` (in `src/eggpool/model_info/identity.py`) uses `choose_alias_candidates()` to prefer exact-case rows over case-folded rows, then `dedupe_alias_strings()` to collapse identical alias strings before declaring ambiguity. Multiple distinct aliases that resolve into the OpenRouter index are kept; multiple that don't resolve fall through to direct/pricing rules. Conflicting folded aliases with no exact-case row produce a clean no-match so the caller can surface `ambiguous_aliases`. Each surviving row is annotated with `match_kind = "exact_case" | "case_folded"` and surfaced under `source_diagnostics.openrouter.alias_rows` so operators can audit the choice.
+- **API detail observation fallback is non-misleading**: `_detail_response()` (`src/eggpool/api/model_info.py`) accepts `observations_error`. When the repository read fails, the response returns `observations: []` plus an `observations_error: <ExcClass>` key instead of synthesizing external-source rows. The legacy `_synthetic: true` projection is retained only for direct test-double callers of `_detail_response()`. The dashboard detail page mirrors the contract via `_render_model_observations_section(observations_error=...)`, which renders an "Observation read failed" panel with the error class name when set.
+- **OpenRouter source health reflects catalog availability, not match success**: `ModelInfoService.refresh_model_info` / `refresh_due_models` call `record_source_success("openrouter", payload_count=N)` immediately after a successful OpenRouter fetch — regardless of whether any local model matched. `model_info_source_health.last_success_at` and `last_payload_count` therefore describe the external source, not local model coverage.
+- **OpenRouter cache bypass on forced refresh**: when configured aliases exist but none match the cached catalog, `OpenRouterModelInfoSource.invalidate_cache()` runs and the forced fetch retries once. The retry is recorded as `cache_retry: true` under `source_diagnostics.openrouter` so operators can see the cache invalidation.
+- **API detail observations reflect persisted DB rows**: `handle_model_info_detail()` reads per-source observation rows via `ModelInfoRepository.list_compact_observations_for_model()`. Rows carry real `source_model_id`, `provider_id`, `observed_at`, and `confidence`. Raw payloads are never returned. The dashboard detail page renders the same rows in an Observations panel.
+- **Canonical detail display-name promotion**: `build_canonical_detail()` promotes an external `display_name_<source>` (e.g. `display_name_openrouter = "MiniMax: MiniMax M3"`) into `detail.display_name` only when the provider did not seed one. `detail.display_name_source` records the chosen source so operators know where the name came from.
+- **Source-scoped advisory pricing**: OpenRouter $/Mtok pricing lives under `detail.pricing.openrouter`, separate from authoritative local cost accounting. The legacy `pricing_observation` block is preserved for back-compat.
+- **Manual refresh reseeds configured aliases**: `refresh_model_info()` calls `seed_configured_aliases()` before external-source matching so newly added `[model_info.aliases]` rows (admin tooling, config reload) take effect without a process restart. Seeding is idempotent.
+- **Catalog-visible models must have a canonical row path**: `reconcile_catalog_snapshot`, `ensure_canonical`, `get_summary_map`, and `_build_detail` (`src/eggpool/model_info/service.py`) all treat both `catalog._models` and `catalog._provider_models` keys as in-catalog. Provider-scoped rows that never appear in the global model index still receive canonical rows and dashboard pills.
+- **Do not add transitive imports to `runtime_paths` or `fastcli`** — they are stdlib-only and must stay lightweight for the Raspberry Pi watchdog contract
+- `eggpool accounts explain` hydrates the catalog from SQLite, not an empty cache. Output uses `click.echo` (no `rich` dependency).
+- Startup crash recovery (`_crash_recovery`) runs at every startup and recovers ALL pending requests and active reservations with no time threshold.
+- `CapabilityError` (HTTP 400) is distinct from `ModelNotFoundError` (404) and `ModelUnavailableError` (503). `BudgetResolutionError` is a subclass of `CapabilityError`.
+- When constructing a `RequestCoordinator` in tests, pass an explicit `transcoder_policy` or assert the desired default; never rely on implicit `None`.
+- DB migrations are numbered SQL files in `src/eggpool/db/schema/`. The `model_info_*` sidecar tables carry FKs to `models.model_id`; catalog entries may reach model-info paths before `_persist_catalog` writes them to `models`, so repository writes seed a placeholder `models` row in the same transaction.
+
+## Error Handling
+
+Use the hierarchy in `errors.py`. Chain exceptions with `raise ... from err` or `raise ... from None`.
+
+- `AggregatorError` → `ConfigError`, `DatabaseError`, `ProxyError`
+- `UpstreamError` (has `status_code`) → `TemporaryUpstreamError`, `TransientUpstreamError`, `AuthenticationError`, `QuotaExhaustedError`, `RateLimitError` (has `retry_after`), `ModelUnavailableError`
+- `ModelNotFoundError` (has `model_id`), `NoEligibleAccountError`, `CatalogUnavailableError`, `AuthenticationUnavailableError`, `UpstreamExhaustedError`, `AccountSuspendedError`, `RequestTooLargeError`, `ModelInfoSourceFetchError`, `ContextLimitExceededError`, `CapabilityError`
+
+## Fast-Path CLI
+
+- `src/eggpool/cli.py` is a tiny bootstrap (~74 lines)
+- `main()` calls `eggpool.fastcli.maybe_run_fast_command()` first; recognized fast commands (`croncheck`, `ensure-running`) are dispatched without importing Click
+- **Do not add transitive imports to `runtime_paths` or `fastcli`** — they are stdlib-only and must stay lightweight for the Raspberry Pi watchdog contract
+- Unrecognized commands fall through to `eggpool.cli_full`, which holds the heavy Click CLI
+- Public symbols (`cli`, helpers used by tests) are lazily forwarded from `cli_full` via PEP 562 `__getattr__`
+
+## Git Workflow
+
+- Branch: `main`
+- Commit messages: concise, imperative mood
+- Never commit secrets, API keys, or `.env` files

{eggpool-0.5.2 → eggpool-0.5.4}/CHANGELOG.md

@@ -7,7 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-Nothing yet.
+### Fixed
+
+- **Python hot-path corrective polish.** Closure pass over the Phase 1-5 landing: selection lock wait/held spans (`selection_lock_wait`, `selection_locked`) now record exactly one sample per attempt via explicit `record_ns()` calls after the lock exits — the placeholder `_maybe_span` blocks inside `_select_and_persist_attempt()` were double-sampling these metrics, depressing p50/p95 and masking real concurrency contention. `CompressionResult` now carries applier-derived `candidate_count`, `eligible_candidate_count`, `suppressed_candidate_count`, and `applied_transform_count` so safe-mode observation counts meaningful candidates without a second observe pass. Safe-mode `apply_safe_compression()` remains a single pass: no-op returns the original payload by identity, applied runs return a path-level copy-on-write payload. `_copy_with_replacements()` receives direct unit coverage for no-op identity, single dict/list paths, multiple shared-prefix and disjoint-branch replacements, duplicate-path last-wins, invalid-path fail-closed, chained transforms, and strict structural-sharing identity of untouched branches. `/api/stats/runtime` `dispatch_spans` is rendered on the runtime dashboard as a `Dispatch spans` panel showing actionable spans (`coordinator_pre_upstream`, `segmentation`, `compression_analyze`, `compression_apply`, `selection_lock_wait`, `selection_locked`, `routing_trace_write`) with p50/p95/max plus `sample_count`; absent spans render as "not observed in recent window" instead of `0 ms`. Behavioral regression guards land in `tests/unit/test_hotpath_corrective_polish.py` and `tests/unit/test_runtime_dispatch_spans_dashboard.py` so an accidental reintroduction of duplicate safe-mode analyze, unconditional deep-copy, double lock-span sampling, or zero-filled dashboard spans is caught at unit-test time. Documentation in `architecture/README.md`, `AGENTS.md`, `.opencode/skills/architecture/SKILL.md`, and `README.md` updated to reflect the corrected copy-on-write semantics. Migration 0043 checksum refreshed for the stale-comment edit.
+
+### Changed
+
+- **Low-power dashboard performance optimization (Raspberry Pi / SBC).** Default install now targets dashboard responsiveness on Raspberry Pi 4/5 and similar SBC hardware while keeping the single Granian worker process model. `DatabaseConfig.worker_threads` defaults to `2` so `app.py:_lifespan_runtime` opens a separate read-only `stats_db` connection on file-backed SQLite — dashboard analytics no longer queue behind request-path writes on the shared connection lock. `ServerConfig.threads` defaults to `2` so the single worker can multiplex streaming proxy traffic + dashboard requests without single-event-loop starvation. Granian `workers=1` is unchanged. `RoutingTraceConfig.mode` defaults to `"sampled"` with `sample_rate = 0.05` and `include_score_components = False`, reducing routing-decision insert volume by ~20x on default installs. The CLI startup log line `Granian profile: workers=1 runtime_threads=N database_worker_threads=M access_log=...` makes the effective profile visible at every `eggpool serve` start.
+- Dashboard HTML and JSON handlers (`handle_runtime`, `handle_cache`, request-shaping/compression/transcoding JSON routes) now use the lifespan-wired `app.state.stats` and pass `use_cache=True` for the heavy aggregate methods (`get_transcoding_stats`, `get_cache_observability`, `get_canonical_request_segmentation`, `get_compression_observability`, `get_compression_runtime`, `get_compression_policy_stats`, `get_cache_stability`, `get_synthetic_cache_summary`, `get_compression_tuning_window_metrics`). The 30s in-memory dashboard cache keeps repeated renders off the database; API endpoints that are documented as exact remain exact. `DashboardTelemetry` (`src/eggpool/dashboard/telemetry.py`) records per-route render durations in a 100-sample rolling buffer; `RuntimeMetricsService._snapshot_dashboard_telemetry` exposes `{recent_render_ms_p50, recent_render_ms_p95, slowest_recent_route, separate_stats_db, runtime_threads, database_worker_threads, routing_trace_mode}` under `/api/stats/runtime`.
+- Background tasks register with explicit `initial_delay_s` offsets (`metrics_flush=5s`, `usage_window_refresh=15s`, `stale_request_finalizer=25s`, `health_disabled_models_prune=40s`, `model_info_canonical_backfill=10s`) so 30s/60s-cadence ticks do not cluster on the same wall-clock second. `background/periodic_initial_offset(name, interval_s, *, max_fraction=0.5)` is the deterministic-from-name helper for future additions. Startup crash recovery is unchanged.
+- `docs/deployment.md` adds a Performance Profiles section (balanced / minimum-footprint / full-diagnostics) with a symptom-to-knob troubleshooting table. `docs/raspberry-pi.md` documents the recommended profile for Pi-class installs.
+
+## [0.5.3] - 2026-07-05
+
+### Fixed
+
+- Installer Python selection now applies the documented 3.11-3.14 support
+  window to both version-suffixed probes and the bare `python3` fallback, so
+  Python 3.15+ is rejected until the Granian/PyO3 dependency stack supports it.
 
 ## [0.5.0] - 2026-07-01
 

{eggpool-0.5.2 → eggpool-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eggpool
-Version: 0.5.2
+Version: 0.5.4
 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
@@ -83,7 +83,7 @@ See [Deployment](docs/deployment.md) for alternative install methods (pipx, manu
 
 | Command | Description |
 |---------|-------------|
-| `eggpool serve` | Start the proxy server (`--daemon` to detach) |
+| `eggpool serve` | Start the proxy server (daemon mode; `--verbose` for foreground) |
 | `eggpool stop` | Stop the running server |
 | `eggpool restart` | Fully restart the server (stop then start) |
 | `eggpool rehash` | Restart to apply config changes |
@@ -184,20 +184,42 @@ See [docs/transcoding.md](docs/transcoding.md) for the full translation table an
 
 EggPool’s request-shaping stack is opt-in and cache-preserving by default. With the shipped config, the public surface stays in reporting mode: no route changes, no stable-prefix mutation, and no synthetic cache annotations on the wire. Routing remains load-based; cache, compression, synthetic-cache, and tuning fields never enter `QuotaFairScorer`.
 
+The detailed request-shaping summary and drill-down cards live on
+`/cache`; `/runtime` keeps a compact relocation panel that points back
+to that page.
+
+The `/cache` page opens with six top-level operator summary cards:
+
+| Summary card | Quiet default | Lights up when |
+|--------------|---------------|----------------|
+| Request changes | no changes | compression failed fallback > 0 |
+| Provider cache counters | `—` | rows reported / classified ratio |
+| EggPool cache annotations | `Off` | dry-run or applied counts or warning code count |
+| Safety guardrail | `Clean` | compression/policy/annotation warnings or fallbacks |
+| Tuning suggestions | `Off` | recommendation or override count > 0 |
+| Routing isolation | `Isolated` | routing guardrail violation |
+
+Raw `reporting_only` and other internal modes survive in the subtext,
+not the primary metric. Advanced diagnostics stay collapsed unless a
+warning or non-default state is present (segmentation parse failures,
+synthetic-cache warnings or applied count, tuning recommendations,
+routing guardrail violation, transcoding loss warnings, compression
+warnings or policy warnings).
+
 ### Operator surfaces
 
 | Surface | Default | Mutates requests? | Primary stats/API |
 |---------|---------|-------------------|-------------------|
-| Cache reporting | on | no | `/api/stats/cache-observability` |
+| Provider cache counters | on | no | `/api/stats/cache-observability` |
 | Request segmentation | on | no | `/api/stats/canonical-request-segmentation` |
 | Native cache preservation | on when transcoding | no | `/api/stats/cache-stability` |
-| Compression opportunities | off unless `[compression].enabled = true` | no | `/api/stats/compression-observability` |
-| Safe compression | off (`mode = "observe"`) | volatile suffix only, fail-closed | `/api/stats/compression-runtime` |
+| Compression | off unless `[compression].enabled = true` | no | `/api/stats/compression-observability` |
+| Compression — safe-mode details | off (`mode = "observe"`) | volatile suffix only, fail-closed | `/api/stats/compression-runtime` |
 | Policy overrides | off (`[[compression.policies]] = []`) | scoped overlay only | `/api/stats/compression-policies` |
-| Synthetic cache controls | off (`enabled = false`, `dry_run = true`) | provider-bound stable prefix only | `/api/stats/synthetic-cache-observability` |
-| Advisory tuning | off (`enabled = false`) | no | `/api/stats/compression-tuning` |
-| Request-shaping summary | on with dashboard/runtime | no | `/api/stats/request-shaping` |
-| Routing guardrails | always on | no | `/api/stats/runtime` |
+| EggPool cache annotations | off (`enabled = false`, `dry_run = true`) | provider-bound stable prefix only | `/api/stats/synthetic-cache-observability` |
+| Tuning suggestions | off (`enabled = false`) | no | `/api/stats/compression-tuning` |
+| Request-shaping summary | on with dashboard | no | `/api/stats/request-shaping` |
+| Routing isolation | always on | no | `/api/stats/runtime` |
 
 ### Stable config knobs
 
@@ -234,7 +256,7 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 
 ### Safety rules
 
-- Safe compression mutates only eligible `volatile_suffix` string leaves.
+- Safe compression mutates only eligible `volatile_suffix` string leaves; no-op runs return the original payload by identity and applied runs use path-level copy-on-write (not a deep copy).
 - Stable-prefix preservation is verified with `stable_prefix_content_hash`; any mismatch falls back to the original payload.
 - Native provider cache annotations are preserved byte-for-byte.
 - Synthetic cache controls are disabled by default and dry-run first when enabled.
@@ -253,6 +275,8 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 
 ### Further reading
 
+See `/cache` for the operator workflow: requests being changed, provider cache counters, compression outcomes, safety guardrails, routing isolation. Advanced diagnostics stay collapsed unless warnings are present.
+
 - Operator guide: [docs/cache-compression.md](docs/cache-compression.md)
 - Copy-pasteable profiles: [docs/cache-compression-profiles.md](docs/cache-compression-profiles.md)
 - Troubleshooting: [docs/cache-compression-troubleshooting.md](docs/cache-compression-troubleshooting.md)
@@ -272,9 +296,9 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 | `GET` | `/api/model-info/{model_id}` | Enriched metadata detail for one model |
 | `GET` | `/api/model-info/{model_id}/aliases` | Source-keyed alias rows for one model |
 | `GET` | `/api/model-info/sources` | Model-info source health |
-| `POST` | `/api/model-info/refresh` | Trigger model-info refresh — `?model_id=<id>&source=<provider_catalog\|openrouter\|artificial_analysis\|huggingface>&force=1` for a single-model force refresh (auth-gated). `model_id` accepts provider-suffixed IDs (`gpt-4o/openai`); unknown source values return HTTP 400 |
+| `POST` | `/api/model-info/refresh` | Trigger model-info refresh — `?model_id=<id>&source=<provider_catalog\|openrouter\|artificial_analysis\|huggingface>&force=1` for a single-model force refresh (auth-gated). `model_id` accepts provider-suffixed IDs (`gpt-4o/openai`); unknown source values return HTTP 400. The response carries `source_diagnostics` (`initialized`, `fetched`, `catalog_count`, `alias_candidates`, `matched_source_model_id`, `miss_reason`, `cache_retry`) so operators can see why a refresh matched or missed |
 | `GET` | `/api/stats/cache-observability` | Cache counter status coverage |
-| `GET` | `/api/stats/canonical-request-segmentation` | Segmentation status and per-region token estimates |
+| `GET` | `/api/stats/canonical-request-segmentation` | Segmentation status, not_collected / empty_request / parse_failure counts, and token estimates |
 | `GET` | `/api/stats/cache-stability` | Transcoder cache boundary tracker counters |
 | `GET` | `/api/stats/compression-observability` | Observe-mode opportunity, per-policy roll-ups |
 | `GET` | `/api/stats/compression-runtime` | Safe-mode applied/fallback counts and latency |
@@ -282,7 +306,7 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 | `GET` | `/api/stats/synthetic-cache-observability` | Synthetic cache candidate / applied / native-preserved counts |
 | `GET` | `/api/stats/compression-tuning` | Threshold tuning recommendations |
 | `GET` | `/api/stats/request-shaping` | Operator-facing request-shaping summary |
-| `GET` | `/api/stats/runtime` | Runtime metrics + hardcoded routing guardrails |
+| `GET` | `/api/stats/runtime` | Runtime metrics + hardcoded routing guardrails; background task summaries now expose supervisor-owned `mode`, `next_run_at`, `overdue_seconds`, plus `background_task_summary` (`registered` / `running` / `failed` / `overdue` / `last_error_count`) so healthy periodic loops no longer render as overdue |
 
 When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with request stats, latency metrics, provider health, model-info detail pages, and more. Stats API available under `/api/stats/*`.
 
@@ -291,6 +315,11 @@ When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with
 - The dashboard `/models` page renders a degraded-state notice above the table if the model-info service is unattached (no `app.state.model_info`) or if `get_summary_map()` raises an exception. The exception's full traceback is logged under `eggpool.dashboard.routes` — the page never embeds the traceback text in HTML.
 - The dashboard `/models/{model_id:path}` detail page distinguishes "no canonical row exists" (empty-state copy) from "lookup failed" (degraded-state notice) when the service throws.
 - `/api/stats/runtime` includes a `model_info` section with `enabled`, `canonical_count`, `catalog_model_count`, `provider_model_count`, `due_count`, and a `source_health` dict (no raw source payloads). Failures surface as `*_error` keys and `probe_errors`, never as raised exceptions.
+- OpenRouter source health reflects catalog availability, not local match success — a successful fetch with zero matches still updates `last_success_at` / `last_payload_count`. When a forced refresh finds configured aliases but no catalog match, the OpenRouter cache is invalidated and the fetch retried once (recorded as `cache_retry: true` under `source_diagnostics.openrouter`).
+- `GET /api/model-info/{model_id}` returns `observations` rows read from `model_info_observations` (per source: `source_model_id`, `provider_id`, `observed_at`, `confidence`, display name, context window, modalities). Raw payloads are never returned. When no rows exist for a canonical model, the field is a synthetic placeholder flagged `_synthetic: true` so callers can distinguish real observation data from fallback synthesis. When the repository read fails the response returns `observations: []` plus an `observations_error: <ExcClass>` key instead of synthesising rows — operators see "no data" rather than fabricated external source ids.
+- The dashboard model detail page mirrors those observation rows in an Observations panel. External `display_name_<source>` values (e.g. `MiniMax: MiniMax M3`) are promoted into `detail.display_name` only when the provider did not seed one; `detail.display_name_source` records the chosen source. Source-scoped advisory pricing (e.g. OpenRouter's `$/Mtok`) lives under `detail.pricing.<source>`, separate from authoritative local cost accounting. When the observation read fails the dashboard renders an "Observation read failed" panel with the error class name.
+- Alias and observation lookups are case-insensitive at the repository layer (`lower(model_id) = lower(?)`), so provider casing drift (`MiniMax-M3` vs `minimax-m3`) does not break refresh or detail lookup. Manual refreshes reseed configured `[model_info.aliases]` before external matching, so newly added aliases apply without a process restart. Alias candidate selection is deterministic: exact-case rows win over case-folded rows; identical alias strings are deduplicated; conflicting folded aliases with no exact-case match produce an unambiguous no-match. The resolver exposes `source_diagnostics.openrouter.alias_rows` (one entry per candidate with `match_kind = "exact_case" | "case_folded"`) and `alias_selection` so operators can audit the choice.
+- `scripts/debug_model_info_openrouter.sh` runs the live verification flow (force refresh → detail GET → source-health query) for any model id; the expected outcomes are documented in [docs/model-info-openrouter-debug.md](docs/model-info-openrouter-debug.md).
 
 ## Documentation
 
@@ -315,13 +344,15 @@ When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with
 ## Development
 
 ```bash
-uv sync --extra dev
+uv sync --extra dev      # install dependencies
+uv run pytest            # run all tests
+uv run ruff format --check src/ tests/ scripts/
 uv run ruff check src/ tests/ scripts/
-uv run ruff format src/ tests/ scripts/
 uv run pyright src/ scripts/
-uv run pytest
 ```
 
+See `AGENTS.md` for focused test subset commands.
+
 ## Agent Configuration
 
 `eggpool configsetup` generates configuration snippets for popular coding agents:

{eggpool-0.5.2 → eggpool-0.5.4}/README.md

@@ -39,7 +39,7 @@ See [Deployment](docs/deployment.md) for alternative install methods (pipx, manu
 
 | Command | Description |
 |---------|-------------|
-| `eggpool serve` | Start the proxy server (`--daemon` to detach) |
+| `eggpool serve` | Start the proxy server (daemon mode; `--verbose` for foreground) |
 | `eggpool stop` | Stop the running server |
 | `eggpool restart` | Fully restart the server (stop then start) |
 | `eggpool rehash` | Restart to apply config changes |
@@ -140,20 +140,42 @@ See [docs/transcoding.md](docs/transcoding.md) for the full translation table an
 
 EggPool’s request-shaping stack is opt-in and cache-preserving by default. With the shipped config, the public surface stays in reporting mode: no route changes, no stable-prefix mutation, and no synthetic cache annotations on the wire. Routing remains load-based; cache, compression, synthetic-cache, and tuning fields never enter `QuotaFairScorer`.
 
+The detailed request-shaping summary and drill-down cards live on
+`/cache`; `/runtime` keeps a compact relocation panel that points back
+to that page.
+
+The `/cache` page opens with six top-level operator summary cards:
+
+| Summary card | Quiet default | Lights up when |
+|--------------|---------------|----------------|
+| Request changes | no changes | compression failed fallback > 0 |
+| Provider cache counters | `—` | rows reported / classified ratio |
+| EggPool cache annotations | `Off` | dry-run or applied counts or warning code count |
+| Safety guardrail | `Clean` | compression/policy/annotation warnings or fallbacks |
+| Tuning suggestions | `Off` | recommendation or override count > 0 |
+| Routing isolation | `Isolated` | routing guardrail violation |
+
+Raw `reporting_only` and other internal modes survive in the subtext,
+not the primary metric. Advanced diagnostics stay collapsed unless a
+warning or non-default state is present (segmentation parse failures,
+synthetic-cache warnings or applied count, tuning recommendations,
+routing guardrail violation, transcoding loss warnings, compression
+warnings or policy warnings).
+
 ### Operator surfaces
 
 | Surface | Default | Mutates requests? | Primary stats/API |
 |---------|---------|-------------------|-------------------|
-| Cache reporting | on | no | `/api/stats/cache-observability` |
+| Provider cache counters | on | no | `/api/stats/cache-observability` |
 | Request segmentation | on | no | `/api/stats/canonical-request-segmentation` |
 | Native cache preservation | on when transcoding | no | `/api/stats/cache-stability` |
-| Compression opportunities | off unless `[compression].enabled = true` | no | `/api/stats/compression-observability` |
-| Safe compression | off (`mode = "observe"`) | volatile suffix only, fail-closed | `/api/stats/compression-runtime` |
+| Compression | off unless `[compression].enabled = true` | no | `/api/stats/compression-observability` |
+| Compression — safe-mode details | off (`mode = "observe"`) | volatile suffix only, fail-closed | `/api/stats/compression-runtime` |
 | Policy overrides | off (`[[compression.policies]] = []`) | scoped overlay only | `/api/stats/compression-policies` |
-| Synthetic cache controls | off (`enabled = false`, `dry_run = true`) | provider-bound stable prefix only | `/api/stats/synthetic-cache-observability` |
-| Advisory tuning | off (`enabled = false`) | no | `/api/stats/compression-tuning` |
-| Request-shaping summary | on with dashboard/runtime | no | `/api/stats/request-shaping` |
-| Routing guardrails | always on | no | `/api/stats/runtime` |
+| EggPool cache annotations | off (`enabled = false`, `dry_run = true`) | provider-bound stable prefix only | `/api/stats/synthetic-cache-observability` |
+| Tuning suggestions | off (`enabled = false`) | no | `/api/stats/compression-tuning` |
+| Request-shaping summary | on with dashboard | no | `/api/stats/request-shaping` |
+| Routing isolation | always on | no | `/api/stats/runtime` |
 
 ### Stable config knobs
 
@@ -190,7 +212,7 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 
 ### Safety rules
 
-- Safe compression mutates only eligible `volatile_suffix` string leaves.
+- Safe compression mutates only eligible `volatile_suffix` string leaves; no-op runs return the original payload by identity and applied runs use path-level copy-on-write (not a deep copy).
 - Stable-prefix preservation is verified with `stable_prefix_content_hash`; any mismatch falls back to the original payload.
 - Native provider cache annotations are preserved byte-for-byte.
 - Synthetic cache controls are disabled by default and dry-run first when enabled.
@@ -209,6 +231,8 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 
 ### Further reading
 
+See `/cache` for the operator workflow: requests being changed, provider cache counters, compression outcomes, safety guardrails, routing isolation. Advanced diagnostics stay collapsed unless warnings are present.
+
 - Operator guide: [docs/cache-compression.md](docs/cache-compression.md)
 - Copy-pasteable profiles: [docs/cache-compression-profiles.md](docs/cache-compression-profiles.md)
 - Troubleshooting: [docs/cache-compression-troubleshooting.md](docs/cache-compression-troubleshooting.md)
@@ -228,9 +252,9 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 | `GET` | `/api/model-info/{model_id}` | Enriched metadata detail for one model |
 | `GET` | `/api/model-info/{model_id}/aliases` | Source-keyed alias rows for one model |
 | `GET` | `/api/model-info/sources` | Model-info source health |
-| `POST` | `/api/model-info/refresh` | Trigger model-info refresh — `?model_id=<id>&source=<provider_catalog\|openrouter\|artificial_analysis\|huggingface>&force=1` for a single-model force refresh (auth-gated). `model_id` accepts provider-suffixed IDs (`gpt-4o/openai`); unknown source values return HTTP 400 |
+| `POST` | `/api/model-info/refresh` | Trigger model-info refresh — `?model_id=<id>&source=<provider_catalog\|openrouter\|artificial_analysis\|huggingface>&force=1` for a single-model force refresh (auth-gated). `model_id` accepts provider-suffixed IDs (`gpt-4o/openai`); unknown source values return HTTP 400. The response carries `source_diagnostics` (`initialized`, `fetched`, `catalog_count`, `alias_candidates`, `matched_source_model_id`, `miss_reason`, `cache_retry`) so operators can see why a refresh matched or missed |
 | `GET` | `/api/stats/cache-observability` | Cache counter status coverage |
-| `GET` | `/api/stats/canonical-request-segmentation` | Segmentation status and per-region token estimates |
+| `GET` | `/api/stats/canonical-request-segmentation` | Segmentation status, not_collected / empty_request / parse_failure counts, and token estimates |
 | `GET` | `/api/stats/cache-stability` | Transcoder cache boundary tracker counters |
 | `GET` | `/api/stats/compression-observability` | Observe-mode opportunity, per-policy roll-ups |
 | `GET` | `/api/stats/compression-runtime` | Safe-mode applied/fallback counts and latency |
@@ -238,7 +262,7 @@ Advanced knobs still exist for policy-scoped rollouts and advisory tuning, but t
 | `GET` | `/api/stats/synthetic-cache-observability` | Synthetic cache candidate / applied / native-preserved counts |
 | `GET` | `/api/stats/compression-tuning` | Threshold tuning recommendations |
 | `GET` | `/api/stats/request-shaping` | Operator-facing request-shaping summary |
-| `GET` | `/api/stats/runtime` | Runtime metrics + hardcoded routing guardrails |
+| `GET` | `/api/stats/runtime` | Runtime metrics + hardcoded routing guardrails; background task summaries now expose supervisor-owned `mode`, `next_run_at`, `overdue_seconds`, plus `background_task_summary` (`registered` / `running` / `failed` / `overdue` / `last_error_count`) so healthy periodic loops no longer render as overdue |
 
 When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with request stats, latency metrics, provider health, model-info detail pages, and more. Stats API available under `/api/stats/*`.
 
@@ -247,6 +271,11 @@ When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with
 - The dashboard `/models` page renders a degraded-state notice above the table if the model-info service is unattached (no `app.state.model_info`) or if `get_summary_map()` raises an exception. The exception's full traceback is logged under `eggpool.dashboard.routes` — the page never embeds the traceback text in HTML.
 - The dashboard `/models/{model_id:path}` detail page distinguishes "no canonical row exists" (empty-state copy) from "lookup failed" (degraded-state notice) when the service throws.
 - `/api/stats/runtime` includes a `model_info` section with `enabled`, `canonical_count`, `catalog_model_count`, `provider_model_count`, `due_count`, and a `source_health` dict (no raw source payloads). Failures surface as `*_error` keys and `probe_errors`, never as raised exceptions.
+- OpenRouter source health reflects catalog availability, not local match success — a successful fetch with zero matches still updates `last_success_at` / `last_payload_count`. When a forced refresh finds configured aliases but no catalog match, the OpenRouter cache is invalidated and the fetch retried once (recorded as `cache_retry: true` under `source_diagnostics.openrouter`).
+- `GET /api/model-info/{model_id}` returns `observations` rows read from `model_info_observations` (per source: `source_model_id`, `provider_id`, `observed_at`, `confidence`, display name, context window, modalities). Raw payloads are never returned. When no rows exist for a canonical model, the field is a synthetic placeholder flagged `_synthetic: true` so callers can distinguish real observation data from fallback synthesis. When the repository read fails the response returns `observations: []` plus an `observations_error: <ExcClass>` key instead of synthesising rows — operators see "no data" rather than fabricated external source ids.
+- The dashboard model detail page mirrors those observation rows in an Observations panel. External `display_name_<source>` values (e.g. `MiniMax: MiniMax M3`) are promoted into `detail.display_name` only when the provider did not seed one; `detail.display_name_source` records the chosen source. Source-scoped advisory pricing (e.g. OpenRouter's `$/Mtok`) lives under `detail.pricing.<source>`, separate from authoritative local cost accounting. When the observation read fails the dashboard renders an "Observation read failed" panel with the error class name.
+- Alias and observation lookups are case-insensitive at the repository layer (`lower(model_id) = lower(?)`), so provider casing drift (`MiniMax-M3` vs `minimax-m3`) does not break refresh or detail lookup. Manual refreshes reseed configured `[model_info.aliases]` before external matching, so newly added aliases apply without a process restart. Alias candidate selection is deterministic: exact-case rows win over case-folded rows; identical alias strings are deduplicated; conflicting folded aliases with no exact-case match produce an unambiguous no-match. The resolver exposes `source_diagnostics.openrouter.alias_rows` (one entry per candidate with `match_kind = "exact_case" | "case_folded"`) and `alias_selection` so operators can audit the choice.
+- `scripts/debug_model_info_openrouter.sh` runs the live verification flow (force refresh → detail GET → source-health query) for any model id; the expected outcomes are documented in [docs/model-info-openrouter-debug.md](docs/model-info-openrouter-debug.md).
 
 ## Documentation
 
@@ -271,13 +300,15 @@ When `[dashboard].enabled = true`, a multi-page dashboard is served at `/` with
 ## Development
 
 ```bash
-uv sync --extra dev
+uv sync --extra dev      # install dependencies
+uv run pytest            # run all tests
+uv run ruff format --check src/ tests/ scripts/
 uv run ruff check src/ tests/ scripts/
-uv run ruff format src/ tests/ scripts/
 uv run pyright src/ scripts/
-uv run pytest
 ```
 
+See `AGENTS.md` for focused test subset commands.
+
 ## Agent Configuration
 
 `eggpool configsetup` generates configuration snippets for popular coding agents: