fix(cli): align empty DM window hints with follow-up queries (#239)

Align empty DM date-window diagnostics with the follow-up command's actual row set. Restrict counts to catalogued conversations only when all date bounds are removed; retain uncatalogued message counts when another bound remains. Preserve archive data, stdout/JSON contracts and retrieval behavior.

Verified the original failure and corrected native CLI in an isolated Linux fixture, including one-bound, remaining-bound and both-bound cases. Focused race tests, full exact-head CI and independent review pass.

Co-authored-by: Robert Navarro <crshman@gmail.com>

Author: rnavarro

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Keep empty DM date-window hints consistent with the suggested follow-up command, excluding uncatalogued conversations only when removing the final date filter. Thanks @rnavarro.
+
 ## 0.15.4 - 2026-09-20
 
 - Update Crawlkit to v0.16.4 so normal snapshot updates accept equivalent attachment schemas with reordered columns, preserving locally retained history without requiring forced replacement.

docs/commands/dms.md

@@ -37,6 +37,8 @@ discrawl dms --with Molty --search "invoice"
 
 `dms` reads the same tables as [`messages`](messages.html) and [`search`](search.html) and prints the same stderr notes when a run returns nothing: the window notes for a `--hours`/`--days`/`--since`/`--before` listing, and the multi-term note for `--search`. They go to stderr, `--json` suppresses them, and stdout and the exit code are unchanged.
 
+When a window note recommends removing all date filters, it counts only messages in catalogued conversations that the default `dms` listing can show. Uncatalogued DMs remain available through message queries, including `dms` with a matching date window. If the recommendation leaves another date filter in place, the note continues to count those messages.
+
 A run that sets `--with` gets no note. `--with` names a person and the query matches it against channel id and channel name alike, which the counts behind a note cannot reproduce, so a `--with` run stays silent rather than reporting numbers taken from every conversation.
 
 ## See also

internal/cli/zero_result_notes.go

@@ -18,10 +18,11 @@ const maxZeroResultTermProbes = 4
 // run with, so every note below is derived from the same row set the query
 // looked at rather than a re-modelled one.
 type zeroResultScope struct {
-	channelID      string
-	guildIDs       []string
-	includeEmpty   bool
-	includeDeleted bool
+	channelID              string
+	guildIDs               []string
+	includeEmpty           bool
+	includeDeleted         bool
+	cataloguedChannelsOnly bool
 }
 
 // listMessagesScope models a store.ListMessages query. ListMessages carries no
@@ -60,10 +61,11 @@ func (r *runtime) newZeroResultScope(channel string, guildIDs []string, includeE
 
 func (s zeroResultScope) storeOptions() store.MessageScopeOptions {
 	return store.MessageScopeOptions{
-		ChannelID:      s.channelID,
-		GuildIDs:       s.guildIDs,
-		IncludeEmpty:   s.includeEmpty,
-		IncludeDeleted: s.includeDeleted,
+		ChannelID:              s.channelID,
+		GuildIDs:               s.guildIDs,
+		IncludeEmpty:           s.includeEmpty,
+		IncludeDeleted:         s.includeDeleted,
+		CataloguedChannelsOnly: s.cataloguedChannelsOnly,
 	}
 }
 
@@ -151,6 +153,8 @@ func (r *runtime) explainEmptySearch(opts store.SearchOptions, mode string) {
 // explainEmptyDirectMessageList explains an empty `dms` listing. Only the
 // window notes can apply: `dms` has no --channel, so there is no concrete
 // channel for the content notes to describe.
+//
+// Removing the last date filter switches to catalogued conversation summaries.
 func (r *runtime) explainEmptyDirectMessageList(with string, includeEmpty bool, window zeroResultWindow) {
 	if r.json || strings.TrimSpace(with) != "" {
 		return
@@ -159,7 +163,19 @@ func (r *runtime) explainEmptyDirectMessageList(with string, includeEmpty bool,
 	if !ok {
 		return
 	}
-	r.explainEmptyMessages(scope, window)
+	stats, ok := r.zeroResultStats(scope)
+	if !ok {
+		return
+	}
+	sinceExcludes, beforeExcludes := window.excludedBounds(stats)
+	if (window.since.IsZero() || sinceExcludes) && (window.before.IsZero() || beforeExcludes) {
+		scope.cataloguedChannelsOnly = true
+		stats, ok = r.zeroResultStats(scope)
+		if !ok {
+			return
+		}
+	}
+	r.explainEmptyDateWindow(scope, window, stats)
 }
 
 // explainEmptyDirectMessageSearch explains an empty `dms --search`. That path
@@ -244,6 +260,12 @@ func (r *runtime) lookupChannel(channelID string) (store.ChannelRow, bool) {
 	return row, true
 }
 
+func (window zeroResultWindow) excludedBounds(stats store.MessageScopeStats) (since, before bool) {
+	since = !window.since.IsZero() && !stats.Newest.IsZero() && stats.Newest.Before(window.since)
+	before = !window.before.IsZero() && !stats.Oldest.IsZero() && !stats.Oldest.Before(window.before) && strings.TrimSpace(window.beforeRaw) != ""
+	return since, before
+}
+
 // explainEmptyDateWindow writes a stderr note when an
 // --hours/--days/--since/--before window looks like the reason the query
 // returned nothing. Each side fires only when every message in scope sits
@@ -254,8 +276,7 @@ func (r *runtime) explainEmptyDateWindow(scope zeroResultScope, window zeroResul
 	if stats.Count == 0 {
 		return
 	}
-	sinceExcludes := !window.since.IsZero() && !stats.Newest.IsZero() && stats.Newest.Before(window.since)
-	beforeExcludes := !window.before.IsZero() && !stats.Oldest.IsZero() && !stats.Oldest.Before(window.before) && strings.TrimSpace(window.beforeRaw) != ""
+	sinceExcludes, beforeExcludes := window.excludedBounds(stats)
 	if !sinceExcludes && !beforeExcludes {
 		return
 	}

internal/cli/zero_result_notes_test.go

@@ -26,6 +26,7 @@ const (
 	zeroResultDeletedChannelID    = "6666666666666666"
 	zeroResultDMChannelID         = "7777777777777777"
 	zeroResultOrphanChannelID     = "8888888888888888"
+	zeroResultOrphanDMChannelID   = "9999999999999999"
 )
 
 func setupZeroResultStore(t *testing.T) (ctx context.Context, cfgPath string) {
@@ -1017,3 +1018,144 @@ func TestExplainEmptyResultsUncataloguedDMDoesNotRecommendEmbedding(t *testing.T
 	require.Contains(t, stderr.String(), "embedding jobs are never created for direct messages")
 	require.NotContains(t, stderr.String(), "--rebuild")
 }
+
+// addUncataloguedDirectMessage stores a direct message whose channel has no
+// channels row, which is what an archive holds after a DM is captured without
+// its conversation ever being catalogued.
+func addUncataloguedDirectMessage(t *testing.T, ctx context.Context, cfgPath string) {
+	t.Helper()
+	cfg, err := config.Load(cfgPath)
+	require.NoError(t, err)
+	s, err := store.Open(ctx, cfg.DBPath)
+	require.NoError(t, err)
+	require.NoError(t, s.UpsertGuild(ctx, store.GuildRecord{ID: store.DirectMessageGuildID, Name: "Direct Messages", RawJSON: `{}`}))
+	require.NoError(t, s.UpsertMessage(ctx, store.MessageRecord{
+		ID:                "m-dm-uncatalogued",
+		GuildID:           store.DirectMessageGuildID,
+		ChannelID:         zeroResultOrphanDMChannelID,
+		ChannelName:       "Bob",
+		AuthorID:          "u3",
+		AuthorName:        "Bob",
+		CreatedAt:         "2020-07-01T00:00:00Z",
+		Content:           "quebec has no channels row",
+		NormalizedContent: "quebec has no channels row",
+		RawJSON:           `{}`,
+	}))
+	require.NoError(t, s.Close())
+}
+
+// `dms --days 1` over an archive holding one catalogued conversation and one
+// direct message with no channels row reported 2 messages in scope and the
+// newest timestamp of the row `dms` cannot print.
+// store.DirectMessageConversations selects from channels and joins messages to
+// it, so the uncatalogued message is in no listing at any window. The count
+// behind the note now matches the listing's own row set.
+func TestExplainEmptyResults_DirectMessageWindowNoteCountsOnlyCataloguedConversations(t *testing.T) {
+	ctx, cfgPath := setupZeroResultStore(t)
+	addUncataloguedDirectMessage(t, ctx, cfgPath)
+
+	var stdout, stderr bytes.Buffer
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "dms", "--days", "1"}, &stdout, &stderr))
+	require.Empty(t, stdout.String())
+	// One conversation, and the newest timestamp is that conversation's, not
+	// the uncatalogued message's 2020-07-01.
+	require.Contains(t, stderr.String(), "note: 1 messages in scope but none within the last 1 days (newest: 2020-03-01T00:00:00Z); try without --days")
+
+	// The command the note recommends lists the conversation it counted.
+	stdout.Reset()
+	stderr.Reset()
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "dms"}, &stdout, &stderr))
+	require.Contains(t, stdout.String(), zeroResultDMChannelID)
+	require.NotContains(t, stdout.String(), zeroResultOrphanDMChannelID)
+	require.Empty(t, stderr.String())
+}
+
+// The same fix from the other side: when every direct message in the archive
+// has no channels row, `dms` returns no conversation at any window, so
+// dropping the window resolves nothing and there is no note to print.
+func TestExplainEmptyResults_DirectMessageWindowNoteSilentWhenNoConversationIsListed(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.toml")
+	cfg := config.Default()
+	cfg.DBPath = filepath.Join(dir, "discrawl.db")
+	require.NoError(t, config.Write(cfgPath, cfg))
+	addUncataloguedDirectMessage(t, ctx, cfgPath)
+
+	var stdout, stderr bytes.Buffer
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "dms", "--days", "1"}, &stdout, &stderr))
+	require.Empty(t, stdout.String())
+	require.Empty(t, stderr.String())
+
+	// Dropping the window, which is what a window note would have recommended,
+	// returns no conversation either. The human listing still prints its column
+	// header, as every table in this CLI does with no rows.
+	stdout.Reset()
+	stderr.Reset()
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "--json", "dms"}, &stdout, &stderr))
+	require.Equal(t, "[]\n", stdout.String())
+	require.Empty(t, stderr.String())
+
+	stdout.Reset()
+	stderr.Reset()
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "dms"}, &stdout, &stderr))
+	require.NotContains(t, stdout.String(), zeroResultOrphanDMChannelID)
+
+	// The message is reachable, just not as a conversation, so the archive is
+	// not simply empty.
+	stdout.Reset()
+	stderr.Reset()
+	require.NoError(t, Run(ctx, []string{
+		"--config", cfgPath, "messages", "--channel", zeroResultOrphanDMChannelID,
+	}, &stdout, &stderr))
+	require.Contains(t, stdout.String(), "quebec has no channels row")
+}
+
+func TestExplainEmptyResults_DirectMessageWindowNoteWithRemainingDateFilter(t *testing.T) {
+	ctx, cfgPath := setupZeroResultStore(t)
+	addUncataloguedDirectMessage(t, ctx, cfgPath)
+	for _, tc := range []struct {
+		name     string
+		args     []string
+		followup []string
+		want     string
+	}{
+		{
+			name: "before remains", args: []string{"--since", "2021-01-01T00:00:00Z", "--before", "2030-01-01T00:00:00Z"},
+			followup: []string{"--before", "2030-01-01T00:00:00Z"}, want: "note: 2 messages in scope but none since 2021-01-01T00:00:00Z (newest: 2020-07-01T00:00:00Z); try without --since",
+		},
+		{
+			name: "since remains", args: []string{"--since", "2019-01-01T00:00:00Z", "--before", "2019-06-01T00:00:00Z"},
+			followup: []string{"--since", "2019-01-01T00:00:00Z"}, want: "note: 2 messages in scope",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			require.NoError(t, Run(ctx, append([]string{"--config", cfgPath, "dms"}, tc.args...), &stdout, &stderr))
+			require.Empty(t, stdout.String())
+			require.Contains(t, stderr.String(), tc.want)
+			stdout.Reset()
+			stderr.Reset()
+			require.NoError(t, Run(ctx, append([]string{"--config", cfgPath, "dms"}, tc.followup...), &stdout, &stderr))
+			require.Contains(t, stdout.String(), "quebec has no channels row")
+			require.Contains(t, stdout.String(), "delta echo in a direct message")
+			require.Empty(t, stderr.String())
+		})
+	}
+}
+
+func TestExplainEmptyResults_DirectMessageWindowNoteDropsBothBounds(t *testing.T) {
+	ctx, cfgPath := setupZeroResultStore(t)
+	addUncataloguedDirectMessage(t, ctx, cfgPath)
+	var stdout, stderr bytes.Buffer
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "dms", "--since", "2021-01-01T00:00:00Z", "--before", "2019-01-01T00:00:00Z"}, &stdout, &stderr))
+	require.Empty(t, stdout.String())
+	require.Contains(t, stderr.String(), "both --since and --before exclude all 1 messages")
+	require.Contains(t, stderr.String(), "try without both --since and --before")
+	stdout.Reset()
+	stderr.Reset()
+	require.NoError(t, Run(ctx, []string{"--config", cfgPath, "dms"}, &stdout, &stderr))
+	require.Contains(t, stdout.String(), zeroResultDMChannelID)
+	require.NotContains(t, stdout.String(), zeroResultOrphanDMChannelID)
+	require.Empty(t, stderr.String())
+}

internal/store/query.go

@@ -87,11 +87,15 @@ func (s *Store) ChannelMessageBounds(ctx context.Context, channelID string) (str
 // SearchMessages filters `deleted_at is null`, ListMessages carries no
 // deleted_at predicate and so returns them. A caller sets it to match the
 // query it is explaining.
+//
+// CataloguedChannelsOnly matches conversation listings, which join messages
+// to channels by both guild and channel ID.
 type MessageScopeOptions struct {
-	ChannelID      string
-	GuildIDs       []string
-	IncludeEmpty   bool
-	IncludeDeleted bool
+	ChannelID              string
+	GuildIDs               []string
+	IncludeEmpty           bool
+	IncludeDeleted         bool
+	CataloguedChannelsOnly bool
 }
 
 // MessageScopeStats summarises the messages allowed by the scope. Count,
@@ -123,11 +127,16 @@ func messageScopeClauses(opts MessageScopeOptions, column func(string) string) (
 			args = append(args, guildID)
 		}
 	}
+	if opts.CataloguedChannelsOnly {
+		// Qualify outer columns so the subquery cannot bind to its own guild_id.
+		clauses = append(clauses, "exists (select 1 from channels cat where cat.id = "+column("channel_id")+
+			" and cat.guild_id = "+column("guild_id")+")")
+	}
 	return strings.Join(clauses, " and "), args
 }
 
 func (s *Store) MessageScopeStats(ctx context.Context, opts MessageScopeOptions) (MessageScopeStats, error) {
-	where, whereArgs := messageScopeClauses(opts, func(name string) string { return name })
+	where, whereArgs := messageScopeClauses(opts, func(name string) string { return "messages." + name })
 	visible := "(? or trim(coalesce(normalized_content, '')) <> '')"
 	args := []any{opts.IncludeEmpty, opts.IncludeEmpty, opts.IncludeEmpty, opts.IncludeEmpty}
 	args = append(args, whereArgs...)

internal/store/store_test.go

@@ -2681,3 +2681,71 @@ func TestMessagePendingEmbeddingJobsCountsWhatEmbedWouldDrain(t *testing.T) {
 	require.Equal(t, 1, stats.DirectMessages)
 	require.Zero(t, stats.Embeddable)
 }
+
+// CataloguedChannelsOnly narrows a scope to the rows
+// DirectMessageConversations can return. That listing selects from channels
+// and joins messages on both channel id and guild id, so a direct message
+// whose channel has no channels row under its guild is in no listing at any
+// window, and a count taken over messages alone reports rows the listing
+// cannot produce.
+func TestMessageScopeStatsCataloguedChannelsOnlyMatchesTheConversationListing(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	s, err := Open(ctx, filepath.Join(t.TempDir(), "discrawl.db"))
+	require.NoError(t, err)
+	defer func() { _ = s.Close() }()
+
+	require.NoError(t, s.UpsertGuild(ctx, GuildRecord{ID: DirectMessageGuildID, Name: "Direct Messages", RawJSON: `{}`}))
+	require.NoError(t, s.UpsertChannel(ctx, ChannelRecord{
+		ID: "c-dm", GuildID: DirectMessageGuildID, Kind: "dm", Name: "Alice", RawJSON: `{}`,
+	}))
+	dm := func(id, channelID, created string) MessageRecord {
+		return MessageRecord{
+			ID: id, GuildID: DirectMessageGuildID, ChannelID: channelID, ChannelName: "Alice",
+			AuthorID: "u2", CreatedAt: created, Content: "hello", NormalizedContent: "hello", RawJSON: `{}`,
+		}
+	}
+	require.NoError(t, s.UpsertMessage(ctx, dm("m-dm", "c-dm", "2026-01-02T00:00:00Z")))
+	require.NoError(t, s.UpsertMessage(ctx, dm("m-dm-orphan", "c-dm-orphan", "2026-01-03T00:00:00Z")))
+
+	// Both messages are in the guild scope, and the newest of them is the one
+	// with no channels row.
+	stats, err := s.MessageScopeStats(ctx, MessageScopeOptions{GuildIDs: []string{DirectMessageGuildID}})
+	require.NoError(t, err)
+	require.Equal(t, 2, stats.Count)
+	require.Equal(t, parseTime("2026-01-03T00:00:00Z"), stats.Newest)
+
+	// The listing returns one conversation, and the narrowed scope counts one.
+	rows, err := s.DirectMessageConversations(ctx, DirectMessageConversationOptions{})
+	require.NoError(t, err)
+	require.Len(t, rows, 1)
+	require.Equal(t, "c-dm", rows[0].ChannelID)
+
+	stats, err = s.MessageScopeStats(ctx, MessageScopeOptions{
+		GuildIDs: []string{DirectMessageGuildID}, CataloguedChannelsOnly: true,
+	})
+	require.NoError(t, err)
+	require.Equal(t, 1, stats.Count)
+	require.Equal(t, parseTime("2026-01-02T00:00:00Z"), stats.Newest)
+
+	// The listing joins on guild as well as channel id, so a channels row
+	// carrying the same id under a different guild leaves the orphan out. Both
+	// tables carry a guild_id, so this also pins the correlated subquery to the
+	// messages row: with the guild half dropped, or with its outer reference
+	// resolving to the channels row it selects from, the count below is 2 and
+	// the newest timestamp is 2026-01-03.
+	require.NoError(t, s.UpsertChannel(ctx, ChannelRecord{
+		ID: "c-dm-orphan", GuildID: "g1", Kind: "text", Name: "same id, other guild", RawJSON: `{}`,
+	}))
+	rows, err = s.DirectMessageConversations(ctx, DirectMessageConversationOptions{})
+	require.NoError(t, err)
+	require.Len(t, rows, 1)
+
+	stats, err = s.MessageScopeStats(ctx, MessageScopeOptions{
+		GuildIDs: []string{DirectMessageGuildID}, CataloguedChannelsOnly: true,
+	})
+	require.NoError(t, err)
+	require.Equal(t, 1, stats.Count)
+	require.Equal(t, parseTime("2026-01-02T00:00:00Z"), stats.Newest)
+}