feat(cache): add cache inventory and guarded pruning

[kingfs]

Problem and scope

Removed worktrees leave cached project indexes behind, including orphan WAL/SHM files after interrupted deletion. Add CLI-only cache stats and explicit cache prune modes for inventory and offline cleanup. There are no new MCP tools: the previously proposed cache_stats / cache_prune registrations and daemon-session pruning behavior have been removed.

This remains a draft for maintainer direction and safety review. No prior tracking-issue discussion has been agreed. The current proposal uses conservative offline maintenance rather than deleting alongside active sessions.

Behavior and safeguards

• Stats and dry-run operate locally without daemon startup and without modifying cache contents. Stable, journal-free databases are inspected immutably. Databases with a WAL or rollback journal are reported as uninspectable and retained, rather than creating SHM or reading stale main-file metadata.
• Actual deletion refuses while any coordinated CBM participant is active, including a daemon with no current client. The idle-only lease does not publish shutdown intent or stop existing users, and blocks new admissions throughout cleanup. Existing legacy coordination checks and per-project locks remain in force.
• --missing-root and --older-than are ANDed. Age is last index time, not last access. Actual missing-root deletion additionally requires --confirm-missing-root, since offline storage is not proof of abandonment. Unknown, inaccessible, non-directory and unresolved roots do not match that filter.
• Databases containing ADRs are retained by default. --include-adrs explicitly permits deleting database-held documents. Unreadable/ambiguous databases are never pruned.
• Standalone --orphan-sidecars deletes only regular project WAL/SHM files whose DB is absent, rechecked under the project lease. Configuration, logs, journals, corrupt/temporary databases, symlinks and source directories are preserved.
• Deletion is not atomic across files. DB failure preserves sidecars; successful DB deletion followed by sidecar failure reports overlapping deleted/failed counts plus partial_count. Cancellation stops further deletion and releases leases; process death releases native leases. Orphan cleanup is explicitly retryable after interruption.
• The README documents size/count semantics, live-observation limits, conservative WAL handling, offline operation, ADR protection and recovery. No automatic cleanup is introduced.

Validation

Linux ARM64:

• Final ASan/UBSan cache, version-cohort and bootstrap suites: 62 passed, including partial deletion, abrupt process exit, cancellation, lease recovery and admission exclusion.
• MCP suite: 318 passed, with four Windows-only platform skips; includes rejection of both removed tool names.
• Product CLI suite: 11 passed, including WAL no-write behavior, journal preservation, ADR protection, explicit missing-root confirmation, active-daemon refusal without stopping it, prefixed global options, Unicode/URI characters and repeatable cleanup.
• Modified-source formatting, cache-module cppcheck, memory-core rules, no-test-skips policy, whitespace checks and workflow YAML parsing passed.
• CLI regressions now gate each native Linux/macOS/Windows PR production-smoke leg; also available as make -f Makefile.cbm test-cache-cli.
• Full cross-platform and sanitizer CI results remain authoritative and are pending for this revision. The earlier MSan startup-test budget adjustment is retained; it preserves the failure-record and single-spawn assertions.

Checklist

• Every commit carries a DCO sign-off
• New behavior has regression tests
• CLI regression tests are wired into cross-platform PR CI
• Full repository and cross-platform CI green for this revision
• Maintainer agreement on feature direction and remaining design choices

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

[DeusData]

Thank you for the contribution, including the inventory/pruning tests and the explicit notes about validation still outstanding. This draft introduces new MCP tools and CLI operations across cache, daemon, and server code, including deletion behavior, so it needs a direction and safety review before we can decide whether to integrate it.

We need more time to review the API boundary and the pruning safeguards, including behavior with active sessions, missing roots, and interrupted operations. Please keep this as a draft while we make that decision; this acknowledgement is neither acceptance nor rejection. Our review queue is quite full, and we appreciate the effort and your patience while we work through it.

[kingfs]

Thank you for the contribution, including the inventory/pruning tests and the explicit notes about validation still outstanding. This draft introduces new MCP tools and CLI operations across cache, daemon, and server code, including deletion behavior, so it needs a direction and safety review before we can decide whether to integrate it.

We need more time to review the API boundary and the pruning safeguards, including behavior with active sessions, missing roots, and interrupted operations. Please keep this as a draft while we make that decision; this acknowledgement is neither acceptance nor rejection. Our review queue is quite full, and we appreciate the effort and your patience while we work through it.

Regarding the MCP tools (cache_stats and cache_prune) introduced in the draft, I agree that these operations are inherently local and probably shouldn't be exposed via MCP for the AI to execute directly.

The core issue I was trying to solve is that my local environment had accumulated around 5 GB of cache. Many of those cache files belonged to worktree paths that had already been cleaned up by the AI, yet their corresponding cache files persisted. That's why I created this PR—though my AI assistant ended up generating a bit more scope and code than was actually necessary!