pantheon-opencode 1.1.1 → 1.2.0

package/commands/pantheon-audit.md

@@ -0,0 +1,25 @@
+---
+description: "Audit: heuristic scan (zero LLM) + Themis review. Usage: /pantheon-audit [--light|--full|--plan]"
+agent: "zeus"
+---
+# /pantheon-audit — Quality & Security Audit
+
+**What:** Layer 1 heuristic scan (zero tokens, <2s). If BLOCKING, returns score. If APPROVED, Themis deep review.
+
+**Usage:**
+- `/pantheon-audit` — Full audit (Layer 1 → 2 → 3)
+- `/pantheon-audit --light` — Layer 1 only (quick scan)
+- `/pantheon-audit --full` — Force full review
+- `/pantheon-audit --plan` — Verification planning only
+
+## Layers
+
+### Layer 1 — Heuristic Scan
+`python3 scripts/themis_heuristic_scan.py [--path=<dir>]`
+Zero tokens, <2s. Checks: ruff, biome, anti-pattern slop, anti-overengineering (YAGNI), hash-anchored edits. Returns score 0-100 + APPROVED/BLOCKING.
+
+### Layer 2 — Themis Deep Review
+~500 tokens. Confidence scoring, regression prediction, OWASP Top 10.
+
+### Layer 3 — Verification Planning
+For N>5 file changes. Sugere plano de verificação antes de implementar.

package/commands/pantheon-consolidate.md

@@ -0,0 +1,11 @@
+---
+description: "Merge and consolidate memory entries"
+agent: zeus
+---
+
+Merge related memory entries and consolidate duplicates:
+
+1. Search for related memories via memory_search
+2. Merge overlapping entries
+3. Remove duplicates via memory_forget
+4. Store consolidated entry via memory_store

package/commands/pantheon-deepwork.md

@@ -0,0 +1,79 @@
+---
+description: "Start a heavy multi-phase task with persisted checkpoints, phased specialist dispatch, and Themis review gates. Progress saved to .pantheon/deepwork/ for resumability."
+agent: "zeus"
+---
+# /pantheon-deepwork — Heavy Task Workflow
+
+Structured, checkpointed workflow for complex multi-step tasks spanning multiple agents and sessions. Progress persisted to `.pantheon/deepwork/<task-slug>/`. Each phase gated by Themis.
+
+| Use When | Don't Use When |
+|---|---|
+| 10+ turns or multi-session | Simple fixes (→ @talos) |
+| Multi-agent dependencies | Single-file changes (→ /subtask) |
+| Costly context loss | < 5 turns (→ normal delegation) |
+
+## Workflow
+
+```
+Phase 0: SCOPING
+  └─ Zeus + Athena define scope, phases, acceptance criteria → PLAN.md
+
+Phase 1: DISCOVERY
+  └─ @apollo maps relevant codebase areas → DISCOVERY.md
+
+Phase 2-N: IMPLEMENTATION (parallel per phase)
+  └─ @hermes, @aphrodite, @demeter, @hephaestus, @prometheus
+  └─ Output: IMPL-phase-<N>-<agent>.md
+
+GATE after each phase:
+  └─ @themis reviews output → FAIL (fix + resubmit) or PASS (continue)
+
+Phase FINAL: VERIFICATION
+  └─ @themis full integration review → REVIEW.md
+  └─ All tests pass, coverage >80%
+```
+
+## Checkpoints
+
+```
+Usage:  --resume <slug> | --status <slug> | --list
+
+.pantheon/deepwork/<slug>/
+├── PLAN.md  DISCOVERY.md  IMPL-phase-*-*.md  phase-*-review.md  REVIEW.md  STATUS.md
+```
+
+## Full-Auto Mode (`--full-auto`)
+
+> ⚠️ Bypasses human review gates. Tier 1 gates (plan, commit, deploy) still require approval.
+
+**Themis auto-approves non-blocking reviews** — only stops on **BLOCKING** verdict. No waiting between phases. Checkpoints saved at every boundary.
+
+```
+/pantheon-deepwork --full-auto "Refactor auth service to use JWT"
+/pantheon-deepwork --full-auto --resume auth-jwt
+```
+
+## Anti-Stall
+
+- **Stall Detection** — 3 turns no progress → escalate
+- **Phase Reminder** — continue only independent work after dispatch
+- **Progress Checkpoint** — every 5 turns, summarize completed vs remaining
+- **Delegate Retry** — failures retried once with rephrased prompt
+
+## Usage
+
+```
+/pantheon-deepwork "Add user authentication with OAuth2"           # Start new session
+/pantheon-deepwork --resume auth-oauth2                            # Resume interrupted
+/pantheon-deepwork --status auth-oauth2                            # Show progress
+/pantheon-deepwork --list    /pantheon-deepwork --archive <slug>    # List / archive
+/pantheon-deepwork --full-auto "Refactor auth"                     # Themis auto-approve
+/pantheon-deepwork --full-auto --resume auth-refactor              # Resume full-auto
+```
+
+## Safety
+
+- All progress persisted — work is never lost
+- Each phase gated by Themis — quality enforced at every step
+- Explicit resume required — no auto-continue without intent (unless `--full-auto`)
+- `.pantheon/deepwork/` is gitignored — no accidental commits

package/commands/pantheon-optimize.md

@@ -0,0 +1,79 @@
+---
+description: "Scan, clean, cache, and archive Pantheon project files. Scans for bloat, archives completed deepwork, migrates flat files to MCP memory, and reports optimization opportunities. Usage: /pantheon-optimize"
+agent: "zeus"
+---
+# /pantheon-optimize — Pantheon Project Optimizer
+
+**What:** Multi-mode optimization: scans for documentation bloat, archives completed deepwork, migrates memory-bank flat files to MCP memory (ChromaDB), and reports token savings.
+
+## Usage
+
+```
+/pantheon-optimize                          → Full scan + compress (default)
+/pantheon-optimize --dry-run                → Preview only, no changes
+/pantheon-optimize --archive                → Archive completed deepwork sessions
+/pantheon-optimize --cache                  → Migrate memory-bank to MCP memory
+/pantheon-optimize --path=<dir>             → Limit scan to directory
+/pantheon-optimize --all                    → Run all modes (default)
+```
+
+## Modes
+
+### `--archive` — Deepwork Archiving
+Archives completed deepwork sessions from `.pantheon/deepwork/<slug>/` to `.pantheon/deepwork/archive/<slug>/`.
+
+**Criteria:** A session is "completed" if it has a `REVIEW.md` containing "APPROVED".
+
+```
+/pantheon-optimize archive                          → Interactive (ask per slug)
+/pantheon-optimize archive --dry-run                → Preview only
+/pantheon-optimize archive --auto                   → Archive all completed
+/pantheon-optimize archive --auto --keep=2           → Keep only PLAN.md + REVIEW.md
+/pantheon-optimize archive --auto --compress         → Single .md per slug
+```
+
+### `--cache` — Memory Bank Migration
+Scans `.pantheon/memory-bank/` for flat `.md` files and migrates them to the MCP memory server (ChromaDB).
+
+**What it does:**
+1. Reads all `.md` files in `.pantheon/memory-bank/`
+2. Chunks by heading (## sections)
+3. Calls `memory_store()` for each chunk with appropriate namespace
+4. Optionally archives the original files after successful migration
+
+```
+/pantheon-optimize cache                     → Preview candidates, ask confirm
+/pantheon-optimize cache --dry-run           → Show what would migrate
+/pantheon-optimize cache --auto              → Migrate + archive originals
+```
+
+### `--dry-run` (global flag)
+Prevents any destructive action. Shows what WOULD be done.
+
+### Default mode (no flags)
+Runs bloat scan on all `.md` and `.json` files + compression report.
+
+## Output
+
+```
+🧹 Pantheon Optimize Report
+
+📦 Bloat Scan: 47 .md + 12 .json files
+   → 3 oversized files found
+   → ~2.4K tokens recoverable
+
+📁 Deepwork Archive: 15 candidates
+   → 12 completed (REVIEW.md APPROVED)
+   → 3 in progress (skipped)
+   → Run with --archive --auto to archive 12 sessions
+
+🗄️  Memory Cache: 24 files in memory-bank/
+   → 18 already in MCP memory (dedup)
+   → 6 candidates for migration (~3.2K tokens)
+   → Run with --cache to migrate
+
+📊 Summary:
+   ⚡ 15 files optimizable → ~5.6K tokens
+   🗑️  12 deepworks archivable → ~320 files cleanup
+   🗄️  6 memory files → MCP migration ready
+```

package/commands/pantheon.md

@@ -0,0 +1,49 @@
+---
+description: "Dispatch a question to 2-4 specialist agents via inline Zeus council"
+agent: zeus
+---
+# /pantheon — Council Synthesis
+
+**What:** Dispatches the question to 2-3 specialist agents **in parallel** via `task()`, then synthesizes their responses into a single recommendation with resolved divergences.
+**Usage:** `/pantheon <question>`
+**When:** Architecture trade-offs, technology selection, security assessments, multi-stakeholder concerns
+**Returns:** Structured synthesis with recommendation, confidence level, resolved divergences
+
+## Dispatch Selection
+
+Choose 2-3 agents based on domain:
+
+| Domain | Specialists |
+|--------|-------------|
+| Architecture | hermes, demeter, themis, athena |
+| Security | themis, hermes, prometheus, nyx |
+| Database | demeter, hermes, prometheus |
+| AI/RAG | hephaestus, nyx |
+| Infrastructure | prometheus, hermes, themis |
+| Frontend/UX | aphrodite, themis, hermes |
+| Observability | nyx, hermes |
+| General | athena, themis, hermes |
+
+Send ALL `task()` calls in a single message. Each must return: Recommendation · Reasoning · Trade-offs · Risks · Confidence.
+
+## Synthesis Structure
+
+After ALL responses arrive, produce EXACTLY this structure:
+
+### 📋 Individual Assessments
+For each specialist: Recommendation, Reasoning, Trade-offs, Risks, Confidence
+
+### ✅ Agreements
+Where 2+ specialists converge
+
+### ⚡ Divergences
+Where they disagree — resolve each one with reasoning
+
+### 🔥 Total Divergence
+If ALL specialists disagree on a point, call this out explicitly
+
+### 🏆 Recommendation
+Decisive conclusion with confidence level
+
+## Question:
+$ARGUMENTS

package/opencode.json

@@ -40,41 +40,8 @@
     "themis": {
       "model": "opencode-go/deepseek-v4-pro"
     },
-    "zeus": {
-      "model": "opencode-go/deepseek-v4-pro"
-    },
     "hephaestus": {
       "model": "opencode-go/deepseek-v4-pro"
-    },
-    "hermes": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "aphrodite": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "demeter": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "prometheus": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "apollo": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "nyx": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "gaia": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "iris": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "mnemosyne": {
-      "model": "opencode-go/deepseek-v4-flash"
-    },
-    "talos": {
-      "model": "opencode-go/deepseek-v4-flash"
     }
   }
-}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.1.1",
-  "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
+  "version": "1.2.0",
+  "description": "Multi-agent orchestration for OpenCode \u2014 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -15,7 +15,7 @@
     "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "prepublishOnly": "node scripts/validate-routing.mjs",
-    "postpublish": "node -e \"console.log('✅ Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
+    "postpublish": "node -e \"console.log('\u2705 Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
     "version:status": "node scripts/versioning.mjs status",
     "version:apply": "node scripts/versioning.mjs apply",
     "release:dry-run": "node scripts/versioning.mjs status && npm pack --dry-run",
@@ -80,4 +80,4 @@
     "node": ">=18"
   },
   "preferGlobal": true
-}
+}

package/scripts/mcp_persistence_server.py

@@ -1,4 +1,3 @@
-# Auto-generated: resolved symlink from ../src/mcp/mcp_persistence_server.py
 #!/usr/bin/env python3
 """Pantheon Persistence MCP Server.
 
@@ -36,6 +35,9 @@ CREATE TABLE IF NOT EXISTS kv_store (
     UNIQUE(namespace, key)
 );
 
+CREATE INDEX IF NOT EXISTS idx_kv_namespace_expires
+ON kv_store(namespace, expires_at);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS kv_store_fts USING fts5(
     namespace, key, value,
     content='kv_store', content_rowid='id',
@@ -52,6 +54,14 @@ CREATE TRIGGER IF NOT EXISTS kv_store_ad AFTER DELETE ON kv_store BEGIN
     VALUES('delete', old.id, old.namespace, old.key, old.value);
 END;
 
+CREATE TRIGGER IF NOT EXISTS kv_store_softdelete_ad
+AFTER UPDATE OF deleted_at ON kv_store
+WHEN new.deleted_at IS NOT NULL AND old.deleted_at IS NULL
+BEGIN
+    INSERT INTO kv_store_fts(kv_store_fts, rowid)
+    VALUES('delete', old.id);
+END;
+
 CREATE TRIGGER IF NOT EXISTS kv_store_au AFTER UPDATE ON kv_store BEGIN
     INSERT INTO kv_store_fts(kv_store_fts, rowid, namespace, key, value)
     VALUES('delete', old.id, old.namespace, old.key, old.value);
@@ -220,6 +230,10 @@ async def kv_store(
         (namespace, key, value, expires_at),
     )
     conn.commit()
+
+    # Opportunistic auto-purge: if namespace has >500 entries, purge expired
+    _opportunistic_auto_purge(conn, namespace)
+    
     return {"status": "stored", "namespace": namespace, "key": key}
 
 
@@ -254,6 +268,52 @@ async def kv_get(
     return str(row[0]) if row else None
 
 
+@mcp.tool(
+    name="kv_stats",
+    description="Return storage statistics: total entries, expired count, per-namespace breakdown, DB file size.",
+)
+async def kv_stats(
+    scope: str = "project",
+) -> dict:
+    """Return storage statistics for the given scope.
+
+    Args:
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Dict with total_entries, expired_entries, namespaces breakdown, db_size_bytes.
+    """
+    conn = _db(scope)
+
+    total = conn.execute("SELECT COUNT(*) FROM kv_store WHERE deleted_at IS NULL").fetchone()[0]
+    expired = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE expires_at IS NOT NULL AND expires_at < datetime('now') "
+        "AND deleted_at IS NULL"
+    ).fetchone()[0]
+
+    ns_rows = conn.execute(
+        "SELECT namespace, COUNT(*) as cnt, "
+        "SUM(CASE WHEN expires_at IS NOT NULL AND expires_at < datetime('now') THEN 1 ELSE 0 END) as expired_count "
+        "FROM kv_store WHERE deleted_at IS NULL GROUP BY namespace ORDER BY cnt DESC"
+    ).fetchall()
+
+    namespaces = {
+        r[0]: {"count": r[1], "expired": r[2]}
+        for r in ns_rows
+    }
+
+    db_path = _resolve_db_path(scope)
+    db_size = db_path.stat().st_size if db_path and db_path.exists() else 0
+
+    return {
+        "scope": scope,
+        "total_entries": total,
+        "expired_entries": expired,
+        "namespaces": namespaces,
+        "db_size_bytes": db_size,
+    }
+
 @mcp.tool(
     name="kv_delete",
     description="Delete a key-value pair by namespace and key. "
@@ -353,6 +413,7 @@ async def kv_search(
 
     # Sanitize: extract up to 10 word tokens, wrap each in quotes
     terms = re.findall(r"\w+", query)[:10]
+    terms = [re.escape(t) for t in terms]
     if not terms:
         return []
     fts_query = " OR ".join(f'"{t}"' for t in terms)
@@ -441,6 +502,275 @@ async def purge_expired(
     return {"purged": count, "dry_run": False}
 
 
+
+def _opportunistic_auto_purge(conn: sqlite3.Connection, namespace: str, threshold: int = 500) -> None:
+    """Lightweight auto-purge: if namespace exceeds threshold, soft-delete expired entries."""
+    count = conn.execute(
+        "SELECT COUNT(*) FROM kv_store WHERE namespace = ? AND deleted_at IS NULL",
+        (namespace,),
+    ).fetchone()[0]
+    if count <= threshold:
+        return
+
+    conn.execute(
+        "UPDATE kv_store SET deleted_at = datetime('now') "
+        "WHERE namespace = ? AND expires_at IS NOT NULL "
+        "AND expires_at < datetime('now') AND deleted_at IS NULL",
+        (namespace,),
+    )
+    conn.commit()
+
+
+@mcp.tool(
+    name="kv_delete_namespace",
+    description="Delete all entries in a namespace. Optionally limit to entries older than N days.",
+)
+async def kv_delete_namespace(
+    namespace: str,
+    scope: str = "project",
+    older_than_days: int | None = None,
+) -> dict:
+    """Delete all entries in a namespace, optionally old entries only.
+
+    Args:
+        namespace: Namespace to clear.
+        scope: 'project' (default) or 'global'.
+        older_than_days: If set, only delete entries older than this many days.
+
+    Returns:
+        Dict with deleted count.
+    """
+    conn = _db(scope)
+
+    if older_than_days is not None:
+        cursor = conn.execute(
+            "DELETE FROM kv_store WHERE namespace = ? "
+            "AND datetime(created_at) < datetime('now', ? || ' days')",
+            (namespace, f"-{older_than_days}"),
+        )
+    else:
+        cursor = conn.execute(
+            "DELETE FROM kv_store WHERE namespace = ?",
+            (namespace,),
+        )
+    conn.commit()
+
+    return {"deleted": cursor.rowcount}
+
+
+# ── Context Checkpoint Tools ────────────────────────────────────────────────────
+# Session-scoped context storage for deepwork checkpoints, phase state,
+# tool call history, and reasoning chains. All entries use namespace
+# "checkpoint:{slug}" with auto-TTL of 4 hours (session duration).
+
+DEFAULT_CONTEXT_TTL: int = 14400  # 4 hours
+
+
+@mcp.tool(
+    name="context_save",
+    description="Save a context checkpoint for a session/phase. "
+    "Stores structured JSON in persistence KV with auto-TTL of 4h.",
+)
+async def context_save(
+    slug: str,
+    key: str,
+    content: str,
+    session_id: str | None = None,
+    ttl: int | None = None,
+    scope: str = "project",
+) -> dict:
+    """Save a context checkpoint with session-level isolation.
+
+    If session_id is provided, namespace becomes "checkpoint:{slug}:{session_id}"
+    preventing cross-session reads. If omitted, a random UUID is auto-generated
+    and returned so the caller can pass it to subsequent calls.
+
+    Args:
+        slug: Session identifier (e.g. "auth-refactor").
+        key: Checkpoint key (e.g. "phase:3", "latest", "heartbeat").
+        content: JSON-serializable string or any text content.
+        session_id: Unique session ID for namespace isolation (auto-generated if None).
+        ttl: TTL in seconds (default 4h / 14400). None = session duration.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Status dict with namespace, key, and session_id for subsequent calls.
+    """
+    actual_session = session_id or uuid.uuid4().hex[:12]
+    ns = f"checkpoint:{slug}:{actual_session}"
+    actual_ttl = ttl if ttl is not None else DEFAULT_CONTEXT_TTL
+
+    conn = _db(scope)
+    expires_at = (datetime.now(timezone.utc) + timedelta(seconds=actual_ttl)).isoformat()
+
+    conn.execute(
+        "INSERT INTO kv_store (namespace, key, value, expires_at, "
+        "created_at, updated_at) VALUES (?, ?, ?, ?, datetime('now'), datetime('now'))"
+        "ON CONFLICT(namespace, key) DO UPDATE SET "
+        "  value = excluded.value, "
+        "  expires_at = excluded.expires_at, "
+        "  updated_at = datetime('now')",
+        (ns, key, content, expires_at),
+    )
+    conn.commit()
+
+    # Also always update "latest" pointer
+    if key != "latest":
+        # Use a larger TTL for "latest" to outlive individual phase entries
+        conn.execute(
+            "INSERT INTO kv_store (namespace, key, value, expires_at, "
+            "created_at, updated_at) VALUES (?, 'latest', ?, ?, datetime('now'), datetime('now'))"
+            "ON CONFLICT(namespace, key) DO UPDATE SET "
+            "  value = excluded.value, "
+            "  expires_at = excluded.expires_at, "
+            "  updated_at = datetime('now')",
+            (ns, content, expires_at),
+        )
+        conn.commit()
+
+    return {"status": "stored", "namespace": ns, "key": key, "session_id": actual_session, "ttl": actual_ttl}
+
+
+@mcp.tool(
+    name="context_get",
+    description="Retrieve a context checkpoint by session slug and key. "
+    "Returns the raw content string or null if expired/not found.",
+)
+async def context_get(
+    slug: str,
+    key: str = "latest",
+    session_id: str | None = None,
+    scope: str = "project",
+) -> str | None:
+    """Get a context checkpoint with session isolation.
+
+    Args:
+        slug: Session identifier.
+        key: Checkpoint key (default "latest").
+        session_id: Required for isolation. If None, searches without session scope.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Content string or None if not found/expired.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    row = conn.execute(
+        "SELECT value FROM kv_store "
+        "WHERE namespace = ? AND key = ? "
+        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND deleted_at IS NULL",
+        (ns, key),
+    ).fetchone()
+    return row[0] if row else None
+
+
+@mcp.tool(
+    name="context_list",
+    description="List all context checkpoints for a session slug. "
+    "Returns keys, timestamps, and TTL info.",
+)
+async def context_list(
+    slug: str,
+    session_id: str | None = None,
+    scope: str = "project",
+) -> list[dict]:
+    """List all checkpoints for a session.
+
+    Args:
+        slug: Session identifier.
+        session_id: Optional. If provided, narrows to specific session.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        List of dicts with key, created_at, expires_at.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+    rows = conn.execute(
+        "SELECT key, created_at, expires_at FROM kv_store "
+        "WHERE namespace = ? "
+        "AND (expires_at IS NULL OR expires_at > datetime('now')) "
+        "AND deleted_at IS NULL "
+        "ORDER BY created_at DESC LIMIT 50",
+        (ns,),
+    ).fetchall()
+    return [
+        {
+            "key": r[0],
+            "created_at": r[1],
+            "expires_at": r[2],
+        }
+        for r in rows
+    ]
+
+
+@mcp.tool(
+    name="context_stats",
+    description="Return session context statistics: "
+    "checkpoint count, TTL remaining, total size per slug.",
+)
+async def context_stats(
+    slug: str,
+    session_id: str | None = None,
+    scope: str = "project",
+) -> dict:
+    """Return storage statistics for a session's context.
+
+    Args:
+        slug: Session identifier.
+        session_id: Optional. If provided, narrows to specific session.
+        scope: 'project' (default) or 'global'.
+
+    Returns:
+        Dict with entry_count, total_bytes, ttl_remaining.
+    """
+    conn = _db(scope)
+    ns = f"checkpoint:{slug}:{session_id}" if session_id else f"checkpoint:{slug}"
+
+    count = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    expired = conn.execute(
+        "SELECT COUNT(*) FROM kv_store "
+        "WHERE namespace = ? AND expires_at < datetime('now') "
+        "AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    size = conn.execute(
+        "SELECT COALESCE(SUM(LENGTH(value)), 0) FROM kv_store "
+        "WHERE namespace = ? AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()[0]
+
+    # Check TTL of latest entry
+    remaining: int | None = None
+    row = conn.execute(
+        "SELECT expires_at FROM kv_store "
+        "WHERE namespace = ? AND key = 'latest' AND deleted_at IS NULL",
+        (ns,),
+    ).fetchone()
+    if row and row[0]:
+        try:
+            exp = datetime.fromisoformat(row[0])
+            now = datetime.now(timezone.utc)
+            remaining = max(0, int((exp - now).total_seconds()))
+        except (ValueError, TypeError):
+            pass
+
+    return {
+        "slug": slug,
+        "namespace": ns,
+        "entry_count": count,
+        "expired_entries": expired,
+        "total_bytes": size,
+        "ttl_remaining_seconds": remaining,
+    }
+
 def _resolve_db_path(scope: str) -> Path | None:
     """Resolve the database file path for a given scope."""
     if scope == "global":