feat(gmail): report how many results a search really has — resultSizeEstimate saturates at 201 and is unusable as a count

[chrischall]

Problem

gog gmail search and gog gmail messages search give a caller no way to learn how large a result set is without walking it. The JSON payload is items + nextPageToken, so "are there more?" is answerable but "how many more?" is not.

That gap causes a specific, repeatable failure in agent/LLM callers: a capped page gets read as the complete answer, and the caller reports that a message does not exist when it does. A page token alone is easy to skim past; a magnitude is not.

Why the obvious fix doesn't work

The Gmail API returns resultSizeEstimate on both users.threads.list and users.messages.list, and gog currently drops it — gmail_search.go:~97 and gmail_messages.go:~110 build the JSON payload by hand from items + nextPageToken.

Surfacing that field would be a bug, not a fix. It saturates. Measured on a live account, gog v0.35.0 (402def5), 2026-08-12:

$ gog api call gmail v1 users.messages.list \
    --params '{"userId":"me","q":"<Q>","maxResults":1,"fields":"resultSizeEstimate"}'

query	resultSizeEstimate	true count (--all)
from:freshbooks.com	201	21
from:housecallpro.com	201	6
from:thumbtack.com newer_than:30d	201	3
from:honeybook.com	201	9
invoice	201	>500
in:inbox	201	large
zzzznomatch	0	0

It returns 201 for every non-empty query and 0 for an empty one — a has-results boolean wearing a number's clothes. It is also independent of maxResults (identical at 1, 10, and 100), so it isn't a per-page figure either. Emitting it would let a caller report "3 of ~201" when the truth is 3 of 6.

Proposed fix

An opt-in --count flag on both search commands that reports a real number, obtained with one extra list call requesting a single maximal page of bare ids:

maxResults=500, fields="threads/id,nextPageToken"   (or messages/id)

• fits in one page → exact total, emitted as totalMatches
• fills the page with more behind it → honest lower bound, emitted as totalMatchesAtLeast

Verified against the same account:

query	probe result	matches --all?
from:freshbooks.com	counted 21, no more pages	✅ 21
from:housecallpro.com	counted 6, no more pages	✅ 6
invoice	counted 500, more pages	✅ lower bound

The response is ids only, so it stays small, and the flag keeps it off the default path — no extra round-trip for callers who don't ask.

Exact whenever the set fits a page, which is the common case and always the case for the narrow queries a false negative is most likely to come from.

Notes

• I have this implemented and validated in a downstream wrapper already; happy to send the --count PR here (branch in progress) if the shape looks right to you.
• Open question for a maintainer: whether --count should also print on the text/table path, or stay JSON-only.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 13, 2026, 12:29 AM ET / 04:29 UTC.

Summary
Keep open: current main has no count contract, and the open linked implementation PR already owns the code change. A maintainer only needs to choose whether the new opt-in count also emits a human-facing stderr hint outside JSON mode.

Reproducibility: yes. for the central gap: current source shows both commands expose only result items and nextPageToken. The supplied linked-PR context also includes live Gmail validation, though this review did not rerun it against a private mailbox.

Maintainer decision needed

Question	Recommendation
Should Gmail --count also print a concise stderr hint for table/plain output, or remain JSON-only?	Keep the stderr hint: Show interactive users the count on stderr while preserving byte-identical parseable stdout.

Why: Both variants fit the supported Gmail surface, but this is new CLI and output API surface and the contributor has explicitly reserved this behavior for maintainer direction.

Next step
The open linked PR already owns the implementation; this issue is waiting only for maintainer product direction.

Review details

Best possible solution:

Land one opt-in whole-query count contract through the linked PR, retaining parseable stdout and documenting exact versus lower-bound fields.

Do we have a high-confidence way to reproduce the issue?

Yes for the central gap: current source shows both commands expose only result items and nextPageToken. The supplied linked-PR context also includes live Gmail validation, though this review did not rerun it against a private mailbox.

Is this the best way to solve the issue?

Unclear pending the text-output decision: the linked opt-in IDs-only count probe is narrow and plausible, but the permanent CLI/output contract needs maintainer approval.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The new flag and JSON field names are a script-facing contract; maintainers need to settle whether table/plain mode also receives a stderr count hint.

Codex review notes: model internal, reasoning high; reviewed against 0d8088534f09.

Label changes

Label changes:

• add clawsweeper:linked-pr-open: Current issue advisory state selects this label.
• remove clawsweeper:needs-maintainer-review: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is an opt-in supported-area convenience feature rather than an urgent break in existing Gmail search behavior.

Evidence reviewed

What I checked:

• Thread search lacks a count contract: Current JSON output contains only threads and nextPageToken, with no count flag or count field. (internal/cmd/gmail_search.go:94, 0d8088534f09)
• Message search lacks a count contract: Current message search returns messages plus nextPageToken only. (internal/cmd/gmail_messages.go:66, 0d8088534f09)
• Open implementation candidate: Open, clean PR feat(gmail): add --count to search and messages search #984 explicitly closes this issue and supplies live Gmail output, focused tests, and follow-up coverage for --all and --results-only. (ca114661c6b9)
• Vision fit: The repository VISION.md supports small useful Gmail primitives but asks for discussion of new API surfaces and script-facing behavior. (VISION.md:13, 0d8088534f09)
• Likely ownership trail: The checked-out search-flow lines trace to Peter Steinberger's release preparation commit; available local history is limited but identifies him as the strongest current routing candidate. (internal/cmd/gmail_search.go:53, 402def5041d6)

Likely related people:

• Peter Steinberger: Current Gmail search-flow lines and the available file history point to the v0.35.0 release-preparation commit. (role: recent area contributor; confidence: low; commits: 402def5041d6; files: internal/cmd/gmail_search.go, internal/cmd/gmail_messages.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[chrischall]

Author follow-up: the two open risks in the review are now resolved, since they're decision inputs and the cross-link to #984 doesn't surface what came of them.

"scope with --page and --all needs an explicit contract" — investigated live; --all was a real defect, not just undocumented. It had already walked every page, so the items in hand were the whole set and the probe re-asked a question the walk had just answered. The total now comes from the walk (exact by construction, no extra request). --page needed no code change but did need stating: the count is always for the whole query, never the remainder after a cursor — verified live returning 6 on page 2 of a 6-thread set rather than the 4 remaining. That's the number that stops a caller reporting an absence, and it stays stable while paging.

"interaction with --results-only" — also a real defect. unwrapPrimary emits the bare result array and threads/messages are both in its known-result list, so the count was computed and then silently discarded — a Gmail request spent for nothing, invisibly. Now skipped, with the reason on stderr.

"snapshot can differ from the displayed page" — worth keeping as a known property rather than fixing: the count is a second request, so a mailbox changing between the two can make it disagree with the page by an item. Making it atomic isn't possible through the list API, and the number is meant to answer "is this all of them?", where being off by one under concurrent mail is immaterial. Happy to state that in the flag help if you'd rather it were explicit.

The one question actually left for a maintainer is the review's own: JSON-only, or also text? Currently the text path prints Showing 2 of 6 matches. to stderr — the same channel and shape as the printNextPageHintWithAll hint immediately beside it, so stdout is byte-identical either way. Strictly-JSON-only is a two-line deletion and I'll push it on request.

#984 has the implementation with live proof attached. It's not trying to pre-empt the needs-product-decision call — if the answer is "not this surface", say so and I'll close it; no attachment to the code. Leaving @clawsweeper re-review for you to fire rather than triggering CI on your repo myself.