Sync a connected Google account forward, on a schedule its owner sets

[lilseyi]

A person connects Gmail in settings, the grant is stored and a historyId
baseline is recorded — and nothing has ever advanced that cursor. There is no
cron entry, there is no webhook, and the gateway's scheduled() handler has no
[triggers] block configured (and reaches only the single-tenant legacy path
when it does fire). apps/mcp/src/communications/gmailSync.js — a complete,
fixture-tested Gmail pipeline — was imported by nothing at all after #388
removed the historical backfill that used to import it.

So this is the trigger that was missing, not a second pipeline. No new Gmail
fetcher was written: runIncrementalSync and getProfileHistoryId come back
into functions/files.ts exactly where runBackfill used to be called from.

What it does

• A five-minute cron, sweepDueGoogleSyncs, that starts a pass only for
  connections that are actually due (now >= lastSyncAt + interval), claims
  each one it starts, and skips anything claimed less than fifteen minutes ago
  so a pass still running is never overtaken. The cron decides only when to
  look; every question about whether a connection may sync is re-asked by the
  pass itself, before a credential is opened. (Due-ness is the one thing that
  is the sweep's alone — stated in crons.ts rather than glossed.)
• A per-connection syncIntervalMinutes, owner-only, with a floor of five
  minutes refused server-side and a ceiling of one day. The default is
  fifteen: three passes an hour at a third of the floor's cost.
• One forward pass per account, inside the existing credential barrier. It
  asks the row before it asks for a credential, advances historyId only over
  mail it actually wrote, re-baselines an expired cursor forward and records the
  gap rather than smoothing it over, and reports every exit — including the ones
  that did nothing — so a claim is never stranded.
• Honest status: how often this account is polled, whether it has ever
  read mail, whether it is draining a backlog, when it is next due, and the last
  failure kept after a later pass succeeded.

Forward-only throughout. #388's decision stands.

Adversarial review, second round — four findings, all fixed

Blocking: a truncated history walk reported the mailbox head as the cursor.
history.list returns the mailbox's current historyId on every page, not a
per-page cursor, and listAllHistory stopped at fifty pages without signalling
it. A truncated walk therefore stored "caught up" while holding only the first
pages, and everything behind them was skipped forever — no gapDetected,
row reading active, firing hardest on the first pass against a weeks-old
baseline. Raising the page limit moves the cliff; leaving the cursor put never
finishes. The walk now reports truncated and carries lastRecordId — a
history record's own id, a valid startHistoryId covering exactly the records
this pass collected — the pass stores that, and syncCatchUp keeps the
connection due on the next tick whatever its interval, so each pass drains
further and the flag clears when the walk reaches the end. The argument, and
the two rejected alternatives, are in docs/decisions/communications.md.

A revoked grant was hammered forever. The failed branch overwrote
health: "reconnect_required" with a plain error, and the pass's skip gate
keys on that state — so a grant Google had revoked was offered back to its token
endpoint on every backoff, and the console never showed the one state the owner
could act on. Health is now preserved, proved through the real sequence
(markReconnectRequired, then a failed pass) rather than by patching the row
into place.

The quota stopped counting exactly where it matters. The failed branch
dropped bytesWritten, and the one caller passing a non-zero figure is the
quota path — which stops after writing whole days. bytesAlreadyUsed froze
below the ceiling, so the same days were rewritten and re-dropped forever and
the ceiling was never crossable. Counted now, with an end-to-end check.

everSynced was true after passes that read nothing. A baseline and a gap
re-baseline are successful passes that read no mail, by design; counting them
as syncs showed a freshly connected mailbox as current before a message had
been read. gmail.lastSyncedAt moves only when mail was read, cursorReady is
what a baseline makes true, and the card has three sentences where it had two.

Taken as far as I judged right: the three unguarded error classifications now
have checks (a rate-limited owner must not be told to reconnect); the flat
15-minute retry is now a ladder to a six-hour cap with a per-connection spread;
writeDayPart does the read-compare on stores without conditional writes too,
so idempotence is a property of this code rather than of R2; crons.ts's
preamble now admits the second class of job rather than filing an engine beside
the sweeps; and every pass that writes leaves an audit row against boundBy —
counts only, and never for a poll that found nothing.

Earlier round, for the record

A circular import between googleConnect.ts and googleSync.ts (an export
sometimes missing, surfacing as an unrelated flaky test); the pass would have
rewritten every touched day forever by passing a wall-clock now into
renderDay; and workspaceId/connectionId were never checked against each
other, which would have filed one context's mail into another's bucket.

Tests

Convex 2,339 → 2,410. Mobile 4,475 → 4,484. Gateway 3,113 → 3,122.

Second sabotage round: 18 more, all 18 red, each isolated to the checks naming
the guard — including one that was green on the first attempt (the single line
wiring truncation into the row), which is why the Convex fixture now pages.
Across both rounds: 43 sabotages, 41 red; the two that stayed green are the
sweep's unreachable-by-construction belt and a no-op sabotage, both since
converted or documented.

What is unexercised

Nothing here has ever contacted Google — every call is a fixture, and that
sentence is now in the decision doc as well as this description, because the
doc outlives the PR. Page shapes, rate-limit reasons and the real historyId
lifetime are documentation rather than observation; Google says "typically at
least a week" and "in rare circumstances only a few hours", which means even a
one-day interval can gap, and the doc says so. The loop is also inert wherever
MAIL_CONNECT_ENABLED is not "true".

Calendar and Chat are deliberately not half-done; what each needs is written
out in docs/decisions/communications.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W42G6GPAm2Nh3nCxp2ir9D

[lilseyi]

Rebased onto current main after the durable move, managed-storage, Fast Search, and observability merges. Revalidation on Node 22: 128 focused Convex Google sync/connect tests passed; Convex and mobile typechecks passed; 42 focused mobile integration tests passed; full MCP/gateway suite passed. The production path remains forward-only and credential access stays behind the existing internal action barrier.