fix: Report clustering availability and publication health

docs/mcp-tools.md

@@ -93,6 +93,31 @@ No parameters.
 
 **Returns:** version, tier, message count, health status, and capabilities.
 
+`health.clustering` reports dependency availability, the last maintenance outcome,
+source freshness, coverage and cluster count. Zero clusters can be a successful
+empty or all-noise result. A missing dependency is reported separately.
+
+All health entries retain `status: "ok" | "degraded"`. Clustering also has a
+`state`: `unknown`, `pending`, `deferred`, `degraded` or `ready`. A disconnected
+database is unknown; busy foreground/model ownership is deferred. Pending
+caller writes and unverified vector-generation coverage cannot report ready.
+`last_error`, `dependency_error` and `process_error` contain categories only.
+The last process failure clears after committed successful clustering work.
+Success pending a caller's outer commit preserves that evidence; a later
+committed maintenance pass can clear it.
+
+Clustering remains optional. Installation guidance is included only when the
+HDBSCAN module is confirmed missing; a failed native import alone does not
+produce a missing-package recommendation.
+
+## truememory_status
+
+Inspect rebuild progress and subsystem health. `status_id` is optional and
+defaults to `0`, the most recent tier-switch rebuild. Clustering appears under
+`degradation.clustering`, with the same fields as stats. Its inspection uses an
+existing connection when available and never constructs a memory instance,
+opens a database, loads a native package/model, or starts maintenance.
+
 ---
 
 ## truememory_configure

docs/resource-budgets.md

@@ -1105,3 +1105,39 @@ vector-publication guards. Ingest database replacement, profile/style getter
 freshness and custom-schema source tracking remain separate work. Synthetic
 SQLite and event tests establish scheduling and ownership behavior; native
 latency, throughput and memory acceptance still require measurement.
+
+### Clustering health visibility (#720)
+
+Clustering health reuses the scheduler's dependency identity and persisted
+attempt/provenance row. It reports availability, outcome, freshness, coverage,
+output count and categorical errors separately. A successful empty or all-noise
+result remains `success_empty` with zero output; a missing dependency cannot
+become an empty success. Existing unverified vector-generation coverage remains
+visible and does not certify complete health.
+
+The engine accessor does not connect or initialize a coordinator. It attempts
+the foreground lock without waiting, then reads the existing connection under
+one read snapshot. Model ownership is also tried without waiting. Foreground
+and model contention report deferred observation; a disconnected engine reports
+unknown readiness. An existing caller transaction is preserved and reported as
+pending caller commit. Source mutations, pending work and failed attempts retain
+their distinct outcomes and prior published counts.
+
+Package inspection uses at most six top-level spec lookups and three distribution
+records per observation. It imports no native module and loads no model.
+Distribution metadata
+failure can report dependency unavailability, but installation guidance requires
+a confirmed absent HDBSCAN module. A cached worker extension failure is reused
+only while its dependency identity matches. Health reads do not change durable
+attempts, capability epochs or scheduling, and do not create a worker or database.
+
+Actual maintenance and bulk-ingest failures emit a categorical warning once per
+failure transition in the shared process coordinator. Repeated status reads and
+foreground notifications do not log warnings. Committed successful clustering,
+including empty output, clears that process failure. A borrowed savepoint release
+does not prove the caller's outer commit and preserves prior process failures
+through rollback. There is no outer-commit callback; a subsequent committed
+successful maintenance pass clears the retained evidence. A process failure is not a durable
+cross-process diagnostic; persisted scheduler outcomes remain independently
+visible. The optional clustering extra, eight persisted layers, nine manual
+result keys, builder algorithms and preference stage are unchanged.