tool-compass 2.4.0__tar.gz → 2.5.0__tar.gz

{tool_compass-2.4.0 → tool_compass-2.5.0}/.env.example

@@ -35,14 +35,15 @@ LOG_LEVEL=INFO
 # Gradio UI Settings
 # =============================================================================
 
-# Server bind address (0.0.0.0 for Docker, 127.0.0.1 for local)
-GRADIO_SERVER_NAME=127.0.0.1
-
-# Server port
-GRADIO_SERVER_PORT=7860
-
-# Enable public sharing link (set to "true" for Gradio share URL)
-# GRADIO_SHARE=false
+# Host / port are set on the CLI, not via env vars — `ui.py` passes them
+# explicitly to Gradio's launch(), which overrides GRADIO_SERVER_NAME/PORT:
+#   tool-compass ui --host 0.0.0.0 --port 7860
+# (defaults: 127.0.0.1:7860; the Docker image already binds 0.0.0.0.)
+
+# Public sharing: pass `tool-compass ui --share` for a public Gradio URL.
+# --share is REFUSED unless GRADIO_AUTH is set, so the link is never wide
+# open. Format is "user:pass" (both sides non-empty).
+# GRADIO_AUTH=user:pass
 
 # =============================================================================
 # Docker-Specific

{tool_compass-2.4.0 → tool_compass-2.5.0}/.gitignore

@@ -68,6 +68,11 @@ db/tools.db
 db/compass_analytics.db
 db/chains.db
 
+# SQLite transient sidecar files (WAL/SHM/journal — rewritten on every open/close)
+db/*.db-shm
+db/*.db-wal
+db/*.db-journal
+
 # Logs
 *.log
 logs/
@@ -121,3 +126,6 @@ npm/README.pt-BR.md
 npm/node_modules/
 npm/package-lock.json
 npm/*.tgz
+
+# Dogfood swarm working artifacts (manifest, wave outputs) — not shipped
+swarms/

{tool_compass-2.4.0 → tool_compass-2.5.0}/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-07-04
+
+Dogfood swarm v4 — a composed re-audit health pass (Stage A bug/security →
+B/C/D proactive/humanization/visual) followed by a 12-feature pass, each
+feature closed by an adversarial cross-wave re-audit. Tests 1148 → 1337
+(88.6% coverage); ruff clean. No breaking API changes — every new config
+field defaults to today's behavior and all existing tool/CLI responses keep
+their shape. Two behavior changes are called out under **Changed**.
+
+### Added
+- **HTTP / streamable-http backend transport.** Backends of type `http` now
+  connect at runtime via the MCP SDK's Streamable HTTP client — tool-compass
+  can front remote / SaaS MCP servers, not just local stdio subprocesses.
+  `url` + `headers` (headers redacted in `doctor` output) as before.
+- **Optional bearer-token gateway auth** (`gateway_auth_token`, or the
+  `TOOL_COMPASS_GATEWAY_AUTH_TOKEN` env var). When set, the HTTP transport
+  requires `Authorization: Bearer <token>` (constant-time compare, `/health`
+  and `/ready` stay open). Opt-in and fail-closed only when enabled; the stdio
+  transport is never affected.
+- **Hybrid search + exact-name boost.** `compass()` now fuses the semantic
+  (HNSW) and lexical signals with Reciprocal Rank Fusion on the healthy path
+  (not only as an Ollama-outage fallback), and an exact tool-name paste
+  (`fs:read_file`, or the bare `read_file`) ranks #1. Toggles: `hybrid_search`,
+  `exact_name_boost`, `exact_match_confidence`.
+- **Full-schema `describe()`.** The complete JSON `inputSchema`
+  (required fields, per-parameter descriptions, enums, defaults) is now
+  preserved through sync and returned by `describe()` alongside the collapsed
+  `parameters` — so an agent can build a correct `execute()` call in one hop.
+- **Per-backend / per-tool timeouts** (`default_timeout`, `tool_timeouts`) —
+  override the 15 s default so slow image/video/LLM backends aren't cut off.
+- **`tool-compass execute <tool> '<json-args>'`** — run a proxied tool call
+  from the terminal to smoke-test a backend. `--timeout`, `--json`.
+- **Per-backend tool allow/deny** (`allow_tools` / `deny_tools` glob lists) —
+  expose a safe subset of a broad backend. Enforced at index time and at the
+  `execute()` boundary (defense-in-depth).
+- **Active liveness probe** on `compass_status(active=True)` — surfaces
+  hung-but-connected backends a passive connection check would miss.
+- **Analytics retention** (`analytics_retention_days`, default 30, `0` =
+  forever) with an automatic prune on startup sync, so the analytics DB no
+  longer grows without bound.
+- **Auto-refresh polling** — `sync_polling_interval` is now honored at runtime
+  (the gateway starts a background re-sync loop when it is `> 0`).
+- **Schema-aware change detection** — a backend that revises a tool's
+  description or parameters (same name) is now re-synced and re-embedded
+  (previously only name changes were detected).
+
+### Fixed
+- **Multi-backend index data loss (HIGH).** Orphan-vector compaction rebuilt
+  the index from only the changed-backend subset, silently deleting every
+  other backend's tools after ~20 churn cycles. Compaction now rebuilds from
+  the full connected catalog.
+- **Analytics time-window skew (HIGH).** Timeframe queries compared naive
+  local time against UTC-stored timestamps, shifting every windowed summary by
+  the host's UTC offset. All analytics windows are now computed in UTC.
+- **Docker UI unreachable.** The published image ran the Gradio UI bound to
+  `127.0.0.1` (loopback) despite the port mapping — `docker-compose up` served
+  nothing on `localhost:7860`. The image now binds `0.0.0.0`.
+- `compass()` no longer raises an unhandled `IndexError` on an empty-match +
+  zero-confidence-chain query; `compass_chains(create/detect)` returns the
+  structured service-unavailable envelope when Ollama is down instead of a raw
+  exception; `compass_chains(detect)` now actually indexes detected chains
+  (was reporting success without indexing them).
+- The embedding-cache write no longer commits inside `build_index`'s atomic
+  rebuild transaction (a failed HNSW save could leave DB/HNSW divergence).
+- CLI `search` now catches the real Ollama-down exception types and falls back
+  to keyword search (matching the UI/gateway), so `--help`'s promise holds.
+- `requirements.txt` now includes `rich` (the Docker image was missing it);
+  `.env.example` / `llms.txt` corrected to the env vars the code actually reads.
+- Several test-integrity fixes (coroutine leak, tautological/mis-named tests).
+
+### Changed
+- **Hybrid search is on by default** (`hybrid_search=True`). This changes the
+  default result ranking (for the better); set `hybrid_search=false` to restore
+  pure-semantic ordering. The response envelope, `min_confidence`, and `top_k`
+  contracts are unchanged.
+- **Backend names containing `:` are now rejected at config load** with a clear
+  error — a colon is the reserved `backend:tool` separator and made routing and
+  the allow/deny policy ambiguous. Rename any such backend (this only rejects
+  configs that were already mis-routing).
+
 ## [2.4.0] - 2026-06-20
 
 Dogfood swarm v3 — full health pass (bug/security → proactive → humanization

{tool_compass-2.4.0 → tool_compass-2.5.0}/Dockerfile

@@ -72,10 +72,14 @@ ENV PYTHONUNBUFFERED=1 \
     PYTHONPATH=/app \
     # Tool Compass settings
     TOOL_COMPASS_BASE_PATH=/app \
-    OLLAMA_URL=http://host.docker.internal:11434 \
-    # Gradio settings
-    GRADIO_SERVER_NAME=0.0.0.0 \
-    GRADIO_SERVER_PORT=7860
+    OLLAMA_URL=http://host.docker.internal:11434
+# UI-DOCKER-BIND-001: the container UI bind is set explicitly on the CMD below
+# (--host 0.0.0.0), NOT via GRADIO_SERVER_NAME. ui.py calls
+# demo.launch(server_name=args.host, ...) with a truthy default, which
+# overrides Gradio's native GRADIO_SERVER_NAME env support — so setting that env
+# here was a silent no-op and left the containerized UI bound to loopback
+# (unreachable through the published port). The prior GRADIO_SERVER_NAME/PORT
+# ENV lines were dropped to remove that misleading dead configuration.
 
 # Expose Gradio UI port
 EXPOSE 7860
@@ -87,8 +91,12 @@ USER compass
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD python -c "from indexer import CompassIndex; idx = CompassIndex(); print('healthy' if idx.load_index() else 'no index')" || exit 1
 
-# Default command: Run Gradio UI
-CMD ["python", "ui.py"]
+# Default command: Run Gradio UI.
+# UI-DOCKER-BIND-001: bind 0.0.0.0 explicitly so the UI is reachable through the
+# published port mapping (inside the container the container boundary is the
+# isolation layer; external exposure is controlled by `docker run -p` /
+# compose `ports:`). Without this the UI bound to 127.0.0.1 and was unreachable.
+CMD ["python", "ui.py", "--host", "0.0.0.0", "--port", "7860"]
 
 # =============================================================================
 # Stage 3: MCP Gateway (alternative entrypoint)
@@ -96,7 +104,13 @@ CMD ["python", "ui.py"]
 FROM production AS mcp-gateway
 
 # Override for HTTP mode (Fly.io / Smithery)
-ENV PORT=8080
+# ci-infra-01: gateway.py's _run_http defaults HOST to 127.0.0.1 (loopback), so
+# without this the published image binds loopback and any orchestrator's proxy /
+# health check (the HEALTHCHECK below hits localhost, but Fly/Smithery reach the
+# container over the network) can't reach the gateway. 0.0.0.0 is the documented
+# reverse-proxy path — this image is meant to sit behind an authenticated edge.
+ENV PORT=8080 \
+    HOST=0.0.0.0
 
 # Expose MCP HTTP port
 EXPOSE 8080

{tool_compass-2.4.0 → tool_compass-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tool-compass
-Version: 2.4.0
+Version: 2.5.0
 Summary: Semantic MCP tool discovery gateway - find tools by intent, not memory
 Project-URL: Homepage, https://github.com/mcp-tool-shop-org/tool-compass
 Project-URL: Documentation, https://github.com/mcp-tool-shop-org/tool-compass#readme
@@ -94,9 +94,10 @@ Tool Compass uses **semantic search** to find relevant tools from a natural lang
 
 ```bash
 npx @mcptoolshop/tool-compass --help
-npx @mcptoolshop/tool-compass serve     # MCP gateway
-npx @mcptoolshop/tool-compass ui        # Gradio UI
-npx @mcptoolshop/tool-compass doctor    # Diagnose setup
+npx @mcptoolshop/tool-compass serve                 # MCP gateway
+npx @mcptoolshop/tool-compass ui                    # Gradio UI
+npx @mcptoolshop/tool-compass doctor                # Diagnose setup
+npx @mcptoolshop/tool-compass execute fs:read_file '{"path":"README.md"}'  # Smoke-test a proxied call
 ```
 
 Downloads a verified platform binary on first run (SHA256-checked against the GitHub Release). Cached locally — subsequent invocations launch instantly. See [@mcptoolshop/tool-compass](https://www.npmjs.com/package/@mcptoolshop/tool-compass) on npm.
@@ -157,13 +158,13 @@ docker-compose --profile with-ollama up
 
 ## Features
 
-- **Semantic Search** - Find tools by describing what you want to do
-- **Progressive Disclosure** - `compass()` → `describe()` → `execute()`
-- **Hot Cache** - Frequently used tools are pre-loaded
-- **Chain Detection** - Automatically discovers common tool workflows
-- **Analytics** - Track usage patterns and tool performance
-- **Cross-Platform** - Windows, macOS, Linux
-- **Docker Ready** - One-command deployment
+- **Hybrid Search** - Semantic (HNSW) + lexical fusion with exact-name boost — describe what you want, or paste a tool name and it ranks #1
+- **Full-Schema Progressive Disclosure** - `compass()` → `describe()` → `execute()`; `describe()` returns the complete `inputSchema` (required fields, descriptions, enums, defaults)
+- **stdio + HTTP backends** - Front local subprocess MCP servers *and* remote / SaaS servers over streamable-http, with optional bearer-token auth
+- **Per-tool timeouts & allow/deny** - Override the default timeout per backend/tool; expose a safe subset of a broad backend
+- **Hot Cache & Chain Detection** - Frequently used tools pre-loaded; common tool workflows discovered automatically
+- **Analytics** - Track usage patterns and tool performance (with retention/prune)
+- **Cross-Platform & Docker Ready** - Windows, macOS, Linux; one-command deployment
 
 ## Architecture
 
@@ -220,16 +221,18 @@ Returns:
 
 | Tool | Description |
 |------|-------------|
-| `compass(intent)` | Semantic search for tools |
-| `describe(tool_name)` | Get full schema for a tool |
+| `compass(intent)` | Hybrid semantic + lexical search with exact-name boost |
+| `describe(tool_name)` | Get the full `inputSchema` for a tool (required/enums/defaults) |
 | `execute(tool_name, args)` | Run a tool on its backend |
 | `compass_categories()` | List categories and servers |
-| `compass_status()` | System health and config |
+| `compass_status(active)` | System health and config; `active=True` runs a live backend liveness probe |
 | `compass_analytics(timeframe)` | Usage statistics |
 | `compass_chains(action)` | Manage tool workflows |
 | `compass_sync(force)` | Rebuild index from backends |
 | `compass_audit()` | Full system report |
 
+The same actions are available from the CLI — including `tool-compass execute <tool> '<json>'` to smoke-test a proxied call from the terminal.
+
 ### Progressive Disclosure Pattern
 
 Tool Compass uses a three-step progressive disclosure pattern to minimize token usage:
@@ -273,13 +276,18 @@ The `hint` field in compass results guides this flow, suggesting when to use `de
 | `OLLAMA_URL` | Ollama server URL | `http://localhost:11434` |
 | `COMFYUI_URL` | ComfyUI server | `http://localhost:8188` |
 | `PORT` | Set to enable HTTP transport (e.g., for Fly.io) | unset (stdio) |
+| `TOOL_COMPASS_GATEWAY_AUTH_TOKEN` | Bearer token required on the HTTP transport (opt-in; overrides the `gateway_auth_token` config field) | unset (no auth) |
 
 **Default data directories:**
 - **Windows:** `%LOCALAPPDATA%\tool-compass\`
 - **macOS:** `~/Library/Application Support/tool-compass/`
 - **Linux:** `~/.config/tool-compass/` (or `$XDG_CONFIG_HOME/tool-compass/`)
 
-See [`.env.example`](.env.example) for all options.
+Config-file settings (in `compass_config.json`) added in v2.5.0 — `hybrid_search`,
+`exact_name_boost`, per-backend `default_timeout` / `tool_timeouts`,
+`allow_tools` / `deny_tools`, `analytics_retention_days`, and HTTP (`type: "http"`)
+backends — are documented in the [Handbook → Configuration](https://mcp-tool-shop-org.github.io/tool-compass/handbook/configuration/).
+See [`.env.example`](.env.example) for env-var options.
 
 ## Performance
 
@@ -368,14 +376,16 @@ intentionally not hand-authored. Hand-curated sections (Known Gaps,
 Remediation History) live outside the `<!-- SHIPCHECK-AUTO-START/END -->`
 markers in SCORECARD.md and survive regenerations.
 
+Latest `shipcheck audit`: **32 checked · 0 unchecked · 5 skipped · 100% pass — all hard gates pass.**
+
 | Category | Score | Notes |
 |----------|-------|-------|
-| A. Security | TBD | SHA-pinned actions; digest-pinned base image; SLSA provenance + SBOM on PyPI + GHCR; pre-commit secrets scan |
-| B. Error Handling | TBD | Structured results, graceful degradation, exit codes |
-| C. Operator Docs | TBD | README, CHANGELOG, LICENSE, Makefile `verify` + `verify-metrics` + `scorecard` |
-| D. Shipping Hygiene | TBD | CI consolidated; timeout-minutes + retention-days on every job; pytest config in pyproject.toml |
-| E. Identity (soft) | TBD | Logo, landing page, GitHub metadata; explicit maintainers in pyproject.toml |
-| **Total** | **TBD** | Regenerate via `make scorecard` |
+| A. Security | ✅ Pass | SHA-pinned actions; digest-pinned base image; SLSA provenance + SBOM on PyPI + GHCR; pre-commit secrets scan; opt-in gateway bearer auth |
+| B. Error Handling | ✅ Pass | Structured results, graceful degradation, exit codes |
+| C. Operator Docs | ✅ Pass | README, CHANGELOG, LICENSE, Makefile `verify` + `verify-metrics` + `scorecard` |
+| D. Shipping Hygiene | ✅ Pass | CI consolidated; timeout-minutes + retention-days on every job; pytest config in pyproject.toml |
+| E. Identity (soft) | ✅ Pass | Logo, landing page, GitHub metadata; explicit maintainers in pyproject.toml |
+| **Total** | **100%** | All hard gates pass — regenerate via `make scorecard` |
 
 ## License
 

{tool_compass-2.4.0 → tool_compass-2.5.0}/README.md

@@ -47,9 +47,10 @@ Tool Compass uses **semantic search** to find relevant tools from a natural lang
 
 ```bash
 npx @mcptoolshop/tool-compass --help
-npx @mcptoolshop/tool-compass serve     # MCP gateway
-npx @mcptoolshop/tool-compass ui        # Gradio UI
-npx @mcptoolshop/tool-compass doctor    # Diagnose setup
+npx @mcptoolshop/tool-compass serve                 # MCP gateway
+npx @mcptoolshop/tool-compass ui                    # Gradio UI
+npx @mcptoolshop/tool-compass doctor                # Diagnose setup
+npx @mcptoolshop/tool-compass execute fs:read_file '{"path":"README.md"}'  # Smoke-test a proxied call
 ```
 
 Downloads a verified platform binary on first run (SHA256-checked against the GitHub Release). Cached locally — subsequent invocations launch instantly. See [@mcptoolshop/tool-compass](https://www.npmjs.com/package/@mcptoolshop/tool-compass) on npm.
@@ -110,13 +111,13 @@ docker-compose --profile with-ollama up
 
 ## Features
 
-- **Semantic Search** - Find tools by describing what you want to do
-- **Progressive Disclosure** - `compass()` → `describe()` → `execute()`
-- **Hot Cache** - Frequently used tools are pre-loaded
-- **Chain Detection** - Automatically discovers common tool workflows
-- **Analytics** - Track usage patterns and tool performance
-- **Cross-Platform** - Windows, macOS, Linux
-- **Docker Ready** - One-command deployment
+- **Hybrid Search** - Semantic (HNSW) + lexical fusion with exact-name boost — describe what you want, or paste a tool name and it ranks #1
+- **Full-Schema Progressive Disclosure** - `compass()` → `describe()` → `execute()`; `describe()` returns the complete `inputSchema` (required fields, descriptions, enums, defaults)
+- **stdio + HTTP backends** - Front local subprocess MCP servers *and* remote / SaaS servers over streamable-http, with optional bearer-token auth
+- **Per-tool timeouts & allow/deny** - Override the default timeout per backend/tool; expose a safe subset of a broad backend
+- **Hot Cache & Chain Detection** - Frequently used tools pre-loaded; common tool workflows discovered automatically
+- **Analytics** - Track usage patterns and tool performance (with retention/prune)
+- **Cross-Platform & Docker Ready** - Windows, macOS, Linux; one-command deployment
 
 ## Architecture
 
@@ -173,16 +174,18 @@ Returns:
 
 | Tool | Description |
 |------|-------------|
-| `compass(intent)` | Semantic search for tools |
-| `describe(tool_name)` | Get full schema for a tool |
+| `compass(intent)` | Hybrid semantic + lexical search with exact-name boost |
+| `describe(tool_name)` | Get the full `inputSchema` for a tool (required/enums/defaults) |
 | `execute(tool_name, args)` | Run a tool on its backend |
 | `compass_categories()` | List categories and servers |
-| `compass_status()` | System health and config |
+| `compass_status(active)` | System health and config; `active=True` runs a live backend liveness probe |
 | `compass_analytics(timeframe)` | Usage statistics |
 | `compass_chains(action)` | Manage tool workflows |
 | `compass_sync(force)` | Rebuild index from backends |
 | `compass_audit()` | Full system report |
 
+The same actions are available from the CLI — including `tool-compass execute <tool> '<json>'` to smoke-test a proxied call from the terminal.
+
 ### Progressive Disclosure Pattern
 
 Tool Compass uses a three-step progressive disclosure pattern to minimize token usage:
@@ -226,13 +229,18 @@ The `hint` field in compass results guides this flow, suggesting when to use `de
 | `OLLAMA_URL` | Ollama server URL | `http://localhost:11434` |
 | `COMFYUI_URL` | ComfyUI server | `http://localhost:8188` |
 | `PORT` | Set to enable HTTP transport (e.g., for Fly.io) | unset (stdio) |
+| `TOOL_COMPASS_GATEWAY_AUTH_TOKEN` | Bearer token required on the HTTP transport (opt-in; overrides the `gateway_auth_token` config field) | unset (no auth) |
 
 **Default data directories:**
 - **Windows:** `%LOCALAPPDATA%\tool-compass\`
 - **macOS:** `~/Library/Application Support/tool-compass/`
 - **Linux:** `~/.config/tool-compass/` (or `$XDG_CONFIG_HOME/tool-compass/`)
 
-See [`.env.example`](.env.example) for all options.
+Config-file settings (in `compass_config.json`) added in v2.5.0 — `hybrid_search`,
+`exact_name_boost`, per-backend `default_timeout` / `tool_timeouts`,
+`allow_tools` / `deny_tools`, `analytics_retention_days`, and HTTP (`type: "http"`)
+backends — are documented in the [Handbook → Configuration](https://mcp-tool-shop-org.github.io/tool-compass/handbook/configuration/).
+See [`.env.example`](.env.example) for env-var options.
 
 ## Performance
 
@@ -321,14 +329,16 @@ intentionally not hand-authored. Hand-curated sections (Known Gaps,
 Remediation History) live outside the `<!-- SHIPCHECK-AUTO-START/END -->`
 markers in SCORECARD.md and survive regenerations.
 
+Latest `shipcheck audit`: **32 checked · 0 unchecked · 5 skipped · 100% pass — all hard gates pass.**
+
 | Category | Score | Notes |
 |----------|-------|-------|
-| A. Security | TBD | SHA-pinned actions; digest-pinned base image; SLSA provenance + SBOM on PyPI + GHCR; pre-commit secrets scan |
-| B. Error Handling | TBD | Structured results, graceful degradation, exit codes |
-| C. Operator Docs | TBD | README, CHANGELOG, LICENSE, Makefile `verify` + `verify-metrics` + `scorecard` |
-| D. Shipping Hygiene | TBD | CI consolidated; timeout-minutes + retention-days on every job; pytest config in pyproject.toml |
-| E. Identity (soft) | TBD | Logo, landing page, GitHub metadata; explicit maintainers in pyproject.toml |
-| **Total** | **TBD** | Regenerate via `make scorecard` |
+| A. Security | ✅ Pass | SHA-pinned actions; digest-pinned base image; SLSA provenance + SBOM on PyPI + GHCR; pre-commit secrets scan; opt-in gateway bearer auth |
+| B. Error Handling | ✅ Pass | Structured results, graceful degradation, exit codes |
+| C. Operator Docs | ✅ Pass | README, CHANGELOG, LICENSE, Makefile `verify` + `verify-metrics` + `scorecard` |
+| D. Shipping Hygiene | ✅ Pass | CI consolidated; timeout-minutes + retention-days on every job; pytest config in pyproject.toml |
+| E. Identity (soft) | ✅ Pass | Logo, landing page, GitHub metadata; explicit maintainers in pyproject.toml |
+| **Total** | **100%** | All hard gates pass — regenerate via `make scorecard` |
 
 ## License
 

{tool_compass-2.4.0 → tool_compass-2.5.0}/analytics.py

@@ -21,7 +21,7 @@ import hashlib
 import threading
 from collections import deque
 import numpy as np
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional, List, Dict, Any, Deque
 from dataclasses import dataclass
@@ -574,6 +574,85 @@ class CompassAnalytics:
             # MCC-B-005: chain pattern save failure degrades analytics only.
             self._note_degraded("_save_chain_pattern", e)
 
+    async def prune_old_records(self, retention_days: int) -> int:
+        """Delete analytics rows older than the retention window (FEAT-04).
+
+        DELETEs from BOTH append-only tables — tool_calls and search_queries —
+        whose created_at is older than `retention_days` days, and returns the
+        total number of rows removed. A sibling gateway agent calls this as
+        ``await analytics.prune_old_records(config.analytics_retention_days)``.
+
+        retention_days <= 0 -> NO-OP (keep forever), returns 0.
+
+        CA-001 discipline: created_at is stamped by SQLite CURRENT_TIMESTAMP,
+        which is UTC. We compute the cutoff INSIDE SQLite via
+        ``datetime('now', '-N days')`` so BOTH sides of the comparison are UTC
+        — never datetime.now() naive local wall-clock, which would skew the
+        cutoff by the host's UTC offset (the exact bug fixed in
+        get_analytics_summary).
+
+        MCC-B-005 discipline: wrapped in the same _degraded / try-except the
+        other write methods use — a prune failure must degrade analytics, not
+        raise up through the caller. Respects the thread-safe lazy connection
+        and the write lock (self._lock) the rest of the module uses.
+        """
+        if self._degraded:
+            return 0
+        # retention_days <= 0 means "keep forever" — nothing to prune.
+        if retention_days <= 0:
+            return 0
+
+        total_deleted = 0
+        try:
+            db = self._get_db()
+
+            # Push the cutoff into SQL so it is evaluated in UTC by SQLite,
+            # matching how created_at was written. datetime('now', ?) with a
+            # '-N days' modifier yields a UTC 'YYYY-MM-DD HH:MM:SS' bound.
+            modifier = f"-{int(retention_days)} days"
+
+            with self._lock:
+                cur = db.execute(
+                    "DELETE FROM tool_calls "
+                    "WHERE created_at < datetime('now', ?)",
+                    (modifier,),
+                )
+                total_deleted += cur.rowcount or 0
+
+                cur = db.execute(
+                    "DELETE FROM search_queries "
+                    "WHERE created_at < datetime('now', ?)",
+                    (modifier,),
+                )
+                total_deleted += cur.rowcount or 0
+
+                db.commit()
+        except sqlite3.Error as e:
+            # MCC-B-005: a prune failure degrades analytics; it must never
+            # break the caller (the gateway prunes as housekeeping).
+            self._note_degraded("prune_old_records", e)
+            return 0
+
+        # VACUUM reclaims the pages freed by a large delete. It CANNOT run
+        # inside a transaction and takes its own file lock, so run it
+        # best-effort AFTER the committed delete and swallow any failure —
+        # reclaiming space is a nice-to-have, never worth raising for. Guard on
+        # a non-trivial delete so we don't VACUUM the whole DB on every no-op
+        # prune. Held under the write lock so it doesn't race another writer.
+        if total_deleted > 0:
+            try:
+                with self._lock:
+                    db.execute("VACUUM")
+            except sqlite3.Error as e:
+                logger.debug(f"VACUUM after prune skipped (non-fatal): {e}")
+
+        if total_deleted:
+            logger.info(
+                f"Pruned {total_deleted} analytics row(s) older than "
+                f"{retention_days} day(s)."
+            )
+        return total_deleted
+
     async def refresh_hot_cache(self, embedder=None, index=None):
         """
         Update the hot cache with top N most used tools.
@@ -798,7 +877,12 @@ class CompassAnalytics:
 
         # Parse timeframe
         hours = {"1h": 1, "24h": 24, "7d": 168, "30d": 720}.get(timeframe, 24)
-        since = datetime.now() - timedelta(hours=hours)
+        # CA-001: created_at is written by SQLite CURRENT_TIMESTAMP, which is UTC.
+        # Compute the window bound in UTC too — datetime.now() is naive LOCAL
+        # wall-clock, so a naive bound skews every window by the host's UTC
+        # offset. strftime drops the tz suffix, yielding a UTC
+        # 'YYYY-MM-DD HH:MM:SS' string that matches CURRENT_TIMESTAMP.
+        since = datetime.now(timezone.utc) - timedelta(hours=hours)
         # Use SQLite-compatible format (YYYY-MM-DD HH:MM:SS) for timestamp comparison
         since_str = since.strftime("%Y-%m-%d %H:%M:%S")
 
@@ -926,26 +1010,60 @@ class CompassAnalytics:
             ORDER BY rank
         """)
 
+        # PC-B-001: this runs on the mandatory init path — get_analytics_instance()
+        # awaits it unconditionally and compass()/execute() call that UNWRAPPED,
+        # so a raw exception here surfaces as a bare traceback through the MCP
+        # JSON-RPC envelope (violates the BE-B-004 "handlers never raise"
+        # invariant). Persisted blobs can be corrupt: a bad schema_json raises
+        # json.JSONDecodeError and a truncated embedding blob raises ValueError
+        # from np.frombuffer — neither is a sqlite3.Error, so nothing above
+        # catches them. Guard per-row and SKIP a bad row rather than aborting the
+        # whole load, matching record_search / record_tool_call which degrade
+        # instead of raising. A per-row skip keeps every good row loadable.
+        skipped = 0
         for row in cursor.fetchall():
-            embedding = None
-            if row["embedding"]:
-                embedding = np.frombuffer(row["embedding"], dtype=np.float32)
-
-            schema = None
-            if row["schema_json"]:
-                schema = json.loads(row["schema_json"])
-
-            self._hot_cache[row["tool_name"]] = HotToolEntry(
-                tool_name=row["tool_name"],
-                rank=row["rank"],
-                call_count=row["call_count"],
-                embedding=embedding,
-                schema=schema,
-                description=row["description"] or "",
-                last_called_at=None,
-            )
+            try:
+                embedding = None
+                if row["embedding"]:
+                    blob = row["embedding"]
+                    # SC-002 (indexer._cache_get): validate the blob byte length
+                    # before np.frombuffer. float32 == 4 bytes/element; a length
+                    # that is not a whole multiple of 4 is a truncated/corrupt
+                    # write and would raise ValueError.
+                    if len(blob) % 4 != 0:
+                        raise ValueError(
+                            f"corrupt embedding blob for {row['tool_name']}: "
+                            f"{len(blob)} bytes not a multiple of 4"
+                        )
+                    embedding = np.frombuffer(blob, dtype=np.float32)
 
-        logger.info(f"Loaded {len(self._hot_cache)} tools into hot cache from DB")
+                schema = None
+                if row["schema_json"]:
+                    schema = json.loads(row["schema_json"])
+
+                self._hot_cache[row["tool_name"]] = HotToolEntry(
+                    tool_name=row["tool_name"],
+                    rank=row["rank"],
+                    call_count=row["call_count"],
+                    embedding=embedding,
+                    schema=schema,
+                    description=row["description"] or "",
+                    last_called_at=None,
+                )
+            except (json.JSONDecodeError, ValueError, TypeError, sqlite3.Error) as e:
+                # Skip the bad row; a single corrupt persisted blob must not
+                # take down the whole hot-cache load (and thus the first
+                # compass()/execute() of the process).
+                skipped += 1
+                logger.warning(
+                    f"Skipping corrupt hot_tools row "
+                    f"'{row['tool_name'] if 'tool_name' in row.keys() else '?'}': {e}"
+                )
+
+        logger.info(
+            f"Loaded {len(self._hot_cache)} tools into hot cache from DB"
+            + (f" ({skipped} corrupt row(s) skipped)" if skipped else "")
+        )
 
     def close(self):
         """Close database connection.