zele 0.3.0 → 0.3.5

package/src/gmail-client.ts

@@ -1,18 +1,22 @@
 // Gmail API client for CLI/TUI use.
 // Wraps the @googleapis/gmail SDK with structured methods, object params, and inferred return types.
 // No abstract interfaces, no RPC layer — just a concrete class for Gmail.
-// Ported from Zero's GoogleMailManager (apps/server/src/lib/driver/google.ts) with CLI adaptations:
-//   - No HTML sanitization (CLI renders text)
-//   - No Effect library (simple retry loop)
-//   - Uses batchModify for label mutations (more efficient than per-thread modify)
-//   - Body decoding inline with Buffer (no base64-js dependency)
-//   - Concurrent hydration with configurable concurrency limit
+// Cache is built into the client for expensive read paths.
+// List/search entry-point calls always fetch fresh IDs and then reuse per-thread cache
+// to avoid repeated N+1 hydration calls.
+// Raw Google API responses are stored in the cache (gmail_v1.Schema$*) so the cache
+// is resilient to changes in our own parsed types. Parsing happens at read time.
+// When account is not provided (bootstrap/login flow), cache is skipped entirely.
 
 import { gmail as gmailApi, type gmail_v1 } from '@googleapis/gmail'
 import type { OAuth2Client } from 'google-auth-library'
 import { createMimeMessage } from 'mimetext'
 import { parseFrom, parseAddressList } from './email-utils.js'
-import { withRetry, mapConcurrent } from './api-utils.js'
+import * as errore from 'errore'
+import { withRetry, mapConcurrent, AuthError, isAuthLikeError, ApiError, NotFoundError, EmptyThreadError, MissingDataError } from './api-utils.js'
+import { renderEmailBody } from './output.js'
+import { getPrisma } from './db.js'
+import type { AccountId } from './auth.js'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -42,8 +46,9 @@ export interface ParsedMessage {
   inReplyTo?: string
   references?: string
   listUnsubscribe?: string
-  body: string // decoded plain text or html
+  body: string // decoded body (html preferred for rich rendering)
   mimeType: string // 'text/plain' or 'text/html'
+  textBody: string | null // decoded text/plain body when available (for reply parsing)
   attachments: AttachmentMeta[]
 }
 
@@ -81,10 +86,29 @@ export interface ThreadListItem {
 
 export interface ThreadListResult {
   threads: ThreadListItem[]
+  /** Raw Google gmail_v1.Schema$Thread metadata responses, parallel to threads[]. */
+  rawThreads: gmail_v1.Schema$Thread[]
   nextPageToken: string | null
   resultSizeEstimate: number
 }
 
+/** Result from getThread() — includes both parsed data and the raw Google response. */
+export interface ThreadResult {
+  parsed: ThreadData
+  raw: gmail_v1.Schema$Thread
+}
+
+// ---------------------------------------------------------------------------
+// Watch event type
+// ---------------------------------------------------------------------------
+
+export interface WatchEvent {
+  account: AccountId
+  type: 'new_message'
+  message: ParsedMessage
+  threadId: string
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -115,6 +139,40 @@ function decodeBase64Url(encoded: string) {
   return Buffer.from(base64, 'base64').toString('utf-8')
 }
 
+function decodeHtmlEntities(value: string): string {
+  const namedEntities: Record<string, string> = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+  }
+
+  return value.replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (match, entity: string) => {
+    if (entity.startsWith('#x') || entity.startsWith('#X')) {
+      const codePoint = Number.parseInt(entity.slice(2), 16)
+      if (!Number.isFinite(codePoint)) return match
+      return String.fromCodePoint(codePoint)
+    }
+
+    if (entity.startsWith('#')) {
+      const codePoint = Number.parseInt(entity.slice(1), 10)
+      if (!Number.isFinite(codePoint)) return match
+      return String.fromCodePoint(codePoint)
+    }
+
+    return namedEntities[entity.toLowerCase()] ?? match
+  })
+}
+
+function sanitizeSnippet(snippet: string): string {
+  return decodeHtmlEntities(snippet)
+    .replace(/[\u00A0\u00AD\u034F\u061C\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 function encodeBase64Url(data: string | Buffer) {
   const buf = typeof data === 'string' ? Buffer.from(data) : data
   return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
@@ -124,12 +182,134 @@ function encodeBase64Url(data: string | Buffer) {
 // GmailClient
 // ---------------------------------------------------------------------------
 
+// TTL constants in milliseconds
+const TTL = {
+  THREAD: 30 * 60 * 1000, // 30 minutes
+  LABELS: 30 * 60 * 1000, // 30 minutes
+  PROFILE: 24 * 60 * 60 * 1000, // 24 hours
+} as const
+
+function isExpired(createdAt: Date, ttlMs: number): boolean {
+  return createdAt.getTime() + ttlMs < Date.now()
+}
+
+/** Boundary helper: wrap a googleapis SDK call, converting auth-like errors to AuthError values.
+ *  Non-auth errors are wrapped in ApiError so they remain error values (no throwing).
+ *  Original error is preserved as `cause` for debugging. */
+function gmailBoundary<T>(email: string, fn: () => Promise<T>) {
+  return errore.tryAsync({
+    try: fn,
+    catch: (err) => isAuthLikeError(err)
+      ? new AuthError({ email, reason: String(err) })
+      : new ApiError({ reason: String(err), cause: err }),
+  })
+}
+
 export class GmailClient {
   private gmail: gmail_v1.Gmail
   private labelIdCache: Record<string, string> = {}
+  private account: AccountId | null
 
-  constructor({ auth }: { auth: OAuth2Client }) {
+  constructor({ auth, account }: { auth: OAuth2Client; account?: AccountId }) {
     this.gmail = gmailApi({ version: 'v1', auth })
+    this.account = account ?? null
+  }
+
+  // =========================================================================
+  // Cache helpers (private) — skip all cache ops when account is null
+  // =========================================================================
+
+  private get cacheEnabled(): boolean {
+    return this.account !== null
+  }
+
+  private async getCachedThread(threadId: string): Promise<gmail_v1.Schema$Thread | undefined> {
+    if (!this.cacheEnabled) return undefined
+    const prisma = await getPrisma()
+    const row = await prisma.thread.findUnique({
+      where: { email_appId_threadId: { email: this.account!.email, appId: this.account!.appId, threadId } },
+    })
+    if (!row || isExpired(row.createdAt, row.ttlMs)) return undefined
+    return JSON.parse(row.rawData) as gmail_v1.Schema$Thread
+  }
+
+  private async cacheThreadData(threadId: string, raw: gmail_v1.Schema$Thread, parsed: ThreadData): Promise<void> {
+    if (!this.cacheEnabled) return
+    const prisma = await getPrisma()
+    await prisma.thread.upsert({
+      where: { email_appId_threadId: { email: this.account!.email, appId: this.account!.appId, threadId } },
+      create: {
+        email: this.account!.email, appId: this.account!.appId, threadId,
+        subject: parsed.subject, snippet: parsed.snippet,
+        fromEmail: parsed.from.email, fromName: parsed.from.name ?? '',
+        date: parsed.date, labelIds: parsed.labelIds.join(','),
+        hasUnread: parsed.hasUnread, msgCount: parsed.messageCount,
+        historyId: parsed.historyId,
+        rawData: JSON.stringify(raw), ttlMs: TTL.THREAD, createdAt: new Date(),
+      },
+      update: {
+        subject: parsed.subject, snippet: parsed.snippet,
+        fromEmail: parsed.from.email, fromName: parsed.from.name ?? '',
+        date: parsed.date, labelIds: parsed.labelIds.join(','),
+        hasUnread: parsed.hasUnread, msgCount: parsed.messageCount,
+        historyId: parsed.historyId,
+        rawData: JSON.stringify(raw), ttlMs: TTL.THREAD, createdAt: new Date(),
+      },
+    })
+  }
+
+  async invalidateThreads(threadIds: string[]): Promise<void> {
+    if (!this.cacheEnabled) return
+    const prisma = await getPrisma()
+    await prisma.thread.deleteMany({ where: { email: this.account!.email, appId: this.account!.appId, threadId: { in: threadIds } } })
+  }
+
+  async invalidateThread(threadId: string): Promise<void> {
+    if (!this.cacheEnabled) return
+    const prisma = await getPrisma()
+    await prisma.thread.deleteMany({ where: { email: this.account!.email, appId: this.account!.appId, threadId } })
+  }
+
+  private async getCachedLabels(): Promise<gmail_v1.Schema$Label[] | undefined> {
+    if (!this.cacheEnabled) return undefined
+    const prisma = await getPrisma()
+    const row = await prisma.label.findUnique({ where: { email_appId: { email: this.account!.email, appId: this.account!.appId } } })
+    if (!row || isExpired(row.createdAt, row.ttlMs)) return undefined
+    return JSON.parse(row.rawData) as gmail_v1.Schema$Label[]
+  }
+
+  private async cacheLabelsData(raw: gmail_v1.Schema$Label[]): Promise<void> {
+    if (!this.cacheEnabled) return
+    const prisma = await getPrisma()
+    await prisma.label.upsert({
+      where: { email_appId: { email: this.account!.email, appId: this.account!.appId } },
+      create: { email: this.account!.email, appId: this.account!.appId, rawData: JSON.stringify(raw), ttlMs: TTL.LABELS, createdAt: new Date() },
+      update: { rawData: JSON.stringify(raw), ttlMs: TTL.LABELS, createdAt: new Date() },
+    })
+  }
+
+  async invalidateLabels(): Promise<void> {
+    if (!this.cacheEnabled) return
+    const prisma = await getPrisma()
+    await prisma.label.deleteMany({ where: { email: this.account!.email, appId: this.account!.appId } })
+  }
+
+  private async getCachedProfile(): Promise<{ emailAddress: string; messagesTotal: number; threadsTotal: number; historyId: string } | undefined> {
+    if (!this.cacheEnabled) return undefined
+    const prisma = await getPrisma()
+    const row = await prisma.profile.findUnique({ where: { email_appId: { email: this.account!.email, appId: this.account!.appId } } })
+    if (!row || isExpired(row.createdAt, row.ttlMs)) return undefined
+    return { emailAddress: row.emailAddress, messagesTotal: row.messagesTotal, threadsTotal: row.threadsTotal, historyId: row.historyId }
+  }
+
+  private async cacheProfileData(profile: { emailAddress: string; messagesTotal: number; threadsTotal: number; historyId: string }): Promise<void> {
+    if (!this.cacheEnabled) return
+    const prisma = await getPrisma()
+    await prisma.profile.upsert({
+      where: { email_appId: { email: this.account!.email, appId: this.account!.appId } },
+      create: { email: this.account!.email, appId: this.account!.appId, ...profile, ttlMs: TTL.PROFILE, createdAt: new Date() },
+      update: { ...profile, ttlMs: TTL.PROFILE, createdAt: new Date() },
+    })
   }
 
   // =========================================================================
@@ -148,47 +328,78 @@ export class GmailClient {
     maxResults?: number
     labelIds?: string[]
     pageToken?: string
-  } = {}): Promise<ThreadListResult> {
+  } = {}): Promise<ThreadListResult | AuthError | ApiError> {
     const { q, resolvedLabelIds } = this.buildSearchParams(folder, query, labelIds)
 
-    const res = await withRetry(() =>
-      this.gmail.users.threads.list({
-        userId: 'me',
-        q: q || undefined,
-        labelIds: resolvedLabelIds.length > 0 ? resolvedLabelIds : undefined,
-        maxResults,
-        pageToken: pageToken || undefined,
-      }),
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.threads.list({
+          userId: 'me',
+          q: q || undefined,
+          labelIds: resolvedLabelIds.length > 0 ? resolvedLabelIds : undefined,
+          maxResults,
+          pageToken: pageToken || undefined,
+        }),
+      ),
     )
+    if (res instanceof Error) return res
 
     const rawThreads = res.data.threads ?? []
 
-    // Hydrate with metadata
-    const threads = await mapConcurrent(rawThreads, async (t) => {
+    // Hydrate with metadata — collect both raw and parsed
+    const hydrated = await mapConcurrent(rawThreads, async (t) => {
       if (!t.id) return null
-      try {
-        const detail = await withRetry(() =>
+
+      const cached = await this.getCachedThread(t.id)
+      if (cached && (!t.historyId || !cached.historyId || t.historyId === cached.historyId)) {
+        return {
+          parsed: GmailClient.parseRawThreadListItem(cached),
+          raw: cached,
+        }
+      }
+
+      // Boundary: threads.get — auth errors abort via mapConcurrent, others skip.
+      const detail = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+        withRetry(() =>
           this.gmail.users.threads.get({
             userId: 'me',
             id: t.id!,
-            format: 'metadata',
-            metadataHeaders: ['Subject', 'From', 'Date', 'To'],
+            format: 'full',
           }),
-        )
-        return this.parseThreadListItem(t.id, detail.data)
-      } catch {
-        return null
+        ),
+      )
+      if (detail instanceof AuthError) return detail
+      if (detail instanceof Error) return null
+
+      const parsed = GmailClient.parseRawThread(detail.data)
+      await this.cacheThreadData(t.id, detail.data, parsed)
+
+      return {
+        parsed: GmailClient.parseRawThreadListItem(detail.data),
+        raw: detail.data,
       }
     })
 
-    return {
-      threads: threads.filter((t): t is ThreadListItem => t !== null),
+    if (hydrated instanceof Error) return hydrated
+
+    const valid = hydrated.filter((t): t is NonNullable<typeof t> => t !== null)
+    const result: ThreadListResult = {
+      threads: valid.map((t) => t.parsed),
+      rawThreads: valid.map((t) => t.raw),
       nextPageToken: res.data.nextPageToken ?? null,
       resultSizeEstimate: res.data.resultSizeEstimate ?? 0,
     }
+
+    return result
   }
 
-  async getThread({ threadId }: { threadId: string }) {
+  async getThread({ threadId }: { threadId: string }): Promise<ThreadResult> {
+    // Check cache
+    const cached = await this.getCachedThread(threadId)
+    if (cached) {
+      return { parsed: GmailClient.parseRawThread(cached), raw: cached }
+    }
+
     const res = await withRetry(() =>
       this.gmail.users.threads.get({
         userId: 'me',
@@ -197,37 +408,13 @@ export class GmailClient {
       }),
     )
 
-    if (!res.data.messages || res.data.messages.length === 0) {
-      return {
-        id: threadId,
-        historyId: res.data.historyId ?? null,
-        messages: [],
-        subject: '',
-        snippet: '',
-        from: { email: '' },
-        date: '',
-        labelIds: [],
-        hasUnread: false,
-        messageCount: 0,
-      } satisfies ThreadData
-    }
+    const parsed = GmailClient.parseRawThread(res.data)
+    const result: ThreadResult = { parsed, raw: res.data }
 
-    const messages = res.data.messages.map((m) => this.parseMessage(m))
-    const latest = messages.findLast((m) => !m.isDraft) ?? messages[messages.length - 1]!
-    const allLabels = [...new Set(messages.flatMap((m) => m.labelIds))]
+    // Write cache
+    await this.cacheThreadData(threadId, res.data, parsed)
 
-    return {
-      id: threadId,
-      historyId: res.data.historyId ?? null,
-      messages,
-      subject: latest.subject,
-      snippet: latest.snippet,
-      from: latest.from,
-      date: latest.date,
-      labelIds: allLabels,
-      hasUnread: messages.some((m) => m.unread),
-      messageCount: messages.filter((m) => !m.isDraft).length,
-    } satisfies ThreadData
+    return result
   }
 
   async getMessage({
@@ -236,14 +423,17 @@ export class GmailClient {
   }: {
     messageId: string
     format?: 'full' | 'metadata' | 'minimal' | 'raw'
-  }) {
-    const res = await withRetry(() =>
-      this.gmail.users.messages.get({
-        userId: 'me',
-        id: messageId,
-        format,
-      }),
+  }): Promise<ParsedMessage | { id: string; raw: string } | AuthError | ApiError> {
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.messages.get({
+          userId: 'me',
+          id: messageId,
+          format,
+        }),
+      ),
     )
+    if (res instanceof Error) return res
 
     if (format === 'raw') {
       return {
@@ -255,16 +445,19 @@ export class GmailClient {
     return this.parseMessage(res.data)
   }
 
-  async getRawMessage({ messageId }: { messageId: string }) {
-    const res = await withRetry(() =>
-      this.gmail.users.messages.get({
-        userId: 'me',
-        id: messageId,
-        format: 'raw',
-      }),
+  async getRawMessage({ messageId }: { messageId: string }): Promise<string | MissingDataError | AuthError | ApiError> {
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.messages.get({
+          userId: 'me',
+          id: messageId,
+          format: 'raw',
+        }),
+      ),
     )
+    if (res instanceof Error) return res
 
-    if (!res.data.raw) throw new Error('No raw email data found')
+    if (!res.data.raw) return new MissingDataError({ what: 'raw email data', resource: `message ${messageId}` })
     return decodeBase64Url(res.data.raw)
   }
 
@@ -321,44 +514,128 @@ export class GmailClient {
   }
 
   // =========================================================================
-  // Draft operations
+  // Reply / Forward (high-level composition)
   // =========================================================================
 
-  async createDraft({
-    to,
-    subject,
+  /**
+   * Reply to a thread. Handles reply-to resolution, reply-all CC computation,
+   * References/In-Reply-To headers, and subject prefixing.
+   */
+  async replyToThread({
+    threadId,
     body,
+    replyAll = false,
     cc,
-    bcc,
-    threadId,
     fromEmail,
-    attachments,
   }: {
-    to: Array<{ name?: string; email: string }>
-    subject: string
+    threadId: string
     body: string
-    cc?: Array<{ name?: string; email: string }>
-    bcc?: Array<{ name?: string; email: string }>
-    threadId?: string
+    replyAll?: boolean
+    cc?: Array<{ email: string }>
     fromEmail?: string
-    attachments?: Array<{ filename: string; mimeType: string; content: Buffer }>
-  }) {
-    const raw = this.buildMimeMessage({ to, subject, body, cc, bcc, attachments, fromEmail })
+  }): Promise<EmptyThreadError | AuthError | ApiError | gmail_v1.Schema$Message> {
+    const { parsed: thread } = await this.getThread({ threadId })
+    if (thread.messages.length === 0) {
+      return new EmptyThreadError({ threadId })
+    }
 
-    const res = await withRetry(() =>
-      this.gmail.users.drafts.create({
-        userId: 'me',
-        requestBody: {
-          message: { raw, threadId },
-        },
-      }),
-    )
+    const lastMsg = thread.messages[thread.messages.length - 1]!
 
-    return res.data
+    const replyTo = lastMsg.replyTo ?? lastMsg.from.email
+    const to = [{ email: replyTo }]
+
+    let resolvedCc: Array<{ email: string }> | undefined
+    if (replyAll) {
+      const profile = await this.getProfile()
+      if (profile instanceof Error) return profile
+      const myEmail = profile.emailAddress.toLowerCase()
+
+      const allRecipients = [
+        ...lastMsg.to.map((r) => r.email),
+        ...(lastMsg.cc?.map((r) => r.email) ?? []),
+      ]
+        .filter((e) => e.toLowerCase() !== myEmail)
+        .filter((e) => e.toLowerCase() !== replyTo.toLowerCase())
+
+      if (allRecipients.length > 0) {
+        resolvedCc = allRecipients.map((e) => ({ email: e }))
+      }
+    }
+
+    if (cc) {
+      resolvedCc = [...(resolvedCc ?? []), ...cc]
+    }
+
+    const refs = [lastMsg.references, lastMsg.messageId].filter(Boolean).join(' ')
+
+    const result = await this.sendMessage({
+      to,
+      subject: lastMsg.subject.startsWith('Re:') ? lastMsg.subject : `Re: ${lastMsg.subject}`,
+      body,
+      cc: resolvedCc,
+      threadId,
+      inReplyTo: lastMsg.messageId,
+      references: refs || undefined,
+      fromEmail,
+    })
+
+    await this.invalidateThread(threadId)
+
+    return result
+  }
+
+  /**
+   * Forward a thread. Fetches the last message, renders its body,
+   * builds the "Forwarded message" block, and sends.
+   */
+  async forwardThread({
+    threadId,
+    to,
+    body,
+    fromEmail,
+  }: {
+    threadId: string
+    to: Array<{ email: string }>
+    body?: string
+    fromEmail?: string
+  }): Promise<EmptyThreadError | gmail_v1.Schema$Message> {
+    const { parsed: thread } = await this.getThread({ threadId })
+    if (thread.messages.length === 0) {
+      return new EmptyThreadError({ threadId })
+    }
+
+    const lastMsg = thread.messages[thread.messages.length - 1]!
+    const renderedBody = renderEmailBody(lastMsg.body, lastMsg.mimeType)
+
+    const fromStr = lastMsg.from.name && lastMsg.from.name !== lastMsg.from.email
+      ? `${lastMsg.from.name} <${lastMsg.from.email}>`
+      : lastMsg.from.email
+
+    const fullBody = [
+      body ?? '',
+      '',
+      '---------- Forwarded message ----------',
+      `From: ${fromStr}`,
+      `Date: ${lastMsg.date}`,
+      `Subject: ${lastMsg.subject}`,
+      `To: ${lastMsg.to.map((t) => t.email).join(', ')}`,
+      '',
+      renderedBody,
+    ].join('\n')
+
+    return this.sendMessage({
+      to,
+      subject: `Fwd: ${lastMsg.subject}`,
+      body: fullBody,
+      fromEmail,
+    })
   }
 
-  async updateDraft({
-    draftId,
+  // =========================================================================
+  // Draft operations
+  // =========================================================================
+
+  async createDraft({
     to,
     subject,
     body,
@@ -368,7 +645,6 @@ export class GmailClient {
     fromEmail,
     attachments,
   }: {
-    draftId: string
     to: Array<{ name?: string; email: string }>
     subject: string
     body: string
@@ -381,9 +657,8 @@ export class GmailClient {
     const raw = this.buildMimeMessage({ to, subject, body, cc, bcc, attachments, fromEmail })
 
     const res = await withRetry(() =>
-      this.gmail.users.drafts.update({
+      this.gmail.users.drafts.create({
         userId: 'me',
-        id: draftId,
         requestBody: {
           message: { raw, threadId },
         },
@@ -393,16 +668,19 @@ export class GmailClient {
     return res.data
   }
 
-  async getDraft({ draftId }: { draftId: string }) {
-    const res = await withRetry(() =>
-      this.gmail.users.drafts.get({
-        userId: 'me',
-        id: draftId,
-        format: 'full',
-      }),
+  async getDraft({ draftId }: { draftId: string }): Promise<NotFoundError | AuthError | ApiError | { id: string; message: ParsedMessage; to: string[]; cc: string[]; bcc: string[] }> {
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.drafts.get({
+          userId: 'me',
+          id: draftId,
+          format: 'full',
+        }),
+      ),
     )
+    if (res instanceof Error) return res
 
-    if (!res.data || !res.data.message) throw new Error('Draft not found')
+    if (!res.data || !res.data.message) return new NotFoundError({ resource: `draft ${draftId}` })
 
     const message = this.parseMessage(res.data.message)
     const headers = res.data.message.payload?.headers ?? []
@@ -424,41 +702,47 @@ export class GmailClient {
     query?: string
     maxResults?: number
     pageToken?: string
-  } = {}) {
-    const res = await withRetry(() =>
-      this.gmail.users.drafts.list({
-        userId: 'me',
-        q: query || undefined,
-        maxResults,
-        pageToken: pageToken || undefined,
-      }),
+  } = {}): Promise<{ drafts: Array<{ id: string; threadId: string | null; subject: string; to: string[]; date: string; snippet: string }>; nextPageToken: string | null } | AuthError | ApiError> {
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.drafts.list({
+          userId: 'me',
+          q: query || undefined,
+          maxResults,
+          pageToken: pageToken || undefined,
+        }),
+      ),
     )
+    if (res instanceof Error) return res
 
     const drafts = await mapConcurrent(res.data.drafts ?? [], async (draft) => {
       if (!draft.id) return null
-      try {
-        const detail = await withRetry(() =>
+      // Boundary: drafts.get — auth errors abort via mapConcurrent, others skip.
+      const detail = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+        withRetry(() =>
           this.gmail.users.drafts.get({
             userId: 'me',
             id: draft.id!,
             format: 'metadata',
           }),
-        )
-        if (!detail.data.message) return null
-        const headers = detail.data.message.payload?.headers ?? []
-        return {
-          id: draft.id,
-          threadId: detail.data.message.threadId ?? null,
-          subject: this.getHeader(headers, 'subject') ?? '(no subject)',
-          to: this.getHeaderValues(headers, 'to'),
-          date: this.getHeader(headers, 'date') ?? '',
-          snippet: detail.data.message.snippet ?? '',
-        }
-      } catch {
-        return null
+        ),
+      )
+      if (detail instanceof AuthError) return detail
+      if (detail instanceof Error) return null
+      if (!detail.data.message) return null
+      const headers = detail.data.message.payload?.headers ?? []
+      return {
+        id: draft.id,
+        threadId: detail.data.message.threadId ?? null,
+        subject: this.getHeader(headers, 'subject') ?? '(no subject)',
+        to: this.getHeaderValues(headers, 'to'),
+        date: this.getHeader(headers, 'date') ?? '',
+        snippet: detail.data.message.snippet ?? '',
       }
     })
 
+    if (drafts instanceof Error) return drafts
+
     return {
       drafts: drafts.filter((d): d is NonNullable<typeof d> => d !== null),
       nextPageToken: res.data.nextPageToken ?? null,
@@ -489,34 +773,42 @@ export class GmailClient {
   // Label mutations (read/unread, star, archive, trash, labels)
   // =========================================================================
 
-  async markAsRead({ threadIds }: { threadIds: string[] }) {
+  async markAsRead({ threadIds }: { threadIds: string[] }): Promise<void | AuthError | ApiError> {
     const messageIds = await this.getMessageIdsForThreads(threadIds, (labelIds) =>
       labelIds.includes('UNREAD'),
     )
+    if (messageIds instanceof Error) return messageIds
     if (messageIds.length === 0) return
     await this.batchModifyMessages(messageIds, { removeLabelIds: ['UNREAD'] })
+    await this.invalidateAfterThreadMutation(threadIds)
   }
 
-  async markAsUnread({ threadIds }: { threadIds: string[] }) {
+  async markAsUnread({ threadIds }: { threadIds: string[] }): Promise<void | AuthError | ApiError> {
     const messageIds = await this.getMessageIdsForThreads(threadIds, (labelIds) =>
       !labelIds.includes('UNREAD'),
     )
+    if (messageIds instanceof Error) return messageIds
     if (messageIds.length === 0) return
     await this.batchModifyMessages(messageIds, { addLabelIds: ['UNREAD'] })
+    await this.invalidateAfterThreadMutation(threadIds)
   }
 
-  async star({ threadIds }: { threadIds: string[] }) {
+  async star({ threadIds }: { threadIds: string[] }): Promise<void | AuthError | ApiError> {
     const messageIds = await this.getMessageIdsForThreads(threadIds)
+    if (messageIds instanceof Error) return messageIds
     if (messageIds.length === 0) return
     await this.batchModifyMessages(messageIds, { addLabelIds: ['STARRED'] })
+    await this.invalidateAfterThreadMutation(threadIds)
   }
 
-  async unstar({ threadIds }: { threadIds: string[] }) {
+  async unstar({ threadIds }: { threadIds: string[] }): Promise<void | AuthError | ApiError> {
     const messageIds = await this.getMessageIdsForThreads(threadIds, (labelIds) =>
       labelIds.includes('STARRED'),
     )
+    if (messageIds instanceof Error) return messageIds
     if (messageIds.length === 0) return
     await this.batchModifyMessages(messageIds, { removeLabelIds: ['STARRED'] })
+    await this.invalidateAfterThreadMutation(threadIds)
   }
 
   async modifyLabels({
@@ -527,20 +819,26 @@ export class GmailClient {
     threadIds: string[]
     addLabelIds?: string[]
     removeLabelIds?: string[]
-  }) {
+  }): Promise<void | AuthError | ApiError> {
     // Resolve add labels (auto-create if missing), but only look up remove labels (never create)
     const resolvedAdd = await Promise.all(addLabelIds.map((l) => this.resolveLabelId(l)))
-    const resolvedRemove = (
-      await Promise.all(removeLabelIds.map((l) => this.lookupLabelId(l)))
-    ).filter((id): id is string => id !== null)
+    const addErr = resolvedAdd.find((r): r is AuthError | ApiError => r instanceof Error)
+    if (addErr) return addErr
+
+    const resolvedRemoveRaw = await Promise.all(removeLabelIds.map((l) => this.lookupLabelId(l)))
+    const removeErr = resolvedRemoveRaw.find((r): r is AuthError | ApiError => r instanceof Error)
+    if (removeErr) return removeErr
+    const resolvedRemove = resolvedRemoveRaw.filter((id): id is string => typeof id === 'string')
 
     const messageIds = await this.getMessageIdsForThreads(threadIds)
+    if (messageIds instanceof Error) return messageIds
     if (messageIds.length === 0) return
 
     await this.batchModifyMessages(messageIds, {
-      addLabelIds: resolvedAdd,
+      addLabelIds: resolvedAdd.filter((r): r is string => typeof r === 'string'),
       removeLabelIds: resolvedRemove,
     })
+    await this.invalidateAfterThreadMutation(threadIds)
   }
 
   async trash({ threadId }: { threadId: string }) {
@@ -550,6 +848,7 @@ export class GmailClient {
         id: threadId,
       }),
     )
+    await this.invalidateAfterThreadMutation([threadId])
   }
 
   async untrash({ threadId }: { threadId: string }) {
@@ -559,25 +858,24 @@ export class GmailClient {
         id: threadId,
       }),
     )
+    await this.invalidateAfterThreadMutation([threadId])
   }
 
-  async archive({ threadIds }: { threadIds: string[] }) {
+  async archive({ threadIds }: { threadIds: string[] }): Promise<void | AuthError | ApiError> {
     const messageIds = await this.getMessageIdsForThreads(threadIds)
+    if (messageIds instanceof Error) return messageIds
     if (messageIds.length === 0) return
     await this.batchModifyMessages(messageIds, { removeLabelIds: ['INBOX'] })
+    await this.invalidateAfterThreadMutation(threadIds)
   }
 
-  async deleteMessage({ messageId }: { messageId: string }) {
-    await withRetry(() =>
-      this.gmail.users.messages.delete({
-        userId: 'me',
-        id: messageId,
-      }),
-    )
+  /** Invalidate thread cache after a thread mutation. */
+  private async invalidateAfterThreadMutation(threadIds: string[]): Promise<void> {
+    await this.invalidateThreads(threadIds)
   }
 
   /** Moves all spam threads to trash. Does not permanently delete. */
-  async trashAllSpam() {
+  async trashAllSpam(): Promise<{ count: number } | AuthError | ApiError> {
     let totalDeleted = 0
     let pageToken: string | undefined
 
@@ -587,11 +885,13 @@ export class GmailClient {
         maxResults: 100,
         pageToken,
       })
+      if (res instanceof Error) return res
 
       if (res.threads.length === 0) break
 
       const threadIds = res.threads.map((t) => t.id)
       const messageIds = await this.getMessageIdsForThreads(threadIds)
+      if (messageIds instanceof Error) return messageIds
       await this.batchModifyMessages(messageIds, {
         addLabelIds: ['TRASH'],
         removeLabelIds: ['SPAM', 'INBOX'],
@@ -609,26 +909,26 @@ export class GmailClient {
   // Labels CRUD
   // =========================================================================
 
-  async listLabels() {
-    const res = await withRetry(() =>
-      this.gmail.users.labels.list({ userId: 'me' }),
-    )
+  async listLabels(): Promise<{ parsed: ReturnType<typeof GmailClient.parseRawLabels>; raw: gmail_v1.Schema$Label[] } | AuthError | ApiError> {
+    // Check cache
+    const cached = await this.getCachedLabels()
+    if (cached) {
+      return { parsed: GmailClient.parseRawLabels(cached), raw: cached }
+    }
 
-    return (
-      res.data.labels?.map((label) => ({
-        id: label.id ?? '',
-        name: label.name ?? '',
-        type: (label.type ?? 'user') as 'system' | 'user',
-        messageListVisibility: label.messageListVisibility ?? null,
-        labelListVisibility: label.labelListVisibility ?? null,
-        color: label.color
-          ? {
-              backgroundColor: label.color.backgroundColor ?? '',
-              textColor: label.color.textColor ?? '',
-            }
-          : null,
-      })) ?? []
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.labels.list({ userId: 'me' }),
+      ),
     )
+    if (res instanceof Error) return res
+
+    const rawLabels = res.data.labels ?? []
+
+    // Write cache
+    await this.cacheLabelsData(rawLabels)
+
+    return { parsed: GmailClient.parseRawLabels(rawLabels), raw: rawLabels }
   }
 
   async getLabel({ labelId }: { labelId: string }) {
@@ -675,35 +975,14 @@ export class GmailClient {
       }),
     )
 
+    await this.invalidateLabels()
+
     return {
       id: res.data.id ?? '',
       name: res.data.name ?? name,
     }
   }
 
-  async updateLabel({
-    labelId,
-    name,
-    color,
-  }: {
-    labelId: string
-    name?: string
-    color?: { backgroundColor: string; textColor: string }
-  }) {
-    await withRetry(() =>
-      this.gmail.users.labels.update({
-        userId: 'me',
-        id: labelId,
-        requestBody: {
-          name,
-          color,
-        },
-      }),
-    )
-    // Invalidate label ID cache since name may have changed
-    this.labelIdCache = {}
-  }
-
   async deleteLabel({ labelId }: { labelId: string }) {
     await withRetry(() =>
       this.gmail.users.labels.delete({
@@ -711,58 +990,71 @@ export class GmailClient {
         id: labelId,
       }),
     )
-    // Invalidate label ID cache
     this.labelIdCache = {}
+    await this.invalidateLabels()
   }
 
   // =========================================================================
   // Label counts (unread counts per folder/label)
   // =========================================================================
 
-  async getLabelCounts() {
-    // Fetch label counts and archive count concurrently
-    const [labels, archiveRes] = await Promise.all([
-      this.listLabels(),
+  async getLabelCounts(): Promise<{ parsed: Array<{ label: string; count: number }>; raw: gmail_v1.Schema$Label[]; archiveEstimate: number | null } | AuthError | ApiError> {
+    // Always fresh: label counts are user-facing live data.
+
+    // Archive count is best-effort — auth errors propagate, others yield null.
+    const archiveRes = await gmailBoundary(this.account?.email ?? 'unknown', () =>
       withRetry(() =>
         this.gmail.users.threads.list({
           userId: 'me',
           q: 'in:archive',
           maxResults: 1,
         }),
-      ).catch(() => null),
-    ])
-
-    const counts = await mapConcurrent(labels, async (label) => {
+      ),
+    )
+    if (archiveRes instanceof AuthError) return archiveRes
+    // archiveRes may be ApiError (non-auth failure) — archive count unavailable
+    const labelsResult = await this.listLabels()
+    if (labelsResult instanceof Error) return labelsResult
+
+    // Fetch detailed counts for each label — collect both raw and parsed
+    const rawDetails: gmail_v1.Schema$Label[] = []
+    const counts = await mapConcurrent(labelsResult.parsed, async (label) => {
       if (!label.id) return null
-      try {
-        const detail = await withRetry(() =>
+      // Boundary: labels.get — auth errors abort via mapConcurrent, others skip.
+      const detail = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+        withRetry(() =>
           this.gmail.users.labels.get({
             userId: 'me',
             id: label.id,
           }),
-        )
-        const labelName = (detail.data.name ?? detail.data.id ?? '').toLowerCase()
-        const isTotalLabel = labelName === 'draft' || labelName === 'sent'
-        return {
-          label: labelName === 'draft' ? 'drafts' : labelName,
-          count: Number(isTotalLabel ? detail.data.threadsTotal : detail.data.threadsUnread) || 0,
-        }
-      } catch {
-        return null
+        ),
+      )
+      if (detail instanceof AuthError) return detail
+      if (detail instanceof Error) return null
+      rawDetails.push(detail.data)
+      const labelName = (detail.data.name ?? detail.data.id ?? '').toLowerCase()
+      const isTotalLabel = labelName === 'draft' || labelName === 'sent'
+      return {
+        label: labelName === 'draft' ? 'drafts' : labelName,
+        count: Number(isTotalLabel ? detail.data.threadsTotal : detail.data.threadsUnread) || 0,
       }
     })
 
+    if (counts instanceof Error) return counts
+
     const result = counts.filter((c): c is NonNullable<typeof c> => c !== null)
 
     // Add archive count (same as Zero's count() method)
-    if (archiveRes) {
+    if (!(archiveRes instanceof Error)) {
       result.push({
         label: 'archive',
         count: Number(archiveRes.data.resultSizeEstimate ?? 0),
       })
     }
 
-    return result
+    const archiveEstimate = !(archiveRes instanceof Error) ? Number(archiveRes.data.resultSizeEstimate ?? 0) : null
+
+    return { parsed: result, raw: rawDetails, archiveEstimate }
   }
 
   // =========================================================================
@@ -789,182 +1081,97 @@ export class GmailClient {
     return data.replace(/-/g, '+').replace(/_/g, '/')
   }
 
-  async getMessageAttachments({ messageId }: { messageId: string }) {
-    const res = await withRetry(() =>
-      this.gmail.users.messages.get({
-        userId: 'me',
-        id: messageId,
-      }),
-    )
-
-    const parts = res.data.payload?.parts
-    if (!parts) return []
-
-    const attachmentParts = this.findAttachmentParts(parts)
-
-    const attachments = await mapConcurrent(attachmentParts, async (part) => {
-      const attId = part.body?.attachmentId
-      if (!attId) return null
-      try {
-        const data = await this.getAttachment({ messageId, attachmentId: attId })
-        return {
-          filename: part.filename ?? '',
-          mimeType: part.mimeType ?? '',
-          size: Number(part.body?.size ?? 0),
-          attachmentId: attId,
-          data,
-        }
-      } catch {
-        return null
-      }
-    })
-
-    return attachments.filter((a): a is NonNullable<typeof a> => a !== null)
-  }
-
   // =========================================================================
   // Account / profile
   // =========================================================================
 
-  async getProfile() {
-    const res = await withRetry(() =>
-      this.gmail.users.getProfile({ userId: 'me' }),
+  async getProfile(): Promise<{ emailAddress: string; messagesTotal: number; threadsTotal: number; historyId: string } | AuthError | ApiError> {
+    // Check cache
+    const cached = await this.getCachedProfile()
+    if (cached) return cached
+
+    const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.getProfile({ userId: 'me' }),
+      ),
     )
+    if (res instanceof Error) return res
 
-    return {
+    const profile = {
       emailAddress: res.data.emailAddress ?? '',
       messagesTotal: res.data.messagesTotal ?? 0,
       threadsTotal: res.data.threadsTotal ?? 0,
       historyId: res.data.historyId ?? '',
     }
-  }
 
-  async getEmailAliases() {
-    const profile = await this.getProfile()
-    const primaryEmail = profile.emailAddress
+    // Write cache
+    await this.cacheProfileData(profile)
 
-    const aliases: Array<{ email: string; name?: string; primary: boolean }> = [
-      { email: primaryEmail, primary: true },
-    ]
-
-    try {
-      const settings = await withRetry(() =>
-        this.gmail.users.settings.sendAs.list({ userId: 'me' }),
-      )
-
-      for (const alias of settings.data.sendAs ?? []) {
-        if (alias.isPrimary && alias.sendAsEmail === primaryEmail) continue
-        aliases.push({
-          email: alias.sendAsEmail ?? '',
-          name: alias.displayName ?? undefined,
-          primary: alias.isPrimary ?? false,
-        })
-      }
-    } catch {
-      // sendAs.list may fail if the user doesn't have permission
-    }
-
-    return aliases
+    return profile
   }
 
   // =========================================================================
-  // History / sync
+  // Static: parse raw Google API responses (used by cache readers)
   // =========================================================================
 
-  async listHistory({
-    startHistoryId,
-    labelId,
-    historyTypes,
-  }: {
-    startHistoryId: string
-    labelId?: string
-    historyTypes?: Array<'messageAdded' | 'messageDeleted' | 'labelAdded' | 'labelRemoved'>
-  }) {
-    const allHistory: gmail_v1.Schema$History[] = []
-    let pageToken: string | undefined
-    let latestHistoryId = startHistoryId
-
-    while (true) {
-      const res = await withRetry(() =>
-        this.gmail.users.history.list({
-          userId: 'me',
-          startHistoryId,
-          labelId,
-          historyTypes,
-          pageToken,
-        }),
-      )
+  /** Parse a raw gmail_v1.Schema$Thread (format: full) into ThreadData. */
+  static parseRawThread(raw: gmail_v1.Schema$Thread): ThreadData {
+    const messages = (raw.messages ?? []).map((m) => GmailClient.parseRawMessage(m))
 
-      if (res.data.history) {
-        allHistory.push(...res.data.history)
+    if (messages.length === 0) {
+      return {
+        id: raw.id ?? '',
+        historyId: raw.historyId ?? null,
+        messages: [],
+        subject: '',
+        snippet: '',
+        from: { email: '' },
+        date: '',
+        labelIds: [],
+        hasUnread: false,
+        messageCount: 0,
       }
-      latestHistoryId = res.data.historyId ?? latestHistoryId
-
-      pageToken = res.data.nextPageToken ?? undefined
-      if (!pageToken) break
-    }
-
-    return {
-      history: allHistory,
-      historyId: latestHistoryId,
     }
-  }
 
-  // NOTE: This method wraps Gmail's push notification API (users.watch),
-  // which requires a Google Cloud Pub/Sub topic. Since zele uses borrowed
-  // OAuth credentials (Thunderbird's client ID), we cannot create Pub/Sub
-  // resources on their GCP project. Users would need their own GCP project,
-  // which defeats the zero-config design. The CLI uses History API polling
-  // instead (see src/commands/watch.ts). This method is kept for potential
-  // future use if users bring their own GCP credentials.
-  async watch({
-    topicName,
-    labelIds = ['INBOX'],
-  }: {
-    topicName: string
-    labelIds?: string[]
-  }) {
-    const res = await withRetry(() =>
-      this.gmail.users.watch({
-        userId: 'me',
-        requestBody: {
-          topicName,
-          labelIds,
-        },
-      }),
-    )
+    const latest = messages.findLast((m) => !m.isDraft) ?? messages[messages.length - 1]!
+    const allLabels = [...new Set(messages.flatMap((m) => m.labelIds))]
 
     return {
-      historyId: res.data.historyId ?? '',
-      expiration: res.data.expiration ?? '',
+      id: raw.id ?? '',
+      historyId: raw.historyId ?? null,
+      messages,
+      subject: latest.subject,
+      snippet: latest.snippet,
+      from: latest.from,
+      date: latest.date,
+      labelIds: allLabels,
+      hasUnread: messages.some((m) => m.unread),
+      messageCount: messages.filter((m) => !m.isDraft).length,
     }
   }
 
-  async stopWatch() {
-    await withRetry(() =>
-      this.gmail.users.stop({ userId: 'me' }),
-    )
-  }
-
-  // =========================================================================
-  // Private: message parsing
-  // =========================================================================
-
-  private parseMessage(message: gmail_v1.Schema$Message): ParsedMessage {
+  /** Parse a raw gmail_v1.Schema$Message into ParsedMessage. */
+  static parseRawMessage(message: gmail_v1.Schema$Message): ParsedMessage {
     const headers = message.payload?.headers ?? []
     const labelIds = message.labelIds ?? []
 
-    const fromHeader = this.getHeader(headers, 'from') ?? ''
-    const toHeader = this.getHeader(headers, 'to') ?? ''
-    const ccHeaders = this.getHeaderAll(headers, 'cc')
+    const getHeader = (name: string) =>
+      headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? null
+
+    const fromHeader = getHeader('from') ?? ''
+    const toHeader = getHeader('to') ?? ''
+    const ccHeaders = headers
+      .filter((h) => h.name?.toLowerCase() === 'cc')
+      .map((h) => h.value ?? '')
+      .filter((v) => v.length > 0)
 
-    const { body, mimeType } = this.extractBody(message.payload ?? {})
+    const { body, mimeType, textBody } = GmailClient.extractBodyStatic(message.payload ?? {})
 
     return {
       id: message.id ?? '',
       threadId: message.threadId ?? '',
-      subject: (this.getHeader(headers, 'subject') ?? '(no subject)').replace(/"/g, '').trim(),
-      snippet: message.snippet ?? '',
+      subject: (getHeader('subject') ?? '(no subject)').replace(/"/g, '').trim(),
+      snippet: sanitizeSnippet(message.snippet ?? ''),
       from: parseFrom(fromHeader),
       to: toHeader ? parseAddressList(toHeader) : [],
       cc:
@@ -972,112 +1179,149 @@ export class GmailClient {
           ? ccHeaders.filter((h) => h.trim().length > 0).flatMap((h) => parseAddressList(h))
           : null,
       bcc: [],
-      replyTo: this.getHeader(headers, 'reply-to') ?? undefined,
-      date: this.getHeader(headers, 'date') ?? '',
+      replyTo: getHeader('reply-to') ?? undefined,
+      date: getHeader('date') ?? '',
       labelIds,
       unread: labelIds.includes('UNREAD'),
       starred: labelIds.includes('STARRED'),
       isDraft: labelIds.includes('DRAFT'),
-      messageId: this.getHeader(headers, 'message-id') ?? '',
-      inReplyTo: this.getHeader(headers, 'in-reply-to') ?? undefined,
-      references: this.getHeader(headers, 'references') ?? undefined,
-      listUnsubscribe: this.getHeader(headers, 'list-unsubscribe') ?? undefined,
+      messageId: getHeader('message-id') ?? '',
+      inReplyTo: getHeader('in-reply-to') ?? undefined,
+      references: getHeader('references') ?? undefined,
+      listUnsubscribe: getHeader('list-unsubscribe') ?? undefined,
       body,
       mimeType,
-      attachments: this.extractAttachmentMeta(message.payload?.parts ?? []),
+      textBody,
+      attachments: GmailClient.extractAttachmentMetaStatic(message.payload?.parts ?? []),
     }
   }
 
-  private parseThreadListItem(
-    threadId: string,
-    thread: gmail_v1.Schema$Thread,
-  ): ThreadListItem {
-    const messages = thread.messages ?? []
-    // Use the last non-draft message, or the last message
+  /** Parse raw gmail_v1.Schema$Thread (format: metadata) into ThreadListItem. */
+  static parseRawThreadListItem(raw: gmail_v1.Schema$Thread): ThreadListItem {
+    const messages = raw.messages ?? []
     const latest =
       messages.findLast((m) => !m.labelIds?.includes('DRAFT')) ?? messages[messages.length - 1]
 
     const headers = latest?.payload?.headers ?? []
     const allLabels = [...new Set(messages.flatMap((m) => m.labelIds ?? []))]
 
+    const getHeader = (name: string) =>
+      headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? null
+
     return {
-      id: threadId,
-      historyId: thread.historyId ?? null,
-      snippet: latest?.snippet ?? '',
-      subject: (this.getHeader(headers, 'subject') ?? '(no subject)').replace(/"/g, '').trim(),
-      from: parseFrom(this.getHeader(headers, 'from') ?? ''),
-      date: this.getHeader(headers, 'date') ?? '',
+      id: raw.id ?? '',
+      historyId: raw.historyId ?? null,
+      snippet: sanitizeSnippet(latest?.snippet ?? ''),
+      subject: (getHeader('subject') ?? '(no subject)').replace(/"/g, '').trim(),
+      from: parseFrom(getHeader('from') ?? ''),
+      date: getHeader('date') ?? '',
       labelIds: allLabels,
       unread: allLabels.includes('UNREAD'),
       messageCount: messages.filter((m) => !m.labelIds?.includes('DRAFT')).length,
     }
   }
 
+  /** Parse raw gmail_v1.Schema$Label[] from labels.list into our label objects. */
+  static parseRawLabels(rawLabels: gmail_v1.Schema$Label[]) {
+    return rawLabels.map((label) => ({
+      id: label.id ?? '',
+      name: label.name ?? '',
+      type: (label.type ?? 'user') as 'system' | 'user',
+      messageListVisibility: label.messageListVisibility ?? null,
+      labelListVisibility: label.labelListVisibility ?? null,
+      color: label.color
+        ? {
+            backgroundColor: label.color.backgroundColor ?? '',
+            textColor: label.color.textColor ?? '',
+          }
+        : null,
+    }))
+  }
+
+  /** Parse raw gmail_v1.Schema$Label[] (with counts) into label count objects. */
+  static parseRawLabelCounts(
+    rawLabels: gmail_v1.Schema$Label[],
+    archiveEstimate: number | null,
+  ) {
+    const result = rawLabels
+      .map((detail) => {
+        const labelName = (detail.name ?? detail.id ?? '').toLowerCase()
+        const isTotalLabel = labelName === 'draft' || labelName === 'sent'
+        return {
+          label: labelName === 'draft' ? 'drafts' : labelName,
+          count: Number(isTotalLabel ? detail.threadsTotal : detail.threadsUnread) || 0,
+        }
+      })
+
+    if (archiveEstimate !== null) {
+      result.push({ label: 'archive', count: archiveEstimate })
+    }
+
+    return result
+  }
+
   // =========================================================================
-  // Private: body extraction
+  // Private static: body/attachment extraction (for static parse methods)
   // =========================================================================
 
-  private extractBody(payload: gmail_v1.Schema$MessagePart): {
+  private static extractBodyStatic(payload: gmail_v1.Schema$MessagePart): {
     body: string
     mimeType: string
+    textBody: string | null
   } {
-    // Direct body on payload
     if (payload.body?.data) {
+      const mime = payload.mimeType ?? 'text/plain'
       return {
         body: decodeBase64Url(payload.body.data),
-        mimeType: payload.mimeType ?? 'text/plain',
+        mimeType: mime,
+        textBody: mime === 'text/plain' ? decodeBase64Url(payload.body.data) : null,
       }
     }
 
     if (!payload.parts) {
-      return { body: '', mimeType: 'text/plain' }
+      return { body: '', mimeType: 'text/plain', textBody: null }
     }
 
-    // Prefer text/html, fallback to text/plain
-    const htmlBody = this.findBodyPart(payload.parts, 'text/html')
-    if (htmlBody) {
-      return { body: decodeBase64Url(htmlBody), mimeType: 'text/html' }
+    const htmlData = GmailClient.findBodyPartStatic(payload.parts, 'text/html')
+    const textData = GmailClient.findBodyPartStatic(payload.parts, 'text/plain')
+    const textBody = textData ? decodeBase64Url(textData) : null
+
+    if (htmlData) {
+      return { body: decodeBase64Url(htmlData), mimeType: 'text/html', textBody }
     }
 
-    const textBody = this.findBodyPart(payload.parts, 'text/plain')
-    if (textBody) {
-      return { body: decodeBase64Url(textBody), mimeType: 'text/plain' }
+    if (textData) {
+      return { body: textBody!, mimeType: 'text/plain', textBody }
     }
 
-    // Nested multipart (e.g. multipart/alternative inside multipart/mixed)
     for (const part of payload.parts) {
       if (part.parts) {
-        const nested = this.extractBody(part)
+        const nested = GmailClient.extractBodyStatic(part)
         if (nested.body) return nested
       }
     }
 
-    return { body: '', mimeType: 'text/plain' }
+    return { body: '', mimeType: 'text/plain', textBody: null }
   }
 
-  private findBodyPart(parts: gmail_v1.Schema$MessagePart[], mimeType: string): string | null {
+  private static findBodyPartStatic(parts: gmail_v1.Schema$MessagePart[], mimeType: string): string | null {
     for (const part of parts) {
       if (part.mimeType === mimeType && part.body?.data) {
         return part.body.data
       }
       if (part.parts) {
-        const found = this.findBodyPart(part.parts, mimeType)
+        const found = GmailClient.findBodyPartStatic(part.parts, mimeType)
         if (found) return found
       }
     }
     return null
   }
 
-  // =========================================================================
-  // Private: attachment handling
-  // =========================================================================
-
-  private extractAttachmentMeta(parts: gmail_v1.Schema$MessagePart[]): AttachmentMeta[] {
+  private static extractAttachmentMetaStatic(parts: gmail_v1.Schema$MessagePart[]): AttachmentMeta[] {
     const results: AttachmentMeta[] = []
 
     for (const part of parts) {
       if (part.filename && part.filename.length > 0 && part.body?.attachmentId) {
-        // Skip inline images (content-disposition: inline with content-id)
         const disposition =
           part.headers?.find((h) => h.name?.toLowerCase() === 'content-disposition')?.value ?? ''
         const hasContentId = part.headers?.some((h) => h.name?.toLowerCase() === 'content-id')
@@ -1093,38 +1337,225 @@ export class GmailClient {
         }
       }
 
-      // Recurse into nested parts
       if (part.parts) {
-        results.push(...this.extractAttachmentMeta(part.parts))
+        results.push(...GmailClient.extractAttachmentMetaStatic(part.parts))
       }
     }
 
     return results
   }
 
-  private findAttachmentParts(
-    parts: gmail_v1.Schema$MessagePart[],
-  ): gmail_v1.Schema$MessagePart[] {
-    const results: gmail_v1.Schema$MessagePart[] = []
+  async getEmailAliases(): Promise<Array<{ email: string; name?: string; primary: boolean }> | AuthError | ApiError> {
+    const profile = await this.getProfile()
+    if (profile instanceof Error) return profile
+    const primaryEmail = profile.emailAddress
 
-    for (const part of parts) {
-      if (part.filename && part.filename.length > 0 && part.body?.attachmentId) {
-        // Filter out inline CID images (same logic as Zero's findAttachments)
-        const disposition =
-          part.headers?.find((h) => h.name?.toLowerCase() === 'content-disposition')?.value ?? ''
-        const isInline = disposition.toLowerCase().includes('inline')
-        const hasContentId = part.headers?.some((h) => h.name?.toLowerCase() === 'content-id')
+    const aliases: Array<{ email: string; name?: string; primary: boolean }> = [
+      { email: primaryEmail, primary: true },
+    ]
 
-        if (!isInline || !hasContentId) {
-          results.push(part)
+    // Boundary: sendAs.list — auth errors propagate; permission-denied is expected
+    // (some accounts lack Gmail settings access) and yields primary email only.
+    const settings = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+      withRetry(() =>
+        this.gmail.users.settings.sendAs.list({ userId: 'me' }),
+      ),
+    )
+    if (settings instanceof AuthError) return settings
+    if (settings instanceof Error) return aliases // permission denied — return primary only
+
+    for (const alias of settings.data.sendAs ?? []) {
+      if (alias.isPrimary && alias.sendAsEmail === primaryEmail) continue
+      aliases.push({
+        email: alias.sendAsEmail ?? '',
+        name: alias.displayName ?? undefined,
+        primary: alias.isPrimary ?? false,
+      })
+    }
+
+    return aliases
+  }
+
+  // =========================================================================
+  // History / sync
+  // =========================================================================
+
+  async listHistory({
+    startHistoryId,
+    labelId,
+    historyTypes,
+  }: {
+    startHistoryId: string
+    labelId?: string
+    historyTypes?: Array<'messageAdded' | 'messageDeleted' | 'labelAdded' | 'labelRemoved'>
+  }): Promise<{ history: gmail_v1.Schema$History[]; historyId: string } | AuthError | ApiError> {
+    const allHistory: gmail_v1.Schema$History[] = []
+    let pageToken: string | undefined
+    let latestHistoryId = startHistoryId
+
+    while (true) {
+      const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+        withRetry(() =>
+          this.gmail.users.history.list({
+            userId: 'me',
+            startHistoryId,
+            labelId,
+            historyTypes,
+            pageToken,
+          }),
+        ),
+      )
+      if (res instanceof Error) return res
+
+      if (res.data.history) {
+        allHistory.push(...res.data.history)
+      }
+      latestHistoryId = res.data.historyId ?? latestHistoryId
+
+      pageToken = res.data.nextPageToken ?? undefined
+      if (!pageToken) break
+    }
+
+    return {
+      history: allHistory,
+      historyId: latestHistoryId,
+    }
+  }
+
+  // =========================================================================
+  // Watch: async generator for inbox polling via History API
+  // =========================================================================
+
+  /**
+   * Poll for new messages using the Gmail History API.
+   * Yields WatchEvent objects as new messages arrive.
+   * Handles history seeding, expiry re-seeding, and client-side query filtering.
+   * Persists historyId in the DB so it survives across CLI invocations.
+   */
+  async *watchInbox({
+    folder = 'inbox',
+    intervalMs = 15_000,
+    query,
+    once = false,
+  }: {
+    folder?: string
+    intervalMs?: number
+    query?: string
+    once?: boolean
+  } = {}): AsyncGenerator<WatchEvent> {
+    if (!this.account) throw new MissingDataError({ what: 'authenticated account', resource: 'watchInbox' })
+
+    const filterLabelId = WATCH_FOLDER_LABELS[folder]
+    if (!filterLabelId) {
+      throw new NotFoundError({ resource: `watch folder "${folder}". Supported: ${Object.keys(WATCH_FOLDER_LABELS).join(', ')}` })
+    }
+
+    // Seed historyId — guaranteed non-undefined after this block
+    let historyId: string = await getLastHistoryId(this.account) ?? ''
+    if (!historyId) {
+      const profile = await this.getProfile()
+      if (profile instanceof Error) throw profile
+      historyId = profile.historyId
+      await setLastHistoryId(this.account, historyId)
+    }
+
+    while (true) {
+      // listHistory returns errors as values — check and handle history expiry.
+      const historyResult = await this.listHistory({
+        startHistoryId: historyId,
+        labelId: filterLabelId,
+        historyTypes: ['messageAdded'],
+      })
+
+      if (historyResult instanceof Error) {
+        if (!isHistoryExpired(historyResult)) throw historyResult
+        // historyId expired — Google only keeps ~7 days. Re-seed.
+        const profile = await this.getProfile()
+        if (profile instanceof Error) throw profile
+        historyId = profile.historyId
+        await setLastHistoryId(this.account, historyId)
+        // Retry once after reseed
+        const retryResult = await this.listHistory({ startHistoryId: historyId, labelId: filterLabelId, historyTypes: ['messageAdded'] })
+        if (retryResult instanceof Error) throw retryResult
+        yield* this.pollOnceFromHistory(retryResult, historyId, query, (newId) => { historyId = newId })
+      } else {
+        yield* this.pollOnceFromHistory(historyResult, historyId, query, (newId) => { historyId = newId })
+      }
+
+      if (once) return
+      await new Promise((resolve) => setTimeout(resolve, intervalMs))
+    }
+  }
+
+  /** Single poll tick from pre-fetched history — yields WatchEvents for new messages. */
+  private async *pollOnceFromHistory(
+    historyData: { history: gmail_v1.Schema$History[]; historyId: string },
+    prevHistoryId: string,
+    query: string | undefined,
+    updateHistoryId: (newId: string) => void,
+  ): AsyncGenerator<WatchEvent> {
+    const { history, historyId: newHistoryId } = historyData
+
+    if (newHistoryId !== prevHistoryId) {
+      updateHistoryId(newHistoryId)
+      await setLastHistoryId(this.account!, newHistoryId)
+    }
+
+    if (history.length === 0) return
+
+    // Collect unique message IDs from messageAdded events
+    const seenIds = new Set<string>()
+    const messageIds: string[] = []
+
+    for (const entry of history) {
+      for (const added of entry.messagesAdded ?? []) {
+        const id = added.message?.id
+        if (id && !seenIds.has(id)) {
+          seenIds.add(id)
+          messageIds.push(id)
         }
       }
-      if (part.parts) {
-        results.push(...this.findAttachmentParts(part.parts))
+    }
+
+    if (messageIds.length === 0) return
+
+    // Hydrate messages with metadata (bounded concurrency).
+    // getMessage returns errors as values — auth errors abort via mapConcurrent,
+    // 404s (message deleted between history and hydration) are skipped.
+    const hydrated = await mapConcurrent(messageIds, async (msgId) => {
+      const msg = await this.getMessage({ messageId: msgId, format: 'metadata' })
+      if (msg instanceof AuthError) return msg // abort batch
+      if (msg instanceof Error) return null    // skip this message
+      if ('raw' in msg) return null
+      if (query && !matchesQuery(msg, query)) return null
+      return msg
+    })
+    if (hydrated instanceof Error) throw hydrated // propagate to generator consumer
+
+    for (const msg of hydrated) {
+      if (!msg) continue
+      yield {
+        account: this.account!,
+        type: 'new_message',
+        message: msg,
+        threadId: msg.threadId,
       }
     }
+  }
 
-    return results
+  // =========================================================================
+  // Private: message parsing (delegates to static methods)
+  // =========================================================================
+
+  private parseMessage(message: gmail_v1.Schema$Message): ParsedMessage {
+    return GmailClient.parseRawMessage(message)
+  }
+
+  private parseThreadListItem(
+    threadId: string,
+    thread: gmail_v1.Schema$Thread,
+  ): ThreadListItem {
+    return GmailClient.parseRawThreadListItem({ ...thread, id: threadId })
   }
 
   // =========================================================================
@@ -1211,11 +1642,13 @@ export class GmailClient {
   // =========================================================================
 
   /** Look up a label ID by name. Returns null if not found (never creates). */
-  private async lookupLabelId(labelNameOrId: string): Promise<string | null> {
+  private async lookupLabelId(labelNameOrId: string): Promise<string | null | AuthError | ApiError> {
     if (SYSTEM_LABEL_IDS.has(labelNameOrId)) return labelNameOrId
     if (this.labelIdCache[labelNameOrId]) return this.labelIdCache[labelNameOrId]!
 
-    const labels = await this.listLabels()
+    const labelsResult = await this.listLabels()
+    if (labelsResult instanceof Error) return labelsResult
+    const { parsed: labels } = labelsResult
     const match = labels.find((l) => l.name.toLowerCase() === labelNameOrId.toLowerCase())
     if (match) {
       this.labelIdCache[labelNameOrId] = match.id
@@ -1226,11 +1659,13 @@ export class GmailClient {
   }
 
   /** Resolve a label ID by name, auto-creating if it doesn't exist. */
-  private async resolveLabelId(labelNameOrId: string): Promise<string> {
+  private async resolveLabelId(labelNameOrId: string): Promise<string | AuthError | ApiError> {
     if (SYSTEM_LABEL_IDS.has(labelNameOrId)) return labelNameOrId
     if (this.labelIdCache[labelNameOrId]) return this.labelIdCache[labelNameOrId]!
 
-    const labels = await this.listLabels()
+    const labelsResult = await this.listLabels()
+    if (labelsResult instanceof Error) return labelsResult
+    const { parsed: labels } = labelsResult
     const match = labels.find((l) => l.name.toLowerCase() === labelNameOrId.toLowerCase())
     if (match) {
       this.labelIdCache[labelNameOrId] = match.id
@@ -1309,17 +1744,20 @@ export class GmailClient {
   private async getMessageIdsForThreads(
     threadIds: string[],
     filter?: (labelIds: string[]) => boolean,
-  ) {
+  ): Promise<string[] | AuthError | ApiError> {
     const allIds: string[] = []
 
-    await mapConcurrent(threadIds, async (threadId) => {
-      const res = await withRetry(() =>
-        this.gmail.users.threads.get({
-          userId: 'me',
-          id: threadId,
-          format: 'metadata',
-        }),
+    const result = await mapConcurrent(threadIds, async (threadId) => {
+      const res = await gmailBoundary(this.account?.email ?? 'unknown', () =>
+        withRetry(() =>
+          this.gmail.users.threads.get({
+            userId: 'me',
+            id: threadId,
+            format: 'metadata',
+          }),
+        ),
       )
+      if (res instanceof Error) return res
 
       for (const msg of res.data.messages ?? []) {
         if (!msg.id) continue
@@ -1327,6 +1765,7 @@ export class GmailClient {
         allIds.push(msg.id)
       }
     })
+    if (result instanceof Error) return result
 
     return [...new Set(allIds)]
   }
@@ -1387,3 +1826,169 @@ export class GmailClient {
     )
   }
 }
+
+// ---------------------------------------------------------------------------
+// Watch: folder label mapping
+// ---------------------------------------------------------------------------
+
+const WATCH_FOLDER_LABELS: Record<string, string> = {
+  inbox: 'INBOX',
+  sent: 'SENT',
+  trash: 'TRASH',
+  spam: 'SPAM',
+  starred: 'STARRED',
+  drafts: 'DRAFT',
+}
+
+// ---------------------------------------------------------------------------
+// Watch: sync state persistence (historyId in DB)
+// ---------------------------------------------------------------------------
+
+async function getLastHistoryId(account: AccountId): Promise<string | undefined> {
+  const prisma = await getPrisma()
+  const row = await prisma.syncState.findUnique({
+    where: { email_appId_key: { email: account.email, appId: account.appId, key: 'history_id' } },
+  })
+  return row?.value
+}
+
+async function setLastHistoryId(account: AccountId, historyId: string): Promise<void> {
+  const prisma = await getPrisma()
+  await prisma.syncState.upsert({
+    where: { email_appId_key: { email: account.email, appId: account.appId, key: 'history_id' } },
+    create: { email: account.email, appId: account.appId, key: 'history_id', value: historyId },
+    update: { value: historyId },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Watch: history expiry detection
+// ---------------------------------------------------------------------------
+
+function isHistoryExpired(err: any): boolean {
+  const status = err?.code ?? err?.status ?? err?.response?.status
+  if (status === 404) return true
+  if (status === 400) {
+    const message = err?.message ?? err?.response?.data?.error?.message ?? ''
+    if (message.includes('historyId')) return true
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Watch: client-side Gmail query matching
+// ---------------------------------------------------------------------------
+// The History API doesn't support server-side query filtering, so we parse
+// common Gmail search operators and match against message metadata.
+//
+// Supported operators: from:, to:, cc:, subject:, is:unread/read/starred,
+// has:attachment, and plain text (matches subject + from).
+// Multiple terms are AND-ed together. Quoted phrases and negation supported.
+//
+// Limitations vs full Gmail search:
+// - label: not supported (labelIds are API IDs like Label_123, not names)
+// - has:attachment uses Content-Type heuristic (metadata format lacks parts)
+// - OR, {}, newer_than:, older_than:, etc. are server-only — warned & skipped
+//
+// See https://support.google.com/mail/answer/7190 for the full Gmail spec.
+// ---------------------------------------------------------------------------
+
+const SERVER_ONLY_OPERATORS = new Set([
+  'in', 'label', 'after', 'before', 'newer_than', 'older_than',
+  'filename', 'size', 'larger', 'smaller', 'deliveredto', 'rfc822msgid',
+  'list', 'category',
+])
+
+const SUPPORTED_OPERATORS = new Set([
+  'from', 'to', 'cc', 'subject', 'is', 'has',
+])
+
+interface QueryTerm {
+  operator: string | null
+  value: string
+  negated: boolean
+}
+
+const warnedOperators = new Set<string>()
+
+function matchesQuery(msg: ParsedMessage, query: string): boolean {
+  const terms = parseQueryTerms(query)
+  return terms.every((term) => matchesTerm(msg, term))
+}
+
+function parseQueryTerms(query: string): QueryTerm[] {
+  const terms: QueryTerm[] = []
+  const regex = /(-?)(?:(\w+):)?(?:"([^"]*)"|([\S]+))/gi
+  let match: RegExpExecArray | null
+
+  while ((match = regex.exec(query)) !== null) {
+    const negated = match[1] === '-'
+    const rawOperator = match[2]?.toLowerCase() ?? null
+    const value = (match[3] ?? match[4] ?? '').toLowerCase()
+    if (!value) continue
+
+    if (!rawOperator && value === 'or') continue
+
+    if (rawOperator && SERVER_ONLY_OPERATORS.has(rawOperator)) {
+      if (!warnedOperators.has(rawOperator)) {
+        warnedOperators.add(rawOperator)
+        console.error(`# --query: "${rawOperator}:" is a server-only operator (use "mail search" instead), skipping`)
+      }
+      continue
+    }
+
+    if (rawOperator && !SUPPORTED_OPERATORS.has(rawOperator)) {
+      if (!warnedOperators.has(rawOperator)) {
+        warnedOperators.add(rawOperator)
+        console.error(`# --query: unknown operator "${rawOperator}:", skipping`)
+      }
+      continue
+    }
+
+    terms.push({ operator: rawOperator, value, negated })
+  }
+
+  return terms
+}
+
+function senderMatches(sender: { name?: string; email: string }, value: string): boolean {
+  const full = `${sender.name ?? ''} ${sender.email}`.toLowerCase()
+  return full.includes(value)
+}
+
+function matchesTerm(msg: ParsedMessage, term: QueryTerm): boolean {
+  let result: boolean
+
+  switch (term.operator) {
+    case 'from':
+      result = senderMatches(msg.from, term.value)
+      break
+    case 'to':
+      result = msg.to.some((r) => senderMatches(r, term.value))
+      break
+    case 'cc':
+      result = (msg.cc ?? []).some((r) => senderMatches(r, term.value))
+      break
+    case 'subject':
+      result = msg.subject.toLowerCase().includes(term.value)
+      break
+    case 'is':
+      if (term.value === 'unread') result = msg.unread
+      else if (term.value === 'read') result = !msg.unread
+      else if (term.value === 'starred') result = msg.starred
+      else result = false
+      break
+    case 'has':
+      if (term.value === 'attachment') result = msg.mimeType.includes('multipart/mixed')
+      else result = false
+      break
+    default: {
+      const subject = msg.subject.toLowerCase()
+      const from = `${msg.from.name ?? ''} ${msg.from.email}`.toLowerCase()
+      result = subject.includes(term.value) || from.includes(term.value)
+      break
+    }
+  }
+
+  return term.negated ? !result : result
+}