pikuri-thunderbird 0.1.0

data/lib/pikuri/thunderbird/calendar_search.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Thunderbird
+    # The +thunderbird_calendar_search+ tool — search local + cached
+    # Thunderbird calendars by title/description/location. Inbound-only; its
+    # read half is +thunderbird_calendar_read+.
+    #
+    # Recall-first (words OR-matched, ranked by matched-word count) on purpose,
+    # mirroring {MailSearch}: tighten it to AND and the model — primed by the
+    # forgiving mail search — reads the sparser hits as "no such event".
+    #
+    # == Empty-corpus guidance (Q6)
+    #
+    # Thunderbird keeps a CalDAV calendar's events *in memory only* unless
+    # "Offline Support" is enabled, so a calendar can look full in the UI yet
+    # have nothing on disk. When no events are cached, this tool returns a
+    # self-fixing observation telling the user the one-click fix rather than a
+    # bare "no results" — and the same fact rides the description, so the LLM
+    # can advise proactively before any empty search.
+    #
+    # Sharing: +P_shared_locked+ — no state of its own, and the {Calendar}
+    # backend it queries locks; see that class's +== Sharing+.
+    class CalendarSearch < Pikuri::Tool
+      DEFAULT_LIMIT = 15
+      MAX_LIMIT = 50
+
+      # @return [String] the enable-Offline-Support guidance, reused by the
+      #   description and the empty-corpus observation.
+      OFFLINE_HINT =
+        'No calendar events are cached to disk. If Thunderbird shows events but ' \
+        'search finds none, enable Offline Support on each calendar ' \
+        '(right-click the calendar → Properties → Offline Support) so its events ' \
+        'are stored locally and become searchable.'
+
+      # @return [String] opencode-shape description.
+      DESCRIPTION = <<~DESC
+        Search the user's local and cached Thunderbird calendars by title, description or location.
+
+        Usage:
+        - Free-text query and/or a date range — both optional; supply at least one.
+        - To list everything on a day or in a span (e.g. "tomorrow's meetings"), pass a broad or empty query with after/before; a single day is after=before=that date.
+        - Each query word is matched independently (across title, description, and location) and events matching more of the words rank first — so extra words broaden the search and surface partial matches, they don't require every word. Matching ignores accents and case. To narrow, add a date range rather than more words.
+        - Optionally restrict to recurring events (a repeating series) or single one-off events with the recurrence filter; omit it to get both.
+        - Reads Thunderbird's on-disk calendar store — it never connects to any calendar server.
+        - Only events cached to disk are visible. A CalDAV calendar keeps events in memory unless its "Offline Support" is enabled (right-click the calendar → Properties → Offline Support); if a search comes back empty but the calendar looks full, that setting is why.
+        - Read an event in full with thunderbird_calendar_read.
+      DESC
+
+      # @param backend [Calendar] the calendar backend.
+      # @return [CalendarSearch]
+      def initialize(backend:)
+        @backend = backend
+        super(
+          name: 'thunderbird_calendar_search',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.optional_string :query, 'Words to find in event title/description/location, e.g. "standup". Omit to list everything in the date range.'
+            p.optional_string :after, 'Only events on/after this date, e.g. "2026-01-01".'
+            p.optional_string :before, 'Only events on/before this date, e.g. "2026-12-31".'
+            p.optional_enum :recurrence, 'Restrict by repetition: "recurring" for repeating series only, "single" for one-off events only. Omit for both.', values: %w[recurring single]
+            p.optional_integer :limit, "Max events (default #{DEFAULT_LIMIT}, max #{MAX_LIMIT}), e.g. 15."
+          },
+          execute: lambda { |query: nil, after: nil, before: nil, recurrence: nil, limit: DEFAULT_LIMIT|
+            CalendarSearch.run_search(backend: @backend, query:, after:, before:, recurrence:, limit:)
+          },
+          trifecta_legs: Pikuri::Thunderbird::INBOUND_LEGS
+        )
+      end
+
+      # @param recurrence [String, nil] +"recurring"+, +"single"+, or +nil+ for
+      #   both (mapped to the backend's tri-state +recurring:+ flag).
+      # @return [String]
+      def self.run_search(backend:, query:, after:, before:, recurrence: nil, limit:)
+        # Refuse a match-everything call: with no query and no date bound this
+        # would dump every cached event. "What's on my calendar" should name a
+        # span — steer the model to add after/before (e.g. this week). A lone
+        # recurrence filter is still too broad to stand in for a span.
+        if [query, after, before].all? { |v| v.to_s.strip.empty? }
+          return 'Error: give a query and/or a date range (after/before) to search for'
+        end
+
+        limit = limit.to_i.clamp(1, MAX_LIMIT)
+        recurring = { 'recurring' => true, 'single' => false }[recurrence]
+        # Fetch one past the cap so a full page is distinguishable from an
+        # exhausted calendar (see {MailSearch.run_search}); limit+1 back means
+        # more exist and {header} says so, rather than let the model read a
+        # full page as the whole calendar.
+        hits = backend.search(query:, limit: limit + 1, recurring:,
+                              after: DateHelpers.parse_after(after), before: DateHelpers.parse_before(before))
+        return offline_or_no_match(backend, query) if hits.empty?
+
+        has_more = hits.size > limit
+        hits = hits.first(limit)
+        [header(shown: hits.size, has_more:), *hits.map { |h| render(h) }].join("\n\n")
+      rescue ArgumentError => e
+        "Error: bad date filter (#{e.message})."
+      end
+
+      # The leading line: affirm completeness when every event fit ("all
+      # shown"), or — when capped — name the two levers that get the rest.
+      # Adding query words is *not* one (words are OR-matched, so they widen);
+      # mirrors {MailSearch.header}, the recall-first principle riding the
+      # prompt snippet ({Extension::INBOUND_USAGE}).
+      #
+      # @param shown [Integer] events actually rendered.
+      # @param has_more [Boolean] whether more matched than fit.
+      # @return [String]
+      def self.header(shown:, has_more:)
+        return "#{shown} event#{shown == 1 ? '' : 's'} (all shown):" unless has_more
+
+        "Top #{shown} events — more exist. To see them, raise limit (up to " \
+          "#{MAX_LIMIT}) or add an after/before date range. Adding query words " \
+          'matches more events (any word), so it will not narrow.'
+      end
+      private_class_method :header
+
+      # Distinguish "no events cached at all" (fixable) from "no match". An
+      # empty query is a date-range listing, so its no-match line names the
+      # range rather than an empty query string.
+      #
+      # @return [String]
+      def self.offline_or_no_match(backend, query)
+        return OFFLINE_HINT if backend.event_count.zero?
+
+        query.to_s.strip.empty? ? 'No events found in that date range.' : "No matching events found for #{query.inspect}."
+      end
+      private_class_method :offline_or_no_match
+
+      # @return [String]
+      def self.render(event)
+        loc = event[:location].to_s.strip
+        tail = +''
+        tail << "  |  where: #{loc}" unless loc.empty?
+        tail << '  |  recurring' if event[:recurring]
+        <<~EV.chomp
+          #{event[:title].to_s.strip.empty? ? '(untitled)' : event[:title].strip}
+            when: #{DateHelpers.when_label(event)}#{tail}
+            id: #{event[:event_id]}
+        EV
+      end
+      private_class_method :render
+    end
+  end
+end

data/lib/pikuri/thunderbird/compose_guard.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+
+module Pikuri
+  module Thunderbird
+    # The mechanical outbound guard for {MailCompose} — deterministic, never an
+    # AI verdict. The compose window is a strong human barrier on the *visible*
+    # (the recipient, gross body content) but soft on the *invisible* (control
+    # bytes, look-alike domains, subtle body-exfil), so the machine covers what
+    # the eye can't. It runs *before* {MailtoUri} encodes anything.
+    #
+    #   ComposeGuard.new(backend: contacts).check(to: 'a@acme.com', body: 'Hi')
+    #   # => #<Verdict ok=true, to=["a@acme.com"], notes=[...]>
+    #
+    # Two tiers:
+    #
+    # * *Hard reject* — a suspicious **body** fails closed (nothing is handed
+    #   off; the human retypes in Thunderbird), because an agent-authored
+    #   outbound body has no honest reason to carry control/bidi/zero-width/
+    #   homoglyph characters. A suspicious **subject or address** is dropped
+    #   (omitted from the draft) for the human to retype — addresses additionally
+    #   must be ASCII-only and non-punycode (an +xn--+ domain is a pre-encoded
+    #   homoglyph that would otherwise pass {Pikuri::Sanitizer}'s mixed-script
+    #   check as pure ASCII).
+    # * *Soft warn* — the correspondence-graph novelty check: a recipient domain
+    #   the user has never exchanged mail with (per {Gloda::Contacts#domains_seen}) stays
+    #   in the draft but earns a loud note urging out-of-band verification. A
+    #   hard reject here would fire on every genuinely-new correspondent. A body
+    #   carrying an *encoded-looking blob* (a long base64, hex or base32 run —
+    #   see {#body_blob_note}) likewise stays but earns a located note.
+    #
+    # == Why per-field address omission
+    #
+    # If any address in a field (To/Cc/Bcc) fails the hard checks, the *whole*
+    # field is dropped, not just the bad address — "the recipient is the attack,"
+    # so forcing a full retype of a tainted field beats silently keeping the
+    # addresses that happened to pass beside it.
+    #
+    # Immutable.
+    class ComposeGuard
+      LOGGER = Pikuri.logger_for('Thunderbird::ComposeGuard')
+
+      # Shortest token the blob spotter sums toward a body warning. Below 16 the
+      # three-class test gets flaky and honest engineering tokens (short SHAs,
+      # build IDs) creep in — and since the sum is body-wide, that means alarm
+      # fatigue. See {#body_blob_note}.
+      BLOB_TOKEN_MIN = 16
+
+      # Joined blob-token length at/above which the body earns the encoded-blob
+      # note. A 32-byte key is 44 base64 chars, comfortably over. See {#body_blob_note}.
+      BLOB_JOIN_MIN = 32
+
+      # The standard base64 alphabet. Excludes base64url's +-+/+_+ on purpose:
+      # those collide with hyphenated labels and +snake_case+ identifiers common
+      # in honest mail, whereas +++ +/+ +=+ never appear in prose tokens. Cost:
+      # base64url/JWT-shaped payloads slip by — accepted, per {#body_blob_note}.
+      BLOB_ALPHABET = %r{\A[A-Za-z0-9+/=]+\z}
+
+      # Single-case hex — what a key already wears on disk. Mixed case is absent
+      # on purpose: that is three-class, so {BLOB_ALPHABET} has it. No interior
+      # +-+, so a dashed UUID matches nothing here.
+      HEX_ALPHABET = /\A(?:[a-f0-9]+|[A-F0-9]+)\z/
+
+      # RFC-4648 base32; single-case like {HEX_ALPHABET}, so it shares the
+      # longer thresholds below.
+      BASE32_ALPHABET = /\A[A-Z2-7]+=*\z/
+
+      # {BLOB_TOKEN_MIN}'s twin for the single-alphabet encodings, doubled: a
+      # one-alphabet run is likelier to be an honest identifier than a base64
+      # run is, so it must be twice as long to count.
+      SINGLE_CLASS_TOKEN_MIN = 32
+
+      # {BLOB_JOIN_MIN}'s twin, in the only gap available: above a full git
+      # SHA-1 (40), below a 32-byte key in base32 (52) or hex (64). Accepts one
+      # irreducible false positive — a lone SHA-256 checksum warns, since a
+      # 256-bit hash and a 256-bit key are the same string (+D_blob_spotter_alphabets+).
+      SINGLE_CLASS_JOIN_MIN = 48
+
+      # The outcome of checking one compose request.
+      #
+      # * +ok+ — +false+ only when a body flag forced a fail-closed abort.
+      # * +error+ — the fail-closed message ({String}), present iff +ok+ is false.
+      # * +to+ / +cc+ / +bcc+ — {Array}<{String}> addresses that passed the hard
+      #   checks (rejected fields come back empty).
+      # * +subject+ — the {String} subject, or +nil+ (absent, or dropped on a flag).
+      # * +body+ — the {String} body when +ok+ (guaranteed clean), else +nil+.
+      # * +notes+ — {Array}<{String}> human-facing warnings (dropped fields +
+      #   novelty) for the observation.
+      Verdict = Data.define(:ok, :error, :to, :cc, :bcc, :subject, :body, :notes)
+
+      # @param backend [Gloda::Contacts, nil] contact resolver for the novelty
+      #   check; +nil+ disables it (the verdict then carries a "couldn't check"
+      #   note).
+      # @return [ComposeGuard]
+      def initialize(backend: nil)
+        @backend = backend
+      end
+
+      # Check one compose request and return a {Verdict}.
+      #
+      # @param to [String] recipient address(es), comma-separated.
+      # @param cc [String, nil] Cc address(es), comma-separated.
+      # @param bcc [String, nil] Bcc address(es), comma-separated.
+      # @param subject [String, nil] subject line.
+      # @param body [String] plain-text body.
+      # @return [Verdict]
+      def check(to:, body:, cc: nil, bcc: nil, subject: nil)
+        body_res = Pikuri::Sanitizer.sanitize(body.to_s)
+        unless body_res.warnings.empty?
+          return Verdict.new(ok: false, error: body_fail_message(body_res),
+                             to: [], cc: [], bcc: [], subject: nil, body: nil, notes: [])
+        end
+
+        notes = []
+        kept_to  = check_addresses('To', to, notes)
+        kept_cc  = check_addresses('Cc', cc, notes)
+        kept_bcc = check_addresses('Bcc', bcc, notes)
+        novelty_note(kept_to + kept_cc + kept_bcc, notes)
+        body_blob_note(body.to_s, notes)
+
+        Verdict.new(ok: true, error: nil, to: kept_to, cc: kept_cc, bcc: kept_bcc,
+                    subject: check_subject(subject, notes),
+                    body: body.to_s.empty? ? nil : body, notes: notes)
+      end
+
+      private
+
+      # @return [String] the fail-closed observation naming the flagged classes.
+      def body_fail_message(result)
+        kinds = result.warnings.map(&:kind).join(', ')
+        "won't compose this message — the body contains characters an outbound " \
+          "mail has no honest reason to carry (#{kinds}). If this is genuinely " \
+          'what you want to send, type it directly in Thunderbird.'
+      end
+
+      # @return [String, nil] the subject when clean, +nil+ when absent or dropped.
+      def check_subject(subject, notes)
+        return nil if subject.nil? || subject.to_s.empty?
+
+        warnings = Pikuri::Sanitizer.sanitize(subject).warnings
+        return subject if warnings.empty?
+
+        notes << "Subject omitted (suspicious characters: #{warnings.map(&:kind).join(', ')}) — " \
+                 'type it in the compose window.'
+        nil
+      end
+
+      # Split a comma-separated address field and keep it only if *every*
+      # address passes the hard checks; otherwise drop the whole field.
+      #
+      # @return [Array<String>] the vetted addresses, or +[]+ if dropped/absent.
+      def check_addresses(label, field, notes)
+        return [] if field.nil? || field.to_s.strip.empty?
+
+        addrs = field.to_s.split(',').map(&:strip).reject(&:empty?)
+        bad = addrs.reject { |a| address_ok?(a) }
+        return addrs if bad.empty?
+
+        notes << "#{label} omitted (couldn't safely include #{bad.map(&:inspect).join(', ')}) — " \
+                 'type the recipient(s) in the compose window.'
+        []
+      end
+
+      # @return [Boolean] whether one address is safe to pre-fill: ASCII-only,
+      #   no +xn--+ punycode, and clean under {Pikuri::Sanitizer}.
+      def address_ok?(addr)
+        return false unless addr.ascii_only?
+        return false if addr.downcase.include?('xn--')
+
+        Pikuri::Sanitizer.sanitize(addr).warnings.empty?
+      end
+
+      # Append the correspondence-graph novelty warning for any recipient domain
+      # the user has no prior mail with. Best-effort: degrades to a "couldn't
+      # check" note when the backend is absent or its identity schema differs
+      # from the probed shape (the schema is unverified across TB versions).
+      #
+      # @return [void]
+      def novelty_note(addrs, notes)
+        domains = addrs.map { |a| a.split('@', 2).last.to_s.downcase }.reject(&:empty?).uniq
+        return if domains.empty?
+
+        unless @backend
+          notes << "Couldn't check whether you've mailed these recipients before " \
+                   '(mail index unavailable) — double-check the address is correct.'
+          return
+        end
+
+        seen = @backend.domains_seen(domains)
+        novel = domains - seen
+        return if novel.empty?
+
+        notes << "You have no prior mail with #{novel.join(', ')}. If you expected a " \
+                 'familiar contact, watch for a look-alike domain and verify out of ' \
+                 'band (not by replying to a suspect message).'
+      rescue SQLite3::SQLException => e
+        LOGGER.warn("recipient-novelty check unavailable: #{e.message}")
+        notes << "Couldn't check whether you've mailed these recipients before — " \
+                 'double-check the address is correct.'
+      end
+
+      # Soft-warn when the body carries an encoded-looking blob: an encoded dump
+      # of a secret is the easiest high-bandwidth exfil, all-printable-ASCII so
+      # it passes the {Pikuri::Sanitizer} gate while the human skims past the
+      # gibberish. A flagged body still composes — the note only aims the eye:
+      #
+      #   body_blob_note("ship it:\naGVsbG8gd29ybGQgT3BlbkFJc2VjcmV0", notes)
+      #   # appends: "Line 2 onward contains encoded-looking content
+      #   #           (aGVsbG8gd29ybGQgT3BlbkFJ…, 32 chars total) — verify you
+      #   #           meant to send this; an encoded blob is how a secret leaks
+      #   #           past a skim."
+      #
+      # @param body [String] the plain-text body (already {Pikuri::Sanitizer}-clean).
+      # @param notes [Array<String>] accumulator, appended to in place.
+      # @return [void]
+      #
+      # == Implementation details
+      #
+      # The two chunk shapes ({#blob_kind}) carry independent thresholds and the
+      # body warns on whichever trips first. Summing body-wide rather than over
+      # one contiguous run folds space-split and word-interleaved payloads back
+      # together for free: cover words fail both gates and drop out.
+      #
+      # A paste / dumb-attack guard, *not* an exfil control — a prompt-injected
+      # model can add "split it into 15-char pieces" for free and walk under
+      # every threshold here. Hence soft-warn, and the minimums kept high to stay
+      # quiet on engineering mail; the irreversible-send compose window is the
+      # real backstop, so err toward not warning. Don't recast this as "closes
+      # the encoded-blob channel."
+      def body_blob_note(body, notes)
+        hits = blob_hits(body)
+        [[:mixed, BLOB_JOIN_MIN], [:single, SINGLE_CLASS_JOIN_MIN]].each do |kind, join_min|
+          matched = hits.select { |hit| hit[:kind] == kind }
+          total = matched.sum { |hit| hit[:token].length }
+          next if total < join_min
+
+          first = matched.first
+          notes << "Line #{first[:line]} onward contains encoded-looking content " \
+                   "(#{first[:token][0, 24]}…, #{total} chars total) — verify you meant " \
+                   'to send this; an encoded blob is how a secret leaks past a skim.'
+          break
+        end
+      end
+
+      # @param body [String] the plain-text body.
+      # @return [Array<Hash>] +{line: Integer, token: String, kind: Symbol}+ per
+      #   blob-shaped token, in reading order.
+      def blob_hits(body)
+        body.split("\n").each_with_index.flat_map do |line, i|
+          line.split(/\s+/).filter_map do |raw|
+            tok = raw.gsub(%r{\A[^A-Za-z0-9+/=]+|[^A-Za-z0-9+/=]+\z}, '')
+            kind = blob_kind(tok)
+            { line: i + 1, token: tok, kind: kind } if kind
+          end
+        end
+      end
+
+      # @param tok [String] a whitespace-delimited token, sentence-punctuation stripped.
+      # @return [Symbol, nil] +:mixed+ for >= {BLOB_TOKEN_MIN} chars of
+      #   {BLOB_ALPHABET} carrying upper *and* lower *and* a digit — encoder
+      #   churn no prose word (one script), Capitalized word (two), or
+      #   +invoice20260722+ slug (two) shows; +:single+ for >=
+      #   {SINGLE_CLASS_TOKEN_MIN} chars of {HEX_ALPHABET} or
+      #   {BASE32_ALPHABET}; +nil+ when neither fits. The digit is required
+      #   either way — it is what keeps an ALL-CAPS sentence out of
+      #   {BASE32_ALPHABET} and a +deadbeef+-ish word out of {HEX_ALPHABET}.
+      def blob_kind(tok)
+        return nil unless tok.match?(/[0-9]/)
+
+        if tok.length >= BLOB_TOKEN_MIN && tok.match?(BLOB_ALPHABET) &&
+           tok.match?(/[A-Z]/) && tok.match?(/[a-z]/)
+          :mixed
+        elsif tok.length >= SINGLE_CLASS_TOKEN_MIN &&
+              (tok.match?(HEX_ALPHABET) || tok.match?(BASE32_ALPHABET))
+          :single
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/thunderbird/contact_search.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Thunderbird
+    # The +thunderbird_contact_search+ tool — resolve a person's name (or a
+    # partial address) to the email address(es) the user has actually
+    # corresponded with, ranked by familiarity. Inbound-only (a pure read,
+    # no egress leg), registered whenever {Gloda} is present — like mail
+    # search, and independently useful ("what's Jon's address?").
+    #
+    # Its reason to exist is {MailCompose}: the user says "email Jon Snow a
+    # summary," the model has a *name* and compose needs an *address*. Rather
+    # than invent one (a mis-send / exfil risk) or stop to ask, resolve it
+    # against the user's own correspondence graph via {Gloda::Contacts#resolve}.
+    # It returns *ranked candidates and never auto-picks* — a look-alike
+    # sender of received mail can surface, so the human reviewing the To field
+    # stays the last line (same posture as {ComposeGuard}).
+    #
+    # Sharing: +P_shared_locked+ — no state of its own, and the {Gloda}
+    # backend it queries locks; see that class's +== Sharing+.
+    class ContactSearch < Pikuri::Tool
+      # @return [Integer] default / max candidates returned (a short
+      #   disambiguation list, not a mailbox scan).
+      DEFAULT_LIMIT = 5
+      MAX_LIMIT = 15
+
+      # @return [String] opencode-shape description.
+      DESCRIPTION = <<~DESC
+        Resolve a person's name (or a partial address) to their email address(es), drawn from the user's own Thunderbird correspondence history.
+
+        Usage:
+        - Give a name ("Jon Snow") or a fragment ("jon", "acme.com") to find who the user has actually mailed or received mail from.
+        - Returns ranked candidates as Name <address> with a familiarity signal — addresses the user has sent mail to rank highest — and never picks one for you.
+        - Use it to fill a recipient before drafting mail, then confirm the address with the user: a look-alike sender can appear in received mail, so resolution alone is not proof.
+        - Reads Thunderbird's own local index only; it never connects to any server.
+      DESC
+
+      # @param backend [Gloda::Contacts] the contact resolver.
+      # @return [ContactSearch]
+      def initialize(backend:)
+        @backend = backend
+        super(
+          name: 'thunderbird_contact_search',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :query, 'A name or partial address to resolve, e.g. "Jon Snow".'
+            p.optional_integer :limit, "Max candidates (default #{DEFAULT_LIMIT}, max #{MAX_LIMIT}), e.g. 5."
+          },
+          execute: lambda { |query:, limit: DEFAULT_LIMIT|
+            ContactSearch.run_search(backend: @backend, query:, limit:)
+          },
+          trifecta_legs: Pikuri::Thunderbird::INBOUND_LEGS
+        )
+      end
+
+      # @return [String] formatted ranked candidates or a no-match line.
+      def self.run_search(backend:, query:, limit:)
+        limit = limit.to_i.clamp(1, MAX_LIMIT)
+        candidates = backend.resolve(query:, limit:)
+        return "No contacts found matching #{query.inspect}." if candidates.empty?
+
+        header = "#{candidates.size} contact#{candidates.size == 1 ? '' : 's'} (best first):"
+        [header, *candidates.map { |c| render(c) }].join("\n\n")
+      end
+
+      # @param c [Hash] one candidate from {Gloda::Contacts#resolve}.
+      # @return [String]
+      def self.render(c)
+        who = c[:name].to_s.empty? ? c[:address] : "#{c[:name]} <#{c[:address]}>"
+        <<~CAND.chomp
+          #{who}
+            #{familiarity(c)}
+        CAND
+      end
+      private_class_method :render
+
+      # @param c [Hash]
+      # @return [String] the one-line familiarity signal (Sent history is the
+      #   established-contact tell; received-only asks for a check).
+      def self.familiarity(c)
+        if c[:sent].positive?
+          "you have sent mail to this address #{c[:sent]}× (#{c[:count]} appearances in all) — an established contact."
+        else
+          "appears only in received mail (#{c[:count]}×); you have never sent here, so verify the address before using it."
+        end
+      end
+      private_class_method :familiarity
+    end
+  end
+end

data/lib/pikuri/thunderbird/database_snapshot.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Pikuri
+  module Thunderbird
+    # A consistent, lock-free, on-disk copy of a live Thunderbird SQLite DB
+    # (Gloda or a calendar store), so pikuri never queries the file
+    # Thunderbird holds open. Thunderbird keeps its DBs locked
+    # (+locking_mode=EXCLUSIVE+), so the only live-file touch is a *bracketed*
+    # +cp --reflink=auto+; every actual query runs against the copy we own.
+    #
+    #   snap = DatabaseSnapshot.new(source: profile.gloda_path, dir: cache_dir)
+    #   snap.refresh          # (re)copies iff the source generation moved
+    #   run_query_against(snap.path)
+    #   snap.generation       # the source change-counter this copy is as-of
+    #
+    # == Why bracketed
+    #
+    # A reflink clone is atomic w.r.t. concurrent writes, but *file
+    # atomicity ≠ DB consistency*: a clone taken mid-transaction faithfully
+    # photographs a torn DB. So each copy is bracketed — read the change
+    # counter (header bytes 24–27) and check +-journal+ absence *before and
+    # after* the copy; a copy counts as settled only when the counter didn't
+    # move and no rollback journal was present at either edge. Otherwise the
+    # copy is discarded and retried after a short backoff.
+    #
+    # The validated change counter doubles as the *generation* stamp: a
+    # caller checks freshness by comparing {.change_counter} of the live
+    # source against {#generation}, and {#refresh} re-copies only when they
+    # differ. One signal drives both consistency and freshness.
+    #
+    # == Implementation details
+    #
+    # On-disk rather than an +:memory:+ load: the page cache keeps idle RAM ≈ 0
+    # for a multi-hundred-MB Gloda, which a memory copy would pin for the life
+    # of the process.
+    #
+    # The copy lands in a caller-owned 0700 dir on the *same filesystem* as
+    # the source (so reflink's copy-on-write extent share is available;
+    # +--reflink=auto+ degrades to a full copy elsewhere). It is
+    # {Pikuri::Finalizers}-reaped, so a normal exit removes it; a crash can
+    # strand it (re-derivable data). Only the main DB file is copied — for a
+    # WAL store that yields an as-of-last-checkpoint view (Thunderbird
+    # checkpoints aggressively), which callers open with +?immutable=1+.
+    class DatabaseSnapshot
+      LOGGER = Pikuri.logger_for('Thunderbird::DatabaseSnapshot')
+
+      # Raised when a settled copy can't be taken within the attempt budget
+      # (Thunderbird mid-sync, counter won't sit still). Recoverable — the
+      # calling tool degrades to a stale snapshot or an +"Error: …"+.
+      class TornError < StandardError; end
+
+      # @return [String] absolute path of the snapshot copy.
+      attr_reader :path
+
+      # @return [Integer, nil] the source change-counter this copy reflects;
+      #   +nil+ before the first successful {#refresh}.
+      attr_reader :generation
+
+      # SQLite's file change counter: 4 big-endian bytes at header offset 24,
+      # bumped only when the DB is unlocked after a modification (so a read
+      # never moves it — a file-format guarantee). +nil+ if the file is too
+      # short to have a header yet.
+      #
+      # @param db_path [String]
+      # @return [Integer, nil]
+      def self.change_counter(db_path)
+        header = File.binread(db_path, 4, 24)
+        header && header.bytesize == 4 ? header.unpack1('N') : nil
+      rescue Errno::ENOENT, EOFError
+        nil
+      end
+
+      # @param source [String] path to the live Thunderbird DB.
+      # @param dir [String] private dir to hold the copy (created 0700 if
+      #   absent); must sit on the same filesystem as +source+ for reflink.
+      # @return [DatabaseSnapshot]
+      def initialize(source:, dir:)
+        @source = source
+        @dir = dir
+        @path = File.join(dir, File.basename(source))
+        @generation = nil
+        FileUtils.mkdir_p(@dir, mode: 0o700)
+        # Fire-and-forget reap of the whole private dir (block form).
+        Pikuri::Finalizers.register { FileUtils.rm_rf(@dir) }
+      end
+
+      # (Re)take the snapshot iff the live source generation differs from the
+      # copy we hold — a no-op (returning +false+) when already current.
+      #
+      # @param attempts [Integer] bracket retries before giving up.
+      # @param backoff [Float] seconds between retries.
+      # @return [Boolean] +true+ if a fresh copy was taken this call.
+      # @raise [TornError] if no settled copy could be taken.
+      def refresh(attempts: 6, backoff: 0.08)
+        live = self.class.change_counter(@source)
+        return false if @generation && live == @generation && File.file?(@path)
+
+        copy_bracketed(attempts, backoff)
+        true
+      end
+
+      private
+
+      # @return [void]
+      # @raise [TornError]
+      def copy_bracketed(attempts, backoff)
+        detail = nil
+        attempts.times do
+          before_counter = self.class.change_counter(@source)
+          before_journal = journal?(@source)
+          copy_file!
+          after_counter = self.class.change_counter(@source)
+          after_journal = journal?(@source)
+
+          if settled?(before_counter, after_counter, before_journal, after_journal)
+            @generation = after_counter
+            return
+          end
+
+          detail = "counter #{before_counter}->#{after_counter}, " \
+                   "journal #{before_journal}/#{after_journal}"
+          sleep(backoff)
+        end
+        raise TornError, "no settled snapshot of #{@source} after #{attempts} tries (#{detail})"
+      end
+
+      # Settled iff the counter is present and unchanged across the copy and
+      # no rollback journal existed at either edge.
+      #
+      # @return [Boolean]
+      def settled?(before_counter, after_counter, before_journal, after_journal)
+        !before_counter.nil? && before_counter == after_counter &&
+          !before_journal && !after_journal
+      end
+
+      # @return [Boolean] whether a +<source>-journal+ (write in flight) exists.
+      def journal?(db_path) = File.exist?("#{db_path}-journal")
+
+      # reflink-when-possible copy through the Subprocess chokepoint.
+      #
+      # @return [void]
+      # @raise [TornError] if +cp+ fails.
+      def copy_file!
+        result = Pikuri::Subprocess.spawn(
+          'cp', '--reflink=auto', '-f', @source, @path, chdir: '/'
+        ).wait
+        return if result.status.success?
+
+        raise TornError, "cp failed copying #{@source}: #{result.output.strip}"
+      end
+    end
+  end
+end