archive-mail skill: read .results envelope + use truncated to avoid silently archiving a partial corpus (search_emails #204)

[kiki830621]

Problem

PsychQuant/che-apple-mail-mcp shipped a breaking response-shape change for the search_emails / list_emails MCP tools in v2.14.0 (PsychQuant/che-apple-mail-mcp#204): both tools now return an envelope { results, returned, limit, truncated } instead of a bare JSON array. Per-result fields are unchanged — consumers must read .results.

The /archive-mail skill (plugins/che-apple-mail-mcp/commands/archive-mail.md) consumes search_emails output as a counted/iterated array:

• Step 3 / 3b / 3c / 3d — search_emails(account_name, query, field, limit: 100) for sender + subject_keywords + bare-subject thread expansion; the three result sets are Message-ID-deduped into the corpus (commands/archive-mail.md:478,500,509).
• Downstream corpus aggregation + thread-completeness counting treat the response as the array.

Two consequences:

1. Envelope drift — the skill should read .results (not the top-level response) when iterating / counting / deduping. Because /archive-mail is an LLM-executed markdown skill, the model generally adapts at runtime, so this is documented-expectation drift rather than a guaranteed crash — but the skill text + examples should be explicit to avoid silent mis-handling.
2. Silent truncation (the real value) — the skill calls search_emails with limit: 100. A prolific sender with >100 matching emails returns a truncated set with no signal under the old bare-array shape; the corpus silently misses emails. This is precisely the bug that motivated search_emails silently truncates at limit — no signal that more results exist che-apple-mail-mcp#204. The new truncated field makes it detectable: the skill should consult truncated and either raise limit (paginate / retry with a larger limit) or warn instead of silently archiving a partial corpus.

Scope

• commands/archive-mail.md: read matches from .results wherever search_emails / list_emails output is iterated/counted/deduped (Steps 3/3b/3c/3d + any thread-completeness count). Make the .results access explicit in the skill text + examples.
• Add truncation handling: when a search_emails call returns truncated == true, raise limit (or paginate) and/or surface a warning in the Step 4.5 preview / Step 10 audit so a partial corpus is never silently archived.
• (If a spec covers the search step) reflect the .results + truncated contract in the relevant openspec/specs/archive-mail-* spec.

Context

• Upstream envelope change: search_emails silently truncates at limit — no signal that more results exist che-apple-mail-mcp#204 (shipped v2.14.0).
• Consumer-update tracker (filed this sibling): Update bare-array consumers of search_emails/list_emails for the #204 truncation envelope che-apple-mail-mcp#205.
• Envelope contract (source of truth): openspec/specs/sqlite-query-engine/spec.md → "Search and list result truncation envelope" in the che-apple-mail-mcp repo; the shipped tool descriptions also document { results, returned, limit, truncated }.

Impact

Low–medium. LLM-driven skill adapts to .results at runtime, but the truncation-aware handling is the substantive fix: it closes the silent-partial-corpus gap (the #204 motivation) for the bulk archive flow.

---

Filed as the cross-repo sibling of PsychQuant/che-apple-mail-mcp#205 (Strategy item 2) during /idd-all #205.