Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
51.5 KB
Raw Blame
import { withConnectorSync, rethrowConnectorWriteError, pendingConnectorResult, type ManagedConnectorSync } from '../persistence/connector-sync.ts';
import { resolveGoogleAccount } from '../persistence/connector-account.ts';
import { googleApiProblem, googleUserinfo } from './api-access.ts';
import { ConnectorHoldSession, connectorHoldsResult } from '../connectors/connector-hold-session.ts';
import { carryLegacyFailCounts } from '../connectors/item-holds.ts';
import { connectorDryRunResult } from '../connectors/api-source.ts';
/**
 * google-source — Gmail/Calendar/Contacts sync for the `google` source kind.
 *
 * Mirrors the github source kind (github-source.ts): a source registered
 * with kind=google is API-backed, not git-backed. Threads, events, and
 * contacts materialize as markdown under the source's managed dir and flow
 * through the standard import pipeline (chunks, embeds, aliases, links).
 *
 * Sweep order: contacts → calendar → gmail — alias rows must exist before
 * the loop detector resolves counterparties.
 *
 * Cursor discipline (per service, independent):
 *  - contacts / calendar: syncToken committed only after that service's
 *    fully-successful sweep; 410 GONE drops the token and re-runs windowed.
 *  - gmail delta: history.list from gmail_history_id; 404 (expired, ~1 week)
 *    falls back to a bookmark-windowed messages.list, then re-anchors.
 *  - gmail INITIAL BACKFILL is explicitly resumable (outside-voice F7a): the
 *    window is drained newest→oldest with a floor cursor persisted per
 *    batch, so a killed 50k-message backfill resumes at the floor instead of
 *    restarting. historyId is captured BEFORE the backfill starts, so the
 *    delta lane takes over with zero gap (overlap re-renders are idempotent).
 *
 * Credentials come from the vault (gbrain google connect) — never from
 * sources.config, which stores only the account pointer.
 */

import { chmodSync, existsSync, readFileSync, renameSync, rmSync } from 'node:fs';
import { join, relative } from 'node:path';

import type { BrainEngine } from '../engine.ts';
import type { SyncOpts, SyncResult } from '../../commands/sync.ts';
import { CredentialError, isCredentialError } from '../creds/errors.ts';
import { GOOGLE_PROVIDER, GoogleTokenProvider, fetchSendAsAliases } from '../creds/providers/google.ts';
import { CommandAccessProvider, EnvAccessProvider, type GoogleAccessProvider } from './access.ts';
import { credentialId, openVault, type CredentialEntry, type CredentialVault } from '../creds/vault.ts';
import { createProgress, startHeartbeat } from '../progress.ts';
import { getCliOptions, cliOptsToProgressOptions } from '../cli-options.ts';
import { isWriteTargetContained } from '../path-confine.ts';
import { atomicWriteFileSync, mkdirPrivate } from '../atomic-write.ts';
import { importRendered, myAddressSet, type ActivePack, type GoogleSyncDeps, type GoogleSyncSummary } from './sweep-shared.ts';
export { myAddressSet } from './sweep-shared.ts';
import { sweepCalendar, sweepContacts } from './people-calendar-sweep.ts';
import { applyLoopDetection, enqueueLoopsExtraction, resolveSweepExclusion } from './loops-enqueue.ts';
import { NO_EXCLUSION } from './loops-exclusion.ts';
import {
  CalendarClient,
  GmailClient,
  GoogleCursorExpiredError,
  PeopleClient,
  type FetchImpl,
} from './google-clients.ts';
import { renderThreadPage, threadRelPath } from './google-render.ts';
import { slugifyPath } from '../sync.ts';
import {
  ALL_GOOGLE_SERVICES,
  isGmailHoldKey,
  type GmailThreadData,
  type GoogleApiProblem,
  type GoogleService,
  type GoogleSourceConfig,
  type GoogleSourceState,
} from './types.ts';
import { LOOPS_EXTRACT_WINDOW_DAYS, loopExtractionEligibility } from './loops-extract.ts';
import { recordGraceVerdict, recordWithheldVerdict, runLoopsCatchup, seedGraceBackfill, seedLoopRechecks, settleDueGraceHolds, type LoopsEnqueueReport } from './loop-catchup.ts';

export type { GoogleSourceConfig } from './types.ts';
export { runGoogleAttachmentBackfill } from './attachment-backfill.ts';
export { parseGoogleSourceConfig } from './source-config.ts';
import { parseGoogleSourceConfig } from './source-config.ts';

// ── Config ───────────────────────────────────────────────────────────────────

const G_KIND = 'google';

export function isGoogleSourceConfig(config: Record<string, unknown>): boolean {
  return config.kind === G_KIND;
}

// ── State ────────────────────────────────────────────────────────────────────

export function googleStateFile(dir: string): string {
  return join(dir, '.google-source.json');
}

function emptyState(): GoogleSourceState {
  return {
    gmail_history_id: null,
    gmail_backfill_floor_ms: null,
    gmail_backfill_done: false,
    gmail_newest_ms: null,
    calendar_sync_token: null,
    calendar_id: null,
    calendar_horizon_ms: null,
    contacts_sync_token: null,
    last_full_at: null,
  };
}

export function readGoogleState(dir: string): GoogleSourceState {
  const file = googleStateFile(dir);
  if (!existsSync(file)) return emptyState();
  try {
    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as Partial<GoogleSourceState>;
    return { ...emptyState(), ...parsed };
  } catch (e) {
    // A CORRUPT existing state file is not a fresh install: silently
    // returning emptyState() would re-run the entire backfill with zero
    // diagnostic. Quarantine for forensics and say so loudly.
    const quarantine = `${file}.corrupt`;
    let failure: { step: 'chmod' | 'rename'; path: string; error: unknown } | null = null;
    try {
      chmodSync(file, 0o600);
    } catch (error) {
      failure = { step: 'chmod', path: file, error };
    }
    try {
      renameSync(file, quarantine);
      if (failure) failure.path = quarantine;
    } catch (error) {
      failure ??= { step: 'rename', path: file, error };
    }
    process.stderr.write(
      `[google] state file ${file} was corrupt (${e instanceof Error ? e.message : String(e)}); ` +
        `quarantined to .corrupt — cursors reset, the next sync re-anchors and resumes.\n`,
    );
    if (failure) {
      process.stderr.write(
        `[google] could not secure the quarantined state file ${failure.path}: ${failure.step} failed ` +
          `(${failure.error instanceof Error ? failure.error.message : String(failure.error)}). ` +
          `It may be readable by other local users; run chmod 600 ${failure.path} or delete it.\n`,
      );
    }
    return emptyState();
  }
}

function writeGoogleState(dir: string, state: GoogleSourceState): void {
  mkdirPrivate(dir);
  // Atomic (tmp+fsync+rename): this file is written once per backfill batch;
  // a torn write would silently reset every cursor (full re-backfill).
  // 0600 is reasserted on every write, so a legacy 0644 file tightens.
  atomicWriteFileSync(googleStateFile(dir), JSON.stringify(state, null, 2), { mode: 0o600 });
}

// ── Sync runner ──────────────────────────────────────────────────────────────

async function saveGoogleState(deps: GoogleSyncDeps, state: GoogleSourceState): Promise<void> {
  if (deps.managed) await deps.managed.saveState(state);
  else writeGoogleState(deps.cfg.dir, state);
}

/** #5867/#5868 state a partial managed run still publishes (E20): never the Gmail cursor. */
function loopRecoveryState(state: GoogleSourceState): Record<string, unknown> {
  const fields = { loop_grace_holds: state.loop_grace_holds, loop_grace_backfill_done: state.loop_grace_backfill_done, loops_catchup: state.loops_catchup,
    loop_withheld_senders: state.loop_withheld_senders, loop_automated_backfill_done: state.loop_automated_backfill_done, calendar_unreadable: state.calendar_unreadable,
    api_access: state.api_access };
  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
}

/**
 * #9011: a thread whose import was still pending when processThread ran detection, then refused as purged content,
 * leaves what detection derived from a page that never landed. Drops its extract candidate and grace hold, and the open
 * loops of that slug while no live page holds it (open_loops.page_slug has no foreign key); the loops also for a refusal
 * an earlier run recorded, which may have resolved after that run's cleanup.
 */
async function forgetRefusedPurgedThreads(deps: GoogleSyncDeps, managed: ManagedConnectorSync, state: GoogleSourceState): Promise<void> {
  await managed.drainPending();
  const slugs = managed.refusedPurgedSlugs(true);
  if (!slugs.length) return;
  const refused = new Set(managed.refusedPurgedSlugs());
  deps.extractCandidates = deps.extractCandidates.filter((c) => !refused.has(c.slug));
  for (const [tid, hold] of Object.entries(state.loop_grace_holds ?? {})) if (hold.slug && refused.has(hold.slug)) delete state.loop_grace_holds![tid];
  await deps.engine.executeRaw(`DELETE FROM open_loops WHERE source_id=$1 AND page_slug=ANY($2::text[])
    AND NOT EXISTS (SELECT 1 FROM pages p WHERE p.source_id=$1 AND p.slug=open_loops.page_slug AND p.deleted_at IS NULL)`, [deps.sourceId, slugs]);
}

// ── Gmail sweep ──────────────────────────────────────────────────────────────

const BACKFILL_BATCH_THREADS = 25;

async function processThread(
  deps: GoogleSyncDeps,
  gmail: GmailClient,
  threadId: string,
  activePack: ActivePack,
  summary: GoogleSyncSummary,
  countedSlugs: Set<string>,
  seen: { thread?: GmailThreadData } = {},
  cutoffMs?: number,
): Promise<GmailThreadData | null> {
  const thread = await gmail.getThread(threadId, deps.cfg.account, {
    ...(deps.opts.signal ? { signal: deps.opts.signal } : {}),
  });
  seen.thread = thread;
  summary.threadsSeen++;
  const newestMs = thread.messages[thread.messages.length - 1]?.internalDateMs ?? 0;
  // #8482: the change feed and held retries name threads of any age; the history window keeps a thread with no page out, as the backfill does.
  if (cutoffMs !== undefined && newestMs < cutoffMs) {
    const [page] = await deps.engine.executeRaw('SELECT 1 FROM pages WHERE source_id = $1 AND slug = $2 AND deleted_at IS NULL',
      [deps.sourceId, slugifyPath(threadRelPath(thread))]);
    if (!page) return null;
  }
  const rendered = renderThreadPage(thread);
  // Pure noise renders no page AND skips detection — an all-noise thread
  // produces an empty verdict anyway, so nothing opens and nothing closes.
  if (!rendered) return thread;
  const slug = await importRendered(deps, rendered.relPath, rendered.markdown, activePack, summary, countedSlugs,
    { thread_id: thread.threadId, message_ids: thread.messages.map((m) => m.id) });
  // #8644/#8938: a purged thread is neither detected nor extracted, and its grace hold is dropped, so its text does not
  // come back through open loops.
  if (slug === null) {
    delete deps.loopState?.loop_grace_holds?.[thread.threadId];
    return thread;
  }
  for (const message of thread.messages) {
    const state = message.attachmentInspection?.state ?? 'not_inspected';
    summary.attachmentInspection[state] = (summary.attachmentInspection[state] ?? 0) + 1;
  }
  deps.processedThreads.add(thread.threadId);
  const verdict = await applyLoopDetection(deps, thread, slug);
  if (verdict && deps.loopState) recordGraceVerdict(deps.loopState, thread, verdict, slug, myAddressSet(deps.entry), deps.log, deps.exclusion);
  if (verdict && deps.loopState) recordWithheldVerdict(deps.loopState, verdict);
  if (verdict?.withheld) summary.loopsWithheld[verdict.withheld.reason] = (summary.loopsWithheld[verdict.withheld.reason] ?? 0) + 1;
  // LLM extraction candidates: trickle + the bounded recent window only —
  // the deep historical backfill is never extracted (spend honesty, F9).
  const windowMs = LOOPS_EXTRACT_WINDOW_DAYS * 86_400_000;
  if (newestMs > 0 && Date.now() - newestMs <= windowMs) {
    // Structural eligibility, not "everything recent": bulk mail the owner
    // never joined would otherwise both pay for model calls AND crowd real
    // threads out of the sweep.
    const verdict = loopExtractionEligibility(thread, myAddressSet(deps.entry), deps.exclusion);
    summary.extractEligibility[verdict.reason] =
      (summary.extractEligibility[verdict.reason] ?? 0) + 1;
    if (verdict.eligible) {
      deps.extractCandidates.push({ slug, threadId: thread.threadId, newestMs });
    }
  }
  return thread;
}

/**
 * A rate-limit failure is transient and self-clearing (Google's own quota
 * window, not a problem with this thread) — it never counts toward a hold.
 * The google-clients.ts retry loop already retries a rate-limited request
 * patiently (DEFAULT_RATE_LIMIT_RETRIES, backoff + jitter) before giving up
 * and throwing this; reaching here means the client's own retry budget was
 * exhausted, not that the thread is bad.
 */
function threadFailureMessage(tid: string, rateLimited: boolean, e: unknown): string {
  return (
    `[google] thread ${tid} failed${rateLimited ? ' (rate limited; not counted toward a hold)' : ''}: ` +
    `${e instanceof Error ? e.message : String(e)}`
  );
}

/**
 * #5581: current mail must be imported down to this far below the newest
 * message before a sweep may call the source fresh. A new install's history
 * anchor only replays changes AFTER it, so until the backfill's newest→oldest
 * floor has passed this horizon the recent inbox is still missing.
 */
export const GMAIL_RECENT_HORIZON_MS = 14 * 86_400_000;
/**
 * #5581 (Eng): the parked delta thread ids are capped at 1,000 ids or 64 KB
 * serialized. A delta larger than the cap is drained in bounded batches: the
 * history listing stops at the last record that fits, the anchor advances only
 * to that record once its threads are landed or parked, and the next run
 * resumes the history from there, so no change is ever dropped.
 */
export const GMAIL_PENDING_MAX_IDS = 1_000;
export const GMAIL_PENDING_MAX_BYTES = 64 * 1024;
/** Test seam: bounded-batch fixtures lower the cap instead of flagging 1,000 threads. */
export const gmailPendingCap = { ids: GMAIL_PENDING_MAX_IDS, bytes: GMAIL_PENDING_MAX_BYTES };
const fitsPendingCap = (ids: readonly string[]) => ids.length <= gmailPendingCap.ids && Buffer.byteLength(JSON.stringify(ids)) <= gmailPendingCap.bytes;

type WalkOutcome = 'done' | 'failed' | 'aborted' | 'more';

interface GmailSweep {
  deps: GoogleSyncDeps;
  gmail: GmailClient;
  state: GoogleSourceState;
  activePack: ActivePack;
  summary: GoogleSyncSummary;
  countedSlugs: Set<string>;
  holds: ConnectorHoldSession;
}

type ThreadOutcome = { kind: 'landed'; newestMs: number } | { kind: 'gone' | 'skipped' | 'failed' | 'rate_limited' };

/**
 * One thread through the item holds: a held thread is skipped unless
 * re-admitted; a failure is counted (a held thread failing again does not
 * block the cursor). On a managed brain a write error aborts the run after
 * the abort path publishes the holds.
 */
async function attemptThread(g: GmailSweep, tid: string, version: string | null, cutoffMs?: number): Promise<ThreadOutcome> {
  if (!g.holds.shouldAttempt(tid, version)) {
    g.deps.tick(`thread ${tid} held`);
    return { kind: 'skipped' };
  }
  const seen: { thread?: GmailThreadData } = {};
  try {
    const thread = await processThread(g.deps, g.gmail, tid, g.activePack, g.summary, g.countedSlugs, seen, cutoffMs);
    g.holds.succeed(tid);
    const newestMs = thread?.messages[thread.messages.length - 1]?.internalDateMs ?? 0;
    if (newestMs > (g.state.gmail_newest_ms ?? 0)) g.state.gmail_newest_ms = newestMs;
    g.deps.tick(`thread ${tid}`);
    return { kind: 'landed', newestMs };
  } catch (e) {
    if (e instanceof GoogleCursorExpiredError && e.status === 404) {
      // Thread deleted between listing and fetch — gone is gone. Skipping
      // (not failing) keeps the cursor moving; --full reconcile removes any
      // page it left behind.
      g.holds.drop(tid);
      g.deps.log(`[google] thread ${tid} vanished (404); skipping`);
      g.deps.tick(`thread ${tid} gone`);
      return { kind: 'gone' };
    }
    const wasHeld = g.holds.isHeld(tid);
    const first = seen.thread?.messages[0];
    const last = seen.thread?.messages[seen.thread.messages.length - 1];
    const classified = await g.holds.fail(tid, e, { version, slug: seen.thread ? threadRelPath(seen.thread).replace(/\.md$/, '') : null,
      meta: { sender: last?.from ?? null, subject: first?.subject ?? null, upstream_at: last ? last.dateIso : null } });
    const rateLimited = classified.scope === 'rate_limit';
    g.summary.failedFiles++;
    g.deps.log(threadFailureMessage(tid, rateLimited, e));
    if (wasHeld && !rateLimited) return { kind: 'skipped' };
    g.summary.status = 'partial';
    return { kind: rateLimited ? 'rate_limited' : 'failed' };
  }
}

/**
 * Drain `[lowerMs, state[floorKey])` newest→oldest, committing the floor per
 * fully-successful batch so a killed walk resumes where it stopped (F7a).
 * Shared by the historical backfill and the history-expired gap.
 */
async function walkGmailWindow(g: GmailSweep, floorKey: 'gmail_backfill_floor_ms' | 'gmail_gap_floor_ms', lowerMs: number): Promise<WalkOutcome> {
  const { deps, gmail, state } = g;
  let floorMs = state[floorKey] ?? Date.now() + 60_000;
  while (floorMs > lowerMs) {
    if (deps.opts.signal?.aborted) return 'aborted';
    const q = `after:${Math.floor(lowerMs / 1000)} before:${Math.ceil(floorMs / 1000)}`;
    // Page-BOUNDED listing (partialOk): a busy inbox can hold far more ids
    // than the client's 500-page safety cap; the floor cursor makes partial
    // listings safe — each iteration takes the newest ~2,000 messages in the
    // window, processes them, drops the floor, and re-queries.
    const ids = await gmail.listMessageIds(q, { maxPages: 20, partialOk: true, ...(deps.opts.signal ? { signal: deps.opts.signal } : {}) });
    if (ids.length === 0) break;
    // Newest-first listing → unique threads in newest-first order; a thread's
    // newest listed message id is its upstream version for the holds.
    const versions = new Map<string, string>();
    for (const m of ids) if (!versions.has(m.threadId)) versions.set(m.threadId, m.id);
    const threadIds = [...versions.keys()];
    let processedAny = false;
    let batchFailed = false;
    let batchOldest = floorMs;
    for (let i = 0; i < threadIds.length; i += BACKFILL_BATCH_THREADS) {
      if (deps.opts.signal?.aborted) break;
      for (const tid of threadIds.slice(i, i + BACKFILL_BATCH_THREADS)) {
        if (deps.opts.signal?.aborted) break;
        const outcome = await attemptThread(g, tid, versions.get(tid) ?? null);
        if (outcome.kind === 'landed') {
          processedAny = true;
          if (outcome.newestMs > 0 && outcome.newestMs < batchOldest) batchOldest = outcome.newestMs;
        } else if (outcome.kind === 'failed' || outcome.kind === 'rate_limited') {
          // A failed thread NEWER than a committed floor would fall outside
          // the resume window (`before:floor`) forever, so the batch holds the
          // floor. A rate limit is per-user: defer the rest of the batch.
          batchFailed = true;
          if (outcome.kind === 'rate_limited') break;
        }
      }
      if (batchFailed || deps.managed && deps.opts.signal?.aborted) break;
      if (processedAny && batchOldest < floorMs) {
        state[floorKey] = batchOldest;
        await saveGoogleState(deps, state);
      }
    }
    if (deps.opts.signal?.aborted) return 'aborted';
    if (batchFailed) return 'failed';
    if (!processedAny || batchOldest >= floorMs) {
      // Nothing moved the floor (all held/vanished or all same-timestamp):
      // step below the oldest listed page to guarantee termination. Only
      // reachable with zero failures.
      state[floorKey] = Math.max(lowerMs - 1, floorMs - 86_400_000);
      await saveGoogleState(deps, state);
    }
    floorMs = state[floorKey] ?? lowerMs;
  }
  return 'done';
}

/**
 * #5581: returns true when CURRENT mail is complete: the history delta
 * drained, no history-expired gap remains, and the recent inbox is
 * imported (backfill done or its floor past GMAIL_RECENT_HORIZON_MS). Held
 * threads never block it; `gbrain waiting` reports them as partial coverage.
 * False = the caller must NOT stamp `last_sync_at`. The deep historical
 * backfill runs AFTER current mail and does not gate freshness; its failures
 * still mark the run partial.
 */
async function sweepGmail(g: GmailSweep, onCurrent?: () => Promise<void>): Promise<boolean> {
  const { deps, gmail, state } = g;
  const cutoffMs = Date.now() - deps.cfg.historyDays * 86_400_000;

  // #5438: a completed backfill whose covered bound is above a now-WIDER
  // window reopens strictly below that bound (the floor's own `before:`).
  const covered = state.gmail_backfill_cutoff_ms;
  if (state.gmail_backfill_done && covered != null && cutoffMs < covered - 86_400_000) {
    deps.log(`[google] history window widened; resuming backfill below ${new Date(covered).toISOString()}`);
    state.gmail_backfill_done = false;
    state.gmail_backfill_floor_ms = covered;
    await saveGoogleState(deps, state);
  }

  // Anchor the delta lane BEFORE importing anything: changes that land
  // during the backfill are replayed by history.list.
  if (!state.gmail_backfill_done && !state.gmail_history_id) {
    const profile = await gmail.getProfile({ ...(deps.opts.signal ? { signal: deps.opts.signal } : {}) });
    if (profile.emailAddress.toLowerCase() !== deps.cfg.account) {
      deps.log(`[google] warning: token account ${profile.emailAddress} != source account ${deps.cfg.account}`);
    }
    state.gmail_history_id = profile.historyId;
    await saveGoogleState(deps, state);
  }
  if (!state.gmail_history_id) return true;

  // ── Current mail first: delta, then any history-expired gap ──
  const delta = await drainGmailDelta(g, cutoffMs);
  if (delta === 'aborted') return false;
  if (state.gmail_gap_floor_ms != null) {
    const gap = await walkGmailWindow(g, 'gmail_gap_floor_ms', state.gmail_gap_after_ms ?? cutoffMs);
    if (gap === 'aborted') return false;
    if (gap === 'done') {
      state.gmail_gap_after_ms = null;
      state.gmail_gap_floor_ms = null;
          await saveGoogleState(deps, state);
    }
  }
  // Held threads no listing of this run reached: re-attempt those retry-held
  // asked for or whose transient reconsideration is due. A failure keeps the
  // hold and never blocks the cursor.
  for (const tid of g.holds.dueHeldKeys().filter(isGmailHoldKey)) {
    if (deps.opts.signal?.aborted) return false;
    await attemptThread(g, tid, null, cutoffMs);
  }
  if (await settleGraceHolds(g, cutoffMs) === 'aborted') return false;
  const isCurrent = (): boolean => {
    if (delta !== 'done' || state.gmail_gap_floor_ms != null) return false;
    if (state.gmail_backfill_done) return true;
    const floor = state.gmail_backfill_floor_ms;
    if (floor == null || state.gmail_newest_ms == null) return false;
    return floor <= Math.max(cutoffMs, state.gmail_newest_ms - GMAIL_RECENT_HORIZON_MS);
  };
  // Stamp freshness BEFORE the backfill spends the rest of the budget: a
  // managed sweep cannot write once its wall-clock signal aborts.
  if (!state.gmail_backfill_done && isCurrent()) await onCurrent?.();

  // ── Historical backfill (resumable, oldest mail last) ──
  if (!state.gmail_backfill_done) {
    const backfill = await walkGmailWindow(g, 'gmail_backfill_floor_ms', cutoffMs);
    if (backfill === 'done') {
      state.gmail_backfill_done = true;
      state.gmail_backfill_cutoff_ms = Math.min(cutoffMs, state.gmail_backfill_floor_ms ?? cutoffMs);
      state.gmail_backfill_floor_ms = null;
      await saveGoogleState(deps, state);
    }
  }
  return isCurrent();
}

/**
 * #5868: seeds the one-shot grace backfill, then settles due grace holds.
 * A re-fetch goes straight through processThread (never the item holds), so
 * a failed grace re-fetch keeps the grace hold and is not an item failure.
 */
async function settleGraceHolds(g: GmailSweep, cutoffMs: number): Promise<'aborted' | void> {
  const { deps, state } = g;
  try {
    await seedGraceBackfill(deps.engine, deps.sourceId, state, deps.log);
    deps.graceBackfillSeeded = true;
  } catch (e) {
    deps.log(`[google] loop grace backfill failed (retried next sweep): ${e instanceof Error ? e.message : String(e)}`);
  }
  try {
    await seedLoopRechecks(deps.engine, deps.sourceId, state, deps.log, Date.now(), state.gmail_backfill_done ? null : cutoffMs);
  } catch (e) {
    deps.log(`[google] loop re-check seeding failed (retried next sweep): ${e instanceof Error ? e.message : String(e)}`);
  }
  const settled = await settleDueGraceHolds({ engine: deps.engine, sourceId: deps.sourceId, state, log: deps.log, signal: deps.opts.signal,
    exclusion: deps.exclusion, processed: deps.processedThreads, refetch: async (tid) => {
      try {
        await processThread(deps, g.gmail, tid, g.activePack, g.summary, g.countedSlugs);
        return 'ok';
      } catch (e) {
        if (e instanceof GoogleCursorExpiredError && e.status === 404) return 'gone';
        if (deps.managed) rethrowConnectorWriteError(e);
        deps.log(`[google] grace re-check of thread ${tid} failed (kept for the next sweep): ${e instanceof Error ? e.message : String(e)}`);
        return 'failed';
      }
    } });
  if (settled === 'aborted') return 'aborted';
}

/** Opens (or widens) the gap window `[after, floor)` that the floor walk drains newest→oldest. */
function openGmailGap(state: GoogleSourceState, cutoffMs: number): void {
  const after = (state.gmail_newest_ms ?? cutoffMs) - 86_400_000;
  state.gmail_gap_after_ms = Math.min(state.gmail_gap_after_ms ?? after, after);
  state.gmail_gap_floor_ms ??= Date.now() + 60_000;
}

async function drainGmailDelta(g: GmailSweep, cutoffMs: number): Promise<WalkOutcome> {
  const { deps, gmail, state } = g;
  let threadIds: string[] = [];
  let newHistoryId: string | null = null;
  let truncated = false;
  let versions = new Map<string, string>();
  const parked = state.gmail_pending_thread_ids ?? [];
  // Room left under the pending cap; a full pending set drains before any new history is listed.
  const room = gmailPendingCap.ids - parked.length;
  if (room > 0) {
    try {
      ({ threadIds, newHistoryId, truncated, versions } = await gmail.listHistoryThreadIds(state.gmail_history_id!, {
        maxThreads: room, ...(deps.opts.signal ? { signal: deps.opts.signal } : {}),
      }));
    } catch (e) {
      if (!(e instanceof GoogleCursorExpiredError)) throw e;
      // History expired (~1 week idle, or a long backfill): re-anchor NOW and
      // open a gap from the newest imported message to the anchor. Anchor and
      // gap persist together: a message arriving after the anchor is replayed
      // by history.list, one before it lies inside the gap.
      deps.log('[google] historyId expired; re-anchoring and draining the gap by window');
      const profile = await gmail.getProfile({ ...(deps.opts.signal ? { signal: deps.opts.signal } : {}) });
      state.gmail_gap_floor_ms = null;
      openGmailGap(state, cutoffMs);
      state.gmail_history_id = profile.historyId;
      await saveGoogleState(deps, state);
    }
  } else {
    // A full pending set drains before any new history is listed: current mail is not yet checked.
    truncated = true;
  }
  if (truncated) deps.log(`[google] history delta over the ${gmailPendingCap.ids}-thread pending cap; draining it in bounded batches`);
  let merged = [...new Set([...parked, ...threadIds])];
  // A pathological id set over the byte cap never advances the anchor: only the parked ids drain.
  if (!fitsPendingCap(merged)) { newHistoryId = null; truncated = true; merged = parked; threadIds = []; }
  // A thread flagged by this listing changed upstream (even when it is also parked): its hold may re-admit it.
  const fromHistory = new Set(threadIds);
  // `unlanded` shrinks as threads land or are dropped (404) or held.
  const unlanded = new Set(merged);
  // Bank drain progress: advancing the anchor is safe because every flagged
  // thread not yet landed stays parked (within the cap).
  const checkpoint = async (): Promise<void> => {
    if (newHistoryId) state.gmail_history_id = newHistoryId;
    state.gmail_pending_thread_ids = [...unlanded];
    await saveGoogleState(deps, state);
  };
  // A managed sweep cannot write once its signal aborts (the lease refuses),
  // so it banks as soon as its first thread lands and then once per batch; an
  // abort then repeats at most one batch. A run that lands nothing writes no
  // checkpoint, so a failed drain leaves the cursor where it was.
  let failed = 0;
  let landedSinceCheckpoint = deps.managed ? BACKFILL_BATCH_THREADS - 1 : 0;
  for (const tid of merged) {
    if (deps.opts.signal?.aborted) {
      if (!deps.managed) await checkpoint();
      return 'aborted';
    }
    // Thread-specific version (the latest history record touching it), so unrelated mail never resets a count.
    const version = fromHistory.has(tid) && versions.get(tid) ? `history:${versions.get(tid)}` : null;
    const outcome = await attemptThread(g, tid, version, cutoffMs);
    if (outcome.kind === 'failed' || outcome.kind === 'rate_limited') {
      failed++;
      // Per-user quota: the remaining threads would burn the client's retry
      // budget against the same exhausted window; they stay parked.
      if (outcome.kind === 'rate_limited') break;
      continue;
    }
    unlanded.delete(tid);
    if (outcome.kind === 'landed' && (failed === 0 || deps.managed) && ++landedSinceCheckpoint >= BACKFILL_BATCH_THREADS) {
      landedSinceCheckpoint = 0;
      await checkpoint();
    }
  }
  if (deps.opts.signal?.aborted) {
    if (!deps.managed) await checkpoint();
    return 'aborted';
  }
  state.gmail_pending_thread_ids = [...unlanded];
  // Unmanaged: the delta cursor advances only when every flagged thread
  // landed — a partial drain re-lists the same window next run (idempotent).
  // A managed sweep that landed a thread already advanced it, parking the rest.
  if (failed === 0 && newHistoryId) state.gmail_history_id = newHistoryId;
  // Bank a clean batch even when nothing landed (every thread gone or held), or a bounded
  // batch of deleted threads would be re-listed forever on a managed brain. A batch with a
  // failure keeps the cursor its checkpoints committed.
  if (deps.managed && failed === 0) await saveGoogleState(deps, state);
  // A bounded batch is not a drained delta: current mail is complete only once the listing is not truncated.
  return failed !== 0 ? 'failed' : truncated ? 'more' : 'done';
}

// ── Full reconcile (deletes) ─────────────────────────────────────────────────

async function reconcileGmailDeletes(
  deps: GoogleSyncDeps,
  gmail: GmailClient,
  summary: GoogleSyncSummary,
): Promise<void> {
  // Enumerate the live window; anything under emails/ not in it vanished
  // (trash/spam/deleted). Only runs when enumeration fully succeeded — an
  // errored listing must never read as a bulk deletion.
  const cutoffSec = Math.floor((Date.now() - deps.cfg.historyDays * 86_400_000) / 1000);
  const ids = await gmail.listMessageIds(`after:${cutoffSec}`, {
    ...(deps.opts.signal ? { signal: deps.opts.signal } : {}),
  });
  const liveThreads = new Set(ids.map((m) => m.threadId));
  const rows = await deps.engine.executeRaw<{ slug: string; source_path: string | null; frontmatter: unknown }>(
    `SELECT slug, source_path, frontmatter FROM pages WHERE source_id = $1 AND deleted_at IS NULL AND slug LIKE 'emails/%'`,
    [deps.sourceId],
  );
  const stale: Array<{ slug: string; source_path: string | null }> = [];
  for (const r of rows) {
    const fm =
      typeof r.frontmatter === 'string'
        ? (JSON.parse(r.frontmatter) as Record<string, unknown>)
        : ((r.frontmatter ?? {}) as Record<string, unknown>);
    const tid = typeof fm.thread_id === 'string' ? fm.thread_id : null;
    const firstIso = typeof fm.first_message_date === 'string' ? fm.first_message_date : null;
    // Pages older than the window are out of enumeration scope — keep them.
    if (firstIso && Date.parse(firstIso) / 1000 < cutoffSec) continue;
    if (tid && !liveThreads.has(tid)) stale.push({ slug: r.slug, source_path: r.source_path });
  }
  if (stale.length === 0) return;
  const { massReconcileAllowed } = await import('../../commands/sync.ts');
  if (stale.length > 200 && !massReconcileAllowed()) {
    deps.log(`[google] mass-delete guard refused ${stale.length} deletes for source ${deps.sourceId}`);
    return;
  }
  if (deps.managed) {
    for (const page of stale) if (await deps.managed.delete(page.slug, page.source_path)) summary.deleted++;
    return;
  }
  await deps.engine.deletePages(stale.map((s) => s.slug), { sourceId: deps.sourceId });
  for (const s of stale) {
    if (!s.source_path) continue;
    // Containment guard mirrors the write path (defense-in-depth on DB rows).
    const target = join(deps.cfg.dir, s.source_path);
    if (isWriteTargetContained(target, deps.cfg.dir)) rmSync(target, { force: true });
  }
  summary.deleted += stale.length;
}

// ── Extract + embed (mirrors github-source's size-gated tail) ───────────────

async function runExtractAndEmbed(
  deps: GoogleSyncDeps,
  summary: GoogleSyncSummary,
): Promise<void> {
  if (deps.managed) return;
  const totalChanges = summary.added + summary.modified;
  const pagesAffected = summary.pagesAffected;
  if (totalChanges === 0 || pagesAffected.length === 0) return;

  if (!deps.opts.noExtract && totalChanges <= 100) {
    try {
      const { extractLinksForSlugs, extractTimelineForSlugs, stampExtracted, slugsSafeToStamp } = await import('../../commands/extract.ts');
      const extractOpts = { sourceId: deps.sourceId };
      const linksResult = await extractLinksForSlugs(deps.engine, deps.cfg.dir, pagesAffected, extractOpts);
      const timelineResult = await extractTimelineForSlugs(deps.engine, deps.cfg.dir, pagesAffected, extractOpts);
      // Stamp only the slugs both hooks actually read from disk; a page the
      // extractor skipped stays stale for 'gbrain extract --stale'.
      await stampExtracted(
        deps.engine,
        slugsSafeToStamp(linksResult, timelineResult)
          .map((slug) => ({ slug, source_id: deps.sourceId })),
      );
    } catch { /* extraction is best-effort */ }
  } else if (totalChanges > 100 && !deps.opts.noExtract) {
    process.stderr.write(`[google] large sync (${totalChanges} pages); extraction deferred to 'gbrain extract --stale --source-id ${deps.sourceId}'\n`);
  }

  if (!deps.opts.noEmbed && totalChanges <= 100 && pagesAffected.length > 0) {
    try {
      const { runEmbedCore } = await import('../../commands/embed.ts');
      await runEmbedCore(deps.engine, { slugs: pagesAffected, sourceId: deps.sourceId });
      summary.embedded = pagesAffected.length;
    } catch { /* embed is best-effort */ }
  } else if (!deps.opts.noEmbed && totalChanges > 100) {
    const drainHint = `run 'gbrain embed --stale --source ${deps.sourceId}' to drain now`;
    try {
      const { submitEmbedBackfill } = await import('../embed-backfill-submit.ts');
      const sub = await submitEmbedBackfill(deps.engine, deps.sourceId, { reason: 'google_sync_defer' });
      if (sub.status === 'submitted') {
        process.stderr.write(`[google] large sync (${totalChanges} pages); embeds deferred to embed-backfill job ${sub.jobId} — or ${drainHint}\n`);
      } else if (sub.status === 'embedding_disabled') {
        process.stderr.write(`[google] large sync (${totalChanges} pages); embed-backfill not queued: embedding is disabled on this brain (keyless by choice)\n`);
      } else {
        process.stderr.write(`[google] large sync (${totalChanges} pages); embed-backfill not queued (${sub.status}) — ${drainHint}\n`);
      }
    } catch (err) {
      process.stderr.write(`[google] embed-backfill submission failed: ${err instanceof Error ? err.message : String(err)} — ${drainHint}\n`);
    }
  }
}

// ── Entry point ──────────────────────────────────────────────────────────────

export async function runGoogleSync(
  engine: BrainEngine,
  sourceId: string,
  cfg: GoogleSourceConfig,
  opts: SyncOpts,
  fetchImpl?: FetchImpl,
  vaultOverride?: CredentialVault,
): Promise<SyncResult> {
  return withConnectorSync(engine, sourceId, 'google', cfg, opts,
    async (managed, options) => options.dryRun ? connectorDryRunResult('google', sourceId) : runGoogleSyncInner(engine, sourceId, cfg, options, managed, fetchImpl, vaultOverride), pendingConnectorResult);
}

async function runGoogleSyncInner(engine: BrainEngine, sourceId: string, cfg: GoogleSourceConfig, opts: SyncOpts,
  managed: ManagedConnectorSync | null, fetchImpl?: FetchImpl, vaultOverride?: CredentialVault): Promise<SyncResult> {
  if (!cfg.account) {
    throw new Error(
      `Google source "${sourceId}" has no account configured. Re-add it: gbrain sources add ${sourceId} --kind google --account <email>`,
    );
  }
  const log = (msg: string): void => {
    process.stderr.write(msg + '\n');
  };
  // Access resolution: the vault is the default; command/env modes let a
  // stack that already holds Google access (gog, gcloud, a credential
  // gateway) drive this source without gbrain's own OAuth flow. Non-vault
  // modes synthesize a minimal identity entry: no meta.scopes (so the scope
  // preflight below trusts cfg.services), no sendas_aliases (best-effort
  // live fetch below), account from the source config.
  let entry: CredentialEntry;
  let tokens: GoogleAccessProvider;
  if (cfg.access === 'command' || cfg.access === 'env') {
    tokens =
      cfg.access === 'command'
        ? new CommandAccessProvider(cfg.tokenCommand ?? '')
        : new EnvAccessProvider(cfg.tokenEnv ?? '');
    entry = {
      id: credentialId(GOOGLE_PROVIDER, cfg.account),
      provider: GOOGLE_PROVIDER,
      kind: 'bearer',
      client_ref: 'byo',
      secret: {},
      meta: { account: cfg.account, connected_at: new Date().toISOString() },
    };
    try {
      // sendAs aliases sharpen "is this message mine" (loop direction). The
      // token may not carry the settings scope — degrade to account-only.
      const aliases = await fetchSendAsAliases(await tokens.getAccessToken(), fetchImpl ?? fetch);
      if (aliases.length > 0) entry.meta.sendas_aliases = aliases;
    } catch { /* account-only identity */ }
  } else {
    const vault = vaultOverride ?? openVault();
    const vaultEntry = await vault.get(credentialId(GOOGLE_PROVIDER, cfg.account));
    if (!vaultEntry) {
      throw new CredentialError('not_connected', ` for ${cfg.account} — run: gbrain google connect --account ${cfg.account}`);
    }
    entry = vaultEntry;
    tokens = new GoogleTokenProvider(vault, entry.id, fetchImpl ?? fetch);
  }
  const clientArgs = [tokens, fetchImpl ?? fetch, log, entry.meta.client_id] as const;
  const gmail = new GmailClient(...clientArgs);
  const calendar = new CalendarClient(...clientArgs);
  const people = new PeopleClient(...clientArgs);
  const progress = createProgress(cliOptsToProgressOptions(getCliOptions()));
  const tick = (note: string): void => progress.tick(1, note);
  const deps: GoogleSyncDeps = { engine, sourceId, cfg, opts, entry, log, tick, exclusion: NO_EXCLUSION, extractCandidates: [], managed, processedThreads: new Set() };

  const summary: GoogleSyncSummary = {
    status: 'synced',
    added: 0,
    modified: 0,
    deleted: 0,
    chunksCreated: 0,
    embedded: 0,
    pagesAffected: [],
    threadsSeen: 0,
    attachmentInspection: {},
    extractEligibility: {},
    loopsWithheld: {},
    failedFiles: 0,
  };
  const countedSlugs = new Set<string>();

  // Active pack for pack-aware typing, mirroring performSyncInner.
  let activePack: ActivePack;
  if (!opts.noSchemaPack) {
    try {
      const { loadActivePack } = await import('../schema-pack/load-active.ts');
      const { loadConfig } = await import('../config.ts');
      const resolved = await loadActivePack({ cfg: loadConfig(), remote: false, sourceId });
      activePack = { page_types: resolved.manifest.page_types };
    } catch { /* legacy prefix typing */ }
  }

  // Scope preflight: a source configured for a service the credential's
  // grant doesn't cover (connect --scopes gmail, source defaults to all
  // three) must fail that service with the catalog's scope_missing fix —
  // not an opaque per-sweep 403 forever.
  const grantedScopes = entry.meta.scopes ?? [];
  const scopeFor: Record<GoogleService, string> = {
    gmail: 'https://www.googleapis.com/auth/gmail.readonly',
    calendar: 'https://www.googleapis.com/auth/calendar.readonly',
    contacts: 'https://www.googleapis.com/auth/contacts.readonly',
  };
  const grantedServices = cfg.services.filter((svc) => grantedScopes.includes(scopeFor[svc]));
  const missingServices = cfg.services.filter((svc) => !grantedScopes.includes(scopeFor[svc]));
  if (grantedScopes.length > 0 && missingServices.length > 0) {
    if (managed) throw new CredentialError('scope_missing', undefined, `services without grant: ${missingServices.join(', ')}`);
    log(new CredentialError('scope_missing', undefined, `services without grant: ${missingServices.join(', ')}`).toHuman());
  }
  const activeServices = grantedScopes.length > 0 ? grantedServices : cfg.services;
  // #5686: every enabled service reads as the pinned account; checked before any service runs.
  if (managed) {
    const { email } = await resolveGoogleAccount({ gmail, calendar, people, userinfo: googleUserinfo(tokens, fetchImpl ?? fetch) }, activeServices, opts.signal);
    await managed.assertAccount(email ? { kind: 'google', email } : null);
  }

  const state = managed ? managed.state(emptyState()) : readGoogleState(cfg.dir);
  deps.loopState = state;
  const firstRun = !state.gmail_backfill_done && state.gmail_history_id === null;
  // Fix wave 4: the Gmail poison ledger is read once and carried into the item holds.
  const holds = await ConnectorHoldSession.open(engine, sourceId, managed, emptyState() as unknown as Record<string, unknown>,
    carryLegacyFailCounts(state.item_holds, state.gmail_fail_counts, (id) => id, new Date().toISOString()), { full: opts.full });
  state.item_holds = holds.holds.initial();
  delete state.gmail_fail_counts;
  progress.start('sync.google_materialize');

  try {
    const serviceErrors: string[] = [];
    // #7073: services this run could not reach, and those it reached, for the stored api_access record.
    const apiProblems: GoogleApiProblem[] = (grantedScopes.length > 0 ? missingServices : []).flatMap((svc) => googleApiProblem(svc, new CredentialError('scope_missing')) ?? []);
    const reached = new Set<GoogleService>();
    const serviceFailed = (svc: GoogleService, e: unknown): void => {
      const problem = googleApiProblem(svc, e);
      if (problem) apiProblems.push(problem);
    };

    if (activeServices.includes('contacts')) {
      const stop = startHeartbeat(progress, 'contacts sweep');
      try {
        await sweepContacts(deps, people, state, activePack, summary, countedSlugs, holds, () => saveGoogleState(deps, state));
        reached.add('contacts');
      } catch (e) {
        if (managed) rethrowConnectorWriteError(e);
        serviceFailed('contacts', e);
        serviceErrors.push(`contacts: ${e instanceof Error ? e.message : String(e)}`);
        summary.status = 'partial';
        if (isCredentialError(e)) log(e.toHuman());
        else log(`[google] contacts sweep failed: ${e instanceof Error ? e.message : String(e)}`);
      } finally {
        stop();
      }
    }

    if (activeServices.includes('calendar')) {
      const stop = startHeartbeat(progress, 'calendar sweep');
      try {
        await sweepCalendar(deps, calendar, state, activePack, summary, countedSlugs, holds);
        reached.add('calendar');
      } catch (e) {
        if (managed) rethrowConnectorWriteError(e);
        serviceFailed('calendar', e);
        serviceErrors.push(`calendar: ${e instanceof Error ? e.message : String(e)}`);
        summary.status = 'partial';
        if (isCredentialError(e)) log(e.toHuman());
        else log(`[google] calendar sweep failed: ${e instanceof Error ? e.message : String(e)}`);
      } finally {
        stop();
      }
    }

    let gmailSweepOk = !activeServices.includes('gmail'); // gmail not active = not gating freshness
    if (activeServices.includes('gmail')) {
      const stop = startHeartbeat(progress, 'gmail sweep');
      try {
        deps.exclusion = await resolveSweepExclusion(deps, gmail);
        // sweepGmail reports thread-level failures via its return value —
        // they exit through normal returns, not throws, and stamping
        // last_sync_at over them would blind the staleness gate (H1).
        gmailSweepOk = await sweepGmail({ deps, gmail, state, activePack, summary, countedSlugs, holds }, async () => {
          // #5581: current mail is complete but the backfill is not: bank freshness now, while the managed lease can still write.
          if (managed && summary.status !== 'partial' && !opts.signal?.aborted) {
            await managed.saveState(state, true, new Date(state.gmail_newest_ms ?? Date.now()).toISOString());
          }
        });
        reached.add('gmail');
        if (opts.full) await reconcileGmailDeletes(deps, gmail, summary);
      } catch (e) {
        if (managed) rethrowConnectorWriteError(e);
        serviceFailed('gmail', e);
        serviceErrors.push(`gmail: ${e instanceof Error ? e.message : String(e)}`);
        summary.status = 'partial';
        if (isCredentialError(e)) log(e.toHuman());
        else log(`[google] gmail sweep failed: ${e instanceof Error ? e.message : String(e)}`);
      } finally {
        stop();
      }
    }

    summary.pagesAffected = [...new Set(summary.pagesAffected)];
    const settled = new Set<GoogleService>([...reached, ...apiProblems.map((p) => p.service)]);
    const keptProblems = (state.api_access?.problems ?? []).filter((p) => !settled.has(p.service) && cfg.services.includes(p.service));
    const problems = [...apiProblems, ...keptProblems];
    if (problems.length > 0 && JSON.stringify(problems) !== JSON.stringify(state.api_access?.problems)) state.api_access = { problems, at: new Date().toISOString() };
    else if (problems.length === 0 && state.api_access) state.api_access = null;
    if (grantedScopes.length > 0 && missingServices.length > 0) summary.status = 'partial';
    if (opts.signal?.aborted) summary.status = 'partial';
    if (opts.full && summary.status === 'synced') state.last_full_at = new Date().toISOString();

    // #5867 managed-only 30-day catch-up and the #5868 one-shot backfill marker; never on an aborted sweep.
    let catchup: LoopsEnqueueReport | null = null;
    if (activeServices.includes('gmail') && !opts.signal?.aborted) {
      if (deps.graceBackfillSeeded) state.loop_grace_backfill_done = true;
      if (managed) {
        try {
          catchup = await runLoopsCatchup({ engine, sourceId, state, log, signal: opts.signal, myAddresses: myAddressSet(entry),
            exclusion: deps.exclusion, inFlight: new Set(deps.extractCandidates.map(c => c.slug)),
            fetchThread: async (tid) => {
              try { return await gmail.getThread(tid, cfg.account, opts.signal ? { signal: opts.signal } : {}); }
              catch (e) { if (e instanceof GoogleCursorExpiredError && e.status === 404) return null; throw e; }
            } });
        } catch (e) {
          log(`[google] loops catch-up failed (retried next sweep): ${e instanceof Error ? e.message : String(e)}`);
        }
      }
    }

    // Per-service cursors were advanced in-place only on success; persist.
    // Throws connector_holds_exhausted before any save, so the cursor stays.
    if (managed && !opts.signal?.aborted) await forgetRefusedPurgedThreads(deps, managed, state);
    state.item_holds = holds.finish();
    if (managed) {
      if (summary.status !== 'partial' && gmailSweepOk) await managed.saveState(state, true, new Date(state.gmail_newest_ms ?? Date.now()).toISOString());
      // A partial run keeps the cursor its mid-run checkpoints committed and publishes changed holds plus the loop recovery state (#5867/#5868).
      else if (!opts.signal?.aborted) await managed.publishHolds(emptyState() as unknown as Record<string, unknown>, state.item_holds, loopRecoveryState(state));
    } else writeGoogleState(cfg.dir, state);
    await holds.complete();
    // An aborted run (wall-clock budget, serve-delegation timeout) skips the
    // extract/embed/extraction tails — the deferred backfill machinery picks
    // them up on the next full run instead of overshooting the budget.
    let loopsEnqueue: LoopsEnqueueReport | undefined;
    if (!opts.signal?.aborted) {
      await runExtractAndEmbed(deps, summary);
      const enqueued = await enqueueLoopsExtraction(deps);
      loopsEnqueue = catchup ? { enqueued: enqueued.enqueued + catchup.enqueued, deferred: enqueued.deferred + catchup.deferred,
        skipped_reason: enqueued.skipped_reason } : enqueued;
      // Auditable per-reason counts (loopExtractionEligibility) — no
      // addresses, subjects or body text ever reach the log.
      if (Object.keys(summary.extractEligibility).length > 0) {
        log(
          `[google] loops_extract eligibility: ${Object.entries(summary.extractEligibility)
            .map(([k, v]) => `${k}=${v}`)
            .join(' ')}`,
        );
      }
      if (Object.keys(summary.loopsWithheld).length > 0) {
        log(`[google] reply-owed loops withheld: ${Object.entries(summary.loopsWithheld).map(([k, v]) => `${k}=${v}`).join(' ')}`);
      }
    }

    // Commitment-loop staleness pass (v1 close semantics): overdue >14d or
    // >90d inactive → 'stale'. Cheap indexed UPDATE, once per sweep.
    try {
      const { markStaleLoops } = await import('../loops/loops-store.ts');
      await markStaleLoops(engine, sourceId);
    } catch { /* best-effort */ }

    // last_sync_at feeds the trust-critical staleness gate (`gbrain waiting`
    // refuses on stale sources). A sync whose GMAIL sweep failed did not
    // refresh the loops' data — stamping it would let a revoked token +
    // frequent cron keep the gate green forever (red-team F2 bypass).
    if (gmailSweepOk && !managed) {
      try {
        await engine.executeRaw(
          `UPDATE sources SET last_sync_at = now(), newest_content_at = $1::timestamptz WHERE id = $2`,
          [new Date(state.gmail_newest_ms ?? Date.now()).toISOString(), sourceId],
        );
      } catch { /* best-effort */ }
    }

    const changed = summary.added + summary.modified + summary.deleted > 0;
    if (activeServices.includes('gmail')) {
      log(`[google] attachment inspection (this sweep only): ${Object.entries(summary.attachmentInspection).map(([state, count]) => `${state}=${count}`).join(' ') || 'no messages inspected'}; historical completeness is not established by incremental sync.`);
    }
    return {
      status:
        summary.status === 'partial'
          ? 'partial'
          : firstRun && changed
            ? 'first_sync'
            : changed
              ? 'synced'
              : 'up_to_date',
      fromCommit: null,
      toCommit: '',
      added: summary.added,
      modified: summary.modified,
      deleted: summary.deleted,
      renamed: 0,
      chunksCreated: summary.chunksCreated,
      embedded: summary.embedded,
      pagesAffected: summary.pagesAffected,
      ...(summary.failedFiles > 0 ? { failedFiles: summary.failedFiles } : {}),
      ...(loopsEnqueue ? { loops_enqueue: loopsEnqueue } : {}),
      ...connectorHoldsResult(sourceId, holds.summary()),
    };
  } finally {
    progress.finish();
  }
}