Repository navigation
Module observability: explain visibility, provenance, collection timings and cache state #365
Description
Goal
Make native Context Engine module behavior understandable and measurable, taking inspiration from Starship's explain / timings while reusing NMSh's /modules, detail UI, /doctor, Status Strip and capability metadata.
UX
For a chosen module, answer:
- What does it show? Where is it routed, and why is it visible/hidden/compacted?
- Which trusted capability/source produced the value, and what evidence is available without leaking secrets?
- Is this value fresh, cached, stale, refreshing, timed out, unavailable or unknown?
- When demand occurs, how long did collection take? Are expensive collectors skipped when hidden?
- Was a value declined by privacy, conditional visibility, absent tool/config, stale context or bounded timeout?
Prefer a compact detail/diagnostic view rather than a global permanent performance panel. On-demand breakdown should not itself trigger unrelated expensive collection. Numbers should distinguish measured collector time from wall-clock scheduling/queue delay; avoid fake zero measurements.
Safety/performance
Observe the existing scheduler, never add probes in render or when hidden. Only expose safe summaries, not tokens, environment secret values, unredacted config paths or arbitrary user data. Cap history/metrics memory; no telemetry upload.
Acceptance
- Source-backed per-module status/provenance/visibility explanations.
- Explicit timing/caching results, including skipped and unavailable cases.
- Works in Main Prompt, Right Context, Rail and Strip as applicable, narrow/NO_COLOR/Safe modes.
- Unit and integration tests for invisible demand, timeouts, stale/cancelled work and sensitive facts.
- Documentation and regression benchmarks. Avoid a competing module runtime.
Parent: #305; overlap with #321 Context Engine performance QA must be coordinated, not duplicated.
Activity
raiseCatError commentedon Oct 10, 2026
On
feature/output-references(#368): /modules detail now shows a Why sentence, the measured collection time per capability (alongside the existing freshness, evidence, error and 'Reads' rows), and /doctor reports prompt-data health from the engine's own counters. No extra collection or resident monitor. Not done: a per-module cache-key/TTL row, a slowest-modules list, and Starship-styleexplaintext export.raiseCatError commentedon Oct 11, 2026
Continued the existing #368 implementation; no new native runtime catalog or duplicate collector was added.
Local additive workflow candidate: 5e45e87. Diagnostic corrections 1a372fb / 06433f1 add source/capability trust and scope, freshness TTL, invalidation/demand-refresh policy, retained cache availability, and measured collector wall time excluding queue delay. No fake zero duration is shown. Timeout/failure messages remain generic and do not expose raw exception paths or secret values.
Module details now reuse the renderer's existing condition predicate against resolved context. An enabled setting no longer claims proven visibility when the current condition fails. Uncollected, stale, pending, absent and failed states remain distinct. Opening details or /doctor reads snapshots/policy and does not request unrelated expensive collectors.
Focused diagnostics/engine/module-manager regressions passed. Final full canonical and exact-head Actions remain pending. Physical Main/Right/Rail/Strip, narrow/NO_COLOR/Safe QA remains outstanding.
Remaining acceptance gap: exact last-frame width compaction/drop decisions are not recorded. Current details report routing, surface availability, conditions and priority, but must not be presented as an exact per-frame visibility trace. That gap is documented in the workflow ledger and needs reconciliation with the frozen workspace/screen geometry integration. No claim that all #365 acceptance is complete.
raiseCatError commentedon Oct 11, 2026
Module detail viewport correction is implemented in 52db115, propagated candidate currently 1007f71 on fix/workflow-maple.
At 50 columns / 24 rows, Source, Cache, Timing and Why could extend below the visible detail panel with no scrolling action. Details now honor the panel height and provide arrows/PageUp/PageDown. View bounds remain ephemeral; reading/resizing changes neither settings nor collector demand.
Direct source typecheck, 25 focused tests across moduleManagerUx, moduleExplain, moduleManager and the new moduleDiagnosticsLive fixture, and verify:fast passed. The live fixture uses NO_COLOR and Safe glyphs, resizes the real PTY and verifies each section is reachable before returning to the shell.
Full canonical verification and exact-head CI remain pending. Exact last-frame module width-compaction decisions remain a documented integration follow-up; this correction does not claim all #365 acceptance complete. Physical terminal QA is still required.