Lite MCP tools disclose a truncated query-stats window (#4231)

[erikdarlingdata]

Part of #4231.

Why

At "Last 7 days", three Lite MCP tools read raw-only tables (query_stats, procedure_stats, query_store_stats) with no rollup fallback. Lite keeps these tables 30 days by default, but the retention is set per collector and a user can lower it. A new install also has less history than the window asks for. In each case the read can serve far less than the caller asked for, and nothing in the answer says so.

#2364 fixed the same problem in Darling's get_query_store_top. This PR is the Lite half of #4231: the shared floor probe, the three MCP tools, and the matching WPF grids. The Darling half, #4278, is merged. This PR also makes the three tools' descriptions match in both products, the last step #4278 left.

What changes

• One shared floor probe, LocalDataService.GetQueryWindowFloorAsync(QueryWindowRelation, serverId, startUtc, endUtc) in Lite/Services/LocalDataService.QueryWindowFloor.cs. It reads MIN(collection_time) from v_query_stats, v_procedure_stats or v_query_store_stats, bounded on both sides of the window. It reads the v_ view, not the bare table. That view is the hot table plus the parquet archive, so the floor covers archived history too. On a seeded store with 500 hot and 500 archived query_stats rows, the probe took 50 to 92 ms locally.
• get_top_queries_by_cpu, get_top_procedures_by_cpu and get_query_store_top (Lite/Mcp/McpQueryTools.cs) each gain effective_start, effective_hours_back, window_truncated and a truncation_note. Every existing field, default and argument is unchanged. The names and meaning match Darling's. window_truncated describes the window's floor, not a page cut, and top or limit never changes it. The threshold is the existing 90-minute McpQueryTools.TruncationSlack.
• The Top Queries, Top Procedures and Query Store grids get a note above the grid. When the floor cuts the window short, it shows "Showing since" and the effective start. The time goes through ServerTimeHelper.FormatServerTime, like the comparison notes on the same tabs. Each grid refreshes the note on a sub-tab switch, a full refresh and a slicer drag. The Query Store slicer reads the same view as its grid, so it shares that grid's probe.
• The note probes the same UTC window the grid read (commit 0ad7d3d9). The probe compares its bounds straight against UTC collection_time. The first version passed server-local times after a slicer drag and under a custom range. On a server not on UTC, the note then probed a window shifted by the server's offset. It then showed a false "Showing since", or missed a real one. Now the slicer handlers pass the slicer's own e.StartUtc and e.EndUtc. The refresh paths call a new LocalDataService.GetQueriesTabWindowUtc, which makes the same GetTimeRange call the three grid reads make.

One description for each tool, in both products (commits f10d80c3, 4226552e, f6e9f53a)

McpToolGuideTests requires each shared tool's served head (the text before <<GUIDE>>) to be the same bytes in both products. So neither PR can change these heads alone. Once #4278 merged, this branch merged dev and changed them in Lite/Mcp/McpQueryTools.cs and Darling's DarlingMcpDataTools.cs together:

• get_query_store_top: the head said "Darling: window_truncated marks a window floor..." and then "Lite: no such floor; the full requested window is always read." The second line was false once Lite had a floor. Both sentences are now one: "window_truncated marks a window floor, not a page cut — no limit changes it — because stored history can be shorter than asked; effective_start / effective_hours_back give the reach actually served." The head went from 422 to 351 bytes.
• get_top_queries_by_cpu and get_top_procedures_by_cpu: each head gains "window_truncated marks a window floor, not a page cut; effective_start / effective_hours_back give the reach actually served." The heads went from 474 to 600 bytes and from 406 to 532. Both stay under the 620-character limit.
• Lite's two CPU tools now end their tails with the CPU topic, as Darling's do. The joins in all four tails had two spaces before the window clause and none after it. Each join now has one space.
• The merge dropped the note this branch had put in get_query_store_top's tail about the stale head line.

Tests that pinned the old text changed with it:

• McpPayloadContractCensusTests: the exception MCP top-queries/top-procedures disclose a shortened raw-tier window (#4231) #4278 added for the two CPU tools is gone. Every Darling window-floor tool now checks its head for "window_truncated" and "not a page cut".
• McpToolGuideHeads.CollectionLog.cs, in both test projects: the test that pinned "Darling: window_truncated" and "Lite: no such floor" now checks the shared head and that neither old line is served.
• McpToolGuideHeads.Data.cs, in both: guardrail rows for the two CPU tools' new sentence. Lite's CPU-topic test is back to Assert.EndsWith.
• The tools/list budget, in both: the three tools' lines in DarlingMcpDataTools.txt and McpQueryTools.txt. TotalCeilingBytes goes from 174,373 to 174,554 in Darling and from 92,041 to 92,222 in Lite. Both grew by the same 181 bytes.

Found, not fixed here

The Queries tab's comparison reads, beside the new note, have the same time-basis bug, and it is older than this PR. After a slicer drag or under a custom range, they read a window shifted by the server's UTC offset. That is #4284. Moving them onto UTC also means moving the comparison's own baseline range, so it gets its own change.

Left for #4231

Stage 3: routing the top-N reads to the hourly rollups, after #4186 merges.

Tests

In Lite.Tests/QueryWindowTruncationTests.cs, with its own DuckDbInitializer so a test controls the archive folder:

• Each of the three tools reports window_truncated: true and the seeded floor as effective_start when the raw table starts after the window's start.
• A floor 60 minutes after the start, inside the 90-minute slack, gives window_truncated: false and a null truncation_note.
• The probe finds the archived parquet floor, not only the hot table's, and is timed.
• QueriesTabGridReads_RouteThroughSharedWindowFloorHelper checks the source. The probe has one call site, and every grid and slicer path calls the shared note helper. No ServerTab*.cs file writes its own MIN(collection_time) query.
• Two tests check the note's text and visibility, truncated and not, through ServerTab.SetWindowTruncatedBanner on an STA thread.
• Three tests from commit 0ad7d3d9, at a -240 minute offset: one pins GetQueriesTabWindowUtc under a custom range. One checks that a slicer's UTC range matches the window the grid read. One scans the source so that every note call takes UTC bounds. With the old slicer and refresh files put back, that source test failed. With the fix restored, it passed.

Runs, on f6e9f53a:

• dotnet build of Lite.Tests and Darling.Tests: 0 warnings, 0 errors.
• Darling classes McpPayloadContractCensusTests, McpToolGuideTests, McpToolGuideHeadsDataTests, McpToolGuideHeadsCollectionLogTests and McpToolsListBudgetTests: 89 of 89 passed.
• Lite classes McpToolGuideTests, McpToolGuideHeadsDataTests, McpToolGuideHeadsCollectionLogTests, McpToolsListBudgetTests and QueryWindowTruncationTests: 31 of 31 passed.
• Full Darling.Tests, once: 14,003 tests, 0 failed, 740 skipped, 1 not run. The skips are live classes. No PostgreSQL rig ran.
• Full Lite.Tests, once: 5,383 tests, 0 failed.
• GitHub Actions CI on f6e9f53a: build, Darling PostgreSQL tests and Lite tests all pass.

CHANGELOG entry

SECTION: Fixed
ENTRY:

• Lite says when a query window was cut short ([Lite MCP tools disclose a truncated query-stats window (#4231) #4279]) - Three MCP tools read raw tables with no rollup fallback: get_top_queries_by_cpu, get_top_procedures_by_cpu and get_query_store_top. Lite keeps those tables 30 days by default, and a user can lower that per collector. So a long window was read from much less history, with nothing to say so. Each tool now returns effective_start, effective_hours_back and window_truncated, plus a truncation_note when the window was cut short. The three grids show "Showing since" and the effective start above the grid in the same case, after a time-range change or a slicer drag. On Lite and Darling alike, each tool's short description now explains window_truncated. The false line that said Lite always reads the full window is gone.
  REF:
  [Lite MCP tools disclose a truncated query-stats window (#4231) #4279]: Lite MCP tools disclose a truncated query-stats window (#4231) #4279

🤖 Generated with Claude Code

https://claude.ai/code/session_01FVjn4PBJN71NQXdFo6ZxNQ

[erikdarlingdata]

Fix: the banner now probes the same UTC window the grid read

Confirmed the defect as described. LocalDataService.GetQueryWindowFloorAsync (Lite/Services/LocalDataService.QueryWindowFloor.cs) compares startUtc/endUtc straight against UTC collection_time, with no offset conversion of its own. Two paths fed it server-local times instead:

1. Lite/Controls/ServerTab.Slicers.cs (all three OnXSlicerChanged handlers): passed fromServer/toServer (ServerTimeHelper.ToServerTime(e.StartUtc)) to RefreshWindowTruncatedBannerAsync. Fixed to pass e.StartUtc, e.EndUtc directly — no conversion needed, those are already UTC.
2. Lite/Controls/ServerTab.Refresh.cs (6 call sites: 3 in the sub-tab switch, 3 in the full refresh): cStart/cEnd(2/3) are server-local under a custom range (GetCurrentWindow converts the pickers with ServerTimeHelper.UtcOffsetMinutes via DisplayTimeToServerTime), UTC otherwise. Rather than reuse those locals for the banner (which would also change what the still-untouched comparison calls receive — see below), each site now computes a dedicated bannerStart/bannerEnd via a new helper.

New helper: LocalDataService.GetQueriesTabWindowUtc(hoursBack, fromDate, toDate, utcOffsetMinutes) (Lite/Services/LocalDataService.cs, right after GetTimeRange), internal static, thin wrapper over the same private GetTimeRange that GetTopQueriesByCpuAsync/GetTopProceduresByCpuAsync/GetQueryStoreTopQueriesAsync already call for their own window. Every Refresh.cs call site passes ServerTimeHelper.UtcOffsetMinutes — the same offset GetCurrentWindow used to produce fromDate/toDate in the first place (confirmed the three grid reads always use SelectedServerTabUtcOffsetMinutes == ServerTimeHelper.UtcOffsetMinutes for their window regardless of what their own utcOffsetMinutes parameter carries — that parameter binds a SQL display column, not the WHERE window), so the round trip can't silently pick up a different offset than the grid used.

Also renamed RefreshWindowTruncatedBannerAsync's parameters start/end → startUtc/endUtc and added a doc paragraph spelling out the UTC requirement, since that was the exact ambiguity that let the bug in.

Comparison calls: left untouched, with the reason

Checked GetComparisonRange() (Lite/Controls/ServerTab.Comparison.cs:59, basis decided at lines 66-77). It is not uniformly UTC: it recomputes its own fromDate/toDate from the pickers independently, converting to server-local via DisplayTimeToServerTime under a custom range (same as the bug just fixed) and staying UTC (DateTime.UtcNow-based) otherwise — a mixed, condition-matched basis, not a fixed one.

RefreshQueryStatsComparisonAsync(cStart, cEnd) and its two twins (same lines as the banner calls, both in ServerTab.Slicers.cs and ServerTab.Refresh.cs) forward cStart/cEnd straight into GetQueryStatsComparisonAsync/twins, which also compare directly against UTC collection_time with no conversion — so yes, they share the same bug shape today, symmetrically: under a custom range, both the "current" argument and GetComparisonRange()'s baseline are consistently server-local (wrong vs. true UTC storage, but shifted by the same amount as each other).

Per the brief's ruling, I did not touch these. Rerouting only the "current" side onto the new UTC helper while GetComparisonRange() stays conditionally server-local would desync current vs. baseline in the custom-range case specifically — a new, different-shaped bug, worse than the existing symmetric one. Fixing it properly means rerouting GetComparisonRange() itself onto the same UTC helper (both current and baseline), which touches every comparison consumer and is a separate design decision, not a mechanical parity copy. Flagging for a follow-up rather than filing an issue myself, since the brief scoped this lane to the banner only.

Tests (Lite.Tests/QueryWindowTruncationTests.cs)

Three new tests, offset -240 minutes (UTC-4) throughout:

• GetQueriesTabWindowUtc_CustomRange_ConvertsServerLocalPickersBackToUtc — pure arithmetic pin on the new helper.
• SlicerBannerWindow_MatchesTheGridsUtcWindow_ForANonUtcServer — pins that e.StartUtc/e.EndUtc (now fed to the banner untouched) equals what the grid's own server-local round trip resolves to.
• WindowTruncatedBannerCallSites_TakeUtcBounds_NotServerLocalOnes — source-scan revert-proof: all 3 slicer banner calls pass e.StartUtc, e.EndUtc; all 6 Refresh.cs banner calls pass bannerStart(2/3)/bannerEnd(2/3), and none pass the raw cStart/cStart2/cStart3 that still feed the (deliberately unchanged) comparison calls.

Revert-proof, actually run: committed the fix, then git checkout 3b8d9e12 -- Lite/Controls/ServerTab.Slicers.cs Lite/Controls/ServerTab.Refresh.cs, rebuilt, ran the class: Total: 11, Failed: 1 — only WindowTruncatedBannerCallSites_TakeUtcBounds_NotServerLocalOnes failed (the two pure-arithmetic tests still passed, as expected, since they pin the helper directly rather than the call sites). Restored the fix with git checkout HEAD -- <both files>, rebuilt clean, all pass again.

Test runs

• QueryWindowTruncationTests alone: 11/11 pass.
• QueryWindowTruncationTests + ServerTabCapabilityPinTests + AlertBadgeServerOffsetTests + AutoRefreshMappingTests + QuerySlicerMetricMapTests: 17/17 pass.
• Merged origin/dev: one conflict, in Darling/Darling.Tests/McpPayloadContractCensusTests.cs (CutNoteKeys) — dev independently added a findings_truncated_note entry (MCP read tools have no default response-size budget: at default arguments 12 tools return >50 KB and 3 return >100 KB for one server, more than an agent client's per-result cap #4198) to the same tuple array this branch's truncation_note entry lives in. Pre-existing divergence, unrelated to this fix. Resolved by keeping both: the full truncation_note (with McpQueryTools.cs and the Lite/At "Last 7 days" the WPF Queries grids silently show ~4 days: Top Queries, Top Procedures and Query Store read raw tables dropped at 4 days, with no floor disclosure (get_query_store_top got one in #2364; the viewer and the query-stats MCP tools didn't) #4231 sentence) plus dev's new findings_truncated_note entry.
• Full Lite suite after the merge, once: Total: 5382, Errors: 0, Failed: 0, Skipped: 0, Not Run: 0.
• Build: dotnet build Lite.Tests/Lite.Tests.csproj -c Debug — 0 Warning(s), 0 Error(s).

Pushed to fix/4231-lite-window-disclosure (now at 3f92c92, includes the dev merge commit). Left the PR as a draft, did not touch its body, did not ready it.

[erikdarlingdata]

Finishing-step lane report (merge dev + shared window-floor head). Context ran out before the full test pass, so this is a checkpoint, not a finish. Everything below is pushed to fix/4231-lite-window-disclosure (now at 4226552e).

1. Merge of origin/dev (commit f10d80c3)

One conflict, in Lite/Mcp/McpQueryTools.cs's get_query_store_top Description(...). Resolved by:

• keeping dev's QueryTextPreviewLength = 400 constant and its doc comment,
• keeping this branch's module_name-miss hint clause ("a module_name miss also carries the window read... as hints."),
• appending dev's query_text-preview sentence right after it, matching the order Darling's dev twin already uses,
• dropping the #4231 WIRE CHANGE: that head sentence is shared... paragraph (step 2 makes it false).

Darling/Darling.Tests/McpPayloadContractCensusTests.cs auto-merged cleanly. Confirmed both PRs' rows survived in WindowFloorBlocks (DarlingMcpDataTools.cs initializer:4, McpQueryTools.cs envelope:1/initializer:4) and WindowFloorTools (both files carry get_query_store_top, get_top_procedures_by_cpu, get_top_queries_by_cpu).

2. The three shared heads (commit 4226552e)

Verified byte-identical between Lite/Mcp/McpQueryTools.cs and Darling/PerformanceMonitor.Darling.Service/Mcp/DarlingMcpDataTools.cs by extracting and diffing both head strings in a script.

• get_query_store_top -- 320 characters:
  "Cost-ranked top Query Store queries (heaviest first), not time-ordered. Requires Query Store enabled on target databases. window_truncated marks a window floor, not a page cut -- no limit changes it -- because stored history can be shorter than asked; effective_start / effective_hours_back give the reach actually served."
• get_top_queries_by_cpu -- 569 characters (was 443; +126 for the appended sentence plus one joining space).
• get_top_procedures_by_cpu -- 501 characters (was 375; +126).

Both CPU-tool heads gained, before <<GUIDE>>: "window_truncated marks a window floor, not a page cut; effective_start / effective_hours_back give the reach actually served." Both stay well under the 620-character cap, so no shortening was needed.

Tail order/spacing (both products, both CPU tools): Lite's tail order now matches Darling's, McpHelpers.WindowTruncatedDescription before McpToolGuideTopics.CpuTimeExtremesAndAttribution. Fixed the join spacing at both seams in all four occurrences: trimmed the base string literal's own trailing space before " + McpHelpers.WindowTruncatedDescription (was a double space, e.g. "appears. window_truncated"), and inserted an explicit " " + between WindowTruncatedDescription and CpuTimeExtremesAndAttribution (was zero spaces, e.g. "truncated.min/max_cpu_ms"). Confirmed by script: no double spaces and no missing-space joins remain in any of the six edited description lines.

3. Test changes (commit 4226552e)

• Lite.Tests/McpToolGuideHeads.Data.cs: CpuTimeExtremesTopic_RidesOnBothTopByCpuTools back to Assert.EndsWith (was Assert.Contains), stale "checks presence, not position" doc comment replaced.
• Darling/Darling.Tests/McpPayloadContractCensusTests.cs: removed the get_top_queries_by_cpu/get_top_procedures_by_cpu carve-out branch in EveryWindowFloorTool_CarriesTheSharedClause_AndNoOtherToolDoes; every Darling window-floor tool now asserts on the head unconditionally.
• Darling/Darling.Tests/McpToolGuideHeads.CollectionLog.cs and Lite.Tests/McpToolGuideHeads.CollectionLog.cs: dropped the ("get_query_store_top", "Lite: no such floor") guardrail row from each; renamed QueryStoreTop_WindowFloorClause_IsScopedToDarlingInTheHead to QueryStoreTop_WindowFloorClause_IsSharedAcrossBothSkusInTheHead in both, asserting the served head contains "window_truncated" and "not a page cut" and contains neither "Darling: window_truncated" nor "Lite: no such floor". Lite's copy also dropped the old "that head sentence is shared" assertion and its now-false summary comment.
• Darling/Darling.Tests/McpToolGuideHeads.Data.cs and Lite.Tests/McpToolGuideHeads.Data.cs: added ("window_truncated") / ("not a page cut") guardrail rows for both CPU tools.
• Grepped both products and both test projects for Lite: no such floor, Darling: window_truncated, WIRE CHANGE: that head, raw retention can be shorter than asked, and #4231 WIRE CHANGE / that head sentence is shared: no stray pins remain outside the intentional Assert.DoesNotContain lines just added.

Verified

• dotnet build Lite.Tests/Lite.Tests.csproj -c Debug: Build succeeded, 0 Warning(s), 0 Error(s).

Not done -- ran out of context before finishing

I hit the context watchdog's hard limit mid-task and had to checkpoint rather than finish. Still open:

• dotnet build Darling/Darling.Tests/Darling.Tests.csproj -c Debug -- not run since the last edits (the earlier merge-only state built fine, but the head/tail edits in DarlingMcpDataTools.cs and the three Darling test files are unverified by a compiler).
• Re-measure McpToolsListBudgetTests.TotalCeilingBytes in both test projects and update Darling/Darling.Tests/McpToolsListBudget/DarlingMcpDataTools.txt and Lite.Tests/McpToolsListBudget/McpQueryTools.txt with a new change-log line for At "Last 7 days" the WPF Queries grids silently show ~4 days: Top Queries, Top Procedures and Query Store read raw tables dropped at 4 days, with no floor disclosure (get_query_store_top got one in #2364; the viewer and the query-stats MCP tools didn't) #4231's head growth. Both CPU-tool heads grew by 126 bytes each, in both products, so these budgets almost certainly need to move.
• Targeted runs of McpPayloadContractCensusTests, McpToolGuideTests, McpToolGuideHeadsDataTests, the McpToolGuideHeads CollectionLog class, McpToolsListBudgetTests, QueryWindowTruncationTests.
• Full suite, once, in both Lite.Tests.exe and Darling.Tests.exe.

Recommend re-queuing the budget re-measurement plus both full suites as the next step; the text/merge work above should be stable since it was built and cross-checked script-side, but it has not been proven against the actual test pins yet.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TszxYhJJbTEh4LrZ56NYo3

[erikdarlingdata]

Budgets and test runs finished (code was already done)

Branch fix/4231-lite-window-disclosure, base commit 4226552 (the previous lane's head-byte-identical fix),
new commit f6e9f53a pushed on top. No product code changed; only the two tools/list budget pins and their
change logs.

Builds

• dotnet build Darling/Darling.Tests/Darling.Tests.csproj -c Debug: Build succeeded, 0 Warning(s), 0 Error(s).
• dotnet build Lite.Tests/Lite.Tests.csproj -c Debug: Build succeeded, 0 Warning(s), 0 Error(s).

Measured budgets (old -> new, both projects agree exactly)

Tool	old bytes	new bytes	delta
get_query_store_top	422	351	-71
get_top_procedures_by_cpu	406	532	+126
get_top_queries_by_cpu	474	600	+126

Net per-tool delta is +181, and it matches the total delta on both sides exactly, confirming no other tool moved.

• Darling/Darling.Tests/McpToolsListBudget/DarlingMcpDataTools.txt: the three tool ... lines updated to 351/532/600.
• Lite.Tests/McpToolsListBudget/McpQueryTools.txt: same three lines updated to 351/532/600.
• Darling.Tests.McpToolsListBudgetTests.TotalCeilingBytes: 174,373 -> 174,554.
• Lite.Tests.McpToolsListBudgetTests.TotalCeilingBytes: 92,041 -> 92,222.
• Added one change-log comment block above each TotalCeilingBytes recording the Lite MCP tools disclose a truncated query-stats window (#4231) #4279 deltas; every prior change-log line kept as-is.

Targeted classes (both projects, all green)

Darling.Tests (single run, 89/89 pass, then split to confirm no class silently matched zero tests):

• McpPayloadContractCensusTests: 68/68
• McpToolGuideTests: 10/10
• McpToolGuideHeadsDataTests: 3/3
• McpToolGuideHeadsCollectionLogTests (the McpToolGuideHeads CollectionLog class): 3/3
• McpToolsListBudgetTests: 5/5

Lite.Tests (single run, 31/31 pass, same per-class confirmation): Lite has no McpPayloadContractCensusTests
class (Darling-only; Lite's nearest analog is the unrelated McpPageContractTests), so it's skipped here per the brief.

• McpToolGuideTests: 8/8
• McpToolGuideHeadsDataTests: 3/3
• McpToolGuideHeadsCollectionLogTests: 4/4
• McpToolsListBudgetTests: 5/5
• QueryWindowTruncationTests: 11/11

Full suites (run once each, foreground, no merge from origin/dev since the brief pins HEAD and supplies its own staleness rule)

• Darling.Tests: Total 14003, Errors 0, Failed 0, Skipped 740, Not Run 1, 121.8s. All 740 skips are the
  usual PG-runtime-gated tests (DARLING_TEST_PGRUNTIME unset per this brief - no rig used). The lone "Not Run: 1"
  has no [FAIL]/[ERROR] line anywhere in the log; it's a benign MTP counter artifact, not a failure. No
  PostgreSQL rig was started, so the CI flake: PgTarget anomaly/blocking worst-tile assertions fail on first attempts unrelated to the change #4274 flake classes (PgTargetAnomalyTests, PgTargetBlockingTests) did not
  run at all here.
• Lite.Tests: Total 5383, Errors 0, Failed 0, Skipped 0, Not Run 0, 291.9s.

One deviation from the brief, flagged for the coordinator

The brief's "Commit trailers" section supplied Claude-Session: https://claude.ai/code/session_01TszxYhJJbTEh4LrZ56NYo3,
but that session URL is already on commit 4226552e (the prior lane's own commit already on this branch before I
started) - reusing it on my commit would misattribute it. My own session's attribution reminder gives a different
URL, so I used that instead on commit f6e9f53a:
Claude-Session: https://claude.ai/code/session_01FVjn4PBJN71NQXdFo6ZxNQ. Worth a glance in case the brief's copy
was meant to be a fresh URL for this dispatch rather than a paste of the prior one.

Nothing deferred; no new issues filed. dev's latest CI wasn't consulted since both full suites came back
fully clean (0 failures) - no failure existed to arbitrate.