Symbol store has no cleanup tool — stale worktree indexes accumulate unbounded

[JRedeker]

Problem

The symbol store at ~/.cache/lgrep/symbols/index_*.json accumulates indexes forever. There is no CLI or MCP tool to prune stale entries. Only the semantic cache (~/.cache/lgrep/{hash}/) has cleanup (lgrep gc, lgrep prune-orphans).

Evidence

On a multi-agent host running ~5–10 OpenCode sessions with frequent per-change worktree creation/deletion (ADV workflow):

$ lgrep list_repos | jq ".repos | length"
101

$ du -sh ~/.cache/lgrep/symbols
477M    /home/jon/.cache/lgrep/symbols

Sampled 19 entries from lgrep list_repos; 9 of 19 point at deleted worktree paths. The on-disk semantic cache is clean:

$ lgrep gc
{"prune_orphans": {"dirs_examined": 18, "orphans": [], ...}}

lgrep gc only scans the semantic cache dirs. Symbol store is never touched.

Impact

1. Disk growth unbounded — 477M today, growing with every new worktree query.
2. list_repos output is noise — stale paths dominate.
3. search_symbols correctness risk — may return symbols from deleted worktrees.
4. Conflicts with documented lgrep gc mental model.

Source

• lgrep/src/lgrep/storage/index_store.py: list_repos() reads repo_path from each index_*.json; delete_index() exists but is not exposed via CLI/MCP.
• lgrep gc --help: "Run garbage collection on semantic caches" — no mention of symbol store.

Proposed API

Option A: Extend lgrep gc with --symbol-store flag (default on or opt-in).
Option B: New lgrep prune-symbols subcommand mirroring prune-orphans.

Either: stale = repo_path no longer exists on disk.

Context

Surfaced on a host that uses lgrep as the sole agent-facing local code intelligence surface (OpenCode LSP disabled). Symbol-store hygiene is load-bearing.

Happy to PR if maintainers indicate direction.

Environment

lgrep 3.1.3, Python 3.13, Ubuntu 24.04 headless, multi-agent OpenCode host.

[JRedeker]

Resolved by prune-symbols, shipped in v3.2.2.

What landed

• CLI: lgrep prune-symbols [--dry-run|--execute] [--storage-dir DIR] — dry-run by default.
• MCP: prune_symbols tool, which additionally skips projects currently loaded in the running server.
• Grace window: recently modified index files are preserved for 1 hour by default (LGREP_PRUNE_MIN_AGE_S). The repo_path_enoent and missing_repo_path_field reasons bypass grace because they are unambiguous.
• Deletion is refused for any path outside the resolved storage root, and for symlinked entries (TOCTOU guard); both surface in failures[] rather than as successful deletes.

Verification against this issue's own evidence

Metric	Reported here	Now
Symbol store size	477M	259M
Indexes / repos	101	45
Stale entries	9 of 19 sampled were dead worktree paths	0

A live prune_symbols dry run through the managed endpoint reports stale_indexes: [], files_examined: 45, with active projects correctly listed under skipped_active.

Note: as of v3.2.2, destructive prune over MCP requires the server to set LGREP_ALLOW_DESTRUCTIVE_MCP; without it the tool returns a preview and a refused_reason. The CLI --execute path is unaffected.