Warn callers when logs MCP tool returns stale data with no date range specified

pkg/cli/logs_orchestrator.go

@@ -41,6 +41,50 @@ func applyMetricsTurnsToRun(run *WorkflowRun, metrics LogMetrics) {
 	}
 }
 
+// staleLogsWarningThreshold is how old the most recent run in a result set may be,
+// when no explicit start_date/end_date was requested, before we warn the caller
+// that the data may not reflect the truly latest workflow runs.
+//
+// When no date range is supplied, pagination walks backwards through time (paging
+// on run creation date) until it has collected the requested count of runs. In a
+// repository with heavy non-agentic or still-in-progress run volume, this walk can
+// silently settle on an old window without any indication to the caller that more
+// recent runs exist. Passing an explicit start_date/end_date bypasses this ambiguity
+// entirely because it bounds the query server-side, so no warning is needed there.
+const staleLogsWarningThreshold = 48 * time.Hour
+
+// staleLogsWarning returns a warning message when a date-unbounded logs query
+// (no start_date/end_date requested) returns a result set whose most recent run
+// is unexpectedly old. Returns "" when no warning is warranted, i.e. when an
+// explicit date range was requested, there are no runs, or the newest run is
+// recent enough.
+func staleLogsWarning(processedRuns []ProcessedRun, startDate, endDate string) string {
+	if startDate != "" || endDate != "" {
+		// Caller supplied an explicit bound; the result is exactly what was asked for.
+		return ""
+	}
+	if len(processedRuns) == 0 {
+		return ""
+	}
+	var newest time.Time
+	for _, pr := range processedRuns {
+		if pr.Run.CreatedAt.After(newest) {
+			newest = pr.Run.CreatedAt
+		}
+	}
+	if newest.IsZero() {
+		return ""
+	}
+	age := time.Since(newest)
+	if age < staleLogsWarningThreshold {
+		return ""
+	}
+	return fmt.Sprintf(
+		"No start_date/end_date was specified, and the most recent run in this result is %s old (created %s). "+
+			"Retry with an explicit start_date (e.g. \"-1d\") to confirm you are seeing the latest workflow runs.",
+		age.Round(time.Hour), newest.Format(time.RFC3339))
+}
+
 // noRunsMessage returns a human-readable explanation for why zero workflow runs
 // were returned.  It inspects the startDate filter and the timeoutReached flag
 // so callers receive actionable guidance instead of a silent empty result.
@@ -183,5 +227,7 @@ func DownloadWorkflowLogs(ctx context.Context, opts LogsDownloadOptions) error {
 		continuation:   continuation,
 		verbose:        opts.Verbose,
 		artifactFilter: runtime.artifactFilter,
+		startDate:      opts.StartDate,
+		endDate:        opts.EndDate,
 	})
 }

pkg/cli/logs_orchestrator_render.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"github.com/github/gh-aw/pkg/constants"
 )
@@ -29,10 +30,21 @@ func renderLogsOutput(processedRuns []ProcessedRun, opts renderLogsOutputOptions
 	logsOrchestratorLog.Printf("Building logs data from %d processed runs (continuation=%t)", len(processedRuns), opts.continuation != nil)
 	logsData := buildLogsData(processedRuns, opts.outputDir, opts.continuation)
 
+	// When no explicit start_date/end_date was requested and the newest run in the
+	// result is unexpectedly old, warn the caller so stale data is never served
+	// silently (see issue: logs MCP tool returns stale data without date params).
+	var hints []string
+	if warning := staleLogsWarning(processedRuns, opts.startDate, opts.endDate); warning != "" {
+		hints = append(hints, warning)
+	}
+
 	// When only the usage artifact was downloaded, add a hint so consumers know how
 	// to fetch additional artifact sets (agent logs, firewall data, etc.).
 	if isUsageOnlyArtifactFilter(opts.artifactFilter) {
-		logsData.Message = usageOnlyArtifactHintMessage()
+		hints = append(hints, usageOnlyArtifactHintMessage())
+	}
+	if len(hints) > 0 {
+		logsData.Message = strings.Join(hints, " ")
 	}
 
 	// Write summary file if requested (default behavior unless disabled with empty string)

pkg/cli/logs_orchestrator_types.go

@@ -89,4 +89,6 @@ type renderLogsOutputOptions struct {
 	continuation   *ContinuationData
 	verbose        bool
 	artifactFilter []string
+	startDate      string
+	endDate        string
 }

pkg/cli/logs_orchestrator_unit_test.go

@@ -368,3 +368,43 @@ func TestCollectProcessedWorkflowRunsAccumulatesBatches(t *testing.T) {
 	assert.Equal(t, int64(1), runs[0].Run.DatabaseID)
 	assert.Equal(t, int64(3), runs[2].Run.DatabaseID)
 }
+
+// TestStaleLogsWarning verifies that a warning is only emitted when no explicit
+// start_date/end_date was requested and the newest run in the result set is older
+// than the staleness threshold. This guards against the "logs" tool silently
+// serving stale data without any indication when called with only a count.
+func TestStaleLogsWarning(t *testing.T) {
+	t.Run("no warning when start date explicitly provided", func(t *testing.T) {
+		runs := []ProcessedRun{{Run: WorkflowRun{CreatedAt: time.Now().Add(-30 * 24 * time.Hour)}}}
+		assert.Empty(t, staleLogsWarning(runs, "-1d", ""))
+	})
+
+	t.Run("no warning when end date explicitly provided", func(t *testing.T) {
+		runs := []ProcessedRun{{Run: WorkflowRun{CreatedAt: time.Now().Add(-30 * 24 * time.Hour)}}}
+		assert.Empty(t, staleLogsWarning(runs, "", "2024-01-01"))
+	})
+
+	t.Run("no warning when no runs", func(t *testing.T) {
+		assert.Empty(t, staleLogsWarning(nil, "", ""))
+	})
+
+	t.Run("no warning when newest run is recent", func(t *testing.T) {
+		runs := []ProcessedRun{
+			{Run: WorkflowRun{CreatedAt: time.Now().Add(-1 * time.Hour)}},
+			{Run: WorkflowRun{CreatedAt: time.Now().Add(-40 * 24 * time.Hour)}},
+		}
+		assert.Empty(t, staleLogsWarning(runs, "", ""))
+	})
+
+	t.Run("warns when no dates given and newest run is old", func(t *testing.T) {
+		oldest := time.Now().Add(-11 * 24 * time.Hour)
+		runs := []ProcessedRun{
+			{Run: WorkflowRun{CreatedAt: oldest}},
+			{Run: WorkflowRun{CreatedAt: oldest.Add(-time.Hour)}},
+		}
+		warning := staleLogsWarning(runs, "", "")
+		require.NotEmpty(t, warning)
+		assert.Contains(t, warning, "No start_date/end_date was specified")
+		assert.Contains(t, warning, "start_date")
+	})
+}

pkg/cli/mcp_logs_guardrail.go

@@ -51,6 +51,18 @@ func extractLogsContinuation(outputStr string) *ContinuationData {
 	return parsed.Continuation
 }
 
+// extractLogsMessage returns the top-level "message" field embedded in the logs
+// JSON output (e.g. a stale-data warning), or "" when absent or unparseable.
+func extractLogsMessage(outputStr string) string {
+	var parsed struct {
+		Message string `json:"message"`
+	}
+	if err := json.Unmarshal([]byte(outputStr), &parsed); err != nil {
+		return ""
+	}
+	return parsed.Message
+}
+
 // buildLogsFileResponse writes the logs JSON output to a content-addressed cache
 // file and returns a JSON response containing the file path.
 // The file is named by the SHA256 hash of its content so that identical results
@@ -142,6 +154,16 @@ func buildLogsFileResponse(outputStr string) string {
 		response.Continuation = continuation
 		response.Message = fmt.Sprintf("PARTIAL RESULTS: the download stopped before all matching runs were collected. %s Partial logs data has been written to '%s'. Use the file_path to read the collected data and the continuation parameters to fetch the remaining logs.", continuation.Message, filePath)
 	}
+	// Surface any top-level warning (e.g. stale-data warning when no date range was
+	// requested) directly in the tool response so callers see it without having to
+	// open the file.
+	if warning := extractLogsMessage(outputStr); warning != "" {
+		if response.Message == "" {
+			response.Message = "WARNING: " + warning
+		} else {
+			response.Message = fmt.Sprintf("%s WARNING: %s", response.Message, warning)
+		}
+	}
 
 	responseJSON, err := json.MarshalIndent(response, "", "  ")
 	if err != nil {

pkg/cli/mcp_logs_guardrail_test.go

@@ -207,3 +207,24 @@ func TestBuildLogsFileResponse_CompleteResultsNotPartial(t *testing.T) {
 	// Cleanup
 	_ = os.Remove(response.FilePath)
 }
+
+func TestBuildLogsFileResponse_SurfacesStaleDataWarning(t *testing.T) {
+	output := `{"summary":{"total_runs":1},"runs":[],"message":"No start_date/end_date was specified, and the most recent run in this result is 264h0m0s old."}`
+
+	result := buildLogsFileResponse(output)
+
+	var response MCPLogsGuardrailResponse
+	if err := json.Unmarshal([]byte(result), &response); err != nil {
+		t.Fatalf("Response should be valid JSON: %v", err)
+	}
+
+	if !strings.Contains(response.Message, "WARNING:") {
+		t.Errorf("Message should surface the embedded warning, got %q", response.Message)
+	}
+	if !strings.Contains(response.Message, "No start_date/end_date was specified") {
+		t.Errorf("Message should include the stale-data warning text, got %q", response.Message)
+	}
+
+	// Cleanup
+	_ = os.Remove(response.FilePath)
+}